wecom_it_smart_desk/docs/03-技术架构/IT智能服务台-系统架构设计文档v2.md

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

文档版本: v2.2 (综合版) 创建日期: 2025-07-11 最近更新: 2026-07-11 架构师: 高见远 (Bob) / 宋献 (Simon) 状态: 正式版

v2.2 变更: 新增 §15.8 坐席端AI辅助消息框与布局优化；更新 §7.2 坐席工作台模块布局参数；更新 §8 AI Wingman 设计新增能力

---

目录

1. 技术文档索引
2. 系统概述
3. 整体架构
4. 技术选型
5. 部署架构
6. 统一入口设计
7. 模块架构
8. AI Wingman 设计
9. 外部系统集成
10. 安全设计
11. 复杂对话场景设计
12. 知识图谱数据模型设计
13. 数据库设计
14. API设计规范
15. 技术方案详解
16. 技术分析报告
17. 阶段5 自动化闭环

---

1. 技术文档索引

本文档为技术架构主文档（综合版），整合了所有技术方案和技术分析文档。

章节	内容	状态
15. 技术方案详解
15.1	认证模块重构	✅ 已实现
15.2	消息功能详细设计	✅ 已实现
15.3	群聊邀请和协助	✅ 已实现
15.4	企微审批工单同步	✅ 设计完成
15.5	复杂场景重构	✅ 设计完成
15.6	ExternalSystemAdapter抽象层	✅ 设计完成
15.7	Wingman设计	✅ 已实现
15.8	坐席端AI辅助消息框与布局优化	✅ 设计完成
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推荐 + 快速回复，统一入口）
• AI Wingman 右侧栏（训练区：智能标注/质量反馈/知识贡献/使用统计）
• AI 辅助消息框（自动补齐/语气调整/文字润色/智能改写）
• 右栏放大/缩小模式切换
• 消息标记（VIP/招手/情绪）

布局参数（v2.1 更新）：

左栏: 260px (会话用户列表 + 待办面板)
中栏: flex:1 (UserInfoBar + TroubleshootBar + 消息列表 + 回复建议区 + ReplyBox)
右栏: 260px(正常) / 560px(放大) (AI训练区 + 模式切换)

详见 §15.8 坐席端AI辅助消息框与布局优化

7.3 H5 用户端模块

技术栈：Vue 3 + Vant 4 + TypeScript

核心功能：

• 消息发送/接收
• 排查步骤引导
• 会话状态查看
• 满意度评价

---

8. AI Wingman 设计

详见第15.7节「Wingman设计」和第15.8节「坐席端AI辅助消息框与布局优化」

Wingman 是坐席工作台的 AI 辅助系统：

现有能力（已实现）：

• 草稿回复：坐席打字 → AI 实时生成草稿
• 自动摘要：会话结束 → AI 结构化摘要
• 标签建议：对话内容 → AI 建议分类标签
• 知识库优化建议：对话分析 → 知识库改进建议

新增能力（设计完成，见 §15.8）：

• 实时自动补齐：输入停顿 > 0.8s → 幽灵文字 → Tab 接受
• 语气调整：选中文字 → 专业/友好/简洁 → 一键改写
• 文字润色：扩写/压缩/纠错 → 精修面板 → 确认替换
• 智能改写：对话上下文 + 知识库 → 3 个备选版本

布局重构（设计完成，见 §15.8）：

• 回复前功能（草稿/知识/推荐/快回）统一到中栏回复建议区
• 回复后功能（标注/反馈/贡献/统计）归右栏 AI 训练区
• 右栏支持放大/缩小模式切换（260px ↔ 560px）

---

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 响应格式

