simon/wecom_it_smart_desk

Fork 0

Files

T

Simon 63262292d7 chore: initial baseline with P0-safety .gitignore

2026-06-14 16:51:56 +08:00

33 KiB

Raw Blame History

企微IT智能服务台 — 项目总览与部署手册

版本: v2.1 | 日期: 2026-06-03 | 编制: 宋献（IT支持组组长） 目标读者: 管理者 / 架构师 / 运维 — 了解项目全貌、架构决策、部署与运维操作

一、项目概述

1.1 背景与痛点

公司约 6000 人，全国设分子机构，使用企业微信作为内部 IM。当前 IT 服务存在三大痛点：

痛点	现状	影响
员工绕过 AI 直接找人工	可通过关键词直通人工坐席，首次后永久记忆	AI 筛选率极低，人工成本高
AI 转人工需另开窗口	跳转到企微"员工服务"模块，与 AI 对话割裂	体验差，员工困惑
无法跨主体共享	企微"员工服务"不支持互联企业应用共享	跨企业服务不可达

1.2 核心方案

自研 IT 服务坐席系统，替代企微内置的"员工服务"模块：

基于企微自建应用消息 API，所有消息由自己的服务器接管
分三步渐进式构建：M1 消息接管 → M2 AI 接入 → M3 知识库闭环
当前处于 M1（消息接管 + 极简坐席）开发完成，部署配置中

1.3 核心设计理念

传统"串行排队"改为**"并行协作"**——AI 全程在线，人工随时介入：

角色	工作方式
AI	全程在线，所有对话可见
坐席	随时介入，AI 始终在旁辅助
员工	同一窗口，AI 和人工无缝切换

二、系统架构

2.1 部署架构总览（预生产环境）

当前阶段：预生产环境。智能咨询系统与 IT 数据查询平台分别部署在不同主机，通过 Nginx 路径路由共用域名 it-dataquery.dc.servyou-it.com。正式环境将迁移到 K8s 集群。

