# 保险智能客服系统 — 文档索引

> **最后更新**：2026-06-08
> **项目状态**：后端 8 模块完成 + 前端 12 页面完成，进度 43%

---

## 文档总览

| 文档 | 位置 | 内容摘要 |
|------|------|---------|
| [需求文档](../保险智能客服系统_需求文档.md) | 根目录 | 完整需求：125 项功能 + 5 角色 + 数据库设计 |
| [API 接口文档](../保险智能客服系统_API接口文档.md) | 根目录 | 45 个接口完整设计 |
| [编码规范](../保险智能客服系统_编码规范.md) | 根目录 | 命名规范 + 项目结构 + BaoDan 集成规范 |
| [测试用例](../保险智能客服系统_测试用例.md) | 根目录 | 功能测试 + 边界测试 + 上线 Checklist |
| [开发计划](../开发计划.md) | 根目录 | 8 阶段开发计划 |
| [开发任务清单](../开发任务清单.md) | 根目录 | 412 项可勾选任务（已完成 182 项） |
| [**快速启动指南**](快速启动指南.md) | docs/ | **一键启动 + 配置流程** |
| [**BaoDan Workflow 配置指南**](BaoDan_Workflow配置指南.md) | docs/ | **产品推荐 Workflow 详细配置步骤** |
| [**企业微信接入指南**](企业微信接入指南.md) | docs/ | **企微自建应用、机器人消息、OAuth 登录完整配置** |
| [部署指南](../部署指南.md) | 根目录 | BaoDan 源码集成指南 |
| [API curl 示例](../API_curl示例.md) | 根目录 | 接口调试 curl 示例 |

---

## 按用途快速索引

### 开始开发前必读

1. **[README.md](../README.md)** — 5 分钟了解项目全貌
2. **[需求文档](../保险智能客服系统_需求文档.md)** — 需求细节（特别是第六章数据库、第九章 BaoDan 集成、第十二章数据流转图）
3. **[开发计划](../开发计划.md)** — 哪些做、哪些不做（BaoDan 原生功能清单）
4. **[开发任务清单](../开发任务清单.md)** — 每天干什么、完成后打勾

### 写代码时参考

5. **[编码规范](../保险智能客服系统_编码规范.md)** — 命名、注释、格式化、错误处理、日志、Git 规范
6. **[API 接口文档](../保险智能客服系统_API接口文档.md)** — 接口设计的权威来源
7. **[API curl 示例](../API_curl示例.md)** — 调试接口时直接复制

### 前端开发

8. **[前端开发计划](../前端开发计划.md)** — 完整组件代码（可以直接参考/复制）

### 测试验收

9. **[测试用例](../保险智能客服系统_测试用例.md)** — 347 个测试用例 + 上线 Checklist

### 部署上线

10. **[部署指南](../部署指南.md)** — BaoDan 集成步骤 + API Key 配置

---

## 关键决策记录

### BaoDan 复用决策（不再重复造轮子）

以下功能 **直接用 BaoDan 后台**，不写后端接口、不写前端页面：

| 功能 | BaoDan 提供 | 对应需求 |
|------|-----------|---------|
| LLM 模型配置 CRUD | ModelProviderCredentialApi | 6.1 |
| Prompt 编辑/版本/测试 | App 配置 + Annotation | 6.2 |
| 对话日志查看/筛选 | BaoDan /logs 页面 | 4.1.1-4.1.2 |
| 负反馈管理 | FeedbackExportApi | 4.1.4 |
| 点赞/点踩 | BaoDan WebApp 内置 | 1.4.1 |
| 推荐追问 | SuggestedQuestionApi | 1.2.4 |
| 来源引用 | RAG 自动返回 | 1.2.3 |
| 会话标题命名 | BaoDan 自动命名 | 1.1.5 |
| 知识库 hit testing | HitTestingApi | 3.4.1 |
| FAQ 管理 | Annotation Reply | 3.4.3 |
| 文档上传/删除/重试 | BaoDan /datasets 后台 | 3.1-3.2 |
| Markdown 渲染 | BaoDan WebApp | 1.2.1 |

### 后端自研接口（25+4 个）

| 模块 | 接口数 | 说明 |
|------|:---:|------|
| 认证 A1 | 4 | 企微登录 + 账密登录 + 刷新 + 退出 |
| 对话 A2 | 5+2 | 发消息 SSE + 会话 CRUD + 反馈 + 检索 |
| 推荐 A3 | 4 | 生成 + 轮询 + 导出 + 分享 |
| 知识库 A4 | 6+4 | 文档增强 + 数据源 CRUD + 同步 |
| 权限 A5 | 3 | 用户 CRUD + 批量导入 + 角色 |
| 日志 A7 | 1 | 系统操作日志 |
| 统计 A8 | 3 | 概览 + 趋势 + KB 健康度 |
| 企微 WB | 4 | 回调 + 消息 + OAuth 入口 + 回调 |

### 前端页面（11 个）

| 类型 | 页面 | 说明 |
|------|------|------|
| 用户端 | LoginPage / ChatPage / RecommendPage / RecommendHistory / RecommendDetail | 5 个 |
| 管理端 | DashboardPage / UsersPage / PermissionsPage / StatsPage / KBManagePage / DataSourcePage | 6 个 |

---

## 数据库表（6 张）

### Phase 0-5（已有建表 SQL）

| 表名 | 用途 |
|------|------|
| wecom_user_mapping | 企微用户 ↔ BaoDan 用户映射 |
| recommendation_records | 推荐方案记录 |
| system_operation_logs | 系统操作审计日志 |

### Phase 7（需追加）

| 表名 | 用途 |
|------|------|
| document_metadata | 文档编号/标签/险种/保司 |
| datasource_configs | 保司 API 数据源配置 |
| datasource_sync_logs | 同步日志 |

---

## 环境变量清单

```bash
# .env（BaoDan + 自研共用）
JWT_SECRET=your-secret-key-here          # JWT 签名密钥
WECOM_CORP_ID=ww1234567890              # 企微企业 ID
WECOM_AGENT_ID=1000002                   # 企微应用 AgentID
WECOM_AGENT_SECRET=your-secret           # 企微应用密钥
WECOM_TOKEN=your-callback-token          # 回调消息验证 Token
WECOM_AES_KEY=your-43-char-key           # 消息加密密钥
WECOM_WEBHOOK_URL=https://...            # 告警通知 Webhook（可选）

BAODAN_CHAT_APP_API_KEY=app-xxxxxxxx       # BaoDan 对话应用 API Key
BAODAN_WORKFLOW_APP_API_KEY=app-yyyyyyyy   # BaoDan Workflow 应用 API Key
BAODAN_DATASET_API_KEY=dataset-xxx         # BaoDan 知识库 API Key（可选）
```