all in
This commit is contained in:
@@ -0,0 +1,340 @@
|
||||
# 文档版本管理 - 使用 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)
|
||||
```
|
||||
|
||||
**功能完美运行！** 🚀
|
||||
Reference in New Issue
Block a user