# 企业智能助手开发路线图

> 开发计划、进度跟踪、任务分解

---

## 📋 当前迭代 (Phase 1: MVP)

### 🔧 后端开发

#### Week 1: 核心功能

- [ ] **数据库设计**
  - [ ] 创建 `platform_ai.prisma` Schema 文件
  - [ ] 定义 Conversation 模型（含 tags 字段）
  - [ ] 定义 Message 模型（含 source 字段）
  - [ ] 定义 MessageFeedback 模型
  - [ ] 定义 AssistantTicket 模型（含 assigneeTeam 字段）
  - [ ] 定义 AIConfiguration 模型
  - [ ] 定义 PromptTemplate 模型 🆕
  - [ ] 定义 KnowledgeFix 模型 🆕
  - [ ] 创建数据库迁移

- [ ] **模块骨架**
  - [ ] 创建 `ai-assistant.module.ts`
  - [ ] 创建 chat 子模块
  - [ ] 创建 ticket 子模块
  - [ ] 创建 llm 子模块
  - [ ] 创建 security 子模块 🆕
  - [ ] 创建 prompt 子模块 🆕
  - [ ] 配置模块依赖

- [ ] **安全服务** 🆕
  - [ ] 创建 PIIService（敏感信息脱敏）
    - [ ] 身份证检测与脱敏
    - [ ] 手机号检测与脱敏
    - [ ] 银行卡号检测与脱敏
  - [ ] 创建 PromptGuardService（Prompt 注入防护）
    - [ ] 攻击模式检测
    - [ ] System Prompt 强化
  - [ ] 创建 OutputFilterService（输出过滤）
    - [ ] 危险内容检测
    - [ ] 外部链接过滤

- [ ] **LLM 服务集成**
  - [ ] 创建 LLMService
  - [ ] 实现 OpenAI 客户端封装
  - [ ] 实现 Azure OpenAI 客户端封装
  - [ ] 实现流式响应处理
  - [ ] 添加环境变量配置
  - [ ] 添加 API Key 验证
  - [ ] 集成安全服务（PII 脱敏 + Prompt 防护）🆕
  - [ ] 实现降级策略（Fallback 消息 + 告警）🆕

- [ ] **Prompt 管理** 🆕
  - [ ] 创建 PromptService
  - [ ] 支持按类别配置 Prompt（IT/HR/行政/通用）
  - [ ] Prompt 版本管理
  - [ ] `GET /prompts` - 获取 Prompt 列表
  - [ ] `PUT /prompts/:id` - 更新 Prompt

- [ ] **对话 API**
  - [ ] `POST /conversations` - 创建对话
  - [ ] `GET /conversations` - 获取对话列表
  - [ ] `GET /conversations/:id` - 获取对话详情
  - [ ] `DELETE /conversations/:id` - 删除对话
  - [ ] `POST /conversations/:id/messages` - 发送消息
  - [ ] `GET /conversations/:id/messages/stream` - SSE 流式响应

- [ ] **反馈 API**
  - [ ] `POST /messages/:id/feedback` - 提交反馈
  - [ ] `PUT /messages/:id/feedback` - 更新反馈

#### Week 2: 工单与集成

- [ ] **工单 API**
  - [ ] `POST /tickets` - 创建工单（含二次确认逻辑）🆕
  - [ ] `GET /tickets` - 获取工单列表
  - [ ] `GET /tickets/:id` - 获取工单详情
  - [ ] `PUT /tickets/:id` - 更新工单
  - [ ] `POST /tickets/:id/assign` - 分配工单
  - [ ] `POST /tickets/:id/resolve` - 解决工单

- [ ] **工单分配逻辑**
  - [ ] 实现问题分类
  - [ ] 实现按团队分配规则（IT/HR/Admin/Finance）🆕
  - [ ] 集成通知服务

- [ ] **权限控制**
  - [ ] 定义权限常量
  - [ ] 添加 Controller Guards
  - [ ] 添加种子数据

- [ ] **工单系统集成** 🆕
  - [ ] 实现 EscalationRequest 数据结构
  - [ ] 调用工单系统 API（source='AI_ASSISTANT'）
  - [ ] 传递最近 N 条消息作为首条评论
  - [ ] 传递用户上下文（userId, departmentId, region）

- [ ] **监控告警** 🆕
  - [ ] 错误日志记录（requestId, 错误类型, userId）
  - [ ] 连续失败告警（3次触发）
  - [ ] 接入监控系统（Prometheus metrics）

### 🎨 前端开发

#### Week 2: UI 组件

