ai-robot-core/spec/ai-service/tasks.md

---
feature_id: "AISVC"
title: "Python AI 中台（ai-service）任务清单"
status: "in-progress"
version: "0.7.0"
last_updated: "2026-02-27"
---

# Python AI 中台任务清单（AISVC）

## 1. 任务拆分原则
- **原子性**：每个任务仅解决一个具体技术点或功能逻辑。
- **可验证性**：任务完成后必须可通过单元测试、接口冒烟或契约校验。
- **弱模型可执行**：任务描述清晰，不依赖 AI 猜测业务逻辑。

## 2. 任务执行计划

### Phase 1: 基础设施（FastAPI 框架与多租户基础）
- [x] T1.1 初始化 FastAPI 项目骨架，配置基础环境与日志（包含 X-Tenant-Id 记录） `[AC-AISVC-01]` ✅
- [x] T1.2 实现 `X-Tenant-Id` Header 拦截器，校验必填性并注入 Request State `[AC-AISVC-10, AC-AISVC-12]` ✅
- [x] T1.3 定义基础响应模型 `ErrorResponse` 与异常处理器（Exception Handler） `[AC-AISVC-03, AC-AISVC-04]` ✅
- [x] T1.4 初始化 PostgreSQL 数据库客户端（SQLModel/SQLAlchemy），支持租户隔离查询逻辑 `[AC-AISVC-11]` ✅
- [x] T1.5 初始化 Qdrant 客户端，封装按租户动态选择 Collection 的工具函数 `[AC-AISVC-10]` ✅
- [x] T1.6 实现 `/ai/health` 健康检查接口 `[AC-AISVC-20]` ✅

### Phase 2: 存储与检索实现（Memory & Retrieval）
- [x] T2.1 实现 Memory 层：定义 `chat_sessions` 与 `chat_messages` SQLModel 实体 `[AC-AISVC-13]` ✅
- [x] T2.2 实现 Memory 层：完成基于 `(tenant_id, session_id)` 的历史消息加载与追加 API `[AC-AISVC-13]` ✅
- [x] T2.3 实现 Retrieval 层：定义 `BaseRetriever` 抽象基类（插件点预留） `[AC-AISVC-16]` ✅
- [x] T2.4 实现 `VectorRetriever`：集成 `qdrant-client` 完成向量检索，支持 scoreThreshold 过滤 `[AC-AISVC-16, AC-AISVC-17]` ✅
- [x] T2.5 编写 Memory 与 Retrieval 层的独立单元测试（Mock 数据库与向量库） `[AC-AISVC-10, AC-AISVC-11]` ✅

### Phase 3: 核心编排（Orchestrator & LLM Adapter）
- [x] T3.1 实现 LLM Adapter：封装 `langchain-openai` 或官方 SDK，支持 `generate` 与 `stream_generate` `[AC-AISVC-02, AC-AISVC-06]` ✅
- [x] T3.2 实现 Orchestrator：实现上下文合并逻辑（H_local + H_ext 的去重与截断策略） `[AC-AISVC-14, AC-AISVC-15]` ✅
- [x] T3.3 实现 Orchestrator：实现 RAG 检索不足时的置信度下调与 `shouldTransfer` 逻辑 `[AC-AISVC-17, AC-AISVC-18, AC-AISVC-19]` ✅
- [x] T3.4 实现 Orchestrator：整合 Memory、Retrieval 与 LLM 完成 non-streaming 生成闭环 `[AC-AISVC-01, AC-AISVC-02]` ✅
- [x] T3.5 验证 non-streaming 响应字段完全符合 `openapi.provider.yaml` 契约 `[AC-AISVC-02]` ✅

### Phase 4: 流式响应（SSE 实现与状态机）
- [x] T4.1 在 API 层实现基于 `Accept` 头的响应模式自动切换逻辑 `[AC-AISVC-06]` ✅
- [x] T4.2 实现 SSE 事件生成器：根据 Orchestrator 的增量输出包装 `message` 事件 `[AC-AISVC-07]` ✅
- [x] T4.3 实现 SSE 状态机：确保 `final` 或 `error` 事件后连接正确关闭，且顺序不乱 `[AC-AISVC-08, AC-AISVC-09]` ✅
- [x] T4.4 实现流式输出过程中的异常捕获，并转化为 `event: error` 输出 `[AC-AISVC-09]` ✅

