diff --git a/docs/superpowers/plans/2026-06-30-ai-ticket-platform-implementation-roadmap.md b/docs/superpowers/plans/2026-06-30-ai-ticket-platform-implementation-roadmap.md index 52991bb..6a5e515 100644 --- a/docs/superpowers/plans/2026-06-30-ai-ticket-platform-implementation-roadmap.md +++ b/docs/superpowers/plans/2026-06-30-ai-ticket-platform-implementation-roadmap.md @@ -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` | | 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. | | 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. | @@ -96,4 +97,3 @@ The product contains multiple independent subsystems. Do not implement the entir - Every backend stage includes API tests. - Every frontend stage includes typecheck and build verification. - Commit after each coherent task. - diff --git a/docs/superpowers/specs/2026-07-01-stage-1-5-shadcn-ui-foundation-design.md b/docs/superpowers/specs/2026-07-01-stage-1-5-shadcn-ui-foundation-design.md new file mode 100644 index 0000000..c61a0cb --- /dev/null +++ b/docs/superpowers/specs/2026-07-01-stage-1-5-shadcn-ui-foundation-design.md @@ -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.