Appearance
Thuật ngữ
Version: 1.6
Date: 2026-11-19
Status: Working baseline
| Thuật ngữ (English) | Hiểu nhanh |
|---|---|
| MINAP (Min-Áp) | Minimum Applications — nền tảng nhiều app nhỏ, dùng chung một tài khoản |
| Platform Core | Phần nền tảng chung (đăng nhập, workspace, catalog…) |
| IdP (Identity Provider) | Hệ thống xác thực đăng nhập (MINAP dùng Keycloak); cấp OIDC token / sub — không phải SoT Account acc_… |
| Federated identity | Liên kết login social (Google, Apple, Microsoft, GitHub, …) trên Keycloak; reference id từng nhà cung cấp không lưu trên Platform Core — chỉ map qua Keycloak sub → acc_… |
| User session (IdP) | Phiên đăng nhập trên một client/thiết bị do Keycloak giữ; đăng xuất từng máy / tất cả = xóa session trên IdP — không SoT session table trên Platform Core |
| Application A/B/C | Tên gọi các ứng dụng nghiệp vụ (không gọi “Product”) |
| MINAP Account | Một người = một tài khoản trên toàn MINAP |
| Personal Workspace | Không gian làm việc cá nhân |
| Organization Workspace | Không gian làm việc của tổ chức / cửa hàng |
| Workspace Membership | Ai thuộc workspace nào, với vai trò gì |
| Platform SDK | Bộ công cụ/hợp đồng để App gắn vào nền tảng; thao tác data ưu tiên qua Platform API có token |
Platform UI (platform-ui) | shadcn-like web kit (Next.js), Mobile-First; browser + RN WebView shell (D-020); không nhầm với Platform SDK |
| shadcn-like | DX compose kiểu shadcn/ui (Tailwind + primitive); kit web DOM — không phải component native RN |
app_id / app_{nanoid} | ID Application đã đăng ký trên Platform Core (D-017/D-018) |
| Platform API credential | Cặp app_id + token/secret do Core cấp; chỉ backend (Infisical); tách biệt user session OIDC |
| File Service | Dịch vụ lưu/tải file dùng chung; metadata trong DB File Service; bytes temp/local/cloud theo storage_name + storage_key |
| Infisical | Open-source (ưu tiên self-hosted) lưu secrets và ENV — SoT theo D-016; không commit secrets vào git |
| Variant cache | Bản WebP multi-size on-demand: disk FS_VARIANT_ROOT/{file_id}/{size}.webp + bảng variant_cache; GC = created_at + variant.ttl (parse vercel/ms; xóa vật lý); size ∈ allowlist; video = frame đầu tĩnh |
ms (vercel/ms) | Parse duration string (30m, 7d, …) → milliseconds — dùng cho temp.ttl / local.retain / variant.ttl trong File Service config |
| node-cron | Scheduler cron Node.js (node-cron/node-cron) — File Service job (*_cron); SoT dùng timezone: 'UTC' + noOverlap: true |
| NanoID | Thư viện sinh ID string ngắn; phần sau prefix trong D-017 |
| UTC (tz=0) | Quy ước lưu/so sánh timestamp nền tảng; Postgres TIMESTAMPTZ + TimeZone=UTC; client format local TZ khi hiển thị (database/00 §2) |
{prefix}_{nanoid} | Format ID nghiệp vụ ổn định lộ API/SDK (vd. file_…, tmp_…, acc_…, ws_…, app_…); không auto-increment; sort theo created_at. ID thuần nội bộ service không bắt buộc prefix — vd. storage_connections.id (D-017) |
file_id | ID ổn định do File Service cấp dạng file_{nanoid}; Application chỉ lưu tham chiếu này — không dùng làm tên object trên disk |
storage_name | Basename vật lý {uuidv7}.{ext} trên temp + files; tách khỏi file_id / tmp_… (ops / version / quarantine sau này) |
storage_key | Relative path chung local + cloud: {acc}/{source_id hoặc _}/{YYYY}/{MM}/{DD}/{storage_name}; kết thúc bằng storage_name |
| Display name / alias | Tên file người dùng thấy — khác storage_name / storage_key trên disk |
| Spec Kit | Tool SDD của GitHub — artifact engine (constitution → tasks + converge); không phải Orchestrator |
| Superpowers | Methodology/skills (obra) — engine implement ưa thích sau Gate 1C (TDD, subagent, review); không thay Spec Kit SoT hay Gate (D-019) |
| Orchestrator | Chat Cursor Agent chính — điều phối specialist + Spec Kit + Superpowers; không phải subagent |
| BA Discovery / Product Discovery | Mode BA trước SDD (ba-discovery); chat riêng; gói .minap/discovery/ + handoff prompt; không gọi BA Requirements / Spec Kit |
| BA Requirements | Mode BA trong pipeline Orchestrator (ba-requirements); Specify/Clarify → spec.md; Gate 1A SoT |
| platform-ai | Repo shared AI kit (.cursor/ agents/rules/skills + templates); không phải nơi chứa work-item/spec của từng product repo |
| Target repo | Repo đích của feature/bug (vd. platform-ui) — sở hữu specs/, .specify/, .minap/work-items/, discovery fills, .specify/bugs/<slug>/ |
| Spec Kit bug extension | Opt-in Spec Kit: /speckit-bug-assess → fix → test; báo cáo dưới .specify/bugs/<slug>/; hybrid với Superpowers debugging |
| Gate 1A | Requirements approval — duyệt spec.md (yêu cầu) |
| Gate 1B | Architecture approval — duyệt plan.md / ADR |
| Gate 1C | Implementation authorization — ủy quyền bắt đầu code theo tasks.md; trước đó không code feature |
| Gate 4 | QA verification — QA PASS/FAIL; Owner acceptance delivery là bước tách |
| Gate 5 | Production release approval — duyệt / hoãn phát hành production |
| D-0xx | Decision ID trong sổ 11-decisions-and-open-questions (vd. D-016 Infisical, D-017 NanoID, D-018 API credentials, D-019 Superpowers sau 1C, D-022 PostgreSQL gói DB) — không phải viết tắt Gate |
| PostgreSQL / schema | RDBMS mặc định gói database platform (D-022); tên vật lý = schema (platform_core, file_service, payment, invoice) |
| Constitution | Nguyên tắc bắt buộc của nền tảng (không dịch tên thành “Hiến pháp” trên hub) |
| AC (Acceptance Criteria) | Tiêu chí chấp nhận — phải kiểm chứng được |
| Hub | Repo trung tâm (docs, governance, agents) |
| Nested repo | Repo con (platform-core, application-a…) nằm trong thư mục hub trên máy bạn |
| Version / Date / Status | Nhãn metadata chuẩn (English) ngay sau H1; Date = ISO YYYY-MM-DD |
| Owner Gate/QA chat | Orchestrator hỏi Owner bằng tiếng Việt, một câu mỗi lượt, rồi cập nhật SoT dưới docs/ / specs/ (D-015) |
| Working baseline | Status: baseline gói đang dùng (docs package Version 1.0) |
| DECIDED | Đã chốt (cũng dùng làm Status meta) |
| PROPOSED | Mới đề xuất — cần bạn duyệt |
| OPEN | Còn bỏ ngỏ |
| DEFERRED | Cố ý hoãn (thường sau MVP) — đã biết hướng nhưng chưa thiết kế/implement sâu; khác OPEN (chưa quyết) và PROPOSED (đề xuất chờ duyệt) |