simon/wecom_it_smart_desk

Fork 0

Files

T

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

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

26 KiB

Raw Blame History

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

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

1. 技术文档索引

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

文档	说明	状态
IT智能服务台-技术架构设计.md	本文档 — 系统架构总览	✅ 正式
统一入口技术设计文档.md	Portal 统一入口详细设计	✅ 实施中
ExternalSystemAdapter设计文档.md	外部系统适配层设计	✅ 设计完成
Wingman设计.md	AI 僚机系统设计	✅ 设计阶段
重构方案-复杂场景技术方案.md	复杂对话场景技术方案	✅ 设计完成
消息功能详细方案.md	消息功能详细设计	✅ 已实现
摇人-多坐席协作-技术方案.md	多坐席协作方案	✅ 已实现
邀请功能-技术方案.md	邀请功能方案	✅ 已实现

2. 系统概述

2.1 项目背景

IT智能服务台是为企业提供 IT support 的智能化服务平台，核心目标：

员工侧：通过 H5 页面提交 IT 问题、AI 自助解答、人工坐席服务
坐席侧：通过自研工作台处理会话、AI 辅助（ Wingman ）、知识推荐
管理侧：通过管理后台配置系统、管理坐席、查看数据

2.2 核心能力

能力	说明
消息路由	AI 与人工无缝切换
实时会话	坐席工作台实时消息
AI 辅助	Wingman 草稿/摘要/知识推荐
外部集成	联软/火绒/aTrust/eHR 终端数据
角色管理	统一入口 + RBAC 权限

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│  │   Dify AI    │     │
│  │ Backend  │──│ (缓存/Session)│──│ (持久化)  │──│ (外部依赖)   │     │
│  │  :8000   │  │  :6379   │  │  :5432   │  │              │     │
│  └────┬─────┘  └──────────┘  └──────────┘  └──────────────┘     │
│       │                                                                  │
└───────┼──────────────────────────────────────────────────────────────────┘
        │  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

3.3 后端架构

backend/
├── app/
│   ├── api/              # API 路由
│   │   ├── admin.py      # 管理后台 API
│   │   ├── agents.py     # 坐席 API
│   │   ├── h5.py        # H5 用户端 API
│   │   ├── portal.py     # 统一入口 API
│   │   └── wecom.py     # 企微回调 API
│   ├── models/           # 数据模型
│   ├── schemas/          # Pydantic Schema
│   ├── services/         # 业务逻辑
│   │   ├── wingman.py   # AI 僚机服务
│   │   ├── external/    # 外部系统适配器
│   │   └── message_router.py  # 消息路由
│   └── config.py         # 配置管理
├── alembic/              # 数据库迁移
└── requirements.txt

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	主数据存储
缓存	Redis	7	Session/Token/缓存
AI 引擎	Dify	—	外部依赖

4.2 关键技术挑战与解决方案

#	挑战	解决方案
1	企微消息加解密	使用 `cryptography` 库实现 AES-CBC-256 加解密
2	access_token 管理	Redis 缓存 + 过期自动刷新（提前 300 秒刷新）
3	坐席端实时性	短轮询（3-5 秒）+ WebSocket 推送
4	消息路由	路由层统一分发，AI/人工无缝切换
5	OAuth2 静默授权	企微 OAuth2 授权 + 后端换算用户身份

5. 部署架构

5.1 部署拓扑

                          ┌────────────────────────────┐
                          │      企微服务器（外部）      │
                          │  qyapi.weixin.qq.com       │
                          └──────────┬─────────────────┘
                                     │ HTTPS :443
                                     ▼
┌──────────────── 办公网络 ────────────────────────────────┐
│                                                          │
│  ┌──────────┐         ┌──────────────────────────┐      │
│  │ 坐席浏览器 │────────▶│ https://itsupport.      │      │
│  │ (内网)    │   HTTPS  │ servyou.com.cn          │      │
│  └──────────┘         └──────────┬───────────────┘      │
│                                  │                       │
├────────────────── OA 服务器网络 ──┼───────────────────────┤
│                                  │                       │
│                          ┌───────▼──────────────┐       │
│                          │   服务器 (Docker)      │       │
│                          │                      │       │
│                          │  ┌────────────────┐  │       │
│                          │  │  Nginx :80/443 │  │       │
│                          │  │  独立容器       │  │       │
│                          │  └───────┬────────┘  │       │
│                          │          │            │       │
│                          │  ┌───────▼────────┐  │       │
│                          │  │  FastAPI :8000 │  │       │
│                          │  │  独立容器       │  │       │
│                          │  └───┬───────┬────┘  │       │
│                          │      │       │        │       │
│                          │  ┌───▼──┐ ┌──▼───┐  │       │
│                          │  │ PG16 │ │Redis7│  │       │
│                          │  │独立容器│ │独立容器│  │       │
│                          │  └──────┘ └──────┘  │       │
│                          └──────────────────────┘       │
│                                   │                      │
│                          ┌────────▼──────────────┐     │
│                          │  现有 AI 服务（外部依赖）│     │
│                          │  ├─ Dify              │     │
│                          │  ├─ RAGFlow           │     │
│                          │  └─ Qwen3-30B        │     │
│                          └───────────────────────┘     │
└──────────────────────────────────────────────────────────┘