### Phase 5: 集成与冒烟测试（Quality Assurance）
- [x] T5.1 编写集成测试：模拟多租户并发请求，验证数据存储与检索的严格物理/逻辑隔离 `[AC-AISVC-10, AC-AISVC-11]` ✅
- [x] T5.2 编写 RAG 冒烟测试：模拟"检索命中"与"检索未命中"两种场景，验证 confidence 变化与回复兜底 `[AC-AISVC-17, AC-AISVC-18]` ✅
- [x] T5.3 契约测试：验证 provider 契约一致性 `[AC-AISVC-01, AC-AISVC-02]` ✅

### Phase 6: 前后端联调真实对接（v0.2.0 迭代）
- [x] T6.1 定义知识库相关实体：`KnowledgeBase`、`Document`、`IndexJob` SQLModel 实体 `[AC-AISVC-21, AC-AISVC-22, AC-AISVC-23, AC-AISVC-24]` ✅
- [x] T6.2 实现 `KBService`：文档上传、存储、列表查询、索引任务状态查询 `[AC-AISVC-21, AC-AISVC-23, AC-AISVC-24]` ✅
- [x] T6.3 实现知识库管理 API：`POST /admin/kb/documents` 真实文件存储与异步索引 `[AC-AISVC-21, AC-AISVC-22]` ✅
- [x] T6.4 实现知识库管理 API：`GET /admin/kb/documents` 真实数据库查询 `[AC-AISVC-23]` ✅
- [x] T6.5 实现知识库管理 API：`GET /admin/kb/index/jobs/{jobId}` 真实任务状态查询 `[AC-AISVC-24]` ✅
- [x] T6.6 实现 RAG 实验室 API：`POST /admin/rag/experiments/run` 真实向量检索 `[AC-AISVC-25, AC-AISVC-26]` ✅
- [x] T6.7 实现会话监控 API：`GET /admin/sessions` 真实会话列表查询 `[AC-AISVC-27]` ✅
- [x] T6.8 实现会话监控 API：`GET /admin/sessions/{sessionId}` 真实会话详情查询 `[AC-AISVC-28]` ✅
- [x] T6.9 前后端联调验证：确认前端页面正常调用后端真实接口 ✅

---

## 3. 待澄清（Open Questions）

> ✅ 已确认：以下事项均已由产品/架构反馈确认，可直接作为实现基准。

1. ✅ **Collection 初始化**：采用**提前预置**模式，不通过业务请求动态创建。
2. ✅ **超时策略**：Python 内部设置 **20s 硬超时**，防止资源泄露与请求堆积。
3. ✅ **SSE 心跳**：必须实现 `: ping` 机制（Keep-alive），防止网关/中间件断开连接。
4. ✅ **置信度**：MVP 优先基于 RAG 检索分数（Score）计算 `confidence`。
5. ✅ **Token 计数**：统一使用 `tiktoken` 库进行精确 Token 计数（用于 history 截断与证据预算）。

---

## 4. 任务状态说明
- ⏳ 待处理 (Pending)
- 🔄 进行中 (In Progress)
- ✅ 已完成 (Completed)
- ❌ 已取消 (Cancelled)

---

## 5. 完成总结

**Phase 1-10 已全部完成，Phase 12-14 部分完成**

| Phase | 描述 | 任务数 | 状态 |
|-------|------|--------|------|
| Phase 1 | 基础设施 | 6 | ✅ 完成 |
| Phase 2 | 存储与检索 | 5 | ✅ 完成 |
| Phase 3 | 核心编排 | 5 | ✅ 完成 |
| Phase 4 | 流式响应 | 4 | ✅ 完成 |
| Phase 5 | 集成测试 | 3 | ✅ 完成 |
| Phase 6 | 前后端联调真实对接 | 9 | ✅ 完成 |
| Phase 7 | 嵌入模型可插拔与文档解析 | 21 | ✅ 完成 |
| Phase 8 | LLM 配置与 RAG 调试输出 | 10 | ✅ 完成 |
| Phase 9 | 租户管理与 RAG 优化 | 10 | ✅ 完成 |
| Phase 10 | Prompt 模板化 | 10 | 🔄 进行中 (8/10) |
| Phase 11 | 多知识库管理 | 8 | 🔄 进行中 (5/8) |
| Phase 12 | 意图识别与规则引擎 | 7 | 🔄 进行中 (5/7) |
| Phase 13 | 话术流程引擎 | 7 | 🔄 进行中 (6/7) |
| Phase 14 | 输出护栏 | 8 | 🔄 进行中 (7/8) |
| Phase 15 | 智能 RAG 增强与编排升级 | 8 | ⏳ 待处理 |

**已完成: 98 个任务**

---

