Skip to content

Sổ quyết định và câu hỏi mở MINAP ​

Version: 1.1
Date: 2026-11-16
Status: Working baseline

1. Quyết định DECIDED / ràng buộc ESTABLISHED ​

IDChủ đềStatusVị trí hiện tại
D-001Mô hình AccountDECIDEDMột người = một MINAP Account
D-002Mô hình WorkspaceDECIDEDPersonal + Organization Workspace từ MVP
D-003Thuật ngữ ApplicationDECIDEDApplication A/B/C
D-004Hướng authenticationESTABLISHEDKeycloak trung tâm; MVP Email/Password + Google Login. Provider social thêm (Apple / Microsoft / GitHub / …) = Identity Brokering trên Keycloak; federated reference ids do Keycloak quản lý; Platform Core chỉ giữ accounts.keycloak_subject (một sub ↔ một acc_…), không nhân bản từng provider id vào Core DB
D-005Tích hợp lưu trữDECIDED DIRECTIONApplication dùng File Service; abstraction S3-compatible; DB File Service = SoT metadata; object storage / local giữ bản gốc; variant on-demand WebP multi-size (FS_VARIANT_ROOT/{file_id}/{size}.webp + bảng variant_cache / job GC). Multi-connection: storage_connections; Infisical: KEK + disk roots (D-016). MinIO Community không mặc định mới — database/92 + database/02-file-service
D-006DeployDECIDEDDocker Swarm; Nginx luôn edge/TLS. Flow 1 mặc định Client→Nginx→Swarm (admin/API). Flow 2 Client→Nginx→Traefik→Swarm chỉ cho UX người dùng cuối quan trọng cần discovery/LB động
D-007ReleaseDECIDEDBlue-Green + rollback nhanh qua Traefik cho portal Flow 2; Flow 1 có thể cutover đơn giản hơn nếu chấp nhận downtime ngắn
D-008Phát triển với AIDECIDEDOrchestrator + bảy chuyên gia + Human Approval Gates
D-009SDDESTABLISHEDSpec Kit gắn Cursor làm SDD artifact engine; không phải Orchestrator
D-019Implement engineDECIDED DIRECTIONSau Gate 1C, ưu tiên Superpowers (TDD, subagent/executing-plans, review, đóng branch) để chạy tasks.md đã duyệt; Spec Kit giữ SoT constitution→tasks→converge; /speckit-implement là fallback cho slice nhỏ; Superpowers không duyệt Gate. Chi tiết: docs/framework/04-sdd-workflow.md
D-010Identity ChatDECIDEDMột MINAP Account ↔ một Matrix Account
D-011General ChatESTABLISHEDToàn nền tảng, ban đầu miễn phí
D-012Lưu trữ ChatESTABLISHEDMặc định 5 GB / user cá nhân hoặc Workspace doanh nghiệp; Cloud Storage add-on thêm
D-013Business ChatDEFERREDCụm DB và file storage tách riêng trong tương lai
D-014Topology repositoryDECIDEDMột workspace MINAP local; các repo platform-common (platform-core, platform-api, platform-sdk, platform-file-service, platform-infra, platform-ui, …) và mỗi Application là git remote độc lập checkout dưới path gốc dành sẵn; hub không chứa nested source. Config ops open-source dùng chung nằm ở platform-infra/ (không tách remote từng tool). Path common thêm (Chat, Payment, Invoice, App Shell) dành sẵn khi được ủy quyền — xem docs/framework/12-workspace-topology.md
D-015Ngôn ngữ tài liệuDECIDEDSoT duy nhất dưới docs/ (VitePress) / specs/ / governance/; không còn docs-site/ hay dual-update EN/VI; văn xuôi tiếng Việt + thuật ngữ chuyên ngành English; không prefix URL /vi. Spec Kit giữ cấu trúc template, nội dung mô tả tiếng Việt. Chat Gate/QA với Owner: Orchestrator confirm bằng tiếng Việt, một câu mỗi lượt, rồi cập nhật SoT — xem docs/framework/13-documentation-language.md
D-016Secrets và ENVDECIDEDOpen-source Infisical (ưu tiên self-hosted) là SoT cho secrets và environment variables; không commit secrets hay production ENV vào git; Application/service nhận qua cơ chế inject đã duyệt của Infisical (ví dụ sync/agent/CI), không dùng file .env dùng chung ad-hoc trong repo
D-017Business identifiersDECIDEDID nghiệp vụ ổn định là string, không dùng integer auto-increment. Format: {prefix}_{nanoid} với alphabet/length NanoID thống nhất toàn platform; ví dụ file_…, acc_…, org_…, ws_…, app_…. Sắp xếp thời gian dùng created_at (không dựa ID). Bắt buộc prefix với ID MINAP ổn định trên API/SDK/URL/log; bỏ prefix chỉ với ID thuần nội bộ hoặc ID vendor ngoài (Keycloak sub, Matrix, payment provider) map qua bảng tham chiếu
D-018Platform SDK / Application API credentialsDECIDED DIRECTIONThao tác data/platform qua SDK đi Platform API đã authenticate. Platform Core đăng ký Application dạng app_{nanoid} và cấp Platform API credential (app_id + token/secret). Hai lớp: user session (OIDC) vs Application credential (chỉ backend; Infisical; không nhét browser bundle). Core sở hữu issue/rotate/revoke, hash, scope, rate limit, audit. Community sau này: login → developer mode → Platform admin verify → tự tạo credential (UX kiểu GitHub PAT), luôn gắn app_…. Xem 09-platform-sdk-and-application-contracts.md §5
D-020Shared UI kitDECIDED DIRECTIONUI kit dùng chung nằm ở platform-ui/ (không phải platform-sdk). Toolchain: shadcn-like web kit trên Next.js (DOM; thường Tailwind + primitive compose kiểu shadcn/ui). Mobile-First; phải chạy ổn trong mobile WebView. Mô hình mobile MVP: React Native là shell WebView load cùng UI web — một bộ component web, không yêu cầu parity component native RN. MVP không bắt buộc Tamagui / RN-Web / dual native renderer. platform-web (App Shell) và frontend Application opt-in consume kit; màn hình domain ở repo Application. Chỉ nâng lên shared native/universal qua change control nếu sau này cần màn RN native thật
D-021Đặt tên Platform CoreDECIDEDNested repo / package / ranh giới sản phẩm trước đây gọi platform-domain / “Platform Domain” đổi thành platform-core / “Platform Core” (npm @minap/platform-core). Docs, topology và Agent rules dùng Platform Core. Work item lịch sử có thể còn tên cũ cho đến khi viết lại.
D-022RDBMS platform (gói database)DECIDEDPostgreSQL là engine mặc định cho Platform Core, File Service, Payment, Invoice (R1–R5, Owner 2026-11-16). Tên vật lý = schema name: platform_core, file_service, payment, invoice. Non-prod ưu tiên một Postgres database + nhiều schema (phương án A); isolation production vẫn OPEN. Không dual-engine MySQL+Postgres mặc định trong lớp này. Chi tiết: docs/architecture/database/91-engine-mysql-vs-postgresql.md. Application DB ngoài phạm vi gói này.

