用途:为 Notion 集成定义生产环境参考架构,统一处理访问、操作、队列、对账与证据。适合在标准化多个 Notion 集成时使用,流程要求在任何实际动作前先产出可审计的决策或工件。
主要能力与结构:将可持久架构拆分为传输、认证、租户绑定、对象身份、schema 映射、操作逻辑、队列、幂等、webhook、对账、遥测与证据存储。需在依赖可变字段、端点、版本、限制或投递行为前,重新核对带日期的证据映射。认证方面,集中密钥检索但不集中明文,每次操作绑定到连接、工作区、环境、能力与已批准内容范围。
使用方式:先定义领域边界、事实来源、租户模型、数据类别与服务目标;为当前页面、块、数据库、数据源、搜索、文件与 webhook 指定适配器;在明确边界放置幂等、检查点、背压、重试分类与死信;把对账作为独立于 webhook 投递的一等服务;定义可观测性、证据、隐私、保留、事件与支持接口;记录部署阶段、兼容策略、失败模式与已测试回滚。工具使用上,用 Read、Glob、Grep 检查文档、配置、代码、夹具与证据,仅在已批准仓库工件上使用 Write 和 Edit;仅调用不授权网络访问、凭据、工作区内容、用户数据、文件传输、部署、能力或共享变更、写入、支出或删除。
审批边界:采用共享令牌、共享队列、外部处理器或跨租户存储前,需架构、安全与数据所有者审查。
错误处理与限制:不要让 SDK 响应结构直接泄漏进领域模型;不要使 webhook 投递成为唯一恢复路径;拒绝无租户绑定的共享可变状态。输出需包含上下文与组件视图、契约、信任边界、失败模式、容量假设、运营归属与上线计划,并明确标注假设、所有者、过期与证据缺口。验证需记录租户隔离、schema 演进、重复写入、信号丢失、队列中断与回滚的预期和实际结果。