Skip to content

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ụcTrạng thái
EngineDECIDED PostgreSQL (D-022)
Tên vật lýSchema PostgreSQL platform_core (DECIDED)
Topology non-prodCù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
Prismaplatform-core/prisma/schema.prisma

3. Quy tắc identity ​

Khái niệmAi sở hữuLưu ở đâu
Đăng nhập / mật khẩuKeycloak (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ườiPlatform Coreaccounts.id = acc_ + NanoID (D-017)
Liên kết tới user IdPPlatform CoreMộ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ảngMục đíchPrefix id
accountsMINAP Account; map Keycloak subacc_…
workspacesPersonal / Organizationws_…
workspace_membershipsRole owner/admin/memberwsm_…
workspace_invitationsInvite Organizationwsi_…
audit_eventsAudit tối thiểuaud_…

4.2 Mở rộng Account (PROPOSED — Owner 2026-11-17) ​

BảngMục đíchPrefix / PK
account_preferencesThiế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Ý địnhTrạng thái
Application registryApplication đăng ký app_…PROPOSED / OPEN chi tiết
Platform API credentialsHash secret, scope, rotate/revoke (D-018)PROPOSED
Application catalog / launchMetadata discovery cho shellPROPOSED
Entitlement / subscriptionHạn mức plan, subject account hoặc workspacePROPOSED
Platform configurationFeature 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ộtKiểuNullNguồn dữ liệuGhi chú
idTEXT PKNOPlatform Core — acc_ + NanoID lúc provision lần đầuBusiness id công khai (D-017). Không phải id Keycloak. Bất biến.
keycloak_subjectTEXT UNIQUENOKeycloak JWT claim sub (Email/Password hoặc Google IdP)Tham chiếu identity ngoài. Unique → một Account / một user IdP.
emailTEXTYESKeycloak 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_nameTEXTYESSeed: Keycloak claim; sau profile update: User → Core (SoT)ensureAccount không đè nếu user đã sửa (PROPOSED).
avatar_file_idTEXTYESUser 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.
statusenum active | inactiveNOPlatform Core mặc định active lúc provision; sau đó operator/adminIdP vẫn có thể cấp token khi inactive; domain từ chối hành động theo workspace.
last_workspace_idTEXTYESPlatform 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_atTIMESTAMPTZYESPlatform Core lúc login thành công (J1b)PROPOSED — không phải SoT bảo mật; chỉ analytics/UX.
created_atTIMESTAMPTZNOPlatform Core đồng hồ DB (now())
updated_atTIMESTAMPTZNOPlatform 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ộtKiểuNullNguồnGhi chú
account_idTEXT PK, FK → accounts.idNOPlatform Core lúc provision (cùng J1) hoặc lazy tạo lần đầu mở settings1–1; xóa Account cascade
localeTEXTNOUser / mặc định platform (vd. vi)BCP 47 ngắn (vi, en) — danh sách locale hỗ trợ OPEN
timezoneTEXTNOUser / mặc định (vd. Asia/Ho_Chi_Minh)IANA timezone
themeenum / TEXTNOUser / mặc định systemsystem | light | dark (PROPOSED)
email_notifications_enabledBOOLEANNOUser / mặc định trueCông tắc tổng email platform; chi tiết từng loại thông báo DEFERRED
created_atTIMESTAMPTZNOPlatform Core
updated_atTIMESTAMPTZNOPlatform 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ộtKiểuNullNguồn dữ liệuGhi chú
idTEXT PKNOPlatform Core — ws_ + NanoIDWorkspace id công khai.
typeenum personal | organizationNOPlatform Corepersonal tự tạo cùng Account; organization từ body API tạo org.
nameVARCHAR(120)NOQuy tắc Platform Core hoặc input UserPersonal: tên mặc định hệ thống; Organization: user nhập (trim, không để trống).
owner_account_idTEXT FK → accounts.idNOPlatform Core — id Account người tạo (acc_…)Không lấy từ Keycloak. Chuyển ownership ngoài scope slice này.
statusenum active | inactiveNOPlatform Core mặc định active
created_atTIMESTAMPTZNOPlatform Core
updated_atTIMESTAMPTZNOPlatform 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ộtKiểuNullNguồn dữ liệuGhi chú
idTEXT PKNOPlatform Core — wsm_ + NanoID
workspace_idTEXT FK → workspaces.idNOPlatform Core — workspace đíchTừ provision hoặc accept invite.
account_idTEXT FK → accounts.idNOPlatform 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_roleenum owner | admin | memberNOPlatform CorePersonal provision → owner. Accept invite → role từ invitation (admin/member thôi).
statusenum active | inactive | removedNOPlatform CoreAuthz yêu cầu active. Remove → removed.
created_atTIMESTAMPTZNOPlatform Core
updated_atTIMESTAMPTZNOPlatform Core

Unique: (workspace_id, account_id).

10. Bảng: workspace_invitations ​

Luồng mời chỉ cho Organization.

CộtKiểuNullNguồn dữ liệuGhi chú
idTEXT PKNOPlatform Core — wsi_ + NanoID
workspace_idTEXT FK → workspaces.idNOUser/API — Organization Workspace được mời vàoTừ chối nếu workspace là Personal.
invitee_emailTEXTNOUser/API — email người mời nhậpLưu lowercase; accept yêu cầu email Account đang login khớp.
invited_roleenum owner | admin | memberNOUser/APIQuy tắc nghiệp vụ MVP: invite không được cấp owner.
statusenum pending | accepted | declined | expiredNOVòng đời Platform CoreMặc định pending; chuyển khi accept/decline/hết hạn.
invited_by_account_idTEXT FK → accounts.idNOPlatform Core — acc_… của người mời (session)Phải là owner hoặc admin active trên workspace đó.
expires_atTIMESTAMPTZNOPlatform Core — mặc định now + 7 ngàyGiả định Gate 1A.
created_atTIMESTAMPTZNOPlatform Core
updated_atTIMESTAMPTZNOPlatform Core

11. Bảng: audit_events ​

Audit tối thiểu cho hành động nhạy cảm (FR-016).

CộtKiểuNullNguồn dữ liệuGhi chú
idTEXT PKNOPlatform Core — aud_ + NanoID
actor_account_idTEXT FK → accounts.idYESPlatform Core — Account thực hiệnNull chỉ khi sự kiện hệ thống/không gắn actor.
actionTEXTNOHằng số code Platform CoreVí dụ account.provisioned, workspace.created, invite.created, invite.accepted, invite.declined, membership.removed.
workspace_idTEXTYESNgữ cảnh Platform CoreSoft reference (không luôn FK).
target_account_idTEXTYESPlatform Core — Account bị ảnh hưởng (nếu có)Soft reference.
payloadJSONBNOPlatform CoreMetadata không chứa secret; không ghi token.
created_atTIMESTAMPTZNOPlatform CoreHướ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 sinh

13. 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 sessions trên Core)
  • Chưa tạo ở đây: application_workspace, Application roles, subscription/entitlement, Chat rooms, registry pháp nhân org_…, lịch sử chuyển ownership

14. Tài liệu liên quan ​

Tài liệuVai trò
platform-core/prisma/schema.prismaSchema 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-modelNguyên tắc identity
/architecture/13-platform-core-usage-guideCách dùng thư viện Platform Core
/architecture/database/20-user-journey-data-ownershipJourney → 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ì?
  • phone trên accounts hay để sau?
  • Chốt migration Prisma cho avatar_file_id / last_login_at / account_preferences

docs/ = SoT duy nhất · văn xuôi tiếng Việt + thuật ngữ chuyên ngành English