UC 8.2.8

---

UC_8.2.8 — Flow 11: Waitlist Processor

🇻🇳 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

2. Trigger

• Một Pod Leader Active có thêm suất trống. Có 4 sự kiện tạo ra suất trống (BR_8.2.8.1). Flow nào tạo ra suất trống thì flow đó kích hoạt Zap Flow 11 ngay sau đó.

3. Pre-conditions

• Leader đang hoạt động bình thường (Status là Active).
• Leader còn suất trống, tức là số mentee hiện có (Current_Count) nhỏ hơn số mentee tối đa (Max_Capacity). VD: leader có Max_Capacity là 10 và Current_Count là 9 thì còn 1 suất.
• Waitlist có ít nhất 1 trader, xếp theo Join_Date là thời điểm trader vào waitlist (BR_8.2.8.2).

4. Post-conditions

• Trader xác nhận hợp lệ: trader vào pod của leader, status pod là Assigned.
• Trader không bấm link trong 48 giờ: status pod của trader thành Waitlist_Ghost; Current_Count của leader giảm 1 để trả lại suất đã giữ; suất đó được mời cho người kế tiếp.
• Không có trader phù hợp: suất để trống, không ai được mời.

5. Basic Flow

5.1 Kiểm tra waitlist (Flow 11 — Trigger, Check)

Stage 1 — Zap bắt đầu

