leaudit-platform-frontend/database/migrations

文档版本管理功能 - 部署指南（使用函数名前缀）

📋 方案说明

使用 函数名前缀 documents_ 来区分版本管理函数，无需创建 schema。

3个新函数：

• documents_get_latest_documents_with_version_info - 获取文档列表
• documents_count_latest_documents_with_filters - 统计文档总数
• documents_get_document_history - 获取历史版本

---

🚀 快速部署（2步）

步骤1：在 Navicat 中执行 SQL 脚本

方法A：查询窗口

1. 打开 Navicat，连接到 PostgreSQL 数据库
2. 点击 "查询" → "新建查询"
3. 打开 add_document_version_management.sql 文件
4. 复制所有内容到查询窗口
5. 点击 "运行" ▶️ 按钮

方法B：运行 SQL 文件

1. 右键点击数据库
2. 选择 "运行 SQL 文件"
3. 选择 add_document_version_management.sql
4. 点击 "开始"

步骤2：重启应用

npm run build
pm2 restart all

就这么简单！ ✅

---

🔍 验证函数是否创建成功

在 Navicat 中执行：

-- 查看新创建的函数
SELECT proname
FROM pg_proc
WHERE proname LIKE 'documents_%';

应该返回 3 个函数名：

documents_get_latest_documents_with_version_info
documents_count_latest_documents_with_filters
documents_get_document_history

在 Navicat 中查看函数

你的数据库
  └─ public (schema)
       └─ 函数
            ├─ documents_get_latest_documents_with_version_info(...)
            ├─ documents_count_latest_documents_with_filters(...)
            └─ documents_get_document_history(...)

---

🧪 测试函数

在 Navicat 查询窗口执行：

-- 测试1：获取文档列表（假设用户ID为1）
SELECT * FROM documents_get_latest_documents_with_version_info(1, 1, 10);

-- 测试2：统计文档总数
SELECT documents_count_latest_documents_with_filters(1);

-- 测试3：获取历史版本（如果有同名文档）
SELECT * FROM documents_get_document_history('测试文档.pdf', 1, 123);

---

📁 在 Navicat 中操作函数

查看函数定义

1. 在左侧树形结构中找到 public → 函数
2. 找到 documents_get_latest_documents_with_version_info
3. 右键 → "设计函数" 或 "查看 SQL"

测试函数（图形界面）

1. 右键点击函数
2. 选择 "执行函数"
3. 输入参数值（如 p_user_id: 1, p_page: 1, p_page_size: 10）
4. 点击 "运行"

删除函数（如果需要重建）

DROP FUNCTION IF EXISTS documents_get_latest_documents_with_version_info;
DROP FUNCTION IF EXISTS documents_count_latest_documents_with_filters;
DROP FUNCTION IF EXISTS documents_get_document_history;

-- 然后重新执行 SQL 脚本

---

✅ 功能验证

1. 访问文档列表页面

打开浏览器：http://your-domain/documents

2. 检查显示效果

✅ 有历史版本的文档：

[▶️] 📄 合同审查.pdf
        合同审查  v1 (共3个历史版本)
        问题数量：3 🟢 ↓ -2

✅ 单版本文档：

📄 新文档.pdf
   合同审查
   问题数量：4

3. 测试展开功能

点击 [▶️] 图标，应该能看到：

[🔽] 📄 合同审查.pdf
        合同审查  v1 (共3个历史版本)
        问题数量：3 🟢 ↓ -2

  ├─ 🕒 v2 版本
  │      问题数量：5 🔴 ↑ +2
  │
  ├─ 🕒 v3 版本
  │      问题数量：3 🟢 ↓ -1
  │
  └─ 🕒 v4 版本 (最早)
         问题数量：4

---

❌ 故障排查

问题1：函数未创建

症状：查询不到函数

解决：

-- 检查是否有错误
-- 在 Navicat 的"消息"窗口查看错误信息

-- 重新执行 SQL 脚本

问题2：前端报错

症状：浏览器控制台显示 function does not exist

解决：

# 1. 确认函数已创建
# 在 Navicat 中执行：
SELECT proname FROM pg_proc WHERE proname LIKE 'documents_%';

# 2. 确认前端代码已更新
# 检查 app/api/files/documents.ts 中的函数名

# 3. 重新构建应用
npm run build
pm2 restart all

问题3：数据不显示

症状：页面显示空白或加载失败

检查清单：

• ✅ SQL 脚本是否执行成功
• ✅ 函数是否创建在 public schema 中
• ✅ 应用是否重启
• ✅ 浏览器控制台是否有错误

解决方案：

# 1. 检查 PostgREST 日志
journalctl -u postgrest -n 50

# 2. 检查应用日志
pm2 logs

# 3. 清除浏览器缓存
# 按 Ctrl + Shift + R (Windows) 或 Cmd + Shift + R (Mac)

---

📊 性能优化

SQL 脚本自动创建了 4 个索引来优化查询性能：

-- 1. 用户+名称+时间索引
idx_documents_user_name_created

-- 2. 名称+用户+时间索引
idx_documents_name_user_created

-- 3. 创建时间索引
idx_documents_created_at

-- 4. 文件状态索引
idx_documents_status

查看索引：

SELECT indexname, indexdef
FROM pg_indexes
WHERE tablename = 'documents';

---

🔐 权限配置（可选）

如果你使用了特定的 PostgREST 用户，需要授权：

-- 查看你的 PostgREST 用户名
SELECT usename FROM pg_user;

-- 授权函数（替换 'authenticator' 为实际用户名）
GRANT EXECUTE ON FUNCTION documents_get_latest_documents_with_version_info TO authenticator;
GRANT EXECUTE ON FUNCTION documents_count_latest_documents_with_filters TO authenticator;
GRANT EXECUTE ON FUNCTION documents_get_document_history TO authenticator;

---

📚 相关文档

• SQL 脚本：add_document_version_management.sql
• 完整技术文档：docs/文档版本管理设计方案.md
• UI 原型：docs/UI设计原型.html

---

✅ 部署检查清单

• SQL 脚本执行成功
• 3个函数已创建
• 应用已重新构建和重启
• 文档列表页面正常显示
• 展开/折叠功能正常
• 问题数量差异正确显示（红色/绿色）

---

🎉 完成！

现在你可以：

• ✅ 查看同名文档的版本历史
• ✅ 展开/折叠历史版本
• ✅ 对比问题数量变化
• ✅ 享受高性能的版本管理功能

部署完成，开始使用吧！ 🚀