wecom_it_smart_desk/docs/03-技术架构/00-系统架构设计文档-v1.3.md

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

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

---

目录

1. 技术文档索引
2. 系统概述
3. 整体架构
4. 技术选型
5. 部署架构
6. 统一入口设计
7. 模块架构
8. AI Wingman 设计
9. 外部系统集成
10. 安全设计
11. 复杂对话场景设计
12. 知识图谱数据模型设计
13. 数据库设计
14. API设计规范

---

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

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秒）。

---

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

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 数据库设计

-- 扩展 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;

---

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

---

15. 阶段5 自动化闭环

新增日期: 2026-07-05 | 架构师: 高见远 (Gao) | 状态: 设计完成（待实现） 范围: 在阶段1-4 基础上新增自动化闭环能力——意图识别与场景路由、员工↔终端映射、知识库自助应答、自动化处置执行（双模式）、审批与审计、转人工兜底、自动关单、管理后台配置、实时进度推送、指标看板。 技术栈: FastAPI + SQLAlchemy + PostgreSQL + Redis / Vue3（Element Plus / Vant4 / Element+Tailwind）三端。

15.1 实现方案与框架选型

15.1.1 核心难点

难点	说明	对策
多外部系统集成	火绒(HMAC-SHA1)/联软(三层认证)/Dify/RAGFlow/北森eHR 认证与协议各异	抽象 BaseClient 统一超时/重试/审计；ActionRegistry 按动作类型注册适配器
风险分级执行	只读/低风险自动执行，写/高危需审批或员工二次确认	执行引擎 Executor 双模式（plan-only / real-exec），risk_level 驱动分支
员工↔终端映射	多源、需优先级与兜底	MappingResolver：联软(主) > aTrust(VPN辅,后置) > eHR(静态)，结果缓存 MappingCache
实时进度	H5/坐席需秒级看到处置进展	复用阶段2 WebSocket，新增 automation.* 事件族，由 ProgressPublisher 统一发布
自动关单	成功+员工已解决 或 静默10min 无异议	Redis TTL + 后台任务触发，复用阶段2满意度

15.1.2 选型（沿用现有栈，仅新增必要依赖）

