# Coding — Folder Structure

> **Managed by:** Dev  
> **Organized by:** Output Type → Function-ID → Ticket-ID  
> **Naming:** Function-ID `F-001_User-Login`, file by `TICKET-ID.md`  
> **Location:** `AK-Docs/04.Coding/` — tách khỏi source repo  
> **Note:** Templates are managed in a separate shared repo.

---

## Folder Tree

```
04.Coding/
│
├── 00.Overview/
│   └── _Index.md                           # Tracker: F-ID | Ticket | Dev | Gate | PR
│
├── 01.Requirements/                        # Gate 1: AI phân tích ticket + source code
│   └── F-001_User-Login/
│       ├── TICKET-100.md                   # Initial implementation
│       └── TICKET-145.md                   # Enhancement (remember me)
│
├── 02.Plans/                               # Gate 2: TDD implementation plan chi tiết
│   └── F-001_User-Login/
│       ├── TICKET-100.md
│       └── TICKET-145.md
│
├── 03.TDD-Notes/                           # Gate 3: Test list viết trước + implementation notes
│   └── F-001_User-Login/
│       ├── TICKET-100.md
│       └── TICKET-145.md
│
├── 04.Reviews/                             # Gate 4: Self-review + impact analysis
│   └── F-001_User-Login/
│       ├── TICKET-100.md
│       └── TICKET-145.md
│
└── 05.Pull-Requests/                       # Gate 5: PR content + review checklist
    └── F-001_User-Login/
        ├── TICKET-100.md
        └── TICKET-145.md
```

---

## File Naming Convention

| Element | Convention | Example |
|---|---|---|
| Section folder | `{N}.{Pascal-Case}/` | `01.Requirements/`, `03.TDD-Notes/` |
| Feature folder | `F-{3-digit}_{Pascal-Case}/` | `F-001_User-Login/` |
| Document file | `TICKET-{ID}.md` | `TICKET-100.md` |

---

## Gate → Folder Mapping

| Gate | Output | Folder |
|---|---|---|
| Gate 1 | Requirement analysis + source code analysis + proposed solution | `01.Requirements/F-001/TICKET-100.md` |
| Gate 2 | TDD implementation plan: step-by-step, file list, test-first | `02.Plans/F-001/TICKET-100.md` |
| Gate 3 | Test list (written before code) + notes during implementation | `03.TDD-Notes/F-001/TICKET-100.md` |
| Gate 4 | Self-review: test results, impact analysis, review checklist | `04.Reviews/F-001/TICKET-100.md` |
| Gate 5 | PR description + reviewer checklist + related doc links | `05.Pull-Requests/F-001/TICKET-100.md` |

---

## File Content Templates

### `01.Requirements` — TICKET-100.md
```markdown
## Ticket Summary
[title, description, AC từ Backlog/Jira]

## Source Code Analysis
- Files liên quan:
- Luồng hiện tại:
- Điểm cần thay đổi:

## Proposed Solution
- Hướng tiếp cận:
- Rủi ro:

## Estimate
- Effort: X giờ
- Scope ảnh hưởng: [low / medium / high]
```

### `02.Plans` — TICKET-100.md
```markdown
## TDD Implementation Plan

### Step 1: Viết test cho [case A]
- File: tests/unit/service/UserServiceTest.java
- Test method: `create_shouldThrow_whenEmailDuplicated()`

### Step 2: Implement [logic A]
- File: src/service/impl/UserServiceImpl.java
- Thay đổi: ...
```

### `03.TDD-Notes` — TICKET-100.md
```markdown
## Test List (viết trước khi implement)
- [ ] TC-01: happy path — tạo user thành công
- [ ] TC-02: email trùng → throw DuplicateEmailException
- [ ] TC-03: input null → throw ValidationException

## Implementation Notes
[ghi chú phát sinh trong quá trình code]
```

### `04.Reviews` — TICKET-100.md
```markdown
## Test Results
- Unit tests: 12/12 PASS
- Integration tests: 3/3 PASS

## Impact Analysis
- Files thay đổi: 5 files
- Chức năng ảnh hưởng: [danh sách]
- Breaking changes: Không / Có → [mô tả]

## Review Checklist
- [ ] Không có business logic trong Controller
- [ ] Dùng DTO, không expose Entity trực tiếp
- [ ] @Transactional đúng chỗ (Service, không phải Controller)
- [ ] Custom exception, không dùng RuntimeException chung
- [ ] Không log sensitive data
- [ ] Unit test + Integration test đều pass
```

### `05.Pull-Requests` — TICKET-100.md
```markdown
## PR: [TICKET-100] Tên feature

### Ticket
[link Backlog/Jira]

### Changes
- [danh sách thay đổi chính]

### Related Docs
- UC Spec: [link 02.BA-Specs/04.UC-Specs/F-001_User-Login/]
- Test Case: [link 03.Testing/01.Testcases/F-001_User-Login/]
- Dev Plan: [link 04.Coding/02.Plans/F-001_User-Login/TICKET-100.md]

### How to Test
1. ...

### Checklist for Reviewer
- [ ] Logic đúng với UC Spec
- [ ] Test coverage đủ
- [ ] Không có code smell
- [ ] Migration (nếu có) an toàn
```

---

## `_Index.md` — Tracker cho TechLead / PM

```markdown
| F-ID  | Ticket      | Feature Name | Dev     | Gate              | PR   |
|-------|------------|-------------|---------|-------------------|------|
| F-001 | TICKET-100 | User Login  | KhanhNV | ✅✅✅✅⬜ Gate 4   | -    |
| F-001 | TICKET-145 | Remember Me | AnhNH   | ✅✅✅✅✅ Done     | #42  |
| F-002 | TICKET-110 | Dashboard   | LyLT    | ✅✅⬜⬜⬜ Gate 2   | -    |
```

---

## Rules

- Không tự sửa template — template nằm trong shared repo riêng
- Không code trước Gate 2 được APPROVED
- Gate 3 bắt buộc TDD: viết test trước → implement → test PASS
- Lưu tài liệu lên GitLab **trước khi tạo Pull Request**
- PR description phải đính kèm link: UC Spec + Test Case + Dev Plan