chore: docs 结构整改 + compose 双目录对齐（合并重建提交）

本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交（5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。一、docs 结构整改（整改 #14）根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入，随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录树并存于 docs/，共 791 文件、双分类体系冲突。修复动作： - b2 同名异主题文件改名迁移保全 9 个 - C 类 39 个孤立文件按主题正确归类 - A/B1 类 222 个重复文件删除（新结构已有内容副本） - 9 个旧独有空目录删除 - 270 处内部引用按 verified 映射改写 - 整改记录 #14 登记于 04-运维文档/部署运维结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。二、compose 双目录对齐（消除踩坑 A） - docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist 改为 src/frontend-*/dist（h5 / agent / admin / terminal） - docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/ - 效果：本地 docker compose up 不再把根目录 stale dist 挂回，与线上一致，分叉隐患消除（已 docker compose config 校验通过）防复发铁律： - 重构须提交；仓库修复须 git stash -u 或先 commit - 新结构须 git add 并提交，避免再次 untracked 复活 - H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
2026-08-07 22:31:32 +08:00
parent 5a77a89ab1
commit facc04aa65
573 changed files with 129347 additions and 909 deletions
@@ -0,0 +1,314 @@
+# 新开发任务说明书 (v0.7.2+)
+
+> **版本**: v1.2 | **日期**: 2026-07-04 | **状态**: 🔴 进行中
+
+---
+
+## 📋 基本信息
+
+| 项目 | 内容 |
+|------|------|
+| **任务名称** | v0.7.2+ 新功能开发 |
+| **任务ID** | #90 等 |
+| **优先级** | 🔴P0 > 🟠P1 |
+| **类型** | 功能开发 / Bug修复 / 安全加固 / 文档完善 |
+| **状态** | 进行中 / 延后 |
+| **负责人** | 宋献 + Claude |
+| **创建日期** | 2026-07-04 |
+
+---
+
+## 📥 输入项来源
+
+### 产品需求
+| 来源文档 | 相关章节 | 说明 |
+|----------|----------|------|
+| `01-产品文档/IT智能服务台-产品需求文档PRD-v2.md` | §4.5 坐席/管理员登录流程 | 登录逻辑调整 |
+| `01-产品文档/IT智能服务台-产品需求文档PRD-v2.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` | - | 架构决策记录 |
+
+### 原型设计
+| 来源文档 | 页面 | 说明 |
+|----------|------|------|
+| `01-产品文档/01-02产品设计/agent-workspace-v5_4.html` | 坐席工作台 | v5.4 UI |
+| `04-原型设计/prototypes-原型图/h5-user-wecom-style-v2-desktop.html` | H5用户端 | v2 桌面版 |
+| `01-产品文档/01-02产品设计/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 |
+