# Project Folder Structure

> Cấu trúc thư mục chuẩn cho toàn dự án PILOT — áp dụng cho tất cả role: BA, Dev, Tester, PM/BrSE.

---

## Tổng quan

```
{Root}/                                 ← Thư mục mở bằng VSCode, có thể chứa nhiều source repo
├── {Source-Repo}/                      ← Source code (GitLab repo)
│
├── AK-Docs/                            ← Tài liệu dự án (GitLab repo riêng)
│   ├── 00.Project-Overview/
│   ├── 01.QnA/
│   ├── 02.BA-Specs/
│   ├── 03.Testing/
│   ├── 04.Coding/
│   ├── 05.Rules/
│   ├── 06.Agent-Records/               ← chỉ khi dùng Light-out Agents (akg)
│   ├── 07.Tasks/                       ← file task đầu vào cho Development Team (ak init tạo khung)
│   └── 99.Memory/
│
└── Shared-Docs/                        ← Template dùng chung cho TẤT CẢ dự án (GitLab repo riêng)
    ├── Spec-Templates/
    ├── QA-Templates/
    ├── Testcase-Templates/
    └── Test-Report-Templates/
```

> **Tự động đồng bộ:** Mỗi lần chạy `ak init` hoặc `ak update`, tool sẽ tự kiểm tra `AK-Docs/` và `Shared-Docs/` cạnh source repo — nếu đã tồn tại (và là git repo) sẽ tự `git pull` để lấy bản mới nhất, nếu chưa có sẽ cảnh báo (warning) để bạn clone thủ công.

---

## Chi tiết — `AK-Docs/`

```
AK-Docs/
│
├── 00.Project-Overview/                ← PM / BrSE quản lý
│   ├── Project-Summary.md              # Goals, scope, background, stack
│   ├── Function-List.md                # F-ID | Feature | BA | Dev | Tester | Status | Tickets | Link Spec
│   ├── Glossary.md                     # Thuật ngữ | Viết trong tài liệu | Nghĩa | Nguồn (create-spec Bước 0.6)
│   └── Team.md                         # Member, role, contact
│
├── 01.QnA/                             ← Trao đổi với khách hàng (có comtor/BrSE)
│   ├── QnA-Log.md                      # Hỏi-đáp thông thường — 1 file duy nhất cho toàn dự án
│   ├── Meetings-Log.md                 # Tổng hợp meeting minutes (taskType `ingest-data`) — tạo khi cần
│   └── Confirmations-Log.md            # Mốc khách CHỐT chính thức (taskType `ingest-data`) — tạo khi cần
│
├── 02.BA-Specs/                        ← BA quản lý
│   ├── 00.Requirements/                # Requirements Gathering
│   ├── 01.Analysis/                    # Gate 1: Business Analysis
│   ├── 02.QnA/                         # Gate 2: Q&A nội bộ với stakeholder
│   ├── 03.UI-Prototypes/               # Gate 3: UI/UX Design
│   └── 04.UC-Specs/                    # Gate 4: Final UC Specification
│
├── 03.Testing/                         ← Tester quản lý
│   ├── 00.Strategies/                  # Test strategy & approach
│   ├── 01.Testcases/                   # create-testcase: QnA Log, Test Plan, TestCase, Review Result, Dev Checklist
│   ├── 02.Reports/                     # Gate 4: Execution & regression reports
│   ├── 03.Test-Data/                   # Test data: CSV, JSON, SQL fixtures
│   ├── 04.Evidence/                    # Gate 3: Screenshots, videos, logs
│   ├── 05.Scripts/                     # Playwright automation scripts
│   ├── 06.Bugs/                        # Gate 3: Bug reports
│   └── 07.AI-Artifacts/               # Legacy — create-testcase không còn ghi vào đây
│
├── 04.Coding/                          ← Dev quản lý
│   ├── 00.Overview/                    # Tracker tổng: F-ID | Ticket | Dev | Gate | PR
│   ├── 01.Requirements/                # Gate 1: AI phân tích ticket + source code (akg: story STORY-xxx_vN.md)
│   ├── 02.Plans/                       # Gate 2: TDD implementation plan
│   ├── 03.TDD-Notes/                   # Gate 3: Test list viết trước + notes
│   ├── 04.Reviews/                     # Gate 4: Self-review + impact analysis
│   └── 05.Pull-Requests/               # Gate 5: PR content + review checklist
│
├── 05.Rules/                           ← Quy định/convention riêng của dự án (khác baseline ở Shared-Docs/05.Rules)
│
├── 06.Agent-Records/                   ← akg (Light-out Agents) ghi, người đọc để audit
│   └── <work item>/                    # vd WONDER-1142-B (BA Team), F-001-B (Dev Team)
│       ├── Function-Breakdown.md       # BA Lead tách chức năng — Human duyệt
│       ├── REV-*.md, ESC-*.md, ADR-*.md
│       ├── Readiness-Report_*.md, Test-Run-*.md
│       └── Ledger.md, Messages.md, Metrics.json
│
├── 07.Tasks/                           ← PM / Human tạo sau khi chốt việc; Development Team (akg) đọc
│   ├── _Index.md                       # Danh sách task: mã, tiêu đề, chức năng, trạng thái, file task
│   ├── _Template/Task_v1.md            # Template file task (ak init / ak update tạo, không đè file đã có)
│   └── DT-001_<Ten>/
│       └── Task_v1.md                  # Nội dung yêu cầu, bảng tài liệu đầu vào (UC Spec bắt buộc), link Backlog chỉ để tham chiếu
│
└── 99.Memory/                          ← Bộ nhớ & tri thức tích luỹ (ak memory)
```