### Phase 7: 嵌入模型可插拔与文档解析支持（v0.3.0 迭代）
- [x] T7.1 设计 `EmbeddingProvider` 抽象基类：定义 `embed()`、`embed_batch()`、`get_dimension()` 接口 `[AC-AISVC-29]` ✅
- [x] T7.2 实现 `EmbeddingProviderFactory` 工厂类：支持根据配置动态加载提供者 `[AC-AISVC-30]` ✅
- [x] T7.3 实现 `OllamaEmbeddingProvider`：封装 Ollama API 调用 `[AC-AISVC-29, AC-AISVC-30]` ✅
- [x] T7.4 实现 `OpenAIEmbeddingProvider`：封装 OpenAI Embedding API `[AC-AISVC-29, AC-AISVC-30]` ✅
- [x] T7.5 实现嵌入配置管理：支持动态配置与热更新 `[AC-AISVC-31]` ✅
- [x] T7.6 实现嵌入模型错误处理与 fallback 策略 `[AC-AISVC-32]` ✅
- [x] T7.7 实现 `DocumentParser` 抽象接口：定义 `parse()` 方法返回纯文本 `[AC-AISVC-33]` ✅
- [x] T7.8 实现 `PDFParser`：使用 PyMuPDF/pdfplumber 解析 PDF `[AC-AISVC-33]` ✅
- [x] T7.9 实现 `WordParser`：使用 python-docx 解析 Word 文档 `[AC-AISVC-34]` ✅
- [x] T7.10 实现 `ExcelParser`：使用 openpyxl 解析 Excel 文档 `[AC-AISVC-35]` ✅
- [x] T7.11 实现 `DocumentParserFactory`：根据文件扩展名选择解析器 `[AC-AISVC-33, AC-AISVC-34, AC-AISVC-35]` ✅
- [x] T7.12 实现文档解析错误处理与格式校验 `[AC-AISVC-36, AC-AISVC-37]` ✅
- [x] T7.13 实现 `GET /admin/embedding/providers` API：返回可用提供者列表 `[AC-AISVC-38]` ✅
- [x] T7.14 实现 `GET /admin/embedding/config` API：返回当前配置 `[AC-AISVC-39]` ✅
- [x] T7.15 实现 `PUT /admin/embedding/config` API：更新配置 `[AC-AISVC-40]` ✅
- [x] T7.16 实现 `POST /admin/embedding/test` API：测试嵌入连接 `[AC-AISVC-41]` ✅
- [x] T7.17 集成嵌入服务到索引流程：替换现有硬编码 Ollama 调用 `[AC-AISVC-29]` ✅
- [x] T7.18 集成文档解析到上传流程：支持多格式文档上传 `[AC-AISVC-33, AC-AISVC-34, AC-AISVC-35]` ✅
- [x] T7.19 编写嵌入服务单元测试 `[AC-AISVC-29, AC-AISVC-30, AC-AISVC-31, AC-AISVC-32]` ✅
- [x] T7.20 编写文档解析单元测试 `[AC-AISVC-33, AC-AISVC-34, AC-AISVC-35, AC-AISVC-36, AC-AISVC-37]` ✅
- [x] T7.21 编写嵌入管理 API 集成测试 `[AC-AISVC-38, AC-AISVC-39, AC-AISVC-40, AC-AISVC-41]` ✅

---

### Phase 8: LLM 配置与 RAG 调试输出（v0.4.0 迭代）
- [x] T8.1 设计 `LLMProviderFactory` 工厂类：支持根据配置动态加载提供者 `[AC-AISVC-42]` ✅
- [x] T8.2 实现 `LLMConfigManager` 配置管理：支持动态配置与热更新 `[AC-AISVC-43, AC-AISVC-44]` ✅
- [x] T8.3 实现 `GET /admin/llm/providers` API：返回可用提供者列表 `[AC-AISVC-42]` ✅
- [x] T8.4 实现 `GET /admin/llm/config` API：返回当前配置 `[AC-AISVC-43]` ✅
- [x] T8.5 实现 `PUT /admin/llm/config` API：更新配置 `[AC-AISVC-44]` ✅
- [x] T8.6 实现 `POST /admin/llm/test` API：测试 LLM 连接 `[AC-AISVC-45, AC-AISVC-46]` ✅
- [x] T8.7 更新 RAG 实验接口：支持 AI 回复生成 `[AC-AISVC-47, AC-AISVC-49]` ✅
- [x] T8.8 实现 RAG 实验流式输出：SSE 流式 AI 回复 `[AC-AISVC-48]` ✅
- [x] T8.9 支持指定 LLM 提供者：RAG 实验可选择不同 LLM `[AC-AISVC-50]` ✅
- [x] T8.10 更新 OpenAPI 契约：添加 LLM 管理和 RAG 实验增强接口 ✅

