rules/naming-convention.md

Naming Convention — Issue / Phase / Track ID

TL;DR: Từ 2026-04-25 trở đi, mọi gap / feature mới chỉ dùng namespace Pxx-yy (priority tier). Các namespace L1-L6, Track A-E, Phase 0-8 là legacy, giữ nguyên cho lịch sử nhưng KHÔNG tạo mới.

1. Tại sao có doc này

Project lịch sử dồn 4 namespace song song:

Namespace Phạm vi Ví dụ Source of truth
Pxx-yy Primary — gap tracker P0-1, P1-4, P2-13 progress/gaps-and-plan.md
Lx Loyalty phased rollout L1, L2, ..., L6 flows/loyalty-flow.md
Track [A-E][0-9]? Payment code work unit Track D1, Track C2, Track E1 Commit messages + progress/features.md Epic 6
Phase [0-8] Payment context broad phase Phase 5, Phase 7 Track D1 architecture/payment-architecture.md

Cùng 1 feature có thể bị reference 3 cách → search khó, người mới đọc dễ confused. Decision 2026-04-25: chuẩn hoá going-forward, giữ legacy.

2. Convention chính (BẮT BUỘC dùng từ giờ)

Pxx-yy — Priority tracker

Format: P{tier}-{seq} — tier là 0/1/2/3, seq là số thứ tự trong tier (gán tăng dần khi tạo gap mới).

Tier nghĩa:

Tier Nghĩa Ví dụ
P0 Blocker production. Salon thật sẽ gặp trong tuần đầu vận hành. P0-1 force cancel, P0-2 deposit guard, P0-3 walk-in IN_PERSON
P1 Important trước launch công khai. Gap UX hoặc safety. P1-1 customer self-cancel, P1-4 retry payment, P1-11 7-day cap
P2 Nice-to-have / post-MVP. P2-13 reconciliation cron, P2-17 optimistic locking
P3 Future / out-of-scope. (chưa có item nào)

Khi nào tạo Pxx mới:

  • Phát hiện gap qua audit / production incident / spec review.
  • Add row vào progress/gaps-and-plan.md section tương ứng tier.
  • Pick seq = max hiện tại + 1 trong tier đó (ví dụ tier P1 đang có max P1-11 → next là P1-12).
  • Mention trong status-matrix files liên quan + checkbox [ ].

Format checkbox:

3. Legacy namespaces (giữ nguyên, KHÔNG tạo mới)

Lx — Loyalty phase

L1 → L6 là 6 phase tuần tự cho Loyalty discount feature:

Phase Status (2026-04-25) Scope
L1 ✅ Schema migration + backfill
L2 ✅ computeLoyaltyDiscount pure helper (19 tests)
L3 ✅ Reserve on booking create + DDD layering
L4 ⏳ Lifecycle listeners (CONSUMED on COMPLETED, rollback on CANCELLED)
L5 ⏳ Public API + customer UI redemption picker
L6 ⏳ Admin UX (view redemption, apply hộ khách) + E2E

Nếu cần thêm Loyalty work item mới sau L6 → tạo Pxx-yy thay vì L7.

Track [A-E][0-9]? — Payment code work unit

Code work unit nội bộ Payment context, đã commit:

Track Scope Status
Track A Foundation primitives (CQRS, outbox, events) ✅
Track B Booking ↔ Payment plumbing ✅
Track C1/C2/C3/C4 Public deposit flow (init / webhook / capture / admin UI) ✅
Track D1/D2/D3 Admin UI (provider config / payment list / booking lead-time) ✅
Track E1 Remaining payment QR ✅

Tất cả Track A-E1 đã ship hết — không tạo mới. Code work unit mới cứ dùng commit message conventional (feat(payment): ...) là đủ.

Phase [0-8] — Payment context broad phase

Legacy từ payment-architecture spec ban đầu. Phần lớn đã merge vào Track A-E:

Phase = Track tương ứng
Phase 0-5 Track A (foundation)
Phase 6 Track A Track B (Outbox publisher)
Phase 6 Track B Track B (Booking events)
Phase 7 Track D1 Track D1 (admin payment config)

Khi đọc payment-architecture cũ thấy "Phase X" → tra cross-ref bảng trên.

4. Quy tắc thực hành

DO

  • ✅ Tạo Pxx-yy mới cho mọi gap / feature work mới (kể cả Loyalty / Payment).
  • ✅ Reference Pxx trong commit message: feat(status-matrix): ship P1-12 retry exhausted notification.
  • ✅ Tag DEFER với cùng prefix: <!-- DEFER:p1-12-magic-link ... -->.
  • ✅ Trong code comment, link Pxx về doc: // P1-12: see progress/gaps-and-plan.md.

DON'T

  • ❌ Tạo L7, Track F, Phase 9 mới — dùng Pxx-yy.
  • ❌ Reference 1 feature bằng 2 namespace cùng lúc trong commit / doc mới (e.g. "P1-4 / Track L4" — gây nhiễu).
  • ❌ Rename Pxx đã có (ví dụ P1-4 đã ship — đừng đổi thành P1-04 hoặc P14). Số sequence là immutable.

5. Liên quan