wecom_it_smart_desk/docs/10-项目管理/任务说明书-01-新开发任务.md

# 新开发任务说明书 (v0.7.2+)

> **版本**: v1.2 | **日期**: 2026-07-04 | **状态**: 🔴 进行中

---

## 📋 基本信息

| 项目 | 内容 |
|------|------|
| **任务名称** | v0.7.2+ 新功能开发 |
| **任务ID** | #90 等 |
| **优先级** | 🔴P0 > 🟠P1 |
| **类型** | 功能开发 / Bug修复 / 安全加固 / 文档完善 |
| **状态** | 进行中 / 延后 |
| **负责人** | 宋献 + Claude |
| **创建日期** | 2026-07-04 |

---

## 📥 输入项来源

### 产品需求
| 来源文档 | 相关章节 | 说明 |
|----------|----------|------|
| `02-产品需求/02-产品需求文档PRD-v1.2-20260704.md` | §4.5 坐席/管理员登录流程 | 登录逻辑调整 |
| `02-产品需求/02-产品需求文档PRD-v1.2-20260704.md` | §9 术语与图标规范 | 统一术语 |
| `02-产品需求/product-产品/v0.7.2-backlog-candidate-2026-06-24.md` | backlog项 | 未来功能候选 |

### 技术架构
| 来源文档 | 相关章节 | 说明 |
|----------|----------|------|
| `03-技术架构/02-技术方案/技术方案-消息功能详细设计.md` | - | 消息功能设计 |
| `03-技术架构/02-技术方案/技术方案-摇人协作.md` | - | 摇人功能设计 |
| `03-技术架构/02-技术方案/技术方案-邀请功能.md` | - | 邀请功能设计 |
| `03-技术架构/01-ADRs-架构决策/ADR-XXX.md` | - | 架构决策记录 |

### 原型设计
| 来源文档 | 页面 | 说明 |
|----------|------|------|
| `04-原型设计/prototypes-原型图/agent-workspace-v5_4.html` | 坐席工作台 | v5.4 UI |
| `04-原型设计/prototypes-原型图/h5-user-wecom-style-v2-desktop.html` | H5用户端 | v2 桌面版 |
| `04-原型设计/prototypes-原型图/admin-dashboard-v1.html` | 管理后台 | v1 UI |

### 项目看板
| 来源 | 任务名 | 说明 |
|------|--------|------|
| `05-项目状态看板/01-项目状态看板.md` | P0任务 | 当前进行中任务 |

---

## 📢 需求变更说明（2026-07-04）

根据 PRD v1.5 更新：
- **用户端**：强制企微内嵌打开，OAuth2 静默授权
- **坐席/管理端**：浏览器直接打开，无需经过企微工作台，支持账号密码+OTP认证

> **核心变更**：坐席/管理员可直接在浏览器打开登录页面，不再需要经过 Portal

---

## 🎯 当前优先级（用户确认）

> **用户确认优先级**：坐席/管理直接登录 > 用户端企微内嵌 > 其他任务

---

## 🆕 新功能开发任务

---

### 任务 1: 坐席/管理端直接登录（🔴 最优先）

| 项目 | 内容 |
|------|------|
| **ID** | #90 |
| **优先级** | 🔴 P0 |
| **类型** | 功能开发 / 登录流程 |
| **描述** | 坐席/管理端浏览器直接打开登录页，智能检测企微登录状态，提供三种登录方式 |
| **状态** | 开发中（v1.8完成） |
| **估时** | 4小时（开发+测试） |

#### 输入项来源
- **产品需求**: PRD v1.5 §4.5 登录流程调整
- **原型设计**: admin-dashboard-v1.html 登录页面
- **项目看板**: P0任务

#### 输出成果要求

