update skill and docs
This commit is contained in:
Canhchimlac
@@ -17,6 +17,10 @@
|
||||
| `SEC` | Security Architecture & Threat Model | `02-architecture/` | sa-2 | Security, kiểm toán |
|
||||
| `INF` | Infrastructure & Deployment Design | `02-architecture/` | sa-2 | DevOps/SRE |
|
||||
| `FAIL` | Failure Mode & Resilience Design | `02-architecture/` | sa-2 | Dev, SRE, QA |
|
||||
| `DOM` | Domain Model — class diagram theo bounded context, aggregate, invariant ↔ `BR` | `02-architecture/` | sa-2 (`dom`) | Dev BE, Tech Lead |
|
||||
| `CTR` | Contract Files Index + **file thật** `contracts/{openapi,asyncapi,partners}/*.yaml` | `02-architecture/` | sa-2 (`ctr`) | Dev BE/FE, QA (contract test), đối tác |
|
||||
| `PDM` | Physical Data Model + **file thật** `schema/<kho>/V*.sql` (DDL, migration có down, seed) | `02-architecture/` | sa-2 (`pdm`) | Dev BE, DBA, DevOps |
|
||||
| `HANDOFF` | Gói bàn giao dev — mục lục đường dẫn thật + checklist đủ/thiếu + dev ký đã nhận | `03-enablement/` | sa-3 (`handoff`) | Dev BE/FE, QA, Tech Lead |
|
||||
| `AGD` | Architecture Guidelines & Reference Impl | `03-enablement/` | sa-3 | Dev |
|
||||
| `FIT` | Fitness Functions | `03-enablement/` | sa-3 | Dev, CI |
|
||||
| `DREV` | Design Review Log | `03-enablement/` | sa-3 | Tech Lead, Dev |
|
||||
@@ -44,11 +48,20 @@ sa-output/<PROJECT>/
|
||||
│ └── OQ_<PROJECT>.md
|
||||
├── 01-context/ CTX · OPT · TCO · ARISK
|
||||
├── 02-architecture/
|
||||
│ ├── ASR · QAS · SAD · ICD · DAT · SEC · INF · FAIL
|
||||
│ └── adr/
|
||||
│ ├── ADR-001_<slug>.md
|
||||
│ └── archive/
|
||||
├── 03-enablement/ AGD · FIT · DREV · TDEBT
|
||||
│ ├── ASR · QAS · SAD · ICD · DAT · SEC · INF · FAIL · DOM · CTR · PDM
|
||||
│ ├── adr/
|
||||
│ │ ├── ADR-001_<slug>.md
|
||||
│ │ └── archive/
|
||||
│ ├── contracts/
|
||||
│ │ ├── openapi/<module>.yaml ← OpenAPI 3.1 — nguồn sự thật của IF sync
|
||||
│ │ ├── asyncapi/<domain>-events.yaml ← AsyncAPI 3.0 — IF async
|
||||
│ │ └── partners/<ten>.yaml ← mirror tài liệu đối tác (ghi nguồn, ngày)
|
||||
│ ├── schema/<kho>/
|
||||
│ │ ├── V001__init_<schema>.sql · V001__init_<schema>.down.sql
|
||||
│ │ └── seed/R__reference_data.sql
|
||||
│ └── diagrams/ ← <ARTIFACT>_<slug>.<type>.json (spec Archify) + .html
|
||||
├── 03-enablement/ HANDOFF · AGD · FIT · DREV · TDEBT
|
||||
│ └── diagrams/
|
||||
└── 04-evolution/ CONF · TRM · PMR
|
||||
```
|
||||
|
||||
@@ -137,14 +150,16 @@ BRIEF/BACKLOG (BA) ──► CTX ──► OPT ──► TCO
|
||||
│
|
||||
└──► ASR ──┬──► QAS ──────────────┬──► FIT ──► CONF
|
||||
│ │
|
||||
└──► SAD ──┬──► ICD ────┤
|
||||
│ ├──► DAT ├──► AGD ──► DREV
|
||||
└──► SAD ──┬──► ICD ──► CTR ──┤
|
||||
│ ├──► DAT ──► DOM ──► PDM ──┼──► HANDOFF ──► AGD ──► DREV
|
||||
│ ├──► SEC │
|
||||
│ ├──► INF └──► TDEBT ──► TRM
|
||||
│ └──► FAIL
|
||||
└──► ADR (sinh ở mọi nhánh)
|
||||
|
||||
DTM đọc: CTX(DRV) · ASR · QAS · ADR · SAD(CMP) · FIT · CONF
|
||||
BA: API ──► ICD/CTR (file contract thắng) · BR ──► DOM (invariant) · FLD (bảng field SRS) ──► PDM (cột)
|
||||
|
||||
DTM đọc: CTX(DRV) · ASR · QAS · ADR · SAD(CMP) · ICD(IF) · CTR · DAT · PDM(TBL) · FIT · CONF
|
||||
ADL đọc: toàn bộ adr/
|
||||
```
|
||||
|
||||
@@ -160,7 +175,9 @@ Hai bộ dùng chung `OQ` và `DEC`. Những chỗ còn lại phải khớp nhau
|
||||
|---|---|---|
|
||||
| `BRIEF` · `GOAL-nn` | `CTX` · `DRV-nn` | SA đọc GOAL để suy ra driver kiến trúc |
|
||||
| `NFR` (BA đề xuất) | `QAS` (SA lượng hoá) | **`QAS` thắng.** BA ghi nhu cầu, SA chốt con số và cách đo |
|
||||
| `API` (BA đề xuất) | `ICD` (SA chốt) | **`ICD` thắng.** BA đánh dấu "chờ xác nhận", SA là người xác nhận |
|
||||
| `API` (BA đề xuất) | `ICD` (SA chốt) → `CTR` (file OpenAPI) | **File contract trong `CTR` thắng.** BA đánh dấu "chờ xác nhận", SA xác nhận qua `ICD` và sinh file; `API` ghi `operationId` |
|
||||
| `SRS` PART 2 bảng field `FLD-*` | `PDM` cột | Cùng độ dài/kiểu/null — UI và DB chặn cùng ngưỡng; lệch ⇒ `OQ`, không im lặng chọn một bên |
|
||||
| `BR-nnn` ràng buộc dữ liệu / tính toán | `DOM` invariant | `BR` là nguồn, `DOM` nói invariant sống ở class nào |
|
||||
| `RBAC` | `SEC` §authz | `SEC` map ma trận RBAC nghiệp vụ xuống cơ chế kỹ thuật |
|
||||
| `IMPACT` | `SAD` + `DAT` | BA nêu module nghiệp vụ bị ảnh hưởng, SA nêu component và dữ liệu |
|
||||
| `BR-nnn` | `ADR` khi rule ép ràng buộc kiến trúc | Ví dụ rule "không được mất giao dịch" ⇒ ADR về consistency |
|
||||
|
||||
@@ -54,19 +54,26 @@ OrderValidator" là sơ đồ không ai đọc được.
|
||||
Kèm mỗi sơ đồ: một **legend** giải thích hình khối và loại mũi tên (sync/async, ai gọi ai,
|
||||
giao thức). Mũi tên không nhãn không mang thông tin.
|
||||
|
||||
**Vẽ bằng mermaid, không ASCII art** — thống nhất với quy tắc `W13` của bộ BA
|
||||
(`../../ba-lifecycle/references/diagram-rules.md`). GitHub/Confluence và Artifact của Claude
|
||||
Code render thẳng, và `git diff` đọc được từng cạnh.
|
||||
**Vẽ theo chuẩn Archify** — thống nhất với quy tắc `W13` của bộ BA; toàn bộ chuẩn ở
|
||||
`../../ba-lifecycle/references/diagram-rules.md`. Mỗi sơ đồ gồm **spec JSON Archify** (nguồn sự
|
||||
thật về topology, `quality_profile: showcase`, validate 0 lỗi) + **mermaid** trong `.md` có marker
|
||||
`<!-- archify: <type> · <spec.json> -->` (bản chiếu, khớp spec hai chiều, không màu) + **bảng đi kèm**.
|
||||
Một đường chính (`variant: emphasis`), ≤ 12 node chính, nhãn cạnh ghi giao thức và sync/async.
|
||||
|
||||
| Sơ đồ | Loại mermaid | Sinh ở |
|
||||
|---|---|---|
|
||||
| C4 Context / Container / Component | `flowchart` + `subgraph` | `SAD` §3–§5 |
|
||||
| Deployment view | `flowchart TB` + `subgraph` theo vùng/AZ | `SAD` §7, `INF` §3 |
|
||||
| Luồng chính, có nhánh lỗi | `sequenceDiagram` | `SAD` §6 |
|
||||
| Ranh giới tin cậy | `flowchart LR` | `SEC` §1 |
|
||||
| Mô hình dữ liệu khái niệm | `erDiagram` | `DAT` §2 |
|
||||
| Phụ thuộc giữa mục roadmap | `flowchart LR` | `TRM` §4 |
|
||||
| Phương án ở mức khối | `flowchart LR` | `OPT` §3 |
|
||||
| Sơ đồ | Loại Archify | Mermaid | Sinh ở |
|
||||
|---|---|---|---|
|
||||
| C4 Context / Container / Component | `architecture` | `flowchart` + `subgraph` | `SAD` §3–§5 |
|
||||
| Deployment view | `architecture` | `flowchart TB` + `subgraph` theo vùng/AZ | `SAD` §7, `INF` §3 |
|
||||
| Luồng chính, có nhánh lỗi | `sequence` | `sequenceDiagram` | `SAD` §6 |
|
||||
| Ranh giới tin cậy | `architecture` | `flowchart LR` | `SEC` §1 |
|
||||
| Ownership / luồng dữ liệu | `dataflow` | `flowchart LR` | `DAT` §1 |
|
||||
| Mô hình dữ liệu khái niệm | *(mermaid-only)* | `erDiagram` | `DAT` §2 |
|
||||
| Class diagram theo bounded context | *(mermaid-only)* | `classDiagram` | `DOM` §2 |
|
||||
| Phụ thuộc giữa mục roadmap | `workflow` | `flowchart LR` | `TRM` §4 |
|
||||
| Phương án ở mức khối | `architecture` | `flowchart LR` | `OPT` §3 |
|
||||
|
||||
Spec đặt ở `<thư mục artifact>/diagrams/`, HTML đã `deliver` nằm cạnh. Người điều phối chạy
|
||||
`node .claude/skills/ba-lifecycle/scripts/diagram-check.mjs --md <artifact>` sau mỗi activity có sơ đồ.
|
||||
|
||||
🔴 **Mỗi sơ đồ phải có bảng đi kèm** (`W13`). Sơ đồ để nhìn; bảng để truy vết, để đặt con số,
|
||||
và để kiểm chứng. Sơ đồ không diễn đạt được timeout, quyền, mã lỗi, hay ai sở hữu cái gì.
|
||||
@@ -169,7 +176,7 @@ Ghi câu này trong mọi tài liệu có sơ đồ:
|
||||
[ ] D1 Mỗi ADR chỉ chứa một quyết định
|
||||
[ ] D2 grep NFR định tính trả về rỗng; mọi QAS đủ 4 câu (kịch bản/số/cách đo/ai đo)
|
||||
[ ] D3 Mọi quyết định nêu ≥1 phương án đã loại + lý do gắn với CON hoặc QAS
|
||||
[ ] D4 Mỗi sơ đồ khai báo mức C4 + có legend, không trộn mức
|
||||
[ ] D4 Mỗi sơ đồ khai báo mức C4 + legend, không trộn mức; có spec Archify validate pass, marker, diagram-check xanh
|
||||
[ ] D5 Mọi interface có chủ, contract, versioning policy
|
||||
[ ] D6 Mọi phụ thuộc ngoài process có timeout/retry/fallback + trả lời 4 câu hỏi
|
||||
[ ] D7 Mỗi thực thể dữ liệu có đúng một single source of truth
|
||||
|
||||
@@ -63,15 +63,21 @@ Gate kiến trúc khác gate BA ở một điểm: **không ký được bằng
|
||||
- [ ] `SEC` — có threat model STRIDE cho luồng nhạy cảm; mô hình authn/authz đã chốt; Security ký
|
||||
- [ ] `INF` — topology môi trường, HA/DR có **RTO/RPO bằng số**, chiến lược scale, observability
|
||||
- [ ] `FAIL` — mỗi phụ thuộc ra ngoài process có failure mode, timeout, retry, fallback
|
||||
- [ ] `sa-conformance` báo coverage `ASR → ADR/CMP` ≥ 100%
|
||||
- [ ] `DOM` — class diagram cho mỗi bounded context có ghi/đọc dữ liệu: aggregate, entity, value object, invariant truy về `BR-nnn`; mọi entity có trong `DAT` §1
|
||||
- [ ] `PDM` — **schema vật lý đủ cột** cho mọi thực thể `DAT`: kiểu, null, default, constraint, PK/FK/index, cờ PII; **DDL + migration** trong `02-architecture/schema/` chạy được từ rỗng và có rollback; công cụ migration chốt bằng `ADR`
|
||||
- [ ] `CTR` — mọi `IF-nnn` sync có file OpenAPI 3.1 và mọi `IF-nnn` async có file AsyncAPI trong `02-architecture/contracts/`, lint pass; cột "Contract ở đâu" của `ICD` trỏ tới file **thật**, không "dự kiến"; mỗi mã lỗi `E-…` của BA có trong response schema
|
||||
- [ ] Mọi sơ đồ (`SAD`, `INF`, `SEC`, `DAT`) có spec Archify validate pass; `diagram-check.mjs` không 🔴
|
||||
- [ ] `sa-conformance` báo coverage `ASR → ADR/CMP` ≥ 100%, `IF → CTR` = 100%, `DAT thực thể → PDM bảng` = 100%
|
||||
|
||||
**Chặn:** còn `QAS` nào ghi "nhanh", "ổn định", "bảo mật" mà không có con số.
|
||||
**Chặn:** còn interface nào không biết ai sở hữu.
|
||||
**Chặn:** còn interface nào không biết ai sở hữu, hoặc còn "contract dự kiến" chưa có file.
|
||||
**Chặn:** còn thực thể trong `DAT` không có bảng trong `PDM`, hoặc migration không có rollback.
|
||||
**Đây là gate nghiêm nhất** — một quyết định sai lọt qua AG2 sẽ thành một cuộc viết lại.
|
||||
|
||||
### AG3 — Build conformance · duyệt bởi **Tech Lead + QA + SRE**
|
||||
|
||||
- [ ] `AGD` đã ban hành và có **reference implementation chạy được**, không chỉ văn bản
|
||||
- [ ] `HANDOFF` ban hành trong tuần đầu thi công: mọi dòng checklist §2 ✅ bằng đường dẫn thật (SRS/AC theo US, `PDM`, `CTR`, `ADR`, `AGD`, `FAIL`), không còn "dự kiến"; Tech Lead + đại diện dev BE/FE/QA ký đã nhận
|
||||
- [ ] `AGD` đã ban hành và có **reference implementation chạy được**, không chỉ văn bản; reference implementation chạy migration của `PDM` và tuân contract trong `CTR`
|
||||
- [ ] `FIT` — mỗi ràng buộc kiến trúc quan trọng có một kiểm thử tự động, **đang xanh trên CI**
|
||||
- [ ] `DREV` ghi mọi lần review kiến trúc, mỗi phát hiện có trạng thái đóng/mở
|
||||
- [ ] Mọi `QAS` mức Must đã có **bài đo thực tế** chứng minh đạt (không phải ước lượng)
|
||||
|
||||
Reference in New Issue
Block a user