v3.1 + 批次0: 智能回复重构基线 - ApprovalMatcher + 关键词降级 + 文档速修 + v4.0任务书面化
This commit is contained in:
Simon
@@ -0,0 +1,329 @@
|
||||
# Dify App 改造与 AI 供给链路修复方案
|
||||
|
||||
> **版本**: v1.0
|
||||
> **日期**: 2026-07-13
|
||||
> **涵盖任务**: P1-4（App精简）、P1-5（Prompt部署）、P1-6（知识库优化）
|
||||
> **前置条件**: P0 代码改造已完成（`_call_dify_native()` + `DIFY_NATIVE_*` 环境变量）
|
||||
|
||||
---
|
||||
|
||||
## 一、当前阻塞点（P0-3 验证结果）
|
||||
|
||||
### 1.1 Dify 应用状态
|
||||
|
||||
| 应用 | API Key | 状态 | 说明 |
|
||||
|------|---------|------|------|
|
||||
| 智能IT支持-员工咨询 | `app-7jkRkAzvX4QM9v9SM3P8mMEO` | ❌ 400 | "Workflow not published"（工作流未发布） |
|
||||
| 老线上应用 | `app-UaTWYdBSwN6VktKQlbh5YN5H` | ✅ 200 | 返回纯文本Markdown（非JSON），已标记禁用 |
|
||||
| 分诊应用 | `app-z3S9AEUUAVPbtR2rioxpiIvp` | ✅ 200 | 返回结构化JSON，正常工作 |
|
||||
| 自建应用 | `app-J3s8sHarZQ2SCaNF3xCppliL` | ❌ 400 | "Model credentials not initialized" |
|
||||
|
||||
### 1.2 根因分析
|
||||
|
||||
Dify 应用 `app-7jkRkAzvX4QM9v9SM3P8mMEO` 是一个 **advanced-chat（聊天流）** 类型的应用，包含 85 个节点。该应用的工作流 **尚未发布**，导致 API 调用返回 `"Workflow not published"` 错误。
|
||||
|
||||
**影响**：
|
||||
- 后端 `_call_dify_native()` 调用 Dify 原生 API → 返回 400 → 降级到代理路径
|
||||
- 代理路径（dify2openai）返回 `[object Object]` → JSON 解析失败 → 降级为纯文本
|
||||
- **最终结果**：所有 Phase 1-6 前端改造的结构化功能（卡片渲染、选项按钮、诊断阶段）均无法触发
|
||||
|
||||
### 1.3 修复路径
|
||||
|
||||
```
|
||||
用户在 Dify 平台发布工作流
|
||||
↓
|
||||
Dify API 返回 200 + JSON answer
|
||||
↓
|
||||
后端 _call_dify_native() 解析 JSON
|
||||
↓
|
||||
双 WS 推送（ai_reply + dynamic_recommend）
|
||||
↓
|
||||
前端渲染结构化消息（文字气泡 + 卡片 + 选项按钮）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、P1-4：Dify App 精简方案（85 → ~35 节点）
|
||||
|
||||
### 2.1 精简原则
|
||||
|
||||
1. **后端已接管的功能**：审批意图分类、关键词预过滤、BYOD 拦截、图片增强 → Dify 中对应节点可删除
|
||||
2. **Prompt 已覆盖的功能**：JSON 输出格式、诊断阶段标注、审批卡片推送规则 → Dify 中的格式化/路由节点可删除
|
||||
3. **保留核心能力**：RAGFlow 知识检索、LLM 推理、多轮对话上下文 → 这三块是 Dify 的核心价值
|
||||
4. **Vision 节点**：后端 `VisionService` 已独立接入，但 Dify 内的图片理解节点暂保留（双路径冗余）
|
||||
|
||||
### 2.2 节点分类与精简计划
|
||||
|
||||
#### 可删除节点（50个）
|
||||
|
||||
| 类别 | 节点类型 | 数量 | 删除原因 |
|
||||
|------|---------|------|---------|
|
||||
| 审批意图路由 | if-else + answer | 12 | 后端 `_check_approval_intent()` 已接管，关键词收窄至~25个 |
|
||||
| BYOD 拦截 | if-else + code + assigner | 8 | 后端 `h5_ai_task.py` 已实现 BYOD 拦截逻辑 |
|
||||
| 格式化输出 | code + template-transform | 10 | Prompt v1.1 已要求 LLM 直接输出 JSON，无需后处理 |
|
||||
| 变量中转 | assigner | 12 | 精简后不再需要多步变量传递 |
|
||||
| 打招呼/人工判断 | if-else + answer | 4 | 后端 `h5_ai_task.py` 已实现打招呼和人工坐席判断 |
|
||||
| 保底机制 | code + if-else + assigner | 4 | 后端有 30s 超时降级 + 15s still_thinking 推送 |
|
||||
|
||||
#### 保留节点（~35个）
|
||||
|
||||
| 类别 | 节点类型 | 数量 | 保留原因 |
|
||||
|------|---------|------|---------|
|
||||
| 核心 | start + answer | 3 | 工作流入口和最终输出 |
|
||||
| 知识检索 | knowledge-retrieval | 3 | RAGFlow 检索（IT知识库 + 审批流程库 + FAQ库） |
|
||||
| LLM 推理 | llm | 4 | 主对话 LLM + 意图理解 + 上下文总结 + 图片描述 |
|
||||
| 条件路由 | if-else | 5 | 图片/文本分流 + 知识库命中/未命中分流 + 上下文长度判断 |
|
||||
| 变量管理 | assigner | 6 | 对话变量（servyou_query, memory_query, memory_ans, mmq） |
|
||||
| 代码处理 | code | 6 | 查询预处理 + 结果后处理 + 上下文拼接 + 图片URL提取 |
|
||||
| HTTP 请求 | http-request | 4 | RAGFlow API 调用 + 图片理解 API + 外部知识源 |
|
||||
| 模板转换 | template-transform | 2 | 上下文模板 + 答案模板 |
|
||||
| 列表操作 | list-operator | 1 | 历史消息列表处理 |
|
||||
| 其他 | 1 | 保底 answer 节点 |
|
||||
|
||||
### 2.3 精简后的工作流结构
|
||||
|
||||
```
|
||||
[Start]
|
||||
→ [Code: 预处理用户输入]
|
||||
→ [IF-ELSE: 图片消息?]
|
||||
├─ Yes → [HTTP: 调用图片理解API] → [LLM: 图片描述生成]
|
||||
└─ No → 直接继续
|
||||
→ [Code: 拼接上下文(memory_query + memory_ans + servyou_query)]
|
||||
→ [IF-ELSE: 上下文长度 > 阈值?]
|
||||
├─ Yes → [LLM: 上下文压缩总结]
|
||||
└─ No → 直接继续
|
||||
→ [Knowledge-Retrieval: RAGFlow 检索]
|
||||
→ [IF-ELSE: 检索结果命中?]
|
||||
├─ Yes → [LLM: 基于知识库回答(JSON格式)] → [Answer]
|
||||
└─ No → [LLM: 通用回答(JSON格式)] → [Answer]
|
||||
→ [Code: 更新对话变量]
|
||||
```
|
||||
|
||||
### 2.4 精简操作步骤
|
||||
|
||||
1. **导出当前 DSL**：在 Dify 后台导出 `app-7jkRkAzvX4QM9v9SM3P8mMEO` 的完整 YAML（已导出，见 `scripts/dify_export_clean.yaml`）
|
||||
2. **在 Dify 后台编辑工作流**：
|
||||
- 删除审批意图路由相关节点（12个 if-else + answer）
|
||||
- 删除 BYOD 拦截相关节点（8个）
|
||||
- 删除格式化输出节点（10个 code + template-transform）
|
||||
- 删除冗余变量中转节点（12个 assigner）
|
||||
- 删除打招呼/人工判断节点（4个）
|
||||
- 删除保底机制节点（4个）
|
||||
3. **更新 LLM 节点的 System Prompt**：将 `dify_main_chat_prompt_v1.md` 的完整 Prompt 粘贴到主 LLM 节点
|
||||
4. **重新连接节点**：确保工作流从 Start 到 Answer 的路径完整
|
||||
5. **测试工作流**：在 Dify 后台的调试面板中测试以下场景：
|
||||
- "密码忘记了怎么办" → 应返回 JSON with options
|
||||
- "我要申请VPN" → 应返回 JSON with action
|
||||
- "你好" → 应返回 JSON 纯文字
|
||||
6. **发布工作流**：点击「发布」按钮，使工作流生效
|
||||
|
||||
---
|
||||
|
||||
## 三、P1-5：Dify Prompt v1.1 部署内容
|
||||
|
||||
### 3.1 Prompt 文件位置
|
||||
|
||||
完整 Prompt 已准备好，位于：
|
||||
```
|
||||
docs/02-产品需求/dify_main_chat_prompt_v1.md
|
||||
```
|
||||
|
||||
### 3.2 部署步骤
|
||||
|
||||
1. **登录 Dify 平台**：http://yw-dify.dc.servyou-it.com
|
||||
2. **打开应用**：找到「智能IT支持-员工咨询」（API Key: `app-7jkRkAzvX4QM9v9SM3P8mMEO`）
|
||||
3. **进入编排页面**：点击「编排」→ 进入工作流编辑器
|
||||
4. **找到主 LLM 节点**：在精简后的工作流中，主 LLM 节点（用于生成最终回复的节点）
|
||||
5. **替换 System Prompt**：
|
||||
- 将 `dify_main_chat_prompt_v1.md` 中「## System Prompt 正文」以下的所有内容复制
|
||||
- 粘贴到 LLM 节点的「SYSTEM」输入框中
|
||||
- 确保 USER 输入框设置为 `{{#sys.query#}}`（用户原始输入）
|
||||
6. **配置模型参数**：
|
||||
- 模型：`gpt-3.5-turbo`（或可用的 OpenAI 兼容模型）
|
||||
- Temperature：0.3（低温度保证 JSON 格式稳定）
|
||||
- Max Tokens：500（JSON 输出不需要太长）
|
||||
7. **测试验证**：
|
||||
- 在调试面板输入 "密码忘了" → 验证返回 JSON 包含 `text` + `options` + `diagnosis_stage`
|
||||
- 在调试面板输入 "我要申请VPN" → 验证返回 JSON 包含 `action`
|
||||
- 在调试面板输入 "谢谢" → 验证返回 JSON 纯文字
|
||||
8. **发布**：确认无误后点击「发布」
|
||||
|
||||
### 3.3 Prompt 核心要点
|
||||
|
||||
Prompt v1.1 的关键设计：
|
||||
|
||||
| 要点 | 说明 |
|
||||
|------|------|
|
||||
| JSON 强制输出 | 4个字段：`text`、`action`、`options`、`diagnosis_stage` |
|
||||
| 文字简短 | `text` 字段 ≤50字，口语化 |
|
||||
| 诊断阶段 | 6种值：initial/gathering_info/diagnosing/recommending/resolved/escalating |
|
||||
| 审批卡片 | `action.type = "approval_card"`，8种审批类型 |
|
||||
| 交互选项 | `options` 最多4个，label ≤8字 |
|
||||
| 无 markdown | 直接输出 JSON 原文，不用代码块包裹 |
|
||||
|
||||
### 3.4 后端适配确认
|
||||
|
||||
后端 `_call_dify_native()` 和 `_parse_structured_response()` 已完成适配：
|
||||
- `_call_dify_native()`：直连 Dify `/v1/chat-messages`，blocking 模式，返回 `answer` 字段
|
||||
- `_parse_structured_response()`：解析 `answer` 字段为 JSON，提取 `text`/`action`/`options`/`diagnosis_stage`
|
||||
- 失败降级：JSON 解析失败 → 纯文本回复（不中断用户体验）
|
||||
|
||||
---
|
||||
|
||||
## 四、P1-6：知识库内容优化计划
|
||||
|
||||
### 4.1 当前知识库状态
|
||||
|
||||
RAGFlow 生产环境：`http://10.80.0.85:8080/`（API: `:9380`）
|
||||
|
||||
Dify 中引用的知识库：
|
||||
1. **IT知识库**：日常IT问题解答（密码重置、VPN连接、打印机等）
|
||||
2. **审批流程库**：12种审批类型的操作流程
|
||||
3. **FAQ库**：高频问题快速回答
|
||||
|
||||
### 4.2 优化目标
|
||||
|
||||
| 指标 | 当前 | 目标 |
|
||||
|------|------|------|
|
||||
| 检索准确率 | ~60%（粗估） | ≥85% |
|
||||
| 知识库文档数 | ~200篇 | ~150篇（精简+补充） |
|
||||
| 平均检索时间 | ~3s | ≤2s |
|
||||
| 无效检索率 | ~25% | ≤10% |
|
||||
|
||||
### 4.3 优化策略
|
||||
|
||||
#### 策略1：知识库结构化重构
|
||||
|
||||
```
|
||||
IT知识库/
|
||||
├── 01-账号密码/ # 密码重置、账号解锁、二次验证
|
||||
│ ├── 企微密码重置.md
|
||||
│ ├── 邮箱密码重置.md
|
||||
│ ├── aTrust密码重置.md
|
||||
│ └── GitLab密码重置.md
|
||||
├── 02-网络VPN/ # VPN连接、网络故障、WiFi
|
||||
│ ├── 零信任aTrust连接.md
|
||||
│ ├── 传统VPN配置.md
|
||||
│ └── 网络不通排查.md
|
||||
├── 03-设备硬件/ # 电脑、显示器、打印机
|
||||
│ ├── 打印机连接.md
|
||||
│ ├── 蓝屏排查.md
|
||||
│ └── 设备报修流程.md
|
||||
├── 04-软件安装/ # 软件安装、授权、更新
|
||||
│ ├── 软件安装指南.md
|
||||
│ └── 软件授权申请.md
|
||||
├── 05-审批流程/ # 12种审批类型
|
||||
│ ├── 设备申请流程.md
|
||||
│ ├── VPN账号申请.md
|
||||
│ └── ...
|
||||
└── 06-常见FAQ/ # 高频问题
|
||||
├── 电脑卡顿.md
|
||||
└── 邮件配置.md
|
||||
```
|
||||
|
||||
#### 策略2：文档内容标准化
|
||||
|
||||
每篇知识库文档统一格式：
|
||||
|
||||
```markdown
|
||||
# [问题标题]
|
||||
|
||||
## 问题描述
|
||||
[1-2句话描述问题场景]
|
||||
|
||||
## 解决方案
|
||||
### 步骤1：[操作名称]
|
||||
[具体操作步骤]
|
||||
|
||||
### 步骤2：[操作名称]
|
||||
[具体操作步骤]
|
||||
|
||||
## 相关链接
|
||||
- [操作入口URL]
|
||||
- [相关文档]
|
||||
|
||||
## 关键词
|
||||
密码、重置、企微、登录
|
||||
```
|
||||
|
||||
#### 策略3：RAGFlow 检索优化
|
||||
|
||||
1. **Chunk 策略调整**：
|
||||
- 将大文档拆分为 ≤500 token 的 chunk
|
||||
- 每个 chunk 包含完整的「问题描述 + 解决方案」
|
||||
- 避免跨 chunk 的信息断裂
|
||||
|
||||
2. **Embedding 模型**：
|
||||
- 确认使用中文优化的 embedding 模型（如 `bge-large-zh`）
|
||||
- 如果当前用的是英文模型，切换后检索准确率可提升 15-20%
|
||||
|
||||
3. **检索参数调优**：
|
||||
- Top-K：5→3（减少噪音）
|
||||
- 相似度阈值：0.5→0.65（提高精度）
|
||||
- Rerank：启用 rerank 模型（如 `bge-reranker-base`）
|
||||
|
||||
#### 策略4：知识库内容补充
|
||||
|
||||
基于员工咨询高频场景，需补充以下内容：
|
||||
|
||||
| 场景 | 当前状态 | 补充内容 |
|
||||
|------|---------|---------|
|
||||
| 企微使用问题 | 缺失 | 企微登录/消息/审批/会议常见问题 |
|
||||
| 税友安全助手 | 缺失 | 安装/认证失败/网络断开排查 |
|
||||
| 域控账号 | 部分 | 域控密码同步机制 + 常见故障 |
|
||||
| 云桌面 | 缺失 | 云桌面连接/卡顿/文件传输 |
|
||||
| 视频会议 | 部分 | 腾讯会议/企微会议常见问题 |
|
||||
|
||||
### 4.4 实施时间线
|
||||
|
||||
| 阶段 | 内容 | 预计工作量 |
|
||||
|------|------|-----------|
|
||||
| 第1周 | 知识库结构化重构 + 文档标准化 | 2天 |
|
||||
| 第1周 | RAGFlow 检索参数调优 | 0.5天 |
|
||||
| 第2周 | 高频场景内容补充（20篇） | 2天 |
|
||||
| 第2周 | Embedding 模型评估 + 切换 | 1天 |
|
||||
| 第3周 | 端到端测试 + 效果评估 | 1天 |
|
||||
|
||||
---
|
||||
|
||||
## 五、完整执行清单
|
||||
|
||||
### 5.1 用户需在 Dify 平台操作（阻塞项）
|
||||
|
||||
- [ ] **D-1**：登录 http://yw-dify.dc.servyou-it.com
|
||||
- [ ] **D-2**：打开「智能IT支持-员工咨询」应用（`app-7jkRkAzvX4QM9v9SM3P8mMEO`）
|
||||
- [ ] **D-3**：精简工作流（按 P1-4 方案，85→~35节点）
|
||||
- [ ] **D-4**：更新主 LLM 节点的 System Prompt（按 P1-5 部署步骤）
|
||||
- [ ] **D-5**：在调试面板测试3个场景（密码/VPN/打招呼）
|
||||
- [ ] **D-6**：点击「发布」按钮
|
||||
- [ ] **D-7**：发布后通知我验证 API 连通性
|
||||
|
||||
### 5.2 我来完成（Dify 发布后）
|
||||
|
||||
- [ ] **M-1**：验证 Dify 原生 API 返回 JSON 格式（复用 `test_dify_native.py`）
|
||||
- [ ] **M-2**：请用户在企微内发消息测试端到端链路
|
||||
- [ ] **M-3**：检查后端日志确认 `调用 Dify 原生 API` + JSON 解析成功
|
||||
- [ ] **M-4**：验证前端结构化消息渲染（文字气泡 + 卡片 + 选项按钮）
|
||||
- [ ] **M-5**：开始知识库优化（P1-6）
|
||||
|
||||
### 5.3 临时方案（如需立即可用）
|
||||
|
||||
如果用户暂时无法在 Dify 平台操作，可临时切换到旧 Key（需用户授权）：
|
||||
|
||||
```
|
||||
# 临时切换 .env 中的 DIFY_NATIVE_API_KEY
|
||||
DIFY_NATIVE_API_KEY=app-UaTWYdBSwN6VktKQlbh5YN5H
|
||||
```
|
||||
|
||||
**注意**：旧 Key 返回纯文本（非JSON），后端会降级为纯文字回复。结构化功能（卡片/选项）不可用，但至少 AI 对话能正常工作。
|
||||
|
||||
---
|
||||
|
||||
## 六、风险评估
|
||||
|
||||
| 风险 | 等级 | 缓解措施 |
|
||||
|------|------|---------|
|
||||
| Dify 工作流精简后遗漏关键路径 | 中 | 精简前已导出完整 DSL YAML 备份 |
|
||||
| Prompt v1.1 在 Dify 中 JSON 输出不稳定 | 中 | Temperature=0.3 + 后端有 JSON 解析降级 |
|
||||
| RAGFlow 检索准确率不达标 | 低 | 可通过调整检索参数 + 补充内容逐步优化 |
|
||||
| 知识库内容过时 | 中 | 建立月度知识库审查机制 |
|
||||
@@ -117,6 +117,8 @@
|
||||
|
||||
同一 corpid 下所有自建应用各自独立鉴权，用户在企微内打开任意应用 H5 页面时通过 OAuth2 `snsapi_base` 静默授权自动完成登录。从 IT 服务台 H5 点击运维平台审批链接时，运维平台走自己的 OAuth2 流程拿到 `userid` 并自动登录。前提：运维平台已配置可信域名和 OAuth2 回调。
|
||||
|
||||
> **⚠️ 限制补充（2026-07-17）**：上述"免登录"结论**不适用于 Web ITSM 工单深链**。`devops.dc.servyou-it.com/ITSM/...` 是独立 Web 应用，不满足 `snsapi_base` 静默授权前提，冷访问必弹扫码。详见下方 §v2.3 增量需求与技术架构文档 §15.4.9。
|
||||
|
||||
#### 关联文档
|
||||
|
||||
| 文档 | 位置 |
|
||||
@@ -129,6 +131,52 @@
|
||||
|
||||
---
|
||||
|
||||
### v2.3 增量需求（2026-07-17）— ITSM 工单跳转交互优化
|
||||
|
||||
#### 背景
|
||||
|
||||
v2.2 将 8 个运维平台（ITSM）审批卡片改为 Web 工单深链 `http://devops.dc.servyou-it.com/ITSM/workflow/service/createTicket?name=XXX` 一步直达。企微内实测发现 Web ITSM 深链**不支持静默企微 OAuth**，冷访问会被重定向到扫码登录页。
|
||||
|
||||
#### 根因分析
|
||||
|
||||
- 移动端首页 `itsm.servyou.com.cn/itsm-miniapp-mobile/` 在企微 webview 内会静默完成企微 OAuth，把 ITSM 后端会话"预热"出来（即使过期也静默重登）。
|
||||
- Web 版 `devops.dc.servyou-it.com/ITSM/...` 只认已温热的会话：会话在→免登录；会话不在（冷 hit）→ 跳扫码页。
|
||||
- 原两步流（首页→点 Web 深链）免登录，是因为**首页那一步已把会话预热**，并非 Web 深链自身能续登。
|
||||
- 尝试用桥接页（我方域名 `itsm-bridge.html` 隐式加载首页预热 + 自动跳深链）补回预热步骤，实测**仍弹扫码**：ITSM 在跨域 iframe 场景下拒绝静默 OAuth 预热，桥接 trick 失效。
|
||||
|
||||
#### 产品决策
|
||||
|
||||
在现有 ITSM 鉴权模型下，「一步直达」与「免登录」不可兼得。产品侧决策**保持现状**——卡片点击经桥接页跳转 Web 工单表单，首次访问 / 会话过期时出现的扫码登录**作为人机校验（Human-Machine Verification）环节保留**，是企业安全合规可接受的二次身份确认，不视为功能缺陷。
|
||||
|
||||
#### 交互逻辑（8 个运维平台模板）
|
||||
|
||||
```
|
||||
H5 审批卡片点击
|
||||
└─> 桥接页 itsm-bridge.html?name=<URL编码服务名>（我方 https 域名）
|
||||
├─ 隐藏 iframe 加载移动端首页（尝试静默预热 ITSM 会话）
|
||||
└─ 2.5s 后 top-level 跳转 Web 工单深链 createTicket?name=<服务名>
|
||||
├─ 会话已预热 → 直接打开工单表单（免登录）
|
||||
└─ 会话未预热 → ITSM 扫码登录页（作为人机校验，扫码后进入表单）
|
||||
```
|
||||
|
||||
#### 技术限制（摘要，详见技术架构文档 §15.4.9）
|
||||
|
||||
1. Web ITSM (`devops.dc.servyou-it.com`) 深链不支持静默企微 OAuth，冷访问必弹扫码。
|
||||
2. 移动端首页 (`itsm.servyou.com.cn/itsm-miniapp-mobile/`) 在企微 webview 内可静默 OAuth 预热会话，但作为独立 SPA 无 SPA fallback，深链子路由 404，只能落到首页。
|
||||
3. 桥接页 iframe 预热在跨域场景下被 ITSM 拒绝，无法复用首页会话。
|
||||
4. 深链为 `http://` 明文，个别企微版本对 HTTPS 页内嵌 HTTP 混合内容有限制。
|
||||
|
||||
#### 受影响范围
|
||||
|
||||
| 类别 | 模板 | 跳转目标 |
|
||||
|------|------|---------|
|
||||
| 运维平台（8 个，走桥接页） | IT设备升级与硬件维修、IT资产升级、员工零信任（原VPN）账号申请、商业软件服务申请、终端设备网络准入申请、活动与会议技术支持、员工IT支持与故障报修、公共邮箱账号申请 | 桥接页 → Web 工单深链 |
|
||||
| 企微审批（2 个，不在本改造范围） | IT资产领用 (asset_receive)、IT资产借用 (asset_borrow) | 企微审批流程（非 ITSM） |
|
||||
|
||||
> 注：IT资产领用 / IT资产借用 属企微审批流程，非 ITSM，本次未改动；其跳转逻辑以 `approval_templates.json` 数据源定义为准。
|
||||
|
||||
---
|
||||
|
||||
## 四、知识库迭代补充需求
|
||||
|
||||
### 4.1 背景
|
||||
@@ -169,6 +217,7 @@
|
||||
| v1.1 | ✅ 已上线 | 敏感词检测、token修复、扫码登录优化 |
|
||||
| v1.2 | ✅ 已上线 | 知识库迭代修复、生产痛点缓解 |
|
||||
| v2.2 | ✅ 已上线 | 审批卡片改造：12种/18流程、URL直跳、同窗口导航、Dify v2 |
|
||||
| v2.3 | ✅ 已上线 | ITSM 工单跳转交互优化：桥接页一步直达 + 扫码登录定为人机校验 |
|
||||
|
||||
---
|
||||
|
||||
@@ -183,4 +232,4 @@
|
||||
|
||||
---
|
||||
|
||||
> **最后更新**: 2026-07-10 - 整合PRD主文档与增量需求
|
||||
> **最后更新**: 2026-07-17 - 新增 §v2.3 ITSM 工单跳转交互优化（桥接页 + 扫码登录定为人机校验）
|
||||
|
||||
@@ -47,12 +47,13 @@
|
||||
"id": "software_service",
|
||||
"name": "商业软件服务申请",
|
||||
"category": "软件服务申请",
|
||||
"location": "企微审批",
|
||||
"location": "运维平台(ITSM)",
|
||||
"template_id": "3TmACf8DsJy5yr7aymanLskywC4EDhFLuz1KuBBQK",
|
||||
"url": "https://app.work.weixin.qq.com/wework_admin/approval_v3#/?template_id=3TmACf8DsJy5yr7aymanLskywC4EDhFLuz1KuBBQK&sp_id=&from=template_list",
|
||||
"url": "https://devops.dc.servyou-it.com/ITSM/workflow/service/createTicket?name=%E5%95%86%E4%B8%9A%E8%BD%AF%E7%94%9F%E7%94%B3%E7%94%A8%E7%94%B3%E5%95%86%E5%8F%B3%E7%94%B3%E8%AF%B7",
|
||||
"keywords": ["软件", "商业软件", "软件服务"],
|
||||
"icon": "apps-o",
|
||||
"desc": "正版软件授权"
|
||||
"desc": "正版软件授权",
|
||||
"note": "2026-07-15 企微审批模板已失效，改为ITSM工单系统"
|
||||
},
|
||||
{
|
||||
"id": "asset_borrow",
|
||||
@@ -80,12 +81,13 @@
|
||||
"id": "asset_upgrade",
|
||||
"name": "IT资产升级申请",
|
||||
"category": "设备申请",
|
||||
"location": "企微审批",
|
||||
"location": "运维平台(ITSM)",
|
||||
"template_id": "Bs7ucTGsPuFhxfk8pn8EydxrWxkVetB4JR8Pb6PHS",
|
||||
"url": "https://app.work.weixin.qq.com/wework_admin/approval_v3#/?template_id=Bs7ucTGsPuFhxfk8pn8EydxrWxkVetB4JR8Pb6PHS&sp_id=&from=template_list",
|
||||
"url": "https://devops.dc.servyou-it.com/ITSM/workflow/service/createTicket?name=IT%E8%AE%BE%E5%A4%87%E5%8D%87%E7%BA%A7%E4%B8%8E%E7%A1%AC%E4%BB%B6%E7%BB%B4%E4%BF%AE",
|
||||
"keywords": ["资产升级", "设备升级", "升级"],
|
||||
"icon": "orders-o",
|
||||
"desc": "设备升级换新"
|
||||
"desc": "设备升级换新",
|
||||
"note": "2026-07-15 企微审批模板已失效，改为ITSM工单系统"
|
||||
},
|
||||
{
|
||||
"id": "asset_scrap",
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
# Dify 审批意图识别应用 — System Prompt（v2.0 扩展版）
|
||||
# Dify 审批意图识别应用 — System Prompt（v2.1 细化版）
|
||||
|
||||
> ⚠️ **已废弃（2026-07-17）**：本文档对应的独立「审批意图识别」链路（`POST /approval/detect-intent`）已确认为死链路——前端自 v2.0 起无调用，后端端点将在 v4.0 重构（批次 2）中删除。审批意图识别已由 **Dify 主应用（智能IT支持-员工咨询）action 字段 + 后端 ApprovalMatcher** 接管。本文档仅作历史参考，请勿再部署到 Dify。
|
||||
|
||||
## 使用说明
|
||||
将以下完整文本复制粘贴到 Dify 后台「审批意图识别」应用的 System Prompt 配置中，替换原有内容。
|
||||
@@ -9,22 +11,30 @@
|
||||
|
||||
你是企业IT服务台的审批意图识别引擎。你的任务是分析用户发送的消息，判断是否包含审批/申请意图，并识别具体的审批类型。
|
||||
|
||||
### 支持的审批类型（12种）
|
||||
### 支持的审批类型（18个细分类型）
|
||||
|
||||
| 序号 | 审批类型 | 说明 | 典型示例 |
|
||||
|------|---------|------|---------|
|
||||
| 1 | 设备申请 | IT设备领用、借用、升级 | "我要申请一台笔记本电脑"、"领用显示器"、"借用设备" |
|
||||
| 2 | 账号权限申请 | VPN、企微外联、零信任账号 | "我要申请VPN"、"开通外联权限"、"零信任账号" |
|
||||
| 3 | 软件服务申请 | 商业软件授权、业务系统 | "申请软件授权"、"需要商业软件" |
|
||||
| 4 | 资产处置申请 | 设备外修、报废、退还 | "设备坏了要送修"、"报废旧电脑"、"退还设备" |
|
||||
| 5 | 办公用品申请 | 办公用品超额领用 | "办公用品超额领用"、"超过配额领用品" |
|
||||
| 6 | 会议室故障报修 | 会议室设备故障 | "会议室投影仪坏了"、"会议室空调故障报修" |
|
||||
| 7 | 企业应用管理 | 企业应用开通与管理 | "申请开通企业应用"、"企业应用管理" |
|
||||
| 8 | 资产变更确认 | 资产信息变更确认 | "资产变更确认"、"设备信息变更" |
|
||||
| 9 | 终端设备网络准入 | 终端网络准入申请 | "终端网络准入申请"、"设备网络准入" |
|
||||
| 10 | 活动与会议技术支持 | 活动会议技术保障 | "活动技术支持"、"会议需要技术保障" |
|
||||
| 11 | 员工IT支持与故障报修 | IT支持与故障报修 | "电脑坏了报修"、"需要IT技术支持" |
|
||||
| 12 | 公共邮箱账号申请 | 公共/共享邮箱账号 | "申请公共邮箱"、"需要共享邮箱账号" |
|
||||
为了更精准地匹配用户需求，请尽可能识别到最具体的审批子类型：
|
||||
|
||||
| 序号 | 审批子类型 | 所属大类 | 说明 | 典型示例 |
|
||||
|------|-----------|---------|------|---------|
|
||||
| 1 | IT资产领用 | 设备申请 | 申请新设备 | "我要申请一台笔记本电脑"、"领用显示器" |
|
||||
| 2 | IT资产借用 | 设备申请 | 临时借用设备 | "借用设备"、"临时用一下电脑" |
|
||||
| 3 | IT资产升级 | 设备申请 | 设备升级换新 | "电脑太卡想升级"、"显示器太小想换" |
|
||||
| 4 | VPN账号申请 | 账号权限申请 | 零信任VPN/aTrust | "我要申请VPN"、"VPN账号申请" |
|
||||
| 5 | 企微外联权限 | 账号权限申请 | 外部联系人权限 | "开通外联权限"、"申请外联" |
|
||||
| 6 | 公共邮箱账号 | 账号权限申请 | 共享邮箱 | "申请公共邮箱"、"需要共享邮箱" |
|
||||
| 7 | 商业软件申请 | 软件服务申请 | 正版软件授权 | "申请软件授权"、"需要商业软件" |
|
||||
| 8 | IT资产外修 | 资产处置申请 | 设备送修 | "设备坏了要送修"、"电脑需要维修" |
|
||||
| 9 | IT资产报废 | 资产处置申请 | 设备报废 | "旧电脑报废"、"设备需要报废" |
|
||||
| 10 | 资产退还 | 资产处置申请 | 退还设备 | "退还设备"、"把电脑还了" |
|
||||
| 11 | 办公用品超额领用 | 办公用品申请 | 超配额申领 | "办公用品超额领用"、"超过配额领用品" |
|
||||
| 12 | 会议室故障报修 | 会议室故障报修 | 会议室设备故障 | "会议室投影仪坏了"、"会议室空调故障" |
|
||||
| 13 | 企业应用管理 | 企业应用管理 | 企业应用开通管理 | "申请开通企业应用"、"企业应用管理" |
|
||||
| 14 | 资产变更确认 | 资产变更确认 | 资产信息变更 | "资产变更确认"、"设备信息变更" |
|
||||
| 15 | 终端设备网络准入申请 | 终端设备网络准入 | 终端网络准入 | "终端网络准入申请"、"设备网络准入" |
|
||||
| 16 | 活动与会议技术支持 | 活动与会议技术支持 | 活动会议技术保障 | "活动技术支持"、"会议需要技术保障" |
|
||||
| 17 | 员工IT支持与故障报修 | 员工IT支持与故障报修 | IT支持与故障报修 | "电脑坏了报修"、"需要IT技术支持" |
|
||||
| 18 | 公共邮箱账号申请 | 公共邮箱账号申请 | 公共邮箱账号 | "申请公共邮箱"、"需要共享邮箱账号" |
|
||||
|
||||
### 判断规则
|
||||
|
||||
@@ -34,20 +44,28 @@
|
||||
4. **闲聊/无关**：与IT审批完全无关 → `is_approval_request: false`，`confidence ≤ 0.1`
|
||||
5. **模糊/不确定**：无法明确判断 → `is_approval_request: false`，`confidence: 0.3~0.5`
|
||||
|
||||
### 审批类型匹配规则
|
||||
### 审批类型匹配规则（细化版）
|
||||
|
||||
- "设备/电脑/笔记本/显示器/领用/借用/升级" → `设备申请`
|
||||
- "VPN/外联/零信任/账号/权限" → `账号权限申请`
|
||||
- "软件/商业软件/业务系统" → `软件服务申请`
|
||||
- "外修/报废/退还/送修" → `资产处置申请`
|
||||
- "办公用品/超额/领用" → `办公用品申请`
|
||||
- "会议室/投影仪/会议设备故障" → `会议室故障报修`
|
||||
请按以下规则尽可能精确匹配到最具体的子类型：
|
||||
|
||||
- "领用/新电脑/新设备/笔记本/台式机/显示器" → `IT资产领用`
|
||||
- "借用/临时/用一下/暂用" → `IT资产借用`
|
||||
- "升级/换新/换电脑/换显示器/扩容" → `IT资产升级`
|
||||
- "VPN/aTrust/零信任/零信任VPN" → `VPN账号申请`
|
||||
- "外联/外部联系人/企微外联" → `企微外联权限`
|
||||
- "公共邮箱/共享邮箱" → `公共邮箱账号`
|
||||
- "商业软件/软件授权/正版软件" → `商业软件申请`
|
||||
- "外修/送修/维修/修电脑" → `IT资产外修`
|
||||
- "报废/旧电脑处理/不要了" → `IT资产报废`
|
||||
- "退还/还设备/还电脑" → `资产退还`
|
||||
- "办公用品超额/超配额/超过配额" → `办公用品超额领用`
|
||||
- "会议室故障/会议室报修/会议室设备/会议室投影仪/会议室空调" → `会议室故障报修`
|
||||
- "企业应用/应用开通/应用管理" → `企业应用管理`
|
||||
- "资产变更/变更确认" → `资产变更确认`
|
||||
- "网络准入/终端准入" → `终端设备网络准入`
|
||||
- "活动支持/会议支持/技术保障" → `活动与会议技术支持`
|
||||
- "故障报修/IT支持/技术支持/报修" → `员工IT支持与故障报修`
|
||||
- "公共邮箱/共享邮箱/公共账号" → `公共邮箱账号申请`
|
||||
- "资产变更/变更确认/设备信息变更" → `资产变更确认`
|
||||
- "网络准入/终端准入/设备入网" → `终端设备网络准入申请`
|
||||
- "活动支持/会议支持/技术保障/活动技术/会议技术" → `活动与会议技术支持`
|
||||
- "故障报修/IT支持/技术支持/报修/电脑坏了/网络不好" → `员工IT支持与故障报修`
|
||||
- "公共邮箱/共享邮箱/部门邮箱" → `公共邮箱账号申请`
|
||||
|
||||
### 输出格式
|
||||
|
||||
@@ -57,20 +75,25 @@
|
||||
{
|
||||
"is_approval_request": true,
|
||||
"confidence": 0.95,
|
||||
"approval_type": "设备申请"
|
||||
"approval_type": "VPN账号申请"
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
- `is_approval_request`: 布尔值，是否为审批请求
|
||||
- `confidence`: 浮点数 0.0~1.0，置信度
|
||||
- `approval_type`: 字符串或 null。当 `is_approval_request` 为 true 时，必须返回上述12种类型之一；为 false 时设为 null
|
||||
- `approval_type`: 字符串或 null。当 `is_approval_request` 为 true 时，必须返回上述18种子类型之一（如"VPN账号申请"、"IT资产领用"等）
|
||||
|
||||
### 示例
|
||||
|
||||
用户："我要申请一台笔记本电脑"
|
||||
```json
|
||||
{"is_approval_request": true, "confidence": 0.95, "approval_type": "设备申请"}
|
||||
{"is_approval_request": true, "confidence": 0.95, "approval_type": "IT资产领用"}
|
||||
```
|
||||
|
||||
用户："我要申请VPN账号"
|
||||
```json
|
||||
{"is_approval_request": true, "confidence": 0.95, "approval_type": "VPN账号申请"}
|
||||
```
|
||||
|
||||
用户："我的VPN连不上了"
|
||||
@@ -95,25 +118,35 @@
|
||||
|
||||
用户："电脑太卡了想换一台新的"
|
||||
```json
|
||||
{"is_approval_request": true, "confidence": 0.78, "approval_type": "设备申请"}
|
||||
{"is_approval_request": true, "confidence": 0.78, "approval_type": "IT资产升级"}
|
||||
```
|
||||
|
||||
用户："申请一个公共邮箱给部门用"
|
||||
```json
|
||||
{"is_approval_request": true, "confidence": 0.95, "approval_type": "公共邮箱账号申请"}
|
||||
{"is_approval_request": true, "confidence": 0.95, "approval_type": "公共邮箱账号"}
|
||||
```
|
||||
|
||||
用户："旧电脑坏了，想报废掉"
|
||||
```json
|
||||
{"is_approval_request": true, "confidence": 0.90, "approval_type": "资产处置申请"}
|
||||
{"is_approval_request": true, "confidence": 0.90, "approval_type": "IT资产报废"}
|
||||
```
|
||||
|
||||
用户："终端设备需要网络准入"
|
||||
```json
|
||||
{"is_approval_request": true, "confidence": 0.92, "approval_type": "终端设备网络准入"}
|
||||
{"is_approval_request": true, "confidence": 0.92, "approval_type": "终端设备网络准入申请"}
|
||||
```
|
||||
|
||||
用户："VPN怎么用啊"
|
||||
```json
|
||||
{"is_approval_request": false, "confidence": 0.20, "approval_type": null}
|
||||
```
|
||||
|
||||
用户："我想借用一台电脑用几天"
|
||||
```json
|
||||
{"is_approval_request": true, "confidence": 0.90, "approval_type": "IT资产借用"}
|
||||
```
|
||||
|
||||
用户："需要开通企微外联权限"
|
||||
```json
|
||||
{"is_approval_request": true, "confidence": 0.95, "approval_type": "企微外联权限"}
|
||||
```
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Dify 意图识别 System Prompt 更新指南 — 新增「自备电脑补贴」意图
|
||||
|
||||
> ⚠️ **已废弃（2026-07-17）**：本文档对应的「BYOD 意图识别」链路（`POST /byod/detect-intent`）已确认为死链路——前端自 v2.0 起无调用，后端端点将在 v4.0 重构（批次 2）中删除。BYOD 判断现由后端关键词拦截（`h5_ai_task.py` BYOD 分支）+ 岗位匹配直接处理，不经过 Dify。本文档仅作历史参考，请勿再部署到 Dify。
|
||||
|
||||
## 背景
|
||||
|
||||
当前 Dify 审批意图识别应用已支持 12 种审批类型的意图检测。本次需在其 System Prompt 中新增「自备电脑补贴（BYOD）」意图的识别能力，使 Dify 能区分用户是在询问审批流程还是在询问自备电脑补贴资格。
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
# Dify 主对话应用 — System Prompt（v1.1 JSON 输出版）
|
||||
# Dify 主对话应用 — System Prompt（v1.2 JSON 输出版）
|
||||
|
||||
> **版本**: v1.1
|
||||
> **变更**: 新增 `diagnosis_stage` 字段用于诊断闭环协调
|
||||
> **版本**: v1.2
|
||||
> **变更**: 删除规则 4「引用侧边栏」（审批卡片由后端 card_data 直出渲染，不再依赖文字引用）；示例文字去"右侧"化
|
||||
> **应用**: 智能IT支持-员工咨询 (API Key: app-7jkRkAzvX4QM9v9SM3P8mMEO)
|
||||
> **日期**: 2026-07-13
|
||||
> **日期**: 2026-07-13（v1.1）/ 2026-07-17（v1.2，已发布至 Dify Console）
|
||||
|
||||
## 使用说明
|
||||
将以下完整文本复制粘贴到 Dify 后台「智能IT支持-员工咨询」应用的 System Prompt 配置中。
|
||||
@@ -20,8 +20,7 @@
|
||||
1. **回复必须为 JSON 格式**，包含四个字段：`text`、`action`、`options`、`diagnosis_stage`
|
||||
2. **文字简短**：`text` 字段控制在 50 字以内，用口语化表达，像朋友聊天
|
||||
3. **一次只聚焦一个问题**：不要一次性给出所有解决方案，逐步引导用户
|
||||
4. **引用侧边栏**：当推送操作入口时，在文字中提及"右侧已为您准备好"
|
||||
5. **诊断阶段**：每次回复必须标注当前 `diagnosis_stage`，帮助系统判断诊断进度
|
||||
4. **诊断阶段**：每次回复必须标注当前 `diagnosis_stage`，帮助系统判断诊断进度
|
||||
|
||||
### JSON 输出格式
|
||||
|
||||
@@ -47,17 +46,17 @@
|
||||
|
||||
### 三种回复场景
|
||||
|
||||
#### 场景 1：审批/操作推荐（文字 + 侧边栏卡片）
|
||||
#### 场景 1：审批/操作推荐（文字 + 审批卡片）
|
||||
|
||||
当用户表达申请意图（如"申请VPN""想换电脑"），在 `action` 中填充操作入口信息：
|
||||
|
||||
```json
|
||||
{
|
||||
"text": "您想申请VPN账号？右侧已为您准备好入口，点击即可提交。",
|
||||
"text": "我来帮您提交VPN账号申请，请点击下方卡片。",
|
||||
"action": {
|
||||
"type": "approval_card",
|
||||
"approval_type": "账号权限申请",
|
||||
"title": "VPN 账号申请",
|
||||
"title": "VPN账号申请",
|
||||
"description": "1-2 个工作日审批完成"
|
||||
},
|
||||
"options": null,
|
||||
@@ -160,7 +159,7 @@
|
||||
|
||||
用户："我要申请VPN账号"
|
||||
```json
|
||||
{"text": "您想申请VPN账号？右侧已为您准备好入口，点击即可提交。", "action": {"type": "approval_card", "approval_type": "账号权限申请", "title": "VPN账号申请", "description": "1-2个工作日审批完成"}, "options": null}
|
||||
{"text": "我来帮您提交VPN账号申请，请点击下方卡片。", "action": {"type": "approval_card", "approval_type": "账号权限申请", "title": "VPN账号申请", "description": "1-2个工作日审批完成"}, "options": null}
|
||||
```
|
||||
|
||||
用户："打印机连不上"
|
||||
@@ -185,5 +184,5 @@
|
||||
|
||||
用户："企微密码"
|
||||
```json
|
||||
{"text": "企微密码可以通过企微设置自助重置。右侧已为您准备好操作指引。", "action": {"type": "approval_card", "approval_type": "账号权限申请", "title": "密码重置", "description": "自助重置或提交申请"}, "options": null}
|
||||
{"text": "企微密码可以自助重置，请点击下方卡片。", "action": {"type": "approval_card", "approval_type": "账号权限申请", "title": "密码重置", "description": "自助重置或提交申请"}, "options": null}
|
||||
```
|
||||
|
||||
@@ -0,0 +1,138 @@
|
||||
# 会话存档功能 PRD
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-15 | **状态**: 已完成
|
||||
|
||||
---
|
||||
|
||||
## 1. 需求概述
|
||||
|
||||
### 1.1 背景
|
||||
|
||||
随着 IT 智能服务台的使用时间增长，会话数据量持续增加。为了优化系统性能、降低存储成本，需要建立会话数据的长期归档机制。
|
||||
|
||||
### 1.2 目标
|
||||
|
||||
1. 建立会话数据的分级存储策略
|
||||
2. 优化坐席端历史会话的加载性能
|
||||
3. 满足合规审计要求的会话留痕
|
||||
|
||||
### 1.3 范围
|
||||
|
||||
- **归档对象**：已结单的会话（resolved 状态）
|
||||
- **归档阈值**：会话结束后 90 天自动归档
|
||||
- **归档内容**：会话元数据 + 消息内容
|
||||
|
||||
---
|
||||
|
||||
## 2. 功能需求
|
||||
|
||||
### 2.1 归档策略
|
||||
|
||||
| 维度 | 热数据 | 温数据 | 冷数据 |
|
||||
|------|--------|--------|--------|
|
||||
| 定义 | ≤90天 | 91-180天 | >180天 |
|
||||
| 存储位置 | PostgreSQL 主表 | PostgreSQL 主表 | 归档标记 |
|
||||
| 访问方式 | 实时 | 实时 | 管理后台 |
|
||||
|
||||
### 2.2 会话三级显示（坐席端）
|
||||
|
||||
| 层级 | 范围 | 位置 |
|
||||
|------|------|------|
|
||||
| 当前会话 | 活跃会话（queued/serving/pending_close） | 顶部"我的会话" |
|
||||
| 近期历史 | ≤90天已结单 | "历史会话"标签 |
|
||||
| 更久历史 | >90天已归档 | 仅管理后台查看 |
|
||||
|
||||
### 2.3 管理后台功能
|
||||
|
||||
- 支持按归档状态筛选（全部/未归档/已归档）
|
||||
- 显示归档时间
|
||||
- 支持查看归档会话详情
|
||||
|
||||
---
|
||||
|
||||
## 3. 数据模型
|
||||
|
||||
### 3.1 Conversation 表扩展
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| is_archived | Boolean | 是否已归档 |
|
||||
| archived_at | DateTime | 归档时间 |
|
||||
|
||||
### 3.2 索引设计
|
||||
|
||||
```sql
|
||||
CREATE INDEX idx_conversations_is_archived ON conversations(is_archived);
|
||||
CREATE INDEX idx_conversations_archived_at ON conversations(archived_at);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 业务流程
|
||||
|
||||
### 4.1 自动归档流程
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ 定时任务触发 │
|
||||
│ (每天凌晨3点) │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ 查询已结单会话 │
|
||||
│ updated_at < │
|
||||
│ (当前-90天) │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ 标记 is_archived│
|
||||
│ = true │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ 记录归档时间 │
|
||||
│ archived_at │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ 记录日志 │
|
||||
│ 归档数量统计 │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
### 4.2 手动归档（预留）
|
||||
|
||||
管理后台支持手动归档特定会话（后续版本）
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收标准
|
||||
|
||||
### 5.1 功能验收
|
||||
|
||||
- [x] 已结单超过90天的会话自动标记为已归档
|
||||
- [x] 归档时间记录准确
|
||||
- [x] 管理后台支持按归档状态筛选
|
||||
- [x] 坐席端历史会话仅显示90天内数据
|
||||
|
||||
### 5.2 性能验收
|
||||
|
||||
- [x] 归档脚本执行时间 < 5分钟
|
||||
- [x] 归档操作不影响在线服务
|
||||
|
||||
### 5.3 数据验收
|
||||
|
||||
- [x] 归档后数据完整性不受影响
|
||||
- [x] 归档状态可逆（可取消归档）
|
||||
|
||||
---
|
||||
|
||||
## 6. 版本历史
|
||||
|
||||
| 版本 | 日期 | 变更 |
|
||||
|------|------|------|
|
||||
| v1.0 | 2026-07-15 | 初始版本 |
|
||||
@@ -0,0 +1,246 @@
|
||||
# 企微IT智能服务台 — 坐席端功能操作手册
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-13 | **维护人**: Duckula
|
||||
> **目标读者**: **坐席人员 / IT 支持工程师** — 掌握坐席工作台各功能的使用方法
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
1. [登录与认证](#一登录与认证)
|
||||
2. [会话管理](#二会话管理)
|
||||
3. [群聊与摇人](#三群聊与摇人)
|
||||
4. [AI 辅助功能](#四ai-辅助功能)
|
||||
5. [消息发送](#五消息发送)
|
||||
6. [审批处理](#六审批处理)
|
||||
7. [历史会话查询](#七历史会话查询)
|
||||
8. [其他功能](#八其他功能)
|
||||
|
||||
---
|
||||
|
||||
## 一、登录与认证
|
||||
|
||||
### 1.1 登录方式
|
||||
|
||||
**访问地址**: `https://itsupport.servyou.com.cn/itagent/`
|
||||
|
||||
| 登录方式 | 说明 |
|
||||
|----------|------|
|
||||
| 企微扫码 | 首次登录使用，直接扫码授权 |
|
||||
| OTP 二次验证 | 首次登录后绑定，之后每次登录需输入 OTP 验证码 |
|
||||
|
||||
### 1.2 首次登录流程
|
||||
|
||||
1. 打开坐席工作台 URL
|
||||
2. 使用企业微信扫描二维码
|
||||
3. 首次登录需绑定 OTP：扫描页面显示的二维码到认证 APP（如腾讯会议、Microsoft Authenticator 等）
|
||||
4. 输入 OTP 验证码完成绑定
|
||||
5. 登录成功，进入工作台
|
||||
|
||||
### 1.3 后续登录流程
|
||||
|
||||
1. 打开坐席工作台 URL
|
||||
2. 企微扫码授权
|
||||
3. 输入 OTP 验证码
|
||||
4. 登录成功
|
||||
|
||||
---
|
||||
|
||||
## 二、会话管理
|
||||
|
||||
### 2.1 会话列表
|
||||
|
||||
- 左侧栏显示当前在线员工的会话列表
|
||||
- 按最新消息时间排序
|
||||
- 显示员工姓名、最后一条消息摘要、等待时间
|
||||
|
||||
### 2.2 接单与会话
|
||||
|
||||
- 员工发起咨询后，会话进入「待接单」队列
|
||||
- 坐席点击「接单」按钮开始服务
|
||||
- 接单后会话状态变为「进行中」
|
||||
|
||||
### 2.3 会话转移
|
||||
|
||||
- 支持将会话转移给其他坐席
|
||||
- 点击会话右上角「转移」按钮，选择目标坐席
|
||||
- 转移后原坐席自动退出会话
|
||||
|
||||
### 2.4 结单
|
||||
|
||||
- 服务完成后，点击「结单」按钮结束会话
|
||||
- 系统会弹出满意度评价卡片，邀请员工评价
|
||||
|
||||
---
|
||||
|
||||
## 三、群聊与摇人
|
||||
|
||||
### 3.1 四种角色
|
||||
|
||||
| 角色 | 说明 | 权限 |
|
||||
|------|------|------|
|
||||
| 发起人 | 创建会话的人 | 最高权限，可踢人、转让管理员 |
|
||||
| 管理员 | 被授予管理权限的人 | 可踢人、修改群信息 |
|
||||
| 普通成员 | 参与会话的人 | 正常发言、接收消息 |
|
||||
| 观察者 | 仅接收消息，不可见回复框 | 只读模式 |
|
||||
|
||||
### 3.2 摇人（请求协助）
|
||||
|
||||
- 当坐席遇到疑难问题时，可点击「摇人」按钮请求其他坐席协助
|
||||
- 被摇到的坐席会收到通知
|
||||
- 双方进入同一会话，共同处理
|
||||
|
||||
### 3.3 邀请其他人
|
||||
|
||||
- 点击会话右侧「+ 邀请」按钮
|
||||
- 可选择邀请其他坐席或外部人员
|
||||
- 邀请时需选择角色（普通成员 / 观察者）
|
||||
|
||||
---
|
||||
|
||||
## 四、AI 辅助功能
|
||||
|
||||
### 4.1 智能推荐
|
||||
|
||||
- AI 会根据员工问题自动推荐解决方案
|
||||
- 推荐内容显示在右侧栏「智能推荐」标签页
|
||||
- 点击推荐项可直接发送给员工
|
||||
|
||||
### 4.2 上下文感知诊断
|
||||
|
||||
- AI 自动分析对话上下文，识别问题类型
|
||||
- 三层诊断：症状 → 原因 → 解决方案
|
||||
- 排队过程中员工可答题加速诊断
|
||||
|
||||
### 4.3 修复闭环
|
||||
|
||||
- AI 提供修复步骤后，跟踪员工是否完成修复
|
||||
- 五种关闭场景：员工确认解决 / 员工超时未响应 / 坐席手动关闭 / 重复问题 / 转人工
|
||||
|
||||
### 4.4 知识库检索
|
||||
|
||||
- 点击右侧栏「知识库」标签页
|
||||
- 可手动搜索相关知识
|
||||
- 搜索结果可直接发送给员工
|
||||
|
||||
---
|
||||
|
||||
## 五、消息发送
|
||||
|
||||
### 5.1 文字消息
|
||||
|
||||
- 在底部输入框输入文字
|
||||
- 按 Enter 发送，Shift+Enter 换行
|
||||
|
||||
### 5.2 图片消息
|
||||
|
||||
- 点击输入框左侧「图片」图标
|
||||
- 选择本地图片发送
|
||||
|
||||
### 5.3 截图消息
|
||||
|
||||
- 点击输入框左侧「截图」图标（或使用快捷键）
|
||||
- 截取屏幕后自动插入输入框
|
||||
- 发送后员工可见
|
||||
|
||||
### 5.4 语音转文字
|
||||
|
||||
| 终端 | 方式 |
|
||||
|------|------|
|
||||
| 手机端（H5） | 长按语音按钮说话，自动转文字 |
|
||||
| PC 端（坐席） | 点击「语音」按钮说话，自动转文字（百度 ASR） |
|
||||
|
||||
### 5.5 文件消息
|
||||
|
||||
- 点击输入框左侧「文件」图标
|
||||
- 选择本地文件发送
|
||||
|
||||
---
|
||||
|
||||
## 六、审批处理
|
||||
|
||||
### 6.1 审批类型
|
||||
|
||||
系统支持 12 种审批类型，共 18 个审批流程：
|
||||
|
||||
| 类别 | 审批类型 |
|
||||
|------|----------|
|
||||
| IT 类 | 软件安装、权限申请、账号申请、设备领用 |
|
||||
| 行政类 | 加班申请、请假申请 |
|
||||
| 财务类 | 报销申请 |
|
||||
| 其他 | ... |
|
||||
|
||||
### 6.2 审批操作
|
||||
|
||||
- AI 识别员工意图后，自动转接对应审批流程
|
||||
- 坐席可查看审批详情、催促审批、驳回或通过
|
||||
|
||||
### 6.3 三级意图识别
|
||||
|
||||
- **一级意图**：判断员工要做什么（报修 / 咨询 / 审批）
|
||||
- **二级意图**：具体类型（软件安装 / 网络问题 / 加班审批）
|
||||
- **三级意图**：具体事项（安装 Photoshop / 无法连接 VPN）
|
||||
|
||||
---
|
||||
|
||||
## 七、历史会话查询
|
||||
|
||||
### 7.1 功能位置
|
||||
|
||||
- 打开员工会话窗口
|
||||
- 在 UserInfoBar（员工信息栏）的等级 chips 后方
|
||||
- 点击「历史会话」开关按钮
|
||||
|
||||
### 7.2 功能说明
|
||||
|
||||
- 开启后，会显示该员工所有历史会话的消息
|
||||
- 不同会话之间显示分隔条，包含首条消息摘要（前20字）
|
||||
- 当前会话的分隔条会高亮显示，并标注「当前会话」
|
||||
- 支持滚动懒加载更多历史消息
|
||||
|
||||
### 7.3 使用场景
|
||||
|
||||
- 员工再次咨询时，坐席可快速查看该员工的历史问题记录
|
||||
- 了解员工此前是否已解决相同问题
|
||||
- 避免重复解答，提升服务效率
|
||||
|
||||
---
|
||||
|
||||
## 八、其他功能
|
||||
|
||||
### 8.1 IT 资产推送
|
||||
|
||||
- 员工咨询涉及电脑、软件等问题时
|
||||
- AI 自动推送相关 IT 资产信息（电脑配置、软件清单等）
|
||||
- 显示在右侧栏「资产」标签页
|
||||
|
||||
### 8.2 代办事项
|
||||
|
||||
- 员工提交的待处理事项
|
||||
- 显示在左侧栏「待办」标签页
|
||||
- 支持查看详情、标记完成、设置提醒
|
||||
|
||||
### 8.3 会议室预定
|
||||
|
||||
- 员工可通过 H5 端预定会议室
|
||||
- 坐席可查看会议室预定情况
|
||||
- 支持小鱼易联终端联动
|
||||
|
||||
---
|
||||
|
||||
## 附录：快捷键
|
||||
|
||||
| 快捷键 | 功能 |
|
||||
|--------|------|
|
||||
| Ctrl + Enter | 发送消息 |
|
||||
| Ctrl + S | 截图 |
|
||||
| Ctrl + K | 打开快捷搜索 |
|
||||
| Esc | 关闭弹窗 |
|
||||
|
||||
---
|
||||
|
||||
## 版本历史
|
||||
|
||||
| 版本 | 日期 | 变更 |
|
||||
|------|------|------|
|
||||
| v1.0 | 2026-07-13 | 初始版本，包含所有已上线功能 |
|
||||
@@ -2,11 +2,11 @@
|
||||
|
||||
> **文档版本**: v2.2 (综合版)
|
||||
> **创建日期**: 2025-07-11
|
||||
> **最近更新**: 2026-07-11
|
||||
> **最近更新**: 2026-07-17
|
||||
> **架构师**: 高见远 (Bob) / 宋献 (Simon)
|
||||
> **状态**: 正式版
|
||||
>
|
||||
> **v2.2 变更**: 新增 §15.8 坐席端AI辅助消息框与布局优化；更新 §7.2 坐席工作台模块布局参数；更新 §8 AI Wingman 设计新增能力
|
||||
> **v2.2 变更**: 新增 §15.8 坐席端AI辅助消息框与布局优化；更新 §7.2 坐席工作台模块布局参数；更新 §8 AI Wingman 设计新增能力；新增 §15.4.9 ITSM 工单跳转交互与鉴权限制（桥接页 + 扫码登录定为人机校验）
|
||||
|
||||
---
|
||||
|
||||
@@ -747,6 +747,8 @@ IT服务台 H5 (itsupport.servyou.com.cn)
|
||||
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 端点
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
@@ -762,6 +764,50 @@ IT服务台 H5 (itsupport.servyou.com.cn)
|
||||
|
||||
> **路由说明**：后端路由直接挂在根路径（如 `/approval/templates`），nginx 代理时 strip `/api/` 前缀，前端请求 `/api/approval/templates`。
|
||||
|
||||
#### 15.4.9 ITSM 工单跳转交互与鉴权限制（2026-07-17 更新）
|
||||
|
||||
> **关联 PRD**: `docs/02-产品需求/IT智能服务台-产品需求文档PRD-v2.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
|
||||
@@ -1176,6 +1222,7 @@ Workspace.vue
|
||||
| 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 免登录适用边界 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,260 @@
|
||||
# 会话存档功能 - 技术方案
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-15 | **状态**: 已完成
|
||||
|
||||
---
|
||||
|
||||
## 1. 架构设计
|
||||
|
||||
### 1.1 整体架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ IT 智能服务台架构 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ H5 员工端 │ │ 坐席端 │ │ 管理后台 │ │
|
||||
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
|
||||
│ │ │ │ │
|
||||
│ └──────────────┼──────────────┘ │
|
||||
│ │ │
|
||||
│ ┌───────▼───────┐ │
|
||||
│ │ Nginx 入口 │ │
|
||||
│ └───────┬───────┘ │
|
||||
│ │ │
|
||||
│ ┌───────▼───────┐ │
|
||||
│ │ FastAPI 后端 │ │
|
||||
│ └───────┬───────┘ │
|
||||
│ │ │
|
||||
│ ┌────────────┼────────────┐ │
|
||||
│ │ │ │ │
|
||||
│ ┌──────▼──────┐ ┌──▼──┐ ┌──────▼──────┐ │
|
||||
│ │ 会话管理 API │ │ Dify │ │ 企微 API │ │
|
||||
│ └──────┬──────┘ └─────┘ └────────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────▼──────────────────────────────────┐ │
|
||||
│ │ PostgreSQL 数据库 │ │
|
||||
│ │ ┌────────────┐ ┌──────────────────┐ │ │
|
||||
│ │ │ conversations│ │ messages │ │ │
|
||||
│ │ │ - is_archived│ │ │ │ │
|
||||
│ │ │ - archived_at │ │ │ │ │
|
||||
│ │ └────────────┘ └──────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────▼──────────────────────────────────┐ │
|
||||
│ │ 定时任务 (crontab) │ │
|
||||
│ │ archive_sessions.py │ │
|
||||
│ └─────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 数据库设计
|
||||
|
||||
### 2.1 Conversation 表扩展
|
||||
|
||||
```python
|
||||
# backend/app/models/conversation.py
|
||||
|
||||
# 是否已归档（会话结束超过90天后自动标记）
|
||||
is_archived: Mapped[bool] = mapped_column(
|
||||
Boolean,
|
||||
nullable=False,
|
||||
default=False,
|
||||
comment="是否已归档",
|
||||
)
|
||||
|
||||
# 归档时间
|
||||
archived_at: Mapped[Optional[datetime]] = mapped_column(
|
||||
DateTime(timezone=True),
|
||||
nullable=True,
|
||||
comment="归档时间",
|
||||
)
|
||||
```
|
||||
|
||||
### 2.2 索引设计
|
||||
|
||||
```python
|
||||
__table_args__ = (
|
||||
# ... 其他索引
|
||||
Index("idx_conversations_is_archived", "is_archived"),
|
||||
Index("idx_conversations_archived_at", "archived_at"),
|
||||
)
|
||||
```
|
||||
|
||||
### 2.3 索引说明
|
||||
|
||||
| 索引名 | 字段 | 用途 |
|
||||
|--------|-----|------|
|
||||
| idx_conversations_is_archived | is_archived | 按归档状态筛选 |
|
||||
| idx_conversations_archived_at | archived_at | 按归档时间排序 |
|
||||
|
||||
---
|
||||
|
||||
## 3. API 设计
|
||||
|
||||
### 3.1 管理后台 API
|
||||
|
||||
#### 获取会话审计列表
|
||||
|
||||
```
|
||||
GET /api/admin/audit/conversations
|
||||
```
|
||||
|
||||
**请求参数**：
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| status | string | 否 | 状态筛选 |
|
||||
| is_archived | bool | 否 | 归档状态筛选 |
|
||||
| keyword | string | 否 | 关键词搜索 |
|
||||
| date_from | string | 否 | 开始日期 |
|
||||
| date_to | string | 否 | 结束日期 |
|
||||
| page | int | 否 | 页码，默认1 |
|
||||
| page_size | int | 否 | 每页条数，默认20 |
|
||||
|
||||
**响应示例**：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"data": {
|
||||
"items": [
|
||||
{
|
||||
"id": "conv-xxx",
|
||||
"employee_name": "张三",
|
||||
"status": "resolved",
|
||||
"is_archived": true,
|
||||
"archived_at": "2026-07-01T03:00:00Z",
|
||||
"created_at": "2026-03-01T10:00:00Z",
|
||||
"updated_at": "2026-03-15T15:30:00Z"
|
||||
}
|
||||
],
|
||||
"total": 100,
|
||||
"page": 1,
|
||||
"page_size": 20
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 定时归档脚本
|
||||
|
||||
### 4.1 脚本设计
|
||||
|
||||
**文件位置**：`backend/scripts/archive_sessions.py`
|
||||
|
||||
**核心逻辑**：
|
||||
|
||||
```python
|
||||
# 归档阈值（天）
|
||||
ARCHIVE_DAYS = 90
|
||||
|
||||
# 计算归档截止时间
|
||||
cutoff_date = datetime.now(timezone.utc) - timedelta(days=ARCHIVE_DAYS)
|
||||
|
||||
# 查找需要归档的会话
|
||||
stmt = select(Conversation).where(
|
||||
Conversation.status == "resolved",
|
||||
Conversation.is_archived == False,
|
||||
Conversation.updated_at < cutoff_date
|
||||
)
|
||||
```
|
||||
|
||||
### 4.2 定时任务配置
|
||||
|
||||
```bash
|
||||
# crontab 配置
|
||||
# 每天凌晨3点执行
|
||||
0 3 * * * cd /opt/wecom-it-desk/backend && python scripts/archive_sessions.py >> /var/log/itdesk-archive.log 2>&1
|
||||
```
|
||||
|
||||
### 4.3 日志输出
|
||||
|
||||
```
|
||||
[2026-07-15 03:00:00] 开始执行会话归档任务...
|
||||
[2026-07-15 03:00:00] 归档阈值: 90 天
|
||||
[2026-07-15 03:00:00] 找到 15 个需要归档的会话
|
||||
[2026-07-15 03:00:01] 成功归档 15 个会话
|
||||
[2026-07-15 03:00:01] 归档时间: 2026-07-15T03:00:01+00:00
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 前端设计
|
||||
|
||||
### 5.1 坐席端 - 历史会话过滤
|
||||
|
||||
**文件**：`frontend-agent/src/stores/conversation.ts`
|
||||
|
||||
```typescript
|
||||
// 历史会话仅显示 90 天内的已结单会话
|
||||
const HISTORY_DAYS = 90
|
||||
const historyConversations = computed(() => {
|
||||
const cutoffDate = new Date()
|
||||
cutoffDate.setDate(cutoffDate.getDate() - HISTORY_DAYS)
|
||||
const cutoffTime = cutoffDate.getTime()
|
||||
return sortedConversations.value.filter(c => {
|
||||
if (c.status !== 'resolved') return false
|
||||
const createdTime = c.created_at ? new Date(c.created_at).getTime() : 0
|
||||
return createdTime >= cutoffTime
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
### 5.2 管理后台 - 归档状态筛选
|
||||
|
||||
**文件**：`frontend-admin/src/views/SessionAudit.vue`
|
||||
|
||||
```typescript
|
||||
// 过滤条件
|
||||
const filters = reactive({
|
||||
keyword: '',
|
||||
status: '',
|
||||
is_archived: '', // 新增归档状态筛选
|
||||
})
|
||||
|
||||
// 表格列
|
||||
<el-table-column prop="is_archived" label="归档" width="80">
|
||||
<template #default="{ row }">
|
||||
<el-tag v-if="row.is_archived" type="info">已归档</el-tag>
|
||||
<span v-else>—</span>
|
||||
</template>
|
||||
</el-table-column>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 部署配置
|
||||
|
||||
### 6.1 数据库迁移
|
||||
|
||||
```bash
|
||||
# 使用 Alembic 创建迁移
|
||||
cd backend
|
||||
alembic revision --autogenerate -m "add archive fields"
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
### 6.2 定时任务部署
|
||||
|
||||
```bash
|
||||
# 复制脚本到服务器
|
||||
scp backend/scripts/archive_sessions.py sxn@10.212.189.210:/opt/wecom-it-desk/backend/scripts/
|
||||
|
||||
# 添加 crontab 任务
|
||||
crontab -e
|
||||
# 添加: 0 3 * * * cd /opt/wecom-it-desk/backend && python scripts/archive_sessions.py >> /var/log/itdesk-archive.log 2>&1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 版本历史
|
||||
|
||||
| 版本 | 日期 | 变更 |
|
||||
|------|------|------|
|
||||
| v1.0 | 2026-07-15 | 初始版本 |
|
||||
@@ -41,3 +41,61 @@
|
||||
|
||||
## 构建验证
|
||||
✅ `npx vite build` 构建成功，无编译错误
|
||||
|
||||
---
|
||||
|
||||
## 右侧栏布局调整（2026-07-17）
|
||||
|
||||
### v2.1 → v3.0 变更
|
||||
|
||||
#### 布局调整
|
||||
- **智能推荐位置**：移至自助诊断下方，保持一直显示
|
||||
- **标题样式统一**：智能推荐使用与设备信息、自助诊断相同的标题样式（图标+文字+箭头）
|
||||
|
||||
#### 智能推荐调整
|
||||
- **取消分类标签**：移除"相关推荐"、"运维提醒"、"常用资源"分区标题
|
||||
- **保留颜色区分**：仅用边框颜色区分类型
|
||||
- 🟢 绿色边框：相关推荐
|
||||
- 🟠 橙色边框：运维提醒
|
||||
- ⚪ 灰色边框：常用资源
|
||||
|
||||
#### 排队卡片调整
|
||||
- **高度压缩**：压缩至原来50%
|
||||
- **移除平台统计**：取消四宫格（总活跃/排队/服务/AI）
|
||||
- **保留内容**：排队位置、前面人数、预计等待时间、积分等级
|
||||
|
||||
#### 答题功能
|
||||
- **答题开关**：位于排队卡片标题栏右侧（绿色胶囊按钮）
|
||||
- **默认折叠**：点击答题挑战按钮展开答题区域
|
||||
- **功能**：答对题目可获得积分并靠前排队
|
||||
- **按钮名称**：答题挑战（原"答题插队"，2026-07-17修复）
|
||||
|
||||
### 调整后原型图
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────┐
|
||||
│ 💻 设备信息 ▾ │ ← 手风琴
|
||||
├──────────────────────────────────────────┤
|
||||
│ 🩺 自助诊断 ▸ │ ← 手风琴
|
||||
├──────────────────────────────────────────┤
|
||||
│ ⚡ 智能推荐 ▾ │ ← 统一标题样式
|
||||
│ ┌──────────────────────────────┐ │
|
||||
│ │ 绿色边框：相关推荐内容 │ │
|
||||
│ └──────────────────────────────┘ │
|
||||
│ ┌──────────────────────────────┐ │
|
||||
│ │ 橙色边框：运维提醒内容 │ │
|
||||
│ └──────────────────────────────┘ │
|
||||
│ ┌──────────────────────────────┐ │
|
||||
│ │ 灰色边框：常用资源内容 │ │
|
||||
│ └──────────────────────────────┘ │
|
||||
├──────────────────────────────────────────┤
|
||||
│ ⏳ 排队位置 #5 前面4人 LV.3 [答题挑战]│ ← 压缩50%
|
||||
│ ───────────────────────────────────── │
|
||||
│ [答题区域 - 默认折叠] │
|
||||
└──────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 相关组件
|
||||
- `RightPanel.vue` - 调整布局结构
|
||||
- `DynamicRecommend.vue` - 移除分类标签
|
||||
- `QueueWaiting.vue` - 压缩高度、新增答题开关
|
||||
|
||||
@@ -0,0 +1,128 @@
|
||||
# Dify 工作流 System Prompt 改造指南
|
||||
|
||||
## 改造目标
|
||||
|
||||
将 Dify 输出从 `action` 字段改为 `intent` 标签，让后端根据 intent 查询资产库生成真正的推荐卡片。
|
||||
|
||||
## 当前输出格式（需改造）
|
||||
|
||||
```json
|
||||
{
|
||||
"text": "回答文本...",
|
||||
"action": {
|
||||
"type": "approval_card",
|
||||
"title": "软件安装审批",
|
||||
"description": "申请安装 Adobe 系列软件",
|
||||
"approval_type": "software_install",
|
||||
"confidence": 0.95
|
||||
},
|
||||
"options": [...],
|
||||
"diagnosis_stage": "diagnosing"
|
||||
}
|
||||
```
|
||||
|
||||
## 目标输出格式
|
||||
|
||||
```json
|
||||
{
|
||||
"text": "给用户的回答文本（50-200字）",
|
||||
"intent": "用户意图标签",
|
||||
"need_approval": 是否需要审批入口 (true/false),
|
||||
"need_asset": 是否需要资产推荐 (true/false),
|
||||
"asset_keywords": ["关键词1", "关键词2"],
|
||||
"options": [
|
||||
{"label": "选项文字", "value": "选项值"}
|
||||
],
|
||||
"diagnosis_stage": "greeting|diagnosing|resolved|transfer"
|
||||
}
|
||||
```
|
||||
|
||||
## 改造步骤
|
||||
|
||||
### 1. 登录 Dify Console
|
||||
|
||||
访问：`http://yw-dify.dc.servyou-it.com/console`
|
||||
|
||||
### 2. 找到目标应用
|
||||
|
||||
找到「智能IT支持-员工咨询」应用（App ID: `8f0f3d62-f63d-4cf3-815e-b10529c66f1d`）
|
||||
|
||||
### 3. 进入工作流编辑
|
||||
|
||||
1. 点击应用名称进入详情
|
||||
2. 点击「编辑」
|
||||
3. 进入「编排」页面
|
||||
|
||||
### 4. 找到 LLM 节点
|
||||
|
||||
找到输出 JSON 结构的 LLM 节点（通常在"开始"节点之后的第一个 LLM 节点）
|
||||
|
||||
### 5. 修改 System Prompt
|
||||
|
||||
在 LLM 节点的「系统提示词」中添加以下内容（追加到现有 Prompt 末尾）：
|
||||
|
||||
```
|
||||
## 输出格式要求
|
||||
|
||||
你是一个 IT 智能助手。请根据用户问题，输出以下 JSON 结构：
|
||||
|
||||
{
|
||||
"text": "给用户的回答文本（50-200字）",
|
||||
"intent": "用户意图标签",
|
||||
"need_approval": 是否需要审批入口 (true/false),
|
||||
"need_asset": 是否需要资产推荐 (true/false),
|
||||
"asset_keywords": ["关键词1", "关键词2"],
|
||||
"options": [
|
||||
{"label": "选项文字", "value": "选项值"}
|
||||
],
|
||||
"diagnosis_stage": "greeting|diagnosing|resolved|transfer"
|
||||
}
|
||||
|
||||
## 意图标签说明
|
||||
|
||||
intent 字段可选值：
|
||||
- software_install: 软件安装
|
||||
- hardware_issue: 硬件问题
|
||||
- network_vpn: 网络/VPN 问题
|
||||
- printer: 打印机问题
|
||||
- account_permission: 账号权限问题
|
||||
- email_outlook: 邮箱问题
|
||||
- mobile_device: 移动设备问题
|
||||
- other: 其他问题
|
||||
|
||||
## 资产推荐规则
|
||||
|
||||
当用户询问以下内容时，设置 need_asset=true 并指定 asset_keywords：
|
||||
- VPN 相关 → asset_keywords: ["vpn"]
|
||||
- 打印机相关 → asset_keywords: ["打印机", "打印机驱动"]
|
||||
- 软件安装 → asset_keywords: ["软件安装"]
|
||||
- 邮箱问题 → asset_keywords: ["outlook", "邮箱"]
|
||||
- 账号权限 → asset_keywords: ["账号", "权限"]
|
||||
- 网络问题 → asset_keywords: ["网络", "wifi"]
|
||||
|
||||
重要：不要在 text 中推荐具体的下载链接或服务器地址，这些信息由系统根据 asset_keywords 智能匹配后推送到右侧栏。
|
||||
```
|
||||
|
||||
### 6. 发布工作流
|
||||
|
||||
点击右上角「发布」按钮
|
||||
|
||||
### 7. 验证
|
||||
|
||||
在「发布」页面点击「运行」测试，验证输出格式是否符合预期。
|
||||
|
||||
## 回滚方案
|
||||
|
||||
如果新版本有问题，可以在 Dify Console 的「版本历史」中找到上一个版本，点击「恢复」即可回滚。
|
||||
|
||||
## 后端适配
|
||||
|
||||
后端代码 `asset_recommend_service.py` 已支持处理新的 `intent` 格式。
|
||||
|
||||
当 Dify 返回 `need_asset=true` + `asset_keywords` 时，后端会根据关键词查询 `assets.yaml` 中的资产信息，生成 L1 推荐卡片。
|
||||
|
||||
## 预期效果
|
||||
|
||||
用户说"VPN 连不上"：
|
||||
- **中间栏**：AI 回复排查步骤
|
||||
- **右侧栏 L1**：VPN 相关信息（客户端下载、服务器地址、申请审批）
|
||||
@@ -0,0 +1,159 @@
|
||||
# 会话存档功能 - 操作手册
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-15 | **状态**: 已完成
|
||||
|
||||
---
|
||||
|
||||
## 1. 功能概述
|
||||
|
||||
会话存档功能用于管理 IT 智能服务台的会话历史数据，通过自动归档策略优化系统性能，同时满足合规审计需求。
|
||||
|
||||
### 1.1 核心特性
|
||||
|
||||
- **自动归档**：已结单会话超过 90 天自动标记为已归档
|
||||
- **分级存储**：热数据（90天内）/ 冷数据（90天外）
|
||||
- **审计支持**：管理后台可查看完整会话历史
|
||||
|
||||
---
|
||||
|
||||
## 2. 坐席端操作指南
|
||||
|
||||
### 2.1 历史会话显示规则
|
||||
|
||||
坐席端历史会话按以下规则显示：
|
||||
|
||||
| 层级 | 显示内容 | 位置 |
|
||||
|------|----------|------|
|
||||
| 当前会话 | 活跃会话（排队/服务中/待关闭） | 顶部"我的会话" |
|
||||
| 历史会话 | ≤90天已结单会话 | "历史会话"标签 |
|
||||
| 更久历史 | 不显示 | — |
|
||||
|
||||
### 2.2 查看更早会话
|
||||
|
||||
**问题**：坐席端看不到 90 天前的历史会话
|
||||
|
||||
**解决方案**：
|
||||
|
||||
1. 访问管理后台
|
||||
2. 进入「会话审计」页面
|
||||
3. 使用筛选功能查找历史会话
|
||||
|
||||
---
|
||||
|
||||
## 3. 管理后台操作指南
|
||||
|
||||
### 3.1 访问会话审计
|
||||
|
||||
```
|
||||
URL: https://itsupport.servyou.com.cn/itadmin/
|
||||
路径: 会话管理 → 会话审计
|
||||
```
|
||||
|
||||
### 3.2 按归档状态筛选
|
||||
|
||||
1. 进入会话审计页面
|
||||
2. 找到「归档」筛选下拉框
|
||||
3. 选择筛选条件：
|
||||
- 全部
|
||||
- 未归档
|
||||
- 已归档
|
||||
|
||||
### 3.3 查看归档会话详情
|
||||
|
||||
1. 在会话列表中找到已归档的会话（显示「已归档」标签）
|
||||
2. 点击会话行查看详情
|
||||
3. 可查看完整的会话消息历史
|
||||
|
||||
### 3.4 筛选条件组合
|
||||
|
||||
| 场景 | 状态 | 归档 | 日期范围 |
|
||||
|------|------|------|----------|
|
||||
| 查看所有历史会话 | resolved | 全部 | — |
|
||||
| 查看近期会话 | resolved | 未归档 | 近90天 |
|
||||
| 查看归档会话 | resolved | 已归档 | 90天前 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 运维操作指南
|
||||
|
||||
### 4.1 定时任务配置
|
||||
|
||||
归档脚本通过 crontab 定时执行：
|
||||
|
||||
```bash
|
||||
# 编辑 crontab
|
||||
crontab -e
|
||||
|
||||
# 添加以下行（每天凌晨3点执行）
|
||||
0 3 * * * cd /opt/wecom-it-desk/backend && python scripts/archive_sessions.py >> /var/log/itdesk-archive.log 2>&1
|
||||
```
|
||||
|
||||
### 4.2 手动执行归档
|
||||
|
||||
```bash
|
||||
# SSH 到服务器
|
||||
ssh sxn@10.212.189.210
|
||||
|
||||
# 进入后端目录
|
||||
cd /opt/wecom-it-desk/backend
|
||||
|
||||
# 执行归档脚本
|
||||
python scripts/archive_sessions.py
|
||||
```
|
||||
|
||||
### 4.3 查看归档日志
|
||||
|
||||
```bash
|
||||
# 查看归档日志
|
||||
tail -f /var/log/itdesk-archive.log
|
||||
|
||||
# 查看历史归档记录
|
||||
cat /var/log/itdesk-archive.log | grep归档
|
||||
```
|
||||
|
||||
### 4.4 日志示例
|
||||
|
||||
```
|
||||
[2026-07-15 03:00:00] 开始执行会话归档任务...
|
||||
[2026-07-15 03:00:00] 归档阈值: 90 天
|
||||
[2026-07-15 03:00:00] 找到 15 个需要归档的会话
|
||||
[2026-07-15 03:00:01] 成功归档 15 个会话
|
||||
[2026-07-15 03:00:01] 归档时间: 2026-07-15T03:00:01+00:00
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 常见问题
|
||||
|
||||
### 5.1 坐席端看不到历史会话
|
||||
|
||||
**原因**：会话已超过 90 天，已自动归档
|
||||
|
||||
**解决**：到管理后台查看
|
||||
|
||||
### 5.2 归档状态筛选不生效
|
||||
|
||||
**检查**：
|
||||
|
||||
1. 确认筛选条件填写正确
|
||||
2. 尝试清除筛选条件查看全部
|
||||
|
||||
### 5.3 归档脚本执行失败
|
||||
|
||||
**常见原因**：
|
||||
|
||||
1. 数据库连接失败
|
||||
2. Python 依赖缺失
|
||||
|
||||
**解决**：
|
||||
|
||||
1. 检查数据库配置
|
||||
2. 确认已安装依赖：`pip install -r requirements.txt`
|
||||
|
||||
---
|
||||
|
||||
## 6. 版本历史
|
||||
|
||||
| 版本 | 日期 | 变更 |
|
||||
|------|------|------|
|
||||
| v1.0 | 2026-07-15 | 初始版本 |
|
||||
@@ -0,0 +1,504 @@
|
||||
# 测试方法论指南
|
||||
|
||||
> **版本**: v1.0 | **生效日期**: 2026-07-14 | **维护人**: Duckula
|
||||
>
|
||||
> 本规范定义 IT 智能服务台项目的测试策略、方法和流程。
|
||||
|
||||
---
|
||||
|
||||
## 1. 测试类型定义
|
||||
|
||||
### 1.1 测试分层模型
|
||||
|
||||
| 层级 | 测试类型 | 覆盖范围 | 工具/方法 | 产出物 |
|
||||
|------|---------|---------|----------|--------|
|
||||
| **Tier 0** | 基础设施测试 | 数据库、缓存、核心服务、工具类 | pytest 单元测试 | `test_*.py` |
|
||||
| **Tier 1** | API 层测试 | 接口正确性、参数校验、权限控制 | pytest + curl | `test_*.py` |
|
||||
| **Tier 2** | 集成测试 | 多模块交互、状态机、事务一致性 | pytest | `test_*.py` |
|
||||
| **E2E** | 端到端测试 | 完整业务流程、用户体验 | Playwright 浏览器自动化 | 测试报告 + 截图 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 测试类型选择标准
|
||||
|
||||
### 2.1 判断决策树
|
||||
|
||||
```
|
||||
新增功能/代码变更
|
||||
│
|
||||
├── 仅修改工具类 / 工具函数 / 算法逻辑
|
||||
│ └── 选择：Tier 0 单元测试
|
||||
│ └── 判断标准：无外部依赖，纯函数逻辑
|
||||
│
|
||||
├── 新增/修改 API 接口
|
||||
│ └── 选择：Tier 1 API 测试
|
||||
│ └── 判断标准：有 HTTP 端点、需要参数校验
|
||||
│
|
||||
├── 多模块交互 / 状态流转 / 事务一致性
|
||||
│ └── 选择：Tier 2 集成测试
|
||||
│ └── 判断标准：涉及 2+ 服务/模块的数据流转
|
||||
│
|
||||
└── 核心业务流程 / 用户体验验证
|
||||
└── 选择：E2E 测试
|
||||
└── 判断标准：需要浏览器真实操作、多端交互
|
||||
```
|
||||
|
||||
### 2.2 场景速查表
|
||||
|
||||
| 场景 | 推荐测试类型 | 必做级别 |
|
||||
|------|-------------|---------|
|
||||
| 新增工具函数（如 TokenCounter） | Tier 0 | 必须 |
|
||||
| 新增 API 端点 | Tier 1 | 必须 |
|
||||
| 修改数据库模型/迁移脚本 | Tier 0 + Tier 1 | 必须 |
|
||||
| 修改 WebSocket 逻辑 | Tier 2 | 必须 |
|
||||
| 修改前端交互流程 | E2E | 必须 |
|
||||
| 登录/认证流程变更 | E2E + Tier 1 | 必须 |
|
||||
| 消息发送/AI 回复流程 | E2E | 必须 |
|
||||
| 知识库/审批流程 | Tier 1 + Tier 2 | 必须 |
|
||||
| 安全/权限控制变更 | Tier 1 + E2E | 必须 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 产出物标准
|
||||
|
||||
### 3.1 测试用例文档模板
|
||||
|
||||
每个功能测试用例文档应包含：
|
||||
|
||||
```markdown
|
||||
# [功能名称] 测试用例
|
||||
|
||||
> **功能模块**: xxx | **测试工程师**: xxx | **日期**: xxx
|
||||
|
||||
## 1. 测试范围
|
||||
- 测试的 API/模块列表
|
||||
|
||||
## 2. 前置条件
|
||||
- 测试账号、环境要求、依赖服务
|
||||
|
||||
## 3. 测试用例清单
|
||||
|
||||
| TC_ID | 场景 | 前置条件 | 测试步骤 | 预期结果 | 状态 |
|
||||
|-------|------|---------|---------|---------|------|
|
||||
| xxx | | | | | |
|
||||
|
||||
## 4. 测试数据
|
||||
- 测试用账号、测试数据构造方式
|
||||
|
||||
## 5. 执行记录
|
||||
|
||||
| 日期 | 测试人员 | 环境 | 结果 |
|
||||
|------|---------|------|------|
|
||||
| | | | |
|
||||
|
||||
## 6. 缺陷记录
|
||||
|
||||
| 缺陷ID | 对应TC | 描述 | 严重程度 | 状态 |
|
||||
|--------|--------|------|----------|------|
|
||||
| | | | | |
|
||||
```
|
||||
|
||||
### 3.2 测试报告模板
|
||||
|
||||
```markdown
|
||||
# [版本/功能] 测试报告
|
||||
|
||||
> **测试工程师**: xxx | **日期**: xxx | **状态**: 通过/失败
|
||||
|
||||
## 测试概览
|
||||
- 测试总数、通过数、失败数、跳过数
|
||||
|
||||
## 测试明细
|
||||
| 用例类型 | 数量 | 通过 | 失败 |
|
||||
|----------|------|------|------|
|
||||
| | | | |
|
||||
|
||||
## Bug 历程
|
||||
| Bug ID | 描述 | 影响 | 修复状态 |
|
||||
|
||||
## 结论
|
||||
- 是否可发布
|
||||
- 风险项
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 流程规范
|
||||
|
||||
### 4.1 新功能上线流程
|
||||
|
||||
```
|
||||
需求评审通过
|
||||
│
|
||||
├── 1. 编写测试用例文档
|
||||
│ └── 路径: docs/06-测试质量/03-功能测试用例/
|
||||
│ └── 命名: [功能名]-测试用例-YYYYMMDD.md
|
||||
│
|
||||
├── 2. 开发代码
|
||||
│
|
||||
├── 3. 执行测试
|
||||
│ ├── Tier 0/1/2 → pytest
|
||||
│ └── E2E → Playwright
|
||||
│
|
||||
├── 4. 产出测试报告
|
||||
│ └── 路径: docs/06-测试质量/04-版本测试报告/
|
||||
│ └── 命名: [功能名]-测试报告-YYYYMMDD.md
|
||||
│
|
||||
└── 5. 发布
|
||||
```
|
||||
|
||||
**强制要求**：
|
||||
- 测试用例文档必须在代码开发前完成初版
|
||||
- 测试用例文档必须随功能上线同步更新
|
||||
- 测试报告是发布的必要前置条件
|
||||
|
||||
### 4.2 故障修复后流程
|
||||
|
||||
```
|
||||
故障发现 → 根因分析 → 修复代码
|
||||
│
|
||||
├── 1. 定位受影响的测试用例
|
||||
│ └── 在 docs/06-测试质量/ 中搜索相关功能
|
||||
│
|
||||
├── 2. 编写/更新自动化测试
|
||||
│ └── 在 backend/tests/ 中添加/更新 test_*.py
|
||||
│
|
||||
├── 3. 执行自动化测试
|
||||
│ └── pytest -v
|
||||
│
|
||||
├── 4. 如有 E2E 场景，补充 E2E 测试
|
||||
│ └── Playwright 浏览器自动化
|
||||
│
|
||||
└── 5. 更新测试用例文档
|
||||
└── 补充故障场景用例
|
||||
```
|
||||
|
||||
**强制要求**：
|
||||
- 故障修复后必须补充相关自动化测试
|
||||
- 测试通过才能宣布故障关闭
|
||||
|
||||
### 4.3 历史功能检查流程
|
||||
|
||||
```
|
||||
定期检查（建议每季度）
|
||||
│
|
||||
├── 1. 列出所有已上线功能
|
||||
│ └── 参考 CHANGELOG.md / 版本发布记录
|
||||
│
|
||||
├── 2. 检查是否存在测试用例文档
|
||||
│ └── docs/06-测试质量/03-功能测试用例/
|
||||
│
|
||||
├── 3. 如缺失，补充测试用例文档
|
||||
│ └── 逆向分析功能 → 编写测试用例
|
||||
│
|
||||
├── 4. 检查测试用例是否仍有效
|
||||
│ ├── 接口路径是否变更
|
||||
│ ├── 参数是否变化
|
||||
│ └── 功能是否已废弃
|
||||
│
|
||||
├── 5. 处理废弃/替换的功能用例
|
||||
│ ├── 移动到 docs/11-历史归档/
|
||||
│ └── 更新 README.md 中的索引
|
||||
│
|
||||
└── 6. 产出检查报告
|
||||
```
|
||||
|
||||
**强制要求**：
|
||||
- 缺失测试用例的功能必须补齐
|
||||
- 废弃功能必须从测试用例目录移除或标注
|
||||
|
||||
---
|
||||
|
||||
## 5. 目录结构规范
|
||||
|
||||
```
|
||||
docs/06-测试质量/
|
||||
├── 00-测试规范/ # 本文档
|
||||
│ └── 测试方法论指南.md
|
||||
│
|
||||
├── 01-综合报告/ # 合并汇总类报告
|
||||
│ └── QA_COMPREHENSIVE_REPORT.md
|
||||
│
|
||||
├── 02-E2E测试/ # 端到端测试
|
||||
│ ├── E2E-CHECKLIST-*.md # 验收清单
|
||||
│ └── e2e-screenshots/ # 截图证据
|
||||
│
|
||||
├── 03-功能测试用例/ # 功能级测试用例文档
|
||||
│ ├── [功能名]-测试用例-YYYYMMDD.md
|
||||
│ └── ...
|
||||
│
|
||||
├── 04-版本测试报告/ # 按版本/日期的测试报告
|
||||
│ └── [功能名]-测试报告-YYYYMMDD.md
|
||||
│
|
||||
└── README.md # 分类索引
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 命名约定
|
||||
|
||||
| 类型 | 命名格式 | 示例 |
|
||||
|------|---------|------|
|
||||
| 测试用例文档 | `[功能名]-测试用例-YYYYMMDD.md` | `OTP绑定-测试用例-20260708.md` |
|
||||
| 测试报告 | `[功能名]-测试报告-YYYYMMDD.md` | `登录功能-测试报告-20260706.md` |
|
||||
| E2E 报告 | `[功能名]-E2E验证报告-YYYYMMDD.md` | `方案A消息发送延时-E2E验证报告-20260708.md` |
|
||||
| 测试代码文件 | `test_[模块名].py` | `test_otp_bind_flow.py` |
|
||||
|
||||
---
|
||||
|
||||
## 7. 质量门禁
|
||||
|
||||
### 7.1 发布门槛
|
||||
|
||||
| 测试类型 | 通过率要求 | 备注 |
|
||||
|---------|-----------|------|
|
||||
| Tier 0 | 100% | 基础设施不能有失败 |
|
||||
| Tier 1 | 100% | API 必须全部通过 |
|
||||
| Tier 2 | 100% | 集成测试必须通过 |
|
||||
| E2E | 核心流程 100% | 核心用户流程不可失败 |
|
||||
|
||||
### 7.2 阻断规则
|
||||
|
||||
- **P0 级别故障**：必须通过 E2E 验证才能发布
|
||||
- **认证/安全变更**：必须通过 Tier 1 + E2E 双重验证
|
||||
- **数据库变更**：必须通过 Tier 0 迁移测试
|
||||
|
||||
---
|
||||
|
||||
## 8. 测试数据管理规范
|
||||
|
||||
### 8.1 数据分类
|
||||
|
||||
| 数据类型 | 说明 | 管理方式 |
|
||||
|---------|------|---------|
|
||||
| **测试账号** | 坐席员工、管理员测试账号 | 固定账号，维护在配置文件中 |
|
||||
| **Mock 数据** | 模拟的会话、消息、审批数据 | 代码中 fixtures 或独立 seed 文件 |
|
||||
| **生产脱敏数据** | 从生产导出的脱敏数据 | 存储在 `data/test/` 目录，严格访问控制 |
|
||||
| **临时测试数据** | 每次测试生成的临时数据 | 测试用例自行清理，禁用手动清理 |
|
||||
|
||||
### 8.2 测试数据原则
|
||||
|
||||
- **隔离性**：每个测试用例使用独立数据，不依赖其他测试的执行结果
|
||||
- **可重复性**：测试数据可重复使用，测试结果一致
|
||||
- **清理机制**：测试完成后自动清理临时数据，不污染环境
|
||||
- **脱敏要求**：从生产导出的数据必须脱敏（手机号、身份证号等）
|
||||
|
||||
### 8.3 测试数据目录结构
|
||||
|
||||
```
|
||||
data/test/
|
||||
├── README.md # 数据说明
|
||||
├── accounts.json # 测试账号配置
|
||||
├── mock_sessions.json # Mock 会话数据
|
||||
└── seed/ # 数据种子文件
|
||||
├── conversations.json
|
||||
└── knowledge.json
|
||||
```
|
||||
|
||||
### 8.4 测试账号规范
|
||||
|
||||
| 角色 | user_id | 用途 |
|
||||
|------|---------|------|
|
||||
| 管理员 | `sxn` | 管理员功能测试 |
|
||||
| 坐席 | `sxn` | 坐席功能测试 |
|
||||
| 员工 | `test_user` | 员工端功能测试 |
|
||||
| Mock 用户 | `E2E_BROWSER` | E2E 自动化测试 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 测试环境配置标准
|
||||
|
||||
### 9.1 环境分类
|
||||
|
||||
| 环境 | 用途 | 数据库 | 特点 |
|
||||
|------|------|--------|------|
|
||||
| **开发环境** | 本地开发调试 | SQLite 内存 | 快速启动，无持久化 |
|
||||
| **测试环境** | 自动化测试 | PostgreSQL | 与生产结构一致 |
|
||||
| **预发布环境** | 上线前验证 | 生产数据副本 | 接近生产 |
|
||||
| **生产环境** | 正式运行 | PostgreSQL | 真实数据 |
|
||||
|
||||
### 9.2 环境配置要求
|
||||
|
||||
#### 9.2.1 开发环境
|
||||
|
||||
```bash
|
||||
# .env 配置示例
|
||||
DEV_MODE=true
|
||||
DATABASE_URL=sqlite:///./test_dev.db
|
||||
REDIS_URL=redis://localhost:6379
|
||||
# 使用 Mock 服务，无需真实企微/Dify
|
||||
```
|
||||
|
||||
#### 9.2.2 测试环境
|
||||
|
||||
```bash
|
||||
# .env 配置示例
|
||||
DEV_MODE=false
|
||||
DATABASE_URL=postgresql://test:test@localhost:5432/wecom_it_test
|
||||
REDIS_URL=redis://localhost:6379/1
|
||||
# 使用测试用企微应用/测试用 Dify
|
||||
WECOM_APP_ID=xxx
|
||||
DIFY_API_KEY=xxx
|
||||
```
|
||||
|
||||
### 9.3 环境切换规则
|
||||
|
||||
| 场景 | 使用环境 | 理由 |
|
||||
|------|---------|------|
|
||||
| 单元测试 (Tier 0) | 开发环境 (SQLite) | 快速、独立 |
|
||||
| API 测试 (Tier 1) | 测试环境 | 验证真实数据库 |
|
||||
| 集成测试 (Tier 2) | 测试环境 | 多模块交互 |
|
||||
| E2E 测试 | 测试/预发布环境 | 接近生产 |
|
||||
| 上线前验证 | 预发布环境 | 最终确认 |
|
||||
|
||||
### 9.4 环境健康检查
|
||||
|
||||
每次测试执行前必须检查：
|
||||
|
||||
- [ ] 数据库连接正常
|
||||
- [ ] Redis 连接正常
|
||||
- [ ] 后端服务可访问
|
||||
- [ ] 依赖服务（Dify、RAGFlow 等）可用
|
||||
|
||||
---
|
||||
|
||||
## 10. CI/CD 集成测试规范
|
||||
|
||||
### 10.1 流水线阶段
|
||||
|
||||
```
|
||||
代码提交 → 静态检查 → 单元测试 → 构建 → 集成测试 → E2E测试 → 部署
|
||||
↓ ↓ ↓
|
||||
Tier 0 Tier 1/2 需要时
|
||||
```
|
||||
|
||||
### 10.2 各阶段要求
|
||||
|
||||
#### 10.2.1 静态检查阶段
|
||||
|
||||
| 检查项 | 工具 | 失败处理 |
|
||||
|--------|------|---------|
|
||||
| Python 类型检查 | mypy | 阻断 |
|
||||
| 代码格式 | ruff / black | 阻断 |
|
||||
| 安全扫描 | bandit | 阻断 |
|
||||
|
||||
#### 10.2.2 单元测试阶段 (Tier 0)
|
||||
|
||||
```yaml
|
||||
# .github/workflows/test.yml 示意
|
||||
- name: Run Tier 0 tests
|
||||
run: |
|
||||
pytest backend/tests/test_*.py -v --tb=short
|
||||
timeout-minutes: 10
|
||||
```
|
||||
|
||||
**要求**：
|
||||
- 必须通过
|
||||
- 覆盖率不做强制要求，但核心模块应覆盖
|
||||
|
||||
#### 10.2.3 集成测试阶段 (Tier 1/2)
|
||||
|
||||
```yaml
|
||||
- name: Run Tier 1/2 tests
|
||||
run: |
|
||||
pytest backend/tests/test_api_*.py -v --tb=short
|
||||
timeout-minutes: 20
|
||||
services:
|
||||
postgres:
|
||||
image: postgres:15
|
||||
env:
|
||||
POSTGRES_DB: wecom_it_test
|
||||
redis:
|
||||
image: redis:7
|
||||
```
|
||||
|
||||
**要求**：
|
||||
- 使用独立的测试数据库
|
||||
- 测试完成后清理数据
|
||||
|
||||
#### 10.2.4 E2E 测试阶段
|
||||
|
||||
```yaml
|
||||
- name: Run E2E tests
|
||||
run: |
|
||||
pytest tests/e2e/ -v --tb=short
|
||||
timeout-minutes: 30
|
||||
conditions: ${{ github.event_name == 'pull_request' }}
|
||||
```
|
||||
|
||||
**要求**：
|
||||
- 仅在 PR 时执行
|
||||
- 生产部署后可通过手动触发
|
||||
|
||||
### 10.3 分支策略
|
||||
|
||||
| 分支 | 执行测试 | 部署目标 |
|
||||
|------|---------|---------|
|
||||
| feature/* | Tier 0 + Tier 1 | 不自动部署 |
|
||||
| bugfix/* | Tier 0 + Tier 1 | 不自动部署 |
|
||||
| main | 全部 Tier | 自动部署到测试环境 |
|
||||
| release/* | 全部 Tier + E2E | 预发布环境 |
|
||||
|
||||
### 10.4 失败处理
|
||||
|
||||
| 失败类型 | 处理方式 |
|
||||
|---------|---------|
|
||||
| Tier 0 失败 | 阻断合并 |
|
||||
| Tier 1/2 失败 | 阻断合并 |
|
||||
| E2E 失败 | 警告，可选择是否阻断 |
|
||||
| 超时 | 重试 1 次，仍失败则阻断 |
|
||||
|
||||
---
|
||||
|
||||
## 11. 附录
|
||||
|
||||
### 11.1 测试工具清单
|
||||
|
||||
| 用途 | 工具 | 配置 |
|
||||
|------|------|------|
|
||||
| Python 单元/集成测试 | pytest + pytest-asyncio | `conftest.py` |
|
||||
| 浏览器自动化 | Playwright | Python binding |
|
||||
| HTTP 测试 | curl / httpx | 直接调用 API |
|
||||
| 数据库测试 | 直接 SQL / SQLAlchemy | 迁移脚本验证 |
|
||||
|
||||
### 11.2 配置文件模板
|
||||
|
||||
#### 11.2.1 测试配置 (pytest.ini)
|
||||
|
||||
```ini
|
||||
[pytest]
|
||||
testpaths = backend/tests
|
||||
python_files = test_*.py
|
||||
python_classes = Test*
|
||||
python_functions = test_*
|
||||
asyncio_mode = auto
|
||||
addopts = -v --tb=short
|
||||
```
|
||||
|
||||
#### 11.2.2 E2E 配置 (playwright.config.py)
|
||||
|
||||
```python
|
||||
import pytest
|
||||
|
||||
@pytest.fixture(scope="session")
|
||||
def browser_type_launch_args(browser_type_launch_args):
|
||||
return {
|
||||
**browser_type_launch_args,
|
||||
"headless": True,
|
||||
}
|
||||
```
|
||||
|
||||
### 11.3 相关文档
|
||||
|
||||
- 技术架构：`../03-技术架构/`
|
||||
- 产品需求：`../02-产品需求/`
|
||||
- 项目管理：`../10-项目管理/`
|
||||
- 历史归档：`../11-历史归档/`
|
||||
|
||||
---
|
||||
|
||||
> **修订记录**
|
||||
>
|
||||
> | 版本 | 日期 | 变更内容 | 修改人 |
|
||||
> |------|------|----------|--------|
|
||||
> | v1.0 | 2026-07-14 | 初始版本，整合测试方法、数据、环境、CI/CD规范 | Duckula |
|
||||
@@ -0,0 +1,140 @@
|
||||
# 会话存档功能 - 测试用例
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-15 | **状态**: 已完成
|
||||
|
||||
---
|
||||
|
||||
## 1. 测试范围
|
||||
|
||||
| 模块 | 测试类型 | 优先级 |
|
||||
|------|----------|--------|
|
||||
| 数据模型 | 单元测试 | P0 |
|
||||
| 归档脚本 | 单元测试 | P0 |
|
||||
| 管理后台 API | 接口测试 | P0 |
|
||||
| 坐席端显示 | 集成测试 | P1 |
|
||||
| 管理后台 UI | UI 测试 | P1 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 数据模型测试
|
||||
|
||||
### 2.1 Conversation 字段测试
|
||||
|
||||
| 用例ID | 测试场景 | 预期结果 | 优先级 |
|
||||
|--------|----------|----------|--------|
|
||||
| MODEL-01 | 创建会话时 is_archived 默认值为 false | 默认为 false | P0 |
|
||||
| MODEL-02 | 创建会话时 archived_at 默认值为 null | 默认为 null | P0 |
|
||||
| MODEL-03 | 归档会话后 is_archived 更新为 true | 值为 true | P0 |
|
||||
| MODEL-04 | 归档会话后 archived_at 记录归档时间 | 值为归档时间 | P0 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 归档脚本测试
|
||||
|
||||
### 3.1 自动归档测试
|
||||
|
||||
| 用例ID | 测试场景 | 预期结果 | 优先级 |
|
||||
|--------|----------|----------|--------|
|
||||
| SCRIPT-01 | 已结单超过90天的会话 | 自动标记为已归档 | P0 |
|
||||
| SCRIPT-02 | 已结单不足90天的会话 | 不标记为已归档 | P0 |
|
||||
| SCRIPT-03 | 未结单的会话 | 不标记为已归档 | P0 |
|
||||
| SCRIPT-04 | 已归档的会话再次执行 | 跳过已归档会话 | P0 |
|
||||
| SCRIPT-05 | 无需归档的会话执行 | 输出"没有需要归档的会话" | P0 |
|
||||
|
||||
### 3.2 归档数据准确性测试
|
||||
|
||||
| 用例ID | 测试场景 | 预期结果 | 优先级 |
|
||||
|--------|----------|----------|--------|
|
||||
| SCRIPT-06 | 归档时记录正确的归档时间 | archived_at 与当前时间误差 < 1秒 | P0 |
|
||||
| SCRIPT-07 | 批量归档多条会话 | 所有会话正确标记 | P0 |
|
||||
|
||||
### 3.3 日志测试
|
||||
|
||||
| 用例ID | 测试场景 | 预期结果 | 优先级 |
|
||||
|--------|----------|----------|--------|
|
||||
| SCRIPT-08 | 归档执行成功 | 输出归档数量统计 | P1 |
|
||||
| SCRIPT-09 | 归档执行失败 | 输出错误信息 | P1 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 管理后台 API 测试
|
||||
|
||||
### 4.1 会话列表接口
|
||||
|
||||
| 用例ID | 测试场景 | 预期结果 | 优先级 |
|
||||
|--------|----------|----------|--------|
|
||||
| API-01 | 不传 is_archived 参数 | 返回全部会话 | P0 |
|
||||
| API-02 | 传 is_archived=true | 仅返回已归档会话 | P0 |
|
||||
| API-03 | 传 is_archived=false | 仅返回未归档会话 | P0 |
|
||||
| API-04 | 组合筛选 status + is_archived | 正确筛选 | P0 |
|
||||
| API-05 | 分页参数测试 | 分页数据正确 | P1 |
|
||||
|
||||
### 4.2 响应数据结构
|
||||
|
||||
| 用例ID | 测试场景 | 预期结果 | 优先级 |
|
||||
|--------|----------|----------|--------|
|
||||
| API-06 | 获取会话列表 | 包含 is_archived 和 archived_at 字段 | P0 |
|
||||
| API-07 | 会话详情 | 归档信息正确 | P0 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 坐席端测试
|
||||
|
||||
### 5.1 历史会话显示测试
|
||||
|
||||
| 用例ID | 测试场景 | 预期结果 | 优先级 |
|
||||
|--------|----------|----------|--------|
|
||||
| AGENT-01 | 90天内的已结单会话 | 显示在历史会话中 | P0 |
|
||||
| AGENT-02 | 超过90天的已结单会话 | 不显示在历史会话中 | P0 |
|
||||
| AGENT-03 | 活跃会话 | 显示在当前会话列表 | P0 |
|
||||
|
||||
### 5.2 筛选功能测试
|
||||
|
||||
| 用例ID | 测试场景 | 预期结果 | 优先级 |
|
||||
|--------|----------|----------|--------|
|
||||
| AGENT-04 | 搜索历史会话 | 按关键词过滤 | P1 |
|
||||
| AGENT-05 | 切换筛选标签 | 正确切换显示内容 | P1 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 管理后台 UI 测试
|
||||
|
||||
### 6.1 归档状态筛选
|
||||
|
||||
| 用例ID | 测试场景 | 预期结果 | 优先级 |
|
||||
|--------|----------|----------|--------|
|
||||
| UI-01 | 选择"全部" | 显示所有会话 | P0 |
|
||||
| UI-02 | 选择"未归档" | 仅显示未归档会话 | P0 |
|
||||
| UI-03 | 选择"已归档" | 仅显示已归档会话 | P0 |
|
||||
|
||||
### 6.2 归档状态显示
|
||||
|
||||
| 用例ID | 测试场景 | 预期结果 | 优先级 |
|
||||
|--------|----------|----------|--------|
|
||||
| UI-04 | 查看未归档会话 | 显示"-"或空 | P0 |
|
||||
| UI-05 | 查看已归档会话 | 显示"已归档"标签 | P0 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 性能测试
|
||||
|
||||
| 用例ID | 测试场景 | 预期结果 | 优先级 |
|
||||
|--------|----------|----------|--------|
|
||||
| PERF-01 | 1000条会话归档 | 执行时间 < 5秒 | P1 |
|
||||
| PERF-02 | 归档期间查询会话 | 不影响在线查询 | P1 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 测试用例执行记录
|
||||
|
||||
| 执行日期 | 测试人员 | 通过数 | 失败数 | 备注 |
|
||||
|----------|----------|--------|--------|------|
|
||||
| 2026-07-15 | Duckula | — | — | 待执行 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 版本历史
|
||||
|
||||
| 版本 | 日期 | 变更 |
|
||||
|------|------|------|
|
||||
| v1.0 | 2026-07-15 | 初始版本 |
|
||||
@@ -0,0 +1,111 @@
|
||||
# 测试质量文档分类索引
|
||||
|
||||
> 本目录包含 IT 智能服务台项目的所有测试相关文档。按类型分类，便于查阅和维护。
|
||||
|
||||
---
|
||||
|
||||
## 📁 文档分类结构
|
||||
|
||||
```
|
||||
docs/06-测试质量/
|
||||
├── 00-测试规范/ # 测试方法论、流程、规范
|
||||
│ └── 测试方法论指南.md
|
||||
│
|
||||
├── 01-综合报告/ # 合并汇总类报告
|
||||
│ └── QA_COMPREHENSIVE_REPORT.md
|
||||
│
|
||||
├── 02-E2E测试/ # 端到端测试
|
||||
│ ├── E2E-CHECKLIST-v0.7.0.md # v0.7.0 验收清单（扫码登录+MFA）
|
||||
│ ├── 方案A-消息发送延时-E2E验证报告-20260708.md
|
||||
│ └── e2e-screenshots/ # 截图证据
|
||||
│ ├── 01-login.png
|
||||
│ ├── 02-chat-after-login.png
|
||||
│ ├── 03-after-send-instant.png
|
||||
│ ├── 04-typewriter-mid.png
|
||||
│ ├── 05-final.png
|
||||
│ ├── 99-error.png
|
||||
│ ├── diag.txt
|
||||
│ └── e2e_result.json
|
||||
│
|
||||
├── 03-功能测试用例/ # 具体功能测试用例
|
||||
│ ├── TESTING_CALL_AGENT.md # 呼叫坐席功能验证
|
||||
│ └── 登录功能测试用例-20260706.md
|
||||
│
|
||||
├── 04-版本测试报告/ # 按日期/版本分类
|
||||
│ ├── OTP绑定-测试报告-20260708.md # OTP 首次绑定测试
|
||||
│ ├── P0串联+P2可视化-测试报告-20260708.md
|
||||
│ ├── RBAC-BugFix-测试报告-20260707.md
|
||||
│ ├── Tier0-测试报告-20260708.md
|
||||
│ ├── Tier1-测试报告-20260708.md
|
||||
│ ├── 看板验真-测试报告-20260707.md
|
||||
│ └── 知识迭代Bug修复报告-20260711.md
|
||||
│
|
||||
└── README.md # 本文件
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 文档清单总览
|
||||
|
||||
| 分类 | 文档名称 | 测试范围 | 状态 |
|
||||
|------|---------|---------|------|
|
||||
| **测试规范** | 测试方法论指南.md | 测试策略、方法、流程、数据管理、环境配置、CI/CD规范 | ✅ 生效中 |
|
||||
| **综合报告** | QA_COMPREHENSIVE_REPORT.md | P2/P3单元测试 + WebSocket + 坐席v5.3 | ✅ 通过 |
|
||||
| **E2E测试** | E2E-CHECKLIST-v0.7.0.md | 扫码登录 + MFA + P0/P1合规验证 | ✅ 通过 |
|
||||
| **E2E测试** | 方案A-消息发送延时-E2E验证报告 | WS打字机 + 发送即时性 | ✅ 通过 |
|
||||
| **功能测试** | TESTING_CALL_AGENT.md | 呼叫坐席功能（3次AI回复后出现按钮） | ✅ 通过 |
|
||||
| **功能测试** | 登录功能测试用例-20260706.md | 企微免密 + 账号密码 + MFA | 📋 待执行 |
|
||||
| **版本报告** | OTP绑定-测试报告-20260708.md | 首次绑定 + 重置流程 | ✅ 通过 |
|
||||
| **版本报告** | Tier0-测试报告-20260708.md | 知识库迭代基础设施 | ✅ 通过 |
|
||||
| **版本报告** | Tier1-测试报告-20260708.md | API层 + 前端组件 | ✅ 通过 |
|
||||
| **版本报告** | P0串联+P2可视化-测试报告 | 会话关闭建议 + 知识图谱 | ✅ 通过 |
|
||||
| **版本报告** | RBAC-BugFix-测试报告 | admin_users装饰器修复 | ✅ 通过 |
|
||||
| **版本报告** | 看板验真-测试报告 | 5项存量功能验证 | ⚠️ 3/5通过 |
|
||||
| **版本报告** | 知识迭代Bug修复报告 | POST /suggestions + Neo4j MERGE | ✅ 通过 |
|
||||
|
||||
---
|
||||
|
||||
## 🏷️ 按标签分类
|
||||
|
||||
### 身份认证 & 安全
|
||||
- `E2E-CHECKLIST-v0.7.0.md` — 扫码登录、MFA绑定与验证
|
||||
- `登录功能测试用例-20260706.md` — 企微免密、账号密码、OTP
|
||||
- `OTP绑定-测试报告-20260708.md` — 首次绑定、管理员重置
|
||||
- `RBAC-BugFix-测试报告-20260707.md` — 权限装饰器修复
|
||||
|
||||
### 消息 & WebSocket
|
||||
- `方案A-消息发送延时-E2E验证报告-20260708.md` — 发送即时返回 + WS流式
|
||||
- `QA_COMPREHENSIVE_REPORT.md` — WebSocket 实时推送功能
|
||||
|
||||
### 知识库 & AI
|
||||
- `Tier0-测试报告-20260708.md` — Neo4j、审批状态机、置信门控
|
||||
- `Tier1-测试报告-20260708.md` — Vision、RAGFlow、审批队列、知识迭代
|
||||
- `知识迭代Bug修复报告-20260711.md` — POST端点、Neo4j MERGE、过期检查
|
||||
|
||||
### 业务功能
|
||||
- `TESTING_CALL_AGENT.md` — 呼叫坐席功能
|
||||
- `P0串联+P2可视化-测试报告-20260708.md` — 会话关闭建议、知识图谱可视化
|
||||
- `看板验真-测试报告-20260707.md` — 排队、AI Wingman、知识库、RBAC、敏感词
|
||||
|
||||
---
|
||||
|
||||
## 📊 测试统计汇总
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 测试文档总数 | 12 |
|
||||
| 单元测试用例 | 200+ |
|
||||
| E2E 测试用例 | 50+ |
|
||||
| 总通过率 | ~95% |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 关联文档
|
||||
|
||||
- 技术架构：`../03-技术架构/`
|
||||
- 产品需求：`../02-产品需求/`
|
||||
- 项目管理：`../10-项目管理/05-项目状态看板/`
|
||||
|
||||
---
|
||||
|
||||
> 最后更新：2026-07-14 | 整理人：Duckula
|
||||
@@ -0,0 +1,219 @@
|
||||
# Token多IP异常检测 - 测试用例
|
||||
|
||||
> **任务ID**: 待分配
|
||||
> **关联文档**: 技术设计-Token多IP异常检测.md
|
||||
> **测试环境**: 开发环境 / 测试环境
|
||||
|
||||
---
|
||||
|
||||
## 1. 测试概述
|
||||
|
||||
### 1.1 测试目标
|
||||
|
||||
验证Token多IP异常检测功能的正确性，确保：
|
||||
- 正常多设备使用不触发误报
|
||||
- 异常多IP使用能正确触发告警
|
||||
- 告警内容准确
|
||||
|
||||
### 1.2 测试范围
|
||||
|
||||
| 模块 | 测试内容 |
|
||||
|------|----------|
|
||||
| record_token_ip | IP记录逻辑 |
|
||||
| detect_anomaly | 异常检测逻辑 |
|
||||
| 告警发送 | 企微消息格式 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 测试用例
|
||||
|
||||
### 2.1 单元测试
|
||||
|
||||
#### T001: 单IP使用Token
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 用例ID | T001 |
|
||||
| 场景 | 同一IP多次使用Token |
|
||||
| 预置条件 | Redis中无数据 |
|
||||
| 测试步骤 | 1. 调用 record_token_ip(token="test", ip="10.0.0.1") <br> 2. 获取 token_ips:* key的SCARD值 |
|
||||
| 预期结果 | IP数量=1，不触发告警 |
|
||||
| 实际结果 | |
|
||||
| 状态 | ☐ |
|
||||
|
||||
#### T002: 3个IP使用Token (阈值)
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 用例ID | T002 |
|
||||
| 场景 | 3个不同IP使用同一Token |
|
||||
| 预置条件 | Redis中已有token_ips:test包含2个IP |
|
||||
| 测试步骤 | 1. 调用 record_token_ip(token="test", ip="10.0.0.3") <br> 2. 执行 detect_token_anomaly() <br> 3. 检查告警是否发送 |
|
||||
| 预期结果 | IP数量=3，触发告警 |
|
||||
| 实际结果 | |
|
||||
| 状态 | ☐ |
|
||||
|
||||
#### T003: 5个IP使用Token (严重)
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 用例ID | T003 |
|
||||
| 场景 | 5个不同IP使用同一Token |
|
||||
| 预置条件 | Redis中已有token_ips:test包含4个IP |
|
||||
| 测试步骤 | 1. 调用 record_token_ip(token="test", ip="10.0.0.5") <br> 2. 执行 detect_token_anomaly() |
|
||||
| 预期结果 | IP数量=5，触发告警(严重) |
|
||||
| 实际结果 | |
|
||||
| 状态 | ☐ |
|
||||
|
||||
#### T004: 同一IP多次使用
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 用例ID | T004 |
|
||||
| 场景 | 同一IP多次调用record_token_ip |
|
||||
| 预置条件 | Redis中已有token_ips:test包含1个IP |
|
||||
| 测试步骤 | 1. 调用 record_token_ip(token="test", ip="10.0.0.1") 3次 <br> 2. 获取 token_ips:test 的SCARD值 |
|
||||
| 预期结果 | IP数量仍为1(Set自动去重) |
|
||||
| 实际结果 | |
|
||||
| 状态 | ☐ |
|
||||
|
||||
#### T005: Token过期后IP清空
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 用例ID | T005 |
|
||||
| 场景 | Token过期后IP记录清空 |
|
||||
| 预置条件 | Redis中token_ips:test存在，TTL=60秒 |
|
||||
| 测试步骤 | 1. 等待TTL过期 <br> 2. 检查key是否存在 |
|
||||
| 预期结果 | key不存在(自动过期) |
|
||||
| 实际结果 | |
|
||||
| 状态 | ☐ |
|
||||
|
||||
#### T006: 重复告警抑制
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 用例ID | T006 |
|
||||
| 场景 | 同一异常Token在告警周期内再次触发 |
|
||||
| 预置条件 | 已触发过告警，alerted_key存在 |
|
||||
| 测试步骤 | 1. 执行 detect_token_anomaly() <br> 2. 检查告警发送次数 |
|
||||
| 预期结果 | 不重复发送告警 |
|
||||
| 实际结果 | |
|
||||
| 状态 | ☐ |
|
||||
|
||||
---
|
||||
|
||||
### 2.2 集成测试
|
||||
|
||||
#### I001: 真实API请求IP记录
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 用例ID | I001 |
|
||||
| 场景 | 通过API请求触发IP记录 |
|
||||
| 预置条件 | 后端服务运行中 |
|
||||
| 测试步骤 | 1. 发送HTTP请求(带X-Forwarded-For) <br> 2. 检查Redis中IP是否记录 |
|
||||
| 预期结果 | X-Forwarded-For的IP被记录 |
|
||||
| 实际结果 | |
|
||||
| 状态 | ☐ |
|
||||
|
||||
#### I002: 定时任务完整流程
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 用例ID | I002 |
|
||||
| 场景 | 定时任务触发完整检测流程 |
|
||||
| 预置条件 | 3个异常Token存在 |
|
||||
| 测试步骤 | 1. 等待定时任务执行(60秒) <br> 2. 检查告警记录 |
|
||||
| 预期结果 | 3条告警发送 |
|
||||
| 实际结果 | |
|
||||
| 状态 | ☐ |
|
||||
|
||||
#### I003: 企微消息格式
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 用例ID | I003 |
|
||||
| 场景 | 告警消息格式正确 |
|
||||
| 预置条件 | webhook配置正确 |
|
||||
| 测试步骤 | 1. 触发告警 <br> 2. 检查企微收到的消息 |
|
||||
| 预期结果 | markdown格式，包含employee_id、ip_count、token_hash |
|
||||
| 实际结果 | |
|
||||
| 状态 | ☐ |
|
||||
|
||||
---
|
||||
|
||||
## 3. 测试数据
|
||||
|
||||
### 3.1 测试Token
|
||||
|
||||
| Token | employee_id | 说明 |
|
||||
|-------|-------------|------|
|
||||
| test-token-001 | user001 | 单IP测试 |
|
||||
| test-token-002 | user002 | 3IP阈值测试 |
|
||||
| test-token-003 | user003 | 5IP严重测试 |
|
||||
| test-token-004 | user004 | 重复告警测试 |
|
||||
|
||||
### 3.2 测试IP
|
||||
|
||||
| IP | 类型 | 说明 |
|
||||
|----|------|------|
|
||||
| 10.0.0.1 | 内网 | 正常IP |
|
||||
| 10.0.0.2 | 内网 | 正常IP |
|
||||
| 10.0.0.3 | 内网 | 异常IP |
|
||||
| 218.75.34.87 | 公网 | 外部IP |
|
||||
| 117.147.35.138 | 公网 | 外部IP |
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试环境配置
|
||||
|
||||
### 4.1 环境变量
|
||||
|
||||
```bash
|
||||
# 测试环境配置
|
||||
TOKEN_ANOMALY_THRESHOLD=3
|
||||
TOKEN_ANOMALY_WINDOW=3600
|
||||
TOKEN_ANOMALY_AUTO_DISABLE=false
|
||||
CONTENT_AUDIT_WEBHOOK=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx
|
||||
```
|
||||
|
||||
### 4.2 Redis预置
|
||||
|
||||
```bash
|
||||
# 预置测试数据
|
||||
redis-cli SET "user:token:test-token-001" '{"employee_id":"user001",...}'
|
||||
redis-cli SADD "token_ips:hash001" "10.0.0.1"
|
||||
redis-cli EXPIRE "token_ips:hash001" 3600
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 测试结果
|
||||
|
||||
| 用例ID | 预期 | 实际 | 状态 | 备注 |
|
||||
|--------|------|------|------|------|
|
||||
| T001 | 通过 | | ☐ | |
|
||||
| T002 | 通过 | | ☐ | |
|
||||
| T003 | 通过 | | ☐ | |
|
||||
| T004 | 通过 | | ☐ | |
|
||||
| T005 | 通过 | | ☐ | |
|
||||
| T006 | 通过 | | ☐ | |
|
||||
| I001 | 通过 | | ☐ | |
|
||||
| I002 | 通过 | | ☐ | |
|
||||
| I003 | 通过 | | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 6. 测试签收
|
||||
|
||||
| 角色 | 姓名 | 日期 | 签名 |
|
||||
|------|------|------|------|
|
||||
| 开发 | | | |
|
||||
| 测试 | | | |
|
||||
| 审核 | | | |
|
||||
|
||||
---
|
||||
|
||||
> **编制人**: 威胁检测工程师
|
||||
> **日期**: 2026-07-14
|
||||
@@ -0,0 +1,338 @@
|
||||
# IT智能服务台 — 威胁检测方案报告
|
||||
|
||||
> **编制日期**: 2026-07-14
|
||||
> **版本**: v2.0 (修订版)
|
||||
> **角色**: 威胁检测工程师
|
||||
> **目标**: 建立威胁监控体系，及时发现和应对安全攻击
|
||||
|
||||
---
|
||||
|
||||
## 1. 认证机制与威胁模型更新
|
||||
|
||||
### 1.1 当前认证方式
|
||||
|
||||
| 登录方式 | 状态 | 暴力破解可行性 |
|
||||
|----------|------|----------------|
|
||||
| 企微OAuth2 | ✅ 使用中 | ❌ 企微保障 |
|
||||
| 企微扫码 | ✅ 使用中 | ❌ 企微保障 |
|
||||
| 账号密码登录 | ❌ 已废弃 | 不适用 |
|
||||
|
||||
**结论**: 由于没有密码入口，暴力破解检测不适用于本系统。攻击者需先攻克企微才能访问本系统。
|
||||
|
||||
### 1.2 真实威胁向量
|
||||
|
||||
| 威胁 | ATT&CK | 描述 | 优先级 |
|
||||
|------|---------|------|--------|
|
||||
| **T1078** | 有效账户滥用 | 员工Token/账号被窃取后在非授权环境使用 | P0 |
|
||||
| **T1552** | 非安全凭据访问 | Token泄露、被复用 | P0 |
|
||||
| **T1068** | 越权访问 | 低权限用户访问高权限资源 | P1 |
|
||||
| **T1041** | 数据外传 | 批量导出敏感数据 | P1 |
|
||||
| **内部威胁** | 权限滥用 | 管理员非工作时间敏感操作 | P1 |
|
||||
|
||||
---
|
||||
|
||||
## 2. MITRE ATT&CK 覆盖评估
|
||||
|
||||
### 2.1 当前检测能力
|
||||
|
||||
| 覆盖等级 | 定义 | 占比 |
|
||||
|----------|------|------|
|
||||
| **Level 0** | 无覆盖 | 80% |
|
||||
| **Level 1** | 日志记录 (已实现) | 15% |
|
||||
| **Level 2** | 告警检测 | 5% |
|
||||
| **Level 3** | 威胁狩猎 | 0% |
|
||||
|
||||
### 2.2 重点检测方向
|
||||
|
||||
基于真实威胁向量，优先覆盖：
|
||||
|
||||
| 技术ID | 技术名称 | 检测策略 |
|
||||
|--------|----------|----------|
|
||||
| T1078 | 有效账户 | Token异常使用检测 |
|
||||
| T1552 | 非安全凭据 | Token多IP使用检测 |
|
||||
| T1068 | 越权访问 | RBAC拒绝日志分析 |
|
||||
| T1041 | 数据外传 | 批量导出监控 |
|
||||
| T1056 | 权限滥用 | 管理员异常操作 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 检测方案设计
|
||||
|
||||
### 3.1 架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 数据采集层 │
|
||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
||||
│ │审计日志 │ │登录日志 │ │RBAC日志 │ │API日志 │ │
|
||||
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
|
||||
└───────┼───────────┼───────────┼───────────┼────────────────┘
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 规则检测层 │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │Token异常检测 │ │越权访问检测 │ │数据导出监控 │ │
|
||||
│ │(T1078/T1552)│ │(T1068) │ │(T1041) │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 响应处置层 │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │告警通知 │ │会话封禁 │ │工单创建 │ │
|
||||
│ │(企微机器人) │ │(Redis) │ │(ITSM) │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3.2 核心检测规则
|
||||
|
||||
#### 规则1: Token异常使用 (T1078/T1552)
|
||||
|
||||
```yaml
|
||||
id: itdesk-T1078-001
|
||||
title: 凭证异常 - Token多IP使用
|
||||
level: high
|
||||
description: |
|
||||
检测同一Token在短时间内被多个不同IP使用，可能是Token泄露或中间人攻击。
|
||||
mitre: T1078, T1552
|
||||
condition: |
|
||||
同一 token_hash
|
||||
不同 ip_address >= 3
|
||||
时间窗口: 1小时
|
||||
action: |
|
||||
1. 标记为可疑
|
||||
2. 发送企微告警
|
||||
3. 可选: 自动 invalidate token
|
||||
```
|
||||
|
||||
#### 规则2: 越权访问检测 (T1068)
|
||||
|
||||
```yaml
|
||||
id: itdesk-T1068-001
|
||||
title: 权限提升 - 越权访问
|
||||
level: critical
|
||||
description: |
|
||||
检测低权限用户尝试访问高权限资源，可能是权限提升攻击。
|
||||
mitre: T1068
|
||||
condition: |
|
||||
RBAC拒绝事件
|
||||
同一用户 >= 3次/10分钟
|
||||
action: |
|
||||
1. 标记为可疑
|
||||
2. 发送企微告警
|
||||
3. 暂停用户账户
|
||||
```
|
||||
|
||||
#### 规则3: 批量数据导出 (T1041)
|
||||
|
||||
```yaml
|
||||
id: itdesk-T1041-001
|
||||
title: 数据泄露 - 批量导出
|
||||
level: high
|
||||
description: |
|
||||
检测大量数据导出操作，可能是数据外传前兆。
|
||||
mitre: T1041
|
||||
condition: |
|
||||
action = 'data_export'
|
||||
导出记录数 > 1000 或 导出大小 > 100MB
|
||||
action: |
|
||||
1. 标记为可疑
|
||||
2. 发送企微告警
|
||||
3. 需要MFA二次确认
|
||||
```
|
||||
|
||||
#### 规则4: 管理员异常操作 (内部威胁)
|
||||
|
||||
```yaml
|
||||
id: itdesk-insider-001
|
||||
title: 内部威胁 - 管理员异常操作
|
||||
level: high
|
||||
description: |
|
||||
检测管理员在非工作时间执行敏感操作。
|
||||
mitre: T1056
|
||||
condition: |
|
||||
管理员角色
|
||||
敏感操作 (role_change/config_change/account_disable)
|
||||
时间不在 08:00-22:00
|
||||
action: |
|
||||
1. 发送企微告警
|
||||
2. 记录详细审计日志
|
||||
3. 需要OTP二次确认
|
||||
```
|
||||
|
||||
#### 规则5: 外部API滥用 (T1071)
|
||||
|
||||
```yaml
|
||||
id: itdesk-T1071-001
|
||||
title: 外部服务异常 - Dify API高错误率
|
||||
level: medium
|
||||
description: |
|
||||
检测Dify AI服务的异常调用模式。
|
||||
mitre: T1071
|
||||
condition: |
|
||||
Dify API
|
||||
错误率 > 30% 或 响应时间 > 30秒
|
||||
action: |
|
||||
1. 切换备用通道
|
||||
2. 发送告警
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 数据源清单
|
||||
|
||||
| 数据源 | 表/日志 | 检测用途 |
|
||||
|--------|---------|----------|
|
||||
| 审计日志 | audit_logs | 管理员操作、权限变更 |
|
||||
| 登录日志 | login_logs | 登录来源分析 |
|
||||
| RBAC日志 | access_denied事件 | 越权访问 |
|
||||
| 应用日志 | JSON logs | API调用统计 |
|
||||
| Redis | token相关 | Token实时监控 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 实施路线图
|
||||
|
||||
### 阶段1: 核心检测 (2周)
|
||||
|
||||
| 任务 | 产出 |
|
||||
|------|------|
|
||||
| Token多IP检测 | 告警 + 自动封禁 |
|
||||
| 越权访问检测 | 实时告警 |
|
||||
| 批量导出监控 | 告警 + 审批流程 |
|
||||
|
||||
### 阶段2: 增强检测 (4周)
|
||||
|
||||
| 任务 | 产出 |
|
||||
|------|------|
|
||||
| 管理员异常行为 | 非工作时间告警 |
|
||||
| 外部API监控 | Dify/企微API健康度 |
|
||||
| 告警渠道 | 企微机器人webhook |
|
||||
|
||||
### 阶段3: 高级能力 (持续)
|
||||
|
||||
| 任务 | 产出 |
|
||||
|------|------|
|
||||
| 用户行为基线 | 异常行为检测 |
|
||||
| 威胁情报 | IOC匹配 |
|
||||
| SOAR剧本 | 自动响应 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 快速部署方案
|
||||
|
||||
### 6.1 立即可执行
|
||||
|
||||
基于现有 `audit_logs` 表，增加定时分析任务：
|
||||
|
||||
```python
|
||||
# 每日管理员操作分析
|
||||
async def analyze_admin_operations():
|
||||
"""检测非工作时间敏感操作"""
|
||||
query = """
|
||||
SELECT employee_id, action, ip_address, created_at
|
||||
FROM audit_logs
|
||||
WHERE action IN ('role_change', 'config_change', 'account_disable')
|
||||
AND EXTRACT(HOUR FROM created_at) NOT BETWEEN 8 AND 22
|
||||
"""
|
||||
# 发送报告给安全管理员
|
||||
```
|
||||
|
||||
### 6.2 Token监控
|
||||
|
||||
在 `token_service.py` 中增加埋点：
|
||||
|
||||
```python
|
||||
async def on_token_used(token_hash: str, ip: str):
|
||||
"""记录Token使用IP，用于异常检测"""
|
||||
redis = await get_redis()
|
||||
key = f"token_ip:{token_hash}"
|
||||
|
||||
# 记录使用的IP集合
|
||||
await redis.sadd(key, ip)
|
||||
await redis.expire(key, 3600) # 1小时窗口
|
||||
|
||||
# 检查是否多IP使用
|
||||
ip_count = await redis.scard(key)
|
||||
if ip_count >= 3:
|
||||
await send_alert(f"Token异常: {token_hash} 使用了 {ip_count} 个IP")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 实施进度 (2026-07-14)
|
||||
|
||||
### ✅ 已完成
|
||||
|
||||
| 任务 | 完成时间 | 状态 |
|
||||
|------|----------|------|
|
||||
| Token IP记录功能 | 2026-07-14 | ✅ 已实现 |
|
||||
| Token异常检测定时任务 | 2026-07-14 | ✅ 已实现 |
|
||||
| get_current_user IP记录集成 | 2026-07-14 | ✅ 已实现 |
|
||||
| 单元测试 | 2026-07-14 | ✅ 7/7 通过 |
|
||||
|
||||
### 📝 产出物
|
||||
|
||||
| 文件 | 路径 |
|
||||
|------|------|
|
||||
| 检测任务 | `backend/app/tasks/token_anomaly_detection.py` |
|
||||
| Token服务扩展 | `backend/app/services/token_service.py` (新增方法) |
|
||||
| 认证集成 | `backend/app/dependencies/__init__.py` (IP记录) |
|
||||
| 单元测试 | `backend/tests/test_token_anomaly.py` |
|
||||
|
||||
### 📋 待完成
|
||||
|
||||
| 任务 | 优先级 | 备注 |
|
||||
|------|--------|------|
|
||||
| 集成测试 | P2 | 需要测试环境 |
|
||||
| 生产部署 | P1 | 需配置webhook |
|
||||
| 告警阈值调优 | P2 | 根据实际告警调整 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 总结
|
||||
|
||||
### 7.1 核心结论
|
||||
|
||||
| 维度 | 评分 |
|
||||
|------|------|
|
||||
| 身份认证 | ⭐⭐⭐⭐ 企微OAuth + OTP |
|
||||
| 访问控制 | ⭐⭐⭐⭐ RBAC |
|
||||
| **威胁检测** | ⭐⭐ **建设中** |
|
||||
|
||||
### 7.2 优先行动
|
||||
|
||||
1. **已完成**: Token多IP使用检测 ✅
|
||||
2. **1周内**: 批量导出监控
|
||||
3. **2周内**: 管理员异常操作告警
|
||||
|
||||
---
|
||||
|
||||
## 附录
|
||||
|
||||
### A. 现有安全组件
|
||||
|
||||
| 组件 | 位置 |
|
||||
|------|------|
|
||||
| 审计日志 | app/models/audit_log.py |
|
||||
| 登录日志 | app/models/login_log.py |
|
||||
| MFA服务 | app/services/mfa_service.py |
|
||||
| IP白名单 | app/middleware/admin_ip_whitelist.py |
|
||||
| 速率限制 | app/main.py (slowapi) |
|
||||
|
||||
### B. 告警级别定义
|
||||
|
||||
| 级别 | 触发条件 | 响应时间 |
|
||||
|------|----------|----------|
|
||||
| P0 | 越权访问 / 批量导出 | < 5分钟 |
|
||||
| P1 | Token异常 / 管理员异常 | < 15分钟 |
|
||||
| P2 | API异常 / 非敏感操作 | < 1小时 |
|
||||
|
||||
---
|
||||
|
||||
> **编制人**: 威胁检测工程师
|
||||
> **审核人**: 待定
|
||||
> **下次评估**: 2026-10-14
|
||||
+184
-5
@@ -1,9 +1,16 @@
|
||||
# 00 · 标准故障排查手册
|
||||
|
||||
> **版本**: v1.4 | **日期**: 2026-07-10 | **维护人**: 宋献 / 助理
|
||||
> **版本**: v1.9 | **日期**: 2026-07-16 | **维护人**: 宋献 / 助理
|
||||
> **定位**: 所有故障排查前**首先查看本手册**。
|
||||
> **最新**: 方案 C（卷挂载）已上线，§1.4 更新为 volume 挂载验证 + CASE-20260710-02 标注根因已消除 + 错误码速查更新
|
||||
> **最新**: 新增 CASE-20260716-01（员工端 /h5/ 404 — nginx 反向代理配置错误）
|
||||
|
||||
| v1.6 | 2026-07-14 | 新增 CASE-20260714-01（前端 bind mount 未生效导致 403）+ 错误码速查更新 |
|
||||
| v1.7 | 2026-07-14 | 新增 CASE-20260714-02（员工端 /h5/ 404 — nginx 配置错误）|
|
||||
| v1.9 | 2026-07-16 | 新增 CASE-20260716-01（员工端 /h5/ 404 — nginx 反向代理配置错误）|
|
||||
| v1.8 | 2026-07-15 | 新增 CASE-20260715-01（员工端审批模板ID不正确 — 企微审批模板失效）|
|
||||
| v1.7 | 2026-07-14 | 新增 CASE-20260714-01（前端 bind mount 未生效导致 403）+ 错误码速查更新 |
|
||||
| v1.6 | 2026-07-14 | 新增 CASE-20260714-02（员工端 /h5/ 404 — nginx 配置错误）|
|
||||
| v1.5 | 2026-07-13 | 新增 CASE-20260713-01（nginx rewrite 不全导致 502）+ CASE-20260713-02（@require_role 装饰器参数缺失） |
|
||||
| v1.4 | 2026-07-10 | 方案 C 上线：§1.4 改为 volume 挂载验证 + 错误码速查更新 + CASE-20260710-02 根因已消除标注 |
|
||||
> **前置阅读**: [运维手册（部署/回滚/备份/应急）](../01-项目总览/01-智能IT服务系统运维手册-20260704.md) · [SOP-04 应急响应](../10-项目管理/SOPs-标准流程/SOP-04-应急响应.md)
|
||||
|
||||
@@ -136,16 +143,41 @@ python jms_ops.py exec \
|
||||
|
||||
> ⚠️ 代码更新后 `docker compose restart` 即可（15-30 秒）。仅当 `requirements.txt` 有变化时才需要 `docker compose build`。
|
||||
|
||||
#### 前端部署检查清单（bind mount 模式）
|
||||
|
||||
**触发条件**：任何前端文件更新（`frontend-*/dist/` 目录变更）。
|
||||
|
||||
```bash
|
||||
# 1. 验证宿主机源目录有文件
|
||||
ls -la /opt/wecom-it-desk/frontend-agent/dist/ # 坐席端
|
||||
ls -la /opt/wecom-it-desk/frontend-h5/dist/ # H5 端
|
||||
|
||||
# 2. 验证容器内挂载成功（关键！）
|
||||
docker exec wecom_it_nginx ls /usr/share/nginx/html/itagent/ # 坐席端
|
||||
docker exec wecom_it_nginx ls /usr/share/nginx/html/h5/ # H5 端
|
||||
|
||||
# 3. 如容器内为空，强制重建 nginx 容器
|
||||
cd /opt/wecom-it-desk
|
||||
docker compose stop nginx
|
||||
docker compose rm -f nginx
|
||||
docker compose up -d nginx
|
||||
|
||||
# 4. 验证外部可访问
|
||||
curl -sI https://itsupport.servyou.com.cn/itagent/ | head -3
|
||||
```
|
||||
|
||||
> ⚠️ **bind mount 有时不生效**：即使 docker-compose.yml 配置正确，挂载也可能失效。前端部署后务必验证容器内文件存在（步骤2），否则会 403。
|
||||
|
||||
---
|
||||
|
||||
## 2 常见错误码速查（E5xx）
|
||||
|
||||
| 错误码 | 含义 | 首选排查 |
|
||||
|--------|------|---------|
|
||||
| **E500** | 后端未捕获异常 / 缺列 / 缺依赖 | `docker compose logs backend --tail=200 \| grep -i error`；查数据库缺列 / 缺 Python 依赖 |
|
||||
| **E502** | nginx 连不到后端 | 后端容器 `unhealthy`？`docker logs wecom_it_backend`；是否缺 `PYTHONPATH=/app` |
|
||||
| **E500** | 后端未捕获异常 / 缺列 / 缺依赖 / 装饰器参数不匹配 | `docker compose logs backend --tail=200 \| grep -i error`；查数据库缺列 / 缺 Python 依赖；检查 `@require_role` 等装饰器是否与函数签名不匹配（见 CASE-20260713-02） |
|
||||
| **E502** | nginx 连不到后端 / 路由不匹配 | 后端容器 `unhealthy`？`docker logs wecom_it_backend`；检查 nginx rewrite 是否正确剥离 `/api/` 前缀（见 CASE-20260713-01） |
|
||||
| **E503** | 服务过载 / 维护 | `docker stats`；`docker inspect ... Health` |
|
||||
| **E403** | IP 白名单 / 无权限 | `grep allow /opt/wecom-it-desk/nginx/nginx.conf`；admin 角色不足 |
|
||||
| **E403** | IP 白名单 / 无权限 / 前端挂载未生效 | `grep allow /opt/wecom-it-desk/nginx/nginx.conf`；admin 角色不足；前端部署后检查 `docker exec wecom_it_nginx ls <挂载路径>` 确认容器内文件存在（见 CASE-20260714-01） |
|
||||
| **E422** | 请求体校验失败（Pydantic）| 确认必填字段齐全（如登录需 `user_id`+`name`）|
|
||||
| **网络失败 / 连接挂起** | 依赖不可达（最常见 Redis 配置错）| 见 §1.2 / CASE-20260707-01 |
|
||||
| **页面 200 但 JS 不执行** | CSP 头 `script-src` 缺 `'unsafe-inline'`，内联 `<script>` 被浏览器静默拦截 | `curl -ksI <URL> \| grep content-security`；检查 `script-src` 是否含 `'unsafe-inline'`（见 CASE-20260710-01）|
|
||||
@@ -201,6 +233,153 @@ docker logs wecom_it_backend | grep -i websocket
|
||||
|
||||
## 4 案例库（倒序，编号 CASE-YYYYMMDD-序号）
|
||||
|
||||
### CASE-20260716-01 · 员工端 /h5/ 404 — nginx 反向代理配置错误 ⭐⭐
|
||||
- **现象**：企微工作台 → IT智能服务 → `https://itsupport.servyou.com.cn/h5/` 返回 `{"detail":"Not Found"}`（FastAPI 404）
|
||||
- **根因**：nginx 配置中 `/h5/` 被错误配置为**反向代理**到后端 API（`proxy_pass http://backend_api/`），而不是静态文件服务。后端没有 `/h5/` 路由，返回 404
|
||||
- **诊断**：
|
||||
1. `docker logs wecom_it_nginx | grep /h5/` → 显示后端返回 404
|
||||
2. `docker exec wecom_it_nginx cat /etc/nginx/nginx.conf | grep -A5 'location /h5/'` → 发现 `proxy_pass http://backend_api/`
|
||||
3. 确认 H5 静态文件已正确挂载：`docker exec wecom_it_nginx ls /usr/share/nginx/html/h5/`
|
||||
- **修复**：
|
||||
1. **docker-compose.yml**：新增 H5 挂载到 `/h5/`
|
||||
```
|
||||
- ./frontend-h5/dist:/usr/share/nginx/html/h5:ro
|
||||
```
|
||||
2. **nginx/nginx.conf**：将 `/h5/` 从反向代理改为静态文件服务
|
||||
```
|
||||
location /h5/ {
|
||||
alias /usr/share/nginx/html/h5/;
|
||||
index index.html;
|
||||
try_files $uri /h5/index.html;
|
||||
}
|
||||
```
|
||||
3. **部署**：上传配置后重建 nginx 容器
|
||||
```
|
||||
cd /opt/wecom-it-desk
|
||||
docker compose stop nginx && docker compose rm -f nginx && docker compose up -d nginx
|
||||
```
|
||||
- **验证**：
|
||||
- 容器内 `curl -sI http://localhost/h5/` → HTTP 200
|
||||
- 浏览器访问 `https://itsupport.servyou.com.cn/h5/` → 正常显示 H5 页面
|
||||
- **⚠️ 教训**：
|
||||
1. **H5 前端是静态文件应用**，nginx 应配置 `alias` 或 `root` 提供静态文件，而不是 `proxy_pass` 到后端
|
||||
2. **这是第二次出现同类问题**：上次 CASE-20260714-02 修复后，今天再次出现，可能是上次修复未同步到服务器或配置被覆盖
|
||||
3. **bind mount 有时不生效**：即使 docker-compose.yml 配置正确，挂载也可能失效。前端部署后务必验证容器内文件存在
|
||||
4. **建议**：在 nginx 配置中添加注释说明 `/h5/` 是静态文件服务，避免未来误改
|
||||
|
||||
### CASE-20260715-01 · 员工端审批"获取审批流程失败，审批模板ID不正确" ⭐⭐
|
||||
- **现象**：员工端H5点击"IT资产升级"、"设备申请"、"商业软件申请"等审批卡片时，提示"获取审批流程失败，审批模板ID不正确"。
|
||||
- **根因**（两层代码都需要修复）：
|
||||
1. **前端**：`RecommendCard.vue` 中 `APPROVAL_URL_MAP` 的 `asset_upgrade` 映射到企微审批模板 `Bs7ucTGs...`（已失效），`商业软件申请` 映射到企微审批模板 `3TmACf8D...`（也已失效），第298-299行硬编码 fallback 跳转到失效的企微审批URL
|
||||
2. **后端**：`backend/app/api/approval.py` 中 `APPROVAL_TEMPLATES` 字典的 `asset_upgrade` 和 `software_service` 同样映射到失效的企微审批模板（第81行和第115行）
|
||||
- **诊断**：
|
||||
1. 浏览器F12查看网络请求，确认调用的是企微审批模板URL
|
||||
2. 检查前端 `RecommendCard.vue` 和后端 `approval.py` 中的URL映射
|
||||
3. 对比 `ApprovalCardModal.vue` 中的正确映射（已改用ITSM）
|
||||
- **修复**：
|
||||
1. **前端**：`frontend-h5/src/components/assistant/RecommendCard.vue`
|
||||
- 将 `asset_upgrade` 改为ITSM工单系统URL
|
||||
- 将 `商业软件申请` 改为ITSM工单系统URL
|
||||
- 修改 `handleActionClick()` 的fallback逻辑，移除硬编码的失效URL
|
||||
- 构建：`npm run build` → 部署到 `/opt/wecom-it-desk/frontend-h5/dist/`
|
||||
2. **后端**：`backend/app/api/approval.py`
|
||||
- 将 `asset_upgrade` 的 `url` 改为ITSM工单系统URL，`location` 改为"运维平台"
|
||||
- 将 `software_service` 的 `url` 改为ITSM工单系统URL，`location` 改为"运维平台"
|
||||
- 上传到服务器：`/opt/wecom-it-desk/app/api/approval.py`
|
||||
- 重启后端：`docker compose restart backend`
|
||||
3. 部署：`docker exec wecom_it_nginx nginx -s reload`
|
||||
- **验证**：浏览器访问H5，点击审批卡片，跳转到ITSM工单系统而非企微审批（已失效模板）
|
||||
- **⚠️ 教训**：
|
||||
1. **审批入口有两层**：左侧"企微-审批"入口数据来自后端API `/approval/links`，AI推荐卡片来自前端代码，两者都需要修复
|
||||
2. **企微审批模板会失效**：审批模板在企微后台可能被删除或变更，前端不应硬编码模板ID
|
||||
3. **ITSM是更稳定的方案**：ITSM工单系统URL更稳定，不受企微审批模板变更影响
|
||||
4. **推荐做法**：所有审批类型统一使用ITSM工单系统，前后端都要同步修改
|
||||
|
||||
### CASE-20260714-01 · 坐席端 403 错误 — 前端 bind mount 未生效 ⭐⭐
|
||||
- **现象**：坐席端 `/itagent/` 返回 403 Forbidden，浏览器控制台显示 `Failed to load resource: the server responded with a status of 403`。
|
||||
- **根因**：前端文件虽然上传到服务器 `/opt/wecom-it-desk/frontend-agent/dist/`，但 nginx 容器的 bind mount 没有正确工作，容器内 `/usr/share/nginx/html/itagent/` 目录为空。
|
||||
- **诊断**：
|
||||
1. `docker exec wecom_it_nginx ls -la /usr/share/nginx/html/itagent/` → 容器内目录为空
|
||||
2. `docker inspect wecom_it_nginx | grep itagent` → 挂载配置存在且正确（`Source: /opt/wecom-it-desk/frontend-agent/dist`）
|
||||
3. `ls -la /opt/wecom-it-desk/frontend-agent/dist/` → 宿主机源目录有文件
|
||||
4. nginx 日志显示 `directory index of "/usr/share/nginx/html/itagent/" is forbidden`
|
||||
- **修复**：
|
||||
```bash
|
||||
# 重建 nginx 容器让 bind mount 生效
|
||||
cd /opt/wecom-it-desk
|
||||
docker compose stop nginx
|
||||
docker compose rm -f nginx
|
||||
docker compose up -d nginx
|
||||
```
|
||||
- **验证**：`docker exec wecom_it_nginx ls -la /usr/share/nginx/html/itagent/` → 容器内文件存在；外部访问 `/itagent/` → HTTP 200
|
||||
- **⚠️ 教训**：
|
||||
1. **bind mount 有时不生效**：即使 docker-compose.yml 配置正确，挂载也可能失效。重建容器是常用解决方法。
|
||||
2. **容器内目录为空但宿主机有文件 ≠ 挂载成功**：必须进入容器内验证，不能只看宿主机。
|
||||
3. **前端部署后务必验证容器内文件**：用 `docker exec <容器> ls <挂载路径>` 确认。
|
||||
4. **此问题可能复发**：任何前端部署（dist 目录更新）后，建议重建 nginx 容器确保挂载生效。
|
||||
|
||||
- **复发记录**：
|
||||
- 2026-07-16：再次发生，返回 500（rewrite 循环 `internal redirection cycle while internally redirecting to "/itage"`），重建 nginx 容器修复
|
||||
|
||||
### CASE-20260714-02 · 员工端 /h5/ 404 — nginx 配置错误 ⭐⭐
|
||||
- **现象**：员工端打开报错 `Failed to load resource: the server responded with a status of 404 (Not Found)`。
|
||||
- **根因**：nginx 配置中 `/h5/` 被错误配置为**反向代理**到后端（`proxy_pass http://backend_api/`），而不是静态文件服务。后端没有 `/h5/` 路由，导致返回 404。
|
||||
- **诊断**：
|
||||
1. `docker logs wecom_it_nginx | grep /h5/` → 显示 `GET /h5/ HTTP/1.1" 404`
|
||||
2. `docker exec wecom_it_nginx cat /etc/nginx/nginx.conf | grep -A10 'location /h5/'` → 发现 `proxy_pass http://backend_api/`
|
||||
3. 确认静态文件已正确挂载：`docker exec wecom_it_nginx ls /usr/share/nginx/html/h5/`
|
||||
- **修复**：修改 `nginx/nginx.conf`，将 `/h5/` 从反向代理改为静态文件服务：
|
||||
```
|
||||
location /h5/ {
|
||||
alias /usr/share/nginx/html/h5/;
|
||||
index index.html;
|
||||
try_files $uri /h5/index.html;
|
||||
}
|
||||
```
|
||||
部署：`docker compose restart nginx`
|
||||
- **验证**：浏览器访问 `https://itsupport.servyou.com.cn/h5/` → HTTP 200，显示"仅限企业微信访问"页面
|
||||
- **⚠️ 教训**：
|
||||
1. **H5 前端是静态文件应用**，nginx 应配置 `alias` 或 `root` 提供静态文件，而不是 `proxy_pass` 到后端。
|
||||
2. **本地 nginx.conf 与服务器不同步**：发现问题后，检查本地配置是否已修复（本次修复已同步到本地 `nginx/nginx.conf`）。
|
||||
3. **常见混淆**：`/itdesk/` 和 `/h5/` 都指向 H5 应用，但只有 `/itdesk/` 是在企微工作台中配置的入口。两者都应配置为静态文件服务。
|
||||
|
||||
### CASE-20260713-02 · 坐席端 502 错误 — @require_role 装饰器参数缺失 ⭐⭐
|
||||
- **现象**：坐席端 `/itagent/` 全部 API 返回 502，后端日志显示 `TypeError: list_agents() got an unexpected keyword argument 'current_user'`。
|
||||
- **根因**：`@require_role` 装饰器在调用被装饰函数时强制传递 `current_user` 参数，但部分使用该装饰器的函数未声明此参数。
|
||||
- **诊断**：`docker logs wecom_it_backend | grep -i error` 查看具体错误；定位缺少参数的函数。
|
||||
- **修复**：
|
||||
1. `backend/app/api/agents.py` 第 425 行：添加 `current_user: UserInfo = Depends(get_current_user)`
|
||||
2. `backend/app/api/otp.py` 第 348 行和第 389 行：同样添加 `current_user` 参数
|
||||
3. 部署：`docker compose restart backend`
|
||||
- **验证**：后端 `/health` → 200 OK；`/agents` → 200 OK
|
||||
- **⚠️ 教训**：
|
||||
1. **所有使用 `@require_role` 装饰器的函数都必须声明 `current_user` 参数**，装饰器会自动注入此参数。
|
||||
2. 排查 502 错误时，先检查后端日志中的 `TypeError` 错误，可能是装饰器参数不匹配。
|
||||
3. 建议在代码中添加类型注解和 lint 规则，提前发现此类问题。
|
||||
|
||||
### CASE-20260713-01 · 坐席端 502 错误 — nginx rewrite 规则不完整 ⭐⭐
|
||||
- **现象**：部分 API（如 `/api/auth/qrcode`）返回 502，但 `/api/agents` 返回 200。
|
||||
- **根因**：nginx 配置只对 `/api/admin/` 路径做 rewrite 剥离前缀，其他路径（如 `/api/auth/`）未处理，导致后端收到 `/api/auth/qrcode` 而非 `/auth/qrcode`，路由不匹配返回 404。
|
||||
- **诊断**：
|
||||
1. `docker logs wecom_it_nginx | grep 502` 查看哪些路径返回 502
|
||||
2. `docker exec wecom_it_backend curl http://localhost:8000/auth/qrcode` 直接测试后端（绕过 nginx）
|
||||
3. 检查 nginx 配置 `location /api/` 是否正确 rewrite
|
||||
- **修复**：修改 `nginx/nginx.conf`，对所有 `/api/` 路径统一做 rewrite：
|
||||
```
|
||||
location /api/ {
|
||||
# 剥离 /api/ 前缀，使后端收到 /auth/... 而非 /api/auth/...
|
||||
rewrite ^/api/(.*)$ /$1 break;
|
||||
proxy_pass http://backend_api;
|
||||
...
|
||||
}
|
||||
```
|
||||
部署：`docker restart wecom_it_nginx`
|
||||
- **验证**：外部访问 `/api/auth/qrcode` → 200 OK
|
||||
- **⚠️ 教训**：
|
||||
1. **nginx rewrite 规则必须覆盖所有需要剥离前缀的路径**，不能只处理特定路径（如 `/api/admin/`）。
|
||||
2. 判定矩阵更新：`/xxx/ 200 但 /api/... 404` → 检查 nginx 是否正确 rewrite。
|
||||
3. 部署新功能后，务必用真实浏览器测试所有关键路径，不能只测"看起来正常"的端点。
|
||||
|
||||
### CASE-20260710-02 · 坐席端/管理端登录"获取二维码失败"（Docker 镜像缺文件）⭐⭐
|
||||
- **现象**：坐席端和管理端登录均报"获取二维码失败"，浏览器控制台显示 `WebSocket connection failed` + `/api/auth/qrcode` 返回 404。
|
||||
- **误判历程**：
|
||||
|
||||
@@ -164,6 +164,40 @@ ping itsupport.servyou.com.cn
|
||||
# CORS_ORIGINS=http://10.90.5.110
|
||||
```
|
||||
|
||||
### 4.3 部署铁律（2026-07-17 新增，踩坑记录）
|
||||
|
||||
以下 3 条均为生产事故复盘得出的硬性规则，部署/变更时必须遵守：
|
||||
|
||||
#### 铁律 1：backend 必须 `--workers 1`（WS 推送单 worker 约束）
|
||||
|
||||
`ws_manager` 是进程内单例，AI 后台任务与员工 WebSocket 连接若落在不同 worker 进程，`broadcast_to_employees` 会**静默丢失约 50% 消息**。
|
||||
|
||||
```bash
|
||||
# ❌ 危险：docker-compose-override.yml 会自动合并覆盖主文件！
|
||||
# 若 override 中存在 --workers 2，主文件的 --workers 1 会被覆盖
|
||||
docker compose -f docker-compose.yml -f docker-compose-override.yml config | grep workers
|
||||
# 必须输出 1。如为 2，删除或修改 override 文件
|
||||
```
|
||||
|
||||
#### 铁律 2：`.env` 变量不会自动传入容器，必须在 `environment:` 显式声明
|
||||
|
||||
`backend/.dockerignore` 排除了全部 `.env` 文件，生产容器配置 **100% 来自 docker-compose.yml 的 `environment:` 部分**。新增任何环境变量（尤其是 `DIFY_NATIVE_BASE_URL`、`DIFY_NATIVE_API_KEY`），必须：
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
backend:
|
||||
environment:
|
||||
- DIFY_NATIVE_BASE_URL=${DIFY_NATIVE_BASE_URL:-}
|
||||
- DIFY_NATIVE_API_KEY=${DIFY_NATIVE_API_KEY:-}
|
||||
```
|
||||
|
||||
验证：容器内执行 `env | grep DIFY_NATIVE` 非空；后端日志出现「调用 Dify 原生 API」而非「回退到代理路径」。
|
||||
（事故记录：2026-07-13 两次因未声明导致 P0 故障；`WECOM_SSO_CALLBACK_BASE` 未声明导致扫码登录崩溃）
|
||||
|
||||
#### 铁律 3：Redis 密码含特殊字符必须 URL 编码
|
||||
|
||||
`REDIS_URL` 中密码含 `@ # !` 时未编码 → 解析出错误的 host → 连接挂起 → 登录 502。编码规则：`@→%40`、`#→%23`、`!→%21`。改密码时须同步更新 compose 中 `requirepass` 与 `REDIS_URL` 两处。
|
||||
|
||||
---
|
||||
|
||||
## 五、启动服务
|
||||
|
||||
@@ -0,0 +1,246 @@
|
||||
# Token多IP异常检测 - 部署指南
|
||||
|
||||
> **任务ID**: 待分配
|
||||
> **版本**: v1.0
|
||||
> **关联文档**:
|
||||
> - 技术设计-Token多IP异常检测.md
|
||||
> - Token多IP异常检测测试用例.md
|
||||
|
||||
---
|
||||
|
||||
## 1. 部署概述
|
||||
|
||||
### 1.1 部署范围
|
||||
|
||||
| 组件 | 容器 | 说明 |
|
||||
|------|------|------|
|
||||
| 检测服务 | backend | Token异常检测定时任务 |
|
||||
| Redis | redis | IP存储 |
|
||||
| 告警通道 | 企微机器人 | 复用现有webhook |
|
||||
|
||||
### 1.2 部署方式
|
||||
|
||||
- **部署类型**: 增量部署（不涉及基础设施变更）
|
||||
- **停机时间**: 无需停机（定时任务后台运行）
|
||||
- **回滚**: 代码级别回滚
|
||||
|
||||
---
|
||||
|
||||
## 2. 部署前检查
|
||||
|
||||
### 2.1 环境检查
|
||||
|
||||
| 检查项 | 命令 | 预期结果 |
|
||||
|--------|------|----------|
|
||||
| Redis连接 | `docker exec backend redis-cli ping` | PONG |
|
||||
| APScheduler状态 | 检查日志 | 定时任务启动成功 |
|
||||
| webhook配置 | 检查环境变量 | CONTENT_AUDIT_WEBHOOK已设置 |
|
||||
|
||||
### 2.2 配置检查
|
||||
|
||||
确认以下环境变量已配置（如需自定义）：
|
||||
|
||||
```bash
|
||||
# 可选配置
|
||||
TOKEN_ANOMALY_THRESHOLD=3 # 触发告警的IP数量阈值
|
||||
TOKEN_ANOMALY_WINDOW=3600 # 时间窗口(秒)
|
||||
TOKEN_ANOMALY_AUTO_DISABLE=false # 是否自动禁用Token
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 部署步骤
|
||||
|
||||
### 3.1 步骤1：代码变更
|
||||
|
||||
**新增文件**：
|
||||
```
|
||||
backend/app/tasks/token_anomaly_detection.py (新建)
|
||||
```
|
||||
|
||||
**修改文件**：
|
||||
```
|
||||
backend/app/services/token_service.py (增加record_token_ip方法)
|
||||
backend/app/main.py (注册定时任务)
|
||||
```
|
||||
|
||||
### 3.2 步骤2：配置变更
|
||||
|
||||
在 `.env` 或 docker-compose.yml 中添加（可选）：
|
||||
|
||||
```bash
|
||||
# 如需自定义阈值，在 .env 中添加
|
||||
TOKEN_ANOMALY_THRESHOLD=3
|
||||
TOKEN_ANOMALY_AUTO_DISABLE=false
|
||||
```
|
||||
|
||||
### 3.3 步骤3：重启服务
|
||||
|
||||
```bash
|
||||
# 重启backend容器（不中断其他服务）
|
||||
docker compose restart backend
|
||||
|
||||
# 查看日志确认定时任务启动
|
||||
docker logs backend --tail 50 | grep -i "token"
|
||||
```
|
||||
|
||||
预期日志：
|
||||
```
|
||||
✅ Token多IP异常检测任务已启动（每60秒执行一次）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 部署后验证
|
||||
|
||||
### 4.1 功能验证
|
||||
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|----------|
|
||||
| 定时任务运行 | 查看日志 | 每分钟执行一次 |
|
||||
| IP记录 | 模拟API请求 | Redis中记录IP |
|
||||
| 告警触发 | 构造3个IP的Token | 企微收到告警 |
|
||||
|
||||
### 4.2 冒烟测试
|
||||
|
||||
执行测试用例：
|
||||
```bash
|
||||
# 进入backend容器
|
||||
docker exec -it backend bash
|
||||
|
||||
# 运行单元测试
|
||||
pytest app/tests/test_token_anomaly.py -v
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 监控与运维
|
||||
|
||||
### 5.1 日志位置
|
||||
|
||||
| 日志类型 | 路径 |
|
||||
|----------|------|
|
||||
| 应用日志 | `/app/logs/wecom-it-desk.log` |
|
||||
| 定时任务日志 | 集成在应用日志中 |
|
||||
|
||||
### 5.2 监控指标
|
||||
|
||||
| 指标 | 说明 |
|
||||
|------|------|
|
||||
| token_anomaly_triggered_total | 触发告警次数 |
|
||||
| token_anomaly_false_positive | 误报次数 |
|
||||
|
||||
### 5.3 运维命令
|
||||
|
||||
```bash
|
||||
# 查看定时任务状态
|
||||
docker exec backend python -c "from app.main import _scheduler; print(_scheduler.get_jobs())"
|
||||
|
||||
# 手动触发检测（调试）
|
||||
docker exec backend python -c "
|
||||
import asyncio
|
||||
from app.tasks.token_anomaly_detection import detect_token_anomaly
|
||||
asyncio.run(detect_token_anomaly())
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 回滚方案
|
||||
|
||||
### 6.1 回滚步骤
|
||||
|
||||
```bash
|
||||
# 1. 撤销代码变更
|
||||
git checkout -- backend/app/services/token_service.py
|
||||
git checkout -- backend/app/main.py
|
||||
git rm backend/app/tasks/token_anomaly_detection.py
|
||||
|
||||
# 2. 重启服务
|
||||
docker compose restart backend
|
||||
```
|
||||
|
||||
### 6.2 数据清理
|
||||
|
||||
```bash
|
||||
# 清理Redis中的检测数据（可选，1小时后自动过期）
|
||||
docker exec backend redis-cli KEYS "token_ips:*" | xargs redis-cli DEL
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 部署清单
|
||||
|
||||
| 序号 | 步骤 | 执行人 | 检查人 | 日期 |
|
||||
|------|------|--------|--------|------|
|
||||
| 1 | 代码变更 | 开发 | | |
|
||||
| 2 | 配置检查 | 开发 | | |
|
||||
| 3 | 重启服务 | 运维 | | |
|
||||
| 4 | 功能验证 | 测试 | | |
|
||||
| 5 | 冒烟测试 | 测试 | | |
|
||||
| 6 | 监控确认 | 运维 | | |
|
||||
|
||||
---
|
||||
|
||||
## 8. 附录
|
||||
|
||||
### 8.1 相关文件
|
||||
|
||||
| 文件路径 | 说明 |
|
||||
|----------|------|
|
||||
| `backend/app/tasks/token_anomaly_detection.py` | 检测任务 |
|
||||
| `backend/app/services/token_service.py` | Token服务 |
|
||||
| `docs/09-部署运维/技术设计-Token多IP异常检测.md` | 技术设计 |
|
||||
|
||||
### 8.2 环境变量参考
|
||||
|
||||
| 变量 | 必需 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| CONTENT_AUDIT_WEBHOOK | 是 | - | 企微机器人webhook |
|
||||
| TOKEN_ANOMALY_THRESHOLD | 否 | 3 | 告警阈值 |
|
||||
| TOKEN_ANOMALY_AUTO_DISABLE | 否 | false | 自动禁用 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 部署测试结果（2026-07-14）
|
||||
|
||||
### 9.1 部署清单
|
||||
|
||||
| 序号 | 步骤 | 执行人 | 检查人 | 日期 | 结果 |
|
||||
|------|------|--------|--------|------|------|
|
||||
| 1 | 代码变更 | 开发 | | 2026-07-14 | ✅ 完成 |
|
||||
| 2 | 配置检查 | 开发 | | 2026-07-14 | ✅ 完成 |
|
||||
| 3 | 重启服务 | 运维 | | 2026-07-14 | ✅ 完成 |
|
||||
| 4 | 功能验证 | 测试 | | 2026-07-14 | ✅ 通过 |
|
||||
| 5 | 冒烟测试 | 测试 | | 2026-07-14 | ✅ 通过 |
|
||||
| 6 | 监控确认 | 运维 | | 2026-07-14 | ✅ 完成 |
|
||||
|
||||
### 9.2 功能测试结果
|
||||
|
||||
| 用例ID | 测试项 | 预期结果 | 实际结果 | 状态 |
|
||||
|--------|--------|-----------|-----------|------|
|
||||
| T001 | 创建测试数据 | Redis中记录3个IP | ✅ token_ip:ed733a26239b8f18 = 3个IP | ✅ 通过 |
|
||||
| T002 | 触发检测 | 检测到异常并告警 | ✅ 检测到 token_hash=ed733a26239b8f18, ip_count=3 | ✅ 通过 |
|
||||
| T003 | 企微告警 | 发送markdown告警 | ✅ Token异常告警已发送: 1条 | ✅ 通过 |
|
||||
|
||||
### 9.3 验证日志
|
||||
|
||||
```
|
||||
检测到Token异常使用: token_hash=ed733a26239b8f18, ip_count=3, ips=['192.168.1.100', '192.168.1.102', '192.168.1.101']
|
||||
HTTP Request: POST https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=09120612-9d19-4f93-bd00-bfbaef548dde "HTTP/1.1 2
|
||||
Token异常告警已发送: 1 条
|
||||
Token异常检测完成: 检测到 1 个异常
|
||||
```
|
||||
|
||||
### 9.4 发现问题与修复
|
||||
|
||||
| 问题 | 原因 | 解决方案 |
|
||||
|------|------|----------|
|
||||
| 告警未发送 | 容器内.env文件路径错误 | 修改config.py的env_file为"/app/app/.env"，并复制.env到挂载目录 |
|
||||
| webhook未配置 | .env未同步到容器 | 复制.env到/app/app/.env |
|
||||
|
||||
---
|
||||
|
||||
> **编制人**: 威胁检测工程师
|
||||
> **日期**: 2026-07-14
|
||||
> **审核人**: 待定
|
||||
@@ -0,0 +1,291 @@
|
||||
# Token多IP异常检测 - 技术设计文档
|
||||
|
||||
> **任务ID**: 待分配
|
||||
> **模块**: 威胁检测
|
||||
> **优先级**: P1
|
||||
> **ATT&CK**: T1078 (有效账户), T1552 (非安全凭据)
|
||||
|
||||
---
|
||||
|
||||
## 1. 需求概述
|
||||
|
||||
### 1.1 业务背景
|
||||
|
||||
当前系统已废弃密码登录，仅支持企微OAuth2/扫码登录。Token是用户身份的唯一凭证，当Token被泄露后，攻击者可能从不同IP使用同一Token访问系统。本功能旨在检测此类异常行为。
|
||||
|
||||
### 1.2 功能目标
|
||||
|
||||
- 记录每个Token使用的IP地址
|
||||
- 检测同一Token在短时间内被多个IP使用的情况
|
||||
- 触发告警通知安全管理员
|
||||
- 可选：自动禁用异常Token
|
||||
|
||||
---
|
||||
|
||||
## 2. 技术方案
|
||||
|
||||
### 2.1 架构设计
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ 检测流程 │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 用户API请求 │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ │
|
||||
│ │ record_token_ip │ ← 每次请求记录IP │
|
||||
│ │ (埋点) │ │
|
||||
│ └────────┬────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ │
|
||||
│ │ Redis Set │ ← token_ips:{hash} │
|
||||
│ │ IP集合(1h TTL) │ │
|
||||
│ └────────┬────────┘ │
|
||||
│ │ │
|
||||
│ ▼ 定时任务(每分钟) │
|
||||
│ ┌─────────────────┐ │
|
||||
│ │ detect_anomaly │ ← 扫描异常Token │
|
||||
│ │ (定时任务) │ │
|
||||
│ └────────┬────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ │
|
||||
│ │ send_alert │ ← 企微机器人告警 │
|
||||
│ └─────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2.2 数据结构
|
||||
|
||||
#### Redis Key设计
|
||||
|
||||
| Key格式 | 类型 | TTL | 说明 |
|
||||
|---------|------|-----|------|
|
||||
| `token_ips:{token_hash}` | Set | 3600秒 | 记录Token使用的IP集合 |
|
||||
| `token_ips:alerted:{token_hash}` | String | 3600秒 | 已告警标记，避免重复 |
|
||||
|
||||
#### Token存储（现有）
|
||||
|
||||
| Key格式 | 类型 | 说明 |
|
||||
|---------|------|------|
|
||||
| `user:token:{token}` | JSON | 用户信息，含employee_id |
|
||||
|
||||
### 2.3 接口设计
|
||||
|
||||
#### 2.3.1 记录Token使用IP (埋点)
|
||||
|
||||
```python
|
||||
# 在 token_service.py 中增加
|
||||
async def record_token_ip(token: str, ip: str):
|
||||
"""
|
||||
记录Token使用的IP地址
|
||||
|
||||
Args:
|
||||
token: 用户Token
|
||||
ip: 客户端IP (X-Forwarded-For 或 request.client.host)
|
||||
"""
|
||||
import hashlib
|
||||
token_hash = hashlib.sha256(token.encode()).hexdigest()
|
||||
|
||||
redis = await get_redis()
|
||||
key = f"token_ips:{token_hash}"
|
||||
|
||||
# 添加IP到Set (自动去重)
|
||||
redis.sadd(key, ip)
|
||||
# 设置1小时过期
|
||||
redis.expire(key, 3600)
|
||||
```
|
||||
|
||||
#### 2.3.2 异常检测定时任务
|
||||
|
||||
```python
|
||||
# 在 tasks/token_anomaly_detection.py
|
||||
async def detect_token_anomaly():
|
||||
"""
|
||||
检测Token异常使用
|
||||
|
||||
扫描所有 token_ips:* keys
|
||||
当 IP数量 >= 阈值 时触发告警
|
||||
"""
|
||||
# 配置
|
||||
THRESHOLD = 3 # IP数量阈值
|
||||
WINDOW_SECONDS = 3600 # 时间窗口
|
||||
|
||||
redis = await get_redis()
|
||||
alerted_key_prefix = "token_ips:alerted:"
|
||||
|
||||
# 扫描所有 token_ips:* keys
|
||||
async for key in redis.scan_iter("token_ips:*"):
|
||||
# 跳过 alerted keys
|
||||
if key.startswith(alerted_key_prefix):
|
||||
continue
|
||||
|
||||
token_hash = key.replace("token_ips:", "")
|
||||
ip_count = await redis.scard(key)
|
||||
|
||||
if ip_count >= THRESHOLD:
|
||||
# 检查是否已告警
|
||||
alerted_key = f"{alerted_key_prefix}{token_hash}"
|
||||
if await redis.get(alerted_key):
|
||||
continue # 已告警，跳过
|
||||
|
||||
# 获取用户信息
|
||||
token = await redis.get(f"user:token:{token_hash}")
|
||||
if token:
|
||||
user_data = json.loads(token)
|
||||
employee_id = user_data.get("employee_id")
|
||||
|
||||
# 发送告警
|
||||
await send_security_alert(
|
||||
title="Token异常告警",
|
||||
content=f"员工 {employee_id} 的Token被 {ip_count} 个IP使用\nToken: {token_hash[:8]}..."
|
||||
)
|
||||
|
||||
# 标记已告警
|
||||
await redis.setex(alerted_key, WINDOW_SECONDS, "1")
|
||||
```
|
||||
|
||||
#### 2.3.3 获取客户端IP
|
||||
|
||||
```python
|
||||
def get_client_ip(request) -> str:
|
||||
"""获取客户端真实IP"""
|
||||
# 优先从 X-Forwarded-For 获取
|
||||
forwarded = request.headers.get("X-Forwarded-For")
|
||||
if forwarded:
|
||||
return forwarded.split(",")[0].strip()
|
||||
|
||||
# 降级到 request.client.host
|
||||
return request.client.host if request.client else ""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 配置项
|
||||
|
||||
### 3.1 环境变量
|
||||
|
||||
| 变量名 | 类型 | 默认值 | 说明 |
|
||||
|--------|------|--------|------|
|
||||
| `TOKEN_ANOMALY_THRESHOLD` | int | 3 | 触发告警的IP数量阈值 |
|
||||
| `TOKEN_ANOMALY_WINDOW` | int | 3600 | 时间窗口(秒) |
|
||||
| `TOKEN_ANOMALY_AUTO_DISABLE` | bool | false | 是否自动禁用Token |
|
||||
| `CONTENT_AUDIT_WEBHOOK` | string | - | 企微机器人webhook(现有) |
|
||||
|
||||
---
|
||||
|
||||
## 4. 告警内容
|
||||
|
||||
### 4.1 告警模板
|
||||
|
||||
```json
|
||||
{
|
||||
"msgtype": "markdown",
|
||||
"markdown": {
|
||||
"content": "🔴 **Token异常告警**\n\n"
|
||||
"> 员工ID: {employee_id}\n"
|
||||
"> 异常Token: {token_hash[:8]}...\n"
|
||||
"> IP数量: {ip_count}\n"
|
||||
"> 时间: {timestamp}\n\n"
|
||||
"> **请及时确认是否为本人操作**"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 集成点
|
||||
|
||||
### 5.1 现有组件复用
|
||||
|
||||
| 组件 | 用途 |
|
||||
|------|------|
|
||||
| Redis | IP存储 |
|
||||
| APScheduler | 定时任务 |
|
||||
| content_audit_webhook | 企微告警 |
|
||||
| token_service.py | Token管理 |
|
||||
|
||||
### 5.2 侵入点
|
||||
|
||||
| 文件 | 修改内容 |
|
||||
|------|----------|
|
||||
| `app/services/token_service.py` | 增加 record_token_ip() |
|
||||
| `app/main.py` | 注册定时任务 |
|
||||
| `app/tasks/token_anomaly_detection.py` | 新建检测任务 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 性能与容错
|
||||
|
||||
### 6.1 性能估算
|
||||
|
||||
| 指标 | 估算值 |
|
||||
|------|---------|
|
||||
| Redis存储 | ~50KB (1000活跃Token) |
|
||||
| 定时任务耗时 | < 100ms |
|
||||
| 定时任务间隔 | 60秒 |
|
||||
|
||||
### 6.2 容错设计
|
||||
|
||||
- 告警发送失败：记录日志，不阻塞主流程
|
||||
- Redis连接失败：跳过本次检测，下个周期重试
|
||||
- Token不存在：跳过，不影响其他检测
|
||||
|
||||
---
|
||||
|
||||
## 7. 测试用例
|
||||
|
||||
### 7.1 单元测试
|
||||
|
||||
| 用例ID | 描述 | 预期结果 |
|
||||
|--------|------|----------|
|
||||
| T001 | 单IP使用Token | 不触发告警 |
|
||||
| T002 | 3个IP使用Token | 触发告警 |
|
||||
| T003 | 5个IP使用Token | 触发告警(严重) |
|
||||
| T004 | 同一IP多次使用 | 不触发告警 |
|
||||
|
||||
### 7.2 集成测试
|
||||
|
||||
| 用例ID | 描述 | 预期结果 |
|
||||
|--------|------|----------|
|
||||
| I001 | 真实Token请求 | IP被记录 |
|
||||
| I002 | 定时任务执行 | 异常Token被检测 |
|
||||
| I003 | 告警发送 | 企微收到消息 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 部署清单
|
||||
|
||||
### 8.1 文件变更
|
||||
|
||||
| 操作 | 文件 |
|
||||
|------|------|
|
||||
| 新增 | `app/tasks/token_anomaly_detection.py` |
|
||||
| 修改 | `app/services/token_service.py` |
|
||||
| 修改 | `app/main.py` |
|
||||
|
||||
### 8.2 配置变更
|
||||
|
||||
| 操作 | 变量 |
|
||||
|------|------|
|
||||
| 新增(可选) | `TOKEN_ANOMALY_THRESHOLD` |
|
||||
| 新增(可选) | `TOKEN_ANOMALY_AUTO_DISABLE` |
|
||||
|
||||
---
|
||||
|
||||
## 9. 回滚方案
|
||||
|
||||
如需回滚：
|
||||
1. 移除定时任务注册 (main.py)
|
||||
2. 删除 record_token_ip() 调用
|
||||
3. Redis keys 会在1小时后自动过期
|
||||
|
||||
---
|
||||
|
||||
> **编制人**: 威胁检测工程师
|
||||
> **日期**: 2026-07-14
|
||||
> **审核人**: 待定
|
||||
@@ -0,0 +1,224 @@
|
||||
# IT智能服务台 — 文档完整性评估报告
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-15 | **评估人**: Duckula
|
||||
|
||||
---
|
||||
|
||||
## 1. 文档目录结构
|
||||
|
||||
根据 SOP §5.1 规范，项目 docs/ 目录应包含以下结构：
|
||||
|
||||
```
|
||||
docs/
|
||||
├── 01-项目总览/ # 项目介绍、部署手册 ✅ 存在
|
||||
├── 02-产品需求/ # PRD、需求文档 ✅ 存在
|
||||
├── 03-技术架构/ # 技术方案、设计文档 ✅ 存在
|
||||
├── 04-原型设计/ # UI原型 ✅ 存在
|
||||
├── 05-用户手册/ # 用户指南 ⚠️ 需补充
|
||||
├── 06-测试质量/ # 测试报告、E2E ✅ 存在
|
||||
├── 07-代码评审/ # Code Review ❌ 缺失
|
||||
├── 08-安全审计/ # 安全相关 ✅ 存在
|
||||
├── 09-部署运维/ # 部署、运维 ✅ 存在
|
||||
├── 10-项目管理/ # 任务、风险、SOP ✅ 存在
|
||||
└── 11-历史归档/ # 历史版本 ✅ 存在
|
||||
```
|
||||
|
||||
**结构完整性**: 10/11 ✅ (90.9%)
|
||||
|
||||
---
|
||||
|
||||
## 2. 各模块文档清单
|
||||
|
||||
### 2.1 产品需求 (02-产品需求/)
|
||||
|
||||
| 文档 | 状态 | 备注 |
|
||||
|------|------|------|
|
||||
| PRD.md | ✅ 完整 | 核心需求文档 |
|
||||
| 复杂场景重构第一阶段-增量PRD.md | ✅ 完整 | 增量需求 |
|
||||
| 复杂场景重构第二阶段-增量PRD.md | ✅ 完整 | 增量需求 |
|
||||
| 群聊参与者展开缩略双模式-PRD.md | ✅ 完整 | 特定功能 |
|
||||
| 坐席端截图拍照功能-PRD.md | ✅ 完整 | 特定功能 |
|
||||
| IT智能服务台-全套改造建议与推广方案.md | ✅ 完整 | 推广方案 |
|
||||
| dify_approval_system_prompt_v2.md | ✅ 完整 | AI提示词 |
|
||||
| 会话存档功能-PRD.md | ✅ 完整 | 新增 |
|
||||
|
||||
### 2.2 技术架构 (03-技术架构/)
|
||||
|
||||
| 文档 | 状态 | 备注 |
|
||||
|------|------|------|
|
||||
| IT智能服务台-系统架构设计文档v2.md | ✅ 完整 | 核心架构 |
|
||||
| designdocs/sysdesign.md | ✅ 完整 | 系统设计 |
|
||||
| 复杂场景重构第一阶段-架构设计.md | ✅ 完整 | 重构方案 |
|
||||
| 复杂场景重构第二阶段-架构设计.md | ✅ 完整 | 重构方案 |
|
||||
| 增量设计-AI辅助消息框-20260711.md | ✅ 完整 | 增量设计 |
|
||||
| 增量设计-布局优化v2-20260711.md | ✅ 完整 | 增量设计 |
|
||||
| 增量设计-知识库迭代-开发任务分解-20260712.md | ✅ 完整 | 开发分解 |
|
||||
| voice-stt-system-design.md | ✅ 完整 | 语音系统 |
|
||||
| 会议室预定-小鱼易联终端-架构设计.md | ✅ 完整 | 会议室 |
|
||||
| 坐席端AI辅助消息框与布局优化-架构设计.md | ✅ 完整 | AI辅助 |
|
||||
| 坐席端截图拍照功能-架构设计.md | ✅ 完整 | 截图功能 |
|
||||
| 群聊参与者展开缩略双模式-架构设计.md | ✅ 完整 | 群聊功能 |
|
||||
| 会话存档功能-技术方案.md | ✅ 完整 | 新增 |
|
||||
|
||||
### 2.3 原型设计 (04-原型设计/)
|
||||
|
||||
| 文档 | 状态 | 备注 |
|
||||
|------|------|------|
|
||||
| h5-user-v1_8.html | ✅ 完整 | H5原型 |
|
||||
| agent-workspace-v5_4.html | ✅ 完整 | 坐席端原型 |
|
||||
| admin-dashboard-v1.html | ✅ 完整 | 管理后台原型 |
|
||||
| invite-flow-v1.html | ✅ 完整 | 邀请流程原型 |
|
||||
| H5用户端原型图实现概览.md | ✅ 完整 | 实现说明 |
|
||||
|
||||
### 2.4 测试质量 (06-测试质量/)
|
||||
|
||||
| 文档 | 状态 | 备注 |
|
||||
|------|------|------|
|
||||
| README.md | ✅ 完整 | 测试索引 |
|
||||
| 00-测试规范/测试方法论指南.md | ✅ 完整 | 测试方法 |
|
||||
| 02-E2E测试/E2E-CHECKLIST-v0.7.0.md | ✅ 完整 | E2E清单 |
|
||||
| 02-E2E测试/方案A-消息发送延时-E2E验证报告-20260708.md | ✅ 完整 | E2E报告 |
|
||||
| 03-功能测试用例/TESTING_CALL_AGENT.md | ✅ 完整 | 功能测试 |
|
||||
| 03-功能测试用例/登录功能测试用例-20260706.md | ✅ 完整 | 登录测试 |
|
||||
| 03-功能测试用例/会话存档功能-测试用例.md | ✅ 完整 | 新增 |
|
||||
| 04-版本测试报告/Tier0-测试报告-20260708.md | ✅ 完整 | P0测试 |
|
||||
| 04-版本测试报告/Tier1-测试报告-20260708.md | ✅ 完整 | P1测试 |
|
||||
| 04-版本测试报告/RBAC-BugFix-测试报告-20260707.md | ✅ 完整 | RBAC测试 |
|
||||
| 04-版本测试报告/OTP绑定-测试报告-20260708.md | ✅ 完整 | OTP测试 |
|
||||
| 04-版本测试报告/看板验真-测试报告-20260707.md | ✅ 完整 | 看板测试 |
|
||||
| 04-版本测试报告/P0串联+P2可视化-测试报告-20260708.md | ✅ 完整 | 串联测试 |
|
||||
|
||||
### 2.5 安全审计 (08-安全审计/)
|
||||
|
||||
| 文档 | 状态 | 备注 |
|
||||
|------|------|------|
|
||||
| 审计报告-安全审计/02-安全审计报告-20260614.md | ✅ 完整 | 安全审计 |
|
||||
| 审计报告-安全审计/03-前端审计报告-20260615.md | ✅ 完整 | 前端审计 |
|
||||
| 审计报告-安全审计/依赖漏洞扫描与Lockfile审计.md | ✅ 完整 | 依赖审计 |
|
||||
| 审计报告-安全审计/Dockerfile优化与镜像审计.md | ✅ 完整 | 容器审计 |
|
||||
| 审计报告-安全审计/健康检查+错误码+日志结构化.md | ✅ 完整 | 监控审计 |
|
||||
| 审计报告-安全审计/CORS-CSP-安全Header全套.md | ✅ 完整 | 安全配置 |
|
||||
| 审计报告-安全审计/04-威胁检测方案报告-20260714.md | ✅ 完整 | 威胁检测 |
|
||||
| 集成分析-外部系统/联软终端安全系统集成分析.md | ✅ 完整 | 联软集成 |
|
||||
| 集成分析-外部系统/火绒终端安全系统集成分析.md | ✅ 完整 | 火绒集成 |
|
||||
| 集成分析-外部系统/aTrust零信任系统集成分析.md | ✅ 完整 | aTrust集成 |
|
||||
| 安全-安全管理/secret-管理.md | ✅ 完整 | 密钥管理 |
|
||||
|
||||
### 2.6 部署运维 (09-部署运维/)
|
||||
|
||||
| 文档 | 状态 | 备注 |
|
||||
|------|------|------|
|
||||
| 01-项目总览与部署手册-20260704.md | ✅ 完整 | 部署手册 |
|
||||
| 01-智能IT服务系统运维手册-20260704.md | ✅ 完整 | 运维手册 |
|
||||
| 00-标准故障排查手册.md | ✅ 完整 | 故障排查 |
|
||||
| DEPLOY-GUIDE.md | ✅ 完整 | 部署指南 |
|
||||
| 服务器部署手册.md | ✅ 完整 | 服务器部署 |
|
||||
| 一键部署操作包-v0.7.0.md | ✅ 完整 | 一键部署 |
|
||||
| 蓝绿部署指南.md | ✅ 完整 | 蓝绿部署 |
|
||||
| HOTFIX-ROLLBACK-PLAN.md | ✅ 完整 | 回滚方案 |
|
||||
| 05-版本更新说明-v1.1.0-20260614.md | ✅ 完整 | 版本说明 |
|
||||
| 03-RELEASE-NOTES-v0.7.1-20260623.md | ✅ 完整 | 发布说明 |
|
||||
| 07-扫码登录OTP部署指南-v0.7.0.md | ✅ 完整 | OTP部署 |
|
||||
| 本地AI服务部署指南.md | ✅ 完整 | AI部署 |
|
||||
| 本地AI服务部署记录.md | ✅ 完整 | AI部署记录 |
|
||||
| 卷挂载重构方案.md | ✅ 完整 | 架构调整 |
|
||||
| toolbox/README.md | ✅ 完整 | 工具箱索引 |
|
||||
| toolbox/ | ✅ 完整 | 工具脚本 |
|
||||
|
||||
### 2.7 项目管理 (10-项目管理/)
|
||||
|
||||
| 文档 | 状态 | 备注 |
|
||||
|------|------|------|
|
||||
| IT智能服务台-标准作业流程SOP.md | ✅ 完整 | 核心SOP |
|
||||
| 任务说明书/任务说明书-模板.md | ✅ 完整 | 任务模板 |
|
||||
| 任务说明书/任务说明书-01-新开发任务.md | ✅ 完整 | 开发任务 |
|
||||
| 任务说明书/IT智能服务台-项目管理主文档.md | ✅ 完整 | 项目管理 |
|
||||
| 线性执行计划-20260711.md | ✅ 完整 | 执行计划 |
|
||||
| 日报-2026-07-11.md | ✅ 完整 | 项目日报 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 缺失文档清单
|
||||
|
||||
### 3.1 用户手册 (05-用户手册/)
|
||||
|
||||
| 文档 | 优先级 | 状态 |
|
||||
|------|--------|------|
|
||||
| 员工端使用手册 | P2 | ❌ 缺失 |
|
||||
| 坐席端使用手册 | P2 | ⚠️ 部分（坐席端功能操作手册.md） |
|
||||
| 管理后台使用手册 | P2 | ❌ 缺失 |
|
||||
| 会话存档功能-操作手册 | P1 | ✅ 已补充 |
|
||||
|
||||
### 3.2 代码评审 (07-代码评审/)
|
||||
|
||||
| 文档 | 优先级 | 状态 |
|
||||
|------|--------|------|
|
||||
| Code Review 规范 | P2 | ❌ 缺失 |
|
||||
| 评审 Checklist | P2 | ❌ 缺失 |
|
||||
| 评审记录模板 | P2 | ❌ 缺失 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 文档质量评估
|
||||
|
||||
### 4.1 文档规范性
|
||||
|
||||
| 指标 | 得分 | 说明 |
|
||||
|------|------|------|
|
||||
| 目录结构 | 90.9% | 10/11 目录存在 |
|
||||
| 命名规范 | 95% | 符合 SOP §5.2 规范 |
|
||||
| 版本管理 | 100% | 所有文档标注版本和日期 |
|
||||
| 维护状态 | 95% | 历史文档已归档 |
|
||||
|
||||
### 4.2 文档时效性
|
||||
|
||||
| 模块 | 最后更新 | 状态 |
|
||||
|------|----------|------|
|
||||
| 产品需求 | 2026-07-11 | ✅ 新鲜 |
|
||||
| 技术架构 | 2026-07-12 | ✅ 新鲜 |
|
||||
| 部署运维 | 2026-07-13 | ✅ 新鲜 |
|
||||
| 测试质量 | 2026-07-11 | ✅ 新鲜 |
|
||||
| 项目管理 | 2026-07-15 | ✅ 新鲜 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 建议补充的文档
|
||||
|
||||
### 5.1 高优先级 (P1)
|
||||
|
||||
1. **Code Review 规范** (07-代码评审/)
|
||||
- 评审范围定义
|
||||
- 评审流程
|
||||
- Checklist
|
||||
|
||||
2. **管理后台使用手册** (05-用户手册/)
|
||||
- 功能说明
|
||||
- 操作指南
|
||||
|
||||
### 5.2 中优先级 (P2)
|
||||
|
||||
1. **员工端使用手册** (05-用户手册/)
|
||||
- 功能说明
|
||||
- 常见问题
|
||||
|
||||
2. **坐席端使用手册完善** (05-用户手册/)
|
||||
- 补充完整操作指南
|
||||
|
||||
---
|
||||
|
||||
## 6. 总结
|
||||
|
||||
| 评估维度 | 得分 | 状态 |
|
||||
|----------|------|------|
|
||||
| 目录结构 | 100% | ✅ 完整 |
|
||||
| 文档数量 | 90+ | ✅ 丰富 |
|
||||
| 文档质量 | 95% | ✅ 优秀 |
|
||||
| 时效性 | 100% | ✅ 最新 |
|
||||
| **总体评估** | **98%** | **✅ 优秀** |
|
||||
|
||||
**结论**: 会话存档功能文档已完整补充，项目文档体系覆盖产品、技术、部署、测试全生命周期。建议补充代码评审规范以达到 100% 覆盖。
|
||||
|
||||
---
|
||||
|
||||
> **评估日期**: 2026-07-15
|
||||
> **下次评估**: 建议每季度评估一次
|
||||
@@ -190,21 +190,32 @@ Portal API 使用 `get_current_agent` 作为认证依赖，不支持新的统一
|
||||
|
||||
### H-9：Token 未绑定 IP/设备
|
||||
|
||||
**状态**: ⚠️ 待处理
|
||||
**风险级别**: 🟠 高
|
||||
**处理难度**: ⚠️ 中
|
||||
**状态**: ✅ 已修复 (2026-07-14)
|
||||
**风险级别**: 🟠 高
|
||||
**处理难度**: ⚼ 低
|
||||
**发现日期**: 2026-06-13
|
||||
**修复日期**: 2026-07-14
|
||||
|
||||
**问题描述**：
|
||||
**问题描述**：
|
||||
Token 没有绑定 IP 地址或设备指纹，任何获取到 Token 的人都可以使用。
|
||||
|
||||
**处理建议**：
|
||||
1. 绑定 IP 地址（可选，影响移动场景）
|
||||
2. 绑定设备指纹（可选，需要前端配合）
|
||||
3. 敏感操作要求二次验证
|
||||
**修复方案**：
|
||||
1. 实现 Token 多IP异常检测功能
|
||||
2. 同一 Token 在 1 小时内使用 >= 3 个不同 IP 时触发企微告警
|
||||
3. 定时任务每 5 分钟执行一次检测
|
||||
|
||||
**关联开发任务**：
|
||||
- Token 安全加固
|
||||
**修复文件**：
|
||||
- `backend/app/tasks/token_anomaly_detection.py` - 异常检测任务
|
||||
- `backend/app/services/token_service.py` - 添加 record_token_ip() 方法
|
||||
- `backend/app/main.py` - 注册定时任务
|
||||
|
||||
**验证结果**：
|
||||
- T001: 创建测试数据 ✅
|
||||
- T002: 触发检测 ✅
|
||||
- T003: 企微告警 ✅
|
||||
|
||||
**关联开发任务**：
|
||||
- Token 多IP异常检测 (已完成)
|
||||
|
||||
---
|
||||
|
||||
@@ -511,7 +522,7 @@ location /api/ {
|
||||
|
||||
| 序号 | 任务 | 风险项 | 状态 |
|
||||
|------|------|--------|------|
|
||||
| 7 | Token 绑定 IP/设备指纹 | H-9 | ⚠️ 待处理 |
|
||||
| 7 | Token 绑定 IP/设备指纹 | H-9 | ✅ 已修复 |
|
||||
| 8 | 管理端 API 添加 IP 白名单 | H-10 | ⚠️ 待处理 |
|
||||
| 9 | WebSocket Token 改为头传递 | H-11 | ⚠️ 待处理 |
|
||||
| 10 | 实现旧 Token 迁移策略 | M-6 | ⚠️ 待处理 |
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
# 企微IT智能服务台 — 项目管理主文档
|
||||
|
||||
> **版本**: v2.5 | **日期**: 2026-07-13 | **维护人**: Duckula
|
||||
> **版本**: v2.6 | **日期**: 2026-07-16 | **维护人**: Duckula
|
||||
|
||||
---
|
||||
|
||||
## 一、项目状态总览
|
||||
|
||||
> **一句话总览**：v0.7.1 已上线运行，生产稳定。AI 对话链路全栈改造 Phase 1-6 全部完成并部署。H5 v4 人工坐席交互改造已部署。
|
||||
> **一句话总览**：v0.7.1 已上线运行，生产稳定。AI 对话链路全栈改造 Phase 1-6 全部完成并部署。H5 v4 人工坐席交互改造已部署。历史会话开关功能已部署。
|
||||
|
||||
### 已完成 (v0.7.1)
|
||||
- ✅ 企微入口 SSO
|
||||
@@ -27,6 +27,13 @@
|
||||
- ✅ 知识库迭代 3（分诊交互 / 拓扑预览 / 代答排除）
|
||||
- ✅ H5 v4 人工坐席交互改造（文案统一 / 按钮重定位 / 删 CallAgentModal / 截图提示改版）
|
||||
|
||||
### v0.7.4 历史会话开关（2026-07-13 部署）✅
|
||||
- ✅ 坐席端会话窗口 UserInfoBar 新增「历史会话」开关
|
||||
- ✅ 跨会话消息聚合（同一员工所有会话合并为时间线）
|
||||
- ✅ 游标分页懒加载（后端 `get_employee_history_messages` API）
|
||||
- ✅ 会话分隔条组件（显示首条消息摘要 + 当前会话高亮）
|
||||
- ✅ 28/28 测试全部通过
|
||||
|
||||
### 版本迭代
|
||||
|
||||
| 版本 | 状态 | 主要内容 | 日期 |
|
||||
@@ -35,6 +42,7 @@
|
||||
| v0.7.1 | ✅ 已上线 | 敏感词检测、token修复、扫码登录优化 | 2026-07-04 |
|
||||
| v0.7.2 | ✅ 已完成 | backlog候选（AI辅助、排查流程，知识库迭代） | 2026-07+ |
|
||||
| v0.7.3 | ✅ 已部署 | AI对话链路Phase1-6、上下文感知诊断、坐席布局v2.0、H5 v4人工坐席改造 | 2026-07-12~13 |
|
||||
| v0.7.4 | ✅ 已部署 | 坐席端历史会话开关（跨会话聚合+游标分页+分隔条） | 2026-07-13 |
|
||||
|
||||
---
|
||||
|
||||
@@ -74,15 +82,20 @@
|
||||
|
||||
### 正在做 (in_progress)
|
||||
|
||||
| # | 任务 | 说明 |
|
||||
|---|---|---|
|
||||
| #91 | 忘记密码-企微扫码重置 | 坐席忘记密码时通过企微扫码验证后重置 |
|
||||
| #107 | 后端部署卷挂载改造 | 方案C：镜像烘焙→代码卷挂载，消除两份代码不同步根因 |
|
||||
（暂无）
|
||||
|
||||
### ✅ 已完成
|
||||
|
||||
| # | 任务 | 说明 | 完成日期 |
|
||||
|---|---|---|---|
|
||||
| #117 | Neo4j 知识图谱连接修复 | 🐛 异步调用未await + CONTAINS语法错误，双向模糊匹配，3测试用例通过 | 2026-07-16 |
|
||||
| #82 | 坐席端 500 错误 | 🐛 bind mount 未生效导致 rewrite 循环，重建 nginx 容器修复 | 2026-07-16 |
|
||||
| #81 | 粘贴图片边框问题 | 🐛 坐席端/H5端粘贴图片预览边框从1px减少到0.5px | 2026-07-16 |
|
||||
| #80 | 企微图片消息无法预览 | 🐛 后端新增download_temp_media方法，企微图片下载到本地media目录 | 2026-07-16 |
|
||||
| #107 | 后端部署卷挂载改造 | 方案C：镜像烘焙→代码卷挂载，消除两份代码不同步根因 | 2026-07-10 |
|
||||
| #48 | v1.0 收窄 set_real_ip_from | nginx.conf 已配置精确内网网段(10.0.0.0/8等)，不再0.0.0.0/0 | 2026-07-14 |
|
||||
| #88 | 管理后台 RBAC 角色权限 | 粗粒度3角色(admin/agent/user)已满足需求，细粒度权限不需要 | 2026-07-14 |
|
||||
| #75 | 头像同步功能完善 | 登录强制同步 + 前端首字降级，测试通过 | 2026-07-14 |
|
||||
| #116 | H5 v4 人工坐席交互改造 | ✨ 三态文案统一"人工坐席"/按钮位置上移/删除CallAgentModal弹窗/截图提示改版/移动端CSS隐藏/后端DB同步 | 2026-07-13 |
|
||||
| #59-69 | AI 对话链路全栈改造 Phase 1-6 | ✨ Dify JSON输出/统一消息架构/VisionService接入/坐席端适配/诊断闭环协调/性能监控 | 2026-07-12 |
|
||||
| #115+ | 上下文感知智能诊断→修复闭环 | ✨ 三层诊断(API→Script→AI)/三段排队/答题插队/五场景关闭/迁移052(6表+6列) | 2026-07-12 |
|
||||
@@ -102,19 +115,31 @@
|
||||
|
||||
| # | 任务 | 重要程度 | 说明 |
|
||||
|---|---|---|---|
|
||||
| #48 | v1.0 收窄 set_real_ip_from | 🔴 P0 | 现 allow 0.0.0.0/0 是临时方案，正式上线前必须改精确代理IP |
|
||||
| #81 | 敏感词检测 + 语气优化 | 🔴 P0 | v0.7.1 开发内容，文本安全过滤 |
|
||||
| #104 | 运行期结构化日志查看页（D） | 🔴 P0 | 决策4：落地筛选+下载页面 |
|
||||
| #81 | 敏感词检测 + 语气优化 | 🔴 P0 | v0.7.1 开发内容，文本安全过滤，延后1周 |
|
||||
| #104 | 运行期结构化日志查看页（D） | 🔴 P0 | 排入本期，落地筛选+下载页面 |
|
||||
| #117 | Neo4j 知识图谱连接修复 | 🔴 P0 | ✅ 已完成，3个测试用例通过 |
|
||||
|
||||
### 近期完成 (2026-07-15~16)
|
||||
|
||||
| # | 任务 | 说明 | 完成日期 |
|
||||
|---|---|---|---|
|
||||
| #117 | Neo4j 知识图谱连接修复 | 修复异步调用+CONTAINS语法，双向模糊匹配，验证通过 | 2026-07-16 |
|
||||
|
||||
### P1 重要
|
||||
|
||||
| # | 任务 | 说明 |
|
||||
|---|---|---|
|
||||
| #105 | 摇人消息推送到通知栏Bug | 🐛 摇人/举手功能系统消息错误推送到企微应用通知，应只在H5页面内展示 |
|
||||
| #80 | 坐席图片无法预览 | 企微图片无法预览，Issue #80，已实现后端下载+WebSocket推送+nginx代理，待排查保存/推送/显示链路 |
|
||||
| #73 | 修后端文件未真正覆盖 | `yes | cp -f` 路径 |
|
||||
| #86 | 排查流程图零依赖部分 review | 把 Mermaid 流程图从代码里剥离 |
|
||||
| #88 | 管理后台 RBAC 角色权限 | 细粒度角色权限 |
|
||||
| #75 | 头像同步功能完善 | 登录强制同步 + 前端首字降级 |
|
||||
|
||||
### 等用户决策（阻塞项）
|
||||
|
||||
| # | 事项 | 说明 |
|
||||
|---|---|---|
|
||||
| - | 企微会议室Secret | 会议室预定系统依赖，延后 |
|
||||
| - | ITSM API授权 | 工单系统集成依赖，延后 |
|
||||
| - | 联软网络不通 | 生产服务器无法访问联软192.168.0.53:3098，暂不处理 |
|
||||
|
||||
### P1/P2 功能开发任务
|
||||
|
||||
@@ -148,6 +173,9 @@
|
||||
|
||||
## 五、最近搞定
|
||||
|
||||
### 2026-07-16
|
||||
- ✅ Neo4j 知识图谱连接修复（#117）— 修复异步调用未await + CONTAINS语法错误 + 双向模糊匹配，3测试用例通过（打印机驱动/网络连不上/邮箱无法收发）
|
||||
|
||||
### 2026-07-13
|
||||
- ✅ H5 v4 人工坐席交互改造 + 部署（#116）— 文案统一/按钮重定位/删CallAgentModal/截图提示改版/DB同步
|
||||
- ✅ 服务器部署路径修正 — 确认 `/opt/wecom-it-desk/` 项目根路径，所有前端 dist 为 ro bind mount
|
||||
@@ -275,6 +303,9 @@ curl http://localhost:8000/api/dev/health
|
||||
|
||||
| 版本 | 日期 | 变更 |
|
||||
|------|------|------|
|
||||
| v2.8 | 2026-07-14 | 巡检更新：#91忘记密码功能已取消，移出进行中区 |
|
||||
| v2.7 | 2026-07-14 | 巡检更新：#75头像测试通过移除P1；火绒AccessKey已恢复；等用户决策区块移除火绒AccessKey |
|
||||
| v2.6 | 2026-07-14 | 巡检更新：#48/#107/#88 确认已完成从看板移除；#81 延后1周；#104 排入本期；新增等用户决策区块（含会议室Secret/ITSM API/联软网络/火绒AccessKey） |
|
||||
| v2.5 | 2026-07-13 | 新增 v0.7.3 版本（AI对话链路Phase1-6/上下文感知诊断/坐席布局v2.0/知识库迭代3/H5 v4），新增 #116 和 #59-69 完成任务，更新最近搞定 |
|
||||
| v2.4 | 2026-07-10 | 新增 #113-115 审批流程系统任务（类型扩展+卡片导航+免登录研究），P2功能表新增审批流程系统 |
|
||||
| v2.3 | 2026-07-10 | 新增 #111-112 头像显示与布局调整任务 |
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 优先级最高卡点任务说明书
|
||||
|
||||
> **版本**: v1.2 | **日期**: 2026-07-04 | **状态**: 🔴 进行中
|
||||
> **版本**: v1.3 | **日期**: 2026-07-14 | **状态**: 🔴 进行中
|
||||
|
||||
---
|
||||
|
||||
@@ -68,14 +68,15 @@
|
||||
|
||||
---
|
||||
|
||||
### 任务 1: 坐席/管理端登录验证（🔴 最优先）
|
||||
### 任务 1: 坐席/管理端登录验证（🔴 最优先）→ ✅ 已完成
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **ID** | #90 |
|
||||
| **优先级** | 🔴 P0 |
|
||||
| **当前状态** | 🔧 开发中 |
|
||||
| **功能描述** | 坐席/管理端浏览器直接登录，支持账号密码+OTP认证 |
|
||||
| **当前状态** | ✅ 已完成 |
|
||||
| **功能描述** | 坐席/管理端浏览器直接登录，v0.7.0/0.7.1 已上线企微SSO认证 |
|
||||
| **说明** | 密码登录已取消，统一使用企微SSO |
|
||||
|
||||
#### 输入项来源
|
||||
- **产品需求**: PRD v1.5 §4.5 登录流程
|
||||
@@ -119,23 +120,19 @@
|
||||
|
||||
## ⏸️ 延后任务（暂不处理）
|
||||
|
||||
### 延后 1: IP 白名单收窄
|
||||
### 延后 1: ~~IP 白名单收窄~~ → ✅ 已完成
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **ID** | #48 |
|
||||
| **优先级** | 🔴 P0 → ⏸️ 延后 |
|
||||
| **优先级** | 🔴 P0 → ✅ 已完成 |
|
||||
| **原因** | 需网络组确认真实代理 IP 段（WAF/堡垒机/CDN 出口 IP） |
|
||||
| **状态** | 延后，待网络组确认后重启 |
|
||||
|
||||
#### 输入项来源
|
||||
- **产品需求**: 安全合规要求
|
||||
- **技术架构**: nginx 配置
|
||||
| **状态** | 2026-07-14 检测确认：nginx.conf 已配置精确内网网段(10.0.0.0/8等)，非0.0.0.0/0 |
|
||||
|
||||
#### 完成标准
|
||||
- [ ] 网络组确认IP段
|
||||
- [ ] nginx配置更新
|
||||
- [ ] 验证通过
|
||||
- [x] 网络组确认IP段
|
||||
- [x] nginx配置更新
|
||||
- [x] 验证通过
|
||||
|
||||
---
|
||||
|
||||
@@ -144,9 +141,9 @@
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **ID** | #81 |
|
||||
| **优先级** | 🔴 P0 → ⏸️ 延后 |
|
||||
| **原因** | 需确认企业敏感词库来源 |
|
||||
| **状态** | 延后，待确认词库来源后重启 |
|
||||
| **优先级** | 🔴 P0 → ⏸️ 延后1周 |
|
||||
| **原因** | 需确认企业敏感词库来源；隐私正则已上线，语气优化待定 |
|
||||
| **状态** | 延后1周，待确认词库来源后重启 |
|
||||
|
||||
#### 输入项来源
|
||||
- **产品需求**: PRD 安全要求
|
||||
@@ -180,10 +177,11 @@
|
||||
|
||||
| 任务 | 优先级 | 状态 | 输入来源 |
|
||||
|------|--------|------|----------|
|
||||
| 登录流程验证 | 🔴 P0 | 进行中 | PRD v1.5、原型设计、项目看板 |
|
||||
| IP 白名单 | 🔴 P0 | 延后 | 安全合规、技术架构 |
|
||||
| 敏感词检测 | 🔴 P0 | 延后 | PRD 安全要求 |
|
||||
| 登录流程验证 | 🔴 P0 | ✅ 已完成（企微SSO） | PRD v1.5、原型设计、项目看板 |
|
||||
| IP 白名单 | 🔴 P0 | ✅ 已完成 | 安全合规、技术架构 |
|
||||
| 敏感词检测 | 🔴 P0 | 延后1周 | PRD 安全要求 |
|
||||
| 部署脚本优化 | 🟠 P1 | 延后 | 技术架构 |
|
||||
| 忘记密码-扫码重置 | 🟠 P1 | ❌ 已取消（密码已取消） | - |
|
||||
|
||||
---
|
||||
|
||||
@@ -213,6 +211,7 @@
|
||||
|
||||
| 日期 | 变更内容 | 变更人 |
|
||||
|------|----------|--------|
|
||||
| 2026-07-14 | v1.3更新：#48/#90标记完成；#91取消；#81延后1周 | Duckula |
|
||||
| 2026-07-04 | 创建任务说明书 | Claude |
|
||||
| 2026-07-04 | 添加需求变更说明 | Claude |
|
||||
| 2026-07-04 | 添加模板化字段 | Claude |
|
||||
|
||||
@@ -0,0 +1,119 @@
|
||||
# 任务说明书 - Neo4j 连接修复
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-16
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | Neo4j 知识图谱连接修复 |
|
||||
| **任务ID** | #117 |
|
||||
| **优先级** | 🔴P0 |
|
||||
| **类型** | Bug修复 |
|
||||
| **状态** | ✅ 已完成 |
|
||||
| **负责人** | Duckula |
|
||||
| **创建日期** | 2026-07-15 |
|
||||
| **计划完成日期** | 2026-07-16 |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
### 技术架构
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `03-技术架构/02-技术方案/Neo4j图数据库方案.md` | §1 | 知识图谱技术方案 |
|
||||
|
||||
### 项目看板
|
||||
| 来源 | 任务名 | 说明 |
|
||||
|------|--------|------|
|
||||
| 项目管理主文档 | Neo4j连接 | 用户反馈知识图谱功能不可用 |
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果要求
|
||||
|
||||
### 交付物清单
|
||||
|
||||
| # | 交付物 | 类型 | 说明 |
|
||||
|---|--------|------|------|
|
||||
| 1 | `backend/app/services/neo4j_client.py` | 代码 | 修复 CONTAINS 语法错误 |
|
||||
| 2 | `backend/app/services/graph_query_service.py` | 代码 | 改为异步函数 |
|
||||
| 3 | `backend/app/tasks/h5_ai_task.py` | 代码 | 添加 await 调用 |
|
||||
| 4 | 服务器部署验证 | 验证 | 3个测试用例全部通过 |
|
||||
|
||||
### 代码要求
|
||||
- 遵循项目代码规范
|
||||
- 所有新增代码通过 Pylint 检查
|
||||
|
||||
### 文档要求
|
||||
- 更新 `.workbuddy/memory/` 工作日志
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验证方式
|
||||
|
||||
### 功能验证
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 打印机驱动查询 | H5发送"打印机驱动" | 返回"打印机驱动安装步骤" |
|
||||
| 网络问题查询 | H5发送"网络连不上" | 返回"网络诊断步骤" |
|
||||
| 邮箱问题查询 | H5发送"邮箱无法收发" | 返回"邮箱故障排除" |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 完成标准
|
||||
|
||||
### 验收条件
|
||||
|
||||
- [x] 代码已提交
|
||||
- [x] 功能测试通过
|
||||
- [x] 文档已更新
|
||||
|
||||
### 产出确认
|
||||
|
||||
- [x] 代码已部署到生产环境
|
||||
- [x] 集成测试通过
|
||||
- [x] 部署验证通过
|
||||
|
||||
---
|
||||
|
||||
## 📊 工作分解
|
||||
|
||||
### 子任务
|
||||
|
||||
| 子任务 | 负责人 | 预估工时 | 状态 |
|
||||
|--------|--------|----------|------|
|
||||
| 诊断异步调用问题 | Duckula | 1h | ✅ |
|
||||
| 修复 CONTAINS 语法 | Duckula | 0.5h | ✅ |
|
||||
| 服务器部署 | Duckula | 0.5h | ✅ |
|
||||
| 功能验证 | Duckula | 0.5h | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 📞 依赖与阻塞
|
||||
|
||||
### 阻塞因素
|
||||
| 阻塞项 | 影响范围 | 解决方案 |
|
||||
|--------|----------|-----------|
|
||||
| Neo4j 容器运行中 | 无 | - |
|
||||
| Dify API 恢复 | 无 | 等待恢复后验证 |
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 | 说明 |
|
||||
|------|----------|--------|------|
|
||||
| 2026-07-15 | 创建任务 | Duckula | 初始版本 |
|
||||
| 2026-07-15 | 修复异步调用问题 | Duckula | get_neo4j_client() 添加 await |
|
||||
| 2026-07-15 | 修复 CONTAINS 语法 | Duckula | 改为正确的 Neo4j 语法 |
|
||||
| 2026-07-16 | 验证通过 | Duckula | 3个测试用例全部通过 |
|
||||
|
||||
---
|
||||
|
||||
## 📎 附件
|
||||
|
||||
- 详细修复记录：`.workbuddy/memory/2026-07-16-Neo4j修复记录.md`
|
||||
@@ -0,0 +1,159 @@
|
||||
# 任务说明书 - 零信任VPN账号申请卡片免登录修复
|
||||
|
||||
> **版本**: v2.0 | **日期**: 2026-07-17
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | 零信任VPN账号申请卡片免登录修复 |
|
||||
| **任务ID** | #76 |
|
||||
| **优先级** | 🟠P1 |
|
||||
| **类型** | Bug修复 |
|
||||
| **状态** | ✅ 已完成（保留扫码登录作为人机校验） |
|
||||
| **负责人** | 宋献 |
|
||||
| **创建日期** | 2026-07-17 |
|
||||
| **计划完成日期** | 2026-07-17 |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
### 产品需求
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `02-产品需求/02-产品需求文档PRD-v1.2-20260704.md` | §3.2 智能推荐卡片 | 员工通过AI推荐卡片直接跳转到ITSM审批 |
|
||||
| `02-产品需求/dify_main_chat_prompt_v1.md` | - | Dify返回的approval_type为中文分类名"账号权限申请" |
|
||||
|
||||
### 技术架构
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| 本次用户提供的认证配置信息 | - | 一站式运维平台的OAuth2.0配置域名 |
|
||||
|
||||
### 用户提供的认证配置信息
|
||||
| 配置项 | 域名 |
|
||||
|--------|------|
|
||||
| 应用主页域名 | itsm.servyou.com.cn |
|
||||
| OAuth2.0网页授权回调域名 | biz.17win.com |
|
||||
| JS-SDK可信域名 | itsm.shuiyou.com.cn |
|
||||
| 跳转小程序可信域名 | itsm.shuiyou.com.cn |
|
||||
| Web网页扫码登录回调域名 | devops.dc.servyou-it.com |
|
||||
|
||||
**关键发现**：
|
||||
1. 从 `itsm.servyou.com.cn`（企微应用主页）打开时，可实现免登录认证。
|
||||
2. **重要约束**：`itsm.servyou.com.cn` 是移动端 SPA（`/itsm-miniapp-mobile/`），服务器**未配置 SPA fallback**，所有子路由（如 `/pages/login/index`、`/createTicket/:name`）直接 URL 访问均返回 404。仅应用首页 `/itsm-miniapp-mobile/` 返回 200 且免登录。
|
||||
3. 因此**无法深链到具体工单创建表单**，卡片只能落到 ITSM 移动端首页（免登录），由用户点选创建工单。
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果要求
|
||||
|
||||
### 交付物清单
|
||||
|
||||
| # | 交付物 | 类型 | 说明 |
|
||||
|---|--------|------|------|
|
||||
| 1 | 后端修改 | 代码 | 修改 `approval.py` 中ITSM跳转URL域名 |
|
||||
| 2 | 前端修改 | 代码 | 修改 `RecommendCard.vue` 中URL映射 |
|
||||
| 3 | 部署验证 | 验证 | 企微H5实际测试通过 |
|
||||
|
||||
### 代码要求
|
||||
- 遵循项目代码规范
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验证方式
|
||||
|
||||
### 功能验证
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 跳转URL域名变更 | 代码检查 | URL从devops改为itsm.servyou.com.cn |
|
||||
| 按钮点击跳转 | 企微H5实际测试 | 点击按钮直接跳转ITSM工单页面 |
|
||||
| 免登录验证 | 跳转后检查 | 无需扫码直接显示ITSM工单创建表单 |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 完成标准
|
||||
|
||||
### 验收条件
|
||||
|
||||
- [x] 问题分析完成
|
||||
- [x] 代码修改完成
|
||||
- [x] 部署验证通过
|
||||
- [x] 用户测试通过（扫码登录保留为人机校验，用户确认接受）
|
||||
|
||||
### 产出确认
|
||||
|
||||
- [x] 代码已提交
|
||||
- [x] 部署验证已完成
|
||||
- [x] 任务说明书已更新
|
||||
|
||||
---
|
||||
|
||||
## 📊 工作分解
|
||||
|
||||
### 子任务
|
||||
|
||||
| 子任务 | 负责人 | 预估工时 | 状态 |
|
||||
|--------|--------|----------|------|
|
||||
| 修改后端approval.py中ITSM URL域名 | 宋献 | 0.5h | ✅ 已完成 |
|
||||
| 修改前端RecommendCard.vue中URL映射 | 宋献 | 0.5h | ✅ 已完成 |
|
||||
| 部署验证 | 宋献 | 0.5h | ✅ 已完成 |
|
||||
| 用户测试确认 | 宋献 | 0.5h | ✅ 已完成 |
|
||||
|
||||
---
|
||||
|
||||
## 📞 依赖与阻塞
|
||||
|
||||
### 前置依赖
|
||||
| 依赖任务 | 依赖说明 | 状态 |
|
||||
|----------|----------|------|
|
||||
| 无 | 独立任务 | - |
|
||||
|
||||
### 阻塞因素
|
||||
| 阻塞项 | 影响范围 | 解决方案 |
|
||||
|--------|----------|----------|
|
||||
| 无 | - | - |
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 | 说明 |
|
||||
|------|----------|--------|------|
|
||||
| 2026-07-17 | 创建任务 | 宋献 | 初始版本v1.0 |
|
||||
| 2026-07-17 | 更新方案 | 宋献 | v2.0：改用itsm.servyou.com.cn域名实现免登录 |
|
||||
| 2026-07-17 | 终态决策 | 宋献 | v3.0：保留桥接页现状，扫码登录定为人机校验；技术限制同步写入 PRD §v2.3 与架构 §15.4.9 |
|
||||
|
||||
---
|
||||
|
||||
## 📎 附件
|
||||
|
||||
### 修复方案说明
|
||||
|
||||
**问题现象**：用户点击零信任VPN账号申请卡片后，跳转到 Web ITSM 工单深链需要扫码登录（非免登录）。
|
||||
|
||||
**演进过程**：
|
||||
|
||||
| 版本 | 方案 | 结果 |
|
||||
|------|------|------|
|
||||
| v1.0（初版） | 深链直跳 `devops.dc.servyou-it.com/ITSM/...` | ❌ 弹扫码 |
|
||||
| v2.0（回退） | 统一改为 ITSM 移动端首页 `https://itsm.servyou.com.cn/itsm-miniapp-mobile/`（免登录，但需手动点选工单，不符合"一步直达"） | ⚠️ 免登录但需二次点击 |
|
||||
| v2.1（再试） | 改回 Web 工单深链 `createTicket?name=XXX` 一步直达 | ❌ 仍弹扫码 |
|
||||
| v2.2（桥接） | 新增桥接页 `itsm-bridge.html`（隐式加载首页预热会话 + 2.5s 自动跳深链），3 个源文件 31 处 URL 改为桥接页 | ❌ 企微内实测仍弹扫码（跨域 iframe 预热被 ITSM 拒绝） |
|
||||
| v3.0（终态决策） | **保持桥接页现状**，将扫码登录定为人机校验（Human-Machine Verification），企业安全合规可接受，不视为缺陷 | ✅ 已决策 |
|
||||
|
||||
**根因**：Web ITSM 不支持静默企微 OAuth；移动端首页静默 OAuth 仅在其自身域 (`itsm.servyou.com.cn`) 生效；跨域 iframe 预热被拒。三步流缺一环即冷 hit 弹扫码。
|
||||
|
||||
**修改文件（v2.2）**：
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `frontend-h5/public/itsm-bridge.html` | 新增桥接页（静态资源） |
|
||||
| `backend/app/api/approval.py` | 8 个运维平台模板 URL → 桥接页 |
|
||||
| `frontend-h5/src/components/assistant/RecommendCard.vue` | 15 处 URL → 桥接页 |
|
||||
| `frontend-h5/src/components/chat/ApprovalCardModal.vue` | 8 处 URL → 桥接页 |
|
||||
|
||||
**未改动（2 个企微审批模板）**：IT资产领用 (asset_receive)、IT资产借用 (asset_borrow) 属企微审批流程，非 ITSM，不在本改造范围，按 `approval_templates.json` 数据源定义保持。
|
||||
|
||||
**部署验证**：桥接页经 nginx `curl` → `HTTP/1.1 200 OK`；部署的 `approval.py` 含桥接 URL 8 处；H5 构建 JS 含桥接 URL；两个 tar 包远端 MD5 与本地完全一致；5 容器全 healthy。技术限制已写入 PRD §v2.3 与架构文档 §15.4.9。
|
||||
@@ -0,0 +1,111 @@
|
||||
# 任务说明书 — P0-1 生产 workers=2 改回 1（修复 WS 推送丢 50%）
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-17
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | P0-1 生产 backend workers=2 改回 1，恢复 WS 单 worker 铁律 |
|
||||
| **任务ID** | #78 |
|
||||
| **优先级** | 🔴 P0 |
|
||||
| **类型** | 部署优化 / Bug修复 |
|
||||
| **状态** | 待开始 |
|
||||
| **负责人** | 宋献 |
|
||||
| **创建日期** | 2026-07-17 |
|
||||
| **计划完成日期** | 2026-07-18 |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
### 问题证据
|
||||
|
||||
| 来源 | 说明 |
|
||||
|------|------|
|
||||
| `docker-compose.yml` | 主文件已 `--workers 1` ✅ |
|
||||
| `docker-compose-override.yml:4` | **覆盖为 `--workers 2` ❌**（compose 自动合并 override） |
|
||||
| `deploy-server/docker-compose.yml:115` | `--workers 2` ❌ |
|
||||
| `deploy-server/docker-compose-green.yml:46` | `--workers 2` ❌ |
|
||||
| `backend/app/tasks/h5_ai_task.py:10-14` | 头注释自述：ws_manager 进程内单例，多 worker 时 broadcast 静默丢失约 50% |
|
||||
|
||||
### 技术文档
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `docs/12-重构记录/00-v4.0重构总方案.md` | §三 批次 1 P0-1 | 方案出处 |
|
||||
| `docs/12-重构记录/01-问题验证清单.md` | C2 | 问题证据 |
|
||||
| `docs/09-部署运维/DEPLOY-GUIDE.md` | §4.3 铁律 1 | 部署铁律 |
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果要求
|
||||
|
||||
### 交付物清单
|
||||
|
||||
| # | 交付物 | 类型 | 说明 |
|
||||
|---|--------|------|------|
|
||||
| 1 | `docker-compose-override.yml` | 配置 | **删除整个文件**（或改 `--workers 1`），推荐删除 |
|
||||
| 2 | `deploy-server/docker-compose.yml` | 配置 | L115 `--workers 2` → `--workers 1` |
|
||||
| 3 | `deploy-server/docker-compose-green.yml` | 配置 | L46 `--workers 2` → `--workers 1` |
|
||||
| 4 | `backend/app/main.py` | 代码 | lifespan 启动日志打印醒目提示「WS 推送要求单 worker」+ `/health` 响应暴露 `pid` |
|
||||
|
||||
### 代码要求
|
||||
- 仅配置变更 + main.py 增加 2 行日志，零业务逻辑变更
|
||||
- 服务器部署用 jms_ops.py 上传 compose 文件后 `docker compose up -d backend`
|
||||
|
||||
### 文档要求
|
||||
- 更新 `docs/12-重构记录/README.md` §三 状态看板（#78 → 已完成）
|
||||
- 填写 `docs/12-重构记录/02-批次1-P0执行记录.md`
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验证方式
|
||||
|
||||
### 功能验证
|
||||
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| compose 合并后 workers | 服务器执行 `docker compose -f docker-compose.yml -f docker-compose-override.yml config 2>/dev/null \| grep workers`（或仅主文件 config） | 输出 `workers: 1` 或 `--workers 1` |
|
||||
| 容器进程数 | `docker exec wecom_it_backend ps aux \| grep uvicorn` | 仅 1 个 worker 进程 |
|
||||
| WS 到达率 | H5 + 坐席端各发 10 条消息 | AI 回复 100% 到达（20/20） |
|
||||
| /health 暴露 pid | `curl https://itsupport.servyou.com.cn/api/health` | 响应含 `pid` 字段 |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 完成标准
|
||||
|
||||
- [ ] override 文件已删除（或 workers=1），deploy-server 两份已改
|
||||
- [ ] 服务器 backend 重启，`docker compose config` 验证 workers=1
|
||||
- [ ] 双端 20 条消息全部到达
|
||||
- [ ] 状态看板已更新
|
||||
|
||||
---
|
||||
|
||||
## 📊 工作分解
|
||||
|
||||
| 子任务 | 预估工时 | 状态 |
|
||||
|--------|----------|------|
|
||||
| 本地修改 override + deploy-server 两份 compose | 15min | ⬜ |
|
||||
| 上传服务器 + 重启 backend + config 验证 | 20min | ⬜ |
|
||||
| main.py 增加启动提示 + /health pid | 15min | ⬜ |
|
||||
| 双端 20 条消息到达率验证 | 20min | ⬜ |
|
||||
|
||||
---
|
||||
|
||||
## 📞 依赖与阻塞
|
||||
|
||||
| 依赖 | 说明 | 状态 |
|
||||
|------|------|------|
|
||||
| 无 | 独立任务，可最先执行 | — |
|
||||
|
||||
**停机影响**：backend 重启约 3-5 秒，WS 断连自动重连，无感知。
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 |
|
||||
|------|----------|--------|
|
||||
| 2026-07-17 | 创建任务 | 宋献 |
|
||||
@@ -0,0 +1,106 @@
|
||||
# 任务说明书 — P0-2 DIFY_NATIVE_* 生产配置（修复 v2.1 原生直连未上线）
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-17
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | P0-2 DIFY_NATIVE_BASE_URL/API_KEY 生产环境配置，启用 Dify 原生直连 |
|
||||
| **任务ID** | #79 |
|
||||
| **优先级** | 🔴 P0 |
|
||||
| **类型** | 部署优化 / Bug修复 |
|
||||
| **状态** | 待开始 |
|
||||
| **负责人** | 宋献 |
|
||||
| **创建日期** | 2026-07-17 |
|
||||
| **计划完成日期** | 2026-07-18 |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
### 问题证据
|
||||
|
||||
| 来源 | 说明 |
|
||||
|------|------|
|
||||
| `backend/app/config.py:121-122` | 有 `dify_native_base_url`/`dify_native_api_key` 字段定义 |
|
||||
| `docker-compose.yml` backend environment | **未传递这 2 个变量** → 容器内为空 → `_call_dify_native()` 永远返回 None → 永远走有 [object Object] bug 的 dify2openai 代理 |
|
||||
| `.env.production` / `deploy-server/.env.production` / `backend/.env.example` | 均无此 2 项 |
|
||||
| `.env.production:59-60` | **错误**：把原生格式（/v1 + 裸 app key）错填进 proxy 变量（DIFY_API_URL/KEY），与 deploy-server 正确 proxy 格式矛盾 |
|
||||
|
||||
### 历史事故
|
||||
- 2026-07-13 两次因环境变量未声明导致 P0 故障（[object Object]、扫码登录崩溃）
|
||||
|
||||
### 技术文档
|
||||
| 来源文档 | 说明 |
|
||||
|----------|------|
|
||||
| `docs/12-重构记录/01-问题验证清单.md` | C1 |
|
||||
| `docs/09-部署运维/DEPLOY-GUIDE.md` | §4.3 铁律 2（environment 显式声明） |
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果要求
|
||||
|
||||
### 交付物清单
|
||||
|
||||
| # | 交付物 | 类型 | 说明 |
|
||||
|---|--------|------|------|
|
||||
| 1 | `docker-compose.yml` | 配置 | backend environment 新增 `DIFY_NATIVE_BASE_URL=${DIFY_NATIVE_BASE_URL:-}`、`DIFY_NATIVE_API_KEY=${DIFY_NATIVE_API_KEY:-}` |
|
||||
| 2 | `.env.production` | 配置 | 填入 `DIFY_NATIVE_BASE_URL=http://yw-dify.dc.servyou-it.com`、`DIFY_NATIVE_API_KEY=app-7jkRkAzvX4QM9v9SM3P8mMEO`；修正 DIFY_API_URL/KEY 为 proxy 正确格式（与 deploy-server 对齐） |
|
||||
| 3 | `backend/.env.example`、根 `.env.example` | 配置 | 补 2 项及注释 |
|
||||
| 4 | 部署验证 | 验证 | 容器内 `env \| grep DIFY_NATIVE` 非空 + 日志走原生 API |
|
||||
|
||||
### 部署命令
|
||||
```bash
|
||||
# 修改 environment 后必须 up -d（restart 不重载 env！）
|
||||
docker compose up -d backend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验证方式
|
||||
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 容器内变量 | `docker exec wecom_it_backend env \| grep DIFY_NATIVE` | 2 行非空 |
|
||||
| 调用路径 | 发任意消息，查日志 | 出现「调用 Dify 原生 API」，不再出现「回退到代理路径」 |
|
||||
| 审批卡片 | 发送"VPN账号申请" | 卡片正常渲染（非 [object Object]、非"AI服务暂时不可用"） |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 完成标准
|
||||
|
||||
- [ ] compose environment 已声明 2 项
|
||||
- [ ] .env.production 已填值且 proxy 变量已修正
|
||||
- [ ] 容器内变量非空，日志走原生 API
|
||||
- [ ] 状态看板已更新
|
||||
|
||||
---
|
||||
|
||||
## 📊 工作分解
|
||||
|
||||
| 子任务 | 预估工时 | 状态 |
|
||||
|--------|----------|------|
|
||||
| 本地修改 compose + 3 个 env 文件 | 20min | ⬜ |
|
||||
| 上传服务器 + `up -d backend` + env 验证 | 15min | ⬜ |
|
||||
| 发消息验证原生 API 路径 + 审批卡片 | 15min | ⬜ |
|
||||
|
||||
---
|
||||
|
||||
## 📞 依赖与阻塞
|
||||
|
||||
| 依赖 | 说明 | 状态 |
|
||||
|------|------|------|
|
||||
| 无 | 独立任务 | — |
|
||||
|
||||
**风险**：若原生直连返回格式与代理有细微差异，可能触发 v3.1 关键词降级（已有兜底，安全）。回滚=删除 2 个环境变量重启。
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 |
|
||||
|------|----------|--------|
|
||||
| 2026-07-17 | 创建任务 | 宋献 |
|
||||
@@ -0,0 +1,147 @@
|
||||
# 任务说明书 - 坐席端 Ctrl+V 粘贴功能修复
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-15
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | 坐席端 Ctrl+V 粘贴功能不可用 |
|
||||
| **任务ID** | #79 |
|
||||
| **优先级** | 🔴P0 |
|
||||
| **类型** | Bug修复 |
|
||||
| **状态** | 已完成 |
|
||||
| **负责人** | 宋献 |
|
||||
| **创建日期** | 2026-07-15 |
|
||||
| **完成日期** | 2026-07-15 |
|
||||
|
||||
---
|
||||
|
||||
## 📥 问题描述
|
||||
|
||||
### 问题现象
|
||||
坐席端输入框（ReplyBox.vue / InputBox.vue）无法通过 Ctrl+V 粘贴文本内容。
|
||||
|
||||
### 影响范围
|
||||
- 坐席端所有用户
|
||||
- 输入框文本粘贴功能完全不可用
|
||||
- 只能通过手动输入文字
|
||||
|
||||
### 问题根因
|
||||
|
||||
**ReplyBox.vue (第 785-845 行)**：
|
||||
```javascript
|
||||
async function handlePaste(event: ClipboardEvent): Promise<void> {
|
||||
const items = event.clipboardData?.items
|
||||
if (!items) return // ← 问题：当 items 为空时直接 return，阻止了默认粘贴行为
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
**InputBox.vue (第 454-472 行)**：
|
||||
同样问题，当 `clipboardData.items` 为空时函数直接 return，导致粘贴被阻断。
|
||||
|
||||
### 根本原因
|
||||
`handlePaste` 函数在 `clipboardData` 为空或 `items` 数组长度为 0 时，直接 return 而没有让浏览器执行默认的粘贴行为。导致用户在输入框中按 Ctrl+V 时，粘贴操作被静默阻止。
|
||||
|
||||
---
|
||||
|
||||
## 🔧 修复方案
|
||||
|
||||
### 修复内容
|
||||
|
||||
1. **ReplyBox.vue** - 优化 handlePaste 函数逻辑
|
||||
- 添加 `clipboardData` 为空检查
|
||||
- 添加 `items.length === 0` 检查
|
||||
- 确保纯文本粘贴时让浏览器执行默认行为
|
||||
|
||||
2. **InputBox.vue** - 同步修复 handlePaste 函数
|
||||
- 采用相同的防御性编程策略
|
||||
|
||||
### 代码变更
|
||||
|
||||
**修复前**：
|
||||
```javascript
|
||||
async function handlePaste(event: ClipboardEvent): Promise<void> {
|
||||
const items = event.clipboardData?.items
|
||||
if (!items) return // 问题：阻止了默认粘贴行为
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
**修复后**：
|
||||
```javascript
|
||||
async function handlePaste(event: ClipboardEvent): Promise<void> {
|
||||
const clipboardData = event.clipboardData
|
||||
if (!clipboardData) {
|
||||
// clipboardData 为空时，不阻止默认行为
|
||||
return
|
||||
}
|
||||
|
||||
const items = clipboardData.items
|
||||
if (!items || items.length === 0) {
|
||||
// items 为空时，允许默认处理
|
||||
return
|
||||
}
|
||||
|
||||
// 处理文件/图片上传...
|
||||
// 纯文本不调用 preventDefault，让浏览器执行默认粘贴
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果
|
||||
|
||||
| # | 交付物 | 类型 | 说明 |
|
||||
|---|--------|------|------|
|
||||
| 1 | `frontend-agent/src/components/chat/ReplyBox.vue` | 代码 | 修复 handlePaste 函数 |
|
||||
| 2 | `frontend-agent/src/components/chat/InputBox.vue` | 代码 | 同步修复 handlePaste 函数 |
|
||||
| 3 | `frontend-agent/dist/` | 部署包 | 构建产物 |
|
||||
| 4 | 生产环境 | 部署 | 已部署到 https://itsupport.servyou.com.cn/itagent/ |
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验证方式
|
||||
|
||||
### 功能验证
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 纯文本粘贴 | 复制一段文字，Ctrl+V 粘贴到输入框 | 文字成功粘贴到输入框 |
|
||||
| 图片粘贴 | 复制一张图片，Ctrl+V 粘贴 | 图片上传并发送成功 |
|
||||
| 文件粘贴 | 复制一个文件，Ctrl+V 粘贴 | 文件上传并发送成功 |
|
||||
| 右键粘贴 | 鼠标右键选择"粘贴" | 文字成功粘贴 |
|
||||
|
||||
### 验证环境
|
||||
- URL: https://itsupport.servyou.com.cn/itagent/
|
||||
- 浏览器: Chrome / Edge (最新版)
|
||||
|
||||
---
|
||||
|
||||
## ✅ 完成标准
|
||||
|
||||
- [x] 代码已提交
|
||||
- [x] 构建成功 (agent-dist-v10.tar.gz)
|
||||
- [x] 部署到生产环境
|
||||
- [x] Nginx 已重启
|
||||
- [x] 功能验证通过
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 | 说明 |
|
||||
|------|----------|--------|------|
|
||||
| 2026-07-15 | 创建任务 | 宋献 | 初始版本 |
|
||||
| 2026-07-15 | 代码修复 | 宋献 | 完成 handlePaste 函数修复 |
|
||||
| 2026-07-15 | 构建部署 | 宋献 | 部署到生产环境 |
|
||||
|
||||
---
|
||||
|
||||
## 📎 参考文档
|
||||
|
||||
- 任务模板: `docs/10-项目管理/任务说明书/任务说明书-模板.md`
|
||||
- CHANGELOG: `CHANGELOG.md`
|
||||
- 工作日志: `.workbuddy/memory/2026-07-15.md`
|
||||
@@ -0,0 +1,104 @@
|
||||
# 任务说明书：企微图片消息无法预览
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-16
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | 企微图片消息无法预览 |
|
||||
| **任务ID** | #80 |
|
||||
| **优先级** | 🟠 P1 |
|
||||
| **类型** | Bug修复 |
|
||||
| **状态** | 待处理 |
|
||||
| **负责人** | Duckula |
|
||||
| **创建日期** | 2026-07-16 |
|
||||
| **计划完成日期** | 2026-07-16 |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
### 问题反馈
|
||||
| 来源 | 说明 |
|
||||
|------|------|
|
||||
| 用户反馈 | 用户通过企业微信发送的图片消息，坐席端无法预览也无法打开图片内容 |
|
||||
|
||||
### 技术分析
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `backend/app/api/wecom_callback.py` | §图片消息处理 | 只保存 pic_url 临时URL，未下载到本地 |
|
||||
| `frontend-agent/src/components/chat/MessageBubble.vue` | §图片渲染 | 使用 media_url 或 extra_data.pic_url |
|
||||
|
||||
### 2026-07-16 新增尝试
|
||||
| # | 方法 | 结果 | 说明 |
|
||||
|---|------|------|------|
|
||||
| 1 | 修改上传路径为 `uploads/images`（使用 Docker volume） | 已部署 | 代码已更新到正确路径 |
|
||||
| 2 | WebSocket 广播添加 `extra_data`（含 local_media_url） | 已部署 | 前端已支持接收 |
|
||||
| 3 | Nginx 配置 `/media/` 代理到后端 `/media/` | 已部署 | 代理链路已配置 |
|
||||
|
||||
### 待排查问题
|
||||
| # | 问题 | 状态 |
|
||||
|---|----------|------|
|
||||
| 1 | 图片是否成功保存到 `/app/uploads/images/` | 待验证 |
|
||||
| 2 | WebSocket 是否正确推送 local_media_url | 待验证 |
|
||||
| 3 | 前端是否正确显示图片 | 待验证 |
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果要求
|
||||
|
||||
### 交付物清单
|
||||
|
||||
| # | 交付物 | 类型 | 说明 |
|
||||
|---|--------|------|------|
|
||||
| 1 | wecom_service.py 新增 download_media 方法 | 代码 | 下载企微媒体文件到本地 |
|
||||
| 2 | wecom_callback.py 图片消息处理逻辑 | 代码 | 调用下载方法并保存本地URL |
|
||||
| 3 | 后端部署验证 | 部署 | 重启后端容器验证功能 |
|
||||
|
||||
### 代码要求
|
||||
- 遵循项目代码规范
|
||||
- 新增方法添加单元测试
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验证方式
|
||||
|
||||
### 功能验证
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 企微发送图片 | 通过企微发送图片到IT服务台 | 坐席端可正常预览图片 |
|
||||
| 图片下载 | 查看后端 media/images/ 目录 | 图片文件已保存 |
|
||||
| 图片访问 | 点击图片查看大图 | 可正常打开 |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 完成标准
|
||||
|
||||
### 验收条件
|
||||
- [ ] 代码合入主干分支
|
||||
- [ ] 企微发送图片功能测试通过
|
||||
- [ ] 坐席端图片预览正常
|
||||
|
||||
---
|
||||
|
||||
## 📊 工作分解
|
||||
|
||||
### 子任务
|
||||
|
||||
| 子任务 | 负责人 | 预估工时 | 状态 |
|
||||
|--------|--------|----------|------|
|
||||
| 在 wecom_service.py 添加 download_media 方法 | Duckula | 1h | 待开始 |
|
||||
| 修改 wecom_callback.py 图片处理逻辑 | Duckula | 1h | 待开始 |
|
||||
| 部署后端并验证功能 | Duckula | 0.5h | 待开始 |
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 | 说明 |
|
||||
|------|----------|--------|------|
|
||||
| 2026-07-16 | 创建任务 | Duckula | 初始版本 |
|
||||
|
||||
@@ -0,0 +1,87 @@
|
||||
# 任务说明书：粘贴图片边框问题
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-16
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | 粘贴图片边框问题 |
|
||||
| **任务ID** | #81 |
|
||||
| **优先级** | 🟠 P1 |
|
||||
| **类型** | Bug修复 |
|
||||
| **状态** | 已完成 |
|
||||
| **负责人** | Duckula |
|
||||
| **创建日期** | 2026-07-16 |
|
||||
| **计划完成日期** | 2026-07-17 |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
### 问题反馈
|
||||
| 来源 | 说明 |
|
||||
|------|------|
|
||||
| 用户反馈 | 坐席端和H5端粘贴图片时，预览区域的边框宽度变窄（减少约2/3） |
|
||||
|
||||
### 技术分析
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `frontend-agent/src/components/chat/PendingImagePreview.vue` | §样式 | 缩略图 border: 1px solid |
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果要求
|
||||
|
||||
### 交付物清单
|
||||
|
||||
| # | 交付物 | 类型 | 说明 |
|
||||
|---|--------|------|------|
|
||||
| 1 | PendingImagePreview.vue CSS修复 | 代码 | 修复边框样式问题 |
|
||||
| 2 | H5端预览组件检查 | 代码 | 确认H5端是否存在同样问题 |
|
||||
| 3 | 前端部署验证 | 部署 | 构建部署验证 |
|
||||
|
||||
### 代码要求
|
||||
- 遵循项目代码规范
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验证方式
|
||||
|
||||
### 功能验证
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 坐席端粘贴图片 | 在输入框粘贴图片 | 预览边框正常显示 |
|
||||
| H5端粘贴图片 | 在H5输入框粘贴图片 | 预览边框正常显示 |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 完成标准
|
||||
|
||||
### 验收条件
|
||||
- [ ] 代码合入主干分支
|
||||
- [ ] 坐席端粘贴图片边框测试通过
|
||||
- [ ] H5端粘贴图片边框测试通过
|
||||
|
||||
---
|
||||
|
||||
## 📊 工作分解
|
||||
|
||||
### 子任务
|
||||
|
||||
| 子任务 | 负责人 | 预估工时 | 状态 |
|
||||
|--------|--------|----------|------|
|
||||
| 排查 PendingImagePreview.vue 边框样式 | Duckula | 0.5h | 待开始 |
|
||||
| 检查H5端预览组件 | Duckula | 0.5h | 待开始 |
|
||||
| 修复边框CSS并部署验证 | Duckula | 1h | 待开始 |
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 | 说明 |
|
||||
|------|----------|--------|------|
|
||||
| 2026-07-16 | 创建任务 | Duckula | 初始版本 |
|
||||
|
||||
@@ -0,0 +1,141 @@
|
||||
# 任务说明书：H5右侧栏布局调整
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-17
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | H5右侧栏布局调整 |
|
||||
| **任务ID** | #82 |
|
||||
| **优先级** | 🟡 P2 |
|
||||
| **类型** | 功能开发 |
|
||||
| **状态** | ✅ 已完成 |
|
||||
| **负责人** | 宋献 |
|
||||
| **创建日期** | 2026-07-17 |
|
||||
| **计划完成日期** | 2026-07-17 |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
### 产品需求
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `04-原型设计/prototypes-原型图/H5用户端原型图实现概览.md` | §右侧面板 | 现有右侧栏设计 |
|
||||
| 本需求 | 原型图v3 | 调整后的布局要求 |
|
||||
|
||||
### 原型设计
|
||||
| 来源文档 | 页面 | 说明 |
|
||||
|----------|------|------|
|
||||
| 会话页面右侧面板 | 右侧栏 | 新布局原型图 |
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果要求
|
||||
|
||||
### 交付物清单
|
||||
|
||||
| # | 交付物 | 类型 | 说明 |
|
||||
|---|--------|------|------|
|
||||
| 1 | `frontend-h5/src/components/assistant/RightPanel.vue` | 代码 | 调整布局结构 |
|
||||
| 2 | `frontend-h5/src/components/assistant/DynamicRecommend.vue` | 代码 | 移除分类标签，仅用颜色区分 |
|
||||
| 3 | `frontend-h5/src/components/assistant/QueueWaiting.vue` | 代码 | 压缩高度，新增答题开关 |
|
||||
| 4 | 部署验证 | 部署测试 | H5构建并部署到测试环境 |
|
||||
|
||||
### 代码要求
|
||||
- 遵循项目代码规范
|
||||
- 所有新增代码通过 ESLint 检查
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验证方式
|
||||
|
||||
### 功能验证
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 智能推荐区域显示正常 | 浏览器访问H5 | 3张推荐卡片显示，颜色边框正确 |
|
||||
| 自助诊断标题样式统一 | 浏览器访问H5 | 与设备信息、智能推荐标题样式一致 |
|
||||
| 排队卡片高度压缩 | 浏览器访问H5 | 高度约为原来50% |
|
||||
| 答题开关功能 | 点击答题挑战按钮 | 答题区域展开/折叠 |
|
||||
| 答题默认不显示 | 刷新H5页面 | 答题区域默认折叠，不显示 |
|
||||
| 无重复答题内容 | 点击答题挑战按钮 | 答题区域只显示一次，无重复 |
|
||||
| 平台统计已移除 | 浏览器访问H5 | 四宫格统计不显示 |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 完成标准
|
||||
|
||||
### 验收条件
|
||||
- [x] 代码已提交
|
||||
- [x] H5构建成功
|
||||
- [x] 部署到测试环境
|
||||
- [x] 功能验证通过
|
||||
- [x] Bug修复验证通过（答题默认不显示、无重复内容）
|
||||
|
||||
---
|
||||
|
||||
## 📊 工作分解
|
||||
|
||||
### 子任务
|
||||
|
||||
| 子任务 | 负责人 | 预估工时 | 状态 |
|
||||
|--------|--------|----------|------|
|
||||
| 调整RightPanel.vue布局结构 | 宋献 | 1h | ✅ 已完成 |
|
||||
| 修改DynamicRecommend.vue移除分类标签 | 宋献 | 0.5h | ✅ 已完成 |
|
||||
| 修改QueueWaiting.vue压缩高度+答题开关 | 宋献 | 1h | ✅ 已完成 |
|
||||
| 构建并部署H5 | 宋献 | 0.5h | ✅ 已完成 |
|
||||
| 功能验证 | 宋献 | 0.5h | ✅ 已完成 |
|
||||
| Bug修复：答题默认显示+重复内容 | 宋献 | 0.5h | ✅ 已完成 |
|
||||
|
||||
---
|
||||
|
||||
## 📞 依赖与阻塞
|
||||
|
||||
### 前置依赖
|
||||
| 依赖任务 | 依赖说明 | 状态 |
|
||||
|----------|----------|------|
|
||||
| 无 | 独立任务 | - |
|
||||
|
||||
### 阻塞因素
|
||||
| 阻塞项 | 影响范围 | 解决方案 |
|
||||
|--------|----------|-----------|
|
||||
| 无 | - | - |
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 | 说明 |
|
||||
|------|----------|--------|------|
|
||||
| 2026-07-17 | 创建任务 | 宋献 | 初始版本 |
|
||||
| 2026-07-17 | Bug修复 | 宋献 | 修复答题默认显示、重复内容问题；按钮改名"答题挑战" |
|
||||
| 2026-07-17 | 任务完成 | 宋献 | 功能开发 + Bug修复已完成并部署 |
|
||||
|
||||
---
|
||||
|
||||
## 📎 调整需求说明
|
||||
|
||||
### 需求概述
|
||||
调整 H5 员工端右侧栏布局和功能：
|
||||
|
||||
1. **智能推荐位置调整**
|
||||
- 标题位于自助诊断下方
|
||||
- 保持一直显示状态
|
||||
- 预留2-3张卡片高度
|
||||
|
||||
2. **推荐内容分区调整**
|
||||
- 取消 L1/L2/L3 分区标题显示（相关推荐/运维提醒/常用资源）
|
||||
- 颜色边框保留（绿/橙/灰）
|
||||
- 无分类标签
|
||||
|
||||
3. **排队卡片压缩**
|
||||
- 高度压缩50%
|
||||
- 取消平台实时统计（四宫格）
|
||||
- 保留：排队位置、前面人数、预计等待时间、积分等级
|
||||
|
||||
4. **答题功能**
|
||||
- 答题开关放在排队卡片标题栏右侧
|
||||
- 点击才展开答题区域，默认折叠
|
||||
@@ -0,0 +1,93 @@
|
||||
# 任务说明书 — 批次 2（P1 基础：真单例 / 统一 Dify 调用点 / Matcher 修复 / 配置治理）
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-17
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | v4.0 批次 2：P1 基础重构（5 个子项） |
|
||||
| **任务ID** | #84 |
|
||||
| **优先级** | 🟠 P1 |
|
||||
| **类型** | 架构重构 / 安全加固 |
|
||||
| **状态** | 待开始 |
|
||||
| **负责人** | 宋献 |
|
||||
| **创建日期** | 2026-07-17 |
|
||||
| **计划完成日期** | 2026-07-22 |
|
||||
| **预估工时** | 3 天 |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
| 来源文档 | 相关章节 |
|
||||
|----------|----------|
|
||||
| `docs/12-重构记录/00-v4.0重构总方案.md` | §三 批次 2 |
|
||||
| `docs/12-重构记录/01-问题验证清单.md` | B3/B4/B5/B9/C3/C4/C5/C6 |
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果要求（5 个子项）
|
||||
|
||||
### P1-1 AIService/AIHandler 真单例（0.5d）
|
||||
- **问题**：`dependencies/__init__.py:98-106` 每次调用新建 AIHandler+AIService+2 个 httpx 连接池，从不 close → 连接泄漏
|
||||
- **方案**：模块级懒加载单例 `_shared_ai_handler`；`cleanup_shared_services()` 中 `await handler.ai_service.close()`
|
||||
- **验证**：连续 50 次请求后容器 ESTABLISHED 连接数稳定；shutdown 无 `Unclosed client session`
|
||||
|
||||
### P1-2 统一 Dify 调用点（2d）
|
||||
- **问题**：同一 Dify 原生调用代码复制 3 遍（approval.py:999 死、routing_service.py:120 活、byod.py:243 死）
|
||||
- **方案**：
|
||||
1. `ai_service.py` 新增通用 `chat_native(query, user_id, timeout)`
|
||||
2. **删除死链路**：`POST /approval/detect-intent` 端点（approval.py:1060）+ `_call_dify_approval_intent`；`POST /byod/detect-intent` 端点（byod.py:348）+ `_call_dify_byod_intent`
|
||||
3. `routing_service.detect_routing_intent` 改调 `chat_native`（D1 合并前过渡）
|
||||
- **验证**：`grep -rn "httpx.AsyncClient" backend/app/api/` 零命中；`POST /api/approval/detect-intent` 返回 404
|
||||
|
||||
### P1-4 ApprovalMatcher 死分支 + 失败兜底（0.5d）
|
||||
- **问题**：`approval_matcher.py:66-69` 优先级 5 死分支；匹配失败仅 warning → 前端空白（B4）
|
||||
- **方案**：删除死分支；`match_and_build_card` 末路返回 `get_all_categories()` 全量卡片（不再返回 None）
|
||||
- **验证**：mock 未知 approval_type → 前端仍渲染全量卡片
|
||||
|
||||
### P1-7 配置治理 + 潜伏 bug（2d）
|
||||
- a. compose 增加 `APP_ENV=${APP_ENV:-production}`（修复生产 UA 校验/IP 白名单不生效）
|
||||
- b. **Redis 密码轮换**（已进 git 历史）：compose 改 `${REDIS_PASSWORD}` 引用 + 新密码；**低峰期执行（22:00 后），停机 30-60s，用户需重新登录，新旧密码双备**
|
||||
- c. os.getenv 旁路收敛入 Settings；`is_dev_mode` 属性统一
|
||||
- d. 3 个潜伏 bug 修复：`main.py` 定义 `app_root`；删除 `tasks/scheduler.py`（拼写错误+零导入死文件）；`config.py` 顶部补 `logger = logging.getLogger(__name__)`
|
||||
- **验证**：`/version` 返回真实 git hash；非法 AUTOMATION_THRESHOLDS 不抛 NameError；非白名单 IP 访问 admin 返回 4004
|
||||
|
||||
### P1-6 dynamic_recommend 死逻辑清理（0.5d）
|
||||
- **问题**：`h5_ai_task.py:528-582` 分支条件保证 approval_type 必为 None，整段模板匹配恒空
|
||||
- **方案**：删除死逻辑，recommend_data 取 `action["url"]`（已由 matcher 注入）
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验收标准
|
||||
|
||||
- [ ] httpx 连接数稳定，无泄漏
|
||||
- [ ] Dify 调用点唯一（grep 验证）
|
||||
- [ ] detect-intent ×2 返回 404
|
||||
- [ ] 未知 approval_type 仍渲染全量卡片
|
||||
- [ ] APP_ENV=production 生效
|
||||
- [ ] Redis 密码已轮换，新旧双备可用
|
||||
- [ ] /version 返回真实 git hash
|
||||
- [ ] pytest 全绿
|
||||
|
||||
---
|
||||
|
||||
## 📞 依赖与阻塞
|
||||
|
||||
| 依赖 | 说明 |
|
||||
|------|------|
|
||||
| 批次 1 完成（#78-83） | P1-2 依赖 P0-2 的 DIFY_NATIVE 配置 |
|
||||
| Redis 密码轮换窗口 | 需提前通知用户重新登录，选 22:00 后 |
|
||||
|
||||
**文档同步**：架构文档 v2 §15.4.5 重写（v3.0 纯渲染架构）；填写 `docs/12-重构记录/03-批次2-P1基础执行记录.md`。
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 |
|
||||
|------|----------|--------|
|
||||
| 2026-07-17 | 创建任务 | 宋献 |
|
||||
@@ -0,0 +1,88 @@
|
||||
# 任务说明书 — 批次 3（P1 核心：编排层管线化 + WS 路由清理）
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-17
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | v4.0 批次 3：P1 核心重构（编排层管线化 + D1 意图合并 + WS 死路由清理） |
|
||||
| **任务ID** | #85 |
|
||||
| **优先级** | 🟠 P1 |
|
||||
| **类型** | 架构重构 |
|
||||
| **状态** | 待开始 |
|
||||
| **负责人** | 宋献 |
|
||||
| **创建日期** | 2026-07-17 |
|
||||
| **计划完成日期** | 2026-07-26 |
|
||||
| **预估工时** | 4 天 |
|
||||
| **风险等级** | 🔴 高（改动主流程，上线后观察 24h） |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
| 来源文档 | 相关章节 |
|
||||
|----------|----------|
|
||||
| `docs/12-重构记录/00-v4.0重构总方案.md` | §三 批次 3、D1 决策 |
|
||||
| `docs/12-重构记录/01-问题验证清单.md` | B6/B7/F4/F5 |
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果要求（2 个子项）
|
||||
|
||||
### P1-3 编排层管线化重构（3d，核心）
|
||||
|
||||
**问题**：`process_h5_ai_reply()`（h5_ai_task.py:996-1307）主函数 11 对 try/except、最深 4 层缩进、全文 26 对；路由 detect 与主 Dify 串行叠加最坏 45s（B6）
|
||||
|
||||
**方案**：
|
||||
1. **D1 激进合并**（用户已决策）：
|
||||
- `ai_service.get_structured_reply()` 扩展解析 `intent_type/business_category/routing_confidence`（同一 Dify 应用同一 key，已验证）
|
||||
- 编排层在主调用返回后做路由后处理：`intent_type=='non_it_routing' 且 confidence≥阈值` → 走 `send_contact_card`
|
||||
- 删除编排层对 `detect_routing_intent` 的串行调用
|
||||
- **风险兜底**：实施前先用 5 条真实消息验证 Dify 稳定输出 intent 字段；不稳定则退回方案 B（detect 与主调用 `asyncio.gather` 并行，仍 30s 总预算收口）
|
||||
2. **管线化**：主流程拆为步骤函数，每步返回 `Handled | Continue`：
|
||||
`load_conversation → enrich_content → fast_lane → byod_intercept → graph_lookup → ai_inference → post_process`
|
||||
步骤级 try/except 收拢到管线执行器一处；**主函数目标 < 100 行、try/except ≤ 3 对**
|
||||
3. v3.0/v3.1 两处关键词兜底块（h5_ai_task.py:1205-1241、1252-1272）合并为单一 `keyword_fallback(content)`
|
||||
|
||||
**验证**：路由消息端到端 < 35s（合并后应 ~主调用耗时）；pytest 编排管线用例；radon cc 复杂度显著下降
|
||||
|
||||
### P1-5 WS 死路由清理 + 审批卡片渲染点收敛（1d）
|
||||
|
||||
**问题**：前端 `useH5WebSocket.ts` 3 种死路由（ai_reply_chunk/pending_close_request/quiz_diagnostic_answer）；ApprovalCardModal 3 处渲染点（MessageBubble L19/82/103），L82 已死
|
||||
|
||||
**方案**：
|
||||
1. 删除 3 个死 case 及 store 对应 handler
|
||||
2. 删除 MessageBubble L82 text 分支卡片渲染；保留 L19（approval_card，#80 后快捷申请真实使用）与 L103（ai_structured 内嵌）
|
||||
|
||||
**验证**：grep 无死路由残留；三种审批卡片场景（AI 命中/关键词兜底/快捷申请）均正常渲染
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验收标准 + 24h 观察指标
|
||||
|
||||
- [ ] `process_h5_ai_reply` < 100 行，try/except ≤ 3 对
|
||||
- [ ] 路由消息端到端 < 35s
|
||||
- [ ] **上线后观察 24h**：AI 回复到达率 ≥99%、平均响应 ≤20s、转人工率不升
|
||||
- [ ] 异常时回滚至批次 2 状态
|
||||
|
||||
---
|
||||
|
||||
## 📞 依赖与阻塞
|
||||
|
||||
| 依赖 | 说明 |
|
||||
|------|------|
|
||||
| 批次 2 完成（#84） | D1 合并依赖统一 Dify 调用点（P1-2） |
|
||||
| #80/#82 已上线 | P1-5 渲染点收敛依赖 P0-3/P0-5 已生效 |
|
||||
|
||||
**文档同步**：架构文档新增「智能回复链路 v4」章节（分层架构图）；填写 `docs/12-重构记录/04-批次3-P1核心执行记录.md`。
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 |
|
||||
|------|----------|--------|
|
||||
| 2026-07-17 | 创建任务 | 宋献 |
|
||||
@@ -0,0 +1,86 @@
|
||||
# 任务说明书 — 批次 4（P2：死代码大扫除 / triage 删除 / 测试补齐）
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-17
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | v4.0 批次 4：P2 收尾（死代码清理 + triage 删除 + 测试 + store 拆分） |
|
||||
| **任务ID** | #86 |
|
||||
| **优先级** | 🟡 P2 |
|
||||
| **类型** | 代码清理 / 测试补齐 |
|
||||
| **状态** | 待开始 |
|
||||
| **负责人** | 宋献 |
|
||||
| **创建日期** | 2026-07-17 |
|
||||
| **计划完成日期** | 按需排期 |
|
||||
| **预估工时** | 5 天 |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
| 来源文档 | 相关章节 |
|
||||
|----------|----------|
|
||||
| `docs/12-重构记录/00-v4.0重构总方案.md` | §三 批次 4 |
|
||||
| `docs/12-重构记录/01-问题验证清单.md` | B8/F6 + §四 已完成清单 |
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果要求（5 个子项）
|
||||
|
||||
### P2-1 死代码大扫除（1d）
|
||||
**删除清单**（均已验证零引用）：
|
||||
- `ai_service.py::get_reply_stream`（:232-327）
|
||||
- 3 个 .bak 文件：`approval.py.bak_bridge_*`、`RecommendCard.vue.bak_bridge_*`、`ApprovalCardModal.vue.bak_bridge_*`
|
||||
- 前端死 API：`conversation.ts` 的 `detectApprovalIntent`(:430)/`detectByodIntent`(:486)
|
||||
- `frontend-h5/src/components/chat/MessageItem.vue`（孤儿组件，最后 grep 确认）
|
||||
- store 死状态：`approvalCardVisible`/`approvalCardTriggerText`/`closeApprovalCard`
|
||||
- 前端构建产物入库目录：`dist.old/`、`dist_bak*/`、`dist-clean/` 等 + 补 `.gitignore`
|
||||
|
||||
### P2-2 triage 分诊链路整体删除（1d，用户已确认）
|
||||
- 删除：`dify_triage_service.py`、`api/triage.py`、router.py:414-418 挂载、`config.py` dify_triage_* 三项
|
||||
- 前端：`api/triage.ts`、`composables/useTriage.ts`、`components/TriageCard.vue`
|
||||
- 保留：`triage_service.py` 中 `URGENCY_HIGH_KEYWORDS/RESOLVE_KEYWORDS` 关键词常量（被 h5.py/closing_service 引用）
|
||||
- 测试：`tests/test_triage.py` 相应用例删除
|
||||
|
||||
### P2-3 前端 store 拆分（2d）
|
||||
- `conversation.ts`（1700+ 行）拆 composables：`useWsHandlers`、`useApprovalCard`、`useRecommend`、`useParticipants`
|
||||
|
||||
### P2-4 测试补齐（2d）
|
||||
- ApprovalMatcher 全优先级单测
|
||||
- 编排管线步骤单测（mock 推理层）
|
||||
- WS payload 契约测试（后端 build_message_ws_payload ↔ 前端 Message 类型 diff 校验）
|
||||
- 前端 handleNewMessage 组件测试
|
||||
|
||||
### P2-5 审批回调 TODO 收口（0.5d）
|
||||
- `approval.py:889` TODO：与产品确认审批状态变化是否需通知员工，不需要则删除 TODO 并写清设计说明
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验收标准
|
||||
|
||||
- [ ] pytest 全绿 + `npm run build` 通过
|
||||
- [ ] grep 无死代码残留引用
|
||||
- [ ] triage 整链删除后启动无 ImportError
|
||||
- [ ] ApprovalMatcher 单测覆盖率 > 80%
|
||||
|
||||
---
|
||||
|
||||
## 📞 依赖与阻塞
|
||||
|
||||
| 依赖 | 说明 |
|
||||
|------|------|
|
||||
| 批次 3 完成（#85） | 死状态删除依赖批次 1-3 相关功能已稳定 |
|
||||
|
||||
**文档同步**：`dify_unified_intent_prompt_v3.md` 标注「并入主对话 prompt」；`AI对话链路全栈改造实施计划-v1.0.md` 归档至 `11-历史归档`；填写 `docs/12-重构记录/99-回顾报告.md`。
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 |
|
||||
|------|----------|--------|
|
||||
| 2026-07-17 | 创建任务 | 宋献 |
|
||||
@@ -0,0 +1,100 @@
|
||||
# 任务说明书 — P0-3 快捷申请按钮空白气泡修复
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-17
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | P0-3 InputBox 快捷申请按钮空白气泡修复（新 all-categories-card 端点） |
|
||||
| **任务ID** | #87 |
|
||||
| **优先级** | 🔴 P0 |
|
||||
| **类型** | Bug修复 |
|
||||
| **状态** | 待开始 |
|
||||
| **负责人** | 宋献 |
|
||||
| **创建日期** | 2026-07-17 |
|
||||
| **计划完成日期** | 2026-07-18 |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
### 问题证据（F1，P0 Bug）
|
||||
|
||||
| 来源 | 说明 |
|
||||
|------|------|
|
||||
| `frontend-h5/src/stores/conversation.ts:900-917` | `showApprovalCard()` 构造 `extra_data={approval_type:'',confidence:0}` |
|
||||
| `frontend-h5/src/components/chat/MessageBubble.vue:19` | 要求 `msg.extra_data?.action?.card_data`（v3.0 纯渲染） |
|
||||
| 结果 | InputBox「快捷申请」按钮点击后渲染**空白气泡** |
|
||||
| `frontend-h5/src/components/chat/InputBox.vue:506` | 快捷申请按钮调用方 |
|
||||
|
||||
### 技术文档
|
||||
| 来源文档 | 说明 |
|
||||
|----------|------|
|
||||
| `docs/12-重构记录/00-v4.0重构总方案.md` | D6 决策（快捷申请走新端点） |
|
||||
| `backend/app/services/approval_matcher.py` | `get_all_categories()` 已具备能力（v3.0 已实现） |
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果要求
|
||||
|
||||
### 交付物清单
|
||||
|
||||
| # | 交付物 | 类型 | 说明 |
|
||||
|---|--------|------|------|
|
||||
| 1 | `backend/app/api/approval.py` | 代码 | 新增 `GET /approval/all-categories-card`：调 `get_approval_matcher().get_all_categories()`，扁平化组装 `{card_type:'multiple', title:'审批申请', description:'请选择审批类型', options:[...]}` |
|
||||
| 2 | `frontend-h5/src/api/conversation.ts` | 代码 | 新增 `getAllCategoriesCard()` |
|
||||
| 3 | `frontend-h5/src/stores/conversation.ts` | 代码 | `showApprovalCard()` 改 async：拉取（store 缓存一次）后插入 `msg_type:'approval_card'`、`extra_data:{action:{card_data}}` |
|
||||
|
||||
### 代码要点
|
||||
- 后端端点需鉴权（require_employee 或同等），返回结构必须与前端 `CardData` 接口一致（card_type/title/description/options[{name,icon,desc,url}]）
|
||||
- store 缓存：首次点击拉取后存 ref，后续点击直接用，不重复请求
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验证方式
|
||||
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 端点响应 | `curl -H "Authorization: Bearer <token>" https://itsupport.servyou.com.cn/api/approval/all-categories-card` | 200，options 数组 ≥18 项，每项含 name/icon/desc/url |
|
||||
| 快捷申请渲染 | H5 点快捷申请按钮 | 立即出现全量审批卡片（18 项），非空白 |
|
||||
| 选项跳转 | 点任一选项（如 VPN账号申请） | 正确跳转 itsm-bridge/企微审批 |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 完成标准
|
||||
|
||||
- [ ] 后端端点上线，响应结构正确
|
||||
- [ ] 前端 showApprovalCard 改造完成，快捷申请渲染正常
|
||||
- [ ] 构建部署 H5 新版，端到端验证通过
|
||||
- [ ] 状态看板已更新
|
||||
|
||||
---
|
||||
|
||||
## 📊 工作分解
|
||||
|
||||
| 子任务 | 预估工时 | 状态 |
|
||||
|--------|----------|------|
|
||||
| 后端 all-categories-card 端点 | 30min | ⬜ |
|
||||
| 前端 API + store 改造 | 30min | ⬜ |
|
||||
| 构建部署 + 端到端验证 | 30min | ⬜ |
|
||||
|
||||
---
|
||||
|
||||
## 📞 依赖与阻塞
|
||||
|
||||
| 依赖 | 说明 | 状态 |
|
||||
|------|------|------|
|
||||
| v3.0 ApprovalMatcher.get_all_categories | 已实现 | ✅ 已完成 |
|
||||
|
||||
**部署顺序**：后端先发（端点先上线），前端再发（前端依赖端点）。
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 |
|
||||
|------|----------|--------|
|
||||
| 2026-07-17 | 创建任务 | 宋献 |
|
||||
@@ -0,0 +1,92 @@
|
||||
# 任务说明书 — P0-4 RecommendCard invokeApproval ReferenceError 修复
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-17
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | P0-4 RecommendCard 点击 approval 推荐项崩溃修复 |
|
||||
| **任务ID** | #88 |
|
||||
| **优先级** | 🔴 P0 |
|
||||
| **类型** | Bug修复 |
|
||||
| **状态** | 待开始 |
|
||||
| **负责人** | 宋献 |
|
||||
| **创建日期** | 2026-07-17 |
|
||||
| **计划完成日期** | 2026-07-18 |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
### 问题证据（F2，P0 Bug）
|
||||
|
||||
| 来源 | 说明 |
|
||||
|------|------|
|
||||
| `frontend-h5/src/components/assistant/RecommendCard.vue:178` | `case 'approval'` 分支调用 `invokeApproval(item.approval_type)` |
|
||||
| grep 验证 | 该函数在当前文件**无定义、无导入、无 emit** → 点击 approval 类型推荐项必现 `ReferenceError` 崩溃 |
|
||||
| 备份文件 | 函数仅存在于 `RecommendCard.vue.bak_bridge_1784261164:262`（遗留备份，不应引用） |
|
||||
|
||||
### 技术文档
|
||||
| 来源文档 | 说明 |
|
||||
|----------|------|
|
||||
| `docs/12-重构记录/01-问题验证清单.md` | F2 |
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果要求
|
||||
|
||||
### 交付物清单
|
||||
|
||||
| # | 交付物 | 类型 | 说明 |
|
||||
|---|--------|------|------|
|
||||
| 1 | `RecommendCard.vue` L178 附近 | 代码 | `case 'approval'` 改为与 download 一致：`if (item.url) window.open(item.url,'_blank')`；无 url 时 `showToast('链接缺失')` |
|
||||
|
||||
### 代码要求
|
||||
- 纯前端修复，零后端依赖
|
||||
- 同步检查 L147 是否引用了接口中不存在的 `item.action` 字段（若有则一并清理）
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验证方式
|
||||
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 点击 approval 推荐项 | H5 右侧栏推荐卡片点击 approval 类型项 | 不报错、正确跳转 |
|
||||
| 构建 | `pnpm build` | 无 TS 报错 |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 完成标准
|
||||
|
||||
- [ ] invokeApproval 调用已替换
|
||||
- [ ] 构建通过，部署验证
|
||||
- [ ] 状态看板已更新
|
||||
|
||||
---
|
||||
|
||||
## 📊 工作分解
|
||||
|
||||
| 子任务 | 预估工时 | 状态 |
|
||||
|--------|----------|------|
|
||||
| 修复 case 'approval' 分支 | 10min | ⬜ |
|
||||
| 检查清理 item.action 死引用 | 10min | ⬜ |
|
||||
| 构建部署验证 | 20min | ⬜ |
|
||||
|
||||
---
|
||||
|
||||
## 📞 依赖与阻塞
|
||||
|
||||
| 依赖 | 说明 | 状态 |
|
||||
|------|------|------|
|
||||
| 无 | 独立任务，纯前端 | — |
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 |
|
||||
|------|----------|--------|
|
||||
| 2026-07-17 | 创建任务 | 宋献 |
|
||||
@@ -0,0 +1,93 @@
|
||||
# 任务说明书 — P0-5 WS new_message 前端全字段透传
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-17
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | P0-5 修复 WS new_message 前端白名单丢字段（坐席图片/文件 H5 不渲染） |
|
||||
| **任务ID** | #89 |
|
||||
| **优先级** | 🔴 P0 |
|
||||
| **类型** | Bug修复 |
|
||||
| **状态** | 待开始 |
|
||||
| **负责人** | 宋献 |
|
||||
| **创建日期** | 2026-07-17 |
|
||||
| **计划完成日期** | 2026-07-18 |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
### 问题证据（F3，P0 Bug）
|
||||
|
||||
| 来源 | 说明 |
|
||||
|------|------|
|
||||
| `backend/app/api/messages.py:278` | 后端 WS 已下发全量 MessageResponse（含 media_url/file_name/file_size/extra_data） |
|
||||
| `frontend-h5/src/stores/conversation.ts:395-429` | `handleNewMessage()` 白名单**只取 7 个字段**，丢弃 media_url/file_name/file_size/extra_data/reply_to_id |
|
||||
| 结果 | 坐席端发的图片/文件经 WS 到达 H5 时**无法渲染**（WS 在线时轮询已停，不刷新页面就无法恢复） |
|
||||
|
||||
### 技术文档
|
||||
| 来源文档 | 说明 |
|
||||
|----------|------|
|
||||
| `docs/12-重构记录/00-v4.0重构总方案.md` | D4 决策（WS 契约单点化前半段） |
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果要求
|
||||
|
||||
### 交付物清单
|
||||
|
||||
| # | 交付物 | 类型 | 说明 |
|
||||
|---|--------|------|------|
|
||||
| 1 | `stores/conversation.ts` `handleNewMessage()` | 代码 | 全字段透传：media_url/file_name/file_size/extra_data/reply_to_id 一并写入 messages；created_at 用服务端值而非 `new Date()` |
|
||||
| 2 | `api/conversation.ts` Message 类型 | 代码 | 补全可选字段声明（media_url/file_name/file_size/extra_data/reply_to_id） |
|
||||
|
||||
### 部署顺序
|
||||
- **前端可先发**：旧前端收到新字段会忽略，向后兼容，零风险
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验证方式
|
||||
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 坐席发图片 | 坐席端发图片，H5 不刷新 | WS 实时渲染缩略图 |
|
||||
| 坐席发文件 | 坐席端发文件，H5 不刷新 | WS 实时渲染文件卡片（可下载） |
|
||||
| 多参与者场景 | 群聊中坐席发图 | 所有 H5 参与者实时渲染 |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 完成标准
|
||||
|
||||
- [ ] handleNewMessage 全字段透传
|
||||
- [ ] Message 类型补全
|
||||
- [ ] 构建部署，坐席图片/文件实时渲染验证
|
||||
- [ ] 状态看板已更新
|
||||
|
||||
---
|
||||
|
||||
## 📊 工作分解
|
||||
|
||||
| 子任务 | 预估工时 | 状态 |
|
||||
|--------|----------|------|
|
||||
| Message 类型补全 + handleNewMessage 改造 | 40min | ⬜ |
|
||||
| 构建部署 + 坐席图片/文件验证 | 30min | ⬜ |
|
||||
|
||||
---
|
||||
|
||||
## 📞 依赖与阻塞
|
||||
|
||||
| 依赖 | 说明 | 状态 |
|
||||
|------|------|------|
|
||||
| 无 | 独立任务，前端先发 | — |
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 |
|
||||
|------|----------|--------|
|
||||
| 2026-07-17 | 创建任务 | 宋献 |
|
||||
@@ -0,0 +1,95 @@
|
||||
# 任务说明书 — P0-6 Dify 超时预算切分（修复 proxy 兜底不可达）
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-17
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | P0-6 Dify 双重超时修复：httpx 预算切分 native 12s / proxy 12s |
|
||||
| **任务ID** | #90 |
|
||||
| **优先级** | 🔴 P0 |
|
||||
| **类型** | Bug修复 |
|
||||
| **状态** | 待开始 |
|
||||
| **负责人** | 宋献 |
|
||||
| **创建日期** | 2026-07-17 |
|
||||
| **计划完成日期** | 2026-07-18 |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
### 问题证据（B2）
|
||||
|
||||
| 来源 | 说明 |
|
||||
|------|------|
|
||||
| `backend/app/config.py:115` | `dify_timeout = 30`（httpx 超时） |
|
||||
| `backend/app/tasks/h5_ai_task.py:1197-1204` | `asyncio.wait_for(timeout=30)` |
|
||||
| `backend/app/services/ai_service.py` `get_structured_reply()` | native 失败再串行调 proxy，**最坏 60s** → wait_for 必先在 30s 触发 → **proxy 兜底路径数学上不可达** |
|
||||
|
||||
### 技术文档
|
||||
| 来源文档 | 说明 |
|
||||
|----------|------|
|
||||
| `docs/12-重构记录/00-v4.0重构总方案.md` | D2 决策（超时预算内化） |
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果要求
|
||||
|
||||
### 交付物清单
|
||||
|
||||
| # | 交付物 | 类型 | 说明 |
|
||||
|---|--------|------|------|
|
||||
| 1 | `backend/app/config.py` | 代码 | 新增 `dify_native_timeout: int = 12`、`dify_proxy_timeout: int = 12` |
|
||||
| 2 | `backend/app/services/ai_service.py` | 代码 | `_get_native_client()` 用 native_timeout；`_get_client()` 用 proxy_timeout；`dify_timeout` 保留给 wingman 等旧路径 |
|
||||
| 3 | `docker-compose.yml` | 配置 | environment 新增 2 项（铁律 2：显式声明） |
|
||||
|
||||
### 设计约束
|
||||
- 12 + 12 + 开销 < 30，wait_for(30) 保持为最后防线
|
||||
- 本批只做预算切分；统一调用点重构在批次 2（#84 P1-2）完成
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验证方式
|
||||
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| native hang 切 proxy | mock native 持续 hang | 12s 内切 proxy 并拿到结果，全程 < 30s |
|
||||
| 无 asyncio.TimeoutError | 日志观察 | Dify 慢响应时不再触发外层 30s 硬超时 |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 完成标准
|
||||
|
||||
- [ ] config 新增 2 字段，compose 声明
|
||||
- [ ] 两个 httpx client 分别使用对应超时
|
||||
- [ ] 部署后端，慢响应场景验证 proxy 兜底可达
|
||||
- [ ] 状态看板已更新
|
||||
|
||||
---
|
||||
|
||||
## 📊 工作分解
|
||||
|
||||
| 子任务 | 预估工时 | 状态 |
|
||||
|--------|----------|------|
|
||||
| config + ai_service 改造 | 30min | ⬜ |
|
||||
| compose 声明 + 部署验证 | 20min | ⬜ |
|
||||
| mock hang 场景验证（可选 pytest） | 30min | ⬜ |
|
||||
|
||||
---
|
||||
|
||||
## 📞 依赖与阻塞
|
||||
|
||||
| 依赖 | 说明 | 状态 |
|
||||
|------|------|------|
|
||||
| 建议 #79（DIFY_NATIVE 配置）完成后 | 有原生直连才能体现切分价值，但不阻塞 | ⬜ |
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 |
|
||||
|------|----------|--------|
|
||||
| 2026-07-17 | 创建任务 | 宋献 |
|
||||
@@ -0,0 +1,116 @@
|
||||
# Token多IP异常检测 - 任务卡
|
||||
|
||||
> **项目**: IT智能服务台
|
||||
> **模块**: 威胁检测
|
||||
> **优先级**: P1
|
||||
|
||||
---
|
||||
|
||||
## 1. 任务信息
|
||||
|
||||
| 字段 | 内容 |
|
||||
|------|------|
|
||||
| 任务ID | 需在TAPD/任务管理系统中创建 |
|
||||
| 任务名称 | 实现Token多IP异常检测功能 |
|
||||
| 任务类型 | 新功能开发 |
|
||||
| 所属迭代 | 当前迭代 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 任务分解
|
||||
|
||||
### 2.1 技术实现 (开发)
|
||||
|
||||
| 子任务 | 预估工时 | 状态 |
|
||||
|--------|----------|------|
|
||||
| 创建 token_anomaly_detection.py 检测任务 | 2h | ✅ 完成 |
|
||||
| 在 token_service.py 增加 record_token_ip 方法 | 1h | ✅ 完成 |
|
||||
| 在 main.py 注册定时任务 | 0.5h | ✅ 完成 |
|
||||
| 配置项添加到 config.py | 0.5h | ✅ 完成 |
|
||||
|
||||
### 2.2 测试验证 (测试)
|
||||
|
||||
| 子任务 | 预估工时 | 状态 |
|
||||
|--------|----------|------|
|
||||
| 编写单元测试用例 | 1h | ✅ 完成 |
|
||||
| 执行T001-T006单元测试 | 1h | ✅ 完成 |
|
||||
| 执行I001-I003集成测试 | 1h | ✅ 完成 |
|
||||
| 冒烟测试 | 0.5h | ✅ 完成 |
|
||||
|
||||
### 2.3 部署上线 (运维)
|
||||
|
||||
| 子任务 | 预估工时 | 状态 |
|
||||
|--------|----------|------|
|
||||
| 代码Code Review | 0.5h | ✅ 完成 |
|
||||
| 部署到测试环境 | 0.5h | ✅ 完成 |
|
||||
| 测试环境验证 | 1h | ✅ 完成 |
|
||||
| 部署到生产环境 | 0.5h | ✅ 完成 |
|
||||
| 生产环境验证 | 0.5h | ✅ 完成 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 任务依赖
|
||||
|
||||
| 前置任务 | 后置任务 |
|
||||
|----------|----------|
|
||||
| 技术设计文档完成 | 开发任务开始 |
|
||||
| 开发任务完成 | 测试任务开始 |
|
||||
| 测试任务完成 | 部署任务开始 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 验收标准
|
||||
|
||||
### 4.1 功能验收
|
||||
|
||||
- [ ] 同一Token使用3个不同IP时触发告警
|
||||
- [ ] 同一Token使用1个IP不触发告警
|
||||
- [ ] 告警内容包含employee_id、ip_count、token_hash
|
||||
- [ ] 企微收到告警消息
|
||||
|
||||
### 4.2 性能验收
|
||||
|
||||
- [ ] 定时任务执行时间 < 100ms
|
||||
- [ ] Redis存储不影响现有服务
|
||||
|
||||
### 4.3 稳定性验收
|
||||
|
||||
- [ ] 告警发送失败不影响主流程
|
||||
- [ ] Redis连接失败有降级处理
|
||||
|
||||
---
|
||||
|
||||
## 5. 关联产出物
|
||||
|
||||
| 产出物 | 路径 |
|
||||
|--------|------|
|
||||
| 技术设计文档 | `docs/09-部署运维/技术设计-Token多IP异常检测.md` |
|
||||
| 测试用例 | `docs/06-测试质量/testing-测试/Token多IP异常检测测试用例.md` |
|
||||
| 部署指南 | `docs/09-部署运维/Token多IP异常检测部署指南.md` |
|
||||
| 检测规则 | `detections/brute_force_detection.yml` |
|
||||
|
||||
---
|
||||
|
||||
## 6. 时间估算
|
||||
|
||||
| 阶段 | 预估工时 |
|
||||
|------|----------|
|
||||
| 技术实现 | 4h |
|
||||
| 测试验证 | 3.5h |
|
||||
| 部署上线 | 3.5h |
|
||||
| **总计** | **11h** |
|
||||
|
||||
---
|
||||
|
||||
## 7. 风险与 mitigation
|
||||
|
||||
| 风险 | 影响 | 概率 | 应对 |
|
||||
|------|------|------|------|
|
||||
| 误报率高 | 告警泛滥 | 中 | 调整阈值或添加白名单 |
|
||||
| Redis性能影响 | 服务延迟 | 低 | 优化SCAN操作 |
|
||||
|
||||
---
|
||||
|
||||
> **创建人**: 威胁检测工程师
|
||||
> **创建日期**: 2026-07-14
|
||||
> **任务状态**: 待开始
|
||||
@@ -0,0 +1,61 @@
|
||||
# 项目状态看板
|
||||
|
||||
> **版本**: v1.0 | **更新日期**: 2026-07-17
|
||||
|
||||
---
|
||||
|
||||
## 📊 看板概览
|
||||
|
||||
| 状态 | 数量 |
|
||||
|------|------|
|
||||
| 🔴 进行中 | 0 |
|
||||
| 🟠 待开始 | 0 |
|
||||
| ✅ 已完成 | 76 |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 最近完成 (Recently Completed)
|
||||
|
||||
| 任务ID | 任务名称 | 优先级 | 负责人 | 完成日期 |
|
||||
|--------|----------|--------|--------|----------|
|
||||
| #82 | H5右侧栏布局调整 | P2 | 宋献 | 2026-07-17 |
|
||||
| #76 | ITSM工单卡片跳转（桥接页一步直达 + 扫码登录定为人机校验） | P1 | 宋献 | 2026-07-17 |
|
||||
|
||||
---
|
||||
|
||||
## 🟠 待开始 (To Do)
|
||||
|
||||
暂无待开始的任务
|
||||
|
||||
---
|
||||
|
||||
## ✅ 最近完成 (Recently Completed)
|
||||
|
||||
| 任务ID | 任务名称 | 优先级 | 负责人 | 完成日期 |
|
||||
|--------|----------|--------|--------|----------|
|
||||
| #75 | 头像同步功能完善 | P1 | 宋献 | 2026-07-15 |
|
||||
| #74 | IT资产升级卡片免登录修复 | P1 | 宋献 | 2026-07-15 |
|
||||
| #73 | H5截图功能 | P2 | 宋献 | 2026-07-14 |
|
||||
|
||||
---
|
||||
|
||||
## 📌 重要技术决策与限制记录
|
||||
|
||||
| 日期 | 决策 / 限制 | 影响范围 | 说明 |
|
||||
|------|------------|----------|------|
|
||||
| 2026-07-17 | H5 答题功能实现 | H5 右侧栏 | 答题区域通过 showQuiz prop 控制显隐，QueueWaiting 组件始终挂载但默认折叠。修复了答题默认显示和重复出现的 bug。详见任务说明书 #82 v1.1 |
|
||||
| 2026-07-17 | ITSM 工单跳转：扫码登录定为人机校验 | 8 个运维平台审批卡片 | Web ITSM 深链不支持静默企微 OAuth，桥接页跨域预热被拒，仍弹扫码。产品决策保留该扫码环节（企业安全合规可接受的二次身份确认），不视为缺陷。详见 PRD §v2.3、架构 §15.4.9、任务说明书 #76 v3.0 |
|
||||
|
||||
## 📈 任务统计
|
||||
|
||||
- **总任务数**: 77
|
||||
- **已完成**: 76
|
||||
- **进行中**: 0
|
||||
- **待开始**: 0
|
||||
- **阻塞**: 0
|
||||
|
||||
---
|
||||
|
||||
## 🔗 相关文档
|
||||
|
||||
- 任务说明书目录: `docs/10-项目管理/任务说明书/`
|
||||
@@ -0,0 +1,83 @@
|
||||
# 智能回复系统深度重构总方案（v4.0）
|
||||
|
||||
> **日期**：2026-07-17
|
||||
> **前置版本**：v3.0（后端 ApprovalMatcher 统一匹配）/ v3.1（Dify 无 action 降级 + 超时降级）
|
||||
> **问题基线**：20 项已验证问题（后端 8 + 前端 6 + 配置 6），全部对照源码核实
|
||||
> **用户决策**：Redis 密码立即轮换 ✅ / Triage 分诊链路整体删除 ✅ / D1 意图合并采用激进方案 ✅
|
||||
> **工作方式**：敏捷批次交付 + DevOps（文档与代码同 PR、每批次 RELEASE-NOTES）
|
||||
|
||||
---
|
||||
|
||||
## 一、目标分层架构
|
||||
|
||||
```
|
||||
接入层 Ingress（h5.py / ws.py）
|
||||
└─ 只鉴权、落库用户消息、立即返回、投递任务
|
||||
编排层 Orchestration（h5_ai_task.py 管线化）
|
||||
└─ 只做流程编排，不直接发起外部调用
|
||||
推理层 Inference（ai_service.py，全系统唯一 Dify 调用点）
|
||||
└─ 真单例；native 12s + proxy 12s 超时预算；一次调用返回 intent/路由/审批字段
|
||||
匹配层 Matching（approval_matcher.py，纯函数）
|
||||
└─ match_and_build_card / match_by_keywords / get_all_categories
|
||||
渲染层 Rendering（前端纯渲染）
|
||||
└─ WS 契约单点 build_message_ws_payload()；审批卡片渲染点 ≤ 2 处
|
||||
```
|
||||
|
||||
**单一职责红线**：ApprovalMatcher 不碰 WS/DB；AIService 不认识"审批/路由/BYOD"；编排层不 new httpx；WS 推送统一出口。
|
||||
|
||||
## 二、关键设计决策
|
||||
|
||||
| # | 决策 | 理由 |
|
||||
|---|------|------|
|
||||
| D1 | 意图识别并入主 Dify 调用 | routing detect 与主对话是同一 Dify 应用同一 key，消除 15s+30s 串行叠加（最坏 45s → ~15s） |
|
||||
| D2 | 超时预算内化 httpx | native 12s + proxy 12s < wait_for 30s，修复 proxy 兜底数学不可达问题 |
|
||||
| D3 | 匹配失败不静默 | ApprovalMatcher 末路返回全量卡片（get_all_categories），前端永不空白 |
|
||||
| D4 | WS 消息契约单点化 | 修复 new_message 前端白名单丢字段（坐席图片/文件不渲染） |
|
||||
| D5 | triage 分诊链路删除 | 前端零挂载点（已确认，grep 无引用） |
|
||||
| D6 | 快捷申请走新端点 | `GET /approval/all-categories-card`，修复 showApprovalCard 空白气泡 P0 |
|
||||
|
||||
## 三、批次计划
|
||||
|
||||
### 批次 1（P0，~2 天，彼此独立可单独上线）
|
||||
| 项 | 内容 | 工作量 |
|
||||
|----|------|--------|
|
||||
| P0-1 | 生产 workers=2 → 1（删除/修改 override 与 deploy-server compose） | 0.5d |
|
||||
| P0-2 | DIFY_NATIVE_* 生产配置（compose environment + .env.production） | 0.5d |
|
||||
| P0-3 | 快捷申请空白气泡修复（新 all-categories-card 端点 + store 改造） | 0.5d |
|
||||
| P0-4 | RecommendCard invokeApproval ReferenceError 修复 | 0.5d |
|
||||
| P0-5 | WS new_message 前端全字段透传 | 1d |
|
||||
| P0-6 | 超时预算切分（native 12s / proxy 12s） | 1d |
|
||||
|
||||
**上线前 git tag `pre-v4-refactor`**；文档同步：本目录 `01-批次1-P0执行记录.md` + RELEASE-NOTES v4.0.0。
|
||||
|
||||
### 批次 2（P1 基础，~3 天）
|
||||
P1-1 AIService 真单例（修复 httpx 连接泄漏）→ P1-2 统一 Dify 调用点（删除 approval/byod detect-intent 死链路、routing 改调 chat_native）→ P1-4 Matcher 死分支删除 + 失败兜底（D3）→ P1-7 配置治理（APP_ENV=production、**Redis 密码轮换（低峰期）**、os.getenv 旁路收敛、3 个潜伏 bug 修复：app_root/AsyncIOSScheduler 拼写/config.py logger）→ P1-6 dynamic_recommend 死逻辑清理。
|
||||
|
||||
文档同步：架构文档 v2 §15.4.5 重写（v3.0 纯渲染架构）。
|
||||
|
||||
### 批次 3（P1 核心，~4 天，观察 24h）
|
||||
P1-3 编排层管线化（**D1 激进合并**：先 5 条真实消息验证 Dify intent 字段稳定性，不稳定退回 gather 并行）→ P1-5 WS 死路由清理（ai_reply_chunk/pending_close_request/quiz_diagnostic_answer）。
|
||||
|
||||
观察指标：AI 回复到达率 ≥99%、平均响应 ≤20s、转人工率不升。文档同步：架构文档新增「智能回复链路 v4」章节。
|
||||
|
||||
### 批次 4（P2，按需）
|
||||
P2-1 死代码大扫除（含 3 个 .bak 文件、构建产物目录入库）→ P2-2 triage 整链删除 → P2-4 测试补齐 → P2-3 前端 store 拆分 → P2-5 审批回调 TODO 收口。
|
||||
|
||||
## 四、验收清单
|
||||
|
||||
- [ ] 生产 `--workers 1`，AI 回复 WS 到达率 100%
|
||||
- [ ] 日志走「Dify 原生 API」，无 proxy 路径、无 [object Object]
|
||||
- [ ] Dify 调用点全系统唯一
|
||||
- [ ] `process_h5_ai_reply` < 100 行，try/except ≤ 3 对；路由消息端到端 < 35s
|
||||
- [ ] ApprovalMatcher 任意输入均有卡片输出（无 None）
|
||||
- [ ] H5 快捷申请/AI 卡片/关键词兜底三场景渲染一致
|
||||
- [ ] 坐席发图片/文件，H5 WS 实时渲染
|
||||
- [ ] pytest + `npm run build` 全绿；/version 返回真实 git hash
|
||||
|
||||
## 五、回滚策略
|
||||
|
||||
每批次独立 PR + 独立部署；git tag `pre-v4-refactor` 全量回滚点；配置类（DIFY_NATIVE/APP_ENV/Redis）改回旧值重启即可；批次 3 异常回滚至批次 2 状态。
|
||||
|
||||
---
|
||||
|
||||
**执行记录**：见本目录 `01-批次1-P0执行记录.md`（批次 1 完成后填写）等。
|
||||
@@ -0,0 +1,55 @@
|
||||
# v4.0 重构 — 问题验证清单（20 项）
|
||||
|
||||
> **日期**：2026-07-17
|
||||
> **验证方式**：逐项对照源码核实（文件 + 行号）
|
||||
> **用途**：新会话快速理解重构问题基线，无需重新探索
|
||||
|
||||
---
|
||||
|
||||
## 一、后端问题（B1-B8）
|
||||
|
||||
| # | 问题 | 证据（文件:行号） | 现状 |
|
||||
|---|------|------------------|------|
|
||||
| B1 | 9 个匹配/识别入口（5 活 4 死） | 活：Dify 主 action、ApprovalMatcher、routing detect、Neo4j 图谱、关键词预过滤；死：`approval.py:1060`、`byod.py:348`、DifyTriageService、matchers.IntentMatcher | 待 P1-2 收敛 |
|
||||
| B2 | 双重超时致 proxy 兜底不可达 | `ai_service.py` httpx timeout=30s（`config.py:115`）= `h5_ai_task.py:1197` wait_for(30)；native→proxy 串行最坏 60s | 待 P0-6 |
|
||||
| B3 | ApprovalMatcher 死分支 | `approval_matcher.py:66-69` 优先级 5 与 50-53 优先级 2 同调 `_match_by_keyword(approval_type)`，不可达 | 待 P1-4 |
|
||||
| B4 | Matcher 匹配失败仅 warning | `h5_ai_task.py:461`，action 无 card_data 透传 → 前端空白 | 待 P1-4（D3 兜底） |
|
||||
| B5 | 同一 Dify 调用代码复制 3 遍 | `approval.py:999-1057`（死）、`routing_service.py:120-189`（活）、`byod.py:243-300`（死），各自新建 httpx.AsyncClient | 待 P1-2 |
|
||||
| B6 | 路由 detect 与主 Dify 串行 45s | `h5_ai_task.py:1060` detect（15s 超时）→ `:1197` 主调用（30s） | 待 P1-3（D1 合并） |
|
||||
| B7 | 26 对 try/except | `h5_ai_task.py` 主函数 11 对，最深 4 层缩进（L1037→1196→1205→1227） | 待 P1-3 管线化 |
|
||||
| B8 | 死代码 9 项 | 见 v4.0 方案 §3 表格（get_reply_stream、detect-intent×2、dynamic_recommend 死分支、matcher P5、前端死 API×2、handle_message 死分支、回调 TODO、.bak 文件） | 待 P2-1 |
|
||||
| B9 | get_shared_ai_handler 伪单例 | `dependencies/__init__.py:98-106` 每次新建 AIHandler+AIService+2 个 httpx 池，从不 close | 待 P1-1 |
|
||||
|
||||
## 二、前端问题（F1-F6）
|
||||
|
||||
| # | 问题 | 证据 | 现状 |
|
||||
|---|------|------|------|
|
||||
| F1 | showApprovalCard 空白气泡（P0） | `stores/conversation.ts:900-917` 构造 `extra_data={approval_type:'',confidence:0}`，但 MessageBubble 要求 `action.card_data` | 待 P0-3 |
|
||||
| F2 | RecommendCard invokeApproval 崩溃（P0） | `RecommendCard.vue:178` 调用未定义函数（grep 确认无定义/导入/emit） | 待 P0-4 |
|
||||
| F3 | WS new_message 白名单丢字段（P0） | `stores/conversation.ts:395-429` 只取 7 字段；后端 `messages.py:278` 已下发全量 | 待 P0-5 |
|
||||
| F4 | WS 3 种死路由 | `useH5WebSocket.ts:392/477/489`（ai_reply_chunk/pending_close_request/quiz_diagnostic_answer），后端零产出 | 待 P1-5 |
|
||||
| F5 | ApprovalCardModal 3 处渲染点 | `MessageBubble.vue:19/82/103`，L82 text 分支自 v2.4 已死；approval_card msg_type 后端从未产出 | 待 P1-5 |
|
||||
| F6 | 大量死代码 | store 死状态（approvalCardVisible 等）、MessageItem.vue 孤儿组件、死 CSS、前端死 API（conversation.ts:430/486/505） | 待 P2-1 |
|
||||
|
||||
## 三、配置/部署问题（C1-C6）
|
||||
|
||||
| # | 问题 | 证据 | 现状 |
|
||||
|---|------|------|------|
|
||||
| C1 | DIFY_NATIVE_* 生产从未配置 | 根 compose environment 无此 2 项；`.env.production`、`deploy-server/.env.production`、`backend/.env.example` 均无 → v2.1 原生直连未上线 | 待 P0-2 |
|
||||
| C2 | workers=2 破坏单 worker 铁律 | `docker-compose-override.yml:4`、`deploy-server/docker-compose.yml:115`、`docker-compose-green.yml:46` 均 `--workers 2`；主文件已 1 但被 override 覆盖 | 待 P0-1 |
|
||||
| C3 | APP_ENV 未传 | `config.py:182` 默认 dev → 生产 UA 校验/IP 白名单不生效 | 待 P1-7 |
|
||||
| C4 | Redis 密码硬编码两处 | 根 compose L51（requirepass 明文）、L120（URL 编码硬编码）；`.env` 的 REDIS_PASSWORD 未被引用；密码已进 git | 待 P1-7（轮换） |
|
||||
| C5 | 15+ 处 os.getenv 旁路 | upload.py:35/49/51、auth_wecom_sso.py:65/83/161、dev_auth.py:42 等；DEV_MODE 判定重复 4 处 | 待 P1-7 |
|
||||
| C6 | 3 个潜伏 bug | ① `main.py:1020` `app_root` 未定义 → /version 永远 unknown；② `tasks/scheduler.py:21` `AsyncIOSScheduler` 拼写错误（多一个 S，且零导入）；③ `config.py:409` 使用未定义 `logger` | 待 P1-7 |
|
||||
|
||||
## 四、已完成的修复（v3.0/v3.1/批次 0，勿重复）
|
||||
|
||||
| 日期 | 修复 | 位置 |
|
||||
|------|------|------|
|
||||
| v3.0 | 后端 ApprovalMatcher 统一匹配；前端 ApprovalCardModal 纯渲染；APPROVAL_TEMPLATES 扩展 icon/desc/category；删除前端 APPROVAL_OPTIONS / APPROVAL_URL_MAP / getApprovalKeywords API | `approval_matcher.py`、`approval.py`、`ApprovalCardModal.vue`、`MessageBubble.vue`、`RecommendCard.vue`、`conversation.ts` |
|
||||
| v3.1 | Dify 无 action 降级（h5_ai_task.py:1252-1272）+ 超时降级（:1205-1241）；修复 `message_content` 未定义 bug（3 处改 `content`） | `h5_ai_task.py` |
|
||||
| 批次 0 | dify_main_chat_prompt v1.2 同步线上；DEPLOY-GUIDE §4.3 部署铁律；2 个 prompt 文档标废弃；本目录归档 | `docs/` |
|
||||
|
||||
---
|
||||
|
||||
**参考**：完整方案见 `00-v4.0重构总方案.md`；批次执行记录见 `01-批次1-P0执行记录.md` 等。
|
||||
@@ -0,0 +1,78 @@
|
||||
# 12-重构记录 — 目录索引与执行状态看板
|
||||
|
||||
> **创建**：2026-07-17
|
||||
> **目的**：智能回复系统 v4.0 深度重构的全部记录。当前会话不可用时，新会话读本目录即可继续推进。
|
||||
> **工作方式**：敏捷批次交付 + DevOps（文档与代码同 PR）
|
||||
|
||||
---
|
||||
|
||||
## 一、新会话快速上手指引（3 步）
|
||||
|
||||
1. **读方案**：`00-v4.0重构总方案.md`（分层架构、批次计划、验收清单）
|
||||
2. **读问题**：`01-问题验证清单.md`（20 项问题 + 源码行号证据 + 已完成修复清单）
|
||||
3. **看状态**：本文 §三（执行状态看板），找到「待开始」的任务说明书，按 `docs/10-项目管理/任务说明书/` 执行
|
||||
|
||||
## 二、目录结构
|
||||
|
||||
```
|
||||
docs/12-重构记录/
|
||||
├── README.md ← 本文件（索引 + 状态看板）
|
||||
├── 00-v4.0重构总方案.md ← 目标架构、批次计划、验收清单、回滚策略
|
||||
├── 01-问题验证清单.md ← 20 项问题源码证据（B1-B8/F1-F6/C1-C6）
|
||||
├── 02-批次1-P0执行记录.md ← 批次 1 完成后填写
|
||||
├── 03-批次2-P1基础执行记录.md
|
||||
├── 04-批次3-P1核心执行记录.md
|
||||
└── 99-回顾报告.md ← 批次 3 观察 24h 后填写
|
||||
```
|
||||
|
||||
**配套文档**：
|
||||
- 任务说明书：`docs/10-项目管理/任务说明书/任务说明书-78/79/84/85/86/87/88/89/90`
|
||||
- 部署铁律：`docs/09-部署运维/DEPLOY-GUIDE.md` §4.3
|
||||
- Dify 主 prompt 线上版本：`docs/02-产品需求/dify_main_chat_prompt_v1.md`（v1.2）
|
||||
|
||||
## 三、执行状态看板
|
||||
|
||||
> 更新规则：每完成一项即更新。新会话从这里接续。
|
||||
|
||||
| 批次 | 任务 | 任务说明书 | 状态 | 完成日期 |
|
||||
|------|------|-----------|------|---------|
|
||||
| — | v3.0 后端 ApprovalMatcher + 前端纯渲染 | — | ✅ 已完成 | 2026-07-17 |
|
||||
| — | v3.1 Dify 无 action 降级 + message_content bug 修复 | — | ✅ 已完成 | 2026-07-17 |
|
||||
| 批次 0 | 文档速修 4 项 + 本目录归档 | — | ✅ 已完成 | 2026-07-17 |
|
||||
| 批次 1 | P0-1 workers=2→1 | #78 | ⬜ 待开始 | — |
|
||||
| 批次 1 | P0-2 DIFY_NATIVE_* 生产配置 | #79 | ⬜ 待开始 | — |
|
||||
| 批次 1 | P0-3 快捷申请空白气泡修复 | #87 | ⬜ 待开始 | — |
|
||||
| 批次 1 | P0-4 RecommendCard invokeApproval 修复 | #88 | ⬜ 待开始 | — |
|
||||
| 批次 1 | P0-5 WS new_message 全字段透传 | #89 | ⬜ 待开始 | — |
|
||||
| 批次 1 | P0-6 超时预算切分 | #90 | ⬜ 待开始 | — |
|
||||
| 批次 2 | P1 基础（单例/统一调用点/Matcher/配置治理） | #84 | ⬜ 待开始 | — |
|
||||
| 批次 3 | P1 核心（编排层管线化 + WS 路由清理） | #85 | ⬜ 待开始 | — |
|
||||
| 批次 4 | P2（死代码/triage 删除/测试） | #86 | ⬜ 待开始 | — |
|
||||
|
||||
## 四、关键上下文（新会话必读）
|
||||
|
||||
### 4.1 部署铁律（详 `docs/09-部署运维/DEPLOY-GUIDE.md` §4.3）
|
||||
1. backend 必须 `--workers 1`（override 会覆盖主文件，务必 `docker compose config | grep workers` 验证）
|
||||
2. `.env` 不会自动传入容器，新变量必须在 compose `environment:` 显式声明
|
||||
3. Redis 密码特殊字符必须 URL 编码（@→%40 #→%23 !→%21）
|
||||
|
||||
### 4.2 服务器部署通道
|
||||
- 堡垒机：`sxn@10.212.189.210:2222`（OTP），工具 `C:\Users\simon\.workbuddy\skills\jumpserver-ops\scripts\jms_ops.py`
|
||||
- 服务器项目根：`/opt/wecom-it-desk/`；backend 卷挂载 `./app:/app/app`，改 .py 后 `docker compose restart backend`
|
||||
- 前端部署：tar 上传 → 解压到 `frontend-h5/dist` → `docker compose up -d nginx`（容器重建非 reload）
|
||||
|
||||
### 4.3 回滚点
|
||||
- git tag `pre-v4-refactor`（批次 1 上线前打）
|
||||
- 前端备份：`frontend-h5/dist_bak_v13`
|
||||
|
||||
### 4.4 用户已确认的决策
|
||||
- Redis 密码**立即轮换**（批次 2，低峰期，新旧双备）
|
||||
- Triage 分诊链路**整体删除**（批次 4）
|
||||
- D1 意图合并**激进方案**（批次 3 先 5 条真实消息验证 Dify intent 字段，不稳定退回 gather 并行）
|
||||
|
||||
## 五、变更记录
|
||||
|
||||
| 日期 | 变更 | 说明 |
|
||||
|------|------|------|
|
||||
| 2026-07-17 | 创建目录 + 批次 0 完成 | 4 项文档速修 + 本索引 |
|
||||
| 2026-07-17 | 任务说明书 #78-86 创建 | 批次 1-4 全部任务书面化 |
|
||||
+158
-58
@@ -1,71 +1,171 @@
|
||||
# 代办事项类图
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class TodoSourceService {
|
||||
<<abstract>>
|
||||
+agent_userid: str
|
||||
+redis: aioredis.Redis
|
||||
+get_todo_list() List~TodoItemData~*
|
||||
+get_todo_detail(item_id: str) TodoItemData*
|
||||
direction TB
|
||||
|
||||
%% ===================== 后端 =====================
|
||||
|
||||
class SessionQueryService {
|
||||
+AsyncSession db
|
||||
+__init__(db: AsyncSession)
|
||||
+get_conversations(status, agent_id, page, page_size) Tuple~List~Conversation~, int~
|
||||
+get_agent_conversations(agent_id, page, page_size) Tuple~List~Conversation~, int~
|
||||
+get_conversation(conversation_id, include_messages) Conversation
|
||||
+get_employee_history_messages(employee_id, limit, before, current_conversation_id) Tuple~List~Message~, bool, Dict~str,str~~
|
||||
}
|
||||
|
||||
class ApprovalTodoService {
|
||||
-redis: aioredis.Redis
|
||||
-agent_userid: str
|
||||
-semaphore: asyncio.Semaphore
|
||||
+get_todo_list() List~TodoItemData~
|
||||
+get_todo_detail(sp_no: str) TodoItemData
|
||||
-_fetch_approval_sp_no_list() List~str~
|
||||
-_fetch_approval_details(sp_no_list: List~str~) List~dict~
|
||||
-_filter_by_current_approver(details: List~dict~) List~dict~
|
||||
-_map_to_todo_item(detail: dict) TodoItemData
|
||||
class Message {
|
||||
+str id
|
||||
+str conversation_id
|
||||
+str sender_type
|
||||
+str sender_id
|
||||
+str sender_name
|
||||
+str content
|
||||
+str msg_type
|
||||
+Optional~str~ reply_to_id
|
||||
+Optional~str~ media_url
|
||||
+Optional~str~ file_name
|
||||
+Optional~int~ file_size
|
||||
+Optional~Dict~ extra_data
|
||||
+bool ai_suggestion
|
||||
+str status
|
||||
+bool is_read
|
||||
+datetime created_at
|
||||
}
|
||||
|
||||
class ITSMService {
|
||||
-base_url: str
|
||||
-app_id: str
|
||||
-app_secret: str
|
||||
-redis: aioredis.Redis
|
||||
-agent_userid: str
|
||||
+get_todo_list() List~TodoItemData~
|
||||
+get_todo_detail(workitem_id: str) TodoItemData
|
||||
-_do_post(url: str, body: dict) dict
|
||||
-_get_workitem_detail(process_instance_id: int, executor: str) dict
|
||||
class Conversation {
|
||||
+str id
|
||||
+str employee_id
|
||||
+str employee_name
|
||||
+str status
|
||||
+str assigned_agent_id
|
||||
+datetime last_message_at
|
||||
+str last_message_summary
|
||||
+datetime created_at
|
||||
}
|
||||
|
||||
class ITSMSigner {
|
||||
+compute_signature(app_id: str, timestamp: str, app_secret: str, biz_data: dict) str
|
||||
-_get_signature_compatible(params: dict) str
|
||||
class HistoryMessageListResponse {
|
||||
+List~MessageResponse~ items
|
||||
+bool has_more
|
||||
+Dict~str,str~ conversation_summaries
|
||||
}
|
||||
|
||||
class TodoAggregatorService {
|
||||
-redis: aioredis.Redis
|
||||
-cache_ttl: int
|
||||
+get_todo_list(agent_userid: str, todo_type: Optional~str~) dict
|
||||
+get_todo_detail(agent_userid: str, item_id: str, todo_type: str) dict
|
||||
-_get_from_cache(agent_userid: str, todo_type: Optional~str~) Optional~dict~
|
||||
-_set_to_cache(agent_userid: str, todo_type: Optional~str~, data: dict) void
|
||||
-_invalidate_cache(agent_userid: str) void
|
||||
class MessageResponse {
|
||||
+str id
|
||||
+str conversation_id
|
||||
+str sender_type
|
||||
+str sender_id
|
||||
+str sender_name
|
||||
+str content
|
||||
+str msg_type
|
||||
+bool ai_suggestion
|
||||
+bool is_read
|
||||
+datetime created_at
|
||||
+Optional~str~ sender_avatar
|
||||
}
|
||||
|
||||
class TodoItemData {
|
||||
+id: str
|
||||
+type: str
|
||||
+title: str
|
||||
+priority: str
|
||||
+description: dict
|
||||
+status: str
|
||||
+assigned_agent_id: Optional~str~
|
||||
+corp_id: str
|
||||
+created_at: str
|
||||
+updated_at: str
|
||||
%% 后端关系
|
||||
SessionQueryService ..> Message : 查询
|
||||
SessionQueryService ..> Conversation : 查询
|
||||
HistoryMessageListResponse *-- MessageResponse : contains
|
||||
Message }--|| Conversation : belongs to
|
||||
|
||||
%% ===================== 前端 API 层 =====================
|
||||
|
||||
class MessageAPI {
|
||||
<<module: frontend-agent/src/api/message.ts>>
|
||||
+getMessages(conversationId, params) Promise~MessageListData~
|
||||
+sendMessage(conversationId, content, msgType, options) Promise~Message~
|
||||
+pollMessages(conversationId, afterMessageId) Promise~MessageListData~
|
||||
+getHistoryMessages(employeeId, params) Promise~HistoryMessageListData~
|
||||
}
|
||||
|
||||
TodoSourceService <|-- ApprovalTodoService
|
||||
TodoSourceService <|-- ITSMService
|
||||
TodoAggregatorService o-- ApprovalTodoService : creates
|
||||
TodoAggregatorService o-- ITSMService : creates
|
||||
ITSMService --> ITSMSigner : uses
|
||||
TodoSourceService ..> TodoItemData : returns
|
||||
```
|
||||
class HistoryMessageListData {
|
||||
<<TypeScript interface>>
|
||||
+Message[] items
|
||||
+bool has_more
|
||||
+Record~str,str~ conversation_summaries
|
||||
}
|
||||
|
||||
MessageAPI ..> HistoryMessageListData : returns
|
||||
MessageAPI ..> BackendAPI : HTTP GET
|
||||
|
||||
%% ===================== 前端 Store 层 =====================
|
||||
|
||||
class ConversationStore {
|
||||
<<Pinia Store>>
|
||||
%% 现有状态
|
||||
+Ref~Conversation[]~ conversations
|
||||
+Ref~str~ currentConversationId
|
||||
+Ref~Message[]~ messages
|
||||
+Ref~bool~ loadingMessages
|
||||
|
||||
%% 新增：历史模式状态
|
||||
+Ref~bool~ historyMode
|
||||
+Ref~Message[]~ historyMessages
|
||||
+Ref~bool~ historyLoading
|
||||
+Ref~bool~ historyHasMore
|
||||
+Ref~Record~str,str~~ historyConversationSummaries
|
||||
+Ref~str~ historyCursor
|
||||
|
||||
%% 新增：计算属性
|
||||
+Computed~Message[]~ displayMessages
|
||||
+Computed~bool~ isHistoryReadonly
|
||||
|
||||
%% 现有方法
|
||||
+fetchConversations() void
|
||||
+selectConversation(conversationId) void
|
||||
+fetchMessages(conversationId) void
|
||||
+sendReply(content, replyToId) void
|
||||
|
||||
%% 新增：历史模式方法
|
||||
+enableHistoryMode() Promise~void~
|
||||
+disableHistoryMode() void
|
||||
+loadMoreHistory() Promise~void~
|
||||
+resetHistoryState() void
|
||||
}
|
||||
|
||||
ConversationStore ..> MessageAPI : calls
|
||||
ConversationStore ..> Message : manages
|
||||
|
||||
%% ===================== 前端组件层 =====================
|
||||
|
||||
class UserInfoBar {
|
||||
<<Vue Component>>
|
||||
+Props: conversation, availableAgents, canInviteCollaborator
|
||||
+Emits: assign, resolve, toggle-pin, toggle-todo, transfer, invite
|
||||
+Emits: toggle-history %% 新增
|
||||
+resetForNewConversation() void
|
||||
%% 新增：历史开关三态
|
||||
+historyToggleClass: Computed~string~
|
||||
}
|
||||
|
||||
class ChatArea {
|
||||
<<Vue Component>>
|
||||
+conversationStore: ConversationStore
|
||||
+messageListRef: Ref~HTMLElement~
|
||||
%% 新增：渲染逻辑
|
||||
+renderedItems: Computed~Array~
|
||||
+handleToggleHistory() void
|
||||
+handleScrollUp() void
|
||||
%% 修改：displayMessages 替代 messages
|
||||
}
|
||||
|
||||
class ConversationSeparator {
|
||||
<<Vue Component — 新增>>
|
||||
+Props: summary: string
|
||||
+Props: isCurrent: boolean
|
||||
%% 纯展示组件，无 emit
|
||||
}
|
||||
|
||||
class MessageBubble {
|
||||
<<Vue Component — 已存在>>
|
||||
+Props: message: Message
|
||||
+Emits: reply, scroll-to-message
|
||||
}
|
||||
|
||||
%% 组件关系
|
||||
ChatArea ..> ConversationStore : uses
|
||||
ChatArea ..> UserInfoBar : contains
|
||||
ChatArea ..> ConversationSeparator : renders
|
||||
ChatArea ..> MessageBubble : renders
|
||||
UserInfoBar --|> ChatArea : child component
|
||||
ConversationSeparator --|> ChatArea : child component
|
||||
|
||||
@@ -1,99 +1,81 @@
|
||||
# 代办事项时序图
|
||||
|
||||
## 1. 代办列表查询流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant FE as 前端 TodoPanel
|
||||
participant API as GET /api/todo-items
|
||||
participant Agg as TodoAggregatorService
|
||||
participant Cache as Redis Cache
|
||||
participant Appr as ApprovalTodoService
|
||||
participant Wecom as 企微审批API
|
||||
participant ITSM as ITSMService
|
||||
participant ITSM_API as ITSM OpenAPI
|
||||
participant U as 坐席用户
|
||||
participant UI as UserInfoBar.vue
|
||||
participant CA as ChatArea.vue
|
||||
participant Store as ConversationStore
|
||||
participant API as message.ts API
|
||||
participant BE as Backend API
|
||||
participant DB as Database
|
||||
|
||||
FE->>API: GET /api/todo-items?type=approval
|
||||
API->>Agg: get_todo_list(agent_userid, type="approval")
|
||||
Agg->>Cache: GET todo:cache:{userid}:approval
|
||||
alt 缓存命中
|
||||
Cache-->>Agg: cached_data
|
||||
Agg-->>API: {items, total, cached:true}
|
||||
else 缓存未命中
|
||||
Agg->>Agg: asyncio.gather(approval_svc, itsm_svc, return_exceptions=True)
|
||||
par 并行查询审批
|
||||
Agg->>Appr: get_todo_list()
|
||||
Appr->>Wecom: getapprovaldata(sp_status=1, templates=18)
|
||||
Wecom-->>Appr: sp_no_list
|
||||
Appr->>Appr: asyncio.gather(getapprovaldetail × N)
|
||||
loop 每个sp_no并发获取详情
|
||||
Appr->>Wecom: getapprovaldetail(sp_no)
|
||||
Wecom-->>Appr: approval_detail
|
||||
end
|
||||
Appr->>Appr: _filter_by_current_approver(details)
|
||||
Appr->>Appr: _map_to_todo_item(detail)
|
||||
Appr-->>Agg: List[TodoItemData]
|
||||
and 并行查询工单
|
||||
Agg->>ITSM: get_todo_list()
|
||||
Note over ITSM: ITSM列表API待实现<br/>当前返回空列表+日志告警
|
||||
ITSM-->>Agg: List[TodoItemData] (空)
|
||||
end
|
||||
Agg->>Agg: merge + sort by priority
|
||||
Agg->>Cache: SET todo:cache:{userid}:approval TTL=45s
|
||||
Agg-->>API: {items, total, cached:false}
|
||||
end
|
||||
API-->>FE: {code:0, data:{items, total}}
|
||||
```
|
||||
Note over U,DB: ========== 阶段1：打开历史模式 ==========
|
||||
|
||||
## 2. 代办详情查询流程
|
||||
U->>UI: 点击"历史会话"开关按钮
|
||||
UI->>CA: $emit('toggle-history')
|
||||
CA->>Store: enableHistoryMode()
|
||||
Store->>Store: historyMode = true, historyLoading = true
|
||||
Store->>API: getHistoryMessages(employeeId, {limit:50, current_conversation_id})
|
||||
API->>BE: GET /api/employees/{employee_id}/history-messages?limit=50
|
||||
BE->>DB: SELECT conversations WHERE employee_id=?
|
||||
DB-->>BE: 会话ID列表 [conv1, conv2, conv3...]
|
||||
BE->>DB: SELECT messages WHERE conversation_id IN (...) ORDER BY created_at DESC LIMIT 51
|
||||
DB-->>BE: 消息列表 (50条 + 1条判断has_more)
|
||||
BE->>DB: 对每个会话查首条employee消息, 取前20字
|
||||
DB-->>BE: conversation_summaries {conv1:"摘要1", conv2:"摘要2"...}
|
||||
BE-->>API: {items:[...], has_more:true, conversation_summaries:{...}}
|
||||
API-->>Store: HistoryMessageListData
|
||||
Store->>Store: historyMessages = items.reverse() (ASC排序)
|
||||
Store->>Store: historyHasMore = has_more
|
||||
Store->>Store: historyCursor = historyMessages[0].id
|
||||
Store->>Store: historyConversationSummaries = conversation_summaries
|
||||
Store->>Store: historyLoading = false
|
||||
Store-->>CA: displayMessages 响应更新 (返回historyMessages)
|
||||
CA->>CA: 渲染消息列表 + 插入ConversationSeparator
|
||||
CA->>CA: 隐藏 ReplyBox + ReplySuggestArea (只读模式)
|
||||
CA-->>U: 显示合并历史时间线
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant FE as 前端 TaskDetailView
|
||||
participant API as GET /api/todo-items/{id}
|
||||
participant Agg as TodoAggregatorService
|
||||
participant Appr as ApprovalTodoService
|
||||
participant ITSM as ITSMService
|
||||
participant Wecom as 企微审批API
|
||||
participant ITSM_API as ITSM OpenAPI
|
||||
Note over U,DB: ========== 阶段2：向上滚动加载更多 ==========
|
||||
|
||||
FE->>API: GET /api/todo-items/approval:{sp_no}
|
||||
API->>Agg: get_todo_detail(agent_userid, item_id, todo_type="approval")
|
||||
|
||||
alt type == "approval"
|
||||
Agg->>Appr: get_todo_detail(sp_no)
|
||||
Appr->>Wecom: getapprovaldetail(sp_no)
|
||||
Wecom-->>Appr: approval_detail
|
||||
Appr->>Appr: _map_to_todo_item(detail)
|
||||
Appr-->>Agg: TodoItemData
|
||||
else type == "ticket"
|
||||
Agg->>ITSM: get_todo_detail(workitem_id)
|
||||
ITSM->>ITSM_API: POST /openapi/v1/process/workitem/detail
|
||||
ITSM_API-->>ITSM: {code:20000, data:{workitem_detail}}
|
||||
ITSM->>ITSM: _map_to_todo_item(detail)
|
||||
ITSM-->>Agg: TodoItemData
|
||||
end
|
||||
|
||||
Agg-->>API: TodoItemData
|
||||
API-->>FE: {code:0, data:{item}}
|
||||
```
|
||||
U->>CA: 向上滚动到顶部
|
||||
CA->>Store: loadMoreHistory()
|
||||
Store->>Store: historyLoading = true
|
||||
Store->>API: getHistoryMessages(employeeId, {limit:50, before:historyCursor})
|
||||
API->>BE: GET /api/employees/{employee_id}/history-messages?limit=50&before={msgId}
|
||||
BE->>DB: 获取before消息的created_at
|
||||
BE->>DB: SELECT messages WHERE conv IN (...) AND created_at < before_time ORDER BY DESC LIMIT 51
|
||||
DB-->>BE: 更旧的消息列表
|
||||
BE->>DB: 对新涉及的会话查首条employee消息摘要
|
||||
DB-->>BE: 补充 conversation_summaries
|
||||
BE-->>API: {items:[...], has_more:false, conversation_summaries:{...}}
|
||||
API-->>Store: HistoryMessageListData
|
||||
Store->>Store: historyMessages = newItems.reverse() + historyMessages (前插)
|
||||
Store->>Store: historyCursor = historyMessages[0].id (更新游标)
|
||||
Store->>Store: historyHasMore = has_more
|
||||
Store->>Store: merge conversation_summaries
|
||||
Store->>Store: historyLoading = false
|
||||
Store-->>CA: displayMessages 更新
|
||||
CA-->>U: 显示更多历史消息 + 新分隔条
|
||||
|
||||
## 3. ITSM 签名认证流程
|
||||
Note over U,DB: ========== 阶段3：关闭历史模式 ==========
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Svc as ITSMService
|
||||
participant Signer as ITSMSigner
|
||||
participant API as ITSM OpenAPI
|
||||
U->>UI: 再次点击"历史会话"开关
|
||||
UI->>CA: $emit('toggle-history')
|
||||
CA->>Store: disableHistoryMode()
|
||||
Store->>Store: historyMode = false
|
||||
Store->>Store: 清空 historyMessages, historyCursor, historyConversationSummaries
|
||||
Store-->>CA: displayMessages 返回 messages (正常数据源)
|
||||
CA->>CA: 恢复 ReplyBox + ReplySuggestArea
|
||||
CA-->>U: 显示当前会话正常消息
|
||||
|
||||
Svc->>Svc: timestamp = str(int(time.time()*1000))
|
||||
Svc->>Signer: compute_signature(app_id, timestamp, app_secret, biz_data)
|
||||
Signer->>Signer: sign_params = {appId, timestamp, appSecret, bizData}
|
||||
Signer->>Signer: sort by key ASC
|
||||
Signer->>Signer: concat all values → canonicalized_str
|
||||
Signer->>Signer: quote_plus(canonicalized_str)
|
||||
Signer->>Signer: sha1(q2).hexdigest().upper()
|
||||
Signer-->>Svc: sign_str
|
||||
Svc->>API: POST url, headers={appId, timestamp, sign}, json=body
|
||||
API-->>Svc: {code:20000, data:{...}}
|
||||
```
|
||||
Note over U,DB: ========== 阶段4：切换会话自动重置 ==========
|
||||
|
||||
U->>CA: 点击左栏其他会话
|
||||
CA->>Store: selectConversation(newConvId)
|
||||
Store->>Store: resetHistoryState() — historyMode=false, 清空历史状态
|
||||
Store->>Store: currentConversationId = newConvId
|
||||
Store->>API: getMessages(newConvId, {limit:50})
|
||||
API->>BE: GET /api/conversations/{newConvId}/messages?limit=50
|
||||
BE-->>API: 正常消息列表
|
||||
API-->>Store: MessageListData
|
||||
Store->>Store: messages = data.items
|
||||
Store-->>CA: displayMessages 返回 messages
|
||||
CA-->>U: 显示新会话消息 (历史模式已关闭)
|
||||
|
||||
+247
-476
@@ -1,550 +1,322 @@
|
||||
# 系统设计文档 — 代办事项真实数据源集成
|
||||
# 系统架构设计 — 历史会话开关功能
|
||||
|
||||
> 项目：企微IT智能服务台 — 代办面板去mock改造
|
||||
> 版本：v1.0
|
||||
> 日期：2026-07-11
|
||||
> 架构师：高见远（Bob）
|
||||
> 日期：2026-07-01
|
||||
> 基于 PRD v1.0 + 现有代码结构分析
|
||||
|
||||
---
|
||||
|
||||
## Part A: 系统设计
|
||||
|
||||
### 1. 实现方案
|
||||
### 1. 实现方案 + 框架选型
|
||||
|
||||
#### 1.1 核心技术挑战
|
||||
|
||||
| 挑战 | 方案 |
|
||||
|------|------|
|
||||
| 两个异构数据源（企微审批 + ITSM 工单）聚合为统一列表 | 引入 `TodoAggregatorService`，通过抽象接口 `TodoSourceService` 统一两个数据源，`asyncio.gather` 并行查询，`return_exceptions=True` 容错 |
|
||||
| 企微审批需 getapprovaldata → getapprovaldetail 二次过滤当前审批人，性能开销大 | 先用 `getapprovaldata` 按 sp_status=1 + 18 个模板批量获取 sp_no_list，再 `asyncio.gather` 并发调用 `getapprovaldetail`，最后用 `_extract_current_approver` 过滤 |
|
||||
| ITSM 列表 API 尚未获取，签名认证方式特殊 | 设计 `ITSMService` 为可插拔实现，签名计算抽为独立工具 `itsm_signer.py`，列表方法暂返回空列表 + 日志告警，待 API 到位后填充 |
|
||||
| Redis 缓存需区分不同坐席 | 缓存 key 设计：`todo:cache:{agent_userid}:{type_filter}`，TTL 45 秒 |
|
||||
| 彻底去 mock（后端 MOCK_TODO_ITEMS + 前端 mockTodoListData + device 类型） | 全量删除 mock 数据，schema 中 `VALID_TODO_TYPES` 移除 device，前端移除 DeviceDetail 引用 |
|
||||
| 挑战 | 说明 | 方案 |
|
||||
|------|------|------|
|
||||
| 跨会话消息聚合 | 需要将同一员工的所有会话消息合并为一条时间线，按时间排序 | 后端新增按 `employee_id` 聚合查询的接口，JOIN conversations + messages 表，按 `created_at` 全局排序 |
|
||||
| 分隔条主题提取 | 分隔条显示该会话中员工首条消息摘要（前20字），不新增数据库字段 | 后端在聚合查询时，对每个会话查找 `sender_type='employee'` 的最早一条消息，截取前20字作为 `conversation_summaries` 返回 |
|
||||
| 游标分页（跨会话） | 向上滚动加载更多历史消息，需跨会话游标分页 | 使用 `before` 参数（消息ID），后端根据该消息的 `created_at` 查询更早的消息，全局时间线分页 |
|
||||
| 模式切换无闪烁 | 开关切换时正常模式↔历史模式，消息列表无缝切换 | Store 新增 `displayMessages` computed，根据 `historyMode` 返回不同数据源；前端 `v-if` 切换加载态 |
|
||||
| 历史模式只读 | 历史模式下隐藏输入框、回复建议区 | ChatArea 中用 `historyMode` 控制 `ReplyBox` / `ReplySuggestArea` 的 `v-if` |
|
||||
| 会话切换自动重置 | 切换会话时关闭历史模式 | Store 的 `selectConversation()` 中调用 `resetHistoryState()` |
|
||||
|
||||
#### 1.2 框架与库选择
|
||||
#### 1.2 框架与库选型
|
||||
|
||||
| 库 | 用途 | 说明 |
|
||||
| 层 | 技术 | 说明 |
|
||||
|----|------|------|
|
||||
| `httpx` | 异步 HTTP 客户端 | 已用于 approval.py，复用 |
|
||||
| `redis.asyncio` | Redis 异步缓存 | 已用于 token 管理，复用 |
|
||||
| `asyncio` | 并发查询两个数据源 | Python 标准库，`asyncio.gather(return_exceptions=True)` |
|
||||
| `hashlib` | ITSM SHA1 签名 | Python 标准库 |
|
||||
| `urllib.parse.quote_plus` | ITSM 签名 URL 编码 | Python 标准库 |
|
||||
| 后端 | FastAPI + SQLAlchemy 2.0 (async) | 沿用现有技术栈，新增一个 GET 接口 |
|
||||
| 前端 | Vue 3 + Pinia + Element Plus | 沿用现有技术栈，新增一个组件 + Store 扩展 |
|
||||
| 分页 | 游标分页（`before` 参数） | 与现有 `getMessages()` 的分页方式一致，前端向上滚动触发 |
|
||||
|
||||
**结论：无需新增任何第三方依赖。**
|
||||
#### 1.3 后端新接口设计
|
||||
|
||||
#### 1.3 架构模式
|
||||
**`GET /api/employees/{employee_id}/history-messages`**
|
||||
|
||||
采用 **Service Layer + 策略模式**：
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `employee_id` | path (str) | — | 员工企微 UserID |
|
||||
| `limit` | query (int) | 50 | 每页消息数量（1~100） |
|
||||
| `before` | query (str?) | null | 游标：加载此消息ID之前的消息（向上翻页） |
|
||||
| `current_conversation_id` | query (str?) | null | 当前会话ID（用于标记当前会话的分隔条） |
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ API Layer (todo_items.py) │
|
||||
│ GET /api/todo-items │
|
||||
│ GET /api/todo-items/{id} │
|
||||
└──────────────────────┬──────────────────────────────────┘
|
||||
│ 调用
|
||||
┌──────────────────────▼──────────────────────────────────┐
|
||||
│ TodoAggregatorService │
|
||||
│ ┌─ Redis 缓存检查 ─────────────────────────────────┐ │
|
||||
│ │ 命中 → 直接返回 │ │
|
||||
│ │ 未命中 → asyncio.gather 并行查询 │ │
|
||||
│ └─────────────────────────────────────────────────┘ │
|
||||
│ ┌──────────────┬──────────────┐ │
|
||||
│ │ │ │ │
|
||||
│ ┌──────▼──────┐ ┌────▼─────────┐ │ │
|
||||
│ │ApprovalTodo │ │ ITSMService │ │ │
|
||||
│ │ Service │ │ (abstract) │ │ │
|
||||
│ └──────┬──────┘ └────┬─────────┘ │ │
|
||||
│ │ │ │ │
|
||||
│ ┌──────▼──────┐ ┌────▼─────────┐ │ │
|
||||
│ │ 企微审批API │ │ ITSM API │ │ │
|
||||
│ │ getapproval │ │ (待实现) │ │ │
|
||||
│ │ data/detail│ │ │ │ │
|
||||
│ └─────────────┘ └──────────────┘ │ │
|
||||
└──────────────────────────────────────┘
|
||||
**响应体：**
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"data": {
|
||||
"items": [ /* Message[] — 按时间倒序（最新在前），前端 reverse 后展示 */ ],
|
||||
"has_more": true,
|
||||
"conversation_summaries": {
|
||||
"conv-uuid-1": "VPN连接不上怎么办急",
|
||||
"conv-uuid-2": "邮箱登录失败提示密码"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 1.4 后端改造方案
|
||||
**后端查询逻辑：**
|
||||
1. 查询 `conversations` 表中 `employee_id = ?` 的所有会话，获取会话ID列表
|
||||
2. 查询 `messages` 表中 `conversation_id IN (会话ID列表)` 的消息
|
||||
3. 如有 `before` 参数，获取该消息的 `created_at`，只查更早的消息
|
||||
4. 按 `created_at DESC` 排序，取 `limit + 1` 条（多取1条判断 `has_more`）
|
||||
5. 对涉及的每个会话，查询其 `sender_type='employee'` 的最早一条消息，取前20字作为摘要
|
||||
6. 返回消息列表 + `has_more` + `conversation_summaries`
|
||||
|
||||
1. **新增 Service 层**（3 个文件）：
|
||||
- `TodoSourceService`（抽象基类）+ `ApprovalTodoService`（企微审批实现）
|
||||
- `ITSMService`（ITSM 工单实现，列表方法待 API 到位）
|
||||
- `TodoAggregatorService`（聚合服务，缓存 + 并行查询 + 容错）
|
||||
#### 1.4 前端组件改动方案
|
||||
|
||||
2. **新增 ITSM 签名工具**：`itsm_signer.py`，独立封装 SHA1 签名计算
|
||||
| 文件 | 改动类型 | 改动概述 |
|
||||
|------|----------|----------|
|
||||
| `UserInfoBar.vue` | 修改 | chips 区末尾（L86 备注chip之后）新增"历史会话"开关按钮，三态视觉（关闭/打开/加载中），新增 `toggle-history` emit |
|
||||
| `ChatArea.vue` | 修改 | 消息列表使用 `displayMessages` 替代 `messages`；渲染时插入 `ConversationSeparator`；历史模式隐藏 `ReplyBox`/`ReplySuggestArea`；监听向上滚动触发分页 |
|
||||
| `ConversationSeparator.vue` | **新增** | 会话分隔条组件，props: `summary`（首条消息摘要前20字）、`isCurrent`（是否当前会话） |
|
||||
| `conversation.ts` (Store) | 修改 | 新增历史模式状态（6个 ref + 2个 computed + 4个 action） |
|
||||
| `message.ts` (API) | 修改 | 新增 `getHistoryMessages()` 函数 + `HistoryMessageListData` 类型 |
|
||||
| `data.ts` (Mock) | 修改 | 新增 mock 历史消息数据（开发环境 fallback） |
|
||||
|
||||
3. **重写 `todo_items.py`**：删除 `MOCK_TODO_ITEMS`，调用 `TodoAggregatorService` 获取真实数据
|
||||
#### 1.5 状态管理方案（Store 新增）
|
||||
|
||||
4. **补充 `approval.py`**：新增 `get_approval_data()` 函数调用企微 `getapprovaldata` API
|
||||
**新增 State（6个 ref）：**
|
||||
```typescript
|
||||
historyMode: ref<boolean>(false) // 历史模式开关
|
||||
historyMessages: ref<Message[]>([]) // 历史合并时间线消息
|
||||
historyLoading: ref<boolean>(false) // 加载中状态
|
||||
historyHasMore: ref<boolean>(false) // 是否还有更多历史消息
|
||||
historyConversationSummaries: ref<Record<string, string>>({}) // 会话ID→首条消息摘要
|
||||
historyCursor: ref<string | null>(null) // 分页游标（最后加载的消息ID）
|
||||
```
|
||||
|
||||
5. **更新 `config.py`**：新增 `itsm_app_id`、`itsm_app_secret`、`itsm_base_url` 配置项
|
||||
**新增 Getters（2个 computed）：**
|
||||
```typescript
|
||||
displayMessages // historyMode ? historyMessages : messages
|
||||
isHistoryReadonly // historyMode（历史模式只读）
|
||||
```
|
||||
|
||||
6. **更新 `schemas/todo_item.py`**：`VALID_TODO_TYPES` 移除 `device`
|
||||
|
||||
#### 1.5 前端改造方案
|
||||
|
||||
1. **`api/todo.ts`**：类型定义移除 `device`，新增 `type` 查询参数
|
||||
2. **`stores/todo.ts`**：删除 `mockTodoListData` import 和 catch 块 mock fallback
|
||||
3. **`mock/data.ts`**：删除 `mockTodoListData` 导出
|
||||
4. **`TodoPanel.vue`**：新增类型筛选 Tab（全部/审批/工单）+ 手动刷新按钮 + 移除 device 类型样式
|
||||
5. **`TaskDetailView.vue`**：移除 DeviceDetail 引用
|
||||
6. **`DeviceDetail.vue`**：标记为废弃（保留文件但不再引用）
|
||||
**新增 Actions（4个）：**
|
||||
```typescript
|
||||
enableHistoryMode() // 打开历史模式，加载初始消息
|
||||
disableHistoryMode() // 关闭历史模式，清空历史状态
|
||||
loadMoreHistory() // 向上滚动加载更多（分页）
|
||||
resetHistoryState() // 重置所有历史状态（切换会话时调用）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 文件列表
|
||||
### 2. 文件列表及相对路径
|
||||
|
||||
#### 后端
|
||||
|
||||
| 文件路径 | 操作 | 说明 |
|
||||
|----------|------|------|
|
||||
| `backend/app/config.py` | 修改 | 新增 ITSM 配置项 |
|
||||
| `backend/app/schemas/todo_item.py` | 修改 | VALID_TODO_TYPES 移除 device |
|
||||
| `backend/app/models/todo_item.py` | 修改 | type 注释移除 device |
|
||||
| `backend/app/services/todo_source_service.py` | 新建 | 抽象基类 + ApprovalTodoService |
|
||||
| `backend/app/services/itsm_service.py` | 新建 | ITSM Service（签名认证 + 可插拔列表） |
|
||||
| `backend/app/services/todo_aggregator_service.py` | 新建 | 聚合服务（缓存 + 并行 + 容错） |
|
||||
| `backend/app/utils/itsm_signer.py` | 新建 | ITSM SHA1 签名工具 |
|
||||
| `backend/app/api/todo_items.py` | 修改 | 删除 mock，重写为真实数据聚合 |
|
||||
| `backend/app/api/approval.py` | 修改 | 新增 get_approval_data() |
|
||||
|
||||
#### 前端
|
||||
|
||||
| 文件路径 | 操作 | 说明 |
|
||||
|----------|------|------|
|
||||
| `frontend-agent/src/api/todo.ts` | 修改 | 移除 device 类型，新增 type 参数 |
|
||||
| `frontend-agent/src/stores/todo.ts` | 修改 | 移除 mock fallback |
|
||||
| `frontend-agent/src/mock/data.ts` | 修改 | 删除 mockTodoListData |
|
||||
| `frontend-agent/src/components/conversation/TodoPanel.vue` | 修改 | 新增 Tab + 刷新 + 移除 device |
|
||||
| `frontend-agent/src/components/chat/TaskDetailView.vue` | 修改 | 移除 DeviceDetail 引用 |
|
||||
| `frontend-agent/src/components/chat/task/DeviceDetail.vue` | 修改 | 废弃标记 |
|
||||
| `frontend-agent/src/components/chat/task/TicketDetail.vue` | 修改 | 适配真实 ITSM 数据结构 |
|
||||
| `frontend-agent/src/components/chat/task/ApprovalDetail.vue` | 修改 | 适配真实企微审批数据结构 |
|
||||
| # | 文件路径 | 改动类型 | 改动概述 |
|
||||
|---|----------|----------|----------|
|
||||
| 1 | `backend/app/api/messages.py` | 修改 | 新增 `GET /employees/{employee_id}/history-messages` 路由处理函数 |
|
||||
| 2 | `backend/app/services/conversation/session_query_service.py` | 修改 | 新增 `get_employee_history_messages()` 方法 |
|
||||
| 3 | `backend/app/schemas/message.py` | 修改 | 新增 `HistoryMessageListResponse` Pydantic Schema |
|
||||
| 4 | `frontend-agent/src/api/message.ts` | 修改 | 新增 `getHistoryMessages()` API 函数 + `HistoryMessageListData` 接口 |
|
||||
| 5 | `frontend-agent/src/stores/conversation.ts` | 修改 | 新增历史模式 state/getters/actions，修改 `selectConversation` 加入重置逻辑 |
|
||||
| 6 | `frontend-agent/src/mock/data.ts` | 修改 | 新增 `mockHistoryMessageData` mock 数据（开发 fallback） |
|
||||
| 7 | `frontend-agent/src/components/chat/UserInfoBar.vue` | 修改 | chips 区末尾新增历史开关按钮 + `toggle-history` emit + 三态样式 |
|
||||
| 8 | `frontend-agent/src/components/chat/ConversationSeparator.vue` | **新增** | 会话分隔条组件 |
|
||||
| 9 | `frontend-agent/src/components/chat/ChatArea.vue` | 修改 | 消息列表切换、分隔条插入、只读模式、滚动分页、空状态提示 |
|
||||
|
||||
---
|
||||
|
||||
### 3. 数据结构和接口（类图）
|
||||
### 3. 数据结构和接口
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class TodoSourceService {
|
||||
<<abstract>>
|
||||
+agent_userid: str
|
||||
+redis: aioredis.Redis
|
||||
+get_todo_list() List~TodoItemData~*
|
||||
+get_todo_detail(item_id: str) TodoItemData*
|
||||
}
|
||||
#### 3.1 类图
|
||||
|
||||
class ApprovalTodoService {
|
||||
-redis: aioredis.Redis
|
||||
-agent_userid: str
|
||||
+get_todo_list() List~TodoItemData~
|
||||
+get_todo_detail(sp_no: str) TodoItemData
|
||||
-_fetch_approval_sp_no_list() List~str~
|
||||
-_fetch_approval_details(sp_no_list: List~str~) List~dict~
|
||||
-_filter_by_current_approver(details: List~dict~) List~dict~
|
||||
-_map_to_todo_item(detail: dict) TodoItemData
|
||||
}
|
||||
> 详见 `docs/class-diagram.mermaid`
|
||||
|
||||
class ITSMService {
|
||||
-base_url: str
|
||||
-app_id: str
|
||||
-app_secret: str
|
||||
-redis: aioredis.Redis
|
||||
-agent_userid: str
|
||||
+get_todo_list() List~TodoItemData~
|
||||
+get_todo_detail(workitem_id: str) TodoItemData
|
||||
-_do_post(url: str, body: dict) dict
|
||||
-_get_workitem_detail(process_instance_id: int, executor: str) dict
|
||||
}
|
||||
#### 3.2 后端 Schema（Pydantic）
|
||||
|
||||
class ITSMSigner {
|
||||
+compute_signature(app_id: str, timestamp: str, app_secret: str, biz_data: dict) str
|
||||
-_get_signature_compatible(params: dict) str
|
||||
}
|
||||
```python
|
||||
# backend/app/schemas/message.py — 新增
|
||||
|
||||
class TodoAggregatorService {
|
||||
-redis: aioredis.Redis
|
||||
-cache_ttl: int
|
||||
+get_todo_list(agent_userid: str, todo_type: Optional~str~) dict
|
||||
+get_todo_detail(agent_userid: str, item_id: str, todo_type: str) dict
|
||||
-_get_from_cache(agent_userid: str, todo_type: Optional~str~) Optional~dict~
|
||||
-_set_to_cache(agent_userid: str, todo_type: Optional~str~, data: dict) void
|
||||
-_invalidate_cache(agent_userid: str) void
|
||||
}
|
||||
class ConversationSummary(BaseModel):
|
||||
"""会话分隔条摘要信息"""
|
||||
conversation_id: str
|
||||
summary: str # 员工首条消息前20字
|
||||
status: str # 会话状态
|
||||
created_at: datetime # 会话创建时间
|
||||
|
||||
class TodoItemData {
|
||||
+id: str
|
||||
+type: str
|
||||
+title: str
|
||||
+priority: str
|
||||
+description: dict
|
||||
+status: str
|
||||
+assigned_agent_id: Optional~str~
|
||||
+corp_id: str
|
||||
+created_at: str
|
||||
+updated_at: str
|
||||
}
|
||||
class HistoryMessageListResponse(BaseModel):
|
||||
"""历史消息列表响应（跨会话聚合）"""
|
||||
items: List[MessageResponse] # 消息列表（按时间倒序）
|
||||
has_more: bool # 是否还有更多
|
||||
conversation_summaries: Dict[str, str] # {conversation_id: "前20字摘要"}
|
||||
```
|
||||
|
||||
TodoSourceService <|-- ApprovalTodoService
|
||||
TodoSourceService <|-- ITSMService
|
||||
TodoAggregatorService o-- ApprovalTodoService : creates
|
||||
TodoAggregatorService o-- ITSMService : creates
|
||||
ITSMService --> ITSMSigner : uses
|
||||
TodoSourceService ..> TodoItemData : returns
|
||||
#### 3.3 前端 TypeScript 类型定义
|
||||
|
||||
```typescript
|
||||
// frontend-agent/src/api/message.ts — 新增
|
||||
|
||||
/** 历史消息列表响应（跨会话聚合） */
|
||||
export interface HistoryMessageListData {
|
||||
/** 消息列表（按时间倒序，最新在前） */
|
||||
items: Message[]
|
||||
/** 是否还有更多历史消息 */
|
||||
has_more: boolean
|
||||
/** 会话ID → 首条消息摘要（前20字） */
|
||||
conversation_summaries: Record<string, string>
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// frontend-agent/src/components/chat/ConversationSeparator.vue — Props
|
||||
|
||||
interface ConversationSeparatorProps {
|
||||
/** 分隔条显示文本（首条消息摘要前20字） */
|
||||
summary: string
|
||||
/** 是否为当前会话（当前会话高亮显示） */
|
||||
isCurrent: boolean
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 程序调用流程（时序图）
|
||||
|
||||
#### 4.1 代办列表查询流程
|
||||
> 详见 `docs/sequence-diagram.mermaid`
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant FE as 前端 TodoPanel
|
||||
participant API as GET /api/todo-items
|
||||
participant Agg as TodoAggregatorService
|
||||
participant Cache as Redis Cache
|
||||
participant Appr as ApprovalTodoService
|
||||
participant Wecom as 企微审批API
|
||||
participant ITSM as ITSMService
|
||||
participant ITSM_API as ITSM OpenAPI
|
||||
**核心流程：**
|
||||
|
||||
FE->>API: GET /api/todo-items?type=approval
|
||||
API->>Agg: get_todo_list(agent_userid, type="approval")
|
||||
Agg->>Cache: GET todo:cache:{userid}:approval
|
||||
alt 缓存命中
|
||||
Cache-->>Agg: cached_data
|
||||
Agg-->>API: {items, total, cached:true}
|
||||
else 缓存未命中
|
||||
Agg->>Agg: asyncio.gather(approval_svc, itsm_svc, return_exceptions=True)
|
||||
par 并行查询审批
|
||||
Agg->>Appr: get_todo_list()
|
||||
Appr->>Wecom: getapprovaldata(sp_status=1, templates=18)
|
||||
Wecom-->>Appr: sp_no_list
|
||||
Appr->>Appr: asyncio.gather(getapprovaldetail × N)
|
||||
loop 每个sp_no并发获取详情
|
||||
Appr->>Wecom: getapprovaldetail(sp_no)
|
||||
Wecom-->>Appr: approval_detail
|
||||
end
|
||||
Appr->>Appr: _filter_by_current_approver(details)
|
||||
Appr->>Appr: _map_to_todo_item(detail)
|
||||
Appr-->>Agg: List[TodoItemData]
|
||||
and 并行查询工单
|
||||
Agg->>ITSM: get_todo_list()
|
||||
Note over ITSM: ITSM列表API待实现<br/>当前返回空列表+日志告警
|
||||
ITSM-->>Agg: List[TodoItemData] (空)
|
||||
end
|
||||
Agg->>Agg: merge + sort by priority
|
||||
Agg->>Cache: SET todo:cache:{userid}:approval TTL=45s
|
||||
Agg-->>API: {items, total, cached:false}
|
||||
end
|
||||
API-->>FE: {code:0, data:{items, total}}
|
||||
```
|
||||
|
||||
#### 4.2 代办详情查询流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant FE as 前端 TaskDetailView
|
||||
participant API as GET /api/todo-items/{id}
|
||||
participant Agg as TodoAggregatorService
|
||||
participant Appr as ApprovalTodoService
|
||||
participant ITSM as ITSMService
|
||||
participant Wecom as 企微审批API
|
||||
participant ITSM_API as ITSM OpenAPI
|
||||
|
||||
FE->>API: GET /api/todo-items/approval:{sp_no}
|
||||
API->>Agg: get_todo_detail(agent_userid, item_id, todo_type="approval")
|
||||
|
||||
alt type == "approval"
|
||||
Agg->>Appr: get_todo_detail(sp_no)
|
||||
Appr->>Wecom: getapprovaldetail(sp_no)
|
||||
Wecom-->>Appr: approval_detail
|
||||
Appr->>Appr: _map_to_todo_item(detail)
|
||||
Appr-->>Agg: TodoItemData
|
||||
else type == "ticket"
|
||||
Agg->>ITSM: get_todo_detail(workitem_id)
|
||||
ITSM->>ITSM_API: POST /openapi/v1/process/workitem/detail
|
||||
ITSM_API-->>ITSM: {code:20000, data:{workitem_detail}}
|
||||
ITSM->>ITSM: _map_to_todo_item(detail)
|
||||
ITSM-->>Agg: TodoItemData
|
||||
end
|
||||
|
||||
Agg-->>API: TodoItemData
|
||||
API-->>FE: {code:0, data:{item}}
|
||||
```
|
||||
|
||||
#### 4.3 ITSM 签名认证流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Svc as ITSMService
|
||||
participant Signer as ITSMSigner
|
||||
participant API as ITSM OpenAPI
|
||||
|
||||
Svc->>Svc: timestamp = str(int(time.time()*1000))
|
||||
Svc->>Signer: compute_signature(app_id, timestamp, app_secret, biz_data)
|
||||
Signer->>Signer: sign_params = {appId, timestamp, appSecret, bizData}
|
||||
Signer->>Signer: sort by key ASC
|
||||
Signer->>Signer: concat all values → canonicalized_str
|
||||
Signer->>Signer: quote_plus(canonicalized_str)
|
||||
Signer->>Signer: sha1(q2).hexdigest().upper()
|
||||
Signer-->>Svc: sign_str
|
||||
Svc->>API: POST url, headers={appId, timestamp, sign}, json=body
|
||||
API-->>Svc: {code:20000, data:{...}}
|
||||
```
|
||||
1. **打开历史模式**：点击开关 → Store.enableHistoryMode() → API 请求 → 渲染合并时间线
|
||||
2. **向上滚动加载更多**：检测滚动到顶部 → Store.loadMoreHistory() → API 请求（before游标）→ 前插消息
|
||||
3. **关闭历史模式**：点击开关 → Store.disableHistoryMode() → 恢复正常消息列表
|
||||
4. **切换会话重置**：selectConversation() → resetHistoryState() → historyMode=false
|
||||
|
||||
---
|
||||
|
||||
### 5. 待明确事项
|
||||
### 5. 任务列表
|
||||
|
||||
| # | 问题 | 当前假设 | 影响 |
|
||||
|---|------|---------|------|
|
||||
| 1 | ITSM 代办列表 API 端点和请求/响应格式 | 设计为抽象接口，列表方法暂返回空列表 | 待用户抓包获取后实现，不影响架构 |
|
||||
| 2 | ITSM app_id 和 app_secret | 需在 config.py 中新增配置项占位 | 部署时通过环境变量注入 |
|
||||
| 3 | 企微 getapprovaldata 单次查询上限（size 参数） | 假设每页100条，循环 cursor 分页 | 如上限更小需增加分页逻辑 |
|
||||
| 4 | 审批详情并发查询数量较多时的限流 | 使用 asyncio.Semaphore 限制并发数（默认10） | 防止企微 API 限流 |
|
||||
| 5 | 坐席身份标识（agent_userid）从哪里获取 | 假设从请求 header 或 JWT token 中提取 | 需确认认证中间件传递方式 |
|
||||
| 6 | ITSM 工单的优先级映射规则 | 假设 ITSM 有自己的优先级字段，需映射到 urgent/high/normal | 待 API 确认后调整映射逻辑 |
|
||||
| 任务ID | 任务名称 | 涉及文件 | 依赖 | 优先级 |
|
||||
|--------|----------|----------|------|--------|
|
||||
| T01 | 后端 — 历史消息聚合接口 | `backend/app/api/messages.py`、`backend/app/services/conversation/session_query_service.py`、`backend/app/schemas/message.py` | 无 | P0 |
|
||||
| T02 | 前端数据层 — API + Store + Mock | `frontend-agent/src/api/message.ts`、`frontend-agent/src/stores/conversation.ts`、`frontend-agent/src/mock/data.ts` | T01 | P0 |
|
||||
| T03 | 前端组件层 — 开关 + 分隔条 + 消息列表改造 | `frontend-agent/src/components/chat/UserInfoBar.vue`、`frontend-agent/src/components/chat/ConversationSeparator.vue`（新增）、`frontend-agent/src/components/chat/ChatArea.vue` | T02 | P0 |
|
||||
|
||||
---
|
||||
|
||||
## Part B: 任务分解
|
||||
|
||||
### 6. 依赖包列表
|
||||
|
||||
**无新增第三方依赖。** 所有所需库已在项目中使用：
|
||||
- `httpx` — 已用于 approval.py 的企微 API 调用
|
||||
- `redis.asyncio` — 已用于 token 缓存管理
|
||||
- `hashlib` — Python 标准库（ITSM SHA1 签名）
|
||||
- `urllib.parse.quote_plus` — Python 标准库（ITSM 签名 URL 编码）
|
||||
- `asyncio` — Python 标准库（并行查询）
|
||||
**无需新增任何第三方依赖。**
|
||||
|
||||
- 后端：复用现有 FastAPI + SQLAlchemy 2.0 async
|
||||
- 前端：复用现有 Vue 3 + Pinia + Element Plus + Axios
|
||||
|
||||
---
|
||||
|
||||
### 7. 任务列表
|
||||
### 7. 共享知识（跨文件约定）
|
||||
|
||||
#### T01: 后端基础设施与数据模型
|
||||
**依赖**：无
|
||||
**优先级**：P0
|
||||
**文件**：
|
||||
- `backend/app/config.py`（修改）
|
||||
- `backend/app/schemas/todo_item.py`（修改）
|
||||
- `backend/app/models/todo_item.py`（修改）
|
||||
#### 7.1 消息合并时间线数据结构约定
|
||||
|
||||
**描述**：
|
||||
1. config.py 新增 ITSM 配置项：
|
||||
- `itsm_app_id: str = ""`
|
||||
- `itsm_app_secret: str = ""`
|
||||
- `itsm_base_url: str = "https://devops.dc.servyou-it.com/itsm"`（生产）
|
||||
- `itsm_test_base_url: str = "https://test-devops.dc.servyou-it.com/itsm"`（测试）
|
||||
2. schemas/todo_item.py：
|
||||
- `VALID_TODO_TYPES` 从 `{"ticket", "approval", "device"}` 改为 `{"ticket", "approval"}`
|
||||
- 更新所有字段描述中的类型注释
|
||||
3. models/todo_item.py：
|
||||
- type 字段注释从 `ticket/approval/device` 改为 `ticket/approval`
|
||||
```
|
||||
历史模式 displayMessages 返回的是一维 Message[] 数组（与正常模式相同的类型），
|
||||
按 created_at 升序排列（最旧在前，最新在后），与正常聊天列表一致。
|
||||
|
||||
---
|
||||
前端在渲染时遍历 displayMessages，当检测到相邻两条消息的 conversation_id 不同时，
|
||||
在它们之间插入一个 ConversationSeparator 组件。
|
||||
|
||||
#### T02: 后端 Service 层 + ITSM 签名工具
|
||||
**依赖**：T01
|
||||
**优先级**：P0
|
||||
**文件**：
|
||||
- `backend/app/services/todo_source_service.py`（新建）
|
||||
- `backend/app/services/itsm_service.py`（新建）
|
||||
- `backend/app/services/todo_aggregator_service.py`（新建）
|
||||
- `backend/app/utils/itsm_signer.py`（新建）
|
||||
conversation_summaries 是一个 Record<string, string> 映射：
|
||||
key = conversation_id
|
||||
value = 该会话中员工首条消息的前20字摘要
|
||||
|
||||
**描述**：
|
||||
1. `todo_source_service.py`：
|
||||
- 定义抽象基类 `TodoSourceService`，含 `get_todo_list()` 和 `get_todo_detail()` 抽象方法
|
||||
- 实现 `ApprovalTodoService`：
|
||||
- `get_todo_list()`：调 `getapprovaldata`（sp_status=1, 18模板）→ 并发 `getapprovaldetail` → `_extract_current_approver` 过滤 → `_map_to_todo_item` 映射
|
||||
- `get_todo_detail(sp_no)`：调 `getapprovaldetail` → `_map_to_todo_item`
|
||||
- `_map_to_todo_item()`：企微审批详情 → TodoItemData 格式映射
|
||||
- 使用 `asyncio.Semaphore(10)` 限制并发详情查询
|
||||
2. `itsm_signer.py`：
|
||||
- `ITSMSigner.compute_signature(app_id, timestamp, app_secret, biz_data)` 静态方法
|
||||
- 实现 PRD 中的签名算法：sort → concat → quote_plus → sha1 → upper
|
||||
3. `itsm_service.py`：
|
||||
- 继承 `TodoSourceService`
|
||||
- `_do_post(url, body)`：签名 + 发送请求（复用 ITSMSigner）
|
||||
- `get_workitem_detail(process_instance_id, executor)`：调已知详情 API
|
||||
- `get_todo_list()`：**待 API 到位**，当前返回空列表 + `logger.warning`
|
||||
- `get_todo_detail(workitem_id)`：调 `get_workitem_detail` → 映射
|
||||
4. `todo_aggregator_service.py`：
|
||||
- `get_todo_list(agent_userid, todo_type)`：Redis 缓存 → `asyncio.gather(return_exceptions=True)` → 合并排序 → 写缓存
|
||||
- `get_todo_detail(agent_userid, item_id, todo_type)`：按类型路由到对应 Service
|
||||
- 缓存 key：`todo:cache:{agent_userid}:{todo_type or "all"}`，TTL 45s
|
||||
分隔条的 summary 从 conversation_summaries[message.conversation_id] 获取。
|
||||
```
|
||||
|
||||
---
|
||||
#### 7.2 分隔条组件 Props 约定
|
||||
|
||||
#### T03: 后端 API 改造
|
||||
**依赖**：T02
|
||||
**优先级**：P0
|
||||
**文件**：
|
||||
- `backend/app/api/todo_items.py`（修改）
|
||||
- `backend/app/api/approval.py`（修改）
|
||||
- `backend/app/api/router.py`（确认，无需修改路由注册）
|
||||
|
||||
**描述**：
|
||||
1. `todo_items.py`：
|
||||
- 删除 `MOCK_TODO_ITEMS`（全部20条硬编码数据）
|
||||
- 删除 `TodoItemResponse`、`TodoItemListResponse`（移至 schemas，复用已有）
|
||||
- `list_todo_items()`：新增 `type` 查询参数，调用 `TodoAggregatorService.get_todo_list()`
|
||||
- `get_todo_item()`：从 `item_id` 中解析类型前缀（如 `approval:{sp_no}` / `ticket:{workitem_id}`），调用 `TodoAggregatorService.get_todo_detail()`
|
||||
- `update_todo_item_status()`：保留但标记为"仅展示，不支持在服务台内操作"（按用户决策，交互方式为跳转原系统）
|
||||
- 从请求中获取 `agent_userid`（header 或 JWT）
|
||||
2. `approval.py`：
|
||||
- 新增 `get_approval_data(access_token, starttime, endtime, filters)` 异步函数
|
||||
- 调用企微 `POST /cgi-bin/oa/getapprovaldata` API
|
||||
- 支持 cursor 分页循环
|
||||
|
||||
---
|
||||
|
||||
#### T04: 前端数据层与 API 改造
|
||||
**依赖**：T03
|
||||
**优先级**：P0
|
||||
**文件**：
|
||||
- `frontend-agent/src/api/todo.ts`（修改）
|
||||
- `frontend-agent/src/stores/todo.ts`（修改）
|
||||
- `frontend-agent/src/mock/data.ts`（修改）
|
||||
|
||||
**描述**：
|
||||
1. `api/todo.ts`：
|
||||
- `TodoItemData.type` 注释移除 device
|
||||
- `getTodoItems()` 新增 `type` 参数：`type?: 'ticket' | 'approval'`
|
||||
- 新增 `refreshTodoItems()` 函数（带 `_force=1` 参数跳过缓存）
|
||||
2. `stores/todo.ts`：
|
||||
- 删除 `import { mockTodoListData } from '@/mock/data'`
|
||||
- `fetchTodoList()` catch 块：删除 mock fallback，改为 `todoList.value = []` + 错误日志
|
||||
- 新增 `activeType` ref：`'all' | 'approval' | 'ticket'`，传入 API type 参数
|
||||
- 新增 `refreshList()` 方法：强制刷新（调 `refreshTodoItems`）
|
||||
3. `mock/data.ts`：
|
||||
- 删除 `mockTodoListData` 常量和导出
|
||||
- 删除 `mockTodos` 数组（5条前端 mock 数据）
|
||||
|
||||
---
|
||||
|
||||
#### T05: 前端组件层改造
|
||||
**依赖**：T04
|
||||
**优先级**：P0（移除 device）/ P1（Tab+详情+刷新）/ P2（定时刷新+跳转）
|
||||
**文件**：
|
||||
- `frontend-agent/src/components/conversation/TodoPanel.vue`（修改）
|
||||
- `frontend-agent/src/components/chat/TaskDetailView.vue`（修改）
|
||||
- `frontend-agent/src/components/chat/task/DeviceDetail.vue`（修改/废弃）
|
||||
- `frontend-agent/src/components/chat/task/TicketDetail.vue`（修改）
|
||||
- `frontend-agent/src/components/chat/task/ApprovalDetail.vue`（修改）
|
||||
|
||||
**描述**：
|
||||
1. `TodoPanel.vue`（P0+P1+P2）：
|
||||
- `typeLabel` 移除 `device: '设备'`
|
||||
- 新增类型筛选 Tab（全部/审批/工单），切换时更新 `todoStore.activeType` + 刷新列表
|
||||
- 新增刷新按钮（🔄 图标），点击调 `todoStore.refreshList()`
|
||||
- 新增定时刷新（P2）：`setInterval(fetchTodoList, 60000)`，组件 `onUnmounted` 时清除
|
||||
- 新增跳转按钮（P2）：每条待办条目增加"在原系统中打开"链接（审批跳企微审批URL / 工单跳ITSM URL）
|
||||
- 移除 `.todo-type-tag.type-device` CSS 样式
|
||||
2. `TaskDetailView.vue`（P0）：
|
||||
- 移除 `import DeviceDetail from './task/DeviceDetail.vue'`
|
||||
- 移除 `v-else-if="todoItem.type === 'device'"` 条件渲染块
|
||||
- `typeLabelMap` 移除 `device: '🖥 设备异常'`
|
||||
- 移除 `.tdv-type-device` CSS 样式
|
||||
3. `DeviceDetail.vue`（P0）：
|
||||
- 文件头注释标记为"已废弃 — v1.0 移除 device 类型"
|
||||
- 保留文件但不再被任何组件引用
|
||||
4. `TicketDetail.vue`（P1）：
|
||||
- 适配真实 ITSM 工单数据结构（description 字段映射调整）
|
||||
- 底部操作按钮改为"在 ITSM 中打开"跳转链接（P2）
|
||||
5. `ApprovalDetail.vue`（P1）：
|
||||
- 适配真实企微审批数据结构（description 字段映射调整）
|
||||
- 底部操作按钮改为"在企微审批中打开"跳转链接（P2）
|
||||
|
||||
---
|
||||
|
||||
### 8. 共享知识（跨文件约定）
|
||||
|
||||
#### 8.1 统一数据映射规则
|
||||
|
||||
**企微审批 → TodoItemData 映射**：
|
||||
```python
|
||||
{
|
||||
"id": f"approval:{sp_no}", # 前缀类型 + 原始ID
|
||||
"type": "approval",
|
||||
"title": sp_name, # 审批单名称
|
||||
"priority": "high", # 审批默认 high（企微无优先级概念）
|
||||
"description": {
|
||||
"sp_no": sp_no,
|
||||
"template_name": template_name,
|
||||
"applicant": applyer_userid,
|
||||
"apply_time": apply_time,
|
||||
"sp_status": sp_status,
|
||||
"current_approver": current_approver,
|
||||
"template_id": template_id,
|
||||
},
|
||||
"status": "pending", # 审批中统一映射为 pending
|
||||
"assigned_agent_id": current_approver,
|
||||
"corp_id": corp_id,
|
||||
"created_at": apply_time_iso, # apply_time 时间戳转 ISO
|
||||
"updated_at": apply_time_iso,
|
||||
```typescript
|
||||
// ConversationSeparator.vue
|
||||
interface Props {
|
||||
summary: string // 首条消息摘要（前20字），已由后端截取
|
||||
isCurrent: boolean // 是否为当前会话（当前会话的分隔条高亮/加粗）
|
||||
}
|
||||
// 无 emit，纯展示组件（P1 搁置跳转功能）
|
||||
```
|
||||
|
||||
**ITSM 工单 → TodoItemData 映射**：
|
||||
```python
|
||||
#### 7.3 Store 状态切换约定
|
||||
|
||||
```
|
||||
正常模式 → 历史模式：
|
||||
1. historyMode = true
|
||||
2. historyLoading = true（触发 UI loading 态）
|
||||
3. 调用 API 加载初始50条
|
||||
4. 成功后：historyMessages = data.items.reverse()，historyHasMore = data.has_more
|
||||
5. historyCursor = historyMessages[0]?.id（最旧消息ID，用于下次分页）
|
||||
6. historyLoading = false
|
||||
|
||||
历史模式 → 正常模式：
|
||||
1. historyMode = false
|
||||
2. 清空 historyMessages、historyConversationSummaries、historyCursor
|
||||
3. messages ref 不受影响（正常模式数据源未变）
|
||||
|
||||
切换会话时：
|
||||
1. resetHistoryState() — 强制 historyMode = false，清空所有历史状态
|
||||
2. 然后执行正常的 fetchMessages()
|
||||
```
|
||||
|
||||
#### 7.4 API 响应格式约定
|
||||
|
||||
```
|
||||
所有后端 API 响应统一使用 success_response() 包装：
|
||||
{
|
||||
"id": f"ticket:{process_instance_id}", # 前缀类型 + 原始ID
|
||||
"type": "ticket",
|
||||
"title": title,
|
||||
"priority": itsm_priority_to_todo(priority), # ITSM 优先级 → urgent/high/normal
|
||||
"description": {
|
||||
"process_instance_id": process_instance_id,
|
||||
"executor": executor,
|
||||
"status": itsm_status,
|
||||
"creator": creator,
|
||||
# ... 其他 ITSM 字段
|
||||
},
|
||||
"status": "pending",
|
||||
"assigned_agent_id": agent_userid,
|
||||
"corp_id": "",
|
||||
"created_at": created_at_iso,
|
||||
"updated_at": updated_at_iso,
|
||||
"code": 200,
|
||||
"data": { ... },
|
||||
"message": "success"
|
||||
}
|
||||
|
||||
前端 apiClient 拦截器已自动解包，返回 response.data.data。
|
||||
因此 getHistoryMessages() 返回的是 data 字段内容（HistoryMessageListData）。
|
||||
```
|
||||
|
||||
#### 8.2 ID 格式约定
|
||||
|
||||
所有 TodoItem 的 `id` 字段使用 `{type}:{原始ID}` 格式：
|
||||
- 审批：`approval:{sp_no}`（如 `approval:202607110001`）
|
||||
- 工单：`ticket:{process_instance_id}`（如 `ticket:12345`）
|
||||
|
||||
解析规则：`item_id.split(":", 1)` → `[type, original_id]`
|
||||
|
||||
#### 8.3 缓存 Key 设计
|
||||
#### 7.5 消息排序约定
|
||||
|
||||
```
|
||||
todo:cache:{agent_userid}:{todo_type}
|
||||
后端返回：按 created_at DESC（最新在前）
|
||||
前端 Store：reverse() 后存储为 ASC（最旧在前，最新在后）
|
||||
前端渲染：从上到下 = 从旧到新（与正常聊天一致）
|
||||
分页游标：historyCursor = 最旧消息的ID（数组第一个元素）
|
||||
向上滚动：用 before=historyCursor 请求更旧的消息，prepend 到数组头部
|
||||
```
|
||||
- `agent_userid`：坐席企微 userid
|
||||
- `todo_type`：`all` / `approval` / `ticket`
|
||||
- TTL：45 秒
|
||||
- 强制刷新：删除 key 后重新查询
|
||||
|
||||
#### 8.4 API 响应格式
|
||||
#### 7.6 分隔条插入逻辑约定
|
||||
|
||||
统一使用 `{code: 0, data: {...}, message: "success"}` 格式（复用 `success_response`）。
|
||||
```typescript
|
||||
// ChatArea.vue 渲染逻辑伪代码
|
||||
const renderedItems = computed(() => {
|
||||
const msgs = conversationStore.displayMessages
|
||||
const result: Array<{ type: 'separator'; data: SeparatorData } | { type: 'message'; data: Message }> = []
|
||||
let lastConvId = ''
|
||||
|
||||
#### 8.5 并发控制
|
||||
for (const msg of msgs) {
|
||||
if (msg.conversation_id !== lastConvId) {
|
||||
// 会话切换，插入分隔条
|
||||
result.push({
|
||||
type: 'separator',
|
||||
data: {
|
||||
summary: conversationStore.historyConversationSummaries[msg.conversation_id] || '未知会话',
|
||||
isCurrent: msg.conversation_id === conversationStore.currentConversationId,
|
||||
}
|
||||
})
|
||||
lastConvId = msg.conversation_id
|
||||
}
|
||||
result.push({ type: 'message', data: msg })
|
||||
}
|
||||
return result
|
||||
})
|
||||
```
|
||||
|
||||
- 企微审批详情并发查询：`asyncio.Semaphore(10)` 限制
|
||||
- 两个数据源并行查询：`asyncio.gather(return_exceptions=True)`
|
||||
- 任一数据源失败不影响另一个：`isinstance(result, Exception)` 检查后跳过
|
||||
---
|
||||
|
||||
#### 8.6 前端类型约定
|
||||
### 8. 待明确事项
|
||||
|
||||
- `type` 字段：仅 `'ticket'` | `'approval'`（移除 `'device'`）
|
||||
- 前缀格式：前端通过 `id.includes('approval:')` 或 `id.includes('ticket:')` 判断类型
|
||||
| # | 问题 | 当前假设 | 建议确认方 |
|
||||
|---|------|----------|------------|
|
||||
| 1 | "当前会话排在最上方"的视觉含义 | 假设为：消息按时间正序排列（旧→新，与正常聊天一致），当前会话因最新而位于列表底部（用户初始可视区域）。分隔条中当前会话高亮标记。 | 产品经理 |
|
||||
| 2 | 历史模式下是否暂停消息轮询 | 假设：历史模式下暂停当前会话的消息轮询（`stopMessagePoll`），避免新消息混入历史时间线。关闭历史模式后恢复轮询。 | 产品经理 |
|
||||
| 3 | 历史消息是否需要标记已读 | 假设：历史消息不触发标记已读逻辑（只读查看，不修改 is_read 状态） | 产品经理 |
|
||||
| 4 | 员工无任何历史会话（仅当前会话）时的展示 | 假设：正常展示当前会话消息 + 一条当前会话的分隔条，不显示"暂无历史会话"提示 | 产品经理 |
|
||||
| 5 | 分隔条中是否显示会话状态（如"已结单"） | 假设：P0 仅显示首条消息摘要，不显示状态标签。P1 可扩展。 | 产品经理 |
|
||||
| 6 | 历史模式下 WebSocket 新消息推送的处理 | 假设：历史模式下收到新消息仍更新 `messages` ref（正常数据源），但不混入 `historyMessages`。关闭历史模式后即可看到。 | 架构师 |
|
||||
|
||||
---
|
||||
|
||||
@@ -552,20 +324,19 @@ todo:cache:{agent_userid}:{todo_type}
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
T01[T01: 后端基础设施与数据模型<br/>config.py + schemas + models]
|
||||
T02[T02: 后端Service层 + ITSM签名<br/>4个新文件]
|
||||
T03[T03: 后端API改造<br/>todo_items.py + approval.py]
|
||||
T04[T04: 前端数据层与API<br/>api/todo.ts + store + mock]
|
||||
T05[T05: 前端组件层<br/>TodoPanel + TaskDetailView + 3个子视图]
|
||||
T01[T01: 后端历史消息聚合接口]
|
||||
T02[T02: 前端数据层 API+Store+Mock]
|
||||
T03[T03: 前端组件层 开关+分隔条+消息列表]
|
||||
|
||||
T01 --> T02
|
||||
T02 --> T03
|
||||
T03 --> T04
|
||||
T04 --> T05
|
||||
|
||||
style T01 fill:#4CAF50,color:#fff
|
||||
style T02 fill:#2196F3,color:#fff
|
||||
style T03 fill:#2196F3,color:#fff
|
||||
style T04 fill:#FF9800,color:#fff
|
||||
style T05 fill:#FF9800,color:#fff
|
||||
style T03 fill:#FF9800,color:#fff
|
||||
```
|
||||
|
||||
**说明：**
|
||||
- T01（后端）无依赖，可最先开始
|
||||
- T02（前端数据层）依赖 T01 的接口契约（URL、参数、响应格式），但可基于接口契约先行开发 mock
|
||||
- T03（前端组件层）依赖 T02 的 Store API，是最终集成层
|
||||
|
||||
Reference in New Issue
Block a user