Skip to content

Luồng người dùng → dữ liệu → DB / owner ​

Version: 0.2
Date: 2026-11-16
Status: Working baseline (journey-first; bổ sung từng bước với Owner)

1. Mục đích ​

Đi theo journey người dùng thật (không theo bảng DB trước) để xác định:

  1. Cần lưu gì
  2. Ở store / database nào
  3. Ai phụ trách (Keycloak, platform-web, Platform Core, File Service, …)

Phạm vi gói DB: Core / File / Payment / Invoice + store ngoài (Keycloak, MinIO, …). Application domain DB ngoài gói này.

2. Quy tắc đọc ​

Ký hiệuNghĩa
SoTNguồn sự thật cho field đó
Không lưuKhông ghi vào store đó (tránh trùng / lệch)
DECIDEDĐã có trong architecture / schema foundation
OPENChưa chốt với Owner

3. Journey J1 — User mới đăng ký / đăng nhập lần đầu ​

Kích hoạt: người dùng mở App Shell (platform-web), chọn đăng ký hoặc đăng nhập bằng Email/Password hoặc Google (D-004).

3.1 Chuỗi trách nhiệm ​

text
Browser (platform-web)
  → redirect OIDC Keycloak (register / login / Google)
  → Keycloak xác thực + (nếu mới) tạo user IdP
  → callback + token về platform-web
  → BE (platform-web hoặc platform-api) gọi Platform Core ensureAccount
  → Core provision Account + Personal Workspace + membership + audit
  → UI vào shell với context Account / Workspace

3.2 Ai làm gì ​

Thành phầnVai trò trong J1
platform-webUI đăng nhập/đăng ký; OIDC redirect/callback; giữ session phía client; không SoT Account
Keycloak (store-keycloak)SoT credential và federation Google; phát hành OIDC token (sub, email, name, …)
Platform Core (db-platform-core / schema platform_core)SoT MINAP Account + Personal Workspace + membership + audit provision
File ServiceKhông tham gia J1 (chưa có upload)
Payment / InvoiceKhông tham gia J1
Matrix / ChatKhông bắt buộc lúc đăng ký; provision map Chat OPEN / thường trì đến lần dùng Chat đầu (D-010)
InfisicalChỉ secrets runtime (client Keycloak, DB URL…) — không lưu hồ sơ user
Application A/B/CKhông tạo tài khoản riêng (D-001)

3.3 Dữ liệu lưu ở đâu ​

A. Keycloak (IdP — ngoài schema MINAP) ​

Thông tinLưu?Ghi chú
Username / email đăng kýCóTheo realm/client Keycloak
Password hashCóChỉ Keycloak — Platform Core không lưu mật khẩu
Google IdP link / federated identityCóGoogle Login
OIDC subCóIdentifier IdP ổn định
Session / refresh token IdPCó (Keycloak)Client chỉ giữ token theo OIDC; không nhét password vào Core

B. Platform Core DB — schema platform_core (D-022) ​

BảngField chínhNguồnKhi nào ghi
accountsid = acc_…Platform Core sinh (D-017)Lần đầu ensureAccount sau login IdP thành công
accountskeycloak_subjectKeycloak JWT subCùng lúc; UNIQUE — một IdP user ↔ một Account
accountsemail, display_nameClaims Keycloak (chuẩn hóa)Cùng lúc; email dùng khớp invite sau này
accountsstatusCore mặc định activeCùng lúc
workspacesPersonal ws_…, owner_account_id, type personalCoreCùng provision (onboarding MVP)
workspace_membershipsaccount_id, workspace_id, platform_role=ownerCoreCùng lúc
audit_eventsví dụ account.provisioned, workspace.createdCoreCùng lúc
workspace_invitations——Không trong J1 thuần đăng ký

Chi tiết cột: /architecture/database/01-platform-core.

C. Không lưu ở đâu (tránh nhầm) ​

ChỗKhông lưu gì trong J1
platform-web DBKhông có SoT Account (shell chỉ session/UI)
File Service DB / MinIOKhông avatar/file bắt buộc lúc đăng ký (OPEN nếu sau này có upload avatar)
Payment / Invoice schemasKhông
Application DBKhông tạo user Application song song

3.4 Email/Password vs Google — khác nhau chỗ nào? ​

Khác biệtEmail/PasswordGoogle
Nơi nhập credentialForm KeycloakGoogle → Keycloak broker
Password trong MINAP DBKhôngKhông
Kết quả sau loginCùng claims sub (+ email/name nếu có)Cùng pattern
Hàng Platform CoreCùng ensureAccount + Personal WorkspaceCùng

