cz-hjjc-budget/docs/payment-template-element-types.md

# 付款模板元素类型整理文档

## 概述

本文档整理了付款模板元素设置页面（`/settings/payment-template-element-settings`）中支持的所有元素类型及其使用规则。

## 元素类型（type）

付款模板元素支持以下4种类型：

### 1. 审批流程（approval_flow）

- **类型值**: `approval_flow`
- **显示标签**: 审批流程
- **标签颜色**: `warning`（橙色）
- **用途**: 关联OA模块的自定义模型，用于审批流程管理
- **必填字段**:
  - `model_id`: 必须关联一个OA模型ID
- **禁用字段**:
  - `field_type`: 不需要字段类型
  - `options`: 不需要选项配置
- **使用场景**: 当需要关联事前流程的审批记录时使用

### 2. 会议纪要（meeting_minutes）

- **类型值**: `meeting_minutes`
- **显示标签**: 会议纪要
- **标签颜色**: `success`（绿色）
- **用途**: 用于关联会议纪要记录
- **必填字段**: 无
- **禁用字段**:
  - `model_id`: 不能关联模型
  - `field_type`: 不需要字段类型
  - `options`: 不需要选项配置
- **使用场景**: 当需要关联会议纪要时使用

### 3. 普通表单元素（form_element）

- **类型值**: `form_element`
- **显示标签**: 普通表单元素
- **标签颜色**: `info`（蓝色）
- **用途**: 用于创建常规的表单输入字段
- **必填字段**:
  - `field_type`: 必须选择字段类型（见下方字段类型说明）
- **禁用字段**:
  - `model_id`: 不能关联模型
  - `options`: 不需要选项配置
- **使用场景**: 当需要创建文本输入、附件上传等常规表单字段时使用

### 4. 勾选清单（checklist）

- **类型值**: `checklist`
- **显示标签**: 勾选清单
- **标签颜色**: `primary`（主题色）
- **用途**: 用于创建可多选的勾选清单
- **必填字段**:
  - `options`: 必须至少配置一个选项（JSON数组格式：`[{label, value}]`）
- **禁用字段**:
  - `model_id`: 不能关联模型
  - `field_type`: 不需要字段类型
- **使用场景**: 当需要创建可多选的勾选清单时使用

## 字段类型（field_type）

**注意**: 字段类型仅当元素类型为 `form_element`（普通表单元素）时使用。

### 1. 单行文本（single_line_text）

- **类型值**: `single_line_text`
- **显示标签**: 单行文本
- **标签颜色**: `primary`（主题色）
- **用途**: 单行文本输入框

### 2. 多行文本（multi_line_text）

- **类型值**: `multi_line_text`
- **显示标签**: 多行文本
- **标签颜色**: `success`（绿色）
- **用途**: 多行文本输入框（文本域）

### 3. 附件（attachment）

- **类型值**: `attachment`
- **显示标签**: 附件
- **标签颜色**: `warning`（橙色）
- **用途**: 文件上传字段

## 元素类型与字段的对应关系

| 元素类型 | 是否需要 model_id | 是否需要 field_type | 是否需要 options |
|---------|------------------|-------------------|-----------------|
| approval_flow | ✅ 必填 | ❌ 不需要 | ❌ 不需要 |
| meeting_minutes | ❌ 不能有 | ❌ 不需要 | ❌ 不需要 |
| form_element | ❌ 不能有 | ✅ 必填 | ❌ 不需要 |
| checklist | ❌ 不能有 | ❌ 不需要 | ✅ 必填（至少1个） |

## 代码位置

### 前端代码

- **页面组件**: `czemc-budget-execution-frontend/src/views/settings/PaymentTemplateElementSettings.vue`
- **类型标签映射函数**: `getElementTypeLabel()` (第272-280行)
- **类型标签颜色映射函数**: `getTypeTagType()` (第283-291行)
- **字段类型标签映射函数**: `getFieldTypeLabel()` (第294-301行)
- **字段类型标签颜色映射函数**: `getFieldTypeTagType()` (第304-311行)

