任务说明书 — 批次 2（P1 基础：真单例 / 统一 Dify 调用点 / Matcher 修复 / 配置治理）
版本: v1.0 | 日期: 2026-07-17
📋 基本信息
| 项目 |
内容 |
| 任务名称 |
v4.0 批次 2：P1 基础重构（5 个子项） |
| 任务ID |
#84 |
| 优先级 |
🟠 P1 |
| 类型 |
架构重构 / 安全加固 |
| 状态 |
待开始 |
| 负责人 |
宋献 |
| 创建日期 |
2026-07-17 |
| 计划完成日期 |
2026-07-22 |
| 预估工时 |
3 天 |
📥 输入项来源
| 来源文档 |
相关章节 |
docs/02-技术文档/重构记录/00-v4.0重构总方案.md |
§三 批次 2 |
docs/02-技术文档/重构记录/01-问题验证清单.md |
B3/B4/B5/B9/C3/C4/C5/C6 |
📤 输出成果要求（5 个子项）
P1-1 AIService/AIHandler 真单例（0.5d）
- 问题：
dependencies/__init__.py:98-106 每次调用新建 AIHandler+AIService+2 个 httpx 连接池，从不 close → 连接泄漏
- 方案：模块级懒加载单例
_shared_ai_handler；cleanup_shared_services() 中 await handler.ai_service.close()
- 验证：连续 50 次请求后容器 ESTABLISHED 连接数稳定；shutdown 无
Unclosed client session
P1-2 统一 Dify 调用点（2d）
- 问题：同一 Dify 原生调用代码复制 3 遍（approval.py:999 死、routing_service.py:120 活、byod.py:243 死）
- 方案：
ai_service.py 新增通用 chat_native(query, user_id, timeout)- 删除死链路：
POST /approval/detect-intent 端点（approval.py:1060）+ _call_dify_approval_intent；POST /byod/detect-intent 端点（byod.py:348）+ _call_dify_byod_intent
routing_service.detect_routing_intent 改调 chat_native（D1 合并前过渡）
- 验证：
grep -rn "httpx.AsyncClient" backend/app/api/ 零命中；POST /api/approval/detect-intent 返回 404
P1-4 ApprovalMatcher 死分支 + 失败兜底（0.5d）
- 问题：
approval_matcher.py:66-69 优先级 5 死分支；匹配失败仅 warning → 前端空白（B4）
- 方案：删除死分支；
match_and_build_card 末路返回 get_all_categories() 全量卡片（不再返回 None）
- 验证：mock 未知 approval_type → 前端仍渲染全量卡片
P1-7 配置治理 + 潜伏 bug（2d）
- a. compose 增加
APP_ENV=${APP_ENV:-production}（修复生产 UA 校验/IP 白名单不生效）
- b. Redis 密码轮换（已进 git 历史）：compose 改
${REDIS_PASSWORD} 引用 + 新密码；低峰期执行（22:00 后），停机 30-60s，用户需重新登录，新旧密码双备
- c. os.getenv 旁路收敛入 Settings；
is_dev_mode 属性统一
- d. 3 个潜伏 bug 修复：
main.py 定义 app_root；删除 tasks/scheduler.py（拼写错误+零导入死文件）；config.py 顶部补 logger = logging.getLogger(__name__)
- 验证：
/version 返回真实 git hash；非法 AUTOMATION_THRESHOLDS 不抛 NameError；非白名单 IP 访问 admin 返回 4004
P1-6 dynamic_recommend 死逻辑清理（0.5d）
- 问题：
h5_ai_task.py:528-582 分支条件保证 approval_type 必为 None，整段模板匹配恒空
- 方案：删除死逻辑，recommend_data 取
action["url"]（已由 matcher 注入）
🔧 验收标准
📞 依赖与阻塞
| 依赖 |
说明 |
| 批次 1 完成（#78-83） |
P1-2 依赖 P0-2 的 DIFY_NATIVE 配置 |
| Redis 密码轮换窗口 |
需提前通知用户重新登录，选 22:00 后 |
文档同步：架构文档 v2 §15.4.5 重写（v3.0 纯渲染架构）；填写 docs/02-技术文档/重构记录/03-批次2-P1基础执行记录.md。
📈 变更记录
| 日期 |
变更内容 |
变更人 |
| 2026-07-17 |
创建任务 |
宋献 |
Simon
44e77dcb0e