StackTrading Docs
BA — Business AnalysisUC 7.1–7.6UC 7.6

UC 7.6

Flow 5 - Trustpilot Review Invite: POST /community/trigger-review-invite hẹn lời mời, cron Trustpilot Invitation Queue chạy suppression check rồi gọi Trustpilot Invitation API, webhook ghi nhận review

FieldValue
BA in ChargeAnh Hoang
Date Created2026-10-12
Versionv1.2
Document ReferencesZapier Integration V7.pdf (§Flow 5 — Trustpilot · §3.1 bảng Users) · RFQ_ Stack Trading Prop Tech V7.pdf (§3.2 Trigger Review Invite · TrustPilot Review Received · §3.3 Background Workers — Trustpilot Invitation Queue) · QnA from clients — QnA_STAGE5_PAYOUT_WITHDRAWAL.md (A-54→A-58, A-60→A-62, A-116) · Common Rules CR-08, CR-18

UC_7.6 — Flow 5: Trustpilot Review Invite

🇻🇳 Section này viết bằng tiếng Việt để BA review. Mọi ID, anchor, tên field/API và text hiển thị cho user giữ nguyên tiếng Anh.

1. Overview

FieldContent
IDUC_7.6
Use CaseFlow 5: Trustpilot Review Invite
DescriptionUC này mời trader viết đánh giá về Stack Trading trên Trustpilot, sau khi trader vừa nhận tiền thưởng lên level. Lời mời được gửi chậm 1 đến 3 ngày sau khi trả tiền, và hệ thống không mời trader vừa được mời hoặc vừa đánh giá gần đây. Khi trader viết đánh giá qua link mời, hệ thống ghi nhận lại ngày trader đánh giá.
Phạm viUC này gồm POST /community/trigger-review-invite khi gọi từ Flow 5, cron "Trustpilot Invitation Queue" và webhook POST /webhooks/trustpilot/review-received. Không gồm: Flow 2 gọi cùng endpoint khi trader pass challenge (UC_5.1), hiển thị điểm và review Trustpilot trên marketing site (UC_1.3.3, UC_1.4.2, UC_1.5.3).
Zapier FlowFlow 5 (Payouts — Bonus), bước "Trustpilot". Chạy sau UC_7.3 (Routing & Execution)
Zapier TableKhông đọc Table nào
APIPOST /community/trigger-review-invite · Trustpilot Invitation API · POST /webhooks/trustpilot/review-received (TrustPilot Review Received)
Cron Job taskTrustpilot Invitation Queue, chạy liên tục (Schedule: Continuous)
3rd PartyTrustpilot

2. Trigger

  • Lệnh trả tiền Flow 5 thành công (Ref: UC_7.3 BR_7.3.4). Hệ thống hẹn lời mời (§5.1).
  • Cron "Trustpilot Invitation Queue" thấy một task trong Scheduled_Tasks đã đến hạn. Hệ thống gửi lời mời (§5.2).
  • Trustpilot gọi webhook khi trader viết đánh giá qua link mời. Hệ thống ghi nhận đánh giá (§5.3).

3. Pre-conditions

  • Đã có Trustpilot API credential và HMAC secret (khoá bí mật để xác thực chữ ký webhook của Trustpilot) do Stack Trading (Adam Culver) cấp. Chưa có thì tạo ClickUp ticket để yêu cầu.

4. Post-conditions

  • Đã gửi: Trustpilot gửi email mời; Users.trustpilot_invited_at là thời điểm gửi; BPS_Audit_Log có thêm 1 dòng.
  • Bị chặn: task bị bỏ, không gọi Trustpilot, không đổi gì trong Users (E_7.6.2).
  • Nhận đánh giá: Users.trustpilot_reviewed_at là thời điểm trader gửi đánh giá (BR_7.6.3).

5. Basic Flow

5.1 Hẹn lời mời (Zapier Flow 5)

