US-P01: Mở workspace SAPP, duyệt sidebar và mở một tool

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-P01
Role thực hiện	R1 - Người dùng tool — 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-02, NFR-P-07 — xem Overview §5
OQ liên quan	OQ-P-13, OQ-P-16, OQ-P-17 — xem Overview §6

Nguồn inventory: A-01, A-03, A-04, A-05, A-06, A-07, A-09 (working/ai-drafts/feature-inventory-platform-20260930.md).

1. US Statement

As a Người dùng tool  [Assumption — OQ-P-13 / G-01]
I want mở /works/sapp, thấy danh sách tool theo nhóm ticket và vào được đúng tool mình cần (hoặc tool dùng gần nhất)
So that [Assumption] tôi chuyển nhanh giữa các công cụ test/vận hành SAPP mà không phải nhớ URL từng tool

2. Dependencies & Definition Of Ready

N/A — đã triển khai (Mode B).

Dependency runtime (để màn chạy đúng):

#	Cần sẵn sàng	Ai cung cấp	Trạng thái
D1	API GET /api/v1/tools/public trả lời được (→ US-P02)	BE	Đã có
D2	Mỗi mã sapp.001–sapp.013 có dòng trong bảng tools, nhóm bật + hiện (fail-closed — thiếu dòng = tool đóng)	Admin CMS (US-P03)	❓ OQ-P-16

3. Business Rules

ID	Rule	Áp dụng ở	Đã cover bởi (AC)	Nguồn code (Mode B/C)
BR-01	Địa chỉ /works/sapp không có màn riêng — luôn chuyển thẳng sang /works/sapp/tools	Entry	AC-M1.1	fe/app/works/sapp/page.tsx:17-19
BR-02	Khi vào /works/sapp/tools, hệ thống chọn tool đích: tool dùng gần nhất nếu tool đó còn mở; nếu không, tool mở đầu tiên theo thứ tự danh mục; không bao giờ đưa người dùng vào tool đang đóng	M1	AC-M1.2, AC-M1.3	fe/src/ui/components/works/shared/tool-availability.ts:41-54, fe/src/ui/pages/works/sapp/tools/index-redirect.tsx:41-47
BR-03	Không đọc được danh sách trạng thái tool → không chọn tool đích, hiện "Không kiểm tra được trạng thái tool"	M1	AC-M1.4	fe/src/ui/pages/works/sapp/tools/index-redirect.tsx:39-47, :66-78
BR-04	Không có tool nào đang mở → hiện "Chưa có tool nào được mở"	M1	AC-M1.5	fe/src/ui/pages/works/sapp/tools/index-redirect.tsx:80-90
BR-05	Việc chuyển sang tool đích là điều hướng thay thế: bấm Back từ tool không quay lại trang chọn tool	M1	AC-M1.6	fe/src/ui/pages/works/sapp/tools/index-redirect.tsx:49-55
BR-06	Sidebar xếp tool theo 6 nhóm ticket (bảng ở §4 M2); tool không có trong danh sách public bị ẩn; tool có trong danh sách nhưng không mở được hiện nhãn "Off" và không bấm được; nhóm không còn tool nào hiện bị ẩn cả tiêu đề	M2 - sidebar	AC-M2.1, AC-M2.2	fe/src/ui/pages/works/sapp/tools/shell.tsx:254-395, fe/src/ui/pages/works/sapp/tools/registry.ts:39-111
BR-07	Trong lúc đang tải trạng thái, tool hiện mờ và không bấm được	M2 - sidebar	AC-M2.3	fe/src/ui/pages/works/sapp/tools/shell.tsx:354-372
BR-08	Người dùng thu/mở được từng nhóm; lựa chọn được nhớ trên trình duyệt; nhóm đang chứa tool đang mở không thu được	M2 - sidebar	AC-M2.4	fe/src/ui/pages/works/sapp/tools/shell.tsx:272-305, :506-550
BR-09	Sidebar thu được thành thanh icon; nếu người dùng chưa chọn, sidebar tự thu khi màn rộng < 1280 px. Giao diện tối bật/tắt được; chưa chọn thì theo cài đặt hệ điều hành. Cả hai lựa chọn được nhớ	M2	AC-M2.5	fe/src/ui/pages/works/sapp/tools/shell.tsx:59, :94-105, :210-224
BR-10	Trên điện thoại, sidebar là ngăn kéo phủ màn; chọn tool thì ngăn kéo đóng	M2	AC-M2.6	fe/src/ui/pages/works/sapp/tools/shell.tsx:81-89, :151-168
BR-11	Tool vừa mở được ghi nhớ trên trình duyệt để lần sau BR-02 quay lại đúng tool	M2	AC-M2.7	fe/src/ui/pages/works/sapp/tools/shell.tsx:122-126, fe/src/ui/components/works/shared/last-tool.ts:10-26
BR-12	Mọi lựa chọn ghi nhớ trên trình duyệt: không đọc/ghi được bộ nhớ trình duyệt thì dùng mặc định, không báo lỗi	M1, M2	EC-M2.1	fe/src/ui/components/works/shared/use-persisted-flag.ts:15-46
BR-13	Mở bất kỳ tool nào (qua sidebar hoặc link chia sẻ) đều đi qua cổng chặn tool (US-P02) trước khi thấy nội dung	M2 - vùng nội dung	AC-M2.8	fe/src/ui/pages/works/sapp/tools/shell.tsx:418-440, fe/src/ui/components/works/shared/tool-gate.tsx:88-267

