导入数据解析组件

导入数据解析组件（DataImportParse）用于按模板解析上传的导入文件，返回结构化的行数据供后续处理。

概述

导入数据解析组件读取用户上传的文件，依据指定的模板（视图）把文件内容解析为结构化数据。解析结果可交给数据导入落库，也可用于导入预览、数据校验或自定义处理。

除解析上传文件外，本组件还负责生成导入模板下载文件：当请求带模板下载标识时，它按模板生成带表头、必填标记与示例行的 Excel 供用户填写。

配置项

配置项	说明
操作对象	解析数据对应的实体对象，必填
解析模板	使用的视图模板，必填，决定列的解析与映射；可点击跳转编辑器
模板类型	文件类型，必填，目前支持 Excel
文件名	导入文件的名称
输出到最终结果	开启后该组件结果作为接口返回值

模板类型取值

值（`TemplateType`）	说明
`Excel`	Excel 文件（缺省，目前唯一取值）

执行流程

使用场景

导入前的数据预览
导入前的数据校验
自定义导入处理
生成导入模板供用户填写

下一步

数据导入 - 把解析结果写入实体
条件分支 - 对解析结果做条件判断
数据导入最佳实践 - 导入扩展与校验技巧

属性明细

以下内容面向技术实现与 AI 检索，说明导入数据解析组件的节点元数据。

所有节点 meta 的取值均以字符串形式存储，数值、布尔值也以字符串表达（如 "true"）。

节点元数据

导入数据解析组件由 FlowCmpType.DataImportParse 标识：

属性名	类型	含义	取值/存储值
`type`	string	组件类型	固定为 `"DataImportParse"`
`MetaObjectId`	string(GUID)	目标实体对象	缺省取当前接口所属对象
`TemplateMetaViewId`	string(GUID)	解析模板（视图）主键	视图（MetaView）主键
`TemplateType`	string	模板类型	`"Excel"`（缺省）
`FileName`	string	导入文件名	例：`"员工导入"`
`IsFinalResult`	string(bool)	是否输出到最终结果	`"true"` / `"false"`
`order`	string	同级排序	例：`"15"`

元数据存储示例

{
  "ID": "parse1",
  "type": "DataImportParse",
  "MetaObjectId": "3f9c0b2e-2d3a-4e6f-9c11-0f7a5b8d2e10",
  "TemplateMetaViewId": "7a2b1c3d-4e5f-6789-abcd-ef0123456789",
  "TemplateType": "Excel",
  "FileName": "员工导入",
  "IsFinalResult": "true",
  "order": "15"
}

服务端执行逻辑

执行时机与场景

导入数据解析组件继承自 InterfaceComponentManagerBase，运行在平台接口链路中，是导入链路的入口：把上传的文件转换为 List<ObjectData>，供后续的数据导入、脚本等组件消费。

它有两种运行分支：

模板下载：请求带 download_template 标识时，生成并返回导入模板文件；
解析：请求携带上传文件（context.Param 为 FileUploadPayload）时，按模板解析为结构化数据。

输入参数（meta 键）

meta 键	说明
`MetaObjectId`	目标对象，不可为空，且对象必须存在
`TemplateMetaViewId`	解析模板视图，不可为空
`TemplateType`	不可为空，且必须在支持列表内（`["EXCEL"]`，不区分大小写）
`FileName`	模板下载时的文件名前缀
`IsFinalResult`	是否把解析结果写入最终结果

执行期还读取：

请求 query 的 download_template：存在时走模板下载分支。
context.Param：解析分支下须为 FileUploadPayload（含 UploadStream、FileName）。
用户主标识（邮箱 / 工号 / 手机号）与主标识展示文本：用于模板列名后缀与员工信息模板的必填列补齐。

执行步骤

校验（_VerifyAsync）

MetaObjectId 不可为空，且对象必须存在。
TemplateMetaViewId 不可为空，模板视图必须存在，且其 MetaObjectId 必须与被操作对象一致。
TemplateType 不可为空且受支持。
把模板 ID 写入上下文 DicParam["ChameleonImportTemplateMetaViewId"]，便于下游的数据导入组件复用。

校验通过后进入下游校验链。

执行（_ExecuteAsync）

再次写入 DicParam["ChameleonImportTemplateMetaViewId"]。
分支判断：
- 请求含 download_template → 生成模板并返回文件流；
- context.Param 为 FileUploadPayload → 解析文件；
- 否则 → 报「未找到导入文件」。

