ADR-0002. Một sản phẩm triển khai, tách thành role api và worker lúc runtime

Trường	Giá trị
Status	Accepted
Date	2026-03-30
Deciders	Phat Nguyen
Supersedes	-

Bối cảnh

• Phần REST (đưa vào hàng đợi, vòng đời, tải về) và pipeline sinh sổ nặng nề có nhu cầu tài nguyên cũng như cách mở rộng rất khác nhau.
• Gói mọi thứ vào mọi bản chạy sẽ lãng phí CPU trên pod API và buộc ingress phải gắn chặt với năng lực render.
• Tách thành hai package riêng lại nhân đôi schema, phần đấu nối DI và hạ tầng triển khai.

Quyết định

Chúng ta sẽ phát hành một image duy nhất và chọn hành vi lúc khởi động bằng APP_ENV_APPLICATION_ROLES (chuỗi CSV gồm api, worker; nếu không hợp lệ hoặc rỗng thì mặc định bật cả hai). configureControllers() chỉ đăng ký controller cho api; configureServices()/configureComponents() chỉ đăng ký pipeline worker (LedgerWorkerService, các generator), bộ phát WebSocket và lượt quét khôi phục cho worker. Kafka consumer và component khôi phục được đăng ký vô điều kiện nhưng tự bỏ qua chính nó khi không có role worker.

Hệ quả

Ưu	Nhược
Mở rộng API và worker độc lập	Việc phân luồng theo role nằm rải rác qua application.ts + các component
Một image, một artifact CI, dùng chung schema/DI	Nếu APP_ENV_APPLICATION_ROLES cấu hình sai thì âm thầm bật lại cả hai
Pod chỉ chạy worker không cần ingress	Phải kiểm tra role ở hai nơi (lúc đăng ký + lúc component tự bỏ qua)

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

Phương án	Ưu	Nhược	Vì sao loại
Hai package riêng	Cô lập triệt để	Nhân đôi schema/DI, triển khai gấp đôi	Quá nhiều trùng lặp cho một bounded context
Luôn chạy cả hai role trên mỗi bản	Cấu hình đơn giản nhất	Lãng phí CPU trên pod API; mở rộng bị gắn chặt	Đánh mất ý nghĩa của việc tách role
Feature flag cho từng component	Điều khiển chi tiết	Số lượng tổ hợp cấu hình bùng nổ	Hai role thô đã bao trùm mọi topology thực tế

Tham chiếu

• ledger/src/common/roles.ts (getAppRoles)
• ledger/src/application.ts (configureComponents/Services/Controllers)
• ledger/src/components/kafka.component.ts, recovery.component.ts (tự bỏ qua)
• Configuration