US-P05: Tra vết log SAP và theo dõi / kích hoạt đợt quét doanh thu

Thuộc FS: 00-overview.md — Nền tảng dùng chung của cụm tool SAPP (as-built @ e77c47a) 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.

Field	Value
US ID	US-P05
Role thực hiện	R1 - Người dùng tool (qua sub-tool sapp.010 — SAPP 26878 "Test data theo luồng") — Assumption (OQ về G-01), xem OQ-P-13
Phase	As-built (đã triển khai)
Priority	N/A — as-built
Status	Draft
NFR liên quan	NFR-P-01, NFR-P-03, NFR-P-04, NFR-P-05 — xem Overview §5
OQ liên quan	OQ-P-01, OQ-P-22 — xem Overview §6

Nguồn inventory: A-13, A-14, A-15.

Sub-tool đang dùng dịch vụ này (Fact): chỉ sapp.010 (FS 26878) — tab "Trace", tab "Chạy lượt quét", bước scan / trace trong các flow, modal tra vết mở từ lịch sử run (fe/src/ui/components/works/sapp/sapp-26878-tool.tsx:34-43, :1376, :1489, :2198-2211; fe/src/ui/components/works/sapp/sapp-26878-step-scan.tsx:6). Các FS nhóm khác không gọi. Chi tiết cách 26878 đặt các màn này vào flow → FS 26878 US-D02 / US-D03.

1. US Statement

As a Người dùng tool (qua sub-tool 26878)  [Assumption — OQ-P-13 / G-01]
I want tra các dòng log mà SAP service ghi cho một deal / event / entry / lớp / giao dịch, xem tiến độ các đợt quét ghi nhận doanh thu, và bắn một lượt quét ngay trên dev/staging
So that dựng và kiểm được dữ liệu test cho kịch bản doanh thu phase 2 mà không phải chờ lượt quét tuần — nguồn: `shared/external/sapp/sapp-26878/0005-sapp-26878-phase2-us04-tra-loi-ops-mind.md:28-30` (đường thay thế "INSERT một dòng `sap_revenue_scan_runs` rồi gọi lượt quét thủ công")

2. Dependencies & Definition Of Ready

N/A — đã triển khai (Mode B).

Dependency runtime:

#	Cần sẵn sàng	Ai cung cấp	Trạng thái
D1	SAPP_SAP_{API_URL,CLIENT_ID,HMAC_SECRET}_<ENV> trong env_systems (US-P04)	Admin CMS	Theo môi trường
D2	SAP service (ngoài mind_keep) chạy; công tắc nghiệp vụ SAP_REVENUE_RECOGNITION_ENABLED bật (phía SAP service)	Đội SAPP	Ngoài hệ thống

3. Business Rules

