docs: add stage 2.5 frontend prototype design
This commit is contained in:
hailin
@@ -0,0 +1,219 @@
|
||||
# Stage 2.5 Global Frontend Prototype Design
|
||||
|
||||
Date: 2026-07-06
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
Stage 2.5 changes the near-term implementation order from backend-first to frontend-product-first. The goal is to expose the full product shape quickly through a Chinese, shadcn-based, interactive frontend prototype while preserving the original system blueprint.
|
||||
|
||||
This stage does not replace backend stages 3 to 5. It creates the UI shell, mock data contracts, page routes, interaction states, and interface expectations that later backend APIs will implement.
|
||||
|
||||
## 2. Product Goal
|
||||
|
||||
Build a complete visible product skeleton for the AI ticket platform:
|
||||
|
||||
- Workbench
|
||||
- Ticket center
|
||||
- Ticket detail and creation
|
||||
- Solution library
|
||||
- Knowledge base and knowledge search
|
||||
- Model providers and model testing
|
||||
- Agent configuration and agent runs
|
||||
- Skill configuration
|
||||
- MCP tools and risk controls
|
||||
- System management and audit
|
||||
|
||||
The result should feel like a coherent enterprise product rather than a set of isolated demo pages.
|
||||
|
||||
## 3. Core Decisions
|
||||
|
||||
| Topic | Decision |
|
||||
|---|---|
|
||||
| Implementation priority | Frontend UI and interactions first, backend APIs later. |
|
||||
| Data source | Use a project-owned mock data layer for pages whose backend does not exist yet. |
|
||||
| UI library | Continue using shadcn/ui, Tailwind CSS, Radix primitives, lucide-react, and project-owned `App*` components. |
|
||||
| Language | All user-facing frontend text must be Chinese. |
|
||||
| Visual direction | Enterprise-grade, clean, calm, information-dense, and suitable for repeated operational use. |
|
||||
| API impact | Each mock module must document the future API contract through typed data structures and page behavior. |
|
||||
| Backend impact | Do not add backend models or APIs in this stage unless a tiny adapter is required to keep existing pages working. |
|
||||
|
||||
## 4. Scope
|
||||
|
||||
### Included
|
||||
|
||||
- Global navigation that exposes the full product map.
|
||||
- Frontend pages for all planned stage modules.
|
||||
- Mock data for model providers, model tests, Agents, Agent runs, Skills, MCP tools, dashboards, and contract-only pages.
|
||||
- Shared empty, loading, error, approval, risk, and trace states.
|
||||
- UI contracts for actions such as model test, Agent run inspection, Skill edit, MCP sync, and high-risk confirmation.
|
||||
- Documentation updates describing the frontend-first strategy and mock-to-real replacement path.
|
||||
|
||||
### Excluded
|
||||
|
||||
- Real LLM calls.
|
||||
- Real model provider persistence.
|
||||
- Real Agent execution.
|
||||
- Real MCP server connection.
|
||||
- Historical ticket import.
|
||||
- Backend API implementation for Stage 3, Stage 4, or Stage 5.
|
||||
- Replacing current working ticket, solution, knowledge, and system APIs with mocks.
|
||||
|
||||
## 5. Navigation Shape
|
||||
|
||||
The sidebar should present these product groups:
|
||||
|
||||
| Group | Routes |
|
||||
|---|---|
|
||||
| 工作台 | `/`, `/dashboard` |
|
||||
| 工单中心 | `/tickets`, `/tickets/new`, `/tickets/:id` |
|
||||
| 知识与方案 | `/knowledge`, `/knowledge/search`, `/knowledge/items/new`, `/solutions`, `/solutions/new` |
|
||||
| Agent | `/agents`, `/agents/runs`, `/agents/runs/:id` |
|
||||
| 模型与工具 | `/modelhub/providers`, `/modelhub/testing`, `/tools/mcp` |
|
||||
| 系统管理 | `/system/users`, `/system/user-groups`, `/system/roles`, `/system/menus`, `/audit` |
|
||||
| 设计系统 | `/design-system` |
|
||||
|
||||
Existing backend-driven menus can remain, but the frontend prototype must ensure these new pages are reachable during local development. If backend menu data does not yet include the new modules, the sidebar may append built-in prototype entries while avoiding duplicate entries.
|
||||
|
||||
## 6. Page Requirements
|
||||
|
||||
### 6.1 Workbench And Dashboard
|
||||
|
||||
Workbench should become the first full-system overview:
|
||||
|
||||
- Pending tickets
|
||||
- High-priority tickets
|
||||
- Knowledge reuse statistics
|
||||
- Solution adoption statistics
|
||||
- Agent run summary
|
||||
- Model health summary
|
||||
- MCP risk reminders
|
||||
|
||||
Dashboard should be a visual overview page with trend cards, operational charts, and top issue categories using mock data. It should not look like a marketing homepage.
|
||||
|
||||
### 6.2 Ticket Pages
|
||||
|
||||
Existing ticket pages remain connected to current APIs. Stage 2.5 improves their visual relationship to future AI features:
|
||||
|
||||
- Detail page should reserve consistent sections for AI analysis, knowledge references, similar tickets, and recommended solutions.
|
||||
- Ticket creation should reserve a future Agent-assisted creation panel.
|
||||
- Table actions and filter density should remain consistent with the design system.
|
||||
|
||||
### 6.3 Knowledge And Solutions
|
||||
|
||||
Existing knowledge and solution pages remain real where APIs exist. Stage 2.5 adds stronger prototype states:
|
||||
|
||||
- Knowledge search result cards must look like citable references.
|
||||
- Solution cards and tables should show reusable status, adoption count, risk note, and applicable scope.
|
||||
- Empty states should guide the user toward creating knowledge items or solutions.
|
||||
|
||||
### 6.4 Model Hub
|
||||
|
||||
Model hub pages are mock-backed in this stage:
|
||||
|
||||
- Provider list with provider type, base URL, enabled state, default model count, and last test status.
|
||||
- Provider create/edit dialog with Chinese fields.
|
||||
- Model testing page with prompt input, model selector, parameter controls, response comparison, latency, token usage, and failure state.
|
||||
|
||||
### 6.5 Agents
|
||||
|
||||
Agent pages are mock-backed in this stage:
|
||||
|
||||
- Agent list with type, enabled state, model, knowledge scope, tool scope, and human confirmation policy.
|
||||
- Agent detail/config page with tabs for basic settings, prompt, knowledge, tools, safety, and output schema.
|
||||
- Agent runs page with run status, ticket association, trigger user, duration, and created time.
|
||||
- Agent run detail page with step timeline: retrieval, skill, model call, tool call, human confirmation, and artifact output.
|
||||
|
||||
### 6.6 Skills
|
||||
|
||||
Skill pages are mock-backed in this stage:
|
||||
|
||||
- Skill list with scenario, enabled state, version, last update time.
|
||||
- Skill edit page with prompt template, input schema preview, output schema preview, and test input panel.
|
||||
- Skill cards must make it clear that Skills are configuration templates, not arbitrary code.
|
||||
|
||||
### 6.7 MCP Tools
|
||||
|
||||
MCP pages are mock-backed in this stage:
|
||||
|
||||
- MCP server list with connection state, tool count, auth type, and last sync time.
|
||||
- Tool list with name, description, risk level, enabled state, and confirmation requirement.
|
||||
- Tool call audit preview with input/output summary and status.
|
||||
- High-risk actions must show a confirmation-oriented UI pattern.
|
||||
|
||||
### 6.8 System Management
|
||||
|
||||
Existing system pages remain connected to current APIs. Stage 2.5 should align their visual density and forms with the new global shell where needed.
|
||||
|
||||
## 7. Mock Data And API Contracts
|
||||
|
||||
Create a frontend-only mock layer for modules without backend support:
|
||||
|
||||
```text
|
||||
frontend/src/features/prototype/
|
||||
mockData.ts
|
||||
types.ts
|
||||
```
|
||||
|
||||
The mock types should define stable future contracts for:
|
||||
|
||||
- `DashboardMetric`
|
||||
- `ModelProvider`
|
||||
- `ModelTestResult`
|
||||
- `AgentDefinition`
|
||||
- `AgentRun`
|
||||
- `AgentStep`
|
||||
- `SkillDefinition`
|
||||
- `McpServer`
|
||||
- `McpTool`
|
||||
- `ToolCall`
|
||||
|
||||
Mock data must be realistic enough to validate UI density, empty states, failed states, and action states. It should not use placeholder names such as "foo", "bar", or "test".
|
||||
|
||||
## 8. Component Strategy
|
||||
|
||||
Stage 2.5 should reuse existing `App*` components first. New shared components are allowed only when at least two prototype modules need the same pattern.
|
||||
|
||||
Likely additions:
|
||||
|
||||
- `AppMetricCard`
|
||||
- `AppRiskBadge`
|
||||
- `AppTraceTimeline`
|
||||
- `AppReferenceCard`
|
||||
- `AppConfigTabs`
|
||||
|
||||
Business pages must not define one-off badge colors, raw color values, or custom table styling. Select menus must keep the `SelectContent > SelectGroup > SelectItem` structure. Forms should use `AppField`.
|
||||
|
||||
## 9. Interaction Requirements
|
||||
|
||||
Prototype pages should support real UI interactions even when data is mocked:
|
||||
|
||||
- Search and local filtering.
|
||||
- Tabs.
|
||||
- Dialog open and close.
|
||||
- Drawer or detail view navigation.
|
||||
- Loading and empty states.
|
||||
- Error states for model test and MCP sync.
|
||||
- High-risk confirmation dialog.
|
||||
- Agent run step expansion.
|
||||
|
||||
Actions may update local component state but must not pretend to persist to backend.
|
||||
|
||||
## 10. Acceptance Criteria
|
||||
|
||||
Stage 2.5 is complete when:
|
||||
|
||||
- The sidebar exposes the full product map.
|
||||
- All planned frontend routes render without blank pages.
|
||||
- All user-facing text is Chinese.
|
||||
- Existing real API pages still work.
|
||||
- Mock-backed pages use typed mock data and realistic operational content.
|
||||
- Model, Agent, Skill, MCP, dashboard, and trace pages have usable interactive states.
|
||||
- `npm run typecheck` passes.
|
||||
- `npm run build` passes.
|
||||
- Documentation explains which pages are real API-backed and which are mock-backed.
|
||||
|
||||
## 11. Implementation Notes
|
||||
|
||||
This stage should be implemented in frontend-only commits except for documentation. Backend work resumes after this prototype stabilizes and API contracts are reviewed.
|
||||
|
||||
Recommended next backend stage after Stage 2.5 remains Stage 3: model gateway and Agent/Skill runtime. Stage 2.5 should make that stage easier by clarifying the frontend contracts before backend schema work begins.
|
||||
Reference in New Issue
Block a user