Bản dịch: UC_9.2 → UC_9.17 (BACKGROUND MECHANISMS & CRON JOBS)

Tổng hợp bản dịch tiếng Việt cho 11 use case thuộc nhóm BACKGROUND MECHANISMS & CRON JOBS đã có tài liệu SRS. File gốc tiếng Anh không bị thay đổi — khi có mâu thuẫn, file gốc là bản chuẩn. Mọi mã UC, field name, API endpoint, business rule ID, status value, code block và nội dung tin nhắn/email gửi cho user giữ nguyên tiếng Anh. UC_9.1, UC_9.4–UC_9.7, UC_9.10 chưa có tài liệu SRS nên chưa có trong bản dịch này. Ngày dịch: 2026-10-27. Cập nhật 2026-10-27: UC_9.2 (v2.0) và UC_9.12 (v1.1) theo CR-20261027-001 (Flow 13 hybrid); UC_9.2 (v2.1) và UC_9.17 (v1.3) đồng bộ account_status = 'Active_DMA'. Cập nhật 2026-10-28: UC_9.3 (v1.1) theo spec Flow 18. Cập nhật 2026-11-05: đồng bộ UC_9.2 (v2.5), UC_9.3 (v1.3), UC_9.11 (v1.1), UC_9.12 (v1.2), UC_9.14 (v1.1), UC_9.15 (v1.1), UC_9.16 (v1.1) theo câu trả lời của khách 2026-10-30 / 2026-11-04; mọi link .md đổi sang đường dẫn tuyệt đối /docs/. Cập nhật 2026-11-05 (sau): UC_9.8 (v1.2) theo câu trả lời của khách 2026-11-03 (Flow 30 — refund và cờ warning_80_fired).

Mục lục

UC_9.2 — Luồng 13: Quản lý Nghỉ phép (DTO W-2 & Tạm ngưng Quốc tế)

Danh mục UC

<a id="UC_9.2"></a>

UC_9.2 — Luồng 13: Quản lý Nghỉ phép (DTO W-2 & Tạm ngưng Quốc tế)

1. Tổng quan

2. Trigger

Hai kênh vào — kênh quyết định path (CR-20261027-001):

(Nguồn: CR-20261027-001 — khách hàng: "W2 traders can use Rippling" · "Create a very simple request form on the unified Dashboard for international contractors"; QnA [HR-DEF-01] 2026-08-15)

2.1 Trigger Path A — webhook Rippling Time Off Request Approved

• Rippling sở hữu yêu cầu của W-2, số dư DTO và việc quản lý duyệt. Flow 13 chỉ bắt đầu sau khi Rippling đã duyệt yêu cầu.
• Khi nhận webhook, Zap chỉ kiểm tra và lưu yêu cầu. Các bước xử lý nghỉ phép (Bước A-3 → A-4) chạy vào leave_start_date đã đăng ký trên Rippling, qua Zapier delay_until — cùng cơ chế Return Protocol dùng cho ngày kết thúc.
• Cùng webhook này cũng kích hoạt Flow 35 — PTO Ledger Sync (UC_9.12). Flow 13 Path A và Flow 35 chạy độc lập trên cùng một event.
• Các trường được dùng từ payload: Rippling worker → user_id; Rippling Request ID; ngày bắt đầu nghỉ; ngày kết thúc nghỉ (→ DTO_Hiatus_End_Date); số ngày được duyệt (→ Requested_Days).

2.2 Trigger Path B — form "Request Time Off" trên Dashboard (chỉ International Contractor)

Điểm vào UI (UC_4.16.2 — Career & HR Widget):

• Nút: "Request Time Off" — góc trên bên phải của phần Employment Status trong Career & HR Widget.
• Điều kiện hiển thị: chỉ International Contractor có Current_Level >= 6. Ẩn với trader W-2 (Employment_Type = 'W-2') và với trader dưới Level 6.
• Thiết kế: References/Wireframe/Dashboard/Flow 13_Request Time Off modal (International).jpg · Figma — modal Request Time Off.

Modal "Request Time Off" (thiết kế đã duyệt):

Figma: modal Request Time Off

⚠️ Ghi chú: cần thêm nút Cancel vào thiết kế (hiện chỉ có Send). Các cách đóng khác (X / click ra ngoài / Esc) — xem Q-4.

Công cụ form: Form native của Dashboard — KHÔNG phải công cụ bên thứ ba (ví dụ Typeform hoặc Google Forms).

Webhook payload được gửi tới Zapier Flow 13 khi Send:

Loại trigger: Submit form → JSON webhook → endpoint catch-hook của Zapier → Flow 13.

2.3 Cổng vào (cả hai kênh)

Current_Level >= 6 — được kiểm tra khi nhận webhook Rippling (Path A) hoặc khi submit form (Path B).

• Nếu Current_Level < 6 → từ chối / bỏ qua. Không xử lý thêm. Path A: ghi log vào BPS_Audit_Log (xem Exc-1).

Lý do: Level 6 là ngưỡng tối thiểu cho hợp đồng lao động W-2 (USA) hoặc hợp đồng independent contractor dựa trên retainer (International). Trader dưới Level 6 hoạt động theo mô hình bonus theo yêu cầu và không đủ điều kiện hưởng chính sách này. (Nguồn: Zapier Integration V7.pdf §Flow 13 lines 1949–1951; khách hàng xác nhận 2026-08-22)

3. Path Router

Path được xác định bởi kênh trigger:

Guard (kiểm tra nhất quán): quốc gia đã xác minh KYC (được ưu tiên hơn billing_country theo CR-20260812-005) và Employment_Type phải khớp với kênh:

• Webhook Rippling cho trader không phải Employment_Type = 'W-2' → không xử lý; ghi log vào BPS_Audit_Log (Exc-1).
• Form Dashboard được gửi bởi trader W-2 (nút lẽ ra phải bị ẩn — defence in depth) → từ chối; không thay đổi trạng thái.

(Nguồn: CR-20261027-001; Zapier Integration V7.pdf §Flow 13 — "Path Router" line 1951)

4. Luồng cơ bản

Path A — USA W-2 Paid DTO

Bước A-1. Nhận webhook duyệt từ Rippling

• Zapier nhận webhook Rippling Time Off Request Approved (§2.1).
• Ánh xạ Rippling worker sang user_id; áp dụng cổng vào (Current_Level >= 6) và guard W-2 (§3). Thất bại → Exc-1.
• Dedup trên Rippling Request ID — webhook được gửi lại không được gia hạn stagnation_deadline hai lần.
• Không có DTO Balance Check và không có lời gọi Rippling API nào từ Stack Trading. Rippling sở hữu số dư DTO và việc duyệt; Flow 13 chỉ xử lý các yêu cầu đã được duyệt. Requested_Days = số ngày được duyệt từ payload.

(Nguồn: QnA_STAGE2_SETTINGS_CAREER_VIRAL.md [HR-DEF-01] — yêu cầu PTO, số dư và việc duyệt do Rippling sở hữu)

Bước A-1.5. Chờ đến ngày bắt đầu nghỉ

• Hôm nay < leave_start_date: Zap tạm dừng với delay_until = leave_start_date (lấy từ payload Rippling) và tiếp tục Bước A-3 vào ngày đó. Trước ngày đó trader giao dịch bình thường; trader_status không đổi.
• Hôm nay ≥ leave_start_date: tiếp tục ngay — webhook đến trễ được xử lý theo Exc-2 (Trường hợp 1 / Trường hợp 2).
• Bước A-2 (ledger Flow 35) và Bước A-5 (DTO_Approval_Notice) không bị trì hoãn — chạy ngay khi nhận webhook.

Bước A-2. PTO Ledger Sync (Flow 35 — song song, không thuộc Zap này)

• Cùng webhook Rippling kích hoạt Flow 35 (UC_9.12), gọi POST /api/ledger/record với metric_category = "Corporate Benefits", metric_value = "[Days_Approved] Days PTO Approved (Paid Time Off)", receipt_hash = [Rippling Request ID].

(Nguồn: Zapier Integration V7.pdf §Flow 35 lines 2535–2548)

Bước A-3. Gia hạn Stagnation Deadline

• Thực thi SQL update:

  UPDATE Users
  SET stagnation_deadline = stagnation_deadline + INTERVAL '[Requested_Days] days'
  WHERE user_id = [trader_id];

• Việc này đảm bảo Flow 12 (Zombie Protocol) và Flow 19 (Stagnation Monitor) không phạt trader vì không hoạt động trong thời gian nghỉ phép đã được duyệt.

(Nguồn: Zapier Integration V7.pdf §Flow 13 line 1961)

Bước A-3.5. Đóng toàn bộ vị thế đang mở

Trước khi khóa tài khoản, Middleware đóng toàn bộ lệnh / vị thế đang mở của trader. Việc khóa tài khoản ở Bước A-4 chỉ được thực thi sau khi tài khoản không còn vị thế đang mở.

(Nguồn: Zapier Integration V7.pdf §Flow 13 — "Disable Trading Account via Middleware (Lock)")

Bước A-4. Khóa tài khoản giao dịch

• Gọi POST /system/set-account-state:

  { "user_id": "[trader_id]", "state": "Locked", "context": "DTO" }

• Middleware gửi các lệnh khóa theo từng nền tảng sau khi xác nhận tài khoản đã flat (Bước A-3.5):
  • Rithmic: R|API+ Suspend Trading.
  • MT5: YourBourse Contest Stop Out Plugin API (POST) — đặt tài khoản ở chế độ Read-Only; đóng băng giá trị Target Profit / Stop Loss trong RAM.
  • TraderEvolution: Admin API — đặt tài khoản ở Lock/Read-Only.
• Ghi DB sau gateway (chỉ thực thi sau khi nhận HTTP 200 từ tất cả gateway đang hoạt động):
  • trader_status = 'On_Leave'
  • is_professional = TRUE (nếu trader dùng DMA)
  • stagnation_deadline đã được cập nhật ở Bước A-3

(Nguồn: Zapier Integration V7.pdf §Flow 13 line 1961; §POST /system/set-account-state lines 136–140; Supplement §3.2)

Bước A-5. Thông báo cho trader

• Gửi ngay khi nhận webhook (không bị trì hoãn bởi Bước A-1.5). Gửi email DTO_Approval_Notice qua AWS SES xác nhận duyệt nghỉ phép, ngày bắt đầu và ngày dự kiến quay lại.
• Thông báo Discord: Đẩy thông báo trạng thái nghỉ phép vào Redis memory queue. Zapier/Bot gom batch các message từ queue (tối đa 5 message / 5 giây) trước khi gửi tới Discord để tránh vi phạm rate-limit.

(Nguồn: Zapier Integration V7.pdf §Flow 13 line 1963; Supplement §3.4)

Path B — International Contractor Unpaid Hiatus

Bước B-1. Validation

• Không áp dụng giới hạn số ngày DTO. Tiếp tục ngay mà không kiểm tra số dư.

(Nguồn: Zapier Integration V7.pdf §Flow 13 line 1965)

Bước B-2. Tạm ngưng Retainer Dots

• Retainer hằng tháng của International Contractor được quản lý bởi một cron job của Middleware (Node.js, chạy hằng tháng) gọi Dots payout API. Đây KHÔNG phải một bước Zapier và không thể tạm dừng qua Zapier.
• Bản thân Dots API không có endpoint "suspend retainer" native — Dots chỉ xử lý các yêu cầu payout riêng lẻ theo yêu cầu.
• Cơ chế: Middleware đặt một DB flag (ví dụ is_retainer_paused = TRUE) trên bản ghi Users của trader. Cron retainer hằng tháng kiểm tra flag này trước khi gọi Dots POST /payees và bỏ qua mọi bản ghi có flag được đặt.
• Tên field chính xác là quyết định triển khai của dev; yêu cầu nghiệp vụ là: không có khoản thanh toán retainer nào được gửi tới Dots trong khi trader đang tạm ngưng.
• Khi quay lại (Bước R-3), Middleware xóa flag (is_retainer_paused = FALSE) để tiếp tục thanh toán hằng tháng bình thường.

