docs: add stage 1.7 ticket visual redesign spec
This commit is contained in:
hailin
@@ -0,0 +1,454 @@
|
|||||||
|
# Stage 1.7 Ticket Experience Visual Redesign Design
|
||||||
|
|
||||||
|
## Background
|
||||||
|
|
||||||
|
Stage 1.6 has established the enterprise governance baseline: login, session-authenticated APIs, backend-driven menus, roles, users, user groups, permission enforcement, and Docker bootstrap.
|
||||||
|
|
||||||
|
The ticket workflow is now protected and usable, but the current ticket UI still feels like a basic demo:
|
||||||
|
|
||||||
|
- The ticket list is a simple table with limited visual hierarchy.
|
||||||
|
- The detail page exposes actions as flat buttons without enough workflow context.
|
||||||
|
- The create page has rough spacing and a few English fallback strings remain in the detail page.
|
||||||
|
- The UI does not yet communicate an enterprise support operations workflow.
|
||||||
|
|
||||||
|
Stage 1.7 intentionally prioritizes visual and interaction quality for the ticket surfaces before deeper backend capabilities such as SLA, batch operations, attachment upload, or row-level permissions.
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
|
||||||
|
Create Stage 1.7 as a visual-first ticket experience stage:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Stage 1.6 = enterprise governance, login, permission menus, deployment bootstrap
|
||||||
|
Stage 1.7 = ticket list/detail/create visual redesign using shadcn/ui
|
||||||
|
Stage 1.8+ = deeper ticket workflow capabilities, SLA, attachments, batch operations
|
||||||
|
Stage 2 = knowledge base and vector retrieval
|
||||||
|
```
|
||||||
|
|
||||||
|
The frontend must use the existing shadcn/ui foundation. New visual work must compose shadcn primitives and existing app-level components rather than introducing a new UI library or ad hoc styled widgets.
|
||||||
|
|
||||||
|
## Goals
|
||||||
|
|
||||||
|
1. Redesign the ticket center as an enterprise operations table, not a simple record list.
|
||||||
|
2. Redesign the ticket detail page around clear workflow context, status timeline, comments, and right-side metadata.
|
||||||
|
3. Redesign the create ticket page into a polished grouped form with Chinese labels and helper copy.
|
||||||
|
4. Keep all visible frontend copy in Chinese.
|
||||||
|
5. Use shadcn/ui components for all new controls, feedback, overlays, status display, and layout surfaces.
|
||||||
|
6. Add only the backend support needed for the redesigned UI, such as pagination, richer filters, and basic requester/assignee display fields.
|
||||||
|
|
||||||
|
## Non-Goals
|
||||||
|
|
||||||
|
- No SLA engine.
|
||||||
|
- No real attachment upload pipeline.
|
||||||
|
- No batch operations.
|
||||||
|
- No Kanban board.
|
||||||
|
- No row-level data permission.
|
||||||
|
- No field-level permission.
|
||||||
|
- No AI ticket drafting implementation.
|
||||||
|
- No knowledge base retrieval implementation.
|
||||||
|
- No new authentication or authorization model.
|
||||||
|
- No replacement of the existing shadcn preset or theme.
|
||||||
|
|
||||||
|
## UI System Requirements
|
||||||
|
|
||||||
|
The implementation must use the existing project shadcn setup:
|
||||||
|
|
||||||
|
- Framework: Vite + React + TypeScript.
|
||||||
|
- Styling: Tailwind CSS v3.
|
||||||
|
- shadcn style: `radix-nova`.
|
||||||
|
- Icon library: `lucide-react`.
|
||||||
|
- Component source: local shadcn files under `frontend/src/components/ui`.
|
||||||
|
|
||||||
|
Required shadcn primitives for Stage 1.7:
|
||||||
|
|
||||||
|
- Already installed: `button`, `badge`, `card`, `dialog`, `input`, `label`, `pagination`, `select`, `separator`, `skeleton`, `sonner`, `table`, `tabs`, `textarea`, `tooltip`.
|
||||||
|
- Add only if needed through `npx shadcn@latest add`: `sheet`, `popover`, `calendar`, `command`, `toggle-group`, `scroll-area`, `empty`.
|
||||||
|
|
||||||
|
Important compatibility rule:
|
||||||
|
|
||||||
|
- The project uses Tailwind CSS v3. Any newly generated shadcn component must be reviewed after `npx shadcn@latest add` and patched if the generated file contains Tailwind v4-only state selectors or syntax that does not compile or render correctly in the current project.
|
||||||
|
|
||||||
|
## Ticket List Redesign
|
||||||
|
|
||||||
|
Route:
|
||||||
|
|
||||||
|
```text
|
||||||
|
#/tickets
|
||||||
|
```
|
||||||
|
|
||||||
|
The page should become a dense operations console.
|
||||||
|
|
||||||
|
### Layout
|
||||||
|
|
||||||
|
Use a constrained full-width content area similar to the governance pages:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Header
|
||||||
|
Metric cards
|
||||||
|
View tabs
|
||||||
|
Filter bar
|
||||||
|
Ticket table
|
||||||
|
Pagination footer
|
||||||
|
```
|
||||||
|
|
||||||
|
### Header
|
||||||
|
|
||||||
|
Header copy:
|
||||||
|
|
||||||
|
```text
|
||||||
|
工单中心
|
||||||
|
集中查看、筛选和处理企业技术支持工单。
|
||||||
|
```
|
||||||
|
|
||||||
|
Primary action:
|
||||||
|
|
||||||
|
```text
|
||||||
|
新建工单
|
||||||
|
```
|
||||||
|
|
||||||
|
### View Tabs
|
||||||
|
|
||||||
|
Use shadcn `Tabs`:
|
||||||
|
|
||||||
|
```text
|
||||||
|
全部工单
|
||||||
|
我的待办
|
||||||
|
我创建的
|
||||||
|
高优先级
|
||||||
|
```
|
||||||
|
|
||||||
|
Stage 1.7 can implement these as frontend view filters if backend support is not yet complete. The backend should still accept a lightweight `view` query parameter if feasible:
|
||||||
|
|
||||||
|
```text
|
||||||
|
all
|
||||||
|
assigned_to_me
|
||||||
|
created_by_me
|
||||||
|
high_priority
|
||||||
|
```
|
||||||
|
|
||||||
|
### Metrics
|
||||||
|
|
||||||
|
Use shadcn `Card` composition. Cards should be compact and operational:
|
||||||
|
|
||||||
|
```text
|
||||||
|
待处理
|
||||||
|
处理中
|
||||||
|
待确认
|
||||||
|
高优先级
|
||||||
|
```
|
||||||
|
|
||||||
|
### Filters
|
||||||
|
|
||||||
|
Use shadcn `Input` and `Select`:
|
||||||
|
|
||||||
|
```text
|
||||||
|
关键词
|
||||||
|
状态
|
||||||
|
优先级
|
||||||
|
关联系统
|
||||||
|
处理人
|
||||||
|
```
|
||||||
|
|
||||||
|
Date range is intentionally deferred unless a lightweight implementation is available without pulling in extra date complexity.
|
||||||
|
|
||||||
|
### Table Columns
|
||||||
|
|
||||||
|
Use the existing `AppDataTable` or a refined ticket-specific table built from shadcn `Table`.
|
||||||
|
|
||||||
|
Required columns:
|
||||||
|
|
||||||
|
```text
|
||||||
|
编号
|
||||||
|
标题
|
||||||
|
状态
|
||||||
|
优先级
|
||||||
|
关联系统
|
||||||
|
影响范围
|
||||||
|
处理人
|
||||||
|
创建时间
|
||||||
|
操作
|
||||||
|
```
|
||||||
|
|
||||||
|
The title cell should show compact secondary metadata when available, such as environment or requester.
|
||||||
|
|
||||||
|
### Pagination
|
||||||
|
|
||||||
|
Use the existing shadcn-compatible `pagination` component.
|
||||||
|
|
||||||
|
The backend should return pagination metadata if implemented:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"items": [],
|
||||||
|
"page": 1,
|
||||||
|
"page_size": 20,
|
||||||
|
"total": 0,
|
||||||
|
"total_pages": 0
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
If backend pagination is delayed, the frontend may paginate the loaded first 100 rows, but the preferred implementation is backend pagination.
|
||||||
|
|
||||||
|
## Ticket Detail Redesign
|
||||||
|
|
||||||
|
Route:
|
||||||
|
|
||||||
|
```text
|
||||||
|
#/tickets/{id}
|
||||||
|
```
|
||||||
|
|
||||||
|
The page should feel like a ticket operations workspace.
|
||||||
|
|
||||||
|
### Layout
|
||||||
|
|
||||||
|
Use a two-column layout:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Header with title, ticket number, status, priority
|
||||||
|
Main column:
|
||||||
|
问题描述
|
||||||
|
处理记录
|
||||||
|
评论与协作
|
||||||
|
Side column:
|
||||||
|
当前状态
|
||||||
|
处理人
|
||||||
|
请求人
|
||||||
|
关联系统
|
||||||
|
运行环境
|
||||||
|
影响范围
|
||||||
|
关联方案
|
||||||
|
AI 支持分析（占位）
|
||||||
|
```
|
||||||
|
|
||||||
|
### Header Actions
|
||||||
|
|
||||||
|
Replace flat status buttons with workflow-aware actions.
|
||||||
|
|
||||||
|
Use shadcn `Dialog` for status transition:
|
||||||
|
|
||||||
|
```text
|
||||||
|
开始处理
|
||||||
|
提交确认
|
||||||
|
标记解决
|
||||||
|
关闭工单
|
||||||
|
```
|
||||||
|
|
||||||
|
The dialog must require a Chinese handling note:
|
||||||
|
|
||||||
|
```text
|
||||||
|
处理说明
|
||||||
|
请说明本次流转的原因、处理动作或待确认事项。
|
||||||
|
```
|
||||||
|
|
||||||
|
### Timeline
|
||||||
|
|
||||||
|
The timeline must render Chinese event labels:
|
||||||
|
|
||||||
|
```text
|
||||||
|
创建工单
|
||||||
|
更新工单
|
||||||
|
状态变更
|
||||||
|
新增评论
|
||||||
|
新增附件
|
||||||
|
```
|
||||||
|
|
||||||
|
English loading/error fallbacks must be replaced:
|
||||||
|
|
||||||
|
```text
|
||||||
|
无法加载工单
|
||||||
|
正在加载工单
|
||||||
|
```
|
||||||
|
|
||||||
|
### Comments
|
||||||
|
|
||||||
|
Comment UI should distinguish:
|
||||||
|
|
||||||
|
```text
|
||||||
|
内部备注
|
||||||
|
用户可见回复
|
||||||
|
```
|
||||||
|
|
||||||
|
Stage 1.7 may still post to the existing comment endpoint, but the UI should present the two visibility options clearly.
|
||||||
|
|
||||||
|
## Ticket Create Redesign
|
||||||
|
|
||||||
|
Route:
|
||||||
|
|
||||||
|
```text
|
||||||
|
#/tickets/new
|
||||||
|
```
|
||||||
|
|
||||||
|
The create page should be a polished enterprise form, not a loose demo form.
|
||||||
|
|
||||||
|
### Layout
|
||||||
|
|
||||||
|
Use grouped sections:
|
||||||
|
|
||||||
|
```text
|
||||||
|
基础信息
|
||||||
|
影响与优先级
|
||||||
|
环境与系统
|
||||||
|
问题描述
|
||||||
|
提交确认
|
||||||
|
```
|
||||||
|
|
||||||
|
Recommended layout:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Main column: grouped form sections
|
||||||
|
Side column: 建单提示 + AI 建单辅助占位
|
||||||
|
```
|
||||||
|
|
||||||
|
### Required Fields
|
||||||
|
|
||||||
|
```text
|
||||||
|
工单标题
|
||||||
|
问题描述
|
||||||
|
优先级
|
||||||
|
```
|
||||||
|
|
||||||
|
Optional fields:
|
||||||
|
|
||||||
|
```text
|
||||||
|
关联系统
|
||||||
|
运行环境
|
||||||
|
影响范围
|
||||||
|
处理人
|
||||||
|
```
|
||||||
|
|
||||||
|
### Behavior
|
||||||
|
|
||||||
|
- Submit success navigates to the ticket detail page.
|
||||||
|
- Submit failure shows Chinese error feedback.
|
||||||
|
- Empty required fields rely on native validation or shadcn field validation styling.
|
||||||
|
- AI helper remains an understated placeholder, not the visual focus.
|
||||||
|
|
||||||
|
## Backend Support
|
||||||
|
|
||||||
|
Backend changes should remain narrow and visual-support oriented.
|
||||||
|
|
||||||
|
### List Query
|
||||||
|
|
||||||
|
Extend `GET /api/tickets` to support:
|
||||||
|
|
||||||
|
```text
|
||||||
|
page
|
||||||
|
page_size
|
||||||
|
status
|
||||||
|
priority
|
||||||
|
q
|
||||||
|
related_system
|
||||||
|
assignee_id
|
||||||
|
view
|
||||||
|
```
|
||||||
|
|
||||||
|
Suggested response:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"items": [],
|
||||||
|
"page": 1,
|
||||||
|
"page_size": 20,
|
||||||
|
"total": 0,
|
||||||
|
"total_pages": 0
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Ticket Output
|
||||||
|
|
||||||
|
Add basic display user fields to ticket output:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"requester": {"id": 1, "display_name": "张三", "username": "zhangsan"},
|
||||||
|
"assignee": {"id": 2, "display_name": "李四", "username": "lisi"}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Existing `requester_id` and `assignee_id` may remain if useful.
|
||||||
|
|
||||||
|
### Status Transition
|
||||||
|
|
||||||
|
The existing status transition endpoint can remain:
|
||||||
|
|
||||||
|
```text
|
||||||
|
POST /api/tickets/{id}/status
|
||||||
|
```
|
||||||
|
|
||||||
|
The frontend dialog should always send a non-empty remark. Backend validation for non-empty remark is preferred if it can be added with tests.
|
||||||
|
|
||||||
|
### Assignment
|
||||||
|
|
||||||
|
If needed for the detail side panel, use the existing `PATCH /api/tickets/{id}` with `assignee_id`. A dedicated assignment endpoint is deferred unless it materially simplifies UI code.
|
||||||
|
|
||||||
|
## Frontend File Scope
|
||||||
|
|
||||||
|
Expected files to touch:
|
||||||
|
|
||||||
|
```text
|
||||||
|
frontend/src/features/tickets/types.ts
|
||||||
|
frontend/src/features/tickets/api.ts
|
||||||
|
frontend/src/features/tickets/TicketListPage.tsx
|
||||||
|
frontend/src/features/tickets/TicketDetailPage.tsx
|
||||||
|
frontend/src/features/tickets/TicketCreatePage.tsx
|
||||||
|
frontend/src/features/tickets/TicketComments.tsx
|
||||||
|
frontend/src/features/tickets/TicketStatusTimeline.tsx
|
||||||
|
frontend/src/components/app/AppDataTable.tsx
|
||||||
|
frontend/src/components/app/AppEmptyState.tsx
|
||||||
|
```
|
||||||
|
|
||||||
|
Add small ticket-specific components only when they reduce page complexity:
|
||||||
|
|
||||||
|
```text
|
||||||
|
frontend/src/features/tickets/TicketMetricCards.tsx
|
||||||
|
frontend/src/features/tickets/TicketFilterBar.tsx
|
||||||
|
frontend/src/features/tickets/TicketTransitionDialog.tsx
|
||||||
|
frontend/src/features/tickets/TicketMetaPanel.tsx
|
||||||
|
```
|
||||||
|
|
||||||
|
## Testing Requirements
|
||||||
|
|
||||||
|
Backend tests:
|
||||||
|
|
||||||
|
- Ticket list pagination returns metadata and items.
|
||||||
|
- Ticket list filters by status, priority, related system, keyword, and view.
|
||||||
|
- Ticket output includes requester and assignee display fields.
|
||||||
|
- Status transition with an empty remark is rejected if backend validation is implemented.
|
||||||
|
|
||||||
|
Frontend verification:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd frontend
|
||||||
|
npm run typecheck
|
||||||
|
npm run build
|
||||||
|
npx shadcn@latest info
|
||||||
|
```
|
||||||
|
|
||||||
|
Backend verification:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd backend
|
||||||
|
python -m pytest apps/tickets/tests -v
|
||||||
|
python -m pytest apps/accounts/tests/test_permission_enforcement.py -v
|
||||||
|
python -m ruff check .
|
||||||
|
```
|
||||||
|
|
||||||
|
Browser visual smoke test:
|
||||||
|
|
||||||
|
- Login as seeded admin.
|
||||||
|
- Open `#/tickets`.
|
||||||
|
- Verify the ticket list renders Chinese tabs, metric cards, filters, table, and pagination.
|
||||||
|
- Open a ticket detail page.
|
||||||
|
- Verify status actions open a Chinese dialog requiring handling note.
|
||||||
|
- Open `#/tickets/new`.
|
||||||
|
- Verify grouped Chinese create form renders without overlap.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- Ticket list, detail, and create pages look like a coherent enterprise admin product.
|
||||||
|
- All visible copy in ticket pages is Chinese.
|
||||||
|
- New UI uses shadcn/ui components and existing app-level components.
|
||||||
|
- No new UI library is introduced.
|
||||||
|
- Backend changes are limited to pagination, filters, display fields, and remark validation if implemented.
|
||||||
|
- Existing authentication and permission enforcement continue to work.
|
||||||
|
- `npm run typecheck`, `npm run build`, backend ticket tests, and ruff pass.
|
||||||
|
- Browser screenshots show no obvious text overlap, broken layout, or blank states on desktop.
|
||||||
Reference in New Issue
Block a user