127 lines
5.1 KiB
Markdown
127 lines
5.1 KiB
Markdown
# FIT — Fitness Functions — <PROJECT>
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Version** | 1.0 |
|
||
| **Date** | YYYY-MM-DD |
|
||
| **Author** | <SA> (skill sa-3-enablement) |
|
||
| **Status** | 🟡 Draft |
|
||
| **Approved by** | Tech Lead: — · QA: — |
|
||
| **Source** | AGD_… v1.0 · QAS_… v1.0 · ADR-… |
|
||
| **Scope** | |
|
||
| **Confidence** | 🟢 |
|
||
|
||
## Change Log
|
||
|
||
| Version | Date | Người sửa | Thay đổi |
|
||
|---|---|---|---|
|
||
| 1.0 | | | Bản đầu |
|
||
|
||
> **Quy tắc `D8`:** ràng buộc không kiểm tự động được thì chỉ là khuyến nghị. Tài liệu này là
|
||
> chỗ biến ràng buộc thành thứ CI cưỡng chế được.
|
||
|
||
---
|
||
|
||
## 1. Bảng trạng thái
|
||
|
||
| ID | Ràng buộc | Nguồn | Công cụ | Bước CI | Chế độ | Trạng thái | Vi phạm | `TD` |
|
||
|---|---|---|---|---|---|---|---|---|
|
||
| `FIT-01` | Tầng domain không import infra | `ADR-002` | ArchUnit | `test` | 🚫 chặn | 🟢 | 0 | |
|
||
| `FIT-02` | Không có secret trong mã nguồn | `SEC` §6 | gitleaks | `pre-build` | 🚫 chặn | 🟢 | 0 | |
|
||
| `FIT-03` | `QAS-004` batch ≤ 45 phút | `QAS-004` | k6 | `perf` (nightly) | ⚠️ cảnh báo | 🔴 | 52 phút | `TD-05` |
|
||
|
||
**Chế độ:** ⚠️ cảnh báo · 🚫 chặn merge · ⏸ chưa bật
|
||
**Trạng thái:** 🟢 xanh · 🔴 đỏ · ⚪ chưa chạy lần nào
|
||
|
||
## 2. Lộ trình bật
|
||
|
||
*Đừng cố phủ hết ngay. Thứ tự đem lại giá trị nhanh nhất, và mọi bài kiểm bắt đầu ở chế độ
|
||
cảnh báo.*
|
||
|
||
| Tuần | Bật gì | Vì sao thứ tự này |
|
||
|---|---|---|
|
||
| 1 | Phụ thuộc giữa tầng/module · quét secret | Rẻ nhất, chặn được nhiều lỗi nhất |
|
||
| 2 | Quét lỗ hổng thư viện · lint contract | Công cụ có sẵn, cấu hình nhanh |
|
||
| 3 | Kiểm thử hiệu năng `QAS` mức Must | Tốn công dựng nhất |
|
||
| 4 | Kiểm tra IaC / policy hạ tầng | Cần quyền trên pipeline hạ tầng |
|
||
|
||
**Lịch chuyển cảnh báo → chặn**
|
||
|
||
| `FIT` | Bật cảnh báo | Vi phạm lúc bật | Ngày chuyển sang chặn | Ai dọn nợ | Trạng thái |
|
||
|---|---|---|---|---|---|
|
||
| `FIT-01` | 2026-09-01 | 12 | 2026-09-20 | anh Nam | |
|
||
|
||
🔴 **Bật chế độ chặn ngay trên codebase đã có nợ sẽ làm CI đỏ toàn bộ và team sẽ tắt nó.**
|
||
Quy tắc chuyển tiếp: bật cảnh báo → ghi số vi phạm làm mốc → quy tắc "không tăng thêm" →
|
||
giảm dần về 0 → chuyển sang chặn.
|
||
|
||
## 3. Chi tiết từng fitness function
|
||
|
||
### `FIT-01` — <tên>
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Ràng buộc kiểm** | *(phát biểu chính xác, kiểm chứng được)* |
|
||
| **Nguồn** | `ADR-002` / `QAS-nnn` / `SEC` §… |
|
||
| **Công cụ** | |
|
||
| **File bài kiểm** | `<đường dẫn trong repo>` |
|
||
| **Chạy ở đâu** | bước `<tên>` trong `<file CI>` · mỗi PR / nightly / trước release |
|
||
| **Thời gian chạy** | … s |
|
||
| **Chế độ** | ⚠️ cảnh báo → 🚫 chặn từ … |
|
||
| **Đỏ thì ai sửa** | |
|
||
| **Ngoại lệ được phép** | *(danh sách whitelist + lý do + hạn — whitelist không có hạn là whitelist vĩnh viễn)* |
|
||
|
||
**Cấu hình mẫu**
|
||
|
||
```
|
||
<đoạn cấu hình/code thật, để người khác nhân bản được>
|
||
```
|
||
|
||
### `FIT-02` — <tên>
|
||
|
||
*(cùng cấu trúc)*
|
||
|
||
## 4. Bảng phủ — ràng buộc nào chưa có bài kiểm
|
||
|
||
*Mọi ràng buộc trong `AGD` §3 và mọi `QAS` mức Must phải xuất hiện ở đây.*
|
||
|
||
| Ràng buộc / `QAS` | Có `FIT` | Nếu không: nhãn `⚠️ Khuyến nghị` | Cách kiểm thủ công | Tần suất |
|
||
|---|---|---|---|---|
|
||
| `AGD` §3.1-1 | `FIT-01` | — | — | — |
|
||
| `AGD` §3.4-2 | ❌ | ⚠️ Khuyến nghị | review PR có checklist | mỗi PR chạm authz |
|
||
| `QAS-007` | ❌ | ⚠️ Khuyến nghị | diễn tập thủ công | mỗi quý |
|
||
|
||
🔴 Dòng không có `FIT` **và** không có nhãn `⚠️ Khuyến nghị` ⇒ chặn AG3. Trong sáu tháng nó sẽ
|
||
bị vi phạm và không ai biết.
|
||
|
||
## 5. `QAS` mức Must × bài đo thật
|
||
|
||
*AG3 yêu cầu **đã đo**, không chấp nhận ước lượng.*
|
||
|
||
| `QAS` | Mục tiêu | Bài đo | Môi trường | Lần đo gần nhất | Kết quả | Đạt |
|
||
|---|---|---|---|---|---|---|
|
||
| `QAS-001` | p95 ≤ 300ms | `perf/api.js` | stg | | | ☐ |
|
||
| `QAS-004` | ≤ 45 phút | `perf/batch.js` | stg | | 52 phút | ❌ |
|
||
|
||
**Sai lệch môi trường** — stg khác prod ở đâu, và sai số ước tính bao nhiêu:
|
||
|
||
| Khác biệt | Ảnh hưởng tới `QAS` nào | Sai số ước tính | Cách bù |
|
||
|---|---|---|---|
|
||
|
||
## 6. Bảo trì bộ fitness function
|
||
|
||
| Việc | Tần suất | Ai |
|
||
|---|---|---|
|
||
| Rà whitelist quá hạn | hàng tháng | |
|
||
| Rà bài kiểm chạy quá lâu (làm chậm CI) | hàng tháng | |
|
||
| Rà `FIT` không còn đúng vì `ADR` đã superseded | sau mỗi `ADR` mới | |
|
||
| Rà bài kiểm luôn xanh vì nó không kiểm gì cả | mỗi quý | |
|
||
|
||
🔴 **Bài kiểm luôn xanh từ ngày đầu là bài kiểm đáng nghi.** Thử phá nó một lần để chắc chắn
|
||
nó đỏ được — bài kiểm không bao giờ đỏ là bài kiểm không kiểm gì.
|
||
|
||
## 7. Open Questions
|
||
|
||
| ID | Câu hỏi | Hỏi ai | Từ ngày | Chặn gì |
|
||
|---|---|---|---|---|
|