(Nguồn: Zapier Integration V7.pdf §Flow 13 lines 1966–1968; §Flow 6 line 1635 — "Update the recurring backend trigger for the new Dots monthly retainer"; khách hàng xác nhận 2026-08-21)

Bước B-3. Gia hạn Stagnation Deadline

• Cùng SQL update như Path A Bước A-3: gia hạn stagnation_deadline thêm Requested_Days.

(Nguồn: Zapier Integration V7.pdf §Flow 13 line 1969)

Bước B-3.5. Đóng toàn bộ vị thế đang mở

• Giống Path A Bước A-3.5: đóng toàn bộ lệnh / vị thế đang mở.
• Việc khóa tài khoản ở Bước B-4 chỉ được thực thi sau khi tài khoản không còn vị thế đang mở.

(Nguồn: Zapier Integration V7.pdf §Flow 13 — "Disable Trading Account via Middleware (Lock)")

Bước B-4. Khóa tài khoản giao dịch

• Gọi POST /system/set-account-state:

  { "user_id": "[trader_id]", "state": "Locked", "context": "Hiatus" }

• Middleware gửi các lệnh khóa theo từng nền tảng sau khi xác nhận tài khoản đã flat (Bước B-3.5):
  • Rithmic: R|API+ Suspend Trading.
  • MT5: YourBourse Contest Stop Out Plugin API (POST) — đặt tài khoản ở chế độ Read-Only; đóng băng Target Profit / Stop Loss trong RAM.
  • TraderEvolution: Admin API — đặt tài khoản ở Lock/Read-Only.
• Ghi DB sau gateway (sau khi nhận HTTP 200 từ tất cả gateway đang hoạt động):
  • trader_status = 'On_Leave'
  • is_professional = TRUE (nếu trader dùng DMA)
  • stagnation_deadline đã được cập nhật ở Bước B-3

(Nguồn: Zapier Integration V7.pdf §Flow 13 line 1970; Supplement §3.2)

Bước B-5. Thông báo cho trader

• Gửi email DTO_Approval_Notice qua AWS SES.
• Thông báo Discord: Đẩy thông báo trạng thái nghỉ phép vào Redis memory queue. Zapier/Bot gom batch (tối đa 5 message / 5 giây) trước khi gửi tới Discord.

(Nguồn: Zapier Integration V7.pdf §Flow 13 line 1972; Supplement §3.4)

Return Protocol (áp dụng cho cả hai Path)

Trigger: Zap Flow 13 gốc (chính Zap đã xử lý việc duyệt nghỉ phép) tiếp tục thực thi thông qua action delay_until của Zapier được đặt theo DTO/Hiatus End Date — Path A: ngày kết thúc nghỉ từ payload webhook Rippling; Path B: End Date từ form Dashboard. Đây KHÔNG phải một backend cron job riêng — Zap tạm dừng giữa chừng tại thời điểm duyệt nghỉ phép và tự động tiếp tục vào ngày kết thúc đã chỉ định.

(Nguồn: Zapier Integration V7.pdf §Flow 13; khách hàng xác nhận 2026-08-22)

Mô hình sở hữu:

• Zapier chịu trách nhiệm: timer delay_until, điều khiển luồng và trình tự các bước sau khi tiếp tục, logic kiểm tra flag/database, và điều hướng thông báo DTO_Welcome_Back.
• Middleware chịu trách nhiệm: thực thi Safety Check (truy vấn bảng Users và blacklist trong PostgreSQL), gọi POST /system/set-account-state khi vượt qua check sạch, đẩy lệnh Restore Trading trực tiếp tới broker server (Rithmic / MT5 / TraderEvolution), và tiếp tục trigger retainer Dots (Path B).

Bước R-1. Safety Check

• Middleware truy vấn PostgreSQL theo user_id. Compliance_Flagged không phải là một field được lưu trữ — nó được đánh giá từ dữ liệu sẵn có:
  • NẾU bất kỳ điều kiện nào sau đây đúng:
    1. Email của user có một dòng khớp trong bảng blacklist (blacklist.email = Users.email AND blacklist.is_active = TRUE — cùng cách kiểm tra như UC_2.6.2 Blacklist Check);
    2. Users.status ∈ {Banned_Chargeback, Failed, Terminated};
    3. Users.payout_status ≠ 'Approved' (ví dụ Hold / Flagged được đặt bởi BPS Apply Payout Hold, webhook payout-profile của Dots, hoặc dispute hold của trader Live ở Flow 14).
    • DỪNG toàn bộ việc kích hoạt lại. KHÔNG mở khóa tài khoản giao dịch. KHÔNG tiếp tục thanh toán.
    • Gửi cảnh báo Slack ngay lập tức cho Head of Ops để review thủ công.
    • Kết thúc luồng.
  • NGƯỢC LẠI: Tiếp tục sang Bước R-2.

(Nguồn: Zapier Integration V7.pdf §Flow 13 lines 1974–1977; khách hàng xác nhận 2026-08-22; QnA_BACKGROUND_MECHANISMS_CRON.md [BG-005] [BG-006] [BG-007] — bảng tính khách hàng 2026-11-04; schema blacklist theo UC_2.6.2 / CHR-17)

Bước R-2. Kích hoạt lại tài khoản giao dịch

• Middleware gọi POST /system/set-account-state:

  { "user_id": "[trader_id]", "state": "Active", "context": "DTO_Return" }

• Middleware đọc Current_Level hiện tại của trader từ PostgreSQL tại thời điểm này (không phải level tại thời điểm duyệt nghỉ phép — việc bị hạ cấp trong thời gian nghỉ được phản ánh tại đây).
• Sau đó Middleware đẩy lệnh Restore Trading tới nền tảng thực thi của broker với các tham số rủi ro tương ứng với level hiện tại của trader: Rithmic 'Enable Trading' / MT5 'Enable' / TraderEvolution tương đương — bao gồm Notional, Daily Loss Limit và Level Stop chính xác cho Current_Level tại thời điểm quay lại.

(Nguồn: Zapier Integration V7.pdf §Flow 13 line 1978; khách hàng xác nhận 2026-08-22, 2026-09-09)

Bước R-3. Tiếp tục Retainer (chỉ Path B)

• Middleware tiếp tục trigger payout retainer Dots định kỳ đã lên lịch (xóa is_retainer_paused = FALSE).
• Flow 36 (Retainer Execution — Ledger Sync) kích hoạt ở chu kỳ thanh toán retainer kế tiếp và ghi bút toán Sổ cái Bất biến (Immutable Ledger).
• Nếu trader bị hạ cấp trong thời gian nghỉ: retainer tiếp tục theo mức retainer tương ứng với Current_Level hiện tại (thấp hơn) của họ, không phải level tại thời điểm duyệt nghỉ phép.

(Nguồn: Zapier Integration V7.pdf §Flow 13 line 1980; khách hàng xác nhận 2026-08-22, 2026-09-09)

Bước R-4. Thông báo cho trader

• Gửi mail DTO_Welcome_Back qua AWS SES.

(Nguồn: Zapier Integration V7.pdf §Flow 13 line 1982)

4.1 Trường hợp đặc biệt: Xử lý Pod Leader & Founding Mentor (Level 7+)

Mục này điều chỉnh mọi hành vi trường hợp đặc biệt chỉ áp dụng khi Trader có is_pod_leader = TRUE hoặc role_flag = 'Founding_Mentor'.

4.1.1 Failsafe Anti-Termination Gate

Trước khi thực thi bất kỳ hành động nghỉ phép nào (Bước A-1/B-1), Middleware PHẢI kiểm tra role flag:

IF users.is_pod_leader = TRUE OR users.role_flag = 'Founding_Mentor':
  → MUST block: do NOT fire POD_LEADER_TERMINATED webhook
  → MUST NOT invoke Flow 15C (offboarding cascade)
  → Proceed with leave processing (soft-lock, stagnation extension, etc.)
ELSE:
  → Standard Trader flow

Các hành động bị chặn trong thời gian nghỉ (áp dụng cho cả hai trigger):

• Webhook POD_LEADER_TERMINATED: không bao giờ được kích hoạt
• Flow 15C (giải thể Pod, tịch thu carry, offboarding Discord/Workspace): không bao giờ được gọi
• Việc zero hóa Pending_Carry_Balance: không bao giờ được thực thi
• Xóa/tạm ngưng Google Workspace: không bao giờ được kích hoạt
• Lưu trữ kênh Discord / thu hồi Role: không bao giờ được kích hoạt

(Nguồn: QnA_STAGE6_POD_SYSTEM_FLOW10_11.md [POD-XF-15] — khách hàng xác nhận 2026-10-30: nghỉ phép đã duyệt là nghỉ tạm thời, KHÔNG phải Drawdown Defense (Flow 4B) hay Termination (Flow 15C))

4.1.2 Tài nguyên được giữ nguyên trong On_Leave

Lưu ý về Founding Mentor: theo BR_9.2.19 và quy tắc Defense Bypass, tài khoản giao dịch của họ VẪN bị khóa trong On_Leave — ngoại lệ Founding Mentor chỉ bao phủ Administrative Roles (Pod/Discord), không bao phủ việc khóa tài khoản giao dịch.

(Nguồn: QnA_STAGE6_POD_SYSTEM_FLOW10_11.md [POD-XF-15], [POD-XF-16] — khách hàng xác nhận 2026-10-30; RFQ_ Stack Trading Prop Tech V7.pdf §Founding Mentor Defense Bypass)

4.1.3 Hành vi của Carry Balance

Pending_Carry_Balance tiếp tục tích lũy và vest bình thường trong thời gian nghỉ phép đã được duyệt. Lần chạy vest hằng tháng (Flow 17, ngày 1 hằng tháng) PHẢI bao gồm các Pod Leader có Pod_Leader_Registry.Status = 'On_Leave' — không đóng băng, không bỏ qua. Áp dụng như nhau cho Pod Leader thông thường và Founding Mentor. Carry chỉ bị đóng băng hoặc tịch thu khi bị tạm ngưng do Drawdown Defense hoặc Termination (Flow 15C).

Các khoản thanh toán khác trong thời gian nghỉ: lương cơ bản W-2 (Path A) tiếp tục qua payroll Rippling; retainer International (Path B) bị tạm ngưng (Bước B-2) và được tiếp tục ở R-3; các khoản payout hiệu suất giao dịch (Flow 5) đạt được trước kỳ nghỉ được xử lý bình thường — không thể đạt target mới trong khi tài khoản đang bị khóa.

(Nguồn: QnA_BACKGROUND_MECHANISMS_CRON.md [BG-008] [BG-009]; QnA_STAGE6_POD_SYSTEM_FLOW10_11.md [POD-XF-18] — bảng tính khách hàng 2026-11-04)

4.1.4 Pod_Leader_Registry Status trong thời gian nghỉ

• Tại Bước A-4 / B-4 (sau khi khóa gateway thành công), Middleware đặt Pod_Leader_Registry.Status = 'On_Leave' cho leader.
• Việc ghép cặp ở Flow 10 chỉ chọn Status == 'Active' [POD-JOIN-19] → leader ở On_Leave tự động bị loại khỏi việc ghép mentee mới. Việc này KHÔNG kích hoạt logic giải thể pod Suspended của Flow 15A.
• Tại Bước R-2 của Return Protocol (khi kích hoạt lại thành công), Middleware đặt Pod_Leader_Registry.Status = 'Active'.

(Nguồn: QnA_STAGE6_POD_SYSTEM_FLOW10_11.md [POD-XF-16] — khách hàng xác nhận 2026-10-30)

4.1.5 SLA của Pod trong thời gian nghỉ

