# 企业智能助手 PRD

> 产品需求文档 - 定义「做什么」和「为什么」

---

## 📋 背景与目标

### 背景

在企业日常运营中，员工经常遇到重复性问题：
- **IT 服务**: 密码重置、VPN 配置、软件安装
- **HR 咨询**: 请假政策、福利查询、报销流程
- **行政事务**: 办公用品申请、会议室预约、访客登记

这些问题占据了 IT、HR、行政人员大量时间，但大多数可以通过标准化答案解决。

### 目标

建立企业级 AI 智能助手系统：
1. **提升效率**: 7x24 小时即时响应常见问题
2. **降低成本**: 减少一线服务人员处理简单问题的工作量
3. **知识沉淀**: 将企业知识转化为 AI 可用的知识库
4. **服务闭环**: 未解决问题自动升级至人工处理

### 成功指标

| 指标 | 目标值 | 说明 |
|------|--------|------|
| 问题自助解决率 | ≥60% | 用户反馈已解决 / 总咨询数 |
| 首次响应时间 | <3s | AI 响应延迟 |
| 用户满意度 | ≥4.0/5.0 | 用户评价平均分 |
| 工单转化率 | ≤40% | 转人工处理比例 |
| AI 幻觉率 | <5% | 编造错误信息比例（见下方定义） |

> **幻觉率定义**: 在有标准答案的问题中，AI 的回答与标准答案明显不符的比例。测量方法：构建标注集（约 100 个常见问题 + 标准答案），定期运行评估脚本，人工复核标记不符项。

---

## 🎯 核心场景优先级（Top Use Cases）

> 初期重点训练和优化方向

| 优先级 | 场景 | 典型问题 | 价值 | 预期解决率 |
|:------:|------|----------|:----:|:----------:|
| **P0** | IT 帮助 | VPN 连接、密码重置、邮箱配置、软件安装 | 🔥 高 | 70% |
| **P0** | HR 政策查询 | 请假制度、年假余额、福利政策、加班规定 | 🔥 高 | 65% |
| **P1** | 报销政策 | 报销流程、发票要求、审批时限、额度标准 | 中 | 60% |
| **P1** | 行政事务 | 办公用品申请、会议室预约、访客流程、快递收发 | 中 | 55% |
| **P2** | 入职引导 | 新员工常见问题、系统账号、办公指南 | 中 | 50% |
| **P2** | 通用咨询 | 公司信息、部门联系方式、流程指引 | 低 | 40% |

### 场景示例

**IT 帮助 (P0)**:
```
用户: VPN 连接不上，显示认证失败
AI: 您好！VPN 认证失败通常有以下几个原因：
1. 密码过期 - 请先尝试重置 AD 密码
2. 证书过期 - 请重新下载 VPN 证书
3. 网络问题 - 请检查网络连接
[详细步骤...]
如果以上方法都无法解决，请点击下方"转人工"按钮。
```

**HR 政策查询 (P0)**:
```
用户: 年假怎么计算？
AI: 根据公司《休假管理制度》：
- 入职满1年：5天
- 入职满5年：10天
- 入职满10年：15天
年假按自然年度计算，当年未休完可延期至次年Q1。
```

---

## 🎯 边界声明

### 本模块职责（In Scope）

- ✅ AI 对话交互界面
- ✅ 大模型 API 调用与响应
- ✅ 对话历史记录
- ✅ 问题分类与路由
- ✅ 未解决问题升级（简单工单）
- ✅ 用户反馈收集
- ✅ 基础使用统计

### 不在本模块范围（Out of Scope）

- ❌ 企业知识库管理（后续迭代）
- ❌ RAG 检索增强（后续迭代）
- ❌ 复杂工单系统（可对接现有审批引擎）
- ❌ 多语言模型支持（初期使用单一模型）
- ❌ 语音交互
- ❌ 微信/钉钉集成

### ⚠️ 关键约束（Critical Constraints）

> 这些约束必须在设计和实现中严格遵守

| 约束 | 说明 | 原因 |
|------|------|------|
| **AI 不执行系统操作** | AI 只提供指导，不直接操作系统（如重置密码、创建账户、审批流程） | 安全风险控制 |
| **AI 不作为决策系统** | AI 仅提供信息和建议，不作为强制决策依据 | 避免责任风险 |
| **权限体系暂不差异化** | 所有用户获得相同的 AI 响应，不按角色差异回答 | 简化 MVP |
| **不存储敏感信息** | 对话中的敏感信息（身份证、银行卡等）必须脱敏后存储 | 数据安全 |

