US-S10: Kiểm tra mail thông báo (luồng 6)

Thuộc FS: 00-overview.md — SAPP-26297 Chuyển nhượng học viên (tool sapp.011) Phần chung (tổng quan, roles, flow tổng, related features, NFR, Open Questions, References) xem ở Overview. File này chỉ chứa nội dung riêng của US.

Cơ chế chạy bước → US-S01. Các bước tạo contact / tạo ticket / kéo stage / đọc ticket dùng đúng quy tắc của US-S09 BR-01 → BR-05. Mail do SAPP gửi sau đồng bộ (SAPP-28980); mind_keep không gửi mail, tool chỉ dựng ticket lỗi, đọc lại trạng thái đồng bộ và hiện checklist kiểm tay.

Field	Value
US ID	US-S10
Role thực hiện	R1 - Người dùng tool — Assumption (OQ về G-01 → OQ-S-01)
Phase	As-built (đã triển khai @ e77c47a)
Priority	N/A — as-built
Status	Draft — phần mail chỉ kiểm tay; 6.5–6.7 phụ thuộc luồng 5 (blocked), 6.8 không dựng được từ tool (OQ-S-10)
NFR liên quan	NFR-S-01, NFR-S-02 — xem Overview §5
OQ liên quan	OQ-S-01, OQ-S-02, OQ-S-10, OQ-S-12, OQ-S-14, OQ-S-19 — xem Overview §6

1. US Statement

As a Người dùng tool  [Assumption — OQ-S-01]
I want dựng ticket HubSpot rơi vào từng lỗi đồng bộ (E01, E03, E04) rồi đọc lại trạng thái đồng bộ,
       và có checklist để kiểm mail trong hộp thư dev
So that kiểm SAPP-28980: "Bốn mẫu mail E01/E03/E04/E05 phải tới đúng người và đủ nội dung"
        (tóm tắt luồng trên màn; mục đích nghiệp vụ rộng hơn là [Assumption] — OQ-S-18)

2. Dependencies & Definition Of Ready

N/A — đã triển khai. Dependency runtime:

#	Cần sẵn sàng	Ai cung cấp	Trạng thái
D1	Như US-S09 D1 (pipeline / stage kích hoạt đồng bộ)	SAPP	⏸ Chờ SAPP câu 4 — OQ-S-10
D2	Bảng log mail trong DB Ops (để chấm tự động thay vì kiểm hộp thư)	SAPP	⏸ Chờ SAPP câu 9 — OQ-S-10
D3	Dữ liệu chắc chắn gây E04 / E03	SAPP	⏸ Chờ SAPP câu 10 — OQ-S-10
D4	Người có quyền đọc hộp thư dev nhận mail	SAPP / BA	❓

3. Business Rules

ID	Rule	Áp dụng ở	Đã cover bởi (AC)	Nguồn code (Mode B/C)
BR-01	Case dựng lỗi (6.1, 6.3, 6.4) chạy chuỗi: tạo contact · tạo ticket · kéo Close success · đọc ticket (chấm trạng thái đồng bộ = SYNC_FAILURE) · checklist mail	M1 - case 6.1, 6.3, 6.4	AC-M1.1, AC-M1.2	fe/src/ui/components/works/sapp/sapp-26297-flows.ts:1833-1898
BR-02	6.1 (E01 — mã lớp không khớp contact): contact được tạo với lop_dang_ky = mã mới 1, cố ý khác mã lớp cũ trên lớp đăng ký chính của ticket	M1 - case 6.1	AC-M1.1	sapp-26297-flows.ts:1839-1850
BR-03	Checklist mail là bước hướng dẫn: chưa đọc được hộp thư từ tool; không còn placeholder chưa thay, không ô trống; CC đủ 5 địa chỉ ADMIN_MAIL_CC (danh sách trong code)	M1 - checklist	AC-M1.1, AC-M1.2	sapp-26297-flows.ts:1817-1824
BR-04	Case chỉ hướng dẫn, không gọi API: 6.2 (khối mã lớp rỗng), 6.5 / 6.6 / 6.7 (gắn BLOCKED, dựng theo luồng 5), 6.8 ("Không dựng được từ tool"), 6.T (danh sách placeholder theo template)	M1 - case 6.2, 6.5 → 6.8, 6.T	AC-M1.3	sapp-26297-flows.ts:1852-1863,1900-1960

