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

# 2026-06-08 工作日志

## 主要工作：NAS部署调试 + PRD审读

### 解决的问题

1. **部署包目录结构问题** — 之前用 PowerShell `Compress-Archive` 打包时，`nginx/nginx-nas.conf` 被压到了 zip 根目录，导致 NAS 解压后路径错误。已改用 Python `zipfile` 重新打包，确保目录结构正确。

2. **Windows `\r\n` 换行符问题** — `.env` 文件从 Windows 上传到 NAS (Linux) 后，`\r` 被当成普通字符读入变量值，导致：
   - `POSTGRES_DB=wecom_it_desk\r` → 后端连接数据库 `wecom` 失败
   - 修复方法：`sed -i 's/\r$//' .env`

3. **postgres 健康检查发现错误数据库** — `docker-compose.nas.yml` 第61行：
   ```yaml
   test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-wecom}"]
   ```
   `pg_isready` 默认连接与用户名同名的数据库 `wecom`，但数据库实际叫 `wecom_it_desk`。
   修复：改为 `pg_isready -U ${POSTGRES_USER:-wecom} -d ${POSTGRES_DB:-wecom_it_desk}`

4. **Docker 卷清理问题** — `docker volume rm` 需要容器先停止才能删除。正确方法：`docker compose -f docker-compose.nas.yml down -v`（加 `-v` 参数会连卷一起删除）

### 最终成功标志

后端启动日志显示：
```
✅ 使用 PostgreSQL 数据库: postgres:5432/wecom_it_desk
✅ 数据库表检查/创建完成
✅ 默认数据初始化完成
✅ Application startup complete.
```

### 待确认

- [ ] nginx 容器是否正常启动（之前报错 `nginx-nas.conf does not exist`）
- [ ] Cloudflare Tunnel 是否正常转发流量
- [ ] Mock 登录页面是否能正常访问

### 下一步

1. 确认 nginx 状态，若配置文件缺失则重新上传
2. 测试 Mock 登录功能（访问 `https://itdesk.amanzac.com/`）
3. 配置企微 AI 机器人转人工链接为 H5 页面

### 下午追加 — API 响应格式修复

4. **Cloudflare Tunnel 503 修复** — cloudflared 加 `--url http://nginx:80` 参数解决 "No ingress rules"
5. **Mock 登录端点 404** — 后端 Docker 镜像是旧代码，`build --no-cache` + `up -d` 重建
6. **Mock 登录参数** — 正确参数名 `employee_id`（非 `user_id`）
7. **数据库缺列** — conversations 表缺 impact_scope/is_blocking/emotion_state/dify_conversation_id，ALTER TABLE SQL 已提供
8. **API 响应格式不统一** — todo_items.py / troubleshooting_templates.py / employees.py 三个文件直接返回 Pydantic 模型，未用 `success_response()` 包裹为 `{code:0, data:{}, message:"success"}`，导致前端拦截器 `res.code !== 0` 报"请求失败"。已全部修复为 `success_response(data=...)` 格式
9. **员工端超时** — H5 前端调用 `/h5/conversations/current`，需先执行 ALTER TABLE 修复缺列才能正常工作
10. **企微IP白名单** — NAS 出口 IP 117.147.35.138 未加白名单（errcode=60020），后端已降级放行

### 深浅色主题同步 v5.3（下午继续）

11. **CSS变量体系完全同步原型v5.3**：
    - accent 统一为 `#3b82f6`（替换 Agent端 `#409eff` + H5端 `#1989FA`）
    - 新增变量：`--border`/`--text-muted`/`--success-soft`/`--danger-soft`/`--warning-soft`/`--accent-soft`/`--purple`/`--orange`/`--shadow`/`--transition`/`--radius`
    - 深色模式色值同步：bg-primary=#0f1923, bg-secondary=#151f2b, bg-tertiary=#1a2736 等

12. **Agent端 87+ 处硬编码颜色全部替换为CSS变量**：
    - 影响组件：UserInfoPanel(15) / RiskAlert(12) / InviteDialog(11) / UserInfoBar(10) / MessageBubble(7) / FlowchartNode(7) / AiDraftBubble(5) / TopBar(4) / QuickReplyPanel(2) / ReplyBox(1) / TodoPanel(2) / TroubleshootBar(1) / ApprovalDetail(4) / TicketDetail(2) / DeviceDetail(2) / AiRecommendInline(1) / Login
    - global.css 中 tag-badge-*/urgency-star/message-agent/ai-tag/conversation-avatar/it-badge 的 #fff → var(--bg-secondary)

