update skill and docs
This commit is contained in:
Canhchimlac
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: sa-2-architecture
|
||||
description: Giai đoạn 2 của quy trình Solution Architect — định nghĩa kiến trúc tới mức dev thi công được. Dùng để lượng hoá NFR thành quality attribute scenario có con số và cách đo, xác định yêu cầu định hình kiến trúc (ASR), phân rã hệ thống thành component/service với sơ đồ C4, viết Architecture Decision Record, chốt contract cho mọi interface, thiết kế kiến trúc dữ liệu và ownership, dựng threat model STRIDE và mô hình phân quyền, thiết kế hạ tầng với HA/DR RTO/RPO, và thiết kế đường lỗi (timeout, retry, circuit breaker, degradation). Kích hoạt khi người dùng nói "thiết kế kiến trúc", "vẽ sơ đồ hệ thống", "C4", "viết ADR", "chốt NFR", "quality attribute", "thiết kế API contract", "mô hình dữ liệu", "threat model", "phân quyền kỹ thuật", "HA DR", "RTO RPO", "timeout retry", "circuit breaker", "chia service thế nào". Input là OPT đã qua AG1; output vào sa-output/<PROJECT>/02-architecture/ và phải qua Gate AG2 (Ready for Build) trước khi dev bắt đầu.
|
||||
description: Giai đoạn 2 của quy trình Solution Architect — định nghĩa kiến trúc tới mức dev thi công được. Dùng để lượng hoá NFR thành quality attribute scenario có con số và cách đo, xác định yêu cầu định hình kiến trúc (ASR), phân rã hệ thống thành component/service với sơ đồ C4, viết Architecture Decision Record, chốt contract cho mọi interface, thiết kế kiến trúc dữ liệu và ownership, dựng threat model STRIDE và mô hình phân quyền, thiết kế hạ tầng với HA/DR RTO/RPO, thiết kế đường lỗi (timeout, retry, circuit breaker, degradation), và lớp bàn giao dev - domain model/class diagram theo bounded context (DOM), contract máy đọc OpenAPI 3.1/AsyncAPI 3.0 cho mọi interface (CTR), schema vật lý đủ cột kèm DDL và migration có rollback (PDM). Mọi sơ đồ theo chuẩn Archify (spec JSON validate showcase + mermaid + bảng). Kích hoạt khi người dùng nói "thiết kế kiến trúc", "vẽ sơ đồ hệ thống", "C4", "viết ADR", "chốt NFR", "quality attribute", "thiết kế API contract", "OpenAPI", "AsyncAPI", "mô hình dữ liệu", "class diagram", "domain model", "aggregate", "thiết kế cơ sở dữ liệu", "schema vật lý", "DDL", "migration", "index", "threat model", "phân quyền kỹ thuật", "HA DR", "RTO RPO", "timeout retry", "circuit breaker", "chia service thế nào". Input là OPT đã qua AG1; output vào sa-output/<PROJECT>/02-architecture/ và phải qua Gate AG2 (Ready for Build) trước khi dev bắt đầu.
|
||||
---
|
||||
|
||||
# GĐ2 · ARCHITECTURE — Định nghĩa kiến trúc
|
||||
@@ -8,8 +8,9 @@ description: Giai đoạn 2 của quy trình Solution Architect — định ngh
|
||||
Mục tiêu duy nhất: **dev đọc xong thi công được, QA đọc xong biết đo cái gì, SRE đọc xong biết
|
||||
vận hành thế nào** — không ai phải quay lại hỏi "cái này để đâu, gọi ai, hỏng thì sao".
|
||||
|
||||
Output: `ASR` · `QAS` · `SAD` · `ADR` · `ICD` · `DAT` · `SEC` · `INF` · `FAIL` trong
|
||||
`sa-output/<PROJECT>/02-architecture/`
|
||||
Output: `ASR` · `QAS` · `SAD` · `ADR` · `DOM` · `ICD` · `CTR` · `DAT` · `PDM` · `SEC` · `INF` · `FAIL` trong
|
||||
`sa-output/<PROJECT>/02-architecture/` (+ `contracts/` file OpenAPI/AsyncAPI, `schema/` DDL + migration,
|
||||
`diagrams/` spec Archify + HTML)
|
||||
|
||||
## Bốn nguyên tắc bất di bất dịch
|
||||
|
||||
@@ -21,7 +22,15 @@ Output: `ASR` · `QAS` · `SAD` · `ADR` · `ICD` · `DAT` · `SEC` · `INF` ·
|
||||
|
||||
Nạp thêm: `../sa-lifecycle/references/design-rules.md` (D1–D12) ·
|
||||
`../sa-lifecycle/references/decision-radar.md` (ngưỡng ADR) ·
|
||||
`../sa-lifecycle/references/artifact-map.md` §3–§4 (header, vòng đời ADR).
|
||||
`../sa-lifecycle/references/artifact-map.md` §3–§4 (header, vòng đời ADR) ·
|
||||
**`../ba-lifecycle/references/diagram-rules.md`** (chuẩn sơ đồ Archify — giai đoạn này vẽ nhiều nhất).
|
||||
|
||||
🔴 **Mọi sơ đồ theo chuẩn Archify** (`D4`, `W13`): spec JSON `diagrams/<ARTIFACT>_<slug>.<type>.json`
|
||||
với `quality_profile: showcase` **+** mermaid có marker `<!-- archify: <type> · <spec> -->` **+** bảng đi
|
||||
kèm. C4/deployment/ranh giới tin cậy → `architecture`; luồng chính → `sequence` (có nhánh lỗi);
|
||||
ownership dữ liệu → `dataflow`; ERD/class → `mermaid-only`. Một đường chính `emphasis`, ≤ 12 node,
|
||||
nhãn cạnh ghi giao thức + sync/async. Người điều phối chạy `archify validate/deliver` và
|
||||
`diagram-check.mjs`; không có Bash ⇒ ghi `humanInputNeeded`, không tự nhận "đã validate".
|
||||
|
||||
## Bước 0 — Chốt input rồi dừng lại
|
||||
|
||||
@@ -33,17 +42,27 @@ Nạp thêm: `../sa-lifecycle/references/design-rules.md` (D1–D12) ·
|
||||
2. **Kiểm AG1** — `OPT` đã `✅ Baselined` và có `Approved by` chưa? Chưa ⇒ báo rõ: thiết kế
|
||||
trên phương án chưa chốt sẽ phải làm lại. Vẫn chạy được nếu người dùng muốn, nhưng toàn bộ
|
||||
`Confidence` là 🔴.
|
||||
3. **Chọn phạm vi chạy** — làm cả 9 artifact hay chỉ một nhóm (`--focus`). Cả 9 là công việc
|
||||
nhiều tuần; hỏi rõ người dùng cần gì trước.
|
||||
3. **Chọn phạm vi chạy** — làm cả 12 artifact hay chỉ một nhóm (`--focus`). Cả 12 là công việc
|
||||
nhiều tuần; hỏi rõ người dùng cần gì trước. Ba artifact **bàn giao thẳng cho dev** (`DOM`, `PDM`,
|
||||
`CTR`) chỉ có nghĩa khi `SAD`/`DAT`/`ICD` đã ổn định — hỏi người dùng có muốn làm ngay không.
|
||||
4. **Cách hiểu bài toán** — 2–3 câu, kèm danh sách file định ghi ra.
|
||||
5. **Hỏi người dùng** xác nhận bốn điểm trên.
|
||||
|
||||
Bỏ bước dừng khi lệnh có `go`.
|
||||
|
||||
## Thực hiện — 9 hoạt động
|
||||
## Thực hiện — 12 hoạt động
|
||||
|
||||
Thứ tự **không tuỳ ý**: 1→2→3 bắt buộc trước; 4–8 chạy song song được; 9 chạy liên tục.
|
||||
Với `--focus`, vẫn phải đọc output của các bước trước, không được bỏ qua.
|
||||
Thứ tự **không tuỳ ý**: 1→2→3 bắt buộc trước; 4–8 chạy song song được; 9 chạy liên tục;
|
||||
10–12 (`DOM` · `CTR` · `PDM`) là **lớp bàn giao dev**, chạy sau artifact nguồn của nó
|
||||
(`DOM` sau `SAD`+`DAT` · `CTR` sau `ICD` · `PDM` sau `DAT`+`DOM`). Với `--focus`, vẫn phải đọc
|
||||
output của các bước trước, không được bỏ qua.
|
||||
|
||||
```
|
||||
qas → asr → sad ─┬─ icd ──→ ctr
|
||||
├─ dat ──→ dom ──→ pdm
|
||||
├─ sec · inf · fail
|
||||
└─ adr (liên tục)
|
||||
```
|
||||
|
||||
### 1 — Lượng hoá NFR thành `QAS` *(`--focus qas`)*
|
||||
|
||||
@@ -227,6 +246,69 @@ Quy tắc `D1`: một ADR, một quyết định. Quy tắc `D3`: bắt buộc n
|
||||
Điểm radar ≥ 8 ⇒ **không được chuyển `Accepted` khi chưa có POC hoặc bài đo**. Giữ ở
|
||||
`Proposed` và tạo mục trong `ARISK`.
|
||||
|
||||
### 10 — Domain model `DOM` *(`--focus dom`)*
|
||||
|
||||
Điền `templates/domain-model.md`. Cần `SAD` (`CMP`), `DAT` §1 (ownership) và `BR` của BA.
|
||||
|
||||
**Vì sao cần:** `DAT` nói ai sở hữu dữ liệu, `PDM` nói bảng trông thế nào — không có `DOM`, dev
|
||||
tự suy aggregate từ bảng, transaction boundary lệch nhau, invariant bị kiểm ở ba chỗ hoặc không chỗ nào.
|
||||
|
||||
Bốn việc:
|
||||
|
||||
1. **Bảng bounded context × aggregate** — mỗi aggregate là một ranh giới transaction; entity thuộc
|
||||
đúng một aggregate; sang aggregate khác chỉ giữ **id**.
|
||||
2. **Class diagram mỗi bounded context** (`classDiagram`, `mermaid-only`, ≤ 12 class) — chỉ thuộc tính
|
||||
nghiệp vụ và phương thức đổi trạng thái; DTO/repository thuộc `AGD`. Kèm bảng: class · invariant
|
||||
(`BR`) · kiểm ở phương thức nào · ai được gọi · bảng `PDM`.
|
||||
3. **Snapshot hay tham chiếu sống** — giá, tên, địa chỉ lúc giao dịch là snapshot; ghi từng trường.
|
||||
4. **Domain event** — tên · aggregate phát · payload tối thiểu (không PII) · người nhận · contract `CTR`.
|
||||
|
||||
🔴 Invariant không truy về `BR-nnn` ⇒ hoặc BA thiếu rule (báo `baSyncIssues`), hoặc SA đang bịa
|
||||
nghiệp vụ. Không được tự thêm rule.
|
||||
|
||||
### 11 — Contract máy đọc `CTR` *(`--focus ctr`)*
|
||||
|
||||
Điền `templates/contract-index.md` **và sinh file thật** trong `02-architecture/contracts/`:
|
||||
`openapi/<module>.yaml` (OpenAPI 3.1, từ `templates/contracts/openapi.template.yaml`),
|
||||
`asyncapi/<domain>-events.yaml` (AsyncAPI 3.0), `partners/<ten>.yaml` (mirror tài liệu đối tác, ghi nguồn).
|
||||
|
||||
Ba ràng buộc:
|
||||
|
||||
1. **Mọi `IF-nnn`** trong `ICD` §2 có `x-if` ở ≥ 1 operation/channel; **mọi endpoint** trong `API`
|
||||
của BA có `operationId`; **mọi mã lỗi** `E-…` của SRS §4.1 có trong `x-error-codes` và schema `Error`.
|
||||
2. **Ba quy ước `ICD` §1 nằm trong `components/`** và được `$ref`: số lớn `type: string`, thời gian
|
||||
`format: date-time`, phân trang theo `ADR`. Lỗi nghiệp vụ là 4xx.
|
||||
3. Mỗi operation ≥ 1 example thành công + 1 lỗi; `operationId` duy nhất toàn dự án.
|
||||
|
||||
Sau đó **sửa `ICD` cột "Contract ở đâu"** trỏ tới file + `operationId` thật. Còn "dự kiến" ⇒ AG2 chặn.
|
||||
|
||||
🔴 **Không tự viết contract thay đối tác ngoài.** Chưa có tài liệu VNPay/GHN ⇒ `ARISK` + `OQ`, file
|
||||
`partners/` để trống có ghi chú, không bịa schema.
|
||||
|
||||
Người điều phối chạy `spectral lint` (nếu có) hoặc
|
||||
`node .claude/skills/sa-2-architecture/scripts/contract-check.mjs --dir <contracts> --icd <ICD> --srs <SRS…> --api <API…>`
|
||||
và chép kết quả vào `CTR` §4.
|
||||
|
||||
### 12 — Schema vật lý `PDM` *(`--focus pdm`)*
|
||||
|
||||
Điền `templates/physical-data-model.md` **và sinh DDL thật** trong `02-architecture/schema/<kho>/`:
|
||||
`V001__init_<schema>.sql` + `V001__….down.sql` (+ `seed/R__reference_data.sql`). Cần `DAT`, `DOM`,
|
||||
bảng field `FLD-*` của SRS PART 2, `SEC` §5.
|
||||
|
||||
Sáu ràng buộc:
|
||||
|
||||
1. **Mọi thực thể `DAT` §1 → ≥ 1 bảng `TBL-nnn`**; bảng không truy về thực thể là thừa hoặc thiếu mô hình.
|
||||
2. **Mọi cột đủ bốn ô**: kiểu có độ dài/độ chính xác · Null · Default · Nguồn (`FLD`/`BR`). Độ dài
|
||||
`varchar` khớp bảng field của SRS theo code point — UI và DB chặn cùng một ngưỡng.
|
||||
3. **Cột PII gắn cờ** và có dòng ở `SEC` §5 (mã hoá, che, retention).
|
||||
4. **Index truy về truy vấn** ở `DAT` §7.1; truy vấn không có index ⇒ thiếu; index không có truy vấn ⇒ bỏ.
|
||||
5. **Migration có down**, chạy được từ CSDL rỗng; công cụ migration chốt bằng `ADR`; migration đổi
|
||||
dữ liệu ghi thêm cách đối chiếu và ngưỡng chênh lệch.
|
||||
6. Quy ước đặt tên, kiểu id, thời gian UTC, tiền, soft delete chốt **một lần** ở §1.
|
||||
|
||||
🔴 **Bảng field của BA và cột của SA lệch nhau là bug chắc chắn** — kiểm §7 hai chiều, lệch ⇒ `OQ`
|
||||
và báo BA (`baSyncIssues`), không im lặng chọn một bên.
|
||||
|
||||
## Trước khi kết thúc
|
||||
|
||||
In bốn thứ:
|
||||
@@ -235,11 +317,14 @@ In bốn thứ:
|
||||
|
||||
**② Checklist D1–D12** dạng ☐/✅.
|
||||
|
||||
**③ Bảng đối chiếu với bộ BA** — `NFR`↔`QAS`, `API`↔`ICD`, `RBAC`↔`SEC`, `BR`↔`ADR`. Mọi chỗ
|
||||
lệch phải liệt kê kèm hành động ("BA cập nhật SRS §… theo `IF-007`").
|
||||
**③ Bảng đối chiếu với bộ BA** — `NFR`↔`QAS`, `API`↔`ICD`/`CTR`, `RBAC`↔`SEC`, `BR`↔`ADR`/`DOM`,
|
||||
`FLD`↔`PDM`. Mọi chỗ lệch phải liệt kê kèm hành động ("BA cập nhật SRS §… theo `IF-007`").
|
||||
|
||||
**④ Danh sách `OQ` mở** kèm người phải trả lời và **hệ quả nếu trả lời ngược**.
|
||||
|
||||
**⑤ Checklist sơ đồ** (`diagram-rules.md` §8) và danh sách spec `diagrams/*.json` cần validate/deliver;
|
||||
với `ctr`/`pdm`: danh sách file contract/DDL cần lint và chạy thử.
|
||||
|
||||
Rồi nhắc người dùng: AG2 cần **Tech Lead + Security + Ops/SRE ký**.
|
||||
|
||||
## Bẫy thường gặp
|
||||
|
||||
Reference in New Issue
Block a user