US-H04: Xem danh sách pipeline và stage

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-05, A-06 (và A-11 cho popup lỗi).

Field	Value
US ID	US-H04
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-04, NFR-H-05 — xem Overview §5
OQ liên quan	OQ-H-01, OQ-H-04, OQ-H-15 — 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 (Deal / Ticket), tải danh sách pipeline rồi xem các stage của một pipeline
So that [Assumption — OQ-H-04] đối chiếu cấu hình pipeline giữa hai portal trước khi clone hoặc nhân bản

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.004 đang bật / hiển thị / đã mở khoá — US-P02	Admin CMS	Runtime
D2	env_systems: token của portal đã chọn — 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	Pipeline chỉ có cho Deal và Ticket (không có Contact); portal Prod / Dev, mặc định Prod + Deal	M1 - field Environment, Object type	AC-M1.1	fe/src/ui/components/works/sapp/pipeline-tool.tsx:31-39,54-55; fe/src/data/models/sapp-hubspot.interface.ts:49-50
BR-02	Tải danh sách chỉ đọc portal đã chọn. Mỗi pipeline hiện: label, "order N" (thiếu → "—"), "N stages", id	M1 - action A1	AC-M1.1	be/libs/modules/src/lib/hubspot/common.service.ts:973-986; fe/src/ui/components/works/sapp/pipeline-tool.tsx:274-301
BR-03	Danh sách rỗng → "No pipelines found."	M1 - state Empty	AC-M1.2	fe/src/ui/components/works/sapp/pipeline-tool.tsx:271-273
BR-04	Mỗi lần tải lại danh sách, pipeline đang mở stage bị đóng	M1 - action A1	AC-M1.3	fe/src/ui/components/works/sapp/pipeline-tool.tsx:88-92
BR-05	Xem stage chỉ đọc; tại một thời điểm chỉ mở stage của một pipeline. Bảng Order / Label / Metadata (các cặp khoá: giá trị nối bằng " · "; deal: probability / isClosed, ticket: ticketState / isClosed); không có stage → "No stages"; kèm "Copy JSON"	M2 - state Has data	AC-M2.1, AC-M2.2	fe/src/ui/components/works/sapp/pipeline-tool.tsx:57,96-115,357-416; be/libs/modules/src/lib/hubspot/common.service.ts:1007-1025
BR-06	Nút "View stages" bị khoá nếu pipeline không có id	M1 - action A2	EC-M1.3	fe/src/ui/components/works/sapp/pipeline-tool.tsx:306-310
BR-07	Trong lúc bất kỳ thao tác pipeline nào đang chạy, mọi nút và ô chọn của màn bị khoá (NFR-H-05)	M1, M2	AC-M1.4	fe/src/ui/components/works/sapp/pipeline-tool.tsx:183-185,243,253,260,310
BR-08	Lỗi: tải danh sách lỗi → 12002, popup "Failed to load pipelines"; xem stage lỗi / không tìm thấy → 12007 "HubSpot pipeline not found", popup "Failed to load pipeline" (NFR-H-04)	M1 - action A1, A2	EC-M1.1, EC-M2.1	be/libs/modules/src/lib/hubspot/common.service.ts:979-984,1018-1023; fe/src/ui/components/works/sapp/pipeline-tool.tsx:87,111

⚠️ Observed (không phải BR): danh sách không làm mới khi đổi Environment / Object type — EC-M1.2, OQ-H-15.

4. Design

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

[Sidebar "SAPP Common Hubspot Tools" → "Pipeline"]  (US-P01, gate US-P02)
  ↓
[M1: Pipeline manager — danh sách]
  ↓ bấm "View stages" trên một pipeline
[M2: Bảng stage (mở ngay dưới pipeline đó)]
  ├─ "Clone to dev" (chỉ khi Prod) ──→ US-H05
  └─ "Duplicate" ────────────────────→ US-H06

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

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

Màn M1 - Pipeline manager (danh sách pipeline)

Field	Value
Figma frame	N/A
Trigger vào màn	Mở /works/sapp/tools/hs-pipeline (sidebar "Pipeline") hoặc link chia sẻ
Mô tả ngắn	Tiêu đề "Pipeline manager"; mô tả "List deal / ticket pipelines and inspect their stages. Clone a prod pipeline into dev (optionally under a new label), or duplicate one within the same portal under a new label. Existing pipelines are matched by label and never overwritten." (fe/src/ui/components/works/sapp/pipeline-tool.tsx:219-234)

