cz-hjjc-budget/docs/事前流程模版设置页面功能说明.md

# 事前流程模版设置页面功能说明

## 页面信息

- **页面路径**: `http://localhost:3000/#/settings/pre-approval-template-settings`
- **路由路径**: `/settings/pre-approval-template-settings`
- **组件位置**: `czemc-budget-execution-frontend/src/views/settings/PreApprovalTemplateSettings.vue`
- **后端控制器**: `backend/Modules/Budget/app/Http/Controllers/Api/PreApprovalTemplateGroupController.php`
- **数据表**: `budget_pre_approval_template_groups`、`budget_pre_approval_template_group_elements`

## 页面概述

事前流程模版设置页面用于管理分组和元素，这些分组和元素在设置事前流程模版时会作为默认数据被拉取。分组是固定的，用于组织和管理各种类型的模板元素。

## 核心功能

### 1. 分组管理

#### 1.1 分组列表展示
- **位置**: 页面主表格区域（第19-62行）
- **功能**: 展示所有事前流程模版分组
- **显示字段**:
  - 序号（自动编号）
  - 分组名称
  - 分组编码（唯一标识）
  - 描述
  - 已使用元素（以标签形式展示元素名称列表）
  - 排序（数字，用于控制显示顺序）
  - 状态（启用/禁用，通过开关切换）
  - 操作按钮（管理元素、编辑、删除）

#### 1.2 添加分组
- **触发方式**: 点击"添加分组"按钮（第12-15行）
- **对话框**: 添加/编辑分组对话框（第66-117行）
- **表单字段**:
  - **分组名称**（必填）: 最大长度200字符
  - **分组编码**（必填）: 最大长度100字符，必须唯一
    - 新建时自动生成（基于时间戳和随机数）
    - 可手动输入或点击刷新按钮重新生成
    - 编辑时不可修改
  - **描述**（可选）: 文本域，最多3行
  - **排序**（可选）: 数字输入，最小值0，默认0
  - **状态**（可选）: 开关，默认启用（1）
- **验证规则**:
  - 分组名称：必填
  - 分组编码：必填，且必须唯一
- **API接口**: `POST /budget/pre-approval-template-groups`

#### 1.3 编辑分组
- **触发方式**: 点击分组列表中的"编辑"按钮（第55行）
- **功能**: 修改分组的基本信息
- **限制**: 分组编码不可修改
- **表单字段**: 与添加分组相同（编码字段禁用）
- **API接口**: `PUT /budget/pre-approval-template-groups/{id}`

#### 1.4 删除分组
- **触发方式**: 点击分组列表中的"删除"按钮（第56行）
- **确认机制**: 删除前弹出确认对话框
- **API接口**: `DELETE /budget/pre-approval-template-groups/{id}`

#### 1.5 状态切换
- **触发方式**: 直接点击分组列表中的状态开关（第42-47行）
- **功能**: 快速启用或禁用分组
- **值映射**: 
  - 启用 = 1
  - 禁用 = 0
- **API接口**: `PUT /budget/pre-approval-template-groups/{id}`

### 2. 分组元素管理

#### 2.1 管理元素入口
- **触发方式**: 点击分组列表中的"管理元素"按钮（第52-54行）
- **对话框**: 管理分组元素对话框（第120-181行）
- **功能**: 打开元素管理界面，显示当前分组的所有元素

#### 2.2 元素列表展示
- **位置**: 管理元素对话框中的表格（第134-174行）
- **显示字段**:
  - 序号（自动编号）
  - 元素名称
  - 元素类型（以标签形式展示）
  - 排序（数字）
  - 操作按钮（上移、下移、删除）

#### 2.3 元素类型
支持以下元素类型（第333-351行）:
- **常规表单字段**: 
  - 文本（text）
  - 数字（number）
  - 日期（date）
  - 文本域（textarea）
  - 复选框（checkbox）
  - 单选框（radio）
  - 下拉选择（select）
  - 文件上传（file）
- **事前流程**（oa_custom_model）: 来自OA系统的自定义流程模型
- **勾选清单**（checklist）: 用于创建勾选清单类型的元素
- **会议纪要**（meeting_minutes）: 会议纪要相关元素
- **明细表格**（detail_table）: 明细表格类型元素

