docs: add AI ticket platform design

2026-06-30 15:20:48 +08:00
commit 3a5953ceab
3 changed files with 702 additions and 0 deletions
--- a/docs/superpowers/specs/2026-06-30-ai-ticket-platform-design.md
+++ b/docs/superpowers/specs/2026-06-30-ai-ticket-platform-design.md
@@ -0,0 +1,654 @@
+# AI-native Technical Support Ticket Platform Design
+
+Date: 2026-06-30
+
+## 1. Product Positioning
+
+This project is a new long-term product, independent from the existing `finance-it-support` repository.
+
+It is an AI-native technical support ticket system for single-enterprise private deployment. It is not a traditional ticket system with AI bolted on, and it is not a generic Agent platform. The core business assets are tickets, business knowledge, and reusable solutions. AI capabilities exist to improve ticket creation, support analysis, knowledge reuse, and operational review.
+
+The system should be built as an independent Git repository so all design, code, migration scripts, and deployment assets have their own version history.
+
+## 2. Core Principles
+
+| Principle | Decision |
+|---|---|
+| Tickets are the business spine | AI capabilities must serve ticket creation, handling, review, and knowledge reuse. |
+| Business knowledge is a first-class asset | Documents, historical tickets, FAQs, and reusable solutions must be searchable, citable, and auditable. |
+| Agents are controlled executors | Agents produce suggestions, drafts, and analysis by default. Business writes require human confirmation. |
+| Skills are reusable capability templates | MVP Skills are configuration-driven, not arbitrary Python code. |
+| MCP is the external tool boundary | Tools are authorized, risk-classified, and audited. Read-only tools come first. |
+| Model gateway isolates providers | The system supports OpenAI-compatible channels and model comparison across chat, vision, multimodal, and embedding models. |
+| Enterprise governance is foundational | Single-enterprise RBAC, menu permissions, button permissions, operation audit, and Agent audit should be implemented early. |
+| Design system comes first | Frontend development starts from product theme tokens and reusable components, not ad hoc page styling. |
+
+## 3. Overall Architecture
+
+The product has four layers:
+
+| Layer | Responsibility |
+|---|---|
+| Ticket business layer | Ticket lifecycle, comments, attachments, status transitions, reusable solutions, exports, statistics. |
+| Business knowledge layer | Knowledge bases, documents, chunks, structured knowledge items, reusable solutions, citations. |
+| AI platform layer | Model providers, model configs, Agents, Skills, MCP tools, vector retrieval, execution traces. |
+| Enterprise governance layer | Users, groups, roles, menus, button permissions, audit logs, system settings. |
+
+Relationship:
+
+```text
+Users / permissions / audit
+    ↓
+Tickets ←→ Business knowledge / reusable solutions
+    ↓            ↓
+Agents / Skills / MCP / model gateway
+    ↓
+LLMs / vision models / embedding models / vector retrieval
+```
+
+Tickets and knowledge are business assets. AI is the capability amplifier. Permissions and audit form the trust boundary.
+
+## 4. MVP Scope
+
+MVP means a complete platform skeleton with minimal but real closed loops in every core module.
+
+### Included
+
+| Module | MVP Capabilities |
+|---|---|
+| Enterprise admin | Users, user groups, roles, menus, button permissions, operation audit. |
+| Tickets | Create, list, detail, edit, status transition, comments, attachments, export. |
+| Ticket events | Status and key field changes recorded as events. |
+| Reusable solutions | Solution library, ticket-solution links, usage count, solution recommendation. |
+| Knowledge base | Document upload, parsing, chunking, embedding, retrieval, structured knowledge items. |
+| Model gateway | OpenAI-compatible providers, model configs, capabilities, model tests, multi-model comparison. |
+| Agents | Ticket creation Agent, support analysis Agent, knowledge distillation Agent. |
+| Skills | Configuration-driven prompt templates with input/output schemas. |
+| MCP tools | Tool server registration, tool sync, risk level, Agent binding, call audit. |
+| Agent audit | Agent runs, steps, model calls, retrieval, tool calls, AI artifact adoption. |
+| Migration | Import historical tickets only, then vectorize and distill useful solutions/knowledge. |
+| Frontend design system | Theme tokens, base components, layout templates, status badges, table/form standards. |
+
+### Excluded From MVP
+
+| Excluded Item | Reason |
+|---|---|
+| Multi-tenant SaaS | Current target is single-enterprise private deployment. |
+| Complex BPMN workflow | Status lifecycle is enough for MVP. |
+| Automatic dispatch loop | Requires more operational data and trust. |
+| Automatic ticket closure | Too risky for first version. |
+| Arbitrary Python code Skills | Security and sandboxing should come later. |
+| Autonomous multi-Agent collaboration | Not needed for the first closed loop. |
+| Unattended production remediation | High-risk MCP actions are out of scope. |
+| Full compatibility with old system fields | This is a new product, not a clone of the old schema. |
+
+## 5. Recommended Technology Stack
+
+| Area | Choice |
+|---|---|
+| Backend | Django + Django Ninja |
+| Database | PostgreSQL + pgvector |
+| Async jobs | Celery + Redis |
+| File storage | MinIO / S3-compatible storage |
+| AI SDK | OpenAI Python SDK-compatible provider adapter |
+| Frontend | React + Vite |
+| UI base | Tailwind CSS + shadcn/ui + Radix UI |
+| Tables | TanStack Table |
+| Forms | React Hook Form + Zod |
+| Icons | lucide-react |
+| Charts | Recharts |
+| Deployment | Docker Compose first |
+
+The backend should start as a modular monolith. Code boundaries should be clear enough to split heavy workers later, but runtime should stay simple during MVP.
+
+Recommended Django apps:
+
+```text
+apps/accounts
+apps/tickets
+apps/knowledge
+apps/solutions
+apps/modelhub
+apps/agents
+apps/skills
+apps/tools
+apps/audit
+apps/system
+```
+
+## 6. Data Model Baseline
+
+### 6.1 Ticket Core
+
+`ticket` should be a slim main table. It answers: what is this ticket, what state is it in, and who owns it now.
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Ticket primary key | New system ID. |
+| `ticket_no` | varchar | User-facing ticket number | Example: `TK202607010001`. |
+| `title` | varchar | Ticket title | Core list/search field. |
+| `description` | text | Problem description | User-confirmed description. |
+| `category_id` | bigint | Ticket category | References `ticket_category`. |
+| `status` | varchar | Ticket status | Pending info, pending handling, in progress, pending confirmation, resolved, closed. |
+| `priority` | varchar | Priority | Low, medium, high, urgent. |
+| `impact_scope` | varchar | Impact scope | Single user, branch, system-level, etc. |
+| `environment` | varchar | Environment | Production, test, staging, local. |
+| `related_system_id` | bigint | Related system | References a system dictionary table. |
+| `requester_id` | bigint | Requester | References user. |
+| `assignee_id` | bigint | Current assignee | References user. |
+| `created_by` | bigint | Creator | Supports creating on behalf of another user. |
+| `created_at` | datetime | Created time | System field. |
+| `updated_at` | datetime | Updated time | System field. |
+| `resolved_at` | datetime | Resolved time | Set when resolved. |
+| `closed_at` | datetime | Closed time | Set when closed. |
+
+Fields intentionally excluded from `ticket`:
+
+| Data | Destination | Reason |
+|---|---|---|
+| Old system ID/source/raw JSON | Temporary migration staging only | Avoid polluting the new long-term model. |
+| Collaborators | `ticket_collaborator` | Many-to-many relation. |
+| Attachments | `ticket_attachment` | Large parsed/OCR content grows independently. |
+| Comments | `ticket_comment` | One-to-many communication history. |
+| Status and field changes | `ticket_event` | Audit and timeline. |
+| Resolution details | `ticket_resolution` and `solution` | Separate instance handling from reusable solutions. |
+| AI output | `ticket_ai_artifact` and `agent_run` | AI output has versions, sources, and confidence. |
+
+### 6.2 Ticket Subtables
+
+`ticket_comment`
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Comment ID |  |
+| `ticket_id` | bigint | Ticket ID |  |
+| `content` | text | Comment content | Communication or handling note. |
+| `comment_type` | varchar | Comment type | User supplement, internal note, system event, AI suggestion. |
+| `visibility` | varchar | Visibility | Internal or requester-visible. |
+| `created_by` | bigint | Creator | User or system Agent identity. |
+| `created_at` | datetime | Created time |  |
+
+`ticket_attachment`
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Attachment ID |  |
+| `ticket_id` | bigint | Ticket ID |  |
+| `file_name` | varchar | Original file name |  |
+| `file_type` | varchar | File type | Image, log, document, archive. |
+| `mime_type` | varchar | MIME type |  |
+| `file_size` | bigint | File size | Bytes. |
+| `storage_path` | varchar | Storage path | MinIO/S3 key. |
+| `ocr_text` | text | OCR or image understanding text | Optional. |
+| `parsed_text` | text | Parsed document/log text | Optional. |
+| `created_by` | bigint | Uploader |  |
+| `created_at` | datetime | Uploaded time |  |
+
+`ticket_event`
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Event ID |  |
+| `ticket_id` | bigint | Ticket ID |  |
+| `event_type` | varchar | Event type | Status change, assignment, edit, close, AI analysis. |
+| `from_value` | jsonb | Previous value | Snapshot or field value. |
+| `to_value` | jsonb | New value | Snapshot or field value. |
+| `operator_id` | bigint | Operator | User ID. |
+| `remark` | text | Remark | Optional. |
+| `created_at` | datetime | Event time |  |
+
+`ticket_category`
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Category ID |  |
+| `parent_id` | bigint | Parent category | Supports hierarchy. |
+| `name` | varchar | Category name |  |
+| `code` | varchar | Category code | Useful for imports and rules. |
+| `description` | text | Description | Can be used as AI classification context. |
+| `enabled` | boolean | Enabled |  |
+| `sort_order` | int | Sort order |  |
+
+### 6.3 Resolution And Reusable Solutions
+
+`ticket_resolution` records the handling result of one ticket.
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Resolution ID |  |
+| `ticket_id` | bigint | Ticket ID |  |
+| `resolution_type` | varchar | Resolution type | Resolved, workaround, transferred, cannot reproduce. |
+| `root_cause` | text | Case-specific root cause | Optional. |
+| `solution_text` | text | Case-specific handling note | Human-confirmed. |
+| `linked_solution_id` | bigint | Linked reusable solution | Optional. |
+| `confirmed_by` | bigint | Confirmer |  |
+| `created_at` | datetime | Created time |  |
+| `updated_at` | datetime | Updated time |  |
+
+`solution` records reusable support solutions.
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Solution ID |  |
+| `title` | varchar | Solution title |  |
+| `problem_signature` | text | Problem signature | Error code, symptom, key log. |
+| `related_system_id` | bigint | Related system | Optional. |
+| `environment_scope` | varchar | Environment scope |  |
+| `category_id` | bigint | Category |  |
+| `root_cause` | text | Common root cause |  |
+| `solution` | text | Standard solution steps |  |
+| `risk_note` | text | Risk note |  |
+| `status` | varchar | Status | Draft, published, disabled. |
+| `usage_count` | int | Usage count | Incremented when adopted. |
+| `created_by` | bigint | Creator |  |
+| `updated_at` | datetime | Updated time |  |
+
+`ticket_solution_link`
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `ticket_id` | bigint | Ticket ID |  |
+| `solution_id` | bigint | Solution ID |  |
+| `link_type` | varchar | Link type | Recommended, adopted, referenced. |
+| `agent_run_id` | bigint | Agent source | Optional. |
+| `created_by` | bigint | Creator |  |
+| `created_at` | datetime | Created time |  |
+
+### 6.4 Knowledge Base
+
+`knowledge_base`
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Knowledge base ID |  |
+| `name` | varchar | Name | Example: payment system knowledge base. |
+| `description` | text | Description |  |
+| `scope` | varchar | Scope | System, business line, department. |
+| `enabled` | boolean | Enabled |  |
+| `created_by` | bigint | Creator |  |
+| `created_at` | datetime | Created time |  |
+| `updated_at` | datetime | Updated time |  |
+
+`knowledge_document`
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Document ID |  |
+| `knowledge_base_id` | bigint | Knowledge base ID |  |
+| `file_name` | varchar | Original file name |  |
+| `file_type` | varchar | File type | PDF, Word, Markdown, log, etc. |
+| `storage_path` | varchar | Storage path | MinIO/S3 key. |
+| `parse_status` | varchar | Parse status | Pending, parsing, success, failed. |
+| `parse_error` | text | Parse error | Optional. |
+| `created_by` | bigint | Uploader |  |
+| `created_at` | datetime | Uploaded time |  |
+
+`knowledge_item`
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Knowledge item ID |  |
+| `knowledge_base_id` | bigint | Knowledge base ID |  |
+| `title` | varchar | Title |  |
+| `problem` | text | Problem symptom |  |
+| `applicable_scope` | text | Applicable scope | System, version, environment, branch. |
+| `error_code` | varchar | Error code | Optional. |
+| `root_cause` | text | Possible cause |  |
+| `troubleshooting_steps` | text | Troubleshooting steps |  |
+| `solution` | text | Solution |  |
+| `risk_note` | text | Risk note |  |
+| `status` | varchar | Status | Draft, published, disabled. |
+| `source_type` | varchar | Source type | Manual, document, ticket, AI draft. |
+| `source_ticket_id` | bigint | Source ticket | Optional. |
+| `created_by` | bigint | Creator |  |
+| `reviewed_by` | bigint | Reviewer | Optional in MVP. |
+| `created_at` | datetime | Created time |  |
+| `updated_at` | datetime | Updated time |  |
+
+`knowledge_chunk`
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Chunk ID |  |
+| `knowledge_base_id` | bigint | Knowledge base ID | Retrieval filter. |
+| `document_id` | bigint | Source document | Optional. |
+| `item_id` | bigint | Source item | Optional. |
+| `chunk_index` | int | Chunk index |  |
+| `content` | text | Chunk content | Retrieval context. |
+| `embedding` | vector | Embedding | pgvector field. |
+| `embedding_model_id` | bigint | Embedding model | References model config. |
+| `metadata` | jsonb | Metadata | Page, heading, tags, etc. |
+| `created_at` | datetime | Created time |  |
+
+### 6.5 AI Platform Tables
+
+`model_provider`
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Provider ID |  |
+| `name` | varchar | Provider name | OpenAI, Azure, private model, etc. |
+| `provider_type` | varchar | Provider type | openai-compatible, custom. |
+| `base_url` | varchar | API base URL | Supports custom channels. |
+| `api_key_encrypted` | text | Encrypted API key | Never store plaintext. |
+| `enabled` | boolean | Enabled |  |
+| `created_at` | datetime | Created time |  |
+| `updated_at` | datetime | Updated time |  |
+
+`model_config`
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Model config ID |  |
+| `provider_id` | bigint | Provider ID |  |
+| `name` | varchar | Display name |  |
+| `model_name` | varchar | API model name |  |
+| `capabilities` | jsonb | Capability tags | chat, vision, embedding, multimodal. |
+| `default_parameters` | jsonb | Default params | temperature, max_tokens, etc. |
+| `is_default_chat` | boolean | Default chat model |  |
+| `is_default_embedding` | boolean | Default embedding model |  |
+| `enabled` | boolean | Enabled |  |
+
+`agent_definition`
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Agent ID |  |
+| `name` | varchar | Agent name | Ticket creation Agent, support analysis Agent. |
+| `agent_type` | varchar | Agent type | ticket_create, ticket_analysis, knowledge_draft. |
+| `description` | text | Description |  |
+| `model_config_id` | bigint | Model config | Can override default. |
+| `system_prompt` | text | System prompt | Behavior constraints. |
+| `output_schema` | jsonb | Output schema | Structured output. |
+| `allowed_knowledge_base_ids` | jsonb | Allowed knowledge bases | MVP can store JSON IDs. |
+| `allowed_skill_ids` | jsonb | Allowed Skills |  |
+| `allowed_tool_ids` | jsonb | Allowed MCP tools |  |
+| `requires_human_confirm` | boolean | Requires confirmation | Default true. |
+| `enabled` | boolean | Enabled |  |
+| `created_at` | datetime | Created time |  |
+| `updated_at` | datetime | Updated time |  |
+
+`agent_run`
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Run ID |  |
+| `agent_id` | bigint | Agent ID |  |
+| `ticket_id` | bigint | Ticket ID | Nullable for tests. |
+| `run_type` | varchar | Run type | Creation, analysis, knowledge draft, test. |
+| `input_snapshot` | jsonb | Input snapshot | Ticket, attachment summary, user input. |
+| `output` | jsonb | Output result | Structured suggestion. |
+| `status` | varchar | Status | running, success, failed, cancelled. |
+| `error_message` | text | Error message | Optional. |
+| `created_by` | bigint | Triggering user |  |
+| `started_at` | datetime | Started time |  |
+| `finished_at` | datetime | Finished time |  |
+
+`agent_step`
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Step ID |  |
+| `run_id` | bigint | Agent run ID |  |
+| `step_type` | varchar | Step type | model_call, retrieval, tool_call, skill, human_confirm. |
+| `step_name` | varchar | Step name |  |
+| `input` | jsonb | Step input | Sensitive data should be masked. |
+| `output` | jsonb | Step output |  |
+| `latency_ms` | int | Latency | Milliseconds. |
+| `status` | varchar | Status | success, failed, skipped. |
+| `error_message` | text | Error message | Optional. |
+| `created_at` | datetime | Created time |  |
+
+`ticket_ai_artifact`
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Artifact ID |  |
+| `ticket_id` | bigint | Ticket ID |  |
+| `agent_run_id` | bigint | Agent run ID |  |
+| `artifact_type` | varchar | Artifact type | Summary, field suggestion, analysis, reply draft. |
+| `content` | jsonb | Artifact content | Structured AI output. |
+| `confidence` | decimal | Confidence | Optional. |
+| `accepted_by` | bigint | Adopting user | Nullable. |
+| `accepted_at` | datetime | Adopted time | Nullable. |
+
+### 6.6 Skills And MCP Tools
+
+`skill_definition`
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Skill ID |  |
+| `name` | varchar | Skill name |  |
+| `description` | text | Description |  |
+| `scenario` | varchar | Scenario | Creation, analysis, reply, knowledge distillation. |
+| `prompt_template` | text | Prompt template | Supports variables. |
+| `input_schema` | jsonb | Input schema |  |
+| `output_schema` | jsonb | Output schema |  |
+| `allowed_tool_ids` | jsonb | Allowed tools | Optional in MVP. |
+| `enabled` | boolean | Enabled |  |
+| `created_at` | datetime | Created time |  |
+| `updated_at` | datetime | Updated time |  |
+
+`tool_server`
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | MCP server ID |  |
+| `name` | varchar | Server name | Example: log platform MCP. |
+| `server_url` | varchar | Server URL |  |
+| `auth_type` | varchar | Auth type | none, token, basic, custom. |
+| `auth_config_encrypted` | text | Encrypted auth config |  |
+| `enabled` | boolean | Enabled |  |
+| `created_at` | datetime | Created time |  |
+
+`tool_definition`
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Tool ID |  |
+| `server_id` | bigint | MCP server ID |  |
+| `name` | varchar | Tool name |  |
+| `description` | text | Description |  |
+| `input_schema` | jsonb | Input schema | Synced from MCP. |
+| `risk_level` | varchar | Risk level | low, medium, high. |
+| `requires_human_confirm` | boolean | Requires confirmation | High risk defaults true. |
+| `enabled` | boolean | Enabled |  |
+
+`tool_call`
+
+| Field | Type Suggestion | Meaning | Notes |
+|---|---|---|---|
+| `id` | bigint / uuid | Tool call ID |  |
+| `run_id` | bigint | Agent run ID |  |
+| `tool_id` | bigint | Tool ID |  |
+| `input` | jsonb | Call input |  |
+| `output` | jsonb | Call output |  |
+| `status` | varchar | Status | success, failed, blocked, waiting_confirm. |
+| `confirmed_by` | bigint | Confirmer | Nullable. |
+| `created_at` | datetime | Call time |  |
+
+## 7. Agent, Skill, MCP Boundaries
+
+| Concept | Responsibility |
+|---|---|
+| Agent | Owns the task goal and execution flow. |
+| Skill | Provides reusable professional capability templates. |
+| MCP | Provides authorized external tool access. |
+
+MVP built-in Agents:
+
+| Agent | Goal | Input | Output | Auto-write business data |
+|---|---|---|---|---|
+| Ticket creation Agent | Help users create complete tickets | Description, images, attachment summaries | Field drafts, missing-info questions, category suggestions, similar tickets | No |
+| Support analysis Agent | Help support engineers analyze tickets | Ticket detail, comments, attachments, knowledge retrieval | Possible causes, steps, solution recommendations, reply draft | No |
+| Knowledge distillation Agent | Turn resolved tickets into knowledge | Ticket, comments, adopted solution | Solution draft, knowledge item draft | No |
+
+MVP Skill examples:
+
+| Skill | Purpose |
+|---|---|
+| Field extraction | Extract ticket fields from natural language. |
+| Missing-info question generation | Identify missing key information and ask concise questions. |
+| Similar ticket summary | Summarize historical similar tickets. |
+| Solution recommendation | Recommend reusable solutions from the solution library. |
+| Customer reply generation | Draft user-facing replies. |
+| Screenshot understanding | Extract errors and system clues from screenshots. |
+| Knowledge draft generation | Create knowledge drafts from resolved tickets. |
+
+MCP rules:
+
+| Risk Level | Examples | MVP Strategy |
+|---|---|---|
+| low | Search docs, search historical tickets | Auto-call allowed if Agent is authorized. |
+| medium | Query logs, monitoring, read-only business status | Auto-call allowed with full audit. |
+| high | Modify config, run commands, restart services | Not available in MVP or requires human confirmation. |
+
+## 8. Frontend Product Shape
+
+The frontend should feel like a minimal, designed enterprise AI workbench.
+
+Navigation groups:
+
+```text
+Workspace
+Tickets
+Knowledge Base
+Solutions
+Agents
+Models & Tools
+System Management
+```
+
+Core pages:
+
+| Module | Page | Goal |
+|---|---|---|
+| Workspace | My tasks | Pending tickets and confirmations. |
+| Workspace | Support overview | Trends, high-frequency issues, Agent usage. |
+| Tickets | Ticket list | Search, filter, export, batch operations. |
+| Tickets | Create ticket | Form plus ticket creation Agent. |
+| Tickets | Ticket detail | Handling, comments, attachments, AI analysis, solution links. |
+| Knowledge | Knowledge bases | Manage business knowledge scopes. |
+| Knowledge | Documents | Upload, parse, chunk, vectorize. |
+| Knowledge | Knowledge items | Maintain structured knowledge. |
+| Solutions | Solution library | Manage reusable solutions. |
+| Agents | Agent config | Configure models, Skills, knowledge, tools, safety. |
+| Agents | Agent runs | Inspect runs and steps. |
+| Models & Tools | Model providers | Configure channels and model capabilities. |
+| Models & Tools | Model testing | Compare model outputs. |
+| Models & Tools | MCP tools | Register services, sync tools, configure risk. |
+| System | Users and groups | User/group/role management. |
+| System | Permissions | Menu and button permissions. |
+| System | Audit logs | Operation and login logs. |
+
+## 9. Frontend Design System Requirement
+
+Frontend development must start with a design system.
+
+Dependency structure:
+
+```text
+shadcn/ui / Radix UI / Tailwind
+        ↓
+Product Design System
+        ↓
+Business Components
+        ↓
+Pages
+```
+
+Business pages should use project-level components instead of direct ad hoc styles.
+
+Required first-phase design tokens and standards:
+
+| Type | Content |
+|---|---|
+| Color | Primary, background, surface, border, text, status, risk, priority. |
+| Typography | Font sizes, line heights, weights. |
+| Spacing | Page padding, section gaps, form/table density. |
+| Radius | Buttons, inputs, dialogs, cards. |
+| Shadow | Only for popovers, dialogs, dropdowns. |
+| Icons | Unified lucide-react icons. |
+| Tables | Filter bar, toolbar, density, pagination, empty state. |
+| Forms | Label alignment, validation, required fields, grouping. |
+| Badges | Ticket status, priority, Agent state, tool risk level. |
+| Layouts | List page, detail page, config page, workbench templates. |
+| AI UI | Running, success, failed, references, adoption buttons, trace display. |
+
+Suggested product components:
+
+```text
+AppButton
+AppInput
+AppSelect
+AppTable
+AppForm
+AppDialog
+AppDrawer
+AppStatusBadge
+AppPriorityBadge
+AppPageHeader
+AppFilterBar
+AppDetailLayout
+AppAuditTimeline
+AgentRunPanel
+KnowledgeReferenceList
+SolutionRecommendationCard
+```
+
+Rules:
+
+- Do not write raw color values in business pages.
+- Do not define one-off status badges in pages.
+- Do not build complex tables from scratch per page.
+- Use unified components for Agent traces, knowledge references, and solution recommendations.
+- AI accent color should be restrained. AI is a capability, not the whole visual identity.
+
+## 10. Development Milestones
+
+| Stage | Goal | Key Deliverables |
+|---|---|---|
+| 0. Product skeleton and design system | Establish project foundation | Backend init, frontend init, Docker Compose, auth, RBAC, audit, design tokens, base components. |
+| 1. Ticket workflow | Replace traditional ticket minimum loop | Ticket CRUD, status flow, comments, attachments, events, export, reusable solutions. |
+| 2. Knowledge and vector retrieval | Make knowledge a core asset | Knowledge base, document parsing, chunks, embeddings, retrieval, knowledge drafts. |
+| 3. Model gateway and Agent/Skill | Establish AI platform capability | Providers, model configs, model comparison, Skills, built-in Agents, Agent runs/steps. |
+| 4. MCP tools and trust boundary | Add controlled tool access | MCP registration, tool sync, risk level, Agent binding, tool calls, confirmation. |
+| 5. Historical migration and polish | Prepare trial replacement | Import historical tickets, vectorize, distill solutions, dashboards, UI polish. |
+
+## 11. Historical Ticket Migration
+
+Only historical tickets should be migrated. Old users, roles, menus, and organization structures should not be migrated.
+
+| Stage | Goal | Approach | Output |
+|---|---|---|---|
+| Raw import | Make historical tickets searchable | Map old records into the new ticket structure via migration staging. | Historical ticket list/detail. |
+| Standardization | Improve retrieval quality | Use rules/AI to extract title, category, system, environment, error codes. | Standard fields and summaries. |
+| Vectorization | Support similar ticket search | Embed description, handling notes, and solution text. | Historical tickets available to retrieval. |
+| Knowledge distillation | Convert valuable tickets into knowledge | Generate drafts, then manually publish. | `solution`, `knowledge_item`, `knowledge_chunk`. |
+| User mapping | Avoid legacy org lock-in | Keep old people names as text where needed; optionally bind to new users later. | Migration remains lightweight. |
+
+## 12. Acceptance Criteria For The First Architecture Slice
+
+The first usable architecture slice is complete when:
+
+- The system can run locally with Docker Compose.
+- Admin users can log in and manage users/groups/permissions.
+- The design system has a preview page and business pages use shared components.
+- Users can create and process tickets end to end.
+- Tickets can link to reusable solutions.
+- Documents and knowledge items can be vectorized and retrieved.
+- At least one OpenAI-compatible model provider can be configured and tested.
+- Built-in Agents can create auditable runs and steps.
+- AI artifacts can be accepted, edited, or ignored by users.
+- MCP tools can be registered and audited, with high-risk calls blocked or requiring confirmation.
+
+## 13. Open Questions
+
+| Topic | Current Decision | Later Decision Needed |
+|---|---|---|
+| Primary key style | bigint or uuid both acceptable | Decide during implementation setup. |
+| Next.js vs Vite | Vite React is preferred for private admin MVP | Revisit only if SSR/BFF becomes necessary. |
+| Code-type Skills | Excluded from MVP | Revisit with sandbox design. |
+| High-risk MCP tools | Excluded or confirmation-only | Revisit after audit and trust model matures. |
+| Workflow engine | Simple status flow for MVP | Revisit if SLA/escalation complexity grows. |