模板下载（download_template）

模板下载（BuildTemplateAsync）流程：

取当前用户主标识（邮箱 / 工号 / 手机号）及主标识展示文本。
取模板视图的列（未隐藏的列表项）。
逐列预处理列名：
- 若配置了自定义导入列名（CustomImportColumnName），使用自定义名；
- 否则若字段类型为人员选择（UserSelect），在列名后拼接主标识展示文本后缀。
员工信息特殊处理：移除 userid 列；并确保主标识对应列（email / number / phone）存在且标记为导入必填，缺失时插入到首列。
生成 Excel（BuildExcelTemplate）：
- 第 0 行为隐藏行，写入各列字段编码；
- 第 1 行为表头，写入列名；导入必填列在列名首字符前加 * 并标红；
- 若任意列配置了导入示例值（ImportExampleValue），追加示例行并以淡黄色底纹展示，同时在末列附加「本行为示例数据，导入时请删除」的说明。
写入 context.DicParam["DownloadFileName"] = "{FileName}{yyyyMMddHHmmss}.xlsx"，并把 MemoryStream 赋给 context.Result。

模板下载分支不继续执行下游组件，直接返回当前上下文。

Excel 解析规则

解析（ExcelToDataList）按文件扩展名选择实现：.xlsx 用 XSSFWorkbook，.xls 用 HSSFWorkbook，其它扩展名报「不支持的文件格式」。

仅解析第一个工作表。
表头读取第 0 行（隐藏的字段编码行），缺失则报「导入文件结构不正确」。
数据从第 2 行开始逐行读取（模板中该位置为示例行，用户导入前需删除）。
单元格取值按类型转换：

单元格类型	取值
文本	`StringCellValue`
数字	日期格式取 `DateCellValue`，否则取 `NumericCellValue`
布尔	`BooleanCellValue`
公式	公式字符串
空 / 错误	`null`

每行的字段编码取自表头行对应列；编码为空的列跳过；整行无有效字段时不加入结果。
解析结果为空时报「导入文件内容为空」。

读取到的时间结果写入上下文 DicParam["ChameleonImportStartTime"]（按用户时区格式化为 yyyy-MM-dd HH:mm）。

输出与上下文

输出项	条件	说明
`context.CmpResult`	解析分支	解析结果 `List<ObjectData>`
`context.TransferResult.List`	解析分支且 `IsFinalResult = "true"`	解析结果列表
`context.Result`	解析分支且 `IsFinalResult = "true"`	`ResponseResult<List<ObjectData>>.Success(list).Total(list.Count)`
`context.Result`	模板下载分支	模板文件的 `MemoryStream`
`DicParam["ChameleonImportTemplateMetaViewId"]`	校验与执行	供数据导入组件回落到同一模板
`DicParam["ChameleonImportStartTime"]`	解析分支	导入开始时间

权限校验

组件本身不做操作权限或 MOU 校验：它只负责模板解析与生成；真正的数据写入权限由下游的数据导入组件在落库时校验。

性能、批次与限制

仅支持 Excel（EXCEL），且只解析首个工作表。
解析会把整个工作表读入内存并生成 List<ObjectData>，数据量由下游导入组件的行数上限（ImportCountlimit = 30000）约束。
组件不做分页与分批，解析结果一次性交给下游。
模板文件名为 {FileName}{yyyyMMddHHmmss}.xlsx，同一时间点多次下载不会互相覆盖。

异常与校验

场景	提示
未配置操作对象	操作对象未找到
未配置模板视图	未设置模板视图
模板视图不存在	按 ID 未找到模板视图
模板视图与对象不匹配	模板视图与对象不匹配
未配置模板类型	模板未找到
模板类型不支持	模板类型不支持
上传文件缺失	未找到导入文件
扩展名不是 `.xls` / `.xlsx`	不支持的文件格式
缺少表头行	导入文件结构不正确
解析结果为空	导入文件内容为空

概述​

配置项​

模板类型取值​

执行流程​

使用场景​

下一步​

属性明细​

节点元数据​

元数据存储示例​

服务端执行逻辑​

执行时机与场景​

输入参数（meta 键）​

执行步骤​

模板下载（download_template）​

Excel 解析规则​

输出与上下文​

权限校验​

性能、批次与限制​

异常与校验​

概述

配置项