#### 2.4 添加元素到分组
- **触发方式**: 在管理元素对话框中点击"添加元素"按钮（第128-131行）
- **对话框**: 添加元素对话框（第184-267行）
- **元素选择**:
  - 下拉选择框，支持搜索过滤
  - 按元素类型分组显示：
    - 常规表单字段
    - 事前流程
    - 历史类型（将清理）- 已移除，不再显示
    - 勾选清单
    - 会议纪要
    - 明细表格
  - 只显示未被使用的元素（跨所有分组检查）
- **表单字段**:
  - **选择元素**（必填）: 从可用元素列表中选择
  - **排序**（可选）: 数字输入，最小值0，默认0
- **验证规则**: 元素ID必填
- **API接口**: `POST /budget/pre-approval-template-groups/{groupId}/elements`
- **限制**: 
  - 同一元素不能在同一分组中重复添加
  - 同一元素不能跨分组使用（已被其他分组使用的元素不可选）

#### 2.5 删除元素
- **触发方式**: 点击元素列表中的"删除"按钮（第164-171行）
- **确认机制**: 删除前弹出确认对话框
- **功能**: 从分组中移除元素
- **API接口**: `DELETE /budget/pre-approval-template-groups/{groupId}/elements/{elementId}`
- **后续操作**: 
  - 删除成功后，元素重新变为可用（可被其他分组使用）
  - 自动刷新元素列表和分组列表

#### 2.6 元素排序
- **上移**: 点击上移按钮（第145-153行）
  - 将元素向上移动一位
  - 第一个元素不可上移
- **下移**: 点击下移按钮（第154-163行）
  - 将元素向下移动一位
  - 最后一个元素不可下移
- **排序更新**: 使用索引作为排序值，批量更新排序
- **API接口**: `POST /budget/pre-approval-template-groups/{groupId}/elements/sort`

### 3. 数据加载逻辑

#### 3.1 分组列表加载
- **函数**: `loadGroups()`（第354-382行）
- **API接口**: `GET /budget/pre-approval-template-groups?all=true`
- **数据处理**:
  - 支持分页和全量加载（使用`all=true`参数）
  - 自动关联加载分组下的元素
  - 将boolean类型的`is_active`转换为数字1/0，以匹配Element Plus的开关组件
  - 为每个分组添加`element_names`数组（元素名称列表）

#### 3.2 可用元素列表加载
- **函数**: `loadAvailableElements()`（第385-472行）
- **功能**: 加载所有可用的元素（未被任何分组使用的元素）
- **加载流程**:
  1. 获取所有已使用的元素ID列表（跨所有分组）
     - API: `GET /budget/pre-approval-template-groups/used-element-ids`
  2. 分别加载各类元素：
     - 常规表单字段: `GET /budget/template-elements?category=form_field&is_active=1&all=true`
     - 事前流程: `GET /budget/template-elements?is_active=1&all=true`（然后筛选）
     - 勾选清单: `GET /budget/template-elements?category=checklist&is_active=1&all=true`
     - 会议纪要: `GET /budget/template-elements?category=meeting_minutes&is_active=1&all=true`
     - 明细表格: `GET /budget/template-elements?category=detail_table&is_active=1&all=true`
  3. 过滤掉已使用的元素
- **事前流程元素筛选逻辑**（第415-419行）:
  - `category === 'pre_approval_flow`
  - 或 `category`为空但有`model_id`
  - 或 `category === 'oa_model'`（兼容旧值）

#### 3.3 分组元素加载
- **函数**: `loadGroupElements()`（第475-485行）
- **API接口**: `GET /budget/pre-approval-template-groups/{groupId}/elements`
- **功能**: 加载指定分组下的所有元素
- **排序**: 按`sort_order`和`id`排序

### 4. 页面初始化

- **生命周期**: `onMounted()`（第768-771行）
- **初始化操作**:
  1. 加载分组列表
  2. 加载可用元素列表（预加载，提升用户体验）

## 后端API接口

### 分组管理接口

