BA Docs

Giao diện

[BRD] SAPP Works tools (as-built, tóm tắt) ​

Reconstructed from code @ e77c47a — dựng lại từ 7 FS as-built và 7 inventory của project này, không phải từ yêu cầu gốc. Hành vi là Fact có bằng chứng (ở FS); mục tiêu, đối tượng và KPI là Assumption cho tới khi BA trả lời G-01 / G-05. BRD chỉ nêu tool phải làm được gì; cơ chế và hành vi chi tiết nằm ở FS.

FieldValue
Created Date30 Sep 2026
Epic / TicketSAPP-20603 · SAPP-23954 · SAPP-24395 · SAPP-26297 · SAPP-26878 · HubSpot common tools
Document OwnerAI (lane ba/) — BA review
Versionv0.1
StatusDraft

Record Of Changes ​

Effective DateUpdate PersonA/M/DChange DescriptionVersion
30 Sep 2026AI (lane ba/)ADựng lại từ code @ e77c47a (Mode B, sau Gate R1)v0.1

A = Add, M = Modify, D = Delete

Definitions And Acronyms ​

#TermDefinition
1Sub-toolMột công cụ trong workspace /works/sapp/tools, có mã cố định sapp.001…sapp.013
2Portal / môi trườngprod · staging · dev của hệ ngoài. HubSpot staging dùng portal production (cố ý, không có portal staging riêng)
3SAPP OpsHệ thống vận hành đào tạo của SAPP (lớp, học viên, đơn hàng, giao dịch)
4eContractHệ thống hợp đồng điện tử của SAPP; cron gọi nhà cung cấp EFY/FPT
5DTTHDoanh thu thực hiện — ghi nhận doanh thu theo buổi học (SAPP-26878 phase 2)
6FixtureBộ id dùng chung cho mọi bước của một lượt test (26297)
7Flow / runMột kịch bản test nhiều bước (26878) và một lần chạy kịch bản đó
8Ghi PRODThao tác làm thay đổi dữ liệu trên môi trường production của hệ ngoài

I. Project Objectives ​

Thực trạng ​

  • Kiểm thử và vận hành các ticket SAPP đòi hỏi thao tác trên nhiều hệ thống cùng lúc (HubSpot, SAPP Ops REST + DB, SAP service, eContract DB, LMS) theo đúng thứ tự và đúng môi trường; làm tay thì phải tự nhớ thứ tự, cầm credential hệ ngoài và tự so từng mã lỗi. (Fact: bối cảnh ghi trong FS 26878 §1.1, FS 26297 §1.1, trích runbook và sổ trao đổi SAPP.)
  • Một số việc vận hành (điều tra hợp đồng điện tử lỗi, gán lại owner ticket) trước đây cần dev truy cập DB / portal production. (Fact từ FS 20603 §1.1; FS 23954 — Assumption.)
  • Cụm tool đã triển khai đủ 13 sub-tool nhưng chưa có tài liệu nghiệp vụ; tài liệu hiện có là API doc cho dev (shared/api-docs/sapp.md) và đã lệch code ở 61 điểm (Gate R1).

Mục tiêu ​

[Assumption — G-05 chưa trả lời]

  • Cho đội làm ticket SAPP một chỗ duy nhất để dựng dữ liệu test, chạy kịch bản nghiệm thu và tra cứu trên các hệ SAPP theo đúng môi trường, không phải cầm credential hệ ngoài.
  • Rút ngắn thời gian điều tra / xử lý sự cố vận hành (eContract lỗi, ticket thiếu owner) mà không cần dev truy cập production.
  • Mục tiêu riêng của dự án DTTH (Fact, trích nguồn SAPP): ghi nhận doanh thu theo buổi học thay vì một lần khi thu tiền (FS 26878 §1.2).

II. Project Scope ​

1. In-scope Functionality ​

  • 13 sub-tool sapp.001…sapp.013 và workspace chung /works/sapp/tools, chia 6 nhóm + nền tảng:

    NhómSub-toolFS
    Nền tảng dùng chunghub, khoá tool, cấu hình hệ ngoài, 5 dịch vụ chungsapp-platform
    HubSpotsapp.001–004sapp-hubspot
    SAPP-20603 eContractsapp.005, 012, 013sapp-20603
    SAPP-24395sapp.006, 007sapp-24395
    SAPP-23954sapp.008, 009sapp-23954
    SAPP-26878sapp.010sapp-26878
    SAPP-26297sapp.011sapp-26297

  • Quản trị trạng thái tool (bật / ẩn / khoá) và cấu hình kết nối hệ ngoài theo môi trường, trong CMS.

