Appearance
PIDEAL — TÀI LIỆU DỰ ÁN
Đọc file này trước khi viết bất kỳ tài liệu nào. Mất 5 phút.
1. Bản đồ khu vực — ai own khu nào
| Thư mục | Nội dung | Người sở hữu | Người review |
|---|---|---|---|
00-standards/ | Chuẩn chung PIGROUP (NFR baseline, templates) | Tech Lead | — |
01-proposals/ | Hồ sơ khởi tạo dự án — ĐÓNG BĂNG, chỉ tham chiếu | — | — |
02-product/ | BRD, PRD, User Story, Business Rule, Decision | PO / BA | Tech Lead (khả thi) |
03-architecture/ | Kiến trúc, NFR profile, ADR kỹ thuật | Tech Lead | Dev team |
04-qa/ | Test plan, test case (theo FEAT/US) | QA | PO + Dev |
2. Quy trình viết requirement (PO/BA)
- Copy template từ 00-standards/templates/ — không viết từ giấy trắng.
- Lấy ID mới: mở
_index.mdcủa loại tài liệu, lấy số tiếp theo, cập nhật dòng "Next ID" ngay. - Viết nội dung, để
status: drafttrong frontmatter. - Tạo Pull Request (xem mục 5) — chuyển
status: in-review. - Review 2 chiều: Dev review tính khả thi kỹ thuật · PO chốt nội dung nghiệp vụ.
- Merge → đổi
status: approved. Khi dev làm xong và nghiệm thu →implemented.
File không bao giờ di chuyển hay đổi tên sau khi có ID — trạng thái nằm trong frontmatter, tổng quan nằm ở _index.md.
3. Quy ước ID
| Loại | Prefix | Ví dụ | Cấp số ở đâu |
|---|---|---|---|
| Feature | FEAT- | FEAT-003 | 02-product/features/_index.md |
| User Story | US- | US-047 | 02-product/features/_index.md |
| Business Rule | BR- | BR-012 | 02-product/rules/global-business-rules.md |
| Product Decision | DEC- | DEC-001 | 02-product/decisions/_index.md |
| ADR kỹ thuật | ADR- | ADR-002 | 03-architecture/adr/ |
| Test Case | TC- | TC-101 (map US) | 04-qa/ (giai đoạn sau) |
- Số tăng dần toàn dự án, không reset theo feature —
US-047là duy nhất, grep một phát ra mọi nơi nhắc nó. - Commit/PR liên quan tới story ghi ID vào message:
US-047: thêm màn hình đặt cọc.
4. Frontmatter chuẩn
yaml
---
id: US-001
feature: FEAT-001
status: draft # draft → in-review → approved → implemented
owner: <tên PO/BA>
rules: [BR-001, BR-003]
updated: 2026-08-13
---5. PO/BA làm việc qua GitHub — không cần cài gì
- Mở file trên github.com → bấm nút ✏️ (Edit) → sửa/viết.
- Kéo xuống chọn "Create a new branch and start a pull request" → Commit.
- Điền mô tả PR, gắn reviewer. Xong — GitHub lo phần còn lại.
Tạo file mới: vào thư mục → Add file → Create new file → dán template vào.
6. Dùng công cụ nào cho việc gì
| Việc | Công cụ |
|---|---|
| PRD, Story, Rule, Decision (nội dung bền) | File markdown trong repo (khu 02-product/) |
| Câu hỏi mở, thảo luận, cần ai đó trả lời | GitHub Issues — label question, feature:FEAT-xxx |
| Bug khi đã có code | GitHub Issues — label bug |
| Quyết định kỹ thuật (stack, pattern) | ADR trong 03-architecture/adr/ |
| Quyết định sản phẩm/nghiệp vụ | DEC trong 02-product/decisions/ |
7. Nguyên tắc viết nhanh
- Mỗi Acceptance Criteria phải test được — viết dạng Given/When/Then.
- Không lẫn giải pháp kỹ thuật vào requirement ("thông báo trong 1 phút" ✅ / "gửi qua BullMQ" ❌).
- Viết cả nhánh lỗi và edge case, không chỉ happy path.
- Thuật ngữ dùng theo 02-product/01-glossary.md — thêm từ mới vào đó trước khi dùng.
- Điều gì chưa chốt → mở Issue hỏi, đừng tự giả định rồi viết như thật.