| 方法 | 路径 | 功能 | 控制器方法 |
|------|------|------|-----------|
| GET | `/budget/pre-approval-template-groups` | 获取分组列表 | `index()` |
| GET | `/budget/pre-approval-template-groups/{id}` | 获取分组详情 | `show()` |
| POST | `/budget/pre-approval-template-groups` | 创建分组 | `store()` |
| PUT | `/budget/pre-approval-template-groups/{id}` | 更新分组 | `update()` |
| DELETE | `/budget/pre-approval-template-groups/{id}` | 删除分组 | `destroy()` |

### 分组元素管理接口

| 方法 | 路径 | 功能 | 控制器方法 |
|------|------|------|-----------|
| GET | `/budget/pre-approval-template-groups/{groupId}/elements` | 获取分组元素列表 | `getElements()` |
| POST | `/budget/pre-approval-template-groups/{groupId}/elements` | 添加元素到分组 | `addElement()` |
| DELETE | `/budget/pre-approval-template-groups/{groupId}/elements/{elementId}` | 从分组移除元素 | `removeElement()` |
| PUT | `/budget/pre-approval-template-groups/{groupId}/elements/{elementId}` | 更新分组元素 | `updateElement()` |
| POST | `/budget/pre-approval-template-groups/{groupId}/elements/sort` | 更新元素排序 | `updateElementSort()` |
| GET | `/budget/pre-approval-template-groups/used-element-ids` | 获取所有已使用的元素ID | `getUsedElementIds()` |

## 数据模型

### 分组模型（PreApprovalTemplateGroup）

- `id`: 主键
- `name`: 分组名称（必填，最大200字符）
- `code`: 分组编码（必填，最大100字符，唯一）
- `description`: 描述（可选）
- `sort_order`: 排序值（整数，默认0）
- `is_active`: 是否启用（布尔值，默认true）
- `created_by`: 创建人ID
- `updated_by`: 更新人ID
- `created_at`: 创建时间
- `updated_at`: 更新时间

### 分组元素关联表（budget_pre_approval_template_group_elements）

- `id`: 主键
- `group_id`: 分组ID（外键）
- `element_id`: 元素ID（外键，关联`budget_template_elements`表）
- `sort_order`: 排序值（整数）
- `is_active`: 是否启用（布尔值）

## 业务规则

1. **分组编码唯一性**: 每个分组的编码必须在系统中唯一
2. **元素唯一性**: 同一个元素不能跨分组使用（一个元素只能属于一个分组）
3. **分组固定性**: 分组是固定的，用于组织模板元素
4. **元素类型多样性**: 支持多种类型的元素（表单字段、事前流程、勾选清单、会议纪要、明细表格等）
5. **排序控制**: 分组和元素都支持排序，用于控制显示顺序
6. **状态管理**: 分组支持启用/禁用状态，用于控制是否在模板设置时可用

## 与其他页面的关系

### 与计划支出模板设置页面的关系

- **页面路径**: `/settings/planned-expenditure-template-settings`
- **关系**: 计划支出模板设置页面在设置事前流程区域时，会从本页面加载启用的分组作为默认模板
- **数据流程**:
  1. 计划支出模板设置页面加载时，如果没有保存的模板配置
  2. 会调用本页面的分组数据（只加载`is_active=1`的分组）
  3. 按`sort_order`排序后，将分组及其元素加载到画布中
  4. 作为默认的事前流程模板配置

## 注意事项

1. **编码生成**: 新建分组时，编码会自动生成，格式为`GROUP_{时间戳}_{随机数}`，也可以手动输入
2. **编码不可修改**: 编辑分组时，编码字段被禁用，不可修改
3. **元素过滤**: 添加元素时，只显示未被使用的元素，已使用的元素不会出现在选择列表中
4. **跨分组检查**: 系统会检查元素是否已被其他分组使用，确保元素唯一性
5. **状态转换**: 分组状态切换时，会立即调用API更新，如果失败会自动恢复原状态
6. **数据刷新**: 添加或删除元素后，会自动刷新分组列表和可用元素列表，确保数据一致性

## 技术实现

- **前端框架**: Vue 3（Composition API）
- **UI组件库**: Element Plus
- **状态管理**: 使用`ref`和`reactive`进行响应式数据管理
- **API调用**: 通过`@/utils/api`中的`preApprovalTemplateGroupAPI`和`templateElementAPI`进行接口调用
- **表单验证**: 使用Element Plus的表单验证规则
- **错误处理**: 统一的错误提示和异常处理机制