# 文档处理功能测试计划

**日期**: 2026-06-23
**目标**: 验证文档处理功能（U1-U9）是否完整实现 R1-R28 需求，并发现潜在 Bug

## 测试范围

### 需求覆盖矩阵

| 需求 | 描述 | 现有覆盖 | 测试计划 |
|------|------|----------|----------|
| R1 | Word 创建 | test_word_renderer.py | 已覆盖，补充边界 |
| R2 | Excel 创建 | test_excel_renderer.py | 已覆盖，补充边界 |
| R3 | PDF 创建 | test_pdf_renderer.py | 已覆盖，补充 CJK |
| R4 | 文档读取 | test_document_tool.py | 已覆盖，补充 PDF/HTML |
| R5-R8 | Agent 工具 | test_document_tool.py | 已覆盖 |
| R9-R10 | REST API | test_documents.py | 已覆盖，补充认证 |
| R11-R12 | 存储+元数据 | test_db.py | 已覆盖 |
| R13 | 路径遍历防护 | test_db.py | 已覆盖 |
| R14 | 文件命名 | test_db.py | 已覆盖 |
| R15 | 下载 | test_documents.py | 已覆盖 |
| R16 | 过期清理 | **未实现** | 标记为已知缺口 |
| R17-R22 | 前端 | 无后端测试 | 前端手动验证 |
| R23-R25 | 模板填充 | test_template_renderer.py | 已覆盖 |
| R26 | SSTI 防护 | test_template_renderer.py | 补充深度测试 |
| R27 | 认证 | **未测试** | **新增认证测试** |
| R28 | 文件大小限制 | 部分覆盖 | 补充 create 限制 |

### 端到端流程

| 流程 | 描述 | 现有覆盖 | 测试计划 |
|------|------|----------|----------|
| F1 | 对话触发文档生成 | 未覆盖 | **新增 E2E 测试** |
| F2 | 前端独立操作 | 部分覆盖 | **新增完整流程测试** |
| F3 | 面板查看/下载 | 部分覆盖 | **新增 list→download 流程** |

## 测试用例清单

### 1. 安全测试（高优先级）

#### 1.1 认证测试（R27）
- `test_create_without_api_key_returns_401`: 配置 API key 但请求不带 → 401
- `test_create_with_wrong_api_key_returns_401`: 错误 key → 401
- `test_create_with_valid_api_key_returns_200`: 正确 key → 200
- `test_download_without_api_key_returns_401`: 下载不带 key → 401
- `test_list_without_api_key_returns_401`: 列表不带 key → 401
- `test_upload_template_without_api_key_returns_401`: 上传不带 key → 401
- `test_api_key_via_query_param`: query param 传 key → 200
- `test_api_key_via_header`: header 传 key → 200
- `test_no_key_configured_allows_all`: 未配置 key → 允许所有（向后兼容）

#### 1.2 模板路径遍历（Bug 确认）
- `test_create_with_template_path_traversal`: template=`../../etc/passwd` → 应 404/400
- `test_create_with_template_absolute_path`: template=`/etc/passwd` → 应 404/400
- `test_create_with_template_null_byte`: template=`file.docx\x00../../etc/passwd` → 应拒绝

#### 1.3 深度 SSTI 测试（R26）
- `test_ssti_class_subclasses`: `{{ ''.__class__.__mro__[1].__subclasses__() }}` → 拦截
- `test_ssti_config_access`: `{{ config }}` → 不泄露
- `test_ssti_globals_access`: `{{ namespace.__init__.__globals__ }}` → 拦截
- `test_ssti_import_statement`: `{% import os %}` → 拦截

### 2. 端到端集成测试（高优先级）

#### 2.1 F1: 创建→列表→下载完整流程
- `test_e2e_create_word_list_download`: 创建 Word → 列表包含 → 下载内容匹配
- `test_e2e_create_excel_list_download`: 创建 Excel → 列表包含 → 下载内容匹配
- `test_e2e_create_pdf_list_download`: 创建 PDF → 列表包含 → 下载内容匹配
- `test_e2e_multiple_documents_same_conversation`: 同一对话多文档，列表按时间倒序

#### 2.2 F2: 模板完整流程
- `test_e2e_upload_template_create_download`: 上传模板 → 用模板创建 → 下载 → 验证变量已替换
- `test_e2e_template_with_loop`: 模板含循环 → 填充 → 下载 → 验证循环展开

#### 2.3 F3: 跨对话隔离
- `test_e2e_conversation_isolation`: 对话 A 的文档不出现在对话 B 列表中
- `test_e2e_download_other_conversation`: 下载不关联当前对话的文档（当前无 ACL，验证可下载）

### 3. Bug 查找测试（中优先级）

#### 3.1 数据库并发
- `test_concurrent_inserts`: 10 个并发 insert_document 全部成功
- `test_concurrent_create_document`: 并发 create_document 无锁错误

#### 3.2 文件系统异常
- `test_download_metadata_exists_file_missing`: 元数据存在但文件被删 → 404
- `test_create_disk_write_failure`: mock 写入失败 → 500（不产生孤立元数据）

#### 3.3 模板异常
- `test_create_with_invalid_docx_template`: 模板不是有效 docx → 错误处理
- `test_create_with_corrupted_template`: 损坏的 docx 文件 → 错误处理
- `test_template_with_missing_variables`: data 缺少变量 → 宽松处理（不崩溃）

#### 3.4 边界情况
- `test_create_empty_content`: 空内容 → 各格式正确处理
- `test_create_very_large_content`: 超大内容（10MB Markdown）→ 不超时
- `test_filename_unicode`: Unicode 文件名 → 正确存储
- `test_filename_only_special_chars`: 文件名只有特殊字符 → sanitize 后非空
- `test_excel_empty_cells_in_renderer`: Markdown 表格含空单元格 → 正确渲染
- `test_excel_special_chars_in_cells`: 单元格含 `|`、换行 → 正确处理
- `test_pdf_mixed_cjk_ascii`: 中英文混合 → 正确渲染
- `test_read_pdf_file`: 读取自创建的 PDF → 返回文本
- `test_read_html_file`: 读取 HTML → 返回纯文本

#### 3.5 数据一致性
- `test_create_document_metadata_matches_file`: 元数据 size 与实际文件大小一致
- `test_create_document_filename_has_correct_extension`: 各格式文件扩展名正确
- `test_download_returns_correct_filename`: 下载响应的 filename 与元数据一致

## 已知缺口（不在本次测试范围）

- R16 过期清理：源码未实现，需先实现再测试
- R17-R22 前端：需手动验证或 E2E 浏览器测试
- 文件大小限制（R28 for /create）：需先实现 content 大小限制

## 验证标准

- 所有安全测试通过（认证、路径遍历、SSTI）
- 所有 E2E 流程测试通过
- Bug 查找测试发现的问题记录为 Issue
- 现有 110 个测试无回归