US-H01: Tra định nghĩa một property

Thuộc FS: 00-overview.md — SAPP HubSpot tools (sapp.001–004) 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. As-built tại commit e77c47a. Nguồn: inventory A-01, A-02, A-11.

Field	Value
US ID	US-H01
Role thực hiện	R1 - Người dùng tool (Assumption — OQ-H-01 về G-01)
Phase	As-built (đã triển khai)
Priority	N/A — as-built
Status	Draft
NFR liên quan	NFR-H-01, NFR-H-02, NFR-H-03, NFR-H-04, NFR-H-05 — xem Overview §5
OQ liên quan	OQ-H-01, OQ-H-04, OQ-H-06, OQ-H-11 — xem Overview §6

1. US Statement

As a Người dùng tool  [Assumption — OQ-H-01 về G-01]
I want chọn portal (Prod / Dev) và loại object, nhập internal name của một property rồi xem định nghĩa của nó (type, field type, group, description, options, JSON gốc)
So that [Assumption — OQ-H-04] kiểm tra nhanh cấu hình property trên HubSpot mà không cần vào trang quản trị HubSpot

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	Tool sapp.003 đang bật / hiển thị / đã mở khoá — US-P02	Admin CMS	Runtime
D2	env_systems: SAPP_PROD_HUBSPOT_ACCESS_TOKEN (Prod), SAPP_DEV_HUBSPOT_ACCESS_TOKEN (Dev) — US-P04	Admin CMS	Runtime

3. Business Rules

ID	Rule	Áp dụng ở	Đã cover bởi (AC)	Nguồn code (Mode B/C)
BR-01	Người dùng chọn portal Prod hoặc Dev (mặc định Prod) và loại object Deal / Ticket / Contact (mặc định Deal)	M1 - field Environment, Object type	AC-M1.1	fe/src/ui/components/works/sapp/property-tool.tsx:25-34,52-53
BR-02	Phải nhập tên property (sau khi cắt khoảng trắng hai đầu) mới được tra cứu; thiếu → popup "Missing property name", không gọi API	M1 - action A1	AC-M1.2	fe/src/ui/components/works/sapp/property-tool.tsx:95-104
BR-03	Tra cứu chỉ đọc portal đã chọn; không ghi gì vào HubSpot	M1 - action A1	AC-M1.1	be/libs/modules/src/lib/hubspot/common.service.ts:489-507; be/libs/services/src/lib/hubspot/hubspot.service.ts:75-83
BR-04	Kết quả hiện: tên (internal name), label, Type, Field type, Group, Description (ô trống hiện "—"); bảng options (Label / Value / Order / Hidden) chỉ hiện khi property có option; khối "Raw JSON" với nút "Copy JSON"	M1 - state Has data	AC-M1.1, AC-M1.3	fe/src/ui/components/works/sapp/property-tool.tsx:36-47,170-237
BR-05	Mỗi lần bấm tra cứu, kết quả cũ bị xoá trước khi gọi	M1 - action A1	AC-M1.4	fe/src/ui/components/works/sapp/property-tool.tsx:105
BR-06	Portal chưa cấu hình token → lỗi 12001 "HubSpot access token is not configured for this environment"	M1 - action A1	EC-M1.2	be/libs/modules/src/lib/hubspot/common.service.ts:47-58
BR-07	Lỗi gọi API → popup tiêu đề "Failed to fetch property", nội dung message (code) (NFR-H-04)	M1 - action A1	AC-M1.5	fe/src/ui/components/works/sapp/property-tool.tsx:72-86

⚠️ Observed (không phải BR): mọi lỗi HubSpot khi đọc property đều trả 12003 "HubSpot property not found" — xem EC-M1.1, OQ-H-06.

4. Design

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

[Sidebar "SAPP Common Hubspot Tools" → "Property"]  (US-P01, gate US-P02)
  ↓
[M1: Property info]
  ├─ thiếu tên ────────────→ popup "Missing property name", ở lại M1
  ├─ OK ───────────────────→ M1 state Has data (chi tiết + options + Raw JSON)
  └─ API lỗi ──────────────→ popup "Failed to fetch property", ở lại M1