Stage 1 — Chọn thời gian chờ và hẹn

  1. Zapier Flow 5 đọc Current_Level của trader và chọn thời gian chờ:

    • Level 1 hoặc 2: không mời, xem E_7.6.1.
    • Level 6: chờ 72 giờ (delay_hours = 72).
    • Level 3 đến 5, hoặc Level 7 trở lên: chờ 24 giờ (delay_hours = 24).

  2. Zapier gọi POST /community/trigger-review-invite:

    Input fieldValue
    user_idID của trader vừa được trả tiền
    delay_hours (int)Theo bước 1
    admin_idKhông bắt buộc, Flow 5 không truyền
    • Chỉ hẹn khi lệnh trả tiền ở UC_7.3 thành công. Lệnh bị timeout hoặc Failed thì không hẹn, vì trader chưa nhận được tiền thì không được mời.
    • delay_hours tính từ mốc lệnh trả tiền thành công ở UC_7.3, không chờ tiền về ngân hàng của trader. VD: lệnh trả tiền thành công lúc 10:00 ngày 5 cho trader Level 4 thì lời mời đến hạn lúc 10:00 ngày 6.
    • Không giới hạn số lần mời trong cả quá trình: mọi lần đạt Profit Target từ Level 3 trở lên đều được hẹn, chỉ bị chặn ở bước 5 nếu không đạt suppression check.

  3. Delay Scheduling: Middleware ghi một task vào bảng Scheduled_Tasks (PostgreSQL) với thời điểm chạy là lúc gọi cộng delay_hours, rồi trả 200 OK. Suppression check không chạy ở bước này mà chạy lúc gửi (bước 5).

5.2 Gửi lời mời (cron Trustpilot Invitation Queue)

Stage 2 — Kiểm tra và gửi

  1. Cron "Trustpilot Invitation Queue" (chạy liên tục; đọc bảng Users và Scheduled_Tasks) lấy các task đã đến hạn. Task được gửi ngay khi đến hạn, không chờ giờ hành chính của trader.

  2. Suppression Check: với mỗi task, cron đọc Users và kiểm tra trader có được mời không (BR_7.6.1). Kiểm tra lúc gửi, không phải lúc hẹn, để trader đã đánh giá trong lúc lời mời đang chờ thì không bị mời trùng. Bị chặn thì xem E_7.6.2.

  3. API Dispatch: đạt thì Middleware gọi Trustpilot Invitation API với referenceId là user_id. referenceId là mã gửi kèm lời mời; khi trader đánh giá qua link mời, webhook ở bước 10 trả lại mã này. Trustpilot tự soạn và gửi email mời. Hệ thống không tạo notification trên Dashboard. Trustpilot báo lỗi thì xem E_7.6.3.

  4. State Update: Middleware cập nhật Users.trustpilot_invited_at là thời điểm hiện tại (BR_7.6.3).

  5. Audit: Middleware ghi một dòng vào BPS_Audit_Log, là bảng PostgreSQL bps_audit_logs lưu thao tác của admin và của hệ thống, phục vụ compliance và theo dõi vận hành:

    FieldValue
    idUUID
    admin_id'SYSTEM' (hoặc NULL). Luồng tự động không có admin thực hiện, nên admin_id của POST /community/trigger-review-invite là không bắt buộc
    user_iduser_id của trader được mời
    action'TRIGGER_REVIEW_INVITE'
    reason'Automated Milestone Invite'
    timestampThời điểm hiện tại

    Dòng log này là bản ghi độc lập, không ảnh hưởng tới flow nào khác. Ghi log lỗi thì xem E_7.6.4.

5.3 Ghi nhận đánh giá (webhook Trustpilot)

