integration-capability-analysis

集成能力分析

Factorial 的集成框架按领域划分——目前包括薪资和财务——每个领域都定义了一组能力，每项能力都注明方向以及背后的 Factorial 端点。本技能会分析一个外部系统的规范，逐项梳理由哪些供应商端点实现这些能力，以及两个 API 之间的每个字段如何映射。

输出是一份集成映射文档，可同时供两类读者使用：负责判断是否值得构建此集成的人，以及随后负责构建的人。前者需要结论，后者需要端点调用顺序和字段映射。两者都遵循同一条规则——有据可引，否则降级表述：如果映射行、端点或结论无法在供应商规范中找到依据，就不能在文档中将其作为事实陈述。

目录即公开文档

Factorial 的 API 文档按领域分别列出能力，每个领域一页：

• 薪资 — https://apidoc.factorialhr.com/v2026-10-01/docs/payroll-integrations
• 财务 — https://apidoc.factorialhr.com/v2026-10-01/docs/finance-integrations

每次分析开始时，都要阅读相关领域的页面。每页都会列出该领域的能力、每项能力的方向、覆盖范围，以及相关 Factorial 端点的链接。这些页面是事实依据：分析其中列出的每项能力，采用页面注明的方向，并从链接的端点参考文档中获取 Factorial 字段名称。不要凭记忆推断薪资或财务集成通常包含什么——实际清单与直觉上的清单并不相同；基于错误能力集构建的映射，看起来可能和正确映射一样可信。

这些 URL 都带有版本号。使用请求者指定的版本；若未指定，则使用上方列出的版本，并在文档标题中记录所用版本，因为字段名称和能力可能随版本变化。

如果无法获取页面，请停止并说明情况，不要自行编造能力清单。

第 1 步 — 判定领域

判断供应商所属的领域：薪资引擎属于薪资；会计系统或 ERP 属于财务。有些系统横跨两个领域——例如带有薪资模块的 ERP——这种情况下，应分别分析每个领域，并为每个领域生成一份文档。如果系统不属于任何一个领域，请说明并停止；强行归入某个领域会导致映射无法使用。

在文档顶部用一行说明分类和理由。不要等待请求者确认；如果这是基于判断作出的分类，请说明这一点并继续分析。

第 2 步 — 加载领域的能力

根据领域页面整理工作清单：列出每项能力、其方向，以及页面链接到的 Factorial 端点。然后跟进这些端点链接以查看字段——未读过的字段无法进行映射。按能力逐项阅读端点文档，而不是一开始全部读完；领域页面链接的端点很多，其中大多数只服务于一项能力。

还要记录页面中对整个领域有约束作用的信息：顺序或设置流程（哪些记录必须先存在才能创建其他记录）、Factorial 写入时要求的标识符（例如，写入 Factorial 的记录必须包含 external_id），以及增量同步参数。这些信息会影响文档中的端点调用顺序，而不仅仅是单独的映射行。

第 3 步 — 清点供应商规范

在进行任何映射之前，先建立事实清单。从能力出发意味着寻找你预期存在的端点，并找到与之相近的内容。

对于 API 规范——OpenAPI/Swagger、开发者门户、PDF 指南——每个操作记录一行：方法、路径、功能、请求和响应字段及其必填标记，以及每项信息的来源（operationId、章节、页面）。这些引用将成为依据。

既要阅读字段文档，也要查看示例。 描述会说明字段的含义；示例往往会告诉你字段实际接受什么——日期格式、真实的枚举值、嵌套对象的结构、哪些字段会一起填充，以及示例中出现但架构从未记录的字段。示例往往能补全架构未明确规定的行为，因此要加以利用。如果示例与架构矛盾，应报告矛盾，而不是默默选其一。

在架构中，仔细检查 allOf 组合（实际的 required 列表是所有分支的并集），以及指向自身祖先的 $ref（这种关系被建模为嵌套对象而非 id——通常无法使用，值得在规范质量方面提出说明）。

对于文件规范，同样要按文件形式建立清单：每种记录类型或布局相当于一个端点，每一列相当于一个字段——并记录必填标记、类型、长度、代码列表、用于关联不同文件中记录的键、交付机制，以及任何确认文件或错误文件。

整份文档检查

以下是关于规范未包含哪些内容的判断；它们对能力的判断与规范实际包含的内容同样重要。要对照整份文件逐项核实，而不是凭印象判断——文件较长时，可进行计数或使用 grep。

• 按方法统计操作数量——GET、POST、PUT、PATCH、DELETE 各有多少个。
• 实际应用的身份验证（根级或每个操作中的 security 块），而非仅在 securitySchemes 下声明。
• 是否有操作声明错误响应。
• 不返回响应正文的操作——创建操作如果不返回任何内容，我们就没有 id 可存储。
• 分页（page、limit、offset、cursor）和列表端点上的增量筛选条件（updated_since、modified_since、since）。
• 速率限制——429、Retry-After、X-RateLimit-*、文档中说明的配额。
• 每一个 enum，因为每一个都是需要映射的代码列表。
• 能力所依赖端点上的 deprecated: true。

报告返回的内容，包括不返回任何内容的情况：“没有列表端点支持增量筛选”也是一项发现，而不是空白。

第 4 步 — 匹配每项能力

方向决定了要在供应商一侧查找什么：