2. Đề xuất cần Owner xác nhận ​

IDĐề xuấtLý do
P-001Coi Salon là Application A cho pilot lát cắt dọc đầuĐã có đề xuất discovery; vẫn cần xác nhận khách hàng
P-002Xây Payment Integration và Invoice Integration thành hai capability có biên riêngVòng đời, đối soát và tuân thủ khác nhau
P-003Salon MVP bắt đầu ghi thanh toán thủ công; hoãn gateway tự độngGiảm phức tạp provider/onboarding trong lúc xác nhận giá trị sản phẩm
P-004Giữ helper custom label/field trong Platform SDK, backed bởi Platform API/cấu hìnhTái sử dụng hành vi nhưng giữ ownership và validation phía server
P-005Cô lập tenant logic mặc định; storage riêng là option enterpriseCân bằng chi phí và yêu cầu cô lập mạnh hơn

3. Câu hỏi mở ​

Platform và repository ​

  • URL remote chính xác của platform-core và từng Application? (ghi trong .minap/config/repos.yaml)
  • Repository triển khai đầu và môi trường deploy là gì?
  • Phân rã module/service Platform Core cụ thể thế nào?
  • Công nghệ database (engine) nào được chọn? → DECIDED D-022 PostgreSQL (R1–R5). Còn OPEN: thiết kế backup/HA cụ thể; isolation production (một DB nhiều schema vs tách DB).
  • Topology Infisical: một project dùng chung hay theo từng Application; môi trường nào (local/staging/production); ai được rotate secrets; đường inject CI/CD?
  • Alphabet, length NanoID chính xác và sổ prefix chuẩn (acc, org, ws, file, tmp, app, …) cho Platform Core và dịch vụ dùng chung? (FS: prefix chỉ file/tmp; storage_connections không prefix — xem database/02-file-service §4)