Link flow chi tiết: N/A — as-built, không có Figma.

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

Màn M1 - Property info

Field	Value
Figma frame	N/A
Trigger vào màn	Mở /works/sapp/tools/hs-get-property (sidebar "Property") hoặc link chia sẻ
Mô tả ngắn	Tiêu đề "Property info"; mô tả "Inspect a deal / ticket / contact property definition — its type, field type and enumeration options — from either portal." (fe/src/ui/components/works/sapp/property-tool.tsx:111-124)

UI States

State	Khi nào	Hiển thị	Figma frame
Default	Vừa vào màn	Hàng form: Environment = Prod, Object type = Deal, ô "Property internal name" trống (placeholder "e.g. dealstage"), nút "Get property". Chưa có vùng kết quả	N/A
Loading	Đang gọi API	Nút đổi thành "Fetching…"; cả nút, hai ô chọn và ô nhập bị khoá (NFR-H-05)	N/A
Has data	API trả property	Dòng tên + label; 4 ô Type / Field type / Group / Description; bảng options (nếu có); khối Raw JSON + "Copy JSON"	N/A
Empty	Property không có option	Không hiện bảng options; các phần khác vẫn hiện	N/A
Error	API lỗi / thiếu tên	Popup lỗi (BR-02, BR-07); vùng kết quả trống	N/A
Disabled	Đang gọi API	Như Loading	N/A

Fields

Field	Required	Type	Default	Format	Validation	Error Message	Visibility	Depends On
Environment	Yes	Dropdown: Prod / Dev	Prod	—	BR-01	—	Always	—
Object type	Yes	Dropdown: Deal / Ticket / Contact	Deal	—	BR-01	—	Always	—
Property internal name	Yes	Text	Trống	Cắt khoảng trắng hai đầu trước khi gửi	BR-02	"Missing property name" — "Please enter the HubSpot internal property name."	Always	—
Kết quả: name, label, Type, Field type, Group, Description	—	Readonly text	—	Trống → "—"	—	—	Sau khi tra thành công	BR-04
Kết quả: bảng options (Label, Value, Order, Hidden)	—	Readonly table	—	Order trống → "—"; Hidden → "yes" / "no"	—	—	Chỉ khi có ≥ 1 option	BR-04
Kết quả: Raw JSON	—	Readonly JSON	—	JSON thụt lề 2	—	—	Sau khi tra thành công	BR-04

Filter / Search / Sort

N/A — màn tra cứu một bản ghi, không phải List / Report.

Actions

A1 - Get property

Item	Description
Trigger	Bấm "Get property" hoặc nhấn Enter trong ô tên property (fe/src/ui/components/works/sapp/property-tool.tsx:153,160-167)
Behavior	Kiểm BR-02 → xoá kết quả cũ (BR-05) → gọi GET /api/v1/sapp/{prod|dev}/hubspot/{deals|contacts|tickets}/properties/:property. Đọc HubSpot portal đã chọn (Prod → portal prod, Dev → portal dev); không ghi hệ thống nào (BR-03)
Success Result	M1 chuyển Has data (BR-04)

Error cases:

Case	Expected Handling
Thiếu tên property	Popup "Missing property name" (BR-02), không gọi API
Token môi trường chưa cấu hình	Popup "Failed to fetch property" — "HubSpot access token is not configured for this environment (12001)" (BR-06)
Property không tồn tại / mọi lỗi HubSpot khác	Popup "Failed to fetch property" — "HubSpot property not found (12003)" (⚠️ Observed — EC-M1.1)

A2 - Copy JSON

Item	Description
Trigger	Bấm "Copy JSON" ở khối Raw JSON
Behavior	Chép JSON property (thụt lề 2) vào clipboard trình duyệt; không gọi API, không ghi hệ thống nào (fe/src/ui/components/works/sapp/property-tool.tsx:224-232)
Success Result	Clipboard chứa JSON. Không có thông báo xác nhận

Error cases:

Case	Expected Handling
Trình duyệt chặn clipboard	Không có xử lý riêng trong code — không hiện thông báo

