Appearance
Mục lục chính và Baseline quyết định MINAP
Version: 1.1
Date: 2026-11-16
Status: Working baseline
1. Hướng sản phẩm
MINAP nghĩa là Min-Áp — Minimum Applications: một nền tảng nhằm giúp các ứng dụng tập trung, giá phải chăng dễ khám phá và sử dụng. Chiến lược sản phẩm là Mini-SaaS Ecosystem với trải nghiệm người dùng đơn giản như Mini App, thay vì tập hợp các tài khoản SaaS rời rạc.
Nền tảng hướng tới thị trường Việt Nam trước. Hướng thương mại là gói đăng ký chi phí thấp, với khoảng mục tiêu ban đầu đã thảo luận từ hơi trên 20.000 VND đến khoảng 200.000–300.000 VND mỗi tháng tùy giá trị ứng dụng và mức sử dụng. Đây là đầu vào chiến lược, không phải bảng giá đã phê duyệt.
2. Từ vựng trạng thái
- DECIDED — Project Owner đã thống nhất rõ ràng; không đổi nếu chưa có quyết định mới.
- ESTABLISHED DIRECTION — hướng nền tảng nhất quán; chi tiết vẫn có thể cần đặc tả.
- PROPOSED — được khuyến nghị nhưng chưa phê duyệt.
- OPEN — cần discovery hoặc quyết định của Owner.
- DEFERRED — cố ý hoãn sau MVP.
3. Baseline hiện tại
| Khu vực | Trạng thái | Baseline |
|---|---|---|
| Mô hình sản phẩm | ESTABLISHED DIRECTION | Hệ sinh thái Mini-SaaS; UX đơn giản kiểu Mini App |
| Đặt tên sản phẩm | DECIDED | Dùng Application A/B/C, không dùng Product A/B/C |
| Identity | DECIDED | Một người = một MINAP Account; không tạo tài khoản riêng theo từng Application |
| Tenancy | DECIDED | Hybrid Personal Workspace + Organization Workspaces từ MVP |
| Authentication | ESTABLISHED DIRECTION | Keycloak tập trung; MVP Email/Password + Google Login |
| Tích hợp nền tảng | ESTABLISHED DIRECTION | Platform Core + Applications độc lập + Platform SDK/contracts; SDK gọi Platform API đã authenticate |
| Platform API credentials | DECIDED DIRECTION | Application nhận diện bằng app_{nanoid}; Platform Core cấp app_id + token (chỉ backend); tách biệt user session (OIDC); sau này developer mode có admin verify (D-018) |
| Lưu trữ file | DECIDED DIRECTION | Applications dùng MINAP File Service; S3-compatible adapter; bản gốc local/cloud; variant on-demand multi-size (WebP, FS_VARIANT_ROOT). MinIO Community không mặc định mới — thay thế PROPOSED (Garage / SeaweedFS / S3 / R2): database/92-object-storage-after-minio |
| Deployment | DECIDED | Docker Swarm; Nginx luôn ở edge. Mặc định: Client→Nginx→Swarm (admin/API). Traefik chỉ cho UX end-user quan trọng: Client→Nginx→Traefik→Swarm |
| Secrets / ENV | DECIDED | Open-source Infisical (ưu tiên self-hosted) lưu secrets và environment variables; không đưa secrets/production ENV vào git |
| Business identifiers | DECIDED | String ID {prefix}_{nanoid} cho entity công khai ổn định (ví dụ acc_, org_, ws_, file_, app_); không dùng auto-increment làm PK nghiệp vụ; sắp xếp theo created_at |
| Chiến lược release | DECIDED | Blue-Green + rollback nhanh cho Flow 2 (Nginx→Traefik) các bề mặt hướng người dùng; Flow 1 có thể cutover đơn giản hơn khi chấp nhận downtime ngắn |
| Phát triển AI | DECIDED | Central Orchestrator + bảy vai trò chuyên gia + Human Approval Gates |
| SDD | ESTABLISHED DIRECTION | GitHub Spec Kit = SDD artifact engine (tới tasks + converge); không phải Orchestrator |
| Implement engine | DECIDED DIRECTION | Ưu tiên Superpowers sau Gate 1C để chạy tasks.md đã duyệt (TDD/subagents/review); Spec Kit implement = fallback (D-019) |
| Topology repository | DECIDED | Các git repo độc lập lồng dưới một workspace MINAP cục bộ (platform-core / platform-api / platform-sdk / platform-file-service / platform-infra / platform-ui / Applications; path common khác dành sẵn sau); hub chỉ chứa governance/docs/agents |
| Đặt tên Platform Core | DECIDED | Tên repo/package/ranh giới là Platform Core (platform-core, @minap/platform-core) — trước đây platform-domain / “Platform Domain” (D-021) |
| Shared UI kit | DECIDED DIRECTION | platform-ui: shadcn-like web kit trên Next.js; Mobile-First; RN = WebView shell (D-020) |
| Ngôn ngữ tài liệu | DECIDED | SoT duy nhất dưới docs/ (VitePress) / specs/; không còn docs-site/; văn xuôi Việt + thuật ngữ English; chat Gate/QA = tiếng Việt, một câu mỗi lượt rồi cập nhật SoT (D-015) |
| RDBMS platform (gói DB) | DECIDED | PostgreSQL mặc định cho Core / File / Payment / Invoice; tên vật lý = schema; non-prod ưu tiên một DB + nhiều schema (D-022, R1–R5) |
| General Chat | DECIDED DIRECTION | Toàn nền tảng, ban đầu miễn phí cho cá nhân và doanh nghiệp |
| Chat identity | DECIDED | Một MINAP Account ánh xạ một Matrix Account |
| Chat storage | DECIDED DIRECTION | Mặc định 5 GB mỗi người dùng cá nhân hoặc business workspace; dung lượng thêm là add-on Cloud Storage |
| Business Chat | DEFERRED | Tương lai: cụm DB và lưu trữ file tách biệt cho tổ chức nhạy cảm về quyền riêng tư |
| Salon | PROPOSED APPLICATION | Application ứng viên đầu tiên; yêu cầu cần xác thực với salon |
| Tích hợp payment | PROPOSED PLATFORM CAPABILITY | Dịch vụ tích hợp payment tái sử dụng, không viết lại trong mọi Application |
| Tích hợp invoice/accounting | PROPOSED PLATFORM CAPABILITY | Khả năng connector tái sử dụng; phạm vi pháp lý/thuế phải được xác thực |
4. Nguyên tắc nền tảng
- Bắt đầu nhỏ, giữ điểm mở rộng. Tránh microservices sớm và over-engineering.
- Ưu tiên open-source và self-hosted khi vận hành hợp lý (gồm Infisical cho secrets/ENV).
- Vòng đời độc lập. Platform Core và từng Application phải cấu hình, triển khai và version độc lập được.
- Tích hợp contract-first. Applications tích hợp qua API đã tài liệu hóa, SDK và hợp đồng có version.
- Identity tập trung, dữ liệu nghiệp vụ thuộc Application.
- Quyền tối thiểu (least privilege) và ủy quyền theo phạm vi Workspace.
- Cách ly dữ liệu phải tường minh. Cách ly tenant logic là mặc định; hạ tầng riêng là tầng isolation cao hơn tùy chọn.
- Không coupling ẩn. Một Application không được phụ thuộc trực tiếp vào database riêng của Application khác.
- Phê duyệt của con người cho thay đổi trọng yếu và phát hành production.
- Không trình bày giả định như quyết định. Giữ sổ quyết định luôn cập nhật.
5. Ranh giới hệ thống khuyến nghị
- MINAP Platform Core: tích hợp identity, ngữ cảnh account/workspace, catalog/launch ứng dụng, Application registry (
app_…) và issue/rotate/revoke Platform API credential, primitive subscription và entitlement, cấu hình nền tảng, primitive audit/event và governance tích hợp. - Platform SDK: helper tích hợp và hợp đồng typed cho identity/workspace context, navigation, localization overrides, custom fields, và client Platform API có chứng thực (Application credentials trên backend; user session trên client). Không phải visual UI kit.
- Platform UI (
platform-ui): shadcn-like web kit dùng chung (Next.js / DOM, Mobile-First) cho App Shell và frontend Application opt-in; mobile qua RN WebView load cùng UI web (D-020). - MINAP File Service: metadata file có thẩm quyền trong database riêng, authorization, vòng đời upload/download, abstraction lưu trữ, quota và chính sách retention; object storage chỉ giữ bytes của file.
- MINAP Chat: trải nghiệm giao tiếp xuyên Application tổng quát, theo hướng Matrix.
- Shared Payment Integration: adapter nhà cung cấp payment, payment intent/status và chuẩn hóa webhook.
- Shared Invoice Integration: connector tới hệ thống invoicing/accounting/tax phù hợp; không thay thế tư vấn pháp lý/thuế hay sản phẩm kế toán đầy đủ.
- Applications: UI theo domain, business logic, data model và workflows.
6. Đặt tên và thuật ngữ
Dùng:
- MINAP Account
- Personal Workspace
- Organization Workspace
- Workspace Membership
- Application A / Application B / Application C
- Platform Core
- Platform SDK
- Platform UI
- File Service
- General Chat / Business Chat
- Payment Integration
- Invoice Integration
Tránh dùng “Product A/B/C”. Tên Application có thể chọn độc lập sau.