Appearance
Database: Platform Core
Version: 0.4
Date: 2026-11-17
Status: Working baseline (foundation Gate 1B + profile/avatar + account_preferences PROPOSED)
Owner repo: platform-core/
Package: @minap/platform-core
DB id: db-platform-core
Tên: Platform Core DB
Tên vật lý: platform_core (DECIDED — PostgreSQL schema name; D-022 / R2)
Work item / feature: MINAP-2026-004 · specs/001-platform-account-workspace-foundation
Schema vật lý: platform-core/prisma/schema.prisma
Quy ước gói DB: mỗi database có một tài liệu chính trong
docs/architecture/database/— mục lục + thiết kế cột/ER nằm cùng file (không tách file schema riêng dưới/architecture/12-…).
1. Mục đích
SoT bền vững cho identity/tenancy nền tảng do platform-core sở hữu: Account, Workspace, Membership, Invitation và Audit — sau khi Keycloak đã xác thực người dùng. Sau này mở rộng catalog, Application registry / credential app_…, entitlement/subscription.
Tích hợp: thư viện import-only cho platform-web BE, platform-admin BE, platform-api (D-021).
Không nằm trong schema lõi này (workstream sau): Application catalog chi tiết, credential app_…, entitlement/billing, metadata File Service, Chat, bảng domain Application.
2. Engine / topology
| Hạng mục | Trạng thái |
|---|---|
| Engine | DECIDED PostgreSQL (D-022) |
| Tên vật lý | Schema PostgreSQL platform_core (DECIDED) |
| Topology non-prod | Cùng Postgres database dùng chung với schema platform khác (phương án A, R4) |
| Local hiện tại (NEED ALIGN) | Compose có thể còn database tên platform_core + schema public — cần migrate về schema SoT platform_core |
| Prisma | platform-core/prisma/schema.prisma |
3. Quy tắc identity
| Khái niệm | Ai sở hữu | Lưu ở đâu |
|---|---|---|
| Đăng nhập / mật khẩu | Keycloak (IdP) | Chỉ trong Keycloak — không nhân bản hash mật khẩu sang Platform DB |
| Federated IdP refs (Google, Apple, Microsoft, GitHub, …) | Keycloak (Identity Brokering / Federated Identity) | Chỉ trong Keycloak — không cột apple_id / github_id / … trên accounts |
| ID công khai ổn định của người | Platform Core | accounts.id = acc_ + NanoID (D-017) |
| Liên kết tới user IdP | Platform Core | Một accounts.keycloak_subject = JWT Keycloak sub (ổn định sau mọi IdP social đã link) |
Vậy: account_id do Platform Core sinh. Thêm Apple/Microsoft/GitHub = cấu hình broker trên Keycloak + (khi cần) account linking trong IdP; Core không đổi mô hình — vẫn một sub ↔ một acc_….
Journey đăng ký/login: /architecture/database/20-user-journey-data-ownership. Nguyên tắc identity: /architecture/04-identity-workspace-and-access-model.
4. Danh mục bảng
4.1 Foundation (đã implement / khớp Gate 1B)
| Bảng | Mục đích | Prefix id |
|---|---|---|
accounts | MINAP Account; map Keycloak sub | acc_… |
workspaces | Personal / Organization | ws_… |
workspace_memberships | Role owner/admin/member | wsm_… |
workspace_invitations | Invite Organization | wsi_… |
audit_events | Audit tối thiểu | aud_… |
4.2 Mở rộng Account (PROPOSED — Owner 2026-11-17)
| Bảng | Mục đích | Prefix / PK |
|---|---|---|
account_preferences | Thiết lập cá nhân hay dùng — cột tường minh (không JSONB-only giai đoạn này) | 1–1 với accounts; PK = account_id hoặc acp_… |
4.3 Tương lai (stub — PROPOSED / OPEN)
| Vùng / bảng đề xuất | Ý định | Trạng thái |
|---|---|---|
| Application registry | Application đăng ký app_… | PROPOSED / OPEN chi tiết |
| Platform API credentials | Hash secret, scope, rotate/revoke (D-018) | PROPOSED |
| Application catalog / launch | Metadata discovery cho shell | PROPOSED |
| Entitlement / subscription | Hạn mức plan, subject account hoặc workspace | PROPOSED |
| Platform configuration | Feature flags / settings toàn nền tảng (không phải preference user) | OPEN |
| Preference long-tail (EAV / JSONB phụ) | Chỉ khi cột cố định không còn đủ | DEFERRED |
5. Tổng quan ER (foundation)
6. Bảng: accounts
MINAP Account — một dòng cho mỗi người (BR-001).
| Cột | Kiểu | Null | Nguồn dữ liệu | Ghi chú |
|---|---|---|---|---|
id | TEXT PK | NO | Platform Core — acc_ + NanoID lúc provision lần đầu | Business id công khai (D-017). Không phải id Keycloak. Bất biến. |
keycloak_subject | TEXT UNIQUE | NO | Keycloak JWT claim sub (Email/Password hoặc Google IdP) | Tham chiếu identity ngoài. Unique → một Account / một user IdP. |
email | TEXT | YES | Keycloak SoT auth; Core mirror (ensure / sau đổi email IdP) | Lowercase; khớp invite. Đổi email: không chỉ UPDATE Core — xem journey J2 (OPEN UX). |
display_name | TEXT | YES | Seed: Keycloak claim; sau profile update: User → Core (SoT) | ensureAccount không đè nếu user đã sửa (PROPOSED). |
avatar_file_id | TEXT | YES | User qua File Service → Core gán file_… | PROPOSED (J2). Soft ref tới File Service; không FK cross-DB. Null = chưa có / đã xóa avatar. |
status | enum active | inactive | NO | Platform Core mặc định active lúc provision; sau đó operator/admin | IdP vẫn có thể cấp token khi inactive; domain từ chối hành động theo workspace. |
last_workspace_id | TEXT | YES | Platform Core — cập nhật khi đổi context workspace (switch-context) | Phải là workspace còn membership active; UI mặc định về Personal nếu null/invalid. MVP Prisma: soft reference (chưa FK cứng). |
last_login_at | TIMESTAMPTZ | YES | Platform Core lúc login thành công (J1b) | PROPOSED — không phải SoT bảo mật; chỉ analytics/UX. |
created_at | TIMESTAMPTZ | NO | Platform Core đồng hồ DB (now()) | |
updated_at | TIMESTAMPTZ | NO | Platform Core đồng hồ DB / Prisma @updatedAt |
Khi ghi: lần đầu ensureAccountFromIdp thành công sau login Keycloak. User quay lại: chỉ lookup theo keycloak_subject — không tạo dòng thứ hai.
Password: không có cột mật khẩu — đổi password chỉ qua Keycloak (J2).
Avatar: bytes + metadata không nằm bảng này; chỉ avatar_file_id. Chi tiết File Service: /architecture/database/02-file-service.
Preference cá nhân: không nhồi theme/locale vào accounts — xem bảng account_preferences (§7).
7. Bảng: account_preferences (PROPOSED)
Thiết lập cá nhân hay dùng — một dòng / Account (1–1). Owner chốt hướng giai đoạn này: bảng riêng + cột cơ bản, chưa EAV/JSONB-only.
| Cột | Kiểu | Null | Nguồn | Ghi chú |
|---|---|---|---|---|
account_id | TEXT PK, FK → accounts.id | NO | Platform Core lúc provision (cùng J1) hoặc lazy tạo lần đầu mở settings | 1–1; xóa Account cascade |
locale | TEXT | NO | User / mặc định platform (vd. vi) | BCP 47 ngắn (vi, en) — danh sách locale hỗ trợ OPEN |
timezone | TEXT | NO | User / mặc định (vd. Asia/Ho_Chi_Minh) | IANA timezone |
theme | enum / TEXT | NO | User / mặc định system | system | light | dark (PROPOSED) |
email_notifications_enabled | BOOLEAN | NO | User / mặc định true | Công tắc tổng email platform; chi tiết từng loại thông báo DEFERRED |
created_at | TIMESTAMPTZ | NO | Platform Core | |
updated_at | TIMESTAMPTZ | NO | Platform Core |
Không nằm đây: password, session thiết bị, federated IdP (Keycloak); display_name / avatar (vẫn accounts); preference Workspace/org; feature flag toàn platform.
Khi ghi: tạo kèm provision Account (PROPOSED) với default; user sửa qua API profile/settings trên platform-web → Core.
8. Bảng: workspaces
Đơn vị tenancy Personal hoặc Organization.
| Cột | Kiểu | Null | Nguồn dữ liệu | Ghi chú |
|---|---|---|---|---|
id | TEXT PK | NO | Platform Core — ws_ + NanoID | Workspace id công khai. |
type | enum personal | organization | NO | Platform Core | personal tự tạo cùng Account; organization từ body API tạo org. |
name | VARCHAR(120) | NO | Quy tắc Platform Core hoặc input User | Personal: tên mặc định hệ thống; Organization: user nhập (trim, không để trống). |
owner_account_id | TEXT FK → accounts.id | NO | Platform Core — id Account người tạo (acc_…) | Không lấy từ Keycloak. Chuyển ownership ngoài scope slice này. |
status | enum active | inactive | NO | Platform Core mặc định active | |
created_at | TIMESTAMPTZ | NO | Platform Core | |
updated_at | TIMESTAMPTZ | NO | Platform Core |
Index / bất biến: partial unique — đúng một workspace personal cho mỗi owner_account_id (migration).
9. Bảng: workspace_memberships
Vai trò cấp nền tảng của một Account trong một Workspace.
| Cột | Kiểu | Null | Nguồn dữ liệu | Ghi chú |
|---|---|---|---|---|
id | TEXT PK | NO | Platform Core — wsm_ + NanoID | |
workspace_id | TEXT FK → workspaces.id | NO | Platform Core — workspace đích | Từ provision hoặc accept invite. |
account_id | TEXT FK → accounts.id | NO | Platform Core — Account thành viên (acc_…) | Không phải Keycloak sub. Lấy từ Account đã xác thực sau login IdP. |
platform_role | enum owner | admin | member | NO | Platform Core | Personal provision → owner. Accept invite → role từ invitation (admin/member thôi). |
status | enum active | inactive | removed | NO | Platform Core | Authz yêu cầu active. Remove → removed. |
created_at | TIMESTAMPTZ | NO | Platform Core | |
updated_at | TIMESTAMPTZ | NO | Platform Core |
Unique: (workspace_id, account_id).
10. Bảng: workspace_invitations
Luồng mời chỉ cho Organization.
| Cột | Kiểu | Null | Nguồn dữ liệu | Ghi chú |
|---|---|---|---|---|
id | TEXT PK | NO | Platform Core — wsi_ + NanoID | |
workspace_id | TEXT FK → workspaces.id | NO | User/API — Organization Workspace được mời vào | Từ chối nếu workspace là Personal. |
invitee_email | TEXT | NO | User/API — email người mời nhập | Lưu lowercase; accept yêu cầu email Account đang login khớp. |
invited_role | enum owner | admin | member | NO | User/API | Quy tắc nghiệp vụ MVP: invite không được cấp owner. |
status | enum pending | accepted | declined | expired | NO | Vòng đời Platform Core | Mặc định pending; chuyển khi accept/decline/hết hạn. |
invited_by_account_id | TEXT FK → accounts.id | NO | Platform Core — acc_… của người mời (session) | Phải là owner hoặc admin active trên workspace đó. |
expires_at | TIMESTAMPTZ | NO | Platform Core — mặc định now + 7 ngày | Giả định Gate 1A. |
created_at | TIMESTAMPTZ | NO | Platform Core | |
updated_at | TIMESTAMPTZ | NO | Platform Core |
11. Bảng: audit_events
Audit tối thiểu cho hành động nhạy cảm (FR-016).
| Cột | Kiểu | Null | Nguồn dữ liệu | Ghi chú |
|---|---|---|---|---|
id | TEXT PK | NO | Platform Core — aud_ + NanoID | |
actor_account_id | TEXT FK → accounts.id | YES | Platform Core — Account thực hiện | Null chỉ khi sự kiện hệ thống/không gắn actor. |
action | TEXT | NO | Hằng số code Platform Core | Ví dụ account.provisioned, workspace.created, invite.created, invite.accepted, invite.declined, membership.removed. |
workspace_id | TEXT | YES | Ngữ cảnh Platform Core | Soft reference (không luôn FK). |
target_account_id | TEXT | YES | Platform Core — Account bị ảnh hưởng (nếu có) | Soft reference. |
payload | JSONB | NO | Platform Core | Metadata không chứa secret; không ghi token. |
created_at | TIMESTAMPTZ | NO | Platform Core | Hướng append-only. |
12. Tóm tắt luồng dữ liệu (provision)
text
Keycloak (Email/Password hoặc Google)
→ access token claims: sub, email?, name?
↓
Platform Core ensureAccount
→ accounts.id = Platform NanoID (acc_…)
→ accounts.keycloak_subject = Keycloak sub
→ accounts.email / display_name = Keycloak claims (đã chuẩn hóa)
→ account_preferences = default (locale/timezone/theme/…) **PROPOSED**
→ workspaces (personal) = Platform sinh
→ workspace_memberships = Platform sinh (role=owner)
→ audit_events = Platform sinh13. Ngoài phạm vi
- Bảng nghiệp vụ Application
- Bytes file / metadata File Service
- Credential / user sessions đa thiết bị trong Keycloak (list/revoke phiên — không bảng
sessionstrên Core) - Chưa tạo ở đây:
application_workspace, Application roles, subscription/entitlement, Chat rooms, registry pháp nhânorg_…, lịch sử chuyển ownership
14. Tài liệu liên quan
| Tài liệu | Vai trò |
|---|---|
platform-core/prisma/schema.prisma | Schema vật lý / enum |
Feature data-model.md / contracts/ (Spec Kit) | Bất biến + shape HTTP nội bộ /internal/v1 |
| /architecture/04-identity-workspace-and-access-model | Nguyên tắc identity |
| /architecture/13-platform-core-usage-guide | Cách dùng thư viện Platform Core |
| /architecture/database/20-user-journey-data-ownership | Journey → data |
15. Câu hỏi mở
- Danh sách bảng tương lai + prefix cho credential
app_ - Entitlement chỉ trong Platform Core DB hay tách service sau
- Đổi email: chỉ qua Keycloak UI hay MINAP gọi Admin API rồi mirror?
- Chốt bộ cột MVP
account_preferences(đề xuất:locale,timezone,theme,email_notifications_enabled) — thêm/bớt gì? phonetrênaccountshay để sau?- Chốt migration Prisma cho
avatar_file_id/last_login_at/account_preferences