docs: redefine product blueprint

docs/superpowers/specs/2026-07-10-ai-ticket-platform-blueprint-v2-design.md

@@ -0,0 +1,378 @@
+# 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 能力应当缩短建单和排查时间，但不能牺牲人工控制、来源追溯和企业治理。