4. Design

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

[/works/sapp] ──(BR-01)──→ [/works/sapp/tools  (M1: chọn tool đích)]
                                 ├─ đang tải ─────────────→ "Đang mở tool…"
                                 ├─ có tool đích (BR-02) ─→ [/works/sapp/tools/<slug>] (replace, BR-05)
                                 ├─ đọc trạng thái lỗi ───→ "Không kiểm tra được trạng thái tool"
                                 └─ không tool nào mở ────→ "Chưa có tool nào được mở"

[M2: Shell — sidebar + breadcrumb + vùng nội dung]
  ├─ bấm tool trong sidebar ─→ vùng nội dung = cổng chặn (US-P02) → nội dung tool
  ├─ "Về Works" ─→ /works
  └─ thu/mở nhóm · thu sidebar · giao diện tối (nhớ trên trình duyệt)

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

Màn M1 - Chọn tool đích (/works/sapp/tools)

Field	Value
Figma frame	N/A — as-built, không có Figma
Trigger vào màn	Mở /works/sapp hoặc /works/sapp/tools
Mô tả ngắn	Màn trung gian, không phải đích đến: quyết định mở tool nào rồi chuyển đi ngay

UI States

State	Khi nào	Hiển thị	Figma frame
Default / Loading	Đang tải trạng thái tool, hoặc đã có tool đích và đang chuyển	Panel spinner "Đang mở tool…"	N/A
Has data	Có tool đích	Không hiển thị gì thêm — chuyển sang tool	N/A
Empty	Không tool nào mở	Panel "Chưa có tool nào được mở" + "Tài khoản này hiện chưa được mở tool nào trong workspace SAPP. Liên hệ quản trị viên workspace để được cấp quyền."	N/A
Error	Không đọc được trạng thái	Panel "Không kiểm tra được trạng thái tool" + "Chưa đọc được danh sách tool từ máy chủ nên không mở tool nào. Vui lòng tải lại trang."	N/A
Disabled	N/A — màn không có thao tác	—	N/A

Fields

N/A — màn không có field nhập/hiển thị dữ liệu.

Filter / Search / Sort

N/A — không phải màn List.

Actions

A1 - Chọn tool đích (hệ thống)

