init git

.claude/skills/sa-lifecycle/references/workflow.md

@@ -0,0 +1,165 @@
+# Workflow SA — 4 giai đoạn, 4 gate
+
+## 1. Sơ đồ
+
+```
+      bài toán nghiệp vụ đã phát biểu được (BRIEF/BACKLOG của BA)
+              │
+   ┌──────────▼──────────┐
+   │ GĐ1 · CONTEXT       │  driver là gì, ràng buộc gì, chọn phương án nào
+   │ sa-1-context        │
+   └──────────┬──────────┘
+              │ AG1 — PO + Tech Lead ký: phương án & ngân sách đã chốt
+   ┌──────────▼──────────┐
+   │ GĐ2 · ARCHITECTURE  │  lượng hoá NFR, phân rã, contract, dữ liệu, bảo mật, hạ tầng
+   │ sa-2-architecture   │
+   └──────────┬──────────┘
+              │ AG2 — Tech Lead + Security + Ops ký: Ready for Build
+   ┌──────────▼──────────┐
+   │ GĐ3 · ENABLEMENT    │  guideline, fitness function, design review, tech debt
+   │ sa-3-enablement     │
+   └──────────┬──────────┘
+              │ AG3 — Tech Lead + QA + SRE ký: kiến trúc thi công đúng, sẵn sàng go-live
+   ┌──────────▼──────────┐
+   │ GĐ4 · EVOLUTION     │  đối chiếu telemetry, đánh giá drift, roadmap kỹ thuật
+   │ sa-4-evolution      │
+   └──────────┬──────────┘
+              │ AG4 — PO + SRE + EA ký: đóng vòng hoặc mở vòng kiến trúc mới
+              ▼
+```
+
+`sa-conformance` chạy song song, cập nhật `DTM` + `ADL` sau mỗi giai đoạn và **có quyền chặn
+AG2, AG3, AG4**.
+
+## 2. Tiêu chí pass từng gate
+
+Gate chỉ ✅ khi **đủ artifact** *và* **đủ nội dung** *và* **có chữ ký duyệt ghi trong header
+artifact** (dòng `Approved by: <tên> · <ngày>`).
+
+Gate kiến trúc khác gate BA ở một điểm: **không ký được bằng "trông hợp lý"**. Mỗi mục dưới
+đây phải chỉ ra được *bằng chứng* — một con số, một ADR, một kết quả POC, một bài đo.
+
+### AG1 — Option sign-off · duyệt bởi **PO + Tech Lead**
+
+- [ ] `CTX` có `DRV-nn` (driver) — mỗi driver ghi rõ **áp lực kinh doanh** đứng sau, không phải tính năng
+- [ ] `CTX` có `CON-nn` (ràng buộc): ngân sách, deadline, cloud/stack bắt buộc, kỹ năng team, pháp lý
+- [ ] `CTX` mô tả hiện trạng as-is: hệ thống, dữ liệu, tích hợp, hợp đồng vendor đang có
+- [ ] `OPT` có **≥ 2 phương án** được chấm điểm theo cùng bộ tiêu chí, và **nêu rõ phương án bị loại + lý do**
+- [ ] `TCO` có chi phí 3 năm: hạ tầng + license + vận hành + con người, theo ≥ 2 kịch bản tải
+- [ ] `ARISK` có rủi ro kỹ thuật mức cao, mỗi cái có **người chịu trách nhiệm** và **cách hạ rủi ro**
+- [ ] Rủi ro mức cao chưa chứng minh được ⇒ có **kế hoạch POC** kèm tiêu chí pass/fail
+
+**Chặn:** chỉ có một phương án ("chúng ta sẽ dùng X") — đó không phải lựa chọn, đó là thói quen.
+**Chặn:** ước lượng chỉ có effort dev, không có chi phí hạ tầng và vận hành.
+
+### AG2 — Ready for Build · duyệt bởi **Tech Lead + Security + Ops/SRE**
+
+- [ ] `ASR` liệt kê yêu cầu thực sự định hình kiến trúc, mỗi cái truy về `DRV` hoặc `QAS`
+- [ ] `QAS` — mọi NFR đã lượng hoá: **kịch bản · con số · cách đo · ai đo**. Không còn NFR định tính
+- [ ] `SAD` có sơ đồ C4 mức Context và Container, có deployment view, mỗi `CMP-nn` ghi rõ trách nhiệm
+- [ ] `ADR-nnn` tồn tại cho **mọi quyết định đạt ngưỡng ở `decision-radar.md`**, mỗi cái nêu phương án đã loại
+- [ ] `ICD` — mọi interface ra khỏi hệ thống có contract, owner, versioning policy, chế độ sync/async
+- [ ] `DAT` — mỗi thực thể dữ liệu có **đúng một** chủ sở hữu; có phân loại PII và retention
+- [ ] `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%
+
+**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.
+**Đâ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
+- [ ] `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)
+- [ ] `FAIL` đã được kiểm chứng: ít nhất các failure mode mức cao đã diễn tập (chaos/fault injection hoặc thủ công)
+- [ ] `TDEBT` — mọi lệch so với kiến trúc đã ghi nhận, có chủ và có hạn, không có mục "sẽ sửa sau" trống
+- [ ] `sa-conformance` báo coverage `QAS → bài đo` và `ràng buộc → FIT` ≥ 100% cho mức Must
+
+**Chặn:** ràng buộc kiến trúc chỉ tồn tại trong văn bản, không có fitness function — theo `D8`
+đó là khuyến nghị, không phải ràng buộc.
+
+### AG4 — Operational review · duyệt bởi **PO + SRE + Enterprise Architect**
+
+- [ ] `CONF` đối chiếu telemetry production với từng `QAS`: đạt / không đạt / chưa đo được
+- [ ] Chi phí hạ tầng thực tế so với `TCO`, giải thích chênh lệch > 20%
+- [ ] Mọi sự cố production trong kỳ truy được về một `ADR`, một `ASM`, hoặc ghi nhận là **điểm mù mới**
+- [ ] `PMR` — đánh giá kiến trúc, liệt kê drift so với `SAD`
+- [ ] `TRM` — roadmap kỹ thuật vòng sau, `TDEBT` đã xếp ưu tiên và đưa vào backlog
+- [ ] `ADL` — mọi ADR có trạng thái đúng (Accepted / Superseded / Deprecated)
+
+**Chặn:** không đo được `QAS` vì AG2 không định nghĩa cách đo — ghi nhận là bài học, không lấp liếm.
+
+## 3. Ai làm gì
+
+| Vai trò | Trách nhiệm trong pipeline SA |
+|---|---|
+| **Solution Architect** | Sở hữu toàn bộ artifact ở đây. Thiết kế, quyết định, ghi ADR, gác conformance |
+| **PO / Khách hàng** | Quyết trade-off nghiệp vụ và ngân sách. Ký AG1, AG4 |
+| **Tech Lead** | Ký AG1–AG3 về khả thi thi công. Phản biện thiết kế. Sở hữu chất lượng code |
+| **Security** | Ký AG2. Có **quyền phủ quyết** threat model và mô hình authz |
+| **Ops / SRE** | Ký AG2, AG3, AG4. Chốt HA/DR, observability, chi phí vận hành |
+| **QA** | Ký AG3. Xác nhận `QAS` đo được và đã đo |
+| **Enterprise Architect** | Ký AG4. Xác nhận không lệch chuẩn doanh nghiệp |
+| **BA** | Cung cấp input nghiệp vụ. Không ký gate kiến trúc |
+
+SA **không** thay PO quyết trade-off nghiệp vụ, **không** thay Security chấp nhận rủi ro,
+**không** thay PM quản tiến độ — nhưng phải cung cấp đủ thông tin để cả ba ra quyết định.
+
+## 4. Khớp với pipeline BA
+
+Hai bộ chạy đan xen, không nối tiếp. Bảng này chốt thứ tự thật:
+
+| Mốc | Điều kiện | Vì sao |
+|---|---|---|
+| SA GĐ1 bắt đầu | BA đã qua **G1** (có `BRIEF`, `GOAL`, `RQ`) | Không có driver thì không chấm được phương án |
+| BA gate **G2** | SA đã qua **AG1** | Tech Lead ký G2 "khả thi kỹ thuật" dựa trên `OPT` + `ARISK` của SA |
+| BA gate **G3** | SA đã qua **AG2** | `API` contract trong SRS phải khớp `ICD`; `NFR` của BA phải khớp `QAS` |
+| BA gate **G4** | SA đã qua **AG3** | UAT không nên chạy trên kiến trúc chưa đo được NFR |
+| BA gate **G5** | SA đã qua **AG4** | Benefit review nghiệp vụ đi cùng conformance kỹ thuật |
+
+🔴 **Điểm giao thường bị bỏ:** BA viết `API contract đề xuất` ở GĐ3 và đánh dấu *"BA đề xuất —
+chờ BE xác nhận"*. Người xác nhận đó chính là SA qua `ICD`. Không nối hai chỗ này thì SRS và
+kiến trúc lệch nhau ngay từ ngày đầu.
+
+## 5. Khi nào được bỏ giai đoạn
+
+| Tình huống | Được bỏ | Bắt buộc giữ |
+|---|---|---|
+| Thêm màn hình trong module đã có, không đổi contract | GĐ1, GĐ2 | Rà `FIT` còn xanh, cập nhật `SAD` nếu thêm `CMP` |
+| Thêm tính năng có endpoint mới, không đổi mô hình dữ liệu | GĐ1 | GĐ2 rút gọn: chỉ `ICD` + `QAS` liên quan |
+| Đổi mô hình dữ liệu / thêm tích hợp ngoài / đổi hạ tầng | — | Đủ 4 giai đoạn |
+| Hệ thống mới hoàn toàn | — | Đủ 4 giai đoạn |
+| POC / thử nghiệm | GĐ3, GĐ4 | GĐ1 (để biết đang chứng minh gì), GĐ2 rút gọn |
+
+Bỏ giai đoạn **phải ghi lý do vào `DEC-nn`** trong `00-index/`. Bỏ im lặng là nợ kiến trúc:
+sáu tháng sau không ai biết hệ thống đang chạy trên giả định nào.
+
+## 6. Vòng lặp ngược
+
+Gate không phải một chiều. Bốn đường quay lui hợp lệ:
+
+- **GĐ3 → GĐ2**: thi công phát hiện thiết kế không khả thi ⇒ `ADR` mới có `Supersedes: ADR-nnn`,
+  cập nhật `SAD`, không cần ký lại AG2 nếu không đụng `ICD`/`DAT`/`SEC`. Đụng ⇒ ký lại.
+- **GĐ4 → GĐ2**: telemetry cho thấy `QAS` không đạt do thiết kế ⇒ mở `ADR` mới, đây là tín hiệu
+  AG2 đã ký trên ước lượng thay vì bài đo.
+- **GĐ2 → GĐ1**: thiết kế chi tiết cho thấy phương án đã chọn quá đắt ⇒ quay lại `OPT`, ghi
+  `DEC-nn` giải thích vì sao đổi. Rẻ hơn nhiều so với phát hiện ở GĐ3.
+- **Bất kỳ → GĐ1**: driver kinh doanh thay đổi ⇒ `CTX` phiên bản mới, rà lại toàn bộ `ADR`
+  có trạng thái `Accepted` xem còn đúng không.
+
+## 7. Nhịp chạy đề xuất
+
+Kiến trúc không phải một đợt làm rồi thôi. Nhịp tối thiểu cho một dự án 6 tháng:
+
+| Việc | Tần suất |
+|---|---|
+| Cập nhật `ADL` + `DTM` (`sa-conformance`) | Cuối mỗi sprint |
+| Design review các thay đổi chạm kiến trúc (`DREV`) | Theo yêu cầu, tối đa 2 ngày chờ |
+| Rà `TDEBT`, xếp lại ưu tiên | Hai tuần một lần |
+| Đo `QAS` mức Must trên môi trường gần production | Trước mỗi release |
+| `CONF` đối chiếu telemetry | Hàng tháng sau go-live |
+| `PMR` đánh giá kiến trúc | Mỗi quý hoặc sau mỗi sự cố nghiêm trọng |