# Review Record — ghi lại review của Human và cách AI xử lý

> Áp dụng cho: `[DEV] 5-Gate Development Workflow` (skill `review-plan` ở Gate 4, Gate 5 peer review).
> File: mục `## Review Record` ở cuối `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md`.

PM, TechLead và Dev đọc mục này để biết: ai đã comment gì, vì sao lỗi xảy ra, đã sửa thế nào, kiểm chứng ra sao, và còn gì chưa đóng. Người đọc không cần mở code hay đọc lại hội thoại.

Trước đây mục này là 2 bảng rời nhau, một bảng finding và một bảng lịch sử, không có mã để nối với nhau. Một ô thường gộp nhiều quyết định, ví dụ "Sửa finding FR-13; giữ nguyên 4 finding còn lại". Trạng thái cũng viết lẫn lộn ("Đã sửa", "Chưa sửa", "Follow-up", "APPROVED"). Rule này thay thế cách ghi đó.

## 1. Cấu trúc mục Review Record

Mục gồm 3 phần, theo đúng thứ tự dưới đây.

### Phần 1 — Bảng tổng hợp comment

Mỗi comment một dòng, để đọc nhanh trong 30 giây.

```markdown
### Tổng hợp comment

| ID | Gate | Nguồn | Mức độ | Tóm tắt | Trạng thái | Liên kết |
|---|---|---|---|---|---|---|
| RC-01 | G5 | AI code review | Major | Buổi ngày kết thúc không về "Cả ngày" khi đơn đổi lại thành nhiều ngày | ✅ Closed | BUG-002 |
| RC-02 | G5 | AI code review | Minor | Nhiều process cùng ghi SQLite có thể trả lỗi 500 | ⏸️ Deferred | AK-130 |
```

- `Tóm tắt`: 1 câu, tối đa khoảng 15 từ, nêu hành vi sai, không nêu cách sửa.
- Không có comment nào → ghi một dòng: `Chưa có comment.`

### Phần 2 — Chi tiết từng comment

Mỗi comment một khối, tiêu đề là `RC-xx — <tóm tắt>`, bên dưới là bảng 2 cột với đủ 10 dòng sau.

```markdown
### RC-01 — Buổi ngày kết thúc không về "Cả ngày" khi đơn đổi lại thành nhiều ngày

| Mục | Nội dung |
|---|---|
| **Trạng thái** | ✅ Closed — KhanhNV xác nhận 2026-10-27 |
| **Mức độ / Loại** | Major / Bug code |
| **Nguồn** | AI code review (subagent), Gate 5 |
| **Vị trí** | `app/(app)/leave/new/useLeaveForm.ts` · FR-13 |
| **Vấn đề** | Đơn 2 ngày chọn Buổi sáng ở ngày cuối → đổi thành 1 ngày → đổi lại 2 ngày: ngày cuối vẫn là Buổi sáng, Số ngày = 1,5 thay vì 2 |
| **Nguyên nhân** | Form giữ giá trị buổi cũ khi group "Buổi ngày kết thúc" hiện lại; FR-13 yêu cầu mặc định Cả ngày |
| **Quyết định** | Sửa — KhanhNV (Dev), 2026-10-27 |
| **Cách sửa** | Tách quy tắc chọn buổi ra hàm `nextFormValues`; group hiện lại thì đặt về Cả ngày |
| **Kiểm chứng** | Test TC-55 – TC-57 (RED → GREEN); `npm test` 68/68 |
| **Liên kết** | BUG-002 · commit `59657f7` |
```

| Dòng | Viết gì |
|---|---|
| **Trạng thái** | Giá trị ở mục 2, kèm người xác nhận và ngày khi `Closed` |
| **Mức độ / Loại** | Giá trị ở mục 2 |
| **Nguồn** | Ai đưa ra comment, ở gate nào |
| **Vị trí** | File (và dòng nếu có) hoặc màn hình; mã requirement liên quan (FR / BR / VR / AT) |
| **Vấn đề** | Hành vi sai mà người dùng thấy, viết sao cho người không đọc code hiểu được. Có bước tái hiện thì ghi bước |
| **Nguyên nhân** | Vì sao sai, ở mức logic. Chưa rõ → `Chưa xác định` |
| **Quyết định** | `Sửa` / `Hoãn` / `Không sửa` — người quyết định, ngày. `Hoãn` và `Không sửa` bắt buộc ghi lý do |
| **Cách sửa** | Thay đổi đã làm. Chưa sửa → `—`, có thể kèm đề xuất |
| **Kiểm chứng** | Test đã chạy, kết quả, evidence. Chưa sửa → `—` |
| **Liên kết** | Bug (`BUG-xxx`), ticket follow-up, commit, TC |