• 后端：FastAPI 路由 + Pydantic Schema + SQLAlchemy 模型 + Alembic 迁移；异步 HTTP 用 httpx（若未引入）；重试用 tenacity。
• 外部客户端：自研 app/core/clients/*，统一封装 HMAC 签名与三层认证，不引入重型 SDK。
• 前端三端：沿用 Vue3 组合式 API + Pinia + 现有 axios/WebSocket 封装，不新增 npm 包。
• 可视化编排引擎：本期用管理后台结构化简易配置（场景开关+触发条件+动作+审批策略），编排引擎列 P2。
• aTrust VPN 自动化：密钥未到，列 P2-04 后置，不影响首期。

15.1.3 架构分层

[三端前端] ──HTTP/WS──> [FastAPI /itportal/automation]
                              │
              ┌───────────────┼───────────────────────┐
        [api/automation]  [services/automation]   [core/clients]
         (路由+WS端点)   (会话/意图/映射/执行/   (火绒/联软/Dify/
                             审批/进度/回滚/异常)   RAGFlow/eHR)
                              │
                   [models/automation] ──SQLAlchemy──> PostgreSQL
                   [Redis] 会话态/映射缓存/静默TTL

15.2 文件列表及相对路径（标注 新增/修改 + 职责）

15.2.1 后端 backend/

路径	状态	职责
app/core/config.py	修改	新增自动化配置键（Dify/RAGFlow/火绒/联软/eHR 基址、密钥占位、阈值默认）
app/core/constants.py	修改	新增 WS 事件名 AUTOMATION_*、错误码段 AUT-*
app/core/clients/__init__.py	新增	客户端包导出
app/core/clients/base.py	新增	带超时/重试/审计的异步 BaseClient
app/core/clients/huorong.py	新增	火绒 HMAC-SHA1：_leak / _virus_events / 病毒隔离(写)
app/core/clients/lianruan.py	新增	联软 LV7000 三层认证，strusername 员工↔终端映射(读)
app/core/clients/dify.py	新增	Dify 意图识别 / AI 编排
app/core/clients/ragflow.py	新增	RAGFlow 知识库检索(:9380)
app/core/clients/ehr.py	新增	北森 eHR 静态映射兜底
app/models/automation.py	新增	AutoSession / AutoAction / ApprovalTicket / ScenarioConfig / ActionLog / RuleVersion / MappingCache
migrations/versions/xxxx_automation.py	新增	Alembic 迁移建表
app/schemas/automation.py	新增	请求/响应 Pydantic Schema
app/dependencies/automation.py	新增	场景配置加载、WS 连接鉴权、审批权限(OTP仅admin配置)
app/services/automation/__init__.py	新增	服务包导出
app/services/automation/session_manager.py	新增	会话生命周期（创建/状态机/关单判定）
app/services/automation/intent_router.py	新增	意图识别 + 场景路由（Dify+RAGFlow）
app/services/automation/mapping_resolver.py	新增	员工↔终端映射解析（联软>eHR）
app/services/automation/executor.py	新增	处置执行引擎（双模式、风险分级、动作编排）
app/services/automation/action_registry.py	新增	动作适配器注册（火绒/联软；aTrust 占位）
app/services/automation/approval.py	新增	审批单创建/流转/审计
app/services/automation/progress_publisher.py	新增	WS 进度统一发布
app/services/automation/rollback.py	新增(P1)	处置失败回滚/补偿
app/services/automation/exception_handler.py	新增(P1)	异常自动转人工 + 通知
app/api/automation.py	新增	REST 路由 + WS 端点
app/main.py	修改	注册 automation router 与 WS 路由

15.2.2 前端 H5（员工端）frontend-h5/src/

路径	状态	职责
api/automation.js	新增	自动化会话/确认/已解决接口
views/AutomationProgress.vue	新增	自动化进度页（WS 实时进展）
components/ActionConfirmDialog.vue	新增(P1)	员工侧高危动作二次确认
components/ResolveFeedback.vue	新增	「已解决」反馈 / 静默关单提示
store/automation.js	新增	Pinia 自动化状态

15.2.3 前端 坐席端 frontend-agent/src/

路径	状态	职责
api/automation.js	新增	会话/审批/接管接口
views/automation/SessionWorkbench.vue	新增	自动化会话工作台
components/automation/ActionApprovalCard.vue	新增	坐席审批卡片
components/automation/TakeoverPanel.vue	新增	转人工/接管面板
store/automation.js	新增	Pinia 状态

15.2.4 前端 管理后台 frontend-admin/src/

路径	状态	职责
api/automation.js	新增	配置/版本/指标接口
views/automation/ScenarioConfig.vue	新增	场景开关+触发条件+动作+审批策略
views/automation/RuleVersion.vue	新增(P1)	规则版本管理/灰度
views/dashboard/AutoMetrics.vue	新增	指标看板（扩展阶段4）
store/automation.js	新增	Pinia 状态

15.3 数据结构和接口（Mermaid 类图）

classDiagram
    class ScenarioConfig {
        +int id
        +str name
        +bool enabled
        +dict trigger_conditions
        +dict actions
        +dict approval_policy
        +int version
        +int gray_pct
        +datetime created_at
        +datetime updated_at
        +int created_by
    }
    class AutoSession {
        +int id
        +int ticket_id
        +str employee_id
        +str intent
        +float intent_confidence
        +int scenario_config_id
        +str status
        +str mode
        +str current_step
        +bool takeover_flag
        +bool auto_close_flag
        +datetime created_at
        +datetime updated_at
    }
    class AutoAction {
        +int id
        +int session_id
        +str type
        +str target
        +dict params
        +str mode
        +str risk_level
        +str status
        +bool is_approved
        +dict result
        +str error_msg
        +bool rolled_back
        +datetime executed_at
    }
    class ApprovalTicket {
        +int id
        +int action_id
        +int session_id
        +int approver_id
        +str employee_id
        +str type
        +str status
        +datetime requested_at
        +datetime resolved_at
        +str resolution
    }
    class ActionLog {
        +int id
        +int session_id
        +int action_id
        +str actor
        +str event
        +dict detail
        +datetime created_at
    }
    class RuleVersion {
        +int id
        +int scenario_config_id
        +int version
        +dict snapshot
        +int gray_pct
        +str status
        +datetime created_at
    }
    class MappingCache {
        +int id
        +str employee_id
        +str terminal_id
        +str source
        +float confidence
        +datetime updated_at
    }
    ScenarioConfig "1" --> "0..*" RuleVersion : has versions
    ScenarioConfig "1" --> "0..*" AutoSession : routes
    AutoSession "1" --> "0..*" AutoAction : produces
    AutoSession "1" --> "0..*" ActionLog : logs
    AutoAction "1" --> "0..1" ApprovalTicket : requires
    MappingCache "1" --> "0..*" AutoSession : used by

15.3.1 核心 API 端点（前缀 /itportal/automation）

方法	路径	说明	角色
POST	/sessions/start	员工提交意图，创建自动化会话	employee
GET	/sessions/{id}	会话状态/进度快照	employee/agent
POST	/sessions/{id}/takeover	转人工/接管（命中阈值或主动）	agent
GET	/actions/{id}	动作状态	employee/agent
POST	/actions/{id}/approve	坐席审批（写/高危）	agent
POST	/actions/{id}/confirm	员工二次确认（P1 高危）	employee
POST	/sessions/{id}/resolved	员工标记已解决（触发关单）	employee
GET	/configs	场景配置列表	admin(OTP)
POST	/configs	新建场景配置	admin(OTP)
PUT	/configs/{id}	修改场景配置	admin(OTP)
POST	/configs/{id}/version	版本快照/灰度发布(P1)	admin(OTP)
GET	/metrics	自动化指标（扩展阶段4看板）	admin
WS	/ws/{session_id}	实时进度推送	employee/agent

15.4 程序调用流程（Mermaid 时序图，全链路 + WS 推送）

sequenceDiagram
    participant H5 as 员工H5
    participant WS as WebSocket网关
    participant API as Automation API
    participant IR as IntentRouter(Dify+RAGFlow)
    participant MR as MappingResolver(联软/eHR)
    participant EX as Executor(执行引擎)
    participant AP as Approval(审批)
    participant PP as ProgressPublisher
    participant T2 as 阶段2工单/满意度

    H5->>API: POST /sessions/start {intent_text, employee_id}
    API->>IR: recognize(intent_text)
    IR->>IR: Dify意图识别 + RAGFlow检索
    IR-->>API: {intent, confidence, knowledge}
    API->>MR: resolve(employee_id)
    MR->>MR: 联软(主)>eHR(兜底) 映射
    MR-->>API: {terminal_id, source}
    API->>EX: plan(scenario_config, intent, mapping)
    alt 自助应答(密码重置/软件安装指引)
        EX-->>API: knowledge answer
        API->>PP: publish(progress=answered)
        PP-->>WS: automation.progress
        WS-->>H5: 展示方案
        H5->>API: POST /sessions/{id}/resolved
    else 自动处置(病毒隔离/终端定位)
        EX->>EX: 生成AutoAction + 风险分级
        alt 低风险(仅出方案/读操作)
            EX->>EX: 执行 action
            EX->>PP: publish(progress=executed)
        else 高风险(写操作/高危)
            EX->>AP: create ApprovalTicket
            AP->>PP: publish(action_required)
            alt 坐席审批
                PP-->>WS: automation.action_required
                WS-->>Agent: 通知
                Agent->>API: POST /actions/{id}/approve
            else 员工二次确认(P1)
                PP-->>WS: automation.action_required
                WS-->>H5: 弹窗
                H5->>API: POST /actions/{id}/confirm
            end
            AP->>EX: execute approved action
        end
        EX->>PP: publish(progress=result)
    end
    PP-->>WS: automation.progress / resolved
    WS-->>H5: 进度/结果
    API->>API: 关单判定(成功+已解决 或 静默10min)
    API->>T2: 复用满意度收集(阶段2)
    T2-->>H5: 满意度推送

阈值转人工（Q3）：意图置信度<0.6 / 处置超时60s / 命中高危必转 / 员工主动转 / 连续「未解决」≥2次 → exception_handler / session_manager 触发 automation.takeover 事件并落入坐席队列。

15.5 有序任务列表（依赖关系 + 实现顺序，对应 P0/P1，P2 标注后置）

任务上限 5 个、每任务≥3 文件、T01 为基础设施；T03/T04/T05 平行依赖 T02，减少线性链。

T01 项目基础设施与公共能力（无依赖，P0）

• 源文件：app/core/config.py(改)、app/core/constants.py(改)、app/core/clients/{__init__,base,huorong,lianruan,dify,ragflow,ehr}.py(新)、app/models/automation.py(新)、migrations/versions/xxxx_automation.py(新)
• 依赖：无　|　优先级：P0
• 交付：配置键、WS 事件/错误码常量、5 个外部客户端封装、7 张表模型与迁移

T02 自动化核心服务（依赖 T01，P0/P1）

• 源文件：app/schemas/automation.py(新)、app/dependencies/automation.py(新)、app/services/automation/{__init__,session_manager,intent_router,mapping_resolver,executor,action_registry,approval,progress_publisher,rollback,exception_handler}.py(新)
• 依赖：T01　|　优先级：P0（rollback/exception_handler 为 P1）
• 交付：意图路由、映射解析、双模式执行引擎、审批、进度发布、回滚补偿(P1)、异常转人工(P1)

T03 后端 API + 坐席端工作台（依赖 T02，P0）

• 源文件：app/api/automation.py(新)、app/main.py(改)、frontend-agent/src/{api/automation.js, views/automation/SessionWorkbench.vue, components/automation/ActionApprovalCard.vue, components/automation/TakeoverPanel.vue, store/automation.js}(新)
• 依赖：T02　|　优先级：P0
• 交付：REST+WS 端点、坐席审批/接管/工作台

T04 H5 员工端交互（依赖 T02，P0/P1）

• 源文件：frontend-h5/src/{api/automation.js, views/AutomationProgress.vue, components/ActionConfirmDialog.vue, components/ResolveFeedback.vue, store/automation.js}(新)
• 依赖：T02　|　优先级：P0（ActionConfirmDialog 二次确认为 P1）
• 交付：进度页、员工二次确认(P1)、已解决反馈、静默关单

T05 管理后台配置 + 指标看板（依赖 T02，P0/P1）

• 源文件：frontend-admin/src/{api/automation.js, views/automation/ScenarioConfig.vue, views/automation/RuleVersion.vue, views/dashboard/AutoMetrics.vue, store/automation.js}(新)
• 依赖：T02　|　优先级：P0（RuleVersion 灰度为 P1）
• 交付：场景开关/触发条件/动作/审批策略配置、规则版本灰度(P1)、指标看板(扩展阶段4)

P2 后置任务（本期不排期，预留接口）

• P2-01 可视化工作流编排引擎（替代结构化简易配置）
• P2-02 自学习场景优化
• P2-03 权限申请自动化
• P2-04 aTrust VPN 自动化（密钥到位后；action_registry 已留占位）

15.5.1 任务依赖图

graph TD
    T01[T01 基础设施与公共能力] --> T02[T02 自动化核心服务]
    T02 --> T03[T03 后端API+坐席端]
    T02 --> T04[T04 H5员工端交互]
    T02 --> T05[T05 管理后台配置+看板]

15.6 依赖包列表（新增）

后端 pip（若尚未引入）：

- httpx>=0.27.0        # 异步 HTTP 客户端（调外部系统）
- tenacity>=8.2.0      # 重试/退避（外部调用健壮性）
- pydantic>=2.0        # 已有，Schema 校验（确认版本一致）

HMAC 用标准库 hmac/hashlib；Redis/PostgreSQL/SQLAlchemy 阶段1-4 已具备，无需新增。

前端 npm：三端复用现有 axios + WebSocket 封装 + vant/element-plus，本期无强制新增包。

15.7 共享知识（跨文件约定）

• 统一响应：{code, msg, data}，成功 code=0；自动化错误码段 AUT-001~AUT-0xx（意图识别失败/映射缺失/执行超时/审批拒绝等）。
• WS 事件名（前缀 automation.）：automation.progress（进度）、automation.action_required（需审批/确认）、automation.resolved（已解决/关单）、automation.takeover（转人工）、automation.error。
• 配置键（前缀 AUTOMATION_）：DIFY_BASE_URL/DIFY_KEY、RAGFLOW_BASE_URL、HUORONG_*(HMAC-SHA1)、LIANRUAN_*(三层认证)、EHR_*、AUTOMATION_THRESHOLDS(置信度0.6/超时60s/未解决≥2)。
• 映射源常量：MAPPING_SOURCES = ["lianruan", "atrust", "ehr"]，优先级顺序固定。
• 表/路由命名：表前缀 auto_；API 前缀 /itportal/automation；服务类后缀 Service/函数式模块。
• 日志规范：结构化日志含 session_id/action_id/employee_id/event；所有外部调用出入参落 ActionLog（审计可追溯）。
• 风险分级：risk_level ∈ {read, low, high}；read/low 默认可自动执行，high 必走审批或员工二次确认。
• OTP 适用范围：仅 admin 配置类接口（新建/修改/版本）需 OTP 双因素；坐席审批与普通会话不需 OTP。
• 静默关单：AutoSession 成功后写 Redis TTL=600s，到期无 resolved 异议则自动关单；员工主动 resolved 立即关单。

15.8 待明确事项（仅技术层面，业务决策已确认）

1. Dify 返回结构：意图字段名与置信度字段名需联调确认（影响 IntentRouter 解析）。
2. RAGFlow 检索策略：结果分页/截断/Top-K 与引用来源展示方式。
3. 火绒写操作细节：HMAC-SHA1 构造、沙箱环境、病毒隔离接口字段与回执。
4. 联软 LV7000：三层认证具体字段、超时与并发限制。
5. AutoSession 与阶段2 工单(Ticket)关系：建议弱关联（session 可独立存在，ticket_id 可空；关单时复用阶段2满意度），需确认是否强制绑定。
6. 静默10分钟关单机制：Redis TTL + 后台任务 vs 轮询，确认后台任务调度方式（APScheduler / FastAPI BackgroundTasks / Redis 键空间通知）。
7. 规则灰度(P1)：按比例灰度还是白名单灰度，发布回滚流程。
8. 审批并发：同一 AutoAction 坐席审批与员工二次确认是否互斥、超时未处理如何降级转人工。

15.9 建议文件变更清单（落盘指引）

文档（合并进已有文件，不新建独立文档）

路径	状态	落盘建议	已有文件
docs/03-技术架构/00-系统架构设计文档-v1.3.md	修改	文末新增「阶段5 自动化闭环」章节（即本章）	是

后端

路径	状态	落盘建议	已有文件
app/core/config.py	修改	追加自动化配置键	是
app/core/constants.py	修改	追加 WS 事件/错误码常量	是
app/core/clients/{__init__,base,huorong,lianruan,dify,ragflow,ehr}.py	新增	整组新建	否
app/models/automation.py	新增	整文件新建	否
migrations/versions/xxxx_automation.py	新增	Alembic 生成并落地	否
app/schemas/automation.py	新增	整文件新建	否
app/dependencies/automation.py	新增	整文件新建	否
app/services/automation/*.py（10个）	新增	整组新建	否
app/api/automation.py	新增	整文件新建	否
app/main.py	修改	注册 router/WS	是

前端 H5

路径	状态	落盘建议	已有文件
frontend-h5/src/api/automation.js	新增	新建	否
frontend-h5/src/views/AutomationProgress.vue	新增	新建	否
frontend-h5/src/components/ActionConfirmDialog.vue	新增	新建	否
frontend-h5/src/components/ResolveFeedback.vue	新增	新建	否
frontend-h5/src/store/automation.js	新增	新建	否

前端 坐席端

路径	状态	落盘建议	已有文件
frontend-agent/src/api/automation.js	新增	新建	否
frontend-agent/src/views/automation/SessionWorkbench.vue	新增	新建	否
frontend-agent/src/components/automation/ActionApprovalCard.vue	新增	新建	否
frontend-agent/src/components/automation/TakeoverPanel.vue	新增	新建	否
frontend-agent/src/store/automation.js	新增	新建	否

前端 管理后台

路径	状态	落盘建议	已有文件
frontend-admin/src/api/automation.js	新增	新建	否
frontend-admin/src/views/automation/ScenarioConfig.vue	新增	新建	否
frontend-admin/src/views/automation/RuleVersion.vue	新增	新建	否
frontend-admin/src/views/dashboard/AutoMetrics.vue	新增	新建（扩展阶段4看板）	否
frontend-admin/src/store/automation.js	新增	新建	否

汇总：文档 1 处合并修改（本章）；代码新增约 35 个文件（后端 21 + 三前端 14），修改 4 个已有文件（config/constants/main + 设计文档）。代码文件按此清单在后续实现阶段落地。

---

附录

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