Các timer SLA của Pod được tạm dừng trong khi leader đang nghỉ — không có Acting Cover, không ghép lại mentee:

• Cron SLA Enforcement của Flow 10.2 loại trừ các user ở Inactive_Hold (Flow 12) hoặc bị Locked do DTO/Hiatus (Flow 13) [POD-SLA-08].
• Daily Engagement Audit của Flow 10.5 loại trừ các leader bị Locked do DTO/Hiatus [POD-AUDIT-10].
• Calendar Compliance Auditor của Flow 10.1B: leader đang DTO/Hiatus được miễn [POD-DISP-08].

(Nguồn: QnA_STAGE6_POD_SYSTEM_FLOW10_11.md [POD-XF-17] — khách hàng xác nhận 2026-10-30)

5. Điều kiện tiên quyết

6. Hậu điều kiện

7. Luồng thay thế

Alt-1 — Số dư DTO đã hết (Path A):

• Được xử lý hoàn toàn bên trong Rippling (policy Rippling do Ops cấu hình theo DTO_Days, Table A/B). Yêu cầu bị từ chối không bao giờ tạo webhook Time Off Request Approved — Flow 13 không được kích hoạt. Xem Q-1.

Alt-3 — Lần nghỉ phép thứ hai được duyệt trong Rippling khi trader đang nghỉ (Path A):

• Mỗi webhook duyệt bổ sung của Rippling (Rippling Request ID mới) gia hạn stagnation_deadline thêm số ngày vừa được duyệt và cập nhật DTO_Hiatus_End_Date.
• Việc gọi lại POST /system/set-account-state với state = "Locked" là idempotent (chống trùng lặp) — tài khoản đã bị khóa, không tạo flag lồng nhau hoặc khóa trùng lặp.
• Việc thực thi hạn mức là trách nhiệm của Rippling (Stack Trading không kiểm tra lại số dư).

Alt-4 — Yêu cầu tạm ngưng thứ hai được gửi khi trader đang nghỉ (Path B):

• Không có giới hạn ngày cho International Contractor. Luôn duyệt — gia hạn stagnation_deadline thêm Requested_Days bổ sung. Việc tạm ngưng lại retainer Dots (is_retainer_paused = TRUE) là idempotent — flag đã được đặt, không thay đổi.
• Return Protocol (Zapier delay_until) theo dõi DTO_Hiatus_End_Date đã cập nhật. Chỉ có một lần thực thi Return Protocol vào ngày kết thúc đã gia hạn cuối cùng.

(Nguồn: Zapier Integration V7.pdf pp. 21, 228-230, 392-394; khách hàng xác nhận 2026-09-09)

Alt-2 — Ngày quay lại của trader đến trong khi các flag Safety Check đang được đặt:

• Flow tự động kích hoạt Return Protocol vào ngày kết thúc đã lên lịch.
• Safety Check phát hiện flag → HALT. Tài khoản vẫn Locked vô thời hạn cho đến khi Ops giải quyết thủ công và kích hoạt lại.
• Đường kích hoạt lại thủ công: Ops gọi POST /system/set-account-state với state = "Active" sau khi giải quyết vấn đề compliance/chargeback — phải được thực thi qua BPS Admin Console (áp dụng cổng RBAC Level_2+/Admin, bắt buộc có reason + transcript_url, ghi log vào BPS_Audit_Log). Bản thân endpoint không có gate; Console là điểm thực thi RBAC (xem BR_9.2.12). (Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §BPS Endpoints lines 2721–2867; khách hàng xác nhận 2026-08-27)

Alt-5 — Trader W-2 hủy hoặc rút ngắn PTO đã duyệt trong Rippling (Path A):

• Không tự động tính lại. Gửi cảnh báo Slack tới #ops-general (hoặc tạo ticket Freshdesk) để Ops kiểm tra thủ công, kích hoạt lại tài khoản giao dịch và điều chỉnh stagnation_deadline nếu cần.
• Không có bút toán ledger điều chỉnh (Flow 35).
• Nếu PTO bị hủy trước leave_start_date, Zap đang chờ (Bước A-1.5) vẫn sẽ khóa tài khoản vào ngày đó — Ops phải hủy lượt Zap đang chờ hoặc mở khóa tài khoản thủ công.

(Nguồn: QnA_BACKGROUND_MECHANISMS_CRON.md [BG-002], [BG-017] — bảng tính khách hàng 2026-11-04)

8. Luồng ngoại lệ

Exc-1 — Webhook Rippling không qua cổng vào / guard (Path A, Bước A-1):

• Worker không thể ánh xạ sang user_id, Current_Level < 6, hoặc Employment_Type != 'W-2'.
• Không gia hạn stagnation_deadline; không khóa. Ghi log vào BPS_Audit_Log để Ops review. Không thông báo cho trader.

Exc-2 — Webhook Rippling đến sau ngày bắt đầu nghỉ (Path A):

• Trường hợp 1 — Hôm nay nằm giữa leave_start_date và leave_end_date: khóa ngay cho phần còn lại của kỳ nghỉ; gia hạn stagnation_deadline thêm đủ Requested_Days đã duyệt; gửi thông báo Slack thường lệ tới #ops-general ghi nhận việc duyệt muộn.
• Trường hợp 2 — Hôm nay đã qua leave_end_date: KHÔNG khóa; Flow 35 vẫn ghi PTO vào ledger; gia hạn stagnation_deadline thêm số ngày đã duyệt; gửi thông báo Slack thường lệ tới #ops-general. Không lên lịch Return Protocol.

(Nguồn: QnA_BACKGROUND_MECHANISMS_CRON.md [BG-003] — bảng tính khách hàng 2026-11-04)

Exc-3 — Lời gọi POST /system/set-account-state thất bại HOẶC execution gateway API trả về lỗi/timeout:

• Tài khoản giao dịch KHÔNG bị khóa như mong đợi. Rủi ro cao: trader có thể tiếp tục giao dịch trong thời gian nghỉ.
• Xử lý lỗi gateway: Middleware retry tối đa 3 lần với exponential backoff. Nếu hết retry → ghi log vào BPS_Audit_Log + gửi cảnh báo Slack SEV-1 tới Ops (#ops-it) để khóa thủ công. (Nguồn: Zapier Integration V7.pdf §Flow 13)

Exc-4 — Việc gửi cảnh báo Safety Check thất bại (thông báo Head of Ops):

• Bản thân quyết định HALT vẫn có hiệu lực — không kích hoạt lại tài khoản trong mọi trường hợp.
• Ghi log lỗi gửi cảnh báo. Điều hướng sang kênh cảnh báo phụ (ví dụ: ticket Freshdesk, email dự phòng).

Exc-5 — Trader có Luồng 14 (Payment Dispute / Chargeback) đang hoạt động trong khi nghỉ phép:

• Nếu một dispute được tạo khi trader_status = 'On_Leave', trạng thái dispute có mức ưu tiên cao hơn On_Leave: trader SIM → Users.status = 'Banned_Chargeback'; trader Live → dispute hold đặt Users.payout_status ≠ 'Approved'.
• Tài khoản KHÔNG ĐƯỢC tự động kích hoạt lại vào Return_Date đã lên lịch cho đến khi Admin giải quyết dispute thủ công.
• Safety Check (Bước R-1) bắt cả hai trường hợp (điều kiện 2 và 3) và dừng việc quay lại — ngoại lệ này ghi lại kịch bản dispute phát sinh giữa kỳ nghỉ để việc thiết lập dữ liệu test được rõ ràng.

(Nguồn: QnA_BACKGROUND_MECHANISMS_CRON.md [BG-005] [BG-006] — bảng tính khách hàng 2026-11-04)

9. Quy tắc nghiệp vụ

10. Tiêu chí chấp nhận

10.1 Câu hỏi mở (CR-20261027-001)

11. Lịch sử thay đổi

UC_9.3 — Luồng 18: Sao lưu Cơ sở dữ liệu Cấu hình & Đồng bộ Khôi phục Thảm họa

Danh mục UC

<a id="UC_9.3"></a>

UC_9.3 — Luồng 18: Sao lưu Cơ sở dữ liệu Cấu hình & Đồng bộ Khôi phục Thảm họa

1. Tổng quan

2. Trigger

Lịch chạy: Cron job theo lịch, hằng ngày lúc 02:00 UTC — cố định theo UTC, không dịch chuyển theo Giờ mùa hè (DST). Mọi lịch cron backend trong toàn hệ thống đều chạy theo UTC cố định.

(Nguồn: QnA_BACKGROUND_MECHANISMS_CRON.md [BG-011] — bảng tính của khách hàng 2026-11-04; ghi đè Zapier Integration V7.pdf §Flow 18 line 2101 "Daily at 02:00 AM CST")

3. Luồng cơ bản

Bước 1 — Export Zapier Tables

• Export toàn bộ các bảng cấu hình: Tables A đến F, cùng các bảng mới được thêm phát hiện tại runtime.
• Định dạng export: JSON, với hai trường metadata bắt buộc được nhúng trong mọi file export:

(Nguồn: Zapier Integration V7.pdf §Flow 18 lines 2102–2108)

Bước 2 — Upload lên S3

• Upload file export JSON lên S3 bucket riêng.
• Quy ước đặt tên: config_backup_YYMMDD_HHMMSS.json
• Bucket dùng chung: Flow 18 dùng cùng S3 bucket và prefix với Flow 40 (Zapier DR Recovery Snapshot). Cả hai luồng dùng chung cấu hình bảo mật và lifecycle.

S3 bucket PHẢI được cấu hình với các thuộc tính sau:

Quy tắc lifecycle (Hot / Cold):

• Không dùng script tùy biến nén thư mục theo tuần/tháng — cron hằng ngày chỉ upload file JSON; việc phân tầng và hết hạn do S3 Lifecycle Rule đảm nhiệm.
• Bản sao lưu cấu hình là điểm khôi phục, không phải audit log — quy tắc "2 years immediately accessible" của RFQ V7 §5.0 (áp dụng cho trading archive) không áp dụng ở đây.
• ⚠️ Thời hạn lưu giữ của Object Lock không được vượt quá 1,856 ngày, nếu không quy tắc hết hạn sẽ không thể xóa object.

(Nguồn: Zapier Integration V7.pdf §Flow 18 lines 2109–2116; §Flow 40 line 2652; QnA_BACKGROUND_MECHANISMS_CRON.md [BG-010] — bảng tính của khách hàng 2026-11-04)

Bước 3 — Xác minh sao lưu độc lập

Một bước xác minh tự động độc lập chạy ngay sau khi upload:

1. Tải xuống file JSON vừa upload từ S3.
2. Tính lại checksum SHA-256 của file đã tải xuống và so sánh với checksum đã tính lúc export.
   • Khớp → file toàn vẹn. Tiếp tục.
   • Không khớp → xác minh thất bại (→ Bước 4, nhánh thất bại).
3. Test-parse nội dung file theo cấu trúc JSON kỳ vọng.
   • Parse thành công → xác minh đạt. Luồng kết thúc thành công.
   • Parse thất bại → xác minh thất bại (→ Bước 4, nhánh thất bại).

(Nguồn: Zapier Integration V7.pdf §Flow 18 lines 2117–2119)

Bước 4 — Xử lý lỗi: Retry, sau đó Cảnh báo

• Nếu sao lưu (Bước 1–2) hoặc xác minh (Bước 3) thất bại, job tự động retry tối đa 3 lần với exponential backoff.
• Nếu vẫn thất bại sau lần retry thứ 3 → gửi cảnh báo Slack tới #ops-dev chứa bước thất bại và lỗi cụ thể (ví dụ: lỗi xác thực KMS, S3 upload timeout, checksum mismatch, lỗi JSON parse).

Kênh cảnh báo: chỉ Slack #ops-dev — theo danh mục kênh Slack (CR-15.2, slack_channel_usage.md): "Config DB Backup success/failure notifications". Không tạo ticket Freshdesk.

(Nguồn: Zapier Integration V7.pdf §Flow 18 lines 2120–2121; CR-15.2; Flow 18 spec 2026-10-28)

4. Điều kiện tiên quyết

5. Hậu điều kiện

6. Luồng ngoại lệ

Exc-1 — Upload S3 thất bại (network timeout, permission denied, KMS key không khả dụng):

• Retry tối đa 3 lần với exponential backoff (Bước 4).
• Tất cả các lần retry đều thất bại → bản sao lưu không được lưu; cảnh báo thất bại Slack được gửi kèm mã lỗi.

Exc-2 — Checksum mismatch sau khi upload:

• File nằm trên S3 nhưng không thể tin cậy là điểm restore hợp lệ.
• Retry tối đa 3 lần (Bước 4). Nếu vẫn không khớp → cảnh báo thất bại Slack kèm chi tiết "checksum mismatch".
• File KHÔNG bị xóa (Object Lock ngăn việc này) — S3 versioning giữ sẵn phiên bản sạch trước đó.

⚠️ [MỞ — Exc-2] Nguồn không quy định file chưa được xác minh có được gắn tag trong S3 metadata hay không. BA cần xác nhận có nên áp dụng tag corrupt=true cho S3 object hay không.

Exc-3 — JSON parse thất bại:

• File có thể bị cắt cụt hoặc gặp vấn đề encoding.
• Hành vi retry và bảo toàn file giống Exc-2; chi tiết cảnh báo "JSON parse error".

Exc-4 — Đọc Zapier Table thất bại (một hoặc nhiều bảng không khả dụng):

• Có thể sinh ra bản export một phần.
• Bản sao lưu một phần có thể âm thầm tạo ra điểm restore không đầy đủ.

⚠️ [MỞ — Exc-4] Nguồn không quy định bản export một phần được upload hay toàn bộ job bị hủy khi một bảng lỗi. BA cần xác nhận: abort-all hay upload-partial-with-error-flag.

Exc-5 — Gửi cảnh báo Slack thất bại:

• Kết quả sao lưu không bị ảnh hưởng, nhưng Ops không có khả năng quan sát.
• Không có kênh dự phòng — cảnh báo chỉ qua Slack. Việc gửi thất bại được ghi log phía server.

7. Quy tắc nghiệp vụ

8. Yêu cầu phi chức năng

9. Tiêu chí chấp nhận

10. Lịch sử cập nhật

UC_9.8 — Luồng 30: Cảnh báo Công suất MID

Danh mục UC

<a id="UC_9.8"></a>

UC_9.8 — Luồng 30: Cảnh báo Công suất MID

1. Tổng quan

2. Trigger

Loại: Nội bộ — được Middleware Hub kích hoạt theo chương trình ngay sau khi Process Payment Webhook cập nhật thành công current_mtd_volume trong cơ sở dữ liệu.

Điều kiện trigger: Mỗi giao dịch thanh toán thành công từ bất kỳ gateway nào (NMI, Triple-A, Nomupay, EBANX, Dusupay, Skrill) và mỗi lần refund đều dẫn đến một lệnh gọi POST /merchant/check-capacity cho MID được dùng.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Check MID Capacity lines 1455–1459; §Process Payment Webhook lines 1339–1346)

