fischer-agentkit/docs/plans/2026-06-23-document-processing-test-plan.md

文档处理功能测试计划

日期: 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 个测试无回归