docs: consolidate project blueprint
This commit is contained in:
hailin
7
.gitignore
vendored
7
.gitignore
vendored
@@ -32,3 +32,10 @@ storage/
|
|||||||
minio-data/
|
minio-data/
|
||||||
postgres-data/
|
postgres-data/
|
||||||
redis-data/
|
redis-data/
|
||||||
|
|
||||||
|
.agents/
|
||||||
|
.codegraph/
|
||||||
|
skills-lock.json
|
||||||
|
frontend/skills-lock.json
|
||||||
|
|
||||||
|
infra/data/
|
||||||
|
|||||||
@@ -10,9 +10,9 @@ Active implementation. The project has a runnable Django + React baseline with e
|
|||||||
|
|
||||||
Key docs:
|
Key docs:
|
||||||
|
|
||||||
- [Product design spec](docs/superpowers/specs/2026-06-30-ai-ticket-platform-design.md)
|
- [Project blueprint](docs/product/blueprint.md)
|
||||||
|
- [Capability status](docs/product/capability-status.md)
|
||||||
- [Design discussion log](docs/communication/2026-06-30-ai-ticket-platform-discussion-log.md)
|
- [Design discussion log](docs/communication/2026-06-30-ai-ticket-platform-discussion-log.md)
|
||||||
- [Implementation roadmap](docs/superpowers/plans/2026-06-30-ai-ticket-platform-implementation-roadmap.md)
|
|
||||||
- [Local setup](docs/development/local-setup.md)
|
- [Local setup](docs/development/local-setup.md)
|
||||||
- [Frontend design system](docs/frontend/design-system.md)
|
- [Frontend design system](docs/frontend/design-system.md)
|
||||||
|
|
||||||
|
|||||||
@@ -14,9 +14,7 @@
|
|||||||
|
|
||||||
| 文档 | 用途 |
|
| 文档 | 用途 |
|
||||||
|---|---|
|
|---|---|
|
||||||
| `docs/superpowers/specs/2026-06-30-ai-ticket-platform-design.md` | 第一版正式产品与架构设计 |
|
| `docs/product/blueprint.md` | 基于本记录与当前代码现状重新规划的唯一主蓝图 |
|
||||||
| `docs/superpowers/plans/2026-06-30-ai-ticket-platform-implementation-roadmap.md` | 分阶段实施路线图 |
|
|
||||||
| `docs/superpowers/plans/2026-06-30-stage-0-foundation-design-system.md` | 阶段 0 详细实施计划 |
|
|
||||||
|
|
||||||
## 2. 初始背景：从现有系统 AI 工单识别开始
|
## 2. 初始背景：从现有系统 AI 工单识别开始
|
||||||
|
|
||||||
@@ -503,12 +501,6 @@ Agent
|
|||||||
|
|
||||||
## 20. 正式设计文档产出
|
## 20. 正式设计文档产出
|
||||||
|
|
||||||
正式设计文档保存到：
|
|
||||||
|
|
||||||
```text
|
|
||||||
docs/superpowers/specs/2026-06-30-ai-ticket-platform-design.md
|
|
||||||
```
|
|
||||||
|
|
||||||
文档内容包括：
|
文档内容包括：
|
||||||
|
|
||||||
- 产品定位
|
- 产品定位
|
||||||
@@ -527,18 +519,6 @@ docs/superpowers/specs/2026-06-30-ai-ticket-platform-design.md
|
|||||||
|
|
||||||
## 21. 实施计划产出
|
## 21. 实施计划产出
|
||||||
|
|
||||||
总路线图保存到：
|
|
||||||
|
|
||||||
```text
|
|
||||||
docs/superpowers/plans/2026-06-30-ai-ticket-platform-implementation-roadmap.md
|
|
||||||
```
|
|
||||||
|
|
||||||
阶段 0 详细计划保存到：
|
|
||||||
|
|
||||||
```text
|
|
||||||
docs/superpowers/plans/2026-06-30-stage-0-foundation-design-system.md
|
|
||||||
```
|
|
||||||
|
|
||||||
阶段 0 计划目标：
|
阶段 0 计划目标：
|
||||||
|
|
||||||
建立可运行项目底座，包括：
|
建立可运行项目底座，包括：
|
||||||
@@ -579,14 +559,11 @@ docs/superpowers/plans/2026-06-30-stage-0-foundation-design-system.md
|
|||||||
建议新会话按以下顺序读取：
|
建议新会话按以下顺序读取：
|
||||||
|
|
||||||
1. `README.md`
|
1. `README.md`
|
||||||
2. `docs/communication/2026-06-30-ai-ticket-platform-discussion-log.md`
|
2. `docs/product/blueprint.md`
|
||||||
3. `docs/superpowers/specs/2026-06-30-ai-ticket-platform-design.md`
|
3. `docs/communication/2026-06-30-ai-ticket-platform-discussion-log.md`
|
||||||
4. `docs/superpowers/plans/2026-06-30-ai-ticket-platform-implementation-roadmap.md`
|
|
||||||
5. `docs/superpowers/plans/2026-06-30-stage-0-foundation-design-system.md`
|
|
||||||
|
|
||||||
如果要开始编码，建议从阶段 0 计划执行，并遵守计划文档顶部说明：
|
如果要开始编码，建议从阶段 0 开始，并遵守以下说明：
|
||||||
|
|
||||||
- 使用 `superpowers:subagent-driven-development` 或 `superpowers:executing-plans`
|
|
||||||
- 按 task 逐项执行
|
- 按 task 逐项执行
|
||||||
- 每个可验证任务单独提交
|
- 每个可验证任务单独提交
|
||||||
- 不跳过测试和构建验证
|
- 不跳过测试和构建验证
|
||||||
|
|||||||
542
docs/product/blueprint.md
Normal file
542
docs/product/blueprint.md
Normal file
@@ -0,0 +1,542 @@
|
|||||||
|
# AI 工单平台项目蓝图
|
||||||
|
|
||||||
|
更新日期：2026-07-14
|
||||||
|
状态：当前唯一主蓝图
|
||||||
|
需求基线：[2026-06-30 AI 工单平台设计沟通记录](../communication/2026-06-30-ai-ticket-platform-discussion-log.md)
|
||||||
|
|
||||||
|
## 1. 蓝图结论
|
||||||
|
|
||||||
|
本项目继续定位为面向单企业私有化部署的 AI-native 技术支持工单产品，不退回旧系统外挂，也不扩张为通用 Agent 平台。
|
||||||
|
|
||||||
|
本次重规划保留原有产品愿景，但调整交付逻辑：
|
||||||
|
|
||||||
|
```text
|
||||||
|
旧交付逻辑：先铺完整平台页面 -> 再逐步补真实能力
|
||||||
|
新交付逻辑：先跑通一个真实业务闭环 -> 抽取共性平台能力 -> 扩展下一个闭环
|
||||||
|
```
|
||||||
|
|
||||||
|
最终平台仍覆盖工单、知识库、模型、Agent、Skill、MCP、权限和审计；区别在于它们不再作为彼此平行的模块同时展开，而是围绕以下价值链依次落地：
|
||||||
|
|
||||||
|
```text
|
||||||
|
把问题说清楚 -> 帮支持人员查清楚 -> 把处理结果复用起来 -> 安全连接外部系统
|
||||||
|
```
|
||||||
|
|
||||||
|
第一个可交付 AI 价值不是“Agent 配置台”，而是“自然语言建单草稿经人工确认后创建真实工单”。第一个可交付知识价值不是“向量库管理页”，而是“支持人员能看到有来源、可采纳的检索结果”。
|
||||||
|
|
||||||
|
## 2. 北极星与成功定义
|
||||||
|
|
||||||
|
### 2.1 产品北极星
|
||||||
|
|
||||||
|
让技术支持人员在一个可信工作区内，更快取得完整问题上下文、找到可靠处理依据、完成客户回复，并把有效经验沉淀为可复用知识。
|
||||||
|
|
||||||
|
### 2.2 首个企业试运行版本的成功定义
|
||||||
|
|
||||||
|
- 普通建单人可以用自然语言、图片或附件描述问题，确认 AI 草稿后创建工单。
|
||||||
|
- 技术支持可以在工单详情内完成接单、沟通、检索、分析、方案采纳、解决和关闭。
|
||||||
|
- 每条 AI 建议都能区分生成内容、引用依据、人工修改和最终采纳结果。
|
||||||
|
- 已解决工单可以生成知识或解决方案草稿，经知识管理员审核后发布。
|
||||||
|
- 系统管理员可以管理用户、角色、模型和内置 Agent；只读 MCP 工具在明确授权后可被调用。
|
||||||
|
- 审计人员可以追溯业务变更、模型调用、知识引用、工具调用和人工确认。
|
||||||
|
- AI、向量检索或 MCP 不可用时，人工工单主流程仍可继续。
|
||||||
|
|
||||||
|
### 2.3 衡量指标
|
||||||
|
|
||||||
|
试运行阶段至少采集以下指标，先建立基线，再设目标值：
|
||||||
|
|
||||||
|
| 维度 | 指标 |
|
||||||
|
|---|---|
|
||||||
|
| 建单质量 | 首次信息完整率、补充信息次数、建单草稿采纳率 |
|
||||||
|
| 支持效率 | 首次响应时长、进入有效排查的时长、平均解决时长 |
|
||||||
|
| 知识复用 | 检索命中率、引用点击率、方案采纳率、重复方案率 |
|
||||||
|
| AI 质量 | 运行成功率、人工采纳率、修改后采纳率、拒绝率、无引用回答率 |
|
||||||
|
| 可信治理 | 越权拦截率、未审计调用数、敏感信息泄露事件数、人工流程降级成功率 |
|
||||||
|
| 系统质量 | 核心接口可用率、异步任务失败率、恢复时间、备份恢复演练结果 |
|
||||||
|
|
||||||
|
## 3. 产品边界
|
||||||
|
|
||||||
|
### 3.1 本版本必须做
|
||||||
|
|
||||||
|
- 单企业用户、用户组、角色、菜单/操作权限和操作审计。
|
||||||
|
- 工单创建、查询、处理、评论、附件、状态流转、导出和解决方案复用。
|
||||||
|
- 文档知识、结构化知识、解决方案、来源追溯和审核发布。
|
||||||
|
- OpenAI-compatible 模型渠道，以及对话、视觉、Embedding 等能力标识。
|
||||||
|
- 建单、支持分析、知识沉淀三类内置 Agent。
|
||||||
|
- 配置型 Skill、版本、输入输出 Schema 和受控资源范围。
|
||||||
|
- Agent 运行、步骤、产物、引用、用量、错误和人工确认记录。
|
||||||
|
- 只读 MCP 服务注册、工具同步、Agent 授权、风险分级和调用审计。
|
||||||
|
- Docker Compose 私有化部署、监控、备份恢复和升级说明。
|
||||||
|
|
||||||
|
### 3.2 明确不做
|
||||||
|
|
||||||
|
- 多租户 SaaS 和租户隔离。
|
||||||
|
- 复杂 BPMN、可视化流程编排和自动派单闭环。
|
||||||
|
- 多 Agent 自主协作。
|
||||||
|
- 任意 Python 代码型 Skill 或用户上传代码执行。
|
||||||
|
- 非只读 MCP 工具的无人值守执行。
|
||||||
|
- AI 自动解决、自动关闭或绕过业务服务直接写核心表。
|
||||||
|
- 为兼容旧系统而复制旧字段、旧权限或旧组织模型。
|
||||||
|
- 在首个试运行前建设独立微服务集群。
|
||||||
|
|
||||||
|
## 4. 目标用户与关键任务
|
||||||
|
|
||||||
|
| 角色 | 首要任务 | AI 提供的帮助 | 最终责任 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| 普通建单人 | 准确提交问题、跟踪进度 | 字段草稿、缺失信息追问、分类和相似问题建议 | 确认提交内容 |
|
||||||
|
| 技术支持 | 理解问题、排查、回复、解决 | 上下文摘要、知识检索、原因假设、排查步骤、回复草稿 | 判断、执行和状态变更 |
|
||||||
|
| 知识管理员 | 审核、发布、维护知识 | 从工单生成草稿、重复检测、失效提醒 | 内容正确性和发布 |
|
||||||
|
| 系统管理员 | 管理权限与 AI 能力 | 模型测试、配置校验、运行诊断 | 配置生效和风险边界 |
|
||||||
|
| 只读审计员 | 追踪业务和 AI 行为 | 聚合运行链路和异常事件 | 审计结论 |
|
||||||
|
|
||||||
|
## 5. 核心业务闭环
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
A["用户描述问题"] --> B["建单 Agent 生成草稿"]
|
||||||
|
B --> C{"用户确认"}
|
||||||
|
C -->|修改或确认| D["业务服务创建工单"]
|
||||||
|
D --> E["技术支持处理"]
|
||||||
|
E --> F["检索知识、方案和历史工单"]
|
||||||
|
F --> G["支持分析 Agent 生成建议"]
|
||||||
|
G --> H{"技术人员采纳"}
|
||||||
|
H --> I["回复、解决、关闭"]
|
||||||
|
I --> J["知识沉淀 Agent 生成草稿"]
|
||||||
|
J --> K{"知识管理员审核"}
|
||||||
|
K -->|发布| L["知识与解决方案资产"]
|
||||||
|
L --> F
|
||||||
|
```
|
||||||
|
|
||||||
|
任何 AI 结果都先写入 AI 产物或草稿，不直接成为正式业务事实。正式写入必须经过“用户确认 -> 对应业务服务 -> 业务事件与审计”这条路径。
|
||||||
|
|
||||||
|
### 5.1 工单类型与状态
|
||||||
|
|
||||||
|
第一版保留同一套工单主模型，采用两种受控流转策略：
|
||||||
|
|
||||||
|
| 类型 | 适用场景 | 建议主路径 |
|
||||||
|
|---|---|---|
|
||||||
|
| 快速咨询 | 进度查询、配置确认、简单答复 | 待处理 -> 已解决/已关闭 |
|
||||||
|
| 技术问题 | 需要排查、验证或协作 | 待处理 -> 处理中 -> 待确认 -> 已解决 -> 已关闭 |
|
||||||
|
|
||||||
|
状态流转由领域服务校验，不在前端拼接规则，也不在 Agent Prompt 中决定。
|
||||||
|
|
||||||
|
## 6. 当前真实基线
|
||||||
|
|
||||||
|
截至 2026-07-14，仓库并非空白项目。重规划必须在已有实现上演进。
|
||||||
|
|
||||||
|
| 能力 | 当前状态 | 蓝图判断 |
|
||||||
|
|---|---|---|
|
||||||
|
| Django/Django Ninja 模块化单体 | 已实现并可运行 | 保留 |
|
||||||
|
| React/Vite/Tailwind/shadcn 前端底座 | 已实现并可构建 | 保留，继续做产品组件层 |
|
||||||
|
| 用户、用户组、角色、菜单权限、审计 | 有真实模型和 API 基础 | 补权限矩阵和关键操作覆盖 |
|
||||||
|
| 工单 | 已有创建、列表、详情、编辑、分类流转、评论、附件元数据、导出 | 补真实文件上传、协作和业务一致性 |
|
||||||
|
| 解决方案 | 已有维护、关联、采纳和工单处理结果 | 保留，统一权威数据来源 |
|
||||||
|
| 知识库 | 已有知识库、条目、切片和检索 API | 当前是 JSON 向量和确定性哈希检索，不能视为真实向量能力 |
|
||||||
|
| 模型、Agent、Skill、MCP | 前端存在类型和演示数据 | 尚无真实后端闭环 |
|
||||||
|
| Docker Compose | 有 PostgreSQL、Redis、MinIO、前后端和 worker 基础 | 补生产化配置、健康检查和恢复流程 |
|
||||||
|
| 自动化验证 | 后端 43 项测试、前端 6 项测试当前通过；前端可类型检查和构建 | 覆盖面仍不足以证明端到端可用 |
|
||||||
|
|
||||||
|
当前需要正视的结构债务：
|
||||||
|
|
||||||
|
- `Ticket.ai_solution` 把 AI 内容放回业务主表，与“AI 产物独立”原则冲突，应停止新增依赖并在后续迁移。
|
||||||
|
- `Ticket.resolution_summary` 与 `TicketResolution` 存在权威来源重叠，需要明确实例处理结果以 `TicketResolution` 为准。
|
||||||
|
- `KnowledgeChunk.embedding` 使用 JSON，检索在应用内遍历并限制前 1000 条，只适合功能桩，不适合真实知识检索。
|
||||||
|
- 附件 API 当前记录存储路径和元数据，但不等于已经完成 MinIO 上传、解析、病毒/类型校验和访问控制。
|
||||||
|
- 原型和概念页面可以作为设计资产，但不计入真实产品完成度；默认业务导航不得让用户误认演示操作已经持久化。
|
||||||
|
|
||||||
|
## 7. 目标架构
|
||||||
|
|
||||||
|
### 7.1 架构原则
|
||||||
|
|
||||||
|
- 继续使用模块化单体，先稳定领域边界，再根据容量和部署需求拆 worker。
|
||||||
|
- 业务模块拥有业务事实，AI 模块拥有运行过程和生成产物。
|
||||||
|
- 所有模型供应商差异收敛在模型网关，业务代码不直接调用供应商 SDK。
|
||||||
|
- 检索、模型和工具调用都生成可追溯快照，避免源内容变化后无法还原当时依据。
|
||||||
|
- 同步 API 负责短事务；文档解析、Embedding 和 Agent 长运行进入 Celery。
|
||||||
|
- 权限校验以后端为最终边界，前端隐藏入口只用于体验。
|
||||||
|
|
||||||
|
### 7.2 逻辑架构
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TB
|
||||||
|
UI["React 企业支持工作台"] --> API["Django Ninja API"]
|
||||||
|
|
||||||
|
subgraph Business["业务资产域"]
|
||||||
|
T["tickets 工单"]
|
||||||
|
S["solutions 解决方案"]
|
||||||
|
K["knowledge 知识库"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Intelligence["智能能力域"]
|
||||||
|
M["modelhub 模型网关"]
|
||||||
|
A["agents 运行时与产物"]
|
||||||
|
SK["skills 配置型能力"]
|
||||||
|
TO["tools MCP 与工具调用"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Governance["企业治理域"]
|
||||||
|
AC["accounts RBAC"]
|
||||||
|
AU["audit 全链路审计"]
|
||||||
|
SY["system 系统配置"]
|
||||||
|
end
|
||||||
|
|
||||||
|
API --> T
|
||||||
|
API --> S
|
||||||
|
API --> K
|
||||||
|
API --> A
|
||||||
|
A --> M
|
||||||
|
A --> SK
|
||||||
|
A --> TO
|
||||||
|
A --> K
|
||||||
|
A --> S
|
||||||
|
A -. "只生成草稿/建议" .-> T
|
||||||
|
AC --> API
|
||||||
|
AU --> T
|
||||||
|
AU --> A
|
||||||
|
AU --> TO
|
||||||
|
|
||||||
|
A --> Q["Celery / Redis"]
|
||||||
|
K --> Q
|
||||||
|
T --> DB["PostgreSQL / pgvector"]
|
||||||
|
S --> DB
|
||||||
|
K --> DB
|
||||||
|
A --> DB
|
||||||
|
T --> OBJ["MinIO"]
|
||||||
|
K --> OBJ
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7.3 模块边界
|
||||||
|
|
||||||
|
| Django app | 拥有的数据与职责 | 不应承担 |
|
||||||
|
|---|---|---|
|
||||||
|
| `accounts` | 用户、组、角色、权限、菜单授权 | 业务状态判断 |
|
||||||
|
| `tickets` | 工单、评论、附件、事件、协作人、处理结果 | 直接调用模型 |
|
||||||
|
| `solutions` | 可复用方案、版本、工单关联与采纳统计 | 保存某次 Agent 的完整输出 |
|
||||||
|
| `knowledge` | 知识库、文档、版本、条目、切片、向量、检索 | Agent 流程编排 |
|
||||||
|
| `modelhub` | 渠道、模型、能力、凭证、测试、调用用量 | 工单业务规则 |
|
||||||
|
| `agents` | Agent 定义版本、运行、步骤、产物、引用、人工决定 | 越过业务服务写正式数据 |
|
||||||
|
| `skills` | Prompt 模板、Schema、版本、资源范围 | 任意代码执行 |
|
||||||
|
| `tools` | MCP 服务、工具快照、授权、风险、调用记录 | 自动批准高风险操作 |
|
||||||
|
| `audit` | 统一审计事件和查询 | 代替领域事件 |
|
||||||
|
| `system` | 全局开关、字典和运行配置 | 存放模块私有配置 |
|
||||||
|
|
||||||
|
## 8. 关键数据设计
|
||||||
|
|
||||||
|
### 8.1 标识策略
|
||||||
|
|
||||||
|
- 延续当前 `BigAutoField` 作为数据库内部主键，避免无业务收益的全表 UUID 改造。
|
||||||
|
- 工单继续使用不可重复的 `ticket_no` 作为业务标识。
|
||||||
|
- Agent run、外部回调和可分享资源增加 UUID `public_id`，不暴露可枚举内部主键。
|
||||||
|
- 旧系统编号只存在迁移 staging 和映射表，不进入工单主表。
|
||||||
|
|
||||||
|
### 8.2 工单与知识
|
||||||
|
|
||||||
|
- `Ticket` 保持瘦主表，只保留身份、当前状态、分类、优先级、提出人、负责人和关键时间。
|
||||||
|
- 评论、附件、协作人、事件和状态历史继续使用子表。
|
||||||
|
- `TicketResolution` 是某次工单处理结果的权威记录。
|
||||||
|
- `Solution` 是可复用知识资产；通过 `TicketSolutionLink` 表达推荐、引用、采纳或派生。
|
||||||
|
- 知识文档必须有版本和处理状态；切片绑定文档版本，发布新版本不能静默改写历史 Agent 引用。
|
||||||
|
- 向量字段改为 pgvector，记录 Embedding 模型、维度、内容哈希和生成时间。
|
||||||
|
|
||||||
|
### 8.3 AI 运行最小实体集
|
||||||
|
|
||||||
|
| 实体 | 作用 |
|
||||||
|
|---|---|
|
||||||
|
| `ModelProvider` | 渠道地址、协议、加密凭证和启用状态 |
|
||||||
|
| `ModelDeployment` | 模型名称、能力类型、上下文限制、默认用途和参数 |
|
||||||
|
| `AgentDefinition` / `AgentVersion` | 稳定身份与不可变运行配置快照 |
|
||||||
|
| `SkillDefinition` / `SkillVersion` | 配置型能力与版本化 Prompt/Schema |
|
||||||
|
| `AgentRun` | 触发人、业务上下文、状态、版本、耗时、错误和用量 |
|
||||||
|
| `AgentStep` | 模型、检索、Skill、工具或人工确认步骤 |
|
||||||
|
| `AgentArtifact` | 字段草稿、分析、排查清单、回复或知识草稿 |
|
||||||
|
| `AgentReference` | 引用的知识、方案、工单、文档切片及当时内容快照 |
|
||||||
|
| `ArtifactDecision` | 采纳、修改后采纳、拒绝及操作者 |
|
||||||
|
| `ToolCall` | 工具输入/输出摘要、状态、风险、耗时和授权依据 |
|
||||||
|
|
||||||
|
Agent 运行必须绑定不可变的 Agent/Skill 版本和实际模型配置，不能只保存当前配置的外键，否则无法复盘历史结果。
|
||||||
|
|
||||||
|
## 9. Agent、Skill、MCP 运行边界
|
||||||
|
|
||||||
|
### 9.1 Agent
|
||||||
|
|
||||||
|
第一版只提供三个系统内置 Agent，不提供可视化自由编排器：
|
||||||
|
|
||||||
|
1. 建单 Agent：抽取字段、判断缺失信息、推荐分类和相似内容。
|
||||||
|
2. 支持分析 Agent：生成问题摘要、原因假设、排查步骤、方案推荐和回复草稿。
|
||||||
|
3. 知识沉淀 Agent：从已解决工单生成解决方案或知识草稿。
|
||||||
|
|
||||||
|
管理员可以选择模型、Skill、知识库和工具范围，但不能改变人工确认边界。
|
||||||
|
|
||||||
|
### 9.2 Skill
|
||||||
|
|
||||||
|
Skill 是有版本的配置型专业能力，不是代码插件。每个 Skill 至少包含适用场景、Prompt 模板、输入 Schema、输出 Schema、允许的知识范围、允许的工具范围和测试样例。发布后的版本不可原地修改。
|
||||||
|
|
||||||
|
### 9.3 MCP
|
||||||
|
|
||||||
|
- 第一版只允许只读工具进入自动调用白名单。
|
||||||
|
- 每个工具同步后生成本地快照，并由管理员标注读写属性、风险等级和数据敏感级别。
|
||||||
|
- Agent 只能调用同时满足“服务启用、工具启用、Agent 已绑定、用户有权限”的工具。
|
||||||
|
- 无法确认读写属性的工具按高风险处理并阻止自动执行。
|
||||||
|
- 写操作只保留接口和确认模型的设计，不进入首个试运行的真实执行范围。
|
||||||
|
|
||||||
|
## 10. 交付路线
|
||||||
|
|
||||||
|
本路线不按模块横向铺开，而按可演示、可测试、可度量的纵向业务切片推进。每一阶段通过退出门槛后再进入下一阶段；平台完整性是终点，不是第一批代码的组织方式。
|
||||||
|
|
||||||
|
### Phase 0：基线收敛
|
||||||
|
|
||||||
|
目标：把当前真实能力、原型资产和结构债务分开，形成可持续演进的干净基线。
|
||||||
|
|
||||||
|
交付：
|
||||||
|
|
||||||
|
- 本蓝图成为唯一主蓝图，旧阶段文档只作 Git 历史参考。
|
||||||
|
- 盘点并处理当前工作树中的原型、设计实验和依赖变更。
|
||||||
|
- 建立“真实 / 演示 / 未实现”能力清单，演示页面有统一边界。
|
||||||
|
- 确认 `TicketResolution`、AI 产物和知识版本的权威数据规则。
|
||||||
|
- 建立后端、前端和端到端测试命令；为核心接口生成稳定契约。
|
||||||
|
- 补充架构决策记录：主键、Vite、模块化单体、人工确认、检索实现。
|
||||||
|
|
||||||
|
退出门槛：
|
||||||
|
|
||||||
|
- 默认产品路径不把 Mock 操作表现为真实成功。
|
||||||
|
- 当前真实业务回归通过，迁移可在全新数据库执行。
|
||||||
|
- 数据债务有明确迁移顺序，后续阶段不再向 `Ticket.ai_solution` 写新逻辑。
|
||||||
|
|
||||||
|
### Phase 1：可信建单闭环
|
||||||
|
|
||||||
|
目标：交付第一个真实 AI 业务闭环，并由它长出最小模型网关和 Agent 运行时。
|
||||||
|
|
||||||
|
交付：
|
||||||
|
|
||||||
|
- 最小模型渠道、模型配置、加密凭证和连通性测试。
|
||||||
|
- `AgentRun`、步骤、产物、引用和人工决定的最小数据模型。
|
||||||
|
- 建单 Agent：自然语言输入 -> 字段草稿 -> 缺失信息 -> 用户确认 -> 创建工单。
|
||||||
|
- AI 失败、超时或输出 Schema 不合法时回退到普通建单。
|
||||||
|
- 工单事件和审计记录用户采纳了哪些 AI 字段。
|
||||||
|
|
||||||
|
退出门槛：
|
||||||
|
|
||||||
|
- 至少一个真实 OpenAI-compatible 渠道可完成建单分析。
|
||||||
|
- 未经确认不能创建或修改工单。
|
||||||
|
- 同一确认请求具备幂等性，不会重复建单。
|
||||||
|
- 正常、拒绝、人工修改、模型失败和超时路径均有自动化测试。
|
||||||
|
|
||||||
|
### Demo Milestone：AI 平台配置演示版
|
||||||
|
|
||||||
|
该里程碑位于 Phase 0 与 Phase 1 之间，是面向研发管理员的真实运行验证，不等同于业务试运行版本。它用于提前验证模型渠道、配置型 Skill、版本化 Agent 和异步执行轨迹能否形成稳定技术底座，完成后仍按 Phase 1 接入可信建单闭环。
|
||||||
|
|
||||||
|
交付：
|
||||||
|
|
||||||
|
- 一个真实 OpenAI-compatible 文本模型渠道和模型测试能力。
|
||||||
|
- Skill 草稿、发布版本、JSON Schema、受限 Prompt 模板和回滚。
|
||||||
|
- Agent 草稿、发布版本、有序 Skill 步骤、沙箱测试和回滚。
|
||||||
|
- Celery 异步运行、步骤轨迹、结构修复、一次瞬时重试、尽力取消和 90 天留存。
|
||||||
|
- 模型、Skill、Agent 和运行记录的研发管理员工作台。
|
||||||
|
- 预置技术支持分析 Agent，完成问题结构化、排查建议和客户回复草稿三步演示。
|
||||||
|
|
||||||
|
退出门槛：
|
||||||
|
|
||||||
|
- 研发管理员可从模型配置开始，完成 Agent 发布、真实运行和轨迹查看。
|
||||||
|
- 发布版本不可变，历史运行能够还原实际 Agent、Skill、模型和参数快照。
|
||||||
|
- 凭证加密、权限、审计、失败终止、重试和取消路径通过自动化测试。
|
||||||
|
- 演示页面与真实页面边界明确，不把 Mock 数据声明为真实运行结果。
|
||||||
|
|
||||||
|
### Phase 2：支持分析工作区
|
||||||
|
|
||||||
|
目标：让技术支持在真实工单详情中获得有依据、可采纳的分析，而不是使用独立聊天页。
|
||||||
|
|
||||||
|
交付：
|
||||||
|
|
||||||
|
- PostgreSQL/pgvector 与真实 Embedding 模型接入。
|
||||||
|
- 知识、解决方案和历史工单的混合检索及引用展示。
|
||||||
|
- 支持分析 Agent：摘要、原因假设、排查步骤、方案推荐和客户回复草稿。
|
||||||
|
- 运行轨迹、引用、耗时、Token/费用和错误详情。
|
||||||
|
- 采纳、修改后采纳、拒绝以及关联解决方案的完整记录。
|
||||||
|
|
||||||
|
退出门槛：
|
||||||
|
|
||||||
|
- 支持人员能从一张真实工单完成“分析 -> 查依据 -> 采纳 -> 回复/解决”。
|
||||||
|
- 每条可采纳结论至少能展示来源，无法提供来源时明确标为模型推断。
|
||||||
|
- 检索或模型失败不阻断人工处理。
|
||||||
|
- 建立离线样例集，能比较调整前后的检索和建议效果。
|
||||||
|
|
||||||
|
### Phase 3：知识飞轮
|
||||||
|
|
||||||
|
目标：把一次性处理结果转化为经过审核、可持续维护的业务资产。
|
||||||
|
|
||||||
|
交付：
|
||||||
|
|
||||||
|
- MinIO 真实文件上传、访问控制、解析状态和失败重试。
|
||||||
|
- 文档版本、解析、切片、Embedding、重建索引和下线流程。
|
||||||
|
- 知识沉淀 Agent 从已解决工单生成草稿。
|
||||||
|
- 知识/方案审核、发布、驳回、版本和来源链路。
|
||||||
|
- 重复方案检测、过期内容标记和被引用影响提示。
|
||||||
|
|
||||||
|
退出门槛：
|
||||||
|
|
||||||
|
- 已解决工单可生成草稿，但未经审核不可进入正式检索范围。
|
||||||
|
- 任一检索结果可回到原文档版本、方案或工单。
|
||||||
|
- 文档更新、重建索引和回滚不会破坏历史 Agent 引用。
|
||||||
|
|
||||||
|
### Phase 4：平台配置与 MCP 可信调用
|
||||||
|
|
||||||
|
目标：在三个内置业务闭环已经稳定后，开放可配置能力和外部只读工具。
|
||||||
|
|
||||||
|
交付：
|
||||||
|
|
||||||
|
- 模型能力注册、用途绑定、参数模板、测试和用量统计。
|
||||||
|
- Agent/Skill 版本、发布、回滚和测试样例管理。
|
||||||
|
- MCP 服务注册、认证配置、连接检查、工具同步和本地快照。
|
||||||
|
- Agent 工具授权矩阵、只读调用、敏感字段脱敏和全量审计。
|
||||||
|
- 高风险、未授权、定义变化和服务不可用时的阻止策略。
|
||||||
|
|
||||||
|
退出门槛：
|
||||||
|
|
||||||
|
- 不改业务代码即可为内置 Agent 切换已授权模型或 Skill 版本。
|
||||||
|
- 至少一个真实只读 MCP 工具能在授权范围内被支持分析 Agent 调用。
|
||||||
|
- 未授权、非只读和高风险调用均被后端拦截并留下审计记录。
|
||||||
|
|
||||||
|
### Phase 5：企业试运行与历史迁移
|
||||||
|
|
||||||
|
目标：达到单企业私有化试运行标准，并导入对检索有价值的历史工单。
|
||||||
|
|
||||||
|
交付：
|
||||||
|
|
||||||
|
- 全新环境一键初始化、迁移、管理员和预置角色创建。
|
||||||
|
- 健康检查、结构化日志、任务监控、告警、备份恢复和升级回滚。
|
||||||
|
- 密钥轮换、日志脱敏、文件安全、权限矩阵和安全检查。
|
||||||
|
- 历史工单 staging、清洗、映射、批次校验和失败重跑。
|
||||||
|
- 关键用户旅程的端到端验收、使用说明和已知限制。
|
||||||
|
|
||||||
|
退出门槛：
|
||||||
|
|
||||||
|
- 新环境可按文档独立部署并通过验收。
|
||||||
|
- 完成一次数据库与对象存储备份恢复演练。
|
||||||
|
- 历史迁移可重复执行且不污染正式工单模型。
|
||||||
|
- 核心业务、三类 Agent 和只读 MCP 均有可追溯验收记录。
|
||||||
|
|
||||||
|
## 11. 阶段依赖与并行边界
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
P0["Phase 0 基线收敛"] --> P1["Phase 1 可信建单"]
|
||||||
|
P1 --> P2["Phase 2 支持分析"]
|
||||||
|
P2 --> P3["Phase 3 知识飞轮"]
|
||||||
|
P3 --> P4["Phase 4 平台配置与 MCP"]
|
||||||
|
P4 --> P5["Phase 5 企业试运行"]
|
||||||
|
```
|
||||||
|
|
||||||
|
在不改变阶段退出门槛的前提下，可并行的工作只有：
|
||||||
|
|
||||||
|
- 设计系统和通用交互组件可以跟随每个纵向切片同步演进。
|
||||||
|
- 运维基线、安全检查和历史数据画像可以提前准备，但正式迁移在数据模型稳定后进行。
|
||||||
|
- 知识样例集可在 Phase 1 开始整理，真实 pgvector 和发布链路分别在 Phase 2、Phase 3 落地。
|
||||||
|
|
||||||
|
模型配置台、Skill 管理台和 Agent 管理台只在 Demo Milestone 的真实运行链路内建设；MCP 管理台不提前展开。完成演示后，平台配置能力必须进入 Phase 1 的真实建单场景，而不是继续横向扩张。
|
||||||
|
|
||||||
|
## 12. 产品信息架构
|
||||||
|
|
||||||
|
首个试运行版本采用任务导向导航：
|
||||||
|
|
||||||
|
| 一级导航 | 页面 |
|
||||||
|
|---|---|
|
||||||
|
| 工作台 | 我的待办、待回复、即将超时、近期 Agent 异常 |
|
||||||
|
| 工单 | 工单列表、创建工单、工单详情 |
|
||||||
|
| 知识 | 统一检索、知识库、知识条目、文档、待审核草稿 |
|
||||||
|
| 解决方案 | 方案列表、详情、版本、引用工单 |
|
||||||
|
| AI 能力 | Agent、运行记录、Skill、模型渠道、模型测试 |
|
||||||
|
| 工具 | MCP 服务、工具授权、调用记录 |
|
||||||
|
| 系统管理 | 用户、用户组、角色、菜单、审计、系统设置 |
|
||||||
|
|
||||||
|
AI 不单独占据主要工作流：建单辅助出现在创建工单页，支持分析出现在工单详情，知识沉淀出现在解决/关闭后的操作区。管理页面只负责配置和诊断。
|
||||||
|
|
||||||
|
## 13. API、异步任务与错误约定
|
||||||
|
|
||||||
|
- 所有写接口使用明确动作语义，例如 `confirm-draft`、`adopt-artifact`，不通过通用 PATCH 隐式触发 AI 或状态变化。
|
||||||
|
- 状态流转、方案采纳、知识发布和 AI 产物采纳均使用数据库事务和幂等键。
|
||||||
|
- Agent 长运行返回 run id；前端轮询状态作为第一版基线，确有实时体验需求再引入 SSE。
|
||||||
|
- 异步任务至少记录 `queued/running/succeeded/failed/cancelled/timed_out`。
|
||||||
|
- 供应商错误统一映射为平台错误码，原始敏感响应仅进入受控诊断日志。
|
||||||
|
- OpenAPI 是前后端契约来源；正式页面不得长期手写一套与后端脱离的重复类型。
|
||||||
|
|
||||||
|
## 14. 安全与可信边界
|
||||||
|
|
||||||
|
- 模型和 MCP 凭证加密保存，前端仅显示脱敏值，审计日志不得记录明文。
|
||||||
|
- 传给外部模型或工具的数据在运行前经过字段级策略和脱敏处理。
|
||||||
|
- Prompt、知识内容和工具返回都视为不可信输入，不能直接转化为业务操作。
|
||||||
|
- Agent 运行使用触发用户的权限上下文，不因系统账号执行而扩大访问范围。
|
||||||
|
- 引用内容、模型输出和人工编辑在界面与数据中保持来源区分。
|
||||||
|
- AI 输出不得成为状态流转的唯一校验条件。
|
||||||
|
- 附件需校验大小、类型和访问权限；恶意文件扫描作为试运行安全门槛。
|
||||||
|
|
||||||
|
## 15. 质量门禁
|
||||||
|
|
||||||
|
每个 Phase 必须同时满足：
|
||||||
|
|
||||||
|
- 后端单元/接口测试通过，Ruff 和迁移检查通过。
|
||||||
|
- 前端测试、类型检查、Lint 和生产构建通过。
|
||||||
|
- 核心用户旅程有跨端测试，不以页面能打开代替闭环完成。
|
||||||
|
- 新增权限点有预置角色矩阵和越权测试。
|
||||||
|
- 新增 AI 能力有成功、失败、超时、非法结构、拒绝和降级测试。
|
||||||
|
- 数据迁移可在全新数据库执行，回滚或向前修复策略明确。
|
||||||
|
- README、蓝图、接口说明和运行手册与代码状态一致。
|
||||||
|
|
||||||
|
“已完成”的定义必须标注层级：
|
||||||
|
|
||||||
|
| 标记 | 含义 |
|
||||||
|
|---|---|
|
||||||
|
| 设计 | 只有设计或交互稿 |
|
||||||
|
| 演示 | 使用 Mock/本地桩，可展示但不持久化 |
|
||||||
|
| 集成 | 已接真实 API/模型，但尚未通过完整验收 |
|
||||||
|
| 可试运行 | 通过权限、审计、失败降级和端到端验收 |
|
||||||
|
|
||||||
|
## 16. 立即执行的下一迭代
|
||||||
|
|
||||||
|
下一迭代先完成 Phase 0，再实施研发管理员使用的 AI 平台配置演示里程碑。该演示只包含模型、Agent 和 Skill，不启动 MCP，也不计为业务闭环完成。
|
||||||
|
|
||||||
|
建议任务顺序：
|
||||||
|
|
||||||
|
1. 将当前工作树中的产品概念实验、依赖升级和文档删除整理成可审查的变更集。
|
||||||
|
2. 建立 `docs/product/capability-status.md`，逐项标注真实、演示、缺失和债务。
|
||||||
|
3. 写出 `TicketResolution`、`AgentArtifact`、知识版本和引用快照的数据决策记录。
|
||||||
|
4. 禁止新增代码读取或写入 `Ticket.ai_solution`，设计兼容迁移。
|
||||||
|
5. 为工单创建、状态流转、方案采纳和知识检索补最小跨端回归。
|
||||||
|
6. 固化全新数据库迁移、后端测试、前端测试/类型检查/Lint/构建命令。
|
||||||
|
7. 完成 AI 平台配置演示里程碑后，更新能力状态并编写 Phase 1 可信建单闭环的实施计划。
|
||||||
|
|
||||||
|
AI 平台配置演示只验证真实运行底座，不建设通用 Agent 平台。其后下一份实施文档必须是“可信建单闭环设计”。
|
||||||
|
|
||||||
|
## 17. 已决策事项
|
||||||
|
|
||||||
|
| 事项 | 决策 |
|
||||||
|
|---|---|
|
||||||
|
| 产品路线 | 新产品替代旧系统，不做旧系统 AI 外挂 |
|
||||||
|
| 部署 | 单企业私有化，不做多租户 |
|
||||||
|
| 架构 | Django 模块化单体 + 异步 worker，不提前微服务化 |
|
||||||
|
| 前端 | 保留 React + Vite；当前无 SSR/SEO 需求，不改 Next.js |
|
||||||
|
| 主键 | 内部 bigint；工单使用业务编号；外部关联场景增加 UUID public id |
|
||||||
|
| 工作流 | 领域服务中的有限状态机，不引入 BPMN |
|
||||||
|
| Agent | 三类内置 Agent，默认只生成建议和草稿 |
|
||||||
|
| Skill | 只做配置型、版本化 Skill |
|
||||||
|
| MCP | 只读优先，未明确只读即阻止自动执行 |
|
||||||
|
| 向量检索 | PostgreSQL + pgvector，当前 JSON 哈希向量仅视为临时桩 |
|
||||||
|
| 历史数据 | 只迁历史工单，经 staging 清洗，不污染正式模型 |
|
||||||
|
|
||||||
|
## 18. 仍需在对应阶段确认
|
||||||
|
|
||||||
|
以下问题不阻塞 Phase 0，但必须在指定阶段开始前形成决策记录：
|
||||||
|
|
||||||
|
| 问题 | 最晚时机 |
|
||||||
|
|---|---|
|
||||||
|
| 首个真实模型渠道、数据出境约束和脱敏规则 | Phase 1 前 |
|
||||||
|
| 图片/附件进入视觉模型的文件范围和保留策略 | Phase 1 前 |
|
||||||
|
| Embedding 模型、维度、中文检索评测集和重建成本 | Phase 2 前 |
|
||||||
|
| 知识审核角色、发布 SLA 和过期策略 | Phase 3 前 |
|
||||||
|
| 首个只读 MCP 服务、认证方式和工具风险责任人 | Phase 4 前 |
|
||||||
|
| 历史工单规模、质量、字段映射和脱敏要求 | Phase 5 前 |
|
||||||
|
|
||||||
|
## 19. 蓝图维护规则
|
||||||
|
|
||||||
|
- 本文描述跨阶段目标、边界、依赖和完成定义，不写文件级编码步骤。
|
||||||
|
- 每次只为当前 Phase 新建设计与实施计划；未开始阶段不提前拆成大量任务。
|
||||||
|
- 产品范围或关键架构变化先更新本文，再修改实施计划。
|
||||||
|
- 已完成阶段的事实写入能力状态文档，讨论过程保留在沟通记录或 Git 历史中。
|
||||||
|
- 如果代码、README 和本文冲突，以已验证代码事实为现状，以本文为后续方向，并立即登记差距。
|
||||||
41
docs/product/capability-status.md
Normal file
41
docs/product/capability-status.md
Normal file
@@ -0,0 +1,41 @@
|
|||||||
|
# AI 工单平台能力状态
|
||||||
|
|
||||||
|
更新日期：2026-07-14
|
||||||
|
|
||||||
|
状态定义：
|
||||||
|
|
||||||
|
| 状态 | 含义 |
|
||||||
|
|---|---|
|
||||||
|
| 真实 | 已接真实数据库或服务，具备自动化测试 |
|
||||||
|
| 演示 | 使用 Mock、确定性桩或独立概念页面 |
|
||||||
|
| 缺失 | 尚无可用实现 |
|
||||||
|
| 债务 | 已有实现与目标架构存在明确差距 |
|
||||||
|
|
||||||
|
## 当前能力
|
||||||
|
|
||||||
|
| 领域 | 能力 | 状态 | 说明 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| 企业治理 | 登录、用户、用户组、角色、菜单权限 | 真实 | Django 权限与菜单 API 已实现 |
|
||||||
|
| 企业治理 | 操作审计 | 真实 | 已覆盖部分治理和工单操作，AI 审计待补 |
|
||||||
|
| 工单 | 创建、查询、编辑、分类状态流转、评论、导出 | 真实 | 后端与前端均使用真实 API |
|
||||||
|
| 工单 | 附件 | 债务 | 当前仅记录附件元数据和存储路径，尚无真实对象上传 |
|
||||||
|
| 工单 | AI 建议 | 债务 | `Ticket.ai_solution` 位于业务主表，后续停止新增依赖 |
|
||||||
|
| 解决方案 | 维护、关联、采纳并关闭工单 | 真实 | 已有 API、事件和使用次数统计 |
|
||||||
|
| 知识 | 知识库、条目、文档文本、切片和检索 | 真实 | 基础 CRUD 与检索 API 可运行 |
|
||||||
|
| 知识 | 向量检索 | 演示 | 使用 JSON 哈希向量和应用内排序，不是 pgvector/真实 Embedding |
|
||||||
|
| AI 平台 | 模型渠道和真实模型测试 | 缺失 | 本次演示里程碑实施 |
|
||||||
|
| AI 平台 | Skill 草稿、发布、Schema 和回滚 | 缺失 | 本次演示里程碑实施 |
|
||||||
|
| AI 平台 | Agent 版本、有序执行和运行轨迹 | 缺失 | 本次演示里程碑实施 |
|
||||||
|
| AI 平台 | MCP | 缺失 | 不在本次演示范围 |
|
||||||
|
| 前端 | 工单工作台概念方案 | 演示 | 保留在 `/concept` 设计实验室，不计为真实功能 |
|
||||||
|
| 部署 | PostgreSQL、Redis、MinIO 本地基础设施 | 真实 | `infra/docker-compose.local.yml` |
|
||||||
|
| 部署 | Celery worker | 债务 | 配置存在但尚无真实任务，本次演示里程碑补齐 |
|
||||||
|
|
||||||
|
## 当前质量基线
|
||||||
|
|
||||||
|
- 后端测试：43 项通过。
|
||||||
|
- 前端测试：6 项通过。
|
||||||
|
- 前端 TypeScript 类型检查和生产构建通过。
|
||||||
|
- 前端生产包存在体积告警，后续管理页面接入时需要按路由拆分评估。
|
||||||
|
|
||||||
|
能力状态只依据已验证代码更新。页面存在、类型定义存在或 Mock 可交互，不视为真实能力。
|
||||||
@@ -1,100 +0,0 @@
|
|||||||
# AI Ticket Platform Implementation Roadmap
|
|
||||||
|
|
||||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:writing-plans to expand each stage into a detailed implementation plan before writing code. Use superpowers:subagent-driven-development or superpowers:executing-plans when executing a detailed stage plan.
|
|
||||||
|
|
||||||
**Goal:** Break the AI-native technical support ticket platform into independently deliverable implementation stages.
|
|
||||||
|
|
||||||
**Architecture:** Build a modular monolith first. Keep Django apps, React feature modules, workers, model gateway, Agent runtime, and MCP integration separated by clear interfaces so heavily loaded areas can be split later.
|
|
||||||
|
|
||||||
**Tech Stack:** Django, Django Ninja, PostgreSQL, pgvector, Redis, Celery, MinIO, React, Vite, Tailwind CSS, shadcn/ui, Radix UI, TanStack Table, OpenAI-compatible model adapter.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Source Spec
|
|
||||||
|
|
||||||
- `docs/superpowers/specs/2026-06-30-ai-ticket-platform-design.md`
|
|
||||||
|
|
||||||
## Planning Rule
|
|
||||||
|
|
||||||
The product contains multiple independent subsystems. Do not implement the entire spec from one plan. Use this roadmap to create one detailed plan per stage. Each detailed plan must produce working, testable software.
|
|
||||||
|
|
||||||
## Stage Breakdown
|
|
||||||
|
|
||||||
| Stage | Name | Purpose | Depends On | Detailed Plan |
|
|
||||||
|---|---|---|---|---|
|
|
||||||
| 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` |
|
|
||||||
| 1.6 | Enterprise governance and login | Add login/logout/current-user APIs, user/user-group/role/menu management, API permission enforcement, permission-driven frontend menus, and deployment bootstrap. | Stage 1.5 | `docs/superpowers/specs/2026-07-01-stage-1-6-enterprise-governance-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. |
|
|
||||||
| 5 | Historical ticket migration and polish | Import historical tickets, standardize fields, vectorize, generate solution drafts, add dashboards and UI polish. | Stage 1, Stage 2, Stage 3 | Create after core flows work. |
|
|
||||||
|
|
||||||
## Stage 0 Deliverables
|
|
||||||
|
|
||||||
| Area | Deliverable |
|
|
||||||
|---|---|
|
|
||||||
| Backend | Django project, settings split, Django Ninja API root, health endpoint, accounts app, audit app, system app. |
|
|
||||||
| Frontend | Vite React project, Tailwind, shadcn/Radix base, theme tokens, layout shell, component preview page. |
|
|
||||||
| Runtime | Docker Compose with backend, frontend, PostgreSQL, Redis, MinIO, Celery worker, Celery beat. |
|
|
||||||
| Governance | Login baseline, users/groups/roles baseline, menu definitions, permission seed command, audit model. |
|
|
||||||
| Quality | pytest, ruff, mypy baseline, frontend lint/typecheck/build, pre-commit optional. |
|
|
||||||
| Documentation | `.env.example`, local startup guide, design system notes. |
|
|
||||||
|
|
||||||
## Stage 1 Deliverables
|
|
||||||
|
|
||||||
| Area | Deliverable |
|
|
||||||
|---|---|
|
|
||||||
| Ticket core | `ticket`, `ticket_category`, `ticket_comment`, `ticket_attachment`, `ticket_event`, `ticket_collaborator`. |
|
|
||||||
| Ticket APIs | Create/list/detail/update/status transition/comment/upload/export. |
|
|
||||||
| Ticket UI | List page, create page, detail page, status timeline, comments, attachments. |
|
|
||||||
| Solutions | `solution`, `ticket_resolution`, `ticket_solution_link`, solution list/detail/linking. |
|
|
||||||
| Audit | Ticket operations written to audit/event tables. |
|
|
||||||
|
|
||||||
## Stage 2 Deliverables
|
|
||||||
|
|
||||||
| Area | Deliverable |
|
|
||||||
|---|---|
|
|
||||||
| Knowledge | `knowledge_base`, `knowledge_document`, `knowledge_item`, `knowledge_chunk`. |
|
|
||||||
| Jobs | Document parsing, chunking, embedding enqueue/retry/status. |
|
|
||||||
| Retrieval | Keyword search plus vector search interface. |
|
|
||||||
| UI | Knowledge base, document status, knowledge item editor, search page. |
|
|
||||||
|
|
||||||
## Stage 3 Deliverables
|
|
||||||
|
|
||||||
| Area | Deliverable |
|
|
||||||
|---|---|
|
|
||||||
| Model gateway | `model_provider`, `model_config`, encrypted secrets, OpenAI-compatible client adapter. |
|
|
||||||
| Model testing | Single model test and multi-model comparison UI. |
|
|
||||||
| Skills | `skill_definition`, prompt template rendering, input/output schema validation. |
|
|
||||||
| Agents | `agent_definition`, `agent_run`, `agent_step`, `ticket_ai_artifact`. |
|
|
||||||
| Built-ins | Ticket creation Agent, support analysis Agent, knowledge distillation Agent. |
|
|
||||||
|
|
||||||
## Stage 4 Deliverables
|
|
||||||
|
|
||||||
| Area | Deliverable |
|
|
||||||
|---|---|
|
|
||||||
| MCP config | `tool_server`, `tool_definition`, `tool_call`. |
|
|
||||||
| Sync | Tool discovery/sync from configured MCP server. |
|
|
||||||
| Risk control | low/medium/high risk, human confirmation for high risk. |
|
|
||||||
| Agent integration | Authorized tool calls appear in `agent_step` and `tool_call`. |
|
|
||||||
|
|
||||||
## Stage 5 Deliverables
|
|
||||||
|
|
||||||
| Area | Deliverable |
|
|
||||||
|---|---|
|
|
||||||
| Migration | Import script and staging model for historical tickets. |
|
|
||||||
| AI cleanup | Summaries, categories, error codes, solution draft generation. |
|
|
||||||
| Retrieval | Historical tickets available for similar-ticket search. |
|
|
||||||
| Dashboards | Ticket trends, high-frequency problems, solution usage, Agent usage. |
|
|
||||||
|
|
||||||
## Cross-Stage Invariants
|
|
||||||
|
|
||||||
- Business writes generated by AI require user confirmation by default.
|
|
||||||
- Secrets are encrypted at rest.
|
|
||||||
- Raw model/tool payloads stored in logs must support masking.
|
|
||||||
- No business page may define one-off colors, status badges, or table styling.
|
|
||||||
- Every backend stage includes API tests.
|
|
||||||
- Every frontend stage includes typecheck and build verification.
|
|
||||||
- Commit after each coherent task.
|
|
||||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -1,601 +0,0 @@
|
|||||||
# Stage 1.5 shadcn UI Foundation Implementation Plan
|
|
||||||
|
|
||||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
||||||
|
|
||||||
**Goal:** Formalize shadcn/ui in the Vite frontend, build a reusable Chinese enterprise admin App component layer, and redesign the existing ticket and solution pages around a production workbench experience.
|
|
||||||
|
|
||||||
**Architecture:** Keep shadcn-generated primitives under `frontend/src/components/ui` and project-owned product components under `frontend/src/components/app`. Business pages should compose App components for layout, table, filters, detail workbench, status, priority, and empty states while preserving existing backend API contracts.
|
|
||||||
|
|
||||||
**Tech Stack:** React 19, Vite 6, TypeScript, Tailwind CSS v3, shadcn/ui, Radix UI, lucide-react, npm.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Source Spec
|
|
||||||
|
|
||||||
- `docs/superpowers/specs/2026-07-01-stage-1-5-shadcn-ui-foundation-design.md`
|
|
||||||
|
|
||||||
## Scope
|
|
||||||
|
|
||||||
Stage 1.5 is frontend-only unless shadcn initialization unexpectedly requires a metadata adjustment. Do not add knowledge base, Agent, Skill, MCP, model gateway, or new backend behavior.
|
|
||||||
|
|
||||||
## File Structure
|
|
||||||
|
|
||||||
Expected created or modified files:
|
|
||||||
|
|
||||||
- Create: `frontend/components.json`
|
|
||||||
- Modify: `frontend/package.json`
|
|
||||||
- Modify: `frontend/package-lock.json`
|
|
||||||
- Modify: `frontend/tailwind.config.ts`
|
|
||||||
- Modify: `frontend/src/styles/globals.css`
|
|
||||||
- Create or replace shadcn primitives in `frontend/src/components/ui/*`
|
|
||||||
- Modify: `frontend/src/app/router.tsx`
|
|
||||||
- Modify: `frontend/src/app/layout/AppShell.tsx`
|
|
||||||
- Replace or remove: `frontend/src/app/layout/Sidebar.tsx`
|
|
||||||
- Replace or remove: `frontend/src/app/layout/Topbar.tsx`
|
|
||||||
- Create: `frontend/src/components/app/AppSidebar.tsx`
|
|
||||||
- Create: `frontend/src/components/app/AppTopbar.tsx`
|
|
||||||
- Modify: `frontend/src/components/app/AppPageHeader.tsx`
|
|
||||||
- Create: `frontend/src/components/app/AppDataTable.tsx`
|
|
||||||
- Create: `frontend/src/components/app/AppFilterBar.tsx`
|
|
||||||
- Create: `frontend/src/components/app/AppDetailLayout.tsx`
|
|
||||||
- Create: `frontend/src/components/app/AppSection.tsx`
|
|
||||||
- Modify: `frontend/src/components/app/AppEmptyState.tsx`
|
|
||||||
- Modify: `frontend/src/components/app/AppStatusBadge.tsx`
|
|
||||||
- Modify: `frontend/src/components/app/AppPriorityBadge.tsx`
|
|
||||||
- Modify: `frontend/src/features/design-system/DesignSystemPreview.tsx`
|
|
||||||
- Create: `frontend/src/features/workbench/WorkbenchPage.tsx`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketListPage.tsx`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketCreatePage.tsx`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketDetailPage.tsx`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketStatusTimeline.tsx`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketComments.tsx`
|
|
||||||
- Modify: `frontend/src/features/solutions/SolutionListPage.tsx`
|
|
||||||
- Modify: `frontend/src/features/solutions/SolutionLinkPanel.tsx`
|
|
||||||
|
|
||||||
## Task 1: Initialize shadcn/ui
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Create: `frontend/components.json`
|
|
||||||
- Modify: `frontend/package.json`
|
|
||||||
- Modify: `frontend/package-lock.json`
|
|
||||||
- Modify: `frontend/tailwind.config.ts`
|
|
||||||
- Modify: `frontend/src/styles/globals.css`
|
|
||||||
- Create or replace: `frontend/src/components/ui/*`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Capture current shadcn state**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npx shadcn@latest info
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected before initialization:
|
|
||||||
|
|
||||||
```text
|
|
||||||
config: null
|
|
||||||
components: []
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Initialize shadcn for the existing Vite app**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npx shadcn@latest init
|
|
||||||
```
|
|
||||||
|
|
||||||
Select options that preserve the existing project shape:
|
|
||||||
|
|
||||||
```text
|
|
||||||
Framework: Vite
|
|
||||||
TypeScript: yes
|
|
||||||
Tailwind CSS file: src/styles/globals.css
|
|
||||||
Tailwind config: tailwind.config.ts
|
|
||||||
Import alias: @
|
|
||||||
Use CSS variables: yes
|
|
||||||
Base color: neutral or zinc
|
|
||||||
```
|
|
||||||
|
|
||||||
Do not accept changes that move the app to Next.js or switch the package manager away from npm.
|
|
||||||
|
|
||||||
- [ ] **Step 3: Add the required shadcn primitives**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npx shadcn@latest add button badge card input textarea select label separator sidebar breadcrumb dropdown-menu table tabs sheet dialog tooltip skeleton sonner
|
|
||||||
```
|
|
||||||
|
|
||||||
If the CLI reports that one component name is unavailable, retry without only that component and document the exact skipped name in this plan's execution notes.
|
|
||||||
|
|
||||||
- [ ] **Step 4: Verify shadcn state**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npx shadcn@latest info
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected:
|
|
||||||
|
|
||||||
```text
|
|
||||||
config: present
|
|
||||||
components: non-empty
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 5: Run frontend typecheck**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npm run typecheck
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: exit code `0`. If shadcn overwrote local component APIs, fix imports and variants in Task 2 instead of editing business pages in this task.
|
|
||||||
|
|
||||||
- [ ] **Step 6: Commit**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add frontend/components.json frontend/package.json frontend/package-lock.json frontend/tailwind.config.ts frontend/src/styles/globals.css frontend/src/components/ui
|
|
||||||
git commit -m "feat: initialize shadcn ui"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Task 2: Build the App Component Layer
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `frontend/src/app/layout/AppShell.tsx`
|
|
||||||
- Create: `frontend/src/components/app/AppSidebar.tsx`
|
|
||||||
- Create: `frontend/src/components/app/AppTopbar.tsx`
|
|
||||||
- Modify: `frontend/src/components/app/AppPageHeader.tsx`
|
|
||||||
- Create: `frontend/src/components/app/AppDataTable.tsx`
|
|
||||||
- Create: `frontend/src/components/app/AppFilterBar.tsx`
|
|
||||||
- Create: `frontend/src/components/app/AppDetailLayout.tsx`
|
|
||||||
- Create: `frontend/src/components/app/AppSection.tsx`
|
|
||||||
- Modify: `frontend/src/components/app/AppEmptyState.tsx`
|
|
||||||
- Modify: `frontend/src/components/app/AppStatusBadge.tsx`
|
|
||||||
- Modify: `frontend/src/components/app/AppPriorityBadge.tsx`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Replace the layout imports**
|
|
||||||
|
|
||||||
`frontend/src/app/layout/AppShell.tsx` should import from the App component layer:
|
|
||||||
|
|
||||||
```tsx
|
|
||||||
import type * as React from 'react'
|
|
||||||
|
|
||||||
import { AppSidebar } from '@/components/app/AppSidebar'
|
|
||||||
import { AppTopbar } from '@/components/app/AppTopbar'
|
|
||||||
|
|
||||||
type AppShellProps = {
|
|
||||||
children: React.ReactNode
|
|
||||||
}
|
|
||||||
|
|
||||||
export function AppShell({ children }: AppShellProps) {
|
|
||||||
return (
|
|
||||||
<div className="min-h-screen bg-background text-foreground">
|
|
||||||
<AppSidebar />
|
|
||||||
<div className="min-h-screen lg:pl-72">
|
|
||||||
<AppTopbar />
|
|
||||||
{children}
|
|
||||||
</div>
|
|
||||||
</div>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Create Chinese sidebar navigation**
|
|
||||||
|
|
||||||
`frontend/src/components/app/AppSidebar.tsx` should define grouped navigation:
|
|
||||||
|
|
||||||
```tsx
|
|
||||||
import { Bot, BriefcaseBusiness, Database, Home, Library, Settings, ShieldCheck, Ticket } from 'lucide-react'
|
|
||||||
|
|
||||||
const navGroups = [
|
|
||||||
{
|
|
||||||
label: '工作台',
|
|
||||||
items: [{ href: '#/', label: '运营总览', icon: Home }]
|
|
||||||
},
|
|
||||||
{
|
|
||||||
label: '业务处理',
|
|
||||||
items: [
|
|
||||||
{ href: '#/tickets', label: '工单中心', icon: Ticket },
|
|
||||||
{ href: '#/tickets/new', label: '创建工单', icon: BriefcaseBusiness },
|
|
||||||
{ href: '#/solutions', label: '解决方案库', icon: Library }
|
|
||||||
]
|
|
||||||
},
|
|
||||||
{
|
|
||||||
label: '平台能力',
|
|
||||||
items: [
|
|
||||||
{ href: '#/knowledge', label: '知识库', icon: Database },
|
|
||||||
{ href: '#/agents', label: 'Agent 配置', icon: Bot },
|
|
||||||
{ href: '#/system', label: '系统治理', icon: ShieldCheck },
|
|
||||||
{ href: '#/design-system', label: '设计系统', icon: Settings }
|
|
||||||
]
|
|
||||||
}
|
|
||||||
]
|
|
||||||
```
|
|
||||||
|
|
||||||
Render the groups in a fixed left sidebar, using lucide icons and Chinese labels only.
|
|
||||||
|
|
||||||
- [ ] **Step 3: Create topbar and breadcrumb placeholder**
|
|
||||||
|
|
||||||
`frontend/src/components/app/AppTopbar.tsx` should show:
|
|
||||||
|
|
||||||
```text
|
|
||||||
AI 工单平台 / 当前工作区
|
|
||||||
```
|
|
||||||
|
|
||||||
and right-side placeholders:
|
|
||||||
|
|
||||||
```text
|
|
||||||
本地环境
|
|
||||||
系统管理员
|
|
||||||
```
|
|
||||||
|
|
||||||
Use `Badge` for `本地环境`, `Button` with `variant="ghost"` for `系统管理员`, `Separator` between breadcrumb and right-side controls, and lucide icons for visible icon buttons.
|
|
||||||
|
|
||||||
- [ ] **Step 4: Create reusable data table wrapper**
|
|
||||||
|
|
||||||
`frontend/src/components/app/AppDataTable.tsx` should accept:
|
|
||||||
|
|
||||||
```tsx
|
|
||||||
type AppDataTableColumn<Row> = {
|
|
||||||
key: string
|
|
||||||
header: React.ReactNode
|
|
||||||
cell: (row: Row) => React.ReactNode
|
|
||||||
className?: string
|
|
||||||
}
|
|
||||||
|
|
||||||
type AppDataTableProps<Row> = {
|
|
||||||
columns: AppDataTableColumn<Row>[]
|
|
||||||
rows: Row[]
|
|
||||||
getRowKey: (row: Row) => React.Key
|
|
||||||
emptyTitle: string
|
|
||||||
emptyDescription?: string
|
|
||||||
toolbar?: React.ReactNode
|
|
||||||
footer?: React.ReactNode
|
|
||||||
onRowClick?: (row: Row) => void
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Use shadcn `Table` primitives internally. Keep row height stable and use Chinese empty-state copy from props.
|
|
||||||
|
|
||||||
- [ ] **Step 5: Create filter and detail helpers**
|
|
||||||
|
|
||||||
Create:
|
|
||||||
|
|
||||||
```text
|
|
||||||
AppFilterBar: section wrapper for search input, select filters, and reset/actions.
|
|
||||||
AppDetailLayout: responsive detail layout with main and side columns.
|
|
||||||
AppSection: titled section wrapper with optional description and action.
|
|
||||||
```
|
|
||||||
|
|
||||||
These components must not know about ticket-specific fields.
|
|
||||||
|
|
||||||
- [ ] **Step 6: Update badge and empty-state components**
|
|
||||||
|
|
||||||
Ensure status labels are Chinese:
|
|
||||||
|
|
||||||
```text
|
|
||||||
pending_info=待补充
|
|
||||||
pending=待处理
|
|
||||||
in_progress=处理中
|
|
||||||
pending_confirm=待确认
|
|
||||||
resolved=已解决
|
|
||||||
closed=已关闭
|
|
||||||
```
|
|
||||||
|
|
||||||
Ensure priority labels are Chinese:
|
|
||||||
|
|
||||||
```text
|
|
||||||
low=低
|
|
||||||
medium=中
|
|
||||||
high=高
|
|
||||||
urgent=紧急
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 7: Run frontend typecheck**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npm run typecheck
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: exit code `0`.
|
|
||||||
|
|
||||||
- [ ] **Step 8: Commit**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add frontend/src/app/layout frontend/src/components/app
|
|
||||||
git commit -m "feat: add enterprise app ui layer"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Task 3: Add Chinese Workbench and Routing
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `frontend/src/app/router.tsx`
|
|
||||||
- Create: `frontend/src/features/workbench/WorkbenchPage.tsx`
|
|
||||||
- Modify: `frontend/src/features/design-system/DesignSystemPreview.tsx`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Add the default workbench route**
|
|
||||||
|
|
||||||
In `frontend/src/app/router.tsx`, change the default route from `/tickets` to `/` and route `/` to `WorkbenchPage`.
|
|
||||||
|
|
||||||
Required behavior:
|
|
||||||
|
|
||||||
```text
|
|
||||||
#/ -> WorkbenchPage
|
|
||||||
#/tickets -> TicketListPage
|
|
||||||
#/tickets/new -> TicketCreatePage
|
|
||||||
#/tickets/:id -> TicketDetailPage
|
|
||||||
#/solutions -> SolutionListPage
|
|
||||||
#/design-system -> DesignSystemPreview
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Create workbench page**
|
|
||||||
|
|
||||||
`WorkbenchPage` should load tickets with `listTickets({})` and show Chinese operational sections:
|
|
||||||
|
|
||||||
```text
|
|
||||||
今日工作台
|
|
||||||
待处理工单
|
|
||||||
处理中
|
|
||||||
高优先级
|
|
||||||
已解决
|
|
||||||
最近工单
|
|
||||||
快捷入口
|
|
||||||
```
|
|
||||||
|
|
||||||
Use the existing ticket API only. Counts can be computed from the loaded list.
|
|
||||||
|
|
||||||
- [ ] **Step 3: Update design system preview**
|
|
||||||
|
|
||||||
The preview page should demonstrate:
|
|
||||||
|
|
||||||
```text
|
|
||||||
按钮
|
|
||||||
状态标签
|
|
||||||
优先级标签
|
|
||||||
筛选条
|
|
||||||
数据表格
|
|
||||||
详情区块
|
|
||||||
空状态
|
|
||||||
```
|
|
||||||
|
|
||||||
All visible text must be Chinese.
|
|
||||||
|
|
||||||
- [ ] **Step 4: Run frontend typecheck**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npm run typecheck
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: exit code `0`.
|
|
||||||
|
|
||||||
- [ ] **Step 5: Commit**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add frontend/src/app/router.tsx frontend/src/features/workbench frontend/src/features/design-system/DesignSystemPreview.tsx
|
|
||||||
git commit -m "feat: add chinese workbench page"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Task 4: Redesign Ticket Pages
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketListPage.tsx`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketCreatePage.tsx`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketDetailPage.tsx`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketStatusTimeline.tsx`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketComments.tsx`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Redesign ticket list as a table workbench**
|
|
||||||
|
|
||||||
Use `AppPageHeader`, `AppFilterBar`, `AppDataTable`, `AppStatusBadge`, and `AppPriorityBadge`.
|
|
||||||
|
|
||||||
Required Chinese table columns:
|
|
||||||
|
|
||||||
```text
|
|
||||||
编号
|
|
||||||
标题
|
|
||||||
状态
|
|
||||||
优先级
|
|
||||||
关联系统
|
|
||||||
影响范围
|
|
||||||
创建时间
|
|
||||||
操作
|
|
||||||
```
|
|
||||||
|
|
||||||
Required actions:
|
|
||||||
|
|
||||||
```text
|
|
||||||
新建工单
|
|
||||||
查看详情
|
|
||||||
重置筛选
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Redesign ticket creation page**
|
|
||||||
|
|
||||||
Use Chinese sections:
|
|
||||||
|
|
||||||
```text
|
|
||||||
创建工单
|
|
||||||
问题描述
|
|
||||||
处理属性
|
|
||||||
影响范围
|
|
||||||
AI 建单辅助
|
|
||||||
```
|
|
||||||
|
|
||||||
Use Chinese labels:
|
|
||||||
|
|
||||||
```text
|
|
||||||
工单标题
|
|
||||||
问题描述
|
|
||||||
优先级
|
|
||||||
关联系统
|
|
||||||
影响范围
|
|
||||||
运行环境
|
|
||||||
提交工单
|
|
||||||
```
|
|
||||||
|
|
||||||
The AI panel must clearly say:
|
|
||||||
|
|
||||||
```text
|
|
||||||
后续阶段将接入建单 Agent，用于补全字段、追问缺失信息和推荐相似问题。
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 3: Redesign ticket detail as an operations workspace**
|
|
||||||
|
|
||||||
Use `AppDetailLayout` with:
|
|
||||||
|
|
||||||
```text
|
|
||||||
Main column: 工单概览, 问题描述, 处理动态, 评论协作
|
|
||||||
Side column: 关键字段, 关联解决方案, AI 支持分析
|
|
||||||
```
|
|
||||||
|
|
||||||
Status transition buttons must show Chinese labels instead of raw enum values.
|
|
||||||
|
|
||||||
- [ ] **Step 4: Localize ticket timeline and comments**
|
|
||||||
|
|
||||||
Replace touched English labels with Chinese:
|
|
||||||
|
|
||||||
```text
|
|
||||||
状态流转
|
|
||||||
评论协作
|
|
||||||
暂无评论
|
|
||||||
发表回复
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 5: Run frontend typecheck**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npm run typecheck
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: exit code `0`.
|
|
||||||
|
|
||||||
- [ ] **Step 6: Commit**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add frontend/src/features/tickets
|
|
||||||
git commit -m "feat: redesign ticket workbench ui"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Task 5: Redesign Solution Pages and Final Verification
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `frontend/src/features/solutions/SolutionListPage.tsx`
|
|
||||||
- Modify: `frontend/src/features/solutions/SolutionLinkPanel.tsx`
|
|
||||||
- Modify: `docs/frontend/design-system.md`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Redesign solution list**
|
|
||||||
|
|
||||||
Use Chinese copy and table/list structure:
|
|
||||||
|
|
||||||
```text
|
|
||||||
解决方案库
|
|
||||||
沉淀可复用的问题特征、排查步骤和处理方案。
|
|
||||||
搜索解决方案
|
|
||||||
状态
|
|
||||||
引用次数
|
|
||||||
查看关联
|
|
||||||
```
|
|
||||||
|
|
||||||
Use badges for published/draft status:
|
|
||||||
|
|
||||||
```text
|
|
||||||
published=已发布
|
|
||||||
draft=草稿
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Localize solution link panel**
|
|
||||||
|
|
||||||
Use Chinese labels:
|
|
||||||
|
|
||||||
```text
|
|
||||||
关联解决方案
|
|
||||||
推荐方案
|
|
||||||
已采纳
|
|
||||||
暂无关联方案
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 3: Update design system docs**
|
|
||||||
|
|
||||||
Update `docs/frontend/design-system.md` so it documents:
|
|
||||||
|
|
||||||
```text
|
|
||||||
shadcn/ui primitives
|
|
||||||
App component layer
|
|
||||||
Chinese-first frontend copy rule
|
|
||||||
Business pages must use AppDataTable/AppFilterBar/AppDetailLayout for repeated patterns
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 4: Run final frontend verification**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npm run typecheck
|
|
||||||
npm run build
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: both commands exit `0`.
|
|
||||||
|
|
||||||
- [ ] **Step 5: Run shadcn info**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npx shadcn@latest info
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected:
|
|
||||||
|
|
||||||
```text
|
|
||||||
components.json exists
|
|
||||||
components list is non-empty
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 6: Commit**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add frontend/src/features/solutions docs/frontend/design-system.md
|
|
||||||
git commit -m "feat: polish solution ui and design docs"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Final Review Checklist
|
|
||||||
|
|
||||||
- [ ] `frontend/components.json` exists.
|
|
||||||
- [ ] App sidebar/topbar text is Chinese.
|
|
||||||
- [ ] Workbench default route exists at `#/`.
|
|
||||||
- [ ] Ticket list is a table-like enterprise view, not a simple card/list dump.
|
|
||||||
- [ ] Ticket create page uses Chinese labels and includes a future AI helper panel.
|
|
||||||
- [ ] Ticket detail uses a main/side workbench layout.
|
|
||||||
- [ ] Solution list and solution link panel are Chinese.
|
|
||||||
- [ ] Touched frontend text is Chinese.
|
|
||||||
- [ ] `cd frontend && npm run typecheck` passes.
|
|
||||||
- [ ] `cd frontend && npm run build` passes.
|
|
||||||
@@ -1,628 +0,0 @@
|
|||||||
# Stage 1.6 Enterprise Governance Implementation Plan
|
|
||||||
|
|
||||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
||||||
|
|
||||||
**Goal:** Add a usable enterprise governance baseline with login, current user, users, user groups, roles, menus, API permission enforcement, permission-driven frontend navigation, and deployment bootstrap.
|
|
||||||
|
|
||||||
**Architecture:** Backend keeps Django's built-in `User`, `Group`, and `Permission` as the core auth model, adds `UserGroup` and `MenuItem` for product governance, exposes session-authenticated Django Ninja APIs, and enforces permissions in ticket/solution/audit/governance routers. Frontend wraps the Vite SPA in an auth provider, renders a shadcn-based Chinese login page for anonymous users, consumes backend menu data in `AppSidebar`, and adds shadcn-based system governance pages.
|
|
||||||
|
|
||||||
**Tech Stack:** Python 3.12, Django, Django Ninja, pytest, ruff, React, Vite, TypeScript, Tailwind CSS v3, shadcn/ui, Radix UI, npm.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Source Spec
|
|
||||||
|
|
||||||
- `docs/superpowers/specs/2026-07-01-stage-1-6-enterprise-governance-design.md`
|
|
||||||
|
|
||||||
## File Structure
|
|
||||||
|
|
||||||
Backend:
|
|
||||||
|
|
||||||
- Modify: `backend/config/settings/base.py`
|
|
||||||
- Modify: `backend/config/urls.py`
|
|
||||||
- Modify: `backend/apps/accounts/models.py`
|
|
||||||
- Modify: `backend/apps/accounts/permissions.py`
|
|
||||||
- Modify: `backend/apps/accounts/schemas.py`
|
|
||||||
- Modify: `backend/apps/accounts/api.py`
|
|
||||||
- Create: `backend/apps/accounts/auth.py`
|
|
||||||
- Create: `backend/apps/accounts/menus.py`
|
|
||||||
- Create: `backend/apps/accounts/bootstrap.py`
|
|
||||||
- Create: `backend/apps/accounts/management/commands/bootstrap_governance.py`
|
|
||||||
- Create: `backend/apps/accounts/migrations/0001_initial.py`
|
|
||||||
- Modify: `backend/apps/tickets/api.py`
|
|
||||||
- Modify: `backend/apps/solutions/api.py`
|
|
||||||
- Modify: `backend/apps/audit/api.py`
|
|
||||||
- Create: `backend/apps/accounts/tests/test_auth_api.py`
|
|
||||||
- Create: `backend/apps/accounts/tests/test_governance_api.py`
|
|
||||||
- Create: `backend/apps/accounts/tests/test_permission_enforcement.py`
|
|
||||||
- Create: `backend/apps/accounts/tests/test_bootstrap_governance.py`
|
|
||||||
- Modify: existing ticket/solution/audit tests to authenticate where protected endpoints are exercised.
|
|
||||||
|
|
||||||
Frontend:
|
|
||||||
|
|
||||||
- Modify: `frontend/src/lib/api.ts`
|
|
||||||
- Create: `frontend/src/features/auth/types.ts`
|
|
||||||
- Create: `frontend/src/features/auth/api.ts`
|
|
||||||
- Create: `frontend/src/features/auth/AuthProvider.tsx`
|
|
||||||
- Create: `frontend/src/features/auth/LoginPage.tsx`
|
|
||||||
- Modify: `frontend/src/app/App.tsx`
|
|
||||||
- Modify: `frontend/src/app/router.tsx`
|
|
||||||
- Modify: `frontend/src/app/layout/AppShell.tsx`
|
|
||||||
- Modify: `frontend/src/components/app/AppSidebar.tsx`
|
|
||||||
- Modify: `frontend/src/components/app/AppTopbar.tsx`
|
|
||||||
- Create: `frontend/src/features/system/api.ts`
|
|
||||||
- Create: `frontend/src/features/system/types.ts`
|
|
||||||
- Create: `frontend/src/features/system/SystemUsersPage.tsx`
|
|
||||||
- Create: `frontend/src/features/system/SystemUserGroupsPage.tsx`
|
|
||||||
- Create: `frontend/src/features/system/SystemRolesPage.tsx`
|
|
||||||
- Create: `frontend/src/features/system/SystemMenusPage.tsx`
|
|
||||||
- Create: `frontend/src/features/audit/AuditLogPage.tsx`
|
|
||||||
- Add shadcn components if missing: `checkbox`, `switch`, `alert`, `pagination`.
|
|
||||||
|
|
||||||
Deployment/docs:
|
|
||||||
|
|
||||||
- Modify: `.env.example`
|
|
||||||
- Create: `infra/backend-entrypoint.sh`
|
|
||||||
- Modify: `infra/backend.Dockerfile`
|
|
||||||
- Modify: `infra/docker-compose.yml`
|
|
||||||
- Modify: `docs/development/local-setup.md`
|
|
||||||
|
|
||||||
## Task 1: Backend Governance Models And Bootstrap
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `backend/apps/accounts/models.py`
|
|
||||||
- Modify: `backend/apps/accounts/permissions.py`
|
|
||||||
- Create: `backend/apps/accounts/menus.py`
|
|
||||||
- Create: `backend/apps/accounts/bootstrap.py`
|
|
||||||
- Create: `backend/apps/accounts/management/commands/bootstrap_governance.py`
|
|
||||||
- Create: `backend/apps/accounts/tests/test_bootstrap_governance.py`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Write failing bootstrap test**
|
|
||||||
|
|
||||||
Create `backend/apps/accounts/tests/test_bootstrap_governance.py` with tests proving:
|
|
||||||
|
|
||||||
```python
|
|
||||||
from django.contrib.auth import get_user_model
|
|
||||||
from django.contrib.auth.models import Group, Permission
|
|
||||||
from django.core.management import call_command
|
|
||||||
|
|
||||||
from apps.accounts.models import MenuItem, UserGroup
|
|
||||||
|
|
||||||
|
|
||||||
def test_bootstrap_governance_seeds_admin_roles_groups_permissions_and_menus(db, settings):
|
|
||||||
settings.DJANGO_SUPERUSER_USERNAME = "admin"
|
|
||||||
settings.DJANGO_SUPERUSER_PASSWORD = "admin12345"
|
|
||||||
settings.DJANGO_SUPERUSER_EMAIL = "admin@example.com"
|
|
||||||
|
|
||||||
call_command("bootstrap_governance")
|
|
||||||
call_command("bootstrap_governance")
|
|
||||||
|
|
||||||
user = get_user_model().objects.get(username="admin")
|
|
||||||
assert user.is_superuser is True
|
|
||||||
assert user.check_password("admin12345")
|
|
||||||
assert Group.objects.filter(name="系统管理员").exists()
|
|
||||||
assert Permission.objects.filter(codename="system.user.manage").exists()
|
|
||||||
assert UserGroup.objects.filter(code="default").exists()
|
|
||||||
assert MenuItem.objects.filter(code="system.users", title="用户管理").exists()
|
|
||||||
assert MenuItem.objects.filter(code="system.roles", permission_code="system.role.view").exists()
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Run the test to verify RED**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd backend
|
|
||||||
python -m pytest apps/accounts/tests/test_bootstrap_governance.py -v
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: fails because `MenuItem`, `UserGroup`, and `bootstrap_governance` do not exist.
|
|
||||||
|
|
||||||
- [ ] **Step 3: Implement models, catalog, menus, bootstrap command**
|
|
||||||
|
|
||||||
Implement:
|
|
||||||
|
|
||||||
- `UserGroup` with `name`, `code`, `description`, `users`, `is_active`, timestamps.
|
|
||||||
- `MenuItem` with `code`, `title`, `path`, `icon`, `parent`, `sort_order`, `permission_code`, `is_visible`, `is_enabled`, timestamps.
|
|
||||||
- Chinese permission names and governance permission codes in `permissions.py`.
|
|
||||||
- Default role names in Chinese.
|
|
||||||
- Default menu catalog in `menus.py`.
|
|
||||||
- `bootstrap_governance()` service function and `bootstrap_governance` management command.
|
|
||||||
|
|
||||||
- [ ] **Step 4: Make migrations and verify GREEN**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd backend
|
|
||||||
python manage.py makemigrations accounts
|
|
||||||
python -m pytest apps/accounts/tests/test_bootstrap_governance.py -v
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: test passes.
|
|
||||||
|
|
||||||
- [ ] **Step 5: Commit**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add backend/apps/accounts
|
|
||||||
git commit -m "feat: add governance bootstrap models"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Task 2: Backend Auth And Current User APIs
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `backend/config/settings/base.py`
|
|
||||||
- Modify: `backend/config/urls.py`
|
|
||||||
- Create: `backend/apps/accounts/auth.py`
|
|
||||||
- Modify: `backend/apps/accounts/schemas.py`
|
|
||||||
- Modify: `backend/apps/accounts/api.py`
|
|
||||||
- Create: `backend/apps/accounts/tests/test_auth_api.py`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Write failing auth API tests**
|
|
||||||
|
|
||||||
Create `backend/apps/accounts/tests/test_auth_api.py` with tests for:
|
|
||||||
|
|
||||||
```python
|
|
||||||
from django.contrib.auth import get_user_model
|
|
||||||
from django.contrib.auth.models import Group
|
|
||||||
from django.core.management import call_command
|
|
||||||
|
|
||||||
|
|
||||||
def test_login_me_and_logout_flow(client, db):
|
|
||||||
call_command("bootstrap_governance")
|
|
||||||
|
|
||||||
login = client.post(
|
|
||||||
"/api/accounts/auth/login",
|
|
||||||
data={"username": "admin", "password": "admin12345"},
|
|
||||||
content_type="application/json",
|
|
||||||
)
|
|
||||||
assert login.status_code == 200
|
|
||||||
assert login.json()["username"] == "admin"
|
|
||||||
|
|
||||||
me = client.get("/api/accounts/auth/me")
|
|
||||||
assert me.status_code == 200
|
|
||||||
payload = me.json()
|
|
||||||
assert payload["username"] == "admin"
|
|
||||||
assert "system.user.manage" in payload["permissions"]
|
|
||||||
assert any(menu["code"] == "system" for menu in payload["menus"])
|
|
||||||
|
|
||||||
logout = client.post("/api/accounts/auth/logout")
|
|
||||||
assert logout.status_code == 200
|
|
||||||
assert client.get("/api/accounts/auth/me").status_code == 401
|
|
||||||
|
|
||||||
|
|
||||||
def test_login_rejects_invalid_password(client, db):
|
|
||||||
get_user_model().objects.create_user(username="u", password="right")
|
|
||||||
|
|
||||||
response = client.post(
|
|
||||||
"/api/accounts/auth/login",
|
|
||||||
data={"username": "u", "password": "wrong"},
|
|
||||||
content_type="application/json",
|
|
||||||
)
|
|
||||||
|
|
||||||
assert response.status_code == 401
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Run tests to verify RED**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd backend
|
|
||||||
python -m pytest apps/accounts/tests/test_auth_api.py -v
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: fails because auth endpoints do not exist.
|
|
||||||
|
|
||||||
- [ ] **Step 3: Implement session auth endpoints**
|
|
||||||
|
|
||||||
Implement:
|
|
||||||
|
|
||||||
- `GET /api/accounts/auth/csrf`
|
|
||||||
- `POST /api/accounts/auth/login`
|
|
||||||
- `POST /api/accounts/auth/logout`
|
|
||||||
- `GET /api/accounts/auth/me`
|
|
||||||
- `CORS_ALLOW_CREDENTIALS = True`
|
|
||||||
- `CSRF_TRUSTED_ORIGINS` env parsing
|
|
||||||
|
|
||||||
- [ ] **Step 4: Verify GREEN**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd backend
|
|
||||||
python -m pytest apps/accounts/tests/test_auth_api.py -v
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: tests pass.
|
|
||||||
|
|
||||||
- [ ] **Step 5: Commit**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add backend/config backend/apps/accounts
|
|
||||||
git commit -m "feat: add session auth api"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Task 3: Backend Governance CRUD APIs
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `backend/apps/accounts/schemas.py`
|
|
||||||
- Modify: `backend/apps/accounts/api.py`
|
|
||||||
- Create: `backend/apps/accounts/tests/test_governance_api.py`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Write failing governance API tests**
|
|
||||||
|
|
||||||
Tests must cover:
|
|
||||||
|
|
||||||
- Admin lists users.
|
|
||||||
- Admin creates a user.
|
|
||||||
- Admin creates a user group and assigns members.
|
|
||||||
- Admin creates a role and assigns permissions.
|
|
||||||
- Admin lists menus and updates one menu permission.
|
|
||||||
- Anonymous calls to governance endpoints return 401.
|
|
||||||
|
|
||||||
- [ ] **Step 2: Run tests to verify RED**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd backend
|
|
||||||
python -m pytest apps/accounts/tests/test_governance_api.py -v
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: fails because CRUD endpoints do not exist.
|
|
||||||
|
|
||||||
- [ ] **Step 3: Implement schemas and APIs**
|
|
||||||
|
|
||||||
Implement `/api/accounts` endpoints:
|
|
||||||
|
|
||||||
- `/users`
|
|
||||||
- `/users/{id}`
|
|
||||||
- `/users/{id}/reset-password`
|
|
||||||
- `/users/{id}/roles`
|
|
||||||
- `/users/{id}/user-groups`
|
|
||||||
- `/user-groups`
|
|
||||||
- `/user-groups/{id}`
|
|
||||||
- `/user-groups/{id}/members`
|
|
||||||
- `/roles`
|
|
||||||
- `/roles/{id}`
|
|
||||||
- `/roles/{id}/permissions`
|
|
||||||
- `/permissions`
|
|
||||||
- `/menus`
|
|
||||||
- `/menus/{id}`
|
|
||||||
- `/menus/reorder`
|
|
||||||
|
|
||||||
- [ ] **Step 4: Verify GREEN**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd backend
|
|
||||||
python -m pytest apps/accounts/tests/test_governance_api.py -v
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: tests pass.
|
|
||||||
|
|
||||||
- [ ] **Step 5: Commit**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add backend/apps/accounts
|
|
||||||
git commit -m "feat: add governance management api"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Task 4: Backend Permission Enforcement
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Create: `backend/apps/accounts/auth.py` if not already created.
|
|
||||||
- Modify: `backend/apps/tickets/api.py`
|
|
||||||
- Modify: `backend/apps/solutions/api.py`
|
|
||||||
- Modify: `backend/apps/audit/api.py`
|
|
||||||
- Modify: existing ticket/solution/audit tests.
|
|
||||||
- Create: `backend/apps/accounts/tests/test_permission_enforcement.py`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Write failing permission enforcement tests**
|
|
||||||
|
|
||||||
Tests must prove:
|
|
||||||
|
|
||||||
- Anonymous ticket list is denied.
|
|
||||||
- User with `ticket.view` can list tickets.
|
|
||||||
- User without `ticket.create` cannot create tickets.
|
|
||||||
- User with `solution.view` can list solutions.
|
|
||||||
- User without `system.audit.view` cannot list audit logs.
|
|
||||||
|
|
||||||
- [ ] **Step 2: Run tests to verify RED**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd backend
|
|
||||||
python -m pytest apps/accounts/tests/test_permission_enforcement.py -v
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: fails because current APIs are public.
|
|
||||||
|
|
||||||
- [ ] **Step 3: Implement helpers and protect APIs**
|
|
||||||
|
|
||||||
Implement helpers:
|
|
||||||
|
|
||||||
```python
|
|
||||||
require_login(request)
|
|
||||||
require_permission(request, "ticket.view")
|
|
||||||
```
|
|
||||||
|
|
||||||
Update routers:
|
|
||||||
|
|
||||||
- `/api/system/health` remains public.
|
|
||||||
- tickets require ticket permissions.
|
|
||||||
- solutions require solution permissions.
|
|
||||||
- audit requires `system.audit.view`.
|
|
||||||
- governance endpoints use governance permissions.
|
|
||||||
|
|
||||||
- [ ] **Step 4: Update existing tests to authenticate**
|
|
||||||
|
|
||||||
Existing ticket/solution/audit API tests should create a superuser or assign required permissions before calling protected endpoints.
|
|
||||||
|
|
||||||
- [ ] **Step 5: Verify backend API tests**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd backend
|
|
||||||
python -m pytest apps/accounts/tests apps/tickets/tests apps/solutions/tests apps/audit/tests -v
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: tests pass.
|
|
||||||
|
|
||||||
- [ ] **Step 6: Commit**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add backend/apps/accounts backend/apps/tickets backend/apps/solutions backend/apps/audit
|
|
||||||
git commit -m "feat: enforce api permissions"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Task 5: Frontend Auth Shell And Permission Menus
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `frontend/src/lib/api.ts`
|
|
||||||
- Create: `frontend/src/features/auth/types.ts`
|
|
||||||
- Create: `frontend/src/features/auth/api.ts`
|
|
||||||
- Create: `frontend/src/features/auth/AuthProvider.tsx`
|
|
||||||
- Create: `frontend/src/features/auth/LoginPage.tsx`
|
|
||||||
- Modify: `frontend/src/app/App.tsx`
|
|
||||||
- Modify: `frontend/src/app/layout/AppShell.tsx`
|
|
||||||
- Modify: `frontend/src/components/app/AppSidebar.tsx`
|
|
||||||
- Modify: `frontend/src/components/app/AppTopbar.tsx`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Add missing shadcn components**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npx shadcn@latest add alert checkbox switch pagination --yes
|
|
||||||
```
|
|
||||||
|
|
||||||
Then review generated files for Tailwind v3 compatibility.
|
|
||||||
|
|
||||||
- [ ] **Step 2: Implement auth API client and provider**
|
|
||||||
|
|
||||||
Implement:
|
|
||||||
|
|
||||||
- CSRF fetch.
|
|
||||||
- login/logout/me calls.
|
|
||||||
- `AuthProvider`.
|
|
||||||
- `useAuth`.
|
|
||||||
- `apiRequest` sends `credentials: "include"` and CSRF token on unsafe methods.
|
|
||||||
|
|
||||||
- [ ] **Step 3: Implement Chinese login page**
|
|
||||||
|
|
||||||
`LoginPage` uses shadcn `Card`, `Input`, `Label`, `Button`, and `Alert`.
|
|
||||||
|
|
||||||
Visible text must include:
|
|
||||||
|
|
||||||
```text
|
|
||||||
AI 工单平台
|
|
||||||
企业技术支持工作台
|
|
||||||
账号
|
|
||||||
密码
|
|
||||||
登录
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 4: Gate app by auth state**
|
|
||||||
|
|
||||||
Anonymous users see `LoginPage`. Authenticated users see `AppShell` and `Router`.
|
|
||||||
|
|
||||||
- [ ] **Step 5: Make sidebar backend-driven**
|
|
||||||
|
|
||||||
`AppSidebar` receives menu data from auth context. Keep local icon mapping with lucide icons.
|
|
||||||
|
|
||||||
- [ ] **Step 6: Run frontend verification**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npm run typecheck
|
|
||||||
npm run build
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: both pass.
|
|
||||||
|
|
||||||
- [ ] **Step 7: Commit**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add frontend/src frontend/components.json frontend/package.json frontend/package-lock.json
|
|
||||||
git commit -m "feat: add frontend auth shell"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Task 6: Frontend System Governance Pages
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Create: `frontend/src/features/system/types.ts`
|
|
||||||
- Create: `frontend/src/features/system/api.ts`
|
|
||||||
- Create: `frontend/src/features/system/SystemUsersPage.tsx`
|
|
||||||
- Create: `frontend/src/features/system/SystemUserGroupsPage.tsx`
|
|
||||||
- Create: `frontend/src/features/system/SystemRolesPage.tsx`
|
|
||||||
- Create: `frontend/src/features/system/SystemMenusPage.tsx`
|
|
||||||
- Create: `frontend/src/features/audit/AuditLogPage.tsx`
|
|
||||||
- Modify: `frontend/src/app/router.tsx`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Add system API client**
|
|
||||||
|
|
||||||
Create typed API functions for users, user groups, roles, permissions, menus, and audit logs.
|
|
||||||
|
|
||||||
- [ ] **Step 2: Add users page**
|
|
||||||
|
|
||||||
`#/system/users` shows table columns:
|
|
||||||
|
|
||||||
```text
|
|
||||||
用户名
|
|
||||||
显示名称
|
|
||||||
邮箱
|
|
||||||
状态
|
|
||||||
角色
|
|
||||||
用户组
|
|
||||||
操作
|
|
||||||
```
|
|
||||||
|
|
||||||
Use Dialog or Sheet for create/edit.
|
|
||||||
|
|
||||||
- [ ] **Step 3: Add user groups page**
|
|
||||||
|
|
||||||
`#/system/user-groups` shows Chinese table and create/edit dialog.
|
|
||||||
|
|
||||||
- [ ] **Step 4: Add roles page**
|
|
||||||
|
|
||||||
`#/system/roles` shows role list and permission matrix grouped by module.
|
|
||||||
|
|
||||||
- [ ] **Step 5: Add menus page**
|
|
||||||
|
|
||||||
`#/system/menus` shows menu rows, required permission, visibility/enabled status, and edit dialog.
|
|
||||||
|
|
||||||
- [ ] **Step 6: Add audit page**
|
|
||||||
|
|
||||||
`#/audit` shows existing operation logs in a Chinese table.
|
|
||||||
|
|
||||||
- [ ] **Step 7: Run frontend verification**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npm run typecheck
|
|
||||||
npm run build
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: both pass.
|
|
||||||
|
|
||||||
- [ ] **Step 8: Commit**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add frontend/src/features/system frontend/src/features/audit frontend/src/app/router.tsx
|
|
||||||
git commit -m "feat: add system governance pages"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Task 7: Deployment Bootstrap And Final Verification
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `.env.example`
|
|
||||||
- Create: `infra/backend-entrypoint.sh`
|
|
||||||
- Modify: `infra/backend.Dockerfile`
|
|
||||||
- Modify: `infra/docker-compose.yml`
|
|
||||||
- Modify: `docs/development/local-setup.md`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Add environment defaults**
|
|
||||||
|
|
||||||
Add admin bootstrap env vars to `.env.example`:
|
|
||||||
|
|
||||||
```dotenv
|
|
||||||
DJANGO_SUPERUSER_USERNAME=admin
|
|
||||||
DJANGO_SUPERUSER_PASSWORD=admin12345
|
|
||||||
DJANGO_SUPERUSER_EMAIL=admin@example.com
|
|
||||||
CSRF_TRUSTED_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Add backend entrypoint**
|
|
||||||
|
|
||||||
Create `infra/backend-entrypoint.sh`:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
#!/bin/sh
|
|
||||||
set -e
|
|
||||||
|
|
||||||
python manage.py migrate
|
|
||||||
python manage.py bootstrap_governance
|
|
||||||
exec "$@"
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 3: Wire backend Dockerfile and compose**
|
|
||||||
|
|
||||||
Backend service uses the entrypoint before running `runserver`. Worker can still start Celery after migrations are handled by backend.
|
|
||||||
|
|
||||||
- [ ] **Step 4: Update setup docs**
|
|
||||||
|
|
||||||
Document:
|
|
||||||
|
|
||||||
- fresh Docker startup
|
|
||||||
- default login account
|
|
||||||
- production warning to override password
|
|
||||||
|
|
||||||
- [ ] **Step 5: Run full verification**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd backend
|
|
||||||
python -m pytest -v
|
|
||||||
python -m ruff check .
|
|
||||||
|
|
||||||
cd ../frontend
|
|
||||||
npm run typecheck
|
|
||||||
npm run build
|
|
||||||
npx shadcn@latest info
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: all commands pass.
|
|
||||||
|
|
||||||
- [ ] **Step 6: Verify compose config**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd infra
|
|
||||||
docker compose --env-file ../.env.example config
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: config prints without errors. On this Windows host, use Docker Desktop's full docker executable path if `docker` is unavailable in shell PATH.
|
|
||||||
|
|
||||||
- [ ] **Step 7: Browser smoke test**
|
|
||||||
|
|
||||||
Start backend and frontend locally if feasible, then verify:
|
|
||||||
|
|
||||||
- anonymous user sees login page
|
|
||||||
- admin can log in
|
|
||||||
- sidebar shows system governance menus
|
|
||||||
- `#/system/users`, `#/system/roles`, `#/system/menus`, `#/audit` render Chinese UI
|
|
||||||
- logout returns to login
|
|
||||||
|
|
||||||
- [ ] **Step 8: Commit**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add .env.example infra docs/development
|
|
||||||
git commit -m "feat: add governance deployment bootstrap"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Final Review Checklist
|
|
||||||
|
|
||||||
- [ ] `bootstrap_governance` is idempotent.
|
|
||||||
- [ ] Login/logout/me APIs work.
|
|
||||||
- [ ] Frontend anonymous state shows login only.
|
|
||||||
- [ ] Sidebar menus are backend-driven.
|
|
||||||
- [ ] User/user-group/role/menu pages use shadcn/App components.
|
|
||||||
- [ ] Ticket/solution/audit/governance APIs enforce permissions.
|
|
||||||
- [ ] Docker startup can migrate and seed governance.
|
|
||||||
- [ ] Backend tests pass.
|
|
||||||
- [ ] Backend ruff passes.
|
|
||||||
- [ ] Frontend typecheck passes.
|
|
||||||
- [ ] Frontend build passes.
|
|
||||||
- [ ] shadcn info still reports Vite/Tailwind v3 and installed components.
|
|
||||||
@@ -1,631 +0,0 @@
|
|||||||
# Stage 1.7 Ticket Experience Visual Redesign Implementation Plan
|
|
||||||
|
|
||||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
||||||
|
|
||||||
**Goal:** Redesign ticket list, detail, and create pages into a polished Chinese enterprise support experience using shadcn/ui, with minimal backend support for pagination, filters, display users, and transition remarks.
|
|
||||||
|
|
||||||
**Architecture:** Backend keeps the existing Django Ninja ticket router and adds a paginated response shape plus richer filters and display user serialization. Frontend keeps the Vite SPA and current app shell, then decomposes ticket pages into small shadcn-composed components for metrics, filters, metadata, and transition dialogs.
|
|
||||||
|
|
||||||
**Tech Stack:** Python 3.12, Django, Django Ninja, pytest, ruff, React, Vite, TypeScript, Tailwind CSS v3, shadcn/ui, Radix UI, npm.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Source Spec
|
|
||||||
|
|
||||||
- `docs/superpowers/specs/2026-07-01-stage-1-7-ticket-experience-visual-redesign-design.md`
|
|
||||||
|
|
||||||
## File Structure
|
|
||||||
|
|
||||||
Backend:
|
|
||||||
|
|
||||||
- Modify: `backend/apps/tickets/schemas.py`
|
|
||||||
- Modify: `backend/apps/tickets/api.py`
|
|
||||||
- Modify: `backend/apps/tickets/services.py`
|
|
||||||
- Modify: `backend/apps/tickets/tests/test_ticket_api.py`
|
|
||||||
|
|
||||||
Frontend:
|
|
||||||
|
|
||||||
- Modify: `frontend/src/features/tickets/types.ts`
|
|
||||||
- Modify: `frontend/src/features/tickets/api.ts`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketListPage.tsx`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketDetailPage.tsx`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketCreatePage.tsx`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketComments.tsx`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketStatusTimeline.tsx`
|
|
||||||
- Create: `frontend/src/features/tickets/TicketMetricCards.tsx`
|
|
||||||
- Create: `frontend/src/features/tickets/TicketFilterBar.tsx`
|
|
||||||
- Create: `frontend/src/features/tickets/TicketTransitionDialog.tsx`
|
|
||||||
- Create: `frontend/src/features/tickets/TicketMetaPanel.tsx`
|
|
||||||
|
|
||||||
## Implementation Progress
|
|
||||||
|
|
||||||
As of 2026-07-03, Stage 1.7 has moved beyond the first visual redesign into a stronger ticket workflow baseline:
|
|
||||||
|
|
||||||
- Ticket categories are standardized as `业务问题`, `技术问题`, `数据问题`, and `操作问题`.
|
|
||||||
- Category-driven status policies shorten simple business/operation tickets while preserving the full technical workflow.
|
|
||||||
- Ticket creation captures business-facing context fields including problem performance, problem object, submitter, submitter organization, and environment.
|
|
||||||
- Solution adoption can close a ticket, write the resolution summary, update usage count, and record timeline events.
|
|
||||||
- Recommended linked solutions remain non-closing references, but resolve/close dialogs prefill the resolution from linked solutions.
|
|
||||||
- Ticket detail side metadata was reduced to avoid repeating the overview card.
|
|
||||||
|
|
||||||
## Task 1: Backend Ticket List Support
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `backend/apps/tickets/schemas.py`
|
|
||||||
- Modify: `backend/apps/tickets/api.py`
|
|
||||||
- Modify: `backend/apps/tickets/services.py`
|
|
||||||
- Modify: `backend/apps/tickets/tests/test_ticket_api.py`
|
|
||||||
|
|
||||||
- [x] **Step 1: Write failing pagination/filter/display tests**
|
|
||||||
|
|
||||||
Add these tests to `backend/apps/tickets/tests/test_ticket_api.py`:
|
|
||||||
|
|
||||||
```python
|
|
||||||
from django.contrib.auth import get_user_model
|
|
||||||
|
|
||||||
|
|
||||||
def test_list_tickets_returns_paginated_response_with_display_users(admin_client, db):
|
|
||||||
user_model = get_user_model()
|
|
||||||
requester = user_model.objects.create_user(username="requester", first_name="请求人")
|
|
||||||
assignee = user_model.objects.create_user(username="assignee", first_name="处理人")
|
|
||||||
Ticket.objects.create(
|
|
||||||
ticket_no="TK202607010100",
|
|
||||||
title="Payment failed",
|
|
||||||
description="A",
|
|
||||||
requester=requester,
|
|
||||||
assignee=assignee,
|
|
||||||
related_system="CRM",
|
|
||||||
)
|
|
||||||
|
|
||||||
response = admin_client.get("/api/tickets?page=1&page_size=20")
|
|
||||||
|
|
||||||
assert response.status_code == 200
|
|
||||||
payload = response.json()
|
|
||||||
assert payload["page"] == 1
|
|
||||||
assert payload["page_size"] == 20
|
|
||||||
assert payload["total"] == 1
|
|
||||||
assert payload["total_pages"] == 1
|
|
||||||
assert payload["items"][0]["requester"]["display_name"] == "请求人"
|
|
||||||
assert payload["items"][0]["assignee"]["display_name"] == "处理人"
|
|
||||||
|
|
||||||
|
|
||||||
def test_list_tickets_filters_by_priority_related_system_and_view(admin_client, db):
|
|
||||||
user_model = get_user_model()
|
|
||||||
current_user = user_model.objects.get(username="admin")
|
|
||||||
Ticket.objects.create(
|
|
||||||
ticket_no="TK202607010101",
|
|
||||||
title="Mine urgent CRM",
|
|
||||||
description="A",
|
|
||||||
priority="urgent",
|
|
||||||
related_system="CRM",
|
|
||||||
assignee=current_user,
|
|
||||||
created_by=current_user,
|
|
||||||
)
|
|
||||||
Ticket.objects.create(
|
|
||||||
ticket_no="TK202607010102",
|
|
||||||
title="Other medium ERP",
|
|
||||||
description="B",
|
|
||||||
priority="medium",
|
|
||||||
related_system="ERP",
|
|
||||||
)
|
|
||||||
|
|
||||||
response = admin_client.get(
|
|
||||||
"/api/tickets?priority=urgent&related_system=CRM&view=assigned_to_me"
|
|
||||||
)
|
|
||||||
|
|
||||||
assert response.status_code == 200
|
|
||||||
payload = response.json()
|
|
||||||
assert payload["total"] == 1
|
|
||||||
assert payload["items"][0]["ticket_no"] == "TK202607010101"
|
|
||||||
|
|
||||||
|
|
||||||
def test_transition_ticket_requires_non_empty_remark(admin_client, db):
|
|
||||||
ticket = Ticket.objects.create(
|
|
||||||
ticket_no="TK202607010103",
|
|
||||||
title="A",
|
|
||||||
description="A",
|
|
||||||
status="pending",
|
|
||||||
)
|
|
||||||
|
|
||||||
response = admin_client.post(
|
|
||||||
f"/api/tickets/{ticket.id}/status",
|
|
||||||
data={"status": "in_progress", "remark": ""},
|
|
||||||
content_type="application/json",
|
|
||||||
)
|
|
||||||
|
|
||||||
assert response.status_code == 400
|
|
||||||
```
|
|
||||||
|
|
||||||
- [x] **Step 2: Run tests to verify RED**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd backend
|
|
||||||
python -m pytest apps/tickets/tests/test_ticket_api.py -v
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: fails because list response is currently a list, display users are missing, advanced filters are missing, and empty transition remark is allowed.
|
|
||||||
|
|
||||||
- [x] **Step 3: Implement schemas and serialization**
|
|
||||||
|
|
||||||
Add schemas to `backend/apps/tickets/schemas.py`:
|
|
||||||
|
|
||||||
```python
|
|
||||||
class TicketUserOut(Schema):
|
|
||||||
id: int
|
|
||||||
username: str
|
|
||||||
display_name: str
|
|
||||||
|
|
||||||
|
|
||||||
class TicketListOut(Schema):
|
|
||||||
items: list[TicketOut]
|
|
||||||
page: int
|
|
||||||
page_size: int
|
|
||||||
total: int
|
|
||||||
total_pages: int
|
|
||||||
```
|
|
||||||
|
|
||||||
Extend `TicketOut` with:
|
|
||||||
|
|
||||||
```python
|
|
||||||
requester_id: int | None
|
|
||||||
requester: TicketUserOut | None = None
|
|
||||||
assignee: TicketUserOut | None = None
|
|
||||||
```
|
|
||||||
|
|
||||||
Implement serializer helpers in `backend/apps/tickets/api.py`:
|
|
||||||
|
|
||||||
```python
|
|
||||||
def serialize_ticket_user(user):
|
|
||||||
if user is None:
|
|
||||||
return None
|
|
||||||
return {
|
|
||||||
"id": user.id,
|
|
||||||
"username": user.username,
|
|
||||||
"display_name": user.get_full_name() or user.username,
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
def serialize_ticket(ticket: Ticket) -> dict:
|
|
||||||
return {
|
|
||||||
"id": ticket.id,
|
|
||||||
"ticket_no": ticket.ticket_no,
|
|
||||||
"title": ticket.title,
|
|
||||||
"description": ticket.description,
|
|
||||||
"status": ticket.status,
|
|
||||||
"priority": ticket.priority,
|
|
||||||
"impact_scope": ticket.impact_scope,
|
|
||||||
"environment": ticket.environment,
|
|
||||||
"related_system": ticket.related_system,
|
|
||||||
"requester_id": ticket.requester_id,
|
|
||||||
"assignee_id": ticket.assignee_id,
|
|
||||||
"requester": serialize_ticket_user(ticket.requester),
|
|
||||||
"assignee": serialize_ticket_user(ticket.assignee),
|
|
||||||
"created_at": ticket.created_at,
|
|
||||||
"updated_at": ticket.updated_at,
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- [x] **Step 4: Implement paginated list and filters**
|
|
||||||
|
|
||||||
Change `list_tickets` to return `TicketListOut` and accept:
|
|
||||||
|
|
||||||
```python
|
|
||||||
page: int = 1
|
|
||||||
page_size: int = 20
|
|
||||||
status: str | None = None
|
|
||||||
priority: str | None = None
|
|
||||||
q: str | None = None
|
|
||||||
related_system: str | None = None
|
|
||||||
assignee_id: int | None = None
|
|
||||||
view: str = "all"
|
|
||||||
```
|
|
||||||
|
|
||||||
Filter rules:
|
|
||||||
|
|
||||||
- `status`: exact status.
|
|
||||||
- `priority`: exact priority.
|
|
||||||
- `q`: `ticket_no`, `title`, or `description` contains keyword.
|
|
||||||
- `related_system`: contains text.
|
|
||||||
- `assignee_id`: exact assignee.
|
|
||||||
- `view=assigned_to_me`: `assignee=request.user`.
|
|
||||||
- `view=created_by_me`: `created_by=request.user`.
|
|
||||||
- `view=high_priority`: `priority in ["high", "urgent"]`.
|
|
||||||
|
|
||||||
Clamp:
|
|
||||||
|
|
||||||
```python
|
|
||||||
page = max(page, 1)
|
|
||||||
page_size = min(max(page_size, 1), 100)
|
|
||||||
```
|
|
||||||
|
|
||||||
- [x] **Step 5: Require transition remarks**
|
|
||||||
|
|
||||||
In `update_ticket_status`, reject blank remarks:
|
|
||||||
|
|
||||||
```python
|
|
||||||
if not payload.remark.strip():
|
|
||||||
raise HttpError(400, "Transition remark is required")
|
|
||||||
```
|
|
||||||
|
|
||||||
Import `HttpError` from `ninja.errors`.
|
|
||||||
|
|
||||||
- [x] **Step 6: Update existing tests for new list shape**
|
|
||||||
|
|
||||||
Change existing list assertions in `test_list_tickets_filters_by_status`:
|
|
||||||
|
|
||||||
```python
|
|
||||||
payload = response.json()
|
|
||||||
assert payload["total"] == 1
|
|
||||||
assert payload["items"][0]["ticket_no"] == "TK202606300001"
|
|
||||||
```
|
|
||||||
|
|
||||||
- [x] **Step 7: Verify GREEN**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd backend
|
|
||||||
python -m pytest apps/tickets/tests/test_ticket_api.py apps/tickets/tests/test_ticket_export.py apps/accounts/tests/test_permission_enforcement.py -v
|
|
||||||
python -m ruff check .
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: all selected tests pass and ruff has no errors.
|
|
||||||
|
|
||||||
- [x] **Step 8: Commit**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add backend/apps/tickets
|
|
||||||
git commit -m "feat: add ticket list visual support api"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Task 2: Frontend Ticket API And List Redesign
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `frontend/src/features/tickets/types.ts`
|
|
||||||
- Modify: `frontend/src/features/tickets/api.ts`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketListPage.tsx`
|
|
||||||
- Create: `frontend/src/features/tickets/TicketMetricCards.tsx`
|
|
||||||
- Create: `frontend/src/features/tickets/TicketFilterBar.tsx`
|
|
||||||
|
|
||||||
- [x] **Step 1: Refresh shadcn docs**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npx shadcn@latest docs tabs table card badge select input pagination skeleton sonner
|
|
||||||
```
|
|
||||||
|
|
||||||
Use installed components first. Do not overwrite existing locally patched components.
|
|
||||||
|
|
||||||
- [x] **Step 2: Update ticket frontend types**
|
|
||||||
|
|
||||||
In `frontend/src/features/tickets/types.ts`, add:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
export type TicketUser = {
|
|
||||||
id: number
|
|
||||||
username: string
|
|
||||||
display_name: string
|
|
||||||
}
|
|
||||||
|
|
||||||
export type TicketListResponse = {
|
|
||||||
items: Ticket[]
|
|
||||||
page: number
|
|
||||||
page_size: number
|
|
||||||
total: number
|
|
||||||
total_pages: number
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Extend `Ticket`:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
requester_id: number | null
|
|
||||||
requester: TicketUser | null
|
|
||||||
assignee: TicketUser | null
|
|
||||||
```
|
|
||||||
|
|
||||||
Add list query type:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
export type TicketListParams = {
|
|
||||||
page?: number
|
|
||||||
page_size?: number
|
|
||||||
status?: string
|
|
||||||
priority?: string
|
|
||||||
q?: string
|
|
||||||
related_system?: string
|
|
||||||
assignee_id?: number
|
|
||||||
view?: 'all' | 'assigned_to_me' | 'created_by_me' | 'high_priority'
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- [x] **Step 3: Update ticket API**
|
|
||||||
|
|
||||||
In `frontend/src/features/tickets/api.ts`, update `listTickets` to return `TicketListResponse` and include all query fields:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
export function listTickets(params: TicketListParams = {}) {
|
|
||||||
const query = new URLSearchParams()
|
|
||||||
Object.entries(params).forEach(([key, value]) => {
|
|
||||||
if (value !== undefined && value !== null && value !== '') {
|
|
||||||
query.set(key, String(value))
|
|
||||||
}
|
|
||||||
})
|
|
||||||
const suffix = query.toString() ? `?${query}` : ''
|
|
||||||
return apiRequest<TicketListResponse>(`/tickets${suffix}`)
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- [x] **Step 4: Create TicketMetricCards**
|
|
||||||
|
|
||||||
Create `frontend/src/features/tickets/TicketMetricCards.tsx` with compact shadcn `Card` metrics for:
|
|
||||||
|
|
||||||
```text
|
|
||||||
待处理
|
|
||||||
处理中
|
|
||||||
待确认
|
|
||||||
高优先级
|
|
||||||
```
|
|
||||||
|
|
||||||
Props:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
type TicketMetricCardsProps = {
|
|
||||||
tickets: Ticket[]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- [x] **Step 5: Create TicketFilterBar**
|
|
||||||
|
|
||||||
Create `frontend/src/features/tickets/TicketFilterBar.tsx` using `AppFilterBar`, `Input`, `Select`, and `Button`.
|
|
||||||
|
|
||||||
Props:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
type TicketFilterBarProps = {
|
|
||||||
q: string
|
|
||||||
status: string
|
|
||||||
priority: string
|
|
||||||
relatedSystem: string
|
|
||||||
onQChange: (value: string) => void
|
|
||||||
onStatusChange: (value: string) => void
|
|
||||||
onPriorityChange: (value: string) => void
|
|
||||||
onRelatedSystemChange: (value: string) => void
|
|
||||||
onReset: () => void
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- [x] **Step 6: Redesign TicketListPage**
|
|
||||||
|
|
||||||
Update `TicketListPage`:
|
|
||||||
|
|
||||||
- Use shadcn `Tabs` for `全部工单`, `我的待办`, `我创建的`, `高优先级`.
|
|
||||||
- Use `TicketMetricCards`.
|
|
||||||
- Use `TicketFilterBar`.
|
|
||||||
- Use backend pagination fields.
|
|
||||||
- Use `Pagination`, `PaginationContent`, `PaginationItem`, `PaginationPrevious`, `PaginationNext`.
|
|
||||||
- Table columns must be Chinese and include requester/assignee display when available.
|
|
||||||
- Empty/error/loading states must be Chinese.
|
|
||||||
|
|
||||||
- [x] **Step 7: Verify frontend GREEN**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npm run typecheck
|
|
||||||
npm run build
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: both pass.
|
|
||||||
|
|
||||||
- [x] **Step 8: Commit**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add frontend/src/features/tickets
|
|
||||||
git commit -m "feat: redesign ticket list experience"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Task 3: Frontend Ticket Detail Redesign
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketDetailPage.tsx`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketComments.tsx`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketStatusTimeline.tsx`
|
|
||||||
- Create: `frontend/src/features/tickets/TicketTransitionDialog.tsx`
|
|
||||||
- Create: `frontend/src/features/tickets/TicketMetaPanel.tsx`
|
|
||||||
|
|
||||||
- [x] **Step 1: Refresh shadcn docs**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npx shadcn@latest docs dialog textarea card badge separator tabs sonner
|
|
||||||
```
|
|
||||||
|
|
||||||
- [x] **Step 2: Create TicketTransitionDialog**
|
|
||||||
|
|
||||||
Create a dialog component with:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
type TicketTransitionDialogProps = {
|
|
||||||
open: boolean
|
|
||||||
status: TicketStatus | null
|
|
||||||
onOpenChange: (open: boolean) => void
|
|
||||||
onSubmit: (status: TicketStatus, remark: string) => Promise<void>
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Visible text:
|
|
||||||
|
|
||||||
```text
|
|
||||||
处理说明
|
|
||||||
请说明本次流转的原因、处理动作或待确认事项。
|
|
||||||
取消
|
|
||||||
确认提交
|
|
||||||
```
|
|
||||||
|
|
||||||
The submit button is disabled until `remark.trim()` is non-empty.
|
|
||||||
|
|
||||||
- [x] **Step 3: Create TicketMetaPanel**
|
|
||||||
|
|
||||||
Create `TicketMetaPanel` with shadcn `Card`, `Badge`, `Separator`, `AppField`, `AppStatusBadge`, and `AppPriorityBadge`.
|
|
||||||
|
|
||||||
Display:
|
|
||||||
|
|
||||||
```text
|
|
||||||
当前状态
|
|
||||||
优先级
|
|
||||||
处理人
|
|
||||||
请求人
|
|
||||||
关联系统
|
|
||||||
运行环境
|
|
||||||
影响范围
|
|
||||||
```
|
|
||||||
|
|
||||||
- [x] **Step 4: Update TicketStatusTimeline**
|
|
||||||
|
|
||||||
Make every event label Chinese:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
const EVENT_LABELS: Record<string, string> = {
|
|
||||||
created: '创建工单',
|
|
||||||
updated: '更新工单',
|
|
||||||
status_change: '状态变更',
|
|
||||||
commented: '新增评论',
|
|
||||||
attachment_added: '新增附件',
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- [x] **Step 5: Update TicketComments**
|
|
||||||
|
|
||||||
Use Chinese labels and distinguish:
|
|
||||||
|
|
||||||
```text
|
|
||||||
内部备注
|
|
||||||
用户可见回复
|
|
||||||
```
|
|
||||||
|
|
||||||
Use shadcn `Tabs` or `Select` to choose visibility. Existing API can still receive:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
{ comment_type: 'internal_note' | 'user_reply', visibility: 'internal' | 'public' }
|
|
||||||
```
|
|
||||||
|
|
||||||
- [x] **Step 6: Redesign TicketDetailPage**
|
|
||||||
|
|
||||||
Update page:
|
|
||||||
|
|
||||||
- Loading title: `正在加载工单`
|
|
||||||
- Error title: `无法加载工单`
|
|
||||||
- Header actions open `TicketTransitionDialog`.
|
|
||||||
- Main column contains `问题描述`, `处理记录`, `评论与协作`.
|
|
||||||
- Side column uses `TicketMetaPanel`, `SolutionLinkPanel`, and restrained AI placeholder.
|
|
||||||
|
|
||||||
- [x] **Step 7: Verify frontend GREEN**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npm run typecheck
|
|
||||||
npm run build
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: both pass.
|
|
||||||
|
|
||||||
- [x] **Step 8: Commit**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add frontend/src/features/tickets
|
|
||||||
git commit -m "feat: redesign ticket detail experience"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Task 4: Frontend Ticket Create Redesign And Final Verification
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketCreatePage.tsx`
|
|
||||||
|
|
||||||
- [x] **Step 1: Refresh shadcn docs**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npx shadcn@latest docs card input select textarea badge alert
|
|
||||||
```
|
|
||||||
|
|
||||||
- [x] **Step 2: Redesign create page**
|
|
||||||
|
|
||||||
Update `TicketCreatePage` into grouped sections:
|
|
||||||
|
|
||||||
```text
|
|
||||||
基础信息
|
|
||||||
影响与优先级
|
|
||||||
环境与系统
|
|
||||||
问题描述
|
|
||||||
提交确认
|
|
||||||
```
|
|
||||||
|
|
||||||
Visible copy must be Chinese. Use `Card`, `Input`, `Select`, `Textarea`, `Badge`, and `Button`.
|
|
||||||
|
|
||||||
- [x] **Step 3: Use Chinese error feedback**
|
|
||||||
|
|
||||||
On create failure, show:
|
|
||||||
|
|
||||||
```text
|
|
||||||
创建工单失败，请检查必填信息或稍后重试。
|
|
||||||
```
|
|
||||||
|
|
||||||
- [x] **Step 4: Run full verification**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd backend
|
|
||||||
python -m pytest apps/tickets/tests apps/accounts/tests/test_permission_enforcement.py -v
|
|
||||||
python -m ruff check .
|
|
||||||
|
|
||||||
cd ../frontend
|
|
||||||
npm run typecheck
|
|
||||||
npm run build
|
|
||||||
npx shadcn@latest info
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: all commands pass.
|
|
||||||
|
|
||||||
- [x] **Step 5: Browser visual smoke test**
|
|
||||||
|
|
||||||
With local backend/frontend running:
|
|
||||||
|
|
||||||
- Login as seeded admin.
|
|
||||||
- Open `#/tickets` and verify Chinese tabs, metrics, filters, table, and pagination.
|
|
||||||
- Open a ticket detail page and verify transition dialog requires handling note.
|
|
||||||
- Open `#/tickets/new` and verify grouped create form has no obvious overlap.
|
|
||||||
|
|
||||||
- [x] **Step 6: Commit**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add frontend/src/features/tickets
|
|
||||||
git commit -m "feat: redesign ticket create experience"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Final Review Checklist
|
|
||||||
|
|
||||||
- [x] Ticket list uses shadcn tabs, cards, table, filters, and pagination.
|
|
||||||
- [x] Ticket detail uses a Chinese transition dialog and no English loading/error copy.
|
|
||||||
- [x] Ticket comments distinguish internal notes and user-visible replies.
|
|
||||||
- [x] Ticket create page uses grouped Chinese form sections.
|
|
||||||
- [x] Backend ticket list supports pagination and visual filters.
|
|
||||||
- [x] Ticket responses include requester and assignee display fields.
|
|
||||||
- [x] Empty transition remarks are rejected.
|
|
||||||
- [x] Backend ticket tests pass.
|
|
||||||
- [x] Backend ruff passes.
|
|
||||||
- [x] Frontend typecheck passes.
|
|
||||||
- [x] Frontend build passes.
|
|
||||||
- [x] shadcn info still reports Vite/Tailwind v3 and installed components.
|
|
||||||
@@ -1,280 +0,0 @@
|
|||||||
# Stage 1.8 Shadcn Admin UI Standardization Implementation Plan
|
|
||||||
|
|
||||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
||||||
|
|
||||||
**Goal:** Rebuild the frontend UI foundation around shadcn/ui so future pages inherit a consistent enterprise admin layout, mobile navigation, form standard, select composition, and visual baseline.
|
|
||||||
|
|
||||||
**Architecture:** shadcn/ui remains the source component library. Project `App*` components become thin composition wrappers around shadcn primitives, while feature pages consume those wrappers instead of hand-rolled layout. The first implementation batch fixes shell navigation, field primitives, select composition, and high-frequency forms.
|
|
||||||
|
|
||||||
**Tech Stack:** React 19, Vite, TypeScript, Tailwind v3, shadcn/ui `radix-nova`, Radix primitives, lucide-react.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## File Structure
|
|
||||||
|
|
||||||
- Modify: `frontend/src/app/layout/AppShell.tsx` - passes mobile menu state into topbar/sidebar sheet.
|
|
||||||
- Modify: `frontend/src/components/app/AppSidebar.tsx` - extracts reusable navigation content and adds sheet-friendly rendering.
|
|
||||||
- Modify: `frontend/src/components/app/AppTopbar.tsx` - adds mobile menu button and keeps desktop actions.
|
|
||||||
- Create: `frontend/src/components/ui/field.tsx` - shadcn field primitive from CLI, merged without losing local component changes.
|
|
||||||
- Modify: `frontend/src/components/app/AppField.tsx` - thin wrapper over shadcn field primitives.
|
|
||||||
- Modify: `frontend/src/features/**` select call sites - wrap `SelectItem` with `SelectGroup`.
|
|
||||||
- Modify: `frontend/src/features/auth/LoginPage.tsx` - migrate login form fields.
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketCreatePage.tsx` - migrate main create form fields.
|
|
||||||
- Modify: `frontend/src/features/solutions/SolutionCreatePage.tsx` - migrate solution form fields.
|
|
||||||
- Modify: `frontend/src/features/system/SystemUsersPage.tsx`, `SystemRolesPage.tsx`, `SystemUserGroupsPage.tsx` - migrate quick-create forms where practical.
|
|
||||||
- Test/verify: `npm run typecheck`, `npm run build`, grep scans, desktop/mobile browser checks.
|
|
||||||
|
|
||||||
## Implementation Progress
|
|
||||||
|
|
||||||
As of 2026-07-02, the Stage 1.8 foundation has been implemented and extended with core ticket page polish:
|
|
||||||
|
|
||||||
- Mobile sidebar navigation is available through a shadcn `Sheet`.
|
|
||||||
- shadcn `Field` primitives are installed and `AppField` is the project wrapper.
|
|
||||||
- Select menus have been swept to use `SelectContent > SelectGroup > SelectItem`.
|
|
||||||
- Login, ticket, solution, and system quick-create forms have been migrated toward `AppField`.
|
|
||||||
- `AppPage`, `AppDataTable`, `AppFilterBar`, and system governance page shells have been standardized.
|
|
||||||
- Enterprise visual foundation, light/dark/system theme switching, and sidebar theme tokens are in place.
|
|
||||||
- Ticket center and ticket detail have been refined as core Stage 1 operational screens.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Task 1: Mobile Shell Navigation
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `frontend/src/app/layout/AppShell.tsx`
|
|
||||||
- Modify: `frontend/src/components/app/AppSidebar.tsx`
|
|
||||||
- Modify: `frontend/src/components/app/AppTopbar.tsx`
|
|
||||||
|
|
||||||
- [x] **Step 1: Inspect current shell boundaries**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
Get-Content frontend/src/app/layout/AppShell.tsx
|
|
||||||
Get-Content frontend/src/components/app/AppSidebar.tsx
|
|
||||||
Get-Content frontend/src/components/app/AppTopbar.tsx
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: `AppShell` renders fixed sidebar and topbar; sidebar is desktop-only.
|
|
||||||
|
|
||||||
- [x] **Step 2: Add mobile menu state in shell**
|
|
||||||
|
|
||||||
Implement `mobileNavOpen` state in `AppShell`, pass `onMobileMenuClick` into topbar, and pass `mobileOpen/onMobileOpenChange` into sidebar.
|
|
||||||
|
|
||||||
- [x] **Step 3: Extract sidebar navigation content**
|
|
||||||
|
|
||||||
In `AppSidebar`, extract grouped nav rendering into `SidebarNavContent({ onNavigate })`. Use the same component for desktop and mobile sheet.
|
|
||||||
|
|
||||||
- [x] **Step 4: Render mobile Sheet**
|
|
||||||
|
|
||||||
Use existing shadcn `Sheet`, `SheetContent`, `SheetHeader`, and `SheetTitle`. The sheet title must be present for accessibility. Menu item clicks call `onNavigate`.
|
|
||||||
|
|
||||||
- [x] **Step 5: Add topbar mobile trigger**
|
|
||||||
|
|
||||||
Add a `Button size="icon" variant="ghost"` visible below `lg`, with `Menu` icon using `data-icon` and `aria-label="打开导航"`.
|
|
||||||
|
|
||||||
- [x] **Step 6: Verify**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
npm run typecheck
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: exit code 0.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Task 2: Install and Merge Shadcn Field Primitive
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Create: `frontend/src/components/ui/field.tsx`
|
|
||||||
- May modify: `frontend/src/components/ui/label.tsx`
|
|
||||||
- May modify: `frontend/src/components/ui/separator.tsx`
|
|
||||||
- Modify: `frontend/src/components/app/AppField.tsx`
|
|
||||||
|
|
||||||
- [x] **Step 1: Preview CLI changes**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
$env:NODE_USE_ENV_PROXY = "1"; $env:HTTP_PROXY = "http://127.0.0.1:7897"; $env:HTTPS_PROXY = "http://127.0.0.1:7897"; cd frontend; npx shadcn@latest add field --dry-run
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: creates `field.tsx`, previews updates to `label.tsx` and `separator.tsx`.
|
|
||||||
|
|
||||||
- [x] **Step 2: Inspect diffs before applying**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
$env:NODE_USE_ENV_PROXY = "1"; $env:HTTP_PROXY = "http://127.0.0.1:7897"; $env:HTTPS_PROXY = "http://127.0.0.1:7897"; cd frontend; npx shadcn@latest add field --diff field.tsx
|
|
||||||
$env:NODE_USE_ENV_PROXY = "1"; $env:HTTP_PROXY = "http://127.0.0.1:7897"; $env:HTTPS_PROXY = "http://127.0.0.1:7897"; cd frontend; npx shadcn@latest add field --diff label.tsx
|
|
||||||
$env:NODE_USE_ENV_PROXY = "1"; $env:HTTP_PROXY = "http://127.0.0.1:7897"; $env:HTTPS_PROXY = "http://127.0.0.1:7897"; cd frontend; npx shadcn@latest add field --diff separator.tsx
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: understand local changes before applying.
|
|
||||||
|
|
||||||
- [x] **Step 3: Add the field component**
|
|
||||||
|
|
||||||
Apply the CLI result, then inspect changed files. If `label.tsx` or `separator.tsx` overwrite local customizations, restore needed local behavior manually.
|
|
||||||
|
|
||||||
- [x] **Step 4: Rebuild AppField**
|
|
||||||
|
|
||||||
Make `AppField` render shadcn `Field`, `FieldLabel`, and optional `FieldDescription`. Support `htmlFor`, `required`, `invalid`, and `description` props.
|
|
||||||
|
|
||||||
- [x] **Step 5: Verify**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
npm run typecheck
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: exit code 0.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Task 3: Select Composition Sweep
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketFilterBar.tsx`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketCreatePage.tsx`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketComments.tsx`
|
|
||||||
- Modify: `frontend/src/features/solutions/SolutionListPage.tsx`
|
|
||||||
- Modify: `frontend/src/features/solutions/SolutionCreatePage.tsx`
|
|
||||||
- Modify: `frontend/src/features/design-system/DesignSystemPreview.tsx`
|
|
||||||
|
|
||||||
- [x] **Step 1: Add SelectGroup imports**
|
|
||||||
|
|
||||||
For each file importing select primitives, add `SelectGroup`.
|
|
||||||
|
|
||||||
- [x] **Step 2: Wrap select items**
|
|
||||||
|
|
||||||
Change:
|
|
||||||
|
|
||||||
```tsx
|
|
||||||
<SelectContent>
|
|
||||||
<SelectItem value="all">全部状态</SelectItem>
|
|
||||||
</SelectContent>
|
|
||||||
```
|
|
||||||
|
|
||||||
to:
|
|
||||||
|
|
||||||
```tsx
|
|
||||||
<SelectContent>
|
|
||||||
<SelectGroup>
|
|
||||||
<SelectItem value="all">全部状态</SelectItem>
|
|
||||||
</SelectGroup>
|
|
||||||
</SelectContent>
|
|
||||||
```
|
|
||||||
|
|
||||||
- [x] **Step 3: Scan**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
rg "SelectContent>[\\s\\S]*SelectItem|<SelectContent>\\s*<SelectItem" frontend/src -n
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: no direct `SelectItem` immediately under `SelectContent`.
|
|
||||||
|
|
||||||
- [x] **Step 4: Verify**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
npm run typecheck
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: exit code 0.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Task 4: High-Frequency Form Migration
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `frontend/src/features/auth/LoginPage.tsx`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketCreatePage.tsx`
|
|
||||||
- Modify: `frontend/src/features/solutions/SolutionCreatePage.tsx`
|
|
||||||
- Modify: `frontend/src/features/system/SystemUsersPage.tsx`
|
|
||||||
- Modify: `frontend/src/features/system/SystemRolesPage.tsx`
|
|
||||||
- Modify: `frontend/src/features/system/SystemUserGroupsPage.tsx`
|
|
||||||
|
|
||||||
- [x] **Step 1: Migrate login fields**
|
|
||||||
|
|
||||||
Use `AppField htmlFor="username"` and `AppField htmlFor="password"`. Inputs receive matching `id` and `aria-invalid={Boolean(error)}` only where field-specific invalid state is needed.
|
|
||||||
|
|
||||||
- [x] **Step 2: Migrate create ticket fields**
|
|
||||||
|
|
||||||
Use `AppField` for title, priority, impact scope, related system, environment, and description. Required fields use `required`.
|
|
||||||
|
|
||||||
- [x] **Step 3: Migrate create solution fields**
|
|
||||||
|
|
||||||
Use `AppField` for title, status, related system, environment scope, problem signature, root cause, solution, and risk note.
|
|
||||||
|
|
||||||
- [x] **Step 4: Migrate quick-create system forms**
|
|
||||||
|
|
||||||
Keep compact horizontal layout, but each input lives inside `AppField` so labels remain visible and shadcn field semantics are consistent.
|
|
||||||
|
|
||||||
- [x] **Step 5: Verify**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
npm run typecheck
|
|
||||||
npm run build
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: both exit code 0.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Task 5: Full UI Verification and Commit
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- All modified frontend files
|
|
||||||
|
|
||||||
- [x] **Step 1: Run shadcn context check**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
$env:NODE_USE_ENV_PROXY = "1"; $env:HTTP_PROXY = "http://127.0.0.1:7897"; $env:HTTPS_PROXY = "http://127.0.0.1:7897"; cd frontend; npx shadcn@latest info
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: current project remains `Vite`, `Tailwind v3`, `radix-nova`, `lucide`.
|
|
||||||
|
|
||||||
- [x] **Step 2: Run source scans**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
rg "space-[xy]-|<SelectContent>\\s*<SelectItem|className=.*size-4" frontend/src/features frontend/src/components/app -n
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: no new violations in migrated surfaces. Remaining non-button decorative icon sizes are acceptable only if not inside shadcn components.
|
|
||||||
|
|
||||||
- [ ] **Step 3: Browser checks**
|
|
||||||
|
|
||||||
User explicitly disabled visual/browser assistance during the Stage 1.8 UI pass, so browser checks remain pending until visual assistance is re-enabled.
|
|
||||||
|
|
||||||
Check desktop and mobile widths for:
|
|
||||||
- Login
|
|
||||||
- Workbench
|
|
||||||
- Ticket list
|
|
||||||
- Create ticket
|
|
||||||
- System users
|
|
||||||
|
|
||||||
Expected: mobile has navigation entry, no horizontal scroll, forms have visible labels.
|
|
||||||
|
|
||||||
- [x] **Step 4: Commit**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add frontend/src docs/superpowers/specs/2026-07-02-stage-1-8-shadcn-admin-ui-standardization-design.md docs/superpowers/plans/2026-07-02-stage-1-8-shadcn-admin-ui-standardization.md
|
|
||||||
git commit -m "feat: standardize shadcn admin ui foundation"
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: commit created on current branch.
|
|
||||||
@@ -1,128 +0,0 @@
|
|||||||
# Adopt Solution Close Ticket Implementation Plan
|
|
||||||
|
|
||||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
||||||
|
|
||||||
**Goal:** Allow support staff to search published solutions, adopt one, write it into the ticket resolution, and close the ticket in one action.
|
|
||||||
|
|
||||||
**Architecture:** Keep the adoption workflow server-side so ticket status, solution link, solution usage count, resolution fields, and timeline events stay consistent. The frontend remains a shadcn/App-component panel that calls a single action endpoint and refreshes ticket context.
|
|
||||||
|
|
||||||
**Tech Stack:** Django, Django Ninja, PostgreSQL migrations already present, React, TypeScript, Tailwind, shadcn/ui project components.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Task 1: Backend Adopt-And-Close Endpoint
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `backend/apps/solutions/schemas.py`
|
|
||||||
- Modify: `backend/apps/solutions/api.py`
|
|
||||||
- Test: `backend/apps/solutions/tests/test_solution_api.py`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Write the failing API test**
|
|
||||||
|
|
||||||
Add a test that creates a published solution and pending ticket, posts to `/api/solutions/{solution_id}/adopt-ticket`, and asserts:
|
|
||||||
|
|
||||||
```python
|
|
||||||
assert response.status_code == 200
|
|
||||||
ticket.refresh_from_db()
|
|
||||||
assert ticket.status == "closed"
|
|
||||||
assert ticket.is_resolved is True
|
|
||||||
assert ticket.replied_to_customer is True
|
|
||||||
assert ticket.resolution_summary == solution.solution
|
|
||||||
assert ticket.events.filter(event_type="solution_adopted").exists()
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Implement the schema and endpoint**
|
|
||||||
|
|
||||||
Add a payload with `ticket_id`, `remark`, and `replied_to_customer`. The endpoint should:
|
|
||||||
|
|
||||||
```python
|
|
||||||
link, _ = TicketSolutionLink.objects.get_or_create(
|
|
||||||
ticket=ticket,
|
|
||||||
solution=solution,
|
|
||||||
link_type="adopted",
|
|
||||||
defaults={"created_by": request.user if request.user.is_authenticated else None},
|
|
||||||
)
|
|
||||||
ticket.status = "closed"
|
|
||||||
ticket.resolution_summary = solution.solution
|
|
||||||
ticket.is_resolved = True
|
|
||||||
ticket.replied_to_customer = payload.replied_to_customer
|
|
||||||
ticket.resolved_at = ticket.resolved_at or timezone.now()
|
|
||||||
ticket.closed_at = timezone.now()
|
|
||||||
ticket.save(update_fields=[...])
|
|
||||||
TicketEvent.objects.create(event_type="solution_adopted", ...)
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 3: Verify backend**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
python -m pytest backend\apps\solutions\tests backend\apps\tickets\tests
|
|
||||||
python -m ruff check backend\apps\solutions backend\apps\tickets
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: all tests pass and ruff reports no issues.
|
|
||||||
|
|
||||||
### Task 2: Frontend Search And Adopt UI
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `frontend/src/features/solutions/api.ts`
|
|
||||||
- Modify: `frontend/src/features/solutions/SolutionLinkPanel.tsx`
|
|
||||||
- Modify: `frontend/src/features/tickets/TicketDetailPage.tsx`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Add API client**
|
|
||||||
|
|
||||||
Add:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
export function adoptSolutionAndCloseTicket(solutionId: number, ticketId: number) {
|
|
||||||
return apiRequest(`/solutions/${solutionId}/adopt-ticket`, {
|
|
||||||
method: 'POST',
|
|
||||||
body: JSON.stringify({
|
|
||||||
ticket_id: ticketId,
|
|
||||||
replied_to_customer: true,
|
|
||||||
remark: '采纳解决方案并关闭工单'
|
|
||||||
})
|
|
||||||
})
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Add search and action button**
|
|
||||||
|
|
||||||
In `SolutionLinkPanel`, add a search input filtering by `title`, `problem_signature`, and `solution`. Rename the adoption action to `采纳并关闭`, call the new endpoint, refresh linked solutions, and notify the parent ticket detail page to reload.
|
|
||||||
|
|
||||||
- [ ] **Step 3: Verify frontend**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
npm run typecheck
|
|
||||||
npm run build
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: TypeScript and Vite build both succeed.
|
|
||||||
|
|
||||||
### Task 3: Commit
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Stage only the backend/frontend files touched by this feature.
|
|
||||||
|
|
||||||
- [ ] **Step 1: Inspect git status**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git status --short
|
|
||||||
git diff --stat
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: existing local `.gitignore` and local lock/compose files remain unstaged.
|
|
||||||
|
|
||||||
- [ ] **Step 2: Commit**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add backend/apps/solutions frontend/src/features/solutions frontend/src/features/tickets/TicketDetailPage.tsx docs/superpowers/plans/2026-07-03-adopt-solution-close-ticket.md
|
|
||||||
git commit -m "feat: adopt solution and close ticket"
|
|
||||||
```
|
|
||||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -1,654 +0,0 @@
|
|||||||
# 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. |
|
|
||||||
@@ -1,240 +0,0 @@
|
|||||||
# 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.
|
|
||||||
@@ -1,480 +0,0 @@
|
|||||||
# Stage 1.6 Enterprise Governance Design
|
|
||||||
|
|
||||||
## Background
|
|
||||||
|
|
||||||
Stage 0 established an RBAC seed baseline with Django's built-in `User`, `Group`, and `Permission` models. Stage 1 added ticket and solution workflows. Stage 1.5 formalized shadcn/ui and created the enterprise admin UI base.
|
|
||||||
|
|
||||||
The current governance capability is still incomplete for an enterprise product:
|
|
||||||
|
|
||||||
- No frontend login or logout flow.
|
|
||||||
- No current-user API for frontend permission and menu rendering.
|
|
||||||
- No user management page.
|
|
||||||
- No user group management page.
|
|
||||||
- No role and permission management page.
|
|
||||||
- No menu permission management page.
|
|
||||||
- No API-level permission enforcement policy across ticket, solution, audit, and system governance APIs.
|
|
||||||
- Docker deployment does not yet run a full governance bootstrap for default admin, roles, permissions, and menus.
|
|
||||||
|
|
||||||
Stage 1.6 fills this gap before Stage 2 knowledge base and later Agent/model/MCP modules. Those later modules must not be built on top of anonymous APIs and hard-coded menus.
|
|
||||||
|
|
||||||
## Decision
|
|
||||||
|
|
||||||
Create a dedicated Stage 1.6 after Stage 1.5:
|
|
||||||
|
|
||||||
```text
|
|
||||||
Stage 0 = project skeleton + RBAC seed baseline
|
|
||||||
Stage 1 = ticket workflow and solution library
|
|
||||||
Stage 1.5 = shadcn enterprise UI foundation
|
|
||||||
Stage 1.6 = login + users + user groups + roles + menus + permission enforcement
|
|
||||||
Stage 2 = knowledge base and vector retrieval
|
|
||||||
```
|
|
||||||
|
|
||||||
Stage 1.6 is a frontend and backend stage. It must use the current shadcn/ui component base for all frontend governance pages.
|
|
||||||
|
|
||||||
## Goals
|
|
||||||
|
|
||||||
1. Add login, logout, and current-user APIs.
|
|
||||||
2. Add frontend login experience and authenticated application shell.
|
|
||||||
3. Add backend CRUD APIs for users, user groups, roles, permissions, and menus.
|
|
||||||
4. Add frontend system governance pages using shadcn components.
|
|
||||||
5. Add menu permission data so frontend navigation is driven by backend permission results instead of hard-coded public menus.
|
|
||||||
6. Add API permission checks for ticket, solution, audit, and governance endpoints.
|
|
||||||
7. Add deployment bootstrap so a fresh Docker environment can create default admin, permissions, roles, user groups, and menus.
|
|
||||||
|
|
||||||
## Non-Goals
|
|
||||||
|
|
||||||
- No SSO, LDAP, SAML, OAuth, enterprise WeChat, or DingTalk login.
|
|
||||||
- No multi-tenant model.
|
|
||||||
- No organization tree or department hierarchy.
|
|
||||||
- No row-level data permission.
|
|
||||||
- No field-level permission.
|
|
||||||
- No approval workflow.
|
|
||||||
- No password complexity policy beyond Django's baseline validation.
|
|
||||||
- No MFA.
|
|
||||||
- No public self-registration.
|
|
||||||
- No Stage 2 knowledge base, model gateway, Agent, Skill, or MCP implementation.
|
|
||||||
|
|
||||||
## Terminology
|
|
||||||
|
|
||||||
| Product Term | Backend Representation | Notes |
|
|
||||||
|---|---|---|
|
|
||||||
| 用户 | Django `User` | Use Django's built-in user model for Stage 1.6. |
|
|
||||||
| 角色 | Django `Group` | Product UI calls it "角色"; backend reuses Django Group permissions. |
|
|
||||||
| 权限点 | Django `Permission` | Seeded by catalog. Canonical business code is like `ticket.view`. |
|
|
||||||
| 用户组 | New `UserGroup` model | Business grouping independent from permission roles. |
|
|
||||||
| 菜单权限 | New `MenuItem` model + permission code | Menus can require a permission code and are returned from `/me`. |
|
|
||||||
| 按钮/操作权限 | Permission codenames | Frontend hides actions; backend still enforces. |
|
|
||||||
|
|
||||||
## Backend Design
|
|
||||||
|
|
||||||
### Authentication
|
|
||||||
|
|
||||||
Use Django session authentication for Stage 1.6.
|
|
||||||
|
|
||||||
Required endpoints under `/api/accounts/auth`:
|
|
||||||
|
|
||||||
| Method | Path | Purpose |
|
|
||||||
|---|---|---|
|
|
||||||
| `GET` | `/csrf` | Set CSRF cookie for SPA login requests. |
|
|
||||||
| `POST` | `/login` | Validate username/password and create Django session. |
|
|
||||||
| `POST` | `/logout` | Clear current session. |
|
|
||||||
| `GET` | `/me` | Return current user, roles, groups, permissions, and authorized menu tree. |
|
|
||||||
|
|
||||||
Cross-origin local development must support session cookies:
|
|
||||||
|
|
||||||
- Backend enables `CORS_ALLOW_CREDENTIALS = True`.
|
|
||||||
- Backend configures `CSRF_TRUSTED_ORIGINS` from env.
|
|
||||||
- Frontend API client sends `credentials: "include"`.
|
|
||||||
- Login flow fetches CSRF before posting credentials.
|
|
||||||
|
|
||||||
### Data Models
|
|
||||||
|
|
||||||
Add models to `backend/apps/accounts/models.py`.
|
|
||||||
|
|
||||||
#### UserGroup
|
|
||||||
|
|
||||||
Business user group separate from role permissions:
|
|
||||||
|
|
||||||
| Field | Type | Notes |
|
|
||||||
|---|---|---|
|
|
||||||
| `name` | varchar unique | Chinese display name. |
|
|
||||||
| `code` | varchar unique | Stable code for integration and seeding. |
|
|
||||||
| `description` | text blank | Optional description. |
|
|
||||||
| `users` | many-to-many `User` | Group members. |
|
|
||||||
| `is_active` | boolean | Disabled groups are not shown in normal assignment. |
|
|
||||||
| `created_at` / `updated_at` | datetime | Audit-friendly timestamps. |
|
|
||||||
|
|
||||||
#### MenuItem
|
|
||||||
|
|
||||||
Backend-driven menu definition:
|
|
||||||
|
|
||||||
| Field | Type | Notes |
|
|
||||||
|---|---|---|
|
|
||||||
| `code` | varchar unique | Stable menu code. |
|
|
||||||
| `title` | varchar | Chinese title. |
|
|
||||||
| `path` | varchar blank | Frontend hash route, such as `#/tickets`. |
|
|
||||||
| `icon` | varchar blank | Frontend icon key understood by AppSidebar. |
|
|
||||||
| `parent` | FK self nullable | Supports menu tree. |
|
|
||||||
| `sort_order` | int | Ordering inside parent. |
|
|
||||||
| `permission_code` | varchar blank | Business permission code required to see the menu. |
|
|
||||||
| `is_visible` | boolean | Hidden menus can still exist for permissions. |
|
|
||||||
| `is_enabled` | boolean | Disabled menus are excluded. |
|
|
||||||
| `created_at` / `updated_at` | datetime | Audit-friendly timestamps. |
|
|
||||||
|
|
||||||
Roles continue to use Django `Group`. Permissions continue to use Django `Permission`.
|
|
||||||
|
|
||||||
### Permission Catalog
|
|
||||||
|
|
||||||
Extend the permission catalog with Chinese names and governance permissions.
|
|
||||||
|
|
||||||
Required governance permission codes:
|
|
||||||
|
|
||||||
```text
|
|
||||||
system.user.view
|
|
||||||
system.user.manage
|
|
||||||
system.user_group.view
|
|
||||||
system.user_group.manage
|
|
||||||
system.role.view
|
|
||||||
system.role.manage
|
|
||||||
system.menu.view
|
|
||||||
system.menu.manage
|
|
||||||
system.audit.view
|
|
||||||
system.setting.manage
|
|
||||||
```
|
|
||||||
|
|
||||||
Existing business permissions remain:
|
|
||||||
|
|
||||||
```text
|
|
||||||
ticket.view
|
|
||||||
ticket.create
|
|
||||||
ticket.edit
|
|
||||||
ticket.export
|
|
||||||
ticket.assign
|
|
||||||
ticket.close
|
|
||||||
solution.view
|
|
||||||
solution.manage
|
|
||||||
knowledge.view
|
|
||||||
knowledge.manage
|
|
||||||
agent.use
|
|
||||||
agent.manage
|
|
||||||
model.manage
|
|
||||||
tool.manage
|
|
||||||
```
|
|
||||||
|
|
||||||
When checking permissions through Django, use `system.<business_code>` because the seeded permission content type uses app label `system`.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
```python
|
|
||||||
request.user.has_perm("system.ticket.view")
|
|
||||||
```
|
|
||||||
|
|
||||||
### Seed And Bootstrap
|
|
||||||
|
|
||||||
Stage 1.6 should add a single bootstrap command that is safe to run repeatedly:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python manage.py bootstrap_governance
|
|
||||||
```
|
|
||||||
|
|
||||||
The command must:
|
|
||||||
|
|
||||||
1. Seed permissions.
|
|
||||||
2. Seed default roles.
|
|
||||||
3. Seed default user groups.
|
|
||||||
4. Seed default menus.
|
|
||||||
5. Create or update a default admin user from env vars.
|
|
||||||
|
|
||||||
Recommended env vars:
|
|
||||||
|
|
||||||
```dotenv
|
|
||||||
DJANGO_SUPERUSER_USERNAME=admin
|
|
||||||
DJANGO_SUPERUSER_PASSWORD=admin12345
|
|
||||||
DJANGO_SUPERUSER_EMAIL=admin@example.com
|
|
||||||
```
|
|
||||||
|
|
||||||
Default roles:
|
|
||||||
|
|
||||||
| Role | Meaning |
|
|
||||||
|---|---|
|
|
||||||
| 系统管理员 | All permissions. |
|
|
||||||
| 知识库管理员 | Knowledge and solution management. |
|
|
||||||
| 技术支持 | Ticket handling and Agent usage. |
|
|
||||||
| 普通建单人 | Create/view own relevant tickets first; broad row-level ownership is deferred. |
|
|
||||||
| 只读审计员 | View tickets, solutions, knowledge, and audit logs. |
|
|
||||||
|
|
||||||
Default menus:
|
|
||||||
|
|
||||||
```text
|
|
||||||
工作台
|
|
||||||
运营总览
|
|
||||||
业务处理
|
|
||||||
工单中心
|
|
||||||
创建工单
|
|
||||||
解决方案库
|
|
||||||
平台能力
|
|
||||||
知识库
|
|
||||||
Agent 配置
|
|
||||||
模型与工具
|
|
||||||
系统治理
|
|
||||||
用户管理
|
|
||||||
用户组管理
|
|
||||||
角色权限
|
|
||||||
菜单权限
|
|
||||||
操作审计
|
|
||||||
设计系统
|
|
||||||
```
|
|
||||||
|
|
||||||
Menus for future modules may be seeded but hidden or disabled until their stage is implemented.
|
|
||||||
|
|
||||||
### Governance APIs
|
|
||||||
|
|
||||||
Add APIs under `/api/accounts`.
|
|
||||||
|
|
||||||
#### Current User
|
|
||||||
|
|
||||||
`GET /api/accounts/auth/me` returns:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"id": 1,
|
|
||||||
"username": "admin",
|
|
||||||
"display_name": "系统管理员",
|
|
||||||
"email": "admin@example.com",
|
|
||||||
"is_superuser": true,
|
|
||||||
"roles": [{"id": 1, "name": "系统管理员"}],
|
|
||||||
"user_groups": [{"id": 1, "name": "默认用户组", "code": "default"}],
|
|
||||||
"permissions": ["ticket.view", "system.user.manage"],
|
|
||||||
"menus": [
|
|
||||||
{
|
|
||||||
"code": "workbench",
|
|
||||||
"title": "工作台",
|
|
||||||
"path": "",
|
|
||||||
"icon": "home",
|
|
||||||
"children": []
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### User APIs
|
|
||||||
|
|
||||||
| Method | Path | Permission |
|
|
||||||
|---|---|---|
|
|
||||||
| `GET` | `/users` | `system.user.view` |
|
|
||||||
| `POST` | `/users` | `system.user.manage` |
|
|
||||||
| `GET` | `/users/{id}` | `system.user.view` |
|
|
||||||
| `PATCH` | `/users/{id}` | `system.user.manage` |
|
|
||||||
| `POST` | `/users/{id}/reset-password` | `system.user.manage` |
|
|
||||||
| `POST` | `/users/{id}/roles` | `system.user.manage` |
|
|
||||||
| `POST` | `/users/{id}/user-groups` | `system.user.manage` |
|
|
||||||
|
|
||||||
#### User Group APIs
|
|
||||||
|
|
||||||
| Method | Path | Permission |
|
|
||||||
|---|---|---|
|
|
||||||
| `GET` | `/user-groups` | `system.user_group.view` |
|
|
||||||
| `POST` | `/user-groups` | `system.user_group.manage` |
|
|
||||||
| `PATCH` | `/user-groups/{id}` | `system.user_group.manage` |
|
|
||||||
| `POST` | `/user-groups/{id}/members` | `system.user_group.manage` |
|
|
||||||
|
|
||||||
#### Role And Permission APIs
|
|
||||||
|
|
||||||
| Method | Path | Permission |
|
|
||||||
|---|---|---|
|
|
||||||
| `GET` | `/roles` | `system.role.view` |
|
|
||||||
| `POST` | `/roles` | `system.role.manage` |
|
|
||||||
| `PATCH` | `/roles/{id}` | `system.role.manage` |
|
|
||||||
| `POST` | `/roles/{id}/permissions` | `system.role.manage` |
|
|
||||||
| `GET` | `/permissions` | `system.role.view` |
|
|
||||||
|
|
||||||
#### Menu APIs
|
|
||||||
|
|
||||||
| Method | Path | Permission |
|
|
||||||
|---|---|---|
|
|
||||||
| `GET` | `/menus` | `system.menu.view` |
|
|
||||||
| `POST` | `/menus` | `system.menu.manage` |
|
|
||||||
| `PATCH` | `/menus/{id}` | `system.menu.manage` |
|
|
||||||
| `POST` | `/menus/reorder` | `system.menu.manage` |
|
|
||||||
|
|
||||||
### API Permission Enforcement
|
|
||||||
|
|
||||||
Add a small accounts permission helper:
|
|
||||||
|
|
||||||
```text
|
|
||||||
require_login(request)
|
|
||||||
require_permission(request, "ticket.view")
|
|
||||||
```
|
|
||||||
|
|
||||||
Enforcement rules:
|
|
||||||
|
|
||||||
- `/api/system/health` remains public.
|
|
||||||
- `/api/accounts/auth/csrf` and `/api/accounts/auth/login` remain public.
|
|
||||||
- `/api/accounts/auth/me` requires login.
|
|
||||||
- Audit log list requires `system.audit.view`.
|
|
||||||
- Ticket list/detail/export require `ticket.view`.
|
|
||||||
- Ticket create requires `ticket.create`.
|
|
||||||
- Ticket update/status/comment/attachment operations require the closest ticket operation permission.
|
|
||||||
- Solution list/detail require `solution.view`.
|
|
||||||
- Solution create/link requires `solution.manage`.
|
|
||||||
|
|
||||||
Frontend hiding is not security. Backend permission checks are mandatory for all protected operations.
|
|
||||||
|
|
||||||
## Frontend Design
|
|
||||||
|
|
||||||
### Auth Flow
|
|
||||||
|
|
||||||
Add frontend auth state:
|
|
||||||
|
|
||||||
```text
|
|
||||||
AuthProvider
|
|
||||||
├─ load /api/accounts/auth/me
|
|
||||||
├─ login(username, password)
|
|
||||||
├─ logout()
|
|
||||||
└─ exposes user, permissions, menus, loading, authenticated
|
|
||||||
```
|
|
||||||
|
|
||||||
Application flow:
|
|
||||||
|
|
||||||
```text
|
|
||||||
Unauthenticated → LoginPage
|
|
||||||
Authenticated → AppShell + Router
|
|
||||||
```
|
|
||||||
|
|
||||||
The login page must use shadcn components and Chinese text:
|
|
||||||
|
|
||||||
- `Card`
|
|
||||||
- `Input`
|
|
||||||
- `Button`
|
|
||||||
- `Alert`
|
|
||||||
- `Label` or shadcn `Field` if installed
|
|
||||||
|
|
||||||
### API Client
|
|
||||||
|
|
||||||
Update `frontend/src/lib/api.ts`:
|
|
||||||
|
|
||||||
- Send `credentials: "include"`.
|
|
||||||
- Include CSRF token for unsafe methods.
|
|
||||||
- Convert `401` into an auth state transition.
|
|
||||||
- Keep error messages Chinese where shown to users.
|
|
||||||
|
|
||||||
### Sidebar Menus
|
|
||||||
|
|
||||||
`AppSidebar` should no longer own the final hard-coded menu list. It should consume menu data from `AuthProvider`.
|
|
||||||
|
|
||||||
Rules:
|
|
||||||
|
|
||||||
- Backend returns only menus the user can see.
|
|
||||||
- Frontend still handles unknown future paths with disabled or placeholder behavior.
|
|
||||||
- Icon mapping is local and controlled, using lucide-react icons.
|
|
||||||
- All menu text is Chinese.
|
|
||||||
|
|
||||||
### Governance Pages
|
|
||||||
|
|
||||||
Add a new feature module:
|
|
||||||
|
|
||||||
```text
|
|
||||||
frontend/src/features/system/
|
|
||||||
```
|
|
||||||
|
|
||||||
Required pages:
|
|
||||||
|
|
||||||
| Route | Page | Purpose |
|
|
||||||
|---|---|---|
|
|
||||||
| `#/system/users` | 用户管理 | List, create, edit active state, assign roles and user groups, reset password. |
|
|
||||||
| `#/system/user-groups` | 用户组管理 | List/create/edit business user groups and members. |
|
|
||||||
| `#/system/roles` | 角色权限 | List/create/edit roles and assign permissions. |
|
|
||||||
| `#/system/menus` | 菜单权限 | View/edit menu tree, menu metadata, and required permission. |
|
|
||||||
| `#/audit` | 操作审计 | Reuse existing audit API with protected access. |
|
|
||||||
|
|
||||||
Required shadcn components:
|
|
||||||
|
|
||||||
- Existing Stage 1.5 components: `button`, `badge`, `card`, `input`, `textarea`, `select`, `label`, `separator`, `sidebar`, `breadcrumb`, `dropdown-menu`, `table`, `tabs`, `sheet`, `dialog`, `tooltip`, `skeleton`, `sonner`.
|
|
||||||
- Add if not installed: `checkbox`, `switch`, `alert`, `empty`, `pagination`.
|
|
||||||
|
|
||||||
Project App components should remain the page-level API:
|
|
||||||
|
|
||||||
- `AppDataTable`
|
|
||||||
- `AppFilterBar`
|
|
||||||
- `AppPageHeader`
|
|
||||||
- `AppSection`
|
|
||||||
- `AppEmptyState`
|
|
||||||
- system-specific wrappers if useful, such as `PermissionMatrix` and `RolePermissionEditor`.
|
|
||||||
|
|
||||||
### Page Experience
|
|
||||||
|
|
||||||
The governance UI should feel like an enterprise admin console, not a demo:
|
|
||||||
|
|
||||||
- Dense tables with Chinese column names.
|
|
||||||
- Dialog or Sheet for create/edit.
|
|
||||||
- Permission assignment grouped by module.
|
|
||||||
- Clear active/disabled status badges.
|
|
||||||
- Empty states in Chinese.
|
|
||||||
- Loading skeletons for initial data fetch.
|
|
||||||
- Toast feedback via `sonner`.
|
|
||||||
|
|
||||||
## Deployment Initialization
|
|
||||||
|
|
||||||
Docker/local startup should support a fresh database:
|
|
||||||
|
|
||||||
```text
|
|
||||||
backend startup:
|
|
||||||
python manage.py migrate
|
|
||||||
python manage.py bootstrap_governance
|
|
||||||
python manage.py runserver 0.0.0.0:8000
|
|
||||||
```
|
|
||||||
|
|
||||||
The exact startup implementation can be an entrypoint script or documented command. The important requirement is that a new developer can bring up Docker Compose and log in with the seeded admin account after migrations finish.
|
|
||||||
|
|
||||||
## Security Notes
|
|
||||||
|
|
||||||
- Default admin password is acceptable only for local/dev. Production deployments must override env vars.
|
|
||||||
- Backend permission checks are the source of truth.
|
|
||||||
- Superusers bypass permission assignment checks through Django's built-in behavior, but `/me` should still return all business permission codes.
|
|
||||||
- Passwords are never returned in API responses.
|
|
||||||
- User deletion should not be implemented in Stage 1.6; use deactivate instead.
|
|
||||||
|
|
||||||
## Testing Requirements
|
|
||||||
|
|
||||||
Backend tests:
|
|
||||||
|
|
||||||
- Login succeeds with seeded admin.
|
|
||||||
- `/me` returns user, roles, permissions, and filtered menus.
|
|
||||||
- Anonymous access to protected endpoints returns 401 or 403.
|
|
||||||
- Permissioned users can access allowed endpoints.
|
|
||||||
- Users without permissions are denied.
|
|
||||||
- User CRUD, role permission assignment, user group membership, and menu update APIs work.
|
|
||||||
- Bootstrap command is idempotent.
|
|
||||||
|
|
||||||
Frontend verification:
|
|
||||||
|
|
||||||
- `npm run typecheck`
|
|
||||||
- `npm run build`
|
|
||||||
- Browser smoke test:
|
|
||||||
- anonymous user sees login page
|
|
||||||
- seeded admin can log in
|
|
||||||
- system governance menus appear
|
|
||||||
- user/role/menu pages render Chinese UI
|
|
||||||
- logout returns to login
|
|
||||||
|
|
||||||
Full project verification:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd backend
|
|
||||||
python -m pytest -v
|
|
||||||
python -m ruff check .
|
|
||||||
|
|
||||||
cd frontend
|
|
||||||
npm run typecheck
|
|
||||||
npm run build
|
|
||||||
```
|
|
||||||
|
|
||||||
## Acceptance Criteria
|
|
||||||
|
|
||||||
- Fresh deployment can create database schema, seed governance data, and log in with the configured admin account.
|
|
||||||
- Frontend is no longer usable as an anonymous public app except for the login page.
|
|
||||||
- Sidebar menus come from backend-authorized menu data.
|
|
||||||
- Users, user groups, roles, permissions, and menus are manageable from Chinese frontend pages.
|
|
||||||
- Backend enforces permissions for ticket, solution, audit, and governance APIs.
|
|
||||||
- Frontend uses shadcn/ui primitives and project App components for all new governance UI.
|
|
||||||
- No Stage 2 knowledge base or AI platform features are implemented in this stage.
|
|
||||||
@@ -1,454 +0,0 @@
|
|||||||
# Stage 1.7 Ticket Experience Visual Redesign Design
|
|
||||||
|
|
||||||
## Background
|
|
||||||
|
|
||||||
Stage 1.6 has established the enterprise governance baseline: login, session-authenticated APIs, backend-driven menus, roles, users, user groups, permission enforcement, and Docker bootstrap.
|
|
||||||
|
|
||||||
The ticket workflow is now protected and usable, but the current ticket UI still feels like a basic demo:
|
|
||||||
|
|
||||||
- The ticket list is a simple table with limited visual hierarchy.
|
|
||||||
- The detail page exposes actions as flat buttons without enough workflow context.
|
|
||||||
- The create page has rough spacing and a few English fallback strings remain in the detail page.
|
|
||||||
- The UI does not yet communicate an enterprise support operations workflow.
|
|
||||||
|
|
||||||
Stage 1.7 intentionally prioritizes visual and interaction quality for the ticket surfaces before deeper backend capabilities such as SLA, batch operations, attachment upload, or row-level permissions.
|
|
||||||
|
|
||||||
## Decision
|
|
||||||
|
|
||||||
Create Stage 1.7 as a visual-first ticket experience stage:
|
|
||||||
|
|
||||||
```text
|
|
||||||
Stage 1.6 = enterprise governance, login, permission menus, deployment bootstrap
|
|
||||||
Stage 1.7 = ticket list/detail/create visual redesign using shadcn/ui
|
|
||||||
Stage 1.8+ = deeper ticket workflow capabilities, SLA, attachments, batch operations
|
|
||||||
Stage 2 = knowledge base and vector retrieval
|
|
||||||
```
|
|
||||||
|
|
||||||
The frontend must use the existing shadcn/ui foundation. New visual work must compose shadcn primitives and existing app-level components rather than introducing a new UI library or ad hoc styled widgets.
|
|
||||||
|
|
||||||
## Goals
|
|
||||||
|
|
||||||
1. Redesign the ticket center as an enterprise operations table, not a simple record list.
|
|
||||||
2. Redesign the ticket detail page around clear workflow context, status timeline, comments, and right-side metadata.
|
|
||||||
3. Redesign the create ticket page into a polished grouped form with Chinese labels and helper copy.
|
|
||||||
4. Keep all visible frontend copy in Chinese.
|
|
||||||
5. Use shadcn/ui components for all new controls, feedback, overlays, status display, and layout surfaces.
|
|
||||||
6. Add only the backend support needed for the redesigned UI, such as pagination, richer filters, and basic requester/assignee display fields.
|
|
||||||
|
|
||||||
## Non-Goals
|
|
||||||
|
|
||||||
- No SLA engine.
|
|
||||||
- No real attachment upload pipeline.
|
|
||||||
- No batch operations.
|
|
||||||
- No Kanban board.
|
|
||||||
- No row-level data permission.
|
|
||||||
- No field-level permission.
|
|
||||||
- No AI ticket drafting implementation.
|
|
||||||
- No knowledge base retrieval implementation.
|
|
||||||
- No new authentication or authorization model.
|
|
||||||
- No replacement of the existing shadcn preset or theme.
|
|
||||||
|
|
||||||
## UI System Requirements
|
|
||||||
|
|
||||||
The implementation must use the existing project shadcn setup:
|
|
||||||
|
|
||||||
- Framework: Vite + React + TypeScript.
|
|
||||||
- Styling: Tailwind CSS v3.
|
|
||||||
- shadcn style: `radix-nova`.
|
|
||||||
- Icon library: `lucide-react`.
|
|
||||||
- Component source: local shadcn files under `frontend/src/components/ui`.
|
|
||||||
|
|
||||||
Required shadcn primitives for Stage 1.7:
|
|
||||||
|
|
||||||
- Already installed: `button`, `badge`, `card`, `dialog`, `input`, `label`, `pagination`, `select`, `separator`, `skeleton`, `sonner`, `table`, `tabs`, `textarea`, `tooltip`.
|
|
||||||
- Add only if needed through `npx shadcn@latest add`: `sheet`, `popover`, `calendar`, `command`, `toggle-group`, `scroll-area`, `empty`.
|
|
||||||
|
|
||||||
Important compatibility rule:
|
|
||||||
|
|
||||||
- The project uses Tailwind CSS v3. Any newly generated shadcn component must be reviewed after `npx shadcn@latest add` and patched if the generated file contains Tailwind v4-only state selectors or syntax that does not compile or render correctly in the current project.
|
|
||||||
|
|
||||||
## Ticket List Redesign
|
|
||||||
|
|
||||||
Route:
|
|
||||||
|
|
||||||
```text
|
|
||||||
#/tickets
|
|
||||||
```
|
|
||||||
|
|
||||||
The page should become a dense operations console.
|
|
||||||
|
|
||||||
### Layout
|
|
||||||
|
|
||||||
Use a constrained full-width content area similar to the governance pages:
|
|
||||||
|
|
||||||
```text
|
|
||||||
Header
|
|
||||||
Metric cards
|
|
||||||
View tabs
|
|
||||||
Filter bar
|
|
||||||
Ticket table
|
|
||||||
Pagination footer
|
|
||||||
```
|
|
||||||
|
|
||||||
### Header
|
|
||||||
|
|
||||||
Header copy:
|
|
||||||
|
|
||||||
```text
|
|
||||||
工单中心
|
|
||||||
集中查看、筛选和处理企业技术支持工单。
|
|
||||||
```
|
|
||||||
|
|
||||||
Primary action:
|
|
||||||
|
|
||||||
```text
|
|
||||||
新建工单
|
|
||||||
```
|
|
||||||
|
|
||||||
### View Tabs
|
|
||||||
|
|
||||||
Use shadcn `Tabs`:
|
|
||||||
|
|
||||||
```text
|
|
||||||
全部工单
|
|
||||||
我的待办
|
|
||||||
我创建的
|
|
||||||
高优先级
|
|
||||||
```
|
|
||||||
|
|
||||||
Stage 1.7 can implement these as frontend view filters if backend support is not yet complete. The backend should still accept a lightweight `view` query parameter if feasible:
|
|
||||||
|
|
||||||
```text
|
|
||||||
all
|
|
||||||
assigned_to_me
|
|
||||||
created_by_me
|
|
||||||
high_priority
|
|
||||||
```
|
|
||||||
|
|
||||||
### Metrics
|
|
||||||
|
|
||||||
Use shadcn `Card` composition. Cards should be compact and operational:
|
|
||||||
|
|
||||||
```text
|
|
||||||
待处理
|
|
||||||
处理中
|
|
||||||
待确认
|
|
||||||
高优先级
|
|
||||||
```
|
|
||||||
|
|
||||||
### Filters
|
|
||||||
|
|
||||||
Use shadcn `Input` and `Select`:
|
|
||||||
|
|
||||||
```text
|
|
||||||
关键词
|
|
||||||
状态
|
|
||||||
优先级
|
|
||||||
关联系统
|
|
||||||
处理人
|
|
||||||
```
|
|
||||||
|
|
||||||
Date range is intentionally deferred unless a lightweight implementation is available without pulling in extra date complexity.
|
|
||||||
|
|
||||||
### Table Columns
|
|
||||||
|
|
||||||
Use the existing `AppDataTable` or a refined ticket-specific table built from shadcn `Table`.
|
|
||||||
|
|
||||||
Required columns:
|
|
||||||
|
|
||||||
```text
|
|
||||||
编号
|
|
||||||
标题
|
|
||||||
状态
|
|
||||||
优先级
|
|
||||||
关联系统
|
|
||||||
影响范围
|
|
||||||
处理人
|
|
||||||
创建时间
|
|
||||||
操作
|
|
||||||
```
|
|
||||||
|
|
||||||
The title cell should show compact secondary metadata when available, such as environment or requester.
|
|
||||||
|
|
||||||
### Pagination
|
|
||||||
|
|
||||||
Use the existing shadcn-compatible `pagination` component.
|
|
||||||
|
|
||||||
The backend should return pagination metadata if implemented:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"items": [],
|
|
||||||
"page": 1,
|
|
||||||
"page_size": 20,
|
|
||||||
"total": 0,
|
|
||||||
"total_pages": 0
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
If backend pagination is delayed, the frontend may paginate the loaded first 100 rows, but the preferred implementation is backend pagination.
|
|
||||||
|
|
||||||
## Ticket Detail Redesign
|
|
||||||
|
|
||||||
Route:
|
|
||||||
|
|
||||||
```text
|
|
||||||
#/tickets/{id}
|
|
||||||
```
|
|
||||||
|
|
||||||
The page should feel like a ticket operations workspace.
|
|
||||||
|
|
||||||
### Layout
|
|
||||||
|
|
||||||
Use a two-column layout:
|
|
||||||
|
|
||||||
```text
|
|
||||||
Header with title, ticket number, status, priority
|
|
||||||
Main column:
|
|
||||||
问题描述
|
|
||||||
处理记录
|
|
||||||
评论与协作
|
|
||||||
Side column:
|
|
||||||
当前状态
|
|
||||||
处理人
|
|
||||||
请求人
|
|
||||||
关联系统
|
|
||||||
运行环境
|
|
||||||
影响范围
|
|
||||||
关联方案
|
|
||||||
AI 支持分析（占位）
|
|
||||||
```
|
|
||||||
|
|
||||||
### Header Actions
|
|
||||||
|
|
||||||
Replace flat status buttons with workflow-aware actions.
|
|
||||||
|
|
||||||
Use shadcn `Dialog` for status transition:
|
|
||||||
|
|
||||||
```text
|
|
||||||
开始处理
|
|
||||||
提交确认
|
|
||||||
标记解决
|
|
||||||
关闭工单
|
|
||||||
```
|
|
||||||
|
|
||||||
The dialog must require a Chinese handling note:
|
|
||||||
|
|
||||||
```text
|
|
||||||
处理说明
|
|
||||||
请说明本次流转的原因、处理动作或待确认事项。
|
|
||||||
```
|
|
||||||
|
|
||||||
### Timeline
|
|
||||||
|
|
||||||
The timeline must render Chinese event labels:
|
|
||||||
|
|
||||||
```text
|
|
||||||
创建工单
|
|
||||||
更新工单
|
|
||||||
状态变更
|
|
||||||
新增评论
|
|
||||||
新增附件
|
|
||||||
```
|
|
||||||
|
|
||||||
English loading/error fallbacks must be replaced:
|
|
||||||
|
|
||||||
```text
|
|
||||||
无法加载工单
|
|
||||||
正在加载工单
|
|
||||||
```
|
|
||||||
|
|
||||||
### Comments
|
|
||||||
|
|
||||||
Comment UI should distinguish:
|
|
||||||
|
|
||||||
```text
|
|
||||||
内部备注
|
|
||||||
用户可见回复
|
|
||||||
```
|
|
||||||
|
|
||||||
Stage 1.7 may still post to the existing comment endpoint, but the UI should present the two visibility options clearly.
|
|
||||||
|
|
||||||
## Ticket Create Redesign
|
|
||||||
|
|
||||||
Route:
|
|
||||||
|
|
||||||
```text
|
|
||||||
#/tickets/new
|
|
||||||
```
|
|
||||||
|
|
||||||
The create page should be a polished enterprise form, not a loose demo form.
|
|
||||||
|
|
||||||
### Layout
|
|
||||||
|
|
||||||
Use grouped sections:
|
|
||||||
|
|
||||||
```text
|
|
||||||
基础信息
|
|
||||||
影响与优先级
|
|
||||||
环境与系统
|
|
||||||
问题描述
|
|
||||||
提交确认
|
|
||||||
```
|
|
||||||
|
|
||||||
Recommended layout:
|
|
||||||
|
|
||||||
```text
|
|
||||||
Main column: grouped form sections
|
|
||||||
Side column: 建单提示 + AI 建单辅助占位
|
|
||||||
```
|
|
||||||
|
|
||||||
### Required Fields
|
|
||||||
|
|
||||||
```text
|
|
||||||
工单标题
|
|
||||||
问题描述
|
|
||||||
优先级
|
|
||||||
```
|
|
||||||
|
|
||||||
Optional fields:
|
|
||||||
|
|
||||||
```text
|
|
||||||
关联系统
|
|
||||||
运行环境
|
|
||||||
影响范围
|
|
||||||
处理人
|
|
||||||
```
|
|
||||||
|
|
||||||
### Behavior
|
|
||||||
|
|
||||||
- Submit success navigates to the ticket detail page.
|
|
||||||
- Submit failure shows Chinese error feedback.
|
|
||||||
- Empty required fields rely on native validation or shadcn field validation styling.
|
|
||||||
- AI helper remains an understated placeholder, not the visual focus.
|
|
||||||
|
|
||||||
## Backend Support
|
|
||||||
|
|
||||||
Backend changes should remain narrow and visual-support oriented.
|
|
||||||
|
|
||||||
### List Query
|
|
||||||
|
|
||||||
Extend `GET /api/tickets` to support:
|
|
||||||
|
|
||||||
```text
|
|
||||||
page
|
|
||||||
page_size
|
|
||||||
status
|
|
||||||
priority
|
|
||||||
q
|
|
||||||
related_system
|
|
||||||
assignee_id
|
|
||||||
view
|
|
||||||
```
|
|
||||||
|
|
||||||
Suggested response:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"items": [],
|
|
||||||
"page": 1,
|
|
||||||
"page_size": 20,
|
|
||||||
"total": 0,
|
|
||||||
"total_pages": 0
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Ticket Output
|
|
||||||
|
|
||||||
Add basic display user fields to ticket output:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"requester": {"id": 1, "display_name": "张三", "username": "zhangsan"},
|
|
||||||
"assignee": {"id": 2, "display_name": "李四", "username": "lisi"}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Existing `requester_id` and `assignee_id` may remain if useful.
|
|
||||||
|
|
||||||
### Status Transition
|
|
||||||
|
|
||||||
The existing status transition endpoint can remain:
|
|
||||||
|
|
||||||
```text
|
|
||||||
POST /api/tickets/{id}/status
|
|
||||||
```
|
|
||||||
|
|
||||||
The frontend dialog should always send a non-empty remark. Backend validation for non-empty remark is preferred if it can be added with tests.
|
|
||||||
|
|
||||||
### Assignment
|
|
||||||
|
|
||||||
If needed for the detail side panel, use the existing `PATCH /api/tickets/{id}` with `assignee_id`. A dedicated assignment endpoint is deferred unless it materially simplifies UI code.
|
|
||||||
|
|
||||||
## Frontend File Scope
|
|
||||||
|
|
||||||
Expected files to touch:
|
|
||||||
|
|
||||||
```text
|
|
||||||
frontend/src/features/tickets/types.ts
|
|
||||||
frontend/src/features/tickets/api.ts
|
|
||||||
frontend/src/features/tickets/TicketListPage.tsx
|
|
||||||
frontend/src/features/tickets/TicketDetailPage.tsx
|
|
||||||
frontend/src/features/tickets/TicketCreatePage.tsx
|
|
||||||
frontend/src/features/tickets/TicketComments.tsx
|
|
||||||
frontend/src/features/tickets/TicketStatusTimeline.tsx
|
|
||||||
frontend/src/components/app/AppDataTable.tsx
|
|
||||||
frontend/src/components/app/AppEmptyState.tsx
|
|
||||||
```
|
|
||||||
|
|
||||||
Add small ticket-specific components only when they reduce page complexity:
|
|
||||||
|
|
||||||
```text
|
|
||||||
frontend/src/features/tickets/TicketMetricCards.tsx
|
|
||||||
frontend/src/features/tickets/TicketFilterBar.tsx
|
|
||||||
frontend/src/features/tickets/TicketTransitionDialog.tsx
|
|
||||||
frontend/src/features/tickets/TicketMetaPanel.tsx
|
|
||||||
```
|
|
||||||
|
|
||||||
## Testing Requirements
|
|
||||||
|
|
||||||
Backend tests:
|
|
||||||
|
|
||||||
- Ticket list pagination returns metadata and items.
|
|
||||||
- Ticket list filters by status, priority, related system, keyword, and view.
|
|
||||||
- Ticket output includes requester and assignee display fields.
|
|
||||||
- Status transition with an empty remark is rejected if backend validation is implemented.
|
|
||||||
|
|
||||||
Frontend verification:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npm run typecheck
|
|
||||||
npm run build
|
|
||||||
npx shadcn@latest info
|
|
||||||
```
|
|
||||||
|
|
||||||
Backend verification:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd backend
|
|
||||||
python -m pytest apps/tickets/tests -v
|
|
||||||
python -m pytest apps/accounts/tests/test_permission_enforcement.py -v
|
|
||||||
python -m ruff check .
|
|
||||||
```
|
|
||||||
|
|
||||||
Browser visual smoke test:
|
|
||||||
|
|
||||||
- Login as seeded admin.
|
|
||||||
- Open `#/tickets`.
|
|
||||||
- Verify the ticket list renders Chinese tabs, metric cards, filters, table, and pagination.
|
|
||||||
- Open a ticket detail page.
|
|
||||||
- Verify status actions open a Chinese dialog requiring handling note.
|
|
||||||
- Open `#/tickets/new`.
|
|
||||||
- Verify grouped Chinese create form renders without overlap.
|
|
||||||
|
|
||||||
## Acceptance Criteria
|
|
||||||
|
|
||||||
- Ticket list, detail, and create pages look like a coherent enterprise admin product.
|
|
||||||
- All visible copy in ticket pages is Chinese.
|
|
||||||
- New UI uses shadcn/ui components and existing app-level components.
|
|
||||||
- No new UI library is introduced.
|
|
||||||
- Backend changes are limited to pagination, filters, display fields, and remark validation if implemented.
|
|
||||||
- Existing authentication and permission enforcement continue to work.
|
|
||||||
- `npm run typecheck`, `npm run build`, backend ticket tests, and ruff pass.
|
|
||||||
- Browser screenshots show no obvious text overlap, broken layout, or blank states on desktop.
|
|
||||||
@@ -1,77 +0,0 @@
|
|||||||
# Stage 1.8 Shadcn Admin UI Standardization Design
|
|
||||||
|
|
||||||
## Goal
|
|
||||||
|
|
||||||
Stage 1.8 upgrades the frontend from page-by-page polish into a stable enterprise admin UI foundation. All website UI must use shadcn/ui as the unified component library and visual source of truth.
|
|
||||||
|
|
||||||
## Principles
|
|
||||||
|
|
||||||
- Use shadcn/ui first. Business pages compose `@/components/ui/*` and the project App component layer; no second UI library.
|
|
||||||
- Keep frontend display text Chinese, concise, and operational.
|
|
||||||
- Use shadcn semantic tokens for color: `background`, `foreground`, `card`, `muted`, `primary`, `secondary`, `border`, `ring`, `destructive`.
|
|
||||||
- Do not introduce a separate theme system. `theme-factory` is used only as a quality checklist for contrast, responsive behavior, spacing, and perceived polish.
|
|
||||||
- Prefer dense but calm enterprise admin screens over marketing layouts, oversized hero blocks, decorative gradients, or AI-purple visual identity.
|
|
||||||
|
|
||||||
## Scope
|
|
||||||
|
|
||||||
### P1 Mobile Navigation
|
|
||||||
|
|
||||||
The current desktop sidebar is hidden on small screens, while the shell only reserves desktop left padding. Stage 1.8 adds a mobile navigation entry in the top bar and renders the same menu tree inside a shadcn `Sheet`.
|
|
||||||
|
|
||||||
Expected behavior:
|
|
||||||
- Desktop keeps fixed sidebar.
|
|
||||||
- Mobile shows a menu button in the top bar.
|
|
||||||
- Tapping the button opens a side sheet with the same grouped navigation.
|
|
||||||
- Tapping a menu item closes the sheet.
|
|
||||||
- Logged-in users can navigate to every visible enabled module on mobile.
|
|
||||||
|
|
||||||
### P2 Form Standardization
|
|
||||||
|
|
||||||
Forms must migrate toward shadcn `FieldGroup`, `Field`, `FieldLabel`, and `FieldDescription` primitives. The project `AppField` remains only as a thin wrapper around shadcn field primitives, not as a custom label/grid replacement.
|
|
||||||
|
|
||||||
Expected behavior:
|
|
||||||
- Required fields have visible labels.
|
|
||||||
- Invalid fields can express `data-invalid` and `aria-invalid`.
|
|
||||||
- Form layout uses `FieldGroup` and `Field` instead of raw `div` stacks.
|
|
||||||
- Login, create ticket, create solution, and system management quick-create forms become the first migrated surfaces.
|
|
||||||
|
|
||||||
### P2 Select Composition
|
|
||||||
|
|
||||||
Every shadcn select menu must use `SelectContent > SelectGroup > SelectItem`. Direct `SelectItem` children under `SelectContent` are not allowed.
|
|
||||||
|
|
||||||
First migrated surfaces:
|
|
||||||
- Ticket filter bar
|
|
||||||
- Ticket create priority
|
|
||||||
- Ticket comments visibility
|
|
||||||
- Solution list status filter
|
|
||||||
- Solution create status
|
|
||||||
- Design system preview select
|
|
||||||
|
|
||||||
### P3 Brand and Admin Visual Standard
|
|
||||||
|
|
||||||
Brand identity should come from consistent admin structure, not decorative theme divergence.
|
|
||||||
|
|
||||||
Visual baseline:
|
|
||||||
- Platform mark: compact text mark for `AI 工单平台`.
|
|
||||||
- Sidebar: grouped navigation, clear active state, consistent icon scale.
|
|
||||||
- Topbar: mobile menu, workspace breadcrumb, environment badge, user actions.
|
|
||||||
- Content: consistent page width, gutters, card/table density, and section spacing.
|
|
||||||
- No decorative gradients, emoji icons, or raw color palettes in business pages.
|
|
||||||
|
|
||||||
## Migration Order
|
|
||||||
|
|
||||||
1. Shell and navigation foundation.
|
|
||||||
2. shadcn field component integration.
|
|
||||||
3. Select composition sweep.
|
|
||||||
4. High-frequency forms migration.
|
|
||||||
5. Page visual pass for login, workbench, tickets, solutions, and system governance.
|
|
||||||
|
|
||||||
## Verification
|
|
||||||
|
|
||||||
- `npm run typecheck`
|
|
||||||
- `npm run build`
|
|
||||||
- `npx shadcn@latest info` with local proxy env
|
|
||||||
- Source scan for direct `SelectContent > SelectItem` patterns
|
|
||||||
- Source scan for form pages still using placeholder-only labels
|
|
||||||
- Browser checks at desktop width and mobile width for login, dashboard, tickets, create ticket, and system users
|
|
||||||
|
|
||||||
@@ -1,219 +0,0 @@
|
|||||||
# 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.
|
|
||||||
@@ -1,378 +0,0 @@
|
|||||||
# AI 工单平台新版产品蓝图
|
|
||||||
|
|
||||||
日期：2026-07-10
|
|
||||||
状态：已确认
|
|
||||||
定位：新版唯一主蓝图（Blueprint V2）
|
|
||||||
|
|
||||||
## 1. 文档定位
|
|
||||||
|
|
||||||
本文以当前代码和已完成能力为新起点，重新规划后续产品阶段。此前的 Stage 0、Stage 1、Stage 1.5、Stage 1.6、Stage 1.7、Stage 1.8、Stage 2 和 Stage 2.5 文档继续保留，用于追溯设计与实施历史，但不再承担后续阶段排序职责。
|
|
||||||
|
|
||||||
后续新增设计、实施计划和进度记录统一引用本文。若旧路线图与本文冲突，以本文为准。
|
|
||||||
|
|
||||||
## 2. 产品目标
|
|
||||||
|
|
||||||
建设一个面向单企业私有化部署的 AI 原生技术支持工单平台。平台以工单和业务知识为核心资产，以模型、智能体、技能和 MCP 工具作为能力放大器，以权限、人工确认和全量审计作为可信边界。
|
|
||||||
|
|
||||||
首个企业试运行版本必须覆盖：
|
|
||||||
|
|
||||||
- 工单、解决方案和知识库业务闭环。
|
|
||||||
- 用户、用户组、角色、菜单权限和审计。
|
|
||||||
- 模型渠道、模型测试和模型选择。
|
|
||||||
- 建单智能体、支持分析智能体和知识沉淀智能体。
|
|
||||||
- 配置型技能与可追踪的智能体运行过程。
|
|
||||||
- 只读 MCP 工具接入、授权、风险控制和调用审计。
|
|
||||||
- Docker Compose 初始化、监控、备份、安全和试运行验收。
|
|
||||||
|
|
||||||
## 3. 核心原则
|
|
||||||
|
|
||||||
### 3.1 产品闭环驱动
|
|
||||||
|
|
||||||
实施顺序采用“先确定完整产品，再逐步替换真实能力”：
|
|
||||||
|
|
||||||
```text
|
|
||||||
当前基线
|
|
||||||
-> 全局产品原型
|
|
||||||
-> AI 平台底座
|
|
||||||
-> AI 工单闭环
|
|
||||||
-> MCP 可信执行
|
|
||||||
-> 企业试运行
|
|
||||||
```
|
|
||||||
|
|
||||||
Stage A 先确定全平台页面、交互和数据契约。Stage B 至 Stage D 逐步将原型数据替换为真实 API 和运行能力。Stage E 不再增加大型模块，只解决试运行质量。
|
|
||||||
|
|
||||||
### 3.2 业务资产优先
|
|
||||||
|
|
||||||
- 工单和知识库是核心业务资产。
|
|
||||||
- 解决方案是可复用知识，不与某次工单处理结果混为一体。
|
|
||||||
- 智能体生成建议、草稿和运行产物，不直接拥有工单或知识数据。
|
|
||||||
- 正式业务写入由对应业务服务完成。
|
|
||||||
|
|
||||||
### 3.3 人工确认优先
|
|
||||||
|
|
||||||
- 建单、工单状态变更、解决方案发布和知识发布必须由用户确认。
|
|
||||||
- 授权后的只读 MCP 工具可以由智能体自动调用。
|
|
||||||
- 非只读操作不进入自动执行范围。
|
|
||||||
- 模型或智能体失败不能阻塞人工工单流程。
|
|
||||||
|
|
||||||
### 3.4 中文企业产品标准
|
|
||||||
|
|
||||||
- 所有前端展示文字以中文为主。
|
|
||||||
- 技术术语仅在必要位置补充英文标识。
|
|
||||||
- 全站使用 shadcn/ui、Tailwind CSS 和项目自有 `App*` 组件层。
|
|
||||||
- 页面必须覆盖加载、空数据、错误、禁用、权限不足和确认状态。
|
|
||||||
- 原型页面必须明确标识演示数据，不能伪装成已经持久化或执行成功。
|
|
||||||
|
|
||||||
## 4. 当前能力基线
|
|
||||||
|
|
||||||
以下能力视为新版蓝图的既有基础，不在后续阶段重复规划：
|
|
||||||
|
|
||||||
- Django + Django Ninja 模块化单体后端。
|
|
||||||
- React + Vite + Tailwind CSS + shadcn/ui 前端基础。
|
|
||||||
- Docker Compose 本地部署基础。
|
|
||||||
- 登录、当前用户、用户、用户组、角色、菜单权限和审计基础。
|
|
||||||
- 亮色、暗色、系统主题及响应式导航基础。
|
|
||||||
- 工单创建、列表、详情、分类驱动流转、评论和事件记录基础。
|
|
||||||
- 解决方案维护、关联、采纳和关闭工单能力。
|
|
||||||
- 知识库、知识条目、切片、确定性向量和检索基础。
|
|
||||||
|
|
||||||
当前尚未完成：
|
|
||||||
|
|
||||||
- 全平台前端产品原型。
|
|
||||||
- 模型网关与真实模型测试。
|
|
||||||
- 技能配置和版本管理。
|
|
||||||
- 智能体运行时、运行记录和执行轨迹。
|
|
||||||
- AI 建单、支持分析和知识沉淀闭环。
|
|
||||||
- MCP 服务、工具授权和可信调用。
|
|
||||||
- 企业试运行级监控、备份、安全和验收。
|
|
||||||
|
|
||||||
## 5. 产品模块与导航
|
|
||||||
|
|
||||||
| 一级模块 | 二级页面 | 核心职责 |
|
|
||||||
|---|---|---|
|
|
||||||
| 工作台 | 业务概览、待办事项、风险提醒、运行状态 | 展示工单、知识、智能体和工具的统一运营视图 |
|
|
||||||
| 工单中心 | 工单列表、创建工单、工单详情、我的待办 | 支持快速咨询与技术问题两类处理模式 |
|
|
||||||
| 知识与方案 | 知识库、知识检索、知识编辑、解决方案、待审核草稿 | 管理文档知识、结构化知识和可复用方案 |
|
|
||||||
| 智能体中心 | 智能体配置、运行记录、执行轨迹、效果统计 | 管理三类内置智能体及其运行情况 |
|
|
||||||
| 技能中心 | 技能列表、模板编辑、输入输出结构、测试 | 管理配置型专业能力模板 |
|
|
||||||
| 模型与工具 | 模型渠道、模型配置、模型测试、工具服务、调用记录 | 管理模型供应商和 MCP 工具 |
|
|
||||||
| 系统管理 | 用户、用户组、角色、菜单、权限、审计、系统配置 | 提供企业治理和安全边界 |
|
|
||||||
| 设计系统 | 组件预览、状态规范、主题规范 | 约束后续页面实现，不面向普通业务用户 |
|
|
||||||
|
|
||||||
## 6. 工单双流程
|
|
||||||
|
|
||||||
工单使用同一套核心数据模型，根据工单类型采用不同流转规则。
|
|
||||||
|
|
||||||
### 6.1 快速咨询
|
|
||||||
|
|
||||||
适用于查询采集进度、配置确认、信息答复等短处理问题。
|
|
||||||
|
|
||||||
```text
|
|
||||||
待处理 -> 完成
|
|
||||||
```
|
|
||||||
|
|
||||||
规则：
|
|
||||||
|
|
||||||
- 创建后可直接执行“完成工单”。
|
|
||||||
- “开始处理”不是必经步骤。
|
|
||||||
- 用户填写简短结果，或采纳已有解决方案自动回填。
|
|
||||||
- 一次操作同步记录解决和关闭时间。
|
|
||||||
- 不重复要求解决说明与关闭说明。
|
|
||||||
|
|
||||||
### 6.2 技术问题
|
|
||||||
|
|
||||||
适用于需要排查、协作、验证和客户确认的问题。
|
|
||||||
|
|
||||||
```text
|
|
||||||
待处理 -> 处理中 -> 已解决 -> 已关闭
|
|
||||||
```
|
|
||||||
|
|
||||||
规则：
|
|
||||||
|
|
||||||
- 开始处理时流转说明默认可选。
|
|
||||||
- 标记解决时必须存在解决结果。
|
|
||||||
- 已关联解决方案可以自动回填解决结果。
|
|
||||||
- 关闭时默认复用解决结果，不要求重复填写。
|
|
||||||
- 重新打开、转派和关键字段变更必须写入处理时间线。
|
|
||||||
|
|
||||||
## 7. 智能体协作流程
|
|
||||||
|
|
||||||
### 7.1 建单智能体
|
|
||||||
|
|
||||||
输入问题描述、截图和附件，输出字段草稿、缺失信息、分类建议、相似工单和可复用方案。用户确认后才创建工单。
|
|
||||||
|
|
||||||
### 7.2 支持分析智能体
|
|
||||||
|
|
||||||
结合工单、知识库、解决方案和授权只读工具，输出可能原因、排查步骤、引用来源和客户回复草稿。技术人员选择采纳内容，智能体不直接改变工单状态。
|
|
||||||
|
|
||||||
### 7.3 知识沉淀智能体
|
|
||||||
|
|
||||||
从已解决或已关闭工单生成解决方案草稿和知识条目草稿。知识管理员审核后发布。
|
|
||||||
|
|
||||||
统一数据链路：
|
|
||||||
|
|
||||||
```text
|
|
||||||
用户触发
|
|
||||||
-> 智能体运行
|
|
||||||
-> 模型、知识或工具调用
|
|
||||||
-> 生成 AI 产物和引用
|
|
||||||
-> 用户确认
|
|
||||||
-> 业务服务写入
|
|
||||||
-> 工单事件和审计日志
|
|
||||||
```
|
|
||||||
|
|
||||||
## 8. 技术架构
|
|
||||||
|
|
||||||
首个试运行版本继续采用模块化单体，不拆分微服务。
|
|
||||||
|
|
||||||
| 层级 | 技术与职责 |
|
|
||||||
|---|---|
|
|
||||||
| 前端产品层 | React、Vite、Tailwind CSS、shadcn/ui、`App*` 组件 |
|
|
||||||
| 业务 API 层 | Django Ninja，承载业务接口和 AI 配置接口 |
|
|
||||||
| AI 运行层 | 模型网关、智能体运行时、技能执行、知识检索、工具调用 |
|
|
||||||
| 异步任务层 | Celery + Redis，处理文档解析、向量化和智能体运行 |
|
|
||||||
| 数据层 | PostgreSQL + pgvector、MinIO、Redis |
|
|
||||||
| 可信治理层 | RBAC、人工确认、操作审计、运行轨迹、工具调用日志 |
|
|
||||||
|
|
||||||
后端模块边界：
|
|
||||||
|
|
||||||
```text
|
|
||||||
accounts
|
|
||||||
tickets
|
|
||||||
solutions
|
|
||||||
knowledge
|
|
||||||
modelhub
|
|
||||||
agents
|
|
||||||
skills
|
|
||||||
tools
|
|
||||||
audit
|
|
||||||
system
|
|
||||||
```
|
|
||||||
|
|
||||||
## 9. 数据所有权与关键实体
|
|
||||||
|
|
||||||
### 9.1 业务实体
|
|
||||||
|
|
||||||
- 工单、评论、附件、事件和处理结果由 `tickets` 管理。
|
|
||||||
- 可复用解决方案及工单关联由 `solutions` 管理。
|
|
||||||
- 知识库、知识条目、文档、切片和向量由 `knowledge` 管理。
|
|
||||||
|
|
||||||
### 9.2 AI 平台实体
|
|
||||||
|
|
||||||
- 模型渠道、模型配置和模型测试记录由 `modelhub` 管理。
|
|
||||||
- 技能、版本、输入结构和输出结构由 `skills` 管理。
|
|
||||||
- 智能体定义、运行、步骤和 AI 产物由 `agents` 管理。
|
|
||||||
- MCP 服务、工具、授权绑定、调用和确认记录由 `tools` 管理。
|
|
||||||
|
|
||||||
### 9.3 数据安全
|
|
||||||
|
|
||||||
- 模型和工具密钥加密保存，前端只显示脱敏结果。
|
|
||||||
- 技能仅支持配置型模板，不允许执行任意 Python 代码。
|
|
||||||
- 每个工具必须具有风险等级、启用状态和授权范围。
|
|
||||||
- 模型调用、知识引用、工具调用和人工确认必须可追踪。
|
|
||||||
|
|
||||||
## 10. 新版实施阶段
|
|
||||||
|
|
||||||
本文是跨阶段主蓝图，不作为一次性实施计划。Stage A 至 Stage E 必须分别建立独立设计规范和实施计划；当前阶段通过退出标准并完成文档同步后，才进入下一阶段。近期只为 Stage A 编写实施计划，不提前展开 Stage B 至 Stage E 的代码任务。
|
|
||||||
|
|
||||||
### Stage A：全局产品原型
|
|
||||||
|
|
||||||
目标：先完整呈现产品最终形态，锁定页面、交互和数据契约。
|
|
||||||
|
|
||||||
主要交付：
|
|
||||||
|
|
||||||
- 完整中文导航与响应式页面结构。
|
|
||||||
- 工作台和企业运营概览。
|
|
||||||
- 模型渠道、模型测试页面。
|
|
||||||
- 智能体配置、运行列表、执行轨迹详情。
|
|
||||||
- 技能配置、结构编辑和原型测试。
|
|
||||||
- MCP 服务、工具、风险和调用审计页面。
|
|
||||||
- 工单创建与详情中的 AI 辅助面板。
|
|
||||||
- 统一指标、风险、引用、轨迹、审批和状态组件。
|
|
||||||
- 生产式 TypeScript Mock 契约与演示数据标识。
|
|
||||||
|
|
||||||
退出标准：
|
|
||||||
|
|
||||||
- 所有规划页面均可访问并具有真实交互状态。
|
|
||||||
- 桌面端和移动端导航完整。
|
|
||||||
- 亮色、暗色和系统主题均正常。
|
|
||||||
- 所有用户可见文案为中文。
|
|
||||||
- 尚未接入 API 的操作不会伪装成持久化成功。
|
|
||||||
- 类型检查、构建和关键前端流程测试通过。
|
|
||||||
|
|
||||||
### Stage B：AI 平台底座
|
|
||||||
|
|
||||||
目标：用真实后端能力替换模型、技能和智能体原型数据。
|
|
||||||
|
|
||||||
主要交付：
|
|
||||||
|
|
||||||
- OpenAI-compatible 模型渠道适配层。
|
|
||||||
- 模型配置、默认模型、用途绑定和连通性测试。
|
|
||||||
- 配置型技能 CRUD、版本和输入输出结构校验。
|
|
||||||
- 智能体定义、模型选择、知识范围和技能绑定。
|
|
||||||
- 智能体运行、步骤、产物、耗时和失败记录。
|
|
||||||
- Celery 异步运行、超时、有限重试和幂等控制。
|
|
||||||
- 前端模型、技能和智能体页面接入真实 API。
|
|
||||||
|
|
||||||
退出标准：
|
|
||||||
|
|
||||||
- 可配置至少一个真实模型渠道并完成测试。
|
|
||||||
- 可运行测试智能体并查看完整执行轨迹。
|
|
||||||
- 失败原因、调用耗时和引用信息可追踪。
|
|
||||||
- API、任务和供应商适配器测试通过。
|
|
||||||
|
|
||||||
### Stage C：AI 工单闭环
|
|
||||||
|
|
||||||
目标：让三类智能体在人工确认边界内服务真实工单和知识业务。
|
|
||||||
|
|
||||||
主要交付：
|
|
||||||
|
|
||||||
- 建单智能体的字段草稿、追问、分类和相似工单推荐。
|
|
||||||
- 支持分析智能体的原因分析、排查步骤、方案和回复草稿。
|
|
||||||
- 知识沉淀智能体的解决方案与知识草稿。
|
|
||||||
- 知识检索、引用来源和相似度展示。
|
|
||||||
- 快速咨询和技术问题两套正式流转规则。
|
|
||||||
- AI 产物采纳、拒绝和人工修改记录。
|
|
||||||
|
|
||||||
退出标准：
|
|
||||||
|
|
||||||
- 三类智能体分别完成一条真实业务闭环。
|
|
||||||
- 所有业务写入均经过用户确认。
|
|
||||||
- 引用能够追溯到知识、方案或工单来源。
|
|
||||||
- AI 失败时人工流程继续可用。
|
|
||||||
- 双流程、AI 采纳和失败降级端到端测试通过。
|
|
||||||
|
|
||||||
### Stage D：MCP 可信执行
|
|
||||||
|
|
||||||
目标：让智能体在明确权限和审计边界内使用外部只读工具。
|
|
||||||
|
|
||||||
主要交付：
|
|
||||||
|
|
||||||
- MCP 服务注册、认证配置、连接检查和工具同步。
|
|
||||||
- 工具描述、输入结构、风险等级和启用状态。
|
|
||||||
- 智能体与工具授权绑定。
|
|
||||||
- 只读工具自动调用。
|
|
||||||
- 非只读及高风险操作的阻止或人工确认机制。
|
|
||||||
- 工具调用输入摘要、输出摘要、耗时、状态和审计记录。
|
|
||||||
|
|
||||||
退出标准：
|
|
||||||
|
|
||||||
- 授权智能体可调用至少一个真实只读 MCP 工具。
|
|
||||||
- 未授权工具无法调用。
|
|
||||||
- 高风险或非只读调用不能自动执行。
|
|
||||||
- 工具权限矩阵、确认边界和审计测试通过。
|
|
||||||
|
|
||||||
### Stage E：企业试运行
|
|
||||||
|
|
||||||
目标：将完整产品提升到单企业私有化试运行标准。
|
|
||||||
|
|
||||||
主要交付：
|
|
||||||
|
|
||||||
- Docker Compose 全新环境初始化。
|
|
||||||
- 数据库迁移、初始管理员和基础角色初始化。
|
|
||||||
- 日志、任务状态、服务健康和关键指标监控。
|
|
||||||
- 数据备份、恢复演练和升级回滚说明。
|
|
||||||
- 权限矩阵、安全配置和敏感信息检查。
|
|
||||||
- 关键页面和接口性能优化。
|
|
||||||
- 试运行验收清单、运维说明和用户操作说明。
|
|
||||||
|
|
||||||
退出标准：
|
|
||||||
|
|
||||||
- 新环境可以按文档一次完成部署和初始化。
|
|
||||||
- 权限、审计、备份恢复和安全检查通过。
|
|
||||||
- 关键业务和 AI 流程通过端到端验收。
|
|
||||||
- 已知限制、运行风险和回退方式有明确记录。
|
|
||||||
|
|
||||||
## 11. 异常与可信边界
|
|
||||||
|
|
||||||
- 模型、知识检索或工具失败时，展示统一中文错误状态和可重试入口。
|
|
||||||
- 智能体运行失败不回滚或破坏已经存在的业务数据。
|
|
||||||
- 异步任务必须记录等待、运行、成功、失败和取消状态。
|
|
||||||
- 工具调用失败不得自动改变工单状态。
|
|
||||||
- 权限不足时前端隐藏无权入口，后端仍必须执行权限校验。
|
|
||||||
- 高风险操作必须展示操作对象、影响范围和确认结果。
|
|
||||||
- 所有 AI 建议必须区分“系统生成”和“用户已采纳”。
|
|
||||||
|
|
||||||
## 12. 测试与阶段完成标准
|
|
||||||
|
|
||||||
前端：
|
|
||||||
|
|
||||||
- TypeScript 类型检查。
|
|
||||||
- 生产构建。
|
|
||||||
- 公共组件和关键交互测试。
|
|
||||||
- 登录、导航、双工单流程、AI 采纳和工具确认端到端测试。
|
|
||||||
|
|
||||||
后端：
|
|
||||||
|
|
||||||
- pytest 自动化测试。
|
|
||||||
- Ruff 代码检查。
|
|
||||||
- 数据库迁移检查和全新数据库迁移验证。
|
|
||||||
- 模型适配、异步任务、权限和工具风险测试。
|
|
||||||
|
|
||||||
跨端：
|
|
||||||
|
|
||||||
- OpenAPI 与 TypeScript 数据契约保持一致。
|
|
||||||
- 前端原型字段与后端正式接口语义一致。
|
|
||||||
- 每个阶段完成后同步 README、设计系统、接口说明和本文进度。
|
|
||||||
- 不能用“页面存在”代替“功能已经真实持久化”的完成声明。
|
|
||||||
|
|
||||||
## 13. 首个试运行版本之外
|
|
||||||
|
|
||||||
以下能力进入试运行后的独立规划，不阻塞 Stage E：
|
|
||||||
|
|
||||||
- 历史工单批量迁移和清洗。
|
|
||||||
- 大规模历史工单向量化。
|
|
||||||
- 自动派单和复杂 SLA。
|
|
||||||
- 可视化流程设计器和 BPMN。
|
|
||||||
- 多智能体自主协作。
|
|
||||||
- 代码型技能和任意代码执行。
|
|
||||||
- 非只读 MCP 工具自动执行。
|
|
||||||
- 多租户 SaaS。
|
|
||||||
- 高度自治的自动解决和自动关闭。
|
|
||||||
- 高级经营分析和模型效果评测平台。
|
|
||||||
|
|
||||||
## 14. 最终成功定义
|
|
||||||
|
|
||||||
首个企业试运行版本完成时，普通建单人可以快速提交咨询或技术问题；技术支持可以在一个工单工作区内完成处理、检索、方案复用和 AI 辅助分析；知识管理员可以审核沉淀内容；系统管理员可以配置模型、智能体、技能、只读工具和权限；审计人员可以追溯每次业务变更、AI 运行和工具调用。
|
|
||||||
|
|
||||||
系统的 AI 能力应当缩短建单和排查时间，但不能牺牲人工控制、来源追溯和企业治理。
|
|
||||||
Reference in New Issue
Block a user