# 企微IT智能服务台 — 项目总览与部署手册

> **版本**: v2.1 | **日期**: 2026-06-03 | **编制**: 宋献（IT支持组组长）
> **目标读者**: **管理者 / 架构师 / 运维** — 了解项目全貌、架构决策、部署与运维操作

---

## 目录

1. [项目概述](#一项目概述)
2. [系统架构](#二系统架构)
3. [三步演进路径](#三三步演进路径)
4. [现有系统复用评估](#四现有系统复用评估)
5. [正式环境部署方案](#五正式环境部署方案)
6. [部署操作手册](#六部署操作手册)
7. [运维管理](#七运维管理)
8. [开发交付状态](#八开发交付状态)
9. [附录](#九附录)

---

## 一、项目概述

### 1.1 背景与痛点

公司约 **6000 人**，全国设分子机构，使用企业微信作为内部 IM。当前 IT 服务存在三大痛点：

| 痛点 | 现状 | 影响 |
|------|------|------|
| 员工绕过 AI 直接找人工 | 可通过关键词直通人工坐席，首次后永久记忆 | AI 筛选率极低，人工成本高 |
| AI 转人工需另开窗口 | 跳转到企微"员工服务"模块，与 AI 对话割裂 | 体验差，员工困惑 |
| 无法跨主体共享 | 企微"员工服务"不支持互联企业应用共享 | 跨企业服务不可达 |

### 1.2 核心方案

**自研 IT 服务坐席系统**，替代企微内置的"员工服务"模块：
- 基于企微自建应用消息 API，所有消息由自己的服务器接管
- 分三步渐进式构建：M1 消息接管 → M2 AI 接入 → M3 知识库闭环
- 当前处于 **M1（消息接管 + 极简坐席）开发完成，部署配置中**

### 1.3 核心设计理念

传统"串行排队"改为**"并行协作"**——AI 全程在线，人工随时介入：

| 角色 | 工作方式 |
|------|---------|
| AI | 全程在线，所有对话可见 |
| 坐席 | 随时介入，AI 始终在旁辅助 |
| 员工 | 同一窗口，AI 和人工无缝切换 |

---

## 二、系统架构

### 2.1 部署架构总览（预生产环境）

> **当前阶段**：预生产环境。智能咨询系统与 IT 数据查询平台**分别部署在不同主机**，通过 Nginx 路径路由共用域名 `it-dataquery.dc.servyou-it.com`。正式环境将迁移到 K8s 集群。

```
浏览器 ──→ it-dataquery.dc.servyou-it.com:80
                  │
                  ▼
         ┌─── nginx (本系统主机) ───────────────┐
         │                                      │
         │  /itdesk/*  → H5 员工端 SPA         │
         │  /itagent/* → 坐席工作台 SPA        │
         │  /api/*     → backend:8000 (FastAPI) │
         │  /ws/*      → backend:8000 (WS)      │
         │  /*         → 数据平台主机（远程IP）  │  ← 跨主机代理
         │                                      │
         └──────────────┬───────────────────────┘
                        │ 本机 Docker 网络
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
    ┌──────────┐ ┌──────────┐ ┌──────────┐
    │ backend  │ │ postgres │ │  redis   │
    │ :8000    │ │ :5432    │ │ :6379    │
    └──────────┘ └──────────┘ └──────────┘
```

| 对比项 | 预生产（当前） | 正式环境（未来） |
|--------|-------------|---------------|
| 部署方式 | Docker Compose（单主机） | K8s 集群（高可用） |
| 与数据平台关系 | 不同主机，Nginx 远程代理 | 独立 K8s 集群 |
| 域名 | 共用 `it-dataquery.dc.servyou-it.com` | 独立域名或 K8s Ingress |

### 2.2 技术栈

| 层级 | 技术选型 | 说明 |
|------|---------|------|
| 反向代理 | Nginx | 统一入口、路径路由、WebSocket 代理 |
| 后端框架 | FastAPI (Python 3.12) | 异步、自动 OpenAPI 文档、类型安全 |
| 数据库 | PostgreSQL 16 | 会话/消息/坐席/配置 持久化（9 张表） |
| 缓存 | Redis 7 | access_token 缓存（TTL 7200s）、JWT 会话 |
| ORM | SQLAlchemy 2.0 (async) | 异步 session、声明式模型 |
| 数据库迁移 | Alembic | 所有表结构变更通过迁移脚本管理 |
| 坐席前端 | Vue3 + ElementPlus + Pinia | 企业级组件库，三栏工作台 |
| 员工 H5 | Vue3 + Vant4 + Pinia | 移动端组件库，企微 WebView 兼容 |
| 容器化 | Docker + Docker Compose | 4 容器一键启停 |

### 2.3 数据库核心表（9 张）

| 表名 | 用途 | 关键字段 |
|------|------|---------|
| `conversations` | 会话主表 | employee_id, status, urgency_score(1-5), tags(JSON), is_vip, participants(JSON) |
| `messages` | 消息记录 | sender_type(employee/agent/ai/system), content, msg_type |
| `agents` | 坐席信息 | user_id, status(online/offline/busy), current_load |
| `quick_reply_templates` | 快速回复模板 | category, title, content(支持 {变量}) |
| `system_configs` | 系统配置 | config_key, config_value（关键词/阈值/话术等） |
| `funny_phrases` | 趣味话术 | scene(6 种场景), content, tone, is_active |
| `approval_links` | 审批流程链接 | category(IT/HR/行政/财务), title, url |
| `software_downloads` | 软件下载入口 | category, name, version, platform, download_url |
| `agent_notes` | 坐席备注 | conversation_id, agent_id, content |

### 2.4 API 接口分组

| 分组 | 路径前缀 | 核心接口 |
|------|---------|---------|
| 企微回调 | `/api/wecom/callback` | GET 验证 URL、POST 接收消息 |
| 会话管理 | `/api/conversations` | 列表/详情/状态/置顶/代办/接单/邀请/退出/移除参与者 |
| 消息管理 | `/api/conversations/{id}/messages` | 消息列表/发送 |
| 坐席管理 | `/api/agents` | 列表/登录/状态切换 |
| H5 用户端 | `/api/h5/*` | 会话/摇人/审批链接/软件下载/OAuth |
| WebSocket | `/ws/{agent_id}` | 实时推送（坐席端） |

统一响应格式：`{ "code": 0, "data": {}, "message": "success" }`

### 2.5 消息收发全链路

```
员工发消息 → 企微回调解密 → 消息路由 → 评分标记 → 入库 → 坐席 WS 推送 → 坐席回复 → 企微主动推送 → 员工同一窗口收到
```

**坐席端通信**：已升级为 WebSocket 实时推送（2026-06-03），替代原计划的短轮询：
- 心跳保活：前端每 30s 发 ping，后端回 pong
- 断线重连：指数退避（1s→2s→4s→...→30s 上限）
- 降级策略：WS 断连时自动降级为 3s 轮询

### 2.6 会话排序与评分规则

**排序**: 紧急 → 举手 → 需介入 → 活跃 → AI处理中 → 已结单（同级按时间倒序）

**紧急度评分**: `基础分(关键词) + 情绪加成 + VIP加成 + 重复追问加成`，范围 1-5

**标记系统**:

| 标记 | 图标 | 触发条件 |
|------|------|---------|
| VIP | 红色 | 企微通讯录规则匹配 |
| 举手 | 黄色 | 员工说关键词或点击摇人按钮 |
| 需介入 | 橙红 | 同一问题追问 >3 轮 |
| 情绪 | 红色 | 关键词匹配（急/崩溃/投诉等） |

---

## 三、三步演进路径

| 里程碑 | 周期 | 核心交付 | 状态 |
|--------|------|---------|------|
| **M1** 消息接管 + 极简坐席 | 6-8 周 | 企微 API 链路验证 · 坐席三栏工作台 · 员工 H5 双栏 · 邀请功能（多人会话协作） | ✅ 代码完成，部署中 |
| **M2** AI 机器人接入 | M1 后 4-6 周 | 千问/Dify/RAGFlow 接入 · AI 前置筛选 · 排队系统 | 📋 计划中 |
| **M3** 知识库闭环迭代 | M2 后 4-6 周 | 坐席标注系统 · 千问自动分析 · 知识库自优化 | 📋 计划中 |

### M1 当前进度（2026-06-03）

| 模块 | 状态 |
|------|------|
| PRD + 架构设计 | ✅ 完成 |
| 后端代码（45+ 文件，7 API 组） | ✅ 完成 |
| 坐席前端（三栏工作台 + WebSocket） | ✅ 完成 |
| 员工 H5（双栏 + 摇人按钮 + 呼叫坐席） | ✅ 完成 |
| 邀请功能（多人会话协作 — PRD §21） | 📋 计划中（M1 范围） |
| 前端功能联调验证 | ✅ 完成（2026-06-03） |
| 测试用例（116 条 pytest） | ✅ 完成 |
| Alembic 数据库迁移 | ✅ 完成 |
| 前端构建产物（dist/） | ✅ 完成 |
| 远程服务器部署 | 🔧 待 SSH 账号 |

### M2 核心改动

只改路由层逻辑，其余不动：
```
M1: 新会话 → 坐席队列
M2: 新会话 → AI 先回答 → AI判断/用户触发 → 坐席队列
```
新增：千问对话模型、RAGFlow 知识库检索、Dify 编排平台、排队系统。目标：AI 首答率 ≥ 80%。

### M3 知识库迭代闭环

```
坐席日常标注 ──→ 千问分析 ──→ 自动处理 ──→ 知识库增强
(正确/错误)      (缺文档/过时)                    │
      ↑                                           │
      └──────────── 持续循环 ─────────────────────┘
```

---

## 四、现有系统复用评估

### 4.1 核心复用（直接影响新系统架构）

| # | 资源 | 复用方式 | 新系统对应 |
|---|------|---------|-----------|
| 1 | Dify Workflow | 直接复用，M2 阶段接入 AI 回复 | 坐席助手 AI 面板 + 自动回复 |
| 2 | dify2openai 桥接 | 直接复用 API | 后端调用 AI 的入口 |
| 3 | RAGFlow 知识库 | 直接复用，M3 阶段混合标注迭代 | 知识库管理 + 标注闭环 |
| 4 | Qwen3-30B 大模型 | 直接复用 | AI 对话底层模型 |
| 5 | bge-m3 向量模型 | RAGFlow 内置，直接复用 | 知识库检索向量化 |
| 6 | Dify 数据库（只读） | 读取 messages 表，同步历史数据 | 历史会话数据迁移 + 统计 |
| 7 | 企微自建应用 | 直接复用应用凭证 | 消息收发的企微入口 |

### 4.2 基础设施复用（零耦合）

| 资源 | 复用方式 | 耦合度 |
|------|---------|--------|
| 企微自建应用凭证 | 配置文件引用（只读） | 零耦合 |
| Dify Workflow API | HTTP 调用 | 外部依赖 |
| RAGFlow 知识库 | HTTP 调用 | 外部依赖 |
| Qwen3-30B 大模型 | HTTP 调用 | 外部依赖 |
| SSL 证书文件 | Nginx 挂载只读 | 零耦合 |

### 4.3 关键结论

> 代码层面复用率约 15%（主要是业务逻辑和 SQL 查询），基础设施和 AI 能力复用率约 70%。
> 新系统用 **FastAPI + SQLAlchemy 2.0**，不沿用旧 Django 代码。底层业务逻辑可参考移植。

---

## 五、正式环境部署方案

### 5.1 核心决策原则

基于四个约束条件：

| # | 约束 | 推导原则 |
|---|------|---------|
| 1 | 对现有正式环境架构影响最小 | **物理隔离 > 逻辑隔离** |
| 2 | 避免变更影响现有服务 | **独立 Nginx 入口** |
| 3 | 减少服务依赖 | **最小化外部依赖** |
| 4 | 避免责任不清 | **独立数据库 + 独立 Redis** |

> **一句话**：新系统作为**独立服务单元**部署，与现有智能 IT 数据平台（Django）在物理资源层面完全解耦，仅通过 HTTP API 调用共享 AI 能力。

### 5.2 关键隔离策略

| 隔离层面 | 方案 | 效果 |
|---------|------|------|
| 服务器级 | 独立 VM，不共用宿主机 | 挂了不影响旧系统 |
| 网络级 | Docker 内部网络，PG/Redis 不暴露宿主机端口 | 外部无法直连数据库 |
| 存储级 | 独立命名卷，不共用 Volume | 数据完全隔离 |
| 域名级 | 路径路由（共用域名） + 独立 Nginx 容器 | `/itdesk/`、`/itagent/`、`/api/` 归属本系统 |
| 认证级 | JWT + 独立 Redis | 账户体系独立 |
| 依赖级 | 仅 HTTP 调用外部 AI 服务 | 外部服务故障只影响 M2 功能 |

### 5.3 与现有系统的解耦修正

原复用评估中的部分共享方案已修正为独立部署：

| 原建议 | 修正方案 | 理由 |
|--------|---------|------|
| 同机部署于 10.80.0.86 | 独立服务器/VM（或同机端口分离+独立 compose） | 避免端口冲突、资源争抢 |
| Redis 复用同实例 | 独立 Redis 容器 | FLUSHDB 误操作、内存 OOM 互相影响 |
| 使用旧系统 Nginx | 独立 Nginx 容器 | 变更反代配置不影响旧系统路由 |
| 复用旧 PG 实例 | 独立 PostgreSQL 容器 | 数据库是责任边界核心 |

### 5.4 Docker Compose 服务清单

| 服务 | 镜像 | 端口 | 健康检查 |
|------|------|------|---------|
| postgres | postgres:16 | 5432（内部） | pg_isready |
| redis | redis:7 | 6379（内部） | redis-cli ping |
| backend | 自构建 Dockerfile | 8000（内部） | GET /health |
| nginx | nginx:alpine | 18080:80（对外） | GET /health |

Docker 网络：`it-desk-internal`（内部，连接 backend/postgres/redis）

### 5.5 资源需求

| 资源 | 配置 | 说明 |
|------|------|------|
| 服务器 | 4C8G + 100GB SSD（最低）/ 8C16G + 200GB SSD（推荐） | Docker Engine 环境 |
| 域名 | `it-dataquery.dc.servyou-it.com`（已就绪，共用） | 路径路由 `/itdesk/` `/itagent/` `/api/` |
| 企微自建应用 | 1 个（已创建） | CorpID/AgentID/Secret/Token/EncodingAESKey |
| 防火墙 | 办公网→服务器:80/443, 企微→服务器:443 | 出站: 企微 API/ Dify/ RAGFlow/ Qwen |

### 5.6 风险矩阵

| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|---------|
| 新服务器申请被拒/延迟 | 中 | 部署延期 | 退化方案：旧服务器端口分离+独立 compose |
| SSL 证书到期 | 低 | HTTPS 不可用 | 复用现有通配符证书 |
| 企微应用配置变更 | 低 | 双系统消息中断 | 建立变更通知机制 |
| Dify/RAGFlow 不可用 | 中 | M2 AI 功能不可用 | 降级：纯坐席模式仍正常工作 |
| Docker 宿主机故障 | 低 | 新系统全宕 | Compose 配置即代码，重建快 |

---

## 六、部署操作手册

> **预生产部署**：本系统与数据平台部署在**不同主机**，通过 Nginx 路径路由共用域名。数据平台请求通过远程 IP 反代（非 Docker 网络）。正式环境将迁移到 K8s。

### 6.1 前置条件

- 服务器已安装 Docker Engine 24+ + Docker Compose v2
- IT 数据查询平台已部署运行
- 有 SSH 登录权限

### 6.2 配置数据平台反代地址

预生产环境中，数据平台部署在**独立主机**。部署前需修改 `nginx/nginx.conf` 中的数据平台上游地址：

```nginx
# nginx/nginx.conf  — 将 DATAQUERY_HOST 替换为数据平台主机的实际 IP
upstream dataquery {
    server 10.80.0.86:80;   # ← 替换为数据平台实际 IP:端口
}
```

> **为什么不创建 Docker 共享网络？** 预生产两台主机不在同一 Docker Engine，无法使用 `docker network create` 互联。正式环境迁移 K8s 后由 Ingress/Service 处理路由。

### 6.3 上传部署包

在本地（Windows）执行打包上传：

```bash
# 方式 A：使用 deploy.sh 打包
bash scripts/deploy.sh --pack
scp it-smart-desk-*.tar.gz user@server:/opt/

# 方式 B：手动打包
tar czf deploy.tar.gz \
  backend/ frontend-h5/dist/ frontend-agent/dist/ \
  nginx/ docker-compose.yml .env.production scripts/
scp deploy.tar.gz user@server:/opt/it-smart-desk/
```

### 6.4 服务器配置与启动

```bash
ssh user@server
cd /opt/it-smart-desk
tar xzf it-smart-desk-*.tar.gz

# 创建环境配置
cp .env.production .env
vim .env    # 填入真实企微凭证
```

`.env` 必填项：

| 配置项 | 说明 | 获取位置 |
|--------|------|---------|
| `WECOM_CORP_ID` | 企业 ID | 企微管理后台 > 我的企业 |
| `WECOM_AGENT_ID` | 应用 AgentId | 企微管理后台 > 应用管理 |
| `WECOM_SECRET` | 应用 Secret | 企微管理后台 > 应用管理 |
| `WECOM_TOKEN` | 回调 Token | 企微管理后台 > 接收消息 |
| `WECOM_ENCODING_AES_KEY` | 回调 AES 密钥 | 企微管理后台 > 接收消息 |
| `POSTGRES_PASSWORD` | 数据库密码 | 自定义强密码 |
| `CORS_ORIGINS` | `http://it-dataquery.dc.servyou-it.com` | CORS 白名单 |

启动：

```bash
bash scripts/deploy.sh
# 自动执行：检查前置条件 → 构建后端镜像 → 启动所有容器 → 运行数据库迁移
```

### 6.5 验证部署

```bash
# 检查容器状态
docker compose ps
# 预期：4 个容器全部 Up/healthy

# 健康检查
curl http://localhost:18080/api/health

# 浏览器验证
# http://it-dataquery.dc.servyou-it.com/itdesk/   → H5 员工咨询页面
# http://it-dataquery.dc.servyou-it.com/itagent/  → 坐席工作台登录页
# http://it-dataquery.dc.servyou-it.com/          → IT 数据查询平台（不变）
# http://it-dataquery.dc.servyou-it.com/api/docs  → FastAPI Swagger 文档
```

### 6.6 常见问题

**nginx 启动失败，报 `host not found in upstream "dataquery"`**
→ `nginx/nginx.conf` 中 `DATAQUERY_HOST` 未替换为数据平台的实际 IP。确保已在部署前完成替换。

**nginx 启动但数据平台页面 502**
→ 本系统主机无法访问数据平台主机 IP。检查防火墙策略是否放行两台主机间的 80 端口。

**访问 `/itdesk/` 返回 404**
→ 检查前端 dist 是否正确挂载：`docker exec wecom_it_nginx ls -la /usr/share/nginx/html/itdesk/`

**API 返回 CORS 错误**
→ 检查 `.env` 中 `CORS_ORIGINS` 是否包含 `http://it-dataquery.dc.servyou-it.com`

**数据库迁移失败**
→ PostgreSQL 可能未就绪，等 30 秒后执行：`docker compose restart backend`

### 6.7 更新部署

```bash
# 仅更新前端
bash scripts/deploy.sh --build
docker compose restart nginx

# 仅更新后端
docker compose build backend
docker compose up -d backend

# 全量更新
bash scripts/deploy.sh --down
bash scripts/deploy.sh
```

### 6.8 回滚

```bash
docker compose down    # 停止新系统所有容器
# 旧系统不受任何影响（独立资源）
```

---

## 七、运维管理

### 7.1 责任矩阵

| 运维操作 | 影响范围 | 备注 |
|---------|---------|------|
| 重启 PostgreSQL | 仅新系统 | 独立实例 |
| 重启 Redis | 仅新系统 | 独立实例 |
| 修改 Nginx 配置 | 仅新系统路由 | 独立容器 |
| 更新后端/前端代码 | 仅新系统 | 独立容器 |
| 企微应用配置变更 | **双系统** | ⚠️ 唯一共享点，需通知双方 |

### 7.2 监控指标

```yaml
主机层面:
  - CPU 使用率 < 80%
  - 内存使用率 < 80%
  - 磁盘使用率 < 70%

容器层面:
  - docker compose ps 全部 "Up" 状态
  - Nginx 健康检查: GET /health → 200
  - Backend 健康检查: GET /health → 200

业务层面（后续接入）:
  - 企微消息回调成功率 > 99%
  - API 响应时间 P95 < 500ms
```

### 7.3 备份策略

| 备份对象 | 方法 | 频率 | 保留 |
|---------|------|------|------|
| PostgreSQL 数据 | `pg_dump` + 卷快照 | 每日凌晨 | 7 天 |
| Redis 数据 | `SAVE` + 复制 dump.rdb | 每日凌晨 | 7 天 |
| Docker 卷 | `tar czf` 归档 | 每周 | 4 周 |

### 7.4 关键对接参数（M2 阶段）

| 参数 | 值 | 用途 |
|------|-----|------|
| dify2openai API | `http://yw-dify.dc.servyou-it.com/dify2openai/v1/chat/completions` | AI 对话 |
| RAGFlow | `http://10.80.0.85:8080` | 知识库管理 |
| Qwen3-30B | `http://10.80.0.49:5000/api/llm/servyou/v1/chat/completions` | 大模型 |
| Dify DB（生产只读） | `10.80.128.40:5432` DB=dify User=difyro | 历史数据同步 |
| 数据平台 | `http://it-dataquery.dc.servyou-it.com` (10.80.0.86) | 部署服务器 |

### 7.5 应急预案可选技术项

> **评估日期**: 2026-06-03 | **来源**: 企微原生1对1方案（PRD §3.2 方式五）可行性评估

#### 7.5.1 备用方案概述

当 H5 WebView 方案（当前主方案）出现以下情况时，可切换至**企微原生1对1方案**作为降级/备用：

| 应急场景 | 当前方案症状 | 备用方案动作 |
|---------|------------|------------|
| H5 前端服务不可用 | Nginx 静态文件丢失/构建产物损坏 | 员工直接在企微与应用1对1聊天，走 `/message/send` 回复 |
| H5 页面性能问题 | WebView 加载慢/白屏/兼容性问题 | 放弃 H5 入口，改用企微原生聊天窗口交互 |
| OAuth2 鉴权异常 | 静默授权失败，H5 无法获取员工身份 | 原生方案无需 OAuth2，回调自带 UserID |
| 跨平台接入需求 | 需接入钉钉/飞书/浏览器用户 | **不适合切换**——原生方案无法跨平台，此时应修复 H5 |
| 外部专家协作 | 坐席需要拉入第三方专家协助 | 启用 `/appchat/create` 创建临时群聊 |

#### 7.5.2 备用方案技术架构

```
┌─────────────────────────────────────────────────────┐
│              员工端（企微原生1对1聊天窗口）               │
│                                                       │
│  员工 ←─消息─→ 自建应用（IT智能助手）                    │
│                  │                                    │
│                  ├─ AI回复 → /message/send → 同一窗口   │
│                  ├─ 坐席回复 → /message/send → 同一窗口 │
│                  └─ 外援 → /appchat/create → 新群聊窗口 │
│                                                       │
│  坐席工作台（保留，不变）                                 │
│  ├─ WebSocket 接收员工消息                              │
│  ├─ 坐席回复 → 后端 → /message/send → 员工窗口           │
│  └─ 外援指令 → 后端 → /appchat/create → 新群聊           │
│                                                       │
└─────────────────────────────────────────────────────┘
```

**核心能力**：项目**已经具备**备用方案所需的全部后端代码：
- `wecom_callback.py`：接收企微回调 ✅
- `message_router._try_ai_reply()` → `wecom_service.send_text_message()`：AI回复走 `/message/send` ✅
- `scoring_service.detect_hand_raise()`：关键词举手检测 ✅
- `wecom_service.send_text_message()`：应用消息推送 ✅

**仅需新增**：
- 交互卡片消息发送（`msgtype="template_card"`）— 用于"转人工"按钮、满意度评分
- AppChat API 封装（`/cgi-bin/appchat/*`）— 用于外援群聊场景
- AI/人工身份区分前缀（如 `🤖 AI回复：` / `👨‍💻 人工坐席（张三）：`）

#### 7.5.3 切换流程

**从 H5 方案切换到原生1对1方案**：

| 步骤 | 操作 | 负责人 | 预计耗时 |
|------|------|--------|---------|
| 1 | 确认企微回调 URL 已配置且可达（H5 方案已配置则无需改动） | 运维 | 0 min |
| 2 | 确认 `message_router._try_ai_reply()` 走 `/message/send`（已实现） | 开发 | 0 min |
| 3 | 通知员工：直接在企微与应用聊天即可，不再进入 H5 | 运维 | 5 min |
| 4 | （可选）关闭 H5 入口：Nginx 配置注释 `/itdesk/` 路由 | 运维 | 2 min |
| 5 | （可选）启用交互卡片：部署 template_card 消息发送代码 | 开发 | 1-2 天 |

> **关键点**：步骤1-3 **零代码改动**即可完成基本切换，因为核心回调+消息推送链路已在运行。

**从原生1对1方案切回 H5 方案**：

| 步骤 | 操作 | 负责人 |
|------|------|--------|
| 1 | 恢复 Nginx `/itdesk/` 路由（如已注释） | 运维 |
| 2 | 确认 H5 构建产物存在且可访问 | 运维 |
| 3 | 通知员工：点击应用 → 进入 H5 咨询页面 | 运维 |

#### 7.5.4 企微 API 限制与容量评估

| API | 限制 | 当前业务量（月均 188 次 AI 会话/天） | 风险 |
|-----|------|--------------------------------|------|
| `/message/send` | ≤账号上限×200人次/天，同一人≤30次/分 | 预估 < 500 人次/天 | ✅ 充裕 |
| `/appchat/create` | ≤1000群/天 | 外援场景低频（预估 < 10群/天） | ✅ 充裕 |
| `/appchat/send` | ≤2万人次/分，同一人≤200条/分 | 群内消息量极小 | ✅ 充裕 |
| 回调消息 | 无硬限制 | 企微服务器推送到回调 URL | ✅ 无风险 |

#### 7.5.5 备用方案局限性与适用边界

| 局限 | 说明 | 影响 |
|------|------|------|
| **无法跨主体企微** | 企微原生1对1仅限同一企微主体内员工 | 无法服务供应商/外包人员 |
| **无法跨平台** | 原生方案绑定企微，无法嵌入钉钉/飞书/浏览器 | H5 扩展场景不可用 |
| **AI/人工区分不直观** | 都以应用身份推送，需内容前缀区分 | 体验不如 H5 的丰富身份标识 |
| **交互卡片需开发** | "转人工"按钮、满意度评分需 template_card 消息类型 | 降级期可用关键词替代（"转人工"） |
| **群聊外援需审批** | appchat API 要求可见范围=根部门 | 需企微管理员配合 |

> **决策建议**：当 H5 不可用且影响范围仅限企微主体内员工时，**立即切换**原生1对1方案（零代码改动）；当需要跨平台/跨主体服务时，**优先修复 H5**，不切换原生方案。

---
---

## 八、开发交付状态

### TL;DR

企微IT智能服务台第一步（消息接管 + 极简坐席台）全部代码已完成并通过测试，共 **110+ 文件**，**116/116 测试全部通过**，覆盖后端 API、坐席工作台、用户端 H5 三个子系统。

### 交付状态

| 阶段 | 状态 | 产出 |
|------|------|------|
| PRD | ✅ 完成 | `PRD.md` — 31 需求（P0/P1/P2），7 用户故事 |
| 架构设计 | ✅ 完成 | `docs/ARCHITECTURE.md` — 9 表 DDL，7 API 组，4 时序图，5 任务分解 |
| T01 项目脚手架 | ✅ 完成 | 57 文件 — docker-compose, nginx, .env, 后端/前端骨架 |
| T02 后端核心服务 | ✅ 完成 | 16 文件 — 企微加解密, 消息路由, 评分, 会话, 趣味话术, 7 API 路由 |
| T03 坐席工作台 | ✅ 完成 | 25 文件 — 三栏布局, 会话管理, 聊天, AI助手面板(5Tab) |
| T04 用户端H5 | ✅ 完成 | 12 文件 — 聊天面板, 摇人按钮, AI助手, 审批链接, 软件下载 |
| QA 测试用例 | ✅ 完成 | 8 文件, 116 测试用例（原 93 + 新增 23） |
| Bug 修复 | ✅ 完成 | 7 个 Bug 修复（详见下方） |
| PostgreSQL/SQLite兼容 | ✅ 完成 | 9 个模型文件全部兼容 SQLite |
| database.py 懒加载 | ✅ 完成 | 避免测试导入时连接 PostgreSQL |
| WecomCrypto 懒加载 | ✅ 完成 | 避免默认 AES Key 导入报错 |
| **pytest 全量验证** | **✅ 116/116 通过** | 1.71 秒完成，0 失败 |

### 关键文件

```
wecom_it_smart_desk/
├── README.md                 # 项目主文档（GitHub 首页）
├── docker-compose.yml       # Docker Compose 容器编排
├── .env                      # 环境变量（数据库密码等，不提交 Git）
├── backend/                  # FastAPI 后端服务
│   ├── app/
│   │   ├── main.py              # FastAPI 应用入口
│   │   ├── config.py             # 配置管理（从 .env 读取）
│   │   ├── database.py           # 懒加载数据库引擎
│   │   ├── models/               # 11 个 ORM 模型（兼容 PostgreSQL/SQLite）
│   │   ├── schemas/              # Pydantic Schema（请求/响应校验）
│   │   ├── utils/
│   │   │   └── wecom_crypto.py   # 企微消息加解密（AES-CBC-256）
│   │   ├── services/
│   │   │   ├── wecom_service.py  # 企微回调处理
│   │   │   ├── message_router.py # 消息路由 + 评分 + 举手检测
│   │   │   ├── scoring_service.py # 紧急度评分引擎
│   │   │   ├── session_service.py # 会话生命周期管理
│   │   │   └── funny_phrase_service.py # 摇人趣味话术生成
│   │   └── api/                  # 8 个 API 路由模块
│   └── tests/                    # 116+ 个测试用例
├── frontend-agent/           # 坐席工作台（Vue 3 + Element Plus）
│   └── src/
│       ├── views/                # LoginView + WorkspaceView
│       ├── components/
│       │   ├── TopBar/           # 顶部栏（主题切换 + 用户信息）
│       │   ├── conversation/     # 会话列表 + 会话条目
│       │   ├── chat/             # 聊天区 + 消息气泡 + 输入框
│       │   ├── assistant/        # AI 推荐内联组件
│       │   ├── troubleshooting/   # 排查步骤栏（FlowchartNode）
│       │   ├── quickreply/       # 快速回复面板（三层导航）
│       │   └── todo/            # 待办面板 + 任务详情视图
│       ├── stores/               # Pinia Store（conversation/agent/quickReply/theme/todo）
│       └── api/                  # API 调用模块
├── frontend-h5/              # 员工端 H5（Vue 3 + Vant）
│   └── src/
│       ├── views/                # ChatView
│       └── components/           # ChatPanel + 摇人按钮 + AI助手
├── nginx/                    # Nginx 反向代理配置
│   └── nginx.conf
├── scripts/                  # 部署和运维脚本
│   ├── start_backend.bat     # Windows 快速启动后端（相对路径）
│   └── restart_backend.ps1   # Windows 重启后端（自动查找 PG/Redis/Python）
└── docs/                     # 项目文档（全部文档统一存放）
    ├── PRD.md                      # 产品需求文档 v1.0
    ├── PRD-v53-incremental.md      # v5.3 增量需求
    ├── ARCHITECTURE.md              # 系统架构设计（合并版）
    ├── 01-项目总览与部署手册.md      # 管理者视角部署手册
    ├── 开发交付概览.md              # 开发交付状态总览
    ├── IT智能服务台-项目迁移文档.md   # 工作区迁移记录
    ├── testing/                    # 测试报告目录
    │   └── QA_COMPREHENSIVE_REPORT.md  # 综合 QA 报告
    ├── diagrams/                   # Mermaid 图表
    │   ├── sequence-diagram.mermaid
    │   ├── sequence-shake.mermaid
    │   ├── sequence-scoring.mermaid
    │   ├── sequence-polling.mermaid
    │   └── class-diagram.mermaid
    └── prototypes/                # 原型文件
        ├── agent-workspace-v5_3.html   # 当前锁定版本（v5.3）
        ├── qr_data_full.json           # 快速回复数据（180条）
        └── archive/                    # 历史原型归档
```

### Bug 修复清单（7 个）

| # | 文件 | 问题 | 修复 |
|---|------|------|------|
| 1 | `message_router.py` | `calculate_urgency()` 是 async 但未 `await` | 添加 `await` |
| 2 | `app/main.py` | 中文引号 `""` 嵌入 Python 双引号字符串，SyntaxError | 转义引号 |
| 3 | `wecom_callback.py` | `WecomCrypto` 模块级初始化，默认 AES Key 不合法导致 `binascii.Error` | 改为懒加载单例 `_get_wecom_crypto()` |
| 4 | `tests/conftest.py` | `aioredis.from_url` mock 路径错误 | 修正为 `redis.asyncio.from_url` |
| 5 | `tests/conftest.py` | `create_test_conversation()` 缺少 `is_pinned`/`is_todo` 参数 | 添加可选参数 |
| 6 | `session_service.py` | `conversation_id` UUID 对象 vs String(36) 列类型不匹配 | 先转字符串再查询 |
| 7 | `scoring_service.py` | 关键词大小写不敏感缺失 + `_check_vip` 缺短路 | `.lower()` + 短路返回 |

### 用户下一步操作

1. **（已验证）pytest 全量通过**：116/116 测试已在开发环境验证通过，本地无需再跑

2. **配置企微应用凭证**：
   - 复制 `.env.example` 为 `.env`
   - 填入企微应用的 CorpID、AgentID、Secret、Token、EncodingAESKey

3. **Docker Compose 启动**（需 PostgreSQL + Redis）：
   ```powershell
   cd C:\Users\simon\wecom_it_smart_desk
   docker-compose up -d
   ```

4. **前端开发启动**：
   ```powershell
   # 坐席工作台
   cd frontend-agent && npm install && npm run dev
   # 用户端 H5
   cd frontend-h5 && npm install && npm run dev
   ```

5. **企微回调配置**：在企微管理后台配置消息回调 URL 指向你的服务器


## 九、附录

### 8.1 需要团队协助的事项

| # | 事项 | 需要谁 | 紧急度 |
|---|------|--------|--------|
| 1 | **服务器 SSH 账号**：用于 Docker 部署 | 运维 | 🔴 高（当前阻塞） |
| 2 | **企微通讯录权限**：确认 API 权限（VIP 功能依赖） | 运维/企微管理员 | 中（M1 可用 mock） |
| 3 | **千问/Dify/RAGFlow 环境**（M2 阶段） | 架构/开发 | 低（M2 前准备） |

### 8.2 项目文件索引

```
wecom_it_smart_desk/
├── README.md                    # 入口索引
├── PRD.md                       # 产品需求文档
├── docs/
│   ├── 01-项目总览与部署手册.md   # ← 本文档（运维/架构/管理者）
│   ├── 02-技术架构与开发指南.md   # 开发者文档
│   └── 03-测试验证文档.md        # 测试文档
├── backend/                     # FastAPI 后端
├── frontend-agent/              # 坐席工作台前端
├── frontend-h5/                 # 员工 H5 前端
├── nginx/nginx.conf             # Nginx 反代配置
├── docker-compose.yml           # Docker Compose 编排
├── .env.production              # 生产环境变量模板
└── scripts/                     # 部署/构建脚本
```

---

> 本文档合并自原 `docs/团队沟通文档-架构消息知识库.md`、`docs/正式环境独立部署架构方案.md`、`docs/DEPLOY_NAS.md`。详细技术规格见 `docs/02-技术架构与开发指南.md`。