wecom_it_smart_desk/docs/07-项目管理/任务说明书/任务说明书-131-快速回复规则后台管理.md

# 任务说明书 - 快速回复规则后台管理

> **版本**: v1.3 | **日期**: 2026-07-28 | **任务ID**: #REQ-通用-002

---

## 📋 基本信息

| 项目 | 内容 |
|------|------|
| **任务名称** | 快速回复规则后台管理 |
| **任务ID** | #REQ-通用-002 |
| **优先级** | 🟡P2 |
| **类型** | 功能开发 |
| **状态** | ✅ 已完成 |
| **负责人** | 宋献 |
| **创建日期** | 2026-07-27 |
| **完成日期** | 2026-07-28 |
| **测试人员** | 宋献 |

---

## 📥 输入项来源

### 产品需求（PRD）
| 来源文档 | 相关章节 | 说明 |
|----------|----------|------|
| `01-产品文档/00-产品规划/PRD-REQ-通用-002-快速回复规则后台管理-v1.2.md` | §1-3 | 需求背景、目标、用户故事（P0/P1/P2） |
| `01-产品文档/00-产品规划/PRD-REQ-通用-002-快速回复规则后台管理-v1.2.md` | §4 | 功能需求详细说明（3 种规则类型） |
| `01-产品文档/00-产品规划/PRD-REQ-通用-002-快速回复规则后台管理-v1.2.md` | §5 | 验收标准 |
| `01-产品文档/00-产品规划/PRD-REQ-通用-002-快速回复规则后台管理-v1.2.md` | §8 | v2.0 扩展规划（置信度阈值/智能体自动优化） |

### 技术方案
| 来源文档 | 相关章节 | 说明 |
|----------|----------|------|
| `02-技术文档/技术方案-REQ-通用-002-快速回复规则后台管理.md` | §3 | 数据库设计（quick_rules + quick_rule_audit_log） |
| `02-技术文档/技术方案-REQ-通用-002-快速回复规则后台管理.md` | §4 | API 设计（12 个端点） |
| `02-技术文档/技术方案-REQ-通用-002-快速回复规则后台管理.md` | §5 | 改造文件列表（ai_handler / routing_service） |
| `02-技术文档/技术方案-REQ-通用-002-快速回复规则后台管理.md` | §9 | v2.0 增量设计（置信度阈值 + 导入导出） |

### 原型设计
| 来源文档 | 页面 | 说明 |
|----------|------|------|
| `01-产品文档/01-02产品设计/快速回复规则后台管理-原型图.html` | 页面1-5 | 规则管理主页 / 子页 4 个 |
| `01-产品文档/01-02产品设计/快速回复规则后台管理-原型图.html` | 页面7 | 智能体审计日志与统计（v2.0） |

### 需了解的现有代码
| 模块/文件 | 说明 |
|-----------|------|
| `app/services/ai_handler.py` — `is_greeting()` | 打招呼检测，需改造为从 DB 加载关键词 |
| `app/services/routing_service.py` — `routing_keyword_prefilter` | 路由预过滤，需改造为从 DB 加载关键词 |
| `app/services/routing_service.py` — `get_routing_target` | 路由目标获取，需改为从 DB 加载 |
| `app/api/router.py` | 需注册 12 个新端点 |
| `app/models/__init__.py` | 需注册 QuickRule + QuickRuleAuditLog 模型 |

---

## 📤 输出成果要求

### 交付物清单

| # | 交付物 | 类型 | 说明 |
|---|--------|------|------|
| 1 | `app/models/quick_rule.py` | 代码 | 规则 ORM 模型（SQLAlchemy 2.0） |
| 2 | `app/models/quick_rule_audit_log.py` | 代码 | 审计日志 ORM 模型 |
| 3 | `app/services/quick_rule_service.py` | 代码 | 规则缓存服务（从 DB 加载 + 降级） |
| 4 | `app/api/admin/quick_rules.py` | 代码 | 12 个 API 端点 |
| 5 | `app/models/__init__.py` | 代码（修改） | 注册新模型 |
| 6 | `app/api/router.py` | 代码（修改） | 注册路由 |
| 7 | `app/main.py` | 代码（修改） | 启动时加载缓存 |
| 8 | `app/services/ai_handler.py` | 代码（修改） | 打招呼检测改造 |
| 9 | `app/services/routing_service.py` | 代码（修改） | 路由服务改造（3 个函数） |
| 10 | `alembic/versions/055_add_quick_rules.py` | DB 迁移 | 创建 quick_rules 表 + 种子数据 |
| 11 | `alembic/versions/056_add_quick_rule_audit_log.py` | DB 迁移 | 创建审计日志表 |
| 12 | `src/frontend-admin/src/api/quickRules.ts` | 代码 | 前端 API 封装（12 个函数） |
| 13 | `src/frontend-admin/src/views/quick-rules/*` | 代码 | 前端页面（主入口 + 5 子页 + 3 组件） |
| 14 | `src/frontend-admin/src/router/index.ts` | 代码（修改） | 注册 6 个新路由 |
| 15 | `src/frontend-admin/src/components/Sidebar.vue` | 代码（修改） | 侧边栏菜单入口 |
| 16 | `scripts/init_quick_rules.sql` | SQL | 数据库初始化数据（53 条） |
| 17 | `scripts/test_quick_rules_api.sh` | 测试 | API 联调脚本（14 个用例） |
| 18 | `tests/test_quick_rules.py` | 测试 | 单元测试（12 个用例） |