- [ ] **对话框组件**
  - [ ] ChatButton (悬浮按钮)
  - [ ] ChatWindow (对话窗口)
  - [ ] ChatHeader (窗口头部)
  - [ ] MessageList (消息列表)
  - [ ] MessageBubble (消息气泡)
  - [ ] ChatInput (输入框)
  - [ ] TypingIndicator (输入中提示)
  - [ ] AIDisclaimerBanner（仅提供指导声明）🆕

- [ ] **Markdown 渲染**
  - [ ] 集成 react-markdown
  - [ ] 代码高亮支持
  - [ ] 链接处理（禁止外部链接点击）🆕

- [ ] **SSE 集成**
  - [ ] EventSource 连接管理
  - [ ] 流式内容渲染
  - [ ] 错误处理

- [ ] **反馈组件**
  - [ ] FeedbackButtons (👍👎)
  - [ ] FeedbackDialog (反馈详情)

- [ ] **工单表单**
  - [ ] TicketForm 组件
  - [ ] 类别选择
  - [ ] 问题描述
  - [ ] 二次确认对话框 🆕（预览发送内容）

- [ ] **全局集成**
  - [ ] 添加到 Layout
  - [ ] 状态管理 (Zustand)

---

## 📅 待规划 (Phase 2)

### P1 - 重要功能

- [ ] **历史对话**
  - [ ] 历史对话列表页面
  - [ ] 对话搜索
  - [ ] 对话导出

- [ ] **问题分类增强**
  - [ ] AI 自动分类
  - [ ] 快捷问题入口
  - [ ] 分类关键词配置

- [ ] **对话标签** 🆕
  - [ ] 自动标签生成（VPN、Password、Leave 等）
  - [ ] 手动标签编辑
  - [ ] 标签统计分析

- [ ] **工单增强**
  - [ ] 工单评论
  - [ ] 状态变更通知
  - [ ] 工单统计
  - [ ] 按部门统计 🆕

- [ ] **知识补充机制（Human-in-the-loop）** 🆕
  - [ ] `POST /knowledge-fix` - 提交知识纠正
  - [ ] `GET /knowledge-fix` - 获取待审核列表
  - [ ] `PUT /knowledge-fix/:id/review` - 审核知识纠正
  - [ ] IT/HR 专员纠正界面
  - [ ] 管理员审核界面
  - [ ] 知识导出（为 RAG 准备）

- [ ] **管理后台仪表盘** 🆕
  - [ ] 调用量统计（24h / 7d）
  - [ ] 成功率 / 失败率
  - [ ] 平均响应时间
  - [ ] 场景分布（IT/HR/Admin/General）
  - [ ] 满意度（点赞率 vs 点踩率）
  - [ ] 幻觉标记数（点踩 + 知识纠正）
  - [ ] 权限控制（仅系统管理员）

### P2 - 增强功能

- [ ] **统计分析**
  - [ ] 使用量统计
  - [ ] 满意度统计
  - [ ] 热门问题
  - [ ] 统计图表
  - [ ] 按部门维度分析 🆕
  - [ ] AI 幻觉率统计 🆕

- [ ] **幻觉率评估** 🆕
  - [ ] 构建标注集（100 个常见问题 + 标准答案）
  - [ ] 编写评估脚本
  - [ ] 定期运行评估
  - [ ] 人工复核流程

- [ ] **配置管理**
  - [ ] System Prompt 配置界面
  - [ ] 模型参数配置
  - [ ] 分类处理人配置
  - [ ] Prompt A/B 测试 🆕

- [ ] **性能优化**
  - [ ] 对话缓存
  - [ ] 消息分页加载
  - [ ] SSE 重连机制

---

## 🚀 后续规划 (Phase 3+)

### 知识库集成

- [ ] RAG 检索增强
- [ ] 知识库管理界面
- [ ] 向量数据库集成
- [ ] 文档导入
- [ ] 使用知识纠正数据增强 RAG 🆕

### 高级功能

- [ ] 多模型支持
- [ ] 对话质检
- [ ] 工单流程集成（审批引擎）
- [ ] 智能路由
- [ ] 权限差异化响应 🆕

### 集成扩展

- [ ] 企业微信集成
- [ ] 钉钉集成
- [ ] 飞书集成

---

## ✅ 已完成

### 2025-12-11