---

### Phase 9: 租户管理与 RAG 优化（v0.5.0 迭代）
- [x] T9.1 实现 `Tenant` 实体：定义租户数据模型 `[AC-AISVC-10]` ✅
- [x] T9.2 实现租户 ID 格式校验：`name@ash@year` 格式验证 `[AC-AISVC-10, AC-AISVC-12]` ✅
- [x] T9.3 实现租户自动创建：请求时自动创建不存在的租户 `[AC-AISVC-10]` ✅
- [x] T9.4 实现 `GET /admin/tenants` API：返回租户列表 `[AC-AISVC-10]` ✅
- [x] T9.5 前端租户选择器：实现租户切换功能 `[AC-ASA-01]` ✅
- [x] T9.6 文档多编码支持：支持 UTF-8、GBK、GB2312 等编码解码 `[AC-AISVC-21]` ✅
- [x] T9.7 按行分块功能：实现 `chunk_text_by_lines` 函数 `[AC-AISVC-22]` ✅
- [x] T9.8 实现 `NomicEmbeddingProvider`：支持多维度向量 `[AC-AISVC-29]` ✅
- [x] T9.9 实现多向量存储：支持 full/256/512 三种维度 `[AC-AISVC-16]` ✅
- [x] T9.10 实现 `KnowledgeIndexer`：优化的知识库索引服务 `[AC-AISVC-22]` ✅

---

### Phase 10: Prompt 模板化（v0.6.0 迭代）

> 目标：将硬编码的 SYSTEM_PROMPT 改为数据库驱动的模板系统，支持按租户配置人设、版本管理、热更新。

- [x] T10.1 定义 `PromptTemplate` 和 `PromptTemplateVersion` SQLModel 实体，创建数据库表 `[AC-AISVC-51, AC-AISVC-52]` ✅
- [x] T10.2 实现 `PromptTemplateService`：模板 CRUD（创建、查询列表、查询详情、更新） `[AC-AISVC-52, AC-AISVC-57, AC-AISVC-58]` ✅
- [x] T10.3 实现模板版本管理：更新时自动创建新版本，保留历史版本 `[AC-AISVC-53]` ✅
- [x] T10.4 实现模板发布与回滚：`publish` 将指定版本标记为已发布，`rollback` 恢复历史版本 `[AC-AISVC-54, AC-AISVC-55]` ✅
- [x] T10.5 实现 `VariableResolver`：内置变量注入（persona_name/current_time/channel_type 等）+ 自定义变量替换 `[AC-AISVC-56]` ✅
- [x] T10.6 实现模板缓存：内存缓存 + TTL 过期 + 发布/回滚时主动失效，fallback 到硬编码 SYSTEM_PROMPT `[AC-AISVC-51]` ✅
- [x] T10.7 实现 Prompt 模板管理 API：`POST/GET/PUT /admin/prompt-templates`，`GET /admin/prompt-templates/{tplId}` `[AC-AISVC-52, AC-AISVC-57, AC-AISVC-58]` ✅
- [x] T10.8 实现 Prompt 模板发布/回滚 API：`POST /admin/prompt-templates/{tplId}/publish`，`POST /admin/prompt-templates/{tplId}/rollback` `[AC-AISVC-54, AC-AISVC-55]` ✅
- [ ] T10.9 修改 Orchestrator 的 `_build_llm_messages()`：从模板服务加载系统指令替代硬编码 `[AC-AISVC-56]`
- [ ] T10.10 编写 Prompt 模板服务单元测试 `[AC-AISVC-51~AC-AISVC-58]`

---

### Phase 11: 多知识库管理（v0.6.0 迭代）

> 目标：从单个 kb_default 升级为多知识库分类管理，支持按类型和优先级组织知识。

- [x] T11.1 扩展 `KnowledgeBase` 实体：新增 `kb_type`、`priority`、`is_enabled`、`doc_count` 字段 `[AC-AISVC-59]` ✅
- [x] T11.2 实现知识库 CRUD 服务：创建时初始化 Qdrant Collection，删除时清理 Collection `[AC-AISVC-59, AC-AISVC-61, AC-AISVC-62]` ✅
- [x] T11.3 实现知识库管理 API：`POST/GET/PUT/DELETE /admin/kb/knowledge-bases` `[AC-AISVC-59, AC-AISVC-60, AC-AISVC-61, AC-AISVC-62]` ✅
- [x] T11.4 升级 Qdrant Collection 命名：`kb_{tenant_id}_{kb_id}`，兼容现有 `kb_{tenant_id}` `[AC-AISVC-63]` ✅
- [x] T11.5 修改文档上传流程：支持指定 `kbId` 参数，索引到对应 Collection `[AC-AISVC-63]` ✅
- [ ] T11.6 修改 `OptimizedRetriever`：支持 `target_kb_ids` 参数，实现多 Collection 并行检索 `[AC-AISVC-64]`
- [ ] T11.7 实现 `kb_default` 自动迁移：首次启动时为现有数据创建默认知识库记录 `[AC-AISVC-59]`
- [ ] T11.8 编写多知识库服务单元测试 `[AC-AISVC-59~AC-AISVC-64]`

