---
name: workflow-plan-task-test-report
description: Quy trình làm việc bắt buộc cho các tác vụ lớn (Mass Refactoring, Feature Development) sử dụng Deep Matrix (D1-D6).
---

# QUY TRÌNH PLAN - TASK - TEST - REPORT (DEEP MATRIX WORKFLOW)

Quy trình này bắt buộc phải được áp dụng khi hệ thống đối mặt với một chiến dịch tái cấu trúc lớn (Mass Refactoring), phát triển tính năng phức tạp ảnh hưởng đến nhiều Module, hoặc bất cứ tác vụ nào vượt quá 10 file mã nguồn.

Mục tiêu: Đảm bảo AI Agent không bị "ảo giác" tiến độ, không bỏ quên logic ngách (corner cases), và liên tục đồng bộ với người dùng.

## 1. PLAN (Lập kế hoạch đa tầng - Deep Matrix từ D1 đến D6)
Sự sơ sài là kẻ thù của hệ thống ERP. Không bao giờ được lao vào code ngay lập tức. Agent phải tạo một file Artifact `task.md` được cấu trúc phân rã cực sâu (Deep Matrix):
- **[D1] Module / Epic**: Nhóm tính năng lớn (VD: Module Bóc Tách Khối Lượng - Takeoff).
- **[D2] Business Flow**: Luồng nghiệp vụ cốt lõi (VD: Parse file CAD DWG).
- **[D3] Domain Logic / Rules**: Các quy tắc nghiệp vụ ngách (VD: Xử lý TCVN3/VNI, Phân tích Bounding Box).
- **[D4] State & Data Transitions**: Sự thay đổi trạng thái và dữ liệu (VD: Mapping hình học sang mã vật tư, Lưu trạng thái DRAFT).
- **[D5] Cross-module Dependencies**: Giao tiếp Event Bus (VD: Bắn event TakeoffApproved, Inventory lắng nghe để Reserve stock).
- **[D6] File-level Execution**: Xác định chính xác các file sẽ bị can thiệp, hàm nào sẽ viết mới, hàm nào bị xóa.
- **Timestamp & Checkbox**: Mỗi task từ D1 đến D6 bắt buộc phải có Checkbox `[ ]` và ô trống Timestamp `(Pending)`.

## 2. TASK (Thực thi từng phần - Incremental Execution)
- Agent tiến hành code từng cụm từ D6 ngược lên.
- Tuyệt đối không dùng "scaffolding giả" (chỉ tạo file rỗng hoặc TODO). Code phải chứa logic thực sự (Migrate toàn bộ code cũ sang code mới).
- Sau khi hoàn thành một khối logic, Agent dùng tool update lại file `task.md` để:
  1. Đánh dấu `[x]` vào checkbox.
  2. Ghi chính xác timestamp lúc hoàn thành (VD: `2026-08-31T18:30:00+07:00`).

## 3. TEST (Kiểm thử thực tế)
- Agent không được tự xưng "đã hoàn thành" nếu chưa trải qua kiểm thử.
- Tự động chạy `pytest` hoặc viết các integration test script để đảm bảo code mới (ví dụ Command Handler) thực sự ghi được vào DB (Schema Isolation) và Event Bus thực sự được kích hoạt.
- Đọc logs để xác nhận không có lỗi `ImportError` do đổi kiến trúc.

## 4. REPORT (Báo cáo & Tạm dừng)
- Sau khi xong một Làn sóng (Wave) hoặc một Module [D1], Agent phải **dừng lại** và tóm tắt tiến độ cho người dùng.
- Báo cáo phải nêu rõ:
  - Những lỗi logic cũ nào đã được xử lý?
  - Dữ liệu đang chảy qua hệ thống như thế nào? (Data Flow).
  - Yêu cầu người dùng review file Artifact `task.md` để chốt tiến độ.

---
**CẢNH BÁO QUAN TRỌNG:** Nếu người dùng phàn nàn "sao làm nhanh thế, có sót không?", Agent phải tự động rà soát lại xem mình có vi phạm bước TASK (chỉ tạo TODO rỗng) hay vi phạm bước TEST (chưa chạy thử API/Code) hay không, và lập tức phân rã logic sâu xuống D5, D6 để bù đắp sự sơ sài.