# 企微IT智能服务台 — 系统架构、消息收发、知识库迭代说明

> **版本**: v1.1 | **日期**: 2026-06-02 | **负责人**: 宋献（IT支持组组长）  
> **目标读者**: 运维团队 / 架构团队 / 开发团队

---

## 一、项目概述

### 1.1 背景

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

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

### 1.2 核心方案

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

---

## 二、系统架构

### 2.1 部署架构总览

> 详见附件：**系统部署架构图**（图1）

系统采用 **Docker Compose 单体容器化部署**，部署于公司内部独立服务器（预生产环境，与数据平台不同主机。正式环境将迁移到 K8s 集群）：

```
┌────────────────────────────────────────────────────┐
│                     Docker Engine                    │
│                                                      │
│  Nginx (:80/:443) — 反向代理 + HTTPS + 静态文件      │
│       │                                              │
│       ├──→ 前端静态资源 (Vue3)                       │
│       │    ├─ 坐席工作台 (ElementPlus)                │
│       │    └─ 员工 H5 端 (Vant4)                     │
│       │                                              │
│       └──→ FastAPI 后端 (:8000)                      │
│            ├─ 消息路由层                              │
│            ├─ 紧急度评分引擎                          │
│            └─ 会话/消息/坐席 管理                     │
│                 │           │                         │
│                 ▼           ▼                         │
│          PostgreSQL 16    Redis 7                     │
│          (:5432)          (:6379)                     │
│          持久化存储        Token 缓存                  │
└────────────────────────────────────────────────────┘
                      ↕ HTTPS
            ┌─────────────────┐
            │  企微服务器       │
            │  (回调推送 + API) │
            └─────────────────┘
```

### 2.2 技术栈

| 层级 | 技术选型 | 说明 |
|------|---------|------|
| 反向代理 | Nginx | HTTPS 终止、静态文件、路由分发 |
| 后端框架 | 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 兼容 |
| 加解密 | cryptography (Python) | AES-CBC-256 企微消息加解密 |
| 容器化 | Docker + Docker Compose | 一键启停，5 个容器 |

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