---

### Phase 12: 意图识别与规则引擎（v0.6.0 迭代）

> 目标：实现基于关键词+正则的意图识别，根据意图路由到不同处理链路。

- [x] T12.1 定义 `IntentRule` SQLModel 实体，创建数据库表 `[AC-AISVC-65]` ✅
- [x] T12.2 实现 `IntentRuleService`：规则 CRUD + 命中统计更新 `[AC-AISVC-65, AC-AISVC-66, AC-AISVC-67, AC-AISVC-68]` ✅
- [x] T12.3 实现 `IntentRouter`：按优先级遍历规则，关键词匹配 + 正则匹配，返回 `IntentMatchResult` `[AC-AISVC-69]` ✅
- [x] T12.4 实现规则缓存：按 tenant_id 缓存规则列表，CRUD 操作时主动失效 `[AC-AISVC-69]` ✅
- [x] T12.5 实现意图规则管理 API：`POST/GET/PUT/DELETE /admin/intent-rules` `[AC-AISVC-65, AC-AISVC-66, AC-AISVC-67, AC-AISVC-68]` ✅
- [ ] T12.6 在 Orchestrator 中集成 IntentRouter：RAG 检索前执行意图识别，按 response_type 路由 `[AC-AISVC-69, AC-AISVC-70]`
- [ ] T12.7 编写意图识别服务单元测试 `[AC-AISVC-65~AC-AISVC-70]`

---

### Phase 13: 话术流程引擎（v0.6.0 迭代）

> 目标：实现固定话术步骤的状态机引擎，支持多轮引导对话。

- [x] T13.1 定义 `ScriptFlow` 和 `FlowInstance` SQLModel 实体，创建数据库表 `[AC-AISVC-71, AC-AISVC-74]` ✅
- [x] T13.2 实现 `ScriptFlowService`：流程定义 CRUD `[AC-AISVC-71, AC-AISVC-72, AC-AISVC-73]` ✅
- [x] T13.3 实现 `FlowEngine.check_active_flow()`：检查会话是否有活跃流程实例 `[AC-AISVC-75]` ✅
- [x] T13.4 实现 `FlowEngine.start()`：创建流程实例，返回第一步话术 `[AC-AISVC-74]` ✅
- [x] T13.5 实现 `FlowEngine.advance()`：根据用户输入匹配条件，推进步骤或重复当前步骤 `[AC-AISVC-75, AC-AISVC-76]` ✅
- [x] T13.6 实现话术流程管理 API：`POST/GET/PUT /admin/script-flows` `[AC-AISVC-71, AC-AISVC-72, AC-AISVC-73]` ✅
- [ ] T13.7 编写话术流程引擎单元测试 `[AC-AISVC-71~AC-AISVC-77]`

---

### Phase 14: 输出护栏（v0.6.0 迭代）

> 目标：实现禁词检测与内容过滤，保障 AI 输出合规可控。

- [x] T14.1 定义 `ForbiddenWord` 和 `BehaviorRule` SQLModel 实体，创建数据库表 `[AC-AISVC-78, AC-AISVC-84]` ✅
- [x] T14.2 实现 `ForbiddenWordService`：禁词 CRUD + 命中统计 `[AC-AISVC-78, AC-AISVC-79, AC-AISVC-80, AC-AISVC-81]` ✅
- [x] T14.3 实现 `BehaviorRuleService`：行为规则 CRUD `[AC-AISVC-84, AC-AISVC-85]` ✅
- [x] T14.4 实现 `InputScanner`：用户输入前置禁词检测（仅记录，不阻断） `[AC-AISVC-83]` ✅
- [x] T14.5 实现 `OutputFilter`：LLM 输出后置过滤（mask/replace/block 三种策略） `[AC-AISVC-82]` ✅
- [x] T14.6 实现 Streaming 模式下的滑动窗口禁词检测 `[AC-AISVC-82]` ✅
- [x] T14.7 实现护栏管理 API：`POST/GET/PUT/DELETE /admin/guardrails/forbidden-words`，`POST/GET /admin/guardrails/behavior-rules` `[AC-AISVC-78~AC-AISVC-85]` ✅
- [ ] T14.8 编写输出护栏服务单元测试 `[AC-AISVC-78~AC-AISVC-85]`

