Simon
44e77dcb0e
**重构前**（旧编号 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 行
84 lines
4.9 KiB
Markdown
84 lines
4.9 KiB
Markdown
# 智能回复系统深度重构总方案（v4.0）
|
||
|
||
> **日期**：2026-07-17
|
||
> **前置版本**：v3.0（后端 ApprovalMatcher 统一匹配）/ v3.1（Dify 无 action 降级 + 超时降级）
|
||
> **问题基线**：20 项已验证问题（后端 8 + 前端 6 + 配置 6），全部对照源码核实
|
||
> **用户决策**：Redis 密码立即轮换 ✅ / Triage 分诊链路整体删除 ✅ / D1 意图合并采用激进方案 ✅
|
||
> **工作方式**：敏捷批次交付 + DevOps（文档与代码同 PR、每批次 RELEASE-NOTES）
|
||
|
||
---
|
||
|
||
## 一、目标分层架构
|
||
|
||
```
|
||
接入层 Ingress（h5.py / ws.py）
|
||
└─ 只鉴权、落库用户消息、立即返回、投递任务
|
||
编排层 Orchestration（h5_ai_task.py 管线化）
|
||
└─ 只做流程编排，不直接发起外部调用
|
||
推理层 Inference（ai_service.py，全系统唯一 Dify 调用点）
|
||
└─ 真单例；native 12s + proxy 12s 超时预算；一次调用返回 intent/路由/审批字段
|
||
匹配层 Matching（approval_matcher.py，纯函数）
|
||
└─ match_and_build_card / match_by_keywords / get_all_categories
|
||
渲染层 Rendering（前端纯渲染）
|
||
└─ WS 契约单点 build_message_ws_payload()；审批卡片渲染点 ≤ 2 处
|
||
```
|
||
|
||
**单一职责红线**：ApprovalMatcher 不碰 WS/DB；AIService 不认识"审批/路由/BYOD"；编排层不 new httpx；WS 推送统一出口。
|
||
|
||
## 二、关键设计决策
|
||
|
||
| # | 决策 | 理由 |
|
||
|---|------|------|
|
||
| D1 | 意图识别并入主 Dify 调用 | routing detect 与主对话是同一 Dify 应用同一 key，消除 15s+30s 串行叠加（最坏 45s → ~15s） |
|
||
| D2 | 超时预算内化 httpx | native 12s + proxy 12s < wait_for 30s，修复 proxy 兜底数学不可达问题 |
|
||
| D3 | 匹配失败不静默 | ApprovalMatcher 末路返回全量卡片（get_all_categories），前端永不空白 |
|
||
| D4 | WS 消息契约单点化 | 修复 new_message 前端白名单丢字段（坐席图片/文件不渲染） |
|
||
| D5 | triage 分诊链路删除 | 前端零挂载点（已确认，grep 无引用） |
|
||
| D6 | 快捷申请走新端点 | `GET /approval/all-categories-card`，修复 showApprovalCard 空白气泡 P0 |
|
||
|
||
## 三、批次计划
|
||
|
||
### 批次 1（P0，~2 天，彼此独立可单独上线）
|
||
| 项 | 内容 | 工作量 |
|
||
|----|------|--------|
|
||
| P0-1 | 生产 workers=2 → 1（删除/修改 override 与 deploy-server compose） | 0.5d |
|
||
| P0-2 | DIFY_NATIVE_* 生产配置（compose environment + .env.production） | 0.5d |
|
||
| P0-3 | 快捷申请空白气泡修复（新 all-categories-card 端点 + store 改造） | 0.5d |
|
||
| P0-4 | RecommendCard invokeApproval ReferenceError 修复 | 0.5d |
|
||
| P0-5 | WS new_message 前端全字段透传 | 1d |
|
||
| P0-6 | 超时预算切分（native 12s / proxy 12s） | 1d |
|
||
|
||
**上线前 git tag `pre-v4-refactor`**；文档同步：本目录 `01-批次1-P0执行记录.md` + RELEASE-NOTES v4.0.0。
|
||
|
||
### 批次 2（P1 基础，~3 天）
|
||
P1-1 AIService 真单例（修复 httpx 连接泄漏）→ P1-2 统一 Dify 调用点（删除 approval/byod detect-intent 死链路、routing 改调 chat_native）→ P1-4 Matcher 死分支删除 + 失败兜底（D3）→ P1-7 配置治理（APP_ENV=production、**Redis 密码轮换（低峰期）**、os.getenv 旁路收敛、3 个潜伏 bug 修复：app_root/AsyncIOSScheduler 拼写/config.py logger）→ P1-6 dynamic_recommend 死逻辑清理。
|
||
|
||
文档同步：架构文档 v2 §15.4.5 重写（v3.0 纯渲染架构）。
|
||
|
||
### 批次 3（P1 核心，~4 天，观察 24h）
|
||
P1-3 编排层管线化（**D1 激进合并**：先 5 条真实消息验证 Dify intent 字段稳定性，不稳定退回 gather 并行）→ P1-5 WS 死路由清理（ai_reply_chunk/pending_close_request/quiz_diagnostic_answer）。
|
||
|
||
观察指标：AI 回复到达率 ≥99%、平均响应 ≤20s、转人工率不升。文档同步：架构文档新增「智能回复链路 v4」章节。
|
||
|
||
### 批次 4（P2，按需）
|
||
P2-1 死代码大扫除（含 3 个 .bak 文件、构建产物目录入库）→ P2-2 triage 整链删除 → P2-4 测试补齐 → P2-3 前端 store 拆分 → P2-5 审批回调 TODO 收口。
|
||
|
||
## 四、验收清单
|
||
|
||
- [ ] 生产 `--workers 1`，AI 回复 WS 到达率 100%
|
||
- [ ] 日志走「Dify 原生 API」，无 proxy 路径、无 [object Object]
|
||
- [ ] Dify 调用点全系统唯一
|
||
- [ ] `process_h5_ai_reply` < 100 行，try/except ≤ 3 对；路由消息端到端 < 35s
|
||
- [ ] ApprovalMatcher 任意输入均有卡片输出（无 None）
|
||
- [ ] H5 快捷申请/AI 卡片/关键词兜底三场景渲染一致
|
||
- [ ] 坐席发图片/文件，H5 WS 实时渲染
|
||
- [ ] pytest + `npm run build` 全绿；/version 返回真实 git hash
|
||
|
||
## 五、回滚策略
|
||
|
||
每批次独立 PR + 独立部署；git tag `pre-v4-refactor` 全量回滚点；配置类（DIFY_NATIVE/APP_ENV/Redis）改回旧值重启即可；批次 3 异常回滚至批次 2 状态。
|
||
|
||
---
|
||
|
||
**执行记录**：见本目录 `01-批次1-P0执行记录.md`（批次 1 完成后填写）等。
|