# 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/
│
└── 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
│   └── 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/                   # Gate 2: Test cases per feature
│   ├── 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/               # AI working docs: Gate 1-2 outputs
│
└── 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
    ├── 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
```

---

## 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 |

---

## 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
```