4. Design

a. Mối liên hệ giữa các màn & User Flow

[Tab "6 · Mail"]
  6.1 / 6.3 / 6.4: [tạo contact (GHI HubSpot)] → [tạo ticket (GHI)] → [kéo Close (GHI) ⇒ SAPP đồng bộ + gửi mail]
                   → [đọc ticket: SYNC_FAILURE] → [checklist mail — kiểm tay hộp thư dev]
  6.2, 6.5–6.8, 6.T: chỉ hướng dẫn

b. Chi tiết từng màn

Màn M1 - Tab "6 · Mail"

Field	Value
Figma frame	N/A
Trigger vào màn	Bấm tab "6 · Mail"
Mô tả ngắn	Tóm tắt: "SAPP-28980. Bốn mẫu mail E01/E03/E04/E05 phải tới đúng người và đủ nội dung. Tool dựng ticket lỗi và đọc lại trạng thái đồng bộ; phần mail kiểm tay trong hộp thư dev (chờ SAPP câu 9). 6.5–6.7 phụ thuộc luồng 5 (blocked)." 9 case

UI States

State	Khi nào	Hiển thị	Figma frame
Default	Vào tab	Tóm tắt + 9 case đóng; fixture hiện ô HubSpot của luồng 6	N/A
Loading	Bước đang chạy	Theo US-S01	N/A
Has data	Bước chạy xong	✓/✗; 6.1 có khung "Điểm verify quan trọng nhất của luồng 6…"; 6.5–6.7 có khung BLOCKED	N/A
Empty	Case chỉ hướng dẫn	Chỉ các dòng chữ	N/A
Error	HubSpot từ chối / thiếu cấu hình	Hộp đỏ (US-S09)	N/A
Disabled	Fixture thiếu giá trị	Nút khoá "Chưa điền: …"	N/A

Fields

Field	Required	Type	Default	Format	Validation	Error Message	Visibility	Depends On
Field tạo contact / tạo ticket / kéo stage / đọc ticket	—	—	Như US-S09 §4 Fields; riêng 6.1: lop_dang_ky = {class_code_1}	—	—	—	Bước tương ứng	Fixture
email, firstname, lastname (6.3)	—	Text	Như US-S09; hướng dẫn: đổi email mới, để trống firstname / lastname	—	Trống ⇒ không gửi (EC-M1.1)	—	Bước tạo contact 6.3	—

Actions

A1 - Chạy các bước của một case

Item	Description
Trigger	Mở case, chạy từng bước (US-S01)
Behavior	Thao tác dùng: tạo contact, tạo ticket, sửa ticket (GHI HubSpot), đọc ticket. Ghi vào: HubSpot theo môi trường — dev = portal dev; staging = portal HubSpot PROD (như US-S09 A1). Kéo stage kích hoạt đồng bộ + gửi mail thật phía SAPP
Success Result	Ticket SYNC_FAILURE; mail kiểm tay

⚠️ Ghi PROD — ở tab staging, các bước HubSpot của luồng 6 ghi vào portal HubSpot production (cùng nguyên nhân với US-S09, be/libs/constants/src/lib/hubspot/hubspot.constants.ts:19-26) — OQ-S-19.

Error cases:

Case	Expected Handling
HubSpot từ chối	Hộp đỏ (US-S09 BR-03)
Đồng bộ chưa xong khi đọc ticket	Check SYNC_FAILURE ✗ — chờ rồi chạy lại

Bảng case (9 case):