Acceptance Criteria của màn M1

AC-M1.1 - Tra cứu thành công

Given tool sapp.003 mở được và portal Dev có property "dealstage" của Deal
When người dùng chọn Environment = Dev, Object type = Deal, nhập "  dealstage  " và bấm "Get property"
Then hệ thống chỉ đọc portal dev với tên "dealstage" (đã cắt khoảng trắng)
And hiện tên "dealstage", label, Type, Field type, Group, Description, bảng options và Raw JSON
And không có dữ liệu nào trên HubSpot bị thay đổi

Maps to:

• Business Rule: BR-01, BR-03, BR-04
• Field/Action: Environment, Object type, Property internal name / A1

AC-M1.2 - Thiếu tên property

Given ô "Property internal name" trống hoặc chỉ có khoảng trắng
When người dùng bấm "Get property"
Then hiện popup "Missing property name" với nội dung "Please enter the HubSpot internal property name."
And không có lời gọi API nào

Maps to:

• Business Rule: BR-02

AC-M1.3 - Property không có option

Given property tra cứu không có option nào (vd kiểu text)
When tra cứu thành công
Then không hiện bảng options
And các ô trống (vd Description) hiện "—"
And khối Raw JSON vẫn hiện kèm nút "Copy JSON"

Maps to:

• Business Rule: BR-04

AC-M1.4 - Tra lại xoá kết quả cũ

Given M1 đang hiện kết quả của property A
When người dùng nhập property B và bấm "Get property"
Then kết quả của A biến mất ngay khi bắt đầu gọi
And nếu B lỗi thì vùng kết quả để trống

Maps to:

• Business Rule: BR-05

AC-M1.5 - Popup lỗi thống nhất

Given API trả lỗi có mã
When người dùng bấm "Get property"
Then hiện popup tiêu đề "Failed to fetch property", nội dung "<message> (<code>)"

Maps to:

• Business Rule: BR-07
• NFR: NFR-H-04

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

ID	Tình huống	Hành vi mong đợi
EC-M1.1	Token hỏng / hết hạn, HubSpot rate limit hoặc lỗi 5xx	⚠️ Observed — hành vi hiện tại: báo "HubSpot property not found (12003)", giống hệt trường hợp property không tồn tại (be/libs/modules/src/lib/hubspot/common.service.ts:500-505). Cố ý hay bug → OQ-H-06
EC-M1.2	Portal đã chọn chưa có token trong env_systems	Popup "Failed to fetch property" — "… not configured for this environment (12001)" (BR-06, NFR-H-02)
EC-M1.3	Đổi Environment / Object type sau khi đã có kết quả	Kết quả cũ vẫn hiện cho tới lần bấm "Get property" tiếp theo (kết quả chỉ xoá ở BR-05) (fe/src/ui/components/works/sapp/property-tool.tsx:105,129-144)
EC-M1.4	Cần tra môi trường Staging	Không có trên UI; chỉ API có biến thể staging (= prod) cho deals / contacts — Overview §2.2, OQ-H-11
EC-M1.5	Tên property sai hoa / thường	Gửi nguyên chuỗi đã cắt khoảng trắng; kết quả theo phản hồi HubSpot (thường là 12003) — chưa chạy thử

5. Cross-feature AC

AC-X.1 - Tool bị gate chặn

Given tool sapp.003 đang bị ẩn / tắt / khoá mã bí mật
When người dùng mở /works/sapp/tools/hs-get-property
Then hành vi theo gate của nền tảng (US-P02), màn M1 không dùng được
And API tra cứu vẫn gọi trực tiếp được (NFR-P-01)

Maps to:

• REL-H-01 (Affects - Hub + gate tool)

AC-X.2 - Token theo môi trường

Given Admin CMS đã xoá giá trị SAPP_DEV_HUBSPOT_ACCESS_TOKEN (US-P04)
When người dùng tra cứu với Environment = Dev
Then nhận lỗi 12001; tra với Environment = Prod vẫn hoạt động

Maps to:

• REL-H-02 (Affects - Cấu hình env_systems)