simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6be361fb63783520f5dcfd7cce386ac9b5523d4f
wecom_it_smart_desk/docs/07-项目管理/任务说明书/任务说明书-131-快速回复规则后台管理.md
T
Simon facc04aa65 chore: docs 结构整改 + compose 双目录对齐（合并重建提交） 
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交
（5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。

一、docs 结构整改（整改 #14）
根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入，
随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录
树并存于 docs/，共 791 文件、双分类体系冲突。

修复动作：
- b2 同名异主题文件改名迁移保全 9 个
- C 类 39 个孤立文件按主题正确归类
- A/B1 类 222 个重复文件删除（新结构已有内容副本）
- 9 个旧独有空目录删除
- 270 处内部引用按 verified 映射改写
- 整改记录 #14 登记于 04-运维文档/部署运维

结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。
残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。

二、compose 双目录对齐（消除踩坑 A）
- docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist
  改为 src/frontend-*/dist（h5 / agent / admin / terminal）
- docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/
- 效果：本地 docker compose up 不再把根目录 stale dist 挂回，
  与线上一致，分叉隐患消除（已 docker compose config 校验通过）

防复发铁律：
- 重构须提交；仓库修复须 git stash -u 或先 commit
- 新结构须 git add 并提交，避免再次 untracked 复活
- H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
2026-08-07 22:31:32 +08:00

8.3 KiB
Raw Blame History

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

版本: 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

✅ 完成标准

  • 后端 12 个 API 端点实现并注册
  • 数据库表创建（quick_rules + quick_rule_audit_log）
  • 53 条初始数据播种
  • QuickRuleService 缓存加载 + 降级兜底
  • 前端 6 个路由 + 侧边栏菜单注册
  • 前端页面部署并通过浏览器验证
  • 打招呼检测 / 路由预过滤功能改造并向后兼容
  • 故障排查手册已更新（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