技能介绍

解决什么问题

Notion 数据库适合承载项目跟踪、内容台账等结构化记录，但一旦数据需要和外部系统双向流动，手写同步很容易出现三类问题：分页遗漏、属性类型对不上、同一记录被多方修改后结果不可预测。Notion 数据库同步桥接 面向这些场景，把 Notion 数据库作为同步链路的一侧，通过 Notion API v2022-06-28 与外部数据源建立数据交换。

核心能力

使用 cursor-based pagination 读取分页数据，避免普通分页在数据变化时漏页或重复读取。
处理 property type mapping，重点覆盖 select、multi-select、relation、formula 等 Notion 属性类型。
在冲突发生时采用 last-write-wins 策略：较晚写入的结果覆盖较早写入结果，不做字段级合并。
可基于 @notionhq/client 的客户端能力组织请求；SDK 示例中出现的 APIErrorCode 与 LogLevel 可分别用于错误分类和日志控制。

关键工作链路可理解为：从 Notion 数据库分页读取记录 → 将数据库属性映射为外部源可接收的结构 → 写入或更新外部数据 → 冲突时保留最后一次写入。外部源的响应结构需要由使用者根据目标系统设计适配逻辑；技能资料本身没有描述具体外部系统的固定适配器。

适用边界与注意点

适合 单侧为 Notion 数据库、另一侧可编程访问的同步任务。如果业务要求字段级合并、人工冲突仲裁、多主节点强一致或跨数据库复杂关系同步，当前资料只说明 last-write-wins，不能直接推出这些能力。另外，relation 与 formula 的映射结果会受 Notion 数据本身约束；分页游标和写入顺序会影响最终一致性表现。建议在接入前先用小样本验证属性类型映射、写入失败重试和冲突结果是否符合预期。