Skip to content

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ựcTrạng tháiBaseline
Mô hình sản phẩmESTABLISHED DIRECTIONHệ sinh thái Mini-SaaS; UX đơn giản kiểu Mini App
Đặt tên sản phẩmDECIDEDDùng Application A/B/C, không dùng Product A/B/C
IdentityDECIDEDMột người = một MINAP Account; không tạo tài khoản riêng theo từng Application
TenancyDECIDEDHybrid Personal Workspace + Organization Workspaces từ MVP
AuthenticationESTABLISHED DIRECTIONKeycloak tập trung; MVP Email/Password + Google Login
Tích hợp nền tảngESTABLISHED DIRECTIONPlatform Core + Applications độc lập + Platform SDK/contracts; SDK gọi Platform API đã authenticate
Platform API credentialsDECIDED DIRECTIONApplication 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ữ fileDECIDED DIRECTIONApplications 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
DeploymentDECIDEDDocker 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 / ENVDECIDEDOpen-source Infisical (ưu tiên self-hosted) lưu secrets và environment variables; không đưa secrets/production ENV vào git
Business identifiersDECIDEDString 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 releaseDECIDEDBlue-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 AIDECIDEDCentral Orchestrator + bảy vai trò chuyên gia + Human Approval Gates
SDDESTABLISHED DIRECTIONGitHub Spec Kit = SDD artifact engine (tới tasks + converge); không phải Orchestrator
Implement engineDECIDED DIRECTIONƯu tiên Superpowers sau Gate 1C để chạy tasks.md đã duyệt (TDD/subagents/review); Spec Kit implement = fallback (D-019)
Topology repositoryDECIDEDCá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 CoreDECIDEDTê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 kitDECIDED DIRECTIONplatform-ui: shadcn-like web kit trên Next.js; Mobile-First; RN = WebView shell (D-020)
Ngôn ngữ tài liệuDECIDEDSoT 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)DECIDEDPostgreSQL 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 ChatDECIDED DIRECTIONToàn nền tảng, ban đầu miễn phí cho cá nhân và doanh nghiệp
Chat identityDECIDEDMột MINAP Account ánh xạ một Matrix Account
Chat storageDECIDED DIRECTIONMặ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 ChatDEFERREDTươ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ư
SalonPROPOSED APPLICATIONApplication ứng viên đầu tiên; yêu cầu cần xác thực với salon
Tích hợp paymentPROPOSED PLATFORM CAPABILITYDị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/accountingPROPOSED PLATFORM CAPABILITYKhả 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 ​

  1. Bắt đầu nhỏ, giữ điểm mở rộng. Tránh microservices sớm và over-engineering.
  2. Ưu tiên open-source và self-hosted khi vận hành hợp lý (gồm Infisical cho secrets/ENV).
  3. 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.
  4. 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.
  5. Identity tập trung, dữ liệu nghiệp vụ thuộc Application.
  6. Quyền tối thiểu (least privilege) và ủy quyền theo phạm vi Workspace.
  7. 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.
  8. 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.
  9. Phê duyệt của con người cho thay đổi trọng yếu và phát hành production.
  10. 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.

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