数据导入组件
数据导入组件（DbImport）用于按导入模板把文件数据写入实体对象。
概述
数据导入组件把已解析的导入数据按指定的视图模板写入目标实体。模板定义了文件列与实体字段的映射关系，组件据此完成字段对应、校验与入库。
组件通常与导入数据解析配合使用：先解析文件，再由本组件落库。若配置了模板，还可在导入前预览与校验。
配置项
| 配置项 | 说明 |
|---|---|
| 操作对象 | 要导入的实体对象，必填 |
| 导入模板 | 使用的视图模板，决定列与字段的映射；可点击跳转编辑器 |
| 跳过操作权限校验 | 开启后不校验当前用户对目标对象的操作权限 |
| 输出到最终结果 | 开启后该组件结果作为接口返回值 |
执行流程
字段映射
字段映射由「导入模板」对应的视图定义，文件中每一列依据模板映射到实体的对应字段：
| 文件列 | 实体字段 |
|---|---|
| 姓名 | Name |
| 编码 | Code |
| 状态 | Status |
模板中可对每个列设置：是否导入必填、自定义导入列名、导入示例值，以及该列所属字段是否参与重复判断。
使用场景
- 批量数据录入
- 数据迁移
- 初始化基础数据
下一步
属性明细
以下内容面向技术实现与 AI 检索，说明数据导入组件的节点元数据。
所有节点
meta的取值均以字符串形式存储，数值、布尔值也以字符串表达（如"true"）。
节点元数据
数据导入组件由 FlowCmpType.DbImport 标识：
| 属性名 | 类型 | 含义 | 取值/存储值 |
|---|---|---|---|
type | string | 组件类型 | 固定为 "DbImport" |
MetaObjectId | string(GUID) | 目标实体对象 | 缺省取当前接口所属对象 |
TemplateMetaViewId | string(GUID) | 导入模板（视图）主键 | 视图（MetaView）主键 |
SkipOperationPermission | string(bool) | 是否跳过操作权限校验 | "true" / "false" |
IsFinalResult | string(bool) | 是否输出到最 终结果 | "true" / "false" |
order | string | 同级排序 | 例："14" |
元数据存储示例
{
"ID": "import1",
"type": "DbImport",
"MetaObjectId": "3f9c0b2e-2d3a-4e6f-9c11-0f7a5b8d2e10",
"TemplateMetaViewId": "7a2b1c3d-4e5f-6789-abcd-ef0123456789",
"SkipOperationPermission": "false",
"IsFinalResult": "true",
"order": "14"
}
服务端执行逻辑
执行时机与场景
数据导入组件继承自 InterfaceComponentManagerBase，运行在平台接口链路中，是「文件 → 数据」链路的落库环节。它需要上游提供 List<ObjectData> 形式的待导入数据（通常来自导入数据解析），并依赖视图模板完成列与字段的映射。
通常在它之前可插入脚本、字段赋值等组件做二次加工（见 导入前对某个字段赋值）；在它之后可接脚本组件做导入后处理（见 导入后执行业务逻辑）。
输入参数（meta 键）
| meta 键 | 说明 |
|---|---|
MetaObjectId | 目标对象，校验阶段使用；不可为空 |
TemplateMetaViewId | 导入模板视图；为空时回落到上下文 DicParam["ChameleonImportTemplateMetaViewId"] |
SkipOperationPermission | "true" 时跳过新增 / 编辑操作权限校验 |
IsFinalResult | 是否把导入结果写入最终结果 |
执行期还读取上下文与请求：
context.DicParam["ChameleonMetaObjectId"]：执行阶段的实际操作对象 ID（由上游数据操作组件设置），与校验阶段的meta.MetaObjectId可能不同。context.CmpResult：待导入数据，须为List<ObjectData>。- 请求 query 的
importRepeatOperation = "1"：重复数据时执行编辑（更新），否则按跳过处理。 context.DicParam["SkipOperationPermission"]：与 meta 中的同名键二者取或，任一为真即跳过权限校验。
执行步骤
校验（_VerifyAsync）
MetaObjectId不可为空，且对象必须存在（同时把对象写入上下文缓存）。- 模板 ID 取
TemplateMetaViewId，为空时回落到上下文；仍为空则报「未配置模板视图」。 - 模板视图必须存在，且其
MetaObjectId必须与被导入对象一致，否则报「模板视图与对象不匹配」。
执行（_ExecuteAsync）
- 读取模板列（
GetImportTemplateColumnsAsync，仅未隐藏的列表项），并设置导入开始时间。 - 若
CmpResult不是List<ObjectData>或为空，直接进入下游。 - 过滤掉带
ChameleonSkipImport标识的行（静默跳过，见 跳过系统级导入）。 - 行数超过
ImportCountlimit（30000）直接报错。 - 权限校验（见下方「权限校验」）。
- 选择同步 / 异步执行（见下方「异步任务与批次」）。
- 逐批执行导入（见下方「数据校验与错误累积」「重复数据处理」）。
字段映射、反向翻译与默认值
- 模板列来自视图列表未隐藏项；每列带
Code（字段编码）、Name（列名）、IsImportRequired（导入必填）等。 - 每一批数据先做 反向翻译（
ReTranslateAsync）：把「数据源 / 人员 / 组织」等字段的显示文本还原为可存储的 value。 - 随后解析 系统默认值（
ParseSystemDefaultValueAsync），为未提供的字段补充默认值。 - 有重复校验键的字段即为必填（重复键参与去重判断）。
数据校验与错误累积
校验按批进行，错误信息累积在行数据的 ImportErrorMessage 动态字段上（该字段是临时拼接的，并非真实字段）：
- 必填校验：列被标记导入必填、或属于重复校验键，而值缺失 / 为空时，写入「XX 不能为空」，并终止该行后续校验。
- 重复校验（同批内去重）：当对象配置了重复校验字段时：
RepeatValidateRelationEnum.And：重复键拼接成一个分组值，同批重复即报「数据重复」；RepeatValidateRelationEnum.IndependentCheck：每个重复键各自独立去重，任一重复即报「数据重复」。
- 系统对象专项校验：员工信息（
System_UserInformation）、组织管理（System_Organization）会调用各自的批量字段校验。 - 字段级校验：
DataVerificationAsync产生失败清单FailureList。
已带 ImportErrorMessage 的行不再参与后续校验。校验完成后，失败行从待写入集合中剔除，并累加到 FailureList。你也可在导入前的脚本中自行给该字段赋值以自定义错误提示（见 自定义导入行错误提示）。
重复数据处理
当对象配置了重复校验字段且写入前发现库中已存在重复记录时：
importRepeatOperation = "1"（重复时编辑）：把命中记录的主键赋给当前行，走更新；- 否则：给该行写入重 复提示（优先使用对象自定义的
RepeatMessage），计入失败清单，跳过。
无重复键时，整批直接新增。
异步任务与批次
- 若上游已开启异步任务（
context.TinyTaskContext不为空），复用该任务执行，不再新建。 - 否则当行数大于
ImportAsyncThreshold（100）时，启动后台异步导入任务，立即返回「后台导入，完成后将通知您」及任务 ID；前端据此轮询、导入完成后由系统通知。 - 同步路径直接在当前请求内执行。
- 无论同步 / 异步，数据都按
BatchOperationPageSize（30）分批处理，每批更新导入进度。
写入方式按对象区分：员工信息、组织管理走各自的 BatchImportAsync，其它对象走通用 BatchAddAsync / BatchUpdateAsync（先经 CopyAsStandardFieldsListAsync 转换字段）。
输出与上下文
| 输出项 | 说明 |
|---|---|
context.CmpResult | 成功导入的数据（PreAddList，已剔除失败行） |
DicParam["BizDataIds"] | 成功导入数据的主键，逗号分隔 |
DicParam["MetaObjectCode"] / DicParam["MetaObjectId"] | 目标对象编码 / ID |
context.TransferResult.List | IsFinalResult = "true" 时写入 |
context.Result | IsFinalResult = "true" 时为成功提示（含开始时间、新增+编辑条数、失败条数） |
| 任务状态 | 有失败行时以「警告」完成，否则正常完成 |
当存在失败行时，组件会内部拉起数据导出组件生成失败明细 Excel（含 ImportErrorMessage 列），以短期存储（30 天）上传，并在导入完成通知中附带下载链接。通知使用模板 DefaultTemplateId_DataImportFinished，参数包括 ImportStartTime、AddedCount、EditCount、FailureCount。
权限校验
- 除非
SkipOperationPermission为真（meta 或上下文任一），否则校验对目标对象的 Insert 与 Update 两种操作权限（MetaObjectDataOperationType）。 - 上传 / 写入过程以当前请求用户身份执行。
性能、批次与限制
| 常量 | 值 | 说明 |
|---|---|---|
ImportCountlimit | 30000 | 单次导入最大行数，超出报错 |
ImportAsyncThreshold | 100 | 超过该行数转后台异步导入 |
BatchOperationPageSize | 30 | 每批处理的数据行数 |
- 异步任务使用独立的
ServiceProvider与TinyTaskContext（避免原请求生命周期结束）。 - 导入失败明细文件为短期存储，30 天后失效。
异常与校验
| 场景 | 提示 |
|---|---|
| 未配置操作对象 | 操作对象未找到 |
| 未配置模板视图 | 未设置模板视图 |
| 模板视图不存在 | 按 ID 未找到模板视图 |
| 模板视图与对象不匹配 | 模板视图与对象不匹配 |
| 行数超过上限 | 超过导入最大行数限制 |
模板数据源
「导入模板」下拉通过 POST /api/DataSource/GetMetaViewDataSource 获取，随操作对象切换重新请求。