cz-hjjc-budget/docs/canvas-groups-source.md

# 计划支出模板设置 - 画布中分组的来源说明

## 页面路径
`http://localhost:3000/#/settings/planned-expenditure-template-settings?categoryId=2`

## 分组来源

画布中显示的分组**来自"事前流程模版设置"页面**（`/settings/pre-approval-template-settings`）。

## 数据流程

### 1. 分组创建和管理
- **位置**: `http://localhost:3000/#/settings/pre-approval-template-settings`
- **页面组件**: `czemc-budget-execution-frontend/src/views/settings/PreApprovalTemplateSettings.vue`
- **功能**: 
  - 创建分组（分组名称、分组编码、描述、排序、状态）
  - 管理分组中的元素（添加、删除、排序）
  - 分组数据存储在 `budget_pre_approval_template_groups` 表

### 2. 分组加载到画布
- **位置**: `czemc-budget-execution-frontend/src/views/settings/CanvasSettings.vue`
- **函数**: `loadDefaultTemplateFromGroups()` (第826-897行)
- **调用时机**:
  1. 当分类没有保存的模板配置时
  2. 当加载模板配置失败时
  3. 作为默认配置来源

### 3. 加载流程详解

```javascript
// 步骤1: 获取所有启用的分组
const groupsResponse = await preApprovalTemplateGroupAPI.getList({ 
  is_active: 1,  // 只获取启用的分组
  all: true      // 获取所有数据，不分页
})

// 步骤2: 按排序顺序处理分组
const sortedGroups = groups.sort((a, b) => (a.sort_order || 0) - (b.sort_order || 0))

// 步骤3: 遍历每个分组，获取分组中的元素
for (const group of sortedGroups) {
  // 获取分组元素
  const elementsResponse = await preApprovalTemplateGroupAPI.getElements(group.id)
  
  // 步骤4: 将元素转换为字段配置
  const fields = elements.map(element => {
    return {
      key: `element_${element.element_id}`,
      label: element.element_name,
      element_type: element.element_type,
      required: false,
      visible: true,
      element_id: element.element_id
    }
  })
  
  // 步骤5: 使用分组编码或ID作为配置的key，分组名称作为title
  const sectionKey = group.code || `group_${group.id}`
  config[sectionKey] = {
    title: group.name,      // 分组名称作为画布区域的标题
    fields: fields,         // 分组中的元素作为字段
    group_id: group.id,      // 保存分组ID
    group_code: group.code  // 保存分组编码
  }
}
```

## 数据结构

### 分组数据结构（来自事前流程模版设置）
```javascript
{
  id: 1,
  name: "上会记录",           // 分组名称
  code: "GROUP_MJ8EE28T_JV", // 分组编码
  description: "描述信息",
  sort_order: 0,             // 排序顺序
  is_active: 1               // 是否启用
}
```

### 画布配置结构（转换后）
```javascript
{
  "GROUP_MJ8EE28T_JV": {     // 使用分组编码作为key
    "title": "上会记录",      // 分组名称
    "fields": [               // 分组中的元素
      {
        "key": "element_1",
        "label": "项目名称",
        "element_type": "text",
        "required": false,
        "visible": true,
        "element_id": 1
      },
      // ... 更多元素
    ],
    "group_id": 1,            // 分组ID
    "group_code": "GROUP_MJ8EE28T_JV"  // 分组编码
  }
  // ... 更多分组
}
```

## 关键API接口

### 1. 获取分组列表
- **API**: `GET /budget/pre-approval-template-groups`
- **参数**: `{ is_active: 1, all: true }`
- **返回**: 所有启用的分组列表

### 2. 获取分组元素
- **API**: `GET /budget/pre-approval-template-groups/{groupId}/elements`
- **返回**: 分组中的元素列表（包含元素名称、类型、排序等）

## 数据库表关系

```
budget_pre_approval_template_groups (分组表)
  ├── id
  ├── name (分组名称)
  ├── code (分组编码)
  ├── sort_order (排序)
  └── is_active (是否启用)

budget_pre_approval_template_group_elements (分组元素关联表)
  ├── group_id (关联分组)
  ├── element_id (关联元素)
  ├── sort_order (元素在分组中的排序)
  └── is_active (元素是否启用)

budget_template_elements (元素表)
  ├── id
  ├── name (元素名称)
  ├── type (元素类型)
  ├── category (元素分类)
  └── ...
```

## 注意事项

1. **分组必须启用**: 只有 `is_active = 1` 的分组才会被加载到画布中

2. **分组排序**: 分组按照 `sort_order` 字段排序，数值越小越靠前

3. **分组编码**: 
   - 优先使用分组的 `code` 字段作为画布配置的 key
   - 如果 `code` 为空，则使用 `group_{id}` 作为 key

4. **元素来源**: 分组中的元素来自"非直接支付模版元素设置"页面（`/settings/template-element-settings`）

5. **默认配置**: 当分类没有保存的模板配置时，会自动从"事前流程模版设置"获取分组作为默认配置

6. **配置保存**: 画布中的配置可以保存到 `budget_planned_expenditure_templates` 表，保存后下次加载会优先使用保存的配置，而不是从分组获取

## 相关文件

- **画布设置页面**: `czemc-budget-execution-frontend/src/views/settings/CanvasSettings.vue`
- **事前流程模版设置页面**: `czemc-budget-execution-frontend/src/views/settings/PreApprovalTemplateSettings.vue`
- **API定义**: `czemc-budget-execution-frontend/src/utils/api.js` (preApprovalTemplateGroupAPI)
- **后端控制器**: `backend/Modules/Budget/app/Http/Controllers/Api/PreApprovalTemplateGroupController.php`
- **后端模型**: `backend/Modules/Budget/app/Models/PreApprovalTemplateGroup.php`