---

### Phase 15: 智能 RAG 增强与编排升级（v0.6.0 迭代）

> 目标：Query 改写、分层排序、行为规则注入、Orchestrator 升级为 12 步 pipeline。

- [ ] T15.1 实现 `QueryRewriter`：基于 LLM 的 Query 改写（解析指代词、补全语义），支持配置开关 `[AC-AISVC-86]`
- [ ] T15.2 实现 `ResultRanker`：按知识库类型优先级 + 自定义权重 + 相似度分数的多维排序 `[AC-AISVC-87]`
- [ ] T15.3 实现话术模板优先匹配：script 类型高分命中时优先作为回复参考 `[AC-AISVC-88]`
- [ ] T15.4 实现行为规则注入到 Prompt：从 BehaviorRuleService 加载规则，追加到系统指令末尾 `[AC-AISVC-84]`
- [ ] T15.5 升级 Orchestrator：整合 InputScanner → FlowEngine → IntentRouter → QueryRewriter → 多知识库检索 → ResultRanker → PromptBuilder → LLM → OutputFilter 完整 12 步 pipeline `[AC-AISVC-69, AC-AISVC-64, AC-AISVC-82, AC-AISVC-86, AC-AISVC-87]`
- [ ] T15.6 预留 `AudioParser` 和 `VideoParser` 扩展点（仅接口定义，不实现） `[AC-AISVC-89]`
- [ ] T15.7 预留对话记录结构化导入接口（仅接口定义，不实现） `[AC-AISVC-90]`
- [ ] T15.8 编写 Orchestrator 升级集成测试：验证意图路由 → 流程引擎 → 多知识库检索 → 护栏过滤的完整链路 `[AC-AISVC-51~AC-AISVC-90]`


---

### Phase 16: 测试与监控系统（v0.7.0 迭代）

> 目标：为 v0.6.0 新增的四大功能提供完整的测试和监控 API，支持前端测试台和监控页面。

#### 16.1 监控数据模型与基础设施

- [ ] T16.1 定义监控数据实体：扩展 `ChatMessage` 实体，新增 `prompt_template_id`、`intent_rule_id`、`flow_instance_id`、`guardrail_triggered`、`guardrail_words` 字段 `[AC-AISVC-91, AC-AISVC-92]`

- [ ] T16.2 实现 Redis 统计缓存层：创建 `MonitoringCache` 服务，支持实时计数器和 Top N 排行榜缓存 `[AC-AISVC-91, AC-AISVC-92]`

- [ ] T16.3 实现 `FlowTestRecord` 实体：用于存储完整流程测试的详细日志（保留 7 天） `[AC-AISVC-93, AC-AISVC-94, AC-AISVC-95]`

- [ ] T16.4 实现 `ExportTask` 实体：用于管理对话导出任务的异步处理 `[AC-AISVC-110]`

- [ ] T16.5 创建监控数据库索引：优化查询性能（按 tenant_id、created_at、intent_rule_id、flow_instance_id 等） `[AC-AISVC-91~AC-AISVC-110]`

#### 16.2 Dashboard 统计增强

- [ ] T16.6 实现 `DashboardService.get_enhanced_stats()`：聚合意图规则、Prompt 模板、话术流程、护栏的统计数据 `[AC-AISVC-91]`

- [ ] T16.7 实现统计数据缓存策略：Dashboard 统计结果缓存 60 秒，Top N 排行榜每 5 分钟预计算 `[AC-AISVC-91]`

- [ ] T16.8 实现 `GET /admin/dashboard/stats` API 增强：支持时间范围筛选（startDate/endDate 参数） `[AC-AISVC-91, AC-AISVC-92]`

#### 16.3 完整流程测试台

- [ ] T16.9 增强 `Orchestrator.generate_with_monitoring()`：支持可选的详细日志记录（enable_detailed_log 参数） `[AC-AISVC-93]`

- [ ] T16.10 实现 12 步流程埋点：在 Orchestrator 的每一步中记录输入/输出/耗时/错误（仅在测试模式下） `[AC-AISVC-93, AC-AISVC-94, AC-AISVC-95]`

- [ ] T16.11 实现 `FlowTestService.test_flow_execution()`：调用增强版 Orchestrator 并保存测试记录 `[AC-AISVC-93]`