### Phần 3 — Lịch sử duyệt gate

Mỗi lần Human trả lời ở một gate thì thêm một dòng. Gate được duyệt mà không có comment chỉ ghi ở phần này, không tạo `RC-xx`.

```markdown
### Lịch sử duyệt gate

| Gate | Ngày giờ | Người duyệt | Kết quả | Comment mở / đóng |
|---|---|---|---|---|
| G1 Requirement | 2026-10-27 16:33 | KhanhNV (Dev) | ✅ APPROVED | 0 / 0 |
| G4 Self-review | 2026-10-27 17:03 | KhanhNV (Dev) | 🐛 BUG | 1 / 0 (RC-01) |
| G4 Self-review | 2026-10-27 17:40 | KhanhNV (Dev) | ✅ APPROVED | 0 / 1 |
```

- `Ngày giờ` lấy từ `.aiflow/tasks/[ticketId]/task-state.json` (`gateApprovals`), đổi sang giờ địa phương của dự án. Không có giờ thì chỉ ghi ngày.
- `Kết quả`: `✅ APPROVED` · `🐛 BUG` · `✅ Done` (Gate 5 xong).
- `Comment mở / đóng`: số comment còn mở / đã đóng tính đến dòng đó, kèm ID nếu có.
- Task có nhiều phần (ví dụ 2 subtask được gộp) → thêm hậu tố: `G4-A`, `G4-B`.

## 2. Giá trị cố định

| Trường | Giá trị |
|---|---|
| **Trạng thái** | `🔴 Open` · `🟡 Fixed` (đã sửa, chờ Human xác nhận) · `✅ Closed` · `⏸️ Deferred` (bắt buộc có ticket hoặc follow-up) · `⚪ Won't fix` (bắt buộc có lý do) · `⚪ Not an issue` |
| **Mức độ** | `Critical` · `Major` · `Minor` · `Suggestion`. Từ `requesting-code-review`: Critical → Critical, Important → Major, Minor → Minor |
| **Loại** | `Bug code` · `Bug requirement` · `Thiếu test` · `Tài liệu` · `Cải tiến` |
| **Nguồn** | `Human — <tên> (<vai trò>)` · `AI code review` · `QA` · `PM` |

Không dùng giá trị khác (`Đã sửa`, `Chưa sửa`, `Follow-up`, `OK`...).

## 3. Quy tắc

1. Một comment một ID `RC-xx`. Đánh số liên tục trong cả task, không dùng lại số cũ. Một tin nhắn `BUG:` nêu nhiều lỗi → tách thành nhiều ID.
2. Viết `Vấn đề` theo hành vi người dùng thấy trước, chi tiết kỹ thuật để ở `Nguyên nhân`.
3. AI sửa xong chỉ được đặt `🟡 Fixed`. Chỉ chuyển `✅ Closed` khi Human trả lời APPROVED ở lần review kế tiếp, hoặc xác nhận rõ comment đó.
4. `⏸️ Deferred` và `⚪ Won't fix` bắt buộc có `Quyết định` ghi người quyết định và lý do. AI không tự quyết hoãn hay bỏ qua comment của Human.
5. Comment lặp lại một ID còn mở → cập nhật khối của ID đó, không tạo khối mới.
6. Lỗi AI tự phát hiện và sửa ở bước self-review, trước khi trình Human, không ghi thành `RC-xx`.
7. Không xoá khối đã đóng. Review Record là lịch sử.
8. Viết cùng ngôn ngữ với phần còn lại của file (theo `custom/rules/output-language.md`). Output tiếng Anh thì dùng tiêu đề tương ứng: `Summary of comments` (`ID | Gate | Source | Severity | Summary | Status | Links`), các dòng chi tiết `Status`, `Severity / Type`, `Source`, `Location`, `Issue`, `Root cause`, `Decision`, `Fix`, `Verification`, `Links`, và `Gate approval history` (`Gate | Date/time | Reviewer | Result | Comments open / closed`). Giá trị ở mục 2 giữ nguyên.