13. **H5端 10 处硬编码颜色替换**：
    - ChatView(2) / ChatPanel(1) / MessageBubble(1) / AiHelperPanel(1) / ComingSoon(1) / ShakeButton(2) / CallAgentModal(2)

14. **两端构建验证通过**：
    - Agent: `dist/index.html` + `dist/assets/Workspace-*.css` + `dist/assets/index-*.js`
    - H5: `dist/index.html` + `dist/assets/ChatView-*.css` + `dist/assets/index-*.js`
    - ⏳ 待部署到 NAS（scp 上传 + `docker restart wecom_it_nginx`）

15. **NAS部署完成**（内网IP 192.168.3.200，非 10.80.0.129）：
    - scp 上传 H5 + Agent dist 至 NAS
    - nginx 重启后前端生效

16. **代码同步检查与修复**（NAS更新后验证本地代码一致性）：

22. **坐席工作台原型 v5.4 调整**：
    - 基于 v5.3 创建 `agent-workspace-v5_4.html`
    - 左栏会话列表新增：头像 + 新消息圆点指示器（3色：紧急红/普通蓝/低优灰）+ 处理对象缩略头像
    - 我的会话：左侧头像（员工）+ 圆点（有/无新消息）+ 右侧缩略头像（处理对象=员工本人）
    - 同事会话：左侧头像（员工）+ 圆点 + 右侧缩略头像（处理坐席）
    - 待办事项：右侧新增 ki-avatar 缩略头像（处理对象=上报人/部门）
    - 历史会话：仅头像，无圆点，无缩略头像
    - 举手图标沿用原有 `conv-tag-urgent` 样式
    - 所有原有样式和内容完整保留
    - 修复 ConversationItem.vue 遗漏 2 处：`#9b59b6` → `var(--purple)`、`#c0c4cc` → `var(--text-placeholder)`
    - 修复 H5 MessageBubble.vue 注释：`#1989FA` → `var(--accent)`
    - 全量扫描确认：所有残留硬编码色值均为可保留项（Login渐变 + SVG插图）

24. **Vue3 前端代码同步 v5.4 原型改动**：
    - ConversationItem.vue 重写：头像渐变色(av-blue~av-pink 7色) + 新消息圆点(dot-urgent红/dot-normal蓝/dot-muted灰3色) + 处理对象缩略头像(ta-blue~ta-pink) + section prop(my/colleague/history)控制缩略头像逻辑
    - ConversationList.vue 重写：取消三段折叠(section-header/ArrowDown/myExpanded等全部移除)，三区始终展开扁平显示
    - TodoPanel.vue：待办条目右侧新增 ki-avatar 缩略头像(ka-blue~ka-red 5色，hash分配)
    - ReplyBox.vue 重写：上方4px拖拽手柄(调整输入区高度+textarea同步) + 快捷工具栏(表情/图片/截图/文件/语音/远程协助/快速回复 7个按钮+分隔线+hover提示气泡+三角箭头) + 输入框+发送按钮合为圆角卡片(.chat-input-card) + textarea resize:none + 发送按钮渐变蓝紫(accent→purple) + 聚焦时卡片蓝色描边+外发光
    - Workspace.vue 重写：左右栏border移除+6px拖拽手柄替代(resize-handle) + 可拖拽调整左栏/右栏宽度(200~500px) + mousedown/mousemove/mouseup事件处理 + body光标切换+userSelect控制
    - global.css 更新：workspace-sidebar/assistant 去掉border+添加position:relative + 新增resize-handle样式(hover变蓝+::after显示⋮) + conversation-item 改为flex+gap+圆角+border + 新增conv-avatar-wrap/new-msg-dot(3色)/conv-target-avatar(7色) + 新增ki-avatar(5色) + conversation-info改为flex:1+min-width:0

23. **坐席工作台原型 v5.4 二次调整**：
    - 取消会话分类折叠：我的会话/同事会话/历史会话全部始终展开，移除折叠箭头和 collapsed 类
    - 消息输入框：padding 上下间距调整，上边框从 1px 改为 3px solid var(--border) 做视觉分隔
    - 中间栏左右边框：改为拖拽手柄（6px宽），鼠标悬停变蓝+显示拖拽指示符，可手动拖拽调整左栏/右栏宽度（范围200~500px）
    - 原型 v5.3 accent=#3b82f6 已与代码完全一致
    - 后端/配置文件不涉及主题变更，无需更新

