simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ca7c6d937a035728bf3214c20cb4437d4e1d6599
wecom_it_smart_desk/docs/03-技术架构/00-系统架构设计文档-v1.3.md
T

587 lines
23 KiB
Markdown
Raw Normal View History

chore: 整理项目结构，清理归档文件，更新部署配置
2026-07-04 21:01:39 +08:00
# IT智能服务台 — 系统架构设计文档
docs: 移动蓝绿部署指南到 troubleshooting 目录
2026-07-05 17:03:36 +08:00
> **文档版本**: v1.5
chore: 整理项目结构，清理归档文件，更新部署配置
2026-07-04 21:01:39 +08:00
> **创建日期**: 2025-07-11
> **最近更新**: 2026-07-04
> **架构师**: 高见远 (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设计规范)
---
## 1. 技术文档索引
本文档为技术架构主文档，相关详细设计文档如下：
| 文档 | 说明 | 状态 |
|------|------|------|
| **本文档** | 系统架构总览 v1.3 | ✅ 正式 |
| **01-ADRs-架构决策/** | 4项架构决策 | ✅ 已完成 |
| **02-技术方案/** | 具体功能技术方案 | |
| ├── [技术方案-消息功能详细设计.md](./02-技术方案/技术方案-消息功能详细设计.md) | 消息功能详细设计 | ✅ 已实现 |
| ├── [技术方案-摇人协作.md](./02-技术方案/技术方案-摇人协作.md) | 多坐席协作方案 | ✅ 已实现 |
| ├── [技术方案-邀请功能.md](./02-技术方案/技术方案-邀请功能.md) | 邀请功能方案 | ✅ 已实现 |
| ├── [技术方案-复杂场景重构.md](./02-技术方案/技术方案-复杂场景重构.md) | 复杂对话场景技术方案 | ✅ 设计完成 |
| └── [技术方案-ExternalSystemAdapter抽象层.md](./02-技术方案/技术方案-ExternalSystemAdapter抽象层.md) | 外部系统适配层设计 | ✅ 设计完成 |
| **03-技术分析/** | 技术研究分析 | |
| ├── [技术分析-H5右侧栏动态推送评估.md](./03-技术分析/技术分析-H5右侧栏动态推送评估.md) | H5右侧栏动态推送评估 | ✅ 已完成 |
| └── [技术分析-架构消息知识库迭代.md](./03-技术分析/技术分析-架构消息知识库迭代.md) | 架构消息知识库迭代 | ✅ 已完成 |
| **04-数据库设计/** | 数据库设计 | |
| └── [数据库设计-ER图与环境变量清点.md](./04-数据库设计/数据库设计-ER图与环境变量清点.md) | 数据库ER图与环境变量 | ✅ 已完成 |
| **05-架构图/** | Mermaid图表 | |
| └── [架构图集](./05-架构图/) | 各类时序图/类图 | ✅ 已完成 |
| [D-T19-知识图谱数据模型设计.md](../02-产品需求/小组任务书/D-T19-知识图谱数据模型设计.md) | 知识图谱数据模型设计 | ✅ 设计完成 |
---
## 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 :5176 │
│ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ 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.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 静默授权（用户端）
- 账号密码+OTP 认证（坐席/管理端）
- 角色检测与路由选择
- 统一 Token 管理
### 6.2 登录方式（v1.5 变更）
> **更新日期**: 2026-07-04 | **核心变更**: 坐席/管理端浏览器直接打开，**无需经过企微工作台**
| 端 | 访问方式 | 登录方式 | 说明 |
|----|----------|----------|------|
| **用户端 (H5)** | 企微工作台 → 应用内嵌打开 | OAuth2 静默授权 | 强制内嵌，保证安全、入口统一、用户粘性 |
| **坐席端** | 浏览器直接打开 | 账号密码+OTP | **无需经过企微**，灵活办公，支持多设备 |
| **管理后台** | 浏览器直接打开 | 账号密码+OTP | **无需经过企微**，安全可控 |
### 6.3 登录流程
```
用户端 (H5) 坐席端 / 管理后台
│ │
▼ ▼
企微工作台打开 浏览器直接访问
│ │
▼ ▼
OAuth2 静默授权 账号密码+OTP验证
(用户无感知) │
│ ▼
▼ 登录成功
跳转 /itdesk/ 跳转 /itagent/ 或 /itadmin/
```
### 6.4 角色路由逻辑
```
OAuth2 授权完成（用户端） / 登录成功（坐席/管理端）
│
▼
查询角色列表: GET /api/portal/roles
│
├── 仅 user 角色 → 直接跳转 /itdesk/
├── user + agent → 显示选择页（2张卡片）
├── user + admin → 显示选择页（2张卡片）
└── user + agent + admin → 显示选择页（3张卡片）
```
### 6.5 URL 路径规划
| 端 | 路径 | 说明 |
|---|------|------|
| 统一入口 | /itportal/ | 路由选择页 |
| 用户端 | /itdesk/ | 员工提交工单 |
| 坐席端 | /itagent/ | IT坐席处理会话 |
| 管理端 | /itadmin/ | 系统配置 |
| API | /api/ | 后端接口 |
### 6.6 企微环境检测
| 组件 | 说明 |
|------|------|
| **用户端检测** | `navigator.userAgent.includes('wxwork')`，非企微跳转拦截页 |
| **坐席/管理端** | 无需检测，浏览器直接访问 |
### 6.7 OTP 双因素认证
| 组件 | 说明 |
|------|------|
| **OTP 绑定** | 首次登录引导绑定，支持 TOTP（Google Authenticator/微信扫码） |
| **OTP API** | `/api/agents/otp-bind`、`/api/agents/otp-verify` |
| **验证场景** | 坐席/管理员登录时需 OTP 验证 |
| **绑定入口** | 坐席端 TopBar 下拉菜单"OTP二次验证"选项 |
### 6.8 测试账号
| 角色 | 用户名 | 初始密码 | OTP | 说明 |
|------|--------|----------|-----|------|
| 坐席 | `sxn` | `admin123` | 需绑定 | IT 支持组组长 |
| 管理 | `sxn` | `admin123` | 需绑定 | 同上，具有 admin 权限 |
> **注意**：生产环境需修改默认密码；坐席/管理员需先绑定OTP才能登录
---
## 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 设计
详见 [02-技术方案/技术方案-Wingman设计.md](./02-技术方案/技术方案-Wingman设计.md)
### 8.1 什么是 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 |
| 企微审批 | 待办同步(P1) | 审批工单同步到坐席待办 | 企微审批应用API |
### 9.2 企微审批工单同步
> **新增日期**: 2026-07-04
| 项目 | 说明 |
|------|------|
| **功能** | 将企微审批工单同步到坐席待办事项面板 |
| **企微API** | `GET /cgi-bin/oa/approvallist` |
| **同步频率** | 每5分钟定时拉取，或 Webhook 实时推送 |
| **数据映射** | 审批标题 → TodoItem.title / 审批状态 → TodoItem.status |
| **依赖** | 需企微管理后台创建审批应用并授权 API |
docs: 移动蓝绿部署指南到 troubleshooting 目录
2026-07-05 17:03:36 +08:00
### 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秒）。
chore: 整理项目结构，清理归档文件，更新部署配置
2026-07-04 21:01:39 +08:00
---
## 10. 安全设计
### 10.1 认证安全
| 安全措施 | 说明 |
|----------|------|
| OAuth2 静默授权 | scope=snsapi_base，用户无感知（用户端） |
| 账号密码+OTP | 坐席/管理端认证方式 |
| state 参数防 CSRF | 随机 state，回调时验证 |
| Token 密码学安全 | secrets.token_urlsafe(32) |
| Token TTL 8小时 | Redis 自动过期 |
| redirect_uri 白名单 | 生产环境仅允许正式域名 |
| 企微 UA 检测 | 用户端非企微环境跳转拦截页 |
| OTP 双因素认证 | 坐席/管理员登录需 OTP 验证码 |
### 10.2 角色安全
| 安全措施 | 说明 |
|----------|------|
| 角色最小权限 | 默认仅 user 角色 |
| 角色来源追溯 | user_roles 表记录 source 和 assigned_by |
| 管理端 IP 白名单 | 仅内网/VPN 可访问 |
docs: 移动蓝绿部署指南到 troubleshooting 目录
2026-07-05 17:03:36 +08:00
### 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;
```
chore: 整理项目结构，清理归档文件，更新部署配置
2026-07-04 21:01:39 +08:00
---
## 11. 复杂对话场景设计
### 11.1 设计理念：TeliChat 三重约束
| 约束 | 作用 | 实现方式 |
|------|------|---------|
| 拓扑结构限制 | 限制对话可以走到哪里 | Neo4j DAG 边定义 |
| 信息状态约束 | 决定当前已经知道什么 | 信息项组合状态 |
| Python 代码约束 | 负责真正的业务判断 | FastAPI 业务逻辑 |
### 11.2 全局意图类型
| 意图 | 用户表达示例 | 处理策略 |
|------|-------------|---------|
| SKIP | "这个问题先不管了" | 跳过当前节点 |
| INSERT | "对了，我的打印机也有问题" | 插入新任务到队列 |
| RESUME | "还是说回刚才那个网络问题" | 恢复之前话题 |
| ESCALATE | "叫个人工来" | 转接坐席 |
---
## 12. 知识图谱数据模型设计
详见 [../02-产品需求/小组任务书/D-T19-知识图谱数据模型设计.md](../02-产品需求/小组任务书/D-T19-知识图谱数据模型设计.md)
### 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. 数据库设计
### 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 |
---
## 附录
### A. 项目阶段规划
| 阶段 | 内容 |
|------|------|
| 阶段一 | 转人工改H5+坐席MVP+邀请+管理后台 |
| 阶段二 | H5全流程+WS+排队+满意度+OAuth2 |
| 阶段三 | AI Wingman+排查流程图+标注+知识图谱 |
| 阶段四 | 迭代闭环+数据看板+知识库 |
| 阶段五 | 自动/辅助审核、开单、结单 |
### B. 部署信息
| 环境 | 域名 | IP |
|------|------|-----|
| 生产 | itsupport.servyou.com.cn | 10.90.5.110 |
| 测试 | itdesk.amanzac.com | NAS |
### C. 技术文档更新日志
| 版本 | 日期 | 修改内容 |
|------|------|---------|
| 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 | 新增企微审批工单同步到待办事项 |
---
> **文档结束** — 本文档为 IT 智能服务台系统架构设计主文档
Reference in New Issue Copy Permalink