### 🔗 与 IAM 权限体系的约定

> 用户身份信息的传递与使用

- ✅ **必须传递用户身份**: 所有请求必须携带完整用户信息（userId、departmentId、region 等）
- ✅ **当前仅用于统计**: MVP 阶段，身份信息仅用于统计维度分析，不影响 AI 回答内容
- 🔮 **未来扩展**: v2+ 版本可能增加「按角色返回不同粒度信息」的能力（如：管理层可查看更详细的政策解读）

```typescript
// 请求必须包含的用户上下文
interface UserContext {
  userId: string;
  departmentId: string;
  departmentName: string;
  region?: string;        // 区域（如有）
  jobLevel?: string;      // 职级（如有）
  // 以上信息当前仅用于统计，不用于回答差异
}
```

---

## 👤 用户故事

### 普通员工

```
作为一名普通员工，
我希望能通过 AI 助手快速查询公司政策，
以便我不需要等待 HR 同事回复。
```

```
作为一名普通员工，
当 AI 无法解决我的问题时，
我希望问题能自动转交给相关人员处理，
以便我的问题最终能得到解决。
```

### IT 支持人员

```
作为一名 IT 支持人员，
我希望 AI 能处理大部分常见 IT 问题，
以便我可以专注于复杂技术问题。
```

```
作为一名 IT 支持人员，
我希望收到的工单包含完整的对话记录，
以便我了解问题的完整上下文。
```

### 部门主管 🆕

```
作为部门主管，
我希望 AI 帮我快速了解团队常见问题，
以便分析流程优化机会。
```

```
作为部门主管，
我希望能看到本部门的 AI 使用统计，
以便评估员工自助解决问题的能力。
```

### 系统管理员

```
作为系统管理员，
我希望能配置 AI 的系统提示词，
以便 AI 能按照公司规范回答问题。
```

```
作为系统管理员，
我希望能查看 AI 助手的使用统计，
以便评估系统效果并持续优化。
```

### 知识贡献者（HR/IT 专员）🆕

```
作为 HR 专员，
当 AI 回答不准确时，
我希望能补充正确答案，
以便提升 AI 的回答质量。
```

---

## 📱 功能需求

### P0 - 核心功能（MVP）

#### 1. AI 对话界面

| 功能点 | 描述 | 优先级 |
|--------|------|--------|
| 对话框组件 | 悬浮式对话窗口，可最小化/最大化 | P0 |
| 消息发送 | 支持文本输入，Enter 发送 | P0 |
| 消息展示 | 区分用户消息和 AI 回复，支持 Markdown | P0 |
| 打字机效果 | AI 回复流式展示 | P0 |
| 对话历史 | 显示当前会话历史 | P0 |
| 快捷入口 | 全局悬浮按钮，点击打开对话框 | P0 |

#### 2. AI 服务

| 功能点 | 描述 | 优先级 |
|--------|------|--------|
| 大模型调用 | 支持 OpenAI / Azure OpenAI API | P0 |
| 流式响应 | Server-Sent Events (SSE) 流式返回 | P0 |
| 对话上下文 | 维护多轮对话上下文 | P0 |
| 系统提示词 | 可配置的 System Prompt | P0 |
| 错误处理 | 优雅处理 API 错误，用户友好提示 | P0 |

#### 3. 反馈与升级

| 功能点 | 描述 | 优先级 |
|--------|------|--------|
| 满意度反馈 | 每条 AI 回复可点赞/点踩 | P0 |
| 问题升级 | "未解决" 按钮触发转人工 | P0 |
| **升级二次确认** 🆕 | 转工单前显示确认对话框，预览将发送的内容 | P0 |
| 简单工单 | 创建工单记录问题和对话 | P0 |
| 工单分配 | 根据问题类型分配处理人/团队 | P0 |

#### 4. 安全防护 🆕

| 功能点 | 描述 | 优先级 |
|--------|------|--------|
| 敏感信息检测 | 发送给 LLM 前检测并脱敏 PII（身份证、手机号、银行卡） | P0 |
| Prompt 注入防护 | 阻止绕过 AI 身份、执行危险指令的尝试 | P0 |
| 操作限制声明 | AI 回复中明确说明"仅提供指导，不执行操作" | P0 |
| 禁止外部链接 | AI 不生成、不执行外部链接或命令 | P0 |

