PHẦN 2 — CẤU TRÚC & CẤU HÌNH

2.1 Mô hình repo (docs + src trong một repo)

Toàn bộ dự án nằm trong một repo GitLab duy nhất tên thaco-voc. Bên trong có hai thư mục song song: docs/ (tài liệu — BA + PM sở hữu) và src/ (source code — DEV sở hữu). Không tách thành hai repo riêng, không cần GitLab Group.

thaco-voc/                 ← 1 repo GitLab duy nhất
├── CLAUDE.md
├── docs/                  ← BA + PM sở hữu, DEV ghi được trong docs/02-requirements/spec/
└── src/                   ← DEV sở hữu (source code)

Mọi người clone một repo, mở Claude Code ở gốc repo để thấy được cả tài liệu lẫn code:

~/work/thaco-voc/          ← mở Claude Code ở ĐÂY (gốc repo)
├── CLAUDE.md
├── docs/
└── src/

2.2 Cây thư mục docs/

Cấu trúc bên trong thư mục docs/ (nằm ở gốc repo thaco-voc, cạnh src/):

docs/
├── CLAUDE.md
├── README.md
├── .claude/
│   ├── roles/{ba,dev,pm}.md
│   └── commands/
│       ├── clarify.md          # /clarify    — sinh câu hỏi làm rõ
│       ├── prd.md              # /prd        — viết PRD theo template
│       ├── spec.md             # /spec       — sinh spec từ PRD
│       ├── trace.md            # /trace      — đối chiếu AC ↔ test
│       ├── dor-check.md        # /dor-check  — kiểm điều kiện giao DEV
│       └── weekly.md           # /weekly     — sinh báo cáo tuần
├── .gitlab/
│   ├── issue_templates/{Feature,Bug,Change-Request}.md
│   └── merge_request_templates/Default.md
├── CODEOWNERS
│
├── 00-inbox/                   # [BA+PM ghi] nguyên liệu thô
│   ├── meetings/ · emails/ · attachments/
│
├── 01-analysis/                # [BA ghi]
│   ├── open-questions.md · clarification-log.md · glossary.md
│   ├── as-is/ · to-be/
│
├── 02-requirements/            # [BA ghi]
│   ├── srs.md · business-rules.md
│   ├── prd/
│   │   ├── FE-001-quan-ly-tien-do-giao-xe.md
│   │   └── _template/prd-template.md
│   ├── spec/
│   │   ├── FE-001-spec.md
│   │   └── _template/spec-template.md
│   └── change-requests/
│
├── 03-design/                  # [BA + DEV]
│   ├── architecture/ · data-model/ · api-contract/ · ui-ux/
│
├── 04-dev/                     # [DEV ghi]
│   ├── tech-notes/ · adr/ · conventions.md
│
├── 05-qa/                      # [PM ghi, DEV bổ sung]
│   ├── test-cases/ · uat/ · defects/
│
├── 06-reports/                 # [PM ghi]
│   ├── raw/ · weekly/ · sprint/
│   ├── metrics-definition.md
│   └── trace-matrix.md
│
└── 99-archive/

2.3 Ranh giới ghi

Ký hiệu: ✍️ được ghi · 👁 chỉ đọc · ❌ không đụng vào. Các thư mục dưới đây nằm trong docs/; riêng src/ là source code.

Thư mục spec/ là ngoại lệ có chủ ý — spec là hợp đồng giữa BA và DEV, nên cả hai phải chạm được vào nó. Đổi lại, mọi thay đổi trong thư mục này bắt buộc qua MR có BA approve:

# CODEOWNERS (đặt ở gốc repo thaco-voc)
/docs/02-requirements/spec/   @ba @dev
/docs/                        @ba @pm
/src/                         @dev

2.4 Quy ước đặt tên

Mã cấp AC là thay đổi quan trọng nhất của v2.0. FE-001 quá thô để đối chiếu — phải xuống tới từng tiêu chí nghiệm thu thì mới trả lời được câu hỏi "yêu cầu này đã có code và test chưa".

2.5 Cấu hình ba AI

Cơ chế nạp context — ba tầng:

Mỗi người thêm vào ~/.claude/CLAUDE.md trên máy mình:

Trong dự án thaco-voc, vai trò của tôi là BA.
Trước khi làm bất kỳ việc gì trong dự án này, đọc `.claude/roles/ba.md` và tuân thủ tuyệt đối.

Header metadata — mọi file trong 02-requirements/, 04-dev/, 05-qa/:

---
id: FE-001
title: Quản lý tiến độ giao xe
owner: BA | DEV | PM
status: draft | reviewing | baselined | approved | changed | deprecated
version: 1.2
gitlab_issue: "#42"
updated: 2026-07-23
source: 00-inbox/meetings/2026-07-21-kickoff.md
---

Riêng file spec thêm ba trường:

prd_baseline: FE-001-v1.0      # tag git của PRD mà spec này dịch ra
approved_by: BA                # ai đã duyệt
approved_at: 2026-07-24

Trường prd_baseline giữ spec không trôi khỏi PRD. Khi PRD lên version mới qua CR, trường này lộ ra ngay spec đang bám vào bản cũ.

2.6 Quy ước GitLab

Scoped labels:

type::feature   type::bug   type::cr   type::task   type::spike   type::doc

status::backlog          ← chưa lên kế hoạch
status::planning         ← đang phân tích / đặc tả / lên kế hoạch (G1–G3)
status::ready-for-dev    ← đã đặc tả xong, sẵn sàng code
status::implement        ← đang code
status::review           ← đang review MR
status::testing          ← đang QC / kiểm thử
status::uat              ← nghiệm thu người dùng
status::pending          ← chờ (gated / lịch / quyết định)
status::blocked          ← bị chặn
status::done             ← hoàn thành

owner::ba      owner::dev     owner::pm
prio::P1       prio::P2       prio::P3
module::voc    module::emenu  module::crm

Trạng thái status::planning gộp cả làm rõ, chốt yêu cầu và đặc tả (G1–G3). Nếu issue nằm ở planning quá lâu, đó là tín hiệu yêu cầu/PRD chưa đủ rõ — chẩn đoán được ngay mà không cần hỏi ai.

Trường bắt buộc trên issue:

Checklist AC trong description — GitLab tự đếm và hiện tiến độ:

## Acceptance Criteria
- [ ] FE-001-AC-01 Hiển thị danh sách xe theo trạng thái giao
- [ ] FE-001-AC-02 Lọc theo khoảng ngày dự kiến giao
- [ ] FE-001-AC-03 Chặn tạo phiếu trùng VIN trong cùng ngày