Simon
1003 lines
44 KiB
Markdown
1003 lines
44 KiB
Markdown
# IT智能服务台 — 系统架构设计文档
|
||
|
||
> **文档版本**: v1.5
|
||
> **创建日期**: 2025-07-11
|
||
> **最近更新**: 2026-07-04
|
||
> **架构师**: 高见远 (Bob)
|
||
> **状态**: 正式版
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
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设计规范)
|
||
|
||
---
|
||
|
||
## 1. 技术文档索引
|
||
|
||
本文档为技术架构主文档，相关详细设计文档如下：
|
||
|
||
| 文档 | 说明 | 状态 |
|
||
|------|------|------|
|
||
| **本文档** | 系统架构总览 v1.3 | ✅ 正式 |
|
||
| **01-ADRs-架构决策/** | 4项架构决策 | ✅ 已完成 |
|
||
| **02-技术方案/** | 具体功能技术方案 | |
|
||
| ├── [技术方案-消息功能详细设计.md](./02-技术方案/技术方案-消息功能详细设计.md) | 消息功能详细设计 | ✅ 已实现 |
|
||
| ├── [技术方案-摇人协作.md](./02-技术方案/技术方案-摇人协作.md) | 多坐席协作方案 | ✅ 已实现 |
|
||
| ├── [技术方案-邀请功能.md](./02-技术方案/技术方案-邀请功能.md) | 邀请功能方案 | ✅ 已实现 |
|
||
| ├── [技术方案-复杂场景重构.md](./02-技术方案/技术方案-复杂场景重构.md) | 复杂对话场景技术方案 | ✅ 设计完成 |
|
||
| └── [技术方案-ExternalSystemAdapter抽象层.md](./02-技术方案/技术方案-ExternalSystemAdapter抽象层.md) | 外部系统适配层设计 | ✅ 设计完成 |
|
||
| **03-技术分析/** | 技术研究分析 | |
|
||
| ├── [技术分析-H5右侧栏动态推送评估.md](./03-技术分析/技术分析-H5右侧栏动态推送评估.md) | H5右侧栏动态推送评估 | ✅ 已完成 |
|
||
| └── [技术分析-架构消息知识库迭代.md](./03-技术分析/技术分析-架构消息知识库迭代.md) | 架构消息知识库迭代 | ✅ 已完成 |
|
||
| **04-数据库设计/** | 数据库设计 | |
|
||
| └── [数据库设计-ER图与环境变量清点.md](./04-数据库设计/数据库设计-ER图与环境变量清点.md) | 数据库ER图与环境变量 | ✅ 已完成 |
|
||
| **05-架构图/** | Mermaid图表 | |
|
||
| └── [架构图集](./05-架构图/) | 各类时序图/类图 | ✅ 已完成 |
|
||
| [D-T19-知识图谱数据模型设计.md](../02-产品需求/小组任务书/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](./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 数据库设计
|
||
|
||
```sql
|
||
-- 扩展 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](../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 响应格式
|
||
|
||
```json
|
||
// 成功
|
||
{"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 类图）
|
||
|
||
```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 推送）
|
||
|
||
```mermaid
|
||
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 任务依赖图
|
||
|
||
```mermaid
|
||
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 智能服务台系统架构设计主文档
|