#### 5. Prompt 管理 🆕

| 功能点 | 描述 | 优先级 |
|--------|------|--------|
| 分类 Prompt | 支持按类别配置不同的 System Prompt（IT/HR/行政/通用） | P0 |
| Prompt 版本管理 | 支持 Prompt 版本历史，便于回滚 | P0 |
| A/B 测试支持 | 支持 Prompt 灰度发布和效果对比 | P1 |

### P1 - 增强功能

#### 6. 对话管理

| 功能点 | 描述 | 优先级 |
|--------|------|--------|
| 历史会话 | 查看历史对话记录 | P1 |
| 新建会话 | 开始新对话，重置上下文 | P1 |
| 对话搜索 | 搜索历史对话内容 | P1 |
| 对话导出 | 导出对话记录 | P1 |

#### 7. 问题分类

| 功能点 | 描述 | 优先级 |
|--------|------|--------|
| 自动分类 | AI 自动识别问题类别（IT/HR/行政） | P1 |
| 快捷问题 | 预设常见问题快速入口 | P1 |
| 关键词路由 | 根据关键词路由到专业回答 | P1 |

#### 8. 对话标签 🆕

| 功能点 | 描述 | 优先级 |
|--------|------|--------|
| 自动标签 | AI 自动识别并添加标签（VPN、Password、Leave 等） | P1 |
| 人工标签 | 支持手动添加/编辑标签 | P1 |
| 标签统计 | 基于标签的问题分布统计 | P1 |

#### 9. 统计分析

| 功能点 | 描述 | 优先级 |
|--------|------|--------|
| 使用统计 | 对话量、解决率、满意度 | P1 |
| 热门问题 | 高频问题统计 | P1 |
| 导出报表 | 统计数据导出 | P1 |
| 部门统计 🆕 | 按部门维度的使用分析 | P1 |

#### 10. 知识补充机制（Human-in-the-loop）🆕

| 功能点 | 描述 | 优先级 |
|--------|------|--------|
| 答案纠错 | IT/HR 专员可对 AI 错误回答进行纠正 | P1 |
| 补充知识 | 纠正的答案可标记为"标准答案" | P1 |
| 知识审核 | 管理员审核知识补充内容 | P1 |
| 知识导出 | 导出纠正记录，未来用于 RAG | P1 |

### P2 - 后续规划

| 功能点 | 描述 | 优先级 |
|--------|------|--------|
| 知识库集成 | RAG 检索增强 | P2 |
| 多模型支持 | 支持切换不同 LLM | P2 |
| 工单流程 | 集成审批引擎 | P2 |
| 智能路由 | 复杂问题智能分派 | P2 |
| 对话质检 | AI 回复质量审核 | P2 |
| 权限差异化 | 按角色提供不同深度的回答 | P2 |

---

## 📊 数据模型（概念级）

### 核心实体

```
┌─────────────────┐     ┌─────────────────┐
│   Conversation  │────<│     Message     │
│   (对话会话)    │     │    (消息)       │
└─────────────────┘     └─────────────────┘
        │                       │
        │                       │
        ▼                       ▼
┌─────────────────┐     ┌─────────────────┐
│     Ticket      │     │    Feedback     │
│  (升级工单)     │     │   (用户反馈)    │
└─────────────────┘     └─────────────────┘
                                │
                                ▼
                        ┌─────────────────┐
                        │  KnowledgeFix   │ 🆕
                        │  (知识纠正)     │
                        └─────────────────┘
```

### 实体说明

| 实体 | 说明 | 主要字段 |
|------|------|----------|
| **Conversation** | 对话会话 | id, userId, title, status, category, tags[], createdAt |
| **Message** | 对话消息 | id, conversationId, role, content, **source** 🆕, createdAt |
| **Feedback** | 用户反馈 | id, messageId, type(👍/👎), comment |
| **Ticket** | 升级工单 | id, conversationId, category, status, assigneeId, **assigneeTeam** 🆕 |
| **KnowledgeFix** 🆕 | 知识纠正 | id, messageId, correctAnswer, contributor, status |
| **PromptConfig** 🆕 | Prompt 配置 | id, category, content, version, isActive |

### 字段增强说明 🆕

**Message.source** - 消息来源类型：
```typescript
enum MessageSource {
  USER = 'user',           // 用户输入
  AI = 'ai',               // AI 回复
  SYSTEM = 'system',       // 系统消息
  ESCALATION = 'escalation' // 升级通知
}
```