- [ ] T16.12 实现 `POST /admin/test/flow-execution` API：支持完整流程测试，返回 12 步执行详情 `[AC-AISVC-93, AC-AISVC-94, AC-AISVC-95]`

#### 16.4 意图规则测试与监控

- [ ] T16.13 实现 `IntentRuleTester.test_rule()`：测试单个规则并检测优先级冲突 `[AC-AISVC-96]`

- [ ] T16.14 实现 `POST /admin/intent-rules/{ruleId}/test` API：返回测试结果和冲突检测 `[AC-AISVC-96]`

- [ ] T16.15 实现 `IntentMonitor.get_rule_stats()`：聚合规则命中统计（命中次数、命中率、平均响应时间） `[AC-AISVC-97]`

- [ ] T16.16 实现 `GET /admin/monitoring/intent-rules` API：返回规则统计列表，支持时间范围筛选 `[AC-AISVC-97]`

- [ ] T16.17 实现 `GET /admin/monitoring/intent-rules/{ruleId}/hits` API：返回规则命中记录详情，支持分页 `[AC-AISVC-98]`

#### 16.5 Prompt 模板测试与监控

- [ ] T16.18 实现 `PromptTemplateMonitor.preview_template()`：渲染模板并计算 Token 数量（使用 tiktoken） `[AC-AISVC-99]`

- [ ] T16.19 实现 `POST /admin/prompt-templates/{tplId}/preview` API：返回渲染结果和 Token 统计 `[AC-AISVC-99]`

- [ ] T16.20 实现 `PromptMonitor.get_template_stats()`：聚合模板使用统计（使用次数、平均 Token 消耗） `[AC-AISVC-100]`

- [ ] T16.21 实现 `GET /admin/monitoring/prompt-templates` API：返回模板统计列表，支持按场景筛选 `[AC-AISVC-100]`

#### 16.6 话术流程测试与监控

- [ ] T16.22 实现 `ScriptFlowTester.simulate_flow()`：模拟流程执行并分析覆盖率 `[AC-AISVC-101]`

- [ ] T16.23 实现 `POST /admin/script-flows/{flowId}/simulate` API：创建模拟会话并返回首步话术 `[AC-AISVC-101]`

- [ ] T16.24 实现 `POST /admin/script-flows/{flowId}/simulate/{simulationId}/next` API：推进模拟流程 `[AC-AISVC-102]`

- [ ] T16.25 实现 `FlowMonitor.get_flow_stats()`：聚合流程激活统计（激活次数、完成率、平均完成时长） `[AC-AISVC-103]`

- [ ] T16.26 实现 `GET /admin/monitoring/script-flows` API：返回流程统计列表 `[AC-AISVC-103]`

- [ ] T16.27 实现 `GET /admin/monitoring/script-flows/{flowId}/executions` API：返回流程执行记录详情，支持分页 `[AC-AISVC-104]`

#### 16.7 输出护栏测试与监控

- [ ] T16.28 实现 `GuardrailTester.test_guardrail()`：测试禁词检测和过滤策略 `[AC-AISVC-105]`

- [ ] T16.29 实现 `POST /admin/guardrails/test` API：返回护栏检测结果 `[AC-AISVC-105]`

- [ ] T16.30 实现 `GuardrailMonitor.get_guardrail_stats()`：聚合护栏拦截统计（拦截次数、替换次数、掩码次数） `[AC-AISVC-106]`

- [ ] T16.31 实现 `GET /admin/monitoring/guardrails` API：返回护栏统计列表，支持按类别筛选 `[AC-AISVC-106]`

- [ ] T16.32 实现 `GET /admin/monitoring/guardrails/{wordId}/blocks` API：返回禁词拦截记录详情，支持分页 `[AC-AISVC-107]`

#### 16.8 对话追踪与导出

- [ ] T16.33 实现 `ConversationTracker.get_conversations()`：查询对话记录列表，支持多条件筛选和分页 `[AC-AISVC-108]`

- [ ] T16.34 实现 `GET /admin/monitoring/conversations` API：返回对话记录列表 `[AC-AISVC-108]`

- [ ] T16.35 实现 `ConversationTracker.get_conversation_detail()`：查询对话的完整 12 步执行链路 `[AC-AISVC-109]`

- [ ] T16.36 实现 `GET /admin/monitoring/conversations/{conversationId}` API：返回对话执行链路详情 `[AC-AISVC-109]`

- [ ] T16.37 实现 `ConversationExporter.export_conversations()`：异步导出对话数据（CSV/JSON 格式） `[AC-AISVC-110]`

- [ ] T16.38 实现 `POST /admin/monitoring/conversations/export` API：创建导出任务并返回任务 ID `[AC-AISVC-110]`