Stage 3 — Nhận webhook

  1. Trustpilot gọi POST /webhooks/trustpilot/review-received (TrustPilot Review Received) kèm Trustpilot JSON payload. Middleware xác thực chữ ký payload bằng Trustpilot Webhook Secret (HMAC). Chữ ký sai thì xem E_7.6.5.
  2. Middleware lấy referenceId (chính là user_id) và created_at (thời điểm trader gửi đánh giá) trong payload, rồi ghi Users.trustpilot_reviewed_at bằng created_at cho trader có user_id đó (BR_7.6.3). Đánh giá không qua link mời, hoặc Trustpilot gỡ đánh giá, thì xem E_7.6.6, E_7.6.7.
  3. Middleware trả 200 OK ngay để Trustpilot không gửi lại.

6. Exceptional Flows

Exception IDExceptionConditionSystem Handling / Fallback
E_7.6.1Trader Level 1 hoặc 2Current_Level từ 2 trở xuống.Zapier dừng, không gọi POST /community/trigger-review-invite.
E_7.6.2Bị chặn ở suppression check (Ref: BR_7.6.1)Trader rơi vào ít nhất 1 trong 4 điều kiện chặn.Middleware bỏ task một cách im lặng: không gọi Trustpilot, không xếp lại hàng chờ. Lời mời kế tiếp đến từ lần đạt Profit Target sau. VD: trader được mời ngày 1, lên level tiếp ngày 20 thì lời mời ngày 21 bị chặn vì chưa đủ 30 ngày.
E_7.6.3Trustpilot Invitation API báo lỗiGọi Trustpilot không thành công.Không thử lại, bỏ qua lời mời này. Lời mời kế tiếp đến từ lần đạt Profit Target sau.
E_7.6.4Ghi bps_audit_logs lỗiInsert vào bps_audit_logs không thành công.Middleware bắt lỗi bằng try/catch, ghi lỗi vào server log, trả 200 OK và đi tiếp. Không chặn luồng, không thử ghi lại. VD: Trustpilot đã nhận lời mời cho trader A nhưng ghi bps_audit_logs bị lỗi kết nối database, thì trustpilot_invited_at của trader A vẫn được cập nhật và server log có dòng báo lỗi.
E_7.6.5Chữ ký webhook saiChữ ký HMAC của payload không hợp lệ.Middleware từ chối, không cập nhật gì.
E_7.6.6Đánh giá không qua link mờiTrader tự viết đánh giá trên Trustpilot, payload không có referenceId.Không map được với trader nào. Hệ thống chấp nhận việc này và không dựng cơ chế đối chiếu theo tên hay email.
E_7.6.7Trustpilot gỡ đánh giáĐánh giá đã ghi nhận bị Trustpilot gỡ.Hệ thống không xoá trustpilot_reviewed_at.

7. Business Rules

BR_IDRule Description
BR_7.6.1Suppression Check (lời mời tự động): Chạy lúc gửi (cron Trustpilot Invitation Queue, sau delay_hours), không chạy lúc hẹn. Cron đọc Users. Lời mời bị chặn nếu bất kỳ điều kiện nào đúng:1. Trạng thái tài khoản là Failed, Terminated hoặc Locked, để không mời người vừa bị thanh lý hoặc khoá tài khoản.2. trustpilot_reviewed_at cách đây dưới 15 ngày, vì trader vừa đánh giá.3. trustpilot_invited_at cách đây dưới 30 ngày, vì trader vừa được mời.4. Trader đã tắt nhận email marketing trong Settings, vì lời mời đánh giá là email marketing.Không lọc theo quốc gia hay ngôn ngữ: mọi trader qua được 4 điều kiện trên đều được mời.
BR_7.6.3Dữ liệu Users UC này đọc và ghi:- trustpilot_invited_at (Timestamp, UTC, CR-08): lần gửi lời mời gần nhất, ghi ở bước 7.- trustpilot_reviewed_at (Timestamp, UTC, CR-08): ngày đánh giá gần nhất map được, ghi ở bước 10.- Trạng thái tài khoản: đọc ở suppression check (Failed, Terminated, Locked).

8. Open Items