**Ticket.category** - 工单分类：
```typescript
enum TicketCategory {
  IT = 'IT',           // IT 支持
  HR = 'HR',           // 人力资源
  ADMIN = 'ADMIN',     // 行政事务
  FINANCE = 'FINANCE', // 财务问题
  OTHER = 'OTHER'      // 其他（无法分类时使用）
}
```

**Ticket.assigneeTeam** - 分配团队：
```typescript
enum AssigneeTeam {
  IT = 'IT',           // IT 团队
  HR = 'HR',           // HR 团队
  ADMIN = 'ADMIN',     // 行政团队
  FINANCE = 'FINANCE'  // 财务团队
}
```

> **说明**: `TicketCategory` 用于描述问题类型，`AssigneeTeam` 用于描述处理团队。一般情况下两者一致，但 `OTHER` 类型的工单会根据内容分配给最合适的团队。

### 🔗 与工单系统的数据约定

> 当 AI 助手发起升级工单时，工单系统将收到以下数据

```typescript
// AI 助手 -> 工单系统 的调用契约
interface EscalationRequest {
  // 来源标识
  source: 'AI_ASSISTANT';           // 固定值，标识来自 AI 助手
  
  // 对话关联
  conversationId: string;           // AI 对话会话 ID
  
  // 用户信息
  userId: string;
  departmentId: string;
  departmentName: string;
  region?: string;
  
  // 问题信息
  category: 'IT' | 'HR' | 'ADMIN' | 'FINANCE' | 'OTHER';
  priority: 'LOW' | 'MEDIUM' | 'HIGH';
  title: string;                    // 自动生成的工单标题
  description: string;              // 用户补充的问题描述
  
  // 对话摘要（作为工单首条内部评论）
  conversationSummary: {
    messageCount: number;           // 对话消息数
    recentMessages: Message[];      // 最近 N 条消息（建议 10 条）
    aiSuggestedCategory: string;    // AI 建议的分类
  };
}
```

**工单系统接收后应**:
1. 创建工单，设置 `source = 'AI_ASSISTANT'`
2. 将 `conversationSummary.recentMessages` 格式化为首条内部评论
3. 根据 `category` 自动分配给对应团队
4. 在工单详情页提供「查看完整对话」链接

---

## 🔐 非功能需求

### 性能要求

| 指标 | 要求 |
|------|------|
| 首字节响应 | <1s（AI 首字输出） |
| API 响应 | <3s（非 AI 接口） |
| 并发支持 | ≥100 并发对话 |

### 安全要求

| 要求 | 说明 |
|------|------|
| 身份认证 | 必须登录后使用 |
| 数据脱敏 | 对话内容不含敏感信息警告 |
| 访问控制 | 用户只能查看自己的对话 |
| 审计日志 | 记录关键操作日志 |

### 🆕 AI 安全要求

| 要求 | 说明 | 实现方式 |
|------|------|----------|
| **Prompt 注入防护** | 阻止恶意 Prompt 绕过系统限制 | 输入过滤 + System Prompt 强化 |
| **身份保护** | AI 不泄露内部身份、配置信息 | System Prompt 明确禁止 |
| **外部资源隔离** | AI 不执行外部链接、命令 | 输出过滤 + 禁止 URL 生成 |
| **PII 脱敏** | 敏感信息发送 LLM 前自动遮蔽 | 正则检测 + 替换为 `[已隐藏]` |

**PII 检测范围**:
- 身份证号（18位/15位）
- 手机号（11位）
- 银行卡号（16-19位）
- 邮箱地址（发送前警告，不强制脱敏）

### 可用性要求

- 7x24 小时服务
- 大模型 API 故障时显示友好提示
- 支持优雅降级

### 🔄 降级策略

> LLM 服务不可用时的处理方案

**触发条件**:
- OpenAI API 返回 5xx 错误
- 请求超时（>30s）
- Rate Limit 超限

**降级行为**:
```typescript
// 固定的 Fallback 消息
const FALLBACK_MESSAGE = `
抱歉，智能助手服务暂时不可用，请稍后重试。

如问题紧急，请通过以下方式联系支持：
- IT 问题：发送邮件至 it-support@company.com
- HR 问题：发送邮件至 hr@company.com
- 或直接创建工单：[工单系统链接]
`;
```

**监控告警**:
- 错误日志记录（包含 requestId、错误类型、用户 ID）
- 连续失败 3 次触发告警通知运维/开发
- 接入现有监控系统（如 Prometheus + Alertmanager）

