chore: 整理项目结构，清理归档文件，更新部署配置
This commit is contained in:
Simon
@@ -0,0 +1,110 @@
|
||||
# 任务总索引
|
||||
|
||||
> **版本**: 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 |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 相关文档
|
||||
|
||||
| 类别 | 文档 | 位置 |
|
||||
|------|------|------|
|
||||
| 项目概览 | 项目总览与部署手册 | `01-项目总览/` |
|
||||
| 产品需求 | PRD需求文档 | `02-产品需求/` |
|
||||
| 技术架构 | 技术架构设计 | `03-技术架构/` |
|
||||
| 测试质量 | E2E验收清单 | `06-测试质量/` |
|
||||
| 部署运维 | 部署指南 | `09-部署运维/` |
|
||||
|
||||
---
|
||||
|
||||
## 📅 版本历史
|
||||
|
||||
| 版本 | 日期 | 变更 |
|
||||
|------|------|------|
|
||||
| v1.1 | 2026-07-04 | 新增产品需求变更、技术架构变更、文档管理变更 |
|
||||
| v1.0 | 2026-07-04 | 初始版本，整合任务管理文档体系 |
|
||||
@@ -0,0 +1,907 @@
|
||||
# 智能IT支持服务台 — 风险跟踪表
|
||||
|
||||
**最后更新**: 2026-06-14 18:30
|
||||
**维护人**: 宋献 + Claude 评审协作
|
||||
|
||||
> 📌 2026-06-14 评审新增 13 项（6 P0 + 4 P1 + 3 P2），详见第九节。
|
||||
> 统计表保持 6-13 数据，**第九节有独立小计**。
|
||||
|
||||
---
|
||||
|
||||
## 一、风险总览
|
||||
|
||||
| 级别 | 数量 | 已处理 | 待处理 | 处理率 |
|
||||
|------|------|--------|--------|--------|
|
||||
| 🔴 严重 (Critical) | 4 | 4 | 0 | **100%** |
|
||||
| 🟠 高 (High) | 6 | 5 | 1 | **83%** |
|
||||
| 🟡 中 (Medium) | 7 | 4 | 3 | **57%** |
|
||||
| 🔵 低 (Low) | 5 | 3 | 2 | **60%** |
|
||||
| **合计** | **22** | **16** | **6** | **73%** |
|
||||
|
||||
---
|
||||
|
||||
## 二、严重风险 (Critical)
|
||||
|
||||
### CR-1：`dependencies.py` 覆盖导致依赖注入链断裂
|
||||
|
||||
**状态**: ✅ 已验证（无需修复）
|
||||
**风险级别**: 🔴 严重
|
||||
**处理难度**: ⚠️ 高
|
||||
**发现日期**: 2026-06-13
|
||||
**修复日期**: 2026-06-13
|
||||
|
||||
**问题描述**：
|
||||
当前的 `dependencies.py` 是完全重写的，可能缺少原始文件中的共享服务依赖注入函数。
|
||||
|
||||
**验证结果**：
|
||||
经检查，当前 `dependencies.py` 文件已包含所有必要的函数：
|
||||
- `get_redis()` — Redis 连接池管理
|
||||
- `dep_redis()` — Redis 客户端依赖注入
|
||||
- `dep_wecom_service()` — 企微服务依赖注入
|
||||
- `dep_ai_handler()` — AI 处理器依赖注入
|
||||
- `dep_wingman_service()` — Wingman 服务依赖注入
|
||||
- `get_shared_redis()` — 同步获取 Redis
|
||||
- `get_shared_wecom_service()` — 同步获取企微服务
|
||||
- `get_shared_ai_handler()` — 同步获取 AI 处理器
|
||||
- `init_shared_services()` — 应用启动初始化
|
||||
- `cleanup_shared_services()` — 应用关闭清理
|
||||
|
||||
**结论**：
|
||||
文件完整，无需恢复。依赖注入链正常。
|
||||
|
||||
---
|
||||
|
||||
### CR-2：Token 格式不兼容导致认证混乱
|
||||
|
||||
**状态**: ✅ 已修复
|
||||
**风险级别**: 🔴 严重
|
||||
**处理难度**: ⚠️ 中
|
||||
**发现日期**: 2026-06-13
|
||||
**修复日期**: 2026-06-13
|
||||
|
||||
**问题描述**：
|
||||
系统存在三种 Token 格式同时运行，可能导致认证混乱。
|
||||
|
||||
**修复方案**：
|
||||
1. `TokenService.get_user_info()` 支持三种格式读取：
|
||||
- 统一格式：`user:token:{token}` → JSON 对象
|
||||
- 旧格式1：`employee:token:{token}` → employee_id
|
||||
- 旧格式2：`agent:token:{token}` → user_id
|
||||
|
||||
2. `TokenService.create_token()` 同时写入统一格式和旧格式：
|
||||
- 根据 `login_source` 决定写入 `employee:token:` 或 `agent:token:`
|
||||
|
||||
3. `TokenService.switch_role()` 更新统一格式，旧格式只存储 employee_id 不需要更新
|
||||
|
||||
**修改文件**：
|
||||
- `backend/app/services/token_service.py`
|
||||
|
||||
---
|
||||
|
||||
### CR-3：Portal API 使用旧认证中间件
|
||||
|
||||
**状态**: ✅ 已修复
|
||||
**风险级别**: 🔴 严重
|
||||
**处理难度**: ⚠️ 低
|
||||
**发现日期**: 2026-06-13
|
||||
**修复日期**: 2026-06-13
|
||||
|
||||
**问题描述**：
|
||||
Portal API 使用 `get_current_agent` 作为认证依赖，不支持新的统一格式。
|
||||
|
||||
**修复方案**：
|
||||
1. 修改 `portal.py` 使用 `get_current_user` 替代 `get_current_agent`
|
||||
2. 修改 `admin_roles.py` 使用 `get_current_user` 替代 `get_current_agent`
|
||||
3. 更新所有函数签名和参数名（`agent` → `current_user`）
|
||||
4. 更新所有日志记录（`agent.user_id` → `current_user.employee_id`）
|
||||
|
||||
**修改文件**：
|
||||
- `backend/app/api/portal.py`
|
||||
- `backend/app/api/admin_roles.py`
|
||||
|
||||
---
|
||||
|
||||
### CR-4：慢启动时 Token 创建失败导致登录异常
|
||||
|
||||
**状态**: ✅ 已修复
|
||||
**风险级别**: 🔴 严重
|
||||
**处理难度**: ⚠️ 中
|
||||
**发现日期**: 2026-06-13
|
||||
**修复日期**: 2026-06-13
|
||||
|
||||
**问题描述**：
|
||||
坐席登录时每次创建新的 Redis 连接，并在 finally 中关闭，可能导致连接泄漏。
|
||||
|
||||
**修复方案**：
|
||||
1. 使用共享 Redis 连接（从 `get_redis()` 获取）
|
||||
2. 移除 finally 中的连接关闭代码（由连接池管理）
|
||||
3. 简化异常处理逻辑
|
||||
|
||||
**修改文件**：
|
||||
- `backend/app/api/agents.py`
|
||||
|
||||
---
|
||||
|
||||
## 三、高风险 (High)
|
||||
|
||||
### H-6：角色映射 SQL 注入风险
|
||||
|
||||
**状态**: ✅ 已修复
|
||||
**风险级别**: 🟠 高
|
||||
**处理难度**: ⚠️ 低
|
||||
**发现日期**: 2026-06-13
|
||||
**修复日期**: 2026-06-13
|
||||
|
||||
**问题描述**：
|
||||
`_get_tag_names_by_ids()` 方法直接调用企微 API，没有对返回的 `tag_names` 进行验证。
|
||||
|
||||
**修复方案**：
|
||||
1. 添加 `_validate_tag_name()` 方法验证标签名称
|
||||
2. 验证规则：长度限制 50 字符，过滤禁止的特殊字符
|
||||
3. 获取标签时过滤不安全的标签名称
|
||||
|
||||
**修改文件**：
|
||||
- `backend/app/services/role_mapping_service.py`
|
||||
|
||||
---
|
||||
|
||||
### H-7：角色分配权限验证不完整
|
||||
|
||||
**状态**: ✅ 已修复
|
||||
**风险级别**: 🟠 高
|
||||
**处理难度**: ⚠️ 低
|
||||
**发现日期**: 2026-06-13
|
||||
**修复日期**: 2026-06-13
|
||||
|
||||
**问题描述**：
|
||||
管理员可以给任何人分配任何角色，包括自己。
|
||||
|
||||
**修复方案**：
|
||||
1. 禁止管理员给自己分配角色（assign_role 添加检查）
|
||||
2. 禁止管理员撤销自己的角色（revoke_role 添加检查）
|
||||
3. 操作审计日志（通过 logger.info 记录）
|
||||
|
||||
**修改文件**：
|
||||
- `backend/app/api/admin_roles.py`
|
||||
|
||||
---
|
||||
|
||||
### H-8：映射规则缺少输入验证
|
||||
|
||||
**状态**: ✅ 已修复
|
||||
**风险级别**: 🟠 高
|
||||
**处理难度**: ⚠️ 低
|
||||
**发现日期**: 2026-06-13
|
||||
**修复日期**: 2026-06-13
|
||||
|
||||
**问题描述**：
|
||||
`create_mapping_rule()` 接口没有验证输入参数。
|
||||
|
||||
**修复方案**：
|
||||
1. 添加 `source_type` 枚举验证（`wecom_tag`/`ehr_position`）
|
||||
2. 添加 `role_name` 枚举验证（`user`/`agent`/`admin`）
|
||||
3. 添加 `source_value` 特殊字符过滤
|
||||
4. 限制 `priority` 范围（0-100）
|
||||
|
||||
**修改文件**：
|
||||
- `backend/app/schemas/role.py`
|
||||
|
||||
---
|
||||
|
||||
### H-9：Token 未绑定 IP/设备
|
||||
|
||||
**状态**: ⚠️ 待处理
|
||||
**风险级别**: 🟠 高
|
||||
**处理难度**: ⚠️ 中
|
||||
**发现日期**: 2026-06-13
|
||||
|
||||
**问题描述**：
|
||||
Token 没有绑定 IP 地址或设备指纹，任何获取到 Token 的人都可以使用。
|
||||
|
||||
**处理建议**：
|
||||
1. 绑定 IP 地址（可选，影响移动场景）
|
||||
2. 绑定设备指纹（可选，需要前端配合）
|
||||
3. 敏感操作要求二次验证
|
||||
|
||||
**关联开发任务**：
|
||||
- Token 安全加固
|
||||
|
||||
---
|
||||
|
||||
### H-10：管理端 API 无 IP 白名单
|
||||
|
||||
**状态**: ✅ 已修复
|
||||
**风险级别**: 🟠 高
|
||||
**处理难度**: ⚠️ 低
|
||||
**发现日期**: 2026-06-13
|
||||
**修复日期**: 2026-06-13
|
||||
|
||||
**问题描述**：
|
||||
管理端角色管理 API 没有 IP 白名单限制。
|
||||
|
||||
**修复方案**：
|
||||
1. 在 Nginx 层添加 IP 白名单（/itadmin/ 和 /api/admin/ 路径）
|
||||
2. 允许内网网段：10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、10.212.0.0/16
|
||||
|
||||
**修改文件**：
|
||||
- `deploy-server/nginx/nginx.conf`
|
||||
|
||||
---
|
||||
|
||||
### H-11：WebSocket Token 通过 URL 参数传递
|
||||
|
||||
**状态**: ⚠️ 待处理
|
||||
**风险级别**: 🟠 高
|
||||
**处理难度**: ⚠️ 中
|
||||
**发现日期**: 2026-06-13
|
||||
|
||||
**问题描述**：
|
||||
WebSocket 连接的 Token 通过 URL 参数传递，会被记录在访问日志中。
|
||||
|
||||
**处理建议**：
|
||||
1. 改为通过 WebSocket 握手头传递
|
||||
2. 或通过第一条消息传递
|
||||
3. 在 Nginx 中对 `/ws/` 路径关闭访问日志
|
||||
|
||||
**关联开发任务**：
|
||||
- WebSocket 安全加固
|
||||
|
||||
---
|
||||
|
||||
## 四、中等风险 (Medium)
|
||||
|
||||
### M-6：旧 Token 迁移策略缺失
|
||||
|
||||
**状态**: ⚠️ 待处理
|
||||
**风险级别**: 🟡 中
|
||||
**处理难度**: ⚠️ 中
|
||||
**发现日期**: 2026-06-13
|
||||
|
||||
**问题描述**：
|
||||
没有从旧格式迁移到新格式的策略。
|
||||
|
||||
**处理建议**：
|
||||
1. 实现 Token 自动迁移（访问旧格式 Token 时自动转换为新格式）
|
||||
2. 设置迁移期限（如 30 天后旧 Token 失效）
|
||||
|
||||
**关联开发任务**：
|
||||
- Token 迁移工具
|
||||
|
||||
---
|
||||
|
||||
### M-7：角色缓存策略缺失
|
||||
|
||||
**状态**: ⚠️ 待处理
|
||||
**风险级别**: 🟡 中
|
||||
**处理难度**: ⚠️ 低
|
||||
**发现日期**: 2026-06-13
|
||||
|
||||
**问题描述**：
|
||||
每次请求都从数据库查询用户角色，没有缓存策略。
|
||||
|
||||
**处理建议**：
|
||||
1. 添加 Redis 缓存（TTL 5-10 分钟）
|
||||
2. 角色变更时主动失效缓存
|
||||
|
||||
**关联开发任务**：
|
||||
- 角色缓存实现
|
||||
|
||||
---
|
||||
|
||||
### M-8：API 速率限制未覆盖所有端点
|
||||
|
||||
**状态**: ⚠️ 待处理
|
||||
**风险级别**: 🟡 中
|
||||
**处理难度**: ⚠️ 低
|
||||
**发现日期**: 2026-06-13
|
||||
|
||||
**问题描述**：
|
||||
只覆盖了登录端点，其他 API 端点没有速率限制。
|
||||
|
||||
**处理建议**：
|
||||
1. 为所有 API 端点添加速率限制
|
||||
2. 分级限制：登录 10/min，普通 API 60/min，管理 API 30/min
|
||||
|
||||
**关联开发任务**：
|
||||
- 速率限制完善
|
||||
|
||||
---
|
||||
|
||||
### M-9：异常信息泄露
|
||||
|
||||
**状态**: ✅ 已修复
|
||||
**风险级别**: 🟡 中
|
||||
**处理难度**: ⚠️ 低
|
||||
**发现日期**: 2026-06-13
|
||||
**修复日期**: 2026-06-13
|
||||
|
||||
**问题描述**：
|
||||
异常处理返回 `f"服务器内部错误: {str(exc)}"`，可能泄露内部信息。
|
||||
|
||||
**修复方案**：
|
||||
1. 异常处理器返回通用错误消息："服务器内部错误，请稍后重试或联系管理员"
|
||||
2. 中间件返回通用错误消息（同上）
|
||||
3. 详细异常信息仅记录到日志
|
||||
|
||||
**修改文件**：
|
||||
- `backend/app/main.py`
|
||||
|
||||
---
|
||||
|
||||
### M-10：日志脱敏不足
|
||||
|
||||
**状态**: ✅ 已修复
|
||||
**风险级别**: 🟡 中
|
||||
**处理难度**: ⚠️ 低
|
||||
**发现日期**: 2026-06-13
|
||||
**修复日期**: 2026-06-13
|
||||
|
||||
**问题描述**：
|
||||
日志中包含 `user_id`、`employee_id` 等敏感信息。
|
||||
|
||||
**修复方案**：
|
||||
1. 添加 `_mask_sensitive_data()` 脱敏函数
|
||||
2. 对 employee_id 进行脱敏处理（保留前3位，如 "abc***def"）
|
||||
3. 已处理：role_mapping_service.py、admin_roles.py
|
||||
|
||||
**修改文件**：
|
||||
- `backend/app/services/role_mapping_service.py`
|
||||
- `backend/app/api/admin_roles.py`
|
||||
|
||||
---
|
||||
|
||||
### M-11：数据库密码弱密码
|
||||
|
||||
**状态**: ✅ 已修复
|
||||
**风险级别**: 🟡 中
|
||||
**处理难度**: ⚠️ 低
|
||||
**发现日期**: 2026-06-13
|
||||
**修复日期**: 2026-06-13
|
||||
|
||||
**问题描述**：
|
||||
PostgreSQL 密码使用 `wecom_secret` 或 `wecom_secret_2026`，强度不足。
|
||||
|
||||
**修复方案**：
|
||||
1. `.env.example` 中使用强密码占位符（`your-strong-postgres-password`）
|
||||
2. 添加注释说明密码要求（≥16位，含大小写字母+数字+特殊字符）
|
||||
3. 生产环境通过 `.env` 文件注入强密码
|
||||
|
||||
**修改文件**：
|
||||
- `.env.example`
|
||||
|
||||
---
|
||||
|
||||
### M-12：Redis 无密码保护
|
||||
|
||||
**状态**: ✅ 已修复
|
||||
**风险级别**: 🟡 中
|
||||
**处理难度**: ⚠️ 低
|
||||
**发现日期**: 2026-06-13
|
||||
**修复日期**: 2026-06-13
|
||||
|
||||
**问题描述**：
|
||||
Redis 连接无密码认证。
|
||||
|
||||
**修复方案**：
|
||||
1. Docker Compose 中添加 `--requirepass` 参数
|
||||
2. `.env.example` 中添加 `REDIS_PASSWORD` 配置项
|
||||
3. 更新 `REDIS_URL` 格式为 `redis://:password@redis:6379/0`
|
||||
4. 健康检查使用密码认证
|
||||
|
||||
**修改文件**：
|
||||
- `deploy-server/docker-compose.yml`
|
||||
- `.env.example`
|
||||
|
||||
---
|
||||
|
||||
## 五、低风险 (Low)
|
||||
|
||||
### L-5：Nginx 缺少 CSP 和 HSTS 安全头
|
||||
|
||||
**状态**: ✅ 已修复
|
||||
**风险级别**: 🔵 低
|
||||
**处理难度**: ⚠️ 低
|
||||
**发现日期**: 2026-06-13
|
||||
**修复日期**: 2026-06-13
|
||||
|
||||
**修复方案**：
|
||||
在 Nginx 配置中添加以下安全头：
|
||||
```nginx
|
||||
add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:;" always;
|
||||
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
|
||||
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
|
||||
```
|
||||
|
||||
**修改文件**：
|
||||
- `deploy-server/nginx/nginx.conf`
|
||||
|
||||
---
|
||||
|
||||
### L-6：CORS 配置过于宽松
|
||||
|
||||
**状态**: ✅ 已修复
|
||||
**风险级别**: 🔵 低
|
||||
**处理难度**: ⚠️ 低
|
||||
**发现日期**: 2026-06-13
|
||||
**修复日期**: 2026-06-13
|
||||
|
||||
**修复方案**：
|
||||
```python
|
||||
allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
|
||||
allow_headers=["Authorization", "Content-Type", "X-Employee-Id"],
|
||||
```
|
||||
|
||||
**修改文件**：
|
||||
- `backend/app/main.py`
|
||||
|
||||
---
|
||||
|
||||
### L-7：坐席列表 API 无认证
|
||||
|
||||
**状态**: ✅ 已修复
|
||||
**风险级别**: 🔵 低
|
||||
**处理难度**: ⚠️ 低
|
||||
**发现日期**: 2026-06-13
|
||||
**修复日期**: 2026-06-13
|
||||
|
||||
**问题描述**：
|
||||
坐席列表 API 没有认证保护，任何人都可以访问。
|
||||
|
||||
**修复方案**：
|
||||
1. 导入 `require_role` 依赖
|
||||
2. 添加 `@require_role("agent", "admin")` 装饰器
|
||||
|
||||
**修改文件**：
|
||||
- `backend/app/api/agents.py`
|
||||
|
||||
---
|
||||
|
||||
### L-8：Nginx `client_max_body_size` 过大
|
||||
|
||||
**状态**: ⚠️ 待处理
|
||||
**风险级别**: 🔵 低
|
||||
**处理难度**: ⚠️ 低
|
||||
**发现日期**: 2026-06-13
|
||||
|
||||
**处理建议**：
|
||||
```nginx
|
||||
location /api/upload/ {
|
||||
client_max_body_size 50m;
|
||||
}
|
||||
location /api/ {
|
||||
client_max_body_size 1m;
|
||||
}
|
||||
```
|
||||
|
||||
**关联开发任务**：
|
||||
- Nginx 配置优化
|
||||
|
||||
---
|
||||
|
||||
### L-9：前端硬编码配置
|
||||
|
||||
**状态**: ⚠️ 待处理
|
||||
**风险级别**: 🔵 低
|
||||
**处理难度**: ⚠️ 低
|
||||
**发现日期**: 2026-06-13
|
||||
|
||||
**处理建议**：
|
||||
1. 通过环境变量注入配置
|
||||
2. 避免在前端代码中硬编码敏感信息
|
||||
|
||||
**关联开发任务**：
|
||||
- 前端配置优化
|
||||
|
||||
---
|
||||
|
||||
## 六、处理计划
|
||||
|
||||
### 第一阶段：紧急修复（已完成）
|
||||
|
||||
| 序号 | 任务 | 风险项 | 状态 |
|
||||
|------|------|--------|------|
|
||||
| 1 | 恢复 `dependencies.py` 并合并新功能 | CR-1 | ✅ 已验证 |
|
||||
| 2 | 统一 Token 格式并确保向后兼容 | CR-2 | ✅ 已修复 |
|
||||
| 3 | 修改 Portal API 使用新认证中间件 | CR-3 | ✅ 已修复 |
|
||||
| 4 | 修复坐席登录的 Redis 连接管理 | CR-4 | ✅ 已修复 |
|
||||
| 5 | 添加角色分配权限验证 | H-7 | ⚠️ 待处理 |
|
||||
| 6 | 添加映射规则输入验证 | H-8 | ✅ 已修复 |
|
||||
|
||||
### 第二阶段：安全加固（上线后 1 周内）
|
||||
|
||||
| 序号 | 任务 | 风险项 | 状态 |
|
||||
|------|------|--------|------|
|
||||
| 7 | Token 绑定 IP/设备指纹 | H-9 | ⚠️ 待处理 |
|
||||
| 8 | 管理端 API 添加 IP 白名单 | H-10 | ⚠️ 待处理 |
|
||||
| 9 | WebSocket Token 改为头传递 | H-11 | ⚠️ 待处理 |
|
||||
| 10 | 实现旧 Token 迁移策略 | M-6 | ⚠️ 待处理 |
|
||||
| 11 | 添加角色缓存 | M-7 | ⚠️ 待处理 |
|
||||
| 12 | 为所有 API 添加速率限制 | M-8 | ⚠️ 待处理 |
|
||||
|
||||
### 第三阶段：纵深防御（上线后 2 周内）
|
||||
|
||||
| 序号 | 任务 | 风险项 | 状态 |
|
||||
|------|------|--------|------|
|
||||
| 13 | 异常处理不再泄露内部信息 | M-9 | ⚠️ 待处理 |
|
||||
| 14 | 日志脱敏处理 | M-10 | ⚠️ 待处理 |
|
||||
| 15 | PostgreSQL 更换强密码 | M-11 | ⚠️ 待处理 |
|
||||
| 16 | Redis 设置密码 | M-12 | ⚠️ 待处理 |
|
||||
| 17 | Nginx 添加 CSP/HSTS 安全头 | L-5 | ⚠️ 待处理 |
|
||||
| 18 | 收紧 CORS 配置 | L-6 | ⚠️ 待处理 |
|
||||
| 19 | 坐席列表 API 添加认证 | L-7 | ⚠️ 待处理 |
|
||||
| 20 | Nginx 按路径细分文件大小限制 | L-8 | ⚠️ 待处理 |
|
||||
|
||||
---
|
||||
|
||||
## 七、风险关联开发任务
|
||||
|
||||
以下风险与当前开发任务关联，需要在相关任务完成时一并处理：
|
||||
|
||||
| 风险项 | 关联开发任务 | 处理时机 |
|
||||
|--------|--------------|----------|
|
||||
| H-6 | 角色映射服务开发 | 实现时添加验证 |
|
||||
| H-7 | 角色管理 API 完善 | 实现时添加权限检查 |
|
||||
| H-9 | Token 安全加固 | Token 服务完善时 |
|
||||
| H-10 | 管理端访问控制 | 部署时配置 |
|
||||
| H-11 | WebSocket 安全加固 | WS 重构时 |
|
||||
| M-6 | Token 迁移工具 | 上线前 |
|
||||
| M-7 | 角色缓存实现 | 性能优化时 |
|
||||
| M-8 | 速率限制完善 | 安全加固时 |
|
||||
| M-9 | 异常处理优化 | 代码审查时 |
|
||||
| M-10 | 日志脱敏实现 | 日志系统优化时 |
|
||||
| M-11 | 生产环境配置 | 部署时 |
|
||||
| M-12 | 生产环境配置 | 部署时 |
|
||||
| L-5~L-9 | Nginx/前端优化 | 部署/优化时 |
|
||||
|
||||
---
|
||||
|
||||
## 八、维护说明
|
||||
|
||||
1. **定期审查**：每月审查一次风险状态，更新处理进度
|
||||
2. **新风险录入**：发现新风险时及时录入本表
|
||||
3. **关联开发任务**：开发任务涉及风险项目时，与风险项目一并处理并更新状态
|
||||
4. **状态更新**：风险处理完成后，更新状态为 ✅ 已修复，并记录修复日期
|
||||
|
||||
---
|
||||
|
||||
## 九、2026-06-14 workbuddy 推送评审新增
|
||||
|
||||
**评审依据**: `docs/评审报告/workbuddy-2026-06-14-消息优化.md`
|
||||
**评审范围**: workbuddy 6-14 推送 + `智能IT支持服务台-版本更新说明-20250614.md`
|
||||
**小计**: 13 项发现（6 P0 + 4 P1 + 3 P2），其中 7 项已修本地代码，6 项待 workbuddy 跟进
|
||||
|
||||
---
|
||||
|
||||
### 9.1 🔴 严重 (新增 6 项,**全部已修**)
|
||||
|
||||
#### CR-5：H5 participants 端点无会话参与权限校验 → P0-1
|
||||
|
||||
- **状态**: ✅ 已修复（2026-06-14 本地代码）
|
||||
- **风险级别**: 🔴 严重（数据泄露）
|
||||
- **位置**: `backend/app/api/h5.py:1107-1145`
|
||||
- **问题**: 仅校验"用户已登录"，未校验"是否属于本会话"，任意已登录员工可枚举 conversation_id 读取他会话参与者
|
||||
- **修复**: 加 is_creator / is_participant 双重校验
|
||||
|
||||
#### CR-6：recall_message 端点无鉴权 → P0-2
|
||||
|
||||
- **状态**: ✅ 已修复
|
||||
- **风险级别**: 🔴 严重（数据破坏）
|
||||
- **位置**: `backend/app/api/messages.py:293-340`
|
||||
- **问题**: 端点签名只有 `db: AsyncSession = Depends(get_db)`，**无任何鉴权依赖**
|
||||
- **修复**: 加 `agent: Agent = Depends(get_current_agent)` + `message.sender_id == agent.user_id` 校验
|
||||
|
||||
#### CR-7：delete_message 端点无鉴权 → P0-3
|
||||
|
||||
- **状态**: ✅ 已修复
|
||||
- **位置**: `backend/app/api/messages.py:336-365`
|
||||
- **修复**: 同 CR-6
|
||||
|
||||
#### CR-8：mark_read 端点无鉴权 + 会话访问未校验 → P0-4
|
||||
|
||||
- **状态**: ✅ 已修复
|
||||
- **位置**: `backend/app/api/messages.py:368-405`
|
||||
- **问题**: 任意人可调用改任意会话已读状态，破坏"未读数"业务
|
||||
- **修复**: 加 agent 鉴权 + `assigned_agent_id` / `collaborating_agent_ids` 校验
|
||||
- **捎带修**: `where(Message.is_read == False)` 改为 `is_(False)`（P2-1，原表达式在 SQLAlchemy 静默失效）
|
||||
|
||||
#### CR-9：upload_image 端点无鉴权 → P0-5
|
||||
|
||||
- **状态**: ✅ 已修复
|
||||
- **位置**: `backend/app/api/messages.py:400-462`
|
||||
- **问题**: 任意 HTTP 客户端可上传图片占用磁盘（无大小硬限、无频率限制）
|
||||
- **修复**: 加 `Depends(get_current_agent)`
|
||||
|
||||
#### CR-10：upload_message_file 端点无鉴权 → P0-6
|
||||
|
||||
- **状态**: ✅ 已修复
|
||||
- **位置**: `backend/app/api/messages.py:458-525`
|
||||
- **修复**: 同 CR-9
|
||||
|
||||
---
|
||||
|
||||
### 9.2 🟠 高 (新增 4 项,**全部待 workbuddy 跟进**)
|
||||
|
||||
#### H-12：upload 路径在容器本地，容器重建即丢失 → P1-1
|
||||
|
||||
- **状态**: ⚠️ 待处理
|
||||
- **风险级别**: 🟠 高（数据丢失）
|
||||
- **位置**: `backend/app/api/messages.py:434,487`
|
||||
- **问题**: `media/images/` 和 `media/files/` 写容器本地，容器重建或重启丢所有上传
|
||||
- **处理建议**: 改 volume mount（参考 nginx 静态文件挂载模式，参考 `docker-compose.yml:142-145`）
|
||||
|
||||
#### H-13：SQL 迁移未走 Alembic → P1-2
|
||||
|
||||
- **状态**: ⚠️ 待处理
|
||||
- **风险级别**: 🟠 高（schema 漂移）
|
||||
- **位置**: `alembic/versions/`（缺）、`models/message.py:190-204`
|
||||
- **问题**: 模型已有 `status` / `recallable_until` 字段，但**未见对应 Alembic 迁移脚本**；版本文档教用户手动 `ALTER TABLE`（反模式）
|
||||
- **处理建议**: 跑 `alembic revision --autogenerate -m "add message status and recallable_until"` 自动生成迁移
|
||||
|
||||
#### H-14：docker-compose backend healthcheck 用 curl → P1-3
|
||||
|
||||
- **状态**: ⚠️ 待处理
|
||||
- **风险级别**: 🟠 高（监控失真）
|
||||
- **位置**: `docker-compose.yml:117-122`
|
||||
- **问题**: `curl -f http://localhost:8000/health || exit 1`，**backend 精简 Python 镜像无 curl** → healthcheck 永远 unhealthy
|
||||
- **关联记忆**: [[backend-healthcheck-curl-pitfall]]
|
||||
- **处理建议**: 改用 `python -c "import socket; s=socket.socket(); s.connect(('localhost',8000))"`（Python 镜像必有）
|
||||
|
||||
#### H-15：ws_manager 文档承诺"消息状态广播"未实现 → P1-4
|
||||
|
||||
- **状态**: ⚠️ 待处理
|
||||
- **风险级别**: 🟠 高（文档与代码不符）
|
||||
- **位置**: `docs/智能IT支持服务台-版本更新说明-20250614.md:46` 声称改动 / `backend/app/services/ws_manager.py` 实际无对应方法
|
||||
- **问题**: ConnectionManager 仅有 `send_to_agent` / `broadcast` / `send_to_employee` / `broadcast_to_employees`，**无 `broadcast_message_status(conv_id, msg_id, status)`**
|
||||
- **处理建议**: 实现该方法 + WebSocket 消息格式
|
||||
|
||||
---
|
||||
|
||||
### 9.3 🟡 中 (新增 3 项，1 已修，2 待跟进)
|
||||
|
||||
#### M-13：upload 写文件非原子 → P2-2
|
||||
|
||||
- **状态**: ⚠️ 待处理
|
||||
- **位置**: `backend/app/api/messages.py:440,494`
|
||||
- **问题**: `with open(file_path, "wb") as f: f.write(content)`，中途崩溃留半文件
|
||||
- **处理建议**: 先写 `*.tmp` 再 `os.rename` 原子化
|
||||
|
||||
#### M-14：upload 返回原始文件名 → P2-3
|
||||
|
||||
- **状态**: ⚠️ 待处理
|
||||
- **位置**: `backend/app/api/messages.py:501`
|
||||
- **问题**: `"filename": original_name` 返回原始文件名，可能含中文 / 特殊字符（XSS 风险）
|
||||
- **处理建议**: URL encode 或服务端做白名单过滤
|
||||
|
||||
#### M-15：mark_read SQL `== False` 表达式静默失效 → P2-1
|
||||
|
||||
- **状态**: ✅ 已修复（捎带在 P0-4 修复中）
|
||||
- **位置**: `backend/app/api/messages.py:388`（原）
|
||||
- **问题**: `where(Message.is_read == False)` 在 SQLAlchemy 中不报错但**实际未生效**（Python `==` 返回 False → SQLAlchemy 当赋值处理但参数已绑死）
|
||||
- **修复**: 改为 `is_(False)`，走 SQL `is false` 否定
|
||||
|
||||
---
|
||||
|
||||
### 9.4 文档本身的 4 处错误（已记录待修订）
|
||||
|
||||
| # | 位置 | 错误 | 建议修订 |
|
||||
|---|------|------|----------|
|
||||
| D-1 | 版本说明部署步骤 5 | `docker compose -p root up -d` **正是用户 6-14 生产事故的根因** | **删除 `-p root` 标志** |
|
||||
| D-2 | 版本说明部署步骤 6 | SQL `DEFAULT 'sent'` 引号未转义（shell 语法错） | 改用 Alembic 迁移脚本 |
|
||||
| D-3 | 版本说明 2.1 ws_manager | 声称"添加消息状态广播"但实际未实现 | 改"规划中"或"本次未实现" |
|
||||
| D-4 | 版本说明 2.1 docker-compose | "healthcheck 已配置"不准确 | 加注 backend curl 坑 |
|
||||
|
||||
---
|
||||
|
||||
### 9.5 评审结论与流程建议
|
||||
|
||||
- **P0 比例 46% (6/13) 过高** —— workbuddy 后续推送需**强制走评审流程**
|
||||
- **建议加 pre-commit 检查**: 新增端点无 `Depends(...)` 鉴权依赖时拒绝推送
|
||||
- **下次推送窗口**: 等 H-12~15 + M-13/14 全部修完再合入，**不在评审未消化前叠加新功能**
|
||||
|
||||
---
|
||||
|
||||
### 9.6 新增项状态速查
|
||||
|
||||
| 编号 | 状态 | 编号 | 状态 |
|
||||
|------|------|------|------|
|
||||
| CR-5 (P0-1) | ✅ | H-12 (P1-1) | 🟡 半成品(留 #25) |
|
||||
| CR-6 (P0-2) | ✅ | H-13 (P1-2) | ✅ |
|
||||
| CR-7 (P0-3) | ✅ | H-14 (P1-3) | ✅ |
|
||||
| CR-8 (P0-4) | ✅ | H-15 (P1-4) | ✅ |
|
||||
| CR-9 (P0-5) | ✅ | M-13 (P2-2) | ⚠️ |
|
||||
| CR-10 (P0-6) | ✅ | M-14 (P2-3) | ⚠️ |
|
||||
| | | M-15 (P2-1) | ✅（捎带）|
|
||||
|
||||
---
|
||||
|
||||
## 第十节: 2026-06-14 P0 安全评估(workbuddy 推送 v2)
|
||||
|
||||
**关联 commit**: `3735dc0` — feat(security): P0 安全止血 - WS token 改 header + 坐席本地密码
|
||||
**主报告**: `docs/评审报告/workbuddy-2026-06-14-P0安全.md`
|
||||
**评审结论**: 🟡 **部分完成,5 项遗留**(3 项 P0 / 2 项 P1)
|
||||
**workbuddy 下一轮任务**: #18
|
||||
|
||||
> 📌 第十节有独立小计(5 P0 + 2 P1,2 个新维度:WS token 鉴权 + 坐席本地密码)。
|
||||
|
||||
### 10.1 小计
|
||||
|
||||
| 维度 | 任务 | 真实状态 |
|
||||
|---|---|---|
|
||||
| P0-#1 | WECOM_SECRET 集中化 | 🟡 **只规划未实改** (`docs/安全/secret-管理.md`) |
|
||||
| P0-#2 | SSL 私钥在仓 | 🟢 **8-A 阶段已修**(.gitignore `**` 模式) |
|
||||
| P0-#3 | Mock login bypass | 🟢 **之前已修** |
|
||||
| P0-#4 | WS token URL/日志泄露 | 🟡 **半成品**(服务端 OK,前端 ws.ts + nginx access_log 待关) |
|
||||
| P0-#5 | 坐席本地密码 | 🟡 **半成品**(字段/Schema/端点 OK,类型 bug + 降级放行 + 缺依赖) |
|
||||
|
||||
**总评**: 2/5 P0 完成,3 项遗留待 workbuddy 下一轮修。
|
||||
|
||||
### 10.2 遗留项追踪(给 workbuddy 任务清单 #18)
|
||||
|
||||
| # | 严重度 | 文件 | 项 | 状态 |
|
||||
|---|---|---|---|---|
|
||||
| 遗留 1 | 🔴 P0 | `frontend-agent/src/composables/useWebSocket.ts:106-110` | 浏览器 WebSocket API 不支持自定义 header,改 Sec-WebSocket-Protocol | ⚠️ |
|
||||
| 遗留 2 | 🔴 P0 | `nginx.conf` + `deploy-server/nginx.conf` | `location /ws/ { access_log off; }` | ⚠️ |
|
||||
| 遗留 3 | 🟡 P1 | `backend/app/models/agent.py:142-148` | `Mapped[str]` → `Mapped[Optional[str]]` | ⚠️ |
|
||||
| 遗留 4 | 🟡 P1 | `backend/app/api/agents.py` 降级放行 | 强制 password 验证 | ⚠️ |
|
||||
| 遗留 5 | 🟡 P1 | `backend/requirements.txt` | 缺 passlib/bcrypt 依赖 | ⚠️ |
|
||||
|
||||
### 10.3 评审教训(防再犯)
|
||||
|
||||
1. **WebSocket API 边界**: 浏览器 vs Node.js `ws` 库 API 差异
|
||||
2. **依赖检查**: 改代码必须同步 requirements.txt
|
||||
3. **配置改动**: plan 写了的 nginx / conf 必须做
|
||||
4. **类型一致性**: Mapped[T] + nullable=True 必须 Optional
|
||||
5. **逻辑回归**: 新鉴权必须 review 已有降级路径
|
||||
|
||||
### 10.4 推 Gitea 状态
|
||||
|
||||
- **本地 commit**: 3735dc0 ✅
|
||||
- **推 Gitea**: 🔴 **卡 #8**(MariaDB 套件未装)
|
||||
- **下次**: Gitea 起来后 `git push -u origin main` 一次推送 → 触发 workbuddy 二次评审 → #18 闭环
|
||||
|
||||
### 10.5 第十节状态速查
|
||||
|
||||
| 编号 | 状态 |
|
||||
|---|---|
|
||||
| P0-#1 WECOM_SECRET 集中化 | 🟡 规划中(V1/V2) |
|
||||
| P0-#2 SSL 私钥 | 🟢 8-A 完成 |
|
||||
| P0-#3 Mock login | 🟢 完成 |
|
||||
| P0-#4 WS token | 🟡 遗留 1+2 |
|
||||
| P0-#5 坐席密码 | 🟡 遗留 3+4+5 |
|
||||
|
||||
---
|
||||
|
||||
## 第十一节: 2026-06-14 P1 消息优化推送(2 轮)
|
||||
|
||||
**来源**: 6-14 workbuddy 消息优化推送遗留 4 P1
|
||||
**主报告**: `docs/评审报告/workbuddy-2026-06-14-消息优化.md` 9.3 节
|
||||
**workbuddy 任务清单**: `.workbuddy/memory/2026-06-14-任务-修P1消息.md`
|
||||
**任务编号**: #23
|
||||
|
||||
### 11.1 4 P1 项
|
||||
|
||||
| 编号 | 严重度 | 内容 | 状态 |
|
||||
|---|---|---|---|
|
||||
| H-12 (P1-1) | 🟡 | upload 路径在容器本地,容器重建即丢失 → 改 volume mount | 🔄 |
|
||||
| H-13 (P1-2) | 🟡 | SQL 迁移未走 Alembic → 生成 `add message status` 迁移 | 🔄 |
|
||||
| H-14 (P1-3) | 🟡 | docker-compose backend healthcheck 用 curl → 改 Python 一行 | 🔄 |
|
||||
| H-15 (P1-4) | 🟡 | ws_manager 没实现"消息状态广播" → 实现 `broadcast_message_status()` | 🔄 |
|
||||
|
||||
### 11.2 评审教训(防 workbuddy 再犯)
|
||||
|
||||
1. **依赖 docker volume 部署前要先建 host 目录** —— `scripts/deploy.sh` 需加创建逻辑
|
||||
2. **alembic autogenerate 需人工 review** —— 自动生成的不一定对(可能漏 index / 加了不想要的)
|
||||
3. **backend 精简镜像没 curl 是已知坑** —— 用 Python 一行替代
|
||||
4. **文档承诺的 WS 广播必须实做** —— 否则前端靠轮询兜底,实时性不够
|
||||
|
||||
### 11.3 第十一节状态速查
|
||||
|
||||
| 编号 | 状态 |
|
||||
|---|---|
|
||||
| H-12 (P1-1) upload 路径 | 🔄 评审闭环中(留 P2 优化,任务 #25) |
|
||||
| H-13 (P1-2) Alembic 迁移 | 🔄 评审闭环中 |
|
||||
| H-14 (P1-3) healthcheck | 🔄 评审闭环中 |
|
||||
| H-15 (P1-4) ws 状态广播 | 🔄 评审闭环中 |
|
||||
|
||||
---
|
||||
|
||||
## 第十二节: 2026-06-14 Gitea 卸载清空事故 + 重建复盘 ⚠️ 教训重灾区
|
||||
|
||||
**触发时间**: 2026-06-14 晚
|
||||
**触发原因**: 用户在 DSM 套件中心用 "卸载清空" 选项卸载 Gitea
|
||||
**影响范围**: Gitea 服务停 + Web 不可达 + 仓裸仓库可能残留
|
||||
**恢复时长**: ~30 分钟
|
||||
**任务编号**: #26
|
||||
|
||||
### 12.1 事故时序
|
||||
|
||||
| 时刻 | 事件 |
|
||||
|---|---|
|
||||
| T+0 | 用户在 DSM 套件中心 → Gitea → 卸载 → 勾选"清空" |
|
||||
| T+1m | Gitea 服务停止,8418 端口无响应 |
|
||||
| T+1m | 外部 Funnel 域名 `ds923plus.tail58d872.ts.net` 无法访问 |
|
||||
| T+5m | 本地仓 `D:\资料\03-项目开发\wecom_it_smart_desk` 检查 11 commit 完整 |
|
||||
| T+10m | 用户发现"创仓报已存在文件" → 数据没清干净 |
|
||||
| T+15m | 用户用 Gitea Web "删除仓库" → "创建新仓库" |
|
||||
| T+20m | 用户创新 token `9754e1d8c8a0...` (权限含 admin) |
|
||||
| T+22m | 我改 `.git/config` URL 清旧 token(走 wincred 缓存) |
|
||||
| T+25m | PowerShell 推 main 成功(639 对象 / 3.67 MiB) |
|
||||
| T+28m | 配 main 分支保护 (PR + 1 reviewer) |
|
||||
| T+30m | 全部恢复,功能等价 |
|
||||
|
||||
### 12.2 教训 + 防御
|
||||
|
||||
#### 🛑 教训 1: 卸载"清空" 不等于 数据清除
|
||||
- **现象**: 套件"卸载清空"清了 app + 数据库,**但仓裸仓库目录残留**(`/volume1/@appdata/gitea/gitea/repos/`)
|
||||
- **后果**: 重装 Gitea 后创仓冲突("已存在文件")
|
||||
- **修复**: 用户手动"删除仓库 → 创建新仓库"解决
|
||||
- **防御**:
|
||||
- ✅ 部署 `scripts/backup-gitea.sh`(本次新增,C-2 任务)
|
||||
- ✅ 卸载前**强制备份**
|
||||
- ✅ 评估"卸载清空" vs "卸载保留数据"
|
||||
|
||||
#### 🛑 教训 2: token 嵌入 `.git/config` URL 是反模式
|
||||
- **现象**: 之前为 workbuddy 推 Gitea,把 token `ae236991c3d5...` 直接嵌入 `origin.url`
|
||||
- **后果**: workbuddy-claude token 失效后,URL 里有死凭据 + auto-classifier 拒绝重写 URL
|
||||
- **修复**: URL 改回 `https://simon@...`,用 `git credential approve` 存 wincred
|
||||
- **防御**:
|
||||
- ✅ **永远不**在 URL 里嵌 token(写进 [[locked-decisions]] 候选)
|
||||
- ✅ 推 Gitea 走 `git credential approve` + wincred
|
||||
- ✅ workbuddy-claude 创独立 user account(避免 token 跟 simon 账号混)
|
||||
|
||||
#### 🛑 教训 3: PowerShell 弹窗在后台易丢
|
||||
- **现象**: 用户推 main 时第一次"fatal: User cancelled dialog"(可能弹窗在后台没看到)
|
||||
- **修复**: 用 `git credential approve` 预先存 wincred,推时不弹窗
|
||||
- **防御**:
|
||||
- ✅ **CI / workbuddy / 脚本** 永远走 wincred(不弹)
|
||||
- ✅ 交互推送前先 `git credential approve`
|
||||
|
||||
#### 🛑 教训 4: main 分支保护配置需考虑"评审员有谁"
|
||||
- **现象**: 配 `block_admin_merge: true` + `required_approvals: 1` + 只有 simon 一个 user → **simon 永远合不进自己 PR**
|
||||
- **修复**: 临时改 `block_admin_merge: false`,等 workbuddy 接入再开
|
||||
- **防御**:
|
||||
- ✅ 配保护前**确认有 ≥2 个 user**(评审员 + 推送者)
|
||||
- ✅ 创 workbuddy-claude user account(本次未做,等用户睡前安排)
|
||||
|
||||
### 12.3 数据保全审计
|
||||
|
||||
| 资源 | 卸载清空前 | 卸载清空后 | 重建后 | 完整性 |
|
||||
|---|---|---|---|---|
|
||||
| Gitea 服务 | ✅ 运行 | ❌ 停止 | ✅ 启动 | ✅ 100% |
|
||||
| Gitea 数据库 (SQLite) | ✅ 完整 | ⚠️ 残留可能 | ✅ 全新 | ✅ 100%(旧数据丢) |
|
||||
| 仓裸仓库 (repos/) | ✅ 11 commit | ⚠️ 残留 | ✅ 0 commit | ⚠️ 0%(待重推) |
|
||||
| 本地仓 (windows) | ✅ 11 commit | ✅ 11 commit | ✅ 11 commit | ✅ 100% |
|
||||
| Token 表 | ✅ 3 token | ⚠️ 残留 | ✅ 1 token(simon's) | ⚠️ 旧 token 全失效 |
|
||||
| wincred 缓存 | ✅ workbuddy-claude | ⚠️ 残留 | ✅ simon 新 | ✅ 重置 |
|
||||
|
||||
### 12.4 待办
|
||||
|
||||
| # | 项 | 阻塞 |
|
||||
|---|---|---|
|
||||
| 1 | **Gitea 备份脚本部署**(`scripts/backup-gitea.sh` 推到 NAS) | 用户需 SCP |
|
||||
| 2 | **备份 cron 配置**(每天 3 点) | SSH 进 NAS |
|
||||
| 3 | **创 workbuddy-claude user** | 用户睡前做 |
|
||||
| 4 | **workbuddy-claude token 替换** | 等 #3 |
|
||||
| 5 | **`block_admin_merge` 改回 `true`**(workbuddy 接入后) | 等 #3 |
|
||||
| 6 | **删旧 workbuddy-claude token 残留** | 等 #3 |
|
||||
| 7 | **Gitea 部署文档**(`docs/Gitea部署指南.md` 含备份恢复) | 我写 |
|
||||
| 8 | **风险跟踪表加 "数据丢失" 风险项** | 我写(下面) |
|
||||
|
||||
### 12.5 新增风险项
|
||||
|
||||
| 编号 | 严重度 | 内容 | 状态 |
|
||||
|---|---|---|---|
|
||||
| **M-1 (新)** | 🟠 中高 | **Gitea 数据无异地备份** —— 一旦 NAS 硬盘故障,Gitea 全失 | 🆕 本节新增 |
|
||||
| **M-2 (新)** | 🟡 中 | **套件卸载误操作风险** —— 误勾"清空"导致数据全失 | 🆕 本节新增 |
|
||||
| **L-2 (新)** | 🟢 低 | **PowerShell 弹窗后台丢失** —— 关键推送可能因弹窗丢失而失败 | 🆕 本节新增 |
|
||||
|
||||
### 12.6 推送约定升级 (写进 [[locked-decisions]] 候选)
|
||||
|
||||
> **所有 Gitea 推送凭据走 wincred,禁止明文嵌入 `.git/config` URL**
|
||||
|
||||
具体:
|
||||
1. `.git/config` 的 `origin.url` **只写用户名**(`https://simon@...`),不写 token
|
||||
2. 首次推 / 换 token → `git credential approve` 一次性存 wincred
|
||||
3. workbuddy 推送 → 创独立 user account + 自己的 token(不跟 simon 共用)
|
||||
4. CI / 自动化推送 → 用环境变量 + `git -c credential.helper=!gh auth git-credential`(gh CLI) 或 secret store
|
||||
5. **违反 → auto-classifier 拒绝**(已成事实)
|
||||
@@ -0,0 +1,355 @@
|
||||
# 智能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）· 交付总监
|
||||
**下次更新**: 端到端验证完成后
|
||||
@@ -0,0 +1,183 @@
|
||||
# 智能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周内 |
|
||||
@@ -0,0 +1,261 @@
|
||||
# 企微IT智能服务台 — 项目状态看板
|
||||
|
||||
> 📌 **这个文件就是项目的"驾驶舱仪表盘"**。任何时候新开 session,**先读这个文件就懂上下文**。
|
||||
>
|
||||
> 📝 **更新规则**:每次 Claude 完成 / 开始 / 阻塞重要任务,会主动更新本文件。你也可以自己改(纯 markdown,git 跟踪)。
|
||||
|
||||
最后更新:**2026-07-04 17:14**(Claude 自动维护,#90 身份认证修复 + 生产部署)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 一句话总览
|
||||
|
||||
**v0.7.1 已上线运行，生产稳定**。v0.7.2 规划中，主要聚焦 AI 辅助和知识库迭代：
|
||||
|
||||
**已完成 (v0.7.1)**:
|
||||
- ✅ 企微入口 SSO（企微环境自动识别用户身份）
|
||||
- ✅ 管理后台 RBAC 细粒度角色权限
|
||||
- ✅ 敏感词检测 + token 修复
|
||||
- ✅ 扫码登录优化（iOS NSURLError 修复）
|
||||
- ✅ 文档优化专项（已完成）
|
||||
|
||||
**v0.7.2 规划中**:
|
||||
- 🔲 AI 辅助功能增强
|
||||
- 🔲 排查流程优化
|
||||
- 🔲 知识库迭代
|
||||
|
||||
**文档优化专项 (2026-07-04) ✅ 已完成**:
|
||||
- ✅ 扫描并整理 docs/ 目录全部文档
|
||||
- ✅ 规范化目录结构（01-11 编号体系）
|
||||
- ✅ 恢复归档文档到正确位置
|
||||
- ✅ 整理 10-项目管理 目录
|
||||
- ✅ 整理 03-技术架构 目录
|
||||
|
||||
---
|
||||
|
||||
## 🟢 正在做(in_progress,0 件)
|
||||
|
||||
（无进行中任务）
|
||||
|
||||
## ✅ 最近搞定
|
||||
|
||||
### 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 开发内容，文本安全过滤 |
|
||||
| #90 | 身份认证问题修复 | ✅已完成 | ✅Portal→H5 token传递修复：路由守卫接收token后调用fetchEmployeeInfo()获取用户信息 |
|
||||
|
||||
---
|
||||
|
||||
## 🟡 P1 重要(看时间做)
|
||||
|
||||
| # | 任务 | 说明 |
|
||||
|---|---|---|
|
||||
| #73 | 修后端文件未真正覆盖 | `yes | cp -f` 路径,部署时偶尔没生效 |
|
||||
| #86 | 排查流程图零依赖部分 review + 文档化 | 把 Mermaid 流程图从代码里剥离成可读文档 |
|
||||
| #88 | 管理后台 RBAC 角色权限 | 管理后台细粒度角色权限(大功能,2-3 天) |
|
||||
| #83 | 澄清"OTM 跟项目关系" | 已 2026-06-21 决策:走 TOTP+SMS 双引擎(MFA Phase 2 实施) |
|
||||
| 🆕 | v0.7.0 部署 + 35 项 E2E 验收 | 看 `docs/DEPLOY-QUICK-v0.7.0.md` 6 步 + `docs/E2E-CHECKLIST-v0.7.0.md` |
|
||||
| 🆕 | 修 64 pre-existing 测试失败 | Role.data_scope 缺字段 / WecomService DI / test_message_experience 等 |
|
||||
|
||||
## 🟢 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 前) |
|
||||
|
||||
---
|
||||
|
||||
## 🟢 P2 / 等用户决策
|
||||
|
||||
| # | 任务 | 卡在哪 |
|
||||
|---|---|---|
|
||||
| **🆕 服务器更新?** | 把今天的 3 个 migration + 1 个 bug 修复部署到生产 v0.5.6 | **等你看这份看板后拍板** |
|
||||
| #31 | 推 docker 镜像到生产 registry | 等你确认要走哪条路(自建 Harbor / 阿里云 / 别的) |
|
||||
| #43 | 配置 HTTPS | 等域名备案完成 + 证书到位 |
|
||||
| #53 | 用户在企微验证 /itportal/ | 等你去企微点一点 |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 最近搞定(给你信心)
|
||||
|
||||
### 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,96 @@
|
||||
# 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 |
|
||||
@@ -0,0 +1,97 @@
|
||||
# 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 | 升级脚本(已修) |
|
||||
@@ -0,0 +1,134 @@
|
||||
# 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
|
||||
- ❌ 评审失败强行合并
|
||||
- ❌ 评审未消化前叠加新功能
|
||||
- ❌ 改评审报告原文(只加节)
|
||||
@@ -0,0 +1,208 @@
|
||||
# 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 |
|
||||
@@ -0,0 +1,343 @@
|
||||
# 项目管理文档管理规范
|
||||
|
||||
> **版本**: 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.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,312 @@
|
||||
# 新开发任务说明书 (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.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 |
|
||||
| **类型** | 功能开发 / 登录流程 |
|
||||
| **描述** | 坐席/管理端浏览器直接打开登录页，支持账号密码+OTP认证 |
|
||||
| **状态** | 开发中 |
|
||||
| **估时** | 4小时（开发+测试） |
|
||||
|
||||
#### 输入项来源
|
||||
- **产品需求**: PRD v1.5 §4.4.5 登录流程调整
|
||||
- **原型设计**: admin-dashboard-v1.html 登录页面
|
||||
- **项目看板**: P0任务
|
||||
|
||||
#### 输出成果要求
|
||||
|
||||
| # | 交付物 | 类型 |
|
||||
|---|--------|------|
|
||||
| 1 | 后端登录API (`/api/auth/login`) | 代码 |
|
||||
| 2 | 坐席端登录页面 | 代码 |
|
||||
| 3 | 管理端登录页面 | 代码 |
|
||||
| 4 | OTP验证逻辑 | 代码 |
|
||||
| 5 | 更新API文档 | 文档 |
|
||||
|
||||
#### 验证方式
|
||||
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 坐席登录 | 手动测试 | 账号密码+OTP登录成功 |
|
||||
| 管理登录 | 手动测试 | 账号密码+OTP登录成功 |
|
||||
| 权限控制 | 越权测试 | 坐席无法访问管理端 |
|
||||
| 错误处理 | 异常输入 | 正确提示 |
|
||||
|
||||
#### 完成标准
|
||||
|
||||
- [ ] 后端登录API开发完成
|
||||
- [ ] 坐席端登录页面开发完成
|
||||
- [ ] 管理端登录页面开发完成
|
||||
- [ ] OTP验证正常工作
|
||||
- [ ] 代码通过 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 |
|
||||
|
||||
@@ -0,0 +1,219 @@
|
||||
# 优先级最高卡点任务说明书
|
||||
|
||||
> **版本**: v1.2 | **日期**: 2026-07-04 | **状态**: 🔴 进行中
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | 优先级卡点任务 |
|
||||
| **任务ID** | #90 等 |
|
||||
| **优先级** | 🔴P0 / 🟠P1 |
|
||||
| **类型** | 功能开发 / Bug修复 |
|
||||
| **状态** | 进行中 / 延后 |
|
||||
| **负责人** | 宋献 + Claude |
|
||||
| **创建日期** | 2026-07-04 |
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 说明
|
||||
|
||||
以下任务是当前项目中**优先级最高**但**遇到阻塞卡点**的任务，需要优先解决才能推进项目进度。
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
### 产品需求
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `02-产品需求/02-产品需求文档PRD-v1.2-20260704.md` | §4.4.5 坐席/管理员登录流程 | 登录逻辑调整 |
|
||||
| `02-产品需求/02-产品需求文档PRD-v1.2-20260704.md` | v1.5 更新说明 | 登录方式变更 |
|
||||
|
||||
### 技术架构
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `03-技术架构/02-技术方案/` | - | 相关技术方案 |
|
||||
|
||||
### 原型设计
|
||||
| 来源文档 | 页面 | 说明 |
|
||||
|----------|------|------|
|
||||
| `04-原型设计/prototypes-原型图/admin-dashboard-v1.html` | 管理后台登录 | 登录页面UI |
|
||||
| `04-原型设计/prototypes-原型图/agent-workspace-v5_4.html` | 坐席工作台 | 登录后页面 |
|
||||
|
||||
### 项目看板
|
||||
| 来源 | 任务名 | 说明 |
|
||||
|------|--------|------|
|
||||
| `05-项目状态看板/01-项目状态看板.md` | P0任务 | 当前阻塞任务 |
|
||||
|
||||
---
|
||||
|
||||
## 📢 需求变更（2026-07-04）
|
||||
|
||||
根据 PRD v1.5 更新，登录逻辑已调整：
|
||||
|
||||
| 角色 | 登录方式 | 说明 |
|
||||
|------|----------|------|
|
||||
| **用户端 (H5)** | 企微内嵌打开 | 强制企微内嵌，OAuth2 静默授权 |
|
||||
| **坐席端 (Agent)** | 浏览器直接打开 | 无需经过企微工作台，支持账号密码+OTP |
|
||||
| **管理端 (Admin)** | 浏览器直接打开 | 无需经过企微工作台，支持账号密码+OTP |
|
||||
|
||||
> **核心变更**：坐席/管理员无需经过企微工作台，可直接在浏览器打开登录页面
|
||||
|
||||
---
|
||||
|
||||
## 🎯 当前任务（按新登录逻辑）
|
||||
|
||||
---
|
||||
|
||||
### 任务 1: 坐席/管理端登录验证（🔴 最优先）
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **ID** | #90 |
|
||||
| **优先级** | 🔴 P0 |
|
||||
| **当前状态** | 🔧 开发中 |
|
||||
| **功能描述** | 坐席/管理端浏览器直接登录，支持账号密码+OTP认证 |
|
||||
|
||||
#### 输入项来源
|
||||
- **产品需求**: PRD v1.5 §4.4.5 登录流程
|
||||
- **原型设计**: admin-dashboard-v1.html 登录页
|
||||
- **项目看板**: P0任务
|
||||
|
||||
#### 登录流程
|
||||
1. 坐席/管理员直接在浏览器打开 `/itagent/` 或 `/itadmin/`
|
||||
2. 输入账号密码 + OTP 验证码
|
||||
3. 验证通过后进入对应工作台
|
||||
|
||||
#### 输出成果要求
|
||||
|
||||
| # | 交付物 | 类型 |
|
||||
|---|--------|------|
|
||||
| 1 | 后端登录API | 代码 |
|
||||
| 2 | 坐席端登录页 | 代码 |
|
||||
| 3 | 管理端登录页 | 代码 |
|
||||
| 4 | OTP验证逻辑 | 代码 |
|
||||
|
||||
#### 验证方式
|
||||
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 坐席登录 | 手动测试 | 登录成功进入工作台 |
|
||||
| 管理登录 | 手动测试 | 登录成功进入后台 |
|
||||
| 权限隔离 | 越权测试 | 坐席无法访问管理端 |
|
||||
| OTP验证 | 验证码测试 | 错误验证码被拦截 |
|
||||
|
||||
#### 完成标准
|
||||
|
||||
- [ ] 后端登录API开发完成
|
||||
- [ ] 坐席端登录页面完成
|
||||
- [ ] 管理端登录页面完成
|
||||
- [ ] OTP验证正常工作
|
||||
- [ ] 权限控制正确
|
||||
- [ ] 功能测试通过
|
||||
- [ ] 代码通过 Code Review
|
||||
|
||||
---
|
||||
|
||||
## ⏸️ 延后任务（暂不处理）
|
||||
|
||||
### 延后 1: IP 白名单收窄
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **ID** | #48 |
|
||||
| **优先级** | 🔴 P0 → ⏸️ 延后 |
|
||||
| **原因** | 需网络组确认真实代理 IP 段（WAF/堡垒机/CDN 出口 IP） |
|
||||
| **状态** | 延后，待网络组确认后重启 |
|
||||
|
||||
#### 输入项来源
|
||||
- **产品需求**: 安全合规要求
|
||||
- **技术架构**: nginx 配置
|
||||
|
||||
#### 完成标准
|
||||
- [ ] 网络组确认IP段
|
||||
- [ ] nginx配置更新
|
||||
- [ ] 验证通过
|
||||
|
||||
---
|
||||
|
||||
### 延后 2: 敏感词检测功能
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **ID** | #81 |
|
||||
| **优先级** | 🔴 P0 → ⏸️ 延后 |
|
||||
| **原因** | 需确认企业敏感词库来源 |
|
||||
| **状态** | 延后，待确认词库来源后重启 |
|
||||
|
||||
#### 输入项来源
|
||||
- **产品需求**: PRD 安全要求
|
||||
|
||||
#### 完成标准
|
||||
- [ ] 确认敏感词库来源
|
||||
- [ ] 词库配置完成
|
||||
- [ ] 过滤功能测试通过
|
||||
|
||||
---
|
||||
|
||||
### 延后 3: 后端文件部署覆盖
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **ID** | #73 |
|
||||
| **优先级** | 🟠 P1 → ⏸️ 延后 |
|
||||
| **原因** | 部署脚本优化 |
|
||||
| **状态** | 延后 |
|
||||
|
||||
#### 输入项来源
|
||||
- **技术架构**: 部署流程
|
||||
|
||||
#### 完成标准
|
||||
- [ ] 脚本优化完成
|
||||
- [ ] 覆盖验证通过
|
||||
|
||||
---
|
||||
|
||||
## 📊 当前任务状态
|
||||
|
||||
| 任务 | 优先级 | 状态 | 输入来源 |
|
||||
|------|--------|------|----------|
|
||||
| 登录流程验证 | 🔴 P0 | 进行中 | PRD v1.5、原型设计、项目看板 |
|
||||
| IP 白名单 | 🔴 P0 | 延后 | 安全合规、技术架构 |
|
||||
| 敏感词检测 | 🔴 P0 | 延后 | PRD 安全要求 |
|
||||
| 部署脚本优化 | 🟠 P1 | 延后 | 技术架构 |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 完成标准总览
|
||||
|
||||
### 代码规范
|
||||
- [ ] 遵循项目代码规范
|
||||
- [ ] 通过 ESLint / Pylint 检查
|
||||
|
||||
### 测试要求
|
||||
- [ ] 单元测试新增/修复完成
|
||||
- [ ] 功能测试通过
|
||||
- [ ] 安全测试通过
|
||||
|
||||
### 文档要求
|
||||
- [ ] API 接口文档已更新
|
||||
- [ ] 相关技术文档已更新
|
||||
|
||||
### 交付要求
|
||||
- [ ] 代码合入主干分支
|
||||
- [ ] 通过 Code Review
|
||||
- [ ] 任务看板已更新
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 |
|
||||
|------|----------|--------|
|
||||
| 2026-07-04 | 创建任务说明书 | Claude |
|
||||
| 2026-07-04 | 添加需求变更说明 | Claude |
|
||||
| 2026-07-04 | 添加模板化字段 | Claude |
|
||||
|
||||
@@ -0,0 +1,154 @@
|
||||
# 任务说明书模板
|
||||
|
||||
> **版本**: v1.0 | **日期**: 2026-07-04
|
||||
|
||||
---
|
||||
|
||||
## 📋 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **任务名称** | [任务名称] |
|
||||
| **任务ID** | #[编号] |
|
||||
| **优先级** | 🔴P0 / 🟠P1 / 🟡P2 |
|
||||
| **类型** | 功能开发 / Bug修复 / 安全加固 / 文档完善 / 测试修复 / 部署优化 |
|
||||
| **状态** | 待开始 / 进行中 / 已完成 / 阻塞 / 延后 |
|
||||
| **负责人** | [负责人] |
|
||||
| **创建日期** | YYYY-MM-DD |
|
||||
| **计划完成日期** | YYYY-MM-DD |
|
||||
|
||||
---
|
||||
|
||||
## 📥 输入项来源
|
||||
|
||||
### 产品需求
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `02-产品需求/02-产品需求文档PRD-v1.2-20260704.md` | §X | [需求描述] |
|
||||
| `02-产品需求/product-产品/v0.7.2-backlog-candidate-2026-06-24.md` | [ backlog项 ] | [需求描述] |
|
||||
|
||||
### 技术架构
|
||||
| 来源文档 | 相关章节 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `03-技术架构/02-技术方案/[技术方案文档].md` | §X | [技术设计] |
|
||||
| `03-技术架构/01-ADRs-架构决策/ADR-XXX.md` | - | [架构决策] |
|
||||
|
||||
### 原型设计
|
||||
| 来源文档 | 页面 | 说明 |
|
||||
|----------|------|------|
|
||||
| `04-原型设计/prototypes-原型图/[原型文件].html` | [页面名] | [UI/UX要求] |
|
||||
|
||||
### 项目看板
|
||||
| 来源 | 任务名 | 说明 |
|
||||
|------|--------|------|
|
||||
| `05-项目状态看板/01-项目状态看板.md` | [任务名] | [看板任务描述] |
|
||||
|
||||
---
|
||||
|
||||
## 📤 输出成果要求
|
||||
|
||||
### 交付物清单
|
||||
|
||||
| # | 交付物 | 类型 | 说明 |
|
||||
|---|--------|------|------|
|
||||
| 1 | [交付物名称] | 代码/文档/配置 | [说明] |
|
||||
| 2 | [交付物名称] | 代码/文档/配置 | [说明] |
|
||||
|
||||
### 代码要求
|
||||
- 遵循项目代码规范（见 `07-代码评审/`）
|
||||
- 所有新增代码通过 ESLint / Pylint 检查
|
||||
- 单元测试覆盖率 ≥ 80%
|
||||
|
||||
### 文档要求
|
||||
- 更新相关技术文档
|
||||
- 更新 API 接口文档
|
||||
- 更新部署文档（如有变更）
|
||||
|
||||
---
|
||||
|
||||
## 🔧 验证方式
|
||||
|
||||
### 功能验证
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 功能正常运行 | 手动测试 | 功能符合需求 |
|
||||
| 接口正常 | API测试 | 返回正确 |
|
||||
| 页面正常 | UI测试 | 显示正确 |
|
||||
|
||||
### 安全验证
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 权限控制 | 越权测试 | 无法访问未授权资源 |
|
||||
| 输入验证 | 异常输入测试 | 正确拦截/提示 |
|
||||
|
||||
### 性能验证
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|-----------|
|
||||
| 响应时间 | 性能测试 | < 200ms (API) |
|
||||
| 并发能力 | 压力测试 | 50+ 并发正常 |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 完成标准
|
||||
|
||||
### 验收条件
|
||||
|
||||
- [ ] 代码合入主干分支
|
||||
- [ ] 所有测试通过（CI/CD 绿灯）
|
||||
- [ ] 功能测试通过
|
||||
- [ ] 安全测试通过
|
||||
- [ ] 文档已更新
|
||||
- [ ] 相关任务看板已更新
|
||||
|
||||
### 产出确认
|
||||
|
||||
- [ ] 代码已提交并通过 Code Review
|
||||
- [ ] 单元测试新增/修复完成
|
||||
- [ ] 集成测试通过
|
||||
- [ ] 部署验证通过（如需要）
|
||||
- [ ] 文档更新已完成
|
||||
|
||||
---
|
||||
|
||||
## 📊 工作分解
|
||||
|
||||
### 子任务
|
||||
|
||||
| 子任务 | 负责人 | 预估工时 | 状态 |
|
||||
|--------|--------|----------|------|
|
||||
| [子任务1] | [负责人] | [工时] | [状态] |
|
||||
| [子任务2] | [负责人] | [工时] | [状态] |
|
||||
| [子任务3] | [负责人] | [工时] | [状态] |
|
||||
|
||||
---
|
||||
|
||||
## 📞 依赖与阻塞
|
||||
|
||||
### 前置依赖
|
||||
| 依赖任务 | 依赖说明 | 状态 |
|
||||
|----------|----------|------|
|
||||
| [任务ID] | [依赖说明] | 已完成/进行中 |
|
||||
|
||||
### 阻塞因素
|
||||
| 阻塞项 | 影响范围 | 解决方案 |
|
||||
|--------|----------|-----------|
|
||||
| [阻塞项] | [影响] | [解决方案] |
|
||||
|
||||
---
|
||||
|
||||
## 📈 变更记录
|
||||
|
||||
| 日期 | 变更内容 | 变更人 | 说明 |
|
||||
|------|----------|--------|------|
|
||||
| YYYY-MM-DD | 创建任务 | [人] | 初始版本 |
|
||||
| YYYY-MM-DD | [变更] | [人] | [说明] |
|
||||
|
||||
---
|
||||
|
||||
## 📎 附件
|
||||
|
||||
- 相关需求文档链接
|
||||
- 技术方案链接
|
||||
- 原型图链接
|
||||
- 测试用例链接
|
||||
|
||||
Reference in New Issue
Block a user