simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
a8da4da0db37cac26870c6a06b8ec25c5b38ef79
wecom_it_smart_desk/docs/07-项目管理/任务说明书/任务说明书-131-快速回复规则后台管理.md
T
Simon 44e77dcb0e chore(docs): docs/ 目录全面重新编号 + 重组 
**重构前**（旧编号 02-11）：
- docs/02-产品需求/      → 00 产品规划/PRD
- docs/03-技术架构/      → 01-05 子目录散落
- docs/04-原型设计/      → 01-02 产品设计（HTML 原型）
- docs/05-原型设计/      → screens/
- docs/06-测试素材/      → 02-E2E / 03-功能 / 04-版本测试
- docs/07-项目管理/      → 任务说明书/日报/计划
- docs/08-安全审计/      → 审计报告
- docs/09-堡垒运维/      → toolbox / deploy
- docs/10-项目管理/      → 任务说明书（重复）
- docs/11-历史归档/      → deploy-nas-archived

**重构后**（新编号 00-07，语义化）：
- docs/00-产品开发流程与文档管理规范.md
- docs/00-版本迭代总览.md
- docs/01-产品文档/      （PRD/原型/认证/会话/AI 服务/坐席/集成）
- docs/02-技术文档/      （技术方案/架构图/重构记录/前端改造/实现配置）
- docs/03-测试文档/      （E2E/功能用例/版本报告/缺陷单）
- docs/04-运维文档/      （部署运维/运维指南）
- docs/05-运营文档/      （品牌推广/用户手册）
- docs/06-安全审计/      （审计报告）
- docs/07-项目管理/      （任务说明书/日报/计划/看板）

**净收益**：
- 目录编号与产品文档管理规范对齐（按文档阶段 01-07 编号）
- 消除 02-产品需求 与 10-项目管理 的编号重叠
- 子目录按文档类型分组（如 01-产品文档/00-产品规划、01-产品文档/01-认证与登录）
- 把运维/安全/项目管理从 0X 散落改为 04/06/07

合计 494 文件 + 78495 行 / - 14076 行
2026-08-03 18:46:55 +08:00

169 lines
8.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 任务说明书 - 快速回复规则后台管理
> **版本**: 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 初始数据 + 任务说明书 |
Reference in New Issue View Git Blame Copy Permalink