17. **企微内嵌网页无法加载修复**：
    - 根因1：OAuth2 回调地址不匹配 — 后端默认构造 `/h5/`，Nginx 只有 `/itdesk/`
    - 修复1（前端）：`employee.ts` 的 `getOAuthAuthorizeUrl()` 传入 `redirect_uri` 参数
    - 修复2（后端）：`h5.py` 默认回调从 `/h5/` 改为 `/itdesk/`
    - 根因2：可信域名/OAuth2回调域需备案主体匹配 → 当前域名无法通过验证
    - 方案B落地：创建 `.env.production` 清空 `VITE_WECOM_CORP_ID`，关闭 OAuth2 走 Mock 登录
    - H5 构建通过，待部署至 NAS
    - 后续拿到公司备案域名后删除 `.env.production` 即可切回 OAuth2

19. **PRD 审读与问题标注**：
    - 全面审读 PRD.md（1552行），对比 15个API文件、13个模型文件、9个Service类
    - 发现 31 项需明确/细化问题：P0×5 + P1×11 + P2×15
    - P0 核心矛盾：PRD 定义"阶段一不接AI/不用WebSocket"，但代码已深度集成
    - P0 最大阻断：OAuth2不可用 + 端到端流程从未验证
    - P1 关键缺失：H5 WebSocket未实现、排队系统未实现、满意度评分未实现、数据模型文档严重滞后
    - 建议：PRD 升版到 v1.0，新增 Non-goals/Launch Criteria/安全/监控章节

20. **战略观点确认与PRD v1.0更新**：
    - 用户确认四个战略观点：①资源审批期并行推进 ②管理后台为第三端 ③AI混合策略 ④零基础原则
    - 确认三系统集成：Dify管配置/RAGFlow阈值自动推送/数据平台短期DB只读+iframe长期API
    - 确认管理后台10大模块（功能开关P0/坐席管理P0/分配模式P1/快速回复P1/主题P2/会话监控P1/数据看板P1/流程图P1/知识库P2/外部集成P0~P2）
    - 确认消息分配6种模式（轮询/手动/最少活跃/加权/技能匹配/优先队列）渐次启用
    - 确认AI混合策略L1~L4四层架构：标注粒度B（标注+实际回复内容），迭代触发B（阈值推荐）
    - 确认阶段细化：1A/1B/1C → 2A/2B/2C/2D → 3A/3B/3C → 4A/4B/4C
    - 确认零基础边界：管理后台配置一切，代码修改需开发但控制颗粒度，操作者=坐席组长
    - PRD 升版至 v1.0，新增 §18管理后台远景规划 + §19系统生态与集成规划 + §20阶段细化与并行推进策略
    - MEMORY.md 同步更新：五阶段细化 + 管理后台 + AI混合策略 + 系统生态 + 零基础原则

21. **现实校准更新**：
    - 消息分配模式：当前1人足够，手动接单完全满足，6种模式为远景按坐席规模渐次解锁
    - 排查流程图+Dify实现路径确认4步：JSON导入导出→Dify变量/知识条目导出→HTTP回调分支→可视化拖拽
    - PRD §18.3 更新为"手动接单优先+远景渐次解锁"，§19.7 细化为分阶段实现路径
    - §20.2B 和 §20.3 推荐事项同步更新

15. **H5端API超时问题确认已解决**：
    - 后端日志显示 `/h5/user` → 200, `/h5/conversations/current` → 200
    - nginx 代理链路正常：`localhost:18080/api/h5/approval-links` → HTTP 200 + 数据
    - 之前超时是后端重启未就绪的瞬时问题

---

## 技术笔记

### NAS 部署关键配置

- **Cloudflare Tunnel Token** 已配置：`CF_TUNNEL_TOKEN=eyJhIjoi...`
- **企微配置** 已填入：
  - `WECOM_CORP_ID=wwa8c87970b2011f41`
  - `WECOM_AGENT_ID=1000133`
  - `WECOM_SECRET=EOtQslW7WD8Rna8Nm9WnwCW-ozHP3tustL4mFnet6O8`
- **Mock 登录已启用**：`MOCK_LOGIN_ENABLED=true`

### 文件位置（NAS）

```
/volume1/docker/wecom-it-desk/
├── docker-compose.nas.yml
├── .env                    # 从 .env.nas 复制并填入真实值
├── nginx/
│   └── nginx-nas.conf     # ← 之前缺失，已重新打包
├── frontend-h5/dist/       # H5 员工端静态文件
├── frontend-agent/dist/    # 坐席工作台静态文件
└── backend/                # 后端源码（会构建为 Docker 镜像）
```