UI States

State	Khi nào	Hiển thị	Figma frame
Default	Vừa vào màn	Environment = Prod, Object type = Deal, nút "Load pipelines". Chưa có danh sách	N/A
Loading	Đang tải danh sách	Nút "Loading…"; mọi nút / ô chọn bị khoá (BR-07)	N/A
Has data	Có pipeline	Mỗi pipeline 1 thẻ: label, "order N", "N stages", id; nút "View stages", "Clone to dev" (chỉ khi Prod — US-H05), "Duplicate" (US-H06)	N/A
Empty	Không có pipeline	"No pipelines found." (BR-03)	N/A
Error	API lỗi	Popup "Failed to load pipelines" (BR-08)	N/A
Disabled	Có thao tác đang chạy	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	Quyết định có nút "Clone to dev" (US-H05)
Object type	Yes	Dropdown: Deal / Ticket	Deal	—	BR-01	—	Always	—
Thẻ pipeline: label, order, số stage, id	—	Readonly	—	order thiếu → "—"; số stage chỉ hiện khi có dữ liệu stage	—	—	Sau khi tải	BR-02

Filter / Search / Sort

Loại	Theo field	Kiểu	Default	Notes
Filter	Environment, Object type	dropdown	Prod, Deal	Chỉ áp dụng khi bấm "Load pipelines" (EC-M1.2)
Search	—	—	—	N/A — không có ô tìm kiếm
Sort	—	—	Theo thứ tự HubSpot trả	Không có sắp xếp trên màn
Pagination	—	—	Không phân trang	Hiện toàn bộ kết quả HubSpot trả

Actions

A1 - Load pipelines

Item	Description
Trigger	Bấm "Load pipelines"
Behavior	Gọi GET /api/v1/sapp/{prod|dev}/hubspot/{deals|tickets}/pipelines. Đọc HubSpot portal đã chọn; không ghi. Thành công → thay danh sách, đóng stage đang mở (BR-04)
Success Result	M1 Has data / Empty

Error cases:

Case	Expected Handling
HubSpot lỗi	Popup "Failed to load pipelines" — "HubSpot API request failed (12002)"
Token chưa cấu hình	Popup … "(12001)" (NFR-H-02)

A2 - View stages

Item	Description
Trigger	Bấm "View stages" trên một thẻ pipeline
Behavior	Gọi GET /api/v1/sapp/{prod|dev}/hubspot/{deals|tickets}/pipelines/:pipelineId với môi trường / object đang chọn. Đọc, không ghi. Trong lúc gọi, mọi nút bị khoá (BR-07)
Success Result	Mở M2 ngay dưới thẻ; stage của pipeline mở trước (nếu có) bị đóng (BR-05)

Error cases:

Case	Expected Handling
Pipeline không tồn tại / lỗi	Popup "Failed to load pipeline" — "HubSpot pipeline not found (12007)"

Acceptance Criteria của màn M1

AC-M1.1 - Tải danh sách pipeline

Given portal dev có 2 pipeline Deal
When người dùng chọn Environment = Dev, Object type = Deal và bấm "Load pipelines"
Then hiện 2 thẻ, mỗi thẻ có label, "order N", "N stages" và id
And có nút "View stages" và "Duplicate", không có nút "Clone to dev"
And không có dữ liệu HubSpot nào bị thay đổi

Maps to:

• Business Rule: BR-01, BR-02
• Field/Action: A1

AC-M1.2 - Không có pipeline

Given portal đã chọn không trả pipeline nào cho object đã chọn
When người dùng bấm "Load pipelines"
Then hiện "No pipelines found."

Maps to:

• Business Rule: BR-03

AC-M1.3 - Tải lại đóng stage đang mở

Given đang mở bảng stage của pipeline A
When người dùng bấm "Load pipelines" và tải thành công
Then danh sách được thay mới và không còn bảng stage nào mở

Maps to:

• Business Rule: BR-04

AC-M1.4 - Khoá khi đang chạy

Given đang tải danh sách hoặc đang xem stage
When thao tác chưa xong
Then Environment, Object type, "Load pipelines" và các nút trên mọi thẻ bị khoá

Maps to:

• Business Rule: BR-07

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