3. Luồng cơ bản

Bước 1 — Cập nhật khối lượng (upstream — Process Payment Webhook)

Sau một giao dịch thanh toán thành công, Process Payment Webhook cập nhật tổng lũy kế của MID trong Merchant_Routing_Config:

current_mtd_volume = current_mtd_volume + transaction_amount

Khi refund, tổng chạy của MID bị trừ và không bao giờ xuống dưới 0 (ví dụ refund giao dịch của tháng trước ngay sau khi reset ngày 1):

current_mtd_volume = GREATEST(0, current_mtd_volume - refund_amount)

current_mtd_volume chỉ là bộ đếm month-to-date nội bộ dùng để cân tải — không phải số dư tài khoản ngân hàng merchant. Bản thân refund vẫn được NMI xử lý bình thường kể cả khi current_mtd_volume = 0.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Process Payment Webhook line 1345; QnA_BACKGROUND_MECHANISMS_CRON.md [BG-024] — khách trả lời 2026-11-03)

Bước 2 — Kiểm tra công suất (POST /merchant/check-capacity)

Ngay sau khi cập nhật DB, Middleware gọi nội bộ POST /merchant/check-capacity.

Input payload:

{
  "merchant_name": "<MID identifier>",
  "current_mtd_volume": <updated value>
}

Logic đánh giá:

ratio = current_mtd_volume / monthly_limit

IF ratio >= 0.80 AND warning_80_fired = FALSE:
  → SET warning_80_fired = TRUE
  → FIRE webhook
ELSE IF ratio < 0.80 AND warning_80_fired = TRUE:
  → SET warning_80_fired = FALSE   (no Slack alert)
ELSE:
  → No action. Return HTTP 200.

Cờ warning_80_fired giúp cảnh báo 80% chỉ bắn một lần cho mỗi lần vượt ngưỡng: khi cờ đang được đặt, các giao dịch tiếp theo trên cùng MID không kích hoạt lại luồng, kể cả khi ratio tăng vượt 90% hoặc 100%. Nếu volume tụt lại dưới 80% (do refund, hoặc do monthly_limit được nâng), cờ được xóa và lần vượt ngưỡng kế tiếp sẽ bắn cảnh báo mới. Không xây DB trigger hay watcher riêng — toàn bộ xử lý nằm trong bước kiểm tra này.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Check MID Capacity lines 1456–1459; QnA_BACKGROUND_MECHANISMS_CRON.md [BG-025] — khách trả lời 2026-11-03)

Response: HTTP 200 OK trong mọi trường hợp (bắn hoặc không bắn).

Bước 3 — Cảnh báo Slack

Gửi tin nhắn Slack tới kênh Operations (#ops-treasury hoặc kênh Ops được cấu hình).

Nội dung tin nhắn Slack:

⚠️ [WARN] MID VOLUME CAPACITY ALERT
MID [merchant_name] has reached [ratio]% of its monthly processing limit.
Current MTD Volume: $[current_mtd_volume]
Monthly Limit: $[monthly_limit]
Action Required: Contact processor to request limit increase, or adjust
Weighted Round-Robin weights in Merchant_Routing_Config to offload traffic.

(Nguồn: Zapier Integration V7.pdf §Flow 30 lines 2466–2469)

4. Mô hình dữ liệu

Bảng Merchant_Routing_Config (PostgreSQL)

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Merchant_Routing_Config lines 847–855; §Alerting line 3273; client confirmed 2026-09-18)

5. Tham chiếu API

Input:

Output: HTTP 200 OK (không cần body — chỉ có side effect)

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Check MID Capacity lines 1455–1459)

6. Luồng ngoại lệ

Exc-1 — warning_80_fired đã là TRUE (chặn trùng lặp):

• Không bắn webhook. Trả về HTTP 200 âm thầm.
• Đây là hành vi mong đợi — cờ được reset bởi cron ngày 1 hằng tháng, hoặc bởi lần kiểm tra công suất kế tiếp khi volume dưới 80% (xem §7).

Exc-2 — monthly_limit của MID là NULL hoặc bằng 0:

Middleware PHẢI áp dụng guard clause: nếu monthly_limit IS NULL OR monthly_limit = 0, bỏ qua phép tính công suất 80% cho MID đó, ghi log cảnh báo phía server với mã NULL_OR_ZERO_MONTHLY_LIMIT_WARNING, và trả về HTTP 200 (không ném exception 500). Ngoài ra, Middleware PHẢI gửi một cảnh báo Ops chủ động tới kênh Slack #ops-treasury với nội dung:

⚠️ Configuration Error: MID [merchant_name] has an active status but a zero or null monthly limit.

Lý do: monthly_limit NULL hoặc bằng 0 trên một MID đang active là lỗi cấu hình nghiêm trọng — phải chuyển cho đội Ops để sửa DB ngay. Đây là cảnh báo cấu hình nội bộ và KHÔNG ĐƯỢC chuyển tới Freshdesk.

(Nguồn: client confirmed 2026-09-18)

Exc-3 — Gửi webhook thất bại:

Khi Middleware bắn webhook cảnh báo công suất và nhận response khác 200 hoặc timeout:

Giai đoạn 1 — Retry: Middleware thực hiện 3 lần retry tự động với exponential backoff.

Giai đoạn 2 — Fallback (đã dùng hết 3 lần retry): Middleware đẩy cảnh báo fallback trực tiếp tới #dev_ops qua lệnh gọi native Slack API webhook.

(Nguồn: client confirmed 2026-09-18)

7. Quy tắc nghiệp vụ

8. Tiêu chí chấp nhận

9. Lịch sử thay đổi

UC_9.9 — Luồng 31: Giám sát Cạn kiệt Tổng hợp (Sev-1)

Danh mục UC

<a id="UC_9.9"></a>

UC_9.9 — Luồng 31: Giám sát Cạn kiệt Tổng hợp (Sev-1)

1. Tổng quan

2. Trigger

Loại: Theo lịch — Zapier Cron Job.

Lịch chạy: Hằng ngày lúc 11:00 PM CST.

(Nguồn: Zapier Integration V7.pdf §Flow 31 line 2473)

3. Luồng cơ bản

Bước 1 — Trigger theo lịch (Zapier)

Scheduler tích hợp sẵn của Zapier kích hoạt lúc 11:00 PM CST hằng ngày và gọi GET /calculate-volume-pacing trên Middleware.

(Nguồn: Zapier Integration V7.pdf §Flow 31 lines 2473–2474)

Bước 2 — Tính toán pacing (GET /calculate-volume-pacing)

Middleware thực thi thuật toán sau trên Merchant_Routing_Config:

2a. Tổng hợp (chỉ MID active):

SELECT
  SUM(current_mtd_volume) AS total_mtd_volume,
  SUM(monthly_limit)      AS total_aggregate_capacity
FROM merchant_routing_config
WHERE is_active = TRUE;

2b. Tính Khối lượng trung bình ngày (ADV):

N = current day of month (e.g. 15)
ADV = total_mtd_volume / N

2c. Dự phóng khối lượng cuối tháng:

T = total days in current calendar month (e.g. 30 for September)
Projected_EOM_Volume = ADV × T

2d. Kiểm tra cạn kiệt:

IF Projected_EOM_Volume >= total_aggregate_capacity:
  projected_exhaustion = true
ELSE:
  projected_exhaustion = false

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Calculate Volume Pacing lines 1460–1464; Zapier Integration V7.pdf §Flow 31 lines 2474–2475)

Bước 3 — Zapier Filter

Zapier đánh giá response. Chỉ tiếp tục nếu projected_exhaustion = true. Nếu false, luồng kết thúc âm thầm — không gửi tin nhắn Slack.

(Nguồn: Zapier Integration V7.pdf §Flow 31 line 2475)

Bước 4 — Cảnh báo Slack SEV-1

Nếu projected_exhaustion = true, gửi cảnh báo SEV-1 CRITICAL tới #ops-treasury (hoặc kênh Operations được cấu hình).

Nội dung tin nhắn Slack:

🚨 [SEV-1 CRITICAL] AGGREGATE VOLUME PACING EXHAUSTION DETECTED
Current Day: [current_day_of_month] / [total_days_in_month]
Total MTD Volume: $[total_mtd_volume]
Average Daily Volume: $[average_daily_volume]/day
Projected EOM Volume: $[projected_eom_volume]
Total Aggregate Capacity: $[total_aggregate_capacity]

CRITICAL: Aggregate pacing indicates all merchant accounts will exhaust
capacity before month end. Immediate intervention required.

(Nguồn: Zapier Integration V7.pdf §Flow 31 lines 2476–2479)

4. API Endpoint

GET /calculate-volume-pacing

Response payload (đường đi bình thường):

