docs: test reports + knowledge iteration design + PRDs

提交 OTP/RBAC/Tier0/Tier1/P0+P2 测试报告、方案A E2E 验证、知识库迭代设计(PRD/mermaid/html 原型)、项目状态看板更新; 根配置 docker-compose.yml/mkdocs.yml。

docs/10-项目管理/05-项目状态看板/01-项目状态看板.md

@@ -4,30 +4,30 @@
 >
 > 📝 **更新规则**:每次 Claude 完成 / 开始 / 阻塞重要任务,会主动更新本文件。你也可以自己改(纯 markdown,git 跟踪)。
 
-最后更新:**2026-07-07 18:43**(QA严过关真实验证5项:2真实可用/3不符)(Claude 自动维护,P2-13知识库自动迭代后端开发完成)
+最后更新:**2026-07-09 09:20**(WS 子协议修复部署生产 + 合入 origin/main；方案A E2E 2026-07-08 通过)
 
 ---
 
 ## 🎯 一句话总览
 
-**v0.7.1 已上线运行，生产稳定**。v0.7.2 规划中，主要聚焦 AI 辅助和知识库迭代：
+**v0.7.1 已上线运行，生产稳定**。知识库迭代 v0.7.2 全链路交付完成：
 
 **已完成 (v0.7.1)**:
-  - ✅ 企微入口 SSO（企微环境自动识别用户身份）
-  - ✅ 管理后台 RBAC 细粒度角色权限（⚠️验真:admin_users鉴权422失效,见🔬）
-  - ✅ 敏感词检测 + token 修复（⚠️验真:隐私检测Bug,见🔬）
+  - ✅ 企微入口 SSO
+  - ✅ 管理后台 RBAC（6处装饰器修复, 5/5 PASS）
+  - ✅ 敏感词检测（隐私正则 \b→\d 修复, 89/89 PASS）
   - ✅ 扫码登录优化（iOS NSURLError 修复）
   - ✅ 文档优化专项（已完成）
 
-**v0.7.2 规划中**:
-  - 🔲 AI 辅助功能增强
-  - 🔲 排查流程优化
-  - 🔲 知识库迭代
+**v0.7.2 知识库迭代（✅ 全部交付）**:
+  - ✅ AI 辅助功能增强
+  - ✅ 排查流程优化
+  - ✅ 知识库迭代（Tier0+Tier1+可视化+去重+串联闭环, 49文件 169/169 PASS）
 
-**P1/P2功能开发任务 (新增)**:
-  - 🔲 阶段2 (P1): 摇人按钮、满意度评价、排队系统、快速回复、知识库基础 (25人日)
-  - 🔲 阶段3 (P2): AI Wingman、会话标注、自动摘要 (18人日)
-  - 🔲 阶段4 (P2): 数据看板、知识库自动迭代 (17人日)
+**P1/P2功能开发任务 ✅ 全部完成**:
+  - ✅ 阶段2 (P1): 摇人按钮、满意度评价、排队系统、快速回复、知识库基础
+  - ✅ 阶段3 (P2): AI Wingman、会话标注、自动摘要
+  - ✅ 阶段4 (P2): 数据看板、知识库自动迭代（含图谱可视化+合并去重）
   - 📋 详细规格: `docs/02-产品需求/功能详细规格说明书-P1P2功能.md`
 
 **文档优化专项 (2026-07-04) ✅ 已完成**:
@@ -61,30 +61,64 @@
 - ✅ 前端：用户头像菜单"修改密码" (H5 ChatPanel)
 - ✅ 部署测试：API验证通过 ✅
 
-## 🔬 验真结论 (2026-07-07) — QA 严过关真实验证
+## 🔬 方案A 消息发送延时改造 — E2E 验真 (2026-07-08) ✅ 通过
 
-> 方法：真实执行代码 + 真实 pytest（非读码结论）。5 项看板标"✅已完成但需验真"的功能，本轮坐实结论。
+> 真实浏览器端到端实测（系统 Chrome + Playwright）。报告：`docs/06-测试质量/方案A-消息发送延时-E2E验证报告-20260708.md`，截图：`docs/06-测试质量/e2e-screenshots/`
 
