341 lines
7.8 KiB
Markdown
341 lines
7.8 KiB
Markdown
# 文档版本管理 - 使用 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 查询窗口执行：
|
||
|
||
```sql
|
||
-- 查看 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：测试函数（可选）
|
||
|
||
```sql
|
||
-- 测试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：
|
||
|
||
```conf
|
||
# /etc/postgrest/config (或其他配置文件路径)
|
||
|
||
# 添加 documents 到 db-schemas
|
||
db-schemas = "public, documents"
|
||
|
||
# 或者，如果之前没有配置，添加这一行
|
||
db-schemas = "public, documents"
|
||
```
|
||
|
||
修改配置后重启 PostgREST：
|
||
```bash
|
||
sudo systemctl restart postgrest
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 权限配置
|
||
|
||
### 查找你的 PostgREST 用户名
|
||
|
||
```sql
|
||
-- 方法1：查看所有数据库用户
|
||
SELECT usename FROM pg_user;
|
||
|
||
-- 方法2：查看当前连接用户
|
||
SELECT current_user;
|
||
```
|
||
|
||
**常见的 PostgREST 用户名**：
|
||
- `authenticator`
|
||
- `web_anon`
|
||
- `postgres`
|
||
- `api_user`
|
||
|
||
### 授权函数给用户
|
||
|
||
将下面的 `YOUR_POSTGREST_USER` 替换为你的实际用户名：
|
||
|
||
```sql
|
||
-- 授权 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：
|
||
|
||
```typescript
|
||
// 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
|
||
|
||
```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
|
||
|
||
```bash
|
||
# 测试获取文档列表
|
||
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. 重启应用：
|
||
```bash
|
||
npm run build
|
||
pm2 restart all
|
||
```
|
||
|
||
2. 访问文档列表页面：`http://your-domain/documents`
|
||
|
||
3. 检查功能：
|
||
- ✅ 文档列表正常显示
|
||
- ✅ 有历史版本的文档显示展开图标
|
||
- ✅ 点击展开图标能看到历史版本
|
||
- ✅ 问题数量差异正确显示（红色/绿色）
|
||
|
||
---
|
||
|
||
## ❌ 故障排查
|
||
|
||
### 问题1：函数未创建成功
|
||
|
||
**症状**：执行查询时提示 `function does not exist`
|
||
|
||
**解决方案**：
|
||
```sql
|
||
-- 检查 documents schema 是否存在
|
||
SELECT schema_name FROM information_schema.schemata WHERE schema_name = 'documents';
|
||
|
||
-- 如果不存在，手动创建
|
||
CREATE SCHEMA IF NOT EXISTS documents;
|
||
|
||
-- 重新执行 SQL 脚本
|
||
```
|
||
|
||
### 问题2：权限不足
|
||
|
||
**症状**：前端报错 `permission denied`
|
||
|
||
**解决方案**：
|
||
```sql
|
||
-- 检查当前用户权限
|
||
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. 前端代码是否已更新并重新构建
|
||
|
||
**解决方案**：
|
||
```bash
|
||
# 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 脚本已自动创建以下索引：
|
||
|
||
```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);
|
||
```
|
||
|
||
查看索引是否创建成功：
|
||
```sql
|
||
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)
|
||
```
|
||
|
||
**功能完美运行！** 🚀
|