# IT智能服务台 - 版本更新说明

**版本**: v1.1.0
**更新日期**: 2026-06-14
**文档状态**: 待审核

---

## 一、本次更新内容

### 1.1 新增功能

| 功能 | 说明 | 优先级 |
|------|------|--------|
| 消息撤回 | 2分钟内可撤回自己的消息 | P0 |
| 消息删除 | 删除自己的消息 | P0 |
| 消息状态 | 支持 sending/sent/delivered/read/recalled 状态 | P0 |
| 标记已读 | 一键标记会话已读 | P1 |
| 图片上传 | 支持图片上传（≤10MB） | P1 |
| 文件上传 | 支持文件上传（≤10MB） | P1 |

### 1.2 架构优化

| 优化项 | 说明 |
|--------|------|
| Health Check | 所有容器已配置健康检查 |
| 自动重启 | 容器崩溃自动重启（restart: unless-stopped） |
| AI Gateway 设计 | 预留多模型切换架构 |

### 1.3 安全增强

| 功能 | 说明 |
|------|------|
| OTP 双因素认证 | 访问管理后台时二次验证 |
| 操作审计 | 关键操作日志记录（规划中） |

---

## 二、需要同步的代码

### 2.1 后端文件

| 文件 | 改动 | 说明 |
|------|------|------|
| `app/models/message.py` | 修改 | 添加 status、recallable_until 字段 |
| `app/api/messages.py` | 修改 | 添加撤回/删除/标记已读/上传 API |
| `app/api/ws_manager.py` | 修改 | 添加消息状态广播 |
| `docker-compose.yml` | 修改 | healthcheck 已配置 |

### 2.2 数据库变更

```sql
-- 需要执行的 SQL 迁移
ALTER TABLE messages ADD COLUMN status VARCHAR(20) DEFAULT 'sent';
ALTER TABLE messages ADD COLUMN recallable_until TIMESTAMP;
```

### 2.3 前端文件（如果有）

| 文件 | 说明 |
|------|------|
| 消息操作菜单 | 撤回/删除按钮 |
| 消息状态显示 | 状态图标 |
| 已读标记 | 一键已读 |

---

## 三、部署步骤

### 3.1 本地打包

```bash
# 后端打包
cd backend
docker build -t wecom-it-desk-backend:latest .

# 导出镜像
docker save wecom-it-desk-backend:latest -o wecom-it-desk-backend.tar
```

### 3.2 服务器部署

```bash
# 1. 上传镜像到堡垒机
# 堡垒机: sxn@10.212.189.210:2222 (OTP)
# 目标路径: /tmp/

# 2. SSH 到正式服务器
ssh sxn@10.212.189.210 -p 2222
ssh 10.90.5.110

# 3. 导入镜像
docker load -i /tmp/wecom-it-desk-backend.tar

# 4. 解决容器冲突（重要！）
docker rm -f wecom_it_redis wecom_it_backend wecom_it_postgres wecom_it_nginx 2>/dev/null

# 5. 重新启动
docker compose -p root up -d

# 6. 执行数据库迁移
docker compose exec backend python -c "from app.database import engine; engine.execute('ALTER TABLE messages ADD COLUMN status VARCHAR(20) DEFAULT 'sent'')"
```

---

## 四、验证清单

### 4.1 健康检查

| 检查项 | 命令 | 预期结果 |
|--------|------|----------|
| 后端服务 | `curl -s http://localhost:8000/health` | `{"status": "ok"}` |
| Nginx | `curl -s http://localhost:80/itdesk/health` | `{"status": "ok"}` |
| 数据库 | `docker compose exec backend python -c "from app.database import engine; print('OK')"` | OK |
| Redis | `docker compose exec redis redis-cli ping` | PONG |

### 4.2 API 测试

| API | 方法 | 测试命令 |
|-----|------|----------|
| 撤回消息 | POST | `curl -X POST http://localhost:8000/api/messages/{id}/recall` |
| 删除消息 | DELETE | `curl -X DELETE http://localhost:8000/api/messages/{id}` |
| 标记已读 | POST | `curl -X POST http://localhost:8000/api/conversations/{id}/mark-read` |
| 图片上传 | POST | `curl -X POST -F "file=@test.jpg" http://localhost:8000/api/messages/image` |

### 4.3 功能测试

| 功能 | 测试场景 | 预期结果 |
|------|----------|----------|
| 消息发送 | 发送文本消息 | 消息正常显示 |
| 消息撤回 | 2分钟内撤回 | 状态变为 recalled |
| 消息撤回 | 超过2分钟 | 返回 403 错误 |
| 标记已读 | 点击已读 | 所有消息标记为已读 |

---

## 五、已知问题与限制

### 5.1 待解决

| 问题 | 状态 | 说明 |
|------|------|------|
| 容器冲突 | 进行中 | 需指定项目名 `-p root` |
| 前端同步 | 待确认 | 可能需要更新前端代码 |

### 5.2 已知限制

| 限制 | 说明 |
|------|------|
| 单节点部署 | MVP 阶段保持单节点 |
| 文件大小 | 单文件 ≤10MB |
| 撤回时间 | 2分钟后不可撤回 |

---

## 六、回滚方案

如果部署失败，执行：

```bash
# 停止服务
docker compose -p root down

# 恢复旧镜像（如果有备份）
docker load -i wecom-it-desk-backend-old.tar

# 使用备份的配置启动
docker compose -p root up -d
```

---

## 七、联系人

| 角色 | 联系人 | 说明 |
|------|--------|------|
| 产品负责人 | 许清楚 | PRD 确认 |
| 技术负责人 | 寇豆码 | 代码审查 |
| QA 负责人 | 严过关 | 测试验证 |
| 运维负责人 | 宋献 | 部署执行 |

---

**文档版本**: 1.0
**审核状态**: 待审核