-| # | 功能 | 看板标签 | 真实结论 | 偏差 |
-|---|------|---------|---------|------|
-| ① | 排队系统 | ✅已完成 | ✅ 真实可用（测试全绿） | 一致 |
-| ② | 知识库自动迭代 | ✅已完成 | ⚠️ 桩实现 + API 未挂载 | **严重** |
-| ③ | AI Wingman | ✅已完成 | ✅ 真实可用（降级兜底） | 一致 |
-| ④ | 管理后台 RBAC | ✅已完成 | 🔴 admin_users 鉴权 422 失效（源码 Bug） | **严重** |
-| ⑤ | 敏感词检测 | ✅已完成 | ⚠️ 隐私检测 Bug + 仅警告不拦截 | 中等 |
+**验证结论**：✅ 员工端发送消息**瞬时返回不阻塞 UI**（点击 1.26s 返回，`ai_reply:null`），AI 回复经 **WebSocket 打字机流式**推送（收到 `ai_reply_chunk` **343 帧**，2.3s 起渲染，Duckula 头像 + 1469 字完整内容正常）。
 
-**真实可用的：①、③（2 项）。实际不达标的：②、④、⑤（3 项）。**
+**⚠️ 顺带修复 1 个真实后端 bug（生产相关）**：WebSocket 握手时浏览器用子协议 `bearer.{token}` 传 token，后端 `ws_manager.connect/connect_employee` 读了 token 却未在 `accept()` 回显子协议 → 浏览器拒绝握手。此前被 3s 轮询兜底**掩盖**，生产坐席/员工 WS 实际走了轮询而非流畅打字机。已修复 `accept(subprotocol=...)`。
 
-### 关键缺陷（需工程侧修复）
-- **④【P0】RBAC**：`app/api/admin_users.py` 把装饰器当依赖用 `Depends(require_role("admin"))`，应为 `@require_role("admin")`。导致管理员用户 CRUD 全部接口每个请求 422，鉴权拦截从未生效。参考 `conversations.py` 写法修复。
-- **②【P1】知识库迭代**：`app/api/router.py` 第 278 行 `knowledge_iteration_router` 被注释未挂载（API 不存在）；且 `_generate_*_suggestion` 是 `TODO` 占位（`[待AI生成]`），AI 生成未实现。
-- **⑤【P1】敏感词**：`check_privacy_leak` 正则用 `\b` 边界，Python `re` 把中文当单词字符，致"中文+号码"场景手机号/身份证检测全失效；且命中仅 WARN 不 BLOCK，词库硬编码未接配置。
+**✅ 已部署生产 (2026-07-09 09:14)**：`docker cp` 修复文件进 `wecom_it_backend` 容器 + `docker restart`，重启后日志确认 H5 员工(tangzhenzhen)/坐席(sxn) WebSocket 连接 `[accepted]` 且**连接建立**（旧代码下浏览器会因未回显 subprotocol 拒绝握手，根本到不了 accepted）。commit `bacd34c` → cherry-pick `6db1c0e` 已推送 `origin/main`。Dify key 临时切换已还原回 `app-J3s8sHarZQ2SCaNF3xCppliL`（dev 验证用，备注于 compose）。
 
-### 本轮新增验证测试（仅测试，未改业务源码）
-- `tests/test_knowledge_iteration.py`（4/4 通过，含 `[待AI生成]` 桩断言）
+**另修复 3 个 dev 容器化环境阻断**（使「Docker dev 栈 + 真实浏览器 E2E」链路可用）：
+1. H5 应用无法挂载：dev compose 补挂载 `./frontend-h5/public:/app/public`（`duckula.webp` 镜像烘焙时缺失）
+2. Mock 登录 500：Vite 代理目标改为可配置 `VITE_PROXY_TARGET`（dev 注入 `http://backend:8000`）
+3. CSP 阻断 dev WS：`index.html` CSP `connect-src` 增加 `ws://localhost:8000`
+
+---
+
+## 🔬 验真结论 (2026-07-07) → ✅ 全部已修复 (2026-07-08)
+
+> 5 项验真发现的缺陷，经 RBAC BugFix + 知识库迭代全链路 + 隐私正则修复，**全部已解决**。
+
+| # | 功能 | 结论 | 修复 |
+|---|------|------|------|
+| ① | 排队系统 | ✅ 真实可用 | — |
+| ② | 知识库自动迭代 | ✅ 全链路（49文件/169测试） | Tier0+Tier1+P0串联+P2 |
+| ③ | AI Wingman | ✅ 真实可用 | — |
+| ④ | 管理后台 RBAC | ✅ 已修复（test_rbac 5/5） | 装饰器修复 |
+| ⑤ | 敏感词检测 | ✅ 已修复（隐私正则 \b→\d） | 89/89 PASS |
 - `tests/test_content_moderation.py`（11/13，2 失败即隐私 Bug 证据）
 - `tests/test_rbac_verification.py`（3/5，2 失败即 422 Bug 证据）
 