{
  "calculation_date": "2026-09-03",
  "current_day_of_month": 3,
  "total_days_in_month": 30,
  "total_mtd_volume": 45000.00,
  "total_aggregate_capacity": 450000.00,
  "average_daily_volume": 15000.00,
  "projected_eom_volume": 450000.00,
  "projected_exhaustion": true,
  "active_mids_count": 4
}

Response payload (Edge Case 2 — không có MID active):

{
  "projected_exhaustion": false,
  "total_aggregate_capacity": 0,
  "active_mids_count": 0,
  "status_code": "NO_ACTIVE_MIDS_WARNING",
  "message": "All payment MIDs are currently inactive. Ops Config Warning dispatched."
}

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Calculate Volume Pacing lines 1460–1464)

5. Cổng an toàn & Trường hợp biên

Edge Case 1 — Chặn nhiễu đầu tháng (thời gian ân hạn 3 ngày dương lịch)

Vào ngày 1 hằng tháng, các giá trị current_mtd_volume vừa được reset về 0.00. ADV sẽ gần bằng 0 và Projected_EOM_Volume sẽ ở mức tối thiểu — phép toán tự nhiên chặn các false positive. Tuy nhiên, vài ngày đầu tháng có thể cho ra dự phóng gây hiểu lầm do mẫu số ADV có ít dữ liệu.

Hành vi đã xác nhận (thời gian ân hạn 3 ngày dương lịch — Option B):

Trong 3 ngày dương lịch đầu tiên của mỗi tháng (ngày 1, 2, 3), Middleware PHẢI bỏ qua hoàn toàn các phép tính pacing của Flow 31 và trả về projected_exhaustion = false vô điều kiện. Từ ngày 4 trở đi, phép toán pacing tiêu chuẩn tiếp tục.

IF current_day_of_month <= 3:
  → return { projected_exhaustion: false }  // Grace period — skip pacing math
ELSE:
  → Execute standard ADV / Projected_EOM_Volume calculation

Lý do: Cổng dựa trên thời gian dễ dự đoán hơn ngưỡng khối lượng tối thiểu. Nó loại bỏ sự mơ hồ về việc một ngày khối lượng thấp là do chủ ý chặn hay do vấn đề cấu hình, và cho phép ngày 4 là điểm bắt đầu sạch của dữ liệu xu hướng đáng tin cậy.

(Nguồn: client confirmed 2026-09-18)

Edge Case 2 — Tất cả MID không active (total_aggregate_capacity = 0)

Nếu không có MID nào có is_active = TRUE, thì total_aggregate_capacity = 0. Nếu không có guard clause, sẽ xảy ra hai chế độ lỗi:

1. Chia cho 0 / NaN / Infinity khi tính tỷ lệ khối lượng.
2. SEV-1 dương tính giả (false-positive): Projected_EOM_Volume (≥ 0) >= 0 luôn là true → bắn một cảnh báo CRITICAL sai. Điều này mô tả sai sự cố thành cạn kiệt khối lượng trong khi nguyên nhân thực là vấn đề cấu hình/vô hiệu hóa gateway.

Hành vi đã xác nhận (Guard Clause — phía server):

Step 1: Query active MIDs
  activeMIDs = SELECT * FROM Merchant_Routing_Config WHERE is_active = TRUE

Step 2: Compute total_aggregate_capacity
  total_aggregate_capacity = SUM(activeMIDs.monthly_limit)

GUARD CLAUSE:
  IF activeMIDs.length = 0 OR total_aggregate_capacity = 0:
    → log WARN: "All payment MIDs inactive — suppressing SEV-1 exhaustion alert"
    → return { projected_exhaustion: false, status_code: "NO_ACTIVE_MIDS_WARNING",
               active_mids_count: 0, total_aggregate_capacity: 0 }
    → Middleware MUST additionally dispatch a separate Ops Config Warning
      to **`#ops-treasury`** (distinct from SEV-1, NOT routed to Freshdesk):
      "🚨 CRITICAL CONFIGURATION ERROR: All MIDs are currently marked inactive."

Step 3 onwards: Standard pacing math — only executes when active_mids_count > 0

Ma trận kịch bản cảnh báo:

(Nguồn: client confirmed 2026-09-17)

Edge Case 3 — Endpoint không khả dụng

Nếu GET /calculate-volume-pacing trả về khác 200 hoặc timeout, Flow 31 thực thi trình xử lý ngoại lệ hai giai đoạn:

Giai đoạn 1 — Tự động retry (backoff 3 lần): Zapier tự động retry 3 lần, mỗi lần cách nhau 5 phút (tổng cửa sổ: 15 phút). Tự phục hồi khi gặp lỗi mạng thoáng qua hoặc Middleware khởi động lại.

Giai đoạn 2 — Cảnh báo Slack SEV-2 (sau 3 lần retry thất bại): Nếu cả 3 lần retry thất bại, Zapier kích hoạt cảnh báo SEV-2 WARNING tới #ops-treasury và #dev_ops.

Nội dung tin nhắn SEV-2:

🟡 [SEV-2 WARNING] Volume Pacing Monitoring Endpoint Unavailable
• Event: Zapier Flow 31 failed to fetch MID volume pacing metrics.
• Target Endpoint: GET /calculate-volume-pacing
• Status: Failed after 3 retries (Non-200 / Timeout).
• Impact: Daily aggregate merchant capacity check was SKIPPED tonight.
• Action Required: @dev_ops please inspect Middleware Hub logs in AWS CloudWatch.

Phân nhánh lỗi của Flow 31:

Zapier Flow 31: GET /calculate-volume-pacing
         │
         ├─ HTTP 200 OK
         │    ├─ projected_exhaustion = true  → SEV-1 Slack Alert (#ops-treasury)
         │    └─ projected_exhaustion = false → Pass (no alert)
         │
         └─ Non-200 / Timeout
              └─ Auto-retry 3×, 5 min intervals
                   └─ Persistent fail (all 3 retries exhausted)
                        └─ SEV-2 Slack Alert (#ops-treasury + #dev_ops)

(Nguồn: client confirmed 2026-09-17)

6. Quy tắc nghiệp vụ

7. Mối quan hệ với UC_9.8 (Flow 30)

8. Tiêu chí chấp nhận

9. Câu hỏi mở

10. Lịch sử thay đổi

UC_9.11 — Luồng 34: Đồng bộ Sổ cái Lương Rippling

1. Danh mục UC

UC_9.11 — Luồng 34: Đồng bộ Sổ cái Lương Rippling

2. Trigger

Event: Rippling gửi webhook khi một kỳ lương hai tuần hoặc hàng tháng định kỳ theo lịch được cleared (tiền đã giải ngân).

Các kỳ lương off-cycle (thưởng hiệu suất Flow 5, severance Flow 9, vesting Pod Leader Flow 17 — đều qua Rippling Off-Cycle Payroll API) không được Luồng 34 xử lý, kể cả khi Rippling gửi cùng một webhook. Xem Alt-3.

(Nguồn: Zapier Integration V7.pdf §Flow 34; §7.2 Option A/B · StackTrading_Backend_Technical_Proposal_v1.6.docx §Option B provider list — Rippling được đánh dấu "—")

⚠️ Option B (POST /webhooks/payroll/rippling → POST /zapier/events/payroll_cleared) được mô tả trong Zapier Integration V7.pdf §7.2 nhưng không nằm trong phạm vi Option B đã được chấp thuận (8 provider: NMI, Triple-A, Skrill, Nomupay, EBANX, Dusupay, Veriff, Dots). Xem Q1.

3. Điều kiện tiên quyết

4. Hậu điều kiện

5. Luồng cơ bản

Bước 1 — Nhận webhook (Zapier)

Zapier catch hook nhận payload Rippling Payroll Run Cleared.

Bước 2 — Filter: chỉ trader W-2 đang hoạt động, chỉ kỳ lương định kỳ (Zapier)

• Ánh xạ Rippling worker sang trader_id.
• Chỉ tiếp tục nếu trader là trader W-2 đang hoạt động của Stack Trading (Employment_Type = 'W-2', tài khoản active).
• Chỉ tiếp tục nếu kỳ lương là kỳ lương định kỳ theo lịch (không phải off-cycle). Off-cycle → dừng (xem Alt-3).
• Ngược lại → dừng (xem Alt-2).
• ⚠️ Trường trong payload Rippling dùng để phân biệt kỳ lương định kỳ với kỳ lương off-cycle chưa có trong nguồn — Dev cần xác nhận với Rippling API.

(Nguồn: Zapier Integration V7.pdf §Flow 34 — "Ensure payload corresponds to an active Stack Trading W2 Trader Only"; QnA_BACKGROUND_MECHANISMS_CRON.md [BG-016] — bảng tính của khách hàng 2026-11-04)

Bước 3 — Kiểm tra dedup

Trước khi gọi sổ cái, kiểm tra provider_event_id (Rippling event / transaction ID) với dedup store. Nếu đã xử lý → Alt-1.

(Nguồn: Zapier Integration V7.pdf §7.2 Option A — "Store provider_event_id in DB to dedup (required for payroll/ledger events)")

Bước 4 — Gọi Middleware POST /api/ledger/record

(Nguồn: Zapier Integration V7.pdf §Flow 34)

Bước 5 — Middleware mint trên Polygon

1. Xác thực chữ ký Zapier JWT. Từ chối nếu không hợp lệ (Exc-1).
2. Khởi tạo Ethers.js wallet phía server bằng private key từ môi trường bảo mật.
3. Thực thi contract.recordMetric(_traderId, _metricCategory, _metricValue, _timestamp, _verificationHash) qua Alchemy RPC, với ánh xạ: trader_id → _traderId, metric_category → _metricCategory, metric_value → _metricValue, date → _timestamp, receipt_hash → _verificationHash.
4. Chờ block confirmation.
5. Ghi tx_hash vào PostgreSQL; log vào BPS_Audit_Log.
6. Trả về HTTP 200 { "status": "success", "tx_hash": "0x..." }.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Record Immutable Ledger; §3.6.1 Smart Contract Architecture)

Bước 6 — Kết thúc Zap.

6. Luồng thay thế

Alt-1 — Gửi trùng

• provider_event_id / receipt_hash đã được xử lý.
• Middleware không gọi lại recordMetric(); trả về HTTP 200 cùng tx_hash đã lưu trước đó.
• Không có event sổ cái thứ hai; không có dòng ticker thứ hai.

Alt-2 — Payload không phải trader W-2 đang hoạt động

• Filter thất bại (contractor, đã chấm dứt, worker không xác định, nhân viên không phải trader).
• Zap dừng ở Bước 2. Không gọi sổ cái. Không có lỗi.

Alt-3 — Rippling báo một kỳ lương off-cycle

• Zap dừng ở Bước 2. Không gọi sổ cái. Không có lỗi.
• Các khoản chi trả W-2 off-cycle đã được chính luồng của chúng ghi nhận qua POST /api/ledger/record: Flow 5 (Performance Bonus, Path C), Flow 9 (Severance, Path C), Flow 17 (Pod Leader Vesting, nhánh US W-2). Ghi lại lần nữa trong Luồng 34 sẽ tạo bản ghi on-chain trùng lặp.

(Nguồn: QnA_BACKGROUND_MECHANISMS_CRON.md [BG-016] — bảng tính của khách hàng 2026-11-04; Zapier Integration V7.pdf §Flow 5 Path C, §Flow 9 Path C; RFQ_ Stack Trading Prop Tech V7.pdf §Process Pod Vesting — Immutable Ledger Logging)

7. Luồng ngoại lệ

Exc-1 — Zapier JWT không hợp lệ / hết hạn

• Middleware trả về HTTP 401; không gọi contract; log vào BPS_Audit_Log với execution_status = REJECTED.

Exc-2 — Lỗi Polygon RPC / giao dịch

• recordMetric() thất bại hoặc không nhận được confirmation.
• Middleware trả về non-2xx; không ghi nhận là đã xử lý (để retry có thể mint).
• Áp dụng Zapier retry (xem Q3). Khi thất bại cuối cùng → cảnh báo Slack tới Ops (kênh theo slack_channel_usage.md, xem Q3).

Exc-3 — Không thể ánh xạ trader_id từ Rippling worker

• Xử lý như Alt-2 (dừng) và ghi log vào BPS_Audit_Log với giá trị UNMAPPED_RIPPLING_WORKER để xem xét thủ công. (Giả định của BA — xem Q4)

8. Quy tắc nghiệp vụ

BR_9.11.1: Phạm vi — Chỉ trader W-2 đang hoạt động

Luồng 34 chỉ ghi nhận lương cho trader W-2 đang hoạt động của Stack Trading. Contractor quốc tế được xử lý bởi Luồng 36 (UC_9.13).

(Nguồn: Zapier Integration V7.pdf §Flow 34)

BR_9.11.2: Ánh xạ sổ cái cố định

metric_category luôn là "W2 Payroll Executed". Định dạng metric_value là "$[Total_Amount] Base + Benefits Paid", số tiền định dạng 2 chữ số thập phân (ví dụ "$2,500.00 Base + Benefits Paid"). receipt_hash luôn là Rippling Transaction ID.

(Nguồn: Zapier Integration V7.pdf §Flow 34; QnA_BACKGROUND_MECHANISMS_CRON.md [BG-016])

BR_9.11.3: Một kỳ lương = Một event sổ cái (idempotency)

provider_event_id phải được lưu và kiểm tra trước khi mint. Các lần retry của Rippling không bao giờ được tạo ra event on-chain thứ hai. Bản trùng trả về HTTP 200 cùng tx_hash gốc.

(Nguồn: Zapier Integration V7.pdf §7.2 Option A)

BR_9.11.4: Ghi sổ cái chỉ dành cho Owner, chỉ dạng Event

Contract không lưu state; dữ liệu chỉ được ghi dưới dạng event log CorporateMetricVerified. Chỉ owner wallet mới được gọi recordMetric().

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §3.6.1)

