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 行
92 lines
5.9 KiB
Markdown
92 lines
5.9 KiB
Markdown
# 02-技术文档/重构记录 — 目录索引与执行状态看板
|
||
|
||
> **创建**：2026-07-17
|
||
> **目的**：智能回复系统 v4.0 深度重构的全部记录。当前会话不可用时，新会话读本目录即可继续推进。
|
||
> **工作方式**：敏捷批次交付 + DevOps（文档与代码同 PR）
|
||
|
||
---
|
||
|
||
## 一、新会话快速上手指引（3 步）
|
||
|
||
1. **读方案**：`00-v4.0重构总方案.md`（分层架构、批次计划、验收清单）
|
||
2. **读问题**：`01-问题验证清单.md`（20 项问题 + 源码行号证据 + 已完成修复清单）
|
||
3. **看状态**：本文 §三（执行状态看板），找到「待开始」的任务说明书，按 `docs/07-项目管理/任务说明书/` 执行
|
||
|
||
## 二、目录结构
|
||
|
||
```
|
||
docs/02-技术文档/重构记录/
|
||
├── README.md ← 本文件（索引 + 状态看板）
|
||
├── 00-v4.0重构总方案.md ← 目标架构、批次计划、验收清单、回滚策略
|
||
├── 01-问题验证清单.md ← 20 项问题源码证据（B1-B8/F1-F6/C1-C6）
|
||
├── 02-批次1-P0执行记录.md ← 批次 1 完成后填写
|
||
├── 03-批次2-P1基础执行记录.md
|
||
├── 04-批次3-P1核心执行记录.md
|
||
└── 99-回顾报告.md ← 批次 3 观察 24h 后填写
|
||
```
|
||
|
||
**配套文档**：
|
||
- 任务说明书：`docs/07-项目管理/任务说明书/任务说明书-78/79/84/85/86/87/88/89/90`
|
||
- 部署铁律：`docs/04-运维文档/部署运维/DEPLOY-GUIDE.md` §4.3
|
||
- Dify 主 prompt 线上版本：`docs/02-产品需求/dify_main_chat_prompt_v1.md`（v1.2）
|
||
|
||
## 三、执行状态看板
|
||
|
||
> 更新规则：每完成一项即更新。新会话从这里接续。
|
||
|
||
| 批次 | 任务 | 任务说明书 | 状态 | 完成日期 |
|
||
|------|------|-----------|------|---------|
|
||
| — | v3.0 后端 ApprovalMatcher + 前端纯渲染 | — | ✅ 已完成 | 2026-07-17 |
|
||
| — | v3.1 Dify 无 action 降级 + message_content bug 修复 | — | ✅ 已完成 | 2026-07-17 |
|
||
| 批次 0 | 文档速修 4 项 + 本目录归档 | — | ✅ 已完成 | 2026-07-17 |
|
||
| 批次 1 | P0-1 workers=2→1 | #78 | ✅ 已完成（预防性，服务器已是1） | 2026-07-17 |
|
||
| 批次 1 | P0-2 DIFY_NATIVE_* 生产配置 | #79 | ✅ 已完成（变量已注入容器） | 2026-07-17 |
|
||
| 批次 1 | P0-3 快捷申请空白气泡修复 | #87 | ⚠️ 误报（InputBox 孤儿组件，端点保留备用） | 2026-07-17 |
|
||
| 批次 1 | P0-4 RecommendCard invokeApproval 修复 | #88 | ✅ 已完成（v16） | 2026-07-17 |
|
||
| 批次 1 | P0-5 WS new_message 全字段透传 | #89 | ✅ 已完成（v16） | 2026-07-17 |
|
||
| 批次 1 | P0-6 超时预算切分 | #90 | ✅ 已完成（native/proxy 各12s，变量已注入） | 2026-07-18 |
|
||
| 批次 2 | P1-1 AIService/AIHandler 真单例 | #84 | ✅ 已完成 | 2026-07-18 |
|
||
| 批次 2 | P1-2 统一 Dify 调用点（删 detect-intent 死链路） | #84 | ✅ 已部署（死端点 404 验证通过） | 2026-07-18 |
|
||
| 批次 2 | P1-4 Matcher 死分支+失败兜底全量卡片 | #84 | ✅ 已部署（含 18 模板字段补全，7 项测试通过） | 2026-07-18 |
|
||
| 批次 2 | P1-7(部分) 3 个潜伏 bug 修复 | #84 | ✅ 已部署（启动无 ImportError） | 2026-07-18 |
|
||
| 批次 2 | P1-7(剩余) APP_ENV 传递+Redis 密码轮换 | #84 | ✅ 已部署（老密码 WRONGPASS 失效，新密码 PONG/读写正常） | 2026-07-18 |
|
||
| 批次 2 | P1-6 recommend 死逻辑清理 | #84 | ✅ 已部署（v18，含结单确认断链修复） | 2026-07-18 |
|
||
| 批次 3 | P1-3 编排层管线化（主函数312→76行）+ D1 止血（15s→8s） | #85 | ✅ 已部署（端到端验证一致，进入 24h 观察期） | 2026-07-18 |
|
||
| 批次 3 | D1 正式合并（后端双模 + Prompt v1.3） | #85 | ✅ 已上线（[D1] 路由意图(主Dify) 日志确认，45s→10s；联系人表空待配置） | 2026-07-18 |
|
||
| 批次 4 | 死代码大扫除（triage 三件套 + /approval/keywords + scheduler.py 孤儿 + 3 个 .bak + get_reply_stream ~96行） | #86 | ✅ 已部署（keywords 404，H5 200，无 ImportError） | 2026-07-18 |
|
||
|
||
### 待部署清单（堡垒机恢复后一次性部署）
|
||
|
||
~~后端 9 文件 + 前端 v17~~ **已全部部署完成（2026-07-18 01:35）**：
|
||
- 后端：`docker compose restart backend` 无 ImportError；detect-intent 双端点 404 ✅；health 200 ✅
|
||
- 前端：v17（`index-BxOIE0ES.js`），H5 HTTP 200，新 JS 已加载 ✅
|
||
- 部署通道记录：`jms_ops.py upload` 的 elFinder 通道 GBK bug（`jumpserver_sftp_upload_v98.py` print emoji 崩溃）；>100KB 文件改用 `pack-upload`（目录直传）绕过
|
||
|
||
## 四、关键上下文（新会话必读）
|
||
|
||
### 4.1 部署铁律（详 `docs/04-运维文档/部署运维/DEPLOY-GUIDE.md` §4.3）
|
||
1. backend 必须 `--workers 1`（override 会覆盖主文件，务必 `docker compose config | grep workers` 验证）
|
||
2. `.env` 不会自动传入容器，新变量必须在 compose `environment:` 显式声明
|
||
3. Redis 密码特殊字符必须 URL 编码（@→%40 #→%23 !→%21）
|
||
|
||
### 4.2 服务器部署通道
|
||
- 堡垒机：`sxn@10.212.189.210:2222`（OTP），工具 `C:\Users\simon\.workbuddy\skills\jumpserver-V2\scripts\v2_ops.py`
|
||
- 服务器项目根：`/opt/wecom-it-desk/`；backend 卷挂载 `./app:/app/app`，改 .py 后 `docker compose restart backend`
|
||
- 前端部署：tar 上传 → 解压到 `frontend-h5/dist` → `docker compose up -d nginx`（容器重建非 reload）
|
||
|
||
### 4.3 回滚点
|
||
- git tag `pre-v4-refactor`（批次 1 上线前打）
|
||
- 前端备份：`frontend-h5/dist_bak_v13`
|
||
|
||
### 4.4 用户已确认的决策
|
||
- Redis 密码**立即轮换**（批次 2，低峰期，新旧双备）
|
||
- Triage 分诊链路**整体删除**（批次 4）
|
||
- D1 意图合并**激进方案**（批次 3 先 5 条真实消息验证 Dify intent 字段，不稳定退回 gather 并行）
|
||
|
||
## 五、变更记录
|
||
|
||
| 日期 | 变更 | 说明 |
|
||
|------|------|------|
|
||
| 2026-07-17 | 创建目录 + 批次 0 完成 | 4 项文档速修 + 本索引 |
|
||
| 2026-07-17 | 任务说明书 #78-86 创建 | 批次 1-4 全部任务书面化 |
|