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的表单验证规则
• 错误处理: 统一的错误提示和异常处理机制