Thêm Apple / Microsoft / GitHub / …: reference id từng nhà cung cấp lưu và quản lý trong Keycloak (federated identities). Core không thêm cột provider — cùng một keycloak_subject sau khi link. Chi tiết UX account linking (cùng email, merge) vẫn OPEN ở sổ quyết định; ranh giới lưu trữ = DECIDED DIRECTION (IdP sở hữu federated refs).

3.5 Tóm tắt một dòng ​

Credential / login → Keycloak. Hồ sơ platform (acc_…, Personal Workspace) → Platform Core. Shell chỉ điều phối OIDC. File/Payment/App không tham gia đăng ký lần đầu.

4. Journey J1b — Đăng nhập lại (đã có Account) ​

Kích hoạt: user đã provision, mở platform-web, login Email/Password hoặc Google.

BướcLưu gì / ở đâuOwner
OIDC loginUser session (thiết bị/client, thời điểm) + tokenKeycloak (SoT phiên) + browser giữ token
ensureAccountLookup accounts theo keycloak_subject — không tạo Account thứ haiPlatform Core
Đồng bộ nhẹ (tuỳ policy)Có thể refresh email từ claim nếu chưa bị user/override policy khóaCore (PROPOSED policy)
last_login_atChỉ “lần gần nhất” (tóm tắt) — không thay danh sách phiênCore cột PROPOSED
Bảng phiên / thiết bị trên CoreKhông (mặc định)Xem §5.7
File / PaymentKhông—

Đăng nhập không ghi password vào Core; không tạo lại Personal Workspace nếu đã có. Phiên đa thiết bị do Keycloak tạo/giữ — không INSERT session row vào platform_core mỗi lần login.

5. Journey J2 — Cập nhật hồ sơ Account (profile / password / avatar) ​

Kích hoạt: user đã login, vào màn hồ sơ trên platform-web (hoặc Account settings).

5.1 Phân tích usecase → nơi lưu ​

UsecaseDữ liệuSoT lưuKhông lưu ở
Cập nhật thông tin tài khoản (vd. display_name)Tên hiển thị platformPlatform Core accounts.display_nameKeycloak không bắt buộc làm SoT sau khi user sửa trên MINAP; platform-web chỉ UI
Thiết lập cá nhân (locale, timezone, theme, …)Preference hay dùngPlatform Core account_preferences (cột — PROPOSED, Owner 2026-11-17)Không JSONB-only giai đoạn này; không Keycloak
Đổi email đăng nhậpEmail dùng auth + khớp inviteKeycloak là SoT auth; Core accounts.email = mirror sau khi IdP đổi thành côngKhông chỉ sửa Core mà bỏ Keycloak (lệch login/invite) — chi tiết UX OPEN
Đổi mật khẩuPassword hashChỉ Keycloak (Account Console / required action / API IdP)Platform Core, File Service, Application DB, Infisical
Đổi / xóa avatarBytes ảnhMinIO (object)Không base64 trong Core; không SoT tên file từ listing bucket
Metadata file (file_…, MIME, size, key, lifecycle)File Service schema file_service—
Con trỏ avatar hiện tạiPlatform Core accounts.avatar_file_id → file_…Không nhân bản bytes

5.2 Chuỗi trách nhiệm (avatar) ​

text
platform-web (UI chọn ảnh)
  → File Service: upload tạm (purpose=account_avatar; không gắn Workspace)
  → upload bytes → MinIO
  → File Service: complete → files.status=available, id=file_…
  → Platform Core: accounts.avatar_file_id = file_… (+ audit)
  → (đổi avatar) soft-delete / unlink file cũ theo policy File Service

5.3 Chuỗi trách nhiệm (đổi mật khẩu) ​

text
platform-web
  → redirect / embed Keycloak (change password)  — hoặc Account Console
  → Keycloak cập nhật credential
  → Core / File: không ghi gì

5.4 Chuỗi trách nhiệm (cập nhật display_name) ​

text
platform-web → Platform Core API (authenticated user session)
  → UPDATE accounts.display_name
  → audit_events (vd. account.profile_updated)

Seed ban đầu từ Keycloak claim name lúc J1; sau khi user sửa trên MINAP, Core là SoT cho display_name (không bị ensureAccount đè lại trừ khi Owner chọn policy khác — PROPOSED).

5.5 Ai làm gì (J2) ​

Thành phầnVai trò
platform-webForm profile / upload avatar / deep-link đổi mật khẩu
KeycloakĐổi password; SoT email auth (khi đổi email)
Platform Coredisplay_name, avatar_file_id, mirror email, audit
File Service + MinIOAvatar metadata + bytes
Payment / Invoice / App DBKhông