5.2 Docker 容器拓扑

新服务器 Docker Engine
│
├── Docker Network: itdesk_net (bridge, internal)
│   │
│   ├── Container: wecom_it_postgres
│   │   Image: postgres:16-alpine
│   │   Volume: wecom_it_postgres_data
│   │   Port: 5432 (仅 itdesk_net 内部)
│   │
│   ├── Container: wecom_it_redis
│   │   Image: redis:7-alpine
│   │   Volume: wecom_it_redis_data
│   │   Port: 6379 (仅 itdesk_net 内部)
│   │
│   ├── Container: wecom_it_backend
│   │   Image: wecom-it-desk-backend:latest
│   │   Port: 8000 (仅 itdesk_net 内部)
│   │   Env: DATABASE_URL, REDIS_URL, WECOM_*
│   │   Healthcheck: GET /health
│   │
│   └── Container: wecom_it_nginx
│       Image: nginx:1.27-alpine
│       Port: 80:80, 443:443 (宿主机映射)
│       Volumes: nginx.conf:ro, 前端dist:ro, SSL:ro
│       Healthcheck: GET /health
│
└── Volumes (命名卷，持久化)
    ├── wecom_it_postgres_data
    └── wecom_it_redis_data

5.3 关键隔离策略

隔离层面	方案	隔离效果
服务器级	独立 VM	挂了不影响其他系统
网络级	Docker 内部网络	PG/Redis 不暴露端口
存储级	独立命名卷	数据完全隔离
域名级	独立子域名	变更不影响其他系统
认证级	JWT + 独立 Redis	账户体系独立

6. 统一入口设计

6.1 概述

统一入口（Portal）是系统的唯一认证入口，所有用户必须通过企微工作台进入系统。

核心功能：

企微 OAuth2 静默授权
角色检测与路由选择
统一 Token 管理

6.2 角色路由逻辑

OAuth2 授权完成
    │
    ▼
查询角色列表: GET /api/portal/roles
    │
    ├── 仅 user 角色 → 直接跳转 /itdesk/
    ├── user + agent → 显示选择页（2张卡片）
    ├── user + admin → 显示选择页（2张卡片）
    └── user + agent + admin → 显示选择页（3张卡片）

6.3 URL 路径规划

端	路径	说明
统一入口	/itportal/	路由选择页
用户端	/itdesk/	员工提交工单
坐席端	/itagent/	IT坐席处理会话
管理端	/itadmin/	系统配置
API	/api/	后端接口

6.4 数据库设计

角色表 (roles)

