Skip to content

Kiến trúc Database — Tổng quan ​

Version: 0.6
Date: 2026-11-17
Status: Working baseline (skeleton; engine D-022 DECIDED)

1. Mục đích ​

Mô tả các datastore platform trong phạm vi thiết kế database lần này: ai sở hữu, tên vật lý, và quan hệ logic.

Quy ước: mỗi database = một tài liệu chính (01–04, …) chứa cả mục lục và thiết kế cột/ER — không tách file schema riêng dưới /architecture/12-….

Trong phạm vi gói này: Platform Core, File Service, Payment Integration, Invoice Integration, store ngoài (ranh giới).
Ngoài phạm vi gói này: DB domain của từng Application (A/B/C, kể cả Salon chỉ là dự kiến) — thiết kế khi có Application Gate / discovery riêng.

Cách đọc theo journey: 20. Journey → data ownership (bắt đầu từ đăng ký / login lần đầu).

2. Nguyên tắc (từ architecture SoT) ​

  1. Không share database giữa Applications — khi Application có DB riêng, Application không đọc DB của Application khác (nguyên tắc nền; schema App không nằm trong gói này).
  2. Ownership rõ — Platform Core, File Service, Payment, Invoice sở hữu dữ liệu của mình.
  3. Business ID dạng {prefix}_{nanoid} (D-017); sắp xếp thời gian qua created_at.
  4. Thời gian = UTC (offset 0): mọi timestamp nghiệp vụ lưu/so sánh theo UTC. PostgreSQL: ưu tiên TIMESTAMPTZ, session/TimeZone = UTC (cài đặt server & app connection). Client (web/app) chủ động format sang local TZ khi hiển thị. Cron File Service: node-cron với timezone: 'UTC'; off-peak = giờ UTC trong biểu thức — không cột window_tz.
  5. Hệ thống ngoài (Keycloak, object store, Matrix, Infisical) không thiết kế schema nghiệp vụ MINAP ở đây — xem 90. Store bên ngoài.

3. Danh mục ​

3.1 Relational DB trong phạm vi gói này ​

Quy ước tên vật lý (Owner):

  • MySQL / MariaDB → cột Tên vật lý = database name
  • PostgreSQL → cột Tên vật lý = schema name (không dùng public làm SoT ownership; mỗi bounded context một schema)
IDTênTên vật lýEngineMô tảOwner pathTài liệuTrạng thái
db-platform-corePlatform Core DBplatform_corePostgreSQL DECIDED (D-022)Account, Workspace, membership; sau này catalog / app_… / entitlementplatform-core/01Một phần (Account/Workspace đã có); catalog/app_…/entitlement PROPOSED
db-file-serviceFile Service DBfile_servicePostgreSQL DECIDED (D-022)Metadata file (file_id, quota, object key) — không chứa bytesplatform-file-service/02Ownership DECIDED; bảng/schema chi tiết OPEN
db-paymentPayment Integration DBpaymentPostgreSQL DECIDED (D-022)Trạng thái / connector payment dùng chungreserved platform-payment/03Capability PROPOSED; engine DECIDED
db-invoiceInvoice Integration DBinvoicePostgreSQL DECIDED (D-022)Trạng thái / connector invoice–tax dùng chungreserved platform-invoice/04Capability PROPOSED; engine DECIDED

ID = mã ổn định trong docs (db-…). Tên = tên gọi đọc được. Tên vật lý = PostgreSQL schema name (D-022). Chi tiết: file 01–04.

3.2 Ngoài phạm vi — Application DB ​

DB domain của Application (A/B/C, Salon, …) không thuộc gói thiết kế database lần này. Chúng sẽ có tài liệu riêng khi Application được Gate / discovery. Nguyên tắc ownership Application vẫn giữ ở architecture SoT tổng thể.

3.3 Không phải RDBMS nghiệp vụ MINAP (vẫn ghi tài liệu) ​

IDTênVai tròTài liệu
store-keycloakKeycloak DBIdP users / credentials90
store-objectMinIO / S3 / R2Bytes file90
store-matrixMatrix / Synapse DBChat state90
store-infisicalInfisicalSecrets / ENV (D-016)90
store-variant-cacheVariant disk + variant_cacheCache multi-size; GC bằng job appFile Service + 90

4. Quan hệ logic ​

5. Engine / topology ​

Phân tích + quyết định: 91. Engine MySQL vs PostgreSQL — R1–R5 DECIDED (D-022).

Chủ đềTrạng thái
Engine mặc định (R1)DECIDED PostgreSQL
Platform Core (R2)DECIDED PostgreSQL → schema platform_core
File / Payment / Invoice (R3)DECIDED PostgreSQL → schema file_service / payment / invoice
Topology non-prod (R4)DECIDED phương án A — một Postgres database + nhiều schema
Dual-engine (R5)DECIDED không mặc định MySQL+Postgres trong lớp này
Backup / HA; isolation productionOPEN

6. Mẫu tài liệu (mỗi file database) ​

Một file = một database (không tách “mục lục” và “schema chi tiết” thành hai trang architecture). Mỗi 0x-*.md nên có:

  1. Mục đích + owner repo
  2. Engine / topology
  3. ER
  4. Bảng → cột (kiểu, null, PK/FK, nguồn dữ liệu, ghi chú)
  5. Index / bất biến
  6. Ngoài phạm vi

Ví dụ đã đầy đủ: 01. Platform Core. File / Payment / Invoice bổ sung cột trong chính 02–04 khi thiết kế.

7. Vòng feedback ​

Owner đọc và feedback trực tiếp trên SoT dưới docs/architecture/database/. Thay đổi material: sửa một lần tại đây.

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