leaudit-platform-frontend/database/migrations/README_documents_schema.md

文档版本管理 - 使用 documents Schema 部署指南

📋 文件说明

本次使用 documents schema 来组织所有文档版本管理相关的 RPC 函数。

SQL 脚本位置：add_document_version_management_with_schema.sql

---

🚀 快速部署（3步）

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

方法A：通过查询窗口

1. 打开 Navicat，连接到你的 PostgreSQL 数据库
2. 点击 "查询" → "新建查询"
3. 打开 add_document_version_management_with_schema.sql 文件
4. 复制所有内容到查询窗口
5. ⚠️ 重要：将所有的 authenticator 替换为你的实际 PostgREST 用户名
6. 点击 "运行" 按钮

方法B：通过文件导入

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

步骤2：验证函数是否创建成功

在 Navicat 查询窗口执行：

-- 查看 documents schema 中的所有函数
SELECT proname, proargnames
FROM pg_proc p
JOIN pg_namespace n ON p.pronamespace = n.oid
WHERE n.nspname = 'documents';

应该看到 3 个函数：

• get_latest_documents_with_version_info
• count_latest_documents_with_filters
• get_document_history

步骤3：测试函数（可选）

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

-- 测试2：统计文档数量
SELECT documents.count_latest_documents_with_filters(1);

---

📁 Navicat 中查看函数

执行成功后，在 Navicat 左侧树形结构中：

你的数据库
  └─ 模式 (Schemas)
       ├─ public
       └─ documents ← 新创建的 schema
            ├─ 表
            └─ 函数 ← 3个新函数在这里
                 ├─ get_latest_documents_with_version_info
                 ├─ count_latest_documents_with_filters
                 └─ get_document_history

---

⚙️ PostgREST 配置

确保你的 PostgREST 配置文件包含 documents schema：

# /etc/postgrest/config (或其他配置文件路径)

# 添加 documents 到 db-schemas
db-schemas = "public, documents"

# 或者，如果之前没有配置，添加这一行
db-schemas = "public, documents"

修改配置后重启 PostgREST：

sudo systemctl restart postgrest

---

🔐 权限配置

查找你的 PostgREST 用户名

-- 方法1：查看所有数据库用户
SELECT usename FROM pg_user;

-- 方法2：查看当前连接用户
SELECT current_user;

常见的 PostgREST 用户名：

• authenticator
• web_anon
• postgres
• api_user

授权函数给用户

将下面的 YOUR_POSTGREST_USER 替换为你的实际用户名：

-- 授权 schema 使用权限
GRANT USAGE ON SCHEMA documents TO YOUR_POSTGREST_USER;

-- 授权函数执行权限
GRANT EXECUTE ON FUNCTION documents.get_latest_documents_with_version_info TO YOUR_POSTGREST_USER;
GRANT EXECUTE ON FUNCTION documents.count_latest_documents_with_filters TO YOUR_POSTGREST_USER;
GRANT EXECUTE ON FUNCTION documents.get_document_history TO YOUR_POSTGREST_USER;

---

🎯 前端代码已自动适配

前端代码已经修改为使用 documents schema：

// app/api/files/documents.ts

// ✅ 已修改为：
postgrestPost('rpc/documents.get_latest_documents_with_version_info', ...)
postgrestPost('rpc/documents.count_latest_documents_with_filters', ...)
postgrestPost('rpc/documents.get_document_history', ...)

无需手动修改前端代码！

---

🧪 完整测试流程

1. 在 Navicat 中测试 SQL

-- 测试获取文档列表
SELECT * FROM documents.get_latest_documents_with_version_info(
  p_user_id := 1,
  p_page := 1,
  p_page_size := 10
);

-- 测试搜索功能
SELECT * FROM documents.get_latest_documents_with_version_info(
  p_user_id := 1,
  p_page := 1,
  p_page_size := 10,
  p_search_name := '合同'
);

-- 测试历史版本查询
SELECT * FROM documents.get_document_history('测试文档.pdf', 1, 123);

2. 测试 PostgREST API

# 测试获取文档列表
curl -X POST http://your-api-url/rpc/documents.get_latest_documents_with_version_info \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "p_user_id": 1,
    "p_page": 1,
    "p_page_size": 10
  }'

3. 测试前端页面

1. 重启应用：

   npm run build
   pm2 restart all
   

2. 访问文档列表页面：http://your-domain/documents

3. 检查功能：

   • ✅ 文档列表正常显示
   • ✅ 有历史版本的文档显示展开图标
   • ✅ 点击展开图标能看到历史版本
   • ✅ 问题数量差异正确显示（红色/绿色）

---

❌ 故障排查

问题1：函数未创建成功

症状：执行查询时提示 function does not exist

解决方案：

-- 检查 documents schema 是否存在
SELECT schema_name FROM information_schema.schemata WHERE schema_name = 'documents';

-- 如果不存在，手动创建
CREATE SCHEMA IF NOT EXISTS documents;

-- 重新执行 SQL 脚本

问题2：权限不足

症状：前端报错 permission denied

解决方案：

-- 检查当前用户权限
SELECT grantee, privilege_type
FROM information_schema.role_usage_grants
WHERE object_schema = 'documents';

-- 重新授权（替换 YOUR_USER 为实际用户）
GRANT USAGE ON SCHEMA documents TO YOUR_USER;
GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA documents TO YOUR_USER;

问题3：前端调用失败

症状：浏览器控制台报错 404 Not Found

检查清单：

1. PostgREST 配置是否包含 documents schema
2. PostgREST 是否已重启
3. 前端代码是否已更新并重新构建

解决方案：

# 1. 检查 PostgREST 配置
cat /etc/postgrest/config

# 2. 确保包含：
# db-schemas = "public, documents"

# 3. 重启 PostgREST
sudo systemctl restart postgrest

# 4. 重新构建前端
npm run build
pm2 restart all

---

📊 性能优化

SQL 脚本已自动创建以下索引：

-- 1. 用户+名称+时间索引
CREATE INDEX idx_documents_user_name_created
ON documents(user_id, name, created_at DESC);

-- 2. 名称+用户+时间索引
CREATE INDEX idx_documents_name_user_created
ON documents(name, user_id, created_at DESC);

-- 3. 创建时间索引
CREATE INDEX idx_documents_created_at
ON documents(created_at DESC);

-- 4. 文件状态索引
CREATE INDEX idx_documents_status
ON documents(status);

查看索引是否创建成功：

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

---

✅ 部署检查清单

• SQL 脚本执行成功
• 3个函数都已创建在 documents schema 中
• 已授权给 PostgREST 用户
• PostgREST 配置已更新
• PostgREST 已重启
• 前端应用已重新构建
• 文档列表页面正常显示
• 展开/折叠功能正常工作
• 问题数量差异正确显示

---

🎉 完成！

部署完成后，你应该能看到：

文档列表页面
  ├─ [▶️] 📄 合同审查.pdf
  │         合同审查  v1 (共3个历史版本)
  │         问题数量：3 🟢 ↓ -2
  │
  ├─ [▶️] 📄 许可证申请.docx
  │         许可证审查  v1 (共2个历史版本)
  │         问题数量：5 🔴 ↑ +1
  │
  └─ 📄 新文档.pdf
            合同审查
            问题数量：4

点击展开图标后：

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

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

功能完美运行！ 🚀