# 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
- [ ] `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, 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**

- [ ] `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)
- [ ] `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 |