ID	Rule	Áp dụng ở	Đã cover bởi (AC)	Nguồn code (Mode B/C)
BR-01	Tra vết và xem đợt quét có trên cả 3 môi trường prod / staging / dev (chỉ đọc); quét thủ công chỉ có dev / staging	M1, M2, M3	AC-M1.1, AC-M3.3	be/apps/api/src/sapp/sapp.controller.ts:3841-3916, :3991-4015
BR-02	Tra vết cần ít nhất một trong 5 khoá lọc: deal_id, event_id, entry_id, class_code, transaction_id; nhiều khoá thì kết hợp AND. Không có khoá → lỗi 13040	M1 - Bộ lọc	AC-M1.2, EC-M1.1	be/libs/modules/src/lib/sapp/sap-log.common.service.ts:132-144, be/libs/constants/src/lib/sapp/sap-log.constants.ts:79-89
BR-03	Tra theo deal_id trả cả dòng phase 1 (hoá đơn, tiền về) của deal đó	M1	AC-M1.3	be/libs/modules/src/lib/sapp/sap-log.common.service.ts:156-164, fe/src/ui/components/works/sapp/sap-log-trace.tsx:44-49
BR-04	limit phải trong 1–200 (ngoài khoảng → lỗi 13041) và áp cho từng bảng, không phải cả kết quả; màn mặc định limit 50, offset 0	M1, M2	AC-M1.4, EC-M1.2	be/libs/modules/src/lib/sapp/sap-log.common.service.ts:146-154, be/libs/constants/src/lib/sapp/sap-log.constants.ts:72-77, fe/src/ui/components/works/sapp/sap-log-trace.tsx:317-321
BR-05	Khoá lọc để trống bị bỏ trước khi gửi (chuỗi rỗng không được coi là điều kiện)	M1, M2	AC-M1.5	be/libs/modules/src/lib/sapp/sap-log.common.service.ts:357-369
BR-06	Yêu cầu tra vết / đợt quét được ký HMAC ở BE bằng credential của môi trường; credential không bao giờ tới trình duyệt	M1, M2	AC-M1.1	be/libs/modules/src/lib/sapp/sap-log.common.service.ts:56-68, :165-188
BR-07	Thiếu URL / client id / HMAC secret của môi trường → lỗi 13037 "SAP service log API is not configured for this environment" (log nêu tên key thiếu); quét thủ công chỉ cần URL	M1, M2, M3	EC-M1.3	be/libs/modules/src/lib/sapp/sap-log.common.service.ts:79-113, :340-355
BR-08	Kết quả tra vết giữ nguyên dữ liệu từng bảng log (vd lesson_entries, event_trackings, logs, scan_runs) kèm số dòng mỗi bảng; màn hiện tóm tắt + dòng thời gian + bảng thô từng bảng	M1	AC-M1.6	be/libs/interface/src/lib/dto/sapp/sap-log.dto.ts:74-86, fe/src/ui/components/works/sapp/sap-log-trace.tsx:420-440
BR-09	Chấm màu trạng thái dòng log theo từ khoá, ưu tiên: lỗi (FAIL, ERROR, REJECT, TIMEOUT, CANCEL, INVALID) → đang xử lý (NOT_SYNCED, PENDING, RETRY…) → thành công (SUCCESS, SYNCED, SENT…) → không rõ	M1 - tóm tắt	AC-M1.6	fe/src/ui/components/works/sapp/sap-log-summary.tsx:160-200
BR-10	Danh sách đợt quét lọc được theo run_type (WEEKLY, MONTH_CLOSE, EVENT_LEAVE, EVENT_RESCHEDULE, EVENT_RESYNC, MANUAL_TEST), from/to (YYYY-MM-DD), limit, offset	M2	AC-M2.1	fe/src/ui/components/works/sapp/sap-log-trace.tsx:501-508, be/libs/interface/src/lib/dto/sapp/sap-log.dto.ts:48-63
BR-11	Quét thủ công bị từ chối trên prod (lỗi 13050) — cả ở tầng dịch vụ lẫn vì không có route prod	M3	AC-M3.3	be/libs/modules/src/lib/sapp/sap-log.common.service.ts:228-236, be/apps/api/src/sapp/sapp.controller.ts:3991-4015
BR-12	Kết quả quét thủ công: triggered=true chỉ nghĩa là đã vào hàng đợi (quét chạy bất đồng bộ); triggered=false nghĩa là nghiệp vụ đang tắt bằng công tắc SAP_REVENUE_RECOGNITION_ENABLED — trả như kết quả bình thường, không phải lỗi	M3	AC-M3.1, AC-M3.2	be/libs/modules/src/lib/sapp/sap-log.common.service.ts:215-271, fe/src/ui/components/works/sapp/sapp-26878-step-scan.tsx:118-150
BR-13	Lỗi quét thủ công từ SAP service: 403 → 13050, 429 → 13051 (hai lượt phải cách nhau ≥ 1 giây), khác → 13052; thông điệp gốc của SAP service được giữ	M3	EC-M3.1, EC-M3.2	be/libs/modules/src/lib/sapp/sap-log.common.service.ts:245-262
BR-14	Màn quét thủ công đặt ngay trên danh sách đợt quét để người dùng đọc kết quả thật của lượt vừa bắn	M3	AC-M3.1	fe/src/ui/components/works/sapp/sapp-26878-tool.tsx:2190-2199

4. Design

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

[Sub-tool 26878] ─ tab "Trace" ──────→ M1 Tra vết log SAP + M2 Đợt quét (prod/staging/dev)
                ─ tab "Chạy lượt quét" → M3 Quét thủ công (dev/staging) + M2 Đợt quét
                ─ bước scan / trace trong flow, modal trace từ lịch sử → dùng lại M3 / M1
M1: nhập khoá → "Tra log" → tóm tắt + bảng thô
M3: "Chạy lượt quét ngay" → vào hàng đợi / nghiệp vụ TẮT / lỗi → đọc M2

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

