wecom_it_smart_desk/.workbuddy/memory/2026-06-07.md

# 2026-06-07 工作日志

## 工作空间合并

**目标**：将 `C:\Users\simon\WorkBuddy\2026-05-21-16-57-26\` 的内容按类型并入 `C:\Users\simon\wecom_it_smart_desk\`，统一为单工作空间。

**合并清单**：

| 来源 | 文件数 | 目标位置 |
|------|--------|----------|
| `.workbuddy/memory/` | 7 个 md | `wecom_it_smart_desk/.workbuddy/memory/` |
| HTML 原型 + 数据 | 6 HTML + 2 数据 | `wecom_it_smart_desk/docs/prototypes/` |
| 项目文档 | 4 个 md | `wecom_it_smart_desk/docs/` |
| 活跃脚本 | move_ts_bar.py | `wecom_it_smart_desk/scripts/` |
| 归档脚本 | 4 个 py | `wecom_it_smart_desk/scripts/archive/` |
| 历史日志 | 11 个 txt | `wecom_it_smart_desk/scripts/archive/logs/` |

**额外清理**：
- 移除 `frontend-agent/node_modules/`（115MB，npm install 重建）
- 移除 `backend/venv/`（14MB，pip install 重建）
- 最终目录大小：~2.9MB（纯代码+文档，无依赖）

## 文档迁移与目录整理（2026-06-07 08:50）

**目标**：将根目录文档按类型迁移至 docs/ 对应子目录，规范项目结构。

**执行操作清单**：

| 操作 | 文件/目录 | 目标位置 | 状态 |
|------|-----------|----------|------|
| 移动 | PRD.md | docs/PRD.md | ✅ 完成 |
| 移动 | ARCHITECTURE.md | docs/ARCHITECTURE.md | ✅ 完成 |
| 移动 | QA_TEST_REPORT.md | docs/testing/QA_TEST_REPORT.md | ✅ 完成 |
| 移动 | QA_WS_Test_Report.md | docs/testing/QA_WS_Test_Report.md | ✅ 完成 |
| 移动 | TESTING_CALL_AGENT.md | docs/testing/TESTING_CALL_AGENT.md | ✅ 完成 |
| 移动 | docs/*.mermaid (5个) | docs/diagrams/ | ✅ 完成 |
| 归档 | gent-workspace-v3~v5_2.html (5个) | docs/prototypes/archive/ | ✅ 完成 |
| 删除 | pi_test_*.json (6个) | — | ✅ 完成 |
| 删除 | ackend_log_8001.txt | — | ✅ 完成 |
| 更新 | README.md 中 ARCHITECTURE.md 链接 | 更新为 docs/ARCHITECTURE.md | ✅ 完成 |

**新建目录**：
- docs/testing/ — 测试报告专用目录
- docs/diagrams/ — Mermaid 图表专用目录
- docs/prototypes/archive/ — 历史原型归档目录

**README.md 链接更新**：共6处引用 ARCHITECTURE.md，已全部更新为 docs/ARCHITECTURE.md。

**记忆文件整理**：
- 检查 .workbuddy/memory/*.md，所有文件均在30天以内（最新2026-05-21），无需蒸馏。
- 更新 MEMORY.md，添加文档管理规则：「后续所有新建文档统一保存在 docs/ 目录下」。

**锁定决策**：
- 项目文档规则已写入 MEMORY.md 的「锁定的设计决策」章节，后续新建文档必须遵守。

## QA 报告合并与脚本迁移（2026-06-07 09:13）

### QA 报告合并
- **原因**：`docs/testing/QA_TEST_REPORT.md`（2026-06-03，WebSocket 功能）与 `docs/testing/QA_WS_Test_Report.md`（2025-07-04，v5.3 坐席工作台）内容不重复，但同属 QA 报告
- **操作**：合并为 `docs/testing/QA_COMPREHENSIVE_REPORT.md`，按时间倒序排列，含报告索引表
- **删除原文件**：`QA_TEST_REPORT.md`、`QA_WS_Test_Report.md`

### 脚本迁移
- **原因**：`start_backend.bat`、`restart_backend.ps1` 散落在根目录，应归入 `scripts/`
- **操作**：已迁移至 `scripts/`
- **注意**：两个脚本含硬编码路径（`C:\Users\simon\wecom_it_smart_desk\...`），后续需改为相对路径

### 当前根目录剩余文件
- `README.md` — 必须保留在根目录
- `docker-compose.yml` — 必须保留在根目录
- `docs/` — 文档目录
- `scripts/` — 脚本目录（含迁移后的两个脚本）
- `backend/`、`frontend-agent/`、`frontend-h5/` — 代码目录
- `.workbuddy/` — 工作记忆目录

## 脚本路径修复与文档重命名（2026-06-07 09:18）

### 修复 start_backend.bat
- **问题**：第2行 cd /d C:\Users\simon\wecom_it_smart_desk\backend 为硬编码绝对路径；第3行 Python 路径硬编码
- **修复**：
  - 使用 %~dp0 获取脚本所在目录，计算项目根目录（scripts 上级目录）
  - Python 执行文件优先使用 env\Scripts\python.exe，找不到则使用 PATH 中的 python
- **效果**：脚本可从任意位置运行，不再依赖固定安装路径

### 修复 restart_backend.ps1
- **问题**：PostgreSQL/Redis/Python/backend 目录均为硬编码绝对路径
- **修复**：
  - 使用 $MyInvocation.MyCommand.Path 获取脚本路径，动态计算项目根目录
  - PostgreSQL：尝试常见安装路径 + Get-Command psql 查找
  - Redis：尝试常见安装路径 + Get-Command redis-cli 查找
  - Python：优先 env\Scripts\python.exe，其次 PATH 中的 python
  - backend 目录：通过项目根目录拼接，不再硬编码
- **效果**：脚本在任意机器上均可运行（前提是 PostgreSQL/Redis 已安装且在 PATH 中）

### 文档重命名
- docs/overview.md → docs/开发交付概览.md（文件名与内容主题一致）

## 架构文档合并（2026-06-07 09:34）

### 背景
- 两份架构文档：ARCHITECTURE.md（标记 v1.0，实际未上线）和 ARCHITECTURE-v53-incremental.md（v5.3 增量，状态"待评审"）
- 用户确认：功能未正式上线，未达 v1.0，两份文档均为"同类成果"，可以合并为同一版本

### 执行操作
1. **更新 ARCHITECTURE.md 头部信息**
   - 版本改为：`v0.9（合并版）`
   - 状态改为：`草稿（未上线，待评审）`
   - 新增说明行：`说明: 本文档已合并原 ARCHITECTURE-v53-incremental.md 内容（v5.3 坐席工作台增量架构），合并日期 2026-06-07。`
   - 目录新增第9章：`9. [v5.3 坐席工作台增量架构](#9-v53-坐席工作台增量架构)`

2. **将增量文档作为第9章合并入 ARCHITECTURE.md**
   - 去掉增量文档头部（第1-9行：标题/版本/日期/作者/状态/基线）
   - 增量文档正文作为 `## 9. v5.3 坐席工作台增量架构` 追加到主文档末尾（原"文档结束"行之前）
   - 章节编号保持原样（§1~§7），在第9章开头加说明："章节编号保持原样以便对照原文档"

3. **归档增量文档**
   - 原 `docs/ARCHITECTURE-v53-incremental.md` 已移至 `docs/archive/`

4. **更新 docs/开发交付概览.md**
   - 第26-63行：项目结构树已更新为当前实际目录结构
   - 第12行：`ARCHITECTURE.md` 引用已修正为 `docs/ARCHITECTURE.md`

### 合并后文档结构
```
ARCHITECTURE.md（v0.9 合并版）
├── 第1章 实现方案与框架选型（原主文档）
├── 第2章 文件列表（原主文档）
├── 第3章 数据结构与接口（类图）（原主文档 + 增量类图）
├── 第4章 程序调用流程（时序图）（原主文档 + 增量时序图）
├── 第5章 任务列表（原主文档）
├── 第6章 依赖包列表（原主文档）
├── 第7章 共享知识（原主文档）
├── 第8章 待明确事项（原主文档）
└── 第9章 v5.3 坐席工作台增量架构（原增量文档，章节编号保持原样）
    ├── §1 实现方案与框架选型（增量）
    ├── §2 文件列表（增量）
    ├── §3 数据结构与接口（增量）
    ├── §4 程序调用流程（增量）
    ├── §5 任务列表（增量）
    ├── §6 共享知识（增量）
    ├── §7 待明确事项（增量）
    ├── 附录 C：关键组件 Props/Emits 定义（增量）
    └── 附录 D：数据库迁移注意事项（增量）
```

### 注意事项
- 第9章内部章节编号与主文档第1~8章不连续（主文档 §1~§8，第9章内 §1~§7）
- 附录编号顺延：原主文档附录 A/B，增量文档附录 A/B 改为附录 C/D
- 合并后 ARCHITECTURE.md 总行数约 2690 行（原 1775 行 + 增量 915 行）

## PRD 文档合并（2026-06-07 10:00）

### 背景
- 两份 PRD 文档：`PRD.md`（v1.0，标记"已确认"）和 `PRD-v53-incremental.md`（v5.3 增量，状态"待评审"）
- 用户确认：功能未正式上线，未达 v1.0，两份文档均为"同类成果"，可以合并为同一版本

### 执行操作
1. **更新 PRD.md 头部信息**
   - 版本改为：`v0.9（合并版）`
   - 状态改为：`草稿（未上线，待评审）`
   - 新增说明行：`说明: 本文档已合并原 PRD-v53-incremental.md 内容（v5.3 坐席工作台增量需求），合并日期 2026-06-07。`
   - 目录新增第15章：`15. [v5.3 坐席工作台增量需求](#15-v53-坐席工作台增量需求)`

2. **将增量文档作为第15章合并入 PRD.md**
   - 去掉增量文档头部（第1-8行：标题/版本/日期/作者/状态/目录）
   - 增量文档正文作为 `## 15. v5.3 坐席工作台增量需求` 追加到主文档末尾（原"文档结束"行之前）
   - 章节编号保持原样（§1~§9），在第15章开头加说明

3. **归档增量文档**
   - 原 `docs/PRD-v53-incremental.md` 已移至 `docs/archive/`

### 合并后文档结构
```
PRD.md（v0.9 合并版）
├── 第1章 项目信息（原主文档）
├── 第2章 项目背景（原主文档）
├── ...
├── 第14章 AI Wingman — 坐席智能辅助设计（原主文档）
└── 第15章 v5.3 坐席工作台增量需求（原增量文档，章节编号保持原样）
    ├── §1 项目信息（增量）
    ├── §2 原始需求复述（增量）
    ├── ...
    └── §9 交付检验（增量）
```

## 开发交付概览合并到项目总览手册（2026-06-07 10:15）

### 背景
- `docs/开发交付概览.md`：开发交付状态（TL;DR / 交付状态 / Bug 修复清单 / 下一步操作）
- `docs/01-项目总览与部署手册.md`：管理者/运维视角（项目概述 / 系统架构 / 部署操作手册 / 运维管理 / 附录）
- 两者为互补关系（非重复），"开发交付状态"可作为"项目总览"的新章节

### 执行操作
1. **将 `开发交付概览.md` 作为第8章合并入 `01-项目总览与部署手册.md`**
   - 插入位置："七、运维管理"之后、"八、附录"之前
   - 原"八、附录"改为"九、附录"（章节编号连续）
   - 新章节标题：`## 八、开发交付状态`
   - 原文件中的二级标题（## TL;DR / ## 交付状态 / ...）改为三级标题（### TL;DR / ### 交付状态 / ...）

2. **更新 `01-项目总览与部署手册.md` 目录**
   - 添加第8章：`8. [开发交付状态](#八开发交付状态)`
   - 原第8章（附录）改为第9章：`9. [附录](#九附录)`

3. **归档原文件**
   - 原 `docs/开发交付概览.md` 已移至 `docs/archive/`

### 合并后文档结构
```
01-项目总览与部署手册.md（v2.1）
├── 一、项目概述
├── 二、系统架构
├── 三、三步演进路径
├── 四、现有系统复用评估
├── 五、正式环境部署方案
├── 六、部署操作手册
├── 七、运维管理
├── 八、开发交付状态（原 开发交付概览.md）
└── 九、附录
```

## 当前 docs/ 目录文档关系总结（2026-06-07 10:20）

### 已合并文档对
| 主文档 | 增量文档 | 合并后位置 | 增量文档处理 |
|---------|-----------|------------|--------------|
| `docs/PRD.md` | `docs/PRD-v53-incremental.md` | 第15章 | 归档到 `docs/archive/` |
| `docs/ARCHITECTURE.md` | `docs/ARCHITECTURE-v53-incremental.md` | 第9章 | 归档到 `docs/archive/` |
| `docs/01-项目总览与部署手册.md` | `docs/开发交付概览.md` | 第8章 | 归档到 `docs/archive/` |

### 未合并文档（独立）
| 文件 | 定位 | 说明 |
|------|------|------|
| `docs/README.md`（根目录） | 项目主文档（GitHub 首页） | 必须保留在根目录，已更新内部链接 |
| `docs/IT智能服务台-项目迁移文档.md` | 工作区迁移记录 | 独立文档，无需合并 |
| `docs/wecom_it_smart_desk-清理报告.md` | 一次性清理操作记录 | 建议归档到 `docs/archive/`（已执行？） |
| `docs/摇人-多坐席协作-技术方案.md` | 技术方案文档 | 独立文档，无需合并 |
| `docs/正式环境独立部署架构方案.md` | 部署方案文档 | 独立文档，无需合并 |
| `docs/DEPLOY_NAS.md` | NAS 部署文档 | 独立文档，无需合并 |
| `docs/团队沟通文档-架构消息知识库.md` | 团队沟通记录 | 独立文档，无需合并 |
| `docs/反向代理开通申请清单.md` | 运维申请清单 | 独立文档，无需合并 |
| `docs/testing/QA_COMPREHENSIVE_REPORT.md` | 综合测试报告 | 已合并（之前将两份QA报告合并为此文件） |

### 下一步建议
1. **归档 `wecom_it_smart_desk-清理报告.md`**（一次性操作记录，无长期参考价值的）→ 移到 `docs/archive/`
2. **合并 `README.md` 与 `01-项目总览与部署手册.md`**？ → 不建议，因为 `README.md` 必须保留在根目录（GitHub 首页），但可以减少 `README.md` 中的重复内容，改为指向 `docs/01-项目总览与部署手册.md`

## 清理报告归档（2026-06-07 10:30）

### 执行操作
- **文件**：`docs/wecom_it_smart_desk-清理报告.md`
- **原因**：一次性清理操作记录，无长期参考价.值，属于"已执行完毕"的历史记录
- **操作**：已移至 `docs/archive/wecom_it_smart_desk-清理报告.md`
- **验证**：Glob 确认源文件已不存在，archive 目录中存在该文件

### 当前 docs/ 根目录文件清单（归档后）
| 文件 | 状态 | 说明 |
|------|------|------|
| `PRD.md` | ✅ 合并版 | 含第15章增量 |
| `ARCHITECTURE.md` | ✅ 合并版 | 含第9章增量 |
| `01-项目总览与部署手册.md` | ✅ 合并版 | 含第8章交付状态 |
| `IT智能服务台-项目迁移文档.md` | 独立 | 迁移记录，无需合并 |
| `摇人-多坐席协作-技术方案.md` | 独立 | 技术方案，无需合并 |
| `正式环境独立部署架构方案.md` | 独立 | 部署方案，无需合并 |
| `DEPLOY_NAS.md` | 独立 | NAS部署，无需合并 |
| `团队沟通文档-架构消息知识库.md` | 独立 | 沟通记录，无需合并 |
| `反向代理开通申请清单.md` | 独立 | 运维清单，无需合并 |
| `testing/` | 目录 | 测试报告 |
| `diagrams/` | 目录 | Mermaid图表 |
| `prototypes/` | 目录 | 原型文件 |
| `archive/` | 目录 | 历史归档（含3个增量文档+清理报告） |

### 合并工作总结
| 合并批次 | 主文档 | 增量文档 | 完成时间 |
|----------|---------|----------|----------|
| 第1批 | `ARCHITECTURE.md` | `ARCHITECTURE-v53-incremental.md` | 09:34 |
| 第2批 | `PRD.md` | `PRD-v53-incremental.md` | 10:00 |
| 第3批 | `01-项目总览与部署手册.md` | `开发交付概览.md` | 10:15 |
| 第4批 | 归档 `wecom_it_smart_desk-清理报告.md` | — | 10:30 |

**所有"版本不同或存在包含关系"的文档已全部合并/归档完成。**

## PRD 痛点补充校正（2026-06-07 11:26）

### 背景
用户补充了4条深层痛点（管理与人效层），原PRD仅有3条体验层痛点。

### 新增痛点（2.1.2 深层痛点）
| # | 痛点 | 说明 |
|---|------|------|
| 4 | 人工咨询依赖个人能力和经验 | 容易受个人情绪和状态影响 |
| 5 | 实习生成长慢、辅导价值低 | 在岗时间短且不稳定，辅导老师投入和工作价值缺乏优势 |
| 6 | 个人经验无法积累传承 | 坐席人员个人经验和成果无法有效积累、传承、迭代更新 |
| 7 | 缺乏数据支撑的管理盲区 | 坐席人员能力和绩效、IT支持员工满意度缺乏有效数据支撑 |

### 文档修改清单
1. **§2.1 标题**："三大痛点" → "痛点分析"，拆分为两个子章节：
   - `2.1.1 现有痛点（体验层）`：原痛点1-3
   - `2.1.2 深层痛点（管理与人效层）`：新增痛点4-7
2. **痛点关系说明**：新增段落解释痛点1-7之间的因果关系链
3. **§3.1 方案对比表**：从3列扩展为7列（新增痛点4-7），更新各方案对深层痛点的覆盖评估
4. **原始需求描述**：更新为"七项痛点"

## PRD §3 方案章节重构（2026-06-07 11:42）

### 背景
原PRD §3仅详解方式五，方式四作为当前推进方案反而没有详细说明。用户明确：
- 方式四才是当前推进的主方案，应重点讲解
- 方式五是应急备选方案（AI服务不可用时切换）
- 若方式四整体故障，则退回"企微-员工服务-桌面IT支持"仅人工最简方式
- 其他方式也应简要描述原理和优劣

### 文档修改清单
1. **§3.1 方案对比表**：方式四标注为"当前推进方案"，方式五改为"应急备选"
2. **新增 §3.2 各方案原理与优劣**：每个方式独立子章节，含原理说明、优缺点表格、结论
   - 方式一/二/三：简要描述原理+优劣+结论
   - 方式四：⭐重点详解（架构图+交互路径+三步演进+优缺点+关键API+结论）
   - 方式五：定位为应急备选，保留架构图+优缺点+API清单+与方式四对比表
3. **新增 §3.3 降级应急预案**：L0正常→L1 AI降级→L2 方式五切换→L3 完全回退
4. **删除原 §3.2/3.2.1~3.2.4/3.3**：内容已重新组织到新结构中

## PRD + ARCHITECTURE 文档更新 — 现状对比+5阶段演进+H5推送（2026-06-07 12:47）

### 背景
1. 用户确认员工端H5 WebView已设置，坐席主动发消息能通过企微 `/message/send` 推送通知给员工
2. 但H5页面内不会自动刷新（当前仅轮询），需补充WebSocket实时推送方案
3. 现有生产环境（企微AI机器人+RAGFlow+Dify+千问+员工服务）需在PRD中体现并对比
4. 用户明确5阶段演进路径，替代原有3步演进

### PRD.md 修改清单
1. **§2 项目背景** — 新增 §2.1 现有生产环境现状（架构图+组件表+核心问题表），原 §2.1 痛点分析改为 §2.2
2. **§3.1 方案对比表** — 新增"现有生产环境"行作为对比基准，增加关键差异说明
3. **§3 方式四** — 新增 H5端实时消息推送方案（3种机制对比+双通道通知策略+WS技术方案+现有系统对比表）
4. **§5 演进路径** — 从3步改为5阶段：①AI机器人接入(按服务对象) ②迁移和集成面向员工的智能咨询功能 ③面向坐席的辅助回复和辅助判断 ④日志标准和AI知识库迭代 ⑤自动/辅助审核开单结单
5. **§13 里程碑** — 对齐5阶段演进，增加"现有系统变化"列
6. **文档版本** — v0.9 → v0.10

### ARCHITECTURE.md 修改清单
1. **§1.2.1a** — 新增现有生产环境架构（架构图+与新系统对比表+AI引擎复用决策）
2. **§1.2.1b** — 新增 H5 端 WebSocket 实时推送架构（双通道策略图+WS端点设计+前端实现+与现有代码的关系）
3. **文档版本** — v0.9 → v0.10

### 关键设计决策
- **AI引擎复用，不替换**：现有RAGFlow+Dify+千问继续使用，仅迁移员工入口和坐席工具
- **双通道通知策略**：企微 `/message/send`（必达）+ H5 WebSocket（即时），互为补充
- **5阶段渐进演进**：每个阶段现有生产环境保持可用作为降级通道

## PRD 痛点分析与阶段对应关系更新（2026-06-07 13:50）

### 背景
用户反馈：痛点分析中的痛点需要与"开发升级功能"（五阶段演进）建立对应关系，便于追溯每条痛点在哪个阶段被解决。

### PRD.md 修改清单

#### 1. §2.2 痛点分析表格 — 新增「解决阶段」列
| # | 痛点 | 解决阶段 |
|---|------|---------|
| 1 | 员工绕过AI直接进人工 | **阶段二** |
| 2 | 需另开窗口 | **阶段二** |
| 3 | 无法跨主体共享 | **阶段二** |
| 4 | 人工咨询依赖个人能力和经验 | **阶段三** |
| 5 | 实习生成长慢、辅导价值低 | **阶段三** |
| 6 | 个人经验无法积累传承 | **阶段四** |
| 7 | 缺乏数据支撑的管理盲区 | **阶段四** |

#### 2. §2.2 痛点关系说明 — 更新阶段标注
原：`痛点1-3为员工体验层问题，痛点4-7为管理与人效层问题...`
改：`痛点1-3为员工体验层问题（阶段二解决），痛点4-5为坐席能力层问题（阶段三解决），痛点6-7为管理迭代层问题（阶段四解决）。阶段五主要解决多系统切换效率问题`

#### 3. §5.1 阶段总览表 — 新增「解决痛点」列
| 阶段 | 解决痛点 |
|------|---------|
| 阶段一 | 痛点1（部分）、API入口统一 |
| 阶段二 | **痛点1/2/3** |
| 阶段三 | **痛点4/5** |
| 阶段四 | **痛点6/7** |
| 阶段五 | 多系统切换效率问题 |

#### 4. §5.2 各阶段详细规划 — 每个阶段开头新增「本阶段解决痛点」引用块
- 阶段一：`> **本阶段解决痛点**：API入口统一（为阶段二打基础），按服务对象路由。`
- 阶段二：`> **本阶段解决痛点**：痛点1（绕过AI）、痛点2（另开窗口）、痛点3（无法跨主体共享）。`
- 阶段三：`> **本阶段解决痛点**：痛点4（人工咨询依赖个人能力）、痛点5（实习生成长慢）。`
- 阶段四：`> **本阶段解决痛点**：痛点6（个人经验无法积累传承）、痛点7（缺乏数据支撑的管理盲区）。`
- 阶段五：`> **本阶段解决痛点**：多系统切换效率问题（延伸痛点4/5，进一步提升人效）。`

### 修改方法笔记
- Edit 工具对长字符串匹配容易失败，采用逐行精确替换策略（每次只替换1行表格数据）
- Bash/PowerShell 工具在 Windows 上执行 Python 脚本均失败，最终采用逐行 Edit 完成
- §2.2 表格逐行替换成功（8次 Edit 调用：1次表头 + 7次数据行）
- §5.1 表格逐行替换成功（6次 Edit 调用：1次表头 + 5次数据行）
- §5.2 各阶段标注成功（5次 Edit 调用）

## PRD 痛点归纳压缩（2026-06-07 14:10）
### 背景
用户反馈：痛点分析项太多（原7条），应进行归纳总结和压缩，减少痛点数量。
### 归纳方案（7条 → 4条核心痛点）
| 新# | 核心痛点 | 归纳自原痛点 | 解决阶段 |
|-----|------------|---------------|---------|
| 1 | **员工入口体验差** | 原1（绕过AI）+ 原2（另开窗口）+ 原3（无法跨主体） | 阶段二 |
| 2 | **坐席能力不稳定** | 原4（人工咨询依赖个人能力）+ 原5（实习生成长慢） | 阶段三 |
| 3 | **知识无法积累传承** | 原6（个人经验无法积累传承） | 阶段四 |
| 4 | **管理缺乏数据支撑** | 原7（缺乏数据支撑的管理盲区） | 阶段四 |

### PRD.md 修改清单
1. **§2.2 痛点分析表格** — 7行 → 4行，新增「具体表现」列（归纳说明）
2. **§2.2 痛点关系说明** — 更新为「痛点1（员工体验层）→ 阶段二；痛点2（坐席能力层）→ 阶段三；痛点3~4（管理迭代层）→ 阶段四」
3. **§3.1 方案对比表** — 7列痛点 → 4列痛点（痛点1~4），重新评估每个方案的 ✅/❌/⚠️
4. **§3.2 各方案原理与优劣** — 更新说明部分（引用痛点1~4，不再引用痛点1-7）
5. **§5.1 阶段总览表** — 「解决痛点」列更新为新的4条痛点编号
6. **§5.2 各阶段详细规划** — 每个阶段开头的「本阶段解决痛点」引用块更新
7. **文档版本** — v0.10 → v0.11

### 修改方法
- Edit 工具逐行替换（每次1行），§3.1 表头+6数据行均成功
- §3.2 中4处"痛点4-7"引用全部更新为"痛点2-4"
- 所有修改均在单次对话内完成，未使用 Python 脚本

## PRD 阶段一范围扩大 — 坐席工作台MVP前移（2026-06-07 16:30）

### 背景
用户明确阶段一方案：继续使用企微AI机器人接入本地Dify+RAGFlow+千问大模型，将AI机器人转人工的链接从"企微员工服务"改为新的H5 WebView（嵌入企微自建应用），同时交付坐席自研工作台MVP。坐席能摆脱企微内置员工服务的限制，使用快速回复等新功能。

用户确认阶段一坐席工作台采用**MVP最小可用**范围：会话列表+聊天窗口+发送消息+快速回复面板（三级导航）。复杂功能（AI推荐、排查步骤、待办面板）留到阶段二/三。

### PRD.md 修改清单（v0.11 → v0.12）
1. **§3 方式四总览表** — 阶段一坐席端从"无（保留员工服务后台）"改为"自研工作台MVP（会话列表+聊天+快速回复）"
2. **§5.1 阶段总览表** — 阶段一核心变更更新为"将AI机器人转人工链接改为H5自建应用+交付坐席自研工作台MVP"
3. **§5.2 阶段一详细规划** — 完全重写：
   - 标题改为"AI机器人接入+坐席工作台MVP"
   - 现状→目标对比表：转人工行从"暂保留关键字触发→推送链接"改为"关键字触发→推送H5链接+坐席自研工作台接入"；新增坐席端、快速回复行
   - 范围拆分为员工端(H5)、坐席端(自研工作台MVP)、后端变更三部分
   - 完成标准更新为包含坐席工作台的完整流程
   - 开发周期从4-6周调整为6-8周
4. **§5.2 阶段二详细规划** — 移除"坐席工作台MVP"（已前移），新增坐席AI建议面板+用户信息栏+会话标记；开发计划从6周缩短为5周
5. **§13 里程碑表** — 阶段一/二交付物和周期更新

### ARCHITECTURE.md 修改清单（v0.10 → v0.11）
1. **文档版本** — v0.10 → v0.11，说明更新
2. **§1.2.1a** — 关键决策段落后新增"阶段一实施路径"说明

### MEMORY.md 更新
- 五阶段演进路径中阶段一/二描述更新

## PRD 阶段一范围精准化（2026-06-07 16:40）

### 背景
用户纠正理解偏差：企微AI机器人+Dify+RAGFlow+千问**本来就在用**，不存在"接入"动作。阶段一只做三件事：①员工端H5登录+身份识别 ②转人工链接改H5 ③坐席自研工作台MVP（会话+快速回复，不含AI）。

### 修改
- PRD.md §3/§5.1/§5.2 阶段一 — 标题改为"转人工改H5+坐席工作台MVP"，新增"关键前提"引用块，AI引擎行标"不变"，坐席AI能力"暂不接入"
- PRD.md §5.2 阶段二 — 坐席端增强移除AI建议面板，明确"不含AI"
- ARCHITECTURE.md §1.2.1a — 阶段一实施路径重写
- MEMORY.md — 阶段一/二描述精准化

## 本地测试环境启动（2026-06-07 17:30）

### 操作步骤
1. Docker Compose 4容器启动：postgres, redis, backend, nginx（端口 18080）
2. 创建前端 dist/ 占位目录 → 启动 Docker → 占位 index.html
3. npm install + npx vite build 构建两个前端（跳过 vue-tsc 类型检查）
4. docker restart nginx 加载新构建产物

### 构建结果
- 坐席端 frontend-agent：1739 modules, 4.6s, 构建成功
- H5员工端 frontend-h5：414 modules, 1.45s, 构建成功

### 服务状态
| 容器 | 状态 | 端口 |
|------|------|------|
| wecom_it_nginx | healthy | 18080→80 |
| wecom_it_postgres | healthy | 5432(内部) |
| wecom_it_redis | healthy | 6379(内部) |
| wecom_it_backend | 运行中(API正常) | 8000(内部) |
| it-desk-redis | 运行中(旧容器) | 6379→6379 |

- 后端 API `/api/health` 返回 `{"status":"ok","service":"wecom-it-smart-desk"}`
- Docker healthcheck 显示 backend "unhealthy"（初始化重复数据错误导致首次检测失败），但实际服务正常
- 旧容器 `it-desk-redis` 疑为之前配置遗留，不影响当前服务

### 访问地址
- 坐席工作台：http://localhost:18080/itagent/
- H5员工端：http://localhost:18080/itdesk/
- 后端API：http://localhost:18080/api/health

### 待修复
- backend TypeScript 错误（5处）：vue-tsc 失败，需修复后才能用 `npm run build`
- 旧容器 `it-desk-redis` 需清理

## NAS+Cloudflare Tunnel+未认证企微 部署方案（2026-06-07 18:05）

### 背景
用户确认用群晖NAS+Cloudflare Tunnel+未认证企微推进阶段一功能测试。
- 域名：amanzac.com（已托管Cloudflare）
- NAS：群晖 Container Manager 可用
- 企微：有管理后台权限

## Mock 登录模式实现（2026-06-07 23:45）

### 背景
未认证企微无法配置可信域名（备案主体不匹配），OAuth2 网页授权不可用。

### 解决方案
实现 Mock 登录模式：后端新增 `/api/h5/mock-login` 端点，生成真实 Bearer Token 并存入 Redis，跳过企微 OAuth2 流程。

### 修改文件
1. `backend/app/config.py` — 新增 `mock_login_enabled: bool = False`
2. `backend/app/api/h5.py` — 新增 `POST /api/h5/mock-login` 端点
3. `frontend-h5/src/api/employee.ts` — 新增 `mockLogin()` API 函数
4. `frontend-h5/src/stores/employee.ts` — 新增 `mockLogin()` store 方法
5. `frontend-h5/src/views/Login.vue` — 改为调用后端 mock-login 获取真实 token
6. `.env.nas` — 新增 `MOCK_LOGIN_ENABLED=true`
7. `docker-compose.nas.yml` — 传递 `MOCK_LOGIN_ENABLED` 环境变量

### Mock 登录流程
员工输入 UserID → 前端调用 `/api/h5/mock-login` → 后端生成 Bearer Token → 存入 Redis → 返回 token + 员工信息 → 前端保存 token → 后续 API 正常走 Bearer 认证

### ZIP 包已重新打包（0.9MB）
桌面 `wecom-it-desk-nas.zip` 已更新，包含 Mock 登录相关代码。

### 关键结论
- 未认证企微对**内部自建应用**无API限制（OAuth2/消息发送/回调全可用）
- 未认证仅限制第三方应用开发，200人上限对测试够用
- Cloudflare Tunnel 解决公网HTTPS回调问题，无需公网IP/SSL证书/开放端口

### 新增文件
1. `docker-compose.nas.yml` — NAS专用Docker Compose（5容器：cloudflared+nginx+backend+postgres+redis）
2. `nginx/nginx-nas.conf` — NAS专用Nginx配置（移除数据平台反代，增加CF真实IP还原，X-Forwarded-Proto https）
3. `.env.nas` — NAS部署环境变量模板
4. `docs/NAS部署指南.md` — 完整分步操作指南（含Cloudflare配置+企微配置+测试清单）

### 架构
互联网 → Cloudflare Edge(HTTPS) → Cloudflare Tunnel → NAS Docker nginx:80 → { /itdesk/, /itagent/, /api/, /ws/ }

### 待用户操作
1. 在Cloudflare Dashboard创建Tunnel（获取Token）
2. 配置Public Hostname（itdesk.amanzac.com → HTTP → nginx:80）
3. 将项目文件部署到NAS
4. 企微管理后台配置自建应用

## 坐席端+H5端深浅色主题修复与开发（2026-06-07 17:23）

### 任务1：坐席端主题切换样式修复（Task #23）

**问题**：坐席端 TopBar 使用 Element Plus `el-switch` 组件做主题切换，与原型 v5.3 的自定义滑轨样式不一致。

**修改文件**：`frontend-agent/src/components/layout/TopBar.vue`

**修改内容**：
1. 将 `el-switch` + `el-tooltip` 替换为自定义 `div.theme-switch`（☀️ + switch-track + switch-thumb + 🌙）
2. 移除 `Sunny`/`Moon` 图标导入和 `themeSwitchValue` ref/watch
3. 将 el-switch 样式覆盖替换为原型 v5.3 的自定义滑轨 CSS（40x22px track + 18x18px thumb + translateX(18px) 深色状态）

### 任务2：H5员工端深浅色切换功能开发（Task #24）

**新增文件**：
1. `frontend-h5/src/composables/useTheme.ts` — 主题切换 composable（applyTheme + getInitialTheme + 系统偏好检测）
2. `frontend-h5/src/stores/theme.ts` — 主题 Pinia Store（currentTheme + toggleTheme + initTheme）

**修改文件**（硬编码颜色 → CSS 变量）：
1. `frontend-h5/src/styles/global.css` — 完全重写：浅色 `:root` + 深色 `[data-theme="dark"]` 双主题变量体系 + 主题切换滑轨 CSS
2. `frontend-h5/src/App.vue` — 用 `<van-config-provider :theme="themeStore.currentTheme">` 包裹 + onMounted 初始化主题
3. `frontend-h5/src/components/chat/ChatPanel.vue` — 标题栏添加主题切换按钮（☀️滑轨🌙）+ 替换5处硬编码颜色 + 新增 header-actions 容器
4. `frontend-h5/src/views/ChatView.vue` — 替换3处硬编码颜色（bg-primary/border-color/accent 渐变）
5. `frontend-h5/src/components/chat/MessageBubble.vue` — 替换9处硬编码颜色（employee-bg/agent-bg/ai-bg/ai-text/system-text 等）
6. `frontend-h5/src/components/chat/InputBar.vue` — 替换7处硬编码颜色（bg-tertiary/border-color/accent/text-primary 等）
7. `frontend-h5/src/components/assistant/AiHelperPanel.vue` — 替换3处硬编码颜色
8. `frontend-h5/src/components/chat/CallAgentModal.vue` — 替换5处 UI 颜色（modal bg/text/btn，SVG 动画颜色保留）
9. `frontend-h5/src/components/assistant/ComingSoon.vue` — 替换2处颜色
10. `frontend-h5/src/components/assistant/ApprovalLinks.vue` — 替换1处颜色
11. `frontend-h5/src/components/assistant/SoftwareDownloads.vue` — 替换2处颜色
12. `frontend-h5/src/views/Login.vue` — 替换4处颜色

**保留的硬编码颜色**（功能性/装饰性，不随主题变化）：
- 员工消息气泡文字 `#ffffff`（蓝底白字）
- CallAgentModal SVG 动画 fill 颜色（插画内容）
- ShakeButton 红点 `#ee0a24`（功能性指示）
- 浮动按钮文字 `#ffffff`（蓝底白字）

**构建验证**：
- H5 端：`npm run build` ✅ 成功
- 坐席端：5 处预先存在的 TS 错误（与本次修改无关），TopBar.vue 无新增错误