2. Out of scope Functionality ​

  • Hành vi bên trong các hệ ngoài (HubSpot workflow, SAP, SAPP Ops, LMS, eContract cron): chỉ mô tả cách tool gọi và hiểu kết quả.
  • Workspace /works/naucode-kahrs (dùng chung cổng chặn nhưng ngoài dự án).
  • Mọi thay đổi / cải tiến tool — tài liệu này mô tả hiện trạng; thay đổi đi theo Mode C.

III. Detail Requirement ​

1. Functional Requirement ​

FR1: Truy cập và điều khiển cụm tool ​

Người dùng mở workspace, chọn tool qua sidebar; Admin CMS đặt trạng thái từng tool và nhóm tool, và cấu hình kết nối hệ ngoài theo môi trường.

Business Rules

  • Tool đang tắt, ẩn hoặc khoá không được dùng; tool khoá chỉ mở bằng mã bí mật Admin đặt.
  • Khi không đọc được trạng thái tool, mọi tool coi như đóng (không mở khi không chắc).
  • Credential hệ ngoài chỉ nằm ở backend; trình duyệt không bao giờ cầm.

Expected Behavior → FS nền tảng US-P01…US-P04.

FR2: Tra cứu và đồng bộ cấu hình HubSpot giữa prod và dev ​

Người dùng tra định nghĩa property, xem lịch sử giá trị property của một bản ghi, xem pipeline / stage, và đưa property / pipeline từ prod sang dev (hoặc nhân bản pipeline trong cùng portal).

Business Rules

  • Đồng bộ prod → dev không được ghi đè định nghĩa đang có ở dev.
  • Nhân bản pipeline được phép trên cả portal prod (hiện trạng — cố ý hay không: OQ-H-03).

Expected Behavior → FS HubSpot US-H01…US-H06.

FR3: Điều tra và chạy lại luồng hợp đồng điện tử (SAPP-20603) ​

Người dùng xem flow process và timeline hợp đồng của một deal, thống kê lỗi theo thời gian, và chạy lại các flow lỗi trên production.

Business Rules

  • Chỉ flow đang FAIL và còn lượt retry mới được đặt lại; một số trạng thái lỗi bị từ chối retry.
  • Retry phải được người dùng xác nhận, liệt kê rõ dòng sẽ đặt lại.
  • Dữ liệu nhạy cảm (token nhà cung cấp) được che; không export; file hợp đồng không bấm mở được (điều kiện SAPP).

Expected Behavior → FS 20603 US-E01…US-E06.

FR4: Dựng dữ liệu test HubSpot và product Ops (SAPP-24395) ​

Người dùng tạo contact và deal mẫu theo 14 deal case trên HubSpot, và tạo hàng loạt payment product trên SAPP Ops theo phiên nhiều bước có thể khôi phục.

Business Rules

  • Deal case quyết định pipeline, stage và các trường riêng của deal.
  • Contact trùng email được dùng lại (hiện trạng: cập nhật đè — OQ-I-05).
  • Phiên bulk product hết hạn sau một khoảng không hoạt động; hết hạn phải bắt đầu lại.

Expected Behavior → FS 24395 US-I01…US-I06.

FR5: Gán lại owner ticket HubSpot (SAPP-23954) ​

Người dùng truy vấn ticket theo pipeline / owner / ngày, làm mới hàng loạt thuộc tính kích hoạt automation gán owner, kiểm tra kết quả, xem lịch sử làm mới, và chạy thử chỉ-đọc logic gán owner cho một ticket.

Business Rules

  • Làm mới hàng loạt phải được xác nhận trước khi chạy.
  • Lịch sử làm mới được giữ có thời hạn.

Expected Behavior → FS 23954 US-T01…US-T05.

FR6: Chạy kịch bản nghiệm thu nhiều hệ thống (SAPP-26878, SAPP-26297) ​

Người dùng chạy kịch bản test theo từng bước có hướng dẫn: 14 flow của dự án doanh thu thực hiện (26878) và 9 luồng / 78 case của chuyển nhượng học viên (26297); mỗi bước gọi hệ ngoài, chạy câu SQL đã duyệt, hoặc hướng dẫn làm tay; kết quả được tự chấm.

Business Rules

  • Chỉ chạy câu SQL đã lập danh mục trên DB dev / staging; không nhận SQL tự do; không có đường production.
  • Kịch bản 26297 không có route production cho Ops / LMS / SQL (HubSpot "staging" là portal prod — OQ-S-19).
  • Một lượt chạy có thể dừng và tiếp tục; lịch sử lượt chạy được giữ có thời hạn.

