feat: 2026-07-11 全量更新 - 代办集成+会议室预定+知识迭代修复+UI统一+Bug修复
== 已部署上线 (9项) == - 代办事项真实数据源集成 (企微审批API 8bug修复链) - H5/坐席端 Logo样式统一+绿色背景 - 视频引导页修复 (localStorage key v2) - 坐席端 v9 Vue版本修复 (ElMessage._context) - 截图按钮 v10 修复 (getDisplayMedia user gesture) - 扫码样式恢复+H5扫码登录跳转修复 - H5截图快捷键提示 == 代码完成待部署 (3项) == - 知识迭代3Bug修复 (#8 POST端点/#7 MERGE幂等/#6 过期检查) - 会议室预定-小鱼易联终端 (40文件, 40/40测试通过) - IT资产升级审批推送 (asset_service.py) == 需求文档 (2项) == - 坐席端AI辅助消息框-PRD (4项新功能确认) - 坐席端布局优化建议 v2.0 (7天计划) == 新增文档 == - 日报-2026-07-11.md - 知识迭代Bug修复报告-20260711.md - 会议室预定-部署指南.md - CHANGELOG.md 更新 == 测试 == - test_todo_integration.py: 40/40 - test_meetingroom.py: 40/40 - test_bugfix_ki_suggestions.py: 21/21
This commit is contained in:
Simon
@@ -1,111 +0,0 @@
|
||||
# 任务总索引
|
||||
|
||||
> **版本**: v1.1 | **日期**: 2026-07-04 | **维护人**: 助理
|
||||
|
||||
---
|
||||
|
||||
## 📊 任务管理文档体系
|
||||
|
||||
本项目采用四级任务管理文档体系：
|
||||
|
||||
| 级别 | 文档 | 位置 | 用途 |
|
||||
|------|------|------|------|
|
||||
| L1 | **项目状态看板** | `05-项目状态看板/01-项目状态看板.md` | 驾驶舱仪表盘，当前正在做+待办 |
|
||||
| L2 | **项目任务状态报告** | `03-项目任务状态报告.md` | 历史全量任务清单（152个） |
|
||||
| L3 | **需求候选池** | `../02-产品需求/product-产品/v0.7.2-backlog-candidate-2026-06-24.md` | 未来版本候选功能 |
|
||||
| L4 | **PRD需求池** | `../02-产品需求/02-产品需求文档PRD-v1.2-20260704.md` | 完整需求来源 |
|
||||
|
||||
---
|
||||
|
||||
## 📍 快速导航
|
||||
|
||||
### 🔴 现在做什么？
|
||||
→ 查看 **项目状态看板** 的「正在做」和「P0必做」区
|
||||
|
||||
### 📜 历史全部任务？
|
||||
→ 查看 **项目任务状态报告**
|
||||
|
||||
### 📋 未来计划？
|
||||
→ 查看 **需求候选池** (v0.7.2+)
|
||||
|
||||
### 📖 需求来源？
|
||||
→ 查看 **PRD需求文档**
|
||||
|
||||
### 📅 每日工作记录？
|
||||
→ 查看 `.workbuddy/memory/` 目录
|
||||
|
||||
---
|
||||
|
||||
## 📈 版本与迭代
|
||||
|
||||
| 版本 | 状态 | 主要内容 | 日期 |
|
||||
|------|------|----------|------|
|
||||
| v0.7.0 | ✅ 已上线 | 企微SSO、MFA、RBAC | 2026-06 |
|
||||
| v0.7.1 | ✅ 已上线 | 敏感词检测、token修复、扫码登录优化 | 2026-07-04 |
|
||||
| v0.7.2 | 📋 规划中 | backlog候选（AI辅助、排查流程、知识库迭代） | 2026-07+ |
|
||||
|
||||
---
|
||||
|
||||
## 📊 最新项目变更（2026-07-04）
|
||||
|
||||
### 产品需求变更
|
||||
- 新增 **应急降级页需求** → `02-产品需求/03-需求-应急降级页发布预演.md`
|
||||
- 更新 **PRD v1.2** → 整合人工按钮与术语统一
|
||||
- 维护 **需求候选池** v0.7.2
|
||||
|
||||
### 技术架构变更
|
||||
- 整理 **技术方案** 5篇：ExternalSystemAdapter抽象层、消息功能、摇人协作、邀请功能、复杂场景重构
|
||||
- 整理 **技术分析** 3篇：架构消息知识库迭代、H5右侧栏动态推送、JumpServer自动化部署
|
||||
- 更新 **数据库设计** ER图与环境变量清点
|
||||
|
||||
### 文档管理变更
|
||||
- 规范化 **目录结构**：01-ADRs / 02-技术方案 / 03-技术分析 / 04-数据库设计 / 05-架构图
|
||||
- 统一 **文档编号**：去除重复前缀，统一命名规范
|
||||
|
||||
---
|
||||
|
||||
## 📂 任务管理文档清单
|
||||
|
||||
### 10-项目管理/
|
||||
|
||||
| 编号 | 文档 | 说明 |
|
||||
|------|------|------|
|
||||
| 01 | `01-任务总索引.md` | 本文档 |
|
||||
| 02 | `02-风险跟踪表.md` | 风险登记册（22项，73%已处理） |
|
||||
| 03 | `03-项目任务状态报告.md` | 历史全量任务（152个） |
|
||||
| 04 | `04-项目开发任务调整建议.md` | 任务调整建议 |
|
||||
| 05 | `05-项目状态看板/01-项目状态看板.md` | 驾驶舱仪表盘 |
|
||||
| 06 | `任务说明书-01-新开发任务.md` | v0.7.2 新功能开发任务 |
|
||||
| 07 | `任务说明书-02-卡点任务.md` | 优先级最高卡点任务 |
|
||||
| 08 | `任务说明书-模板.md` | 任务说明书模板 |
|
||||
|
||||
### SOPs-标准流程/
|
||||
|
||||
| 编号 | 文档 | 说明 |
|
||||
|------|------|------|
|
||||
| SOP-01 | `SOP-01-Gitea部署.md` | Gitea 部署 SOP |
|
||||
| SOP-02 | `SOP-02-Gitea备份恢复.md` | Gitea 备份恢复 SOP |
|
||||
| SOP-03 | `SOP-03-推送评审.md` | 推送评审 SOP |
|
||||
| SOP-04 | `SOP-04-应急响应.md` | 应急响应 SOP |
|
||||
| SOP-05 | `SOP-05-项目管理文档管理规范.md` | 文档管理规范 SOP |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 相关文档
|
||||
|
||||
| 类别 | 文档 | 位置 |
|
||||
|------|------|------|
|
||||
| 项目概览 | 项目总览与部署手册 | `01-项目总览/` |
|
||||
| 产品需求 | PRD需求文档 | `02-产品需求/` |
|
||||
| 技术架构 | 技术架构设计 | `03-技术架构/` |
|
||||
| 测试质量 | E2E验收清单 | `06-测试质量/` |
|
||||
| 部署运维 | 部署指南 | `09-部署运维/` |
|
||||
|
||||
---
|
||||
|
||||
## 📅 版本历史
|
||||
|
||||
| 版本 | 日期 | 变更 |
|
||||
|------|------|------|
|
||||
| v1.1 | 2026-07-04 | 新增产品需求变更、技术架构变更、文档管理变更 |
|
||||
| v1.0 | 2026-07-04 | 初始版本，整合任务管理文档体系 |
|
||||
@@ -1,355 +0,0 @@
|
||||
# 智能IT支持服务台 — 项目任务状态报告
|
||||
|
||||
**报告时间**: 2026-06-13 11:00
|
||||
**报告版本**: v1.0
|
||||
**任务空间状态**: 已清理（12个重复任务已删除）
|
||||
|
||||
---
|
||||
|
||||
## 一、任务空间概览
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| **总任务数** | 152 |
|
||||
| **已完成** | 151 (99.3%) |
|
||||
| **进行中** | 1 (0.7%) |
|
||||
| **待处理** | 0 |
|
||||
|
||||
---
|
||||
|
||||
## 二、五阶段演进进度
|
||||
|
||||
### ✅ 阶段一：MVP + 邀请 + 管理后台（108个任务）
|
||||
|
||||
| 功能模块 | 任务数 | 状态 | 关键任务ID |
|
||||
|---------|--------|------|-----------|
|
||||
| H5用户端基础功能 | 15 | ✅ 完成 | #14, #24, #67-84 |
|
||||
| 坐席工作台 | 20 | ✅ 完成 | #13, #23, #54-66 |
|
||||
| 邀请功能-后端 | 5 | ✅ 完成 | #108, #114, #119 |
|
||||
| 邀请功能-坐席端 | 3 | ✅ 完成 | #109, #145 |
|
||||
| 邀请功能-H5端 | 4 | ✅ 完成 | #110, #148 |
|
||||
| 管理后台 | 15 | ✅ 完成 | #97-98, #141-144 |
|
||||
| 端到端验证 | 1 | 🔄 进行中 | #149 |
|
||||
| 消息功能增强 | 10 | ✅ 完成 | #116-118, #120-121 |
|
||||
| 截图/表情/文件 | 15 | ✅ 完成 | #123-136 |
|
||||
| 部署配置 | 12 | ✅ 完成 | #15-17, #30, #85-90 |
|
||||
| 安全加固 | 3 | ✅ 完成 | #147 |
|
||||
|
||||
### ⏳ 阶段二：H5全流程 + WS + 排队 + 满意度 + OAuth2
|
||||
|
||||
| 功能模块 | 状态 | 备注 |
|
||||
|---------|------|------|
|
||||
| H5全流程 | ✅ 基础完成 | 邀请功能已闭环 |
|
||||
| WebSocket推送 | ✅ 完成 | H5 WS端点已上线 |
|
||||
| OAuth2认证 | ✅ 完成 | 企微环境限制已部署 |
|
||||
| 排队机制 | ❌ 未开始 | P1优先级 |
|
||||
| 满意度评价 | ❌ 未开始 | P1优先级 |
|
||||
|
||||
### ❌ 阶段三至五：待启动
|
||||
|
||||
- **阶段三**: AI Wingman + 排查流程图 + 标注
|
||||
- **阶段四**: 迭代闭环 + 数据看板 + 知识库
|
||||
- **阶段五**: 自动/辅助审核、开单、结单
|
||||
|
||||
---
|
||||
|
||||
## 三、跨阶段工作进度
|
||||
|
||||
### 🔐 外部系统集成（4个任务）
|
||||
|
||||
| 系统 | 任务ID | 状态 | 产出 |
|
||||
|------|--------|------|------|
|
||||
| 火绒企业版 | #137 | ✅ 完成 | 17个API端点，认证成功 |
|
||||
| 联软LV7000 | #138 | ✅ 完成 | 68个API端口，员工映射核心价值 |
|
||||
| aTrust零信任 | #139-140 | ✅ 完成 | 官方文档修正版 |
|
||||
| ExternalSystemAdapter | #150 | ✅ 完成 | 统一集成接口规范 |
|
||||
|
||||
### 🎨 UI/UX优化（20个任务）
|
||||
|
||||
| 类别 | 任务ID | 状态 |
|
||||
|------|--------|------|
|
||||
| CSS变量体系 | #26-29, #31-45, #61 | ✅ 完成 |
|
||||
| 深浅色切换 | #23-24 | ✅ 完成 |
|
||||
| 原型图迭代 | #54-55, #71-80 | ✅ 完成 |
|
||||
| 企微风格更新 | #156 | ✅ 完成 |
|
||||
| 术语统一 | #154 | ✅ 完成 |
|
||||
|
||||
### 📝 文档/PRD（18个任务）
|
||||
|
||||
| 类别 | 任务ID | 状态 |
|
||||
|------|--------|------|
|
||||
| PRD更新 | #1-10, #50-52, #96-99 | ✅ 完成 |
|
||||
| 架构文档 | #4, #12 | ✅ 完成 |
|
||||
| 部署文档 | #17 | ✅ 完成 |
|
||||
| 记忆文件 | #11, #18 | ✅ 完成 |
|
||||
|
||||
### 🐛 Bug修复（10个任务）
|
||||
|
||||
| Bug | 任务ID | 状态 | 说明 |
|
||||
|-----|--------|------|------|
|
||||
| system_alerts类型 | #141, #146 | ✅ 完成 | 阻断性Bug |
|
||||
| urgency_score列头 | #142 | ✅ 完成 | UI显示错误 |
|
||||
| agent role校验 | #143 | ✅ 完成 | 权限校验缺失 |
|
||||
| quick_reply status | #144 | ✅ 完成 | 状态校验缺失 |
|
||||
| H5登录认证 | #92, #151 | ✅ 完成 | JWT过期+循环依赖+401去重 |
|
||||
| API超时 | #25 | ✅ 完成 | 超时配置优化 |
|
||||
|
||||
### 🔒 安全加固（3个任务）
|
||||
|
||||
| 项目 | 任务ID | 状态 |
|
||||
|------|--------|------|
|
||||
| WebSocket认证 | #147 | ✅ 完成 |
|
||||
| WS消息去重 | #147 | ✅ 完成 |
|
||||
| Portal Token安全 | #151 | ✅ 完成 |
|
||||
|
||||
---
|
||||
|
||||
## 四、当前进行中的任务
|
||||
|
||||
### 🔄 #149: 1C端到端验证 — 完整链路跑通
|
||||
|
||||
**状态**: In Progress
|
||||
**阻塞**: 已解除（#148/#151已完成）
|
||||
**验证范围**:
|
||||
1. H5登录（OAuth2/Portal Token/降级登录）
|
||||
2. 坐席接单（会话分配/状态流转）
|
||||
3. 消息收发（文本/图片/文件/表情）
|
||||
4. 邀请功能（邀请→加入→退出→移除）
|
||||
5. 管理后台配置（仪表盘/功能开关/坐席管理）
|
||||
|
||||
**执行方式**: 需要在实际环境中手动验证
|
||||
**验证环境**:
|
||||
- 正式服务器: `https://itsupport.servyou.com.cn`
|
||||
- ~~NAS测试: `https://itdesk.amanzac.com`~~ (已下线)
|
||||
|
||||
---
|
||||
|
||||
## 五、任务清理记录
|
||||
|
||||
### 已删除的重复任务（12个）
|
||||
|
||||
| 任务ID | 原任务ID | 原因 |
|
||||
|--------|---------|------|
|
||||
| #155 | #148 | 邀请功能H5端补全重复 |
|
||||
| #152 | #150 | ExternalSystemAdapter重复 |
|
||||
| #153 | #147 | WebSocket WS-06去重子任务 |
|
||||
| #53 | #11 | 更新项目记忆文件重复 |
|
||||
| #166 | #130 | 构建验证重复 |
|
||||
| #133 | #129 | 截图功能修复重叠 |
|
||||
| #160 | #151 | H5登录Bug子任务 |
|
||||
| #161 | #151 | H5登录Bug子任务 |
|
||||
| #162 | #151 | H5登录Bug子任务 |
|
||||
| #163 | #156 | UI风格更新子任务 |
|
||||
| #164 | #156 | UI风格更新子任务 |
|
||||
| #165 | #156 | UI风格更新子任务 |
|
||||
|
||||
---
|
||||
|
||||
## 六、关键决策记录
|
||||
|
||||
### 2026-06-13 决策
|
||||
|
||||
| 决策 | 内容 | 影响 |
|
||||
|------|------|------|
|
||||
| UI风格统一 | 坐席端+H5端统一企微浅色扁平风格 | accent=#07C160 |
|
||||
| 术语统一 | "举手"→"招手"，"铃铛"→"传菜铃" | 25+处代码修改 |
|
||||
| 双企微应用方案 | 正式应用+测试应用 | 子域名申请困难 |
|
||||
| H5登录安全加固 | JWT过期检查+循环依赖修复+401去重 | 4项Bug修复 |
|
||||
|
||||
### 部署方案
|
||||
|
||||
| 阶段 | 正式环境 | 测试环境 |
|
||||
|------|---------|---------|
|
||||
| 正式上线前 | itsupport.servyou.com.cn (10.90.5.110) | ~~itdesk.amanzac.com (NAS)~~ (已下线) |
|
||||
| 正式上线后 | 公司高可用架构 | 10.90.5.10 |
|
||||
|
||||
---
|
||||
|
||||
## 七、技术债务清单
|
||||
|
||||
| 项目 | 优先级 | 说明 |
|
||||
|------|--------|------|
|
||||
| Redis密码加固 | P2 | 中风险安全项 |
|
||||
| PostgreSQL强密码 | P2 | 中风险安全项 |
|
||||
| CORS配置收紧 | P2 | 低风险安全项 |
|
||||
| CSP策略实施 | P2 | 低风险安全项 |
|
||||
| aTrust API对接 | P1 | 需找信息安全团队获取密钥 |
|
||||
| 北森eHR对接 | P1 | 需找HR数字化团队对接 |
|
||||
|
||||
---
|
||||
|
||||
## 八、下一步建议
|
||||
|
||||
### 立即执行（P0）
|
||||
1. **执行端到端验证**：在 10.90.5.10 正式环境验证完整链路
|
||||
2. **构建并部署最新代码**：将今天的 Bug 修复 + UI 风格更新部署到服务器
|
||||
|
||||
### 近期安排（P1）
|
||||
3. **创建测试企微应用**：按照双企微应用方案，创建"智能IT支持服务台-测试"应用
|
||||
4. **阶段二启动**：排队机制 + 满意度评价设计
|
||||
5. **aTrust对接**：找信息安全团队获取API密钥
|
||||
|
||||
### 技术债务（P2）
|
||||
6. **安全加固收尾**：Redis/PostgreSQL/CORS/CSP
|
||||
7. **统一入口 Phase 2-4**：路由选择页 + 管理后台
|
||||
|
||||
---
|
||||
|
||||
## 九、项目健康度评估
|
||||
|
||||
| 维度 | 评分 | 说明 |
|
||||
|------|------|------|
|
||||
| **任务管理** | ✅ 优秀 | 无重复、无冲突、进度清晰 |
|
||||
| **代码质量** | ✅ 优秀 | 前端构建通过率100%，后端编译验证通过 |
|
||||
| **测试覆盖** | ⚠️ 良好 | 邀请功能后端20个测试全部通过，前端测试待补充 |
|
||||
| **文档完整性** | ✅ 优秀 | PRD/架构/部署文档齐全 |
|
||||
| **安全状态** | ⚠️ 良好 | 严重+高风险已修复，中/低风险待处理 |
|
||||
|
||||
---
|
||||
|
||||
## 十、附录：完整任务列表
|
||||
|
||||
### 已完成任务（151个）
|
||||
|
||||
| ID | 任务名称 | 类别 |
|
||||
|----|---------|------|
|
||||
| #1 | 更新PRD §2 项目背景 | 文档 |
|
||||
| #2 | 重构PRD §5 演进路径 | 文档 |
|
||||
| #3 | 更新PRD §3 方案章节 | 文档 |
|
||||
| #4 | 更新ARCHITECTURE.md | 文档 |
|
||||
| #5 | 更新 PRD §5.1 阶段总览表 | 文档 |
|
||||
| #6 | 更新 PRD §3 方式四总览表 | 文档 |
|
||||
| #7 | 调整 PRD §5.2 阶段二详细规划 | 文档 |
|
||||
| #8 | 更新 PRD 文档版本号 | 文档 |
|
||||
| #9 | 更新 PRD §13 里程碑表 | 文档 |
|
||||
| #10 | 重写 PRD §5.2 阶段一详细规划 | 文档 |
|
||||
| #11 | 更新项目记忆文件 | 文档 |
|
||||
| #12 | 更新 ARCHITECTURE.md | 文档 |
|
||||
| #13 | 安装坐席端前端依赖并构建 | 部署 |
|
||||
| #14 | 安装H5员工端前端依赖并构建 | 部署 |
|
||||
| #15 | 准备 NAS Docker 部署配置 | 部署 |
|
||||
| #16 | 配置 Cloudflare Tunnel + DNS | 部署 |
|
||||
| #17 | 编写 NAS+Tunnel+企微 完整部署指南 | 文档 |
|
||||
| #18 | 更新项目文档和记忆 | 文档 |
|
||||
| #19 | 调查 Employee 前端 API 调用 | 调查 |
|
||||
| #20 | 调查 Agent 前端 API 调用 | 调查 |
|
||||
| #21 | 调查后端响应模型 | 调查 |
|
||||
| #22 | 调查 Axios 拦截器 | 调查 |
|
||||
| #23 | 修复坐席端深浅色切换样式 | UI |
|
||||
| #24 | 为H5员工端增加深浅色切换 | UI |
|
||||
| #25 | 排查H5端API超时根因 | Bug |
|
||||
| #26 | 更新Agent端global.css | CSS |
|
||||
| #27 | 更新H5端global.css | CSS |
|
||||
| #28 | 修复Agent端硬编码颜色 | CSS |
|
||||
| #29 | 修复H5端硬编码颜色 | CSS |
|
||||
| #30 | 构建前端并部署到NAS | 部署 |
|
||||
| #31-45 | 修复各组件硬编码颜色（15个） | CSS |
|
||||
| #46 | 检查 Agent 端代码同步状态 | 检查 |
|
||||
| #47 | 检查 H5 端代码同步状态 | 检查 |
|
||||
| #48 | 检查原型图 accent 色值 | 检查 |
|
||||
| #49 | 检查后端和配置文件同步 | 检查 |
|
||||
| #50 | 审读PRD文档 | 文档 |
|
||||
| #51 | 回答分配模式推荐 | 文档 |
|
||||
| #52 | 将决策同步至PRD | 文档 |
|
||||
| #54 | 调整坐席工作台原型图 v5.4 | 原型 |
|
||||
| #55 | 调整坐席工作台原型细节 | 原型 |
|
||||
| #56 | 更新 ConversationItem | UI |
|
||||
| #57 | 取消会话分类折叠 | UI |
|
||||
| #58 | TodoPanel 添加缩略头像 | UI |
|
||||
| #59 | ReplyBox 圆角卡片 | UI |
|
||||
| #60 | Workspace 三栏拖拽 | UI |
|
||||
| #61 | global.css 补充 v5.4 变量 | CSS |
|
||||
| #62-64 | 修改配色（3个） | UI |
|
||||
| #65 | 添加设备状态图标 | UI |
|
||||
| #66 | 消息输入框自适应高度 | UI |
|
||||
| #67 | H5复用排查步骤功能 | 功能 |
|
||||
| #68 | 重新设计H5排查步骤 | 功能 |
|
||||
| #69 | 重写TroubleshootFlow | 功能 |
|
||||
| #70 | 更新原型v5.4 | 原型 |
|
||||
| #71 | 创建 H5 用户端原型 | 原型 |
|
||||
| #72 | 创建双布局H5原型 | 原型 |
|
||||
| #73-80 | H5原型图迭代（8个） | 原型 |
|
||||
| #81 | 实现H5用户端Vue3代码 | 开发 |
|
||||
| #82 | 添加 agentOnline 属性 | 开发 |
|
||||
| #83 | 验证 CSS 自定义属性 | 检查 |
|
||||
| #84 | 构建 H5 前端验证 | 构建 |
|
||||
| #85 | 查阅 NAS 部署配置 | 部署 |
|
||||
| #86 | 构建 H5 前端 dist | 构建 |
|
||||
| #87 | 更新 NAS 部署配置 | 部署 |
|
||||
| #89 | 确认 NAS 部署文件 | 部署 |
|
||||
| #90 | 上传部署文件到 NAS | 部署 |
|
||||
| #92 | 修复 H5 端认证逻辑 | Bug |
|
||||
| #93 | 重新运行数据分析 | 分析 |
|
||||
| #94 | 生成完整汇报大纲 | 文档 |
|
||||
| #95 | 制作数据可视化图表 | 文档 |
|
||||
| #96 | 查找现有PRD文档 | 文档 |
|
||||
| #97 | 更新PRD文档 | 文档 |
|
||||
| #98 | 更新路线图文档 | 文档 |
|
||||
| #99 | 更新MEMORY.md | 文档 |
|
||||
| #100 | 生成新服务器部署方案 | 部署 |
|
||||
| #101 | 更新部署配置 | 部署 |
|
||||
| #102 | 修复 Dockerfile pip 超时 | 部署 |
|
||||
| #103 | 修复部署包目录结构 | 部署 |
|
||||
| #104 | 提供服务器端清理命令 | 部署 |
|
||||
| #105 | 重新生成部署包 | 部署 |
|
||||
| #106 | 对比 PRD M1 需求 | 分析 |
|
||||
| #107 | 检查M1遗漏功能 | 分析 |
|
||||
| #108 | 实现邀请功能-后端API | 开发 |
|
||||
| #109 | 实现邀请功能-坐席前端 | 开发 |
|
||||
| #110 | 实现邀请功能-H5落地页 | 开发 |
|
||||
| #111 | 更新PRD文件上传 | 文档 |
|
||||
| #112 | 搜索M1功能开源代码 | 调查 |
|
||||
| #113 | 寻找企微风格表情包 | 调查 |
|
||||
| #114 | 实现邀请功能 | 开发 |
|
||||
| #115 | 研究桌面远程协助 | 调查 |
|
||||
| #116 | 实现消息复制功能 | 开发 |
|
||||
| #117 | 实现图片粘贴上传 | 开发 |
|
||||
| #118 | 实现文件上传功能 | 开发 |
|
||||
| #119 | 创建 Alembic 迁移脚本 | 开发 |
|
||||
| #120 | 实现输入指示器 | 开发 |
|
||||
| #121 | 实现消息回复引用 | 开发 |
|
||||
| #122 | 启动本地开发环境验证 | 测试 |
|
||||
| #123 | 实现坐席端截图功能 | 开发 |
|
||||
| #124 | 同步消息边框和气泡样式 | UI |
|
||||
| #125 | 修复表情包英文、截图功能 | Bug |
|
||||
| #126 | 坐席端替换表情选择器 | 开发 |
|
||||
| #127 | 坐席端优化截图交互 | 开发 |
|
||||
| #128 | H5端修复表情面板 | Bug |
|
||||
| #129 | H5端修复截图功能 | Bug |
|
||||
| #130 | 构建验证 | 构建 |
|
||||
| #131 | 修复H5表情选择后输入框 | Bug |
|
||||
| #132 | 简化两端截图交互 | 开发 |
|
||||
| #134 | 实现会话框粘贴图片和文件 | 开发 |
|
||||
| #135 | 修复截图发送失败 | Bug |
|
||||
| #136 | 修复 H5 端截图确认后 | Bug |
|
||||
| #137 | 完成火绒集成分析报告 | 集成 |
|
||||
| #138 | 完成联软集成分析 | 集成 |
|
||||
| #139 | 完成aTrust零信任集成分析 | 集成 |
|
||||
| #140 | 基于官方docx修正aTrust | 集成 |
|
||||
| #141 | Bug1: system_alerts 类型 | Bug |
|
||||
| #142 | Monitor.vue: urgency_score | Bug |
|
||||
| #143 | Bug2: agent role 校验 | Bug |
|
||||
| #144 | Bug3: quick_reply status | Bug |
|
||||
| #145 | 邀请功能代码补全 | 开发 |
|
||||
| #146 | 修复 Bug1 遗留问题 | Bug |
|
||||
| #147 | WebSocket P0安全修复 | 安全 |
|
||||
| #148 | 跟踪：邀请群聊功能 | 跟踪 |
|
||||
| #150 | ExternalSystemAdapter设计 | 架构 |
|
||||
| #151 | 跟踪：员工端窗口Bug | 跟踪 |
|
||||
| #154 | "人工"按钮需求文档 | 文档 |
|
||||
| #156 | 原型图修改+UI风格更新 | UI |
|
||||
| #157 | 更新项目任务完成情况 | 文档 |
|
||||
| #158 | 生成项目状态报告 | 文档 |
|
||||
| #159 | 创建软件开发团队 | 管理 |
|
||||
|
||||
### 进行中任务（1个）
|
||||
|
||||
| ID | 任务名称 | 状态 | 阻塞 |
|
||||
|----|---------|------|------|
|
||||
| #149 | 1C端到端验证 | 🔄 进行中 | 无 |
|
||||
|
||||
---
|
||||
|
||||
**文档生成**: 2026-06-13 11:00
|
||||
**维护人**: 齐活林（Qi）· 交付总监
|
||||
**下次更新**: 端到端验证完成后
|
||||
@@ -1,183 +0,0 @@
|
||||
# 智能IT支持服务台 — 项目开发任务调整建议
|
||||
|
||||
> **文档版本**: V1.1
|
||||
> **创建日期**: 2026-06-11
|
||||
> **更新日期**: 2026-07-04
|
||||
> **作者**: 宋献 + WorkBuddy
|
||||
> **状态**: 已更新
|
||||
|
||||
---
|
||||
|
||||
## 一、项目当前状态总览（2026-07-04 更新）
|
||||
|
||||
| 维度 | 状态 | 备注 |
|
||||
|------|------|------|
|
||||
| PRD | ✅ v1.2 完成 | 整合人工按钮与术语统一，应急降级页需求 |
|
||||
| 技术架构 | ✅ 整理完成 | ADR 4篇 / 技术方案 5篇 / 技术分析 3篇 / 数据库设计 1篇 |
|
||||
| 坐席工作台 | ✅ v5.4 已上线 | WebSocket/快速回复/邀请/Ai推荐 |
|
||||
| H5用户端 | ✅ v2 已上线 | OAuth登录/AI面板/排查流程 |
|
||||
| 管理后台 | ✅ v1 已上线 | RBAC/快速回复审核/系统配置 |
|
||||
| 后端 | ✅ v0.7.1 已上线 | FastAPI/SQLAlchemy/完整API |
|
||||
| 原型 | ✅ v5.4 锁定 | 活跃原型12 + 历史17 |
|
||||
| 外部系统集成 | ✅ 3份完成 | 火绒/联软/aTrust 集成分析 |
|
||||
| 部署 | ✅ 正式生产已部署 | 10.90.5.110 |
|
||||
| **v0.7.1 上线** | ✅ 已完成 | 2026-07-04 |
|
||||
| **文档优化专项** | ✅ 已完成 | 目录结构规范化 |
|
||||
|
||||
---
|
||||
|
||||
## 二、核心问题识别
|
||||
|
||||
### 问题1：阶段一"最后一公里"卡住了
|
||||
|
||||
代码已写完但端到端验证未跑通，存在集成层面Gap。当前H5登录Bug + 管理后台类型问题，导致1C无法闭环。
|
||||
|
||||
### 问题2：外部系统对接全是"待对接"状态
|
||||
|
||||
4个外部系统（联软/火绒/aTrust/eHR）的分析文档已完成，但没有任何一个系统完成了实际API联调。这是阶段二及后续的关键路径依赖。
|
||||
|
||||
### 问题3：WebSocket安全债务积压
|
||||
|
||||
WS-01（认证缺失）是P0级安全问题，当前生产环境WebSocket无任何认证，阶段二实时推送上线前必须修复。
|
||||
|
||||
### 问题4：邀请功能设计完成，编码状态不明
|
||||
|
||||
PRD §21 已确认邀请功能纳入1A，技术方案和原型已完成，但代码层面是否有完整的后端API + 前端交互闭环需要验证。
|
||||
|
||||
---
|
||||
|
||||
## 三、调整建议
|
||||
|
||||
### 🔴 P0 — 立即推进（1~2周内）
|
||||
|
||||
| # | 任务 | 原排期 | 调整 | 原因 |
|
||||
|---|------|--------|------|------|
|
||||
| 1 | H5登录Bug修复 | 1C | 不变，优先级提升为最高 | 端到端验证的前置条件 |
|
||||
| 2 | 管理后台3个代码问题修复 | 1B | 不变，优先级提升 | system_alerts类型不匹配是阻断性的 |
|
||||
| 3 | 端到端验证(1C) | 1C | 不变 | 阶段一交付的唯一标准 |
|
||||
| 4 | 邀请功能端到端验证 | 1A | 确认编码完整性 | 设计+原型+技术方案都有，需确认代码是否可跑通 |
|
||||
|
||||
**建议做法**：集中1周时间，先修Bug → 跑通1C → 邀请功能验证。阶段一的目标是可演示的MVP，不追求完美。
|
||||
|
||||
### 🟡 P1 — 阶段二前置工作（2~4周内）
|
||||
|
||||
| # | 任务 | 原排期 | 调整 | 原因 |
|
||||
|---|------|--------|------|------|
|
||||
| 5 | WebSocket P0修复（WS-01认证+WS-06去重） | 2A | 提前至1C之后立即做 | 安全是不可妥协的，阶段二实时推送上线前必须完成 |
|
||||
| 6 | 联软API对接 | 无明确排期 | **新增为阶段二首个外部集成** | strusername是映射的金钥匙，联软是四系统架构的主源(P0) |
|
||||
| 7 | 外部系统抽象层设计 | 无 | **新增** | 后端需设计统一的ExternalSystemAdapter抽象层，联软/火绒/aTrust/eHR统一接口，解耦具体实现 |
|
||||
|
||||
**联软对接建议**：
|
||||
- 本周内：联系终端安全团队，申请API测试账户
|
||||
- 同时：后端先基于文档Mock数据开发抽象层
|
||||
- 获取账户后：立即联调验证
|
||||
|
||||
### 🟢 P2 — 中期推进（1~2月内）
|
||||
|
||||
| # | 任务 | 原排期 | 调整 | 原因 |
|
||||
|---|------|--------|------|------|
|
||||
| 8 | 火绒API对接 | 无明确排期 | 阶段二期间推进 | 火绒=安全源（杀毒+漏洞+隔离），与联软互补，但非映射关键路径 |
|
||||
| 9 | aTrust API对接 | 无明确排期 | 阶段二期间推进 | aTrust=VPN源，覆盖远程场景，需找信息安全团队获取API ID/密钥 |
|
||||
| 10 | eHR对接 | 无明确排期 | 阶段二后期 | eHR=辅助/静态数据，优先级最低 |
|
||||
| 11 | OAuth2登录切换 | 2D | 不变，等公司域名审批 | 1A~2C继续使用Mock登录，不影响功能开发 |
|
||||
|
||||
### 📋 备忘 — 条件触发
|
||||
|
||||
| 条件 | 触发动作 |
|
||||
|------|---------|
|
||||
| 公司购买了企微设备管理 | 接入为第五映射源（MAC→火绒交叉匹配桥） |
|
||||
| 坐席扩至3人以上 | 启用轮询/最少活跃分配模式（管理后台已预留） |
|
||||
| Dify Agent2创建完成 | 启动3A（AI Wingman验证） |
|
||||
|
||||
---
|
||||
|
||||
## 四、外部系统集成排程调整
|
||||
|
||||
原五阶段路线图未细化外部系统集成的具体排期。基于分析结果，建议如下：
|
||||
|
||||
```
|
||||
阶段一收尾（当前）
|
||||
└─ 1C端到端验证
|
||||
└─ 邀请功能闭环
|
||||
|
||||
阶段二（H5全流程+实时推送）
|
||||
├─ 2A WebSocket修复+实时推送
|
||||
│ └─ WS-01认证、WS-06去重（P0安全）
|
||||
├─ 2B 联软集成（映射主源） ← 🆕 新增
|
||||
│ └─ queryDevByParams → 员工↔终端映射
|
||||
│ └─ 抽象层 ExternalSystemAdapter
|
||||
├─ 2C 火绒集成（安全源） ← 🆕 新增
|
||||
│ └─ 终端列表+详情+漏洞+隔离
|
||||
├─ 2D 接单优化+满意度
|
||||
└─ 2E OAuth2（待域名审批）
|
||||
|
||||
阶段三（AI Wingman）
|
||||
├─ 3A AI Wingman验证
|
||||
├─ 3B 排查流程图+AI混合
|
||||
│ └─ aTrust集成（VPN源） ← 🆕 移入3B
|
||||
│ └─ VPN会话+踢出+授信状态
|
||||
├─ 3C 标注体系
|
||||
└─ eHR对接（辅助源） ← 🆕 移入3C后
|
||||
```
|
||||
|
||||
**调整逻辑**：
|
||||
- 联软提前到2B：映射是后续所有功能（终端信息面板、一键隔离、VPN状态）的基础设施，越早接入越好
|
||||
- 火绒紧跟联软2C：联软提供映射后，火绒的安全数据才有锚点（通过MAC/pc_name交叉匹配）
|
||||
- aTrust移到3B：VPN场景相对独立，不阻塞核心流程，与排查流程图结合更有价值
|
||||
- eHR放到3C后：静态数据同步，优先级最低，联软已经覆盖了映射需求
|
||||
|
||||
---
|
||||
|
||||
## 五、映射架构（已确认）
|
||||
|
||||
### 四系统联合架构
|
||||
|
||||
```
|
||||
联软 LV7000（主源 P0）
|
||||
└─ strusername → 精确员工账号→终端映射
|
||||
└─ 覆盖：总部办公员工（强制安装联软安全助手）
|
||||
|
||||
aTrust（VPN源）
|
||||
└─ name / bindUsers / vips（待实测）→ VPN终端映射
|
||||
└─ 覆盖：远程接入员工
|
||||
|
||||
eHR（辅助源）
|
||||
└─ 静态数据：部门/岗位/联系方式
|
||||
└─ 覆盖：人员基础信息补全
|
||||
|
||||
火绒（安全源，不参与映射）
|
||||
└─ 终端安全状态：杀毒/漏洞/隔离
|
||||
└─ 与联软通过MAC/pc_name交叉匹配
|
||||
```
|
||||
|
||||
### ❌ 已排除：企微设备管理
|
||||
|
||||
- 原因：企微"设备管理"为安全高级功能，需付费购买，公司未购买
|
||||
- API验证：errcode 48002（应用无调用权限）
|
||||
- 潜在价值：如未来购买，可作为交叉验证源
|
||||
- 企微仍作为通信平台（H5宿主+消息推送+用户身份认证），不参与终端映射
|
||||
|
||||
---
|
||||
|
||||
## 六、风险提示
|
||||
|
||||
| 风险 | 影响 | 缓解措施 |
|
||||
|------|------|---------|
|
||||
| 外部团队对接响应慢 | 联软/火绒/aTrust都是跨团队协作，API账户审批可能耗时2-4周 | 本周立即启动联系，同时用Mock数据开发 |
|
||||
| aTrust `vips`字段实测可能不存在 | VPN虚拟IP交叉匹配方案失效 | 联软的映射为主源，aTrust的vips仅为辅助验证 |
|
||||
| OAuth2域名审批延期 | H5必须继续用Mock登录，影响真实用户体验 | Mock登录已够用，阶段二功能不受影响 |
|
||||
| WebSocket认证修复涉及现有连接 | 修复后坐席端需同步升级 | 先在预生产环境验证，再灰度发布 |
|
||||
|
||||
---
|
||||
|
||||
## 七、建议的下一步行动
|
||||
|
||||
| 优先级 | 行动 | 负责人 | 时间 |
|
||||
|--------|------|--------|------|
|
||||
| 🔴 | 修复H5登录Bug | 开发 | 本周 |
|
||||
| 🔴 | 修复管理后台3个代码问题 | 开发 | 本周 |
|
||||
| 🔴 | 端到端验证(1C)跑通 | 开发 | 本周~下周 |
|
||||
| 🟡 | 联系终端安全团队（联软API账户） | 宋献 | 本周 |
|
||||
| 🟡 | 联系信息安全团队（火绒AccessKey + aTrust API ID） | 宋献 | 本周 |
|
||||
| 🟡 | 设计ExternalSystemAdapter抽象层 | 开发 | 下周 |
|
||||
| 🟢 | WebSocket P0安全修复 | 开发 | 1C完成后1周内 |
|
||||
@@ -1,387 +0,0 @@
|
||||
# 企微IT智能服务台 — 项目状态看板
|
||||
|
||||
> 📌 **这个文件就是项目的"驾驶舱仪表盘"**。任何时候新开 session,**先读这个文件就懂上下文**。
|
||||
>
|
||||
> 📝 **更新规则**:每次 Claude 完成 / 开始 / 阻塞重要任务,会主动更新本文件。你也可以自己改(纯 markdown,git 跟踪)。
|
||||
|
||||
最后更新:**2026-07-09**(WS 子协议修复部署生产 + 合入 origin/main；方案A E2E 2026-07-08 通过；+ 日志体系 5 项决策登记 #101–#104)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 一句话总览
|
||||
|
||||
**v0.7.1 已上线运行，生产稳定**。知识库迭代 v0.7.2 全链路交付完成：
|
||||
|
||||
**已完成 (v0.7.1)**:
|
||||
- ✅ 企微入口 SSO
|
||||
- ✅ 管理后台 RBAC（6处装饰器修复, 5/5 PASS）
|
||||
- ✅ 敏感词检测（隐私正则 \b→\d 修复, 89/89 PASS）
|
||||
- ✅ 扫码登录优化（iOS NSURLError 修复）
|
||||
- ✅ 文档优化专项（已完成）
|
||||
|
||||
**v0.7.2 知识库迭代（✅ 全部交付）**:
|
||||
- ✅ AI 辅助功能增强
|
||||
- ✅ 排查流程优化
|
||||
- ✅ 知识库迭代（Tier0+Tier1+可视化+去重+串联闭环, 49文件 169/169 PASS）
|
||||
|
||||
**P1/P2功能开发任务 ✅ 全部完成**:
|
||||
- ✅ 阶段2 (P1): 摇人按钮、满意度评价、排队系统、快速回复、知识库基础
|
||||
- ✅ 阶段3 (P2): AI Wingman、会话标注、自动摘要
|
||||
- ✅ 阶段4 (P2): 数据看板、知识库自动迭代（含图谱可视化+合并去重）
|
||||
- 📋 详细规格: `docs/02-产品需求/功能详细规格说明书-P1P2功能.md`
|
||||
|
||||
**文档优化专项 (2026-07-04) ✅ 已完成**:
|
||||
- ✅ 扫描并整理 docs/ 目录全部文档
|
||||
- ✅ 规范化目录结构（01-11 编号体系）
|
||||
- ✅ 恢复归档文档到正确位置
|
||||
- ✅ 整理 10-项目管理 目录
|
||||
- ✅ 整理 03-技术架构 目录
|
||||
|
||||
---
|
||||
|
||||
## 🟢 正在做(in_progress,1 件)
|
||||
|
||||
| # | 任务 | 说明 |
|
||||
|---|---|---|
|
||||
| #91 | 忘记密码-企微扫码重置 | 坐席忘记密码时通过企微扫码验证后重置 |
|
||||
|
||||
### #90 开发进度 (2026-07-06) ✅ 已完成
|
||||
|
||||
- ✅ 后端登录API (`/api/agents/login`)
|
||||
- ✅ 坐席端登录页面 (账号密码+OTP)
|
||||
- ✅ 管理端登录页面 (账号密码+OTP)
|
||||
- ✅ 企微客户端检测功能 (v1.8 新增)
|
||||
- ✅ 部署测试 (2026-07-06 10:05 生产验证通过)
|
||||
|
||||
### #91 开发进度 (2026-07-07) ✅ 已完成
|
||||
|
||||
- ✅ 后端API：`POST /api/agents/password/reset-by-wecom` 企微OAuth扫码重置密码
|
||||
- ✅ 前端：登录页"忘记密码"入口 (H5)
|
||||
- ✅ 前端：修改密码弹窗 (H5 + Admin)
|
||||
- ✅ 前端：用户头像菜单"修改密码" (H5 ChatPanel)
|
||||
- ✅ 部署测试：API验证通过 ✅
|
||||
|
||||
## 🔬 方案A 消息发送延时改造 — E2E 验真 (2026-07-08) ✅ 通过
|
||||
|
||||
> 真实浏览器端到端实测（系统 Chrome + Playwright）。报告：`docs/06-测试质量/方案A-消息发送延时-E2E验证报告-20260708.md`，截图：`docs/06-测试质量/e2e-screenshots/`
|
||||
|
||||
**验证结论**：✅ 员工端发送消息**瞬时返回不阻塞 UI**（点击 1.26s 返回，`ai_reply:null`），AI 回复经 **WebSocket 打字机流式**推送（收到 `ai_reply_chunk` **343 帧**，2.3s 起渲染，Duckula 头像 + 1469 字完整内容正常）。
|
||||
|
||||
**⚠️ 顺带修复 1 个真实后端 bug（生产相关）**：WebSocket 握手时浏览器用子协议 `bearer.{token}` 传 token，后端 `ws_manager.connect/connect_employee` 读了 token 却未在 `accept()` 回显子协议 → 浏览器拒绝握手。此前被 3s 轮询兜底**掩盖**，生产坐席/员工 WS 实际走了轮询而非流畅打字机。已修复 `accept(subprotocol=...)`。
|
||||
|
||||
**✅ 已部署生产 (2026-07-09 09:14)**：`docker cp` 修复文件进 `wecom_it_backend` 容器 + `docker restart`，重启后日志确认 H5 员工(tangzhenzhen)/坐席(sxn) WebSocket 连接 `[accepted]` 且**连接建立**（旧代码下浏览器会因未回显 subprotocol 拒绝握手，根本到不了 accepted）。commit `bacd34c` → cherry-pick `6db1c0e` 已推送 `origin/main`。Dify key 临时切换已还原回 `app-J3s8sHarZQ2SCaNF3xCppliL`（dev 验证用，备注于 compose）。
|
||||
|
||||
**另修复 3 个 dev 容器化环境阻断**（使「Docker dev 栈 + 真实浏览器 E2E」链路可用）：
|
||||
1. H5 应用无法挂载：dev compose 补挂载 `./frontend-h5/public:/app/public`（`duckula.webp` 镜像烘焙时缺失）
|
||||
2. Mock 登录 500：Vite 代理目标改为可配置 `VITE_PROXY_TARGET`（dev 注入 `http://backend:8000`）
|
||||
3. CSP 阻断 dev WS：`index.html` CSP `connect-src` 增加 `ws://localhost:8000`
|
||||
|
||||
---
|
||||
|
||||
## 🔬 验真结论 (2026-07-07) → ✅ 全部已修复 (2026-07-08)
|
||||
|
||||
> 5 项验真发现的缺陷，经 RBAC BugFix + 知识库迭代全链路 + 隐私正则修复，**全部已解决**。
|
||||
|
||||
| # | 功能 | 结论 | 修复 |
|
||||
|---|------|------|------|
|
||||
| ① | 排队系统 | ✅ 真实可用 | — |
|
||||
| ② | 知识库自动迭代 | ✅ 全链路（49文件/169测试） | Tier0+Tier1+P0串联+P2 |
|
||||
| ③ | AI Wingman | ✅ 真实可用 | — |
|
||||
| ④ | 管理后台 RBAC | ✅ 已修复（test_rbac 5/5） | 装饰器修复 |
|
||||
| ⑤ | 敏感词检测 | ✅ 已修复（隐私正则 \b→\d） | 89/89 PASS |
|
||||
- `tests/test_content_moderation.py`（11/13，2 失败即隐私 Bug 证据）
|
||||
- `tests/test_rbac_verification.py`（3/5，2 失败即 422 Bug 证据）
|
||||
|
||||
## 🔬 #75 头像同步功能 复盘 (2026-07-07/08)
|
||||
|
||||
> 软件团队快速模式交付（工程师 12/12 单测 + 103 回归通过）。**关键边界：验证的是代码逻辑，未做真实业务效果验证。**
|
||||
|
||||
**已验证（代码层，07-08 23:00 真实再跑）**：`backend/tests/test_avatar_service.py` **12 passed in 0.77s**（5 TestCleanAvatarUrl + 5 TestSyncEmployeeAvatar + 2 TestSessionServiceAvatar）。仅 2 个 deprecation warning（`datetime.utcnow()`），与 #75 主线无关。
|
||||
|
||||
**test_h5_oauth.py 6 失败归因**：抓 `test_callback_stores_token_in_redis:237 assert stored is not None` traceback 验证，根因是 `mock_redis`（fakeredis）跨 fixture 状态丢失 + redis 库 `setex` deprecated，**与 #75 avatar_service / sync_employee_avatar 无任何代码引用关系**——是历史遗留（与 QA 昨夜的"16 失败全在 test_h5_oauth.py"一致）。
|
||||
|
||||
**git 真实状态（07-08 23:00 摸底）**：
|
||||
- HEAD = `ba068d3`，**#75 15 个文件中 14 个与 HEAD 一致**（avatar_service.py / test_avatar_service.py / h5.py OAuth 段 / agents.py / auth_qrcode.py / qrcode_service.py / dev_auth.py / auth_wecom_sso.py / session_service.py + 6 个前端 .vue），已被其他 agent 在 400ce3d / 9bb080d / ba068d3 等 commit 整合。
|
||||
- 仅 1 个 `M` = `backend/app/api/h5.py` 是别的 agent 的 h5_send_message AI 异步化重构（`dep_ai_handler` → `app.tasks.h5_ai_task.process_h5_ai_reply`），与 #75 无关。
|
||||
|
||||
**为什么本地 / 预生产都看不到效果（5 因）**：
|
||||
1. **绑定登录动作**：#75 在每次登录时强制同步，已登录态不触发 → 改完代码不重登看不到变化。
|
||||
2. **mock / 测试账号**：本地 dev 走 `/api/h5/mock-login` 传固定 avatar；预生产测试账号企微通讯录可能未返回新头像。
|
||||
3. **企微通讯录缓存延迟**：企微通讯录 API 有缓存，换头像后不立即生效。
|
||||
4. **前端不主动重拉**：`employee.ts` 已登录不自动重拉 avatar，依赖登录时刷新。
|
||||
5. **token 登录态**：已持 token 进入不触发重新同步。
|
||||
|
||||
**任务状态**：
|
||||
- ✅ Task #3（提交代码）：**completed — 变体结论：#75 已被 HEAD 含括，无需独立提交**。夜班 agent 已把 #75 散落到多个 commit（400ce3d / 9bb080d / ba068d3 等）。
|
||||
- ⏳ Task #1（端到端真实效果验证）：pending — 待真实企微账号换头像→退出重登实测
|
||||
- ⏳ Task #2（手动刷新兜底按钮）：pending
|
||||
- ⏳ Task #4（补 SSO/JS-SDK employee upsert 头像）：pending
|
||||
|
||||
**下一步建议**：直接进 Task #1 端到端验真（最快闭环 #75 真实效果），或开 Task #2 兜底按钮（不依赖重登提升可用性）。等你通知启动。
|
||||
|
||||
## ✅ 最近搞定
|
||||
|
||||
### 2026-07-06 P1功能开发完成
|
||||
|
||||
- ✅ **P1-25 满意度评价**：会话结束后5星+表情评价，含文字反馈；后端API + H5弹窗 + 坐席端自动发送邀请 + 管理后台统计
|
||||
|
||||
### 2026-07-05 生产问题修复
|
||||
|
||||
- ✅ **坐席端消息列表 500 错误**：添加 `current_agent` 参数到 `list_messages` 函数
|
||||
- ✅ **坐席端消息发送失败**：安装缺失的 `wordfilter` 模块，补充文档
|
||||
- ✅ **文档补充**：更新 requirements.txt 和部署手册，新增 Python 依赖管理章节
|
||||
- 📝 详细记录（已并入 [标准故障排查手册](../../09-部署运维/00-标准故障排查手册.md)）
|
||||
|
||||
### 2026-07-07 管理后台登录修复 + 故障排查文档整合
|
||||
|
||||
- ✅ **管理后台登录"网络连接失败"根因修复**：Redis 密码 `R3d!s@2026#Secure` 含 `@`/`#`，`urlparse` 误判为 URL 分隔符 → 连到不存在的 host → 连接**无限挂起**（浏览器"网络连接失败"、curl 永远无返回）。修复：`backend/app/config.py` 加 `unquote()`+5s socket 超时；`docker-compose.yml` 后端 `REDIS_URL` 改 URL-encode（`R3d%21s%402026%23Secure`）；redis `--requirepass`/healthcheck 保持**明文**；重建 backend+redis。真实浏览器（headless Chromium）登录截图证明 sxn/admin 成功进入仪表盘。详见手册 [CASE-20260707-01](../../09-部署运维/00-标准故障排查手册.md)。
|
||||
- ✅ **故障排查文档整合 (v1.0)**：9 份散落文档合并为 `09-部署运维/00-标准故障排查手册.md` 单一入口（删 9 份、修 13 处断链、mkdocs 新增「故障排查」导航）；经验固化三层——项目 MEMORY「⚠️ 生产环境地雷」+「故障排查文档（单一入口）」、用户级 Skill `deploy-troubleshoot`、用户级 MEMORY「验证完成硬规则」。
|
||||
|
||||
### 2026-07-04 下午 (#90 身份认证修复 + 部署)
|
||||
|
||||
- ✅ **#90 Portal→H5 token传递修复**：路由守卫接收token后调用`fetchEmployeeInfo()`获取用户信息，修复token存在但用户信息未初始化的认证问题
|
||||
- ✅ **#90 生产部署成功**：H5 前端已构建并部署到生产服务器 (10.90.5.110)，Nginx 已重载
|
||||
|
||||
---
|
||||
|
||||
## 🔴 P0 必做(下一个 sprint)
|
||||
|
||||
| # | 任务 | 重要程度 | 说明 |
|
||||
|---|---|---|---|
|
||||
| #48 | v1.0 收窄 set_real_ip_from | 🔴 P0 | 现 allow 0.0.0.0/0 是临时方案,正式上线前必须改精确代理 IP |
|
||||
| #81 | 敏感词检测 + 语气优化 | 🔴 P0 | v0.7.1 开发内容，文本安全过滤 ⚠️验真:隐私检测Bug+仅警告 |
|
||||
| #90 | 身份认证问题修复 | ✅已完成 | ✅Portal→H5 token传递修复：路由守卫接收token后调用fetchEmployeeInfo()获取用户信息 |
|
||||
| #104 | 运行期结构化日志查看页（D） | 🔴 P0 | 决策4：落地「按级别/时间筛选 + 下载」页面与后端接口（`GET /api/admin/runtime-logs`），权限 admin；产品规格见 `docs/04-功能设计/系统日志与审计日志-产品与设计.md`；状态：待开发 |
|
||||
|
||||
---
|
||||
|
||||
## 🟡 P1 重要(看时间做)
|
||||
|
||||
| # | 任务 | 说明 |
|
||||
|---|---|---|
|
||||
| #73 | 修后端文件未真正覆盖 | `yes | cp -f` 路径,部署时偶尔没生效 |
|
||||
| #86 | 排查流程图零依赖部分 review + 文档化 | 把 Mermaid 流程图从代码里剥离成可读文档 |
|
||||
| #88 | 管理后台 RBAC 角色权限 | 管理后台细粒度角色权限(大功能,2-3 天) 🔴验真:admin_users鉴权422失效 |
|
||||
| #83 | 澄清"OTM 跟项目关系" | 已 2026-06-21 决策:走 TOTP+SMS 双引擎(MFA Phase 2 实施) |
|
||||
| 🆕 | v0.7.0 部署 + 35 项 E2E 验收 | 看 `docs/09-部署运维/deploy/10-一键部署操作包-v0.7.0.md` 6 步 + `docs/06-测试质量/testing-测试/E2E-CHECKLIST-v0.7.0.md` |
|
||||
| #100 | 消息推送策略优化与超时提醒 | ✅已完成：坐席回复仅推 H5，超时未回复发送企微提醒，10分钟后标记待关闭 |
|
||||
| 🆕 | 修 64 pre-existing 测试失败 | Role.data_scope 缺字段 / WecomService DI / test_message_experience 等 |
|
||||
| #75 | 头像同步功能完善 | 登录全路径强制同步 + 前端首字降级；代码已交付（12/12 单测 + 103 回归），**业务效果待端到端验真** | 🆕 等用户通知执行 |
|
||||
| #101 | 管理后台日志命名区分（决策1） | 侧边栏「系统日志」明确区分「配置变更历史(A)」与「安全审计日志(B)」，避免管理员混淆；状态：待开发 |
|
||||
| #102 | 配置变更 A+B 双写边界确认（决策2） | 维持 `PUT /api/admin/configs/{key}` 同时写 `config_change_logs` 与 `audit_logs` 的 `config_change` 事件，不收敛；代码已实现，本文档锁定边界；状态：设计中 |
|
||||
| #103 | 配置变更历史页筛选（决策3） | A 页补充「配置键/操作人/时间」筛选，后端 `GET /api/admin/system-logs` 增加对应过滤参数；状态：待开发 |
|
||||
|
||||
---
|
||||
|
||||
### 🎯 P1/P2 功能开发任务 (2026-07-06 新增)
|
||||
|
||||
**详细规格**: `docs/02-产品需求/功能详细规格说明书-P1P2功能.md`
|
||||
|
||||
#### 阶段2 - P1功能 (25人日)
|
||||
|
||||
| # | 功能 | 需求ID | 预估工时 | 状态 |
|
||||
|---|---|---|---|---|
|
||||
| 🆕 P1-24 | 摇人按钮 | 输入框左侧一键呼叫坐席 | 5人日 | ✅已完成 |
|
||||
| 🆕 P1-25 | 满意度评价 | 会话结束后5星+表情评价 | 5人日 | ✅已完成 |
|
||||
| 🆕 P1-26 | 排队系统 | 多会话时排队等待+显示位置 | 6人日 | ✅已验真(2026-07-07) |
|
||||
| 🆕 P1-27 | 快速回复 | 坐席常用语管理+搜索+分类 | 5人日 | ✅已完成 |
|
||||
| 🆕 P1-28 | 知识库(基础) | FAQ手动维护+RAGFlow检索 | 4人日 | ✅已完成 |
|
||||
|
||||
#### 阶段3 - P2功能-上半 (18人日)
|
||||
|
||||
| # | 功能 | 需求ID | 预估工时 | 状态 |
|
||||
|---|---|---|---|---|
|
||||
| 🆕 P2-09 | AI Wingman | AI建议回复+Ctrl+1/2/3快捷采纳 | 8人日 | ✅已验真(2026-07-07) |
|
||||
| 🆕 P2-10 | 会话标注 | 坐席标注AI回复准确性 | 5人日 | ✅已完成 |
|
||||
| 🆕 P2-11 | 自动摘要 | 会话结束后AI摘要 | 5人日 | ✅已完成 |
|
||||
|
||||
#### 阶段4 - P2功能-下半 (17人日)
|
||||
|
||||
| # | 功能 | 需求ID | 预估工时 | 状态 |
|
||||
|---|---|---|---|---|
|
||||
| 🆕 P2-12 | 数据看板 | 服务数据统计+可视化 | 10人日 | ✅已完成 |
|
||||
| 🆕 P2-13 | 知识库自动迭代 | AI分析高频+建议更新+图谱可视化+合并去重+会话闭环 | 7人日 | ✅全链路(2026-07-08: 49文件, 169/169 PASS) |
|
||||
|
||||
---
|
||||
|
||||
## 🟢 P2 / 等用户决策
|
||||
|
||||
| # | 任务 | 卡在哪 |
|
||||
|---|---|---|
|
||||
| **🆕 服务器更新?** | 把 v0.7.0 部署到生产(扫码+MFA+高危+4 项 P0) | **等你跑 `DEPLOY-QUICK-v0.7.0.md` 6 步** |
|
||||
| #31 | 推 docker 镜像到生产 registry | 等你确认要走哪条路(自建 Harbor / 阿里云 / 别的) |
|
||||
| #43 | 配置 HTTPS | 等域名备案完成 + 证书到位 |
|
||||
| #53 | 用户在企微验证 /itportal/ | 等你去企微点一点 |
|
||||
| 🆕 #23 | 清理 ~/Downloads/ patch1 包 | 部署观察期后拍板 |
|
||||
| 🆕 #24 | 清理生产 patch1 回滚备份 | 1 周观察期后拍板 |
|
||||
| 🆕 #48 | 收窄 set_real_ip_from 内网地址 | 部署后下一迭代(v1.0 前) |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 最近搞定(给你信心)
|
||||
|
||||
### 2026-07-04 上午 (文档优化专项)
|
||||
|
||||
- ✅ **文档全面扫描**:扫描 docs/ 目录下全部约 100 个文档，识别缺失/冲突/异常内容
|
||||
- ✅ **问题清单识别**:发现 6 个关键问题（用户手册空白、看板过期、KPI缺失等）
|
||||
- ✅ **行业最佳实践对比**:对比 ServiceNow/Zendesk/ITSM 行业基准
|
||||
- ✅ **Portal token 传递修复**:修复 backend/app/api/portal.py 身份认证问题
|
||||
|
||||
### 2026-06-22 凌晨 02:30+ (E2E §3.4 验证)
|
||||
|
||||
- ✅ **#46 nginx path-prefix bug 真修好**(之前 2026-06-22 凌晨已改配置,本次 admin token 验证三端点全部到 backend)
|
||||
- ✅ **#54 E2E §3.4 验证完成**:`/api/admin/high-risk/whitelist` → HTTP 200 + `{"code":2001,"message":"高危操作需要 OTP 二次验证"}`(完美:鉴权链通 + #19 中间件工作 + #20 MFA UI 流程就绪)
|
||||
- ✅ **#59 admin token 生成命令固化**:`backend/scripts/gen_admin_token.py` + `docker exec` 单行命令,可复现)
|
||||
- ✅ **新发现**:`/api/admin/mfa/users` 端点真不存在(backend 只定义 `/admin/mfa/reset/{id}`,无 list)→ 已加 v0.7.1 backlog
|
||||
- ✅ **新坑经验**:`http://wecom_it_nginx/api/...` 容器内 curl 会 301 → `https://`(nginx 强制 HTTPS 升级),必须用 `https://` + `-k`
|
||||
|
||||
### 2026-06-22 凌晨 (E2E 浏览器测试 - 用户反馈澄清)
|
||||
|
||||
- ⚠️ **#61 用户反馈 2 个浏览器 bug**:
|
||||
1. 二维码不显示 — **真 bug**: 后端 `auth_qrcode.py:91-96` 没返回 `qrcode_png_base64`,前端 `QrcodeLogin.vue:34-40` 永远拿不到数据(已查,根因清楚,待修)
|
||||
2. /itportal/ 直接出扫码页 — **不是 bug, 是设计**: v0.7.0 故意把 `/` redirect 到 `/qrcode-login`(`c389959 feat(portal)`),扫码成功后**按角色自动跳**(/itadmin/ /itagent/ /itdesk/),`PortalSelect` 保留为**多角色用户 fallback**。原 v0.5.x 是「先选角色再登录」2 步,v0.7.0 改成「先扫码自动识别」1 步。
|
||||
|
||||
### 2026-06-22 凌晨(自动跑批)
|
||||
|
||||
- ✅ **#23** `~/Downloads/patch1*` 已删(`backend-patch1-ws-fix.tar.gz` 21KB + `backend-v070-patch1.tar.gz` 63KB)
|
||||
- ✅ **#41** MkDocs 文档站后台跑起来(`http://127.0.0.1:8765/`,58 个 markdown,Material theme)
|
||||
- ✅ **#58** 38 → 13 backend pytest 失败修复(根因:`conftest` patch 路径错 + `h5_client` fixture 缺 WecomService mock)
|
||||
- ✅ **#49** `/api/ready` defer 到 v0.7.1,backlog 已存 `memory/v0.7.1-backlog-2026-06-22.md`
|
||||
- ✅ 4 个 agent 状态复核:#14/#17/#19/#20 全部合入 main(commit `bf872da` + `f564d0e`),worktree 分支已清
|
||||
- ✅ 集成测试再确认:4 套新测试 70 passed(扫码 13 + MFA 21 + 高危 28 + UUID 8)+ WS 8 passed + 4 xfail = 78 + 4 xfail(跟 merge 报告一致)
|
||||
|
||||
### 2026-06-21(凌晨 1 小时 sprint)
|
||||
|
||||
#### 🆕 v0.7.0 release 收尾(8 个 worktree → main)
|
||||
|
||||
- ✅ **#14 阶段 1.1**:后端 `auth_qrcode.py` 4 端点(create/poll/scan/confirm)
|
||||
- ✅ **#15 阶段 1.2**:前端 `Login.vue` + `QrcodeLogin.vue` 扫码 UI
|
||||
- ✅ **#16 阶段 1.3**:坐席/管理员域名路由分发(`/itagent/` `/itadmin/`)
|
||||
- ✅ **#17 阶段 2.1**:后端 MFA 服务 + pyotp 集成
|
||||
- ✅ **#18 阶段 2.2**:数据库 User MFA 字段 + Alembic migration 023
|
||||
- ✅ **#19 阶段 2.3**:高危操作路由白名单 + 中间件(5 类白名单)
|
||||
- ✅ **#20 阶段 2.4**:前端 MFA UI(绑定 + 验证 + 高危弹窗 + 管理表格)
|
||||
- ✅ **#21 集成测试 + E2E + 培训文档**:E2E-CHECKLIST 176 行 + DEPLOY-QUICK 252 行
|
||||
|
||||
#### 🔐 P0/P1 合规修复(#30)
|
||||
|
||||
- ✅ WS endpoint `missing argument 'request'`(签名 + 8 个回归测试)
|
||||
- ✅ messages.id VARCHAR → UUID(migration 025)
|
||||
- ✅ nginx access_log 脱敏脚本(删 Authorization/Cookie)
|
||||
- ✅ Gitea token 撤销流程已文档化(旧 token 已 revoke,新 token 已签发)
|
||||
|
||||
#### 🐛 测试修复(#32)
|
||||
|
||||
- ✅ wordfilter 1.0.6 API 适配(`Wordfilter()` 实例 + `addWords()` + `blacklisted()`)
|
||||
- ✅ SQLite ARRAY/JSONB 编译补丁(quiz.keywords / themes.palette)
|
||||
- ✅ conftest autouse 业务表清理(feedback 事务隔离)
|
||||
- ✅ h5_client 用 `127.0.0.1` 跳过企微 UA 检测
|
||||
- ✅ wecom mock 默认 name 不覆盖 body.name
|
||||
- ✅ 测试基线:570 ERROR → 470 passed, 4 xfailed, 64 failed
|
||||
|
||||
#### 📦 提交记录
|
||||
|
||||
- `8e748d1` docs: CHANGELOG.md 添加 v0.7.0 release 节
|
||||
- `1255e95` docs: v0.7.0 一键部署操作包
|
||||
- `c33abb6` fix(tests): h5_client UA 检测
|
||||
- `a9b97de` fix(tests): wordfilter API + SQLite 编译补丁 + 事务隔离
|
||||
- `e96fbb2` docs: v0.7.0 E2E 验收清单
|
||||
- `bf872da` feat(merge): 4 个 worktree 合入 main
|
||||
- **tag v0.7.0** 已打
|
||||
|
||||
### 历史(2026-06-16 选重点)
|
||||
|
||||
#### 🛠️ Dev 环境(本地链路全通)
|
||||
|
||||
- ✅ **本地 dev 4 端链路跑通**(#89-92):
|
||||
- backend (8000) + h5 (5174) + agent (5173) + admin (5175) + portal (5176) 全起
|
||||
- Mock 企微 OAuth 全通(`/api/dev/login` 给 token)
|
||||
- portal → H5 / 坐席 / 管理员 跳转正常
|
||||
- ✅ **修了 3 个 dev 启动坑**:
|
||||
1. `pydantic==2.7.5` → `2.7.4`(2.7.5 被 PyPI yank)
|
||||
2. docker-compose 加 `PYTHONPATH=/app`(alembic 1.13+ 不再默认 prepend cwd)
|
||||
3. dev 启动必须用 `--env-file .env.dev`(根 `.env` 冲突)
|
||||
|
||||
#### 🐛 Bug 修复
|
||||
|
||||
- ✅ **#93 修 portal dev 模式跳错端口**:`import.meta.env.DEV` 判断,生产走相对路径,dev 走完整 URL
|
||||
- ✅ **#97 修 require_role 装饰器**:`@wraps` 让 FastAPI 看到 `__wrapped__` 签名,Depends 未被解析 → `current_user` 实际是 Depends 对象。用 `inspect` 合并 signature + 手动设 `wrapper.__signature__` 修
|
||||
- ✅ **#99 dev 模式短路企微推送**:避免 `.env.dev` 用 `dev_corp_id_xxxxx` 调企微 API 返 `invalid corpid` 噪音
|
||||
|
||||
#### 🗃️ 数据库 migration(3 个)
|
||||
|
||||
- ✅ **#94 alembic 010**:加 `agents.otp_secret` + `agents.otp_enabled`
|
||||
- ✅ **#94 alembic 011**:加 `conversations.impact_scope` + `is_blocking` + `emotion_state`(用户坐席发消息 500 的真因)
|
||||
- ✅ **#96 alembic 012**:加 `conversations.dify_conversation_id` + `employees.it_level` + `it_level_source` + `notes`
|
||||
|
||||
#### 🛡️ 防错工具(留底用)
|
||||
|
||||
- ✅ **#95 dev-check-schema-drift.ps1**:对比 SQLAlchemy 模型 vs Postgres schema,漂移 exit 1。以后模型加字段忘 migration 一跑就发现(用 docker exec,免去 Python 依赖)
|
||||
|
||||
#### 📋 其他
|
||||
|
||||
- ✅ **#68 H5 空白页闪一下**:dev 模式验证不再白屏(生产未复测)
|
||||
|
||||
### 历史(选重点)
|
||||
|
||||
- ✅ v0.5.5:应急页 v0.5.4 + 移除 IT 设备升级 + admin 登录修复 + 内容审核架构
|
||||
- ✅ v0.5.3:重打后端部署包(5 IT + 2 HR + 1 行政 + 1 财务 = 9 条)
|
||||
- ✅ v0.5.6-dev-tooling 已 tag + push gitea(本地 dev 工具集)
|
||||
- ✅ messages.id varchar=UUID SQL bug 修了(#60)+ 10 个回归测试通过
|
||||
- ✅ nginx /api/admin/ 和 /itadmin/ 修复 403/allow(#57)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 怎么跑起来(3 步)
|
||||
|
||||
### 1. 后端 dev(已经在跑 ✅)
|
||||
|
||||
```powershell
|
||||
cd D:\资料\03-项目开发\wecom_it_smart_desk-claude
|
||||
docker compose -f docker-compose.dev.yml --env-file .env.dev up -d
|
||||
curl http://localhost:8000/api/dev/health
|
||||
```
|
||||
|
||||
### 2. 前端 dev(已经在跑 ✅)
|
||||
|
||||
```powershell
|
||||
# 一次性装 4 个前端依赖(已装好)
|
||||
.\scripts\dev-frontend-install.ps1
|
||||
|
||||
# 之后:一起起所有前端
|
||||
.\scripts\dev-frontend-start.ps1
|
||||
# 单独停:.\scripts\dev-frontend-start.ps1 -Stop
|
||||
```
|
||||
|
||||
### 3. 浏览器验证
|
||||
|
||||
- portal:http://localhost:5176/itportal/select
|
||||
- H5:http://localhost:5174/itdesk/
|
||||
- 坐席:http://localhost:5173/itagent/
|
||||
- 管理员:http://localhost:5175/itadmin/
|
||||
|
||||
---
|
||||
|
||||
## 📌 怎么读这份文档
|
||||
|
||||
**你是运维小白,不需要懂代码**。看这个文件就能 1 分钟懂:
|
||||
|
||||
1. **"现在在干嘛?"** → 看「正在做」表
|
||||
2. **"接下来要干嘛?"** → 看「P0 必做」表
|
||||
3. **"我需要做什么?"** → 看「正在做」表里的「你做什么」列
|
||||
4. **"今天有啥进展?"** → 看「最近搞定」
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Claude 怎么帮你
|
||||
|
||||
每次开新 session 我会:
|
||||
|
||||
1. **第一件事**:读这个文件 + TaskList,告诉你"上次到这了"
|
||||
2. **完成一件重要事**:更新这个文件(改状态、加完成项)
|
||||
3. **遇到阻塞**:写在「P2 / 等用户决策」里,等你回话
|
||||
4. **新需求进来**:跟当前 in_progress 比较,看是**接着做**还是**并行加**(参考你的"并行处理"反馈)
|
||||
|
||||
---
|
||||
|
||||
**这个文件就是你和 Claude 之间的"工作交接本"。有问题改这里就行。**
|
||||
@@ -0,0 +1,462 @@
|
||||
# 企微IT智能服务台 — 标准作业流程SOP
|
||||
|
||||
> **版本**: v1.5 | **日期**: 2026-07-10
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
1. [Gitea部署](#1-gitea部署)
|
||||
2. [Gitea备份恢复](#2-gitea备份恢复)
|
||||
3. [推送评审](#3-推送评审)
|
||||
4. [应急响应](#4-应急响应)
|
||||
5. [文档管理规范](#5-文档管理规范)
|
||||
6. [BugFix快捷路径](#6-bugfix-快捷路径v11-优化版)
|
||||
7. [部署运维工具箱管理](#7-部署运维工具箱管理)
|
||||
8. [任务路由表](#8-任务路由表)
|
||||
|
||||
---
|
||||
|
||||
## 1. Gitea部署
|
||||
|
||||
> **适用**: 新机器 / NAS 迁移 / Gitea重建
|
||||
> **耗时**: 30-45 分钟
|
||||
|
||||
### 1.1 前置检查
|
||||
|
||||
```bash
|
||||
# 1.1 NAS 可达
|
||||
ping 100.85.152.112
|
||||
|
||||
# 1.2 SSH 通
|
||||
ssh simon@100.85.152.112
|
||||
|
||||
# 1.3 Tailscale 状态
|
||||
sudo tailscale status
|
||||
|
||||
# 1.4 端口 8418 未占
|
||||
sudo lsof -i :8418
|
||||
```
|
||||
|
||||
### 1.2 装 Gitea 套件
|
||||
|
||||
1. DSM → 套件中心
|
||||
2. 搜 `Gitea` → 安装
|
||||
3. 装好跳 `http://100.85.152.112:8418/`
|
||||
|
||||
---
|
||||
|
||||
## 2. Gitea备份恢复
|
||||
|
||||
> **适用**: 数据丢失应急 / 误操作回滚 / 异地迁移
|
||||
> **耗时**: 5-15 分钟
|
||||
|
||||
### 2.1 备份策略
|
||||
|
||||
| 项 | 值 | 备注 |
|
||||
|---|---|---|
|
||||
| 频率 | 每天 3 点 | cron |
|
||||
| 保留 | 7 天 | 默认 |
|
||||
| 路径 | `/volume1/backups/gitea/` | NAS 本地 |
|
||||
| 工具 | `scripts/backup-gitea.sh` | 已写 |
|
||||
|
||||
### 2.2 手动备份(应急)
|
||||
|
||||
```bash
|
||||
ssh simon@100.85.152.112
|
||||
sudo bash /volume1/docker/wecom-it-desk/scripts/backup-gitea.sh
|
||||
```
|
||||
|
||||
### 2.3 恢复流程
|
||||
|
||||
```bash
|
||||
# 停止 Gitea
|
||||
sudo docker stop gitea
|
||||
|
||||
# 恢复数据
|
||||
sudo bash /volume1/docker/wecom-it-desk/scripts/restore-gitea.sh <backup_file>
|
||||
|
||||
# 启动 Gitea
|
||||
sudo docker start gitea
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 推送评审
|
||||
|
||||
> **适用**: 任何 commit 推 Gitea / PR 评审 / workbuddy 推送
|
||||
> **耗时**: 5-15 分钟
|
||||
|
||||
### 3.1 推送前自检(4 件套)
|
||||
|
||||
```bash
|
||||
cd D:\资料\03-项目开发\wecom_it_smart_desk
|
||||
|
||||
# 必跑
|
||||
bash scripts/pre-commit-check.sh --branch
|
||||
|
||||
# 严格模式(任何 warn 失败)
|
||||
bash scripts/pre-commit-check.sh --branch --strict
|
||||
```
|
||||
|
||||
**通过标准**:
|
||||
- ✅ PASS ≥ 检查项数
|
||||
- ⚠️ WARN 看是否影响评审
|
||||
- ❌ FAIL 必修
|
||||
|
||||
### 3.2 Commit 规范
|
||||
|
||||
格式: `<type>(<scope>): <subject>`
|
||||
|
||||
| type | 用途 |
|
||||
|------|------|
|
||||
| feat | 新功能 |
|
||||
| fix | Bug修复 |
|
||||
| docs | 文档 |
|
||||
| style | 格式 |
|
||||
| refactor | 重构 |
|
||||
| test | 测试 |
|
||||
| chore | 维护 |
|
||||
|
||||
### 3.3 PR 评审要求
|
||||
|
||||
- 所有 P0 鉴权修复必须走评审
|
||||
- 端点变更需鉴权依赖
|
||||
- 数据库 schema 变化必须 alembic 迁移
|
||||
|
||||
---
|
||||
|
||||
## 4. 应急响应
|
||||
|
||||
> **适用**: P0 漏洞 / 数据丢失 / 服务中断 / 安全事件
|
||||
> **响应时间**: 5 分钟响应 + 30 分钟止血 + 24 小时根因
|
||||
|
||||
### 4.1 事件分级
|
||||
|
||||
| 等级 | 场景 | 响应时间 |
|
||||
|------|------|----------|
|
||||
| 🔴 **P0 紧急** | P0 鉴权漏洞 + 数据泄露 + 服务全停 | 5 min |
|
||||
| 🟠 **P1 高** | P1 功能故障 + 单服务降级 | 30 min |
|
||||
| 🟡 **P2 中** | P2 性能 / UI 问题 | 4 h |
|
||||
| 🟢 **P3 低** | 体验优化 | 1 周 |
|
||||
|
||||
### 4.2 P0 应急流程(5 min 响应)
|
||||
|
||||
#### 4.2.1 立即止血
|
||||
|
||||
1. **服务降级**:
|
||||
- 关闭外网访问: `sudo iptables -A INPUT -p tcp --dport 8418 -j DROP`
|
||||
- 或: 套件中心停 Gitea
|
||||
- 或: Nginx `deny all;`
|
||||
|
||||
2. **停可疑服务**:
|
||||
- 停后端: `docker compose stop backend`
|
||||
- 停 WebSocket: `docker compose stop nginx`
|
||||
|
||||
3. **保留现场**:
|
||||
- 不删任何文件
|
||||
- 不改配置
|
||||
- 截图/录屏
|
||||
|
||||
#### 4.2.2 快速评估
|
||||
|
||||
| 问题 | 影响范围 | 可行方案 |
|
||||
|------|----------|----------|
|
||||
| | | |
|
||||
|
||||
#### 4.2.3 升级上报
|
||||
|
||||
- 5 分钟无法止血 → 升级到技术负责人
|
||||
- 30 分钟无法解决 → 升级到管理层
|
||||
|
||||
### 4.3 P1 应急流程(30 min)
|
||||
|
||||
1. **定位问题**: 30 分钟内确定故障范围
|
||||
2. **临时方案**: 提供绕过/降级方案
|
||||
3. **根本修复**: 24 小时内完成
|
||||
|
||||
---
|
||||
|
||||
## 5. 文档管理规范
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-04
|
||||
|
||||
### 5.1 文档目录结构
|
||||
|
||||
```
|
||||
docs/
|
||||
├── 01-项目总览/ # 项目介绍、部署手册
|
||||
├── 02-产品需求/ # PRD、需求文档
|
||||
├── 03-技术架构/ # 技术方案、设计文档
|
||||
├── 04-原型设计/ # UI原型
|
||||
├── 05-用户手册/ # 用户指南
|
||||
├── 06-测试质量/ # 测试报告、E2E
|
||||
├── 07-代码评审/ # Code Review
|
||||
├── 08-安全审计/ # 安全相关
|
||||
├── 09-部署运维/ # 部署、运维
|
||||
├── 10-项目管理/ # 任务、风险、SOP
|
||||
└── 11-历史归档/ # 历史版本
|
||||
```
|
||||
|
||||
### 5.2 文档命名规范
|
||||
|
||||
| 类型 | 命名格式 | 示例 |
|
||||
|------|----------|------|
|
||||
| 需求文档 | `需求-<功能名>.md` | `需求-应急降级页.md` |
|
||||
| 技术方案 | `技术方案-<模块名>.md` | `技术方案-消息功能.md` |
|
||||
| 测试报告 | `测试-<功能>-<日期>.md` | `测试-E2E-20260708.md` |
|
||||
| 部署手册 | `部署-<环境>-<日期>.md` | `部署-生产-20260704.md` |
|
||||
|
||||
### 5.3 文档维护
|
||||
|
||||
| 文档状态 | 维护要求 |
|
||||
|----------|----------|
|
||||
| 正式发布 | 仅通过 PR 评审更新 |
|
||||
| 更新中 | 标注"草稿"或"进行中" |
|
||||
| 已废弃 | 移至历史归档 |
|
||||
|
||||
### 5.4 版本管理
|
||||
|
||||
- 重大更新 → 新版本号
|
||||
- 小修复 → 保留版本号，更新日期
|
||||
- 版本历史记录在文档末尾
|
||||
|
||||
---
|
||||
|
||||
## 6. BugFix 快捷路径（v1.1 优化版）
|
||||
|
||||
> **适用**: 非紧急 Bug 修复，不涉及核心架构变更
|
||||
> **目标**: 快速响应 + 风险可控
|
||||
|
||||
### 6.1 处理流程（6 步）
|
||||
|
||||
| 步骤 | 操作 | 产出 | 备注 |
|
||||
|------|------|------|------|
|
||||
| 1 | 定位根因 | 问题定位文档 | 明确问题文件和行号 |
|
||||
| 2 | 影响评估 | 影响分析报告 | 正面/负面影响 + 风险等级 |
|
||||
| 3 | 方案确认 | 修复方案 | 需用户确认后执行 ⚠️ |
|
||||
| 4 | 部署执行 | 部署完成 | 上传 → cp → 重启 |
|
||||
| 5 | 功能验证 | 验证通过 | 实际触发功能测试 |
|
||||
| 6 | 状态更新 | 看板已更新 | 正在做 → 已完成 |
|
||||
|
||||
### 6.2 部署三问（部署前必确认）
|
||||
|
||||
| 问题 | 目的 |
|
||||
|------|------|
|
||||
| 会影响坐席和员工端使用吗？ | 评估业务影响 |
|
||||
| 会重启容器或服务吗？ | 评估可用性影响 |
|
||||
| 验证方式是什么？ | 明确如何验证修复效果 |
|
||||
|
||||
### 6.3 复盘要求
|
||||
|
||||
| 场景 | 是否需要复盘 | 理由 |
|
||||
|------|-------------|------|
|
||||
| **简单Bug**（单文件修改、<15分钟） | ❌ 不需要 | 流程简单，无学习价值 |
|
||||
| **复杂Bug**（多文件/多模块、涉及架构） | ✅ 建议 | 有技术沉淀价值 |
|
||||
| **重复出现的问题** | ✅ 必须 | 识别系统性风险 |
|
||||
| **有改进点** | ✅ 必须 | 沉淀到SOP，避免重复踩坑 |
|
||||
| **紧急止血**（P0/P1） | ❌ 事后补 | 先解决问题，24小时内补记录 |
|
||||
|
||||
### 6.4 验收条件
|
||||
|
||||
| 条件 | 说明 |
|
||||
|------|------|
|
||||
| 代码改动已确认 | 用户或自己确认修复方案 |
|
||||
| 部署后容器健康 | docker ps 显示 healthy |
|
||||
| 功能验证通过 | 按 §6.5 验证手段分层选择工具，前端类必须 agent-browser 截图 |
|
||||
| 看板状态已更新 | 正在做 → 已完成 |
|
||||
| 复盘报告（按需） | 复杂Bug/重复问题/有改进点时才需要 |
|
||||
|
||||
### 6.5 验证手段分层
|
||||
|
||||
验证不是"看看没报错就行"，必须按以下分层选择验证工具：
|
||||
|
||||
| 验证类型 | 工具 | 适用场景 | 证据形式 |
|
||||
|---------|------|---------|---------|
|
||||
| API/后端 | curl / HTTP 请求 | 接口返回值、状态码、响应体 | curl 输出 + HTTP 状态码 |
|
||||
| 前端渲染/登录/交互 | **agent-browser** 技能 | 页面渲染、表单填写、按钮点击、键盘输入、登录流程 | 真实浏览器截图 |
|
||||
| 前端诊断（F12 等效） | **agent-browser** Debug 命令 | 白屏、JS 不执行、API 异常、CSP 违规 | console 日志 + errors + network 请求 + 截图 |
|
||||
| 服务器状态 | jumpserver-ops | 容器状态、进程、日志 | docker ps / logs 输出 |
|
||||
|
||||
**验证硬规则**：
|
||||
- 前端/登录类修复 → **必须**用 agent-browser 截图取证，不能只用 curl
|
||||
- API/后端类修复 → curl 真实返回 + 必要时代码层拦截响应体
|
||||
- **禁止**只因 `docker logs` 无报错就断言修复
|
||||
|
||||
**前端诊断命令组合**（白屏/JS不执行/API异常/CSP违规场景必须采集）：
|
||||
|
||||
| 采集项 | agent-browser 命令 | F12 等效面板 | 必须采集 |
|
||||
|--------|-------------------|-------------|---------|
|
||||
| JS 错误 | `errors` | Console > Errors | ✅ |
|
||||
| 控制台日志 | `console` | Console | ✅ |
|
||||
| 网络请求 | `network requests` | Network | ✅ |
|
||||
| 页面截图 | `screenshot` | — | ✅ |
|
||||
| HAR 录制 | `network har start` → 操作 → `network har stop` | Network (完整请求/响应) | API 异常时 |
|
||||
| DOM 检查 | `eval "document.documentElement.outerHTML.substring(0, 500)"` | Elements | 疑似渲染异常时 |
|
||||
| Cookie/Storage | `cookies` / `storage local` | Application | 登录态问题时 |
|
||||
|
||||
**标准前端诊断流程**：
|
||||
```
|
||||
agent-browser open <url>
|
||||
agent-browser wait --load load
|
||||
agent-browser console --clear # 清除旧日志
|
||||
agent-browser errors # 采集 JS 错误
|
||||
agent-browser console # 采集控制台日志
|
||||
agent-browser network requests # 采集网络请求
|
||||
agent-browser screenshot # 截图取证
|
||||
agent-browser close
|
||||
```
|
||||
|
||||
> **注意**：以上命令在同一个浏览器 session 中执行，cookie 和状态自动保持。只需在最后执行一次 `close`。
|
||||
|
||||
---
|
||||
|
||||
## 7. 部署运维工具箱管理
|
||||
|
||||
> **适用**: 故障排查 / 部署运维过程中产生的可复用脚本、配置模板、调试工具
|
||||
> **工具箱位置**: `docs/09-部署运维/toolbox/`
|
||||
|
||||
### 7.1 工具沉淀流程
|
||||
|
||||
每次故障排查或部署完成后，按以下流程处理排查过程中产生的脚本和工具：
|
||||
|
||||
| 步骤 | 操作 | 说明 |
|
||||
|------|------|------|
|
||||
| 1 | **评估复用价值** | 该脚本/配置是否可能在后续排查中再次使用？ |
|
||||
| 2 | **归档** | 有复用价值 → 复制到 `toolbox/`（活跃工具）或 `toolbox/archive/`（历史脚本） |
|
||||
| 3 | **登记** | 在 `toolbox/README.md` 的工具索引表中添加条目（工具名、用途、使用方式） |
|
||||
| 4 | **清理根目录** | 删除项目根目录的临时文件（渲染输出、中间产物等），保持根目录整洁 |
|
||||
|
||||
### 7.2 归档分类标准
|
||||
|
||||
| 分类 | 存放位置 | 判定标准 | 示例 |
|
||||
|------|----------|----------|------|
|
||||
| **活跃工具** | `toolbox/` | 当前可复用、有通用价值的脚本或配置模板 | `fast_upload.py`、`nginx-access-control.conf` |
|
||||
| **历史脚本** | `toolbox/archive/` | 一次性修复脚本，仅供历史参考 | `fix_admin_role.py`、`patch-redis-url.py` |
|
||||
| **临时文件** | 直接删除 | 渲染输出、中间产物、调试快照 | `rendered_scan.html`、`tmp_*.html` |
|
||||
|
||||
### 7.3 README 维护要求
|
||||
|
||||
- 新增工具时**必须同步更新** `toolbox/README.md` 的工具索引表
|
||||
- 每个条目包含：工具名、用途、使用方式
|
||||
- archive/ 中的脚本按"修复场景 + 日期"分组登记
|
||||
- README 版本号随工具增减递增
|
||||
|
||||
### 7.4 故障排查手册更新触发条件
|
||||
|
||||
以下场景**必须同步更新** `00-标准故障排查手册.md`：
|
||||
|
||||
| 触发条件 | 更新内容 |
|
||||
|----------|----------|
|
||||
| 新案例（排查耗时 > 30 分钟） | §4 案例库新增 `CASE-YYYYMMDD-序号` 条目 |
|
||||
| 发现新的排查盲点 | §1 快速诊断决策树补充检查步骤 |
|
||||
| 新的错误现象 | §2 错误码速查表新增行 |
|
||||
| nginx 新陷阱 | §4 附：nginx 配错急救流程新增步骤 |
|
||||
| 响应头相关故障 | §1 Step 0 HTTP 响应头检查更新 |
|
||||
|
||||
### 7.5 工具箱与 SOP 的关系
|
||||
|
||||
```
|
||||
故障排查 → 产出脚本 → 评估复用价值 → 归档到 toolbox
|
||||
↓
|
||||
更新 README.md
|
||||
↓
|
||||
更新故障排查手册（按需）
|
||||
↓
|
||||
更新 SOP（仅涉及流程变更时）
|
||||
```
|
||||
|
||||
**原则**：工具箱是"弹药库"，故障排查手册是"作战手册"，SOP 是"军规"。三者各司其职，不混为一谈。
|
||||
|
||||
---
|
||||
|
||||
## 8. 任务路由表
|
||||
|
||||
> **适用**: 收到任何新请求时的统一入口
|
||||
> **执行者**: 交付总监（齐活林）使用 `task-intake` 技能执行
|
||||
> **原则**: 先路由再执行，先想清楚再动手
|
||||
|
||||
### 8.1 路由表
|
||||
|
||||
| 输入特征 | 路由到 | 产出物 | 执行方 | 参考 |
|
||||
|---------|--------|--------|--------|------|
|
||||
| 🏗️ 新功能（中大型，>10文件） | 软件团队标准 SOP | PRD+架构+代码+测试 | PM→Architect→Engineer→QA | 软件团队 SOP |
|
||||
| ⚡ 新功能（小型，≤10文件） | 软件团队快速模式 | 代码+测试 | Engineer→QA | 软件团队 SOP |
|
||||
| 🔧 Bug 修复 | SOP §6 BugFix | 修复+验证 | Engineer→QA | SOP §6 |
|
||||
| 🚀 部署运维 | 直接执行 | 部署完成+验证 | AI+jumpserver-ops | SOP §7 |
|
||||
| 🩺 故障排查 | deploy-troubleshoot | 定位+修复+案例 | 三步隔离法 | 故障排查手册 |
|
||||
| 🔴 应急事件（P0/P1） | SOP §4 应急响应 | 止血+根因 | 应急流程 | SOP §4 |
|
||||
| 🔍 代码调试 | diagnose 技能 | 根因+回归 | 六阶段调试 | diagnose SKILL.md |
|
||||
| 📊 技术评估/决策 | Plan 模式 | 评估报告 | AI+人 | — |
|
||||
| 📋 方案调研 | Plan 模式 | 方案文档 | AI+人 | — |
|
||||
| 📝 文档更新 | 直接执行 | 文档 | AI | SOP §5 |
|
||||
| 🛠️ 工具沉淀 | SOP §7 流程 | 工具归档+README | AI | SOP §7 |
|
||||
|
||||
### 8.2 路由优先级
|
||||
|
||||
当请求可能匹配多个分类时，按以下优先级路由：
|
||||
|
||||
1. **🔴 应急事件** > 一切（先止血再说）
|
||||
2. **🩺 故障排查** > **🔧 Bug 修复**（先隔离定位再修 Bug）
|
||||
3. **🏗️/⚡ 新功能** > **📊 技术评估**（明确要做的不需要评估）
|
||||
4. **📝 文档更新** / **🛠️ 工具沉淀** 通常作为其他任务的收尾步骤
|
||||
|
||||
### 8.3 task-intake 技能
|
||||
|
||||
任务路由通过 `task-intake` 技能执行（项目级 skill，位置：`.workbuddy/skills/task-intake/`）。
|
||||
|
||||
**执行流程**：
|
||||
1. **分类** — 判断请求属于哪类任务
|
||||
2. **结构化** — 输出四要素（是什么/要什么/怎么做/谁来做）
|
||||
3. **路由** — 对照 §8.1 路由表确定执行路径
|
||||
4. **移交** — 输出路由卡，交给对应执行方
|
||||
|
||||
**路由卡格式**：
|
||||
```
|
||||
是什么：[任务分类] + [一句话描述]
|
||||
要什么：[期望产出物] + [验收标准]
|
||||
怎么做：[执行路径] + [技能/工具]
|
||||
谁来做：[执行角色] + [协作方]
|
||||
路由到：[工作流名称]
|
||||
```
|
||||
|
||||
### 8.4 上下文隔离原则
|
||||
|
||||
路由卡**只传递结论，不传递思考过程**。下一阶段拿到的是干净的输入，不被前一阶段的假设和试错带偏。
|
||||
|
||||
| 正确 | 错误 |
|
||||
|------|------|
|
||||
| "故障定位在 Nginx 层，证据是 curl 返回 403" | "我一开始以为是后端，试了 A/B/C 都不对..." |
|
||||
| "根因是 CSP 缺少 unsafe-inline" | "我检查了 JS 加载、签名 URL、轮询逻辑..." |
|
||||
|
||||
### 8.5 与齐活林（交付总监）的集成
|
||||
|
||||
```
|
||||
请求到达 → 齐活林调用 task-intake → 输出路由卡
|
||||
↓
|
||||
├─ 标准SOP → TeamCreate → PM → Architect → Engineer → QA
|
||||
├─ 快速模式 → TeamCreate → Engineer → QA
|
||||
├─ BugFix → TeamCreate → Engineer → QA
|
||||
├─ 故障排查 → deploy-troubleshoot → jumpserver-ops(传输)
|
||||
├─ 应急响应 → SOP §4 流程
|
||||
├─ Plan模式 → 评估/方案文档
|
||||
└─ 直接执行 → 文档/工具沉淀
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 附录：相关文档
|
||||
|
||||
| 文档 | 位置 |
|
||||
|------|------|
|
||||
| 项目管理主文档 | `10-项目管理/任务说明书/` |
|
||||
| 风险跟踪表 | `10-项目管理/任务说明书/02-风险跟踪表.md` |
|
||||
| 技术架构 | `03-技术架构/` |
|
||||
| 部署手册 | `09-部署运维/` |
|
||||
| 标准故障排查手册 | `09-部署运维/00-标准故障排查手册.md` |
|
||||
| 部署运维工具箱 | `09-部署运维/toolbox/` |
|
||||
| task-intake 技能 | `.workbuddy/skills/task-intake/SKILL.md` |
|
||||
|
||||
---
|
||||
|
||||
> **本文档为标准作业流程综合文档，最后更新：2026-07-10（§6.5 验证手段分层新增前端诊断 F12 等效命令 + agent-browser SKILL.md 补全 Debug/Network 文档）**
|
||||
@@ -1,96 +0,0 @@
|
||||
# SOP-001: Gitea 部署标准作业流程
|
||||
|
||||
**适用**: 新机器 / NAS 迁移 / Gitea 重建
|
||||
**耗时**: 30-45 分钟
|
||||
**关联**: [[Gitea部署指南]] / [[ADR-001]]
|
||||
|
||||
---
|
||||
|
||||
## 1. 前置检查
|
||||
|
||||
```bash
|
||||
# 1.1 NAS 可达
|
||||
ping 100.85.152.112
|
||||
|
||||
# 1.2 SSH 通
|
||||
ssh simon@100.85.152.112
|
||||
|
||||
# 1.3 Tailscale 状态
|
||||
sudo tailscale status
|
||||
|
||||
# 1.4 端口 8418 未占
|
||||
sudo lsof -i :8418
|
||||
```
|
||||
|
||||
## 2. 装 Gitea 套件
|
||||
|
||||
1. DSM → 套件中心
|
||||
2. 搜 `Gitea` → 安装
|
||||
3. 装好跳 `http://100.85.152.112:8418/`
|
||||
|
||||
## 3. 初始化
|
||||
|
||||
1. 创管理员:
|
||||
- 用户名: `simon`
|
||||
- 邮箱: 你的
|
||||
- 密码: 强密码(≥16 位)
|
||||
2. 数据库: 选 **SQLite3**
|
||||
3. 站点名: `企微 IT 智能服务台 Git`
|
||||
4. 立即登录
|
||||
|
||||
## 4. 创仓 + token
|
||||
|
||||
1. 创仓 `wecom_it_smart_desk`(不勾 README 初始化)
|
||||
2. 创 simon access token(`simon-admin`)
|
||||
3. 创 workbuddy-claude user + token(`claude-push`)
|
||||
|
||||
## 5. 配 Tailscale Funnel
|
||||
|
||||
```bash
|
||||
sudo tailscale funnel --bg 8418
|
||||
# 验证
|
||||
curl -I https://ds923plus.tail58d872.ts.net/
|
||||
```
|
||||
|
||||
## 6. 配分支保护
|
||||
|
||||
见 [[ADR-001]] §5 + `scripts/branch-protection.sh`(待写)
|
||||
|
||||
## 7. 部署备份
|
||||
|
||||
```bash
|
||||
# 推备份脚本
|
||||
scp scripts/backup-gitea.sh simon@100.85.152.112:/volume1/docker/wecom-it-desk/scripts/
|
||||
|
||||
# 配 cron
|
||||
ssh simon@100.85.152.112
|
||||
sudo crontab -e
|
||||
# 加: 0 3 * * * /volume1/docker/wecom-it-desk/scripts/backup-gitea.sh
|
||||
```
|
||||
|
||||
## 8. 本地仓接入
|
||||
|
||||
```bash
|
||||
cd D:\资料\03-项目开发\wecom_it_smart_desk
|
||||
git remote add origin https://simon@ds923plus.tail58d872.ts.net/simon/wecom_it_smart_desk.git
|
||||
git push -u origin main # 弹窗输 token
|
||||
```
|
||||
|
||||
## 9. 验证清单
|
||||
|
||||
- [ ] Gitea Web UI 正常
|
||||
- [ ] Funnel 域名正常
|
||||
- [ ] 创仓 + token 完成
|
||||
- [ ] 分支保护已配
|
||||
- [ ] 备份 cron 已配
|
||||
- [ ] 本地 push 成功
|
||||
- [ ] workbuddy-claude user 已创 + token 已配
|
||||
|
||||
## 10. 出错回滚
|
||||
|
||||
| 现象 | 解决 |
|
||||
|---|---|
|
||||
| 8418 端口冲突 | Docker 版用 3000 端口 |
|
||||
| SQLite 写失败 | 检查 `/volume1/@appdata/gitea` 权限 |
|
||||
| Funnel 域名不通 | `sudo tailscale funnel --bg 8418` 重试 |
|
||||
| 推 Gitea 401 | 清 wincred,重输 token |
|
||||
@@ -1,97 +0,0 @@
|
||||
# SOP-002: Gitea 备份恢复标准作业流程
|
||||
|
||||
**适用**: 数据丢失应急 / 误操作回滚 / 异地迁移
|
||||
**耗时**: 5-15 分钟
|
||||
**关联**: [[Gitea部署指南]] §6/§7
|
||||
|
||||
---
|
||||
|
||||
## 1. 备份策略
|
||||
|
||||
| 项 | 值 | 备注 |
|
||||
|---|---|---|
|
||||
| 频率 | 每天 3 点 | cron |
|
||||
| 保留 | 7 天 | 默认 |
|
||||
| 路径 | `/volume1/backups/gitea/` | NAS 本地 |
|
||||
| 异地 | OSS / COS 推 | M-1 风险,待解决 |
|
||||
| 工具 | `scripts/backup-gitea.sh` | 已写 |
|
||||
|
||||
## 2. 手动备份(应急)
|
||||
|
||||
```bash
|
||||
ssh simon@100.85.152.112
|
||||
sudo bash /volume1/docker/wecom-it-desk/scripts/backup-gitea.sh
|
||||
```
|
||||
|
||||
输出:
|
||||
```
|
||||
[INFO] === Gitea 备份开始 ===
|
||||
[OK] 备份配置 app.ini
|
||||
[OK] SQLite 热备完成
|
||||
[OK] 仓库 tar 完成
|
||||
[INFO] === 备份完成 ===
|
||||
[OK] 最终备份: gitea-backup-20260615-030000.tar.gz
|
||||
```
|
||||
|
||||
## 3. 列出可用备份
|
||||
|
||||
```bash
|
||||
ls -lh /volume1/backups/gitea/
|
||||
# gitea-backup-20260614-180000.tar.gz 500M
|
||||
# gitea-backup-20260613-180000.tar.gz 495M
|
||||
# gitea-backup-20260612-180000.tar.gz 490M
|
||||
```
|
||||
|
||||
## 4. 恢复到 latest
|
||||
|
||||
```bash
|
||||
sudo bash /volume1/docker/wecom-it-desk/scripts/backup-gitea.sh --restore latest
|
||||
```
|
||||
|
||||
**会做**:
|
||||
1. 停 Gitea 套件
|
||||
2. 解压备份
|
||||
3. 覆盖 app.ini / SQLite / repos
|
||||
4. 启动 Gitea 套件
|
||||
|
||||
⚠️ 5 秒倒计时,Ctrl+C 取消
|
||||
|
||||
## 5. 恢复到指定时间
|
||||
|
||||
```bash
|
||||
# 看时间戳
|
||||
ls /volume1/backups/gitea/ | grep gitea-backup
|
||||
# gitea-backup-20260614-180000.tar.gz
|
||||
|
||||
# 恢复
|
||||
sudo bash /volume1/docker/wecom-it-desk/scripts/backup-gitea.sh --restore 20260614-180000
|
||||
```
|
||||
|
||||
## 6. 验证恢复
|
||||
|
||||
1. `http://100.85.152.112:8418/` → 登录 simon
|
||||
2. 选仓 → 看 commit 历史
|
||||
3. 验证仓裸仓库大小(`du -sh /volume1/@appdata/gitea/gitea/repos/`)
|
||||
4. 验证 LFS 数据
|
||||
|
||||
## 7. 异地推 OSS(待配)
|
||||
|
||||
```bash
|
||||
# NAS 装 rclone
|
||||
sudo apt install rclone # 或 synology 套件版
|
||||
|
||||
# 配 OSS
|
||||
rclone config
|
||||
# 选 aliyun OSS / 腾讯云 COS
|
||||
|
||||
# 加 cron
|
||||
0 4 * * * rclone copy /volume1/backups/gitea/ remote:gitea-backup/ --include "gitea-backup-*.tar.gz"
|
||||
```
|
||||
|
||||
## 8. 故障排查
|
||||
|
||||
| 现象 | 原因 | 解决 |
|
||||
|---|---|---|
|
||||
| 备份文件大小 0 | SQLite .backup 失败 | 改用文件复制模式(脚本已支持) |
|
||||
| 恢复后启动失败 | 数据不一致 | 试更早的备份 |
|
||||
| LFS 数据丢 | 备份脚本漏 LFS | 升级脚本(已修) |
|
||||
@@ -1,134 +0,0 @@
|
||||
# SOP-003: 推送评审标准作业流程
|
||||
|
||||
**适用**: 任何 commit 推 Gitea / PR 评审 / workbuddy 推送
|
||||
**耗时**: 5-15 分钟
|
||||
**关联**: [[CONTRIBUTING]] / [[scripts/pre-commit-check.sh]] / [[风险跟踪表]] 第九/十/十一节
|
||||
|
||||
---
|
||||
|
||||
## 1. 推送前自检(4 件套)
|
||||
|
||||
```bash
|
||||
cd D:\资料\03-项目开发\wecom_it_smart_desk
|
||||
|
||||
# 必跑
|
||||
bash scripts/pre-commit-check.sh --branch
|
||||
|
||||
# 严格模式(任何 warn 失败)
|
||||
bash scripts/pre-commit-check.sh --branch --strict
|
||||
```
|
||||
|
||||
**通过标准**:
|
||||
- ✅ PASS ≥ 检查项数
|
||||
- ⚠️ WARN 看是否影响评审
|
||||
- ❌ FAIL 必修
|
||||
|
||||
## 2. Commit 规范
|
||||
|
||||
格式: `<type>(<scope>): <subject>`
|
||||
|
||||
| type | 用途 |
|
||||
|---|---|
|
||||
| `feat` | 新功能 |
|
||||
| `fix` | Bug 修复 |
|
||||
| `refactor` | 重构(无新功能 / 无 Bug 修复) |
|
||||
| `docs` | 文档 |
|
||||
| `chore` | 构建/工具/依赖 |
|
||||
| `security` | 安全 |
|
||||
| `perf` | 性能 |
|
||||
| `test` | 测试 |
|
||||
|
||||
**subject**: 中文,祈使句,≤50 字
|
||||
**body**: 详细说明,每行 ≤72 字
|
||||
**footer**: 关联 Issue / workbuddy 任务
|
||||
|
||||
## 3. 推送流程
|
||||
|
||||
### 3.1 workbuddy 推送
|
||||
|
||||
1. workbuddy 客户端启动 → 读 `config.json` + `memory/`
|
||||
2. 接任务(W-1 / W-2 / ...)
|
||||
3. 写代码 → 本地 commit
|
||||
4. 推 `feature/xxx` 分支(不走 main,需 PR)
|
||||
5. 通知 Claude 评审
|
||||
|
||||
### 3.2 simon 推送(自己改)
|
||||
|
||||
1. 本地改 + commit
|
||||
2. 推 `feature/xxx` 分支
|
||||
3. Gitea Web 开 PR
|
||||
4. 自己 approve + merge(因 `block_admin_merge: false`)
|
||||
|
||||
## 4. 评审流程
|
||||
|
||||
### 4.1 Claude 评审(主)
|
||||
|
||||
1. 收到 workbuddy 推送通知
|
||||
2. Read 文件 + diff
|
||||
3. 检查 4 件套
|
||||
4. 写评审报告 `docs/评审报告/workbuddy-{date}-{topic}.md`
|
||||
5. 评级:
|
||||
- 🟢 通过 → 通知合并
|
||||
- 🟡 留 P1/P2 修 → 评审报告列遗留
|
||||
- 🔴 拒绝 → 评审报告列阻断
|
||||
|
||||
### 4.2 simon 合并
|
||||
|
||||
1. 评审通过 → Gitea Web 合并 PR
|
||||
2. 触发 Gitea Actions CI(待配)
|
||||
3. CI 绿 → 删 feature 分支
|
||||
|
||||
## 5. 评审失败处理
|
||||
|
||||
| 评级 | 处理 |
|
||||
|---|---|
|
||||
| 🟢 通过 | 合并 + 部署 |
|
||||
| 🟡 留 P1 | 合并 + 写遗留表 + workbuddy 下一轮修 |
|
||||
| 🔴 拒绝 | workbuddy 修 → 重新评审 |
|
||||
|
||||
## 6. 评审报告格式
|
||||
|
||||
`docs/评审报告/workbuddy-{YYYY-MM-DD}-{topic}.md`:
|
||||
|
||||
```markdown
|
||||
# 评审: {topic}
|
||||
|
||||
**推送日期**: {date}
|
||||
**评审日期**: {date}
|
||||
**评审人**: Claude
|
||||
**关联 PR**: feature/xxx → main
|
||||
**关联 commit**: N 个
|
||||
|
||||
## ⭐ 一句话结论
|
||||
...
|
||||
|
||||
## 📊 评审结果
|
||||
| # | 项 | 评级 | 备注 |
|
||||
|---|---|---|---|
|
||||
|
||||
## ✅ 已正确完成
|
||||
...
|
||||
|
||||
## 🟡 半成品(留 P2 优化)
|
||||
...
|
||||
|
||||
## ❌ 错误
|
||||
...
|
||||
|
||||
## 📁 变更清单(N commit)
|
||||
...
|
||||
|
||||
## 🔄 下一轮任务清单
|
||||
...
|
||||
|
||||
## 🔗 推 Gitea 状态
|
||||
- 远端分支: feature/xxx (HEAD = xxx)
|
||||
- 评审: ✅ 通过 / 🟡 通过 + 留 / 🔴 拒绝
|
||||
```
|
||||
|
||||
## 7. 不允许
|
||||
|
||||
- ❌ 跳过评审直推 main
|
||||
- ❌ 评审失败强行合并
|
||||
- ❌ 评审未消化前叠加新功能
|
||||
- ❌ 改评审报告原文(只加节)
|
||||
@@ -1,208 +0,0 @@
|
||||
# SOP-004: 应急响应标准作业流程
|
||||
|
||||
**适用**: P0 漏洞 / 数据丢失 / 服务中断 / 安全事件
|
||||
**响应时间**: 5 分钟响应 + 30 分钟止血 + 24 小时根因
|
||||
**关联**: [[风险跟踪表]] / [[CONTRIBUTING]] §紧急修复
|
||||
|
||||
---
|
||||
|
||||
## 1. 事件分级
|
||||
|
||||
| 等级 | 场景 | 响应时间 |
|
||||
|---|---|---|
|
||||
| 🔴 **P0 紧急** | P0 鉴权漏洞 + 数据泄露 + 服务全停 | 5 min |
|
||||
| 🟠 **P1 高** | P1 功能故障 + 单服务降级 | 30 min |
|
||||
| 🟡 **P2 中** | P2 性能 / UI 问题 | 4 h |
|
||||
| 🟢 **P3 低** | 体验优化 | 1 周 |
|
||||
|
||||
## 2. P0 应急流程(5 min 响应)
|
||||
|
||||
### 2.1 立即止血
|
||||
|
||||
1. **服务降级**:
|
||||
- 关闭外网访问:`sudo iptables -A INPUT -p tcp --dport 8418 -j DROP`
|
||||
- 或:套件中心停 Gitea
|
||||
- 或:Nginx `deny all;`
|
||||
2. **停可疑服务**:
|
||||
- 停后端:`docker compose stop backend`
|
||||
- 停 WebSocket:`docker compose stop nginx`(整体停)
|
||||
3. **保留现场**:
|
||||
- 不删任何文件
|
||||
- 复制 log 到 `/tmp/incident-{timestamp}/`
|
||||
- 截图
|
||||
|
||||
### 2.2 通知
|
||||
|
||||
1. 微信 / 电话通知项目负责人 宋献
|
||||
2. 邮件群发:`wecom-it-desk-incident@servyou-it.com`
|
||||
3. 建应急群
|
||||
|
||||
### 2.3 临时回滚
|
||||
|
||||
```bash
|
||||
# 1. 找上一个稳定版本
|
||||
git tag -l # 看 release tag
|
||||
git log --oneline -20 # 看 commit 历史
|
||||
|
||||
# 2. 回滚到上一个 commit
|
||||
git revert HEAD # 生成新 commit 撤销
|
||||
# 或
|
||||
git reset --hard HEAD~1 # 强回滚(慎用)
|
||||
|
||||
# 3. 强推(临时,需 admin 权限)
|
||||
git push -f origin main
|
||||
```
|
||||
|
||||
## 3. 根因分析(24h 内)
|
||||
|
||||
### 3.1 收集证据
|
||||
|
||||
```bash
|
||||
# 后端日志
|
||||
docker logs backend --tail 1000 > /tmp/incident/backend.log
|
||||
|
||||
# nginx 错误日志
|
||||
sudo cat /var/log/nginx/error.log > /tmp/incident/nginx-error.log
|
||||
|
||||
# Gitea 日志
|
||||
sudo synopkg log Gitea > /tmp/incident/gitea.log
|
||||
```
|
||||
|
||||
### 3.2 5 Why 分析
|
||||
|
||||
```markdown
|
||||
# 5 Why 分析
|
||||
|
||||
**事件**: 坐席登录无鉴权
|
||||
**Why 1**: agents.py login() 函数没用 Depends(get_current_*)
|
||||
**Why 2**: workbuddy 加新端点时没跑 pre-commit-check
|
||||
**Why 3**: pre-commit-check 不在 git commit hook 里
|
||||
**Why 4**: 没用 pre-commit 框架(只是脚本)
|
||||
**Why 5**: 流程规范没强制(评审可跳)
|
||||
|
||||
**根因**: 流程规范未自动化
|
||||
**对策**: 加 pre-commit + Gitea Actions 强制
|
||||
```
|
||||
|
||||
### 3.3 写事故报告
|
||||
|
||||
`docs/事故报告/incident-{date}-{topic}.md`:
|
||||
|
||||
```markdown
|
||||
# 事故报告: {topic}
|
||||
|
||||
**日期**: {date}
|
||||
**等级**: 🔴 P0
|
||||
**响应人**: {name}
|
||||
**持续**: X 分钟
|
||||
|
||||
## 1. 时序
|
||||
| 时刻 | 事件 |
|
||||
|---|---|
|
||||
|
||||
## 2. 影响范围
|
||||
- 用户: X 人受影响
|
||||
- 数据: 是否泄露
|
||||
- 服务: 停 X 分钟
|
||||
|
||||
## 3. 5 Why 根因
|
||||
...
|
||||
|
||||
## 4. 修复 commit
|
||||
- {commit-hash}
|
||||
- {commit-message}
|
||||
|
||||
## 5. 防止再发
|
||||
- [ ] 加 pre-commit hook
|
||||
- [ ] 加 Gitea Actions 强制
|
||||
- [ ] 更新风险跟踪表
|
||||
- [ ] 评审 SOP 更新
|
||||
```
|
||||
|
||||
## 4. P1 应急流程(30 min 响应)
|
||||
|
||||
### 4.1 评估
|
||||
|
||||
- 是否影响生产用户?
|
||||
- 是否有降级方案?
|
||||
|
||||
### 4.2 止血
|
||||
|
||||
- 单服务降级(关问题服务,其它继续)
|
||||
- 临时禁用相关端点(nginx `location /api/v1/xxx { return 503; }`)
|
||||
|
||||
### 4.3 修复
|
||||
|
||||
- hotfix 分支(从 main 拉)
|
||||
- PR + 评审 + 合并 + 部署
|
||||
|
||||
## 5. 数据丢失应急
|
||||
|
||||
### 5.1 Gitea 数据丢失
|
||||
|
||||
1. **别再操作** Gitea(避免覆盖)
|
||||
2. 跑 `scripts/backup-gitea.sh --restore latest`
|
||||
3. 验证:仓 commit 数 / token 列表
|
||||
4. 不行:试更早备份
|
||||
|
||||
### 5.2 生产数据库丢失
|
||||
|
||||
1. 立即停所有服务(避免写入)
|
||||
2. 看 PostgreSQL 数据目录:`/var/lib/postgresql/data`
|
||||
3. 走 PITR(Point In Time Recovery)
|
||||
4. 启用只读模式 + 通知用户
|
||||
|
||||
## 6. 安全事件
|
||||
|
||||
### 6.1 Token 泄露
|
||||
|
||||
1. **立即撤销** token:
|
||||
```bash
|
||||
curl -X DELETE -H "Authorization: token $ADMIN_TOKEN" \
|
||||
"http://100.85.152.112:8418/api/v1/users/{username}/tokens"
|
||||
```
|
||||
2. 清 wincred 缓存
|
||||
3. 创新 token + 配新凭据
|
||||
4. 改所有引用旧 token 的脚本/配置
|
||||
5. 评审日志:谁访问过 / 推过什么
|
||||
|
||||
### 6.2 入侵检测
|
||||
|
||||
1. 看 `auth.log` / `nginx-access.log` / `backend.log`
|
||||
2. 找异常 IP / 时间 / 路径
|
||||
3. 封 IP:`sudo iptables -A INPUT -s {ip} -j DROP`
|
||||
4. 改所有密码 / 凭据
|
||||
5. 走事件调查流程
|
||||
|
||||
## 7. 通讯模板
|
||||
|
||||
### 7.1 启动应急
|
||||
|
||||
```
|
||||
【应急启动】{事件简述}
|
||||
等级: 🔴 P0
|
||||
影响: {用户/数据/服务}
|
||||
已开始止血:{动作}
|
||||
请相关人:{人名} 立即响应
|
||||
群: {微信群名}
|
||||
```
|
||||
|
||||
### 7.2 解决通知
|
||||
|
||||
```
|
||||
【已解决】{事件简述}
|
||||
持续: X 分钟
|
||||
修复: {commit-hash}
|
||||
根因: {5 Why 结论}
|
||||
防止再发: {动作}
|
||||
报告: docs/事故报告/{file}.md
|
||||
```
|
||||
|
||||
## 8. 联系
|
||||
|
||||
| 角色 | 联系人 |
|
||||
|---|---|
|
||||
| 项目负责人 | 宋献(企业微信 / 手机) |
|
||||
| 运维 | IT 支持组 |
|
||||
| Gitea | 群晖技术支持（部署在公司内网服务器） |
|
||||
| Tailscale | tailscale.com/support |
|
||||
@@ -1,343 +0,0 @@
|
||||
# 项目管理文档管理规范
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-04 | **状态**: 正式发布
|
||||
|
||||
---
|
||||
|
||||
## 1. 目的与适用范围
|
||||
|
||||
### 1.1 目的
|
||||
|
||||
规范 IT 智能服务台项目的文档管理流程，确保文档的准确性、完整性和可追溯性，提高团队协作效率。
|
||||
|
||||
### 1.2 适用范围
|
||||
|
||||
本规范适用于 IT 智能服务台项目开发过程中的所有文档，包括但不限于：
|
||||
- 产品需求文档（PRD）
|
||||
- 技术架构文档
|
||||
- 原型设计文档
|
||||
- 代码评审报告
|
||||
- 测试文档
|
||||
- 部署运维文档
|
||||
- 项目管理文档（任务说明书、风险跟踪表等）
|
||||
|
||||
---
|
||||
|
||||
## 2. 文档目录结构
|
||||
|
||||
### 2.1 顶级目录划分
|
||||
|
||||
```
|
||||
docs/
|
||||
├── 01-项目总览/ ← 核心文档（必读）
|
||||
├── 02-产品需求/ ← PRD、功能需求
|
||||
├── 03-技术架构/ ← 架构设计、ADR、图表
|
||||
├── 04-原型设计/ ← UI/UX原型
|
||||
├── 05-用户手册/ ← 用户指南
|
||||
├── 06-测试质量/ ← 测试文档
|
||||
├── 07-代码评审/ ← Code Review
|
||||
├── 08-安全审计/ ← 安全、集成分析
|
||||
├── 09-部署运维/ ← 部署、运维、故障排查
|
||||
├── 10-项目管理/ ← SOP、项目管理
|
||||
└── 11-历史归档/ ← 历史归档
|
||||
```
|
||||
|
||||
### 2.2 子目录命名规范
|
||||
|
||||
| 目录类型 | 命名规则 | 示例 |
|
||||
|----------|----------|------|
|
||||
| 功能模块 | `XX-功能模块名/` | `02-技术方案/` |
|
||||
| 文档类型 | `XX-文档类型-类型名/` | `01-ADRs-架构决策/` |
|
||||
| 归档目录 | `archive/` | `prototypes-原型图/archive/` |
|
||||
|
||||
---
|
||||
|
||||
## 3. 文档命名规范
|
||||
|
||||
### 3.1 核心文档
|
||||
|
||||
```
|
||||
序号-文档名-YYYYMMDD.扩展名
|
||||
```
|
||||
|
||||
**规则**：
|
||||
- 序号：01、02、03...（两位数字）
|
||||
- 文档名：中文描述，不超过30字
|
||||
- 日期：创建或重大更新日期（8位数字）
|
||||
|
||||
**示例**：
|
||||
- `01-项目总览与部署手册-20260704.md`
|
||||
- `02-产品需求文档PRD-v1.2-20260704.md`
|
||||
|
||||
### 3.2 普通文档
|
||||
|
||||
```
|
||||
文档名-YYYYMMDD.扩展名
|
||||
```
|
||||
|
||||
**示例**：
|
||||
- `v0.7.1-release-notes-20260623.md`
|
||||
|
||||
### 3.3 归档文档
|
||||
|
||||
```
|
||||
原文档名-archived-YYYYMMDD.扩展名
|
||||
```
|
||||
|
||||
**示例**：
|
||||
- `PRD-v53-incremental-archived-20260704.md`
|
||||
|
||||
### 3.4 ADR 文档
|
||||
|
||||
```
|
||||
ADR-XXX-标题.扩展名
|
||||
```
|
||||
|
||||
**示例**：
|
||||
- `ADR-001-Gitea自托管-Funnel暴露.md`
|
||||
|
||||
### 3.5 SOP 文档
|
||||
|
||||
```
|
||||
SOP-序号-流程名.扩展名
|
||||
```
|
||||
|
||||
**示例**：
|
||||
- `SOP-01-Gitea部署.md`
|
||||
|
||||
### 3.6 禁止事项
|
||||
|
||||
- ❌ 禁止使用特殊字符（`/ \ : * ? " < > |`）
|
||||
- ❌ 禁止使用空格（用 `-` 或 `_` 代替）
|
||||
- ❌ 禁止使用 emoji
|
||||
- ❌ 禁止纯数字命名
|
||||
|
||||
---
|
||||
|
||||
## 4. 文档版本管理
|
||||
|
||||
### 4.1 版本号规则
|
||||
|
||||
采用 `主版本.次版本.修订号` 格式：
|
||||
- **主版本**：重大架构变更或功能迭代
|
||||
- **次版本**：功能新增或较大调整
|
||||
- **修订号**：文档修正、错别字修改
|
||||
|
||||
**示例**：v1.0 → v1.1 → v2.0
|
||||
|
||||
### 4.2 版本记录
|
||||
|
||||
每个文档头部必须包含版本信息：
|
||||
|
||||
```markdown
|
||||
> **版本**: v1.0 | **日期**: 2026-07-04 | **作者**: xxx | **状态**: 草稿/评审中/正式发布
|
||||
```
|
||||
|
||||
### 4.3 变更记录
|
||||
|
||||
重大文档必须包含变更记录：
|
||||
|
||||
```markdown
|
||||
## 📈 版本历史
|
||||
|
||||
| 版本 | 日期 | 变更内容 | 变更人 |
|
||||
|------|------|----------|--------|
|
||||
| v1.0 | 2026-07-04 | 初始版本 | xxx |
|
||||
| v1.1 | 2026-07-05 | 新增xxx功能 | xxx |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 任务说明书要求
|
||||
|
||||
### 5.1 必含字段
|
||||
|
||||
根据任务类型，必须包含以下字段：
|
||||
|
||||
| 字段 | 说明 | 必填 |
|
||||
|------|------|------|
|
||||
| 任务名称 | 任务简短描述 | ✅ |
|
||||
| 任务ID | 唯一标识（如 #90） | ✅ |
|
||||
| 优先级 | P0/P1/P2 | ✅ |
|
||||
| 状态 | 待开始/进行中/已完成/阻塞/延后 | ✅ |
|
||||
| 输入项来源 | 产品需求/技术架构/原型设计/项目看板 | ✅ |
|
||||
| 输出成果要求 | 交付物清单 | ✅ |
|
||||
| 验证方式 | 测试方法 | ✅ |
|
||||
| 完成标准 | 验收条件 | ✅ |
|
||||
|
||||
### 5.2 输入项来源规范
|
||||
|
||||
每项任务必须明确输入来源：
|
||||
|
||||
```markdown
|
||||
### 📥 输入项来源
|
||||
|
||||
#### 产品需求
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `02-产品需求/02-产品需求文档PRD-v1.2-20260704.md` | §4.5 | 登录流程要求 |
|
||||
|
||||
#### 技术架构
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `03-技术架构/02-技术方案/技术方案-消息功能详细设计.md` | - | 技术实现方案 |
|
||||
|
||||
#### 原型设计
|
||||
| 来源文档 | 页面 | 说明 |
|
||||
|----------|------|------|
|
||||
| `04-原型设计/prototypes-原型图/admin-dashboard-v1.html` | 登录页 | 登录UI要求 |
|
||||
```
|
||||
|
||||
### 5.3 输出成果要求
|
||||
|
||||
明确每项任务的交付物：
|
||||
|
||||
```markdown
|
||||
### 📤 输出成果要求
|
||||
|
||||
| # | 交付物 | 类型 | 说明 |
|
||||
|---|--------|------|------|
|
||||
| 1 | 后端登录API | 代码 | `/api/auth/login` 接口 |
|
||||
| 2 | 登录页面 | 代码 | Vue组件 |
|
||||
| 3 | API文档 | 文档 | 更新OpenAPI |
|
||||
```
|
||||
|
||||
### 5.4 验证方式
|
||||
|
||||
```markdown
|
||||
### 🔧 验证方式
|
||||
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 功能正常运行 | 手动测试 | 登录成功 |
|
||||
| 权限控制 | 越权测试 | 无法访问未授权页面 |
|
||||
| 响应时间 | 性能测试 | < 500ms |
|
||||
```
|
||||
|
||||
### 5.5 完成标准
|
||||
|
||||
```markdown
|
||||
### ✅ 完成标准
|
||||
|
||||
- [ ] 代码合入主干分支
|
||||
- [ ] 所有测试通过
|
||||
- [ ] 功能测试通过
|
||||
- [ ] 安全测试通过
|
||||
- [ ] 文档已更新
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 文档审批流程
|
||||
|
||||
### 6.1 审批角色
|
||||
|
||||
| 文档类型 | 审批人 |
|
||||
|----------|--------|
|
||||
| 产品需求（PRD） | 产品经理 + 技术负责人 |
|
||||
| 技术架构文档 | 技术负责人 |
|
||||
| 代码评审报告 | 评审参与者 |
|
||||
| 部署文档 | 运维负责人 |
|
||||
|
||||
### 6.2 审批状态
|
||||
|
||||
| 状态 | 说明 |
|
||||
|------|------|
|
||||
| 草稿 | 初始编写 |
|
||||
| 评审中 | 等待审批 |
|
||||
| 修订中 | 评审反馈需修改 |
|
||||
| 正式发布 | 审批通过 |
|
||||
| 已废弃 | 被新版本替代 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 文档归档要求
|
||||
|
||||
### 7.1 归档条件
|
||||
|
||||
满足以下任一条件应归档：
|
||||
- 文档被新版本替代
|
||||
- 对应功能已完成并稳定运行超过3个月
|
||||
- 文档内容已整合到其他文档
|
||||
|
||||
### 7.2 归档命名
|
||||
|
||||
归档文档添加 `-archived-YYYYMMDD` 后缀：
|
||||
|
||||
```bash
|
||||
# 归档前
|
||||
PRD-v53-incremental.md
|
||||
|
||||
# 归档后
|
||||
PRD-v53-incremental-archived-20260704.md
|
||||
```
|
||||
|
||||
### 7.3 归档位置
|
||||
|
||||
- 历史归档文档统一放置在 `11-历史归档/` 目录
|
||||
- 按时间顺序保留，最新版本在主目录
|
||||
|
||||
---
|
||||
|
||||
## 8. 文档索引维护
|
||||
|
||||
### 8.1 主索引文档
|
||||
|
||||
`01-项目总览/00-索引-YYYYMMDD.md` 为项目主索引，需保持更新。
|
||||
|
||||
### 8.2 更新规则
|
||||
|
||||
| 操作 | 同步要求 |
|
||||
|------|----------|
|
||||
| 新增文档 | 添加到对应目录 + 更新索引 |
|
||||
| 删除文档 | 从索引移除 |
|
||||
| 移动文档 | 更新索引路径 |
|
||||
| 重大变更 | 同步更新 CHANGELOG |
|
||||
|
||||
---
|
||||
|
||||
## 9. 文档质量检查清单
|
||||
|
||||
### 9.1 基本检查
|
||||
|
||||
- [ ] 文档命名符合规范
|
||||
- [ ] 头部包含版本信息
|
||||
- [ ] 目录结构清晰
|
||||
- [ ] 无错别字
|
||||
|
||||
### 9.2 内容检查
|
||||
|
||||
- [ ] 需求来源明确
|
||||
- [ ] 技术方案合理
|
||||
- [ ] 验证方式可行
|
||||
- [ ] 完成标准可衡量
|
||||
|
||||
### 9.3 关联检查
|
||||
|
||||
- [ ] 相关文档链接正确
|
||||
- [ ] 版本历史完整
|
||||
- [ ] 索引已更新
|
||||
|
||||
---
|
||||
|
||||
## 10. 附则
|
||||
|
||||
### 10.1 生效日期
|
||||
|
||||
本规范自 2026-07-04 起正式执行。
|
||||
|
||||
### 10.2 解释权
|
||||
|
||||
本规范解释权归项目负责人所有。
|
||||
|
||||
### 10.3 修订周期
|
||||
|
||||
每季度评审一次，根据实际执行情况进行修订。
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 版本 | 日期 | 变更内容 | 变更人 |
|
||||
|------|------|----------|--------|
|
||||
| v1.0 | 2026-07-04 | 初始版本 | Claude |
|
||||
@@ -0,0 +1,265 @@
|
||||
# 企微IT智能服务台 — 项目管理主文档
|
||||
|
||||
> **版本**: v2.4 | **日期**: 2026-07-10 | **维护人**: 助理
|
||||
|
||||
---
|
||||
|
||||
## 一、项目状态总览
|
||||
|
||||
> **一句话总览**：v0.7.1 已上线运行，生产稳定。知识库迭代 v0.7.2 全链路交付完成。
|
||||
|
||||
### 已完成 (v0.7.1)
|
||||
- ✅ 企微入口 SSO
|
||||
- ✅ 管理后台 RBAC（6处装饰器修复）
|
||||
- ✅ 敏感词检测（隐私正则修复）
|
||||
- ✅ 扫码登录优化
|
||||
- ✅ 文档优化专项
|
||||
|
||||
### v0.7.2 知识库迭代（全部交付）
|
||||
- ✅ AI 辅助功能增强
|
||||
- ✅ 排查流程优化
|
||||
- ✅ 知识库迭代
|
||||
|
||||
### 版本迭代
|
||||
|
||||
| 版本 | 状态 | 主要内容 | 日期 |
|
||||
|------|------|----------|------|
|
||||
| v0.7.0 | ✅ 已上线 | 企微SSO、MFA、RBAC | 2026-06 |
|
||||
| v0.7.1 | ✅ 已上线 | 敏感词检测、token修复、扫码登录优化 | 2026-07-04 |
|
||||
| v0.7.2 | ✅ 已完成 | backlog候选（AI辅助、排查流程，知识库迭代） | 2026-07+ |
|
||||
|
||||
---
|
||||
|
||||
## 二、任务管理文档体系
|
||||
|
||||
本项目采用四级任务管理文档体系：
|
||||
|
||||
| 级别 | 文档 | 用途 |
|
||||
|------|------|------|
|
||||
| L1 | **项目状态看板** | 驾驶舱仪表盘，当前正在做+待办 |
|
||||
| L2 | **项目任务状态报告** | 历史全量任务清单 |
|
||||
| L3 | **需求候选池** | 未来版本候选功能 |
|
||||
| L4 | **PRD需求池** | 完整需求来源 |
|
||||
|
||||
---
|
||||
|
||||
## 三、快速导航
|
||||
|
||||
### 🔴 现在做什么？
|
||||
查看 **项目状态看板** 的「正在做」和「P0必做」区
|
||||
|
||||
### 📜 历史全部任务？
|
||||
查看 **项目任务状态报告**
|
||||
|
||||
### 📋 未来计划？
|
||||
查看 **需求候选池** (v0.7.2+)
|
||||
|
||||
### 📖 需求来源？
|
||||
查看 **PRD需求文档**
|
||||
|
||||
### 📅 每日工作记录？
|
||||
查看 `.workbuddy/memory/` 目录
|
||||
|
||||
---
|
||||
|
||||
## 四、项目状态看板
|
||||
|
||||
### 正在做 (in_progress)
|
||||
|
||||
| # | 任务 | 说明 |
|
||||
|---|---|---|
|
||||
| #91 | 忘记密码-企微扫码重置 | 坐席忘记密码时通过企微扫码验证后重置 |
|
||||
| #107 | 后端部署卷挂载改造 | 方案C：镜像烘焙→代码卷挂载，消除两份代码不同步根因 |
|
||||
|
||||
### ✅ 已完成
|
||||
|
||||
| # | 任务 | 说明 | 完成日期 |
|
||||
|---|---|---|---|
|
||||
| #111 | 坐席端消息头像不显示Bug | 🐛 后端消息接口未返回sender_avatar → Schema添加字段 + API填充员工/AI头像 + 前端显示 | 2026-07-10 |
|
||||
| #112 | 坐席端消息布局调整 | ✨ 头像和名字位置互换（头像在前、名字在后） | 2026-07-10 |
|
||||
| #113 | 审批类型扩展与卡片URL直跳 | ✨ 审批类型 5→12种/18流程，后端静态模板+关键词扩展，前端卡片12类17选项URL直跳，Dify v2 System Prompt覆盖全部12类 | 2026-07-10 |
|
||||
| #114 | 审批卡片同窗口导航改造 | ✨ window.open(\_blank) → window.location.href，企微原生返回按钮，COEP/CSP安全头分析 | 2026-07-10 |
|
||||
| #115 | 企微跨应用免登录研究 | 📋 同corpid下IT服务台H5与运维平台各自独立OAuth2 snsapi_base静默授权，结论已归档 | 2026-07-10 |
|
||||
| #108 | H5消息重复Bug | 🐛 员工发送消息后自己看到两条 → sendNewMessage未更新lastMessageId导致轮询重复拉取 → 已修复并部署 | 2026-07-10 |
|
||||
| #109 | H5消息自动滚动 | ✨ 收到新消息时自动滚动到底部 → 已实现并部署 | 2026-07-10 |
|
||||
| #110 | WebSocket Token认证修复 | 🐛 QR码登录存储user:token:*但WS只查agent:token:* → 支持两种格式查询 | 2026-07-10 |
|
||||
| #105 | 摇人消息推送到通知栏Bug | 🐛 删除shake/call_agent函数中的企微消息推送调用，修复完成并已部署 | 2026-07-10 |
|
||||
|
||||
### P0 必做 (下一个 sprint)
|
||||
|
||||
| # | 任务 | 重要程度 | 说明 |
|
||||
|---|---|---|---|
|
||||
| #48 | v1.0 收窄 set_real_ip_from | 🔴 P0 | 现 allow 0.0.0.0/0 是临时方案，正式上线前必须改精确代理IP |
|
||||
| #81 | 敏感词检测 + 语气优化 | 🔴 P0 | v0.7.1 开发内容，文本安全过滤 |
|
||||
| #104 | 运行期结构化日志查看页（D） | 🔴 P0 | 决策4：落地筛选+下载页面 |
|
||||
|
||||
### P1 重要
|
||||
|
||||
| # | 任务 | 说明 |
|
||||
|---|---|---|
|
||||
| #105 | 摇人消息推送到通知栏Bug | 🐛 摇人/举手功能系统消息错误推送到企微应用通知，应只在H5页面内展示 |
|
||||
| #73 | 修后端文件未真正覆盖 | `yes | cp -f` 路径 |
|
||||
| #86 | 排查流程图零依赖部分 review | 把 Mermaid 流程图从代码里剥离 |
|
||||
| #88 | 管理后台 RBAC 角色权限 | 细粒度角色权限 |
|
||||
| #75 | 头像同步功能完善 | 登录强制同步 + 前端首字降级 |
|
||||
|
||||
### P1/P2 功能开发任务
|
||||
|
||||
#### 阶段2 - P1功能
|
||||
|
||||
| # | 功能 | 状态 |
|
||||
|---|---|---|
|
||||
| P1-24 | 摇人按钮 | ✅已完成 |
|
||||
| P1-25 | 满意度评价 | ✅已完成 |
|
||||
| P1-26 | 排队系统 | ✅已完成 |
|
||||
| P1-27 | 快速回复 | ✅已完成 |
|
||||
| P1-28 | 知识库(基础) | ✅已完成 |
|
||||
|
||||
#### 阶段3 - P2功能
|
||||
|
||||
| # | 功能 | 状态 |
|
||||
|---|---|---|
|
||||
| P2-09 | AI Wingman | ✅已完成 |
|
||||
| P2-10 | 会话标注 | ✅已完成 |
|
||||
| P2-11 | 自动摘要 | ✅已完成 |
|
||||
| P2-07~11 | 审批流程系统 | ✅已完成（详见任务说明书-78） |
|
||||
|
||||
#### 阶段4 - P2功能
|
||||
|
||||
| # | 功能 | 状态 |
|
||||
|---|---|---|
|
||||
| P2-12 | 数据看板 | ✅已完成 |
|
||||
| P2-13 | 知识库自动迭代 | ✅已完成 |
|
||||
|
||||
---
|
||||
|
||||
## 五、最近搞定
|
||||
|
||||
### 2026-07-10
|
||||
- ✅ 审批类型扩展 5→12种/18流程 + 卡片URL直跳 + Dify v2 发布（#113）
|
||||
- ✅ 审批卡片同窗口导航改造（#114）
|
||||
- ✅ 企微跨应用免登录可行性研究（#115）
|
||||
- ✅ 坐席端消息头像不显示Bug修复 + 部署（#111）
|
||||
- ✅ 坐席端消息布局调整（头像在名字前） + 部署（#112）
|
||||
- ✅ H5消息重复Bug修复 + 部署
|
||||
- ✅ H5消息自动滚动功能 + 部署
|
||||
- ✅ WebSocket Token认证修复 + 部署
|
||||
- ✅ 摇人消息推送Bug修复 + 部署
|
||||
|
||||
### 2026-07-09
|
||||
- ✅ WS 子协议修复部署生产
|
||||
- ✅ 方案A E2E 通过
|
||||
|
||||
### 2026-07-08
|
||||
- ✅ 消息发送延时 E2E 验证通过
|
||||
- ✅ 头像同步功能代码交付（12/12测试通过）
|
||||
|
||||
### 2026-07-07
|
||||
- ✅ 管理后台登录修复
|
||||
- ✅ 故障排查文档整合
|
||||
|
||||
### 2026-07-06
|
||||
- ✅ P1-25 满意度评价完成
|
||||
- ✅ #90 身份认证问题修复
|
||||
|
||||
### 2026-07-05
|
||||
- ✅ 坐席端消息列表500错误修复
|
||||
- ✅ 消息发送失败修复
|
||||
- ✅ 文档补充
|
||||
|
||||
---
|
||||
|
||||
## 六、风险管理
|
||||
|
||||
### 风险总览
|
||||
|
||||
| 级别 | 数量 | 已处理 | 待处理 | 处理率 |
|
||||
|------|------|--------|--------|--------|
|
||||
| 🔴 严重 (Critical) | 4 | 4 | 0 | **100%** |
|
||||
| 🟠 高 (High) | 6 | 5 | 1 | **83%** |
|
||||
| 🟡 中 (Medium) | 7 | 4 | 3 | **57%** |
|
||||
| 🔵 低 (Low) | 5 | 3 | 2 | **60%** |
|
||||
| **合计** | **22** | **16** | **6** | **73%** |
|
||||
|
||||
---
|
||||
|
||||
## 七、怎么跑起来
|
||||
|
||||
### 1. 后端 dev
|
||||
|
||||
```powershell
|
||||
cd D:\资料\03-项目开发\wecom_it_smart_desk
|
||||
docker compose -f docker-compose.dev.yml --env-file .env.dev up -d
|
||||
curl http://localhost:8000/api/dev/health
|
||||
```
|
||||
|
||||
### 2. 前端 dev
|
||||
|
||||
```powershell
|
||||
# 一起起所有前端
|
||||
.\scripts\dev-frontend-start.ps1
|
||||
```
|
||||
|
||||
### 3. 浏览器验证
|
||||
|
||||
| 端 | 地址 |
|
||||
|---|------|
|
||||
| Portal | http://localhost:5176/itportal/select |
|
||||
| H5 | http://localhost:5174/itdesk/ |
|
||||
| 坐席 | http://localhost:5173/itagent/ |
|
||||
| 管理员 | http://localhost:5175/itadmin/ |
|
||||
|
||||
---
|
||||
|
||||
## 八、文档清单
|
||||
|
||||
### 任务说明书/
|
||||
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
| IT智能服务台-项目管理主文档 | 本文档 |
|
||||
| 02-风险跟踪表.md | 风险登记册（22项） |
|
||||
| 任务说明书-01-新开发任务.md | v0.7.2 新功能开发任务 |
|
||||
| 任务说明书-02-卡点任务.md | 优先级最高卡点任务 |
|
||||
| 任务说明书-75-头像同步功能完善.md | 进行中的任务 |
|
||||
| 任务说明书-78-审批流程系统.md | 审批类型扩展+卡片URL直跳+同窗口导航+免登录研究 |
|
||||
|
||||
### SOPs-标准流程/
|
||||
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
| SOP-01-Gitea部署.md | Gitea 部署 SOP |
|
||||
| SOP-02-Gitea备份恢复.md | Gitea 备份恢复 SOP |
|
||||
| SOP-03-推送评审.md | 推送评审 SOP |
|
||||
| SOP-04-应急响应.md | 应急响应 SOP |
|
||||
| SOP-05-项目管理文档管理规范.md | 文档管理规范 SOP |
|
||||
|
||||
---
|
||||
|
||||
## 九、相关文档
|
||||
|
||||
| 类别 | 文档 | 位置 |
|
||||
|------|------|------|
|
||||
| 项目概览 | 项目总览与部署手册 | `01-项目总览/` |
|
||||
| 产品需求 | PRD需求文档 | `02-产品需求/` |
|
||||
| 技术架构 | 技术架构设计 | `03-技术架构/` |
|
||||
| 测试质量 | E2E验收清单 | `06-测试质量/` |
|
||||
| 部署运维 | 部署指南 | `09-部署运维/` |
|
||||
|
||||
---
|
||||
|
||||
## 十、版本历史
|
||||
|
||||
| 版本 | 日期 | 变更 |
|
||||
|------|------|------|
|
||||
| v2.4 | 2026-07-10 | 新增 #113-115 审批流程系统任务（类型扩展+卡片导航+免登录研究），P2功能表新增审批流程系统 |
|
||||
| v2.3 | 2026-07-10 | 新增 #111-112 头像显示与布局调整任务 |
|
||||
| v2.2 | 2026-07-10 | 新增 #108-110 Bug修复任务（消息重复、自动滚动、WS认证） |
|
||||
| v2.1 | 2026-07-10 | 看板新增 #107 后端部署卷挂载改造任务 |
|
||||
| v2.0 | 2026-07-10 | 整合任务总索引、项目状态看板、任务状态报告、风险跟踪表 |
|
||||
| v1.1 | 2026-07-04 | 新增产品需求变更、技术架构变更、文档管理变更 |
|
||||
| v1.0 | 2026-07-04 | 初始版本 |
|
||||
|
||||
---
|
||||
|
||||
> **本文档就是项目的"驾驶舱仪表盘"。任何时候新开 session，先读这个文件就懂上下文。
|
||||
@@ -0,0 +1,94 @@
|
||||
# 任务说明书 - 摇人消息推送到通知栏Bug修复
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-10
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | 摇人消息推送到通知栏Bug修复 |
|
||||
| **任务ID** | #105 |
|
||||
| **优先级** | 🟠 P1 |
|
||||
| **类型** | Bug修复 |
|
||||
| **状态** | ✅ 已完成 |
|
||||
| **负责人** | 助理 |
|
||||
| **创建日期** | 2026-07-10 |
|
||||
| **计划完成日期** | 2026-07-10 |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
### 问题描述
|
||||
| 来源 | 描述 |
|
||||
|------|------|
|
||||
| 用户反馈 | 2026-07-10 07:28:53 摇人功能触发后，系统消息"大哥，俺这就去摇人，稍等..."和"人摇来了！IT坐席为您服务"出现在企微应用通知消息中，按理只需显示在员工端会话页面 |
|
||||
|
||||
### 问题定位
|
||||
| 文件 | 行号 | 问题 |
|
||||
|------|------|------|
|
||||
| `backend/app/api/h5.py` | 1169-1174 | shake函数错误调用wecom_service.send_text_message推送企微消息 |
|
||||
| `backend/app/api/h5.py` | 1335-1340 | call_agent函数错误调用wecom_service.send_text_message推送企微消息 |
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果要求
|
||||
|
||||
### 交付物清单
|
||||
|
||||
| # | 交付物 | 类型 | 说明 |
|
||||
|---|--------|------|------|
|
||||
| 1 | h5.py代码修复 | 代码 | 删除两处企微消息推送调用 |
|
||||
| 2 | 部署验证 | 部署 | 部署到测试环境验证 |
|
||||
|
||||
### 代码修改
|
||||
- `backend/app/api/h5.py`:
|
||||
- 第1169-1174行：删除shake函数的wecom_service.send_text_message调用
|
||||
- 第1335-1340行：删除call_agent函数的wecom_service.send_text_message调用
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验证方式
|
||||
|
||||
### 功能验证
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 摇人功能 | 员工端点击摇人按钮 | 系统消息仅在H5页面内展示，不出现在企微通知 |
|
||||
| 举手功能 | 员工端点击举手按钮 | 系统消息仅在H5页面内展示，不出现在企微通知 |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 完成标准
|
||||
|
||||
### 验收条件
|
||||
|
||||
- [x] 代码已修复
|
||||
- [x] 测试环境部署验证通过
|
||||
- [x] 项目管理主文档已更新
|
||||
|
||||
---
|
||||
|
||||
## 📞 依赖与阻塞
|
||||
|
||||
### 前置依赖
|
||||
无
|
||||
|
||||
### 阻塞因素
|
||||
无
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 | 说明 |
|
||||
|------|----------|--------|------|
|
||||
| 2026-07-10 | 创建任务 | 助理 | 初始版本 |
|
||||
| 2026-07-10 | 代码已修复 | 助理 | 删除两处企微消息推送调用 |
|
||||
|
||||
---
|
||||
|
||||
## 📎 附件
|
||||
|
||||
- 问题反馈：`backend/app/api/h5.py`
|
||||
@@ -1,140 +0,0 @@
|
||||
# 任务说明书：消息推送策略优化与超时提醒
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-05
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | 消息推送策略优化与超时提醒 |
|
||||
| **任务ID** | #100 |
|
||||
| **优先级** | 🟠 P1 |
|
||||
| **类型** | 功能开发 |
|
||||
| **状态** | ✅ 已完成 |
|
||||
| **负责人** | 宋献 |
|
||||
| **创建日期** | 2026-07-05 |
|
||||
| **计划完成日期** | 待定 |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
### 产品需求
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `02-产品需求/04-技术方案-消息推送策略优化与超时提醒.md` | 全文 | 技术方案文档 |
|
||||
|
||||
### 技术架构
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `backend/app/api/messages.py` | send_message 函数 | 现有消息发送逻辑 |
|
||||
| `backend/app/models/conversation.py` | Conversation 模型 | 会话数据模型 |
|
||||
|
||||
### 项目看板
|
||||
| 来源 | 任务名 | 说明 |
|
||||
|------|--------|------|
|
||||
| 用户反馈 | 消息推送策略 | 坐席回复不应出现在企微应用消息列表 |
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果要求
|
||||
|
||||
### 交付物清单
|
||||
|
||||
| # | 交付物 | 类型 | 说明 |
|
||||
|---|--------|------|------|
|
||||
| 1 | 数据库迁移脚本 | SQL | conversations 表新增 4 个字段 |
|
||||
| 2 | 提醒服务 | Python | `backend/app/services/reminder_service.py` |
|
||||
| 3 | 定时任务 | Python | `backend/app/tasks/reminder_task.py` |
|
||||
| 4 | 消息发送逻辑修改 | Python | 移除企微 API 调用，仅走 WebSocket |
|
||||
| 5 | 部署验证 | - | 生产环境测试通过 |
|
||||
|
||||
### 代码要求
|
||||
- 遵循项目代码规范
|
||||
- 所有新增代码通过 Pylint 检查
|
||||
- 单元测试覆盖新增逻辑
|
||||
|
||||
### 文档要求
|
||||
- 更新本任务说明书状态
|
||||
- 更新项目状态看板
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验证方式
|
||||
|
||||
### 功能验证
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 坐席发送消息 | 坐席回复用户消息 | 仅出现在 H5 页面，不出现在企微应用消息 |
|
||||
| 超时提醒 | 坐席回复后等待 3 分钟 | 收到企微提醒消息 |
|
||||
| 提醒只发一次 | 再次等待 3 分钟 | 不再收到提醒 |
|
||||
| 待关闭状态 | 坐席回复后等待 10 分钟 | 会话状态变为 pending_close |
|
||||
|
||||
### 安全验证
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 权限控制 | 非坐席无法触发 | 仅坐席回复触发逻辑 |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 完成标准
|
||||
|
||||
### 验收条件
|
||||
|
||||
- [ ] 代码合入主干分支
|
||||
- [ ] 功能测试通过
|
||||
- [ ] 部署验证通过
|
||||
|
||||
### 产出确认
|
||||
|
||||
- [ ] 数据库迁移完成
|
||||
- [ ] 后端代码修改完成
|
||||
- [ ] 定时任务运行正常
|
||||
- [ ] 生产环境验证通过
|
||||
|
||||
---
|
||||
|
||||
## 📊 工作分解
|
||||
|
||||
### 子任务
|
||||
|
||||
| 子任务 | 负责人 | 预估工时 | 状态 |
|
||||
|--------|--------|----------|------|
|
||||
| T1. 数据库迁移 | 宋献 | 0.5h | 待开始 |
|
||||
| T2. 消息发送逻辑修改 | 宋献 | 0.5h | 待开始 |
|
||||
| T3. 新建提醒服务 | 宋献 | 1h | 待开始 |
|
||||
| T4. 新建定时任务 | 宋献 | 1h | 待开始 |
|
||||
| T5. 定时任务注册 | 宋献 | 0.5h | 待开始 |
|
||||
| T6. 部署测试 | 宋献 | 1h | 待开始 |
|
||||
|
||||
**总计**：约 4.5 小时
|
||||
|
||||
---
|
||||
|
||||
## 📞 依赖与阻塞
|
||||
|
||||
### 前置依赖
|
||||
| 依赖任务 | 依赖说明 | 状态 |
|
||||
|----------|----------|------|
|
||||
| 无 | 独立任务 | - |
|
||||
|
||||
### 阻塞因素
|
||||
| 阻塞项 | 影响范围 | 解决方案 |
|
||||
|--------|----------|-----------|
|
||||
| 无 | - | - |
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 | 说明 |
|
||||
|------|----------|--------|------|
|
||||
| 2026-07-05 | 创建任务 | 宋献 | 初始版本 |
|
||||
|
||||
---
|
||||
|
||||
## 📎 附件
|
||||
|
||||
- 技术方案：`docs/03-技术架构/02-技术方案/技术方案-消息推送策略优化与超时提醒.md`
|
||||
@@ -0,0 +1,121 @@
|
||||
# 任务说明书 — 企微模板卡片消息
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-10
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | 企微模板卡片消息样式升级 |
|
||||
| **任务ID** | #76 |
|
||||
| **优先级** | 🟡 P2 |
|
||||
| **类型** | 功能开发 |
|
||||
| **状态** | 已完成 |
|
||||
| **负责人** | 开发团队 |
|
||||
| **创建日期** | 2026-07-10 |
|
||||
| **计划完成日期** | 2026-07-10 |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
### 产品需求
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `02-产品需求/IT智能服务台-产品需求文档PRD-v2.md` | §3.新增需求 | 超时提醒消息样式升级 |
|
||||
|
||||
### 技术架构
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| 企微开发者文档 | 模板卡片消息 | text_notice 类型实现 |
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果要求
|
||||
|
||||
### 交付物清单
|
||||
|
||||
| # | 交付物 | 类型 | 说明 |
|
||||
|---|--------|------|------|
|
||||
| 1 | `app/services/wecom_service.py` | 代码 | 新增 `send_template_card_message()` 方法 |
|
||||
| 2 | `app/services/reminder_service.py` | 代码 | 改用模板卡片发送超时提醒 |
|
||||
|
||||
### 代码要求
|
||||
- 遵循项目代码规范
|
||||
- 异步方法设计，与现有 `send_card_message` 保持一致
|
||||
|
||||
### 文档要求
|
||||
- 本任务说明书
|
||||
- 更新产品需求文档
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验证方式
|
||||
|
||||
### 功能验证
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 模板卡片发送成功 | 触发超时提醒 | 企微收到卡片消息 |
|
||||
| 跳转按钮可用 | 点击按钮 | 打开 IT 服务台页面 |
|
||||
| 关键数据高亮 | 查看消息 | 显示 "10分钟 剩余处理时间" |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 完成标准
|
||||
|
||||
### 验收条件
|
||||
|
||||
- [x] 代码合入主干分支
|
||||
- [x] 功能开发完成
|
||||
- [x] 文档已更新
|
||||
|
||||
### 产出确认
|
||||
|
||||
- [x] `wecom_service.py` 新增方法
|
||||
- [x] `reminder_service.py` 调用模板卡片接口
|
||||
- [x] 任务书已创建
|
||||
- [x] PRD 已更新
|
||||
|
||||
---
|
||||
|
||||
## 📊 工作分解
|
||||
|
||||
### 子任务
|
||||
|
||||
| 子任务 | 负责人 | 预估工时 | 状态 |
|
||||
|--------|--------|----------|------|
|
||||
| 新增 send_template_card_message 方法 | 开发 | 0.5h | ✅ |
|
||||
| 改造 reminder_service 调用 | 开发 | 0.5h | ✅ |
|
||||
| 文档补充 | 开发 | 0.5h | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 📞 依赖与阻塞
|
||||
|
||||
### 前置依赖
|
||||
| 依赖任务 | 依赖说明 | 状态 |
|
||||
|----------|----------|------|
|
||||
| 无 | 独立功能 | - |
|
||||
|
||||
### 阻塞因素
|
||||
| 阻塞项 | 影响范围 | 解决方案 |
|
||||
|--------|----------|-----------|
|
||||
| 无 | - | - |
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 | 说明 |
|
||||
|------|----------|--------|------|
|
||||
| 2026-07-10 | 创建任务 | 开发 | 初始版本 |
|
||||
| 2026-07-10 | 代码开发完成 | 开发 | 实现模板卡片发送 |
|
||||
| 2026-07-10 | 文档补充 | 开发 | 补充任务书和PRD |
|
||||
|
||||
---
|
||||
|
||||
## 📎 附件
|
||||
|
||||
- 企微模板卡片文档：https://developer.work.weixin.qq.com/document/path/101032
|
||||
@@ -0,0 +1,646 @@
|
||||
# 任务说明书 — 后端部署卷挂载改造
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-10
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | 后端部署架构改造：镜像烘焙 → 代码卷挂载 |
|
||||
| **任务ID** | #107 |
|
||||
| **优先级** | 🟠 P1 |
|
||||
| **类型** | 部署优化 |
|
||||
| **状态** | 待开始 |
|
||||
| **负责人** | 宋献 |
|
||||
| **创建日期** | 2026-07-10 |
|
||||
| **计划完成日期** | 2026-07-11 |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
### 产品需求
|
||||
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| 无 | — | 运维需求，非产品功能 |
|
||||
|
||||
### 技术架构
|
||||
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `03-技术架构/IT智能服务台-系统架构设计文档v2.md` | §5.0 部署模式演进 | 方案 C 设计说明 |
|
||||
| `09-部署运维/卷挂载重构方案.md` | 全文 | 完整 8 章节方案（架构师高见远产出） |
|
||||
| `09-部署运维/00-标准故障排查手册.md` | §1.4 + CASE-20260710-02 | 部署前同步检查清单 + 镜像缺文件案例 |
|
||||
|
||||
### 事故背景
|
||||
|
||||
| 日期 | 事故 | 根因 |
|
||||
|------|------|------|
|
||||
| 2026-07-07 | 认证路由缺失 | Docker 镜像未重新构建 |
|
||||
| 2026-07-10 | auth.py 缺失导致认证全断 | 镜像从 backend/app/（旧代码）构建，两份代码不同步 |
|
||||
|
||||
**共同根因**：代码通过 `COPY . .` 烘焙进镜像，服务器两份代码不同步导致构建出缺文件的镜像。
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果要求
|
||||
|
||||
### 交付物清单
|
||||
|
||||
| # | 交付物 | 类型 | 说明 |
|
||||
|---|--------|------|------|
|
||||
| 1 | `backend/Dockerfile` | 配置 | 删除 `COPY . .`，新增 `ENV PYTHONDONTWRITEBYTECODE=1` |
|
||||
| 2 | `docker-compose.yml` | 配置 | backend 服务 volumes 新增 `./app:/app/app` |
|
||||
| 3 | 服务器代码目录调整 | 运维 | `app/` 成为唯一代码源，`backend/app/` 保留 48h 后删除 |
|
||||
| 4 | 部署验证通过 | 验证 | 健康检查 + auth 模块 + 卷挂载 + 代码一致性 |
|
||||
|
||||
### 代码要求
|
||||
|
||||
- Dockerfile 变更：仅删除 `COPY . .`（第 53 行），新增 `ENV PYTHONDONTWRITEBYTECODE=1`，其余不变
|
||||
- docker-compose.yml 变更：backend 服务 volumes 段新增一行 `./app:/app/app`，插入到 `backend-uploads` 行之前
|
||||
- 不涉及任何 Python 业务代码变更
|
||||
|
||||
### 文档要求
|
||||
|
||||
- 架构设计文档已更新（§5.0 部署模式演进，v2.1）
|
||||
- 项目管理主文档已更新（看板新增 #107）
|
||||
- 完整方案文档已归档：`docs/09-部署运维/卷挂载重构方案.md`
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验证方式
|
||||
|
||||
### 功能验证
|
||||
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 容器运行状态 | `docker compose ps backend` | Status 为 `Up (healthy)` |
|
||||
| 健康检查 | `curl -sf http://localhost:8000/health` | 返回 `{"status":"healthy"}` 或类似 |
|
||||
| **Auth 模块** | `docker exec wecom_it_backend python -c "from app.auth import router; print('OK')"` | 输出 `OK`（曾因缺失导致故障） |
|
||||
| 卷挂载 | `docker exec wecom_it_backend ls -la /app/app/main.py` | 文件存在且可读 |
|
||||
| 代码一致性 | `md5sum` 对比宿主机与容器内 `main.py` | md5 值一致 |
|
||||
| 日志检查 | `docker compose logs --tail=50 backend` | 无 `ModuleNotFoundError` / `ImportError` |
|
||||
|
||||
### 安全验证
|
||||
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| `COPY . .` 已移除 | `grep -c "COPY . ." backend/Dockerfile` | 返回 0 |
|
||||
| 卷挂载已添加 | `grep "app:/app/app" docker-compose.yml` | 返回匹配 |
|
||||
| `__pycache__` 禁止 | `docker exec wecom_it_backend python -c "import sys; print(sys.dont_write_bytecode)"` | 输出 `True` |
|
||||
|
||||
### 性能验证
|
||||
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 容器重启速度 | 部署后 `docker compose restart backend` + `time` 计时 | < 15 秒（此前需 4-6 分钟） |
|
||||
| 健康检查就绪 | 重启后 `curl /health` 轮询 | 15 秒内就绪 |
|
||||
|
||||
---
|
||||
|
||||
## 🔄 回滚策略（CRITICAL）
|
||||
|
||||
### 回滚触发条件
|
||||
|
||||
满足以下 **任一** 条件即触发回滚：
|
||||
|
||||
| # | 触发条件 | 检测方法 |
|
||||
|---|----------|----------|
|
||||
| 1 | 容器启动失败（反复重启） | `docker compose ps backend` 状态为 `restarting` 或 `unhealthy` |
|
||||
| 2 | 健康检查连续失败 | `curl -sf http://localhost:8000/health` 返回非 200 |
|
||||
| 3 | 关键模块导入失败（如 auth） | `docker exec wecom_it_backend python -c "from app.auth import router"` 报错 |
|
||||
| 4 | 卷挂载路径不存在或权限拒绝 | 容器日志出现 `ModuleNotFoundError` 或 `PermissionError` |
|
||||
| 5 | 业务接口大面积 500 错误 | Nginx 日志或后端日志大量 500 状态码 |
|
||||
|
||||
### 回滚步骤（可通过 jumpserver-ops 执行）
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# =============================================================================
|
||||
# 回滚脚本：卷挂载方案 → 镜像烘焙方案
|
||||
# 执行方式：通过 jumpserver-ops 在 10.90.5.110 上执行
|
||||
# 前提：备份文件存在（部署时已创建 .bak.{TIMESTAMP} 后缀文件）
|
||||
# =============================================================================
|
||||
|
||||
set -e
|
||||
cd /opt/wecom-it-desk
|
||||
|
||||
echo "===== 回滚开始: $(date) ====="
|
||||
|
||||
# --- 步骤 1: 恢复备份的配置文件 ---
|
||||
echo ">>> [1/6] 恢复配置文件..."
|
||||
|
||||
COMPOSE_BAK=$(ls -t /opt/wecom-it-desk/docker-compose.yml.bak.* 2>/dev/null | head -1)
|
||||
if [ -z "$COMPOSE_BAK" ]; then
|
||||
echo "ERROR: 未找到 docker-compose.yml 备份文件！"
|
||||
echo "可手动从 git 恢复: git checkout -- docker-compose.yml"
|
||||
exit 1
|
||||
fi
|
||||
cp "$COMPOSE_BAK" /opt/wecom-it-desk/docker-compose.yml
|
||||
echo " 已恢复 docker-compose.yml <- $COMPOSE_BAK"
|
||||
|
||||
DOCKERFILE_BAK=$(ls -t /opt/wecom-it-desk/backend/Dockerfile.bak.* 2>/dev/null | head -1)
|
||||
if [ -z "$DOCKERFILE_BAK" ]; then
|
||||
echo "ERROR: 未找到 Dockerfile 备份文件！"
|
||||
echo "可手动从 git 恢复: git checkout -- backend/Dockerfile"
|
||||
exit 1
|
||||
fi
|
||||
cp "$DOCKERFILE_BAK" /opt/wecom-it-desk/backend/Dockerfile
|
||||
echo " 已恢复 Dockerfile <- $DOCKERFILE_BAK"
|
||||
|
||||
# --- 步骤 2: 确保 backend/app/ 存在（回滚安全网） ---
|
||||
echo ">>> [2/6] 检查 backend/app/ 目录..."
|
||||
|
||||
if [ ! -d /opt/wecom-it-desk/backend/app/ ] || [ -z "$(ls -A /opt/wecom-it-desk/backend/app/ 2>/dev/null)" ]; then
|
||||
echo " backend/app/ 不存在或为空，从 app/ 同步代码..."
|
||||
mkdir -p /opt/wecom-it-desk/backend/app/
|
||||
cp -r /opt/wecom-it-desk/app/* /opt/wecom-it-desk/backend/app/
|
||||
cp -r /opt/wecom-it-desk/app/.* /opt/wecom-it-desk/backend/app/ 2>/dev/null || true
|
||||
echo " 已同步代码到 backend/app/"
|
||||
else
|
||||
echo " backend/app/ 已存在，跳过同步"
|
||||
fi
|
||||
|
||||
# --- 步骤 3: 重新构建镜像（使用原始 Dockerfile，含 COPY . .） ---
|
||||
echo ">>> [3/6] 重新构建后端镜像..."
|
||||
docker compose build --no-cache backend
|
||||
|
||||
# --- 步骤 4: 重启容器 ---
|
||||
echo ">>> [4/6] 重启后端容器..."
|
||||
docker compose up -d backend
|
||||
|
||||
# --- 步骤 5: 等待服务就绪 ---
|
||||
echo ">>> [5/6] 等待服务启动..."
|
||||
echo " 等待 45 秒（healthcheck start_period）..."
|
||||
sleep 45
|
||||
|
||||
# --- 步骤 6: 验证 ---
|
||||
echo ">>> [6/6] 验证回滚结果..."
|
||||
|
||||
echo "--- 容器状态 ---"
|
||||
docker compose ps backend
|
||||
|
||||
echo "--- 健康检查 ---"
|
||||
if curl -sf http://localhost:8000/health > /dev/null 2>&1; then
|
||||
echo " PASS: /health 返回正常"
|
||||
else
|
||||
echo " WARN: /health 未就绪，再等待 15 秒..."
|
||||
sleep 15
|
||||
if curl -sf http://localhost:8000/health > /dev/null 2>&1; then
|
||||
echo " PASS: /health 返回正常（延迟就绪）"
|
||||
else
|
||||
echo " FAIL: /health 仍然失败"
|
||||
echo " 查看日志: docker compose logs --tail=50 backend"
|
||||
fi
|
||||
fi
|
||||
|
||||
echo "--- Auth 模块验证 ---"
|
||||
if docker exec wecom_it_backend python -c "from app.auth import router; print('auth OK')" 2>/dev/null; then
|
||||
echo " PASS: auth 模块可导入"
|
||||
else
|
||||
echo " FAIL: auth 模块导入失败"
|
||||
echo " 查看日志: docker compose logs --tail=50 backend"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "===== 回滚完成: $(date) ====="
|
||||
echo ""
|
||||
echo "如回滚后仍有问题，请检查:"
|
||||
echo " 1. backend/app/ 代码是否完整: ls -la /opt/wecom-it-desk/backend/app/"
|
||||
echo " 2. 镜像构建是否成功: docker images | grep wecom-it-desk-backend"
|
||||
echo " 3. 容器日志: docker compose logs -f backend"
|
||||
```
|
||||
|
||||
### 回滚后验证
|
||||
|
||||
| 验证项 | 命令 | 预期结果 |
|
||||
|--------|------|----------|
|
||||
| 容器运行状态 | `docker compose ps backend` | Status 为 `Up (healthy)` |
|
||||
| 健康检查 | `curl -sf http://localhost:8000/health` | 返回正常 |
|
||||
| Auth 模块 | `docker exec wecom_it_backend python -c "from app.auth import router; print('OK')"` | 输出 `OK` |
|
||||
| Nginx 代理 | `curl -sf http://localhost:80/itdesk/health` | 返回正常 |
|
||||
| 日志无异常 | `docker compose logs --tail=50 backend` | 无 `ModuleNotFoundError` / `ImportError` |
|
||||
|
||||
### 回滚时间预估
|
||||
|
||||
| 步骤 | 耗时 |
|
||||
|------|------|
|
||||
| 恢复配置文件 | 5 秒 |
|
||||
| 检查/同步 backend/app/ | 5-30 秒 |
|
||||
| 重建镜像 | 2-4 分钟 |
|
||||
| 重启容器 | 10 秒 |
|
||||
| 等待就绪 | 45 秒 |
|
||||
| 验证 | 15 秒 |
|
||||
| **总计** | **3.5-5.5 分钟** |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 完成标准
|
||||
|
||||
### 验收条件
|
||||
|
||||
- [ ] Dockerfile 已删除 `COPY . .`，已新增 `PYTHONDONTWRITEBYTECODE=1`
|
||||
- [ ] docker-compose.yml 已新增 `./app:/app/app` 卷挂载
|
||||
- [ ] 镜像已重建并重启成功
|
||||
- [ ] 健康检查通过（`/health` 返回正常）
|
||||
- [ ] Auth 模块可导入（`from app.auth import router` 成功）
|
||||
- [ ] 卷挂载验证通过（容器内 `/app/app/main.py` 可访问）
|
||||
- [ ] 代码一致性验证通过（宿主机与容器 md5 一致）
|
||||
- [ ] 日志无 `ModuleNotFoundError` / `ImportError`
|
||||
- [ ] 部署 48 小时后 `backend/app/` 已清理
|
||||
- [ ] 文档已更新（架构设计文档 v2.1、项目管理主文档 v2.1）
|
||||
|
||||
### 产出确认
|
||||
|
||||
- [ ] 服务器 Dockerfile 已更新
|
||||
- [ ] 服务器 docker-compose.yml 已更新
|
||||
- [ ] 镜像重建成功
|
||||
- [ ] 容器运行正常
|
||||
- [ ] 回滚脚本已验证可用
|
||||
- [ ] 备份文件已创建（`.bak.{TIMESTAMP}`）
|
||||
- [ ] `.rollback-info` 文件已记录
|
||||
|
||||
---
|
||||
|
||||
## 📊 工作分解
|
||||
|
||||
### 子任务
|
||||
|
||||
| 子任务 | 负责人 | 预估工时 | 状态 | 依赖 |
|
||||
|--------|--------|----------|------|------|
|
||||
| S1: 前置验证与备份 | 宋献 | 2 分钟 | 待开始 | 无 |
|
||||
| S2: 代码同步与验证 | 宋献 | 1 分钟 | 待开始 | S1 |
|
||||
| S3: 修改 Dockerfile | 宋献 | 1 分钟 | 待开始 | S2 |
|
||||
| S4: 修改 docker-compose.yml | 宋献 | 1 分钟 | 待开始 | S3 |
|
||||
| S5: 重建镜像并重启 | 宋献 | 3 分钟 | 待开始 | S4 |
|
||||
| S6: 部署后验证 | 宋献 | 2 分钟 | 待开始 | S5 |
|
||||
| S7: 清理 backend/app/（48h 后） | 宋献 | 1 分钟 | 待开始 | S6 + 48h |
|
||||
|
||||
### 预估总时间
|
||||
|
||||
| 阶段 | 步骤 | 耗时 |
|
||||
|------|------|------|
|
||||
| 准备 | S1 + S2 | 3 分钟 |
|
||||
| 变更 | S3 + S4 | 2 分钟 |
|
||||
| 部署 | S5 | 3 分钟 |
|
||||
| 验证 | S6 | 2 分钟 |
|
||||
| **总计** | S1-S6 | **约 10 分钟** |
|
||||
| 清理 | S7（48h 后） | 1 分钟 |
|
||||
| **回滚（如需）** | 回滚脚本 | **3.5-5.5 分钟** |
|
||||
|
||||
---
|
||||
|
||||
## 📞 依赖与阻塞
|
||||
|
||||
### 前置依赖
|
||||
|
||||
| 依赖任务 | 依赖说明 | 状态 |
|
||||
|----------|----------|------|
|
||||
| 无 | 独立运维任务 | — |
|
||||
|
||||
### 阻塞因素
|
||||
|
||||
| 阻塞项 | 影响范围 | 解决方案 |
|
||||
|--------|----------|-----------|
|
||||
| 无 | — | — |
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 风险评估
|
||||
|
||||
| # | 风险 | 概率 | 等级 | 对策 |
|
||||
|---|------|------|------|------|
|
||||
| R1 | `__pycache__` 污染宿主机代码目录 | 中 | 中 | Dockerfile 设置 `PYTHONDONTWRITEBYTECODE=1` |
|
||||
| R2 | 宿主机代码被意外修改导致运行中服务异常 | 低 | 中 | 生产不启用 `--reload`；限制目录写权限 |
|
||||
| R3 | `backend/app/` 被提前删除导致回滚失败 | 低 | 高 | 48 小时内不删除；回滚脚本含自动同步逻辑 |
|
||||
| R4 | requirements.txt 与代码不同步 | 低 | 中 | 部署前 diff 对比；新增依赖时先重建镜像 |
|
||||
| R5 | 卷挂载路径与现有挂载冲突 | 极低 | 低 | `/app/app` 与 `/app/uploads`、`/app/logs` 无交集 |
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 | 说明 |
|
||||
|------|----------|--------|------|
|
||||
| 2026-07-10 | 创建任务 | 宋献 | 初始版本，基于架构师高见远的卷挂载重构方案 |
|
||||
|
||||
---
|
||||
|
||||
## 📎 附件
|
||||
|
||||
- **完整方案文档**：`docs/09-部署运维/卷挂载重构方案.md`（含完整命令块、时序图、风险评估）
|
||||
- **架构设计文档**：`docs/03-技术架构/IT智能服务台-系统架构设计文档v2.md` §5.0
|
||||
- **故障排查手册**：`docs/09-部署运维/00-标准故障排查手册.md` §1.4 + CASE-20260710-02
|
||||
- **deploy-troubleshoot skill**：`~/.workbuddy/skills/deploy-troubleshoot/SKILL.md` Step -1 部署前同步检查
|
||||
- **task-intake skill**：`.workbuddy/skills/task-intake/SKILL.md` Step 3.1 部署运维前置检查
|
||||
|
||||
---
|
||||
|
||||
## 📝 完整部署命令块
|
||||
|
||||
以下命令可通过 jumpserver-ops 在服务器 10.90.5.110 上按步骤执行。
|
||||
|
||||
### S1: 前置验证与备份
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
cd /opt/wecom-it-desk
|
||||
|
||||
# 1. 验证当前服务正常
|
||||
echo ">>> 验证当前服务状态..."
|
||||
curl -sf http://localhost:8000/health > /dev/null && echo " PASS: 当前服务正常" || { echo " FAIL: 当前服务异常，请先修复再部署"; exit 1; }
|
||||
|
||||
# 2. 备份配置文件
|
||||
BACKUP_TS=$(date +%Y%m%d%H%M%S)
|
||||
cp /opt/wecom-it-desk/docker-compose.yml /opt/wecom-it-desk/docker-compose.yml.bak.${BACKUP_TS}
|
||||
cp /opt/wecom-it-desk/backend/Dockerfile /opt/wecom-it-desk/backend/Dockerfile.bak.${BACKUP_TS}
|
||||
echo " PASS: 备份完成 (timestamp: ${BACKUP_TS})"
|
||||
|
||||
# 3. 记录回滚信息
|
||||
cat > /opt/wecom-it-desk/.rollback-info << EOF
|
||||
ROLLBACK_TIMESTAMP=${BACKUP_TS}
|
||||
COMPOSE_BAK=/opt/wecom-it-desk/docker-compose.yml.bak.${BACKUP_TS}
|
||||
DOCKERFILE_BAK=/opt/wecom-it-desk/backend/Dockerfile.bak.${BACKUP_TS}
|
||||
DEPLOY_DATE=$(date)
|
||||
EOF
|
||||
echo " PASS: 回滚信息已记录到 .rollback-info"
|
||||
echo ""
|
||||
echo "===== S1 完成 ====="
|
||||
```
|
||||
|
||||
### S2: 代码同步与验证
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
cd /opt/wecom-it-desk
|
||||
|
||||
# 1. 验证 app/ 目录存在且包含关键文件
|
||||
echo ">>> 验证代码目录..."
|
||||
for f in app/__init__.py app/main.py app/config.py app/database.py; do
|
||||
if [ -f "$f" ]; then
|
||||
echo " PASS: $f 存在"
|
||||
else
|
||||
echo " FAIL: $f 不存在！请先解压部署包: tar -xf /tmp/deploy-backend.tar -C ./"
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
|
||||
# 2. 验证 auth 模块（关键！曾因缺失导致故障）
|
||||
if [ -f "app/api/auth.py" ]; then
|
||||
echo " PASS: app/api/auth.py 存在"
|
||||
else
|
||||
echo " FAIL: app/api/auth.py 不存在！认证功能将不可用"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 3. 统计代码文件数
|
||||
FILE_COUNT=$(find app/ -name "*.py" | wc -l)
|
||||
echo " INFO: app/ 目录共 ${FILE_COUNT} 个 Python 文件"
|
||||
|
||||
echo ""
|
||||
echo "===== S2 完成 ====="
|
||||
```
|
||||
|
||||
### S3: 修改 Dockerfile
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
DOCKERFILE=/opt/wecom-it-desk/backend/Dockerfile
|
||||
|
||||
echo ">>> 修改 Dockerfile..."
|
||||
|
||||
# 直接写入完整文件（最可靠）
|
||||
cat > "$DOCKERFILE" << 'DOCKERFILE_EOF'
|
||||
# =============================================================================
|
||||
# 企微IT智能服务台 — 后端 Docker 镜像构建文件
|
||||
# =============================================================================
|
||||
# 说明：基于 Python 3.12 构建后端镜像
|
||||
# 变更：2025-07-10 方案C — 代码改为 volume 挂载，镜像不再 COPY 业务代码
|
||||
# 用法：docker build -t wecom-it-desk-backend .
|
||||
# =============================================================================
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 第一阶段：构建阶段
|
||||
# --------------------------------------------------------------------------
|
||||
FROM python:3.12-slim AS builder
|
||||
|
||||
# 设置工作目录
|
||||
WORKDIR /app
|
||||
|
||||
# 安装系统依赖（psycopg2 编译需要 + qrcode 图片处理需要 + healthcheck 需要 curl）
|
||||
RUN apt-get update && \
|
||||
apt-get install -y --no-install-recommends gcc libpq-dev libjpeg-dev zlib1g-dev curl && \
|
||||
rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# 复制依赖声明文件并安装（利用 Docker 层缓存，依赖不变则不重新安装）
|
||||
COPY requirements.txt .
|
||||
RUN pip install --no-cache-dir \
|
||||
--timeout 180 \
|
||||
--retries 5 \
|
||||
-i https://mirrors.aliyun.com/pypi/simple/ \
|
||||
--trusted-host mirrors.aliyun.com \
|
||||
-r requirements.txt
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 第二阶段：运行阶段（更小的镜像体积）
|
||||
# --------------------------------------------------------------------------
|
||||
FROM python:3.12-slim
|
||||
|
||||
# 设置标签信息
|
||||
LABEL maintainer="IT服务台开发团队"
|
||||
LABEL description="企微IT智能服务台后端服务"
|
||||
LABEL changelog="2025-07-10: 移除 COPY . .，代码改为 volume 挂载"
|
||||
|
||||
# 安装运行时依赖（psycopg2 运行时需要 libpq + healthcheck 需要 curl）
|
||||
RUN apt-get update && \
|
||||
apt-get install -y --no-install-recommends libpq5 curl && \
|
||||
rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# 设置工作目录
|
||||
WORKDIR /app
|
||||
|
||||
# 禁止 Python 写入 __pycache__（防止污染宿主机代码目录）
|
||||
ENV PYTHONDONTWRITEBYTECODE=1
|
||||
|
||||
# 从构建阶段复制已安装的 Python 包
|
||||
COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
|
||||
COPY --from=builder /usr/local/bin /usr/local/bin
|
||||
|
||||
# 业务代码通过 docker-compose volumes 挂载（./app:/app/app），不再 COPY 进镜像
|
||||
|
||||
# 暴露端口
|
||||
EXPOSE 8000
|
||||
|
||||
# 启动命令（Docker Compose 中会覆盖）
|
||||
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
|
||||
DOCKERFILE_EOF
|
||||
|
||||
# 验证
|
||||
if grep -q "COPY . ." "$DOCKERFILE"; then
|
||||
echo " FAIL: Dockerfile 仍包含 COPY . ."
|
||||
exit 1
|
||||
fi
|
||||
if grep -q "PYTHONDONTWRITEBYTECODE" "$DOCKERFILE"; then
|
||||
echo " PASS: PYTHONDONTWRITEBYTECODE 已设置"
|
||||
else
|
||||
echo " FAIL: PYTHONDONTWRITEBYTECODE 未找到"
|
||||
exit 1
|
||||
fi
|
||||
echo " PASS: Dockerfile 已更新"
|
||||
|
||||
echo ""
|
||||
echo "===== S3 完成 ====="
|
||||
```
|
||||
|
||||
### S4: 修改 docker-compose.yml
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
cd /opt/wecom-it-desk
|
||||
|
||||
COMPOSE_FILE=/opt/wecom-it-desk/docker-compose.yml
|
||||
|
||||
echo ">>> 修改 docker-compose.yml..."
|
||||
|
||||
# 在 backend-uploads 行之前插入代码卷挂载行
|
||||
sed -i '/backend-uploads:\/app\/uploads/i\ - ./app:/app/app # 代码卷挂载（方案C）' "$COMPOSE_FILE"
|
||||
|
||||
# 验证
|
||||
if grep -q "./app:/app/app" "$COMPOSE_FILE"; then
|
||||
echo " PASS: 代码卷挂载已添加"
|
||||
else
|
||||
echo " FAIL: 代码卷挂载未找到，请手动编辑 docker-compose.yml"
|
||||
echo " 在 backend 服务的 volumes: 下添加:"
|
||||
echo " - ./app:/app/app"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "===== S4 完成 ====="
|
||||
```
|
||||
|
||||
### S5: 重建镜像并重启
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
cd /opt/wecom-it-desk
|
||||
|
||||
echo ">>> 重建后端镜像..."
|
||||
docker compose build backend
|
||||
echo " PASS: 镜像构建完成"
|
||||
|
||||
echo ""
|
||||
echo ">>> 重启后端容器..."
|
||||
docker compose up -d backend
|
||||
echo " PASS: 容器已启动"
|
||||
|
||||
echo ""
|
||||
echo ">>> 等待服务就绪 (45秒)..."
|
||||
sleep 45
|
||||
|
||||
echo ""
|
||||
echo "===== S5 完成 ====="
|
||||
```
|
||||
|
||||
### S6: 部署后验证
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
cd /opt/wecom-it-desk
|
||||
|
||||
echo "===== 部署后验证 ====="
|
||||
echo ""
|
||||
|
||||
# 1. 容器状态
|
||||
echo "--- 1. 容器状态 ---"
|
||||
docker compose ps backend
|
||||
echo ""
|
||||
|
||||
# 2. 健康检查
|
||||
echo "--- 2. 健康检查 ---"
|
||||
if curl -sf http://localhost:8000/health; then
|
||||
echo ""
|
||||
echo " PASS: /health 正常"
|
||||
else
|
||||
echo " FAIL: /health 异常"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# 3. Auth 模块验证
|
||||
echo "--- 3. Auth 模块验证 ---"
|
||||
if docker exec wecom_it_backend python -c "from app.auth import router; print(' auth module: OK')" 2>/dev/null; then
|
||||
echo " PASS: auth 模块可导入"
|
||||
else
|
||||
echo " FAIL: auth 模块导入失败"
|
||||
echo " 查看日志: docker compose logs --tail=50 backend"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# 4. 卷挂载验证
|
||||
echo "--- 4. 卷挂载验证 ---"
|
||||
if docker exec wecom_it_backend ls -la /app/app/main.py > /dev/null 2>&1; then
|
||||
echo " PASS: /app/app/main.py 可访问（卷挂载正常）"
|
||||
else
|
||||
echo " FAIL: /app/app/main.py 不可访问（卷挂载异常）"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# 5. 代码来源验证
|
||||
echo "--- 5. 代码来源验证 ---"
|
||||
HOST_HASH=$(md5sum /opt/wecom-it-desk/app/main.py | awk '{print $1}')
|
||||
CONTAINER_HASH=$(docker exec wecom_it_backend md5sum /app/app/main.py 2>/dev/null | awk '{print $1}')
|
||||
if [ "$HOST_HASH" = "$CONTAINER_HASH" ]; then
|
||||
echo " PASS: 宿主机与容器代码一致 (md5: ${HOST_HASH})"
|
||||
else
|
||||
echo " WARN: 宿主机与容器代码不一致"
|
||||
echo " 宿主机: $HOST_HASH"
|
||||
echo " 容器: $CONTAINER_HASH"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# 6. 日志检查
|
||||
echo "--- 6. 最近 20 行日志 ---"
|
||||
docker compose logs --tail=20 backend
|
||||
echo ""
|
||||
|
||||
echo "===== 验证完成 ====="
|
||||
echo ""
|
||||
echo "如全部 PASS，部署成功。"
|
||||
echo "如出现 FAIL，请执行回滚脚本（见上方回滚策略章节）。"
|
||||
```
|
||||
|
||||
### S7: 清理（48 小时后执行）
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
cd /opt/wecom-it-desk
|
||||
|
||||
echo ">>> 清理旧代码目录..."
|
||||
echo " 注意：仅在部署成功 48 小时后执行此步骤！"
|
||||
echo ""
|
||||
|
||||
# 确认服务稳定
|
||||
curl -sf http://localhost:8000/health > /dev/null && echo " 服务正常" || { echo " 服务异常，取消清理"; exit 1; }
|
||||
|
||||
# 删除 backend/app/（不再需要）
|
||||
if [ -d /opt/wecom-it-desk/backend/app/ ]; then
|
||||
echo " 删除 backend/app/..."
|
||||
rm -rf /opt/wecom-it-desk/backend/app/
|
||||
echo " PASS: backend/app/ 已删除"
|
||||
else
|
||||
echo " INFO: backend/app/ 已不存在，跳过"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "===== 清理完成 ====="
|
||||
```
|
||||
@@ -0,0 +1,279 @@
|
||||
# 任务说明书 — 审批流程系统
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-10
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | 审批类型扩展 + 卡片URL直跳 + 同窗口导航 + 免登录研究 |
|
||||
| **任务ID** | #113-115 |
|
||||
| **优先级** | 🟡 P2 |
|
||||
| **类型** | 功能开发 |
|
||||
| **状态** | ✅ 已完成并部署 |
|
||||
| **负责人** | 开发团队（software-approval-expand / software-approval-nav 团队） |
|
||||
| **创建日期** | 2026-07-10 |
|
||||
| **完成日期** | 2026-07-10 |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
### 产品需求
|
||||
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `02-产品需求/IT智能服务台-产品需求文档PRD-v2.md` | §v2.2 增量需求 P2-07~P2-11 | 审批类型扩展、卡片URL关联、导航方式、免登录研究 |
|
||||
| `02-产品需求/approval_templates.json` | 全文 | 18个审批流程的结构化数据源 |
|
||||
| `02-产品需求/dify_approval_system_prompt_v2.md` | 全文 | Dify意图识别System Prompt v2 |
|
||||
| `02-产品需求/外来资料/IT审批与运维流程清单.xlsx` | 全文 | 原始审批流程清单（18行） |
|
||||
|
||||
### 技术架构
|
||||
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `03-技术架构/IT智能服务台-系统架构设计文档v2.md` | §15.4.3~15.4.8 | 审批模板扩展、意图识别链路、前端卡片架构、导航方案选型、跨应用免登录、后端API |
|
||||
|
||||
---
|
||||
|
||||
## 📝 任务详情
|
||||
|
||||
### 子任务 #113：审批类型扩展与卡片URL直跳
|
||||
|
||||
#### 背景
|
||||
|
||||
原系统仅支持 5 种审批类型（设备申请、账号权限、软件服务、资产处置、办公用品），Dify 意图识别也仅覆盖这 5 类。根据 `IT审批与运维流程清单.xlsx`，实际需要覆盖 12 种审批类型 / 18 个审批流程（企微审批 12 个 + 运维平台 6 个）。
|
||||
|
||||
#### 实现内容
|
||||
|
||||
**后端** (`backend/app/api/approval.py`)：
|
||||
- `APPROVAL_TEMPLATES` 从 5 个扩展到 18 个（静态硬编码，含完整 URL、keywords、location）
|
||||
- `APPROVAL_PREFILTER_KEYWORDS` 从 5 类扩展到 12 类关键词
|
||||
- `KEYWORD_TO_APPROVAL_TYPE` 扩展为 12 类映射
|
||||
- 新增 7 种类型：会议室故障报修、企业应用管理、资产变更确认、终端设备网络准入、活动与会议技术支持、员工IT支持与故障报修、公共邮箱账号申请
|
||||
- 意图识别三级链路保持不变：关键词预过滤 → Dify原生API → 关键词降级兜底
|
||||
|
||||
**前端** (`frontend-h5/src/components/chat/ApprovalCardModal.vue`)：
|
||||
- `ApprovalOption` 接口新增 `url?: string` 字段
|
||||
- `APPROVAL_OPTIONS` 从 5 类扩展到 12 类 / 17 个选项，每个选项携带完整审批 URL
|
||||
- `handleSelect` 优先检查 `option.url`，有则直接跳转；无则 fallback 到后端模板匹配
|
||||
|
||||
**Dify**：
|
||||
- System Prompt v2 覆盖全部 12 种审批类型，含示例、匹配规则、置信度评分指南
|
||||
- 已由管理员手动粘贴发布到 Dify 后台
|
||||
|
||||
**数据文件**：
|
||||
- `approval_templates.json` — 18 个审批流程的结构化数据（id, name, category, location, template_id, url, keywords, icon, desc）
|
||||
- `dify_approval_system_prompt_v2.md` — Dify 应用的完整 System Prompt 文本
|
||||
|
||||
#### 审批流程清单（18个）
|
||||
|
||||
| # | 审批类型 | 流程名称 | 平台 |
|
||||
|---|---------|---------|------|
|
||||
| 1 | 设备申请 | IT设备领用申请 | 企微审批 |
|
||||
| 2 | 设备申请 | IT设备外修申请 | 企微审批 |
|
||||
| 3 | 账号权限申请 | VPN权限申请 | 企微审批 |
|
||||
| 4 | 账号权限申请 | 企微外联权限申请 | 企微审批 |
|
||||
| 5 | 软件服务申请 | 商业软件服务申请 | 企微审批 |
|
||||
| 6 | 资产处置申请 | IT资产报废申请 | 企微审批 |
|
||||
| 7 | 资产处置申请 | IT资产退还申请 | 企微审批 |
|
||||
| 8 | 办公用品申请 | 办公用品超额领用审批 | 企微审批 |
|
||||
| 9 | 会议室故障报修 | 会议室故障报修 | 企微审批 |
|
||||
| 10 | 企业应用管理 | 企业应用管理 | 企微审批 |
|
||||
| 11 | 资产变更确认 | 资产变更确认 | 企微审批 |
|
||||
| 12 | 员工IT支持与故障报修 | 员工IT支持与故障报修 | 企微审批 |
|
||||
| 13 | 终端设备网络准入 | 终端设备网络准入申请 | 运维平台 |
|
||||
| 14 | 终端设备网络准入 | 终端设备网络准入-会议室设备 | 运维平台 |
|
||||
| 15 | 活动与会议技术支持 | 大型活动技术保障申请 | 运维平台 |
|
||||
| 16 | 活动与会议技术支持 | 会议技术支持申请 | 运维平台 |
|
||||
| 17 | 公共邮箱账号申请 | 公共邮箱账号申请 | 运维平台 |
|
||||
| 18 | 员工IT支持与故障报修 | 故障报修工单 | 运维平台 |
|
||||
|
||||
---
|
||||
|
||||
### 子任务 #114：审批卡片同窗口导航改造
|
||||
|
||||
#### 背景
|
||||
|
||||
初始实现使用 `window.open(url, '_blank')` 在新标签页打开审批页面。在企微 H5 webview 内，新标签页体验不佳（用户需手动切换标签页）。改为同窗口导航 `window.location.href = url`，由企微原生提供顶部返回按钮。
|
||||
|
||||
#### 安全头分析
|
||||
|
||||
生产环境 H5 页面设置了以下安全头，阻止跨域 iframe 嵌入：
|
||||
|
||||
| 安全头 | 当前值 | 影响 |
|
||||
|--------|--------|------|
|
||||
| CSP `default-src` | `'self'`（无 `frame-src`） | 只允许同域 iframe |
|
||||
| COEP | `require-corp` | 跨域资源必须带 CORP 头 |
|
||||
| CORP | `same-origin` | H5 自身资源仅同域可加载 |
|
||||
|
||||
**结论**：不改安全头的情况下，同窗口导航（方案 A）是最佳选择。企微审批 URL 本身未设 `X-Frame-Options`，但 COEP 这一层仍会拦截 iframe。
|
||||
|
||||
#### 方案选型
|
||||
|
||||
| 方案 | 说明 | 改动量 | 风险 | 选型 |
|
||||
|------|------|--------|------|------|
|
||||
| A. 同窗口导航 | `location.href = url`，企微原生返回 | 1行 | 零 | ✅ 已采用 |
|
||||
| B. iframe嵌入 | 自定义返回/关闭覆盖层 | 需改COEP/CSP | 降低安全级别 | 待评估 |
|
||||
| C. 同源代理 | 后端代理iframe | 复杂度高 | 可能破坏JS/cookie | 不推荐 |
|
||||
|
||||
#### 代码改动
|
||||
|
||||
文件 `frontend-h5/src/components/chat/ApprovalCardModal.vue`：
|
||||
|
||||
```typescript
|
||||
// 改动1：handleSelect 中 option.url 分支
|
||||
// Before: window.open(option.url, '_blank'); showToast('已打开审批页面');
|
||||
// After: window.location.href = option.url;
|
||||
|
||||
// 改动2：handleSelect 中 fallback 匹配分支
|
||||
// Before: window.open(result.url, '_blank'); showToast('已打开审批页面');
|
||||
// After: window.location.href = result.url;
|
||||
```
|
||||
|
||||
移除两处 `showToast` 调用（页面立即跳转，toast 不可见）。
|
||||
|
||||
---
|
||||
|
||||
### 子任务 #115：企微跨应用免登录可行性研究
|
||||
|
||||
#### 背景
|
||||
|
||||
IT智能服务台 H5 与一站式运维平台同为税友集团企微下的自建应用（同一 corpid）。用户从 IT 服务台 H5 点击运维平台审批链接时，是否需要重新登录？
|
||||
|
||||
#### 结论
|
||||
|
||||
**可行**。同一 corpid 下的自建应用各自独立走 OAuth2 `snsapi_base` 静默授权：
|
||||
1. 用户从 IT 服务台 H5 点击运维平台链接
|
||||
2. 运维平台检测到未登录 → 自动发起 OAuth2 `snsapi_base` 静默授权
|
||||
3. 企微 webview 自动带上 corpid 凭证 → 运维平台后端拿到 `userid`
|
||||
4. 用户无感知完成登录
|
||||
|
||||
**前提条件**：
|
||||
- 运维平台已配置企微可信域名
|
||||
- 运维平台已实现 OAuth2 回调后端逻辑
|
||||
- 两个应用在同一企微 corpid 下
|
||||
|
||||
**企微审批 URL** (`app.work.weixin.qq.com`)：企微内置浏览器打开时自动登录，无需额外配置。
|
||||
|
||||
---
|
||||
|
||||
## 🔧 技术方案
|
||||
|
||||
### 后端 API 端点
|
||||
|
||||
| 端点 | 方法 | 说明 | 认证 |
|
||||
|------|------|------|------|
|
||||
| `/approval/templates` | GET | 返回全部18个审批模板 | 需要 |
|
||||
| `/approval/keywords` | GET | 返回12类审批关键词映射 | 需要 |
|
||||
| `/approval/detect` | POST | 意图识别（关键词预过滤 → Dify → 降级兜底） | 需要 |
|
||||
| `/approval/jump/{template_id}` | POST | 创建审批跳转 | 需要 |
|
||||
|
||||
### 意图识别三级链路
|
||||
|
||||
```
|
||||
用户消息
|
||||
↓
|
||||
1. 关键词预过滤 (_keyword_prefilter)
|
||||
命中 → 返回模板
|
||||
未命中 ↓
|
||||
2. Dify 原生 API (app-7jkRkAzvX4QM9v9SM3P8mMEO)
|
||||
返回 is_approval_request + approval_type
|
||||
置信度 ≥ 0.7 → 匹配模板
|
||||
未命中 ↓
|
||||
3. 关键词降级兜底 (_fallback_detect)
|
||||
模糊匹配 → 返回模板或 None
|
||||
```
|
||||
|
||||
### 前端组件架构
|
||||
|
||||
```
|
||||
ApprovalCardModal.vue
|
||||
├── ApprovalOption 接口 { name, icon, desc, url? }
|
||||
├── APPROVAL_OPTIONS (12类 / 17选项，每个带 url)
|
||||
├── handleSelect(option)
|
||||
│ ├── option.url 存在 → window.location.href = option.url
|
||||
│ └── fallback → 调后端 /approval/detect → /approval/jump
|
||||
├── loadKeywords() → 从后端加载关键词列表
|
||||
└── onMounted → 初始化
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 交付物清单
|
||||
|
||||
### 代码文件
|
||||
|
||||
| 文件 | 改动类型 | 说明 |
|
||||
|------|---------|------|
|
||||
| `backend/app/api/approval.py` | 修改 | 18个模板+12类关键词+映射表 |
|
||||
| `frontend-h5/src/components/chat/ApprovalCardModal.vue` | 修改 | 12类卡片+URL直跳+同窗口导航 |
|
||||
|
||||
### 数据文件
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `docs/02-产品需求/approval_templates.json` | 18个审批流程结构化数据 |
|
||||
| `docs/02-产品需求/dify_approval_system_prompt_v2.md` | Dify System Prompt v2全文 |
|
||||
| `docs/02-产品需求/外来资料/IT审批与运维流程清单.xlsx` | 原始数据源 |
|
||||
|
||||
### 文档更新
|
||||
|
||||
| 文档 | 更新内容 |
|
||||
|------|---------|
|
||||
| `docs/02-产品需求/IT智能服务台-产品需求文档PRD-v2.md` | 新增 v2.2 增量需求（P2-07~P2-11） |
|
||||
| `docs/03-技术架构/IT智能服务台-系统架构设计文档v2.md` | §15.4.3~15.4.8 扩展 |
|
||||
| `docs/10-项目管理/任务说明书/IT智能服务台-项目管理主文档.md` | 新增 #113-115 任务 |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 验证结果
|
||||
|
||||
| 验证项 | 方法 | 结果 |
|
||||
|--------|------|------|
|
||||
| 后端 API 模板列表 | `docker exec wecom_it_backend curl -s http://localhost:8000/approval/templates` | ✅ 返回18个模板 |
|
||||
| 后端 API 关键词 | `docker exec wecom_it_backend curl -s http://localhost:8000/approval/keywords` | ✅ 12类关键词映射正确 |
|
||||
| 前端 H5 页面可访问 | `docker exec wecom_it_nginx curl -s -o /dev/null -w '%{http_code}' http://localhost/h5/` | ✅ HTTP 301（正常重定向） |
|
||||
| nginx 容器文件 | `docker exec wecom_it_nginx ls /usr/share/nginx/html/h5/` | ✅ assets/ + index.html 齐全 |
|
||||
| 浏览器渲染 | agent-browser 打开 H5 URL | ✅ 登录页正常渲染，无JS报错 |
|
||||
| 生产容器状态 | `docker ps` | ✅ backend healthy / nginx running |
|
||||
| 企微内实测 | 用户手动测试 | ✅ 企微审批+运维平台审批均通过 |
|
||||
| Dify 意图识别 | 用户手动测试 | ✅ Dify v2 已发布，识别新增7种类型 |
|
||||
|
||||
---
|
||||
|
||||
## 📌 已知非阻塞项
|
||||
|
||||
| 项 | 说明 | 影响 |
|
||||
|----|------|------|
|
||||
| `import os` 未使用 | `approval.py` 中 `os.getenv` 调用被移除后，`import os` 变为未使用 | Linter警告，不影响运行 |
|
||||
| `it_device_repair` 模板 | 后端模板中有 `it_device_repair` 但前端"设备申请"下无对应选项 | 不影响功能，该模板通过意图识别仍可触发 |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 部署记录
|
||||
|
||||
| 步骤 | 操作 | 时间 |
|
||||
|------|------|------|
|
||||
| 后端文件上传 | `jms_ops.py upload` → `/tmp/approval_v2.py` | 2026-07-10 |
|
||||
| 后端替换+重启 | `cp /tmp/approval_v2.py` + `docker compose restart backend` | 2026-07-10 |
|
||||
| 前端构建 | `npm run build`（465 modules, 3.18s） | 2026-07-10 |
|
||||
| 前端打包上传 | `tar -czf` → `jms_ops.py upload` | 2026-07-10 |
|
||||
| 前端解压+重启 | `tar -xzf` + `docker compose restart nginx` | 2026-07-10 |
|
||||
| 导航改造部署 | 同上流程（第二次部署） | 2026-07-10 |
|
||||
| 临时文件清理 | `/tmp/approval_v2.py` + `/tmp/frontend-h5-dist*.tar.gz` | 2026-07-10 |
|
||||
| Dify System Prompt | 用户手动粘贴发布 | 2026-07-10 |
|
||||
|
||||
---
|
||||
|
||||
## 📎 关联文档
|
||||
|
||||
| 文档 | 位置 |
|
||||
|------|------|
|
||||
| PRD v2 | `docs/02-产品需求/IT智能服务台-产品需求文档PRD-v2.md` |
|
||||
| 架构设计 v2 | `docs/03-技术架构/IT智能服务台-系统架构设计文档v2.md` |
|
||||
| 审批模板数据 | `docs/02-产品需求/approval_templates.json` |
|
||||
| Dify Prompt v2 | `docs/02-产品需求/dify_approval_system_prompt_v2.md` |
|
||||
| 原始清单 | `docs/02-产品需求/外来资料/IT审批与运维流程清单.xlsx` |
|
||||
@@ -0,0 +1,128 @@
|
||||
# IT智能服务台 - 每日工作日报
|
||||
|
||||
> **日期**: 2026-07-11 (周六)
|
||||
> **汇报人**: 宋献 (Simon)
|
||||
> **版本快照**: `v2026.07.11-evening` (待打标签)
|
||||
|
||||
---
|
||||
|
||||
## TL;DR
|
||||
|
||||
今日完成 **13 项工作**：9 项已部署上线、3 项代码完成待部署、2 项需求文档确认。涉及前端 3 端（坐席/H5/终端）、后端 15+ 文件、测试 61+ 用例全部通过。
|
||||
|
||||
---
|
||||
|
||||
## 一、已部署上线 (9项)
|
||||
|
||||
| # | 功能 | 端 | 关键文件 | 验证状态 |
|
||||
|---|------|----|---------|---------|
|
||||
| 1 | 代办事项真实数据源集成 | 后端+坐席 | `todo_source_service.py` / `itsm_service.py` / `todo_aggregator_service.py` / `TodoPanel.vue` | ✅ sxn 2条审批正确返回 |
|
||||
| 2 | H5 Logo样式统一 | H5 | `Login.vue` / `ChatPanel.vue` / `index.html` | ✅ HTTP 200 + 截图 |
|
||||
| 3 | 视频引导页修复 | H5 | `VideoIntro.vue` / `router/index.ts` | ✅ HTTP 200 / 6.3MB |
|
||||
| 4 | 坐席端Login样式+绿色背景 | 坐席 | `Login.vue` | ✅ 服务器CSS验证 |
|
||||
| 5 | H5 UI调整-头像恢复 | H5 | `ChatPanel.vue` | ✅ JS内容验证 |
|
||||
| 6 | 坐席端v9 Vue版本修复 | 坐席 | `main.ts` / `api/index.ts` | ✅ Playwright 0错误 |
|
||||
| 7 | 截图按钮修复v10 | 坐席 | `ReplyBox.vue` / `ScreenCapture.vue` | ✅ 服务器JS hash确认 |
|
||||
| 8 | 扫码样式恢复+登录跳转 | 坐席+H5 | `Login.vue` (双端) | ✅ 截图验证 |
|
||||
| 9 | H5截图快捷键提示 | H5 | `InputBar.vue` | ✅ HTTP 200 + JS验证 |
|
||||
|
||||
### 关键 Bug 修复链
|
||||
|
||||
#### 代办事项-企微审批API (8个问题)
|
||||
1. `WECOM_APPROVAL_SECRET` 未注入容器 → docker-compose.yml 添加环境变量
|
||||
2. Redis 无密码认证 → Redis command 添加 `--requirepass`
|
||||
3. Docker bind mount `./app:/app/app` 丢失 → 恢复卷挂载
|
||||
4. 企微 `getapprovaldata` API 废弃(404) → 改用 `getapprovalinfo` 新API
|
||||
5. `token_manager.py` `.decode()` 报错 → `isinstance` 安全检查
|
||||
6. errcode=60020 IP白名单 → 改用 `TokenManager`
|
||||
7. errcode=301025 invalid filter → 代码层过滤替代API层过滤
|
||||
8. `_extract_current_approver` 字段名全错 → `sp_status` / `details[].approver.userid`
|
||||
|
||||
#### 坐席端 v9 TypeError
|
||||
- **根因**: pnpm 严格模式下 Vue 版本不一致 (3.5.35 vs 3.5.39)，导致 `ElMessage._context` 上下文丢失
|
||||
- **修复**: 删除 node_modules + npm 重装 + 显式设置 `ElMessage._context = app._context`
|
||||
|
||||
#### 截图按钮 v10
|
||||
- **根因**: `await requestFullscreen()` 消耗了 user gesture，`getDisplayMedia()` 静默失败
|
||||
- **修复**: 移除 `requestFullscreen()` 调用，`getDisplayMedia()` 同步调用
|
||||
|
||||
---
|
||||
|
||||
## 二、代码完成待部署 (3项)
|
||||
|
||||
| # | 功能 | 文件数 | 测试 | 部署方式 |
|
||||
|---|------|--------|------|---------|
|
||||
| 1 | 知识迭代3个Bug修复 | 3个.py文件 | 21/21通过 | `docker compose restart backend` |
|
||||
| 2 | 会议室预定-小鱼易联终端 | 40文件 | 40/40通过 | 全栈部署（DB迁移+后端+终端前端） |
|
||||
| 3 | IT资产升级审批推送 | 3文件 | 待测 | `docker compose restart backend` |
|
||||
|
||||
### 知识迭代 Bug 修复详情
|
||||
- **#8 P1**: `knowledge_iteration.py:168` 新增 `POST /suggestions` 端点（405→200）
|
||||
- **#7 P2**: `neo4j_client.py:526` Cypher `CREATE`→`MERGE`（关系创建幂等化）
|
||||
- **#6 P2**: `main.py:133` 新增 `expire_pending_suggestions()` + APScheduler 定时任务（interval=1h）
|
||||
|
||||
### 会议室预定系统详情
|
||||
- **后端**: 8新建 + 6修改（config/models/schemas/services/api/ws/router/alembic 050）
|
||||
- **终端前端**: 22新建（Vue3+Vite+Tailwind+Pinia+TS，深色主题大屏）
|
||||
- **H5端**: 4新建/修改（MeetingroomView + API + 路由 + ChatPanel入口）
|
||||
- **架构**: 企微API唯一数据源 + Redis缓存 + WS三连接池 + 终端绑定本地存储
|
||||
|
||||
---
|
||||
|
||||
## 三、需求文档确认 (2项)
|
||||
|
||||
| # | 文档 | 状态 | 预估工期 |
|
||||
|---|------|------|---------|
|
||||
| 1 | 坐席端AI辅助消息框-PRD | 用户已确认全选4项功能 | ~8天 |
|
||||
| 2 | 均席端布局优化建议 v2.0 | 用户已确认方案 | ~7天 |
|
||||
|
||||
### AI辅助消息框 (4项新功能)
|
||||
1. 实时自动补齐（内联幽灵文字，Tab接受，debounce 800ms）
|
||||
2. 语气调整（专业/友好/简洁，选中文字后一键改写）
|
||||
3. 文字润色（扩写/压缩/纠错，弹出精修面板）
|
||||
4. 智能改写（3个备选版本）
|
||||
|
||||
### 布局优化 v2.0 (5项核心改造)
|
||||
1. 工具栏单行左右分区（常规绿色/AI琥珀色）
|
||||
2. 回复建议区（AI推荐+快速回复，选中后自动缩回）
|
||||
3. 右栏改为AI训练区（~250px弹性）
|
||||
4. 中栏折叠优化（UserInfoBar+TroubleshootBar默认折叠）
|
||||
5. 左右栏瘦身（280→260 / 320→300，中栏+40px）
|
||||
|
||||
---
|
||||
|
||||
## 四、今日文档产出
|
||||
|
||||
| 文档 | 路径 |
|
||||
|------|------|
|
||||
| 代办事项集成PRD | `docs/02-产品需求/prd_todo_integration.md` |
|
||||
| AI辅助消息框PRD | `docs/02-产品需求/坐席端AI辅助消息框-PRD.md` |
|
||||
| 布局优化建议v2.0 | `docs/02-产品需求/坐席端布局优化建议.md` |
|
||||
| 会议室预定PRD | `docs/02-产品需求/会议室预定-小鱼易联终端-PRD.md` |
|
||||
| 会议室预定架构设计 | `docs/03-技术架构/会议室预定-小鱼易联终端-架构设计.md` |
|
||||
| 知识库迭代技术方案 | `docs/03-技术架构/增量设计-知识库迭代与痛点缓解-20260711.md` |
|
||||
| 知识库迭代原型设计 | `docs/01-产品设计/知识库迭代-未实现功能原型设计-20260711.md` |
|
||||
| CHANGELOG更新 | `CHANGELOG.md` |
|
||||
| 本日报 | `docs/10-项目管理/日报-2026-07-11.md` |
|
||||
|
||||
---
|
||||
|
||||
## 五、测试覆盖
|
||||
|
||||
| 测试文件 | 用例数 | 状态 |
|
||||
|---------|--------|------|
|
||||
| `test_todo_integration.py` | 40 | ✅ 全部通过 |
|
||||
| `test_meetingroom.py` | 40 | ✅ 全部通过 |
|
||||
| `test_bugfix_ki_suggestions.py` | 21 | ✅ 全部通过 |
|
||||
| `test_asset_approval_urge.py` | - | 待运行 |
|
||||
|
||||
---
|
||||
|
||||
## 六、遗留事项
|
||||
|
||||
1. ⏳ ITSM 工单列表 API 待抓包（app_id/app_secret 待申请）
|
||||
2. ⏳ 企微审批查询时间范围 7天→30天（API限制31天）
|
||||
3. ⏳ `itsm_service.py:33` httpx.Timeout 缺 write/pool 参数（预存Bug，非本次引入）
|
||||
4. ⏳ 会议室预定系统待部署（需确认部署窗口）
|
||||
5. ⏳ 知识迭代Bug修复待部署（低风险，随时可部署）
|
||||
6. ⏳ IT资产升级审批推送待部署+测试
|
||||
Reference in New Issue
Block a user