lingyue-zhibao/test/TEST_SUMMARY.md

测试结果总结

测试环境

• 使用模型：Claude Sonnet 4.5
• 测试时间：2026-01-17
• 测试文件：test/test.docx (3.49 MB)

修复的问题

1. 外键约束失败（已修复 ✅）

问题： parse_tasks 表的外键约束要求 document_id 必须存在于 documents 表中，但上传流程没有创建 documents 记录。

修复：

• 在 FileUploadService 中添加 DocumentService 依赖
• 上传文件后先创建 documents 记录
• 修复 DocumentService.saveDocument() 方法逻辑，支持外部指定 ID 的插入操作
• 测试脚本添加用户注册步骤，确保 userId 存在于 users 表

相关提交：

• b22a18c - fix: 修复文件上传时外键约束失败问题
• 72248a3 - fix: 修复 DocumentService.saveDocument 方法逻辑

2. PostgreSQL JSONB 类型处理（已修复 ✅）

问题： MyBatis-Plus 的 JacksonTypeHandler 无法正确处理 PostgreSQL 的 JSONB 类型字段。

修复：

• 创建自定义的 PostgreSqlJsonbTypeHandler
• 使用 PGobject 正确设置 JSONB 类型
• 更新 ParseTask 实体使用新的类型处理器

相关提交：

• 06b9243 - fix: 修复 ParseTask 实体 options 字段 JSONB 类型处理
• 839cb73 - fix: 添加 PostgreSQL JSONB 类型处理器

3. 补充表缺失（非阻塞问题 ⚠️）

问题： text_storage 表不存在，导致记录文本存储路径失败。

说明： 这不是阻塞性问题。代码已经有异常捕获，失败不影响主流程。

解决方案：

• 执行 backend/sql/supplement_tables.sql 初始化补充表
• 参考 backend/sql/README_SUPPLEMENT.md 获取详细说明

测试流程验证

✅ 成功的步骤

1. 用户注册 - 测试脚本自动注册唯一用户
2. 文件上传 - 3.49 MB Word 文档上传成功
3. 文档记录创建 - documents 表记录创建成功
4. 解析任务创建 - parse_tasks 表记录创建成功（外键约束满足）
5. Word 文本提取 - 成功提取文档文本内容
6. 文本写入 - 文本写入到 /data/lingyue/texts/{id}/{documentId}.txt
7. 版面分析 - 识别到 22 个版面元素
8. 任务状态保存 - JSONB 类型字段保存成功

⚠️ 非阻塞警告

• Redis 连接失败 - Redis 未启动，不影响核心功能
• text_storage 记录失败 - 补充表未初始化，不影响解析流程

测试脚本功能

test/test_upload_api.sh 提供以下功能：

基本用法

# 默认配置 (localhost:5232)
./test/test_upload_api.sh

# 指定服务器
./test/test_upload_api.sh 192.168.1.100 5232

# 上传并轮询状态
./test/test_upload_api.sh -p

# 查询上次上传的状态
./test/test_upload_api.sh -s

测试流程

1. 检查依赖（curl、jq）
2. 验证测试文件存在
3. 检查服务健康状态
4. 自动注册测试用户
5. 上传文件
6. 查询解析状态
7. 可选：轮询直到完成

建议的下一步

必需操作

1. 初始化补充表

   psql -U postgres -d lingyue_zhibao -f backend/sql/supplement_tables.sql
   

可选操作

1. 启动 Redis - 如果需要使用缓存功能

2. 初始化 RAG 表 - 如果需要使用 RAG 检索功能

   psql -U postgres -d lingyue_zhibao -f backend/sql/rag_tables.sql
   

已提交的修复

所有修复已提交到 dev 分支：

508ed6b - docs: 添加数据库补充表初始化说明文档
839cb73 - fix: 添加 PostgreSQL JSONB 类型处理器
06b9243 - fix: 修复 ParseTask 实体 options 字段 JSONB 类型处理
72248a3 - fix: 修复 DocumentService.saveDocument 方法逻辑
b22a18c - fix: 修复文件上传时外键约束失败问题
a54573c - test: 添加文件上传接口测试脚本
b09d6c3 - test: 添加测试文件 test.docx

结论

✅ 文件上传和解析核心功能已正常工作

主要流程（用户注册 → 文件上传 → 文档记录 → 解析任务 → 文本提取 → 版面分析 → 状态保存）全部成功完成。

非核心功能（文本存储路径记录）需要初始化补充表后才能完全正常工作。