BR_9.11.5: tx_hash được lưu trước khi trả response thành công

Middleware chỉ trả về thành công cho Zapier sau khi có block confirmation và sau khi tx_hash được ghi vào PostgreSQL.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Record Immutable Ledger — "Await confirmation and write the Polygon transaction hash to PostgreSQL")

BR_9.11.6: Luồng 34 chỉ ghi lương định kỳ — Các khoản chi trả off-cycle do chính luồng của chúng ghi nhận

Luồng 34 chỉ ghi nhận lương W-2 định kỳ theo lịch (lương cơ bản, phúc lợi). Các khoản chi trả W-2 off-cycle được ghi nhận bởi luồng kích hoạt chúng, qua POST /api/ledger/record: Flow 5 (Performance Bonus), Flow 9 (Severance), Flow 17 (Pod Leader Vesting). Luồng 34 lọc bỏ các kỳ lương off-cycle để mỗi khoản thanh toán tạo ra đúng một bản ghi sổ cái.

(Nguồn: QnA_BACKGROUND_MECHANISMS_CRON.md [BG-016] — bảng tính của khách hàng 2026-11-04, thay thế giả định trong QnA_STAGE5_PAYOUT_WITHDRAWAL.md A-33 rằng Luồng 34 ghi nhận các khoản chi trả off-cycle Path C; Zapier Integration V7.pdf §Flow 5, §Flow 9; RFQ_ Stack Trading Prop Tech V7.pdf §Process Pod Vesting)

BR_9.11.7: Lưu trữ audit

Mọi lần thực thi đều được ghi vào BPS_Audit_Log. Thời hạn lưu trữ: 5 năm + 1 tháng (CFTC 1.31 / NFA); các object cũ hơn 25 tháng được chuyển sang cold storage.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Audit Requirements)

9. Tiêu chí chấp nhận

10. Tham chiếu API

POST /api/ledger/record

Request:

{
  "trader_id": "94a2b1c8-3f4e-4b21-a123-890abcdef123",
  "metric_category": "W2 Payroll Executed",
  "metric_value": "$4,500.00 Base + Benefits Paid",
  "date": "2026-03-15T18:00:00Z",
  "receipt_hash": "rip_pay_8830192a7c41f"
}

Response (HTTP 200):

{ "status": "success", "tx_hash": "0x..." }

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Record Immutable Ledger)

11. Câu hỏi mở

12. Lịch sử thay đổi

UC_9.12 — Luồng 35: Đồng bộ Sổ cái PTO Rippling

1. Danh mục UC

UC_9.12 — Luồng 35: Đồng bộ Sổ cái PTO Rippling

2. Trigger

Event: Webhook Rippling Time Off Request Approved → catch hook của Zapier Flow 35.

Upstream: trader W-2 yêu cầu nghỉ phép ngay trong Rippling và Rippling phê duyệt (CR-20261027-001). Cùng một webhook được phân nhánh tới hai Zap độc lập: Flow 35 (UC này — sổ cái) và Flow 13 Path A (UC_9.2 — gia hạn stagnation_deadline, khóa tài khoản, thông báo). Stack Trading không tạo bản ghi nghỉ phép trong Rippling.

(Nguồn: Zapier Integration V7.pdf §Flow 35 · CR-20261027-001 · UC_9.2 §2.1)

3. Điều kiện tiên quyết

4. Hậu điều kiện

5. Luồng cơ bản

Bước 1 — Nhận webhook (Zapier).

Bước 2 — Filter: trader W-2 đang hoạt động. Chỉ tiếp tục nếu payload tương ứng với trader W-2 đang hoạt động của Stack Trading; ngược lại dừng (Alt-2).

(Nguồn: Zapier Integration V7.pdf §Flow 35)

Bước 3 — Kiểm tra dedup trên Rippling Request ID. Nếu đã xử lý → Alt-1.

Bước 4 — Gọi POST /api/ledger/record

(Nguồn: Zapier Integration V7.pdf §Flow 35)

Bước 5 — Middleware mint trên Polygon — giống hệt UC_9.11 Bước 5 (xác thực JWT → Ethers.js wallet → recordMetric() qua Alchemy → chờ confirmation → lưu tx_hash → HTTP 200).

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Record Immutable Ledger)

Bước 6 — Kết thúc Zap.

6. Luồng thay thế

Alt-1 — Gửi trùng: trả về HTTP 200 cùng tx_hash đã lưu; không mint lần hai.

Alt-2 — Không phải trader W-2 đang hoạt động: Zap dừng ở filter; không gọi sổ cái.

7. Luồng ngoại lệ

Exc-1 (JWT không hợp lệ → HTTP 401) và Exc-2 (lỗi Polygon RPC → non-2xx, không đánh dấu đã xử lý, Zapier retry) — giống UC_9.11 §7.

Exc-3 — Kỳ nghỉ sau đó bị hủy trong Rippling

• Event on-chain là bất biến và không thể đảo ngược. Không ghi bút toán sổ cái điều chỉnh.
• Việc mở lại tài khoản giao dịch và điều chỉnh stagnation_deadline do Ops xử lý thủ công — xem UC_9.2 Alt-5.

(Nguồn: QnA_BACKGROUND_MECHANISMS_CRON.md [BG-017], [BG-002] — bảng tính của khách hàng 2026-11-04)

8. Quy tắc nghiệp vụ

BR_9.12.1: Chỉ ghi sổ cái

Luồng 35 chỉ ghi event PTO lên Sổ cái Bất biến (Immutable Ledger). Việc gia hạn stagnation_deadline, TRIM_TO_COMPLIANCE và khóa thực thi (Rithmic / MT5 / TraderEvolution) thuộc Luồng 13 (UC_9.2 Steps A-3+) và không được thực thi lại tại đây.

(Nguồn: Zapier Integration V7.pdf §Flow 35 — hành động duy nhất là POST /api/ledger/record rồi "Terminate Zap"; §Flow 13)

BR_9.12.2: Ánh xạ sổ cái cố định

metric_category = "Corporate Benefits"; metric_value = "[Days_Approved] Days PTO Approved (Paid Time Off)", với Days_Approved là số nguyên — PTO chỉ được tính theo ngày trọn (không có nửa ngày); receipt_hash = Rippling Request ID.

(Nguồn: Zapier Integration V7.pdf §Flow 35; QnA_BACKGROUND_MECHANISMS_CRON.md [BG-018] — bảng tính của khách hàng 2026-11-04)

BR_9.12.3: Phạm vi — Chỉ W-2 đang hoạt động

Thời gian tạm nghỉ (hiatus) của contractor quốc tế là không lương và không được Luồng 35 ghi nhận.

(Nguồn: Zapier Integration V7.pdf §Flow 35; §Flow 13 Path B)

BR_9.12.4: Một lần phê duyệt = Một event sổ cái

Rippling Request ID là khóa idempotency (chống trùng lặp). Giống BR_9.11.3.

BR_9.12.5: Lưu trữ audit

Giống BR_9.11.7 (5 năm + 1 tháng; > 25 tháng → cold storage).

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Audit Requirements)

9. Tiêu chí chấp nhận

10. Tham chiếu API

POST /api/ledger/record — schema như UC_9.11 §10.

{
  "trader_id": "94a2b1c8-3f4e-4b21-a123-890abcdef123",
  "metric_category": "Corporate Benefits",
  "metric_value": "3 Days PTO Approved (Paid Time Off)",
  "date": "2026-03-15T18:00:00Z",
  "receipt_hash": "rip_pto_99120482"
}

11. Câu hỏi mở

12. Lịch sử thay đổi

UC_9.13 — Luồng 36: Đồng bộ Sổ cái Retainer Dots

1. Danh mục UC

UC_9.13 — Luồng 36: Đồng bộ Sổ cái Retainer Dots

2. Trigger

(Nguồn: Zapier Integration V7.pdf §7.3 Option B · StackTrading_Backend_Technical_Proposal_v1.6.docx §Option B provider list — Dots ✓)

3. Điều kiện tiên quyết

4. Hậu điều kiện

5. Luồng cơ bản

Bước 1 — Ingress (Middleware). Nhận Dots webhook tại POST /webhooks/retainer/dots → xác thực chữ ký → dedup trên provider_event_id (trùng → Alt-1) → ghi event_log.

Bước 2 — Emit (Middleware). POST /zapier/events/retainer_processed với payload đã chuẩn hóa.

(Nguồn: Zapier Integration V7.pdf §7.3 Option B)

Bước 3 — Filter (Zapier). Chỉ tiếp tục nếu payload tương ứng với contractor quốc tế đang hoạt động của Stack Trading (Level 6+). Ngược lại dừng (Alt-2).

(Nguồn: Zapier Integration V7.pdf §Flow 36)

Bước 4 — Gọi POST /api/ledger/record

(Nguồn: Zapier Integration V7.pdf §Flow 36)

Bước 5 — Middleware mint trên Polygon — giống UC_9.11 Bước 5.

Bước 6 — Kết thúc Zap.

6. Luồng thay thế

Alt-1 — Dots gửi trùng: dedup tại ingress trên provider_event_id trả về HTTP 200 cho Dots; không emit gì tới Zapier.

Alt-2 — Không phải contractor quốc tế đang hoạt động L6+: Zap dừng ở filter; không gọi sổ cái.

7. Luồng ngoại lệ

Exc-1 — Chữ ký Dots không hợp lệ: ingress từ chối (HTTP 401); không có dòng event_log; dòng audit REJECTED.

Exc-2 — Zapier JWT không hợp lệ / lỗi Polygon RPC: giống UC_9.11 Exc-1 / Exc-2. Vì event đã nằm trong event_log, Ops có thể replay.

8. Quy tắc nghiệp vụ

BR_9.13.1: Phạm vi — contractor quốc tế đang hoạt động, Level 6+

