docs: add stage 1.5 shadcn ui design
This commit is contained in:
hailin
@@ -24,6 +24,7 @@ The product contains multiple independent subsystems. Do not implement the entir
|
|||||||
|---|---|---|---|---|
|
|---|---|---|---|---|
|
||||||
| 0 | Foundation and design system | Create the repo skeleton, local runtime, auth/RBAC baseline, audit baseline, frontend theme and component standards. | None | `docs/superpowers/plans/2026-06-30-stage-0-foundation-design-system.md` |
|
| 0 | Foundation and design system | Create the repo skeleton, local runtime, auth/RBAC baseline, audit baseline, frontend theme and component standards. | None | `docs/superpowers/plans/2026-06-30-stage-0-foundation-design-system.md` |
|
||||||
| 1 | Ticket workflow and reusable solutions | Implement ticket lifecycle, comments, attachments, events, export, solution library, and solution links. | Stage 0 | Create after Stage 0 passes. |
|
| 1 | Ticket workflow and reusable solutions | Implement ticket lifecycle, comments, attachments, events, export, solution library, and solution links. | Stage 0 | Create after Stage 0 passes. |
|
||||||
|
| 1.5 | shadcn enterprise UI foundation | Formalize shadcn/ui initialization, add a project-owned App component layer, redesign current ticket and solution pages, and enforce Chinese frontend text. | Stage 1 | `docs/superpowers/specs/2026-07-01-stage-1-5-shadcn-ui-foundation-design.md` |
|
||||||
| 2 | Knowledge base and vector retrieval | Implement knowledge bases, documents, parsing jobs, chunks, embeddings, and retrieval. | Stage 0, partial Stage 1 | Create after Stage 1 model contracts stabilize. |
|
| 2 | Knowledge base and vector retrieval | Implement knowledge bases, documents, parsing jobs, chunks, embeddings, and retrieval. | Stage 0, partial Stage 1 | Create after Stage 1 model contracts stabilize. |
|
||||||
| 3 | Model gateway and Agent/Skill runtime | Implement provider configs, model configs, model testing, Skill configs, built-in Agents, runs, steps, AI artifacts. | Stage 0, Stage 1, Stage 2 retrieval interfaces | Create after Stage 2 retrieval contracts exist. |
|
| 3 | Model gateway and Agent/Skill runtime | Implement provider configs, model configs, model testing, Skill configs, built-in Agents, runs, steps, AI artifacts. | Stage 0, Stage 1, Stage 2 retrieval interfaces | Create after Stage 2 retrieval contracts exist. |
|
||||||
| 4 | MCP tools and trust boundary | Implement MCP server registration, tool sync, risk levels, Agent tool binding, tool calls, confirmation, audit. | Stage 3 | Create after Agent runtime exists. |
|
| 4 | MCP tools and trust boundary | Implement MCP server registration, tool sync, risk levels, Agent tool binding, tool calls, confirmation, audit. | Stage 3 | Create after Agent runtime exists. |
|
||||||
@@ -96,4 +97,3 @@ The product contains multiple independent subsystems. Do not implement the entir
|
|||||||
- Every backend stage includes API tests.
|
- Every backend stage includes API tests.
|
||||||
- Every frontend stage includes typecheck and build verification.
|
- Every frontend stage includes typecheck and build verification.
|
||||||
- Commit after each coherent task.
|
- Commit after each coherent task.
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,240 @@
|
|||||||
|
# Stage 1.5 shadcn UI Foundation Design
|
||||||
|
|
||||||
|
## Background
|
||||||
|
|
||||||
|
Stage 0 established a basic frontend shell and local UI primitives. Stage 1 added ticket and solution pages. The current implementation is functional, but it is still closer to a demo workflow than an enterprise-grade workbench:
|
||||||
|
|
||||||
|
- The frontend has Tailwind CSS and local component primitives, but it has not been formally initialized as a shadcn/ui project.
|
||||||
|
- `frontend/components.json` does not exist, and `npx shadcn@latest info` reports `config: null` and `components: []`.
|
||||||
|
- Ticket list, ticket detail, ticket creation, and solution pages work, but the visual hierarchy, table capability, filtering, empty states, and operation layout are too thin for later enterprise modules.
|
||||||
|
- Some user-facing frontend text is still English, while the product requirement is Chinese-first.
|
||||||
|
|
||||||
|
Stage 1.5 is therefore inserted between Stage 1 and Stage 2. Its purpose is to stabilize the UI base before adding knowledge base, model gateway, Agent, Skill, MCP, and governance-heavy screens.
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
|
||||||
|
Adopt option A from the UI direction discussion:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Formal shadcn/ui initialization
|
||||||
|
↓
|
||||||
|
Project-owned App component layer
|
||||||
|
↓
|
||||||
|
Chinese enterprise ticket workbench pages
|
||||||
|
```
|
||||||
|
|
||||||
|
Use `satnaing/shadcn-admin` as an aesthetic and layout reference, not as a direct source transplant. The project keeps its current Vite React structure and npm package manager.
|
||||||
|
|
||||||
|
## Goals
|
||||||
|
|
||||||
|
1. Convert the frontend from "local shadcn-like primitives" to a real shadcn/ui-based project.
|
||||||
|
2. Build a reusable enterprise admin UI layer for future modules.
|
||||||
|
3. Redesign the current ticket and solution pages around a Chinese workbench experience.
|
||||||
|
4. Make ticket tables feel production-ready with filtering, status/priority presentation, row actions, and pagination-ready structure.
|
||||||
|
5. Make ticket detail feel like an operations workspace, not a field dump.
|
||||||
|
6. Ensure all user-visible frontend text in this stage is Chinese.
|
||||||
|
|
||||||
|
## Non-Goals
|
||||||
|
|
||||||
|
- Do not add Stage 2 knowledge base backend models.
|
||||||
|
- Do not implement Agent, Skill, MCP, or model gateway behavior.
|
||||||
|
- Do not replace Vite with Next.js.
|
||||||
|
- Do not switch npm to pnpm.
|
||||||
|
- Do not copy the shadcn-admin repository wholesale.
|
||||||
|
- Do not implement real authentication screens unless required by existing routing.
|
||||||
|
|
||||||
|
## UI Style Direction
|
||||||
|
|
||||||
|
The target is a simple, modern, dense enterprise application:
|
||||||
|
|
||||||
|
- Quiet operational layout instead of marketing-style pages.
|
||||||
|
- Left sidebar navigation with grouped Chinese modules.
|
||||||
|
- Topbar focused on breadcrumb, global actions, and user/system status.
|
||||||
|
- Clean card usage only for repeated items, metrics, or framed tools.
|
||||||
|
- Data-heavy pages use tables, filters, compact toolbars, and clear status badges.
|
||||||
|
- Detail pages use a workbench layout with primary content, timeline, and side panels.
|
||||||
|
- Colors come from theme tokens and component variants, not one-off page colors.
|
||||||
|
|
||||||
|
## Required shadcn/ui Base
|
||||||
|
|
||||||
|
The frontend should be initialized with the shadcn CLI using npm:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd frontend
|
||||||
|
npx shadcn@latest init
|
||||||
|
```
|
||||||
|
|
||||||
|
The implementation plan may adjust exact CLI flags based on the current CLI prompt format, but it must preserve:
|
||||||
|
|
||||||
|
- Vite framework.
|
||||||
|
- TypeScript.
|
||||||
|
- Tailwind CSS v3.
|
||||||
|
- `@` import alias.
|
||||||
|
- Existing `frontend/src/styles/globals.css`.
|
||||||
|
- Existing `frontend/tailwind.config.ts`.
|
||||||
|
|
||||||
|
Add only the components required by the first UI base pass. Expected components include:
|
||||||
|
|
||||||
|
- `button`
|
||||||
|
- `badge`
|
||||||
|
- `card`
|
||||||
|
- `input`
|
||||||
|
- `textarea`
|
||||||
|
- `select`
|
||||||
|
- `label`
|
||||||
|
- `separator`
|
||||||
|
- `sidebar`
|
||||||
|
- `breadcrumb`
|
||||||
|
- `dropdown-menu`
|
||||||
|
- `table`
|
||||||
|
- `tabs`
|
||||||
|
- `sheet`
|
||||||
|
- `dialog`
|
||||||
|
- `tooltip`
|
||||||
|
- `skeleton`
|
||||||
|
- `sonner`
|
||||||
|
|
||||||
|
If a component is unavailable or named differently in the installed shadcn CLI version, use the current official equivalent and document the difference in the implementation notes.
|
||||||
|
|
||||||
|
## Product Component Layer
|
||||||
|
|
||||||
|
Create project-owned components under `frontend/src/components/app`. These components form the stable API for business pages.
|
||||||
|
|
||||||
|
Required components:
|
||||||
|
|
||||||
|
| Component | Purpose |
|
||||||
|
|---|---|
|
||||||
|
| `AppShell` | Overall application frame with sidebar, topbar, content area, and responsive behavior. |
|
||||||
|
| `AppSidebar` | Chinese navigation groups for workbench, tickets, knowledge, solutions, agents, models/tools, and system management. |
|
||||||
|
| `AppTopbar` | Breadcrumb, page context, quick actions, and system/user placeholder controls. |
|
||||||
|
| `AppPageHeader` | Consistent title, description, actions, and optional metadata. |
|
||||||
|
| `AppDataTable` | Reusable table wrapper with toolbar slot, empty state, row actions, and pagination-ready footer. |
|
||||||
|
| `AppFilterBar` | Search, select filters, date/status placeholders, and reset action layout. |
|
||||||
|
| `AppDetailLayout` | Workbench layout for detail pages with main column, timeline/content panels, and right side panel. |
|
||||||
|
| `AppSection` | Lightweight section wrapper for grouped fields or activity blocks. |
|
||||||
|
| `AppStatusBadge` | Unified Chinese status badge for ticket lifecycle. |
|
||||||
|
| `AppPriorityBadge` | Unified Chinese priority badge. |
|
||||||
|
| `AppEmptyState` | Chinese empty-state pattern with optional action. |
|
||||||
|
|
||||||
|
Business pages should use these App components instead of importing shadcn primitives directly for layout-level concerns.
|
||||||
|
|
||||||
|
## Page Redesign Scope
|
||||||
|
|
||||||
|
### 1. Workbench Home
|
||||||
|
|
||||||
|
The default application view should feel like an operations console:
|
||||||
|
|
||||||
|
- Key ticket counters.
|
||||||
|
- Pending/high-priority/processing overview.
|
||||||
|
- Recent ticket activity placeholder using current available ticket data.
|
||||||
|
- Quick links to create ticket and solution library.
|
||||||
|
|
||||||
|
### 2. Ticket List
|
||||||
|
|
||||||
|
Redesign into an enterprise table page:
|
||||||
|
|
||||||
|
- Chinese page title and description.
|
||||||
|
- Filter bar with keyword, status, priority, and owner placeholders.
|
||||||
|
- Metric strip for ticket states.
|
||||||
|
- Data table with stable columns:
|
||||||
|
- 编号
|
||||||
|
- 标题
|
||||||
|
- 状态
|
||||||
|
- 优先级
|
||||||
|
- 分类
|
||||||
|
- 负责人
|
||||||
|
- 创建时间
|
||||||
|
- 操作
|
||||||
|
- Empty state in Chinese.
|
||||||
|
- Row actions such as 查看详情 and 关联方案 where supported by current routes.
|
||||||
|
|
||||||
|
### 3. Ticket Create
|
||||||
|
|
||||||
|
Redesign into a guided creation surface:
|
||||||
|
|
||||||
|
- Chinese labels and helper text.
|
||||||
|
- Clear sectioning for problem description, classification, priority, requester/contact, and attachments placeholder.
|
||||||
|
- Right-side or inline "后续 AI 建单辅助" placeholder panel, clearly marked as upcoming capability without implying it works now.
|
||||||
|
|
||||||
|
### 4. Ticket Detail
|
||||||
|
|
||||||
|
Redesign into a workbench:
|
||||||
|
|
||||||
|
- Header with ticket title, status, priority, and primary actions.
|
||||||
|
- Main problem summary and field sections.
|
||||||
|
- Status timeline and comments as operational activity.
|
||||||
|
- Side panel for linked solutions and future AI support analysis placeholder.
|
||||||
|
- Use Chinese labels for all states, fields, actions, and empty states.
|
||||||
|
|
||||||
|
### 5. Solution List
|
||||||
|
|
||||||
|
Redesign as a knowledge asset list:
|
||||||
|
|
||||||
|
- Chinese title and description.
|
||||||
|
- Search/filter toolbar.
|
||||||
|
- Table or structured list with category, effectiveness/use count placeholder, update time, and actions.
|
||||||
|
- Make the page visually aligned with ticket pages.
|
||||||
|
|
||||||
|
### 6. Design System Preview
|
||||||
|
|
||||||
|
Update preview page to show the new UI base:
|
||||||
|
|
||||||
|
- shadcn primitives.
|
||||||
|
- App components.
|
||||||
|
- Chinese status, priority, table, filters, section, and empty states.
|
||||||
|
|
||||||
|
## Chinese Localization Requirement
|
||||||
|
|
||||||
|
All frontend user-visible text touched by Stage 1.5 must be Chinese:
|
||||||
|
|
||||||
|
- Navigation labels.
|
||||||
|
- Page titles and descriptions.
|
||||||
|
- Button labels.
|
||||||
|
- Empty states.
|
||||||
|
- Form labels and placeholders.
|
||||||
|
- Status and priority labels.
|
||||||
|
- Table columns.
|
||||||
|
- Toasts or inline feedback.
|
||||||
|
|
||||||
|
Internal variable names, file names, TypeScript types, API field names, and backend enum values may stay English.
|
||||||
|
|
||||||
|
## Compatibility Requirements
|
||||||
|
|
||||||
|
- Existing backend APIs remain unchanged.
|
||||||
|
- Existing Stage 1 frontend routes remain reachable.
|
||||||
|
- Existing tests and type checks must continue to pass.
|
||||||
|
- Docker Compose deployment should still be compatible with the frontend build output.
|
||||||
|
- The project must continue to use npm for frontend package management.
|
||||||
|
|
||||||
|
## Verification
|
||||||
|
|
||||||
|
Stage 1.5 is complete only when:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd frontend
|
||||||
|
npm run typecheck
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
both pass, and the local app visually shows:
|
||||||
|
|
||||||
|
- shadcn initialized with `components.json`.
|
||||||
|
- Chinese sidebar/topbar navigation.
|
||||||
|
- redesigned workbench, ticket list, ticket create, ticket detail, and solution list pages.
|
||||||
|
|
||||||
|
Backend tests are not required for Stage 1.5 unless backend code is modified. If backend code is changed unexpectedly, run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python -m pytest -v
|
||||||
|
python -m ruff check .
|
||||||
|
```
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- `frontend/components.json` exists and matches the Vite/Tailwind/TypeScript project.
|
||||||
|
- The frontend uses shadcn-generated primitives where applicable.
|
||||||
|
- Business pages consume the project-owned App component layer for layout and repeated UI patterns.
|
||||||
|
- The current crude ticket table is replaced by a denser, clearer enterprise table experience.
|
||||||
|
- Ticket detail reads as an operational workbench.
|
||||||
|
- User-facing frontend text touched in this stage is Chinese.
|
||||||
|
- No new Stage 2/3/4 backend capability is introduced.
|
||||||
Reference in New Issue
Block a user