---

## 🔧 验证方式

### 功能验证
| 验证项 | 验证方法 | 预期结果 |
|--------|----------|-----------|
| 数据库表创建 | `\d quick_rules` | 表存在，字段完整 |
| 数据播种 | `SELECT rule_type, COUNT(*) FROM quick_rules GROUP BY rule_type` | greeting=12, routing_prefilter=35, routing_target=6 |
| 服务加载 | `docker logs wecom_it_backend \| grep QuickRuleService` | "QuickRuleService 加载完成" |
| 前端页面 | 浏览器访问 `/itadmin/quick-rules` | 页面正常渲染，统计卡片有数据 |
| Tab 切换 | 点击 Tab | 数据即时加载，无"加载失败" |
| 新增/编辑/删除 | 操作规则 | 弹窗正常，数据刷新 |
| 导入/导出 | 批量操作 | JSON 文件导入导出正常 |
| 打招呼检测 | 企微发送"你好" | 返回引导话术 |
| 路由预过滤 | 发送"打印机坏了" | 触发业务路由 |

### 安全验证
| 验证项 | 验证方法 | 预期结果 |
|--------|----------|-----------|
| IP 白名单 | 非白名单 IP 访问 | 返回 4004 |
| Admin 权限 | 非 admin 角色调用 | 403 |

---

## ✅ 完成标准

- [x] 后端 12 个 API 端点实现并注册
- [x] 数据库表创建（quick_rules + quick_rule_audit_log）
- [x] 53 条初始数据播种
- [x] QuickRuleService 缓存加载 + 降级兜底
- [x] 前端 6 个路由 + 侧边栏菜单注册
- [x] 前端页面部署并通过浏览器验证
- [x] 打招呼检测 / 路由预过滤功能改造并向后兼容
- [x] 故障排查手册已更新（v2.8，4 个 CASE）
- [ ] 前端空状态 / Skeleton 加载状态
- [ ] 单元测试通过

---

## 📊 工作分解

| 子任务 | 预估工时 | 状态 |
|--------|----------|------|
| PRD + 原型图 + 技术方案 | 2h | ✅ |
| 后端模型 + API（12 端点） | 3h | ✅ |
| 后端改造（打招呼 + 路由） | 1h | ✅ |
| Alembic 迁移 + SQL 种子 | 0.5h | ✅ |
| 前端 API 封装 | 0.5h | ✅ |
| 前端页面（Tab 式重构） | 2h | ✅ |
| 部署 + 调试（`.data` 兼容 / 路由恢复） | 3h | ✅ |
| 文档补充（任务说明书 + 故障手册） | 1h | ✅ |
| v1.2 UI 整理：删除顶部 3 张重复统计卡片（2026-07-28，宋献） | - | ✅ |
| v1.3 BUG 修复：修复"路由目标"分类筛选 500 错误（2026-07-28，Duckula） | 0.5h | ✅ |

---

## 📞 依赖与阻塞

| 依赖项 | 状态 |
|--------|------|
| jumpserver-V2 skill（部署） | ✅ |
| 前端构建环境（ASCII 路径 `D:\dev\wecom`） | ✅ |
| IP 白名单（`115.227.36.10`） | ✅ |

---

## 📝 踩坑与经验

| 问题 | 根因 | 修复 | CASE 编号 |
|------|------|------|-----------|
| 前端"加载失败" | `.data` 层数不匹配（拦截器已 unwrap，调用处重复取） | 移除 7 处 `.data` | CASE-20260728-01 |
| API 全部 404 | `@/utils/request` 不存在 | 改为 `apiClient` | CASE-20260728-02 |
| 部署后 crash-loop | 远程缺失 meetingroom_guide 等模块 | 注释缺失 import，增量部署 | CASE-20260728-03 |
| 欢迎与引导 404 | CRASHFIX 清理误删路由注册 | 恢复 import + include_router | CASE-20260728-04 |
| "路由目标"分类筛选 500 | Pydantic 序列化失败（priority 字段未声明 Optional + SQL 初始数据缺 priority 列） | 修响应模型 + SQL 补列 + DB 回填 + AST 校验 | CASE-20260728-05 / BUG-通用-002 |

---

## 📈 变更记录

| 日期 | 版本 | 变更内容 | 变更人 | 变更原因 | 影响范围 |
|------|------|----------|--------|----------|----------|
| 2026-07-28 | v1.0 | 创建任务说明书 | 宋献 | 基于已完成工作回溯 | REQ-通用-002 全部交付物 |
| 2026-07-28 | v1.2 | 已完成子任务追加"删除顶部 3 张重复统计卡片"，同步 PRD v1.2 引用 | 宋献 | 页面信息冗余整理 | 管理后台 `/quick-rules` 页面 |
| 2026-07-28 | v1.3 | 追加 BUG-通用-002 修复子任务（QuickRuleResponse Pydantic 序列化失败）；同步 BUG 单、故障手册、整改记录 | Duckula | 用户反馈"路由目标"分类筛选 500 错误 | 后端响应模型 + SQL 初始数据 + 任务说明书 |