Giao diện
US-T04: Xem và tải lại lịch sử làm mới ​
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-09, A-10.
| Field | Value |
|---|---|
| US ID | US-T04 |
| Role thực hiện | R1 - Người dùng tool Assumption (OQ về G-01) |
| 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-05, NFR-T-07 — xem Overview §5 |
| OQ liên quan | OQ-T-01, OQ-T-11, OQ-T-16 — xem Overview §6 |
1. US Statement ​
text
As a Người dùng tool (Assumption — OQ về G-01)
I want xem danh sách các ticket đã được làm mới cap_nhat_owner trên portal đang chọn (giá trị và owner trước → sau, thời gian),
và "Tải lại" một dòng để đọc giá trị hiện tại của ticket đó trên HubSpot
So that [Assumption — OQ-T-01] theo dõi được sau khi làm mới thì owner của ticket có được gán hay không, kể cả sau khi đã rời màn2. 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 | Có lượt làm mới thành công trong vòng hạn lưu (US-T02, NFR-T-05) | Người dùng | N/A — runtime |
| D2 | Redis của mind_keep hoạt động | Hạ tầng | N/A — runtime |
| D3 | Token HubSpot của portal trong env_systems — cho "Tải lại" (US-P04) | Admin CMS | N/A — runtime |
3. Business Rules ​
| ID | Rule | Áp dụng ở | Đã cover bởi (AC) | Nguồn code (Mode B/C) |
|---|---|---|---|---|
| BR-01 | Lịch sử lưu riêng từng portal (prod / dev); modal hiển thị lịch sử của portal đang chọn | M1 - toàn modal | AC-M1.1 | be/libs/constants/src/lib/sapp/sapp-23954.constants.ts:38-39; fe/src/ui/components/works/sapp/sapp-23954-tool.tsx:316-320, :356-361 |
| BR-02 | Danh sách hiển thị mới nhất trước | M1 - bảng lịch sử | AC-M1.1 | be/libs/modules/src/lib/sapp/common.service.ts:1086 |
| BR-03 | Mỗi dòng hiển thị: Ticket ID + tên ticket; cap_nhat_owner trước → sau (theo nhãn tuỳ chọn của portal); owner trước → sau dạng "{tên} ({id})"; thời gian làm mới theo định dạng ngày giờ Việt Nam của máy người dùng; giá trị trống hiện "—" | M1 - bảng lịch sử | AC-M1.1 | fe/src/ui/components/works/sapp/sapp-23954-tool.tsx:279-302, :374-437 |
| BR-04 | "Tải lại" một dòng: đọc lại ticket trên HubSpot và ghi đè tên ticket (nếu HubSpot có tên), cap_nhat_owner "sau" và owner "sau" của đúng dòng đó bằng giá trị hiện tại; giữ nguyên giá trị "trước" và thời gian làm mới; lưu lại lịch sử và thay dòng trên màn | M1 - action Tải lại | AC-M1.2 | be/libs/modules/src/lib/sapp/common.service.ts:1233-1259; fe/src/ui/components/works/sapp/sapp-23954-tool.tsx:326-349 |
| BR-05 | "Tải lại" dòng không còn trong lịch sử → báo lỗi "SAPP-23954 refresh-history item not found" (13025) | M1 - action Tải lại | AC-M1.4 | be/libs/modules/src/lib/sapp/common.service.ts:1225-1231; be/libs/constants/src/lib/error-codes/error-codes.constants.ts:664-667 |
| BR-06 | Trong lúc tải lại một dòng, nút "Tải lại" của dòng đó khoá và có spinner; các dòng khác vẫn bấm được | M1 - action Tải lại | AC-M1.2 | fe/src/ui/components/works/sapp/sapp-23954-tool.tsx:323, :351-354, :414-427 |
| BR-07 | Xem lịch sử chỉ đọc Redis; "Tải lại" chỉ đọc HubSpot và ghi Redis của mind_keep — không ghi HubSpot | M1 - action Mở lịch sử, Tải lại | AC-M1.2 | be/libs/modules/src/lib/sapp/common.service.ts:1078-1096, :1214-1278 |
| BR-08 | Không có chức năng xoá dòng / xoá lịch sử trên màn | M1 - toàn modal | AC-M1.1 | fe/src/ui/components/works/sapp/sapp-23954-tool.tsx:356-438 |
⚠️ Observedkhông viết thành BR: hạn 7 ngày cho cả danh sách, gia hạn mỗi lần ghi, không giới hạn số dòng (EC-M1.1, NFR-T-05, OQ-T-11); đọc lịch sử lỗi dùng mã của truy vấn (EC-M1.3, OQ-T-16).
4. Design ​
a. Mối liên hệ giữa các màn & User Flow ​
text
[US-T01 M1: nút "Lịch sử làm mới"]
↓
[M1: Modal "Lịch sử làm mới" (portal đang chọn)]
├─ đang tải ──→ "Đang tải…"
├─ rỗng ──→ "Chưa có lịch sử làm mới."
├─ có dữ liệu ──→ bảng; bấm "Tải lại" trên 1 dòng ──→ dòng được thay bằng giá trị hiện tại
├─ lỗi tải ──→ hộp lỗi "Không tải được lịch sử làm mới"
└─ đóng modal ──→ quay lại US-T01Link 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 - Modal "Lịch sử làm mới" ​
| Field | Value |
|---|---|
| Figma frame | N/A |
| Trigger vào màn | Bấm "Lịch sử làm mới" ở khối bộ lọc US-T01 (luôn bấm được, không cần truy vấn trước) |
| Mô tả ngắn | Modal tiêu đề "Lịch sử làm mới", phụ đề "Ticket đã làm mới cap_nhat_owner (portal {env}). Bấm "Tải lại" để đọc giá trị hiện tại." và bảng lịch sử |
UI States ​
| State | Khi nào | Hiển thị | Figma frame |
|---|---|---|---|
| Default | Modal vừa mở | Chuyển ngay sang Loading | N/A |
| Loading | Đang đọc lịch sử | Spinner + "Đang tải…"; khi tải lại 1 dòng: spinner ở nút dòng đó | N/A |
| Has data | Có dòng lịch sử | Bảng cột Ticket · cap_nhat_owner (trước → sau) · Owner (trước → sau) · Thời gian · nút "Tải lại"; cuộn trong modal, tiêu đề bảng cố định | N/A |
| Empty | Lịch sử portal rỗng / đã hết hạn | "Chưa có lịch sử làm mới." | N/A |
| Error | Đọc lịch sử lỗi / tải lại lỗi | Hộp lỗi "Không tải được lịch sử làm mới" hoặc "Tải lại mục lịch sử thất bại", nội dung "{thông điệp} ({mã})" | N/A |
| Disabled | Dòng đang tải lại | Nút "Tải lại" của dòng đó khoá | N/A |
Fields ​
| Field | Required | Type | Default | Format | Validation | Error Message | Visibility | Depends On |
|---|---|---|---|---|---|---|---|---|
| Ticket (ID + tên) | — | Text | — | ID; tên trống = "—" | — | — | Readonly | Dòng lịch sử |
| cap_nhat_owner (trước → sau) | — | Text → Text | — | nhãn tuỳ chọn; trống = "—" | BR-03 | — | Readonly | Dòng lịch sử; "sau" đổi khi Tải lại (BR-04) |
| Owner (trước → sau) | — | Text → Text | — | "{tên} ({id})" hoặc id; trống = "—" | BR-03 | — | Readonly | Dòng lịch sử; "sau" đổi khi Tải lại (BR-04) |
| Thời gian | — | Datetime | — | ngày giờ định dạng vi-VN theo giờ máy | — | — | Readonly | Thời điểm lượt làm mớ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 | — | — | — | N/A — không có bộ lọc (chỉ theo portal của tab, BR-01) |
| Search | — | — | — | N/A — không có tìm kiếm |
| Sort | Thời gian làm mới | cố định | Mới nhất trước | BR-02 |
| Pagination | — | — | Không phân trang | Trả toàn bộ danh sách; không giới hạn số dòng (EC-M1.1) |
Actions ​
A1 - Mở lịch sử ​
| Item | Description |
|---|---|
| Trigger | Bấm "Lịch sử làm mới" |
| Behavior | Đọc toàn bộ lịch sử của portal đang chọn từ Redis mind_keep, đảo thứ tự để mới nhất trước (BR-01, BR-02). Ghi vào: không ghi |
| Success Result | Bảng lịch sử hoặc "Chưa có lịch sử làm mới." |
Error cases:
| Case | Expected Handling |
|---|---|
| Redis lỗi | Hộp lỗi "Không tải được lịch sử làm mới" với "Failed to query SAPP-23954 tickets (13022)" — ⚠️ Observed dùng mã của truy vấn (EC-M1.3) |
A2 - Tải lại một dòng ​
| Item | Description |
|---|---|
| Trigger | Bấm "Tải lại" trên một dòng |
| Behavior | Tìm dòng theo mã dòng; đọc tên, cap_nhat_owner, owner hiện tại của ticket trên HubSpot và danh sách owner của portal; ghi đè giá trị "sau" của dòng (BR-04); lưu lại toàn bộ lịch sử và gia hạn lại hạn lưu (NFR-T-05). Ghi vào: Redis mind_keep (key lịch sử của portal). HubSpot portal dev / prod chỉ đọc (BR-07) |
| Success Result | Dòng trên màn được thay bằng dòng đã cập nhật; các dòng khác không đổi |
Error cases:
| Case | Expected Handling |
|---|---|
| Dòng không còn trong lịch sử (hết hạn giữa chừng) | Hộp lỗi "Tải lại mục lịch sử thất bại" với "SAPP-23954 refresh-history item not found (13025)" (BR-05) |
| Ticket không đọc được trên HubSpot / thiếu token | Hộp lỗi "Tải lại mục lịch sử thất bại" với lỗi HubSpot tương ứng; dòng giữ nguyên |
| Không tải được danh sách owner | Vẫn tải lại; owner "sau" chỉ hiển thị id (US-T02 BR-10) |
| Lỗi không xác định | Hộp lỗi với "Failed to reload SAPP-23954 refresh-history item (13026)" |
A3 - Đóng modal ​
| Item | Description |
|---|---|
| Trigger | Bấm nút đóng của modal |
| Behavior | Đóng modal, không ghi dữ liệu |
| Success Result | Quay lại màn US-T01, trạng thái màn giữ nguyên |
Error cases:
| Case | Expected Handling |
|---|---|
| N/A | Không có lỗi |
Acceptance Criteria của màn M1 ​
AC-M1.1 - Xem lịch sử theo portal ​
gherkin
Given lịch sử portal dev có 2 dòng: T1 làm mới lúc 09:00, T2 làm mới lúc 10:00; lịch sử portal prod có 1 dòng T9
When ở tab "Dev" bấm "Lịch sử làm mới"
Then modal có phụ đề chứa "(portal dev)" và bảng có đúng 2 dòng, T2 ở trên T1
And không có dòng T9
And mỗi dòng hiển thị Ticket ID, tên, cap_nhat_owner trước → sau, owner trước → sau, thời gian và nút "Tải lại"
And modal không có nút xoá dòngMaps to:
- Business Rule: BR-01, BR-02, BR-03, BR-08
- Field/Action: A1
AC-M1.2 - Tải lại ghi đè giá trị "sau" ​
gherkin
Given dòng T1 đang hiển thị cap_nhat_owner "— → Xử lý ticket thông thường", owner "— → Nguyễn An (101)", thời gian 09:00
And hiện tại trên HubSpot T1 có cap_nhat_owner = "Cập nhật thành công", owner = 202 (tên "Trần Bình")
When bấm "Tải lại" trên dòng T1
Then trong lúc chờ, nút "Tải lại" của dòng T1 khoá và có spinner
And dòng T1 đổi thành cap_nhat_owner "— → Cập nhật thành công", owner "— → Trần Bình (202)", thời gian vẫn 09:00
And giá trị "Xử lý ticket thông thường" lúc làm mới không còn hiển thị trên dòng
And không có dữ liệu nào trên HubSpot bị ghiMaps to:
- Business Rule: BR-04, BR-06, BR-07
- Field/Action: A2
AC-M1.3 - Lịch sử rỗng ​
gherkin
Given portal prod chưa có lượt làm mới nào trong hạn lưu
When ở tab "Prod" bấm "Lịch sử làm mới"
Then modal hiển thị "Chưa có lịch sử làm mới."Maps to:
- Business Rule: BR-01
AC-M1.4 - Tải lại dòng đã hết hạn ​
gherkin
Given modal đang hiển thị dòng T1 nhưng lịch sử portal đã hết hạn trên Redis
When bấm "Tải lại" trên dòng T1
Then hiện hộp lỗi "Tải lại mục lịch sử thất bại" với "SAPP-23954 refresh-history item not found (13025)"Maps to:
- Business Rule: BR-05
Negative AC / Edge Cases của màn M1 ​
| ID | Tình huống | Hành vi mong đợi |
|---|---|---|
| EC-M1.1 | ⚠️ Observed — hạn lưu và kích thước lịch sử | Hành vi hiện tại: hạn 7 ngày áp cho cả danh sách của portal và được gia hạn lại mỗi lần ghi (làm mới hoặc "Tải lại"); từng dòng không có hạn riêng, không giới hạn số dòng, không xoá dòng cũ → nếu tool được dùng ít nhất 1 lần mỗi 7 ngày, danh sách phình mãi và modal tải toàn bộ không phân trang. Nguồn: be/libs/constants/src/lib/sapp/sapp-23954.constants.ts:41-42; be/libs/modules/src/lib/sapp/common.service.ts:1062-1066, :1261-1265. NFR-T-05, DR-T-07, OQ-T-11 |
| EC-M1.2 | Làm mới lại ticket có dòng đã bị "Tải lại" | Dòng mới có "trước" = giá trị "sau" đã bị ghi đè bởi "Tải lại" của dòng gần nhất (US-T02 BR-09), không phải giá trị lúc lượt làm mới trước |
| EC-M1.3 | ⚠️ Observed — đọc lịch sử lỗi | Hành vi hiện tại: trả mã 13022 "Failed to query SAPP-23954 tickets" (mã của chức năng truy vấn). Nguồn: be/libs/modules/src/lib/sapp/common.service.ts:1087-1094. OQ-T-16 |
| EC-M1.4 | "Tải lại" cùng lúc với một lượt làm mới đang ghi lịch sử | Cả hai đọc cả danh sách rồi ghi đè cả danh sách, không có khoá → có thể mất dòng / mất cập nhật. Suy từ code, chưa chạy thử để xác nhận |
| EC-M1.5 | Ticket đã đổi tên trên HubSpot | "Tải lại" cập nhật tên mới; HubSpot không có tên thì giữ tên cũ |
| EC-M1.6 | Thời gian hiển thị | Theo múi giờ của máy người dùng (định dạng vi-VN); giá trị lưu là thời điểm chuẩn ISO |
5. Cross-feature AC ​
AC-X.1 - Đọc giá trị hiện tại do automation tạo ra ​
gherkin
Given automation HubSpot (ngoài hệ thống) đã gán owner cho T1 sau nhiều phút kể từ lúc làm mới
When bấm "Tải lại" trên dòng T1
Then owner "sau" của dòng T1 hiển thị owner mới do automation gánMaps to:
- REL-06 (Be Affected - Automation HubSpot, ngoài hệ thống)
AC-X.2 - Nhãn cap_nhat_owner ​
gherkin
Given lookup property cap_nhat_owner (nhóm HubSpot) trả nhãn cho giá trị V
When bảng lịch sử hiển thị giá trị V
Then cột cap_nhat_owner hiển thị nhãn của VMaps to:
- REL-05 (Affects - HubSpot Get property)