1. Trigger: Khi một flow khác vừa tạo ra suất trống cho một leader Active, flow đó kích hoạt Zap Flow 11 ngay sau đó cho đúng leader đó (BR_8.2.8.1). VD: Flow 4 vừa cho 1 mentee lên Level 7 và rời pod, thì Flow 4 kích hoạt Zap Flow 11 cho leader của mentee đó. Zap nhận tín hiệu bằng cách nào và kèm dữ liệu gì chưa chốt (§8 #6).
2. Check: Zap kiểm tra waitlist có ai đang chờ không. Ai được tính là đang ở waitlist xem BR_8.2.8.2. Hệ thống không dùng bộ đếm Pod_Waitlist_Count, nên Zap kiểm tra bằng cách nào chưa chốt (§8 #6). Waitlist không có ai, hoặc Zap lỗi, thì xem E_8.2.8.1, E_8.2.8.2.

5.2 Chọn trader và giữ chỗ (Process Waitlist Queue API)

Zapier Flow 11 không có dòng riêng cho việc gọi API này. API nằm ở RFQ V7 và trả trader để Zapier gửi email mời, nên được đặt giữa bước Check và bước Engagement Check. Các bước 4 đến 7 chạy bên trong API; API chỉ trả kết quả sau khi làm xong.

Stage 2 — Chọn trader

3. Zap gọi Process Waitlist Queue API (POST /process-waitlist-queue) để Middleware chọn trader cho leader. Mỗi suất trống gọi 1 lần. VD: 3 mentee rời pod cùng lúc thì Zap gọi API 3 lần và nhận về 3 trader khác nhau.

   Input field	Value
   leader_id	Leader_ID của leader vừa có suất trống. RFQ V7 ghi trường này là không bắt buộc, nhưng Flow 11 luôn truyền vì waitlist được xét theo đúng leader vừa có suất. Không truyền thì xử lý thế nào chưa chốt (§8 #8)

4. Middleware khoá dòng của leader trong Pod_Leader_Registry. Trong lúc lần gọi này đang xử lý, các lần gọi khác phải chờ (BR_8.2.8.7). Leader không tồn tại, không còn Active hoặc đã hết suất thì xem E_8.2.8.3.

5. Middleware chọn 1 trader theo BR_8.2.8.3, chỉ xét trader có status pod Waitlist. Middleware bỏ qua trader đang Inactive_Hold và trader có tài khoản giao dịch đang bị khoá (Locked) do DTO hoặc Hiatus. Middleware khoá dòng của trader được chọn. Nếu trader đó đang bị một lần gọi khác khoá thì Middleware bỏ qua và xét người kế tiếp, để các lần gọi cùng lúc không chọn trùng 1 trader. VD: 2 lần gọi chạy cùng lúc cho 2 suất; lần thứ nhất đã khoá trader A nên lần thứ hai bỏ qua A và chọn trader B. Không có ai phù hợp thì xem E_8.2.8.4.

Stage 3 — Giữ chỗ

6. Middleware giữ chỗ ngay cho trader vừa chọn, ghi cùng lúc 3 thay đổi:

   • Tăng Current_Count của leader thêm 1.
   • Đổi status pod của trader từ Waitlist sang Pending_Pod_Confirmation (BR_8.2.8.4).
   • Lưu thời điểm gửi lời mời, dùng để tính hạn 48 giờ của link xác nhận.

   Ghi lỗi thì xem E_8.2.8.5.

7. Middleware trả 200 OK cho Zapier:

   Output field	Value
   next_candidate_id	UUID của trader vừa được chọn và giữ chỗ
   queue_position	Vị trí của trader trong waitlist theo Join_Date tại lúc được chọn. Chỉ dùng nội bộ để ghi log, không hiển thị cho trader

   Zapier gọi trùng hoặc gọi dư đều an toàn (BR_8.2.8.7).

8. Vì suất đã được tính vào Current_Count, Flow 10 không thấy suất này khi ghép pod cho trader mới đăng ký. Nhờ vậy trader được mời không bao giờ bấm link hợp lệ rồi bị báo hết chỗ.

5.3 Gửi lời mời (Flow 11 — Engagement Check)

Stage 4 — Gửi email qua Klaviyo

9. Sau khi giữ chỗ xong, payload Pod_Spot_Available_Confirm được gửi tới Klaviyo API để Klaviyo soạn email mời. Sau bước này Zap Flow 11 kết thúc. Middleware hay Zapier là bên gửi chưa chốt (§8 #7). Sotatek dựng dữ liệu gửi sang Klaviyo, không soạn nội dung email.

   Input field	Value
   user_id	UUID của trader được mời
   Email trader	Địa chỉ để Klaviyo gửi lời mời
   Link xác nhận	Link có sẵn user_id làm tham số, để khi trader bấm thì hệ thống biết ai bấm. Link chỉ dùng được 1 lần và hết hạn sau 48 giờ. Trader không cần đăng nhập khi bấm. Link trỏ về trang nào chưa chốt (§8 #2)
   Hạn xác nhận	Thời điểm gửi lời mời cộng 48 giờ, theo giờ UTC (CR-08), để email ghi rõ hạn. VD: gửi lúc 10:00 UTC ngày 15 thì hạn là 10:00 UTC ngày 17

10. Mỗi lần mời chỉ gửi email 1 lần. Zapier gọi lại Process Waitlist Queue API thì trader đã được mời không nhận lời mời lần nữa, vì status pod đã chuyển sang Pending_Pod_Confirmation. Email này dùng để lọc ra trader còn quan tâm (BR_8.2.8.6). Gửi sang Klaviyo lỗi thì xem E_8.2.8.6.

5.4 Trader bấm link (Flow 11 — Wait)

Các bước 13 và 14, cùng §5.6, chạy bên trong endpoint nhận Klaviyo webhook callback; endpoint chỉ trả kết quả sau khi làm xong.

Stage 5 — Nhận lần bấm

11. Klaviyo gửi email cho trader và theo dõi trader có bấm link không.

12. Khi trader bấm link, Klaviyo gửi Klaviyo webhook callback (POST) về Middleware. Nguồn không đặt tên endpoint này; tên, đường dẫn và tên trường trả về do BE chốt trong OpenAPI spec. Trader thấy trang gì sau khi bấm chưa chốt (§8 #2).

    Input field	Value
    user_id	Bắt buộc. Lấy từ tham số trên link xác nhận

    Input sai hoặc user_id không tồn tại thì xem E_8.2.8.7.

Stage 6 — Kiểm tra lại

13. Middleware khoá dòng của trader trong Users, để các lần bấm khác của cùng trader phải chờ.
14. Middleware kiểm tra lại trader và leader theo BR_8.2.8.5, vì từ lúc mời tới lúc bấm có thể đã gần 48 giờ trôi qua. Đạt cả 2 kiểm tra thì sang §5.6. VD: trader được mời lúc 10:00 ngày 15 và bấm link lúc 09:00 ngày 17; trong lúc đó leader bị Suspended, nên Middleware ghép trader sang leader khác (E_8.2.8.12). Trường hợp suất bị người khác lấy mất không thể xảy ra, vì suất đã được giữ từ lúc gửi lời mời. Các trường hợp không đạt xem E_8.2.8.8 đến E_8.2.8.13.

5.5 Trader không bấm link trong 48 giờ (Flow 11 — IF No Click)

Stage 7 — Đánh Ghost

15. Trader không bấm link trong 48 giờ thì Klaviyo loại trader và báo cho hệ thống để mời người kế tiếp. Klaviyo báo về Middleware bằng cách nào, Middleware nhận ở đâu, và cách đếm đủ 48 giờ, đều chưa chốt; UC này chưa có cron job (§8 #1).
16. Trader bị loại khỏi waitlist. Status pod của trader thành Waitlist_Ghost. "Ghost" là trader đã được mời nhưng không phản hồi. Từ đây hệ thống xử lý trader như người chưa có pod: thẻ My POD hiện nút [Join a POD]. Muốn vào pod lại, trader bấm nút này và gửi lại form Style theo Flow 10, được ghép như người mới; nếu phải vào waitlist thì đứng cuối hàng (Ref: UC_8.2.1 BR_8.2.1.1).
17. Current_Count của leader giảm 1 để trả lại suất đã giữ cho trader này.
18. Việc giảm Current_Count kích hoạt lại Zap Flow 11 cho leader này, quay về bước 1, để mời người kế tiếp. Cách kích hoạt chưa chốt (§8 #6).

5.6 Trader vào pod (Flow 11 — Assign)

Stage 8 — Gán pod

19. Middleware chạy bước gán pod của Flow 10 ngay trong endpoint nhận Klaviyo webhook callback (UC_8.2.1 §5.4). Khác biệt duy nhất: Middleware không tăng Current_Count lần nữa, vì đã tăng lúc giữ chỗ ở bước 6. Status pod của trader thành Assigned. Mọi thay đổi ở bước 14 (nhánh từ chối hoặc ghép lại) và ở bước này được ghi xuống database cùng nhau; lỗi giữa chừng thì huỷ toàn bộ.

20. Middleware trả 200 OK kèm kết quả xử lý, là 1 trong các trường hợp:

    • Trader đã vào pod của leader đã giữ chỗ.
    • Leader cũ không còn Active, trader đã được ghép sang leader khác.
    • Trader về Waitlist.
    • Trader bị từ chối vì không còn đủ điều kiện.
    • Lời mời đã quá 48 giờ, không ghi gì.
    • Bỏ qua và không ghi gì, vì không có lời mời đang chờ.

    Tên trường chứa kết quả do BE chốt. Bấm trùng thì xem E_8.2.8.14.

21. Chỉ sau khi ghi xong, Middleware mới làm tiếp 2 việc:

    • Gửi sự kiện Pod_Assignment_Confirmation sang Klaviyo để Klaviyo email cho trader (Ref: UC_8.2.1 API_8.2.1.3).
    • Tự gán role Pod Member trên Discord cho trader, theo cách xử lý của API Manage Discord Role (POST /manage-discord-role), không đi qua Zap (Ref: UC_8.2.1 API_8.2.1.2).

    Gửi email hoặc gán role lỗi thì xem E_8.2.8.15.

22. Thẻ My POD trên dashboard của trader chuyển từ Pending sang Matched (Ref: UC_4.14.2 BR_4.14.2.13 sự kiện 4).

5.7 Cập nhật waitlist (Flow 11 — Decrement)

23. Hệ thống không dùng bộ đếm Pod_Waitlist_Count ghi trong RFQ V7, nên bước này không ghi gì thêm. Waitlist là các trader có status pod Waitlist, xếp theo Join_Date; BE tự quyết cách lưu. Trader rời waitlist khi status pod đổi, VD thành Assigned ở bước 19 hoặc Waitlist_Ghost ở bước 16. Danh sách đầy đủ xem BR_8.2.8.2.

6. Exceptional Flows

7. Business Rules

7.1 BR_8.2.8.1 — Sự kiện kích hoạt Flow 11

Flow 11 chạy mỗi khi một leader Active có thêm suất trống. Flow nào gây ra sự kiện thì flow đó gọi Flow 11 ngay sau đó.

• Chỉ xét leader Active. Khi leader bị Suspended hoặc Terminated, cả pod bị rã qua Flow 15A (mentee được ghép sang leader khác hoặc vào waitlist). Flow 11 không mời ai vào pod của leader đó.
• Giảm Max_Capacity không phải sự kiện kích hoạt Flow 11. Giảm xuống thấp hơn số mentee đang có thì hệ thống không đẩy mentee nào ra. VD: pod có 10 mentee, Operations giảm Max_Capacity từ 10 xuống 8 thì cả 10 mentee vẫn ở lại. Flow 11 chỉ mời người mới khi số mentee tự giảm xuống dưới Max_Capacity; VD pod trên giảm dần còn 7 mentee thì mới có 1 suất để mời. Không cần code thêm, vì điều kiện "Current_Count nhỏ hơn Max_Capacity" đã tự chặn.

7.2 BR_8.2.8.2 — Waitlist: ai vào, đứng ở đâu

Waitlist là hàng chờ có thứ tự: trader có Join_Date sớm hơn thì đứng trước (Ref: CR-08). VD: trader A vào waitlist ngày 10, trader B vào ngày 12 thì A đứng trước B.

• Join_Date là ngày vào waitlist, khác với pod_join_date là ngày vào pod. Vào waitlist không đổi pod_join_date, và pod_join_date không được dùng để xếp hàng.
• Trader đang chờ thì bị Inactive_Hold (30 ngày không giao dịch, Zombie Protocol của Flow 12): trader vẫn giữ bản ghi và Join_Date, nhưng bị bỏ qua khi chọn người. Khi trader bấm Reactivate (Flow 12), status pod về Waitlist và trader đứng đúng vị trí cũ.
• Trader đang ở pod thì bị Inactive_Hold, sau đó kích hoạt lại: hệ thống chạy lại bước ghép pod của Flow 10 như với người mới (UC_8.2.1 BR_8.2.1.2). Hệ thống không ưu tiên pod cũ; trader chỉ về lại pod cũ khi bước ghép tình cờ chọn đúng leader đó. Không có leader cùng Asset_Class còn suất thì trader vào waitlist, đứng cuối hàng. VD: mentee A thuộc pod của leader X, bị Inactive_Hold nên suất được mời cho trader B. A kích hoạt lại; leader Y cùng Asset_Class có ít mentee hơn thì A vào pod của Y, không chờ suất ở pod X.
• Trader đang chờ bấm link (Pending_Pod_Confirmation) thì bị Flow 12 quét trúng: xử lý như không bấm link, status pod thành Waitlist_Ghost (E_8.2.8.10).
• Trader đang chờ mà tài khoản giao dịch bị khoá (Locked) do DTO hoặc Hiatus: trader vẫn giữ Join_Date nhưng bị bỏ qua khi chọn người, và được xét lại khi tài khoản về Active.
• Trader rời waitlist khi: status pod thành Assigned (đã vào pod); status pod thành Waitlist_Ghost (không bấm link trong 48 giờ, hoặc bị Flow 12 quét trúng khi đang chờ bấm link); status pod thành null (bị từ chối lúc bấm link, E_8.2.8.11); tài khoản giao dịch thành Failed (trader SIM bị Hard Breach hoặc Resign) hoặc Terminated (trader LIVE bị Hard Breach hoặc Resign); hoặc trader lên Level 7 trở lên (thành Alumni).
• Email Pod_Waitlist_Notification gửi 1 lần mỗi khi trader vào waitlist qua Flow 10, Flow 15A hoặc Flow 12. Không gửi email định kỳ báo vị trí.
• Waitlist không có hạn. Chờ bao lâu cũng được, waitlist dài không kéo theo xử lý tự động nào; Operations tự lo bổ sung Pod Leader.
• Dashboard không hiển thị vị trí trong hàng hay thời gian chờ ước tính (Ref: UC_4.14.2 BR_4.14.2.5).

7.3 BR_8.2.8.3 — Chọn trader cho suất trống

Middleware không xét chung cả waitlist mà xét riêng cho leader vừa có suất trống. Chỉ xét trader có status pod Waitlist; bỏ qua trader Inactive_Hold và trader có tài khoản giao dịch đang Locked do DTO hoặc Hiatus.

VD: một leader Futures vừa có 1 suất, danh sách Style của leader có Scalping. Waitlist có 3 trader:

• Trader A chơi Forex, vào ngày 1: bị loại vì khác Asset_Class.
• Trader B chơi Futures, Style Swing, vào ngày 2.
• Trader C chơi Futures, Style Scalping, vào ngày 5.

Middleware chọn C. B vào sớm hơn, nhưng C khớp Style của leader nên được ưu tiên.

• Asset_Class đọc từ bảng Users. Trading Style đọc từ profile trader đã lưu ở Flow 10.
• Nhiều lần chọn chạy cùng lúc thì mỗi lần phải chọn một trader khác nhau, không được chọn trùng (BR_8.2.8.7).

7.4 BR_8.2.8.4 — Status pod của trader

• Status pod lưu ở cột riêng (VD pod_status), tách khỏi cột status tài khoản giao dịch users.status, để hai loại status không ghi đè lên nhau.
• Trader được tính là đang ở waitlist khi status pod là Waitlist, Inactive_Hold hoặc Pending_Pod_Confirmation.

7.5 BR_8.2.8.6 — Ba email Klaviyo của Pod

Pod_Spot_Available_Confirm dùng để lọc ra trader còn quan tâm: chỉ trader bấm link mới được vào pod, nhờ vậy hệ thống không đưa người đã không còn hoạt động vào pod của leader. Nội dung email do Klaviyo hoặc khách quản lý.

8. Open Items

Chi tiết: QnA_init_docs.md.

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

---

Changelog