| # | 交付物 | 类型 |
|---|--------|------|
| 1 | 后端登录API (`/api/agents/login`) | 代码 |
| 2 | 坐席端登录页面 (v1.8) | 代码 |
| 3 | 管理端登录页面 | 代码 |
| 4 | OTP验证逻辑 | 代码 |
| 5 | 企微客户端检测 (JS-SDK/wecom://) | 代码 |
| 6 | 更新API文档 | 文档 |

#### 验证方式

| 验证项 | 验证方法 | 预期结果 |
|--------|----------|-----------|
| 坐席登录 | 手动测试 | 账号密码+OTP登录成功 |
| 管理登录 | 手动测试 | 账号密码+OTP登录成功 |
| 权限控制 | 越权测试 | 坐席无法访问管理端 |
| 错误处理 | 异常输入 | 正确提示 |

#### 完成标准

- [x] 后端登录API开发完成
- [x] 坐席端登录页面开发完成
- [x] 管理端登录页面开发完成
- [x] OTP验证正常工作
- [x] 企微客户端检测功能 (v1.8)
- [ ] 部署测试
- [ ] 代码通过 Code Review

---

### 任务 2: 收窄 IP 白名单安全加固（⏸️ 延后）

| 项目 | 内容 |
|------|------|
| **ID** | #48 |
| **优先级** | P1 → ⏸️ 延后 |
| **类型** | 安全加固 |
| **描述** | 当前 `/api/admin/` + `/itadmin/` 使用 `allow 0.0.0.0/0` 临时全开，需收窄到精确代理 IP |
| **阻塞原因** | 需网络组确认真实代理 IP 段（WAF/堡垒机/CDN 出口 IP） |
| **估时** | 1小时（改 nginx + reload + 验证） |

#### 输入项来源
- **产品需求**: 安全合规要求
- **技术架构**: nginx 配置
- **项目看板**: 安全加固任务

#### 输出成果要求

| # | 交付物 | 类型 |
|---|--------|------|
| 1 | nginx IP白名单配置 | 配置 |
| 2 | 安全验证报告 | 文档 |

#### 验证方式
- [ ] 内部IP可访问
- [ ] 外部IP被拦截

#### 完成标准
- [ ] nginx 配置已更新
- [ ] 已验证内网访问正常
- [ ] 已验证外网无法访问管理端

---

### 任务 3: 修复部署脚本文件覆盖问题

| 项目 | 内容 |
|------|------|
| **ID** | #73 |
| **优先级** | P1 |
| **类型** | 部署优化 |
| **描述** | `yes | cp -f` 路径问题导致部署时文件偶尔没真正覆盖 |
| **根因** | `deploy-staging/` bind mount + RO 双重坑 |
| **估时** | 2小时（改 deploy 脚本用 rsync --checksum） |

#### 输入项来源
- **技术架构**: 部署流程文档
- **项目看板**: 部署优化任务

#### 输出成果要求

| # | 交付物 | 类型 |
|---|--------|------|
| 1 | 优化后的部署脚本 | 脚本 |
| 2 | 部署验证测试 | 测试 |

#### 验证方式
- [ ] 增量部署测试通过
- [ ] 文件覆盖生效

#### 完成标准
- [ ] 部署脚本已优化
- [ ] 验证测试通过

---

### 任务 4: 排查流程图文档化

| 项目 | 内容 |
|------|------|
| **ID** | #86 |
| **优先级** | P1 |
| **类型** | 文档完善 |
| **描述** | 把 Mermaid 流程图从代码里剥离成可读文档 |
| **估时** | 3小时 |

#### 输入项来源
- **原型设计**: 排查流程原型
- **技术架构**: 代码中的 Mermaid 图表
- **项目看板**: 文档完善任务

#### 输出成果要求

| # | 交付物 | 类型 |
|---|--------|------|
| 1 | 排查流程图文档 | 文档 |
| 2 | 更新架构图索引 | 文档 |

#### 验证方式
- [ ] 文档可读性检查

#### 完成标准
- [ ] 流程图文档完整
- [ ] 索引已更新

---

### 任务 5: pytest 测试失败修复

| 项目 | 内容 |
|------|------|
| **ID** | #92 |
| **优先级** | P1 |
| **类型** | 测试修复 |
| **描述** | 修复 v0.7.1-dev 引入的 pytest 失败（当前 64 个 pre-existing 失败） |
| **根因** | conftest.py SQLite StaticPool 性能 + Windows + utf-8 + asyncio loop 顺序问题 |
| **估时** | 4小时 |

#### 输入项来源
- **项目看板**: 测试修复任务

#### 输出成果要求

| # | 交付物 | 类型 |
|---|--------|------|
| 1 | 修复后的 conftest.py | 代码 |
| 2 | 测试通过报告 | 文档 |

#### 验证方式
- [ ] pytest 运行通过

#### 完成标准
- [ ] 所有测试通过

---

### 任务 6: 敏感词检测 + 语气优化（⏸️ 延后）

| 项目 | 内容 |
|------|------|
| **ID** | #81 |
| **优先级** | P0 → ⏸️ 延后 |
| **类型** | 功能开发 |
| **描述** | v0.7.1 开发内容，文本安全过滤 |
| **阻塞原因** | 需确认企业敏感词库来源 |
| **估时** | 待评估 |

#### 输入项来源
- **产品需求**: PRD 安全要求

#### 输出成果要求

| # | 交付物 | 类型 |
|---|--------|------|
| 1 | 敏感词过滤服务 | 代码 |
| 2 | 敏感词库配置 | 配置 |

#### 验证方式
- [ ] 敏感词拦截测试

#### 完成标准
- [ ] 敏感词库已配置
- [ ] 过滤功能正常

---

## 📊 任务统计

| 优先级 | 数量 | 估时 |
|--------|------|------|
| P0 | 2 | 待评估 |
| P1 | 5 | ~10小时 |

---

## ✅ 完成标准总览

### 代码规范
- [ ] 遵循项目代码规范
- [ ] 通过 ESLint / Pylint 检查

### 测试要求
- [ ] 单元测试覆盖率 ≥ 80%
- [ ] 功能测试通过
- [ ] 安全测试通过

### 文档要求
- [ ] 相关技术文档已更新
- [ ] API 接口文档已更新

### 交付要求
- [ ] 代码合入主干分支
- [ ] 通过 Code Review
- [ ] 任务看板已更新

---

## 📈 变更记录

| 日期 | 变更内容 | 变更人 |
|------|----------|--------|
| 2026-07-04 | 创建任务说明书 | Claude |
| 2026-07-04 | 更新登录逻辑说明 | Claude |
| 2026-07-04 | 添加模板化字段 | Claude |