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,504 @@
+# 测试方法论指南
+
+> **版本**: v1.0 | **生效日期**: 2026-07-14 | **维护人**: Duckula
+>
+> 本规范定义 IT 智能服务台项目的测试策略、方法和流程。
+
+---
+
+## 1. 测试类型定义
+
+### 1.1 测试分层模型
+
+| 层级 | 测试类型 | 覆盖范围 | 工具/方法 | 产出物 |
+|------|---------|---------|----------|--------|
+| **Tier 0** | 基础设施测试 | 数据库、缓存、核心服务、工具类 | pytest 单元测试 | `test_*.py` |
+| **Tier 1** | API 层测试 | 接口正确性、参数校验、权限控制 | pytest + curl | `test_*.py` |
+| **Tier 2** | 集成测试 | 多模块交互、状态机、事务一致性 | pytest | `test_*.py` |
+| **E2E** | 端到端测试 | 完整业务流程、用户体验 | Playwright 浏览器自动化 | 测试报告 + 截图 |
+
+---
+
+## 2. 测试类型选择标准
+
+### 2.1 判断决策树
+
+```
+新增功能/代码变更
+    │
+    ├── 仅修改工具类 / 工具函数 / 算法逻辑
+    │   └── 选择：Tier 0 单元测试
+    │   └── 判断标准：无外部依赖，纯函数逻辑
+    │
+    ├── 新增/修改 API 接口
+    │   └── 选择：Tier 1 API 测试
+    │   └── 判断标准：有 HTTP 端点、需要参数校验
+    │
+    ├── 多模块交互 / 状态流转 / 事务一致性
+    │   └── 选择：Tier 2 集成测试
+    │   └── 判断标准：涉及 2+ 服务/模块的数据流转
+    │
+    └── 核心业务流程 / 用户体验验证
+        └── 选择：E2E 测试
+        └── 判断标准：需要浏览器真实操作、多端交互
+```
+
+### 2.2 场景速查表
+
+| 场景 | 推荐测试类型 | 必做级别 |
+|------|-------------|---------|
+| 新增工具函数（如 TokenCounter） | Tier 0 | 必须 |
+| 新增 API 端点 | Tier 1 | 必须 |
+| 修改数据库模型/迁移脚本 | Tier 0 + Tier 1 | 必须 |
+| 修改 WebSocket 逻辑 | Tier 2 | 必须 |
+| 修改前端交互流程 | E2E | 必须 |
+| 登录/认证流程变更 | E2E + Tier 1 | 必须 |
+| 消息发送/AI 回复流程 | E2E | 必须 |
+| 知识库/审批流程 | Tier 1 + Tier 2 | 必须 |
+| 安全/权限控制变更 | Tier 1 + E2E | 必须 |
+
+---
+
+## 3. 产出物标准
+
+### 3.1 测试用例文档模板
+
+每个功能测试用例文档应包含：
+
+```markdown
+# [功能名称] 测试用例
+
+> **功能模块**: xxx | **测试工程师**: xxx | **日期**: xxx
+
+## 1. 测试范围
+- 测试的 API/模块列表
+
+## 2. 前置条件
+- 测试账号、环境要求、依赖服务
+
+## 3. 测试用例清单
+
+| TC_ID | 场景 | 前置条件 | 测试步骤 | 预期结果 | 状态 |
+|-------|------|---------|---------|---------|------|
+| xxx   |      |         |         |         |      |
+
+## 4. 测试数据
+- 测试用账号、测试数据构造方式
+
+## 5. 执行记录
+
+| 日期 | 测试人员 | 环境 | 结果 |
+|------|---------|------|------|
+|      |         |      |      |
+
+## 6. 缺陷记录
+
+| 缺陷ID | 对应TC | 描述 | 严重程度 | 状态 |
+|--------|--------|------|----------|------|
+|        |        |      |          |      |
+```
+
+### 3.2 测试报告模板
+
+```markdown
+# [版本/功能] 测试报告
+
+> **测试工程师**: xxx | **日期**: xxx | **状态**: 通过/失败
+
+## 测试概览
+- 测试总数、通过数、失败数、跳过数
+
+## 测试明细
+| 用例类型 | 数量 | 通过 | 失败 |
+|----------|------|------|------|
+|          |      |      |      |
+
+## Bug 历程
+| Bug ID | 描述 | 影响 | 修复状态 |
+
+## 结论
+- 是否可发布
+- 风险项
+```
+
+---
+
+## 4. 流程规范
+
+### 4.1 新功能上线流程
+
+```
+需求评审通过
+    │
+    ├── 1. 编写测试用例文档
+    │   └── 路径: docs/03-测试文档/03-功能测试用例/
+    │   └── 命名: [功能名]-测试用例-YYYYMMDD.md
+    │
+    ├── 2. 开发代码
+    │
+    ├── 3. 执行测试
+    │   ├── Tier 0/1/2 → pytest
+    │   └── E2E → Playwright
+    │
+    ├── 4. 产出测试报告
+    │   └── 路径: docs/03-测试文档/04-版本测试报告/
+    │   └── 命名: [功能名]-测试报告-YYYYMMDD.md
+    │
+    └── 5. 发布
+```
+
+**强制要求**：
+- 测试用例文档必须在代码开发前完成初版
+- 测试用例文档必须随功能上线同步更新
+- 测试报告是发布的必要前置条件
+
+### 4.2 故障修复后流程
+
+```
+故障发现 → 根因分析 → 修复代码
+    │
+    ├── 1. 定位受影响的测试用例
+    │   └── 在 docs/03-测试文档/ 中搜索相关功能
+    │
+    ├── 2. 编写/更新自动化测试
+    │   └── 在 backend/tests/ 中添加/更新 test_*.py
+    │
+    ├── 3. 执行自动化测试
+    │   └── pytest -v
+    │
+    ├── 4. 如有 E2E 场景，补充 E2E 测试
+    │   └── Playwright 浏览器自动化
+    │
+    └── 5. 更新测试用例文档
+        └── 补充故障场景用例
+```
+
+**强制要求**：
+- 故障修复后必须补充相关自动化测试
+- 测试通过才能宣布故障关闭
+
+### 4.3 历史功能检查流程
+
+```
+定期检查（建议每季度）
+    │
+    ├── 1. 列出所有已上线功能
+    │   └── 参考 CHANGELOG.md / 版本发布记录
+    │
+    ├── 2. 检查是否存在测试用例文档
+    │   └── docs/03-测试文档/03-功能测试用例/
+    │
+    ├── 3. 如缺失，补充测试用例文档
+    │   └── 逆向分析功能 → 编写测试用例
+    │
+    ├── 4. 检查测试用例是否仍有效
+    │   ├── 接口路径是否变更
+    │   ├── 参数是否变化
+    │   └── 功能是否已废弃
+    │
+    ├── 5. 处理废弃/替换的功能用例
+    │   ├── 移动到 docs/08-历史归档/
+    │   └── 更新 README.md 中的索引
+    │
+    └── 6. 产出检查报告
+```
+
+**强制要求**：
+- 缺失测试用例的功能必须补齐
+- 废弃功能必须从测试用例目录移除或标注
+
+---
+
+## 5. 目录结构规范
+
+```
+docs/03-测试文档/
+├── 00-测试规范/                    # 本文档
+│   └── 测试方法论指南.md
+│
+├── 01-综合报告/                    # 合并汇总类报告
+│   └── QA_COMPREHENSIVE_REPORT.md
+│
+├── 02-E2E测试/                    # 端到端测试
+│   ├── E2E-CHECKLIST-*.md         # 验收清单
+│   └── e2e-screenshots/           # 截图证据
+│
+├── 03-功能测试用例/                # 功能级测试用例文档
+│   ├── [功能名]-测试用例-YYYYMMDD.md
+│   └── ...
+│
+├── 04-版本测试报告/                # 按版本/日期的测试报告
+│   └── [功能名]-测试报告-YYYYMMDD.md
+│
+└── README.md                       # 分类索引
+```
+
+---
+
+## 6. 命名约定
+
+| 类型 | 命名格式 | 示例 |
+|------|---------|------|
+| 测试用例文档 | `[功能名]-测试用例-YYYYMMDD.md` | `OTP绑定-测试用例-20260708.md` |
+| 测试报告 | `[功能名]-测试报告-YYYYMMDD.md` | `登录功能-测试报告-20260706.md` |
+| E2E 报告 | `[功能名]-E2E验证报告-YYYYMMDD.md` | `方案A消息发送延时-E2E验证报告-20260708.md` |
+| 测试代码文件 | `test_[模块名].py` | `test_otp_bind_flow.py` |
+
+---
+
+## 7. 质量门禁
+
+### 7.1 发布门槛
+
+| 测试类型 | 通过率要求 | 备注 |
+|---------|-----------|------|
+| Tier 0 | 100% | 基础设施不能有失败 |
+| Tier 1 | 100% | API 必须全部通过 |
+| Tier 2 | 100% | 集成测试必须通过 |
+| E2E | 核心流程 100% | 核心用户流程不可失败 |
+
+### 7.2 阻断规则
+
+- **P0 级别故障**：必须通过 E2E 验证才能发布
+- **认证/安全变更**：必须通过 Tier 1 + E2E 双重验证
+- **数据库变更**：必须通过 Tier 0 迁移测试
+
+---
+
+## 8. 测试数据管理规范
+
+### 8.1 数据分类
+
+| 数据类型 | 说明 | 管理方式 |
+|---------|------|---------|
+| **测试账号** | 坐席员工、管理员测试账号 | 固定账号，维护在配置文件中 |
+| **Mock 数据** | 模拟的会话、消息、审批数据 | 代码中 fixtures 或独立 seed 文件 |
+| **生产脱敏数据** | 从生产导出的脱敏数据 | 存储在 `data/test/` 目录，严格访问控制 |
+| **临时测试数据** | 每次测试生成的临时数据 | 测试用例自行清理，禁用手动清理 |
+
+### 8.2 测试数据原则
+
+- **隔离性**：每个测试用例使用独立数据，不依赖其他测试的执行结果
+- **可重复性**：测试数据可重复使用，测试结果一致
+- **清理机制**：测试完成后自动清理临时数据，不污染环境
+- **脱敏要求**：从生产导出的数据必须脱敏（手机号、身份证号等）
+
+### 8.3 测试数据目录结构
+
+```
+data/test/
+├── README.md                    # 数据说明
+├── accounts.json                # 测试账号配置
+├── mock_sessions.json           # Mock 会话数据
+└── seed/                       # 数据种子文件
+    ├── conversations.json
+    └── knowledge.json
+```
+
+### 8.4 测试账号规范
+
+| 角色 | user_id | 用途 |
+|------|---------|------|
+| 管理员 | `sxn` | 管理员功能测试 |
+| 坐席 | `sxn` | 坐席功能测试 |
+| 员工 | `test_user` | 员工端功能测试 |
+| Mock 用户 | `E2E_BROWSER` | E2E 自动化测试 |
+
+---
+
+## 9. 测试环境配置标准
+
+### 9.1 环境分类
+
+| 环境 | 用途 | 数据库 | 特点 |
+|------|------|--------|------|
+| **开发环境** | 本地开发调试 | SQLite 内存 | 快速启动，无持久化 |
+| **测试环境** | 自动化测试 | PostgreSQL | 与生产结构一致 |
+| **预发布环境** | 上线前验证 | 生产数据副本 | 接近生产 |
+| **生产环境** | 正式运行 | PostgreSQL | 真实数据 |
+
+### 9.2 环境配置要求
+
+#### 9.2.1 开发环境
+
+```bash
+# .env 配置示例
+DEV_MODE=true
+DATABASE_URL=sqlite:///./test_dev.db
+REDIS_URL=redis://localhost:6379
+# 使用 Mock 服务，无需真实企微/Dify
+```
+
+#### 9.2.2 测试环境
+
+```bash
+# .env 配置示例
+DEV_MODE=false
+DATABASE_URL=postgresql://test:test@localhost:5432/wecom_it_test
+REDIS_URL=redis://localhost:6379/1
+# 使用测试用企微应用/测试用 Dify
+WECOM_APP_ID=xxx
+DIFY_API_KEY=xxx
+```
+
+### 9.3 环境切换规则
+
+| 场景 | 使用环境 | 理由 |
+|------|---------|------|
+| 单元测试 (Tier 0) | 开发环境 (SQLite) | 快速、独立 |
+| API 测试 (Tier 1) | 测试环境 | 验证真实数据库 |
+| 集成测试 (Tier 2) | 测试环境 | 多模块交互 |
+| E2E 测试 | 测试/预发布环境 | 接近生产 |
+| 上线前验证 | 预发布环境 | 最终确认 |
+
+### 9.4 环境健康检查
+
+每次测试执行前必须检查：
+
+- [ ] 数据库连接正常
+- [ ] Redis 连接正常
+- [ ] 后端服务可访问
+- [ ] 依赖服务（Dify、RAGFlow 等）可用
+
+---
+
+## 10. CI/CD 集成测试规范
+
+### 10.1 流水线阶段
+
+```
+代码提交 → 静态检查 → 单元测试 → 构建 → 集成测试 → E2E测试 → 部署
+                              ↓           ↓         ↓
+                           Tier 0     Tier 1/2   需要时
+```
+
+### 10.2 各阶段要求
+
+#### 10.2.1 静态检查阶段
+
+| 检查项 | 工具 | 失败处理 |
+|--------|------|---------|
+| Python 类型检查 | mypy | 阻断 |
+| 代码格式 | ruff / black | 阻断 |
+| 安全扫描 | bandit | 阻断 |
+
+#### 10.2.2 单元测试阶段 (Tier 0)
+
+```yaml
+# .github/workflows/test.yml 示意
+- name: Run Tier 0 tests
+  run: |
+    pytest backend/tests/test_*.py -v --tb=short
+  timeout-minutes: 10
+```
+
+**要求**：
+- 必须通过
+- 覆盖率不做强制要求，但核心模块应覆盖
+
+#### 10.2.3 集成测试阶段 (Tier 1/2)
+
+```yaml
+- name: Run Tier 1/2 tests
+  run: |
+    pytest backend/tests/test_api_*.py -v --tb=short
+  timeout-minutes: 20
+  services:
+    postgres:
+      image: postgres:15
+      env:
+        POSTGRES_DB: wecom_it_test
+    redis:
+      image: redis:7
+```
+
+**要求**：
+- 使用独立的测试数据库
+- 测试完成后清理数据
+
+#### 10.2.4 E2E 测试阶段
+
+```yaml
+- name: Run E2E tests
+  run: |
+    pytest tests/e2e/ -v --tb=short
+  timeout-minutes: 30
+  conditions: ${{ github.event_name == 'pull_request' }}
+```
+
+**要求**：
+- 仅在 PR 时执行
+- 生产部署后可通过手动触发
+
+### 10.3 分支策略
+
+| 分支 | 执行测试 | 部署目标 |
+|------|---------|---------|
+| feature/* | Tier 0 + Tier 1 | 不自动部署 |
+| bugfix/* | Tier 0 + Tier 1 | 不自动部署 |
+| main | 全部 Tier | 自动部署到测试环境 |
+| release/* | 全部 Tier + E2E | 预发布环境 |
+
+### 10.4 失败处理
+
+| 失败类型 | 处理方式 |
+|---------|---------|
+| Tier 0 失败 | 阻断合并 |
+| Tier 1/2 失败 | 阻断合并 |
+| E2E 失败 | 警告，可选择是否阻断 |
+| 超时 | 重试 1 次，仍失败则阻断 |
+
+---
+
+## 11. 附录
+
+### 11.1 测试工具清单
+
+| 用途 | 工具 | 配置 |
+|------|------|------|
+| Python 单元/集成测试 | pytest + pytest-asyncio | `conftest.py` |
+| 浏览器自动化 | Playwright | Python binding |
+| HTTP 测试 | curl / httpx | 直接调用 API |
+| 数据库测试 | 直接 SQL / SQLAlchemy | 迁移脚本验证 |
+
+### 11.2 配置文件模板
+
+#### 11.2.1 测试配置 (pytest.ini)
+
+```ini
+[pytest]
+testpaths = backend/tests
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+asyncio_mode = auto
+addopts = -v --tb=short
+```
+
+#### 11.2.2 E2E 配置 (playwright.config.py)
+
+```python
+import pytest
+
+@pytest.fixture(scope="session")
+def browser_type_launch_args(browser_type_launch_args):
+    return {
+        **browser_type_launch_args,
+        "headless": True,
+    }
+```
+
+### 11.3 相关文档
+
+- 技术架构：`../03-技术架构/`
+- 产品需求：`../02-产品需求/`
+- 项目管理：`../07-项目管理/`
+- 历史归档：`../08-历史归档/`
+
+---
+
+> **修订记录**
+>
+> | 版本 | 日期 | 变更内容 | 修改人 |
+> |------|------|----------|--------|
+> | v1.0 | 2026-07-14 | 初始版本，整合测试方法、数据、环境、CI/CD规范 | Duckula |