- [ ] T16.39 实现 `GET /admin/monitoring/conversations/export/{exportId}` API：查询导出任务状态和下载链接 `[AC-AISVC-110]`

#### 16.9 性能优化与测试

- [ ] T16.40 实现监控数据异步更新：对话结束时异步更新统计计数器，不阻塞响应 `[AC-AISVC-91, AC-AISVC-92]`

- [ ] T16.41 实现测试日志自动清理：定时任务清理 7 天前的 `FlowTestRecord` 数据 `[AC-AISVC-93]`

- [ ] T16.42 实现导出文件自动清理：定时任务清理 24 小时过期的导出文件 `[AC-AISVC-110]`

- [ ] T16.43 编写监控服务单元测试：覆盖统计聚合、缓存策略、数据导出等核心逻辑 `[AC-AISVC-91~AC-AISVC-110]`

- [ ] T16.44 编写测试 API 集成测试：验证完整流程测试、规则测试、模板预览等功能 `[AC-AISVC-93~AC-AISVC-105]`

- [ ] T16.45 性能测试：验证监控埋点对生产环境性能影响 <5%，Dashboard 统计查询 <500ms `[AC-AISVC-91, AC-AISVC-92]`

---

## Phase 16 任务进度追踪

| 任务 | 描述 | 状态 |
|------|------|------|
| T16.1 | 监控数据实体扩展 | ⏳ 待处理 |
| T16.2 | Redis 统计缓存层 | ⏳ 待处理 |
| T16.3 | FlowTestRecord 实体 | ⏳ 待处理 |
| T16.4 | ExportTask 实体 | ⏳ 待处理 |
| T16.5 | 监控数据库索引 | ⏳ 待处理 |
| T16.6 | Dashboard 统计聚合 | ⏳ 待处理 |
| T16.7 | 统计缓存策略 | ⏳ 待处理 |
| T16.8 | Dashboard API 增强 | ⏳ 待处理 |
| T16.9 | Orchestrator 监控增强 | ⏳ 待处理 |
| T16.10 | 12 步流程埋点 | ⏳ 待处理 |
| T16.11 | FlowTestService | ⏳ 待处理 |
| T16.12 | 完整流程测试 API | ⏳ 待处理 |
| T16.13 | IntentRuleTester | ⏳ 待处理 |
| T16.14 | 意图规则测试 API | ⏳ 待处理 |
| T16.15 | IntentMonitor | ⏳ 待处理 |
| T16.16 | 意图规则监控 API | ⏳ 待处理 |
| T16.17 | 规则命中记录 API | ⏳ 待处理 |
| T16.18 | PromptTemplateMonitor | ⏳ 待处理 |
| T16.19 | 模板预览 API | ⏳ 待处理 |
| T16.20 | PromptMonitor | ⏳ 待处理 |
| T16.21 | 模板监控 API | ⏳ 待处理 |
| T16.22 | ScriptFlowTester | ⏳ 待处理 |
| T16.23 | 流程模拟 API | ⏳ 待处理 |
| T16.24 | 流程推进 API | ⏳ 待处理 |
| T16.25 | FlowMonitor | ⏳ 待处理 |
| T16.26 | 流程监控 API | ⏳ 待处理 |
| T16.27 | 流程执行记录 API | ⏳ 待处理 |
| T16.28 | GuardrailTester | ⏳ 待处理 |
| T16.29 | 护栏测试 API | ⏳ 待处理 |
| T16.30 | GuardrailMonitor | ⏳ 待处理 |
| T16.31 | 护栏监控 API | ⏳ 待处理 |
| T16.32 | 护栏拦截记录 API | ⏳ 待处理 |
| T16.33 | ConversationTracker | ⏳ 待处理 |
| T16.34 | 对话追踪列表 API | ⏳ 待处理 |
| T16.35 | 对话详情查询 | ⏳ 待处理 |
| T16.36 | 对话详情 API | ⏳ 待处理 |
| T16.37 | ConversationExporter | ⏳ 待处理 |
| T16.38 | 对话导出 API | ⏳ 待处理 |
| T16.39 | 导出状态查询 API | ⏳ 待处理 |
| T16.40 | 异步统计更新 | ⏳ 待处理 |
| T16.41 | 测试日志清理 | ⏳ 待处理 |
| T16.42 | 导出文件清理 | ⏳ 待处理 |
| T16.43 | 监控服务单元测试 | ⏳ 待处理 |
| T16.44 | 测试 API 集成测试 | ⏳ 待处理 |
| T16.45 | 性能测试 | ⏳ 待处理 |