sys-analysis-design/sa-output/e-commerce/02-architecture/adr/ADR-014_transactional-outbox-publish-su-kien.md

# ADR-014 — Transactional Outbox cho publish sự kiện Cart & Order / Payment

*Tên file: `adr/ADR-014_transactional-outbox-publish-su-kien.md`*

| | |
|---|---|
| **Status** | `Proposed` |
| **Date** | 2026-09-15 |
| **Người quyết** | SA + Tech Lead (cấu trúc/tích hợp — `decision-radar.md §5`) — chưa ký thật |
| **Người đề xuất** | SA (qua skill `sa-2-architecture`, hoạt động `adr`) |
| **Điểm radar** | **6/10** *(chấm theo `decision-radar.md §2`, kế thừa nguyên ước lượng đã ghi ở `DAT_e-commerce_v1.0.md §4.1`: Chi phí đảo ngược=1 (1–3 tuần — `outbox_event` là bảng nội bộ, không phải dữ liệu nghiệp vụ, chưa tới mức "phải migrate dữ liệu") · Bán kính ảnh hưởng=1 (Cart&Order + Payment, 2 `CMP` publish, cộng tiền lệ cho các module tương lai) · Chạm `QAS` Must=1 (gián tiếp `QAS-005`/`DRV-08` — không mất giao dịch, không phải chính nó là con số `QAS`) · Ràng buộc dài hạn=2 (trở thành chuẩn chung cho mọi module publish sự kiện, ≥1 năm) · Tranh cãi=0, cộng +1 vì đây là quyết định **thiết lập tiền lệ** áp dụng toàn hệ thống (`decision-radar.md §4`) → **5–7 ⇒ `ADR` bắt buộc**, dưới ngưỡng 8 nên không bắt buộc POC trước khi `Accepted`, nhưng cần bài đo/`FIT` xác nhận trước khi chuyển `Accepted` theo §6)* |
| **Supersedes** | — |
| **Superseded by** | — |
| **Liên quan** | `ASR-004` · `ASR-005` · `QAS-005` · `DRV-08` · `ADR-004` · `ADR-005` · `ADR-013` · `DAT_e-commerce_v1.0.md §1.3, §1.4, §4.1` · `FAIL_e-commerce_v1.0.md §7` · `OQ-044` · `DEC-25` |

> ⚠️ **ADR bất biến sau khi `Accepted`.** Muốn đổi quyết định thì viết ADR mới có
> `Supersedes: ADR-014` và đổi trạng thái bản cũ thành `Superseded by`. Không sửa nội dung ADR
> đã `Accepted`, không xoá ADR đã `Rejected`.

---

## 0. Ghi chú Preflight & ngoại lệ gate — bắt buộc đọc trước

AG1 vẫn chưa ký thật; AG2 (gate của chính GĐ2) chưa tới hạn. Theo `SKILL.md`, hoạt động 1 (`QAS`)
→ 2 (`ASR`) → 3 (`SAD`) đã hoàn tất và được duyệt từng phần từ trước; hoạt động 4–8 (`ICD`/`DAT`/
`SEC`/`INF`/`FAIL`) đã chạy và duyệt từng phần (`DEC-18…30`). `ADR-001…013` đã viết (`Proposed`).
`DAT_e-commerce_v1.0.md §4.1` (duyệt từng phần, `DEC-25`) đã chọn **TẠM** hướng Transactional
Outbox cho khoảng trống dual-write phát hiện ở `FAIL §7`, và yêu cầu SA viết `ADR-014` chính thức
ở lượt hoạt động `adr` này. Người dùng (vai điều phối dự án chạy thử) đã được cảnh báo lại và
**khẳng định muốn tiếp tục**.