// 成功
{"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 数据模型

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 消息模型扩展

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

数据结构：

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模型

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                │
└─────────────────────────────────────────┘

---

15.8 坐席端AI辅助消息框与布局优化

新增日期: 2026-07-11 (v2.1) | 架构师: 宋献 (Simon)
关联文档: docs/03-技术架构/坐席端AI辅助消息框与布局优化-架构设计.md
关联PRD: docs/02-产品需求/坐席端AI辅助消息框-PRD.md + docs/02-产品需求/坐席端布局优化建议.md

15.8.1 功能概述

在现有 Wingman 基础上新增 4 项 AI 辅助功能 + 坐席端布局全面重构：

AI 辅助消息框（4 项新增功能）：

功能	交互方式	后端方法	temperature
实时自动补齐	内联幽灵文字，Tab 接受，debounce 800ms	generate_completion()	0.2
语气调整	选中文字 → 专业/友好/简洁 → 原文/改写对比	adjust_tone()	0.3
文字润色	点润色按钮 → 扩写/压缩/纠错 → 精修面板	polish_text()	0.3
智能改写	点改写按钮 → 3 个备选版本 → 替换/追加	rewrite_versions()	0.6

布局重构：

改动区域	变化
左栏	280px → 260px（会话用户列表）
中栏	+80px 宽度；新增回复建议区；UserInfoBar/TroubleshootBar 默认折叠
右栏	320px → 260px(正常)/560px(放大)；改为 AI 训练区；支持模式切换
工具栏	单行左右分区：常规工具(左) + AI工具(右)

15.8.2 后端架构

WingmanService 扩展（backend/app/services/wingman_service.py）：

WingmanService
  ├── 现有方法（保持不变）
  │   ├── generate_draft()         temp=0.3
  │   ├── generate_summary()       temp=0.3
  │   ├── suggest_tags()           temp=0.3
  │   └── generate_knowledge_suggestion()
  │
  ├── 新增方法
  │   ├── generate_completion()    temp=0.2  ← 自动补齐
  │   ├── adjust_tone()            temp=0.3  ← 语气调整
  │   ├── polish_text()            temp=0.3  ← 文字润色
  │   └── rewrite_versions()       temp=0.6  ← 智能改写
  │
  └── 改造方法
      └── _call_wingman_api(context, temperature=0.3)  ← 新增可选参数

关键改造：_call_wingman_api() 新增 temperature 参数（默认 0.3 保持兼容），各方法按需传递不同值。

API 端点（backend/app/api/wingman.py）：

端点	方法	说明
/api/conversations/{id}/wingman/autocomplete	POST	自动补齐
/api/conversations/{id}/wingman/tone-adjust	POST	语气调整
/api/conversations/{id}/wingman/polish	POST	文字润色
/api/conversations/{id}/wingman/rewrite	POST	智能改写

新增 Pydantic 请求模型（backend/app/schemas/wingman_assist.py）：AutocompleteRequest、ToneAdjustRequest、PolishRequest、RewriteRequest，含字段验证和枚举类型。

15.8.3 前端架构

新增组件树：

Workspace.vue
  ├── ConversationList.vue (左栏 - 会话用户列表)
  ├── ChatArea.vue (中栏)
  │   ├── UserInfoBar.vue (详情默认折叠)
  │   ├── TroubleshootBar.vue (默认折叠为图标条)
  │   ├── MessageList.vue
  │   ├── ReplySuggestArea.vue (新增 - 回复建议区)
  │   │   ├── AiRecommendBar.vue (合并自 AiRecommendInline + AiSuggestReply)
  │   │   └── QuickReplyBar.vue (改造自 QuickReplyPanel)
  │   └── ReplyBox.vue (改造)
  │       ├── GhostTextOverlay.vue (新增 - 幽灵文字)
  │       ├── ToneAdjustPopover.vue (新增 - 语气浮层)
  │       ├── PolishPanel.vue (新增 - 润色面板)
  │       └── RewritePanel.vue (新增 - 改写面板)
  └── AiAssistantPanel.vue (全面重构)
      ├── PanelModeToggle.vue (新增 - 正常/放大切换)
      └── AiTrainingPanel.vue (新增 - 训练区)
          ├── SmartTagEditor.vue (智能标注)
          ├── QualityFeedback.vue (质量反馈)
          ├── KnowledgeContribute.vue (知识贡献)
          └── UsageStats.vue (使用统计)

新增 Composable：

Composable	职责
useAutoComplete.ts	debounce 800ms + AbortController + ghost text 管理
useAiTextTools.ts	语气/润色/改写统一调用和结果管理
usePanelMode.ts	右栏 260px ↔ 560px 模式切换

功能重复清理（5 处）：

编号	重复类型	清理方案
R1	AI草稿双展示	统一到中栏回复建议区
R2	AI推荐回复三处展示	合并为 AiRecommendBar.vue
R3	排查流程命名混淆	右栏按钮重命名为"智能标注"
R4	标签建议双入口	合并为单一"智能标注"功能
R5	孤儿组件	删除 AiRecommendInline.vue

15.8.4 关键设计决策

决策	选择	理由
补齐交互	textarea + mirror div + ghost overlay	保持现有快捷键和粘贴功能不变
补齐 API	HTTP + AbortController	轻量请求，与现有 Wingman 调用一致
语气/润色浮层	el-popover / el-drawer	不遮挡消息列表，不打断工作流
右栏模式切换	CSS 变量 + class 切换	组件不销毁，状态不丢失
回复建议区动画	max-height transition	平滑过渡，组件实例保持存活
temperature 改造	可选参数默认 0.3	现有方法无需修改，向后兼容

15.8.5 开发计划

阶段	内容	预估
Phase 1	后端 WingmanService 扩展 + Pydantic 模型	1.5 天
Phase 2	前端 API 层 + Composable	1 天
Phase 3	ReplyBox 工具栏 + AI 辅助组件	2 天
Phase 4	布局重构 + 回复建议区	2 天
Phase 5	右栏训练区 + 模式切换	1.5 天
Phase 6	功能清理 + 联调测试	1 天
合计		9 天

完整架构设计（类图、时序图、API 规范、Dify prompt 模板、TypeScript 类型定义）详见独立文档：docs/03-技术架构/坐席端AI辅助消息框与布局优化-架构设计.md

---

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