simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e196d5a3e3f96c402c337e888b49e8610cb80828
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

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