chore: initial baseline with P0-safety .gitignore

2026-06-14 16:49:18 +08:00
commit 63262292d7
510 changed files with 146008 additions and 0 deletions
@@ -0,0 +1,727 @@
+# 企微IT智能服务台 — 项目总览与部署手册
+
+> **版本**: v2.1 | **日期**: 2026-06-03 | **编制**: 宋献（IT支持组组长）
+> **目标读者**: **管理者 / 架构师 / 运维** — 了解项目全貌、架构决策、部署与运维操作
+
+---
+
+## 目录
+
+1. [项目概述](#一项目概述)
+2. [系统架构](#二系统架构)
+3. [三步演进路径](#三三步演进路径)
+4. [现有系统复用评估](#四现有系统复用评估)
+5. [正式环境部署方案](#五正式环境部署方案)
+6. [部署操作手册](#六部署操作手册)
+7. [运维管理](#七运维管理)
+8. [开发交付状态](#八开发交付状态)
+9. [附录](#九附录)
+
+---
+
+## 一、项目概述
+
+### 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/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）执行打包上传：
+
+```bash
+# 方式 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 服务器配置与启动
+
+```bash
+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
+bash scripts/deploy.sh
+# 自动执行：检查前置条件 → 构建后端镜像 → 启动所有容器 → 运行数据库迁移
+```
+
+### 6.5 验证部署
+
+```bash
+# 检查容器状态
+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
+# 仅更新前端
+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 回滚
+
+```bash
+docker compose down    # 停止新系统所有容器
+# 旧系统不受任何影响（独立资源）
+```
+
+---
+
+## 七、运维管理
+
+### 7.1 责任矩阵
+
+| 运维操作 | 影响范围 | 备注 |
+|---------|---------|------|
+| 重启 PostgreSQL | 仅新系统 | 独立实例 |
+| 重启 Redis | 仅新系统 | 独立实例 |
+| 修改 Nginx 配置 | 仅新系统路由 | 独立容器 |
+| 更新后端/前端代码 | 仅新系统 | 独立容器 |
+| 企微应用配置变更 | **双系统** | ⚠️ 唯一共享点，需通知双方 |
+
+### 7.2 监控指标
+
+```yaml
+主机层面:
+  - 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()` + 短路返回 |
+
+### 用户下一步操作
+
+1. **（已验证）pytest 全量通过**：116/116 测试已在开发环境验证通过，本地无需再跑
+
+2. **配置企微应用凭证**：
+   - 复制 `.env.example` 为 `.env`
+   - 填入企微应用的 CorpID、AgentID、Secret、Token、EncodingAESKey
+
+3. **Docker Compose 启动**（需 PostgreSQL + Redis）：
+   ```powershell
+   cd C:\Users\simon\wecom_it_smart_desk
+   docker-compose up -d
+   ```
+
+4. **前端开发启动**：
+   ```powershell
+   # 坐席工作台
+   cd frontend-agent && npm install && npm run dev
+   # 用户端 H5
+   cd frontend-h5 && npm install && npm run dev
+   ```
+
+5. **企微回调配置**：在企微管理后台配置消息回调 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`。