Mã case	Tên	Bước	Kỳ vọng tool chấm
6.1	E01 — mã lớp không khớp contact	tạo contact (lop_dang_ky = mã mới 1) · tạo ticket (lớp đăng ký chính = mã cũ) · kéo Close · đọc ticket · checklist	SYNC_FAILURE; mail (tay): tới Ticket Owner, CC ADMIN_MAIL_CC, có danh sách mã lệch
6.2	E01 biến thể — khối mã lớp rỗng	hướng dẫn	Kiểm tay: mail vẫn gửi, không khối trống / vỡ layout
6.3	E04 — không tạo được tài khoản	hướng dẫn dựng · tạo contact · tạo ticket · kéo Close · đọc ticket · checklist	SYNC_FAILURE; mail (tay): TICKET_OWNER_NAME, CONTACT_NAME, CONTACT_ID, REASONS, có CC
6.4	E03 — không thêm được học viên vào lớp (2 mã cùng lỗi)	hướng dẫn dựng · tạo contact · tạo ticket (2 lớp mới lỗi) · kéo Close · đọc ticket · checklist	SYNC_FAILURE; mail (tay): 2 lỗi gộp một mail
6.5	E03 luồng hoàn tác	hướng dẫn (theo 5.4)	BLOCKED — kiểm tay
6.6	E05 — cần xử lý thủ công → CX theo khu vực	hướng dẫn (theo 5.3, 3 biến thể khu vực)	BLOCKED — kiểm tay
6.7	E05 fallback — chương trình không map được	hướng dẫn	BLOCKED — kiểm tay
6.8	Mail lỗi không làm hỏng đồng bộ	hướng dẫn	"Không dựng được từ tool" (cần đổi SMTP dev)
6.T	Đối chiếu replacements ↔ placeholder	hướng dẫn	Danh sách placeholder theo 5 template — kiểm tay

Acceptance Criteria của màn M1

AC-M1.1 - E01 mã lớp không khớp contact

Given fixture đủ ô HubSpot luồng 6
When người dùng chạy "Contact KHÔNG chứa mã lớp của ticket" (lop_dang_ky = class_code_1)
And chạy "Ticket có lop_dang_ki_chinh = MA_LOP_CU", "Kéo ticket sang Close success"
And chạy "Đọc lại ticket" sau khi đồng bộ xong
Then properties.trang_thai_dong_bo_lms = "SYNC_FAILURE"
And bước checklist mail chỉ hiện hướng dẫn kiểm tay, không có check tự động

Maps to:

• Business Rule: BR-01, BR-02, BR-03

AC-M1.2 - E04 và E03

Scenario Outline: ticket lỗi đồng bộ
  Given tester đã dựng dữ liệu theo hướng dẫn của <case>
  When người dùng chạy tạo contact, tạo ticket, kéo Close success, đọc lại ticket
  Then properties.trang_thai_dong_bo_lms = "SYNC_FAILURE"
  And nội dung mail được kiểm tay theo checklist

  Examples:
    | case | dựng                                                          |
    | 6.3  | email mới chưa có tài khoản LMS, để trống firstname/lastname  |
    | 6.4  | lop_moi chứa 2 mã lớp mà việc thêm học viên sẽ fail           |

Maps to:

• Business Rule: BR-01, BR-03

AC-M1.3 - Case chỉ hướng dẫn

Scenario Outline: không gọi API
  When người dùng mở case <case>
  Then chỉ hiện bước hướng dẫn <ghi chú> và không có request nào

  Examples:
    | case | ghi chú                                  |
    | 6.2  | dựng lỗi khác lệch mã lớp                 |
    | 6.5  | kèm cảnh báo BLOCKED                      |
    | 6.6  | kèm cảnh báo BLOCKED                      |
    | 6.7  | kèm cảnh báo BLOCKED                      |
    | 6.8  | "Không dựng được từ tool"                 |
    | 6.T  | danh sách placeholder theo template       |

Maps to:

• Business Rule: BR-04

Negative AC / Edge Cases của màn M1

ID	Tình huống	Hành vi mong đợi
EC-M1.1	⚠️ Observed — 6.3 "để trống firstname / lastname" khi email đã tồn tại	Hành vi hiện tại: ô trống bị bỏ khỏi payload; contact trùng email bị dùng lại nên tên cũ vẫn còn, lỗi E04 có thể không xảy ra (sapp-26297-step-call.tsx:110-116 · sapp-26297-flows.ts:1872-1873 · hubspot/common.service.ts:607-661) — OQ-S-02
EC-M1.2	⚠️ Ghi PROD — chạy ở tab staging	Hành vi hiện tại: contact / ticket lỗi được tạo trên HubSpot production và có thể kích hoạt mail thật — OQ-S-19
EC-M1.3	Không có quyền đọc hộp thư dev	Tool không chấm được mail — kết quả luồng 6 chỉ còn trạng thái SYNC_FAILURE

5. Cross-feature AC

AC-X.1 - Mail do SAPP gửi

Given ticket được kéo sang Close success và đồng bộ thất bại
Then hubspot-service của SAPP gửi mail theo template tương ứng; mind_keep không gửi mail

Maps to:

• REL-07 (Affects - Hệ thống SAPP)