all in

2025-12-05 00:09:32 +08:00
parent bb3d22eabf
commit 3d1dbb3f97
214 changed files with 113060 additions and 1232 deletions
@@ -0,0 +1,333 @@
+# 合同起草功能使用指南
+
+## 功能概述
+
+合同起草功能允许用户基于预定义的合同模板，通过填写占位符快速生成新的合同文档。
+
+---
+
+## 核心功能
+
+✅ **已实现功能**：
+
+1. **创建草稿**：从合同模板创建新的草稿
+2. **占位符填写**：通过表单填写合同信息
+3. **一键替换**：批量替换文档中的占位符
+4. **实时预览**：在线编辑和预览文档
+5. **保存草稿**：随时保存当前填写状态
+6. **完成起草**：标记草稿为已完成
+
+---
+
+## 使用流程
+
+### 1. 浏览合同模板
+
+访问合同模板列表页：`/contract-template`
+
+### 2. 选择模板并起草
+
+1. 点击模板进入详情页
+2. 点击"起草合同"按钮
+3. 输入合同标题（系统会生成默认标题）
+4. 点击确定创建草稿
+
+### 3. 填写合同信息
+
+进入起草页面后：
+
+- **左侧**：文档预览区（60%）- 实时显示文档内容
+- **右侧**：占位符表单（40%）- 分组显示需要填写的字段
+
+填写步骤：
+1. 按分组填写字段（甲方信息、乙方信息、合同条款等）
+2. 必填字段标注红色星号（*）
+3. 支持的字段类型：
+   - 文本（text）
+   - 数字（number）
+   - 日期（date）
+   - 电话（tel）
+   - 多行文本（textarea）
+
+### 4. 一键替换占位符
+
+点击"一键替换占位符"按钮：
+- 系统会将表单中的值批量替换到文档中
+- 显示替换进度和结果
+- 替换完成后自动保存
+
+### 5. 手动编辑（可选）
+
+替换后可以继续手动编辑文档：
+- 使用 Collabora Online 编辑器
+- 支持所有 Word 文档编辑功能
+- 缩放：Ctrl + 鼠标滚轮
+
+### 6. 保存草稿
+
+随时点击"保存草稿"按钮保存当前状态
+
+### 7. 完成起草
+
+确认无误后点击"完成起草"按钮：
+- 系统会检查必填字段是否都已填写
+- 完成后草稿状态变更为"已完成"
+- 自动跳转回模板列表页
+
+---
+
+## 占位符规范
+
+### 占位符格式
+
+在模板文档中使用双花括号标记占位符：
+
+```
+{{占位符名称}}
+```
+
+示例：
+```
+甲方（以下简称甲方）：{{甲方名称}}
+地址：{{甲方地址}}
+法定代表人：{{甲方法定代表人}}
+联系电话：{{甲方联系电话}}
+
+乙方（以下简称乙方）：{{乙方名称}}
+地址：{{乙方地址}}
+法定代表人：{{乙方法定代表人}}
+联系电话：{{乙方联系电话}}
+
+合同金额：{{合同金额}}元
+签订日期：{{签订日期}}
+```
+
+### 常用占位符
+
+**基本信息**：
+- `{{合同编号}}`
+- `{{合同标题}}`
+
+**甲方信息**：
+- `{{甲方名称}}`
+- `{{甲方地址}}`
+- `{{甲方法定代表人}}`
+- `{{甲方联系电话}}`
+
+**乙方信息**：
+- `{{乙方名称}}`
+- `{{乙方地址}}`
+- `{{乙方法定代表人}}`
+- `{{乙方联系电话}}`
+
+**合同条款**：
+- `{{合同金额}}`
+- `{{签订日期}}`
+- `{{履行期限}}`
+- `{{付款方式}}`
+
+---
+
+## 模板管理员指南
+
+### 配置模板占位符
+
+管理员需要为每个模板配置 `placeholder_schema` 字段，定义占位符表单结构。
+
+#### 配置示例
+
+```sql
+UPDATE contract_templates
+SET placeholder_schema = '{
+  "fields": [
+    {
+      "key": "甲方名称",
+      "label": "甲方名称",
+      "type": "text",
+      "required": true,
+      "group": "甲方信息",
+      "placeholder": "请输入甲方名称"
+    },
+    {
+      "key": "合同金额",
+      "label": "合同金额（元）",
+      "type": "number",
+      "required": true,
+      "group": "合同条款",
+      "placeholder": "请输入金额"
+    },
+    {
+      "key": "签订日期",
+      "label": "签订日期",
+      "type": "date",
+      "required": true,
+      "group": "合同条款"
+    }
+  ]
+}'::jsonb
+WHERE id = 1;
+```
+
+#### 字段配置说明
+
+- **key**: 占位符键名（必须与文档中的占位符一致，不含花括号）
+- **label**: 表单显示标签
+- **type**: 字段类型（text, number, date, tel, email, textarea）
+- **required**: 是否必填（true/false）
+- **group**: 分组名称（用于表单分组显示）
+- **placeholder**: 输入提示（可选）
+- **defaultValue**: 默认值（可选）
+
+### 制作模板文档
+
+1. 使用 Word 创建合同模板
+2. 在需要填写的位置插入占位符：`{{占位符名称}}`
+3. 保存为 .docx 格式
+4. 上传到系统
+5. 配置 `placeholder_schema`
+
+### 占位符命名规范
+
+- 使用中文名称，直观易懂
+- 避免特殊字符
+- 保持命名简洁
+- 同一信息使用统一命名
+
+---
+
+## 技术说明
+
+### 数据库表结构
+
+#### drafted_contracts（起草合同表）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | SERIAL | 主键ID |
+| template_id | INTEGER | 关联的模板ID |
+| file_path | TEXT | 起草后的文件路径 |
+| title | TEXT | 合同标题 |
+| placeholder_values | JSONB | 占位符填充值 |
+| status | TEXT | 状态（draft/completed/archived） |
+| created_by | INTEGER | 创建人ID |
+| created_at | TIMESTAMPTZ | 创建时间 |
+| updated_at | TIMESTAMPTZ | 更新时间 |
+
+#### contract_templates 扩展字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| placeholder_schema | JSONB | 占位符配置Schema |
+
+### API 接口
+
+#### 1. 创建草稿
+
+```
+POST /api/contracts/draft
+```
+
+**请求**：
+```json
+{
+  "templateId": 123,
+  "title": "采购合同-20250104"
+}
+```
+
+**响应**：
+```json
+{
+  "id": 456,
+  "filePath": "drafts/contract_123_1_1704355200000.docx",
+  "title": "采购合同-20250104",
+  "templateId": 123
+}
+```
+
+#### 2. 保存占位符值
+
+```
+PUT /api/contracts/draft/:id/placeholders
+```
+
+**请求**：
+```json
+{
+  "placeholders": {
+    "甲方名称": "广东省烟草专卖局",
+    "合同金额": "500000"
+  }
+}
+```
+
+**响应**：
+```json
+{
+  "success": true
+}
+```
+
+#### 3. 完成起草
+
+```
+POST /api/contracts/draft/:id/complete
+```
+
+**响应**：
+```json
+{
+  "success": true
+}
+```
+
+---
+
+## 常见问题
+
+### Q: 占位符没有被替换？
+
+**A**: 可能的原因：
+1. 占位符格式不正确（必须是 `{{名称}}`）
+2. placeholder_schema 中的 key 与文档中的占位符不一致
+3. 字段值为空（只替换有值的字段）
+
+### Q: 如何检查模板中有哪些占位符？
+
+**A**:
+1. 在 Word 中打开模板文档
+2. 使用查找功能（Ctrl+F）搜索 `{{`
+3. 记录所有占位符名称
+
+### Q: 可以自定义占位符分组吗？
+
+**A**: 可以。在 placeholder_schema 中通过 `group` 字段自定义分组名称。
+
+### Q: 替换后还能继续编辑吗？
+
+**A**: 可以。替换只是批量修改文档内容，之后仍可使用 Collabora 编辑器手动编辑。
+
+### Q: 草稿保存在哪里？
+
+**A**: 草稿文件保存在 MinIO 的 `drafts/` 目录下，数据库记录保存在 `drafted_contracts` 表中。
+
+---
+
+## 后续规划
+
+🔲 **待实现功能**：
+
+1. 草稿列表页面
+2. 草稿历史版本
+3. 草稿搜索和筛选
+4. 批量起草
+5. 模板变量智能推荐
+6. 导出为 PDF
+7. 审批流程集成
+8. 电子签名集成
+
+---
+
+## 支持与反馈
+
+如有问题或建议，请联系技术支持团队。