simon/wecom_it_smart_desk

Fork 0

Files

T

Simon 64ff1bf7d5 chore: 整理项目结构，清理归档文件，更新部署配置

2026-07-04 21:01:39 +08:00

20 KiB

Raw Blame History

IT智能服务台 — 系统架构设计文档

文档版本: v1.4 创建日期: 2025-07-11 最近更新: 2026-07-04 架构师: 高见远 (Bob) 状态: 正式版

1. 技术文档索引

本文档为技术架构主文档，相关详细设计文档如下：

文档	说明	状态
本文档	系统架构总览 v1.3	✅ 正式
01-ADRs-架构决策/	4项架构决策	✅ 已完成
02-技术方案/	具体功能技术方案
├── 技术方案-消息功能详细设计.md	消息功能详细设计	✅ 已实现
├── 技术方案-摇人协作.md	多坐席协作方案	✅ 已实现
├── 技术方案-邀请功能.md	邀请功能方案	✅ 已实现
├── 技术方案-复杂场景重构.md	复杂对话场景技术方案	✅ 设计完成
└── 技术方案-ExternalSystemAdapter抽象层.md	外部系统适配层设计	✅ 设计完成
03-技术分析/	技术研究分析
├── 技术分析-H5右侧栏动态推送评估.md	H5右侧栏动态推送评估	✅ 已完成
└── 技术分析-架构消息知识库迭代.md	架构消息知识库迭代	✅ 已完成
04-数据库设计/	数据库设计
└── 数据库设计-ER图与环境变量清点.md	数据库ER图与环境变量	✅ 已完成
05-架构图/	Mermaid图表
└── 架构图集	各类时序图/类图	✅ 已完成
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

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

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 可访问

11. 复杂对话场景设计

11.1 设计理念：TeliChat 三重约束

约束	作用	实现方式
拓扑结构限制	限制对话可以走到哪里	Neo4j DAG 边定义
信息状态约束	决定当前已经知道什么	信息项组合状态
Python 代码约束	负责真正的业务判断	FastAPI 业务逻辑

11.2 全局意图类型

意图	用户表达示例	处理策略
SKIP	"这个问题先不管了"	跳过当前节点
INSERT	"对了，我的打印机也有问题"	插入新任务到队列
RESUME	"还是说回刚才那个网络问题"	恢复之前话题
ESCALATE	"叫个人工来"	转接坐席

12. 知识图谱数据模型设计

详见 ../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 响应格式

// 成功
{"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 智能服务台系统架构设计主文档

20 KiB Raw Blame History Unescape Escape

IT智能服务台 — 系统架构设计文档

目录

1. 技术文档索引

2. 系统概述

2.1 项目背景

2.2 核心能力

3. 整体架构

3.1 系统架构图

3.2 前端架构

4. 技术选型

4.1 核心技术栈

5. 部署架构

5.1 部署拓扑

6. 统一入口设计

6.1 概述

6.2 登录方式（v1.5 变更）

6.3 登录流程

6.4 角色路由逻辑

6.5 URL 路径规划

6.6 企微环境检测

6.7 OTP 双因素认证

6.8 测试账号

7. 模块架构

7.1 管理后台模块

7.2 坐席工作台模块

7.3 H5 用户端模块

8. AI Wingman 设计

8.1 什么是 Wingman

9. 外部系统集成

9.1 系统角色与优先级

9.2 企微审批工单同步

10. 安全设计

10.1 认证安全

10.2 角色安全

11. 复杂对话场景设计

11.1 设计理念：TeliChat 三重约束

11.2 全局意图类型

12. 知识图谱数据模型设计

12.1 实体类型

12.2 关系类型

13. 数据库设计

13.1 核心表结构

14. API设计规范

14.1 响应格式

14.2 认证方式

附录

A. 项目阶段规划

B. 部署信息

C. 技术文档更新日志

20 KiB

Raw Blame History