ai-ticket-platform/docs/superpowers/specs/2026-06-30-ai-ticket-platform-design.md

# 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. |