### 📊 管理后台需求（Admin Dashboard）

> MVP 阶段需要的简易监控仪表盘

**核心指标展示**:

| 指标 | 说明 | 更新频率 |
|------|------|----------|
| 调用量 | 最近 24h / 7d 对话数 | 实时 |
| 成功率 | LLM 调用成功比例 | 实时 |
| 失败率 | LLM 调用失败比例 | 实时 |
| 平均响应时间 | AI 首字节响应延迟 | 实时 |
| 场景分布 | IT / HR / Admin / General 占比 | 每小时 |
| 满意度 | 点赞率 vs 点踩率 | 每小时 |
| 幻觉标记数 | 来自点踩 + 知识纠正的数量 | 每日 |

**页面位置**: 系统设置 > AI 助手管理 > 仪表盘

**权限要求**: 仅系统管理员可访问

---

## ✅ 验收标准

### MVP 验收标准

- [ ] 用户可以通过悬浮按钮打开 AI 对话框
- [ ] 用户可以发送消息并收到 AI 流式回复
- [ ] AI 回复支持 Markdown 渲染
- [ ] 用户可以对 AI 回复点赞/点踩
- [ ] 用户可以点击"未解决"将问题升级
- [ ] 升级前显示二次确认对话框 🆕
- [ ] 升级后创建工单并分配给处理人/团队
- [ ] 处理人可以查看工单和对话历史
- [ ] AI 回复中明确说明"仅提供指导" 🆕

### 安全验收标准 🆕

- [ ] 敏感信息（身份证、银行卡、手机号）在发送 LLM 前被脱敏
- [ ] Prompt 注入攻击被有效拦截（测试用例通过率 ≥95%）
- [ ] AI 不泄露内部配置、Prompt 内容
- [ ] AI 不生成可点击的外部链接

### 非功能验收标准

- [ ] AI 首字节响应时间 <1s
- [ ] 系统支持 100 并发对话
- [ ] 所有接口有权限控制
- [ ] 关键操作有审计日志

### 质量验收标准 🆕

- [ ] AI 幻觉率（编造公司政策）<5%
- [ ] 用户满意度 ≥4.0/5.0
- [ ] 问题自助解决率 ≥50%（MVP 阶段）

---

## 📅 里程碑

### Phase 1: MVP（2周）

**目标**: 基础对话能力 + 问题升级 + 安全防护

- Week 1: 后端 API + 数据库设计
  - [ ] 数据库 Schema
  - [ ] 对话 API（创建、发送消息）
  - [ ] 大模型集成（OpenAI）
  - [ ] SSE 流式响应
  - [ ] PII 脱敏服务 🆕
  - [ ] Prompt 注入防护 🆕

- Week 2: 前端对话框 + 工单
  - [ ] 悬浮对话框组件
  - [ ] 消息展示（Markdown）
  - [ ] 反馈收集
  - [ ] 升级二次确认 🆕
  - [ ] 简单工单创建

### Phase 2: 增强功能（2周）

**目标**: 历史管理 + 统计分析 + 知识补充

- [ ] 历史对话查看
- [ ] 对话搜索
- [ ] 问题分类
- [ ] 对话标签 🆕
- [ ] 使用统计
- [ ] 知识补充机制 🆕

### Phase 3: 知识库集成（规划中）

**目标**: RAG 增强，提升回答准确率

- [ ] 知识库管理
- [ ] 向量检索集成
- [ ] 回答引用来源
- [ ] 知识贡献奖励

---

## 📚 相关文档

- [架构设计](./ARCHITECTURE.md)
- [API 接口](./API.md)
- [开发待办](./TODO.md)

---

**创建时间**: 2025-12-11  
**更新时间**: 2025-12-11  
**状态**: 规划中  
**版本**: v1.3

### 版本历史

| 版本 | 日期 | 变更说明 |
|------|------|----------|
| v1.0 | 2025-12-11 | 初始版本 |
| v1.1 | 2025-12-11 | 增加核心场景优先级、AI 安全约束、Prompt 管理、知识补充机制、数据模型增强字段 |
| v1.2 | 2025-12-11 | 增加与工单系统数据约定、幻觉率测量定义、降级策略、管理后台需求、IAM 权限约定 |
| v1.3 | 2025-12-11 | 与 ARCHITECTURE/API 文档对齐：TicketCategory 增加 OTHER 枚举值 |