CREATE TABLE roles (
    id SERIAL PRIMARY KEY,
    name VARCHAR(50) NOT NULL UNIQUE,           -- 角色标识: user/agent/admin
    display_name VARCHAR(100) NOT NULL,         -- 显示名称
    description TEXT,                            -- 角色描述
    permissions JSONB DEFAULT '[]',              -- 权限列表
    is_default BOOLEAN DEFAULT FALSE,          -- 是否默认角色
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

用户角色关联表 (user_roles)

CREATE TABLE user_roles (
    id SERIAL PRIMARY KEY,
    employee_id VARCHAR(100) NOT NULL,          -- 企微 UserID
    role_id INTEGER NOT NULL REFERENCES roles(id),
    source VARCHAR(50) NOT NULL,                -- 来源: auto/tag/ehr/manual
    assigned_by VARCHAR(100),                   -- 分配者
    assigned_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    expires_at TIMESTAMP,                      -- 过期时间
    UNIQUE(employee_id, role_id)
);

7. 模块架构

7.1 管理后台模块

详见 ARCHITECTURE-admin.md

技术栈：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 设计

详见 Wingman设计.md

8.1 什么是 Wingman

Wingman 是坐席工作台的 AI 辅助系统，在坐席处理会话时实时提供：

草稿回复：坐席打字 → AI 实时生成 3 条草稿
自动摘要：会话结束 → AI 200 字摘要
知识推荐：对话中识别关键字 → 推 FAQ
排查步骤：员工描述问题 → AI 给 step-by-step

8.2 系统架构

┌─────────────────────────────────────────────────────────┐
│  FastAPI 后端                                           │
│  ┌──────────────────────────────────────────────┐      │
│  │  WingmanService (wingman.py)                 │      │
│  │  ├── draft_reply()        草稿回复          │      │
│  │  ├── summarize()          自动摘要          │      │
│  │  ├── recommend_knowledge() 知识推荐          │      │
│  │  └── troubleshoot()       排查步骤          │      │
│  └────────────────┬─────────────────────────────┘      │
│                   │                                     │
│  ┌────────────────▼─────────────────────────────┐      │
│  │  DifyClient (dify_client.py)                │      │
│  └──────────────────────────────────────────────┘      │
└────────────────────┬────────────────────────────────────┘
                     │ HTTPS
                     ▼
┌─────────────────────────────────────────────────────────┐
│  Dify 平台                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ 工作流 A     │  │ 工作流 B     │  │ 工作流 C     │  │
│  │ 草稿回复     │  │ 摘要生成     │  │ 排查步骤     │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘

8.3 数据模型

class WingmanDraft(Base):
    """草稿回复"""
    __tablename__ = "wingman_drafts"
    conv_id = Column(String, ForeignKey("conversations.id"))
    agent_id = Column(String, ForeignKey("agents.id"))
    drafts = Column(JSON)                    # ["draft1", "draft2", "draft3"]
    context_messages = Column(JSON)          # 最近 10 条消息
    accepted_index = Column(Integer, nullable=True)
    expires_at = Column(DateTime)            # 5 分钟后过期

class WingmanSummary(Base):
    """会话摘要"""
    __tablename__ = "wingman_summaries"
    conv_id = Column(String, unique=True)
    summary = Column(String(2000))           # AI 生成
    edited_summary = Column(String(2000))    # 坐席修改
    final_summary = Column(String(2000))    # 最终版本
    agent_id = Column(String)

9. 外部系统集成

详见 ExternalSystemAdapter设计文档.md

9.1 系统角色与优先级

系统	角色	核心能力	认证方式
联软LV7000	主映射源(P0)	终端查询、硬件详情、在线状态	IP白名单+账号密码
火绒企业版	安全源(P0)	终端列表、漏洞/病毒事件	HMAC-SHA1 AccessKey
aTrust	VPN源(P1)	在线用户+VPN IP、终端查询	HMAC-SHA256签名
北森eHR	辅助静态数据(P2)	员工基础信息、任职信息	OAuth2.0

9.2 架构分层

┌─────────────────────────────────────────────────┐
│              上层业务代码（AI Wingman等）          │
├─────────────────────────────────────────────────┤
│           ExternalSystemService（统一门面）        │
│    ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│    │ 缓存层   │ │ 降级策略 │ │ 配置管理 │       │
│    └──────────┘ └──────────┘ └──────────┘       │
├─────────────────────────────────────────────────┤
│           ExternalSystemAdapter（抽象基类）        │
│    ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────┐│
│    │ LianRuan │ │ HuoRong  │ │ aTrust   │ │eHR ││
│    │ Adapter  │ │ Adapter  │ │ Adapter  │ │适配││
│    └──────────┘ └──────────┘ └──────────┘ └────┘│
├─────────────────────────────────────────────────┤
│               MockAdapter（开发期）               │
└─────────────────────────────────────────────────┘

9.3 核心抽象接口

class ExternalSystemAdapter(ABC):
    @property
    @abstractmethod
    def system_name(self) -> str: ...

    @property
    @abstractmethod
    def is_available(self) -> bool: ...

    @abstractmethod
    async def health_check(self) -> bool: ...

    async def get_terminal_by_user(self, username: str) -> Optional[TerminalInfo]: ...

    async def get_security_status(self, terminal_id: str) -> Optional[SecurityStatus]: ...

10. 安全设计

10.1 认证安全

安全措施	说明
OAuth2 静默授权	scope=snsapi_base，用户无感知
state 参数防 CSRF	随机 state，回调时验证
Token 密码学安全	secrets.token_urlsafe(32)
Token TTL 8小时	Redis 自动过期
redirect_uri 白名单	生产环境仅允许正式域名
企微 UA 检测	非企微 WebView 拒绝访问

10.2 角色安全

安全措施	说明
角色最小权限	默认仅 user 角色
角色来源追溯	user_roles 表记录 source 和 assigned_by
管理端 IP 白名单	仅内网/VPN 可访问
OTP 二次验证	管理后台访问需 OTP 验证

10.3 API 安全

安全措施	说明
API Key 认证	外部系统独立认证通道
速率限制	slowapi 中间件
CORS 配置	限制允许的来源

11. 复杂对话场景设计

详见重构方案-复杂场景技术方案.md

11.1 设计理念：TeliChat 三重约束

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

11.2 信息项修饰机制

修饰	含义	应用场景
固定	用户回答后不再重复询问	已通过系统获取的信息
增量	允许用户补充新信息	故障描述、错误信息
明确	必须明确回答	紧急程度确认
隐含	可以从上下文推断	AI 推断的问题类型
复述	要求用户确认信息正确性	重要操作确认
必需	必须填写才能进入下一节点	必填字段

11.3 全局意图类型

意图	用户表达示例	处理策略
SKIP	"这个问题先不管了"	跳过当前节点
INSERT	"对了，我的打印机也有问题"	插入新任务到队列
RESUME	"还是说回刚才那个网络问题"	恢复之前话题
SWITCH	"先帮我看看VPN吧"	切换到指定话题
CORRECT	"刚才说错了，是win10"	更新信息项值
PAUSE	"我先去开会，等会继续"	保存状态，等待恢复
ESCALATE	"叫个人工来"	转接坐席

11.4 核心场景

场景	支持状态
非线性跳转	✅ 支持
多意图并行	✅ 支持
信息更正	✅ 支持
任务中断恢复	✅ 支持

12. 数据库设计

12.1 核心表结构

表名	说明
agents	坐席信息
conversations	会话表
messages	消息表
quick_reply_templates	快速回复模板
system_configs	系统配置
roles	角色表
user_roles	用户角色关联
role_mapping_rules	角色映射规则

12.2 Alembic 迁移

所有数据库迁移位于 backend/alembic/versions/ 目录，按序号执行：

alembic/
├── env.py              # 迁移环境配置
├── script.py.mako
└── versions/
    ├── 001_initial.py      # 初始表结构
    ├── 002_agents.py       # 坐席扩展
    ├── 003_conversations.py
    ├── 004_messages.py
    ├── 005_system_configs.py
    └── ...                 # 后续迁移

13. API 设计规范

13.1 响应格式

// 成功
{"code": 0, "data": {...}, "message": "success"}

// 失败
{"code": 1001, "data": null, "message": "参数错误"}

13.2 错误码规范

错误码	含义
0	成功
1001	参数错误
1002	未授权
1003	资源不存在
1004	无权限访问
1005	服务器内部错误

13.3 认证方式

端	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	整合技术架构文档，统一入口、部署、AI Wingman、外部系统集成等模块

文档结束 — 本文档为 IT 智能服务台系统架构设计主文档

26 KiB Raw Blame History Unescape Escape

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

目录

1. 技术文档索引

2. 系统概述

2.1 项目背景

2.2 核心能力

3. 整体架构

3.1 系统架构图

3.2 前端架构

3.3 后端架构

4. 技术选型

4.1 核心技术栈

4.2 关键技术挑战与解决方案

5. 部署架构

5.1 部署拓扑

5.2 Docker 容器拓扑

5.3 关键隔离策略

6. 统一入口设计

6.1 概述

6.2 角色路由逻辑

6.3 URL 路径规划

6.4 数据库设计

角色表 (roles)

用户角色关联表 (user_roles)

7. 模块架构

7.1 管理后台模块

7.2 坐席工作台模块

7.3 H5 用户端模块

8. AI Wingman 设计

8.1 什么是 Wingman

8.2 系统架构

8.3 数据模型

9. 外部系统集成

9.1 系统角色与优先级

9.2 架构分层

9.3 核心抽象接口

10. 安全设计

10.1 认证安全

10.2 角色安全

10.3 API 安全

11. 复杂对话场景设计

11.1 设计理念：TeliChat 三重约束

11.2 信息项修饰机制

11.3 全局意图类型

11.4 核心场景

12. 数据库设计

12.1 核心表结构

12.2 Alembic 迁移

13. API 设计规范

13.1 响应格式

13.2 错误码规范

13.3 认证方式

附录

A. 项目阶段规划

B. 部署信息

C. 技术文档更新日志

26 KiB

Raw Blame History