Mục lục Tài liệu
Tài liệu tổ chức theo 7 nhóm:
| Nhóm | Mục đích | Bắt đầu từ |
|---|---|---|
| Product | Tầm nhìn, business, PRD | product/product-brief.md |
| Architecture | Technical design, API, data model | architecture/architecture.md |
| Flows | Nghiệp vụ end-to-end | flows/booking-flow.md |
| Rules | Conventions bắt buộc | rules/development-rules.md |
| Operations | Setup, deploy, onboarding, troubleshoot | operations/onboarding.md |
| Mobile | Plan cho mobile app (owner + staff) | mobile/feature-plan.md |
| Progress | Tiến độ, changelog, defer | progress/README.md |
Product — Tầm nhìn & PRD
| Doc | Nội dung |
|---|---|
product/product-brief.md |
Business context, target users, MVP scope |
product/prd.md |
User stories, acceptance criteria, API mapping |
Architecture — Technical Design
| Doc | Nội dung |
|---|---|
architecture/architecture.md |
Tech stack, system design, module structure |
architecture/role-matrix.md |
BẮT BUỘC — Ma trận quyền endpoint × role × action (audit pending) |
architecture/api-design.md |
BẮT BUỘC — API conventions, response envelope, error codes |
architecture/payment-architecture.md |
BẮT BUỘC — DDD + Hexagonal Payment bounded context |
architecture/subscription-architecture.md |
BẮT BUỘC khi code SaaS billing — DDD + Hexagonal Subscription bounded context, provider-agnostic (LS/Stripe/Paddle), migration strategy |
architecture/custom-domain.md |
BẮT BUỘC khi code host routing / tenant-by-domain / TLS edge — Caddy on-demand TLS + clean-URL rewrite, TenantDomain model, verification flow, 9 phases |
architecture/embed-widget.md |
Script nhúng booking vào website khác — embed layout, framing/CSP, postMessage, embed.js loader (ưu tiên sau custom-domain) |
Flows — Nghiệp vụ End-to-End
| Doc | Nội dung |
|---|---|
flows/booking-flow.md |
BẮT BUỘC — Booking create/update, settings enforcement, integration events |
flows/booking-status-flow.md |
BẮT BUỘC — State machine, transitions, guards, role matrix |
flows/payment-fundamentals.md |
BẮT BUỘC đọc trước — Concepts (intent, state machine, coupling, payable total), event/error reference, UI map |
flows/payment-flow.md |
BẮT BUỘC — 20 scenarios end-to-end (deposit, cancel, no-show, refund, retry, reconciliation, QR remaining) |
flows/subscription-flow.md |
BẮT BUỘC khi code SaaS billing — 12 scenarios (trial, checkout, dunning, cancel, reactivation, provider migration) |
flows/loyalty-flow.md |
Loyalty redemption + auto-earn lifecycle |
flows/status-matrix/ |
Bức tranh toàn cảnh — transition matrix theo status × payment × performer (gaps + roadmap đã chuyển sang progress/gaps-and-plan.md) |
Rules — Conventions Bắt Buộc
| Doc | Nội dung |
|---|---|
rules/development-rules.md |
BẮT BUỘC — Git, testing, code quality, ESLint, PR rules |
rules/timezone-rules.md |
BẮT BUỘC — UTC in DB, salon-tz in UI, conversion utilities, display snapshot |
rules/ui-conventions.md |
BẮT BUỘC — Admin UI design system |
rules/task-workflow.md |
BẮT BUỘC — Quy trình 7 phases cho mọi task |
rules/naming-convention.md |
BẮT BUỘC — Pxx-yy priority tracker; L/Track/Phase legacy giữ nguyên không tạo mới |
rules/defer-convention.md |
BẮT BUỘC khi defer — Tag format DEFER:<id>, ID naming, resolution workflow. Auto-indexed via yarn --cwd docs defer:list |
Operations — Setup & Deploy
| Doc | Nội dung |
|---|---|
operations/onboarding.md |
Clone, install, chạy local dev |
operations/owner-onboarding.md |
Salon owner onboarding flow |
operations/super-admin-impersonation.md |
Super-admin impersonation — flow, identity model, audit trail, troubleshoot |
operations/docker-deploy.md |
Production deploy — Docker, GHCR, scale + rolling update, Caddy TLS edge (§2.4) |
operations/caddy-dev-setup.md |
Cài Caddy native trên dev server (không Docker) để test custom domain giống production |
operations/deploy-docs-site.md |
Deploy static docs site (PM2 + Nginx) — documents.<domain> |
operations/troubleshooting.md |
BẮT BUỘC khi debug — Symptom → flow doc → code path → common causes. Add row khi fix bug class mới |
operations/gitnexus-setup.md |
GitNexus code intelligence setup |
Mobile — Plan cho Mobile App
| Doc | Nội dung |
|---|---|
mobile/admin-settings-inventory.md |
Inventory toàn bộ cài đặt đang quản lý trên /admin + mức ưu tiên khi port lên mobile |
mobile/feature-plan.md |
Kiến trúc thông tin + phân pha MVP/V1/V2 cho owner + staff app, milestone, dependencies backend |
Progress — Tiến Độ
| Doc | Nội dung |
|---|---|
progress/README.md |
Bắt đầu từ đây — Map câu hỏi tiến độ → file, quick snapshot, workflow check |
progress/features.md |
Feature overview & status |
progress/changelog.md |
Development history, test coverage |
progress/testing.md |
Test inventory (unit / integration / E2E) across all repos |
progress/DEFERRED.md |
Auto-generated — Open defers (xem rules/defer-convention.md) |
progress/gaps-and-plan.md |
Status-matrix gap roadmap — P0/P1/P2 prioritized, link evidence cho mỗi item đã ship |