# 任务说明书 — P0-1 生产 workers=2 改回 1（修复 WS 推送丢 50%）

> **版本**: v1.0 | **日期**: 2026-07-17

---

## 📋 基本信息

| 项目 | 内容 |
|------|------|
| **任务名称** | P0-1 生产 backend workers=2 改回 1，恢复 WS 单 worker 铁律 |
| **任务ID** | #78 |
| **优先级** | 🔴 P0 |
| **类型** | 部署优化 / Bug修复 |
| **状态** | 待开始 |
| **负责人** | 宋献 |
| **创建日期** | 2026-07-17 |
| **计划完成日期** | 2026-07-18 |

---

## 📥 输入项来源

### 问题证据

| 来源 | 说明 |
|------|------|
| `docker-compose.yml` | 主文件已 `--workers 1` ✅ |
| `docker-compose-override.yml:4` | **覆盖为 `--workers 2` ❌**（compose 自动合并 override） |
| `deploy-server/docker-compose.yml:115` | `--workers 2` ❌ |
| `deploy-server/docker-compose-green.yml:46` | `--workers 2` ❌ |
| `backend/app/tasks/h5_ai_task.py:10-14` | 头注释自述：ws_manager 进程内单例，多 worker 时 broadcast 静默丢失约 50% |

### 技术文档
| 来源文档 | 相关章节 | 说明 |
|----------|----------|------|
| `docs/02-技术文档/重构记录/00-v4.0重构总方案.md` | §三 批次 1 P0-1 | 方案出处 |
| `docs/02-技术文档/重构记录/01-问题验证清单.md` | C2 | 问题证据 |
| `docs/04-运维文档/部署运维/DEPLOY-GUIDE.md` | §4.3 铁律 1 | 部署铁律 |

---

## 📤 输出成果要求

### 交付物清单

| # | 交付物 | 类型 | 说明 |
|---|--------|------|------|
| 1 | `docker-compose-override.yml` | 配置 | **删除整个文件**（或改 `--workers 1`），推荐删除 |
| 2 | `deploy-server/docker-compose.yml` | 配置 | L115 `--workers 2` → `--workers 1` |
| 3 | `deploy-server/docker-compose-green.yml` | 配置 | L46 `--workers 2` → `--workers 1` |
| 4 | `backend/app/main.py` | 代码 | lifespan 启动日志打印醒目提示「WS 推送要求单 worker」+ `/health` 响应暴露 `pid` |

### 代码要求
- 仅配置变更 + main.py 增加 2 行日志，零业务逻辑变更
- 服务器部署用 v2_ops.py 上传 compose 文件后 `docker compose up -d backend`

### 文档要求
- 更新 `docs/02-技术文档/重构记录/README.md` §三 状态看板（#78 → 已完成）
- 填写 `docs/02-技术文档/重构记录/02-批次1-P0执行记录.md`

---

## 🔧 验证方式

### 功能验证

| 验证项 | 验证方法 | 预期结果 |
|--------|----------|-----------|
| compose 合并后 workers | 服务器执行 `docker compose -f docker-compose.yml -f docker-compose-override.yml config 2>/dev/null \| grep workers`（或仅主文件 config） | 输出 `workers: 1` 或 `--workers 1` |
| 容器进程数 | `docker exec wecom_it_backend ps aux \| grep uvicorn` | 仅 1 个 worker 进程 |
| WS 到达率 | H5 + 坐席端各发 10 条消息 | AI 回复 100% 到达（20/20） |
| /health 暴露 pid | `curl https://itsupport.servyou.com.cn/api/health` | 响应含 `pid` 字段 |

---

## ✅ 完成标准

- [ ] override 文件已删除（或 workers=1），deploy-server 两份已改
- [ ] 服务器 backend 重启，`docker compose config` 验证 workers=1
- [ ] 双端 20 条消息全部到达
- [ ] 状态看板已更新

---

## 📊 工作分解

| 子任务 | 预估工时 | 状态 |
|--------|----------|------|
| 本地修改 override + deploy-server 两份 compose | 15min | ⬜ |
| 上传服务器 + 重启 backend + config 验证 | 20min | ⬜ |
| main.py 增加启动提示 + /health pid | 15min | ⬜ |
| 双端 20 条消息到达率验证 | 20min | ⬜ |

---

## 📞 依赖与阻塞

| 依赖 | 说明 | 状态 |
|------|------|------|
| 无 | 独立任务，可最先执行 | — |

**停机影响**：backend 重启约 3-5 秒，WS 断连自动重连，无感知。

---

## 📈 变更记录

| 日期 | 变更内容 | 变更人 |
|------|----------|--------|
| 2026-07-17 | 创建任务 | 宋献 |