ID	Tình huống	Hành vi mong đợi
EC-M1.1	HubSpot lỗi khi tải danh sách	Popup "Failed to load pipelines" — "(12002)"; danh sách cũ (nếu có) giữ nguyên (BR-08)
EC-M1.2	Tải danh sách ở Prod, sau đó đổi Environment sang Dev (hoặc đổi Object type) mà không bấm "Load pipelines"	⚠️ Observed — hành vi hiện tại theo code: danh sách của Prod vẫn hiện, nhưng "View stages" gọi theo môi trường / object mới với id của danh sách cũ (thường ra 12007); các nút ghi ở US-H05 / US-H06 cũng dùng môi trường mới (fe/src/ui/components/works/sapp/pipeline-tool.tsx:54-56,239-254,269,306-308). Phát hiện khi viết R3, chưa chạy thử — OQ-H-15
EC-M1.3	Pipeline không có id trong phản hồi	Nút "View stages", "Clone to dev", "Duplicate" của thẻ đó bị khoá (BR-06)

Màn M2 - Bảng stage của một pipeline

Field	Value
Figma frame	N/A
Trigger vào màn	Bấm "View stages" trên một thẻ ở M1 (A2)
Mô tả ngắn	Khối "Stages" mở ngay trong thẻ pipeline, liệt kê stage và metadata, kèm "Copy JSON"

UI States

State	Khi nào	Hiển thị	Figma frame
Default	N/A — chỉ hiện khi đã có dữ liệu	—	N/A
Loading	Đang gọi A2	Mọi nút bị khoá. Chữ "Loading…" chỉ hiện trên nút "View stages" của thẻ đang mở stage (nếu có), không phải thẻ vừa bấm (fe/src/ui/components/works/sapp/pipeline-tool.tsx:275,314)	N/A
Has data	Có stage	Bảng Order / Label / Metadata; metadata trống → "—"	N/A
Empty	Pipeline không có stage	Dòng "No stages"	N/A
Error	A2 lỗi	Popup "Failed to load pipeline"; không mở M2	N/A
Disabled	Có thao tác đang chạy	Nút trong thẻ bị khoá (BR-07)	N/A

Fields

Field	Required	Type	Default	Format	Validation	Error Message	Visibility	Depends On
Order	—	Readonly number	—	Thiếu → "—"	—	—	Always	BR-05
Label	—	Readonly text	—	—	—	—	Always	BR-05
Metadata	—	Readonly text	—	khoá: giá trị nối " · "; trống → "—"	—	—	Always	BR-05

Filter / Search / Sort

N/A — bảng chi tiết của một pipeline, thứ tự theo HubSpot trả.

Actions

A3 - Copy JSON

Item	Description
Trigger	Bấm "Copy JSON" trong khối Stages
Behavior	Chép JSON toàn bộ pipeline (cả stage) vào clipboard; không gọi API, không ghi hệ thống nào (fe/src/ui/components/works/sapp/pipeline-tool.tsx:361-371)
Success Result	Clipboard chứa JSON, không có thông báo

Error cases:

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

Acceptance Criteria của màn M2

AC-M2.1 - Xem stage của pipeline Deal

Given danh sách Deal của portal prod đã tải
When người dùng bấm "View stages" trên pipeline "Sales Pipeline"
Then ngay dưới thẻ hiện bảng Order / Label / Metadata
And cột Metadata của mỗi stage hiện dạng "probability: 0.2 · isClosed: false"
And có nút "Copy JSON"

Maps to:

• Business Rule: BR-05
• Field/Action: A2, A3

AC-M2.2 - Chỉ mở một pipeline

Given đang mở stage của pipeline A
When người dùng bấm "View stages" trên pipeline B
Then bảng stage của A đóng và bảng stage của B mở

Maps to:

• Business Rule: BR-05

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

ID	Tình huống	Hành vi mong đợi
EC-M2.1	Pipeline bị xoá trên HubSpot sau khi tải danh sách	Popup "Failed to load pipeline" — "HubSpot pipeline not found (12007)" (BR-08)
EC-M2.2	Pipeline không có stage	Dòng "No stages" (BR-05)

5. Cross-feature AC

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

Given tool sapp.004 đang bị ẩn / tắt / khoá mã bí mật
When người dùng mở /works/sapp/tools/hs-pipeline
Then hành vi theo gate của nền tảng (US-P02)
And API list / get pipeline 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 token của portal đã chọn chưa cấu hình (US-P04)
When người dùng bấm "Load pipelines"
Then nhận lỗi 12001

Maps to:

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