Simon
facc04aa65
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交 （5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。 一、docs 结构整改（整改 #14） 根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入， 随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录 树并存于 docs/，共 791 文件、双分类体系冲突。 修复动作： - b2 同名异主题文件改名迁移保全 9 个 - C 类 39 个孤立文件按主题正确归类 - A/B1 类 222 个重复文件删除（新结构已有内容副本） - 9 个旧独有空目录删除 - 270 处内部引用按 verified 映射改写 - 整改记录 #14 登记于 04-运维文档/部署运维 结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。 残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。 二、compose 双目录对齐（消除踩坑 A） - docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist 改为 src/frontend-*/dist（h5 / agent / admin / terminal） - docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/ - 效果：本地 docker compose up 不再把根目录 stale dist 挂回， 与线上一致，分叉隐患消除（已 docker compose config 校验通过） 防复发铁律： - 重构须提交；仓库修复须 git stash -u 或先 commit - 新结构须 git add 并提交，避免再次 untracked 复活 - H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
1230 lines
55 KiB
Markdown
1230 lines
55 KiB
Markdown
# IT智能服务台 — 系统架构设计文档
|
||
|
||
> **文档版本**: v2.2 (综合版)
|
||
> **创建日期**: 2025-07-11
|
||
> **最近更新**: 2026-07-17
|
||
> **架构师**: 高见远 (Bob) / 宋献 (Simon)
|
||
> **状态**: 正式版
|
||
>
|
||
> **v2.2 变更**: 新增 §15.8 坐席端AI辅助消息框与布局优化；更新 §7.2 坐席工作台模块布局参数；更新 §8 AI Wingman 设计新增能力；新增 §15.4.9 ITSM 工单跳转交互与鉴权限制（桥接页 + 扫码登录定为人机校验）
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
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设计规范)
|
||
15. [技术方案详解](#15-技术方案详解)
|
||
16. [技术分析报告](#16-技术分析报告)
|
||
17. [阶段5 自动化闭环](#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/04-运维文档/部署运维/卷挂载重构方案.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 响应格式
|
||
|
||
```json
|
||
// 成功
|
||
{"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 数据模型
|
||
|
||
```python
|
||
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 消息模型扩展
|
||
|
||
```python
|
||
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`
|
||
|
||
**数据结构**：
|
||
|
||
```typescript
|
||
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）下
|
||
|
||
> **⚠️ 限制（2026-07-17）**：上述结论仅适用于**同一企微 corpid 下、且目标应用已实现 `snsapi_base` 静默授权回调**的场景。Web ITSM（`devops.dc.servyou-it.com`）为独立 Web 应用，**不满足**该前提，其工单深链冷访问必弹扫码，详见 §15.4.9。
|
||
|
||
#### 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.4.9 ITSM 工单跳转交互与鉴权限制（2026-07-17 更新）
|
||
|
||
> **关联 PRD**: `01-产品文档/00-产品规划/PRD-REQ-通用-001-前端设计系统-v1.2.md` §v2.3
|
||
|
||
**背景**：运维平台（ITSM）审批卡片需从 H5 跳转至 Web 工单创建表单。需求为「一步直达 + 免登录」，实测暴露 ITSM 鉴权模型约束。
|
||
|
||
**已部署方案：桥接页（Bridge Page）**
|
||
|
||
```
|
||
H5 卡片 option.url
|
||
└─> https://itsupport.servyou.com.cn/h5/itsm-bridge.html?name=<URL编码服务名>
|
||
├─ 隐藏 iframe 加载 ITSM 移动端首页（尝试静默 OAuth 预热会话）
|
||
└─ setTimeout 2500ms → window.top.location.href =
|
||
'http://devops.dc.servyou-it.com/ITSM/workflow/service/createTicket?name=<服务名>'
|
||
```
|
||
|
||
**桥接页文件**：`frontend-h5/public/itsm-bridge.html`（静态资源，随 H5 `dist` 部署，经 nginx 托管于 `/h5/itsm-bridge.html`）。
|
||
|
||
**跳转目标映射（8 个运维平台模板）**：
|
||
|
||
| 后端模板 ID | 工单服务名 | 桥接页 name 参数 |
|
||
|------------|-----------|------------------|
|
||
| `it_device_repair` | IT设备升级与硬件维修 | `IT设备升级与硬件维修` |
|
||
| `asset_upgrade` | IT资产升级 | `IT资产升级` |
|
||
| `zero_trust_vpn` | 员工零信任（原VPN）账号申请 | `员工零信任（原VPN）账号申请` |
|
||
| `software_service` | 商业软件服务申请 | `商业软件服务申请` |
|
||
| `network_access` | 终端设备网络准入申请 | `终端设备网络准入申请` |
|
||
| `event_support` | 活动与会议技术支持 | `活动与会议技术支持` |
|
||
| `it_support_repair` | 员工IT支持与故障报修 | `员工IT支持与故障报修` |
|
||
| `public_email` | 公共邮箱账号申请 | `公共邮箱账号申请` |
|
||
|
||
**技术限制（关键，已实证）**：
|
||
|
||
| # | 限制 | 影响 | 证据 |
|
||
|---|------|------|------|
|
||
| L1 | Web ITSM 无静默 OAuth | `devops.dc.servyou-it.com/ITSM/...` 深链只认已建立的服务端会话；冷访问（无会话）→ 302 跳转扫码登录页 | 企微内实测弹扫码 |
|
||
| L2 | 移动端 SPA 无深链能力 | `itsm.servyou.com.cn` 为 SPA，未配置 SPA fallback，深链子路由（含 `createTicket/:name`）直接 404，仅首页可免登录 | curl 验证 `/itsm-miniapp-mobile/` → 200，其余 → 404 |
|
||
| L3 | 跨域 iframe 预热被拒 | 桥接页（`itsm-bridge.html`，我方域名）内 iframe 加载移动端首页，ITSM 在跨域上下文拒绝静默 OAuth 预热，桥接 trick 失效 → 跳转 Web 深链仍为冷 hit → 弹扫码 | 企微内实测仍弹扫码 |
|
||
| L4 | 明文 HTTP 混合内容 | 深链为 `http://`（非 HTTPS），个别企微版本对 HTTPS 页内嵌 HTTP 混合内容有限制 | 设计层面风险，未实测触发 |
|
||
|
||
**结论**：在现有 ITSM 鉴权模型下，「一步直达」与「免登录」不可兼得。产品侧决策**保留扫码登录**，将其视为**人机校验（Human-Machine Verification）**环节——企业安全合规可接受的二次身份确认，不视为功能缺陷。
|
||
|
||
**不受影响（2 个企微审批类）**：`asset_receive` / `asset_borrow` 属企微审批流程，走企微审批应用 API（`app.work.weixin.qq.com`），非 ITSM，不经由本桥接页。
|
||
|
||
### 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模型
|
||
|
||
```python
|
||
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/02-技术文档/01-架构设计/坐席端AI辅助消息框与布局优化-架构设计.md`
|
||
> **关联PRD**: `01-产品文档/04-坐席工作台/PRD-REQ-坐席-002-AI辅助消息框-v1.0.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/02-技术文档/01-架构设计/坐席端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) |
|
||
| v2.3 | 2026-07-17 | ITSM 工单跳转交互优化：新增 §15.4.9 桥接页交互与鉴权限制（L1~L4），修正 §15.4.7 免登录适用边界 |
|
||
|
||
---
|
||
|
||
> **文档结束** — 本文档为 IT 智能服务台系统架构设计综合主文档
|