644 lines
15 KiB
Markdown
644 lines
15 KiB
Markdown
# 合同起草功能 - 更新后的架构说明
|
||
|
||
## 业务逻辑调整
|
||
|
||
基于新的业务需求，草稿功能调整为**临时编辑模式**：
|
||
|
||
### ✅ 新的业务逻辑
|
||
|
||
1. **"保存草稿"** → **"导出文档"**
|
||
- 功能：下载 MinIO 上的当前文件
|
||
- 不保存占位符值到数据库
|
||
|
||
2. **"完成起草"**
|
||
- 功能：下载文件 + 删除草稿记录
|
||
- 操作完成后返回模板列表
|
||
|
||
3. **关闭页面/返回**
|
||
- 自动删除草稿记录
|
||
- 草稿是临时的，不保留
|
||
|
||
4. **草稿记录策略**
|
||
- 临时存在，仅用于跟踪编辑会话
|
||
- 离开页面即删除
|
||
- 不持久化占位符值
|
||
|
||
---
|
||
|
||
## 架构变更
|
||
|
||
### 删除的功能
|
||
|
||
```diff
|
||
- updatePlaceholders() # 不再保存占位符值
|
||
- completeDraft() # 不再更新状态为 completed
|
||
- getDraftsByUser() # 不需要查询草稿列表
|
||
```
|
||
|
||
### 新增的功能
|
||
|
||
```diff
|
||
+ deleteDraft() # 删除草稿记录
|
||
+ handleExportDocument() # 下载 MinIO 文件
|
||
+ beforeunload 监听 # 页面关闭时删除草稿
|
||
+ 组件卸载清理 # 路由跳转时删除草稿
|
||
```
|
||
|
||
---
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
app/
|
||
├── routes/
|
||
│ ├── contract-template.detail.$id.tsx # 模板详情页（创建草稿）
|
||
│ └── contract-draft.$draftId.tsx # 草稿编辑页（loader + action: delete）
|
||
│
|
||
├── api/
|
||
│ └── contracts/
|
||
│ └── draft-service.server.ts # 业务逻辑
|
||
│ ├── createDraftContract() # 创建草稿记录
|
||
│ ├── deleteDraft() # 删除草稿记录（新增）
|
||
│ ├── getDraftById() # 获取草稿详情
|
||
│ ├── copyMinioFile() # 文件复制（预留）
|
||
│ └── generateDraftFilePath() # 生成文件路径
|
||
│
|
||
└── components/
|
||
└── contracts/
|
||
└── PlaceholderForm.tsx # 占位符表单
|
||
├── "导出文档" 按钮（新）
|
||
└── "完成起草" 按钮
|
||
```
|
||
|
||
---
|
||
|
||
## 数据流
|
||
|
||
### 1. 创建草稿
|
||
|
||
```
|
||
用户点击"起草合同"
|
||
↓
|
||
contract-template.detail.$id.tsx
|
||
├─ action() 创建草稿记录
|
||
└─ redirect 到 /contract-draft/:draftId
|
||
```
|
||
|
||
### 2. 编辑草稿
|
||
|
||
```
|
||
草稿编辑页
|
||
├─ loader() 加载草稿和模板数据
|
||
├─ 左侧：Collabora 编辑器（实时编辑 MinIO 文件）
|
||
└─ 右侧：占位符表单（本地状态，不保存到数据库）
|
||
```
|
||
|
||
### 3. 导出文档
|
||
|
||
```
|
||
用户点击"导出文档"
|
||
↓
|
||
handleExportDocument()
|
||
├─ downloadFile(draft.file_path)
|
||
│ └─ 从 MinIO 下载文件
|
||
├─ 创建 Blob URL
|
||
└─ 触发浏览器下载
|
||
```
|
||
|
||
### 4. 完成起草
|
||
|
||
```
|
||
用户点击"完成起草"
|
||
↓
|
||
handleComplete()
|
||
├─ 1. 调用 handleExportDocument()
|
||
│ └─ 下载文件
|
||
├─ 2. 延迟 500ms
|
||
└─ 3. fetcher.submit({ _action: 'delete' })
|
||
↓
|
||
action() 删除草稿记录
|
||
↓
|
||
redirect 到 /contract-template
|
||
```
|
||
|
||
### 5. 关闭页面/返回
|
||
|
||
```
|
||
方式一：页面关闭（beforeunload）
|
||
↓
|
||
handleBeforeUnload()
|
||
└─ navigator.sendBeacon('/contract-draft/:id', { _action: 'delete' })
|
||
|
||
方式二：路由跳转（组件卸载）
|
||
↓
|
||
useEffect cleanup
|
||
└─ fetch('/contract-draft/:id', { method: 'POST', keepalive: true })
|
||
|
||
方式三：点击返回按钮
|
||
↓
|
||
handleBack()
|
||
├─ confirm('确定要返回吗？草稿将被删除。')
|
||
└─ fetcher.submit({ _action: 'delete' })
|
||
```
|
||
|
||
---
|
||
|
||
## 核心代码实现
|
||
|
||
### draft-service.server.ts
|
||
|
||
```typescript
|
||
import { postgrestGet, postgrestPost, postgrestPut, postgrestDelete } from '~/api/postgrest-client';
|
||
|
||
/**
|
||
* 创建草稿记录（临时记录，用于跟踪编辑会话）
|
||
*/
|
||
export async function createDraftContract(
|
||
request: CreateDraftRequest,
|
||
userId: number,
|
||
draftFilePath?: string,
|
||
jwt?: string
|
||
): Promise<DraftedContract> {
|
||
// 1. 查询模板信息
|
||
const templateResponse = await postgrestGet('contract_templates', {
|
||
select: 'id,file_path',
|
||
filter: { id: `eq.${request.templateId}` },
|
||
token: jwt
|
||
});
|
||
|
||
// 2. 确定文件路径（模板路径 or 复制路径）
|
||
const finalFilePath = draftFilePath || template.file_path;
|
||
|
||
// 3. 创建草稿记录（不保存 placeholder_values）
|
||
const insertResponse = await postgrestPost('drafted_contracts', {
|
||
body: {
|
||
template_id: request.templateId,
|
||
file_path: finalFilePath,
|
||
title: request.title,
|
||
placeholder_values: {}, // 始终为空
|
||
status: 'draft',
|
||
created_by: userId
|
||
},
|
||
select: '*',
|
||
token: jwt
|
||
});
|
||
|
||
return draft as DraftedContract;
|
||
}
|
||
|
||
/**
|
||
* 删除草稿记录
|
||
*/
|
||
export async function deleteDraft(
|
||
draftId: number,
|
||
userId: number,
|
||
jwt?: string
|
||
): Promise<void> {
|
||
await postgrestDelete('drafted_contracts', {
|
||
filter: {
|
||
id: `eq.${draftId}`,
|
||
created_by: `eq.${userId}`
|
||
},
|
||
token: jwt
|
||
});
|
||
|
||
console.log('[Draft Service] 草稿已删除:', draftId);
|
||
}
|
||
|
||
/**
|
||
* 获取草稿详情
|
||
*/
|
||
export async function getDraftById(
|
||
draftId: number,
|
||
userId: number,
|
||
jwt?: string
|
||
): Promise<DraftedContract | null> {
|
||
const response = await postgrestGet('drafted_contracts', {
|
||
select: '*',
|
||
filter: {
|
||
id: `eq.${draftId}`,
|
||
created_by: `eq.${userId}`
|
||
},
|
||
token: jwt
|
||
});
|
||
|
||
return draft as DraftedContract;
|
||
}
|
||
```
|
||
|
||
### contract-draft.$draftId.tsx
|
||
|
||
```typescript
|
||
/**
|
||
* Action 函数：只处理删除操作
|
||
*/
|
||
export async function action({ request, params }: ActionFunctionArgs) {
|
||
const draftId = parseInt(params.draftId || '0');
|
||
const { userInfo, frontendJWT } = await getUserSession(request);
|
||
const userId = parseInt(userInfo.sub);
|
||
const jwt = frontendJWT || undefined;
|
||
|
||
const formData = await request.formData();
|
||
const actionType = formData.get('_action') as string;
|
||
|
||
if (actionType === 'delete') {
|
||
await deleteDraft(draftId, userId, jwt);
|
||
return json({ success: true, message: '草稿已删除' });
|
||
}
|
||
|
||
return json({ error: '无效的操作类型' }, { status: 400 });
|
||
}
|
||
|
||
export default function ContractDraftPage() {
|
||
const { draft, template } = useLoaderData<typeof loader>();
|
||
const navigate = useNavigate();
|
||
const fetcher = useFetcher<ActionData>();
|
||
|
||
const [placeholderValues, setPlaceholderValues] = useState(
|
||
draft.placeholder_values || {}
|
||
);
|
||
|
||
// 监听删除成功
|
||
useEffect(() => {
|
||
if (fetcher.data?.success && fetcher.data.message === '草稿已删除') {
|
||
navigate('/contract-template');
|
||
}
|
||
}, [fetcher.data, navigate]);
|
||
|
||
// 监听页面关闭 - 自动删除草稿
|
||
useEffect(() => {
|
||
const handleBeforeUnload = () => {
|
||
const formData = new FormData();
|
||
formData.append('_action', 'delete');
|
||
navigator.sendBeacon(`/contract-draft/${draft.id}`, formData);
|
||
};
|
||
|
||
window.addEventListener('beforeunload', handleBeforeUnload);
|
||
return () => window.removeEventListener('beforeunload', handleBeforeUnload);
|
||
}, [draft.id]);
|
||
|
||
// 组件卸载时删除草稿
|
||
useEffect(() => {
|
||
return () => {
|
||
const formData = new FormData();
|
||
formData.append('_action', 'delete');
|
||
fetch(`/contract-draft/${draft.id}`, {
|
||
method: 'POST',
|
||
body: formData,
|
||
keepalive: true
|
||
});
|
||
};
|
||
}, [draft.id]);
|
||
|
||
// 导出文档（下载 MinIO 文件）
|
||
const handleExportDocument = async () => {
|
||
try {
|
||
const blob = await downloadFile(draft.file_path);
|
||
const blobUrl = URL.createObjectURL(blob);
|
||
const fileName = `${draft.title}.${draft.file_path.split('.').pop()}`;
|
||
|
||
const a = document.createElement('a');
|
||
a.href = blobUrl;
|
||
a.download = fileName;
|
||
document.body.appendChild(a);
|
||
a.click();
|
||
|
||
setTimeout(() => {
|
||
document.body.removeChild(a);
|
||
URL.revokeObjectURL(blobUrl);
|
||
}, 100);
|
||
|
||
toastService.success('文件下载成功');
|
||
} catch (error) {
|
||
toastService.error('下载失败');
|
||
}
|
||
};
|
||
|
||
// 完成起草（下载 + 删除）
|
||
const handleComplete = async () => {
|
||
await handleExportDocument();
|
||
|
||
setTimeout(() => {
|
||
const formData = new FormData();
|
||
formData.append('_action', 'delete');
|
||
fetcher.submit(formData, { method: 'post' });
|
||
}, 500);
|
||
};
|
||
|
||
// 返回（删除草稿）
|
||
const handleBack = () => {
|
||
if (confirm('确定要返回吗？草稿将被删除。')) {
|
||
const formData = new FormData();
|
||
formData.append('_action', 'delete');
|
||
fetcher.submit(formData, { method: 'post' });
|
||
}
|
||
};
|
||
|
||
return (
|
||
<div className="flex h-screen">
|
||
<div className="w-[60%]">
|
||
<FilePreview fileContent={{ path: draft.file_path }} />
|
||
</div>
|
||
|
||
<div className="w-[40%]">
|
||
<PlaceholderForm
|
||
schema={template.placeholder_schema}
|
||
values={placeholderValues}
|
||
onChange={setPlaceholderValues}
|
||
onBatchReplace={handleBatchReplace}
|
||
onExportDocument={handleExportDocument}
|
||
onComplete={handleComplete}
|
||
isReplacing={isReplacing}
|
||
isDeleting={fetcher.state !== 'idle'}
|
||
/>
|
||
</div>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
### PlaceholderForm.tsx
|
||
|
||
```typescript
|
||
interface PlaceholderFormProps {
|
||
schema: PlaceholderSchema | null;
|
||
values: Record<string, string>;
|
||
onChange: (values: Record<string, string>) => void;
|
||
onBatchReplace: () => void;
|
||
onExportDocument: () => void; // 导出文档
|
||
onComplete: () => void;
|
||
isReplacing: boolean;
|
||
isDeleting: boolean; // 是否正在删除
|
||
}
|
||
|
||
export function PlaceholderForm({
|
||
schema,
|
||
values,
|
||
onChange,
|
||
onBatchReplace,
|
||
onExportDocument,
|
||
onComplete,
|
||
isReplacing,
|
||
isDeleting
|
||
}: PlaceholderFormProps) {
|
||
// ...
|
||
|
||
return (
|
||
<div>
|
||
{/* 表单字段 */}
|
||
{/* ... */}
|
||
|
||
{/* 操作按钮 */}
|
||
<div className="space-y-3">
|
||
{/* 一键替换 */}
|
||
<button
|
||
onClick={onBatchReplace}
|
||
disabled={isReplacing || isDeleting}
|
||
>
|
||
一键替换占位符
|
||
</button>
|
||
|
||
{/* 导出文档 */}
|
||
<button
|
||
onClick={onExportDocument}
|
||
disabled={isReplacing || isDeleting}
|
||
>
|
||
<i className="ri-download-line mr-2"></i>
|
||
导出文档
|
||
</button>
|
||
|
||
{/* 完成起草 */}
|
||
<button
|
||
onClick={handleCompleteClick}
|
||
disabled={isReplacing || isDeleting}
|
||
>
|
||
{isDeleting ? '处理中...' : '完成起草'}
|
||
</button>
|
||
</div>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 关键技术点
|
||
|
||
### 1. 页面关闭时发送请求
|
||
|
||
使用 `navigator.sendBeacon` 确保请求发送：
|
||
|
||
```typescript
|
||
navigator.sendBeacon(
|
||
`/contract-draft/${draft.id}`,
|
||
formData
|
||
);
|
||
```
|
||
|
||
**优势**：
|
||
- 异步发送，不阻塞页面关闭
|
||
- 浏览器保证发送（即使页面已关闭）
|
||
- 不受页面卸载影响
|
||
|
||
### 2. 组件卸载时清理
|
||
|
||
使用 `fetch` 的 `keepalive` 选项：
|
||
|
||
```typescript
|
||
fetch(`/contract-draft/${draft.id}`, {
|
||
method: 'POST',
|
||
body: formData,
|
||
keepalive: true // 关键：确保请求在页面关闭后仍然发送
|
||
});
|
||
```
|
||
|
||
**优势**：
|
||
- 即使组件已卸载，请求仍会发送
|
||
- 适用于 SPA 路由跳转场景
|
||
|
||
### 3. 文件下载实现
|
||
|
||
使用 `axios-client` 的 `downloadFile` 方法：
|
||
|
||
```typescript
|
||
const blob = await downloadFile(draft.file_path);
|
||
const blobUrl = URL.createObjectURL(blob);
|
||
|
||
const a = document.createElement('a');
|
||
a.href = blobUrl;
|
||
a.download = fileName;
|
||
a.click();
|
||
|
||
URL.revokeObjectURL(blobUrl); // 清理内存
|
||
```
|
||
|
||
---
|
||
|
||
## 数据库设计
|
||
|
||
### drafted_contracts 表
|
||
|
||
```sql
|
||
CREATE TABLE drafted_contracts (
|
||
id SERIAL PRIMARY KEY,
|
||
template_id INTEGER NOT NULL, -- 关联的模板ID
|
||
file_path TEXT NOT NULL, -- 文件路径（模板路径或复制路径）
|
||
title TEXT NOT NULL, -- 合同标题
|
||
placeholder_values JSONB DEFAULT '{}', -- 占位符值（始终为空，不使用）
|
||
status TEXT DEFAULT 'draft', -- 状态（始终为 draft）
|
||
created_by INTEGER, -- 创建人ID
|
||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ DEFAULT NOW()
|
||
);
|
||
```
|
||
|
||
**字段说明**：
|
||
- `placeholder_values`：保留字段，始终为空对象 `{}`
|
||
- `status`：保留字段，始终为 `'draft'`
|
||
- 草稿记录仅用于跟踪当前编辑会话，离开即删除
|
||
|
||
---
|
||
|
||
## 用户体验流程
|
||
|
||
### 正常流程
|
||
|
||
```
|
||
1. 用户在模板详情页点击"起草合同"
|
||
↓
|
||
2. 输入合同标题
|
||
↓
|
||
3. 进入草稿编辑页
|
||
├─ 左侧：Collabora 实时编辑
|
||
└─ 右侧：填写占位符表单
|
||
↓
|
||
4. 点击"一键替换占位符"
|
||
└─ 在 Collabora 中替换所有 {{占位符}}
|
||
↓
|
||
5. 点击"导出文档"
|
||
└─ 下载当前编辑的文件
|
||
↓
|
||
6. 继续编辑或点击"完成起草"
|
||
├─ 下载文件
|
||
└─ 删除草稿记录，返回模板列表
|
||
```
|
||
|
||
### 中断流程
|
||
|
||
```
|
||
用户编辑过程中离开页面：
|
||
|
||
方式一：关闭浏览器标签页
|
||
↓ beforeunload 事件
|
||
└─ 自动删除草稿记录
|
||
|
||
方式二：点击浏览器返回按钮
|
||
↓ 组件卸载
|
||
└─ 自动删除草稿记录
|
||
|
||
方式三：点击页面"返回"按钮
|
||
↓ 弹窗确认
|
||
├─ 确定：删除草稿，返回模板列表
|
||
└─ 取消：留在编辑页
|
||
```
|
||
|
||
---
|
||
|
||
## 优势总结
|
||
|
||
### 1. 简化了数据管理
|
||
|
||
- ✅ 不保存占位符值到数据库
|
||
- ✅ 不需要更新草稿状态
|
||
- ✅ 不需要查询草稿列表
|
||
- ✅ 草稿记录仅用于会话跟踪
|
||
|
||
### 2. 更好的用户体验
|
||
|
||
- ✅ 随时导出当前编辑的文件
|
||
- ✅ 离开页面自动清理
|
||
- ✅ 无需手动删除草稿
|
||
- ✅ 操作流程更清晰
|
||
|
||
### 3. 系统维护简单
|
||
|
||
- ✅ 无需担心草稿堆积
|
||
- ✅ 无需定期清理过期草稿
|
||
- ✅ 数据库存储压力小
|
||
- ✅ 业务逻辑简单
|
||
|
||
---
|
||
|
||
## 待实施任务
|
||
|
||
### 1. 数据库迁移
|
||
|
||
```bash
|
||
psql -U postgres -d docreview
|
||
\i database/migrations/001_create_drafted_contracts.sql
|
||
```
|
||
|
||
### 2. 配置测试模板
|
||
|
||
在模板文档中添加占位符：
|
||
- `{{甲方名称}}`
|
||
- `{{乙方名称}}`
|
||
- `{{合同金额}}`
|
||
|
||
配置 `placeholder_schema`：
|
||
|
||
```sql
|
||
UPDATE contract_templates
|
||
SET placeholder_schema = '{
|
||
"fields": [
|
||
{
|
||
"key": "甲方名称",
|
||
"label": "甲方名称",
|
||
"type": "text",
|
||
"required": true,
|
||
"group": "甲方信息"
|
||
},
|
||
{
|
||
"key": "乙方名称",
|
||
"label": "乙方名称",
|
||
"type": "text",
|
||
"required": true,
|
||
"group": "乙方信息"
|
||
},
|
||
{
|
||
"key": "合同金额",
|
||
"label": "合同金额（元）",
|
||
"type": "number",
|
||
"required": true,
|
||
"group": "合同条款"
|
||
}
|
||
]
|
||
}'::jsonb
|
||
WHERE id = 1;
|
||
```
|
||
|
||
### 3. 功能测试
|
||
|
||
- [ ] 创建草稿
|
||
- [ ] 填写占位符表单
|
||
- [ ] 一键替换功能
|
||
- [ ] 导出文档功能
|
||
- [ ] 完成起草功能（下载 + 删除）
|
||
- [ ] 返回按钮（删除）
|
||
- [ ] 页面关闭自动删除
|
||
- [ ] 路由跳转自动删除
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
新的架构更加简洁高效：
|
||
|
||
1. ✅ **草稿是临时的** - 离开即删除
|
||
2. ✅ **不保存占位符** - 减少数据库操作
|
||
3. ✅ **自动清理** - 无需手动管理
|
||
4. ✅ **用户体验好** - 随时导出，自动清理
|
||
5. ✅ **维护成本低** - 逻辑简单，代码清晰
|
||
|
||
功能已完成，代码已通过类型检查！🎉
|