5.6 Quản lý IdP đã liên kết (list / thời điểm / revoke) ​

Có thể lấy từ Keycloak — Keycloak là SoT danh sách federated identities của user. Platform Core không bảng/accounts columns liệt kê Google/Apple/…

Hành độngNguồn dữ liệuAi thực thi
Xem đã link những IdP nàoKeycloak federated identities (Account API hoặc Admin API; hoặc UI Account Console)Đọc từ IdP lúc cần — không cache SoT lâu dài trên Core
Xem “lúc nào” (nếu IdP trả)Metadata Keycloak (tuỳ phiên bản/API: thời điểm link có thể hạn chế)Hiển thị từ response IdP; nếu thiếu timestamp → OPEN / không bịa trên Core
Link thêm providerKeycloak broker / Account Console flowKeycloak
Revoke / unlinkKeycloak xóa federated identity linkKeycloak; Core không đổi keycloak_subject trừ khi xóa cả user IdP
Audit platform (tuỳ chọn)Có thể ghi audit_events kiểu account.idp_unlinked sau khi IdP xác nhậnCore chỉ audit sự kiện, không nhân bản danh sách IdP

Hai hướng UX (OPEN chốt Owner):

  1. Redirect / embed Keycloak Account Console — ít code, UI IdP chuẩn.
  2. Custom UI trên platform-web — BE (shell) gọi Keycloak Account API (user token) hoặc proxy qua service có quyền; vẫn không ghi danh sách vào Postgres Core.
text
platform-web (màn “Tài khoản liên kết”)
  → đọc danh sách federated IdP từ Keycloak (API hoặc Account Console)
  → user revoke → Keycloak unlink
  → (optional) Core audit_events

5.7 Phiên đăng nhập đa thiết bị / lịch sử / đăng xuất từng máy ​

Usecase: mỗi lần login trên thiết bị khác → có thể xem phiên (thời gian, thiết bị/client), đăng xuất một phiên hoặc tất cả.

Thông tinSoT lưu ở đâuGhi chú
Session đang active (session id, client, IP/UA nếu IdP có, started/last access)Keycloak user sessionsQuản lý bởi IdP (memory/cluster/persistent theo cấu hình Keycloak) — không bảng sessions trên Platform Core làm SoT
Access / refresh token trên thiết bịBrowser / app + Keycloakplatform-web không tự invent session store song song
Đăng xuất một thiết bị / phiênGọi Keycloak xóa user session đóToken phiên đó hết hiệu lực; không cần UPDATE Postgres Core để “hủy session”
Đăng xuất tất cảKeycloak logout-all / xóa mọi user sessions (+ revoke refresh nếu bật)Cùng nguyên tắc
accounts.last_login_atCore (tóm tắt)Không đủ cho UI “danh sách thiết bị”
Lịch sử login đã kết thúc (audit dài hạn)OPEN: Keycloak Events (LOGIN/LOGOUT) và/hoặc Core audit_events append-onlySession store IdP thường không phải kho lịch sử vĩnh viễn; nếu cần “xem lại tháng trước” phải bật event store / ghi audit có chủ đích

Luồng đúng khi user “đăng xuất thiết bị X”:

text
platform-web (UI danh sách phiên)
  → đọc sessions từ Keycloak (Account Console hoặc Admin/Account API)
  → user chọn đăng xuất phiên / tất cả
  → Keycloak invalidate session(s)   ← bước bắt buộc để hủy session
  → (optional) Core audit_events: account.session_revoked
  → Không UPDATE/DELETE hàng “session” trên platform_core (vì không có SoT session ở đó)

Không làm: nhân bản danh sách phiên active vào Postgres Core rồi “cập nhật DB” coi như đã logout mà không gọi Keycloak — token vẫn sống trên IdP.

UX hiển thị (OPEN chốt Owner): Keycloak Account Console (Devices/Sessions) vs custom UI gọi API Keycloak — giống pattern linked IdPs §5.6.

6. Journey tiếp theo (khung) ​

IDJourneyTrạng thái tài liệu
J1Đăng ký / login lần đầu§3
J1bĐăng nhập lại§4
J2Profile / password / avatar / linked IdPs / sessions thiết bị§5
J3Chọn/switch WorkspaceStub
J4Mời thành viên OrganizationStub (workspace_invitations)
J5Upload fileทั่วไป (không phải avatar)Stub → mở rộng File Service
J6Bật / mở ApplicationStub
J7Thanh toán / hóa đơnStub

7. Tham chiếu ​

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