Dưới Level 6, trader theo mô hình thưởng theo yêu cầu (on-demand bonus; không có retainer). Lương W-2 của Mỹ thuộc Luồng 34.

(Nguồn: Zapier Integration V7.pdf §Flow 36)

BR_9.13.2: Ánh xạ sổ cái cố định

metric_category = "Payroll Executed"; metric_value = "$[Total_Amount] Retainer Paid ([billing_country])"; receipt_hash = Dots Transaction ID.

(Nguồn: Zapier Integration V7.pdf §Flow 36)

BR_9.13.3: Hardened Ingress (Option B) là bắt buộc đối với Dots

Dots webhook đi vào qua Middleware Hub (xác thực chữ ký, dedup provider_event_id, ghi event_log trước khi emit). Dots không được gọi Zapier trực tiếp.

(Nguồn: Zapier Integration V7.pdf §7.3 · StackTrading_Backend_Technical_Proposal_v1.6.docx §Option B)

BR_9.13.4: Một retainer = Một event sổ cái

Dedup tại ingress (provider_event_id) và tại POST /api/ledger/record (receipt_hash). Không có bản ghi sổ cái trùng lặp.

(Nguồn: Zapier Integration V7.pdf §7.3 — "Ensure downstream actions are idempotent (no duplicate ledger entries / payouts / accounting entries)")

BR_9.13.5: Lưu trữ audit

Giống BR_9.11.7.

9. Tiêu chí chấp nhận

10. Tham chiếu API

POST /api/ledger/record — schema như UC_9.11 §10.

{
  "trader_id": "94a2b1c8-3f4e-4b21-a123-890abcdef123",
  "metric_category": "Payroll Executed",
  "metric_value": "$2,500.00 Retainer Paid (UK)",
  "date": "2026-03-31T18:00:00Z",
  "receipt_hash": "dots_txn_441029381"
}

11. Câu hỏi mở

12. Lịch sử thay đổi

UC_9.14 — Luồng 32: Velocity Reward Engine

1. Danh mục UC

UC_9.14 — Luồng 32: Velocity Reward Engine

2. Trigger

Sự kiện: Middleware nhận Everflow S2S webhook tại POST /api/referral/velocity-reward.

Everflow gửi webhook khi số lượt giới thiệu của origin_user_id vượt ngưỡng mốc. Middleware là điểm vào duy nhất — luồng không đi qua Zapier.

(Nguồn: Zapier Integration V7.pdf §Flow 32)

3. Điều kiện tiên quyết

4. Hậu điều kiện

5. Luồng cơ bản

Bước 1 — Cổng Idempotency

Middleware lấy khóa mức hàng (row-level lock) trước mọi thao tác ghi:

BEGIN;
SELECT id FROM idempotency_log
WHERE provider_event_id = :provider_event_id
FOR UPDATE;

• Nếu hàng tồn tại: trả về HTTP 200 OK với { "status": "duplicate", "skipped": true } — không xử lý tiếp.
• Nếu hàng không tồn tại: chèn hàng mới với provider_event_id, origin_user_id, event_type, received_at; giữ khóa cho đến khi commit ở Bước 3.

UNIQUE index trên provider_event_id là lớp bảo vệ cứng chống chèn đồng thời.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Velocity Reward Engine)

Bước 2 — Cổng Sanctions

SELECT 1 FROM Compliance_geo_restrictions
WHERE country_code = :billing_country
  AND (region_code = :billing_region OR region_code IS NULL);

• Nếu tìm thấy hàng: trả về HTTP 403 Forbidden với { "error": "SANCTIONS_BLOCKED", "user_id": :origin_user_id }. Hủy luồng. Ghi sự kiện sanctions-block vào bps_audit_logs.
• Nếu không tìm thấy hàng: chuyển sang Bước 3.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Velocity Reward Engine)

Bước 3 — Tạo mã khuyến mãi

INSERT INTO promo_codes (
  code,
  applicable_product_id,
  discount_percent,
  is_used,
  origin_user_id,
  event_type,
  created_at
) VALUES (
  :generated_code,        -- cryptographically random alphanumeric, 16 chars
  'EVAL_L1',
  100,
  false,
  :origin_user_id,
  :event_type,
  NOW()
);
COMMIT;  -- releases FOR UPDATE lock from Step 1

generated_code là chuỗi chữ-số ngẫu nhiên mật mã học dài 16 ký tự, duy nhất nhờ ràng buộc UNIQUE trên cột code.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Velocity Reward Engine)

Bước 4 — Email Klaviyo

Middleware gọi Klaviyo Transactional API:

• Template: Velocity_Reward_Unlocked
• Đến: địa chỉ email của origin_user_id
• Các trường payload: promo_code, event_type, milestone_count (3 hoặc 6), applicable_product (EVAL_L1)

Khi Klaviyo API lỗi: áp dụng retry với exponential backoff (xem Exc-1). Không chặn việc gửi Discord khi các retry Klaviyo đang diễn ra.

(Nguồn: Zapier Integration V7.pdf §Flow 32)

Bước 5 — Thông báo Discord

Đưa tin nhắn Discord vào Redis queue cho #trading-floor-announcements:

• Giới hạn tốc độ: 5 tin nhắn mỗi 5 giây (do queue consumer thực thi).
• Triển khai: chỉ dùng fetch() gốc — axios bị cấm tuyệt đối.
• Nội dung tin nhắn: Thông báo thành tích đạt mốc của origin_user_id (tên hiển thị hoặc handle ẩn danh theo chính sách cộng đồng).

Queue consumer lấy tin ra khỏi queue và gọi Discord Bot API trong giới hạn tốc độ cho phép.

(Nguồn: Zapier Integration V7.pdf §Flow 32)

Bước 6 — Audit Log

Ghi vào bps_audit_logs:

{
  "event_type": "VELOCITY_REWARD_ISSUED",
  "origin_user_id": "<id>",
  "provider_event_id": "<id>",
  "milestone": 3,
  "promo_code": "<code>",
  "timestamp": "<ISO-8601>"
}

Sao chép sang S3 Glacier Object Lock (WORM). Thời gian lưu trữ: 5 năm + 1 tháng. 2 năm đầu lưu ở tầng truy cập tức thì. Sau 2 năm: Glacier Deep Archive. Theo yêu cầu lưu trữ hồ sơ của CFTC/NFA.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Velocity Reward Engine)

6. Luồng thay thế

Alt-1 — Sự kiện trùng lặp (provider_event_id đã được xử lý)

• Cổng idempotency phát hiện hàng đã tồn tại (Bước 1).
• Trả về HTTP 200 OK: { "status": "duplicate", "skipped": true }.
• Không tạo mã khuyến mãi. Không gửi email. Không gửi Discord. Không có sự kiện audit (sự kiện đã được ghi ở lần xử lý đầu tiên).
• Luồng kết thúc bình thường.

7. Luồng ngoại lệ

Exc-1 — Klaviyo API lỗi (Bước 4)

Middleware áp dụng exponential backoff:

delay(attempt) = 5s × 2^attempt
  attempt 1 → 10s
  attempt 2 → 20s
  attempt 3 → 40s

Sau 3 lần retry thất bại (tổng cửa sổ backoff ~70s):

• Ghi một entry WARN vào bps_audit_logs: { "event": "KLAVIYO_RETRY_EXHAUSTED", "promo_code": "<code>", "origin_user_id": "<id>" }.
• Gửi cảnh báo Slack SEV-2 tới #dev_ops: "⚠️ [SEV-2] Velocity Reward email failed after 3 retries for user <id>. Promo code <code> was issued but email not delivered. Manual resend required."
• Thông báo Discord (Bước 5) vẫn tiếp tục bất kể Klaviyo lỗi — mã khuyến mãi đã được commit.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Velocity Reward Engine)

Exc-2 — Discord API lỗi (Bước 5)

Redis queue consumer retry theo hướng dẫn rate-limit của Discord Bot. Nếu kênh Discord không khả dụng (non-2xx sau các lần retry):

• Ghi WARN vào bps_audit_logs.
• Cảnh báo Slack tới #dev_ops: "⚠️ [SEV-2] Discord broadcast failed for Velocity Reward event <provider_event_id>.".
• Không chặn luồng — mã khuyến mãi và email không bị ảnh hưởng.

Exc-3 — Bị chặn bởi sanctions (Bước 2)

• Trả về HTTP 403 Forbidden.
• Ghi bản ghi sanctions-block vào bps_audit_logs với event_type = 'VELOCITY_REWARD_SANCTIONS_BLOCKED'.
• Không tạo mã khuyến mãi. Không gửi email. Không gửi Discord.
• Việc sao chép sự kiện chặn sang S3 Glacier vẫn được áp dụng (audit trail CFTC/NFA).

Exc-4 — Xung đột khi INSERT promo_codes (ràng buộc UNIQUE trên code)

• Middleware tạo lại code ngẫu nhiên mới và retry INSERT (tối đa 3 lần).
• Nếu cả 3 lần retry đều thất bại: trả về HTTP 500, ghi log ERROR, gửi cảnh báo Slack SEV-2 tới #dev_ops.
• Xác suất xung đột với chuỗi chữ-số ngẫu nhiên 16 ký tự là không đáng kể nhưng vẫn phải có cơ chế bảo vệ này.

8. Quy tắc nghiệp vụ

BR_9.14.1: Idempotency là bắt buộc — PostgreSQL FOR UPDATE + UNIQUE Index

Mọi Everflow webhook đến PHẢI được kiểm tra xem đã xử lý chưa bằng SELECT ... FOR UPDATE trên bảng idempotency trước khi ghi bất cứ thứ gì. Ràng buộc UNIQUE trên provider_event_id là lớp bảo vệ cứng. Sự kiện trùng lặp PHẢI trả về HTTP 200 OK một cách im lặng — không phải HTTP 4xx — để tránh retry storm từ Everflow.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Velocity Reward Engine)

BR_9.14.2: Cổng Sanctions chạy trước khi tạo mã khuyến mãi

Việc kiểm tra Compliance_geo_restrictions trên billing_country/billing_region PHẢI chạy trước khi bất kỳ mã khuyến mãi nào được ghi vào promo_codes. User bị sanctions tuyệt đối không được nhận mã khuyến mãi hay email, kể cả khi sự kiện mốc của Everflow là hợp lệ.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Velocity Reward Engine)

BR_9.14.3: Tham số mã khuyến mãi là cố định

Mọi mã khuyến mãi do Flow 32 phát hành PHẢI có:

• applicable_product_id = 'EVAL_L1'
• discount_percent = 100
• is_used = false (trạng thái ban đầu)

Không có sản phẩm hay giá trị giảm giá nào khác hợp lệ cho luồng này.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Velocity Reward Engine)

BR_9.14.4: Triển khai Discord — chỉ dùng native fetch(), không dùng axios

Mọi lời gọi Discord API trong Flow 32 PHẢI dùng fetch() API gốc. axios bị cấm tuyệt đối. Quy tắc này áp dụng cho mọi lời gọi Discord Bot từ Middleware trong luồng này.

(Nguồn: Zapier Integration V7.pdf §Flow 32)

BR_9.14.5: Giới hạn tốc độ Discord — 5 tin nhắn mỗi 5 giây qua Redis Queue

Các broadcast Discord PHẢI được đưa vào Redis queue và tiêu thụ với tốc độ tối đa 5 tin nhắn mỗi 5 giây. Cấm các lời gọi Discord đồng bộ trực tiếp bỏ qua queue để tránh bị ban do vượt rate-limit của API.

(Nguồn: Zapier Integration V7.pdf §Flow 32)

BR_9.14.6: Audit Trail CFTC/NFA — S3 Glacier WORM, lưu trữ 5 năm + 1 tháng