| 表名 | 用途 | 关键字段 |
|------|------|---------|
| `conversations` | 会话主表 | employee_id, status(queued/serving/resolved), urgency_score(1-5), tags(JSON), is_vip |
| `messages` | 消息记录 | sender_type(employee/agent/ai/system), content, msg_type(text/image/file) |
| `agents` | 坐席信息 | user_id, status(online/offline/busy), current_load, max_load |
| `quick_reply_templates` | 快速回复模板 | category, title, content(支持 {变量}), variables(JSON) |
| `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 接口分组（7 组，约 25 个端点）

| 分组 | 路径前缀 | 核心接口 |
|------|---------|---------|
| 企微回调 | `/api/wecom/callback` | GET 验证 URL、POST 接收消息 |
| 会话管理 | `/api/conversations` | 列表/详情/状态/置顶/代办/接单 |
| 消息管理 | `/api/conversations/{id}/messages` | 消息列表/发送 |
| 坐席管理 | `/api/agents` | 列表/登录/状态切换 |
| 快速回复 | `/api/quick-replies` | CRUD |
| H5 用户端 | `/api/h5/*` | 会话/摇人/审批链接/软件下载/OAuth |
| 系统健康 | `/api/health` | Docker 健康检查 |

统一响应格式：
```json
{ "code": 0, "data": {}, "message": "success" }
```
错误码：0=成功，1000+=通用错误，2000+=企微 API 错误，3000+=业务逻辑错误。

---

## 三、消息收发全链路

### 3.1 流程总览

> 详见附件：**消息收发全链路流程图**（图2）

完整链路（6 步闭环）：

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

### 3.2 详细步骤

| 步骤 | 触发方 | 操作 | 技术要点 |
|------|--------|------|---------|
| ① 接收 | 员工 | 在企微应用中发消息 | 企微应用内消息，非微信客服 |
| ② 回调 | 企微服务器 | POST 加密 XML 到 `/api/wecom/callback` | AES-CBC-256 加密，SHA1 签名验证 |
| ③ 解密 | FastAPI | `wecom_crypto.decrypt_message()` | 使用 `cryptography` 库，兼容企微官方加解密 |
| ④ 路由 | MessageRouter | `route_message()` 核心编排 | 按序调用：创建会话→VIP检测→标记检测→评分→入库 |
| ⑤ 评分 | ScoringService | 5 步评分 + 标记：VIP→情绪→举手→需介入→紧急度 | 纯规则引擎（M1 不用 AI） |
| ⑥ 入库 | PostgreSQL | INSERT conversations + messages | 会话和消息原子写入 |
| ⑦ 轮询 | 坐席浏览器 | 每 3 秒 GET `/api/conversations` | 按紧急度 DESC 排序，列表 + 未读标记 |
| ⑧ 回复 | 坐席 | POST 消息内容 → 后端调用企微 API | 同时写 DB 和调用企微 `message/send` 接口 |
| ⑨ 推送 | 企微服务器 | 推送坐席回复到员工 | 同一对话窗口显示，无跳转 |

### 3.3 紧急度评分公式

```
紧急度 = 基础分(关键词) + 情绪加成 + VIP加成 + 重复追问加成
```

- 分值范围：1-5，限幅 `clamp(1, 5)`
- 映射：1=低, 2=中, 3=高, 4=紧急, 5=最高
- 所有关键词和阈值存 `system_configs` 表，支持动态修改无需重启

### 3.4 会话排序规则

```
紧急 → 举手 → 需介入 → 活跃 → AI处理中 → 已结单
（同级按 last_message_at 倒序）
```

### 3.5 坐席端通信

M1 已升级为 **WebSocket 实时推送**（2026-06-03 完成），坐席浏览器通过 `ws://host/ws/{agent_id}` 保持长连接：
- 新消息/会话状态变更通过 WS 实时推送，无需轮询
- 心跳保活：前端每 30 秒发 ping，后端回 pong
- 断线重连：指数退避（1s→2s→4s→...→30s 上限）
- 降级策略：WS 断连时自动降级为 3 秒轮询，WS 重连后自动停止轮询

> 旧方案（已废弃）：M1 原计划使用短轮询（3-5秒），已替换为 WebSocket。

### 3.6 员工端架构双方案（2026-06-03 评估）

> **评估结论**: 企微原生1对1方案技术完全可行，已纳入项目选型文档和运维应急预案

当前 H5 WebView 方案（方案A）与企微原生1对1方案（方案B）为双轨可选架构：

| 维度 | 方案A: H5 WebView | 方案B: 原生1对1 + 外援群聊 |
|------|-------------------|---------------------------|
| 员工入口 | 点击应用 → H5 页面 | 直接在企微与应用1对1聊天 |
| 交互体验 | H5 内输入框 | **原生聊天窗口，体验最优** |
| 前端开发 | 大（Vue3+Vant4） | **零** |
| 跨平台 | **✅ 可挂载钉钉/飞书/浏览器** | ❌ 绑定企微 |
| 跨主体 | **✅ 可（其他认证方式）** | ❌ 仅同一企微主体 |
| OAuth2 | 必须 | **不需要** |
| AI/人工区分 | H5 可做丰富标识 | 需内容前缀区分 |
| 外援协作 | 需额外设计 | **原生群聊(appchat)** |
| 消息存档 | 全量经后端 | **全量经后端（无需会话存档权限）** |
| 切换成本 | — | **核心链路已实现，零代码改动可切换** |

**方案B 交互路径**（关键纠正：不是每次都创建群聊）：
1. **AI 自助**：员工发消息 → 企微回调 → Dify → `/message/send` → 同一窗口
2. **坐席介入**：坐席工作台 → `/message/send` → 同一窗口（员工无感知切换）
3. **外援场景**：坐席发起 → `/appchat/create` → **新群聊窗口**（非常态，低频）

**选型决策**（详见 PRD §3.3）：
- 企微主体内服务 → 方案B 体验更优
- 需跨平台/跨主体 → 方案A 不可替代
- **推荐混合策略**：原生1对1做日常入口，H5 保留为扩展层

**运维应急**（详见 `01-项目总览与部署手册.md` §7.5）：
- H5 不可用时，零代码切换至方案B
- 需外援协作时，按需启用 appchat 群聊

---

## 四、三步演进路径与知识库迭代

### 4.1 三步总览

> 详见附件：**三步演进路径与知识库迭代闭环图**（图3）

| 里程碑 | 周期 | 核心交付 |
|--------|------|---------|
| **M1: 消息接管 + 极简坐席** | 6 周（进行中） | 企微 API 链路验证 · 坐席三栏工作台 · 员工 H5 双栏 |
| **M2: AI 机器人接入** | M1 后 4-6 周 | 千问/Dify/RAGFlow 接入 · AI 前置筛选 · 排队系统 |
| **M3: 知识库闭环迭代** | M2 后 4-6 周 | 坐席标注系统 · 千问自动分析 · 知识库自优化 |

### 4.2 M1 — 当前阶段详情

| 模块 | 内容 | 状态 |
|------|------|------|
| 企微消息对接 | 自建应用回调 + AES 加解密 + token 管理 | ✅ 代码完成 |
| 消息路由 | 所有消息进路由层，新会话→坐席队列 | ✅ 代码完成 |
| 紧急度评分 | 5 步评分引擎（VIP/情绪/举手/需介入/紧急度） | ✅ 代码完成 |
| 坐席工作台 | Vue3 三栏布局（会话列表/对话区/AI助手面板） | ✅ 代码完成 |
| 员工 H5 | Vue3+Vant4 双栏布局（对话区/助手面板+摇人按钮） | ✅ 代码完成 |
| 测试用例 | 116 条 pytest 全部通过 | ✅ 完成 |
| 环境搭建 | Docker Compose + PostgreSQL + Redis | 🔧 配置中 |

M1 **不接入 AI**——先验证企微基础链路（消息收发、会话管理、坐席工作台）完整可用。

### 4.3 M2 — AI 接入计划

核心改动：**只改路由层逻辑**，其余不动。

```
M1: 新会话 → 坐席队列
M2: 新会话 → AI 先回答 → AI判断/用户触发 → 坐席队列
```

新增能力：
- 千问（通义千问）作为对话模型
- RAGFlow 作为知识库语义检索引擎
- Dify 作为 AI 应用编排平台
- 转人工触发：关键词 / AI 连续 2 轮追问 / AI 调用超时 3 秒
- AI 回复末尾自动追加 "以上为 AI 自动回复，如需人工帮助请回复'转人工'"
- 排队系统：等待人数、预计时间

目标：AI 首答率 ≥ 80%

### 4.4 M3 — 知识库迭代闭环（核心创新）

这是整个系统从"工具"进化为"智能平台"的关键一步。

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

**标注融入日常工作流**，不另开标注页面：
- 对话区每条 AI 回复旁有 👍 / 👎 按钮
- 坐席在正常服务过程中顺手标注

**千问自动分析**两类问题：
| 分析结果 | 自动处理 |
|---------|---------|
| **缺文档**：知识库没有覆盖此问题 | 千问生成标准 FAQ → 推送 RAGFlow |
| **信息过时**：知识库有文档但内容不对 | 标记原文档需更新 → 通知管理员审核 |

### 4.5 并行协作模式（设计理念）

传统"串行排队"改为**"并行协作"**：

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

### 4.6 AI Wingman — 坐席端智能辅助（2026-06-04 新增）

> **设计理念**：AI不仅服务员工，更要解放坐席——从"坐席=打字员"升级为"坐席=审核员+专家"

**三层渐进式架构**：

| 层 | 目标 | 核心功能 | 行业验证 | 实施时间 |
|----|------|---------|---------|---------|
| 效率层 | 消灭重复劳动 | AI草稿回复 + 自动摘要 + 自动标签 | 打字量 -80%，填单 1分钟→10秒 | Phase 1（已确认） |
| 认知层 | 降低认知负荷 | 知识推荐 + SOP导航 + 相似工单 + 客户画像 | 新人上手 -50% | Phase 2 |
| 情感层 | 减少情绪消耗 | 情绪识别 + 安抚话术 + 语气润色 + 疲劳检测 | 情绪耗竭 -45% | Phase 3 |

**Phase 1 双区布局**（已确认实现方案）：

| 区域 | 位置 | 功能 |
|------|------|------|
| 内嵌区 | 对话流中（每条员工消息下方） | AI草稿回复 — [采纳]/[编辑]/[忽略] 三选一 |
| 侧栏区 | 右侧 AI 助手面板 | 会话自动摘要、自动标签、知识推荐、快捷回复库 |

**底层实现**：扩展现有 Dify，新增坐席端 Wingman Agent：
- Agent 1（已有）：员工端 AI，直接回答员工问题
- Agent 2（新增）：坐席端 Wingman，辅助坐席生成草稿/摘要/知识推荐
- 两个 Agent 共用知识库，但 system prompt 和上下文不同

**为什么这样做**：
1. 坐席每天大量重复回复（密码重置、VPN指引等），AI草稿让坐席从"打字员"变"审核员"
2. 结单文书消耗 70% 非服务时间，自动摘要压缩到 10%
3. 员工情绪会传染坐席，情绪预警+安抚话术帮助保持专业冷静
4. 参考：NiCE Copilot、Helpshift AI Copilot、天润融通、循环智能等产品验证

---

## 五、运维相关信息

### 5.1 资源配置需求

| 资源 | 最低配置 | 建议配置 |
|------|---------|---------|
| 服务器 | 4 核 / 8 GB / 100 GB SSD | Docker Engine 环境 |
| 公网 HTTPS 域名 | 1 个 | 用于企微回调 URL |
| 企微自建应用 | 1 个（已创建） | CorpID/AgentID/Secret/Token/EncodingAESKey |

> **待办**：企微回调 URL 需要公司服务器+公网 HTTPS 域名，目前暂缓，先在本机测试环境完成其他部分。

### 5.2 Docker Compose 服务清单

| 服务 | 镜像 | 端口 | 健康检查 |
|------|------|------|---------|
| postgres | postgres:16 | 5432 | pg_isready |
| redis | redis:7 | 6379 | redis-cli ping |
| backend | 自构建 Dockerfile | 8000 | /api/health |
| frontend-agent | 自构建 + Nginx 静态 | 80/443 | — |
| frontend-h5 | 同 Nginx 容器 | — | — |

### 5.3 关键配置项（.env）

```env
# 企微
WECOM_CORP_ID=ww...
WECOM_AGENT_ID=1000002
WECOM_SECRET=...
WECOM_TOKEN=...         # 回调验证 Token
WECOM_ENCODING_AES_KEY=...  # 43 位随机字符串

# 数据库
DATABASE_URL=postgresql://user:pass@postgres:5432/wecom_it_desk

# Redis
REDIS_URL=redis://redis:6379/0

# 服务
BACKEND_PORT=8000
CORS_ORIGINS=http://localhost:5173
```

### 5.4 启动命令

```bash
# 一键启动所有服务
docker compose up -d

# 数据库迁移
docker compose exec backend alembic upgrade head

# 查看日志
docker compose logs -f backend

# 停止
docker compose down
```

---

## 六、当前进展与待办

### 6.1 当前进度

| 模块 | 状态 | 备注 |
|------|------|------|
| PRD | ✅ 完成 | 31 项需求，7 个用户故事 |
| 架构设计 | ✅ 完成 | 9 张表 DDL，7 组 API，4 个时序图 |
| 后端代码 | ✅ 完成 | 45 个文件，7 个服务层 + 7 个 API 路由 |
| 坐席前端 | ✅ 完成 | 25 个文件，Vue3+ElementPlus 三栏布局 |
| 员工 H5 | ✅ 完成 | 12 个文件，Vue3+Vant4 双栏+摇人 |
| 测试用例 | ✅ 完成 | 116 条 pytest 全部通过 |
| 环境搭建 | 🔧 进行中 | PostgreSQL + Redis 安装配置中 |
| 企微回调 | ⏳ 待办 | 需要公司服务器 + 公网 HTTPS 域名 |

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

| # | 事项 | 需要谁 | 紧急度 |
|---|------|--------|--------|
| 1 | **服务器资源**：分配一台 Linux 服务器用于 Docker 部署 | 运维 | 中 |
| 2 | **公网域名**：一个 HTTPS 域名用于企微回调 URL | 运维/架构 | 中（M1 联调前） |
| 3 | **SSL 证书**：通配符证书或 Let's Encrypt | 运维 | 中（同上） |
| 4 | **企微通讯录权限**：确认 API 权限（VIP 功能依赖） | 运维/企微管理员 | 低（M1 可暂用 mock） |
| 5 | **千问/Dify/RAGFlow 环境**（M2 阶段） | 架构/开发 | 低（M2 前准备） |

### 6.3 下一步计划

1. **本周**：完成本机 PostgreSQL + Redis 安装，后端本地启动验证
2. **下周**：坐席前端启动联调，Swagger 接口测试
3. **服务器就绪后**：Docker Compose 部署 + 企微回调配置 + 完整链路联调

---

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

> 基于交接文档 + db_query_project_v8 源码分析，评估现有企微AI客服系统可复用的服务能力和资源

### 7.1 现有系统全景

```
┌──────────────────────────────────────────────────────────────┐
│                     员工（企微App）                            │
│                        │ 发消息/收回复                          │
│                        ▼                                      │
│              ┌─────────────────┐                               │
│              │  企业微信自建应用  │                               │
│              └────────┬────────┘                               │
│                       │ 回调/主动消息                             │
│                       ▼                                      │
│              ┌─────────────────┐    ┌──────────────────┐       │
│              │ B端生产智能体     │───▶│ dify2openai 桥接  │       │
│              │ agent.dc.servyou │    │ yw-dify.dc       │       │
│              └────────┬────────┘    └────────┬─────────┘       │
│                       │                      │                 │
│                       ▼                      ▼                 │
│              ┌─────────────────┐    ┌──────────────────┐       │
│              │   Dify Workflow  │    │  RAGFlow 知识库   │       │
│              │  yw-dify.dc      │    │  10.80.0.85:8080 │       │
│              └─────────────────┘    └──────────────────┘       │
│                       │                      │                 │
│                       ▼                      ▼                 │
│              ┌─────────────────┐    ┌──────────────────┐       │
│              │  Qwen3-30B      │    │  bge-m3 向量模型  │       │
│              │  10.80.0.49     │    │                  │       │
│              └─────────────────┘    └──────────────────┘       │
│                                                              │
│              ┌──────────────────────────────────────────┐      │
│              │     智能IT数据平台 (Django 3.2)            │      │
│              │     it-dataquery.dc.servyou-it.com        │      │
│              │     10.80.0.86                             │      │
│              │  ┌────────────┬────────────┬───────────┐  │      │
│              │  │ 数据查询统计 │ 人工介入标注 │ 人工录入  │  │      │
│              │  └────────────┴────────────┴───────────┘  │      │
│              │  DB: dify(只读) + intervention_db(读写)     │      │
│              └──────────────────────────────────────────┘      │
└──────────────────────────────────────────────────────────────┘
```

### 7.2 可复用资源清单

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

| # | 资源 | 现有位置/信息 | 复用方式 | 新系统对应 |
|---|------|-------------|---------|-----------|
| 1 | **Dify Workflow** | `yw-dify.dc.servyou-it.com/apps` | 直接复用，M2阶段接入AI回复 | 坐席助手AI面板 + 自动回复 |
| 2 | **dify2openai 桥接** | `yw-dify.dc/dify2openai/v1/chat/completions` | 直接复用API | 后端调用AI的入口 |
| 3 | **RAGFlow 知识库** | `10.80.0.85:8080` | 直接复用，M3阶段混合标注迭代 | 知识库管理 + 标注闭环 |
| 4 | **Qwen3-30B 大模型** | `10.80.0.49:5000/api/llm/servyou/v1` | 直接复用 | AI对话底层模型 |
| 5 | **bge-m3 向量模型** | RAGFlow 内置 | 直接复用 | 知识库检索向量化 |
| 6 | **Dify 数据库（只读）** | `10.80.128.40:5432` DB=dify User=difyro | 读取messages表获取AI对话记录 | 历史会话数据迁移 + 统计 |
| 7 | **企微自建应用** | 已创建，有CorpID/AgentID/Secret | 直接复用应用凭证 | 消息收发的企微入口 |

#### 🟡 业务逻辑复用（需适配改造）

| # | 现有能力 | 现有实现 | 适配到新系统 | 改造量 |
|---|---------|---------|-------------|-------|
| 8 | **会话定义** | 15分钟无交互=一个会话结束 | 改为新系统会话状态机（queued→serving→resolved） | 中 |
| 9 | **自助解决判定** | 15分钟内未转人工 | 复用判定逻辑，改为新系统统计口径 | 小 |
| 10 | **知识库命中判定** | 回答含"您的问题可能不在服务业务范围内"=未命中 | 复用关键词，增加AI置信度评分 | 小 |
| 11 | **系统转人工判定** | 用户输入"IT"即转人工 | 改为摇人按钮 + 智能评分触发 | 中 |
| 12 | **人工介入标注** | ManualIntervention模型（命中/待处理/已处理） | 适配为新系统会话标记体系（VIP/举手/需介入/情绪） | 中 |
| 13 | **人工录入** | ManualEntry模型（补录线下咨询） | 复用，接入新系统数据库 | 小 |
| 14 | **月度报表查询** | MonthlyReportQueryView | 改造为新系统运营报表 | 中 |
| 15 | **坐席登录认证** | Session + Redis + 12小时超时 | 改为JWT + Redis，复用登录逻辑 | 小 |
| 16 | **密码修改** | ChangePasswordView | 复用，加哈希加密（现在明文存储） | 小 |

#### 🟢 基础设施复用（直接复用或微调）

| # | 资源 | 现有配置 | 复用方式 |
|---|------|---------|---------|
| 17 | **服务器 10.80.0.86** | 现有Django+PostgreSQL+Redis | 新系统后端部署目标 |
| 18 | **域名** | `it-dataquery.dc.servyou-it.com` | 新系统用子域名如 `itdesk.dc.servyou-it.com` |
| 19 | **SSL证书** | ssl/目录 | 复用或申请新证书 |
| 20 | **Nginx** | `nginx/nginx.conf` | 改反代配置指向新系统 |
| 21 | **Docker Compose 部署模式** | 现有5套 compose 编排 | 复用部署模式，新系统加自己的 compose |
| 22 | **Redis** | `10.90.5.8` Redis 7 + 密码（见运维密码管理） | 直接连接使用 |
| 23 | **Docker网络** | dbquery_net 桥接模式 | 新建 itdesk_net |
| 24 | **SearXNG 搜索** | `10.90.5.8:8080` | M2阶段AI联网搜索能力 |
| 25 | **LangBot** | `10.90.5.8:30030` | 可选，多模型接入 |

### 7.3 数据模型映射（旧→新）

#### 用户模型

| 现有 system_users | 新系统 Agent（坐席） | 复用方式 |
|-------------------|---------------------|---------|
| username | username | ✅ 直接复用 |
| password（明文⚠️） | password_hash | 🔄 改为bcrypt哈希 |
| is_active | is_online | 🔄 语义变更 |
| created_at | created_at | ✅ 直接复用 |
| — | display_name | 🆕 新增 |
| — | role | 🆕 新增（admin/agent） |

#### 会话/消息模型

| 现有 messages（Dify只读） | 新系统 Conversation + Message | 说明 |
|--------------------------|-------------------------------|------|
| id | — | Dify消息ID，迁移时关联 |
| session_id → user_name | Conversation.user_id | 会话归属用户 |
| query | Message.content（type=text） | 用户问题 |
| answer | Message.content（type=ai_reply） | AI回复 |
| created_at | Message.created_at | 时间戳 |
| — | Conversation.status | 🆕 状态机 |
| — | Conversation.urgency_score | 🆕 紧急度 |
| — | Conversation.tags | 🆕 标记体系 |

#### 人工介入模型

| 现有 ManualIntervention | 新系统 Conversation.tags | 说明 |
|------------------------|--------------------------|------|
| message_id | conversation_id | 关联对象变更 |
| manual_intervention（是/否） | tags中的"需介入" | 逻辑迁移 |
| operation_user | agent_id | 操作人关联 |
| knowledge_status（命中/待处理/已处理） | tags中的知识库状态 | 逻辑迁移 |
| query | — | 已在Message中 |

#### 人工录入模型

| 现有 ManualEntry | 新系统 | 说明 |
|-----------------|--------|------|
| 整个模型 | ✅ 可直接复用 | 补录线下咨询记录 |

### 7.4 技术栈对比与迁移路径

| 维度 | 现有系统 | 新系统 | 迁移策略 |
|------|---------|--------|---------|
| 后端框架 | Django 3.2（同步） | FastAPI（异步） | **完全重写后端**，Django不适配实时消息 |
| 数据库ORM | Django ORM | SQLAlchemy 2.0（异步） | 模型定义迁移，逻辑重写 |
| 前端坐席台 | Bootstrap + jQuery | Vue3 + ElementPlus | **完全重写前端** |
| 前端用户端 | 无（企微原生聊天） | Vue3 + Vant4 (H5) | 新建 |
| 数据库 | PG 11.8（Dify只读）+ PG 13（本地） | PG 16（统一） | 升级，合并为单库 |
| 缓存 | Redis 7（django-redis） | Redis 7（aioredis） | 复用Redis实例 |
| 部署 | Docker Compose | Docker Compose | 复用模式 |
| 认证 | Django Session | JWT + Redis | 重写认证层 |

> **关键结论**：代码层面复用率约 15%（主要是业务逻辑和SQL查询），基础设施和AI能力复用率约 70%。

### 7.5 对接点梳理（新系统与现有系统交互）

#### M1阶段（当前）— 纯坐席台

```
新系统独立运行，不与现有系统交互
├── 企微消息 → 新后端(FastAPI) → 坐席台(Vue3) → 回复
├── 数据库：本地 PostgreSQL 16
└── 缓存：本地 Redis
```

#### M2阶段 — 接入AI

```
新系统 + 现有AI能力
├── 企微消息 → 新后端 → Dify(dify2openai) → AI回复
│                     └─ 同时 → 坐席台（AI助手面板展示AI回复）
├── AI无法解决 → 转坐席（摇人）
├── 读取Dify数据库 → 同步历史对话到新系统
└── RAGFlow → 知识库检索
```

#### M3阶段 — 知识库迭代

```
新系统 + AI + 知识库闭环
├── 坐席标注 → RAGFlow 知识库更新
├── AI回复 + 坐席校正 → 知识库质量提升
├── 统计面板 → 月度运营报告（复用现有报表逻辑）
└── 数据平台 → 合并到新系统或并行运行
```

### 7.6 关键对接参数汇总

| 参数 | 值 | 用途 |
|------|-----|------|
| dify2openai API | `http://yw-dify.dc.servyou-it.com/dify2openai/v1/chat/completions` | AI对话 |
| dify2openai Key | `http://yw-dify.dc.servyou-it.com/v1\|app-***\|Chat` | 认证 |
| 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 Pwd=*** | 历史数据 |
| Dify DB（测试） | `10.199.16.9:5432` DB=dify User=dify_ro | 测试环境 |
| Redis | `10.90.5.8:6379` Pwd=*** | 缓存共享 |
| 数据平台 | `http://it-dataquery.dc.servyou-it.com` (10.80.0.86) | 部署服务器 |
| B端智能体 | `https://agent.dc.servyou-it.com` | 智能体管理 |
| SearXNG | `http://10.90.5.8:8080` | 联网搜索 |
| Dify App ID | `a57543f3-de66-47cc-ad89-d0540c08159f` | 消息查询过滤 |

### 7.7 对运维/架构/开发的具体建议

**给运维：**
1. **10.80.0.86 服务器**已跑Django+PG+Redis，新系统FastAPI可同机部署（不同端口），后续迁容器
2. **域名**申请 `itdesk.dc.servyou-it.com`，Nginx反代到新系统8001端口
3. **Redis**可复用现有实例（db=0给旧系统，db=1给新系统）
4. **SSL**复用现有通配符或新申请

**给架构：**
1. **M1独立运行**，不依赖现有系统，降低风险
2. **M2通过dify2openai API对接**，不需要改Dify Workflow代码
3. **Dify数据库只读**，新系统通过SQL同步历史数据，不影响现有AI服务
4. **RAGFlow API**直接调用，M3阶段做双向同步

**给开发：**
1. 新系统用 **FastAPI + SQLAlchemy 2.0**，不要沿用Django代码
2. 现有系统的 **业务逻辑（会话判定、命中判定、报表SQL）** 可参考移植
3. **数据模型映射**见7.3节，需要做数据迁移脚本
4. **API对接参数**见7.6节，M2阶段需要配置

### 7.8 风险与注意事项

| 风险 | 级别 | 应对 |
|------|------|------|
| Dify数据库是只读的，不能写入 | ⚠️ 中 | 新系统自建库，只从Dify同步数据 |
| 现有系统密码明文存储 | 🔴 高 | 新系统必须用bcrypt，迁移时做哈希转换 |
| dify2openai桥接由CF维护 | ⚠️ 中 | 提前沟通M2对接需求，预留联调时间 |
| RAGFlow知识库由宋献IT组维护 | ℹ️ 低 | M3阶段需协调知识库写入权限 |
| 现有Django 3.2 + PG 11.8版本老旧 | ⚠️ 中 | 新系统独立部署，不升级旧系统 |

---

## 附录：代码仓库

```
C:\Users\simon\wecom_it_smart_desk\
├── PRD.md                 # 产品需求文档
├── ARCHITECTURE.md        # 系统架构设计（含类图/时序图/API/DDL）
├── docker-compose.yml     # Docker 编排
├── .env                   # 环境变量
├── backend/               # FastAPI 后端 (45 个文件)
│   ├── app/
│   │   ├── api/           # 7 个路由模块
│   │   ├── services/      # 6 个服务层
│   │   ├── models/        # 9 个数据模型
│   │   ├── schemas/       # 6 个 Pydantic Schema
│   │   └── utils/         # 加解密/token/响应工具
│   └── alembic/           # 数据库迁移
├── frontend-agent/        # 坐席工作台前端 (25 个文件)
├── frontend-h5/           # 员工 H5 前端 (12 个文件)
├── tests/                 # 测试用例 (116 条)
└── docs/                  # 文档
```

---

> 本文档面向运维/架构/开发三团队沟通使用。详细技术规格见 `ARCHITECTURE.md`，产品需求见 `PRD.md`。