simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bea288e414c72f5e17f45cf635cb1769cc2b2692
wecom_it_smart_desk/docs/03-技术架构/IT智能服务台-系统架构设计文档v2.md
T

1019 lines
44 KiB
Markdown
Raw Normal View History

feat: 2026-07-11 全量更新 - 代办集成+会议室预定+知识迭代修复+UI统一+Bug修复
2026-07-11 23:13:10 +08:00
# IT智能服务台 — 系统架构设计文档
> **文档版本**: v2.1 (综合版)
> **创建日期**: 2025-07-11
> **最近更新**: 2026-07-10
> **架构师**: 高见远 (Bob)
> **状态**: 正式版
---
## 目录
1. [技术文档索引](#1-技术文档索引)
2. [系统概述](#2-系统概述)
3. [整体架构](#3-整体架构)
4. [技术选型](#4-技术选型)
5. [部署架构](#5-部署架构)
6. [统一入口设计](#6-统一入口设计)
7. [模块架构](#7-模块架构)
8. [AI Wingman 设计](#8-ai-wingman-设计)
9. [外部系统集成](#9-外部系统集成)
10. [安全设计](#10-安全设计)
11. [复杂对话场景设计](#11-复杂对话场景设计)
12. [知识图谱数据模型设计](#12-知识图谱数据模型设计)
13. [数据库设计](#13-数据库设计)
14. [API设计规范](#14-api设计规范)
15. [技术方案详解](#15-技术方案详解)
16. [技术分析报告](#16-技术分析报告)
17. [阶段5 自动化闭环](#17-阶段5-自动化闭环)
---
## 1. 技术文档索引
本文档为技术架构主文档（综合版），整合了所有技术方案和技术分析文档。
| 章节 | 内容 | 状态 |
|------|------|------|
| **15. 技术方案详解** | | |
| 15.1 | 认证模块重构 | ✅ 已实现 |
| 15.2 | 消息功能详细设计 | ✅ 已实现 |
| 15.3 | 群聊邀请和协助 | ✅ 已实现 |
| 15.4 | 企微审批工单同步 | ✅ 设计完成 |
| 15.5 | 复杂场景重构 | ✅ 设计完成 |
| 15.6 | ExternalSystemAdapter抽象层 | ✅ 设计完成 |
| **16. 技术分析报告** | | |
| 16.1 | JP-webcli自动化部署能力分析 | ✅ 已完成 |
| **17. 阶段5 自动化闭环** | | |
| 17.1 | 自动化闭环设计 | ✅ 设计完成 |
---
## 2. 系统概述
### 2.1 项目背景
IT智能服务台是为企业提供 IT support 的智能化服务平台，核心目标：
- **员工侧**：通过 H5 页面提交 IT 问题、AI 自助解答、人工坐席服务
- **坐席侧**：通过自研工作台处理会话、AI 辅助（ Wingman ）、知识推荐
- **管理侧**：通过管理后台配置系统、管理坐席、查看数据
### 2.2 核心能力
| 能力 | 说明 |
|------|------|
| 消息路由 | AI 与人工无缝切换 |
| 实时会话 | 坐席工作台实时消息 |
| AI 辅助 | Wingman 草稿/摘要/知识推荐 |
| 外部集成 | 联软/火绒/aTrust/eHR 终端数据 |
| 角色管理 | 统一入口 + RBAC 权限 |
| 知识图谱 | Neo4j 图数据库支撑智能对话 |
---
## 3. 整体架构
### 3.1 系统架构图
```
┌─────────────────────────────────────────────────────────────────────┐
│ Linux 服务器 Docker │
│ │
│ ┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │ Nginx │ │ Frontend │ │ Frontend │ │ Frontend │ │
│ │ (反代) │──│ Agent │ │ H5 User │ │ Portal │ │
│ │ :80/:443│ │ (Vue3+EP) │ │ (Vue3+Vant4)│ │ (Vue3) │ │
│ └────┬─────┘ └──────────────┘ └──────────────┘ └────────────┘ │
│ │ :5173 :5174 :5175 │
│ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ FastAPI │ │ Redis │ │PostgreSQL│ │ Neo4j │ │
│ │ Backend │──│ (缓存/Session)│──│ (持久化) │──│ (知识图谱) │ │
│ │ :8000 │ │ :6379 │ │ :5432 │ │ :7687 │ │
│ └────┬─────┘ └──────────┘ └──────────┘ └──────┬───────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌──────────────┐ │
│ └───────────────────────────────────────│ Dify AI │ │
│ │ (外部依赖) │ │
│ └──────────────┘ │
└───────────────────────────────────────────────────────────────────────┘
│ HTTPS
▼
┌───────────────┐
│ 企微服务器 │
│ (消息回调API) │
└───────────────┘
```
### 3.2 前端架构
| 端 | 路径 | 技术栈 | 端口 |
|----|------|--------|------|
| Portal | /itportal/ | Vue3 + Element Plus | 5176 |
| 坐席端 | /itagent/ | Vue3 + Element Plus | 5173 |
| H5用户端 | /itdesk/ | Vue3 + Vant 4 | 5174 |
| 管理后台 | /itadmin/ | Vue3 + Element Plus + Tailwind | 5175 |
---
## 4. 技术选型
### 4.1 核心技术栈
| 层级 | 技术 | 版本 | 说明 |
|------|------|------|------|
| 前端框架 | Vue 3 | ^3.4.0 | Composition API |
| 前端路由 | Vue Router | ^4.3.0 | SPA 路由 |
| 状态管理 | Pinia | ^2.1.0 | 轻量级状态管理 |
| UI 组件 | Element Plus | ^2.7.0 | 坐席端/Portal |
| UI 组件 | Vant 4 | ^4.0 | H5 移动端 |
| 样式 | Tailwind CSS | ^3.4.0 | 管理后台 |
| 构建工具 | Vite | ^5.3.0 | 快速构建 |
| 后端框架 | FastAPI | 0.110+ | 异步高性能 |
| ORM | SQLAlchemy | 2.0+ | async ORM |
| 数据库 | PostgreSQL | 16 | 主数据存储 |
| 图数据库 | Neo4j Community | 5.x | 知识图谱存储 |
| 缓存 | Redis | 7 | Session/Token/缓存 |
| AI 引擎 | Dify | — | 外部依赖 |
---
## 5. 部署架构
### 5.0 部署模式演进
> **新增日期**: 2026-07-10 (v2.1) | **架构师**: 高见远 (Gao) | **方案编号**: 方案 C
#### 背景与问题
2026 年 7 月连续两次因部署导致认证功能损坏：
- **07-07**：Docker 镜像未重新构建 → 路由缺失
- **07-10**：镜像从 `backend/app/`（旧代码）构建 → 缺少 `auth.py` → 认证全断
**根因**：服务器存在两份代码（`/opt/wecom-it-desk/app/` 较新 + `/opt/wecom-it-desk/backend/app/` 较旧构建用），Docker 镜像 `COPY . .` 烘焙代码，两份不同步就构建出缺文件的镜像。
#### 方案 C：代码卷挂载（当前采用）
**核心原理**：镜像只包含 Python 运行时 + 依赖包（site-packages），业务代码通过 Docker volume 挂载到容器 `/app/app/`，运行时从宿主机实时读取。
```
┌─────────────────────────────────────────────────────────┐
│ 宿主机 /opt/wecom-it-desk/ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐ │
│ │ backend/ │ │ app/ │ │
│ │ ├ Dockerfile│ │ ├ main.py │ │
│ │ ├ req...txt │ │ ├ auth.py │ │
│ │ └ (无app/) │ │ ├ api/ │ │
│ │ (仅构建配置) │ │ └ ... │ │
│ └──────┬───────┘ └──────────┬────────────────────┘ │
│ │ │ volume mount │
│ │ build context │ ./app → /app/app │
│ │ (仅 requirements) │ │
└─────────┼──────────────────────┼─────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────┐
│ Docker Container (wecom_it_backend) │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ /app/ │ │
│ │ ├ app/ ← 卷挂载（运行时读取宿主机代码） │ │
│ │ ├ uploads/ ← Docker named volume │ │
│ │ ├ logs/ ← 宿主机目录挂载 │ │
│ │ └ site-packages/ ← 镜像内置（构建时安装） │ │
│ └─────────────────────────────────────────────────┘ │
│ 镜像 = Python 运行时 + 依赖包（无业务代码） │
└─────────────────────────────────────────────────────────┘
```
#### 核心变更点
| # | 变更项 | 变更前 | 变更后 |
|---|--------|--------|--------|
| 1 | Dockerfile `COPY . .` | 代码烘焙进镜像 | **删除**，代码通过 volume 提供 |
| 2 | Dockerfile `ENV` | 无 | 新增 `PYTHONDONTWRITEBYTECODE=1` |
| 3 | docker-compose.yml `volumes` | 仅 uploads + logs | 新增 `./app:/app/app` 代码挂载 |
| 4 | 服务器目录 `backend/app/` | 旧代码（构建用） | **删除**（不再需要） |
| 5 | 服务器目录 `app/` | 新代码（部署用） | **唯一代码源**（volume 挂载源） |
| 6 | 部署流程 | 每次重建镜像 | 代码更新仅重启，依赖更新才重建 |
#### 部署流程对比
| 操作 | 变更前（镜像烘焙） | 变更后（卷挂载） |
|------|-------------------|-----------------|
| 代码更新 | 解压→同步到 backend/app/→重建镜像→重启 (4-6 分钟) | 解压→重启容器 (**15-30 秒**) |
| 依赖更新 | 更新 requirements.txt→重建镜像→重启 (3-5 分钟) | 同左 (2-4 分钟) |
| 同步风险 | **高**（两份代码可能不一致） | **零**（只有一份 app/） |
#### 回滚策略
- **触发条件**：容器启动失败 / 健康检查失败 / auth 模块导入失败 / 卷挂载异常 / 大面积 500 错误
- **回滚步骤**：恢复备份配置→确保 backend/app/ 存在→重建镜像→重启容器→验证
- **回滚时间**：3.5-5.5 分钟
- **安全网**：部署时自动创建 `.bak.{TIMESTAMP}` 备份 + `.rollback-info` 记录路径
> **完整方案文档**：`docs/09-部署运维/卷挂载重构方案.md`（含完整命令块、时序图、风险评估、7 步任务分解）
### 5.1 部署拓扑
```
┌────────────────────────────┐
│ 企微服务器（外部） │
│ qyapi.weixin.qq.com │
└──────────┬─────────────────┘
│ HTTPS :443
▼
┌──────────────── 办公网络 ────────────────────────────────┐
│ │
│ ┌──────────┐ ┌──────────────────────────┐ │
│ │ 坐席浏览器 │────────▶│ https://itsupport. │ │
│ │ (内网) │ HTTPS │ servyou.com.cn │ │
│ └──────────┘ └──────────┬───────────────┘ │
│ │ │
├────────────────── OA 服务器网络 ──┼───────────────────────┤
│ │ │
│ ┌───────▼──────────────┐ │
│ │ 服务器 (Docker) │ │
│ │ ┌────────────────┐ │ │
│ │ │ Nginx :80/443 │ │ │
│ │ └───────┬────────┘ │ │
│ │ │ │ │
│ │ ┌───────▼────────┐ │ │
│ │ │ FastAPI :8000 │ │ │
│ │ └───────┬────────┘ │ │
│ │ │ │ │
│ │ ┌───────▼────────┐ │ │
│ │ │ PostgreSQL │ │ │
│ │ └───────┬────────┘ │ │
│ │ │ │ │
│ │ ┌───────▼────────┐ │ │
│ │ │ Redis │ │ │
│ │ └───────┬────────┘ │ │
│ └──────────┴───────────┘ │
│ │ │
│ ┌────────▼──────────────┐ │
│ │ 现有 AI 服务（外部依赖）│ │
│ └───────────────────────┘ │
└──────────────────────────────────────────────────────────┘
```
---
## 6. 统一入口设计
### 6.1 概述
统一入口（Portal）是系统的认证入口，按角色分发到对应端。
**核心功能**：
- 企微 OAuth2 静默授权（用户端）
- 扫码认证（坐席/管理端）
- 角色检测与路由选择
- 统一 Token 管理
### 6.2 登录方式（v1.5 变更）
> **更新日期**: 2026-07-04 | **核心变更**: 坐席/管理端浏览器直接打开，**无需经过企微工作台**
| 端 | 访问方式 | 登录方式 | 说明 |
|----|----------|----------|------|
| **用户端 (H5)** | 企微工作台 → 应用内嵌打开 | OAuth2 静默授权 | 强制内嵌，保证安全、入口统一、用户粘性 |
| **坐席端** | 浏览器直接打开 | 扫码登录 | **无需经过企微**，灵活办公，支持多设备 |
| **管理后台** | 浏览器直接打开 | 扫码登录 | **无需经过企微**，安全可控 |
---
## 7. 模块架构
### 7.1 管理后台模块
**技术栈**：Vue 3 + TypeScript + Element Plus + Tailwind CSS + Pinia
**核心功能**：
- 运营仪表盘
- 功能开关配置
- 坐席管理（角色/技能标签）
- 外部系统集成配置
- 快速回复审核
- 会话监控
- 知识图谱管理
### 7.2 坐席工作台模块
**技术栈**：Vue 3 + TypeScript + Element Plus + Pinia
**核心功能**：
- 会话列表（排队/进行中/已解决）
- 实时聊天
- 快速回复
- AI Wingman 右侧栏
- 消息标记（VIP/招手/情绪）
### 7.3 H5 用户端模块
**技术栈**：Vue 3 + Vant 4 + TypeScript
**核心功能**：
- 消息发送/接收
- 排查步骤引导
- 会话状态查看
- 满意度评价
---
## 8. AI Wingman 设计
详见第15.7节「Wingman设计」
Wingman 是坐席工作台的 AI 辅助系统：
- **草稿回复**：坐席打字 → AI 实时生成 3 条草稿
- **自动摘要**：会话结束 → AI 200 字摘要
- **知识推荐**：对话中识别关键字 → 推 FAQ
- **排查步骤**：员工描述问题 → AI 给 step-by-step
---
## 9. 外部系统集成
### 9.1 系统角色与优先级
| 系统 | 角色 | 核心能力 | 认证方式 |
|------|------|---------|---------|
| 联软LV7000 | 主映射源(P0) | 终端查询、硬件详情、在线状态 | IP白名单+账号密码 |
| 火绒企业版 | 安全源(P0) | 终端列表、漏洞/病毒事件 | HMAC-SHA1 AccessKey |
| aTrust | VPN源(P1) | 在线用户+VPN IP、终端查询 | HMAC-SHA256签名 |
| 北森eHR | 辅助静态数据(P2) | 员工基础信息、任职信息 | OAuth2.0 |
| 企微审批 | 审批跳转+待办同步(P0/P1) | 12种审批类型URL直跳 + 审批工单同步到坐席待办 | 企微审批应用API |
| 运维平台 | 审批跳转(P1) | 6种运维审批工单URL直跳（同 corpid 跨应用免登录） | OAuth2 snsapi_base |
详见第15.9节「ExternalSystemAdapter抽象层设计」
---
## 10. 安全设计
### 10.1 认证安全
| 安全措施 | 说明 |
|----------|------|
| OAuth2 静默授权 | scope=snsapi_base，用户无感知（用户端） |
| 扫码认证 | 坐席/管理端认证方式 |
| state 参数防 CSRF | 随机 state，回调时验证 |
| Token 密码学安全 | secrets.token_urlsafe(32) |
| Token TTL 8小时 | Redis 自动过期 |
| redirect_uri 白名单 | 生产环境仅允许正式域名 |
| 企微 UA 检测 | 用户端非企微环境跳转拦截页 |
| OTP 双因素认证 | 坐席/管理员登录需 OTP 验证码 |
详见第15.2节「认证模块重构」
---
## 11. 复杂对话场景设计
详见第15.8节「复杂场景重构技术方案」
### 11.1 设计理念：TeliChat 三重约束
| 约束 | 作用 | 实现方式 |
|------|------|---------|
| 拓扑结构限制 | 限制对话可以走到哪里 | Neo4j DAG 边定义 |
| 信息状态约束 | 决定当前已经知道什么 | 信息项组合状态 |
| Python 代码约束 | 负责真正的业务判断 | FastAPI 业务逻辑 |
### 11.2 全局意图类型
| 意图 | 用户表达示例 | 处理策略 |
|------|-------------|---------|
| SKIP | "这个问题先不管了" | 跳过当前节点 |
| INSERT | "对了，我的打印机也有问题" | 插入新任务到队列 |
| RESUME | "还是说回刚才那个网络问题" | 恢复之前话题 |
| ESCALATE | "叫个人工来" | 转接坐席 |
---
## 12. 知识图谱数据模型设计
### 12.1 实体类型
| 实体类型 | 说明 | 示例 |
|----------|------|------|
| Domain | 业务域 | 网络域、安全域、设备域 |
| Issue | 问题 | VPN连不上、打印机故障 |
| Solution | 解决方案 | 密码重置、重启服务 |
| FAQ | 常见问题 | 如何连接VPN |
### 12.2 关系类型
| 关系类型 | 方向 | 含义 | 核心属性 |
|----------|------|------|----------|
| BELONGS_TO | Issue→Domain | 属于 | weight |
| RECOMMENDS | Issue→Solution | 推荐 | priority, confidence |
| CAN_RESOLVE | Solution→Issue | 解决 | success_rate |
---
## 13. 数据库设计
详见第15.10节「数据库ER图与环境变量」
### 13.1 核心表结构
| 表名 | 说明 |
|------|------|
| agents | 坐席信息 |
| conversations | 会话表 |
| messages | 消息表 |
| quick_reply_templates | 快速回复模板 |
| system_configs | 系统配置 |
| roles | 角色表 |
| user_roles | 用户角色关联 |
---
## 14. API设计规范
### 14.1 响应格式
```json
// 成功
{"code": 0, "data": {...}, "message": "success"}
// 失败
{"code": 1001, "data": null, "message": "参数错误"}
```
### 14.2 认证方式
| 端 | localStorage 键 | 说明 |
|----|-----------------|------|
| 坐席端 | `agent_token` | 坐席工作台 |
| 管理后台 | `admin_token` | 管理后台 |
| 统一入口 | `user_token` | Portal |
---
## 15. 技术方案详解
### 15.1 认证模块重构
> 整合自：技术方案-认证模块重构v2.md
#### 15.1.1 认证方式
| 场景 | 认证方式 | 说明 |
|------|----------|------|
| 企微内打开 | OAuth2 静默授权 | snsapi_base，自动获取 userid |
| 企微外打开 | 扫码登录 | 用户用企微扫码授权 |
| 互联企业 | 扫码 + 账号绑定 | 扫码后无本地记录则跳转绑定页 |
#### 15.1.2 统一认证API
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/auth/qrcode` | 获取扫码登录二维码 |
| GET | `/api/auth/scan/status` | 轮询扫码状态 |
| GET | `/api/auth/oauth2/callback` | OAuth2回调处理 |
| POST | `/api/auth/bind` | 账号绑定(互联企业) |
| POST | `/api/auth/verify` | 验证Token |
| POST | `/api/auth/logout` | 登出 |
| GET | `/api/auth/me` | 获取当前用户信息 |
#### 15.1.3 数据模型
```python
class LoginLog(Base):
"""登录日志模型"""
id: Mapped[str] = mapped_column(String(36), primary_key=True)
employee_id: Mapped[str] = mapped_column(String(64), nullable=True)
corp_id: Mapped[str] = mapped_column(String(64), nullable=False)
login_method: Mapped[str] = mapped_column(String(20)) # oauth/qrcode/bind
login_source: Mapped[str] = mapped_column(String(20)) # h5/agent/admin
ip_address: Mapped[str] = mapped_column(String(45), nullable=True)
status: Mapped[str] = mapped_column(String(20)) # success/failed/cancelled
created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
```
### 15.2 消息功能详细设计
> 整合自：技术方案-消息功能详细设计v2.md
#### 15.2.1 消息模型扩展
```python
class Message(Base):
# 消息状态（V2新增）
message_status: Mapped[str] = mapped_column(
String(20), nullable=False, default="sent",
comment="消息状态: sent/delivered/read"
)
# 表情回应（V2新增）
reactions: Mapped[Optional[Dict[str, str]]] = mapped_column(
JSON, nullable=True, default=None,
comment="表情回应: {emoji: user_id}"
)
# 设备类型
device_type: Mapped[str] = mapped_column(
String(20), nullable=False, default="desktop"
)
# 已读用户列表
read_by: Mapped[Optional[List[str]]] = mapped_column(
JSON, nullable=True, default=None
)
```
#### 15.2.2 WebSocket事件
| 事件名 | 说明 |
|--------|------|
| `new_message` | 新消息 |
| `message_status_changed` | 消息状态变更 |
| `reaction_added` | 表情回应添加 |
| `reaction_removed` | 表情回应移除 |
| `typing` | 对方正在输入 |
#### 15.2.3 推送策略优化
- 坐席回复仅推送到 H5 页面（WebSocket）
- 3分钟未回复自动发送企微提醒
- 10分钟后自动标记会话为"待关闭"状态
### 15.3 群聊邀请和协助
> 整合自：技术方案-群聊邀请和协助.md
#### 15.3.1 两种协作场景
| 场景 | 描述 | 字段 |
|------|------|------|
| **摇人协作** | 坐席A邀请坐席B协助处理 | `collaborating_agent_ids` |
| **邀请功能** | 坐席邀请员工/部门加入会话 | `participants` |
#### 15.3.2 权限矩阵
```
原始员工 主责坐席 协作坐席 被邀请人
查看消息 ✅ ✅ ✅ ✅
发送消息 ✅ ✅ ✅ ✅
邀请他人 ❌ ✅ ✅ ❌
结单 ❌ ✅ ❌ ❌
转接 ❌ ✅ ❌ ❌
```
### 15.4 企微审批工单同步
> 整合自：02-技术方案-企微审批工单同步.md
#### 15.4.1 整体架构
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 企微审批系统 │ ───▶ │ IT服务台后端 │ ───▶ │ 坐席待办事项 │
│ (外部API) │ │ (同步服务) │ │ (todo_items) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
#### 15.4.2 数据映射
| 企微审批字段 | todo_item 字段 |
|-------------|----------------|
| `sp_no` | `id` |
| `sp_name` | `title` |
| `apply_name` | `description.applicant` |
| `apply_time` | `created_at` |
#### 15.4.3 审批模板（12种类型 / 18个流程）
> 2026-07-10 更新：从原 6 个模板扩展到 18 个，覆盖全部 IT 审批流程。
| 序号 | 审批类型 | 流程名称 | 来源 | 后端模板 ID |
|------|---------|---------|------|------------|
| 1 | 设备申请 | IT资产领用登记 | 企微审批 | `asset_receive` |
| 2 | 设备申请 | IT资产借用申请 | 企微审批 | `asset_borrow` |
| 3 | 设备申请 | IT资产升级申请 | 企微审批 | `asset_upgrade` |
| 4 | 账号权限申请 | 企微外联权限申请 | 企微审批 | `wecom_external` |
| 5 | 账号权限申请 | 员工零信任（原VPN）账号 | 运维平台 | `zero_trust_vpn` |
| 6 | 账号权限申请 | 公共邮箱账号申请 | 运维平台 | `public_email` |
| 7 | 软件服务申请 | 商业软件服务申请 | 企微审批 | `software_service` |
| 8 | 资产处置申请 | IT资产外修申请 | 企微审批 | `asset_repair` |
| 9 | 资产处置申请 | IT资产报废申请 | 企微审批 | `asset_scrap` |
| 10 | 资产处置申请 | 资产退还登记 | 企微审批 | `asset_return` |
| 11 | 办公用品申请 | 办公用品超额领用审批 | 企微审批 | `office_supplies` |
| 12 | 会议室故障报修 | 会议室故障报修 | 企微审批 | `meeting_room_repair` |
| 13 | 企业应用管理 | 企业应用管理 | 企微审批 | `app_management` |
| 14 | 资产变更确认 | 资产变更确认 | 企微审批 | `asset_change` |
| 15 | 终端设备网络准入 | 终端设备网络准入申请 | 运维平台 | `network_access` |
| 16 | 活动与会议技术支持 | 活动与会议技术支持 | 运维平台 | `event_support` |
| 17 | 员工IT支持与故障报修 | 员工IT支持与故障报修 | 运维平台 | `it_support_repair` |
| 18 | 设备申请 | IT设备升级与硬件维修 | 运维平台 | `it_device_repair` |
#### 15.4.4 审批意图识别架构
```
用户消息
│
▼
┌─────────────────────┐
│ 关键词预过滤 │ _keyword_prefilter()
│ (APPROVAL_PREFILTER │ 合并 APPROVAL_TEMPLATES keywords + 预定义关键词
│ _KEYWORDS) │ 命中任意关键词 → 继续；未命中 → 跳过审批检测
└────────┬────────────┘
│ 命中
▼
┌─────────────────────┐
│ Dify 意图识别 │ _call_dify_approval_intent()
│ (原生 /v1/chat- │ 绕过 Dify2OpenAI 代理（序列化 bug）
│ messages API) │ 返回 JSON: {is_approval_request, confidence, approval_type}
└────────┬────────────┘
│ Dify 不可用
▼
┌─────────────────────┐
│ 关键词降级兜底 │ _fallback_detect()
│ (KEYWORD_TO_ │ 遍历关键词→审批类型映射
│ APPROVAL_TYPE) │ 置信度 0.6（低于阈值但预过滤已通过）
└─────────────────────┘
```
**Dify 配置**：System Prompt v2 覆盖 12 种审批类型，定义 4 级置信度策略：
- 明确审批意图（≥0.85）：用户直接表达"申请""报修"等动作
- 隐含审批意图（0.7~0.85）：描述需求但未明确说"申请"
- 咨询/提问（≤0.3）：询问信息而非申请
- 闲聊/无关（≤0.1）：与 IT 审批完全无关
#### 15.4.5 审批卡片前端架构
**组件**：`frontend-h5/src/components/chat/ApprovalCardModal.vue`
**数据结构**：
```typescript
interface ApprovalOption {
name: string // 选项名称
icon: string // Vant 图标
desc: string // 简短描述
url?: string // 直接跳转 URL（存在时直接导航，不存在时走后端模板匹配）
}
```
**选项配置**：`APPROVAL_OPTIONS` 按 `approval_type` 分组，12 种类型 / 17 个选项，每个选项均携带 `url` 字段。
**导航逻辑**（`handleSelect`）：
```
点击审批选项
│
├─ option.url 存在？─YES─→ window.location.href = option.url（同窗口导航）
│ 企微 webview 原生提供返回按钮
│
└─ option.url 不存在 ──→ fallback: 后端模板匹配
├─ type === 'jump' → createApprovalJump() → window.location.href
└─ type !== 'jump' → showToast('开发中')
```
#### 15.4.6 审批页面导航方案选型
| 方案 | 实现方式 | 优点 | 缺点 | 结论 |
|------|---------|------|------|------|
| A. 同窗口导航 | `window.location.href = url` | 1 行改动，企微原生返回，零风险 | 无自定义 UI | ✅ **已采用** |
| B. iframe 嵌入 | iframe + 自定义返回/关闭覆盖层 | 体验最佳，自定义 UI | 需放宽 COEP/CSP 安全头 | 待评估 |
| C. 同源代理 iframe | 后端代理页面 | 不改安全头 | 破坏审批 JS/cookie，复杂度高 | ❌ 不推荐 |
**方案 A 采用原因**：
生产环境 H5 nginx 配置了三道安全屏障：
1. CSP `default-src 'self'`（无 `frame-src`）→ 只允许同域 iframe
2. COEP `require-corp` → 跨域资源必须带 CORP 头
3. CORP `same-origin` → H5 自身资源仅同域可加载
企微审批 URL（`app.work.weixin.qq.com`）虽然未设 `X-Frame-Options`，但 COEP 这一层会拦截跨域 iframe。方案 B 需要将 COEP 从 `require-corp` 改为 `credentialless` 并在 CSP 中添加 `frame-src` 白名单，涉及安全策略变更。
在企微 webview 中，`window.location.href` 导航后企微原生提供顶部返回按钮，体验接近内嵌。
#### 15.4.7 企微跨应用免登录
**场景**：用户在 IT 服务台 H5 中点击运维平台审批链接，是否需要重新登录？
**结论**：可行。同一 corpid 下所有自建应用各自独立鉴权：
```
IT服务台 H5 (itsupport.servyou.com.cn)
│ 用户点击运维平台审批链接
▼
一站式运维平台 (devops.dc.servyou-it.com)
│ 运维平台走自己的 OAuth2 snsapi_base 静默授权
│ 企微 webview 自动注入 corpid + userid
▼
自动登录，无需手动输入凭证
```
**前提条件**：
1. 运维平台已配置企微可信域名
2. 运维平台已实现 OAuth2 回调后端逻辑
3. 两个应用在同一企微（同 corpid）下
#### 15.4.8 后端 API 端点
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/approval/templates` | 获取全部 18 个审批模板 |
| GET | `/approval/templates/{template_id}` | 获取单个模板基本信息 |
| GET | `/approval/templates/{template_id}/detail` | 获取模板详情（含审批字段） |
| POST | `/approval/jump` | 创建审批跳转链接（返回审批 URL） |
| POST | `/approval/submit` | 提交审批（API 模式，需企微 access_token） |
| POST | `/approval/callback` | 企微审批回调接收 |
| GET | `/approval/keywords` | 获取关键词→审批类型映射 |
| POST | `/approval/detect-intent` | 检测审批意图（预过滤→Dify→兜底三级链路） |
> **路由说明**：后端路由直接挂在根路径（如 `/approval/templates`），nginx 代理时 strip `/api/` 前缀，前端请求 `/api/approval/templates`。
### 15.5 复杂场景重构技术方案
> 整合自：技术方案-复杂场景重构.md
#### 15.5.1 设计理念：TeliChat 三重约束
| 约束 | 作用 | 实现方式 |
|------|------|---------|
| 拓扑结构限制 | 限制对话可以走到哪里 | Neo4j DAG 边定义 |
| 信息状态约束 | 决定当前已经知道什么 | 信息项组合状态 |
| Python 代码约束 | 负责真正的业务判断 | FastAPI 业务逻辑 |
#### 15.5.2 信息项修饰机制
| 修饰 | 含义 |
|------|------|
| `固定` | 用户回答后不再重复询问 |
| `增量` | 允许用户补充新信息 |
| `明确` | 必须明确回答 |
| `隐含` | 可以从上下文推断 |
| `复述` | 要求用户确认信息正确性 |
| `必需` | 必须填写才能进入下一节点 |
#### 15.5.3 四大复杂场景
1. **非线性跳转** - 用户在对话过程中不按线性路径跳转
2. **多意图并行** - 用户一次输入包含多个意图
3. **信息更正** - 用户更正之前提供的信息
4. **任务中断与恢复** - 任务进行中中断，后续可以恢复
### 15.6 ExternalSystemAdapter抽象层设计
> 整合自：技术方案-ExternalSystemAdapter抽象层.md
#### 15.6.1 架构分层
```
┌─────────────────────────────────────────────────┐
│ 上层业务代码（AI Wingman等） │
├─────────────────────────────────────────────────┤
│ ExternalSystemService（统一门面） │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 缓存层 │ │ 降级策略 │ │ 配置管理 │ │
│ └──────────┘ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────────┤
│ ExternalSystemAdapter（抽象基类） │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────┐│
│ │ LianRuan │ │ HuoRong │ │ aTrust │ │eHR ││
│ │ Adapter │ │ Adapter │ │ Adapter │ │适配││
│ └──────────┘ └──────────┘ └──────────┘ └────┘│
├─────────────────────────────────────────────────┤
│ MockAdapter（开发期） │
└─────────────────────────────────────────────────┘
```
#### 15.6.2 统一DTO模型
```python
class TerminalInfo(BaseModel):
"""统一终端信息模型"""
source_system: str
computer_name: str
ip_addresses: List[str]
mac_addresses: List[str]
os_version: Optional[str]
is_online: bool
logged_in_user: Optional[str]
department: Optional[str]
class SecurityStatus(BaseModel):
"""统一安全状态模型"""
source_system: str
terminal_id: str
virus_events: Optional[Dict]
vulnerabilities: Optional[List]
is_isolated: bool
```
### 15.7 Wingman设计
#### 15.7.1 核心能力
| 能力 | 说明 |
|------|------|
| 草稿回复 | 坐席打字 → AI 实时生成 3 条草稿 |
| 自动摘要 | 会话结束 → AI 200 字摘要 |
| 知识推荐 | 对话中识别关键字 → 推 FAQ |
| 排查步骤 | 员工描述问题 → AI 给 step-by-step |
#### 15.7.2 技术架构
```
┌─────────────────────────────────────────┐
│ 坐席工作台 (Vue3) │
└─────────────────┬───────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ FastAPI 后端 │
│ ┌─────────────────────────────────┐ │
│ │ Wingman Service │ │
│ │ • 草稿生成 │ │
│ │ • 自动摘要 │ │
│ │ • 知识推荐 │ │
│ │ • 排查步骤 │ │
│ └─────────────────────────────────┘ │
└─────────────────┬───────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ Dify / RAGFlow │
└─────────────────────────────────────────┘
```
---
## 16. 技术分析报告
### 16.1 JP-webcli自动化部署能力分析
> 整合自：技术分析-jp-webcli自动化部署能力分析.md
#### 16.1.1 核心自动化能力
| 能力 | 实现方式 | 状态 |
|------|---------|------|
| 自动登录 | Playwright 填写用户名/密码 | ✅ 稳定 |
| OTP 双因素认证 | pyotp 本地生成 TOTP | ✅ 自动填充 |
| 资产导航 | DOM 选择器定位目标行 | ✅ 支持模糊匹配 |
| Web CLI 连接 | 点击连接按钮 → 处理 Luna dialog | ✅ 含轮询重试 |
| 命令执行 | `keyboard.type()` 逐字输入 | ✅ 含 delay 防丢字 |
| SFTP 文件上传 | `set_input_files()` 文件管理器 | ✅ 分块（8 chunk） |
| base64 大文件传输 | 分段 echo + base64 -d 还原 | ✅ 250 字符/段 |
| 截图留存 | `page.screenshot()` | ✅ PNG 格式 |
| 会话复用 | `persistent_context` / CDP connect | ✅ v10 |
| 轮询等待 | 检测 prompt 字符/dialog/terminal | ✅ 40s → 待命 |
#### 16.1.2 部署场景
| 场景 | 日期 | 成果 |
|------|------|------|
| Hotfix #116 扫码获取 | 06-22 | `auth_qrcode.py` 部署成功 |
| Hotfix #120 扫码自动确认 | 06-23 | 29KB `qrcode_service.py` + 8 chunk SFTP |
---
## 17. 阶段5 自动化闭环
> **新增日期**: 2026-07-05 | **架构师**: 高见远 (Gao) | **状态**: 设计完成（待实现）
### 17.1 核心难点与对策
| 难点 | 说明 | 对策 |
|------|------|------|
| 多外部系统集成 | 火绒/联软/Dify/RAGFlow/eHR 认证与协议各异 | 抽象 `BaseClient` 统一超时/重试/审计 |
| 风险分级执行 | 只读/低风险自动执行，写/高危需审批 | 双模式执行引擎（plan-only / real-exec） |
| 员工↔终端映射 | 多源、需优先级与兜底 | `MappingResolver`：联软 > aTrust > eHR |
| 实时进度 | H5/坐席需秒级看到处置进展 | 复用 WebSocket，新增 `automation.*` 事件 |
### 17.2 架构分层
```
[三端前端] ──HTTP/WS──> [FastAPI /itportal/automation]
│
┌───────────────┼───────────────────────┐
[api/automation] [services/automation] [core/clients]
(路由+WS端点) (会话/意图/映射/执行/ (火绒/联软/Dify/
审批/进度/回滚/异常) RAGFlow/eHR)
│
[models/automation] ──SQLAlchemy──> PostgreSQL
[Redis] 会话态/映射缓存/静默TTL
```
### 17.3 核心API端点
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/sessions/start` | 员工提交意图，创建自动化会话 |
| GET | `/sessions/{id}` | 会话状态/进度快照 |
| POST | `/sessions/{id}/takeover` | 转人工/接管 |
| POST | `/actions/{id}/approve` | 坐席审批 |
| GET | `/configs` | 场景配置列表 |
| WS | `/ws/{session_id}` | 实时进度推送 |
### 17.4 风险分级
| 风险等级 | 说明 | 处理方式 |
|----------|------|---------|
| `read` | 只读操作 | 默认可自动执行 |
| `low` | 低风险操作 | 默认可自动执行 |
| `high` | 高危操作 | 必走审批或员工二次确认 |
---
### D. 员工端消息发送延时改造方案
> 状态：已完成
#### 问题背景
员工端 H5 发送一条消息时，后端会**同步**完成「消息落库 → 调用 AI 推理 → 返回响应」。由于 AI 推理本身耗时（非流式，一次 3~15 秒），整个 HTTP 请求被 AI 阻塞，前端即便做了乐观更新，发送态切换和 AI 回复仍被拖慢，用户感知为"发送有延时"。
#### 根因分析
**后端**：发送与 AI 推理串行耦合
- `h5_send_message` 第 897 行同步等待 AI 推理完成
- `ai_service` 内部走 **Dify 非流式调用** (`stream: False`)
**前端**：发送态依赖被阻塞的响应
- 已做乐观更新（自己消息立即显示，标记 sending）
- 但 sending → sent 切换依赖后端响应返回
#### 推荐方案：异步化 + 流式 WS 推送
**后端改造**：
1. 消息发送接口只存消息立即返回
2. AI 推理放到后台任务
3. 经 WS 流式推送 `ai_reply_chunk` 片段
4. 完成后推送完整 `ai_reply` 消息
**前端改造**：
1. 响应返回后立即将消息标记为 `sent`
2. WS 监听 `ai_reply_chunk` 事件，进行打字机效果展示
3. WS 监听 `ai_reply` 事件，替换占位消息
#### WS 事件协议
| 事件 type | 触发时机 | data 字段 |
|---|---|---|
| `ai_reply_chunk` | AI 每生成一个片段 | conversation_id, chunk |
| `ai_reply` | AI 完整生成并落库 | 完整 Message 对象 |
| `ai_reply_failed` | AI 推理异常 | conversation_id, reason |
#### 关键决策（ADR-001）
采用单 Worker 部署：
- 后端 docker-compose.yml 的 uvicorn 启动参数由 `--workers 2` 改为 `--workers 1`
- 原因：避免跨 worker 广播 50% 丢失问题
#### 实施结果
| 任务 | 状态 |
|---|---|
| 后端：拆后台任务 + WS 事件 + 兜底 | ✅ 已完成 |
| 前端：WS 监听 + 打字机拼装 + 状态修正 | ✅ 已完成 |
| 联调 + 端到端验证 | ✅ 已完成 |
---
### E. 项目阶段规划
| 阶段 | 内容 |
|------|------|
| 阶段一 | 转人工改H5+坐席MVP+邀请+管理后台 |
| 阶段二 | H5全流程+WS+排队+满意度+OAuth2 |
| 阶段三 | AI Wingman+排查流程图+标注+知识图谱 |
| 阶段四 | 迭代闭环+数据看板+知识库 |
| 阶段五 | 自动/辅助审核、开单、结单 |
### F. 部署信息
| 环境 | 域名 | IP |
|------|------|-----|
| 生产 | itsupport.servyou.com.cn | 10.90.5.110 |
| 测试 | itdesk.amanzac.com | NAS |
### G. 技术文档更新日志
| 版本 | 日期 | 修改内容 |
|------|------|---------|
| v1.0 | 2026-07-04 | 整合技术架构文档 |
| v1.1 | 2026-07-04 | 新增知识图谱章节 |
| v1.2 | 2026-07-04 | 新增登录设计章节 |
| v1.3 | 2026-07-04 | 坐席/管理端无需经过企微 |
| v1.4 | 2026-07-04 | 新增企微审批工单同步 |
| v2.0 | 2026-07-10 | 综合版：整合所有技术方案和技术分析 |
| v2.1 | 2026-07-10 | 部署架构新增方案 C（代码卷挂载替代镜像烘焙），含回滚策略 |
| v2.2 | 2026-07-10 | 审批系统扩展：15.4 节从 6 模板扩展到 12种/18流程，新增意图识别架构(15.4.4)、前端卡片架构(15.4.5)、导航方案选型(15.4.6)、跨应用免登录(15.4.7)、API端点(15.4.8) |
---
> **文档结束** — 本文档为 IT 智能服务台系统架构设计综合主文档
Reference in New Issue Copy Permalink