Màn M1 - Tra vết log SAP

Field	Value
Figma frame	N/A — as-built, không có Figma
Trigger vào màn	Trong sapp.010: tab "Trace", hoặc modal tra vết theo deal của một run
Mô tả ngắn	Bộ lọc 5 khoá + limit/offset → tóm tắt, dòng thời gian, bảng thô

UI States

State	Khi nào	Hiển thị	Figma frame
Default	Chưa tra	Section "Bộ lọc" + gợi ý "Cần ÍT NHẤT một khóa; nhiều khóa thì AND với nhau. limit áp cho TỪNG BẢNG…"	N/A
Disabled	Chưa có khoá nào	Cảnh báo "Chưa có khóa lọc nào — nhập ít nhất một trong deal_id · event_id · entry_id · class_code · transaction_id…"	N/A
Loading	Đang tra	Nút "Đang tra…"	N/A
Has data	Có kết quả	Tóm tắt có chấm màu + bảng thô theo thứ tự bảng	N/A
Empty	Không bảng nào có dòng	Tóm tắt/bảng rỗng	N/A
Error	API lỗi	Lỗi "Không tra được log SAP" + thông điệp	N/A

Fields

Field	Required	Type	Default	Format	Validation	Error Message	Visibility	Depends On
deal_id	Một trong 5	Text	— ("27334455")	id HubSpot	BR-02	13040	Always	—
event_id	Một trong 5	Text	— ("REVENUE_RECOGNITION.…")	—	BR-02	13040	Always	—
entry_id	Một trong 5	Text	— ("uuid")	uuid; phase 2 = external_reference	BR-02	13040	Always	—
class_code	Một trong 5	Text	— ("ACCA.F2.2609.NEU.01")	—	BR-02	13040	Always	—
transaction_id	Một trong 5	Text	— ("uuid giao dịch trên Order")	uuid; phase 1	BR-02	13040	Always	—
limit	No	Number	50	1–200	BR-04	13041 "limit must be between 1 and 200"	Always	—
offset	No	Number	0	≥ 0	—	—	Always	—

Nguồn: fe/src/ui/components/works/sapp/sap-log-trace.tsx:38-67, :317-321.

Filter / Search / Sort

Loại	Theo field	Kiểu	Default	Notes
Filter	5 khoá lọc	free-text, AND	—	BR-02
Search	—	—	—	Không có
Sort	—	—	Thứ tự SAP service trả	—
Pagination	limit / offset	Number	50 / 0	Áp từng bảng (BR-04)

Actions

A1 - Tra log

Item	Description
Trigger	Bấm "Tra log" (hoặc tự chạy khi mở từ nơi đã biết deal)
Behavior	POST /api/v1/sapp/<env>/sap-log/trace; BE bỏ khoá rỗng (BR-05), ký HMAC (BR-06), gọi SAP service. Chỉ đọc log SAP của môi trường đã chọn — kể cả prod; không ghi
Success Result	Hiện tóm tắt + bảng thô (BR-08, BR-09)

Error cases:

Case	Expected Handling
Không có khoá	13040
limit ngoài 1–200	13041
Thiếu cấu hình	13037
SAP service lỗi	13038 "Failed to trace SAP log"

Acceptance Criteria của màn M1

AC-M1.1 - Tra vết trên prod (chỉ đọc)

Given môi trường prod có đủ SAPP_SAP_*_PROD
When người dùng nhập deal_id và bấm "Tra log"
Then nhận được các bảng log của deal trên SAP service prod; không có dữ liệu nào bị ghi

Maps to:

• Business Rule: BR-01, BR-06

AC-M1.2 - Nhiều khoá kết hợp AND

Given người dùng nhập class_code và deal_id
When tra
Then chỉ trả dòng khớp cả hai khoá

Maps to:

• Business Rule: BR-02

AC-M1.3 - Tra theo deal có cả phase 1

Given deal có hoá đơn và tiền về (phase 1) và dòng doanh thu theo buổi (phase 2)
When tra theo deal_id
Then kết quả có cả dòng phase 1 và phase 2

Maps to:

• Business Rule: BR-03

AC-M1.4 - limit áp từng bảng

Given limit = 50
When tra một lớp có 80 dòng sổ cái và 70 dòng log
Then mỗi bảng trả tối đa 50 dòng (không phải 50 dòng tổng)