### 后端代码

- **控制器**: `backend/Modules/Budget/app/Http/Controllers/Api/PaymentTemplateElementController.php`
- **模型**: `backend/Modules/Budget/app/Models/PaymentTemplateElement.php`
- **数据库表**: `budget_payment_template_elements`
- **迁移文件**: 
  - `backend/Modules/Budget/database/migrations/2025_12_15_145312_create_payment_template_elements_table.php`
  - `backend/Modules/Budget/database/migrations/2025_12_17_144831_add_field_type_to_payment_template_elements_table.php`
  - `backend/Modules/Budget/database/migrations/2025_12_22_000001_add_options_to_payment_template_elements_table.php`

## 验证规则

### 前端验证

前端在 `formRules` 中定义了以下验证规则：

1. **元素类型验证**:
   - `type`: 必填，必须选择元素类型

2. **勾选清单验证**:
   - `options`: 当类型为 `checklist` 时，必须至少添加一个选项，且选项值不能重复

3. **普通表单元素验证**:
   - `field_type`: 当类型为 `form_element` 时，必须选择字段类型

4. **审批流程验证**:
   - `model_id`: 当类型为 `approval_flow` 时，必须选择关联模型

### 后端验证

后端在 `PaymentTemplateElementController` 中定义了以下验证规则：

1. **类型验证**:
   ```php
   'type' => 'required|in:approval_flow,meeting_minutes,form_element,checklist'
   ```

2. **字段类型验证**:
   ```php
   'field_type' => 'nullable|in:single_line_text,multi_line_text,attachment'
   ```

3. **业务规则验证**:
   - 审批流程必须提供 `model_id`
   - 会议纪要不能有 `model_id`
   - 普通表单元素必须提供 `field_type`，且不能有 `model_id`
   - 勾选清单必须提供 `options`（至少1个），且不能有 `model_id` 和 `field_type`

## 使用示例

### 创建审批流程元素

```javascript
{
  name: "合同审批流程",
  type: "approval_flow",
  model_id: 123,  // OA模型ID
  description: "关联合同审批流程",
  sort_order: 1,
  is_active: true
}
```

### 创建会议纪要元素

```javascript
{
  name: "会议纪要",
  type: "meeting_minutes",
  description: "关联会议纪要",
  sort_order: 2,
  is_active: true
}
```

### 创建普通表单元素

```javascript
{
  name: "备注说明",
  type: "form_element",
  field_type: "multi_line_text",  // 多行文本
  description: "备注说明字段",
  sort_order: 3,
  is_active: true
}
```

### 创建勾选清单元素

```javascript
{
  name: "验收清单",
  type: "checklist",
  options: [
    { label: "材料齐全", value: "材料齐全" },
    { label: "质量合格", value: "质量合格" },
    { label: "手续完备", value: "手续完备" }
  ],
  description: "验收检查清单",
  sort_order: 4,
  is_active: true
}
```

## 注意事项

1. **类型切换**: 当切换元素类型时，系统会自动清除不相关的字段（如 `model_id`、`field_type`、`options`）

2. **选项格式**: 勾选清单的 `options` 必须是 JSON 数组格式，每个选项包含 `label` 和 `value` 字段，且 `value` 不能重复

3. **字段类型限制**: 字段类型（`field_type`）仅在元素类型为 `form_element` 时有效

4. **模型关联**: 审批流程类型必须关联一个有效的OA模型（`is_sub = 0` 的非子表单模型）

5. **数据存储**: 
   - `options` 字段以 JSON 格式存储在数据库中
   - `is_active` 字段在数据库中为布尔类型，前端使用 1/0 进行转换

## 更新记录

- **2025-01-XX**: 初始文档创建，整理所有元素类型定义和使用规则
- **2025-01-XX**: 补充 `checklist` 类型到前端表单选择器和筛选器中