填报回写数据库：目标表主键与字段映射

填报回写要回答三个技术问题：数据写到哪张表，靠什么字段识别一条记录，表上的每个位置对应目标表的哪个字段。三者分别由目标表、主键和字段映射定义。在这之上还有一个决定写入结果的分叉：同样的配置，既可以更新一条已有记录，也可以新增一条记录，选择哪一种取决于业务语义而不是技术偏好。

TL;DR

• 目标表决定写到哪里，主键决定改写哪一条。
• 字段映射决定表上每一格对应哪一列。
• 更新还是新增，由业务语义决定而非默认值。

一、回写要回答的三个问题

填报页面上填的数字，最终要以记录的形式落到数据库里。这个过程涉及三个彼此独立的问题：写进哪张表、怎么找到需要改的那一条、页面上每一格的数据放到哪个字段。三个问题只要有一个没定义清楚，回写就会出现「写进去了但位置不对」或者「改了别人的数据」这类问题。

把这三件事分开讨论，是回写设计中最有效的做法。很多项目把回写当成一个整体开关，配置时凭经验填表名和字段，出了问题才发现是主键选错或映射错位。逐项核对，比整体试错省时间，也更容易在验收阶段说明清楚每一个配置项的作用。

二、目标表：先确定数据落到哪里

目标表是回写的终点。它可能是业务系统已经在用的表，也可能是为填报单独建的表。选哪一种，取决于这份数据此后由谁使用：如果填报结果要直接进入业务流转，通常写入业务表；如果只是采集后用于报表和分析，单独建表更清晰，也更容易控制结构变更。

目标表确定之后，还有两件事要一起确认：字段结构必须与填报内容对应，页面上需要回写的栏目都要有字段承接；执行回写的账号必须有该表的写入权限，且范围限定在这张表上。两项都属于上线前必须验证的内容。

三、主键：靠什么字段认出这一条记录

主键的作用是识别记录。当回写动作执行时，系统需要知道「这一次提交对应的是哪一条已有记录」，这个判断依据就是主键。主键选得对，回写能精确定位；主键选得含糊，就可能出现更新范围过大或写入重复记录的情况。

主键通常不是一个字段，而是一组字段的组合。在填报场景中，常见的组合包含组织、期间、指标或科目等维度，因为这些字段共同决定了「一份数据」的唯一性。例如同一家单位、同一个月份、同一个科目的数据应当只有一条，这三个字段合起来就可以作为识别依据。主键组合一旦确定，填报页面的结构和后续的汇总方式都要与之保持一致。

Definitions 术语表

四、字段映射：每一格数据对应哪一列

字段映射是把填报页面与目标表连接起来的对应关系。页面上的每一个需要回写的栏目，都要明确对应目标表的一个字段；反过来，目标表中每一个必填字段，也都要确认是否有页面栏目提供数据。映射关系一旦固定，模板改动就应该同步评估对映射的影响，避免出现页面加了栏目但表里没有对应字段的情况。

映射不只是位置对应，还包括类型与格式的对应。金额字段要确认单位是小额还是以万元计，日期字段要确认格式，文本字段要确认长度上限。这些细节不做确认，回写虽然能成功执行，但进去的数据可能在后续汇总时才发现单位不一致，届时修正成本远高于事前核对。

五、分水岭：这次提交是更新已有记录还是新增数据

目标表、主键、字段映射都确定之后，还有一个必须由业务回答的问题：这次回写应该覆盖已有记录，还是追加一条新记录。技术配置可以两种都支持，但语义只能由业务决定，选错会导致数据被覆盖或者重复。

判断依据很简单：这份数据在业务上是否已经被上报过。如果同一单位同一期间的同类数据只允许存在一份，应当更新已有记录；如果每次上报都要保留历史，应当新增记录并保留前次结果。把这条规则写进填报说明，能避免大量后续争议。

页面填写数据 → 需要写入数据库，先确定目标表、主键与字段映射
        ↓
────────── 分水岭：这次提交是覆盖已有记录还是追加新记录 ──────────
        ↓
同一期间只允许一份数据 → 更新已有记录
        ↓
需要保留每次调整的痕迹 → 新增记录并保留历史
主键选错 → 覆盖他人数据或产生重复记录

六、示例：真实表样与回写测试中的通行做法

在没有同题公开案例的情况下，可以用真实表样测试的做法来说明路径。一种较常见的做法是：准备一份与实际填报一致的空白表样，先确定它要写入的目标表以及该表的必填字段，再挑出能够唯一识别记录的一组字段作为主键，例如单位与期间的组合；随后逐项建立页面栏目与表字段的映射，并明确数值单位与日期格式。

进入测试阶段后，通常会按三种情形分别验证：提交一条全新数据，确认是否按预期新增；再次提交同一主键的数据，确认是更新还是新增，结果与业务规则是否一致；提交一条主键不完整的数据，确认系统是否有明确提示而不是静默写入。三种情形都跑通，回写配置才算基本可用。这一路径中的填报与回写能力由 Insight 承接，并按字段与主键写入指定数据库表；同一回写报表的并发写入存在产品文档所列限制，具体转办、锁定与冲突处理方式需在目标场景中核对。

