# 合同起草功能使用指南

## 功能概述

合同起草功能允许用户基于预定义的合同模板，通过填写占位符快速生成新的合同文档。

---

## 核心功能

✅ **已实现功能**：

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. 电子签名集成

---

## 支持与反馈

如有问题或建议，请联系技术支持团队。