Appearance
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:
- Cần lưu gì
- Ở store / database nào
- 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ệu | Nghĩa |
|---|---|
| SoT | Nguồn sự thật cho field đó |
| Không lưu | Không ghi vào store đó (tránh trùng / lệch) |
| DECIDED | Đã có trong architecture / schema foundation |
| OPEN | Chư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 / Workspace3.2 Ai làm gì
| Thành phần | Vai trò trong J1 |
|---|---|
| platform-web | UI đă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 Service | Không tham gia J1 (chưa có upload) |
| Payment / Invoice | Không tham gia J1 |
| Matrix / Chat | Khô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) |
| Infisical | Chỉ secrets runtime (client Keycloak, DB URL…) — không lưu hồ sơ user |
| Application A/B/C | Khô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 tin | Lưu? | Ghi chú |
|---|---|---|
| Username / email đăng ký | Có | Theo realm/client Keycloak |
| Password hash | Có | Chỉ Keycloak — Platform Core không lưu mật khẩu |
| Google IdP link / federated identity | Có | Google Login |
OIDC sub | Có | Identifier IdP ổn định |
| Session / refresh token IdP | Có (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ảng | Field chính | Nguồn | Khi nào ghi |
|---|---|---|---|
accounts | id = acc_… | Platform Core sinh (D-017) | Lần đầu ensureAccount sau login IdP thành công |
accounts | keycloak_subject | Keycloak JWT sub | Cùng lúc; UNIQUE — một IdP user ↔ một Account |
accounts | email, display_name | Claims Keycloak (chuẩn hóa) | Cùng lúc; email dùng khớp invite sau này |
accounts | status | Core mặc định active | Cùng lúc |
workspaces | Personal ws_…, owner_account_id, type personal | Core | Cùng provision (onboarding MVP) |
workspace_memberships | account_id, workspace_id, platform_role=owner | Core | Cùng lúc |
audit_events | ví dụ account.provisioned, workspace.created | Core | Cù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 DB | Không có SoT Account (shell chỉ session/UI) |
| File Service DB / MinIO | Không avatar/file bắt buộc lúc đăng ký (OPEN nếu sau này có upload avatar) |
| Payment / Invoice schemas | Không |
| Application DB | Không tạo user Application song song |
3.4 Email/Password vs Google — khác nhau chỗ nào?
| Khác biệt | Email/Password | |
|---|---|---|
| Nơi nhập credential | Form Keycloak | Google → Keycloak broker |
| Password trong MINAP DB | Không | Không |
| Kết quả sau login | Cùng claims sub (+ email/name nếu có) | Cùng pattern |
| Hàng Platform Core | Cùng ensureAccount + Personal Workspace | Cù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ước | Lưu gì / ở đâu | Owner |
|---|---|---|
| OIDC login | User session (thiết bị/client, thời điểm) + token | Keycloak (SoT phiên) + browser giữ token |
ensureAccount | Lookup accounts theo keycloak_subject — không tạo Account thứ hai | Platform Core |
| Đồng bộ nhẹ (tuỳ policy) | Có thể refresh email từ claim nếu chưa bị user/override policy khóa | Core (PROPOSED policy) |
last_login_at | Chỉ “lần gần nhất” (tóm tắt) — không thay danh sách phiên | Core cột PROPOSED |
| Bảng phiên / thiết bị trên Core | Không (mặc định) | Xem §5.7 |
| File / Payment | Khô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_coremỗ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
| Usecase | Dữ liệu | SoT lưu | Không lưu ở |
|---|---|---|---|
Cập nhật thông tin tài khoản (vd. display_name) | Tên hiển thị platform | Platform Core accounts.display_name | Keycloak 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ùng | Platform 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ập | Email dùng auth + khớp invite | Keycloak là SoT auth; Core accounts.email = mirror sau khi IdP đổi thành công | Không chỉ sửa Core mà bỏ Keycloak (lệch login/invite) — chi tiết UX OPEN |
| Đổi mật khẩu | Password hash | Chỉ Keycloak (Account Console / required action / API IdP) | Platform Core, File Service, Application DB, Infisical |
| Đổi / xóa avatar | Bytes ảnh | MinIO (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ại | Platform 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 Service5.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ần | Vai trò |
|---|---|
| platform-web | Form profile / upload avatar / deep-link đổi mật khẩu |
| Keycloak | Đổi password; SoT email auth (khi đổi email) |
| Platform Core | display_name, avatar_file_id, mirror email, audit |
| File Service + MinIO | Avatar metadata + bytes |
| Payment / Invoice / App DB | Khô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 động | Nguồn dữ liệu | Ai thực thi |
|---|---|---|
| Xem đã link những IdP nào | Keycloak 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 provider | Keycloak broker / Account Console flow | Keycloak |
| Revoke / unlink | Keycloak xóa federated identity link | Keycloak; 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ận | Core chỉ audit sự kiện, không nhân bản danh sách IdP |
Hai hướng UX (OPEN chốt Owner):
- Redirect / embed Keycloak Account Console — ít code, UI IdP chuẩn.
- 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_events5.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 tin | SoT lưu ở đâu | Ghi chú |
|---|---|---|
| Session đang active (session id, client, IP/UA nếu IdP có, started/last access) | Keycloak user sessions | Quả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 + Keycloak | platform-web không tự invent session store song song |
| Đăng xuất một thiết bị / phiên | Gọ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_at | Core (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-only | Session 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)
| ID | Journey | Trạng thái tài liệu |
|---|---|---|
| J1 | Đăng ký / login lần đầu | §3 |
| J1b | Đăng nhập lại | §4 |
| J2 | Profile / password / avatar / linked IdPs / sessions thiết bị | §5 |
| J3 | Chọn/switch Workspace | Stub |
| J4 | Mời thành viên Organization | Stub (workspace_invitations) |
| J5 | Upload fileทั่วไป (không phải avatar) | Stub → mở rộng File Service |
| J6 | Bật / mở Application | Stub |
| J7 | Thanh toán / hóa đơn | Stub |
7. Tham chiếu
- Identity: /architecture/04-identity-workspace-and-access-model
- Schema Core: /architecture/database/01-platform-core
- File Service DB: /architecture/database/02-file-service
- Store ngoài: /architecture/database/90-external-stores
- D-001, D-004, D-017, D-022