Giao diện
US-T01: Truy vấn ticket theo pipeline / cap_nhat_owner / owner / ngày ​
Thuộc FS: 00-overview.md — SAPP-23954 Ticket Owner 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 @
e77c47a· nguồn: inventory 23954 A-01, A-02, A-03, A-04, A-05.
| Field | Value |
|---|---|
| US ID | US-T01 |
| Role thực hiện | R1 - Người dùng tool Assumption (OQ về G-01); R2 - Hệ thống (tải lookup) |
| Phase | Đã triển khai (as-built @ e77c47a) |
| Priority | N/A — as-built |
| Status | Draft |
| NFR liên quan | NFR-T-01, NFR-T-02, NFR-T-04 — xem Overview §5 |
| OQ liên quan | OQ-T-01, OQ-T-02, OQ-T-05, OQ-T-06, OQ-T-15 — xem Overview §6 |
1. US Statement ​
text
As a Người dùng tool (Assumption — OQ về G-01)
I want chọn portal HubSpot Dev hoặc Prod, lọc ticket theo pipeline, giá trị cap_nhat_owner,
có / chưa có owner và khoảng ngày tạo, rồi chọn các ticket trong kết quả
So that [Assumption — OQ-T-01] tìm đúng nhóm ticket cần "làm mới" để automation gán owner chạy lại2. Dependencies & Definition Of Ready ​
N/A — đã triển khai (Mode B).
Dependency runtime (tham khảo):
| # | Cần sẵn sàng | Ai cung cấp | Trạng thái |
|---|---|---|---|
| D1 | Token HubSpot của portal đang chọn trong env_systems (US-P04) | Admin CMS | N/A — runtime |
| D2 | Tool sapp.008 đang bật / đã mở khoá (US-P02) | Admin CMS | N/A — runtime |
| D3 | Lookup pipeline ticket và property cap_nhat_owner của nhóm HubSpot (REL-04, REL-05) | Đã có | N/A — runtime |
3. Business Rules ​
| ID | Rule | Áp dụng ở | Đã cover bởi (AC) | Nguồn code (Mode B/C) |
|---|---|---|---|---|
| BR-01 | Có 2 portal Dev và Prod; khi mở màn, portal mặc định là Dev. Mọi truy vấn chạy trên portal đang chọn | M1 - tab portal | AC-M1.1 | fe/src/ui/components/works/sapp/sapp-23954-tool.tsx:58-61, :913, :957 |
| BR-02 | Khi mở panel của một portal, hệ thống tải danh sách pipeline ticket và danh sách tuỳ chọn cap_nhat_owner của portal đó làm bộ lọc; tuỳ chọn đang bị ẩn trên HubSpot không hiển thị | M1 - field Pipeline, Cập nhật owner | AC-M1.2, EC-M1.1 | fe/src/ui/components/works/sapp/sapp-23954-tool.tsx:447-476 |
| BR-03 | Mọi bộ lọc đều tuỳ chọn và kết hợp theo VÀ; trong một bộ lọc chọn nhiều giá trị thì ticket khớp bất kỳ giá trị nào. Không chọn bộ lọc nào = lấy mọi ticket của portal | M1 - action Truy vấn ticket | AC-M1.3, AC-M1.4 | be/libs/modules/src/lib/sapp/common.service.ts:322-342, :364 |
| BR-04 | Bộ lọc owner có 3 lựa chọn: "Tất cả" (không lọc), "Có owner" (chỉ ticket đã gán owner), "Chưa có owner" (chỉ ticket chưa gán owner) | M1 - field Chủ sở hữu (owner) | AC-M1.5 | fe/src/ui/components/works/sapp/sapp-23954-tool.tsx:531-533, :702-713; be/libs/modules/src/lib/sapp/common.service.ts:337-342 |
| BR-05 | Ngày "từ" không được chọn sau ngày "đến" và ngược lại (lịch chặn ngày ngoài khoảng) | M1 - field Tạo từ ngày / Đến ngày | AC-M1.6 | fe/src/ui/components/works/sapp/sapp-23954-tool.tsx:717-729 |
| BR-06 | Kết quả luôn sắp theo ngày tạo mới nhất trước | M1 - bảng kết quả | AC-M1.3 | be/libs/modules/src/lib/sapp/common.service.ts:365-370 |
| BR-07 | Mỗi lần truy vấn lấy 100 ticket; còn trang sau thì có nút "Tải thêm" để nối trang kế vào cuối bảng, giữ nguyên lựa chọn | M1 - action Tải thêm | AC-M1.7 | fe/src/ui/components/works/sapp/sapp-23954-tool.tsx:66, :648-653, :861-875; be/libs/constants/src/lib/sapp/sapp-23954.constants.ts:27-31 |
| BR-08 | Tên pipeline tra từ danh sách pipeline ticket của portal; không tra được thì hiển thị id pipeline | M1 - cột Pipeline | AC-M1.8 | be/libs/modules/src/lib/sapp/common.service.ts:376-394; fe/src/ui/components/works/sapp/sapp-23954-tool.tsx:843 |
| BR-09 | Truy vấn mới (không phải "Tải thêm") thay toàn bộ bảng, xoá lựa chọn và xoá kết quả làm mới cũ | M1 - action Truy vấn ticket | AC-M1.9 | fe/src/ui/components/works/sapp/sapp-23954-tool.tsx:557-569 |
| BR-10 | "Chọn tất cả" chỉ chọn các ticket đã tải trên màn, không phải toàn bộ tổng số khớp bộ lọc | M1 - action Chọn tất cả | AC-M1.10 | fe/src/ui/components/works/sapp/sapp-23954-tool.tsx:673-678 |
| BR-11 | Nút "Làm mới cap_nhat_owner (N)" chỉ bật khi đã chọn ≥ 1 ticket (N = số đã chọn) — hành động làm mới ở US-T02 | M1 - action Chọn ticket | AC-M1.10 | fe/src/ui/components/works/sapp/sapp-23954-tool.tsx:773-787 |
⚠️ Observedkhông viết thành BR: lọc ngày theo UTC (EC-M1.4, OQ-T-06); tên tham số owner ngược nghĩa (EC-M1.5, OQ-T-05); đổi tab mất trạng thái (EC-M1.6, OQ-T-15).
4. Design ​
a. Mối liên hệ giữa các màn & User Flow ​
text
[Menu "SAPP 23954 - Ticket Owner" › "Query & Refresh tickets"]
↓
[M1: Panel truy vấn — tab Dev (mặc định) / Prod]
↓ hệ thống tải lookup Pipeline + cap_nhat_owner
↓ người dùng chọn bộ lọc → "Truy vấn ticket"
[M1: Bảng kết quả]
├─ còn trang sau → "Tải thêm" → nối dòng
├─ chọn ticket → "Làm mới cap_nhat_owner (N)" ──→ US-T02
├─ "Lịch sử làm mới" ──→ US-T04
└─ lỗi API → hộp lỗi "Truy vấn ticket thất bại", giữ bảng cũLink flow chi tiết nếu có:
- N/A — không có flow Figma / Mermaid.
b. Chi tiết từng màn ​
Màn M1 - Panel truy vấn ticket (sapp.008) ​
| Field | Value |
|---|---|
| Figma frame | N/A |
| Trigger vào màn | Mở /works/sapp/tools/sapp-23954 từ menu "SAPP 23954 - Ticket Owner" › "Query & Refresh tickets" |
| Mô tả ngắn | Tiêu đề "SAPP-23954 Ticket Owner", 2 tab Dev / Prod, khối bộ lọc + nút "Truy vấn ticket" / "Lịch sử làm mới", bảng kết quả có chọn dòng |
UI States ​
| State | Khi nào | Hiển thị | Figma frame |
|---|---|---|---|
| Default | Vừa vào màn / vừa đổi tab | Tab Dev chọn sẵn; bộ lọc trống; chú thích "Bỏ trống mọi bộ lọc để lấy tất cả ticket. Sắp xếp theo ngày tạo mới nhất."; chưa có bảng kết quả | N/A |
| Loading | Đang tải lookup / đang truy vấn | Nhóm checkbox hiện đang tải; nút đổi thành "Đang truy vấn…" có spinner; khi "Tải thêm" thì spinner ở nút "Tải thêm" | N/A |
| Has data | Truy vấn có kết quả | Dòng "Kết quả — hiển thị {số dòng} / {tổng} ticket · đã chọn {N}"; bảng cột: chọn · Ticket ID · Tên ticket · Pipeline · cap_nhat_owner · Owner ID; ô trống hiện "—" | N/A |
| Empty | Truy vấn không có ticket khớp | "Không có ticket khớp bộ lọc."; lookup rỗng: "Không có pipeline." / "Không có tùy chọn." | N/A |
| Error | API lỗi | Hộp lỗi tiêu đề "Truy vấn ticket thất bại" (hoặc "Không tải được danh sách pipeline" / "Không tải được tùy chọn cap_nhat_owner"), nội dung "{thông điệp} ({mã})" | N/A |
| Disabled | Đang truy vấn / chưa chọn ticket | Nút "Truy vấn ticket" và "Tải thêm" khoá khi đang truy vấn; nút "Làm mới cap_nhat_owner (0)" khoá khi chưa chọn ticket | N/A |
Fields ​
| Field | Required | Type | Default | Format | Validation | Error Message | Visibility | Depends On |
|---|---|---|---|---|---|---|---|---|
| Tab portal | Yes | Tab (Dev / Prod) | Dev | — | Chỉ 2 giá trị (BR-01) | — | Always | — |
| Pipeline | No | Multi-select checkbox | Không chọn | id pipeline ticket | Tuỳ chọn từ lookup (BR-02) | — | Always | Portal đang chọn |
| Cập nhật owner (cap_nhat_owner) | No | Multi-select checkbox | Không chọn | giá trị dropdown HubSpot | Tuỳ chọn không ẩn từ lookup (BR-02) | — | Always | Portal đang chọn |
| Chủ sở hữu (owner) | No | Dropdown | "Tất cả" | Tất cả / Có owner / Chưa có owner | BR-04 | — | Always | — |
| Tạo từ ngày (createdate ≥) | No | Date | Trống | ngày (gửi đi 00:00:00.000 UTC) | Không sau "Đến ngày" (BR-05) | — (lịch chặn chọn) | Always | Đến ngày |
| Đến ngày (createdate ≤) | No | Date | Trống | ngày (gửi đi 23:59:59.999 UTC) | Không trước "Tạo từ ngày" (BR-05) | — (lịch chặn chọn) | Always | Tạo từ ngày |
| Ô chọn dòng / Chọn tất cả | No | Checkbox | Bỏ chọn | — | BR-10 | — | Khi có kết quả | Các dòng đã tải |
Filter / Search / Sort (chỉ màn List/Report — xóa nếu không phải) ​
| Loại | Theo field | Kiểu | Default | Notes |
|---|---|---|---|---|
| Filter | Pipeline | multi-select | Tất cả | Khớp bất kỳ (BR-03) |
| Filter | cap_nhat_owner | multi-select | Tất cả | Khớp bất kỳ (BR-03) |
| Filter | Owner | dropdown 3 trạng thái | Tất cả | BR-04; ⚠️ Observed tên tham số API ngược nghĩa (EC-M1.5) |
| Filter | Ngày tạo | date range | Không giới hạn | Trọn ngày theo UTC — ⚠️ Observed (EC-M1.4) |
| Search | — | — | — | N/A — không có ô tìm kiếm tự do |
| Sort | Ngày tạo | cố định | Mới nhất trước | Không đổi được (BR-06) |
| Pagination | — | cursor "Tải thêm" | 100 / trang | BR-07, NFR-T-04 |
Actions ​
A1 - Chọn portal ​
| Item | Description |
|---|---|
| Trigger | Bấm tab "Dev" hoặc "Prod" |
| Behavior | Đổi portal; panel được dựng lại từ đầu và tải lại lookup của portal mới (BR-01, BR-02). Không ghi dữ liệu |
| Success Result | Panel của portal mới ở trạng thái Default |
Error cases:
| Case | Expected Handling |
|---|---|
| Đang có bộ lọc / kết quả / lựa chọn ở tab cũ | ⚠️ Observed — toàn bộ bị mất khi đổi tab (EC-M1.6) |
A2 - Tải lookup bộ lọc (hệ thống) ​
| Item | Description |
|---|---|
| Trigger | Panel của portal được mở |
| Behavior | Đọc danh sách pipeline ticket và định nghĩa property cap_nhat_owner của portal từ HubSpot qua lookup nhóm HubSpot (REL-04, REL-05); bỏ tuỳ chọn ẩn (BR-02). Chỉ đọc |
| Success Result | Hai nhóm checkbox "Pipeline" và "Cập nhật owner (cap_nhat_owner)" có tuỳ chọn |
Error cases:
| Case | Expected Handling |
|---|---|
| Lookup pipeline lỗi | Hộp lỗi "Không tải được danh sách pipeline"; nhóm checkbox trống ("Không có pipeline.") |
Lookup cap_nhat_owner lỗi | Hộp lỗi "Không tải được tùy chọn cap_nhat_owner"; nhóm checkbox trống ("Không có tùy chọn.") |
A3 - Truy vấn ticket ​
| Item | Description |
|---|---|
| Trigger | Bấm "Truy vấn ticket" |
| Behavior | Gửi bộ lọc hiện tại (BR-03, BR-04, BR-05) với 100 dòng / trang tới HubSpot Search của portal đang chọn; sắp mới nhất trước (BR-06); tra tên pipeline (BR-08). Chỉ đọc HubSpot, không ghi. Thay bảng, xoá lựa chọn và kết quả làm mới cũ (BR-09) |
| Success Result | Bảng kết quả + "hiển thị N / tổng" |
Error cases:
| Case | Expected Handling |
|---|---|
| Portal chưa cấu hình token HubSpot | Hộp lỗi "Truy vấn ticket thất bại" với thông điệp thiếu cấu hình (mã 12001 — xem US-P04) |
| HubSpot trả lỗi / lỗi không xác định | Hộp lỗi "Truy vấn ticket thất bại" — lỗi HubSpot trả nguyên mã lỗi HubSpot chung; lỗi khác "Failed to query SAPP-23954 tickets (13022)". Bảng cũ giữ nguyên |
A4 - Tải thêm ​
| Item | Description |
|---|---|
| Trigger | Bấm "Tải thêm" (chỉ hiện khi còn trang sau) |
| Behavior | Truy vấn lại cùng bộ lọc với con trỏ trang kế; nối dòng vào cuối, giữ lựa chọn (BR-07). Chỉ đọc |
| Success Result | Bảng dài thêm tối đa 100 dòng; nút ẩn khi hết trang |
Error cases:
| Case | Expected Handling |
|---|---|
| API lỗi | Hộp lỗi "Truy vấn ticket thất bại"; các dòng đã có giữ nguyên |
A5 - Chọn ticket / Chọn tất cả ​
| Item | Description |
|---|---|
| Trigger | Bấm vào dòng hoặc ô chọn của dòng; bấm ô "Chọn tất cả" ở tiêu đề bảng |
| Behavior | Bật / tắt chọn dòng; "Chọn tất cả" chọn (hoặc bỏ chọn nếu đã chọn hết) mọi dòng đã tải (BR-10); cập nhật "đã chọn N" và nút làm mới (BR-11). Không ghi dữ liệu |
| Success Result | Dòng được chọn tô nền; nút "Làm mới cap_nhat_owner (N)" bật khi N > 0 |
Error cases:
| Case | Expected Handling |
|---|---|
| Tổng khớp bộ lọc lớn hơn số dòng đã tải | "Chọn tất cả" chỉ chọn số đã tải (EC-M1.3) |
Acceptance Criteria của màn M1 ​
AC-M1.1 - Portal mặc định Dev ​
gherkin
Given người dùng mở màn "Query & Refresh tickets"
When màn hiển thị xong
Then tab "Dev" đang được chọn
And mọi truy vấn sau đó chạy trên portal HubSpot dev cho tới khi người dùng chọn tab "Prod"Maps to:
- Business Rule: BR-01
- Field/Action: Tab portal, A1
AC-M1.2 - Tải bộ lọc từ portal ​
gherkin
Given portal dev có property cap_nhat_owner với 1 tuỳ chọn đang bị ẩn
When panel Dev được mở
Then nhóm "Cập nhật owner (cap_nhat_owner)" liệt kê các tuỳ chọn không ẩn, không có tuỳ chọn bị ẩn
And nhóm "Pipeline" liệt kê pipeline ticket của portal devMaps to:
- Business Rule: BR-02
- Field/Action: A2
AC-M1.3 - Truy vấn không bộ lọc ​
gherkin
Given không chọn bộ lọc nào
When bấm "Truy vấn ticket"
Then hệ thống trả tối đa 100 ticket bất kỳ của portal, sắp theo ngày tạo mới nhất trước
And dòng tiêu đề hiển thị "hiển thị {số dòng} / {tổng}" với tổng là số ticket của portalMaps to:
- Business Rule: BR-03, BR-06, BR-07
- Field/Action: A3
AC-M1.4 - Kết hợp bộ lọc ​
gherkin
Given chọn 2 pipeline P1, P2 và 1 giá trị cap_nhat_owner "Xử lý ticket thông thường"
When bấm "Truy vấn ticket"
Then chỉ trả ticket thuộc P1 hoặc P2 VÀ có cap_nhat_owner = "Xử lý ticket thông thường"Maps to:
- Business Rule: BR-03
- Field/Action: Pipeline, Cập nhật owner
AC-M1.5 - Lọc theo owner ​
gherkin
Given chọn "Chủ sở hữu (owner)" = "Chưa có owner"
When bấm "Truy vấn ticket"
Then chỉ trả ticket chưa được gán owner (Owner ID hiển thị "—")
And chọn "Có owner" thì chỉ trả ticket đã có owner; chọn "Tất cả" thì không lọc theo ownerMaps to:
- Business Rule: BR-04
- Field/Action: Chủ sở hữu (owner)
AC-M1.6 - Khoảng ngày hợp lệ ​
gherkin
Given đã chọn "Đến ngày" = 10/09/2026
When mở lịch "Tạo từ ngày"
Then không chọn được ngày sau 10/09/2026Maps to:
- Business Rule: BR-05
- Field/Action: Tạo từ ngày, Đến ngày
AC-M1.7 - Tải thêm giữ lựa chọn ​
gherkin
Given kết quả có 100 dòng, tổng 250, đã chọn 3 ticket
When bấm "Tải thêm"
Then bảng có 200 dòng, 3 ticket vẫn đang chọn
And sau lần "Tải thêm" tiếp theo bảng có 250 dòng và nút "Tải thêm" biến mấtMaps to:
- Business Rule: BR-07
- Field/Action: A4
AC-M1.8 - Tên pipeline ​
gherkin
Given ticket thuộc pipeline có id tra được trong danh sách pipeline của portal
When bảng kết quả hiển thị
Then cột "Pipeline" hiển thị tên pipeline
And nếu id không tra được tên thì hiển thị id pipelineMaps to:
- Business Rule: BR-08
AC-M1.9 - Truy vấn mới xoá lựa chọn và kết quả làm mới ​
gherkin
Given đã chọn 5 ticket và đang hiển thị khối "Kết quả làm mới" của lượt trước
When bấm "Truy vấn ticket" lần nữa
Then bảng được thay bằng kết quả mới, "đã chọn 0"
And khối "Kết quả làm mới" biến mấtMaps to:
- Business Rule: BR-09
AC-M1.10 - Chọn tất cả và nút làm mới ​
gherkin
Given bảng đang có 100 dòng đã tải trên tổng 250
When bấm ô "Chọn tất cả"
Then 100 dòng được chọn, "đã chọn 100"
And nút "Làm mới cap_nhat_owner (100)" bật
And bấm lại ô "Chọn tất cả" thì bỏ chọn cả 100 và nút về "Làm mới cap_nhat_owner (0)" ở trạng thái khoáMaps to:
- Business Rule: BR-10, BR-11
- Field/Action: A5
Negative AC / Edge Cases của màn M1 ​
| ID | Tình huống | Hành vi mong đợi |
|---|---|---|
| EC-M1.1 | Lookup pipeline hoặc cap_nhat_owner lỗi | Hộp lỗi tương ứng; nhóm checkbox trống; vẫn truy vấn được không theo bộ lọc đó |
| EC-M1.2 | Truy vấn không có ticket khớp | "Không có ticket khớp bộ lọc."; không có nút "Tải thêm"; nút làm mới khoá |
| EC-M1.3 | "Chọn tất cả" khi tổng > số dòng đã tải | Chỉ các dòng đã tải được chọn (BR-10); muốn chọn thêm phải "Tải thêm" trước |
| EC-M1.4 | ⚠️ Observed — ticket tạo lúc 00:00–06:59 giờ VN | Hành vi hiện tại: khoảng ngày tính trọn ngày theo UTC (từ 00:00:00.000Z đến 23:59:59.999Z), nên ticket tạo 00:00–06:59 giờ VN ngày D bị tính vào ngày D-1. Nguồn: fe/src/ui/components/works/sapp/sapp-23954-tool.tsx:534-535; be/libs/modules/src/lib/sapp/common.service.ts:343-356. Cố ý hay bug: OQ-T-06 |
| EC-M1.5 | ⚠️ Observed — gọi API trực tiếp với tham số owner | Hành vi hiện tại: tham số tên "noOwner" = true nghĩa là có owner, = false nghĩa là chưa có owner (màn gửi đúng theo nghĩa này nên người dùng màn không bị ảnh hưởng). Nguồn: be/libs/interface/src/lib/dto/sapp/sapp-23954-ticket.dto.ts:28-34; be/libs/modules/src/lib/sapp/common.service.ts:337-342. OQ-T-05 |
| EC-M1.6 | ⚠️ Observed — đổi tab Dev ↔ Prod giữa chừng | Hành vi hiện tại: panel dựng lại → mất bộ lọc, kết quả, lựa chọn của tab trước; quay lại tab cũ thấy trạng thái Default. Nguồn: fe/src/ui/components/works/sapp/sapp-23954-tool.tsx:955-957. OQ-T-15, DR-T-09 |
| EC-M1.7 | Ticket có tên / cap_nhat_owner / owner trống | Ô hiển thị "—" |
| EC-M1.8 | Refresh trình duyệt | Mọi bộ lọc, kết quả, lựa chọn mất (không lưu trạng thái); tab về Dev |
5. Cross-feature AC ​
AC-X.1 - Bộ lọc dùng lookup của nhóm HubSpot ​
gherkin
Given lookup pipeline ticket và lookup property cap_nhat_owner của nhóm HubSpot hoạt động bình thường cho portal đang chọn
When panel truy vấn được mở
Then danh sách "Pipeline" khớp danh sách pipeline ticket mà lookup trả về
And danh sách "Cập nhật owner" khớp các tuỳ chọn không ẩn mà lookup trả vềMaps to:
- REL-04 (Affects - HubSpot Xem pipeline)
- REL-05 (Affects - HubSpot Get property)
AC-X.2 - Cổng tool nền tảng ​
gherkin
Given tool sapp.008 đang ẩn hoặc khoá theo cấu hình nền tảng
When người dùng mở đường dẫn màn
Then màn truy vấn không hiển thị theo hành vi cổng của nền tảng (US-P02)Maps to:
- REL-01 (Affects - Hub mở tool)
- REL-02 (Affects - Khoá tool)