Appearance
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
| ID | Chủ đề | Status | Vị trí hiện tại |
|---|---|---|---|
| D-001 | Mô hình Account | DECIDED | Một người = một MINAP Account |
| D-002 | Mô hình Workspace | DECIDED | Personal + Organization Workspace từ MVP |
| D-003 | Thuật ngữ Application | DECIDED | Application A/B/C |
| D-004 | Hướng authentication | ESTABLISHED | Keycloak 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-005 | Tích hợp lưu trữ | DECIDED DIRECTION | Application 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-006 | Deploy | DECIDED | Docker 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-007 | Release | DECIDED | Blue-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-008 | Phát triển với AI | DECIDED | Orchestrator + bảy chuyên gia + Human Approval Gates |
| D-009 | SDD | ESTABLISHED | Spec Kit gắn Cursor làm SDD artifact engine; không phải Orchestrator |
| D-019 | Implement engine | DECIDED DIRECTION | Sau 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-010 | Identity Chat | DECIDED | Một MINAP Account ↔ một Matrix Account |
| D-011 | General Chat | ESTABLISHED | Toàn nền tảng, ban đầu miễn phí |
| D-012 | Lưu trữ Chat | ESTABLISHED | Mặc định 5 GB / user cá nhân hoặc Workspace doanh nghiệp; Cloud Storage add-on thêm |
| D-013 | Business Chat | DEFERRED | Cụm DB và file storage tách riêng trong tương lai |
| D-014 | Topology repository | DECIDED | Mộ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-015 | Ngôn ngữ tài liệu | DECIDED | SoT 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-016 | Secrets và ENV | DECIDED | Open-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-017 | Business identifiers | DECIDED | ID 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-018 | Platform SDK / Application API credentials | DECIDED DIRECTION | Thao 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-020 | Shared UI kit | DECIDED DIRECTION | UI 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 Core | DECIDED | Nested 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-022 | RDBMS platform (gói database) | DECIDED | PostgreSQL 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ất | Lý do |
|---|---|---|
| P-001 | Coi 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-002 | Xây Payment Integration và Invoice Integration thành hai capability có biên riêng | Vòng đời, đối soát và tuân thủ khác nhau |
| P-003 | Salon MVP bắt đầu ghi thanh toán thủ công; hoãn gateway tự động | Giảm phức tạp provider/onboarding trong lúc xác nhận giá trị sản phẩm |
| P-004 | Giữ helper custom label/field trong Platform SDK, backed bởi Platform API/cấu hình | Tái sử dụng hành vi nhưng giữ ownership và validation phía server |
| P-005 | Cô lập tenant logic mặc định; storage riêng là option enterprise | Câ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-corevà 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_connectionskhông prefix — xemdatabase/02-file-service§4)
Hybrid SDD (Spec Kit + Superpowers)
- Ưu tiên marketplace
/add-plugin superpowershay giữ plugin local~/.cursor/plugins/local/superpowerscho mọi developer? - Luôn Superpowers sau 1C, hay fallback
/speckit-implementtheo 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.2trong.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 DBconfig.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:
- Thêm decision ID, ngày, quyết định, lý do và tài liệu bị ảnh hưởng.
- Cập nhật master index.
- Cập nhật kiến trúc và Application spec liên quan.
- Ghi nhận tác động migration/tương thích.
- 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.