Giao diện
US-P07: Thêm option vào property danh sách của HubSpot dev ​
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-P07 |
| Role thực hiện | R1 - Người dùng tool (qua sub-tool sapp.010 — SAPP 26878, bước option của flow phase 2) — 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 — xem Overview §5 |
| OQ liên quan | OQ-P-01, OQ-P-03 — xem Overview §6 |
Nguồn inventory: A-17.
Sub-tool đang dùng dịch vụ này (Fact): chỉ sapp.010 (FS 26878) — bước loại option ("Thêm option vào N property") trong flow phase 2, dùng để thêm mã lớp Ops vừa tạo vào các property danh sách của Deal / Contact (fe/src/ui/components/works/sapp/sapp-26878-step-option.tsx:28-47, :80-95) → FS 26878 US-D03.
1. US Statement ​
text
As a Người dùng tool (qua sub-tool 26878) [Assumption — OQ-P-13 / G-01]
I want thêm một giá trị mới (vd mã lớp vừa tạo) vào danh sách lựa chọn của một property Deal / Contact trên portal HubSpot dev
So that [Assumption] bước sau ghi được giá trị đó lên Deal / Contact (property dạng danh sách từ chối giá trị ngoài danh sách)2. Dependencies & Definition Of Ready ​
N/A — đã triển khai (Mode B).
Dependency runtime: SAPP_DEV_HUBSPOT_ACCESS_TOKEN (US-P04); property đích tồn tại trên portal dev.
3. Business Rules ​
| ID | Rule | Áp dụng ở | Đã cover bởi (AC) | Nguồn code (Mode B/C) |
|---|---|---|---|---|
| BR-01 | Chỉ chạy trên portal HubSpot dev: chỉ có route dev cho Deal và Contact; không có route staging/prod | M1 | AC-M1.4 | be/apps/api/src/sapp/sapp.controller.ts:821-846, :1101-1106 |
| BR-02 | value bắt buộc (bỏ khoảng trắng đầu/cuối); rỗng → lỗi 13047 "Property option requires a non-empty value". label không nhập thì bằng value | M1 - field value | AC-M1.1, EC-M1.1 | be/libs/modules/src/lib/hubspot/common.service.ts:722-731 |
| BR-03 | Property không tồn tại → 12003 "HubSpot property not found"; property không phải dạng danh sách → 13048 (không đổi kiểu property) | M1 | EC-M1.2, EC-M1.3 | be/libs/modules/src/lib/hubspot/common.service.ts:733-753 |
| BR-04 | Option đã có (trùng value) → không thêm, trả added=false kèm số option hiện có | M1 | AC-M1.2 | be/libs/modules/src/lib/hubspot/common.service.ts:755-762 |
| BR-05 | Thêm option = gửi lại toàn bộ danh sách option cũ (giữ nguyên nhãn, thứ tự, ẩn/hiện) + option mới ở cuối | M1 | AC-M1.1 | be/libs/modules/src/lib/hubspot/common.service.ts:764-789 |
| BR-06 | HubSpot giữ danh sách option riêng cho từng loại đối tượng: property cùng tên ở Deal và Contact phải thêm riêng | M1 | AC-M1.3 | be/apps/api/src/sapp/sapp.controller.ts:1101-1106 |
| BR-07 | HubSpot từ chối cập nhật → 13049 "Failed to add HubSpot property option" | M1 | EC-M1.4 | be/libs/modules/src/lib/hubspot/common.service.ts:790-811 |
4. Design ​
a. Mối liên hệ giữa các màn & User Flow ​
text
[FS 26878 · bước option] (giá trị = mã lớp từ bước trước)
↓ "Thêm option vào N property"
[M1: Dịch vụ thêm option] POST /api/v1/sapp/dev/hubspot/{deals|contacts}/properties/<property>/options
├─ added=true → "Đã thêm option mới"
├─ added=false → "Option đã có sẵn — không tạo thêm bản thứ hai"
└─ lỗi → 13047 / 12003 / 13048 / 13049b. Chi tiết từng màn ​
Màn M1 - Dịch vụ thêm option property (gọi từ bước option của sub-tool 26878) ​
| Field | Value |
|---|---|
| Figma frame | N/A — as-built, không có Figma |
| Trigger vào màn | Bước option trong flow phase 2 của sapp.010 |
| Mô tả ngắn | Không có màn riêng ở nền tảng — dịch vụ API; UI bước do FS 26878 đặc tả |
UI States ​
N/A — dịch vụ không có màn riêng; UI của bước (kết quả "Đã thêm option mới" / "Option đã có sẵn…", cảnh báo staging phải làm tay) thuộc FS 26878 (fe/src/ui/components/works/sapp/sapp-26878-step-option.tsx:120-215).
Fields ​
| Field | Required | Type | Default | Format | Validation | Error Message | Visibility | Depends On |
|---|---|---|---|---|---|---|---|---|
| object (đường dẫn) | Yes | deals / contacts | — | — | Chỉ 2 route (BR-01) | 404 nếu khác | — | — |
| property (đường dẫn) | Yes | Text | — | tên nội bộ property | Phải tồn tại, dạng danh sách (BR-03) | 12003 / 13048 | — | — |
| value | Yes | Text | — | — | Không rỗng sau trim (BR-02) | 13047 | — | — |
| label | No | Text | = value | — | — | — | — | value |
| description | No | Text | — | — | — | — | — | — |
| displayOrder | No | Number | -1 (HubSpot tự đánh số) | — | — | — | — | — |
| hidden | No | Boolean | false | — | — | — | — | — |
Nguồn: be/libs/interface/src/lib/dto/hubspot/hubspot-property.dto.ts:70-92.
Filter / Search / Sort ​
N/A — không phải màn List.
Actions ​
A1 - Thêm option ​
| Item | Description |
|---|---|
| Trigger | Bước option được chạy (mỗi property một lời gọi) |
| Behavior | Đọc property, kiểm BR-02…BR-04, gửi lại toàn bộ danh sách (BR-05). Ghi định nghĩa property trên portal HubSpot dev; không có đường ghi staging/PROD |
| Success Result | { property, added, optionCount } |
Error cases:
| Case | Expected Handling |
|---|---|
| value rỗng | 13047 |
| Property không có / không phải danh sách | 12003 / 13048 |
| HubSpot từ chối | 13049 |
| Thiếu token dev | 12001 |
Acceptance Criteria của màn M1 ​
AC-M1.1 - Thêm option mới, giữ option cũ ​
gherkin
Given property deal "lop_dang_ky" trên dev có 5 option
When thêm value "ACCA.F2.2609.NEU.01" (không nhập label)
Then property có 6 option: 5 option cũ giữ nguyên + option mới ở cuối, label = value
And kết quả added = true, optionCount = 6Maps to:
- Business Rule: BR-02, BR-05
AC-M1.2 - Idempotent theo value ​
gherkin
Given option "ACCA.F2.2609.NEU.01" đã có
When thêm lại cùng value
Then không thay đổi gì, added = falseMaps to:
- Business Rule: BR-04
AC-M1.3 - Deal và Contact tách riêng ​
gherkin
Given đã thêm option vào deals.lop_dang_ky
When kiểm tra contacts.lop_dang_ky
Then contact chưa có option đó cho tới khi gọi route contactsMaps to:
- Business Rule: BR-06
AC-M1.4 - Chỉ dev ​
gherkin
Given người dùng chọn staging trong sub-tool 26878
When tới bước option
Then không có route staging/prod để gọi; FS 26878 hướng dẫn làm tay trên HubSpotMaps to:
- Business Rule: BR-01
Negative AC / Edge Cases của màn M1 ​
| ID | Tình huống | Hành vi mong đợi |
|---|---|---|
| EC-M1.1 | value = " " | 13047 |
| EC-M1.2 | Property không tồn tại | 12003 |
| EC-M1.3 | Property dạng text/số | 13048, property không bị đổi |
| EC-M1.4 | HubSpot trả lỗi khi cập nhật | 13049 |
| EC-M1.5 | FE khai báo được loại đối tượng tickets cho route này (fe/src/data/constants/api.ts:192-195) | BE không có route tickets → gọi sẽ không tìm thấy route; hiện 26878 chỉ dùng deals/contacts |
| EC-M1.6 | ⚠️ Observed — Route public, không cần đăng nhập | Ai gọi được API đều sửa được định nghĩa property portal dev (NFR-P-01, OQ-P-01) |
5. Cross-feature AC ​
AC-X.1 - Lý do staging phải làm tay ​
gherkin
Given staging HubSpot dùng credential portal prod (NFR-P-03)
When 26878 chạy flow phase 2 trên staging
Then bước option không gọi dịch vụ này; người dùng thêm option tay rồi bỏ qua bước (FS 26878)Maps to:
- REL-05 (Be Affected - FS 26878)