Expected Behavior → FS 26878 US-D01…US-D18, FS 26297 US-S01…US-S10; dịch vụ chung US-P05…US-P09.

2. Non-functional Requirement ​

  • Phân quyền (hiện trạng, cần quyết định): mọi API /api/v1/sapp/* (259 route) không yêu cầu đăng nhập, kể cả route ghi production; khoá tool chỉ có hiệu lực ở giao diện (NFR-P-01, NFR-P-02; G-02).
  • An toàn production: có chốt chặn thật cho SQL, quét doanh thu, callback SAP, thêm option property; các đường ghi production còn lại được liệt kê ở mỗi FS với nhãn ⚠️ Ghi PROD.
  • Truy vết: không có nhật ký ai đã chạy thao tác ghi production nào (OQ-E-03); lịch sử run / làm mới chỉ lưu tạm (OQ-D-17).
  • Đúng môi trường: mỗi thao tác phải hiển thị rõ môi trường đang chọn trước khi ghi.

IV. Assumptions ​

  • Người dùng là "người dùng tool" nội bộ (đội làm ticket SAPP / vận hành) — chưa xác nhận (G-01).
  • Mục tiêu ở §I là suy luận từ hành vi tool và nguồn SAPP có trích dẫn — chưa xác nhận (G-05).
  • Tool dùng cho kiểm thử và vận hành nội bộ, không phục vụ học viên / khách hàng trực tiếp.

V. Constraints ​

  • Tài liệu chỉ viết trong source (ba/); không đọc / ghi Jira hay Confluence (quyết định dự án).
  • Hành vi đúng tại commit e77c47a; code đổi sau đó → cập nhật theo Update mode của /document-existing.
  • Phụ thuộc hệ ngoài của SAPP: một số luồng đang chặn chờ SAPP (26878 US-09 sign-callback, 26297 luồng 4–5).

VI. Success Criteria ​

[Assumption — G-05]

  • Người mới đọc FS hiểu được mỗi tool làm gì, ghi vào đâu, môi trường nào — không cần hỏi dev.
  • Mọi thao tác ghi production được liệt kê và có quyết định "cố ý / cần sửa" từ BA.
  • FS as-built được duyệt ở Gate R2 và dùng làm baseline cho thay đổi sau (Mode C).

VII. Open Questions ​

IDQuestionOwnerDue DateStatus
G-01Ai dùng cụm tool /works/sapp? (OQ-P-13, OQ-H-01, OQ-E-04, OQ-I-16, OQ-D-05, OQ-S-01)BA—Open
G-02259 route không cần đăng nhập, gồm ghi prod: cố ý hay nợ bảo mật? (OQ-P-01, NFR-P-01)BA / Tech—Open
G-03Các thao tác ghi prod (HubSpot duplicate pipeline, 23954 refresh, eContract retry) có cố ý? (OQ-H-03, OQ-T-03, OQ-E-02)BA—Open
G-04HubSpot "staging" = portal prod: chấp nhận ghi đè contact học viên thật? (OQ-I-05, OQ-D-16, OQ-S-19)BA—Open
G-05Mục tiêu nghiệp vụ và KPI của từng nhóm toolBA—Open
G-06Các lỗi nghi ngờ suy từ code có cần chạy thử để xác nhận? (OQ-I-09, OQ-D-04, OQ-S-*)BA—Open
G-07Chi tiết 26878: log re-sync, "deal có sẵn", history phase 2, trả mã lớp (OQ-D-01, 03, 06, 07)BA—Open
G-08Luồng đang bị chặn bởi SAPP (OQ-D-08, OQ-S-10)BA / SAPP—Open
G-09Cấu hình môi trường Ops của bulk product, trạng thái tool trên prod (OQ-I-04, OQ-P-*)BA—Open
G-10Có đặc tả gốc của các ticket để đối chiếu AC/BR? (OQ-D-13)BA—Open

Chi tiết từng câu và các OQ không chặn: working/ai-drafts/gate-r1-summary-20260930.md và §6 của mỗi FS.

VIII. Reference ​

  • 7 FS as-built: ../fs/*-as-built-v0.1-20260930/
  • Inventory + Gate R1: ../../working/ai-drafts/feature-inventory-*-20260930.md, gate-r1-summary-20260930.md
  • Danh sách US (R2): ../../working/ai-drafts/us-backlog-r2-20260930.md
  • API doc: shared/api-docs/sapp.md; trao đổi SAPP: shared/external/sapp/; runbook: shared/runbooks/sapp/