- [x] **后端服务实现 v1.0** 🆕
  - [x] 创建 Prisma Schema (platform_ai.prisma)
  - [x] 创建模块骨架 (ai-assistant.module.ts)
  - [x] 创建 DTO 定义
  - [x] 创建安全服务 (PII 脱敏、Prompt 防护)
  - [x] 创建 LLM 服务 (OpenAI Provider)
  - [x] 创建对话服务和控制器
  - [x] 创建反馈服务和控制器
  - [x] 创建工单服务和控制器
  - [x] 创建知识补充服务和控制器
  - [x] 创建 Prompt 模板服务和控制器
  - [x] 创建配置服务和控制器
  - [x] 创建统计服务和控制器
  - [x] 注册模块到 AppModule
  - [x] 创建 E2E 结构化用例（`docs/modules/ai-assistant/10-e2e-test-spec.md`）
  - [x] 创建 API 实现一致性检查文档

- [x] **文档规划 v1.0**
  - [x] 创建模块目录结构
  - [x] 编写 PRD.md
  - [x] 编写 ARCHITECTURE.md
  - [x] 编写 API.md
  - [x] 编写 TODO.md
  - [x] 编写 README.md

- [x] **文档增强 v1.1**
  - [x] PRD: 增加核心场景优先级
  - [x] PRD: 增加关键约束（AI 不执行操作、不作为决策系统）
  - [x] PRD: 增加部门主管用户故事
  - [x] PRD: 增加安全功能（PII 脱敏、Prompt 注入防护）
  - [x] PRD: 增加 Prompt 管理功能
  - [x] PRD: 增加知识补充机制
  - [x] PRD: 增加升级二次确认
  - [x] PRD: 增加 AI 幻觉率验收标准
  - [x] ARCHITECTURE: 增加安全服务设计
  - [x] ARCHITECTURE: 增加数据模型字段（source、assigneeTeam、tags）
  - [x] ARCHITECTURE: 增加 KnowledgeFix、PromptTemplate 模型
  - [x] TODO: 更新任务列表

---

## ⚠️ 问题与风险

### 技术风险

1. **LLM API 稳定性**
   - 风险：OpenAI API 可能不稳定
   - 缓解：支持 Azure OpenAI 备选
   - 状态：待实现

2. **Token 成本**
   - 风险：使用量大时成本高
   - 缓解：使用滑动窗口限制上下文
   - 状态：已在设计中考虑

3. **响应延迟**
   - 风险：LLM 响应慢影响体验
   - 缓解：SSE 流式响应
   - 状态：已在设计中考虑

4. **Prompt 注入攻击** 🆕
   - 风险：恶意用户绕过 AI 限制
   - 缓解：多层防护（输入过滤 + System Prompt 强化 + 输出过滤）
   - 状态：已在设计中考虑

5. **AI 幻觉（Hallucination）** 🆕
   - 风险：AI 编造不存在的公司政策
   - 缓解：知识补充机制 + 质量监控 + 明确告知用户
   - 状态：已在设计中考虑

### 依赖风险

1. **OpenAI API Key**
   - 需要申请 API Key
   - 需要配置计费
   - 状态：待确认

### 安全风险 🆕

1. **敏感信息泄露**
   - 风险：用户在对话中输入敏感信息
   - 缓解：PII 脱敏服务
   - 状态：已在设计中考虑

2. **内部信息泄露**
   - 风险：AI 泄露 System Prompt 或内部配置
   - 缓解：Prompt 强化 + 输出过滤
   - 状态：已在设计中考虑

---

## 📊 进度统计

| 分类 | 已完成 | 进行中 | 待开发 |
|------|--------|--------|--------|
| 文档规划 | 6 | 0 | 0 |
| 后端核心 | 15 | 0 | 27 |
| 前端组件 | 0 | 0 | 18 |
| 管理后台 | 0 | 0 | 8 |
| 增强功能 | 0 | 0 | 30 |

**总体进度**: 约 25% (后端 MVP 基本完成)

---

## 📚 相关文档

- [PRD 产品需求](./01-prd.md)
- [架构设计](./03-architecture.md)
- [API 接口](./07-api.md)
- [模块索引](./README.md)

---

**创建时间**: 2025-12-11  
**迁移时间**: 2025-12-25  
**状态**: 规划中  
**版本**: v1.5

### 版本历史

| 版本 | 日期 | 变更说明 |
|------|------|----------|
| v1.0 | 2025-12-11 | 初始版本 |
| v1.1 | 2025-12-11 | 增加安全服务任务、知识补充机制、Prompt 管理、数据模型增强 |
| v1.2 | 2025-12-11 | 增加工单系统集成、监控告警、管理后台仪表盘、幻觉率评估、降级策略 |
| v1.3 | 2025-12-11 | 与 PRD/ARCHITECTURE/API 文档版本对齐 |
| v1.4 | 2025-12-11 | 后端服务实现完成，更新进度 |
| v1.5 | 2025-12-11 | 添加 E2E 结构化用例和 API 一致性检查 |