用途：为开发者在集成 Terra API（统一健康与健身数据 API，支持 500+ 可穿戴设备）时提供经过生产环境验证的最佳实践规则，来自真实的跨设备集成经验。
主要能力与规则分类（按影响优先级）：
- Webhook 处理（关键）：在解析 JSON 前，用原始未改动 body 校验签名头 HMAC（terra-signature / X-Terra-Signature，大小写不敏感读取）；在超时内（默认 8 秒）返回 200 并异步处理；按 X-Terra-Trace-Id 去重，terra-reference 为大请求各分块共享；将原始 payload 归档到对象存储，用 payload key 关联行；显式路由非数据事件，处理 s3_payload 投递，遇到未知类型不崩溃。
- 数据处理与幂等（关键）：activity/sleep 以 summary_id 为键，daily 类型以 (connection, date) 为键，hormone 以时间戳为键；在任何时区转换前先从 ISO 字符串切出日期；标准字段遵循超集保证，当 X-Terra-Ordering-Timestamp 更新或相等时覆盖；enrichment 分数打破超集保证，用 COALESCE 避免 null 覆盖；把指标抽取为带类型的列，原始 payload 存对象存储；遵循 timestamp_localization 标志，明确选定一种存储策略。
- 认证与连接生命周期（高）：将自己的用户 ID 作为 reference_id 传入，它是每个 webhook 的关联键；用幂等 upsert 处理全部七种 auth 事件类型；user_reauth 会签发新的 Terra 用户 ID，需替换旧的；解析逗号分隔的 scope 字符串，在 permission_change 时应用 scopes_added/scopes_removed；在页面挂载、认证重定向和定时任务中与 Terra API 状态对账；调用公开 integrations 目录时发送 dev-id，否则返回全部 provider 而非你启用的集合。
- 多设备数据（中）：同一会话会按设备各到达一次且 summary_id 不同，合并策略由应用自己负责；enrichment 分数为 provider 无关且可比较，但仅在分数权重激活时存在。
- 测试（低-中）：mock SDK、数据库与后台任务，使异步处理变为急切执行；测试重放、空数据数组、未知用户、type 0、enrichment 为 null、reauth 替换等边界情况。
使用方式：处理某领域时阅读 rules/ 下对应规则文件（如写 webhook 端点前读 rules/webhooks-verify-raw-body.md 及同类文件）。每条规则含正误代码示例，并链接到 docs.tryterra.co 相关页面（任意文档 URL 后加 .md 可得 markdown 版本）。若已连接 terra-docs MCP 服务器（https://docs.tryterra.co/~gitbook/mcp），可用其工具搜索和获取这些页面。
限制与范围说明：本技能覆盖 Terra 核心健康与健身 API 集成。Terra 还提供用于设备端来源（Apple Health、Samsung Health、Health Connect）的移动端 SDK、基于 websocket 的实时 Streaming API、向 AI 智能体暴露健康数据查询工具的 MCP 服务器、计划训练与路线（写回设备类产品）以及实验室报告，这些表面见 docs.tryterra.co。本资料未提供具体收费、价格或平台信息。