出站——Factorial 是数据源。我们从 Factorial 的端点读取数据，并写入供应商，因此供应商需要写入端点（用于创建的 POST、用于更新的 PUT/PATCH），并且这些端点必须接受 Factorial 读取端点返回的数据。

入站——供应商是数据源。我们从供应商读取数据并写入 Factorial，因此供应商需要读取端点（GET，最好支持分页和按修改日期筛选），并返回 Factorial 写入端点所需的数据。

丰富的读取 API 对出站能力毫无帮助，丰富的写入 API 对入站能力也毫无帮助。供应商看起来覆盖全面，却最终无法满足需求，最常见的原因就是这种不匹配。

针对每项能力，找出实现它的供应商端点，并按照实现中调用它们的顺序列出——包括让主要调用成为可能的辅助调用：创建前解析法律实体或成本中心 id，创建后读回供应商的标识符，以及查询代码列表。然后检查字段，而不只是端点：几乎所有 HR API 都有 POST /employees，但它能否携带 Factorial 新员工的数据，完全取决于它的字段。

步骤 5 — 映射字段

这是文档的核心。对于每项能力，按照数据流动的方向，映射两个系统之间传递数据的每个字段。

对于每一行，记录：源字段和目标字段，使用完整路径（GET /employees → birth_on；POST /workers → person.date_of_birth）；目标字段是否为必填；是否存在转换；以及证据——架构、文档说明或示例。

集成往往正是在转换环节出问题，因此请具体说明：

• 格式 — 日期、时间戳和时区、小数分隔符、货币使用代码还是符号、金额采用主单位还是次单位。
• 代码列表 — 映射具体取值，而不只是字段。如果双方都公布了枚举值，请提供取值映射表；如果供应商的列表按客户配置，请说明映射需要按客户配置。
• 结构 — 一个字段拆分成多个字段（完整地址拆分为街道、门牌号和邮政编码）、多个字段合并为一个字段、扁平字段转换为嵌套对象、必须展平的列表。
• 单位 — 工作时间使用小时还是百分比、薪资按月还是按年、缺勤按天还是按小时。
• 标识符 — 一侧的 ID 存储在何处，以及下次同步时如何匹配记录。

然后分别列出两类缺口，因为它们的含义不同：

• 供应商要求但 Factorial 无对应源数据的字段。 这些字段会阻碍该能力，或迫使流程使用默认值或手动步骤。每项都需要明确的解决方案：常量、按客户配置的值、推导值，或缺口。
• Factorial 中存在但供应商没有对应目标字段的数据。 通常只是供应商不持有的数据；值得列出，以免有人误以为这些数据会同步。

绝不要为了补全一行而臆造供应商字段。未映射的行是一项发现；规格中不存在但听起来合理的字段名，则是文档缺陷。

步骤 6 — 分类

每项能力给出三种判定之一。

完全支持 — 供应商提供了该能力所需的所有操作，方向正确；目标端要求的每个字段都有源数据；并且下次同步时能够再次识别该记录。只有在规格明确说明所有这些内容时，才能判定为完全支持。

部分支持 — 操作存在，但缺少某项必要条件：目标端必填字段没有源数据、没有更新或更正途径、下次同步时无法匹配记录、时间相关数据没有生效日期，或代码列表没有公布取值。每项部分支持的判定都要说明限制，并给出可行性判断——可直接发布，或须先弥补缺口，以及弥补缺口所需的工作。

不支持 — 规格未涵盖该能力：缺少相应操作或实体、规格对此保持沉默，或唯一途径是通过供应商的 UI 手动操作。未涵盖和未说明归为同一类，因为结果相同——我们只能基于文档中记载的内容进行开发。在能力部分注明规格是明确排除了该功能，还是仅未作说明，因为未说明的问题可以向供应商确认，从而改变判定。

最后两种判定的界线：缺少字段会使能力变为部分支持；缺少操作或实体则意味着不支持。对于其他方面均可正常工作的能力，如果只有一项细节未说明——例如重新发送会替换数据还是累积数据——应判为部分支持，并明确指出这项细节是限制所在。

步骤 7 — 撰写文档

遵循 assets/report-template.md。填写每个部分；如果没有内容，请写“无”，而不是省略该部分，这样读者就能分清“没有内容可报告”和“尚未分析”。

首先写能力摘要，因为决策者会先看这一部分。然后为每项能力各写一个章节——包括领域页面列出的所有能力，即使是不受支持的能力，也要列出，以表明每项能力都经过了评估。每个章节都应包含端点调用顺序、字段映射、缺口和判定。字段映射是工程师实际实施的依据，因此必须完整覆盖范围内的字段，并准确说明路径和转换方式。

最后列出供应商问题，按每个答案对计划影响的大小排序，并合并可通过一次交流解决的问题。

保存为 <vendor>-<domain>-integration-mapping.md。

常见错误

• 凭记忆而不是依据领域页面开展工作。 实际能力列表更长，有时也出乎意料——其中包括方向。每次都要阅读该页面。
• 只匹配端点，不匹配字段。 端点名称正确但字段不符，最多只能算部分匹配。
• 忽略示例。 格式、枚举值和未记录的字段往往只出现在示例中。
• 臆造字段。 只映射供应商规范中出现的字段。
• 映射字段，却不映射取值。 两个 status 字段的枚举不同，在取值也映射之前，就不能算完成映射。
• 凭印象断言缺失。 “没有更新端点”会影响判定。请进行计数或 grep，然后再说明。