> **Yêu cầu thô của khách** lưu trên Backlog (ticket + Backlog Document), không chép vào AK-Docs. Analysis và UC Spec ghi nguồn ở frontmatter `sources` (ticket / Document / comment kèm `updated`). `ak backlog-fetch <key>` lấy đầy đủ yêu cầu dạng JSON.

---

## Chi tiết — `Shared-Docs/`

> Repo dùng chung cho **TẤT CẢ dự án** — chỉ chứa template gốc, không chứa tài liệu của riêng dự án nào. Chỉ AI Testing Team mới có quyền chỉnh sửa.

| Thư mục | Nội dung |
|---|---|
| `Spec-Templates/` | Template UC Spec cho BA (Gate 1→4 của `create-spec` workflow) |
| `QA-Templates/` | Template chiến lược test, checklist review cho Tester |
| `Testcase-Templates/` | Template bộ Test Case (Gate 1→4 của `create-testcase` workflow) |
| `Test-Report-Templates/` | Template báo cáo thực thi test (execution report, regression report) |

Mỗi dự án khi cần tạo tài liệu mới (UC Spec, Test Case, Test Report...) sẽ copy template tương ứng từ `Shared-Docs/` về đúng thư mục trong `AK-Docs/` của dự án đó rồi điền nội dung.

---

## Quy tắc đặt tên

| Element | Convention | Ví dụ |
|---|---|---|
| Section folder | `{N}.{Pascal-Case}/` | `00.Requirements/`, `03.TDD-Notes/` |
| Feature folder | `F-{3-digit}_{Pascal-Case}/` | `F-001_User-Login/` |
| File có version | `{Pascal-Name}_v{N}.md` | `UC-Spec_v2.md` |
| File theo ticket | `TICKET-{ID}.md` | `TICKET-100.md` |
| File archive | `_archive/` subfolder | `04.UC-Specs/F-001/_archive/` |

---

## Ai lưu tài liệu ở đâu, khi nào

| Vai trò | Lưu vào | Thời điểm |
|---|---|---|
| PM / BrSE | `00.Project-Overview/` | Đầu dự án + mỗi sprint |
| BA / PM / Comtor | `01.QnA/QnA-Log.md` | Khi có câu hỏi từ khách hàng |
| PM / BrSE / Comtor | `01.QnA/Meetings-Log.md`, `Confirmations-Log.md` | Ingest link/text đã approve, qua taskType `ingest-data` (`ak use` → "📥 Ingest Data") |
| BA | `02.BA-Specs/` | Sau khi Gate 4 APPROVED |
| Tester | `03.Testing/` | Sau khi Gate 4 APPROVED |
| Dev | `04.Coding/` | Trước khi tạo Pull Request |
| akg (Light-out Agents) | `06.Agent-Records/<work item>/`; cập nhật dòng trong `00.Project-Overview/Function-List.md`, `Glossary.md` | Trong lúc team agent chạy |
| PM / Human (sau khi chốt việc) | `07.Tasks/<Task-ID>_<Ten>/Task_vN.md`, dòng trong `07.Tasks/_Index.md` | Trước khi giao task cho Development Team (`akg dev run --task <file>`) |

---

## Luồng tài liệu qua từng vai trò

```
PM tạo ticket (Backlog/Jira)
      │
      ▼
[BA] ak use TICKET-123
  → 02.BA-Specs/ (Gate 1→4)
  → Thông báo Dev + Tester sau Gate 4 APPROVED
      │
      ├──────────────────────────────────┐
      ▼                                  ▼
[Tester] Extension sidebar           [Dev] ak use TICKET-123
  → 03.Testing/ (Gate 1→4)             → 04.Coding/ (Gate 1→5)
      │                                  │
      └──────────────┬───────────────────┘
                     ▼
              Pull Request
              link: UC Spec + Test Case + Dev Plan
                     │
                     ▼
              [PM] Gate 4 Tester → Go / No-Go
```
