.excelconfig 文件 Schema¶

位置：/{软件名}.application/excelconfig/{配置名}.excelconfig（单文件）　|　XML 根：excelconfig 资源元素（IMPMappingConfigVO）　|　与技能对齐：generate-excelconfig-file 机制背景见 [[design/table-schema/overview]]。

1. 用途与落盘¶

Excel 导入配置 = 模板（jsonTemplate JSON）+ 元数据，驱动「按模板导出 .xlsx / 导入校验入库」。目标可以是**表单**（exportTarget=form）或**库表**（database）。

storage/workspace/{软件名}.application/excelconfig/{配置名}.excelconfig

2. 属性表¶

属性	XML 形态	类型	说明
`id`	根属性	string	`__` + 短 UUID；视图引用键 `impmappingconfigid`
`name`	子元素	string	必填；文件名；应用内唯一；导出模板文件名常用
`parentId`	子元素	string	= 软件 id
`templateType`	子元素	string	必填 `EXCEL_JSON`（现行唯一生成类型）
`jsonTemplate`	CDATA	string	必填；TemplateJson 整段 JSON（见 §3）；空/非法 JSON 拒存
`templatePath`	子元素	string	可空；如 `/resources/exceltemplate/xxx.xlsx`
`description`	CDATA	string	可空

3. jsonTemplate 结构¶

根对象：

{
  "templateName": "配置显示名",
  "templateDesc": "",
  "sheets": [ /* JsonExcelSheet */ ],
  "config": { "showRequiredMark": true, "openValidateTip": true, "excelRowHeight": 15 }
}

Sheet（JsonExcelSheet）¶

字段	说明
`id` / `name`	Sheet id；Excel Sheet 名（≤31 字符，运行按名匹配）
`exportTarget`	`form` / `database`
`formId`	form 模式必填（表单 id，非 name）
`dataSourceId` + `targetTableId`	database 模式必填
`sheetType`	`master` / `detail`；须有 master
`fieldList`	非空；列序 = Excel 列序
`labelRows`	多级表头（可空）；数据起始行 = 标签最大 rowLevel（无则 1）
`dataRow`	`{ height, isExample, style? }`

校验（ImportPlanBuilder）：无 master、Sheet name 空、fieldList 空、字段缺 key、form 缺 formId、database 缺 dataSourceId/targetTableId → 抛错。

字段（JsonFieldItem）¶

id、key（必填，对应表单字段/列名）、name（表头显示）、类型/必填/校验等属性；完整字段表见技能文档 §3。

4. XML 骨架¶

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<excelconfig id="__excelLeaveImport01">
  <name>请假导入</name>
  <parentId>软件id</parentId>
  <templateType>EXCEL_JSON</templateType>
  <templatePath></templatePath>
  <jsonTemplate><![CDATA[{
    "templateName": "请假导入",
    "sheets": [{
      "id": "__sheetMain000000001",
      "name": "Sheet1",
      "exportTarget": "form",
      "formId": "表单id",
      "sheetType": "master",
      "fieldList": [ /* JsonFieldItem… */ ],
      "labelRows": [],
      "dataRow": { "height": 15 }
    }],
    "config": { "showRequiredMark": true, "openValidateTip": true, "excelRowHeight": 15 }
  }]]></jsonTemplate>
</excelconfig>

设计态 API：/api/designtime/applications/{appId}/excelconfigs（CRUD + export-excel 按已存 JSON 导出 .xlsx）。

5. 相关¶

资源	文档
导入目标表单	[[form-file]]
库表模式数据源	[[datasource-file]]
菜单挂接（linkType=03）	[[menu-file]]
生成操作指南	`agent-skills-usage/skills/generate-excelconfig-file/SKILL.md`（含字段全表、库表导入样例）