Hybrid SDD (Spec Kit + Superpowers) ​

  • Ưu tiên marketplace /add-plugin superpowers hay giữ plugin local ~/.cursor/plugins/local/superpowers cho mọi developer?
  • Luôn Superpowers sau 1C, hay fallback /speckit-implement theo kích thước?
  • Handoff qua Orchestrator vs bridge Spec Kit↔Superpowers tự động?
  • Bootstrap TDD khi repo đích chưa có test harness?
  • Chính sách bump khi Superpowers ra bản mới sau pin 7.0.2 trong .minap/config/framework.yaml?

Identity và workspace ​

  • Một realm Keycloak hay nhiều realm?
  • Account linking + session/thiết bị UX: Keycloak Account Console vs custom UI gọi API (SoT vẫn Keycloak)? Lịch sử login dài hạn: chỉ Keycloak Events hay thêm Core audit_events? Lời mời tổ chức, chuyển ownership và xóa account?
  • Application role và quyền mức resource biểu diễn và cache thế nào?

Application A — Salon ​

  • Chỉ tóc, hay salon/beauty/nail/spa?
  • Walk-in trước hay lịch hẹn bắt buộc ở MVP?
  • Một lượt một hay nhiều dịch vụ? Nhiều nhân viên / lượt?
  • Hoa hồng, giảm giá, hoàn tiền và tách thanh toán?
  • Salon nào sẽ xác nhận workflow và giả thuyết giá?

Payment và invoice ​

  • Provider thanh toán nào onboard được dưới tình trạng pháp lý/kinh doanh thực tế?
  • Xác nhận chuyển VietQR thủ công hay đối soát tự động?
  • Loại hóa đơn và connector provider nào thực sự cần?
  • Trách nhiệm tuân thủ của MINAP so với merchant và provider?

File Service và Chat ​

  • Schema metadata File Service cụ thể và Application được cache field nào local?
  • Variant: tập MIME input; xác nhận allowlist size (đề xuất 96/128/192/256/384/512/768/1024); quality/seek ffmpeg; đa node / shared FS_VARIANT_ROOT; key DB config.variant.* (output WebP + video frame đầu đã quyết)
  • Hạn mức 5 GB dùng chung các Application hay riêng Chat?
  • Chủ thể billing quota và hành vi downgrade?
  • Matrix server/client SDK và chính sách federation nào?
  • Đính kèm Matrix map sang ủy quyền File Service thế nào (variant vs original)?
  • Mô hình retention và mã hóa cần gì?

UI kit và frontend shell ​

  • Pin phiên bản/package cụ thể cho stack shadcn-like (Tailwind major, cách registry component, layout publish trong platform-ui).
  • Consumer đầu: chỉ App Shell (platform-web) và Application A, hay kit-first trước Shell?
  • Dark mode, density, Workspace theming — trong kit MVP hay sau?
  • IA/navigation App Shell và Next.js app nào host route nào (kit D-020 = web + WebView; composition Shell vẫn OPEN).
  • Khi nào (nếu có) mở lại shared component native/universal ngoài mô hình WebView shell.

SDK ​

  • Hai Application nào biện minh cho package SDK dùng chung đầu tiên?
  • Entity nào mở điểm mở rộng custom-field?
  • Custom field có searchable/reportable/exportable ở MVP không?
  • Platform API credential: tên sản phẩm, wire format (header scheme, token prefix/độ dài) và OpenAPI security scheme?
  • Scope mặc định/tối đa; gắn Workspace vs Application vs cả hai?
  • Lifetime, rotate, dual-active keys, tách env (dev/staging/prod), playbook khi lộ?
  • MVP: chỉ credential do platform cấp, hay sớm có portal developer mode?
  • Tiêu chí/SLA verify của admin cho community developer mode?
  • MVP có cần on-behalf-of (ghép user session + Application credential) không?

4. Quy tắc change-control ​

Khi Owner giải quyết mục OPEN hoặc duyệt mục PROPOSED:

  1. Thêm decision ID, ngày, quyết định, lý do và tài liệu bị ảnh hưởng.
  2. Cập nhật master index.
  3. Cập nhật kiến trúc và Application spec liên quan.
  4. Ghi nhận tác động migration/tương thích.
  5. Vô hiệu và lặp lại Gate phê duyệt liên quan nếu yêu cầu hoặc kiến trúc đã duyệt thay đổi.

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