Item	Description
Trigger	Trạng thái tool vừa tải xong (US-P02 A1)
Behavior	Áp BR-02 trên danh mục 13 tool; không gọi thêm API (dùng lại kết quả tải một lần của shell). Không ghi dữ liệu vào hệ thống nào
Success Result	Điều hướng thay thế sang /works/sapp/tools/<slug> (BR-05)

Error cases:

Case	Expected Handling
Đọc trạng thái lỗi (mạng, timeout, 4xx/5xx)	State Error (BR-03)
Không có tool mở	State Empty (BR-04)

Acceptance Criteria của màn M1

AC-M1.1 - /works/sapp chuyển thẳng

Given người dùng mở /works/sapp
When trang tải
Then trình duyệt được chuyển sang /works/sapp/tools, không có màn trung gian nào khác

Maps to:

• Business Rule: BR-01

AC-M1.2 - Quay lại tool dùng gần nhất

Given trình duyệt đã ghi nhớ tool dùng gần nhất là "sapp-23954"
And tool sapp.008 đang hiện và bật
When người dùng mở /works/sapp/tools
Then người dùng được đưa tới /works/sapp/tools/sapp-23954

Maps to:

• Business Rule: BR-02, BR-11

AC-M1.3 - Tool gần nhất đã đóng → tool mở đầu tiên

Given tool dùng gần nhất đang bị tắt hoặc ẩn
When người dùng mở /works/sapp/tools
Then người dùng được đưa tới tool mở đầu tiên theo thứ tự danh mục (nhóm HubSpot trước)
And không bao giờ được đưa vào tool đang đóng

Maps to:

• Business Rule: BR-02

AC-M1.4 - Không đọc được trạng thái

Given API danh sách trạng thái tool lỗi hoặc quá 10 giây
When người dùng mở /works/sapp/tools
Then màn hiện "Không kiểm tra được trạng thái tool"
And không chuyển sang tool nào

Maps to:

• Business Rule: BR-03

AC-M1.5 - Không có tool nào mở

Given danh sách trạng thái đọc được nhưng không tool nào vừa hiện vừa bật
When người dùng mở /works/sapp/tools
Then màn hiện "Chưa có tool nào được mở"

Maps to:

• Business Rule: BR-04

AC-M1.6 - Back không quay về trang chọn

Given người dùng đã được chuyển từ /works/sapp/tools sang một tool
When người dùng bấm Back của trình duyệt
Then trình duyệt về trang trước /works/sapp/tools (không bị chuyển tới lại)

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	Tool ghi nhớ là slug không còn trong danh mục	Bỏ qua, áp nhánh "tool mở đầu tiên" (BR-02)
EC-M1.2	Bộ nhớ trình duyệt bị chặn	Không có tool ghi nhớ → áp nhánh "tool mở đầu tiên" (BR-12)
EC-M1.3	Câu chữ state Empty nói "Tài khoản này…" dù workspace không có đăng nhập	Hiện đúng câu chữ trong code; không phân biệt người dùng (NFR-P-01, OQ-P-13)

Màn M2 - Khung workspace (Shell) + sidebar

