| name | doc-fe-implement |
| description | FE screen design doc workflow for Blog Du Lịch. Use when writing, updating, or standardizing a frontend screen specification document. Ensures consistent 10-section format with YAML frontmatter, navigation, layout tree, API links, state snippets, error handling, responsive table, and events mapping. Trigger phrases: write screen doc, update screen spec, standardize doc, create design doc, doc fe, screen design, spec màn hình. |
| argument-hint | ScreenCode cần viết/update (e.g. ADMIN_LOGIN, HOME, ADMIN_CATEGORY_LIST) |
Doc FE Implement Skill
Mục tiêu
Viết mới hoặc cập nhật một FE screen design doc đúng format chuẩn, đảm bảo đồng bộ với API spec và code thực tế.
Khi nào dùng
- Tạo doc cho màn hình mới
- Cập nhật doc cũ thiếu section hoặc sai format
- Chuẩn hoá loạt doc trước khi merge
Procedure
Bước 1 — Xác định màn hình, Component và Utils
- Xem danh sách tại
demo_docs/fe/[Design][LIST] SCREEN_DanhSachManHinh.md
- Đọc thư viện UI tại
demo_docs/fe/[Design][LIST] COMPONENT_DanhSach.md để biết các component đã có sẵn (bắt buộc dùng lại nếu phù hợp).
- Đọc thư viện Utils tại
demo_docs/fe/[Design][LIST] UTILS_DanhSach.md để biết các hàm logic dùng chung (format, parse lỗi...).
- Đọc
demo_docs/[Design][COMMON] MESSAGE_Catalog.md trước khi định nghĩa lỗi, success, confirm hoặc info message.
- QUAN TRỌNG: Nếu message đã có trong Message Catalog thì dùng lại đúng Message ID; nếu chưa có thì thêm mới vào Message Catalog trước khi reference trong Screen doc.
- QUAN TRỌNG: Nếu màn hình yêu cầu tạo một component mới hoặc hàm logic mới có khả năng tái sử dụng, bạn BẮT BUỘC phải cập nhật thêm vào file
COMPONENT_DanhSach.md hoặc UTILS_DanhSach.md tương ứng.
- File đích:
demo_docs/fe/[Design][SCREEN] {ScreenCode}_{ScreenName}.md
- Nếu màn hình gọi API, đọc trước các file API liên quan tại
demo_docs/api/
Bước 2 — Áp dụng 12-section template
Xem template đầy đủ tại screen-template.md.
Bắt buộc có đủ 12 sections (+ Change Log):
- Change Log — bảng Ver/Nội dung/Ngày/Người tạo, ngay sau frontmatter
- Tổng quan — mô tả ngắn mục đích màn hình
- Thông tin chung — bảng Route / Auth / Redirect / Params
- Navigation — bảng "Vào từ đâu" và "Đi đến đâu"
- Layout & Components — JSX tree minh hoạ cấu trúc (phải sử dụng các component từ
COMPONENT_DanhSach.md)
- Ma trận trạng thái UI — bảng enable/disable/ẩn của button theo từng trạng thái (init, loading, chọn 1 dòng, chọn nhiều, no-permission)
- Chi tiết UI từng section — bảng 9 cột: Control / Loại / I/O / Ràng buộc / Giá trị khởi tạo / Nguồn dữ liệu / Event ID / JSON Field / Ghi chú
- API Calls — bảng endpoint + Event ID + link API doc + sub-section Request Mapping + Response Mapping
- State Management — snippet
useState / useEffect hoặc ghi "Không có"
- Xử lý lỗi & Edge Cases — bảng có cột HTTP Status + Component hiển thị, phân biệt interceptor vs màn hình tự xử lý
- Responsive — bảng breakpoint mobile/tablet/desktop
- Events & Actions — bảng tóm tắt (Event ID / Tên / Control / Trigger / API / Mô tả) + chi tiết từng event quan trọng kèm Sequence Diagram Mermaid
- Message List — bảng MessageId / Loại (E/C/S/I) / Nội dung / Component hiển thị / Điều kiện
Bước 3 — Kiểm tra liên kết API
- Mỗi API Call phải có link
[Design][API] API{ID}_...md
- Đối chiếu field trong bảng với API spec thực tế (đặc biệt request body, response shape)
Bước 4 — Validate format
Xem rules đầy đủ tại format-rules.md.
Checklist nhanh:
Output
### Files changed
- demo_docs/fe/[Design][SCREEN] {ScreenCode}_{ScreenName}.md
### Sections added/updated
- [x] YAML frontmatter
- [x] Change Log
- [x] 1. Tổng quan
- [x] 2. Thông tin chung
- [x] 3. Navigation
- [x] 4. Layout & Components
- [x] 5. Ma trận trạng thái UI
- [x] 6. Chi tiết UI từng section
- [x] 7. API Calls (+ Request/Response Mapping)
- [x] 8. State Management
- [x] 9. Xử lý lỗi & Edge Cases
- [x] 10. Responsive
- [x] 11. Events & Actions (+ Sequence Diagrams)
- [x] 12. Message List
### API links verified
- API01 → ✓
📝 Ghi Log Bắt Buộc
Sau khi hoàn thành skill này, PHẢI ghi log vào reports/AGENT_EXECUTION_LOG.md trước khi báo cáo kết quả.
Dùng template sau (copy và điền vào):
### [YYYY-MM-DD HH:mm:ss] - {be-agent | fe-agent | test-agent | playwright-agent | docs-agent}
- **Task**: {Mô tả ngắn gọn việc vừa làm}
- **Skill Used**: {tên skill này}
- **Target Feature**: {key trong PROJECT_MANIFEST.yml, ví dụ: auth_login}
- **Files Processed**:
- `path/to/file` [Modified]
- `path/to/file` [Verified/Unchanged]
- **Status**: SUCCESS | FAILED | PARTIAL
- **Notes**: {Ghi chú: findings, residual risks, việc chưa làm}
⚠️ Nếu bị interrupt, ghi Status: PARTIAL và ghi rõ đã làm đến bước nào.
⚠️ Sau khi ghi log, cập nhật cycle_checkpoint trong PROJECT_MANIFEST.yml.
