# 企微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，先读这个文件就懂上下文。