Maps to:

• Business Rule: BR-04

AC-M1.5 - Khoá rỗng bị bỏ

Given người dùng nhập deal_id và để class_code rỗng
When tra
Then điều kiện gửi đi chỉ có deal_id

Maps to:

• Business Rule: BR-05

AC-M1.6 - Tóm tắt có chấm màu

Given một dòng log có trạng thái "SYNC_FAILED"
When hiển thị tóm tắt
Then dòng đó được chấm màu "lỗi" (ưu tiên hơn "đang xử lý" và "thành công")
And bảng thô vẫn hiện nguyên cột và giá trị gốc

Maps to:

• Business Rule: BR-08, BR-09

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

ID	Tình huống	Hành vi mong đợi
EC-M1.1	Gọi API không có khoá nào	13040 "At least one of deal_id, event_id, entry_id, class_code, transaction_id is required"
EC-M1.2	limit = 500	13041
EC-M1.3	Thiếu SAPP_SAP_HMAC_SECRET_STAGING	13037; log BE nêu tên key thiếu
EC-M1.4	⚠️ Observed — Route tra vết public, không cần đăng nhập	Ai có URL API đều đọc được log SAP prod (NFR-P-01, OQ-P-01)

Màn M2 - Đợt quét (phase 2)

Field	Value
Figma frame	N/A — as-built, không có Figma
Trigger vào màn	Trong sapp.010: dưới M1 (tab "Trace") và dưới M3 (tab "Chạy lượt quét")
Mô tả ngắn	Danh sách lượt quét doanh thu thực hiện; thứ đáng đọc nhất là counters từng dòng

UI States

State	Khi nào	Hiển thị	Figma frame
Default / Has data	Tải xong	Section "Đợt quét (phase 2)" + bộ lọc + danh sách	N/A
Loading	Đang tải	Bộ lọc vô hiệu	N/A
Empty	Không có lượt	Danh sách rỗng	N/A
Error	API lỗi	"Không tải được danh sách đợt quét"	N/A
Disabled	Đang tải	Ô lọc vô hiệu	N/A

Fields

Field	Required	Type	Default	Format	Validation	Error Message	Visibility	Depends On
run_type	No	Dropdown	"— Tất cả —"	6 giá trị BR-10	enum	—	Always	—
limit	No	Number	50	1–200	BR-04	13041	Always	—
from / to	No	Date	—	YYYY-MM-DD	—	—	Always	—

Filter / Search / Sort

Loại	Theo field	Kiểu	Default	Notes
Filter	run_type	dropdown	Tất cả	BR-10
Filter	from / to	date range	—
Search	—	—	—	Không có
Sort	—	—	Thứ tự SAP service trả
Pagination	limit / offset	Number	50 / 0

Actions

A1 - Tải danh sách đợt quét

Item	Description
Trigger	Mở màn / đổi bộ lọc
Behavior	POST /api/v1/sapp/<env>/sap-log/scan-runs (ký HMAC). Chỉ đọc SAP service; không ghi
Success Result	Danh sách lượt quét với counters

Error cases:

Case	Expected Handling
SAP service lỗi	13039 "Failed to get SAP revenue scan runs"
Thiếu cấu hình	13037

Acceptance Criteria của màn M2

AC-M2.1 - Lọc theo loại lượt

Given có lượt WEEKLY và MANUAL_TEST
When chọn run_type = MANUAL_TEST
Then chỉ hiện lượt MANUAL_TEST

Maps to:

• Business Rule: BR-10

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

ID	Tình huống	Hành vi mong đợi
EC-M2.1	Vừa bắn quét thủ công, danh sách chưa có lượt mới	Hành vi đúng thiết kế: quét chạy bất đồng bộ — đọc lại sau (BR-12)

Màn M3 - Chạy lượt quét doanh thu (quét thủ công)

Field	Value
Figma frame	N/A — as-built, không có Figma
Trigger vào màn	Trong sapp.010: tab "Chạy lượt quét", hoặc bước scan của flow phase 2
Mô tả ngắn	"Bắn một lượt quét doanh thu NGAY, bỏ điều kiện chỉ-chạy-Thứ-7 của lượt quét tuần. Cửa sổ phủ tới HẾT HÔM NAY…" (fe/src/ui/components/works/sapp/sapp-26878-manual-scan.tsx:16)

