# AI 工单平台项目蓝图

更新日期：2026-07-16
状态：当前唯一主蓝图  
需求基线：[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-16，仓库并非空白项目。重规划必须在已有实现上演进。

| 能力 | 当前状态 | 蓝图判断 |
|---|---|---|
| Django/Django Ninja 模块化单体 | 已实现并可运行 | 保留 |
| React/Vite/Tailwind/shadcn 前端底座 | 已实现并可构建 | 保留，继续做产品组件层 |
| 用户、用户组、角色、菜单权限、审计 | 有真实模型和 API 基础 | 补权限矩阵和关键操作覆盖 |
| 工单 | 已有创建、列表、详情、编辑、分类流转、评论、附件元数据、导出 | 补真实文件上传、协作和业务一致性 |
| 解决方案 | 已有维护、关联、采纳和工单处理结果 | 保留，统一权威数据来源 |
| 知识库 | 已有知识库、条目、切片和检索 API | 当前是 JSON 向量和确定性哈希检索，不能视为真实向量能力 |
| 模型、Agent、Skill | 已完成真实渠道、版本配置、Celery 有序运行和轨迹 | Demo Milestone 已通过真实三步验收 |
| MCP | 尚无实现 | 按原蓝图推迟到可信业务闭环之后 |
| Docker Compose | 有 PostgreSQL、Redis、MinIO、前后端和 worker 基础 | 补生产化配置、健康检查和恢复流程 |
| 自动化验证 | 后端 79 项、前端 38 项测试通过；Ruff、迁移、Django、ESLint、类型检查和构建通过 | AI 配置底座已完成真实端到端验收，业务闭环仍待实施 |

当前需要正视的结构债务：

- `Ticket.ai_solution` 把 AI 内容放回业务主表，与“AI 产物独立”原则冲突，应停止新增依赖并在后续迁移。
- `Ticket.resolution_summary` 与 `TicketResolution` 存在权威来源重叠，需要明确实例处理结果以 `TicketResolution` 为准。
- `KnowledgeChunk.embedding` 使用 JSON，检索在应用内遍历并限制前 1000 条，只适合功能桩，不适合真实知识检索。
- 附件 API 当前记录存储路径和元数据，但不等于已经完成 MinIO 上传、解析、病毒/类型校验和访问控制。
- `/concept` 设计实验室及其 Mock 数据已删除；全局 Agent 助手仍必须明确标注本地演示且不得写入业务数据。

## 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 运行时。

交付：

- `TicketDraft`、逐问消息、临时图片和通用 `AgentArtifact` 数据模型。
- 单步建单 Agent：自然语言输入 -> 字段草稿 -> 批量补齐或最多 5 轮逐问 -> 用户确认 -> 创建工单。
- 草稿修订号与事务锁保证并发安全；同一草稿重复确认只返回原工单。
- 整单记录 `accepted`、`modified` 或 `rejected`，不把 AI 产物写入 `Ticket.ai_solution`。
- AI 失败、超时或输出 Schema 不合法时回退到普通建单。
- JPEG、PNG、WebP 图片经 Django 校验、去 EXIF 并代理写入 MinIO；视觉请求必须同时满足模型能力和渠道图片出境授权。
- 24 小时未完成草稿清理、已确认草稿/对话/产物永久保留，以及脱敏普通审计。

退出门槛：

- 至少一个真实 OpenAI-compatible 渠道可完成建单分析。
- 未经确认不能创建或修改工单。
- 同一确认请求具备幂等性，不会重复建单。
- 正常、拒绝、人工修改、模型失败和超时路径均有自动化测试。

实现状态（2026-07-16）：

- 真实文本模型已完成“描述 -> AI 草稿 -> 人工补齐 -> 明确确认 -> 幂等创建”验收。
- 图片存储、多模态协议、能力校验和 Base64 不落库已有自动化覆盖。
- 真实视觉渠道尚未验收，视觉能力不得标记为正式可用。

### 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. 立即执行的下一迭代

AI 平台配置演示版已于 2026-07-16 完成真实渠道固定端到端验收。草稿沙箱与发布版本均完成三步运行，版本快照、结构修复、权限拒绝、凭证脱敏和审计抽查通过。该演示只包含模型、Agent 和 Skill，不启动 MCP，也不计为业务闭环完成。

当前收尾与下一阶段任务顺序：

1. 为 Phase 1 编写“可信建单闭环设计”，明确自然语言草稿、人工确认和幂等建单契约。
2. 写出 `TicketResolution`、`AgentArtifact`、知识版本和引用快照的数据决策记录。
3. 禁止新增代码读取或写入 `Ticket.ai_solution`，设计兼容迁移。
4. 将已验证的 Agent 运行底座接入建单草稿，不允许模型直接写工单业务表。
5. 完成草稿确认、人工修改、拒绝、模型失败和超时路径。
6. 为工单创建、状态流转、方案采纳和知识检索补最小跨端回归。

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 和本文冲突，以已验证代码事实为现状，以本文为后续方向，并立即登记差距。