> **DEC-31 (SA)** — Viết `ADR-014`/`ADR-015`/`ADR-016`/`ADR-017` (`Proposed`) cho e-commerce trong
> khi AG1 chưa ký thật và AG2 chưa tới hạn — tiếp nối `DEC-01…30`. Hiện thực hoá 4 hướng đã chọn
> TẠM qua `OQ-044`/`DEC-25` (outbox), `OQ-050`/`DEC-28` (service JWT), và 2 ứng viên mới của `INF`
> (`DEC-30`: blue-green, Terraform). Tất cả 4 `ADR` giữ `Status Proposed` — không `Accepted`. Chỉ
> link 4 `ADR` này vào `DAT §4.1`, `SEC §2.4`/§4 (TB3/TB4), `INF §7.2`/§11 (thay "ứng viên"/"chưa
> viết" bằng đường dẫn thật), không đổi nội dung chuyên môn khác của ba tài liệu đó — mỗi file
> chạm tới bump `+0.1` kèm Change Log "chỉ link ADR, không đổi nội dung". Cập nhật `ADL`/`DTM`.
> **Người quyết:** Điều phối dự án (đại diện PO, dự án chạy thử).
> **Radar (ước lượng cho việc tiếp tục dưới ngoại lệ, khác điểm radar riêng của từng ADR):** ~4 —
> chi phí đảo ngược thấp (ghi 4 ADR + link tài liệu, chưa có dòng code phụ thuộc) · bán kính ảnh
> hưởng: AG2 phụ thuộc nhưng bản thân *việc ghi dưới ngoại lệ* thì nhỏ · chạm gián tiếp `QAS-005`/
> `QAS-007`/`QAS-002`/`QAS-010` Must (đang hiện thực hoá các cơ chế đạt chúng) nhưng chưa cam kết
> thi công (không `ADR` nào `Accepted`) · không ràng buộc dài hạn tự thân (nội dung từng `ADR` đã
> được chấm radar riêng, 5–7, không cái nào ≥8) · không tranh cãi mới, tiếp nối tiền lệ `DEC-17/23`
> → **ghi `DEC-nn`, không cần thêm `ADR` cho chính việc chạy dưới ngoại lệ**.
> **Hệ quả nếu không chấp nhận ngoại lệ:** `OQ-044`/`OQ-050` tiếp tục treo ở trạng thái "đã chọn
> hướng nhưng chưa có `ADR`" — Dev không có tài liệu chính thức để thi công outbox/service-authn;
> `INF §7.2`/§11 tiếp tục ghi "đề xuất ADR mới, chưa viết", để lộ khoảng trống ở tiêu chí AG2
> "`ADR` tồn tại cho mọi quyết định đạt ngưỡng radar".

---

## 1. Bối cảnh

`FAIL_e-commerce_v1.0.md §7` phát hiện một khoảng trống: nếu service chết **sau** `COMMIT`
transaction tạo `Order` nhưng **trước** khi publish `OrderPlaced`/`PaymentInitRequested` thành
công, sự kiện bị mất vĩnh viễn — không consumer nào (Commission, Promotion, Notification,
Shipping, Payment) biết `Order` đó tồn tại. Đây là bài toán **dual write** kinh điển (ghi DB + gọi
message queue không nguyên tử). `DAT_e-commerce_v1.0.md §4.1` đã phân tích khoảng trống này và đề
xuất Transactional Outbox, được duyệt **TẠM** qua `DEC-25` với yêu cầu SA viết `ADR` chính thức.

`ADR-005` đã chốt message backbone (SQS FIFO + EventBridge); `ADR-013` bổ sung một sự kiện mới
(`PaymentInitRequested`) publish **cùng lúc** với `OrderPlaced` ngay sau khi commit — càng làm
tăng tầm quan trọng của việc publish nguyên tử, vì nay có ≥2 sự kiện phải cùng "sống hay chết"
với transaction ghi `Order`.

**Ràng buộc đang chi phối:**

| Nguồn | Nội dung |
|---|---|
| `ASR-004` | Webhook + xác nhận thanh toán phải idempotent + có cơ chế bù — mở rộng tinh thần sang cả bước publish sự kiện tạo đơn |
| `ASR-005` | Message backbone SQS FIFO + EventBridge đã chọn (`ADR-005`) — outbox là cơ chế publish nguyên tử **lên trên** backbone đó, không thay thế nó |
| `QAS-005` | Fan-out lag ≤5 giây từ `OrderPlaced` tới consumer — outbox relay (đề xuất 1–2 giây) phải nằm trong ngân sách này |
| `DRV-08` | Xác nhận thanh toán/giao dịch không được mất — outbox là biện pháp trực tiếp chống mất sự kiện `OrderPlaced`/`PaymentInitRequested` |

**Cái đã biết chắc / cái còn là giả định:**

| Điều | 🟢 Đã kiểm chứng / 🔴 Giả định | Bằng chứng |
|---|---|---|
| Dual-write (ghi DB + gọi queue không cùng transaction) có thể mất sự kiện nếu service chết giữa hai bước | 🟢 Đã kiểm chứng — đây là vấn đề đã biết rộng rãi trong kiến trúc phân tán, không cần đo riêng cho dự án này | `FAIL §7` |
| Relay poller in-process (đọc `outbox_event` mỗi 1–2 giây) đủ nhanh để không ăn hết ngân sách `QAS-005` (≤5 giây) | 🔴 Giả định (`ASM-38`, `DAT §4.1`) | Chưa đo — cần bài đo GĐ3 |
| Consumer đã có dedupe theo `eventId` (chống publish trùng khi relay publish thành công nhưng đánh dấu `published` thất bại — at-least-once) | 🟢 Đã kiểm chứng — đã thiết kế ở `ICD §4` | `ICD_e-commerce_v1.0.md §4` |

## 2. Phương án đã cân nhắc

### PA-1 — Job quét đối chiếu định kỳ

| | |
|---|---|
| **Mô tả** | Job định kỳ (đề xuất mỗi 5 phút) quét `order` không có sự kiện tương ứng đã publish thành công (dựa cột đánh dấu `event_published_at`), publish lại |
| **Ưu** | Không cần bảng/hạ tầng mới, chỉ thêm 1 cột đánh dấu |
| **Nhược** | Không giải quyết nguyên nhân gốc — luồng publish "bình thường" (ngay sau commit) vẫn là dual-write không nguyên tử, job chỉ là lưới vá muộn; có race condition giữa "đang xử lý" và "đã mất" nếu không thiết kế cẩn thận cột đánh dấu; độ trễ phát hiện tối đa bằng chu kỳ job (5 phút) — vượt xa ngân sách `QAS-005` (≤5 giây) cho trường hợp cần vá; không tổng quát — mỗi module publish event sau này phải tự cài lại logic quét riêng |
| **Chi phí đảo ngược** | Trung bình — đổi sang cơ chế khác sau khi nhiều module đã cài job quét riêng tốn công dọn dẹp từng nơi |

### PA-2 — Transactional Outbox *(chọn)*

| | |
|---|---|
| **Mô tả** | Ghi một dòng `outbox_event` **trong cùng transaction DB** với việc tạo `Order`/`OrderSeller`/`OrderItem` (cùng schema `cart_order`, cùng ACID). Một relay (poller in-process, đề xuất chu kỳ 1–2 giây, `ASM-38`) đọc `outbox_event` trạng thái `pending`, publish lên SQS/EventBridge, đánh dấu `published` khi thành công. Payment Service dùng bảng `outbox_event` riêng trong RDS Payment của nó (2 DB khác nhau, không chia sẻ bảng) |
| **Ưu** | Đảm bảo tính nguyên tử thật sự giữa ghi DB và phát sự kiện (industry-standard); dùng được cho **mọi** module publish event sau này, không chỉ Cart & Order; độ trễ phát hiện/publish thấp (1–2 giây), nằm gọn trong ngân sách `QAS-005` (≤5 giây) |
| **Nhược** | Thêm bảng `outbox_event` mỗi module publish + một relay process cần giám sát riêng (lag alerting); độ trễ publish tăng nhẹ (1–2 giây thay vì tức thời) |
| **Chi phí đảo ngược** | Trung bình (1–3 tuần) — sau khi Cart&Order + Payment đã tích hợp, đổi sang cơ chế khác cần sửa lại relay + rà lại mọi module đã dùng, nhưng `outbox_event` là bảng nội bộ kỹ thuật, không phải dữ liệu nghiệp vụ, nên chưa tới mức "phải migrate dữ liệu" |

### PA-3 — 2PC (Distributed transaction giữa DB và message broker)

| | |
|---|---|
| **Mô tả** | Dùng giao thức 2-phase commit (XA transaction) trải rộng cả việc ghi DB lẫn publish message, đảm bảo cả hai cùng commit hoặc cùng rollback |
| **Ưu** | Về lý thuyết là đảm bảo nhất quán mạnh nhất giữa hai hệ thống |
| **Nhược** | **Không khả thi kỹ thuật** — SQS FIFO và EventBridge (đã chốt ở `ADR-005`) là dịch vụ managed của AWS, **không hỗ trợ tham gia giao thức XA/2PC**; ngay cả nếu đổi sang một message broker hỗ trợ 2PC, cơ chế này làm giảm throughput đáng kể (transaction coordinator là điểm nghẽn tập trung) và đội chưa có kinh nghiệm vận hành (`CON-05`) |
| **Chi phí đảo ngược** | Không áp dụng — loại ngay từ đầu vì không khả thi kỹ thuật với hạ tầng đã chọn |

### Bảng so sánh

| Tiêu chí | PA-1 | PA-2 | PA-3 |
|---|---|---|---|
| Đảm bảo nguyên tử ghi DB + publish | ❌ Không (chỉ vá muộn) | ✅ Có | ✅ Về lý thuyết |
| Khả thi với SQS FIFO/EventBridge (`ADR-005`) | ✅ | ✅ | ❌ Không hỗ trợ XA |
| Độ trễ phát hiện/publish khi lỗi | Tối đa chu kỳ job (5 phút) — vượt `QAS-005` | 1–2 giây (`ASM-38`) — trong ngân sách `QAS-005` | N/A (không khả thi) |
| Tổng quát cho mọi module tương lai | 🔶 Phải cài riêng từng nơi | ✅ Một chuẩn chung | N/A |

## 3. Quyết định

> **Chọn PA-2 — Transactional Outbox (bảng `outbox_event` + relay poller in-process chu kỳ
> 1–2 giây).**

**Vì sao:** Đây là phương án duy nhất vừa giải quyết đúng nguyên nhân gốc (dual-write không
nguyên tử) vừa khả thi với message backbone đã chọn (`ADR-005`), và tổng quát hoá được cho mọi
module publish sự kiện trong tương lai — đúng tinh thần `DRV-08` (không mất giao dịch).

**Phạm vi áp dụng:** Toàn hệ thống — mọi module publish sự kiện qua SQS FIFO/EventBridge (bắt đầu
với Cart & Order publish `OrderPlaced`/`PaymentInitRequested`, và Payment Service publish
`PaymentConfirmed`/`PaymentInitReady`/`PaymentInitFailed` qua bảng `outbox_event` riêng trong RDS
Payment của nó). Module nào publish sự kiện mới sau này (Commission, Shipping, …) dùng cùng mẫu.

### Điều kiện chuyển `Proposed → Accepted`

| Điều kiện | Ai xác nhận | Trạng thái hiện tại |
|---|---|---|
| Tech Lead xác nhận thiết kế relay (poller in-process, chu kỳ 1–2 giây, số instance/HA của relay) | Tech Lead | Mở (`OQ-044` chưa đóng) |
| Bài đo xác nhận relay lag thật không ăn quá nhiều vào ngân sách `QAS-005` (≤5 giây) | Tech Lead + QA | Chưa chạy — GĐ3 |
| `FIT` §6 dưới đây chạy PASS ít nhất 1 lần ở staging | Tech Lead/SRE | Chưa chạy |

## 4. Phương án bị loại và lý do

| Phương án | Loại vì | Gắn với | Điều kiện nào thì xét lại |
|---|---|---|---|
| PA-1 — Job quét đối chiếu định kỳ | Không giải quyết nguyên nhân gốc (vẫn dual-write ở luồng bình thường), độ trễ phát hiện tối đa 5 phút vượt xa ngân sách `QAS-005` (≤5 giây), không tổng quát cho module tương lai | `QAS-005`, `DRV-08` | Chỉ xét lại như biện pháp bổ sung (không thay thế outbox) nếu cần một lớp giám sát "vá muộn" cho các dòng `outbox_event` bị kẹt bất thường — bản thân outbox relay đã đóng vai trò chính |
| PA-3 — 2PC (XA transaction) | Không khả thi kỹ thuật — SQS FIFO/EventBridge không hỗ trợ XA/2PC (`ADR-005`); ngay cả đổi broker, giảm throughput đáng kể và đội chưa có kinh nghiệm (`CON-05`) | `ADR-005`, `CON-05` | Chỉ xét lại nếu đổi hẳn message backbone sang một hệ có hỗ trợ 2PC **và** có bằng chứng throughput đáp ứng — chưa có tiền lệ ở dự án này |

## 5. Hệ quả

**Hệ quả tích cực**

- Đảm bảo tính nguyên tử thật sự giữa ghi `Order` và phát sự kiện — đóng khoảng trống `FAIL §7`
- Một chuẩn chung dùng được cho mọi module publish sự kiện sau này (Commission, Shipping,
  Notification, …), không phải thiết kế lại từ đầu mỗi lần
- Cho phép `ADR-013` publish đồng thời `OrderPlaced` + `PaymentInitRequested` một cách an toàn

**Hệ quả tiêu cực phải sống chung**

- Thêm bảng `outbox_event` ở mỗi module publish (Cart & Order, Payment Service — đã thiết kế ở
  `DAT §1.3`/§1.4) — tăng độ phức tạp schema
- Relay process là một thành phần mới cần giám sát riêng (lag alerting theo tuổi dòng `pending`,
  chưa thiết kế ngưỡng cụ thể — thuộc `inf`)
- Độ trễ publish tăng nhẹ (1–2 giây thay vì tức thời) — cần xác nhận không ăn quá nhiều vào ngân
  sách `QAS-005` (≤5 giây) khi cộng cả thời gian consumer xử lý

**Cái quyết định này khoá lại**

| Muốn đổi về sau thì | Tốn |
|---|---|
| Đổi khỏi Outbox sang cơ chế khác (VD CDC — Change Data Capture) sau khi mọi module đã tích hợp | Cần thay relay + rà lại từng module đã dùng — nhiều tuần, dù không phải migrate dữ liệu nghiệp vụ |

**Việc phát sinh**

| Việc | Chủ | Hạn | Ghi ở đâu |
|---|---|---|---|
| Thiết kế chi tiết relay (số instance, HA, cơ chế lock tránh 2 relay cùng publish 1 dòng) | Tech Lead + SA (hoạt động `inf` lượt sau) | Trước khi Dev thi công | `INF_e-commerce_v1.0.md` (bổ sung) |
| Thêm alerting lag `outbox_event` (tuổi dòng `pending` vượt ngưỡng) | SA (hoạt động `inf`)/Ops | Trước AG2 | `INF_e-commerce_v1.0.md` |
| Viết `FIT-26`/`FIT-27` thật | QA/Dev (GĐ3) | GĐ3 | `03-enablement/FIT_e-commerce.md` |

## 6. Cách kiểm chứng quyết định này được tuân thủ

| Cách kiểm | Công cụ | Chạy ở đâu | `FIT` |
|---|---|---|---|
| Không có publish nào đi thẳng SQS/EventBridge mà bỏ qua ghi `outbox_event` trong cùng transaction ("không publish ngoài outbox") | Static analysis (lint rule cấm gọi trực tiếp SDK publish ngoài lớp outbox) + integration test kiểm tra mọi `Order` tạo ra đều có dòng `outbox_event` tương ứng trong cùng transaction | CI + staging | `FIT-26` *(ứng viên GĐ3)* |
| Chaos: kill relay process giữa lúc có tải, xác nhận `outbox_event` tồn đọng không mất; khi relay phục hồi (restart), toàn bộ dòng `pending` được publish, không mất và không publish thiếu | Chaos test — dừng relay, tạo N `Order`, khởi động lại relay, đếm số sự kiện consumer nhận được so với N | Staging | `FIT-27` *(ứng viên GĐ3)* |

Cả `FIT-26`/`FIT-27` là **ứng viên**, chưa viết thật (thuộc GĐ3 `sa-3-enablement`).

## 7. Điều kiện xét lại

| Dấu hiệu | Ngưỡng | Ai theo dõi |
|---|---|---|
| Relay lag thật (từ lúc `outbox_event` ghi tới lúc publish) thường xuyên vượt ngưỡng, ăn quá nhiều vào ngân sách `QAS-005` | p95 lag > 3 giây (margin còn lại quá mỏng so với ngân sách 5 giây) | Tech Lead + SRE |
| Số dòng `outbox_event` tồn đọng (`pending`) tăng liên tục, không giảm | Tồn đọng > vài phút liên tục theo dõi qua CloudWatch (ngưỡng cụ thể chưa chốt — thuộc `inf`) | Ops/SRE |

## 8. Tham chiếu

- POC: Không bắt buộc (radar 6/10, dưới ngưỡng 8) — nhưng khuyến nghị bài đo relay lag trước khi
  `Accepted`
- Bài đo: `FIT-26`/`FIT-27` (ứng viên GĐ3)
- Tài liệu ngoài: —
- Thảo luận: `DAT_e-commerce_v1.0.md §4.1` (phát hiện + đề xuất), `FAIL_e-commerce_v1.0.md §7`
  (khoảng trống gốc), `OQ-044`/`DEC-25` (chọn hướng TẠM)