UI States

State	Khi nào	Hiển thị	Figma frame
Default	Chưa bắn	Nút "Chạy lượt quét ngay"	N/A
Loading	Đang bắn	"Đang bắn lượt quét…"	N/A
Has data (queued)	triggered=true	"Đã đưa lượt quét vào hàng đợi" + "⚠ Mới là vào hàng đợi, chưa phải quét xong…"; nút thành "Chạy lại"	N/A
Has data (tắt)	triggered=false	"Nghiệp vụ đang TẮT — không có lượt quét nào chạy" + "SAP_REVENUE_RECOGNITION_ENABLED đang bằng false. Đây là công tắc rollback, không phải lỗi…"	N/A
Error	Lỗi	"Không chạy được lượt quét" (+ "Nhịp chặn tối thiểu 1 giây giữa hai lượt…" khi 429)	N/A
Disabled	Môi trường prod	"Lượt quét thủ công không chạy trên production — đúng thiết kế."	N/A

Nguồn: fe/src/ui/components/works/sapp/sapp-26878-step-scan.tsx:95-166.

Fields

N/A — màn chỉ có nút, không có field nhập.

Filter / Search / Sort

N/A — không phải màn List.

Actions

A1 - Chạy lượt quét ngay

Item	Description
Trigger	Bấm "Chạy lượt quét ngay" / "Chạy lại"
Behavior	GET /api/v1/sapp/<dev|staging>/sap-log/manual-scan (không ký). SAP service đưa một lượt quét vào hàng đợi trên dev hoặc staging; lượt quét ghi sổ doanh thu phía SAP service của môi trường đó. Không có đường ghi PROD (BR-11)
Success Result	Một trong hai kết quả bình thường của BR-12

Error cases:

Case	Expected Handling
Hai lượt cách nhau < 1 giây	13051
SAP service trả 403	13050
Lỗi khác	13052 kèm thông điệp gốc

Acceptance Criteria của màn M3

AC-M3.1 - Vào hàng đợi

Given môi trường staging, nghiệp vụ đang bật
When bấm "Chạy lượt quét ngay"
Then hiện "Đã đưa lượt quét vào hàng đợi" kèm cảnh báo chưa phải quét xong
And lượt mới xuất hiện ở M2 khi SAP service xử lý xong

Maps to:

• Business Rule: BR-12, BR-14

AC-M3.2 - Nghiệp vụ tắt không phải lỗi

Given SAP_REVENUE_RECOGNITION_ENABLED = false ở SAP service dev
When bấm "Chạy lượt quét ngay"
Then hiện "Nghiệp vụ đang TẮT — không có lượt quét nào chạy" (không phải hộp lỗi)

Maps to:

• Business Rule: BR-12

AC-M3.3 - Prod bị chặn

Given người dùng chọn prod
When mở màn quét thủ công
Then thấy "Lượt quét thủ công không chạy trên production — đúng thiết kế."
And gọi thẳng dịch vụ với prod thì bị từ chối 13050; không có route prod

Maps to:

• Business Rule: BR-01, BR-11

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

ID	Tình huống	Hành vi mong đợi
EC-M3.1	Bấm hai lần liền nhau	Lượt hai: 13051 "Manual sweeps must be at least 1 second apart"
EC-M3.2	⚠️ Observed — SAP service trả 403 vì lý do khác prod	Vẫn báo mã 13050 "…cannot run against production" (kèm thông điệp gốc) — be/libs/modules/src/lib/sapp/sap-log.common.service.ts:249-254; OQ-P-22
EC-M3.3	Thiếu SAPP_SAP_API_URL_DEV	13037

5. Cross-feature AC

AC-X.1 - 26878 dùng lại màn, không mô tả lại

Given FS 26878 có bước trace / scan trong flow và tab Trace / Chạy lượt quét
When đặc tả các bước đó
Then FS 26878 tham chiếu US-P05 cho hành vi tra vết, đợt quét, quét thủ công

Maps to:

• REL-05 (Be Affected - FS 26878)

AC-X.2 - Phụ thuộc SAP service

Given lượt quét tuần do cron ở SAP service (ngoài mind_keep) chạy
When SAP service không chạy hoặc công tắc nghiệp vụ tắt
Then mind_keep chỉ phản ánh kết quả SAP service trả về

Maps to:

• REL-08 (Affects - SAP service)