docs: 移动蓝绿部署指南到 troubleshooting 目录

docs/03-技术架构/00-系统架构设计文档-v1.3.md

@@ -1,6 +1,6 @@
 # IT智能服务台 — 系统架构设计文档
 
-> **文档版本**: v1.4
+> **文档版本**: v1.5
 > **创建日期**: 2025-07-11
 > **最近更新**: 2026-07-04
 > **架构师**: 高见远 (Bob)
@@ -356,6 +356,43 @@ Wingman 是坐席工作台的 AI 辅助系统：
 | **数据映射** | 审批标题 → TodoItem.title / 审批状态 → TodoItem.status |
 | **依赖** | 需企微管理后台创建审批应用并授权 API |
 
+### 9.3 WebSocket 实时通讯技术方案
+
+> **新增日期**: 2026-07-05 | **状态**: 已实现
+
+#### 9.3.1 技术选型
+
+| 方案 | 优点 | 缺点 | 结论 |
+|------|------|------|------|
+| WebSocket | 双向实时、低延迟 | 需心跳维护 | ✅ 推荐 |
+| SSE | 简单单向 | 仅服务器→客户端 | ❌ 不适合 |
+| 轮询 | 实现简单 | 延迟高、资源浪费 | ❌ 不推荐 |
+
+#### 9.3.2 消息类型
+
+| 消息类型 | 方向 | 说明 |
+|----------|------|------|
+| `message_new` | Server→Client | 新消息推送 |
+| `message_recall` | Server→Client | 消息撤回 |
+| `typing` | Bidirectional | 对方正在输入 |
+| `presence` | Bidirectional | 在线状态 |
+| `ping/pong` | Bidirectional | 心跳保活 |
+
+#### 9.3.3 心跳机制
+
+- 客户端每 30 秒发送一次 ping
+- 服务端 60 秒内未收到 ping 断开连接
+
+#### 9.3.4 断线重连
+
+- 前端 WebSocket 断开后自动重连
+- 最大重连次数: 5
+- 重连间隔: 2s, 4s, 8s, 16s, 32s
+
+#### 9.3.5 降级策略
+
+WebSocket 连接失败或断开时，自动降级为轮询（每3-5秒）。
+
 ---
 
 ## 10. 安全设计
@@ -381,6 +418,56 @@ Wingman 是坐席工作台的 AI 辅助系统：
 | 角色来源追溯 | user_roles 表记录 source 和 assigned_by |
 | 管理端 IP 白名单 | 仅内网/VPN 可访问 |
 
+### 10.3 OTP 双因素认证技术方案
+
+> **新增日期**: 2026-07-05 | **状态**: 规划中
+
+#### 10.3.1 技术选型
+
+| 方案 | 优点 | 缺点 | 结论 |
+|------|------|------|------|
+| TOTP (Google Authenticator) | 开源成熟无需服务器 | 需手动绑定 | ✅ 推荐 |
+| 短信OTP | 用户无需安装App | 有成本，有延迟 | ❌ 不推荐 |
+| 邮箱OTP | 无需安装App | 有延迟，不实时 | ❌ 不推荐 |
+
+#### 10.3.2 认证流程
+
+```
+用户输入账号密码
+    ↓
+验证账号密码成功
+    ↓
+返回要求OTP验证
+    ↓
+用户输入OTP验证码
+    ↓
+验证OTP → 返回结果
+```
+
+#### 10.3.3 绑定流程
+
+```
+用户首次登录 → 系统检测未绑定OTP → 显示绑定页面 → 用户扫描二维码 → 输入验证码确认 → 绑定成功
+```
+
+#### 10.3.4 API 设计
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/api/auth/otp-bind` | 绑定OTP |
+| POST | `/api/auth/otp-verify` | 验证OTP |
+| POST | `/api/auth/otp-unbind` | 解绑OTP（管理员） |
+| GET | `/api/auth/otp-status` | 查询OTP绑定状态 |
+
+#### 10.3.5 数据库设计
+
+```sql
+-- 扩展 agents 表新增字段
+ALTER TABLE agents ADD COLUMN otp_secret VARCHAR(32) DEFAULT NULL;
+ALTER TABLE agents ADD COLUMN otp_bound BOOLEAN DEFAULT FALSE;
+ALTER TABLE agents ADD COLUMN otp_bound_at TIMESTAMP DEFAULT NULL;
+```
+
 ---
 
 ## 11. 复杂对话场景设计