Không còn hạng mục mở. Chi tiết: QnA_init_docs.md.

9. Phân chia trách nhiệm

Hạng mụcSotatek buildStack Trading OpsBên thứ 3
Bước Zap Flow 5 "Trustpilot" (điều kiện level, delay_hours)✅—Zapier
POST /community/trigger-review-invite, bảng Scheduled_Tasks, cron Trustpilot Invitation Queue, suppression check, tích hợp Trustpilot Invitation API✅——
POST /webhooks/trustpilot/review-received (webhook nhận đánh giá, xác thực HMAC)✅——
Cấp HMAC secret và credential Trustpilot—✅ (Adam Culver)—
Soạn và gửi email mời, xử lý đánh giá trùng——Trustpilot
Ghi bps_audit_logs khi gửi lời mời (try/catch, lỗi chỉ ghi server log)✅——

Changelog

DateVersionUpdated itemBeforeAfterNotes
2026-10-12v1Initial document——Bản tiếng Việt để BA re-check, viết theo template UC_8.1.1. Câu hỏi còn mở xem QnA_init_docs.md — chưa đưa vào UC. QnA override / bổ sung spec V7: (1) chặn theo trạng thái tài khoản — A-56: "If the account is Failed, Terminated, or Locked, silently drop the task." (2) hai cooldown khác nhau là cố ý — A-54 (tự động 30 ngày, BPS 15 ngày). (3) đếm giờ từ lúc gửi lệnh trả tiền — A-55: "Do not build listeners to wait for external bank clearance." (4) không ghi nhận review tự nhiên, không reset khi Trustpilot gỡ review — A-60, A-61.
2026-10-12v1Thêm mục "API & Tác vụ nền"; Stage 1–4Endpoint chỉ nhắc trong luồng, không có spec Input/Output; cron "Trustpilot Invitation Queue" chỉ một dòng; không nhắc bảng Scheduled_Tasks; endpoint BPS không ghi rõ không có pathThêm API-1 (POST /community/trigger-review-invite), API-2 (Trustpilot Invitation API), API-3 (POST /webhooks/trustpilot/review-received), API-4 (BPS Trigger Review Invite — path chưa có trong source), JOB-1 (Trustpilot Invitation Queue — Continuous, Users / Scheduled_Tasks), bảng field Users (trustpilot_invited_at, trustpilot_reviewed_at — Timestamp)Theo yêu cầu BA: UC phải ghi đủ API và tác vụ nền. Nguồn: RFQ V7 §3.2, BPS Endpoints, §3.3; Zapier V7 §3.1 bảng Users. Xử lý khi Trustpilot API lỗi vẫn mở ở QnA N-02.
2026-10-12v1Basic Flow Stage 1–4Nhánh delay_hours = 24 không ghi lại endpoint; Stage 4 chỉ ghi "endpoint BPS" không có pathMỗi bước gọi API ghi rõ mã + tên + method/path (API-1→API-4); endpoint BPS ghi POST <path chờ chốt>Theo yêu cầu BA: API phải xuất hiện ngay trong basic flow.
2026-10-13v1Stage 1, JOB-1, BR_7.6.1Chưa nói lệnh trả tiền lỗi thì có hẹn không; Scheduled_Tasks chưa nói lưu ở đâu; chưa nói khung giờ gửi; suppression có 3 điều kiệnChỉ hẹn khi lệnh trả tiền thành công; Scheduled_Tasks lưu PostgreSQL, không mất khi restart; gửi ngay khi đến hạn; suppression thêm điều kiện 4 (đã tắt email marketing); không lọc theo quốc giaBA Anh Hoang chốt 2026-10-13: A-114 (không mời), A-59 (không mời), A-99 (lưu DB), A-63 (gửi luôn), A-86 (mời tất cả). N-01 đóng — Flow 2 và Flow 5 là 2 flow riêng, Flow 5 chỉ cần không mời Level 1–2; lặp lời mời đã được chặn bằng cooldown 30 / 15 ngày.
2026-10-13v1BR_7.6.2Chưa nói 2 kênh mời có ghi chung trustpilot_invited_at khôngGhi chung một cột: mời tay cũng chặn lời mời tự động trong 30 ngàyBA Anh Hoang chốt A-75 (2026-10-13): tính chung để tránh gửi quá nhiều; khớp Zapier V7 §3.1 (trustpilot_invited_at — "last automated or manual review invitation").
2026-10-14v1Toàn UC — viết lại theo khuôn UC_8.1.xCó bảng Thuật ngữ; Basic Flow 4 Stage nhưng gọi API theo mã (API-1…API-4, JOB-1) và link xuống mục riêng "API & Tác vụ nền"; mục này liệt kê 4 API (API-1 POST /community/trigger-review-invite, API-2 Trustpilot Invitation API, API-3 POST /webhooks/trustpilot/review-received, API-4 BPS Trigger Review Invite POST <path chờ chốt>) + JOB-1 Trustpilot Invitation Queue + bảng field Users; xử lý lỗi Trustpilot Invitation API (N-02) chỉ ghi trong bảng API-2Bỏ bảng Thuật ngữ (giải thích ngay câu dùng lần đầu). Bỏ mục "API & Tác vụ nền": input / output / xử lý của từng API chuyển vào đúng bước Basic Flow (bảng Input field | Value ở Stage 1 và Stage 4). Cron Trustpilot Invitation Queue mô tả trong Trigger + Stage 2, không đánh số. Rẽ nhánh (chữ ký sai, review tự nhiên, gỡ review, 409) viết [If …] → ngay trong bước. Bảng field Users chuyển thành BR_7.6.3. Thêm mục Open Items chứa N-02. Số API giữ 4 API đúng như nguồn: POST /community/trigger-review-invite (Zapier V7 §Flow 5 Trustpilot; RFQ V7 §3.2), Trustpilot Invitation API (RFQ V7 §3.2 Trigger Review Invite bước 3), POST /webhooks/trustpilot/review-received (RFQ V7 §3.2 TrustPilot Review Received), BPS Trigger Review Invite (RFQ V7 BPS Endpoints — không có path, path do BE đặt)Theo yêu cầu BA: mô tả và thứ tự như UC_8.1.1 / UC_8.1.2. Nội dung nghiệp vụ và BR ID (BR_7.6.1, BR_7.6.2) giữ nguyên. Đối chiếu nguồn: 4 API cũ đều có trong RFQ V7 / Zapier V7 nên không đổi số API; chỉ bỏ JOB-1 khỏi danh sách đánh số (là cron nội bộ, RFQ V7 §3.3).
2026-10-23v1Stage 2 bước 4–5Stage 2 bước 4 chỉ ghi "ghi BPS_Audit_Log"; chưa nói ghi field gì, chưa nói xử lý khi ghi log lỗiTách ghi log thành Stage 2 bước 5 (ứng với bước 5 "Audit" của API), ghi ngay trong bước: bảng bps_audit_logs (PostgreSQL) với field id (UUID), admin_id = 'SYSTEM' (hoặc NULL), user_id, action = 'TRIGGER_REVIEW_INVITE', reason = 'Automated Milestone Invite', timestamp = NOW(). Insert bọc try/catch: lỗi thì ghi server log, trả 200 OK, không chặn luồng. Thêm dòng RACIKhách định nghĩa bổ sung (2026-10-23): "admin_id: Pass 'SYSTEM' (or NULL) if triggered by an automated flow… action: 'TRIGGER_REVIEW_INVITE'… reason: Pass 'Automated Milestone Invite' if triggered by the system… This log is a standalone record and has no impact on other flows… if the insert fails, write the error to the server log and return HTTP 200 OK without blocking execution."
2026-10-23v1Bỏ Stage 4 (mời tay từ BPS), BR_7.6.2Có Stage 4 — BPS Trigger Review Invite (user_id, admin_id, reason, transcript_url; cooldown 15 ngày → 409 Conflict; ghi BPS_Audit_Log); BR_7.6.2 so sánh mời tự động vs mời tay, hai kênh ghi chung trustpilot_invited_at; Trigger, Overview, Scope, Document References, BR_7.6.3, RACI có nhắc mời tayUC chỉ còn luồng mời tự động (POST /community/trigger-review-invite + cron Trustpilot Invitation Queue) và webhook nhận review. Bỏ Stage 4, BR_7.6.2 và mọi chỗ nhắc mời tayTheo BA Anh Hoang (2026-10-23): UC_7.6 là luồng tự động sau payout (khớp WBS UC_7.6); endpoint admin thủ công BPS Trigger Review Invite (RFQ V7 BPS Endpoints) không thuộc UC này.
2026-10-23v1Stage 1–2: tên bướcBước chỉ đánh sốGắn tên bước theo logic của POST /community/trigger-review-invite: Delay Scheduling (Stage 1 bước 2), Suppression Check, API Dispatch, State Update, Audit (Stage 2 bước 2–5)Theo yêu cầu BA: dễ đối chiếu với 5 bước Logic Requirement trong RFQ V7 §3.2.
2026-10-23v1Stage 1 — Delay SchedulingScheduled_Tasks lưu trong PostgreSQL — task không được mất khi hệ thống khởi động lạiScheduled_Tasks lưu trong PostgreSQLTheo yêu cầu BA: bỏ vế giải thích thừa; lưu DB thì mặc nhiên không mất khi restart.
2026-10-23v1Stage 1 — nhánh delay_hours[Else] → delay_hours = 24; bảng input ghi "ngược lại 24"Ghi rõ nhánh Else gồm Current_Level từ 3 đến 5 và từ 7 trở lên; bảng input ghi tương tựTheo yêu cầu BA: ghi cụ thể level thay vì "ngược lại".
2026-10-29v1.1Toàn UC — cấu trúc lại theo khuôn UC_1.8.7Description ghi chi tiết endpoint, bảng Scheduled_Tasks, cron và webhook; nhánh [If …] nằm trong bước; bước đánh số lại từ 1 ở mỗi Stage; BR_7.6.1, BR_7.6.3 dạng bảng riêngDescription chỉ ghi tổng quan. Mục đánh số 1 đến 9; §5 chia 5.1 hẹn lời mời, 5.2 gửi lời mời, 5.3 ghi nhận đánh giá; bước đánh số liên tục 1 đến 11. Thêm bảng §6 Exceptional Flows (E_7.6.1 đến E_7.6.7). 2 BR gom vào bảng §7. Overview thêm dòng API và Cron Job task. Mọi BR đều được refer từ bước hoặc exception liên quan. Giữ nguyên anchor BR_7.6.1, BR_7.6.3, UC_7.6-open-itemsBA yêu cầu viết dễ hiểu như UC_1.8.7, không đổi nghiệp vụ
2026-10-30v1.2E_7.6.3 · §8 Open Items (N-02)Trustpilot Invitation API báo lỗi: chưa chốt (N-02)Không thử lại, bỏ qua lời mời; đóng N-02Khách xác nhận bản tóm tắt cách xử lý lỗi Flow 5 của BA

QnA Init Docs — UC_7.6 (Flow 5 - Trustpilot Review Invite)

Previous Page

UC 8.1–8.5

On this page

UC_7.6 — Flow 5: Trustpilot Review Invite1. Overview2. Trigger3. Pre-conditions4. Post-conditions5. Basic Flow5.1 Hẹn lời mời (Zapier Flow 5)5.2 Gửi lời mời (cron Trustpilot Invitation Queue)5.3 Ghi nhận đánh giá (webhook Trustpilot)6. Exceptional Flows7. Business Rules8. Open Items9. Phân chia trách nhiệmChangelog