Mọi sự kiện audit (phát hành thưởng, sanctions block, hết số lần retry) PHẢI được ghi vào bps_audit_logs và sao chép sang S3 Glacier Object Lock (WORM). Thời gian lưu trữ: 5 năm + 1 tháng. 2 năm đầu ở tầng truy cập tức thì. Sau 2 năm: Glacier Deep Archive. Chính sách Object Lock cấm xóa thủ công.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Velocity Reward Engine)

BR_9.14.7: Exponential Backoff — Cơ số 5s, 3 lần Retry, SEV-2 khi cạn Retry

Lỗi API bên thứ ba (Klaviyo, Discord) PHẢI áp dụng exponential backoff: delay = 5s × 2^attempt (10s, 20s, 40s). Sau 3 lần retry thất bại, gửi cảnh báo Slack SEV-2 tới #dev_ops. Luồng không bị crash — các bước phía sau đã hoàn tất không bị rollback.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Velocity Reward Engine)

BR_9.14.8: Chỉ có hai sự kiện mốc hợp lệ

Chỉ EV_MILESTONE_3_REFS và EV_MILESTONE_6_REFS là trigger hợp lệ cho Flow 32. Mọi giá trị event_type khác nhận được tại POST /api/referral/velocity-reward PHẢI trả về HTTP 400 Bad Request và được ghi log là INVALID_EVENT_TYPE. Mỗi mốc (3 và 6) phát hành đúng một mã EVAL_L1 100% dùng một lần.

(Nguồn: Zapier Integration V7.pdf §Flow 32; QnA_STAGE1_CHECKOUT_ONBOARDING.md STAGE1-064; UC_9.x_Client_Questions.md F32-01 — mốc 3/6 được xác nhận 2026-11-05)

9. Tiêu chí chấp nhận

10. Mô hình dữ liệu

Bảng: promo_codes

Bảng: idempotency_log (logic — có thể trùng với bảng idempotency hiện có)

11. Tham chiếu API

POST /api/referral/velocity-reward

Request payload:

{
  "provider_event_id": "ef_evt_abc123xyz",
  "origin_user_id": 10042,
  "event_type": "EV_MILESTONE_3_REFS",
  "referral_count": 3,
  "billing_country": "US",
  "billing_region": "TX"
}

Response — Happy path (HTTP 200 OK):

{
  "status": "success",
  "promo_code": "ABCD1234EFGH5678",
  "applicable_product": "EVAL_L1",
  "discount_percent": 100,
  "email_dispatched": true,
  "discord_queued": true
}

Response — Sự kiện trùng lặp (HTTP 200 OK):

{
  "status": "duplicate",
  "skipped": true
}

Response — Sanctions block (HTTP 403 Forbidden):

{
  "error": "SANCTIONS_BLOCKED",
  "user_id": 10042
}

Response — event_type không hợp lệ (HTTP 400 Bad Request):

{
  "error": "INVALID_EVENT_TYPE",
  "received": "EV_UNKNOWN",
  "accepted": ["EV_MILESTONE_3_REFS", "EV_MILESTONE_6_REFS"]
}

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §Velocity Reward Engine)

12. Câu hỏi mở

13. Lịch sử thay đổi

UC_9.15 — Luồng 33: Xác minh Amplify Bounty

1. Danh mục UC

UC_9.15 — Luồng 33: Xác minh Amplify Bounty

2. Trigger

Trader chạy slash command Discord /submit-bounty [url] trong #bounty-submissions. Sau khi các kiểm tra phía bot đạt (§5 Bước 1–2), bot gửi webhook tới Zapier Flow 33.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §2.3; Zapier Integration V7.pdf §Flow 33)

3. Điều kiện tiên quyết

4. Hậu điều kiện

5. Luồng cơ bản

Bước 1 — Kiểm tra định dạng URL (Discord Bot, phía client)

Bot kiểm tra đầu vào là URL TikTok hoặc YouTube Shorts hợp lệ trước khi chấp nhận. Không hợp lệ → Alt-1.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §2.3 — Validation)

Bước 2 — Rate limit (Discord Bot)

Mỗi discord_user_id chỉ được gửi một lần trong 24 giờ. Vượt quá → Alt-2.

Triển khai (giả định của BA): Redis SET bounty_rate:{discord_user_id} 1 NX EX 86400; key đã tồn tại → từ chối.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §2.3 — Rate Limiting)

Bước 3 — Webhook tới Zapier

Payload: discord_user_id, url, platform (tiktok | youtube_shorts), timestamp.

Bước 4 — Audit Bước 1: URL chưa từng được dùng

Zapier gọi GET /bounty/check-url?url=[URL-encoded]. Middleware truy vấn bounty_submissions.

• is_unique = false → dừng; DM: "This link has already been used to claim a reward." (Alt-3)

(Nguồn: Zapier Integration V7.pdf §Flow 33 Step 1; RFQ V7 §API Check Bounty URL)

Bước 5 — Audit Bước 2: lấy chỉ số

Zapier lấy Views, Likes, Comments từ TikTok / YouTube API. Khi API lỗi, retry 3 lần với exponential backoff (trong vòng 10 giây). Mọi lần retry đều thất bại → Exc-1.

(Nguồn: QnA_BACKGROUND_MECHANISMS_CRON.md [BG-015] — client sheet 2026-11-04)

Bước 6 — Audit Bước 3: bộ lọc định lượng (Zapier Filter)

Phải đạt cả hai. Nếu không → Alt-4 (Math Failure).

(Nguồn: Zapier Integration V7.pdf §Flow 33 Step 3)

Bước 7 — Audit Bước 4: audit pháp chứng bằng Gemini 1.5 Pro

1. Ẩn PII — loại bỏ email, số điện thoại, định danh tài khoản, thông tin thanh toán, họ tên đầy đủ khỏi toàn bộ văn bản trước khi gửi tới LLM.
2. Đầu vào — mô tả video + 10 comment hàng đầu.
3. Prompt (tác vụ suy luận chuyên sâu, không phải bộ phân loại spam cơ bản): "Analyze these comments for bot-farm patterns (repetitive emojis, generic praise, identical phrasing). Return 'AUDIT_PASS' or 'AUDIT_FAIL'."
4. Lưu trữ — chỉ lưu AUDIT_PASS / AUDIT_FAIL được rút ra trong Google Sheets (không lưu comment gốc).
5. AUDIT_FAIL → Alt-5.

(Nguồn: Zapier Integration V7.pdf §Flow 33 Step 4 — LLM Analysis (Privacy-Safe))

Bước 8 — Audit Bước 5: trao thưởng (khi PASS)

1. Gọi POST /generate-promo-code (type = Associate Track 100%, origin_user_id = trader đã gửi).
2. Ghi nhận URL là đã thưởng trong bounty_submissions.
3. DM trader: "Success. Your impact is verified. Your free Associate Track code is [promo_code]. It has also been sent to your email."
4. Truy vấn Users theo discord_user_id. Nếu tồn tại user đã liên kết có email → gửi mã tới email đó qua AWS SES. Nếu không có tài khoản liên kết → bỏ qua email; DM Discord là kênh gửi duy nhất.

(Nguồn: Zapier Integration V7.pdf §Flow 33 Step 5; QnA_BACKGROUND_MECHANISMS_CRON.md [BG-013], [BG-014] — client sheet 2026-11-04)

6. Luồng thay thế

(Nguồn: Zapier Integration V7.pdf §Flow 33 Steps 1, 5 — Communication Matrix)

7. Luồng ngoại lệ

Exc-1 — Social API không khả dụng sau 3 lần retry / URL không hợp lệ, ở chế độ riêng tư hoặc đã bị xóa: không thưởng; lần gửi này được tính vào rate limit 24h của discord_user_id đó; DM thông báo cho user rằng xác minh thất bại và có thể gửi lại sau 24 giờ (nội dung — xem Q5); ghi log vào BPS_Audit_Log. (Nguồn: QnA [BG-015] — client sheet 2026-11-04)

Exc-2 — Gemini timeout / đầu ra sai định dạng (không đúng chính xác AUDIT_PASS / AUDIT_FAIL): coi là không đạt (fail-closed); không thưởng; ghi log để kiểm tra thủ công. (Giả định của BA)

Exc-3 — POST /generate-promo-code thất bại sau khi PASS: không đánh dấu URL là đã thưởng; cảnh báo Ops tới #ops-marketing; DM trader thông báo đang chờ phát hành thủ công. (Giả định của BA)

Exc-4 — DM Discord bị chặn bởi cài đặt quyền riêng tư của user: user đã liên kết → email vẫn được gửi khi PASS; ghi log lỗi DM. User chưa liên kết → cũng không có email, nên mã không được gửi tới user; ghi log để Ops theo dõi xử lý.

8. Quy tắc nghiệp vụ

BR_9.15.1: Chỉ nhận đầu vào có cấu trúc

#bounty-submissions chỉ chấp nhận slash command /submit-bounty (Send Messages tắt cho @everyone, Use Application Commands bật).

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §2.3)

BR_9.15.2: Nền tảng được hỗ trợ

Chỉ chấp nhận URL TikTok và YouTube Shorts; được bot kiểm tra trước khi gửi.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §2.3)

BR_9.15.3: Một lần gửi mỗi 24 giờ cho mỗi discord_user_id

Rate limit 24h và số lần vi phạm chống bot (anti-bot strike) được theo dõi theo discord_user_id (dù đã liên kết hay chưa). Các lần xác minh thất bại (lỗi API sau khi retry, URL không hợp lệ/riêng tư) cũng được tính.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §2.3; QnA_BACKGROUND_MECHANISMS_CRON.md [BG-013], [BG-015] — client sheet 2026-11-04)

BR_9.15.4: Một phần thưởng cho mỗi URL

GET /bounty/check-url trả về is_unique = false cho mọi URL đã được thưởng. Chỉ các URL đã được thưởng mới chặn việc gửi lại.

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §API Check Bounty URL)

BR_9.15.5: Ngưỡng định lượng

Views ≥ 50,000 VÀ (Likes + Comments) / Views ≥ 0.015. Cả hai đều bao gồm giá trị biên.

(Nguồn: Zapier Integration V7.pdf §Flow 33 Step 3)

BR_9.15.6: Quyền riêng tư với LLM

PII được ẩn trước khi bất kỳ văn bản nào đến LLM; chỉ lưu kết quả PASS/FAIL được rút ra (Google Sheets); cấu hình LLM enterprise với thời hạn lưu giữ được xác định rõ.

(Nguồn: Zapier Integration V7.pdf §Flow 33 Step 4)

BR_9.15.7: Định nghĩa phần thưởng

Dùng một lần, giảm 100% Associate Track, có thể chuyển nhượng, origin_user_id được ghi log để audit. (usage_limit = 1 theo QnA STAGE1-074.)

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §API Generate Promo Code · QnA_STAGE1_CHECKOUT_ONBOARDING.md STAGE1-074)

BR_9.15.8: Nội dung thông báo được cố định

Nội dung DM Discord cho Alt-3/4/5 và PASS tuân theo Communication Matrix của V7 nguyên văn (tiếng Anh).

(Nguồn: Zapier Integration V7.pdf §Flow 33 Step 5)

9. Tiêu chí chấp nhận

10. Tham chiếu API

GET /bounty/check-url

Response: { "is_unique": true }

POST /generate-promo-code

Request (theo V7: type, origin_user_id):

{
  "type": "ASSOCIATE_TRACK_100",
  "origin_user_id": "94a2b1c8-3f4e-4b21-a123-890abcdef123"
}

Response: { "promo_code": "STRING" }

Các giá trị enum của type không được định nghĩa trong V7 — ASSOCIATE_TRACK_100 là placeholder do BA đặt (xem Q3).

(Nguồn: RFQ_ Stack Trading Prop Tech V7.pdf §API)

11. Câu hỏi mở

12. Lịch sử thay đổi

UC_9.16 — Luồng 38: Chặn Hỗ trợ & Tạo Ticket Freshdesk