+## 🔬 #75 头像同步功能 复盘 (2026-07-07/08)
+
+> 软件团队快速模式交付（工程师 12/12 单测 + 103 回归通过）。**关键边界：验证的是代码逻辑，未做真实业务效果验证。**
+
+**已验证（代码层，07-08 23:00 真实再跑）**：`backend/tests/test_avatar_service.py` **12 passed in 0.77s**（5 TestCleanAvatarUrl + 5 TestSyncEmployeeAvatar + 2 TestSessionServiceAvatar）。仅 2 个 deprecation warning（`datetime.utcnow()`），与 #75 主线无关。
+
+**test_h5_oauth.py 6 失败归因**：抓 `test_callback_stores_token_in_redis:237 assert stored is not None` traceback 验证，根因是 `mock_redis`（fakeredis）跨 fixture 状态丢失 + redis 库 `setex` deprecated，**与 #75 avatar_service / sync_employee_avatar 无任何代码引用关系**——是历史遗留（与 QA 昨夜的"16 失败全在 test_h5_oauth.py"一致）。
+
+**git 真实状态（07-08 23:00 摸底）**：
+- HEAD = `ba068d3`，**#75 15 个文件中 14 个与 HEAD 一致**（avatar_service.py / test_avatar_service.py / h5.py OAuth 段 / agents.py / auth_qrcode.py / qrcode_service.py / dev_auth.py / auth_wecom_sso.py / session_service.py + 6 个前端 .vue），已被其他 agent 在 400ce3d / 9bb080d / ba068d3 等 commit 整合。
+- 仅 1 个 `M` = `backend/app/api/h5.py` 是别的 agent 的 h5_send_message AI 异步化重构（`dep_ai_handler` → `app.tasks.h5_ai_task.process_h5_ai_reply`），与 #75 无关。
+
+**为什么本地 / 预生产都看不到效果（5 因）**：
+1. **绑定登录动作**：#75 在每次登录时强制同步，已登录态不触发 → 改完代码不重登看不到变化。
+2. **mock / 测试账号**：本地 dev 走 `/api/h5/mock-login` 传固定 avatar；预生产测试账号企微通讯录可能未返回新头像。
+3. **企微通讯录缓存延迟**：企微通讯录 API 有缓存，换头像后不立即生效。
+4. **前端不主动重拉**：`employee.ts` 已登录不自动重拉 avatar，依赖登录时刷新。
+5. **token 登录态**：已持 token 进入不触发重新同步。
+
+**任务状态**：
+- ✅ Task #3（提交代码）：**completed — 变体结论：#75 已被 HEAD 含括，无需独立提交**。夜班 agent 已把 #75 散落到多个 commit（400ce3d / 9bb080d / ba068d3 等）。
+- ⏳ Task #1（端到端真实效果验证）：pending — 待真实企微账号换头像→退出重登实测
+- ⏳ Task #2（手动刷新兜底按钮）：pending
+- ⏳ Task #4（补 SSO/JS-SDK employee upsert 头像）：pending
+
+**下一步建议**：直接进 Task #1 端到端验真（最快闭环 #75 真实效果），或开 Task #2 兜底按钮（不依赖重登提升可用性）。等你通知启动。
+
 ## ✅ 最近搞定
 
 ### 2026-07-06 P1功能开发完成
@@ -131,6 +165,7 @@
 | 🆕 | v0.7.0 部署 + 35 项 E2E 验收 | 看 `docs/09-部署运维/deploy/10-一键部署操作包-v0.7.0.md` 6 步 + `docs/06-测试质量/testing-测试/E2E-CHECKLIST-v0.7.0.md` |
 | #100 | 消息推送策略优化与超时提醒 | ✅已完成：坐席回复仅推 H5，超时未回复发送企微提醒，10分钟后标记待关闭 |
 | 🆕 | 修 64 pre-existing 测试失败 | Role.data_scope 缺字段 / WecomService DI / test_message_experience 等 |
+| #75 | 头像同步功能完善 | 登录全路径强制同步 + 前端首字降级；代码已交付（12/12 单测 + 103 回归），**业务效果待端到端验真** | 🆕 等用户通知执行 |
 
 ---
 
@@ -161,7 +196,7 @@
 | # | 功能 | 需求ID | 预估工时 | 状态 |
 |---|---|---|---|---|
 | 🆕 P2-12 | 数据看板 | 服务数据统计+可视化 | 10人日 | ✅已完成 |
-| 🆕 P2-13 | 知识库自动迭代 | AI分析高频问题+建议更新 | 7人日 | ⚠️验真:桩+API未挂载 |
+| 🆕 P2-13 | 知识库自动迭代 | AI分析高频+建议更新+图谱可视化+合并去重+会话闭环 | 7人日 | ✅全链路(2026-07-08: 49文件, 169/169 PASS) |
 
 ---