旧Excel台账里“行政部”和“行政”是同一个部门资产编码00128被保存成了128一行“办公电脑20台”原值写的是整批金额。把文件上传成功不代表这份台账已经正确进入资产系统。历史数据导入真正要解决的是旧表里的记录怎样转换成系统可以识别、关联和追溯的资产事实。上传、解析只是开始后面还要明确字段含义、确认业务粒度、处理错误行并核对最终数量与金额。本文用一份100条记录的旧台账作教学案例给出暂存数据结构、字段校验、批次处理和验收方法。技术示例面向Java 17、Spring Boot与MySQL 8.x字段和数量均为演示不代表真实项目实测。本文重点是首次迁移的完整流程同一文件反复提交、跨批次重复建卡等问题将在重复导入专题单独展开。目录先确定一行数据代表什么模板不是换列名而是约定字段含义Excel读出来的值未必是用户看到的值先导入暂存区错误行不要污染正式台账预检通过以后还需要一次提交确认导入结果应能回答“哪一行为什么没进来”验收不能只看“成功85条”需要撤销时先确认资产有没有被使用一、先确定一行数据代表什么设计模板前先看原表的记录粒度。一行是单台设备、采购批次还是某类资产的汇总如果这个问题没有解决再严格的格式校验也可能导入错误。旧台账内容不能直接做的处理应确认的业务事实办公电脑20台原值100000元生成20张卡每张原值100000元金额是总额还是单价是否需要逐件管理资产编码00128自动转成数值128编码是否保留前导零使用人张伟随便匹配第一个同名员工员工号、所属组织及离职状态状态“正常”一律转换为在用“正常”是技术状况还是使用状态原值为空自动填0数据缺失还是确实为零本例限定为“一行一件实物、一张资产卡”数量必须为1金额统一人民币元。批量汇总行先进入人工拆分流程不在本次导入中自动展开。拆分会影响数量和金额分摊应保留原记录与拆分后的对应关系。还要约定迁移截止时间。系统迁移的是某一时点的资产状态若导出后旧表继续发生借用、归还和调拨需要冻结窗口或补录增量清单不能导完快照就宣布账实同步。图1旧文件先经过粒度确认、映射和预检再进入正式入库与对账上传成功只是流程起点。二、模板不是换列名而是约定字段含义模板应带版本号例如asset-import-v1。导入任务保存模板版本及映射版本避免下个月修改字段解释后无法重现旧批次的处理规则。Excel字段目标字段类型与规则不满足时旧资产编码legacy_code文本按约定保留前导零空值进入确认不猜编码资产名称asset_name非空文本长度有上限行错误所属公司编码company_id在当前授权组织范围内映射拒绝越界部门编码department_id属于目标公司且允许使用行错误使用人工号custodian_id可选非空则需唯一匹配同名不能自动认领启用日期service_dateyyyy-MM-dd使用LocalDate格式或日历错误原值元original_cost非负Decimal本例最多两位小数不自动舍入使用状态usage_status按已确认字典转换未知值待处理是否允许停用部门承接历史记录、离职员工如何迁移要由业务规则决定。例如系统可以保留历史保管人信息同时把当前责任人设为待确认不能为了通过关联校验直接把全部旧记录挂到管理员名下。图2原始列先标准化再转换为系统标识名称映射存在歧义时应拦截而不是选一个看起来相近的值。公司范围必须来自服务端授权上下文。即使Excel有公司编码也只能从当前用户可操作范围内选择不能让上传者通过改一列数据跨公司写入。三、Excel读出来的值未必是用户看到的值1. 编码列应明确要求文本Excel数值单元格可能只存128显示格式却是00000。Apache POI的DataFormatter可按单元格格式取得显示文本但如果原文件已经丢失前导零和格式就无法凭读取工具恢复00128。因此应在模板中把编码设为文本并在接收时检查单元格类型超过Excel数值精度的长编号也不能先读成浮点数再转字符串。2. 金额不通过double中转本例不接受货币符号、千位逗号、科学计数法及超过两位的小数要求先把待导入值整理成规范十进制文本。下面是Java 17中可独立使用的字段解析示例金额上限需按实际系统调整importjava.math.BigDecimal;importjava.math.RoundingMode;importjava.util.regex.Pattern;publicfinalclassImportAmountParser{privatestaticfinalPatternAMOUNTPattern.compile((?:0|[1-9][0-9]{0,13})(?:\\.[0-9]{1,2})?);publicstaticBigDecimalparse(Stringraw){if(rawnull||!AMOUNT.matcher(raw.trim()).matches()){thrownewIllegalArgumentException(AMOUNT_FORMAT_INVALID);}returnnewBigDecimal(raw.trim()).setScale(2,RoundingMode.UNNECESSARY);}}这是单字段规则不负责Excel读取也不代表所有企业都只能保留两位小数。关键是按明确契约拒绝或转换而不是悄悄四舍五入。输入本例预期12501250.001250.501250.501,250.50拒绝要求规范格式空字符串拒绝不当作012.345拒绝不隐式舍入-1拒绝不符合本例原值约定3. 日期和公式分开处理启用日期优先要求ISO格式文本严格解析为LocalDate。若兼容Excel日期数值应由读取库识别日期格式和工作簿日期系统不自己硬编码起点去换算。金额等关键字段本例拒绝公式单元格要求在迁移副本里固化并复核数值同时保留原文件。公式缓存可能未更新支持公式计算的系统还需要明确计算范围、外部引用与失败处理不能直接假定“显示出来就是最终值”。上传端同时限制文件大小、工作表数、行列数和解压资源校验真实格式不仅检查扩展名。大文件采用适合的流式读取方案不能取消压缩安全限制来解决所有读取异常。四、先导入暂存区错误行不要污染正式台账建议分成三类记录批次、来源行和正式资产。正式资产模型继续使用项目现有设计不把导入状态混进资产使用状态。记录最低字段import_batchid、company_id、file_hash、template_version、mapping_version、snapshot_time、statusimport_rowbatch_id、source_sheet、source_row_no、raw_payload、normalized_payload、status、error_codeasset_card资产字段、source_batch_id、source_row_id、created_by、created_atraw_payload保留来源值normalized_payload保留映射后的目标值两者不能混用其中人员等敏感数据应限制访问并设置保留期限。文件摘要用于识别来源与追溯不单独承担所有业务防重规则。以下为MySQL 8.x隔离测试库中的暂存表示例假定批次表已由项目管理它不含完整外键、审计和租户安全设计不能直接替代生产表CREATETABLEasset_import_row_demo(idBIGINTPRIMARYKEYAUTO_INCREMENT,batch_idBIGINTNOTNULL,source_sheetVARCHAR(64)NOTNULL,source_row_noINTNOTNULL,raw_payload JSONNOTNULL,normalized_payload JSONNULL,statusVARCHAR(24)NOTNULL,error_codeVARCHAR(64)NULL,error_messageVARCHAR(500)NULL,target_asset_idBIGINTNULL,UNIQUEKEYuk_source_row(batch_id,source_sheet,source_row_no),KEYidx_batch_status(batch_id,status))ENGINEInnoDB;唯一键只保证同一批次内来源行不会重复落暂存不表示不同文件中的同一资产已经自动防重。正式写入仍须保留业务唯一约束不能把导入变成绕过约束的特殊通道。图3文件格式、字段值、业务关联和授权范围依次校验任何一层失败都应落到具体来源行和错误原因。本例100条来源记录中90条通过6条部门映射不明确4条金额格式不符预检结果应清楚显示“90条可提交、10条待处理”而不是“成功90%”就直接结束。如果一行有多个错误可用独立错误明细表记录字段、错误码与提示不要只留下最后一个错误覆盖此前结果。五、预检通过以后还需要一次提交确认预检与正式提交之间部门可能停用权限可能调整资产编码也可能被其他请求占用。因此预检结果是候选结果不是无限期有效的写入许可。确认页面至少展示目标公司、截止时点、模板版本、可导入行数、待处理行数以及有效记录的金额小计。若金额有解析失败不能把该小计称为“原文件总金额”。批次状态可以采用UPLOADED → VALIDATING → READY → IMPORTING → COMPLETED或PARTIAL批次级不可恢复错误进入FAILED。行状态单独采用READY、INVALID、IMPORTED、WRITE_FAILED两个层级分别表达流程与结果。图4分批提交可能得到部分成功批次状态与每行结果共同决定如何恢复不能用一条“导入失败”覆盖已提交事实。本例选择“允许明确确认后部分导入”90条有效记录先提交10条待纠正。若业务要求整份文件同时生效则应采用另一个明确方案不能边写边承诺全有或全无。提交事务的流程伪代码如下接收提交指令 服务端验证操作者对批次与目标公司的权限 原子地将READY批次认领为IMPORTING 逐个受控大小的数据块 开启数据库事务 锁定或认领本块尚未处理的来源行 重新校验关联、权限、业务约束及映射版本 写入正式资产并记录来源行标识 在同一事务内把来源行更新为IMPORTED 提交事务 失败时 回滚当前块 在独立、可靠的状态记录中登记失败原因 汇总已提交行与未提交行进入可恢复状态如果一个块中数据库约束冲突简单实现可以回滚整块并标记待重试若要求其余行继续成功就要单独设计行级事务或失败隔离不能在同一失败事务里catch后继续假装提交成功。Spring事务还需验证代理调用、回滚规则与多数据源边界。不要在导入事务内临时执行建表、改表或TRUNCATEMySQL多类DDL会隐式提交不能靠普通ROLLBACK保证撤销。进程在某块提交后崩溃恢复任务应以已持久化的来源行状态为准不能重新从文件第一行盲写。防重复点击、重试认领与跨批次幂等的完整实现留到下一篇但这不意味着第一版可以取消唯一约束。六、导入结果应能回答“哪一行为什么没进来”错误回执至少包含工作表、Excel原行号、来源编码、字段、错误码及修正提示。保留原行号不把有效记录过滤以后重新编号避免用户对错位置。原行号字段错误码提示示例18部门编码DEPARTMENT_NOT_FOUND当前公司下未找到该部门请确认映射42原值AMOUNT_FORMAT_INVALID请提供不含货币符号与千位分隔符的金额67使用人工号CUSTODIAN_AMBIGUOUS人员标识不能唯一确定请补充工号回执不直接写SQL异常或数据库路径。导出Excel时把用户原始文本作为文本单元格写入不将其解释成公式CSV回执还需针对以等号等字符开头的内容设置明确的公式注入防护规则。本例如果90条预检有效记录中85条写入5条因提交时关联变化未写入汇总应满足100条来源85条已导入10条预检无效5条提交失败或待处理。状态集合需要互斥且穷尽仍有未处理状态时必须列出不能漏计。可以用只读SQL核对暂存状态分布SELECTbatch_id,status,COUNT(*)ASrow_countFROMasset_import_row_demoWHEREbatch_id1001GROUPBYbatch_id,status;代码中的1001仅作教学批次号。生产查询还需要公司范围与访问权限过滤知道批次ID不代表拥有查看权限。七、验收不能只看“成功85条”数量相等也可能导错部门金额相等也可能互相错配。核对应该覆盖来源、字段、关联和业务可用性。图5导入完成后核对的是资产事实和追溯关系而不仅是成功数量未处理记录必须有明确去向。验收用例预期留存证据文本编码00128前导零按规则保留来源与卡片对照汇总行“电脑20台”被阻止或进入已批准拆分流程处理记录同名部门与人员不随机匹配字典映射结果金额空值、三位小数按契约拒绝错误回执跨公司修改模板服务端拒绝权限测试记录文件含公式按既定政策处理单元格类型与错误码块提交后进程中断已成功数据可辨认未成功部分可恢复批次与行状态正式资产抽样可以正常查询、借用或进入对应业务业务操作记录金额对账应使用相同币种和范围将“已导入来源行的规范金额之和”与“该批次生成正式资产的金额之和”比较不把整份文件总额与部分成功总额直接相比。本例暂存金额位于JSON中正式实现宜增加类型化校验列或审查后的对账查询避免临时强制转换掩盖非法值。抽样还应覆盖每个部门、状态类型和异常边界不能只抽前十条正常电脑。导入完成后发生了新的借用或调拨不宜用当前状态直接与迁移快照硬对应以迁移时点及后续流水解释差异。八、需要撤销时先确认资产有没有被使用整批导错目标公司不应立即按source_batch_id删除所有资产。部分资产可能已经被借用、调拨或引用直接删除会破坏后续记录。在确认尚无后续业务、依赖完整可控的情况下可评估有审计记录的撤销流程已经被业务使用的记录应采用经过审批的更正、停用或其他补偿方案。文件来源与迁移历史仍应保留不能靠删除日志“回到没发生过”。上线前确定谁负责最终核对、错误行什么时候补齐以及旧台账何时停止继续维护迁移才算真正交接完成。固定资产导入不是把Excel搬进数据库而是把一份有歧义的历史资料转成有规则、有来源、能继续流转的数据。让AI帮忙开发时可以把模板、映射表和上述验收用例一起提供要求它逐项实现并解释异常路径而不是只生成一个上传按钮。参考资料Apache POI电子表格读取、格式与日期处理MySQL会引发隐式提交的语句Spring声明式事务回滚规则
