# workbuddy 任务 — 修消息优化推送遗留 P1-1~4

**触发日期**: 2026-06-14
**来源**: 之前评审报告 `docs/评审报告/workbuddy-2026-06-14-消息优化.md` 9.3 节遗留 4 P1
**Gitea 仓(公网 Funnel)**: `https://ds923plus.tail58d872.ts.net/simon/wecom_it_smart_desk`
**Gitea 仓(内网 LAN)**: `http://100.85.152.112:8418/simon/wecom_it_smart_desk`
**当前 main HEAD**: `3c1d563`
**workbuddy token**: 见 `.workbuddy/config.json` 的 `gitea.token` 字段

---

## ▶▶▶ 任务清单(按推荐度,4 项)起

### P1-1. upload 路径在容器本地(改 volume mount)

**问题**: 消息图片/文件上传路径(在容器内)会在容器重建时丢失。当前 docker-compose.yml 应该是 backend 容器内路径,**没挂载到 host** 或 NAS。

**修复**:
1. 编辑 `docker-compose.yml` 的 backend 服务:
   ```yaml
   backend:
     volumes:
       # 新增
       - backend-uploads:/app/uploads
   volumes:
     backend-uploads:
       driver: local
       driver_opts:
         type: none
         o: bind
         device: /volume1/docker/wecom-it-desk/uploads
   ```
2. `backend/app/api/messages.py` `upload_image` / `upload_message_file` 端点保存路径用 `UPLOAD_DIR` 配置项(从 `app.config` 读),不用硬编码
3. 加 `UPLOAD_DIR=/app/uploads` 到 `.env.example`
4. `nginx.conf` `/uploads/` 路径反代到 backend,或加 `location /uploads/ { root /volume1/...; }` 静态服务
5. `scripts/deploy.sh` 创建 `/volume1/docker/wecom-it-desk/uploads/` 目录(部署时)

**验收**:
- 容器重建后上传文件**不丢**
- `df -h` 看 host 上 `/volume1/.../uploads` 体积能涨

### P1-2. 消息状态字段走 Alembic 迁移

**问题**: `backend/app/models/message.py` 之前加了 `status` 字段(已发/已送达/已读/撤回/删除等),但 **alembic 迁移未生成**。

**修复**:
```bash
cd backend
alembic revision --autogenerate -m "add message status and recallable_until"
# 检查生成的迁移脚本
# 字段:
#   - status: String(20), default="sent", nullable=False
#   - recallable_until: DateTime, nullable=True
alembic upgrade head
```

**手动 SQL 不行**(评审报告已点出,部署步骤 6 引号未转义是历史错误)

**验收**:
- `alembic upgrade head` 不报错
- 生产数据库 `messages` 表有 `status` + `recallable_until` 字段

### P1-3. backend healthcheck 改用 Python 一行

**问题**: `docker-compose.yml` backend 用了 `curl http://localhost:8000/` 当 healthcheck,但**精简 backend 镜像没装 curl**(参考 [[backend-healthcheck-curl-pitfall]]),导致 `unhealthy` 但业务正常。

**修复**: 编辑 `docker-compose.yml`:
```yaml
backend:
  healthcheck:
    test: ["CMD", "python", "-c", "import socket; s=socket.socket(); s.connect(('localhost', 8000))"]
    interval: 30s
    timeout: 10s
    retries: 3
    start_period: 40s
```

或更稳(用 HTTP 检测):
```yaml
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/api/v1/system/health').read()"]
# 需要 backend 有 /api/v1/system/health 端点(可能需要新增)
```

**验收**:
- `docker ps` 显示 backend `healthy`(不再 `unhealthy`)
- 业务正常

### P1-4. ws_manager 实现消息状态广播

**问题**: 文档承诺了"消息状态广播"(撤回/已读/删除等事件推送),但 `ws_manager.py` 实际**没实现**。

**修复**: 在 `backend/app/services/ws_manager.py` 加方法:
```python
async def broadcast_message_status(
    self,
    conv_id: str,
    msg_id: str,
    status: str,
    extra: dict = None,
) -> int:
    """向会话所有参与方广播消息状态变更。
    
    Args:
        conv_id: 会话ID
        msg_id: 消息ID
        status: 新状态(sent / delivered / read / recalled / deleted)
        extra: 额外数据(可选,如 recall_by / recall_at)
    
    Returns:
        推送到客户端数量
    """
    # 1. 查会话所有参与方(agent_id + employee_id)
    # 2. 找每个参与方的 WebSocket 连接
    # 3. 发 JSON 消息 {"type": "message_status", "msg_id": ..., "status": ..., "extra": ...}
    # 4. 返回推送数
    ...
```

调用方:`messages.py` `recall_message` / `delete_message` / `mark_read` 在改 DB 状态后,**调 `await ws_manager.broadcast_message_status(...)`**。

**验收**:
- 端到端测试:坐席 A 撤回消息 → 坐席 B + H5 员工实时收到 `message_status` 推送
- 前端(`useWebSocket.ts`)处理 `message_status` 类型消息(更新 UI)

## ▼▼▼ 任务清单止

---

## 🔄 工作流(等 workbuddy 修完 4 项后)

1. workbuddy 修完 → 提交 commit 到 Gitea
2. 通知 Claude 评审
3. Claude 评审(对照 4 项 + 跑相关测试)
4. 合并到 main
5. 关 #23

## 🔴 评审历史(防 workbuddy 再犯)

参考评审报告 `docs/评审报告/workbuddy-2026-06-14-消息优化.md` 9.5 节:

- **P0 比例 46% (6/13) 过高** —— 后续推送需**强制走评审流程**
- pre-commit 检查建议(Claude 可生成脚本):新增端点无 `Depends(...)` 鉴权 → 拒绝推送
- 4 P1 一旦 P0 修完就推,**不要在评审未消化前叠加新功能**

## 关联

- 评审主报告: `docs/评审报告/workbuddy-2026-06-14-消息优化.md`
- 风险跟踪表: 第九节(P1-1~4 状态追踪) + 即将加第十一节
- Claude 记忆: `review-messages-2026-06-14.md`
- Gitea 仓: `https://ds923plus.tail58d872.ts.net/simon/wecom_it_smart_desk` (公网 Funnel)