浏览器 ──→ it-dataquery.dc.servyou-it.com:80
                  │
                  ▼
         ┌─── nginx (本系统主机) ───────────────┐
         │                                      │
         │  /itdesk/*  → H5 员工端 SPA         │
         │  /itagent/* → 坐席工作台 SPA        │
         │  /api/*     → backend:8000 (FastAPI) │
         │  /ws/*      → backend:8000 (WS)      │
         │  /*         → 数据平台主机（远程IP）  │  ← 跨主机代理
         │                                      │
         └──────────────┬───────────────────────┘
                        │ 本机 Docker 网络
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
    ┌──────────┐ ┌──────────┐ ┌──────────┐
    │ backend  │ │ postgres │ │  redis   │
    │ :8000    │ │ :5432    │ │ :6379    │
    └──────────┘ └──────────┘ └──────────┘

对比项	预生产（当前）	正式环境（未来）
部署方式	Docker Compose（单主机）	K8s 集群（高可用）
与数据平台关系	不同主机，Nginx 远程代理	独立 K8s 集群
域名	共用 `it-dataquery.dc.servyou-it.com`	独立域名或 K8s Ingress

2.2 技术栈

层级	技术选型	说明
反向代理	Nginx	统一入口、路径路由、WebSocket 代理
后端框架	FastAPI (Python 3.12)	异步、自动 OpenAPI 文档、类型安全
数据库	PostgreSQL 16	会话/消息/坐席/配置持久化（9 张表）
缓存	Redis 7	access_token 缓存（TTL 7200s）、JWT 会话
ORM	SQLAlchemy 2.0 (async)	异步 session、声明式模型
数据库迁移	Alembic	所有表结构变更通过迁移脚本管理
坐席前端	Vue3 + ElementPlus + Pinia	企业级组件库，三栏工作台
员工 H5	Vue3 + Vant4 + Pinia	移动端组件库，企微 WebView 兼容
容器化	Docker + Docker Compose	4 容器一键启停

2.3 数据库核心表（9 张）

表名	用途	关键字段
`conversations`	会话主表	employee_id, status, urgency_score(1-5), tags(JSON), is_vip, participants(JSON)
`messages`	消息记录	sender_type(employee/agent/ai/system), content, msg_type
`agents`	坐席信息	user_id, status(online/offline/busy), current_load
`quick_reply_templates`	快速回复模板	category, title, content(支持 {变量})
`system_configs`	系统配置	config_key, config_value（关键词/阈值/话术等）
`funny_phrases`	趣味话术	scene(6 种场景), content, tone, is_active
`approval_links`	审批流程链接	category(IT/HR/行政/财务), title, url
`software_downloads`	软件下载入口	category, name, version, platform, download_url
`agent_notes`	坐席备注	conversation_id, agent_id, content

2.4 API 接口分组

分组	路径前缀	核心接口
企微回调	`/api/wecom/callback`	GET 验证 URL、POST 接收消息
会话管理	`/api/conversations`	列表/详情/状态/置顶/代办/接单/邀请/退出/移除参与者
消息管理	`/api/conversations/{id}/messages`	消息列表/发送
坐席管理	`/api/agents`	列表/登录/状态切换
H5 用户端	`/api/h5/*`	会话/摇人/审批链接/软件下载/OAuth
WebSocket	`/ws/{agent_id}`	实时推送（坐席端）

统一响应格式：{ "code": 0, "data": {}, "message": "success" }

2.5 消息收发全链路

员工发消息 → 企微回调解密 → 消息路由 → 评分标记 → 入库 → 坐席 WS 推送 → 坐席回复 → 企微主动推送 → 员工同一窗口收到

坐席端通信：已升级为 WebSocket 实时推送（2026-06-03），替代原计划的短轮询：

心跳保活：前端每 30s 发 ping，后端回 pong
断线重连：指数退避（1s→2s→4s→...→30s 上限）
降级策略：WS 断连时自动降级为 3s 轮询

2.6 会话排序与评分规则

排序: 紧急 → 举手 → 需介入 → 活跃 → AI处理中 → 已结单（同级按时间倒序）

紧急度评分: 基础分(关键词) + 情绪加成 + VIP加成 + 重复追问加成，范围 1-5

标记系统:

标记	图标	触发条件
VIP	红色	企微通讯录规则匹配
举手	黄色	员工说关键词或点击摇人按钮
需介入	橙红	同一问题追问 >3 轮
情绪	红色	关键词匹配（急/崩溃/投诉等）

三、三步演进路径

里程碑	周期	核心交付	状态
M1 消息接管 + 极简坐席	6-8 周	企微 API 链路验证 · 坐席三栏工作台 · 员工 H5 双栏 · 邀请功能（多人会话协作）	✅ 代码完成，部署中
M2 AI 机器人接入	M1 后 4-6 周	千问/Dify/RAGFlow 接入 · AI 前置筛选 · 排队系统	📋 计划中
M3 知识库闭环迭代	M2 后 4-6 周	坐席标注系统 · 千问自动分析 · 知识库自优化	📋 计划中

M1 当前进度（2026-06-03）

模块	状态
PRD + 架构设计	✅ 完成
后端代码（45+ 文件，7 API 组）	✅ 完成
坐席前端（三栏工作台 + WebSocket）	✅ 完成
员工 H5（双栏 + 摇人按钮 + 呼叫坐席）	✅ 完成
邀请功能（多人会话协作 — PRD §21）	📋 计划中（M1 范围）
前端功能联调验证	✅ 完成（2026-06-03）
测试用例（116 条 pytest）	✅ 完成
Alembic 数据库迁移	✅ 完成
前端构建产物（dist/）	✅ 完成
远程服务器部署	🔧 待 SSH 账号

M2 核心改动

只改路由层逻辑，其余不动：

M1: 新会话 → 坐席队列
M2: 新会话 → AI 先回答 → AI判断/用户触发 → 坐席队列

新增：千问对话模型、RAGFlow 知识库检索、Dify 编排平台、排队系统。目标：AI 首答率 ≥ 80%。

M3 知识库迭代闭环

坐席日常标注 ──→ 千问分析 ──→ 自动处理 ──→ 知识库增强
(正确/错误)      (缺文档/过时)                    │
      ↑                                           │
      └──────────── 持续循环 ─────────────────────┘

四、现有系统复用评估

4.1 核心复用（直接影响新系统架构）

#	资源	复用方式	新系统对应
1	Dify Workflow	直接复用，M2 阶段接入 AI 回复	坐席助手 AI 面板 + 自动回复
2	dify2openai 桥接	直接复用 API	后端调用 AI 的入口
3	RAGFlow 知识库	直接复用，M3 阶段混合标注迭代	知识库管理 + 标注闭环
4	Qwen3-30B 大模型	直接复用	AI 对话底层模型
5	bge-m3 向量模型	RAGFlow 内置，直接复用	知识库检索向量化
6	Dify 数据库（只读）	读取 messages 表，同步历史数据	历史会话数据迁移 + 统计
7	企微自建应用	直接复用应用凭证	消息收发的企微入口

4.2 基础设施复用（零耦合）

资源	复用方式	耦合度
企微自建应用凭证	配置文件引用（只读）	零耦合
Dify Workflow API	HTTP 调用	外部依赖
RAGFlow 知识库	HTTP 调用	外部依赖
Qwen3-30B 大模型	HTTP 调用	外部依赖
SSL 证书文件	Nginx 挂载只读	零耦合

4.3 关键结论

代码层面复用率约 15%（主要是业务逻辑和 SQL 查询），基础设施和 AI 能力复用率约 70%。新系统用 FastAPI + SQLAlchemy 2.0，不沿用旧 Django 代码。底层业务逻辑可参考移植。

五、正式环境部署方案

5.1 核心决策原则

基于四个约束条件：

#	约束	推导原则
1	对现有正式环境架构影响最小	物理隔离 > 逻辑隔离
2	避免变更影响现有服务	独立 Nginx 入口
3	减少服务依赖	最小化外部依赖
4	避免责任不清	独立数据库 + 独立 Redis

一句话：新系统作为独立服务单元部署，与现有智能 IT 数据平台（Django）在物理资源层面完全解耦，仅通过 HTTP API 调用共享 AI 能力。

5.2 关键隔离策略

隔离层面	方案	效果
服务器级	独立 VM，不共用宿主机	挂了不影响旧系统
网络级	Docker 内部网络，PG/Redis 不暴露宿主机端口	外部无法直连数据库
存储级	独立命名卷，不共用 Volume	数据完全隔离
域名级	路径路由（共用域名） + 独立 Nginx 容器	`/itdesk/`、`/itagent/`、`/api/` 归属本系统
认证级	JWT + 独立 Redis	账户体系独立
依赖级	仅 HTTP 调用外部 AI 服务	外部服务故障只影响 M2 功能

5.3 与现有系统的解耦修正

原复用评估中的部分共享方案已修正为独立部署：

原建议	修正方案	理由
同机部署于 10.80.0.86	独立服务器/VM（或同机端口分离+独立 compose）	避免端口冲突、资源争抢
Redis 复用同实例	独立 Redis 容器	FLUSHDB 误操作、内存 OOM 互相影响
使用旧系统 Nginx	独立 Nginx 容器	变更反代配置不影响旧系统路由
复用旧 PG 实例	独立 PostgreSQL 容器	数据库是责任边界核心

5.4 Docker Compose 服务清单

服务	镜像	端口	健康检查
postgres	postgres:16	5432（内部）	pg_isready
redis	redis:7	6379（内部）	redis-cli ping
backend	自构建 Dockerfile	8000（内部）	GET /health
nginx	nginx:alpine	18080:80（对外）	GET /health

Docker 网络：it-desk-internal（内部，连接 backend/postgres/redis）

5.5 资源需求

资源	配置	说明
服务器	4C8G + 100GB SSD（最低）/ 8C16G + 200GB SSD（推荐）	Docker Engine 环境
域名	`it-dataquery.dc.servyou-it.com`（已就绪，共用）	路径路由 `/itdesk/` `/itagent/` `/api/`
企微自建应用	1 个（已创建）	CorpID/AgentID/Secret/Token/EncodingAESKey
防火墙	办公网→服务器:80/443, 企微→服务器:443	出站: 企微 API/ Dify/ RAGFlow/ Qwen

5.6 风险矩阵

风险	概率	影响	缓解措施
新服务器申请被拒/延迟	中	部署延期	退化方案：旧服务器端口分离+独立 compose
SSL 证书到期	低	HTTPS 不可用	复用现有通配符证书
企微应用配置变更	低	双系统消息中断	建立变更通知机制
Dify/RAGFlow 不可用	中	M2 AI 功能不可用	降级：纯坐席模式仍正常工作
Docker 宿主机故障	低	新系统全宕	Compose 配置即代码，重建快

六、部署操作手册

预生产部署：本系统与数据平台部署在不同主机，通过 Nginx 路径路由共用域名。数据平台请求通过远程 IP 反代（非 Docker 网络）。正式环境将迁移到 K8s。

6.1 前置条件

服务器已安装 Docker Engine 24+ + Docker Compose v2
IT 数据查询平台已部署运行
有 SSH 登录权限

6.2 配置数据平台反代地址

预生产环境中，数据平台部署在独立主机。部署前需修改 nginx/nginx.conf 中的数据平台上游地址：

# nginx/nginx.conf  — 将 DATAQUERY_HOST 替换为数据平台主机的实际 IP
upstream dataquery {
    server 10.80.0.86:80;   # ← 替换为数据平台实际 IP:端口
}

为什么不创建 Docker 共享网络？ 预生产两台主机不在同一 Docker Engine，无法使用 docker network create 互联。正式环境迁移 K8s 后由 Ingress/Service 处理路由。

6.3 上传部署包

在本地（Windows）执行打包上传：

# 方式 A：使用 deploy.sh 打包
bash scripts/deploy.sh --pack
scp it-smart-desk-*.tar.gz user@server:/opt/

# 方式 B：手动打包
tar czf deploy.tar.gz \
  backend/ frontend-h5/dist/ frontend-agent/dist/ \
  nginx/ docker-compose.yml .env.production scripts/
scp deploy.tar.gz user@server:/opt/it-smart-desk/

6.4 服务器配置与启动

ssh user@server
cd /opt/it-smart-desk
tar xzf it-smart-desk-*.tar.gz

# 创建环境配置
cp .env.production .env
vim .env    # 填入真实企微凭证

.env 必填项：

配置项	说明	获取位置
`WECOM_CORP_ID`	企业 ID	企微管理后台 > 我的企业
`WECOM_AGENT_ID`	应用 AgentId	企微管理后台 > 应用管理
`WECOM_SECRET`	应用 Secret	企微管理后台 > 应用管理
`WECOM_TOKEN`	回调 Token	企微管理后台 > 接收消息
`WECOM_ENCODING_AES_KEY`	回调 AES 密钥	企微管理后台 > 接收消息
`POSTGRES_PASSWORD`	数据库密码	自定义强密码
`CORS_ORIGINS`	`http://it-dataquery.dc.servyou-it.com`	CORS 白名单

启动：

bash scripts/deploy.sh
# 自动执行：检查前置条件 → 构建后端镜像 → 启动所有容器 → 运行数据库迁移

6.5 验证部署

# 检查容器状态
docker compose ps
# 预期：4 个容器全部 Up/healthy

# 健康检查
curl http://localhost:18080/api/health

# 浏览器验证
# http://it-dataquery.dc.servyou-it.com/itdesk/   → H5 员工咨询页面
# http://it-dataquery.dc.servyou-it.com/itagent/  → 坐席工作台登录页
# http://it-dataquery.dc.servyou-it.com/          → IT 数据查询平台（不变）
# http://it-dataquery.dc.servyou-it.com/api/docs  → FastAPI Swagger 文档

6.6 常见问题

nginx 启动失败，报 host not found in upstream "dataquery" → nginx/nginx.conf 中 DATAQUERY_HOST 未替换为数据平台的实际 IP。确保已在部署前完成替换。

nginx 启动但数据平台页面 502 → 本系统主机无法访问数据平台主机 IP。检查防火墙策略是否放行两台主机间的 80 端口。

访问 /itdesk/ 返回 404 → 检查前端 dist 是否正确挂载：docker exec wecom_it_nginx ls -la /usr/share/nginx/html/itdesk/

API 返回 CORS 错误 → 检查 .env 中 CORS_ORIGINS 是否包含 http://it-dataquery.dc.servyou-it.com

数据库迁移失败 → PostgreSQL 可能未就绪，等 30 秒后执行：docker compose restart backend

6.7 更新部署

# 仅更新前端
bash scripts/deploy.sh --build
docker compose restart nginx

# 仅更新后端
docker compose build backend
docker compose up -d backend

# 全量更新
bash scripts/deploy.sh --down
bash scripts/deploy.sh

6.8 回滚

docker compose down    # 停止新系统所有容器
# 旧系统不受任何影响（独立资源）

七、运维管理

7.1 责任矩阵

运维操作	影响范围	备注
重启 PostgreSQL	仅新系统	独立实例
重启 Redis	仅新系统	独立实例
修改 Nginx 配置	仅新系统路由	独立容器
更新后端/前端代码	仅新系统	独立容器
企微应用配置变更	双系统	⚠️ 唯一共享点，需通知双方

7.2 监控指标

主机层面:
  - CPU 使用率 < 80%
  - 内存使用率 < 80%
  - 磁盘使用率 < 70%

容器层面:
  - docker compose ps 全部 "Up" 状态
  - Nginx 健康检查: GET /health → 200
  - Backend 健康检查: GET /health → 200

业务层面（后续接入）:
  - 企微消息回调成功率 > 99%
  - API 响应时间 P95 < 500ms

7.3 备份策略

备份对象	方法	频率	保留
PostgreSQL 数据	`pg_dump` + 卷快照	每日凌晨	7 天
Redis 数据	`SAVE` + 复制 dump.rdb	每日凌晨	7 天
Docker 卷	`tar czf` 归档	每周	4 周

7.4 关键对接参数（M2 阶段）

参数	值	用途
dify2openai API	`http://yw-dify.dc.servyou-it.com/dify2openai/v1/chat/completions`	AI 对话
RAGFlow	`http://10.80.0.85:8080`	知识库管理
Qwen3-30B	`http://10.80.0.49:5000/api/llm/servyou/v1/chat/completions`	大模型
Dify DB（生产只读）	`10.80.128.40:5432` DB=dify User=difyro	历史数据同步
数据平台	`http://it-dataquery.dc.servyou-it.com` (10.80.0.86)	部署服务器

7.5 应急预案可选技术项

评估日期: 2026-06-03 | 来源: 企微原生1对1方案（PRD §3.2 方式五）可行性评估

7.5.1 备用方案概述

当 H5 WebView 方案（当前主方案）出现以下情况时，可切换至企微原生1对1方案作为降级/备用：

应急场景	当前方案症状	备用方案动作
H5 前端服务不可用	Nginx 静态文件丢失/构建产物损坏	员工直接在企微与应用1对1聊天，走 `/message/send` 回复
H5 页面性能问题	WebView 加载慢/白屏/兼容性问题	放弃 H5 入口，改用企微原生聊天窗口交互
OAuth2 鉴权异常	静默授权失败，H5 无法获取员工身份	原生方案无需 OAuth2，回调自带 UserID
跨平台接入需求	需接入钉钉/飞书/浏览器用户	不适合切换——原生方案无法跨平台，此时应修复 H5
外部专家协作	坐席需要拉入第三方专家协助	启用 `/appchat/create` 创建临时群聊

7.5.2 备用方案技术架构

┌─────────────────────────────────────────────────────┐
│              员工端（企微原生1对1聊天窗口）               │
│                                                       │
│  员工 ←─消息─→ 自建应用（IT智能助手）                    │
│                  │                                    │
│                  ├─ AI回复 → /message/send → 同一窗口   │
│                  ├─ 坐席回复 → /message/send → 同一窗口 │
│                  └─ 外援 → /appchat/create → 新群聊窗口 │
│                                                       │
│  坐席工作台（保留，不变）                                 │
│  ├─ WebSocket 接收员工消息                              │
│  ├─ 坐席回复 → 后端 → /message/send → 员工窗口           │
│  └─ 外援指令 → 后端 → /appchat/create → 新群聊           │
│                                                       │
└─────────────────────────────────────────────────────┘

核心能力：项目已经具备备用方案所需的全部后端代码：

wecom_callback.py：接收企微回调 ✅
message_router._try_ai_reply() → wecom_service.send_text_message()：AI回复走 /message/send ✅
scoring_service.detect_hand_raise()：关键词举手检测 ✅
wecom_service.send_text_message()：应用消息推送 ✅

仅需新增：

交互卡片消息发送（msgtype="template_card"）— 用于"转人工"按钮、满意度评分
AppChat API 封装（/cgi-bin/appchat/*）— 用于外援群聊场景
AI/人工身份区分前缀（如 🤖 AI回复： / 👨‍💻 人工坐席（张三）：）

7.5.3 切换流程

从 H5 方案切换到原生1对1方案：

步骤	操作	负责人	预计耗时
1	确认企微回调 URL 已配置且可达（H5 方案已配置则无需改动）	运维	0 min
2	确认 `message_router._try_ai_reply()` 走 `/message/send`（已实现）	开发	0 min
3	通知员工：直接在企微与应用聊天即可，不再进入 H5	运维	5 min
4	（可选）关闭 H5 入口：Nginx 配置注释 `/itdesk/` 路由	运维	2 min
5	（可选）启用交互卡片：部署 template_card 消息发送代码	开发	1-2 天

关键点：步骤1-3 零代码改动即可完成基本切换，因为核心回调+消息推送链路已在运行。

从原生1对1方案切回 H5 方案：

步骤	操作	负责人
1	恢复 Nginx `/itdesk/` 路由（如已注释）	运维
2	确认 H5 构建产物存在且可访问	运维
3	通知员工：点击应用 → 进入 H5 咨询页面	运维

7.5.4 企微 API 限制与容量评估

API	限制	当前业务量（月均 188 次 AI 会话/天）	风险
`/message/send`	≤账号上限×200人次/天，同一人≤30次/分	预估 < 500 人次/天	✅ 充裕
`/appchat/create`	≤1000群/天	外援场景低频（预估 < 10群/天）	✅ 充裕
`/appchat/send`	≤2万人次/分，同一人≤200条/分	群内消息量极小	✅ 充裕
回调消息	无硬限制	企微服务器推送到回调 URL	✅ 无风险

7.5.5 备用方案局限性与适用边界

局限	说明	影响
无法跨主体企微	企微原生1对1仅限同一企微主体内员工	无法服务供应商/外包人员
无法跨平台	原生方案绑定企微，无法嵌入钉钉/飞书/浏览器	H5 扩展场景不可用
AI/人工区分不直观	都以应用身份推送，需内容前缀区分	体验不如 H5 的丰富身份标识
交互卡片需开发	"转人工"按钮、满意度评分需 template_card 消息类型	降级期可用关键词替代（"转人工"）
群聊外援需审批	appchat API 要求可见范围=根部门	需企微管理员配合

决策建议：当 H5 不可用且影响范围仅限企微主体内员工时，立即切换原生1对1方案（零代码改动）；当需要跨平台/跨主体服务时，优先修复 H5，不切换原生方案。

八、开发交付状态

TL;DR

企微IT智能服务台第一步（消息接管 + 极简坐席台）全部代码已完成并通过测试，共 110+ 文件，116/116 测试全部通过，覆盖后端 API、坐席工作台、用户端 H5 三个子系统。

交付状态

阶段	状态	产出
PRD	✅ 完成	`PRD.md` — 31 需求（P0/P1/P2），7 用户故事
架构设计	✅ 完成	`docs/ARCHITECTURE.md` — 9 表 DDL，7 API 组，4 时序图，5 任务分解
T01 项目脚手架	✅ 完成	57 文件 — docker-compose, nginx, .env, 后端/前端骨架
T02 后端核心服务	✅ 完成	16 文件 — 企微加解密, 消息路由, 评分, 会话, 趣味话术, 7 API 路由
T03 坐席工作台	✅ 完成	25 文件 — 三栏布局, 会话管理, 聊天, AI助手面板(5Tab)
T04 用户端H5	✅ 完成	12 文件 — 聊天面板, 摇人按钮, AI助手, 审批链接, 软件下载
QA 测试用例	✅ 完成	8 文件, 116 测试用例（原 93 + 新增 23）
Bug 修复	✅ 完成	7 个 Bug 修复（详见下方）
PostgreSQL/SQLite兼容	✅ 完成	9 个模型文件全部兼容 SQLite
database.py 懒加载	✅ 完成	避免测试导入时连接 PostgreSQL
WecomCrypto 懒加载	✅ 完成	避免默认 AES Key 导入报错
pytest 全量验证	✅ 116/116 通过	1.71 秒完成，0 失败

关键文件

wecom_it_smart_desk/
├── README.md                 # 项目主文档（GitHub 首页）
├── docker-compose.yml       # Docker Compose 容器编排
├── .env                      # 环境变量（数据库密码等，不提交 Git）
├── backend/                  # FastAPI 后端服务
│   ├── app/
│   │   ├── main.py              # FastAPI 应用入口
│   │   ├── config.py             # 配置管理（从 .env 读取）
│   │   ├── database.py           # 懒加载数据库引擎
│   │   ├── models/               # 11 个 ORM 模型（兼容 PostgreSQL/SQLite）
│   │   ├── schemas/              # Pydantic Schema（请求/响应校验）
│   │   ├── utils/
│   │   │   └── wecom_crypto.py   # 企微消息加解密（AES-CBC-256）
│   │   ├── services/
│   │   │   ├── wecom_service.py  # 企微回调处理
│   │   │   ├── message_router.py # 消息路由 + 评分 + 举手检测
│   │   │   ├── scoring_service.py # 紧急度评分引擎
│   │   │   ├── session_service.py # 会话生命周期管理
│   │   │   └── funny_phrase_service.py # 摇人趣味话术生成
│   │   └── api/                  # 8 个 API 路由模块
│   └── tests/                    # 116+ 个测试用例
├── frontend-agent/           # 坐席工作台（Vue 3 + Element Plus）
│   └── src/
│       ├── views/                # LoginView + WorkspaceView
│       ├── components/
│       │   ├── TopBar/           # 顶部栏（主题切换 + 用户信息）
│       │   ├── conversation/     # 会话列表 + 会话条目
│       │   ├── chat/             # 聊天区 + 消息气泡 + 输入框
│       │   ├── assistant/        # AI 推荐内联组件
│       │   ├── troubleshooting/   # 排查步骤栏（FlowchartNode）
│       │   ├── quickreply/       # 快速回复面板（三层导航）
│       │   └── todo/            # 待办面板 + 任务详情视图
│       ├── stores/               # Pinia Store（conversation/agent/quickReply/theme/todo）
│       └── api/                  # API 调用模块
├── frontend-h5/              # 员工端 H5（Vue 3 + Vant）
│   └── src/
│       ├── views/                # ChatView
│       └── components/           # ChatPanel + 摇人按钮 + AI助手
├── nginx/                    # Nginx 反向代理配置
│   └── nginx.conf
├── scripts/                  # 部署和运维脚本
│   ├── start_backend.bat     # Windows 快速启动后端（相对路径）
│   └── restart_backend.ps1   # Windows 重启后端（自动查找 PG/Redis/Python）
└── docs/                     # 项目文档（全部文档统一存放）
    ├── PRD.md                      # 产品需求文档 v1.0
    ├── PRD-v53-incremental.md      # v5.3 增量需求
    ├── ARCHITECTURE.md              # 系统架构设计（合并版）
    ├── 01-项目总览与部署手册.md      # 管理者视角部署手册
    ├── 开发交付概览.md              # 开发交付状态总览
    ├── IT智能服务台-项目迁移文档.md   # 工作区迁移记录
    ├── testing/                    # 测试报告目录
    │   └── QA_COMPREHENSIVE_REPORT.md  # 综合 QA 报告
    ├── diagrams/                   # Mermaid 图表
    │   ├── sequence-diagram.mermaid
    │   ├── sequence-shake.mermaid
    │   ├── sequence-scoring.mermaid
    │   ├── sequence-polling.mermaid
    │   └── class-diagram.mermaid
    └── prototypes/                # 原型文件
        ├── agent-workspace-v5_3.html   # 当前锁定版本（v5.3）
        ├── qr_data_full.json           # 快速回复数据（180条）
        └── archive/                    # 历史原型归档

Bug 修复清单（7 个）

#	文件	问题	修复
1	`message_router.py`	`calculate_urgency()` 是 async 但未 `await`	添加 `await`
2	`app/main.py`	中文引号 `""` 嵌入 Python 双引号字符串，SyntaxError	转义引号
3	`wecom_callback.py`	`WecomCrypto` 模块级初始化，默认 AES Key 不合法导致 `binascii.Error`	改为懒加载单例 `_get_wecom_crypto()`
4	`tests/conftest.py`	`aioredis.from_url` mock 路径错误	修正为 `redis.asyncio.from_url`
5	`tests/conftest.py`	`create_test_conversation()` 缺少 `is_pinned`/`is_todo` 参数	添加可选参数
6	`session_service.py`	`conversation_id` UUID 对象 vs String(36) 列类型不匹配	先转字符串再查询
7	`scoring_service.py`	关键词大小写不敏感缺失 + `_check_vip` 缺短路	`.lower()` + 短路返回

用户下一步操作

（已验证）pytest 全量通过：116/116 测试已在开发环境验证通过，本地无需再跑
配置企微应用凭证：
- 复制 .env.example 为 .env
- 填入企微应用的 CorpID、AgentID、Secret、Token、EncodingAESKey

Docker Compose 启动（需 PostgreSQL + Redis）：

cd C:\Users\simon\wecom_it_smart_desk
docker-compose up -d

前端开发启动：

# 坐席工作台
cd frontend-agent && npm install && npm run dev
# 用户端 H5
cd frontend-h5 && npm install && npm run dev

企微回调配置：在企微管理后台配置消息回调 URL 指向你的服务器

九、附录

8.1 需要团队协助的事项

#	事项	需要谁	紧急度
1	服务器 SSH 账号：用于 Docker 部署	运维	🔴 高（当前阻塞）
2	企微通讯录权限：确认 API 权限（VIP 功能依赖）	运维/企微管理员	中（M1 可用 mock）
3	千问/Dify/RAGFlow 环境（M2 阶段）	架构/开发	低（M2 前准备）

8.2 项目文件索引

wecom_it_smart_desk/
├── README.md                    # 入口索引
├── PRD.md                       # 产品需求文档
├── docs/
│   ├── 01-项目总览与部署手册.md   # ← 本文档（运维/架构/管理者）
│   ├── 02-技术架构与开发指南.md   # 开发者文档
│   └── 03-测试验证文档.md        # 测试文档
├── backend/                     # FastAPI 后端
├── frontend-agent/              # 坐席工作台前端
├── frontend-h5/                 # 员工 H5 前端
├── nginx/nginx.conf             # Nginx 反代配置
├── docker-compose.yml           # Docker Compose 编排
├── .env.production              # 生产环境变量模板
└── scripts/                     # 部署/构建脚本

本文档合并自原 docs/团队沟通文档-架构消息知识库.md、docs/正式环境独立部署架构方案.md、docs/DEPLOY_NAS.md。详细技术规格见 docs/02-技术架构与开发指南.md。

33 KiB Raw Blame History Unescape Escape