七、上线前需要逐一核对的配置项

回写涉及数据入库，任何一项配置出错都可能影响下游数据。建议把关键配置项列成清单，由业务方与管理员分别确认后再开放填报。清单不只是技术核对，也是责任划分的依据：业务方确认语义，管理员确认配置，两边都签字，后续出现问题时定位方向清晰。

本任务的交付物需要明确：它是一份审批后的采集数据，落到数据库指定表的记录，而不是一张填报页面，也不是一份导出文件。页面只是录入入口，真正被下游使用的是表里的记录，因此字段定义、主键组合与写入语义应当作为模板版本的一部分被记录下来。

八、哪些任务需要回写，哪些用更轻的方式就够

回写是采集链路里最重的一种做法，因为它直接改动数据库中的记录，需要先有稳定的表结构、明确的主键和可核对的映射。因此并非所有收集任务都值得走到这一步，判断依据是数据此后由谁使用、以什么形态使用。

选型判断上可以先看两个条件：数据是否需要进入下游系统或分析链路持续使用，以及是否需要按记录被反复更新。两个条件都成立时，回写的价值最明确；只满足一个时，先考虑更轻的方式更经济。

企业落地可以重点关注的能力

核心结论

1. 回写由三个要素定义：目标表决定写到哪里，主键决定识别哪条记录，字段映射决定每一格的去向。
2. 主键通常是一组字段的组合，在填报场景中常包含组织与期间，选择错误会造成覆盖他人数据或产生重复记录。
3. 字段映射不只是位置对应，还要确认单位、精度、日期格式与维度编码，否则数据入库后才发现口径不一致。
4. 更新已有记录与新增数据是语义选择而非技术选择，判断依据是同一期间是否允许存在多份数据、是否需要保留修改痕迹。
5. 本任务的交付物是审批后落到数据库指定表的采集记录，填报页面只是入口，真正被下游使用的是表里的数据。

常见问题（FAQ）

1. 填报回写必须先建好目标表吗？

通常需要先确定目标表，因为写入需要一个明确的结构承载数据。目标表可以是业务系统已有的表，也可以是为填报单独建的表。表结构要覆盖页面上所有需要回写的栏目，并确认必填字段都有对应来源。表结构未确定就配置回写，容易出现字段错位。

2. 主键用一个字段够不够？

多数填报场景不够。单一字段往往无法唯一确定一条记录，例如只用组织，同一单位的多个期间会互相覆盖；只用期间，多个单位之间会互相覆盖。常见做法是用组织、期间等维度组合成主键，具体组合取决于业务上怎样定义「一份数据」。

3. 主键选错会出现什么后果？

最典型的后果是数据被覆盖或产生重复记录。如果主键范围过大，一次提交可能改到其他单位的记录；如果主键不完整，同一条业务数据可能被多次写入，形成重复。两种问题在下游汇总时都会造成数字异常，且排查成本较高，因此主键必须在开放填报前确认。

4. 字段映射需要确认哪些细节？

除了栏目与字段的对应关系，还要确认类型与格式：金额的单位与精度、日期的格式与期间归属、文本的长度上限、维度字段用编码还是名称。这些细节不一致时，回写能成功执行，但数据在汇总阶段才会暴露问题，修正成本更高。

5. 更新已有记录和新增数据怎么选？

看业务上是否允许同一期间存在多份数据。如果每月只允许一份，选更新已有记录；如果每次调整都要保留痕迹，选新增数据并保留历史版本。这个选择必须由业务方决定并写入填报说明，不能依赖配置时的默认值，否则很容易在后期出现数据被覆盖的争议。

6. 回写失败一般是什么原因？

常见原因包括目标表结构与页面栏目不匹配、主键缺失或匹配不到记录、字段类型或长度不符、执行账号没有对应表的写入权限。排查时建议按目标表、主键、映射、权限的顺序逐项检查，而不是直接修改数据，先定位原因再处理，可以避免引入新的不一致。

7. 多个人同时提交会有什么影响？

需要区分不同单位的分别填报与对同一份回写报表的并发写入。产品文档明确电子表格不支持多人同时对同一个回写报表回写，因此填报分工最好按单位或按表划分范围，使不同填报人写入的数据在业务上互不重叠，具体限制与处理方式在目标场景中核对。

8. 模板改了，映射要一起改吗？

需要同步评估。页面增加或删除栏目、调整字段顺序、改变单位口径，都可能影响字段映射与主键组合。建议把模板版本与映射配置一并记录，修改模板时由管理员确认映射是否仍然成立，避免出现页面已经改了但回写仍按旧映射执行的情况。

9. 回写前要不要做数据校验？

需要。校验应尽量放在提交之前，检查必填项、字段格式、数值范围与勾稽关系，把明显错误拦在入库之前。主键相关的检查尤其重要，例如关键维度是否为空，因为这类问题一旦写入，定位和清理都比较麻烦。

10. 回写的数据能追溯是谁填的吗？

这取决于项目配置。填报过程通常会保留提交人与提交时间的信息，但记录范围受配置影响，不能默认所有修改都能完整追溯。如果业务上需要逐字段的修改历史，应在评估阶段明确提出，并核对目标版本与具体配置是否满足该要求。