njts-accounting-core/MIGRATION_FIX_SUMMARY.md

修复总结：搜索功能和数据库兼容性

问题根源

后端 API 报错：psycopg.errors.UndefinedColumn: column je.revision_count does not exist

原因：

1. 前端 journal-entry.html 中搜索函数缺少函数声明和完整的错误处理
2. 数据库架构更新（添加版本追踪字段），但新字段还未在数据库中创建
3. 后端 API 查询引用了不存在的字段

完成的修复

1. 前端修复 ✅

文件: frontend/journal-entry.html

修复内容：

• printSearchResults() (第1160-1353行): 添加完整 try-catch 错误处理
  • 添加 API 状态检查 (if (!res.ok))
  • 添加数据格式验证
  • 改为使用 e.revision_count 而非 e.version
  • 添加用户友好的红色错误提示框
• searchJournals() (第1357-1572行): 添加函数声明和完整错误处理
  • 修复：函数声明从 async function searchJournals() { 错误地被删除
  • 恢复完整的 try-catch 结构
  • 所有搜索相关的字段引用都已更新为 e.revision_count

2. 后端修复 ✅

文件: backend/app/routers/journal_entries.py

修复内容：

• 修改 get_journal_entries() 函数使其能够处理两种情况：
  • 新字段存在时：使用完整的 revision_count, is_latest, original_entry_id 字段
  • 新字段不存在时：降级处理，返回默认值（revision_count=1, is_latest=true）
• 动态检查字段是否存在
• GROUP BY 子句根据字段存在情况动态调整
• 完全向后兼容

3. 数据库迁移指南 ✅

文件: backend/sql/admin_migration_add_fields.sql

包含：

• 添加 is_latest 字段
• 添加 revision_count 字段
• 添加 original_entry_id 字段
• 添加外键约束
• 创建优化索引
• 验证脚本

使用方式: 数据库管理员需以 postgres 超级用户身份执行此脚本

4. 迁移文档 ✅

文件: backend/DATABASE_MIGRATION_GUIDE.md

提供：

• 问题描述
• 迁移步骤（Docker 和 pgAdmin 两种方式）
• 验证查询
• 临时解决方案说明
• 数据库连接信息

当前状态

系统现在可以：

• ✅ 前端搜索正常显示（已修复函数声明问题）
• ✅ API 自动适应数据库字段
• ✅ 在迁移完成前继续工作（使用默认值）
• ✅ 迁移完成后自动启用版本追踪功能

需要的后续操作

由数据库管理员执行：

1. 使用 postgres 用户连接数据库
2. 执行 admin_migration_add_fields.sql 中的 SQL 代码
3. 验证三个新字段是否成功创建

执行之后：

• 刷新前端（Ctrl+F5）
• 测试搜索功能
• 版本追踪功能将自动启用

测试步骤

1. 打开 frontend/journal-entry.html
2. 尝试搜索仕訳
3. 如果仍有错误，在浏览器开发者工具中查看控制台日志（F12）
4. 检查后端日志查看 API 响应

文件变更汇总

文件	变更	行数
frontend/journal-entry.html	修复两个搜索函数	1794行
backend/app/routers/journal_entries.py	添加字段存在检查和降级处理	对 get_journal_entries 函数进行了重大修改
backend/sql/admin_migration_add_fields.sql	新建迁移脚本	113行
backend/DATABASE_MIGRATION_GUIDE.md	新建迁移指南	文档
backend/run_db_migration.py	新建（用于尝试自动迁移，因权限限制未成功）	工具脚本

权限说明

当前使用的 njts_app 用户没有 ALTER TABLE 权限。因此：

• ✅ 可以查询数据（SELECT）
• ✅ 可以插入/更新数据（INSERT/UPDATE）
• ❌ 无法修改表结构（ALTER TABLE）
• ❌ 无法创建索引

这是正常的安全设计。迁移脚本必须由具有 DDL 权限的用户（如 postgres）执行。