Simon
44e77dcb0e
**重构前**（旧编号 02-11）： - docs/02-产品需求/ → 00 产品规划/PRD - docs/03-技术架构/ → 01-05 子目录散落 - docs/04-原型设计/ → 01-02 产品设计（HTML 原型） - docs/05-原型设计/ → screens/ - docs/06-测试素材/ → 02-E2E / 03-功能 / 04-版本测试 - docs/07-项目管理/ → 任务说明书/日报/计划 - docs/08-安全审计/ → 审计报告 - docs/09-堡垒运维/ → toolbox / deploy - docs/10-项目管理/ → 任务说明书（重复） - docs/11-历史归档/ → deploy-nas-archived **重构后**（新编号 00-07，语义化）： - docs/00-产品开发流程与文档管理规范.md - docs/00-版本迭代总览.md - docs/01-产品文档/ （PRD/原型/认证/会话/AI 服务/坐席/集成） - docs/02-技术文档/ （技术方案/架构图/重构记录/前端改造/实现配置） - docs/03-测试文档/ （E2E/功能用例/版本报告/缺陷单） - docs/04-运维文档/ （部署运维/运维指南） - docs/05-运营文档/ （品牌推广/用户手册） - docs/06-安全审计/ （审计报告） - docs/07-项目管理/ （任务说明书/日报/计划/看板） **净收益**： - 目录编号与产品文档管理规范对齐（按文档阶段 01-07 编号） - 消除 02-产品需求 与 10-项目管理 的编号重叠 - 子目录按文档类型分组（如 01-产品文档/00-产品规划、01-产品文档/01-认证与登录） - 把运维/安全/项目管理从 0X 散落改为 04/06/07 合计 494 文件 + 78495 行 / - 14076 行
659 lines
26 KiB
Markdown
659 lines
26 KiB
Markdown
# IT智能服务台 — 系统架构设计文档
|
||
|
||
> **文档版本**: v1.0
|
||
> **创建日期**: 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. [API设计规范](#13-api设计规范)
|
||
|
||
---
|
||
|
||
## 1. 技术文档索引
|
||
|
||
本文档为技术架构主文档，相关详细设计文档如下：
|
||
|
||
| 文档 | 说明 | 状态 |
|
||
|------|------|------|
|
||
| [IT智能服务台-技术架构设计.md](./IT智能服务台-技术架构设计.md) | 本文档 — 系统架构总览 | ✅ 正式 |
|
||
| [统一入口技术设计文档.md](./统一入口技术设计文档.md) | Portal 统一入口详细设计 | ✅ 实施中 |
|
||
| [ExternalSystemAdapter设计文档.md](./ExternalSystemAdapter设计文档.md) | 外部系统适配层设计 | ✅ 设计完成 |
|
||
| [Wingman设计.md](./Wingman设计.md) | AI 僚机系统设计 | ✅ 设计阶段 |
|
||
| [重构方案-复杂场景技术方案.md](./重构方案-复杂场景技术方案.md) | 复杂对话场景技术方案 | ✅ 设计完成 |
|
||
| [消息功能详细方案.md](./消息功能详细方案.md) | 消息功能详细设计 | ✅ 已实现 |
|
||
| [摇人-多坐席协作-技术方案.md](./摇人-多坐席协作-技术方案.md) | 多坐席协作方案 | ✅ 已实现 |
|
||
| [邀请功能-技术方案.md](./邀请功能-技术方案.md) | 邀请功能方案 | ✅ 已实现 |
|
||
|
||
---
|
||
|
||
## 2. 系统概述
|
||
|
||
### 2.1 项目背景
|
||
|
||
IT智能服务台是为企业提供 IT support 的智能化服务平台，核心目标：
|
||
|
||
- **员工侧**：通过 H5 页面提交 IT 问题、AI 自助解答、人工坐席服务
|
||
- **坐席侧**：通过自研工作台处理会话、AI 辅助（ Wingman ）、知识推荐
|
||
- **管理侧**：通过管理后台配置系统、管理坐席、查看数据
|
||
|
||
### 2.2 核心能力
|
||
|
||
| 能力 | 说明 |
|
||
|------|------|
|
||
| 消息路由 | AI 与人工无缝切换 |
|
||
| 实时会话 | 坐席工作台实时消息 |
|
||
| AI 辅助 | Wingman 草稿/摘要/知识推荐 |
|
||
| 外部集成 | 联软/火绒/aTrust/eHR 终端数据 |
|
||
| 角色管理 | 统一入口 + RBAC 权限 |
|
||
|
||
---
|
||
|
||
## 3. 整体架构
|
||
|
||
### 3.1 系统架构图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ Linux 服务器 Docker │
|
||
│ │
|
||
│ ┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
|
||
│ │ Nginx │ │ Frontend │ │ Frontend │ │ Frontend │ │
|
||
│ │ (反代) │──│ Agent │ │ H5 User │ │ Portal │ │
|
||
│ │ :80/:443│ │ (Vue3+EP) │ │ (Vue3+Vant4)│ │ (Vue3) │ │
|
||
│ └────┬─────┘ └──────────────┘ └──────────────┘ └────────────┘ │
|
||
│ │ :5173 :5174 :5176 │
|
||
│ ▼ │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
|
||
│ │ FastAPI │ │ Redis │ │PostgreSQL│ │ Dify AI │ │
|
||
│ │ Backend │──│ (缓存/Session)│──│ (持久化) │──│ (外部依赖) │ │
|
||
│ │ :8000 │ │ :6379 │ │ :5432 │ │ │ │
|
||
│ └────┬─────┘ └──────────┘ └──────────┘ └──────────────┘ │
|
||
│ │ │
|
||
└───────┼──────────────────────────────────────────────────────────────────┘
|
||
│ HTTPS
|
||
▼
|
||
┌───────────────┐
|
||
│ 企微服务器 │
|
||
│ (消息回调API) │
|
||
└───────────────┘
|
||
```
|
||
|
||
### 3.2 前端架构
|
||
|
||
| 端 | 路径 | 技术栈 | 端口 |
|
||
|----|------|--------|------|
|
||
| Portal | /itportal/ | Vue3 + Element Plus | 5176 |
|
||
| 坐席端 | /itagent/ | Vue3 + Element Plus | 5173 |
|
||
| H5用户端 | /itdesk/ | Vue3 + Vant 4 | 5174 |
|
||
| 管理后台 | /itadmin/ | Vue3 + Element Plus + Tailwind | 5175 |
|
||
|
||
### 3.3 后端架构
|
||
|
||
```
|
||
backend/
|
||
├── app/
|
||
│ ├── api/ # API 路由
|
||
│ │ ├── admin.py # 管理后台 API
|
||
│ │ ├── agents.py # 坐席 API
|
||
│ │ ├── h5.py # H5 用户端 API
|
||
│ │ ├── portal.py # 统一入口 API
|
||
│ │ └── wecom.py # 企微回调 API
|
||
│ ├── models/ # 数据模型
|
||
│ ├── schemas/ # Pydantic Schema
|
||
│ ├── services/ # 业务逻辑
|
||
│ │ ├── wingman.py # AI 僚机服务
|
||
│ │ ├── external/ # 外部系统适配器
|
||
│ │ └── message_router.py # 消息路由
|
||
│ └── config.py # 配置管理
|
||
├── alembic/ # 数据库迁移
|
||
└── requirements.txt
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 技术选型
|
||
|
||
### 4.1 核心技术栈
|
||
|
||
| 层级 | 技术 | 版本 | 说明 |
|
||
|------|------|------|------|
|
||
| 前端框架 | Vue 3 | ^3.4.0 | Composition API |
|
||
| 前端路由 | Vue Router | ^4.3.0 | SPA 路由 |
|
||
| 状态管理 | Pinia | ^2.1.0 | 轻量级状态管理 |
|
||
| UI 组件 | Element Plus | ^2.7.0 | 坐席端/Portal |
|
||
| UI 组件 | Vant 4 | ^4.0 | H5 移动端 |
|
||
| 样式 | Tailwind CSS | ^3.4.0 | 管理后台 |
|
||
| 构建工具 | Vite | ^5.3.0 | 快速构建 |
|
||
| 后端框架 | FastAPI | 0.110+ | 异步高性能 |
|
||
| ORM | SQLAlchemy | 2.0+ | async ORM |
|
||
| 数据库 | PostgreSQL | 16 | 主数据存储 |
|
||
| 缓存 | Redis | 7 | Session/Token/缓存 |
|
||
| AI 引擎 | Dify | — | 外部依赖 |
|
||
|
||
### 4.2 关键技术挑战与解决方案
|
||
|
||
| # | 挑战 | 解决方案 |
|
||
|---|------|---------|
|
||
| 1 | 企微消息加解密 | 使用 `cryptography` 库实现 AES-CBC-256 加解密 |
|
||
| 2 | access_token 管理 | Redis 缓存 + 过期自动刷新（提前 300 秒刷新） |
|
||
| 3 | 坐席端实时性 | 短轮询（3-5 秒）+ WebSocket 推送 |
|
||
| 4 | 消息路由 | 路由层统一分发，AI/人工无缝切换 |
|
||
| 5 | OAuth2 静默授权 | 企微 OAuth2 授权 + 后端换算用户身份 |
|
||
|
||
---
|
||
|
||
## 5. 部署架构
|
||
|
||
### 5.1 部署拓扑
|
||
|
||
```
|
||
┌────────────────────────────┐
|
||
│ 企微服务器（外部） │
|
||
│ qyapi.weixin.qq.com │
|
||
└──────────┬─────────────────┘
|
||
│ HTTPS :443
|
||
▼
|
||
┌──────────────── 办公网络 ────────────────────────────────┐
|
||
│ │
|
||
│ ┌──────────┐ ┌──────────────────────────┐ │
|
||
│ │ 坐席浏览器 │────────▶│ https://itsupport. │ │
|
||
│ │ (内网) │ HTTPS │ servyou.com.cn │ │
|
||
│ └──────────┘ └──────────┬───────────────┘ │
|
||
│ │ │
|
||
├────────────────── OA 服务器网络 ──┼───────────────────────┤
|
||
│ │ │
|
||
│ ┌───────▼──────────────┐ │
|
||
│ │ 服务器 (Docker) │ │
|
||
│ │ │ │
|
||
│ │ ┌────────────────┐ │ │
|
||
│ │ │ Nginx :80/443 │ │ │
|
||
│ │ │ 独立容器 │ │ │
|
||
│ │ └───────┬────────┘ │ │
|
||
│ │ │ │ │
|
||
│ │ ┌───────▼────────┐ │ │
|
||
│ │ │ FastAPI :8000 │ │ │
|
||
│ │ │ 独立容器 │ │ │
|
||
│ │ └───┬───────┬────┘ │ │
|
||
│ │ │ │ │ │
|
||
│ │ ┌───▼──┐ ┌──▼───┐ │ │
|
||
│ │ │ PG16 │ │Redis7│ │ │
|
||
│ │ │独立容器│ │独立容器│ │ │
|
||
│ │ └──────┘ └──────┘ │ │
|
||
│ └──────────────────────┘ │
|
||
│ │ │
|
||
│ ┌────────▼──────────────┐ │
|
||
│ │ 现有 AI 服务（外部依赖）│ │
|
||
│ │ ├─ Dify │ │
|
||
│ │ ├─ RAGFlow │ │
|
||
│ │ └─ Qwen3-30B │ │
|
||
│ └───────────────────────┘ │
|
||
└──────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 5.2 Docker 容器拓扑
|
||
|
||
```
|
||
新服务器 Docker Engine
|
||
│
|
||
├── Docker Network: itdesk_net (bridge, internal)
|
||
│ │
|
||
│ ├── Container: wecom_it_postgres
|
||
│ │ Image: postgres:16-alpine
|
||
│ │ Volume: wecom_it_postgres_data
|
||
│ │ Port: 5432 (仅 itdesk_net 内部)
|
||
│ │
|
||
│ ├── Container: wecom_it_redis
|
||
│ │ Image: redis:7-alpine
|
||
│ │ Volume: wecom_it_redis_data
|
||
│ │ Port: 6379 (仅 itdesk_net 内部)
|
||
│ │
|
||
│ ├── Container: wecom_it_backend
|
||
│ │ Image: wecom-it-desk-backend:latest
|
||
│ │ Port: 8000 (仅 itdesk_net 内部)
|
||
│ │ Env: DATABASE_URL, REDIS_URL, WECOM_*
|
||
│ │ Healthcheck: GET /health
|
||
│ │
|
||
│ └── Container: wecom_it_nginx
|
||
│ Image: nginx:1.27-alpine
|
||
│ Port: 80:80, 443:443 (宿主机映射)
|
||
│ Volumes: nginx.conf:ro, 前端dist:ro, SSL:ro
|
||
│ Healthcheck: GET /health
|
||
│
|
||
└── Volumes (命名卷，持久化)
|
||
├── wecom_it_postgres_data
|
||
└── wecom_it_redis_data
|
||
```
|
||
|
||
### 5.3 关键隔离策略
|
||
|
||
| 隔离层面 | 方案 | 隔离效果 |
|
||
|---------|------|---------|
|
||
| 服务器级 | 独立 VM | 挂了不影响其他系统 |
|
||
| 网络级 | Docker 内部网络 | PG/Redis 不暴露端口 |
|
||
| 存储级 | 独立命名卷 | 数据完全隔离 |
|
||
| 域名级 | 独立子域名 | 变更不影响其他系统 |
|
||
| 认证级 | JWT + 独立 Redis | 账户体系独立 |
|
||
|
||
---
|
||
|
||
## 6. 统一入口设计
|
||
|
||
### 6.1 概述
|
||
|
||
统一入口（Portal）是系统的唯一认证入口，所有用户必须通过企微工作台进入系统。
|
||
|
||
**核心功能**：
|
||
- 企微 OAuth2 静默授权
|
||
- 角色检测与路由选择
|
||
- 统一 Token 管理
|
||
|
||
### 6.2 角色路由逻辑
|
||
|
||
```
|
||
OAuth2 授权完成
|
||
│
|
||
▼
|
||
查询角色列表: GET /api/portal/roles
|
||
│
|
||
├── 仅 user 角色 → 直接跳转 /itdesk/
|
||
├── user + agent → 显示选择页（2张卡片）
|
||
├── user + admin → 显示选择页（2张卡片）
|
||
└── user + agent + admin → 显示选择页（3张卡片）
|
||
```
|
||
|
||
### 6.3 URL 路径规划
|
||
|
||
| 端 | 路径 | 说明 |
|
||
|---|------|------|
|
||
| 统一入口 | /itportal/ | 路由选择页 |
|
||
| 用户端 | /itdesk/ | 员工提交工单 |
|
||
| 坐席端 | /itagent/ | IT坐席处理会话 |
|
||
| 管理端 | /itadmin/ | 系统配置 |
|
||
| API | /api/ | 后端接口 |
|
||
|
||
### 6.4 数据库设计
|
||
|
||
#### 角色表 (roles)
|
||
|
||
```sql
|
||
CREATE TABLE roles (
|
||
id SERIAL PRIMARY KEY,
|
||
name VARCHAR(50) NOT NULL UNIQUE, -- 角色标识: user/agent/admin
|
||
display_name VARCHAR(100) NOT NULL, -- 显示名称
|
||
description TEXT, -- 角色描述
|
||
permissions JSONB DEFAULT '[]', -- 权限列表
|
||
is_default BOOLEAN DEFAULT FALSE, -- 是否默认角色
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
```
|
||
|
||
#### 用户角色关联表 (user_roles)
|
||
|
||
```sql
|
||
CREATE TABLE user_roles (
|
||
id SERIAL PRIMARY KEY,
|
||
employee_id VARCHAR(100) NOT NULL, -- 企微 UserID
|
||
role_id INTEGER NOT NULL REFERENCES roles(id),
|
||
source VARCHAR(50) NOT NULL, -- 来源: auto/tag/ehr/manual
|
||
assigned_by VARCHAR(100), -- 分配者
|
||
assigned_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
expires_at TIMESTAMP, -- 过期时间
|
||
UNIQUE(employee_id, role_id)
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 模块架构
|
||
|
||
### 7.1 管理后台模块
|
||
|
||
详见 [ARCHITECTURE-admin.md](./ARCHITECTURE-admin.md)
|
||
|
||
**技术栈**：Vue 3 + TypeScript + Element Plus + Tailwind CSS + Pinia
|
||
|
||
**核心功能**：
|
||
- 运营仪表盘
|
||
- 功能开关配置
|
||
- 坐席管理（角色/技能标签）
|
||
- 外部系统集成配置
|
||
- 快速回复审核
|
||
- 会话监控
|
||
|
||
### 7.2 坐席工作台模块
|
||
|
||
**技术栈**：Vue 3 + TypeScript + Element Plus + Pinia
|
||
|
||
**核心功能**：
|
||
- 会话列表（排队/进行中/已解决）
|
||
- 实时聊天
|
||
- 快速回复
|
||
- AI Wingman 右侧栏
|
||
- 消息标记（VIP/招手/情绪）
|
||
|
||
### 7.3 H5 用户端模块
|
||
|
||
**技术栈**：Vue 3 + Vant 4 + TypeScript
|
||
|
||
**核心功能**：
|
||
- 消息发送/接收
|
||
- 排查步骤引导
|
||
- 会话状态查看
|
||
- 满意度评价
|
||
|
||
---
|
||
|
||
## 8. AI Wingman 设计
|
||
|
||
详见 [Wingman设计.md](./Wingman设计.md)
|
||
|
||
### 8.1 什么是 Wingman
|
||
|
||
Wingman 是坐席工作台的 AI 辅助系统，在坐席处理会话时实时提供：
|
||
|
||
- **草稿回复**：坐席打字 → AI 实时生成 3 条草稿
|
||
- **自动摘要**：会话结束 → AI 200 字摘要
|
||
- **知识推荐**：对话中识别关键字 → 推 FAQ
|
||
- **排查步骤**：员工描述问题 → AI 给 step-by-step
|
||
|
||
### 8.2 系统架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ FastAPI 后端 │
|
||
│ ┌──────────────────────────────────────────────┐ │
|
||
│ │ WingmanService (wingman.py) │ │
|
||
│ │ ├── draft_reply() 草稿回复 │ │
|
||
│ │ ├── summarize() 自动摘要 │ │
|
||
│ │ ├── recommend_knowledge() 知识推荐 │ │
|
||
│ │ └── troubleshoot() 排查步骤 │ │
|
||
│ └────────────────┬─────────────────────────────┘ │
|
||
│ │ │
|
||
│ ┌────────────────▼─────────────────────────────┐ │
|
||
│ │ DifyClient (dify_client.py) │ │
|
||
│ └──────────────────────────────────────────────┘ │
|
||
└────────────────────┬────────────────────────────────────┘
|
||
│ HTTPS
|
||
▼
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Dify 平台 │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ 工作流 A │ │ 工作流 B │ │ 工作流 C │ │
|
||
│ │ 草稿回复 │ │ 摘要生成 │ │ 排查步骤 │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 8.3 数据模型
|
||
|
||
```python
|
||
class WingmanDraft(Base):
|
||
"""草稿回复"""
|
||
__tablename__ = "wingman_drafts"
|
||
conv_id = Column(String, ForeignKey("conversations.id"))
|
||
agent_id = Column(String, ForeignKey("agents.id"))
|
||
drafts = Column(JSON) # ["draft1", "draft2", "draft3"]
|
||
context_messages = Column(JSON) # 最近 10 条消息
|
||
accepted_index = Column(Integer, nullable=True)
|
||
expires_at = Column(DateTime) # 5 分钟后过期
|
||
|
||
class WingmanSummary(Base):
|
||
"""会话摘要"""
|
||
__tablename__ = "wingman_summaries"
|
||
conv_id = Column(String, unique=True)
|
||
summary = Column(String(2000)) # AI 生成
|
||
edited_summary = Column(String(2000)) # 坐席修改
|
||
final_summary = Column(String(2000)) # 最终版本
|
||
agent_id = Column(String)
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 外部系统集成
|
||
|
||
详见 [ExternalSystemAdapter设计文档.md](./ExternalSystemAdapter设计文档.md)
|
||
|
||
### 9.1 系统角色与优先级
|
||
|
||
| 系统 | 角色 | 核心能力 | 认证方式 |
|
||
|------|------|---------|---------|
|
||
| 联软LV7000 | 主映射源(P0) | 终端查询、硬件详情、在线状态 | IP白名单+账号密码 |
|
||
| 火绒企业版 | 安全源(P0) | 终端列表、漏洞/病毒事件 | HMAC-SHA1 AccessKey |
|
||
| aTrust | VPN源(P1) | 在线用户+VPN IP、终端查询 | HMAC-SHA256签名 |
|
||
| 北森eHR | 辅助静态数据(P2) | 员工基础信息、任职信息 | OAuth2.0 |
|
||
|
||
### 9.2 架构分层
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 上层业务代码（AI Wingman等） │
|
||
├─────────────────────────────────────────────────┤
|
||
│ ExternalSystemService（统一门面） │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ 缓存层 │ │ 降级策略 │ │ 配置管理 │ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ │
|
||
├─────────────────────────────────────────────────┤
|
||
│ ExternalSystemAdapter（抽象基类） │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────┐│
|
||
│ │ LianRuan │ │ HuoRong │ │ aTrust │ │eHR ││
|
||
│ │ Adapter │ │ Adapter │ │ Adapter │ │适配││
|
||
│ └──────────┘ └──────────┘ └──────────┘ └────┘│
|
||
├─────────────────────────────────────────────────┤
|
||
│ MockAdapter（开发期） │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 9.3 核心抽象接口
|
||
|
||
```python
|
||
class ExternalSystemAdapter(ABC):
|
||
@property
|
||
@abstractmethod
|
||
def system_name(self) -> str: ...
|
||
|
||
@property
|
||
@abstractmethod
|
||
def is_available(self) -> bool: ...
|
||
|
||
@abstractmethod
|
||
async def health_check(self) -> bool: ...
|
||
|
||
async def get_terminal_by_user(self, username: str) -> Optional[TerminalInfo]: ...
|
||
|
||
async def get_security_status(self, terminal_id: str) -> Optional[SecurityStatus]: ...
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 安全设计
|
||
|
||
### 10.1 认证安全
|
||
|
||
| 安全措施 | 说明 |
|
||
|----------|------|
|
||
| OAuth2 静默授权 | scope=snsapi_base，用户无感知 |
|
||
| state 参数防 CSRF | 随机 state，回调时验证 |
|
||
| Token 密码学安全 | secrets.token_urlsafe(32) |
|
||
| Token TTL 8小时 | Redis 自动过期 |
|
||
| redirect_uri 白名单 | 生产环境仅允许正式域名 |
|
||
| 企微 UA 检测 | 非企微 WebView 拒绝访问 |
|
||
|
||
### 10.2 角色安全
|
||
|
||
| 安全措施 | 说明 |
|
||
|----------|------|
|
||
| 角色最小权限 | 默认仅 user 角色 |
|
||
| 角色来源追溯 | user_roles 表记录 source 和 assigned_by |
|
||
| 管理端 IP 白名单 | 仅内网/VPN 可访问 |
|
||
| OTP 二次验证 | 管理后台访问需 OTP 验证 |
|
||
|
||
### 10.3 API 安全
|
||
|
||
| 安全措施 | 说明 |
|
||
|----------|------|
|
||
| API Key 认证 | 外部系统独立认证通道 |
|
||
| 速率限制 | slowapi 中间件 |
|
||
| CORS 配置 | 限制允许的来源 |
|
||
|
||
---
|
||
|
||
## 11. 复杂对话场景设计
|
||
|
||
详见 [重构方案-复杂场景技术方案.md](./重构方案-复杂场景技术方案.md)
|
||
|
||
### 11.1 设计理念：TeliChat 三重约束
|
||
|
||
| 约束 | 作用 | 实现方式 |
|
||
|------|------|---------|
|
||
| 拓扑结构限制 | 限制对话可以走到哪里 | Neo4j DAG 边定义 |
|
||
| 信息状态约束 | 决定当前已经知道什么 | 信息项组合状态 |
|
||
| Python 代码约束 | 负责真正的业务判断 | FastAPI 业务逻辑 |
|
||
|
||
### 11.2 信息项修饰机制
|
||
|
||
| 修饰 | 含义 | 应用场景 |
|
||
|------|------|---------|
|
||
| 固定 | 用户回答后不再重复询问 | 已通过系统获取的信息 |
|
||
| 增量 | 允许用户补充新信息 | 故障描述、错误信息 |
|
||
| 明确 | 必须明确回答 | 紧急程度确认 |
|
||
| 隐含 | 可以从上下文推断 | AI 推断的问题类型 |
|
||
| 复述 | 要求用户确认信息正确性 | 重要操作确认 |
|
||
| 必需 | 必须填写才能进入下一节点 | 必填字段 |
|
||
|
||
### 11.3 全局意图类型
|
||
|
||
| 意图 | 用户表达示例 | 处理策略 |
|
||
|------|-------------|---------|
|
||
| SKIP | "这个问题先不管了" | 跳过当前节点 |
|
||
| INSERT | "对了，我的打印机也有问题" | 插入新任务到队列 |
|
||
| RESUME | "还是说回刚才那个网络问题" | 恢复之前话题 |
|
||
| SWITCH | "先帮我看看VPN吧" | 切换到指定话题 |
|
||
| CORRECT | "刚才说错了，是win10" | 更新信息项值 |
|
||
| PAUSE | "我先去开会，等会继续" | 保存状态，等待恢复 |
|
||
| ESCALATE | "叫个人工来" | 转接坐席 |
|
||
|
||
### 11.4 核心场景
|
||
|
||
| 场景 | 支持状态 |
|
||
|------|---------|
|
||
| 非线性跳转 | ✅ 支持 |
|
||
| 多意图并行 | ✅ 支持 |
|
||
| 信息更正 | ✅ 支持 |
|
||
| 任务中断恢复 | ✅ 支持 |
|
||
|
||
---
|
||
|
||
## 12. 数据库设计
|
||
|
||
### 12.1 核心表结构
|
||
|
||
| 表名 | 说明 |
|
||
|------|------|
|
||
| agents | 坐席信息 |
|
||
| conversations | 会话表 |
|
||
| messages | 消息表 |
|
||
| quick_reply_templates | 快速回复模板 |
|
||
| system_configs | 系统配置 |
|
||
| roles | 角色表 |
|
||
| user_roles | 用户角色关联 |
|
||
| role_mapping_rules | 角色映射规则 |
|
||
|
||
### 12.2 Alembic 迁移
|
||
|
||
所有数据库迁移位于 `backend/alembic/versions/` 目录，按序号执行：
|
||
|
||
```
|
||
alembic/
|
||
├── env.py # 迁移环境配置
|
||
├── script.py.mako
|
||
└── versions/
|
||
├── 001_initial.py # 初始表结构
|
||
├── 002_agents.py # 坐席扩展
|
||
├── 003_conversations.py
|
||
├── 004_messages.py
|
||
├── 005_system_configs.py
|
||
└── ... # 后续迁移
|
||
```
|
||
|
||
---
|
||
|
||
## 13. API 设计规范
|
||
|
||
### 13.1 响应格式
|
||
|
||
```json
|
||
// 成功
|
||
{"code": 0, "data": {...}, "message": "success"}
|
||
|
||
// 失败
|
||
{"code": 1001, "data": null, "message": "参数错误"}
|
||
```
|
||
|
||
### 13.2 错误码规范
|
||
|
||
| 错误码 | 含义 |
|
||
|--------|------|
|
||
| 0 | 成功 |
|
||
| 1001 | 参数错误 |
|
||
| 1002 | 未授权 |
|
||
| 1003 | 资源不存在 |
|
||
| 1004 | 无权限访问 |
|
||
| 1005 | 服务器内部错误 |
|
||
|
||
### 13.3 认证方式
|
||
|
||
| 端 | localStorage 键 | 说明 |
|
||
|----|-----------------|------|
|
||
| 坐席端 | `agent_token` | 坐席工作台 |
|
||
| 管理后台 | `admin_token` | 管理后台 |
|
||
| 统一入口 | `user_token` | Portal |
|
||
|
||
---
|
||
|
||
## 附录
|
||
|
||
### A. 项目阶段规划
|
||
|
||
| 阶段 | 内容 |
|
||
|------|------|
|
||
| 阶段一 | 转人工改H5+坐席MVP+邀请+管理后台 |
|
||
| 阶段二 | H5全流程+WS+排队+满意度+OAuth2 |
|
||
| 阶段三 | AI Wingman+排查流程图+标注 |
|
||
| 阶段四 | 迭代闭环+数据看板+知识库 |
|
||
| 阶段五 | 自动/辅助审核、开单、结单 |
|
||
|
||
### B. 部署信息
|
||
|
||
| 环境 | 域名 | IP |
|
||
|------|------|-----|
|
||
| 生产 | itsupport.servyou.com.cn | 10.90.5.110 |
|
||
| 测试 | itdesk.amanzac.com | NAS |
|
||
|
||
### C. 技术文档更新日志
|
||
|
||
| 版本 | 日期 | 修改内容 |
|
||
|------|------|---------|
|
||
| v1.0 | 2026-07-04 | 整合技术架构文档，统一入口、部署、AI Wingman、外部系统集成等模块 |
|
||
|
||
---
|
||
|
||
> **文档结束** — 本文档为 IT 智能服务台系统架构设计主文档
|