Field	Value
Figma frame	N/A — as-built, không có Figma
Trigger vào màn	Mọi route /works/sapp/tools/*
Mô tả ngắn	Khung "SAPP Tools" bọc mọi tool: sidebar theo nhóm, breadcrumb Works › SAPP › <tool>, nút "Về Works", công tắc giao diện tối, vùng nội dung tool

UI States

State	Khi nào	Hiển thị	Figma frame
Default	Trạng thái tool đã tải	Sidebar 6 nhóm; tool mở là link; tool đóng có nhãn "Off"	N/A
Loading	Đang tải trạng thái	Tool trong sidebar mờ nhấp nháy, không bấm được (tooltip "Đang kiểm tra trạng thái tool…")	N/A
Has data	Đang ở một tool	Tool đó được tô đậm; nhóm chứa nó không thu được (tooltip "Nhóm chứa tool đang mở")	N/A
Empty	Một nhóm không còn tool nào hiện	Ẩn cả tiêu đề nhóm	N/A
Error	Đọc trạng thái lỗi	Mọi tool đóng; vùng nội dung hiện panel lỗi của cổng chặn (US-P02)	N/A
Disabled	Tool đóng	Không phải link, nhãn "Off", tooltip "Tool này hiện không khả dụng"	N/A

Fields

Danh mục tool hiển thị (Fact — fe/src/ui/pages/works/sapp/tools/registry.ts:39-111, fe/src/data/constants/tool-codes.ts:32-44):

Nhóm sidebar	Nhãn tool (slug → mã)
SAPP Common Hubspot Tools	Clone (hs-clone-prod-to-dev → sapp.001) · Snapshot (hs-snapshot-property → sapp.002) · Property (hs-get-property → sapp.003) · Pipeline (hs-pipeline → sapp.004)
SAPP 20603 - EContract	Retry econtract (econtract → sapp.005) · Check luồng econtract (econtract-timeline → sapp.012) · Thống kê lỗi econtract (econtract-error-stats → sapp.013)
SAPP 24395 - Tự động ghi nhận doanh thu	Contact / Deal instances (sapp-24395 → sapp.006) · Bulk product creation (sapp-24395-products → sapp.007)
SAPP 23954 - Ticket Owner	Query & Refresh tickets (sapp-23954 → sapp.008) · Check snapshot (sapp-23954-snapshot → sapp.009)
SAPP 26878 - Doanh thu thực hiện (Ops → HubSpot → SAP)	Test data theo luồng (sapp-26878 → sapp.010)
SAPP 26297 - Chuyển nhượng học viên	Test theo luồng (sapp-26297 → sapp.011)

Field	Required	Type	Default	Format	Validation	Error Message	Visibility	Depends On
Mục tool trong sidebar	—	Link / mục vô hiệu	—	Nhãn + icon	BR-06, BR-07	—	Ẩn nếu tool không có trong danh sách public	Trạng thái tool (US-P02)
Thanh icon (thu sidebar)	—	Công tắc	Thu nếu màn < 1280 px	—	BR-09	—	Chỉ màn ≥ sm	—
Giao diện tối	—	Công tắc	Theo hệ điều hành	—	BR-09	—	Always	—

Filter / Search / Sort

N/A — sidebar không có tìm kiếm/lọc.

Actions

A1 - Mở một tool

Item	Description
Trigger	Bấm tool trong sidebar, hoặc mở link /works/sapp/tools/<slug>
Behavior	Vùng nội dung hiển thị qua cổng chặn (BR-13); tool được ghi nhớ (BR-11). Không ghi dữ liệu vào hệ thống nào ngoài bộ nhớ trình duyệt
Success Result	Nội dung tool hiện (nếu tool mở)

Error cases:

Case	Expected Handling
Tool đóng / khoá / trạng thái lỗi	Panel tương ứng của cổng chặn (US-P02)

A2 - Thu/mở nhóm · thu sidebar · đổi giao diện

Item	Description
Trigger	Bấm tiêu đề nhóm / nút "Thu gọn danh sách tool" / công tắc "Giao diện tối"
Behavior	Đổi hiển thị và lưu lựa chọn vào bộ nhớ trình duyệt (BR-08, BR-09)
Success Result	Lần mở sau giữ nguyên lựa chọn

Error cases:

Case	Expected Handling
Bộ nhớ trình duyệt bị chặn	Đổi được trong phiên, lần sau về mặc định (BR-12)

A3 - Về Works

Item	Description
Trigger	Bấm "Về Works" hoặc mục "Works" trên breadcrumb
Behavior	Điều hướng tới /works
Success Result	Rời workspace SAPP

Error cases:

Case	Expected Handling
—	N/A — chỉ điều hướng

Acceptance Criteria của màn M2

AC-M2.1 - Tool đóng hiện "Off"

Given tool sapp.004 có trong danh sách public nhưng đang tắt
When shell hiển thị sidebar
Then mục "Pipeline" hiện nhãn "Off", không phải link và không bấm được

Maps to:

• Business Rule: BR-06

AC-M2.2 - Tool ẩn biến mất, nhóm rỗng bị ẩn

Given cả sapp.008 và sapp.009 không có trong danh sách public
When shell hiển thị sidebar
Then tiêu đề nhóm "SAPP 23954 - Ticket Owner" không xuất hiện

Maps to:

• Business Rule: BR-06

AC-M2.3 - Trạng thái đang tải

Given trạng thái tool chưa tải xong
When người dùng nhìn sidebar
Then mọi tool hiện mờ và không bấm được

Maps to:

• Business Rule: BR-07

AC-M2.4 - Nhớ nhóm thu gọn

Given người dùng thu nhóm "SAPP 24395 - Tự động ghi nhận doanh thu" khi đang ở tool của nhóm khác
When người dùng tải lại trang
Then nhóm đó vẫn thu
And nhóm chứa tool đang mở không thu được khi bấm

Maps to:

• Business Rule: BR-08

AC-M2.5 - Tự thu sidebar và theo giao diện hệ điều hành

Given người dùng chưa từng chọn thu sidebar hay giao diện
And màn rộng 1200 px, hệ điều hành đang ở chế độ tối
When mở workspace
Then sidebar ở dạng thanh icon và giao diện tối

Maps to:

• Business Rule: BR-09

AC-M2.6 - Ngăn kéo trên điện thoại

Given màn điện thoại
When người dùng mở danh sách tool rồi chọn một tool
Then ngăn kéo đóng và tool được mở

Maps to:

• Business Rule: BR-10

AC-M2.7 - Ghi nhớ tool vừa mở

Given người dùng mở tool "sapp-26878"
When lần sau mở /works/sapp/tools và sapp.010 còn mở
Then người dùng được đưa lại sapp-26878

Maps to:

• Business Rule: BR-11, BR-02

AC-M2.8 - Link chia sẻ vẫn qua cổng chặn

Given người dùng mở link /works/sapp/tools/hs-pipeline trực tiếp
When tool sapp.004 đang tắt
Then vùng nội dung hiện "Tool đã bị tắt" (US-P02), không hiện nội dung tool

Maps to:

• Business Rule: BR-13

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

ID	Tình huống	Hành vi mong đợi
EC-M2.1	Bộ nhớ trình duyệt không đọc được	Dùng mặc định (nhóm mở, sidebar theo độ rộng, giao diện theo hệ điều hành), không lỗi (BR-12)
EC-M2.2	Tên hiển thị của tool khác nhau giữa sidebar và mã/tên trong DB (vd sapp.010)	Sidebar dùng nhãn danh mục FE; tên chuẩn chưa chốt (OQ-P-17)
EC-M2.3	Trạng thái chỉ tải một lần khi vào workspace; admin tắt tool trong lúc người dùng đang mở	Sidebar/cổng chặn không tự cập nhật đến khi tải lại trang (fe/src/ui/components/works/shared/use-tools-state.ts:40-77)
EC-M2.4	Giao diện ẩn/khoá tool không phải ranh giới bảo mật	⚠️ Observed — API tool vẫn gọi được trực tiếp (NFR-P-01, NFR-P-02, OQ-P-04)

5. Cross-feature AC

AC-X.1 - Mọi FS nhóm dùng chung khung này

Given một tool bất kỳ sapp.001–sapp.013
When người dùng mở tool đó
Then tool hiển thị trong shell của US-P01 và qua cổng chặn US-P02; FS nhóm không mô tả lại sidebar/cổng chặn

Maps to:

• REL-01…REL-06 (Be Affected - 6 FS nhóm tool)