用途
Terra Troubleshooting 是一个面向 Terra API 的故障排查与调试技能，适用于开发者在使用 Terra 集成健康与运动数据时遇到连接问题、数据同步异常、Webhook 失败、SDK 错误或特定提供商兼容性问题时进行诊断和修复。
主要能力
该技能覆盖以下排查方向：
- 快速诊断：提供健康检查脚本，检测 API 连通性和已连接用户数量。
- 认证问题：处理无效 API key 或 dev-id、Widget 会话过期、移动端 SDK token 失效等问题。
- 连接问题：解决用户卡在“连接中”、提供商返回“Access Denied”、WHOOP/Dexcom 等特殊激活需求。
- 数据同步问题：排查无数据、重复数据、历史数据缺失等情况，并给出各提供商历史数据上限参考。
- Webhook 问题：检查 Webhook 未接收、签名验证失败、超时处理等。
- SDK 问题：涵盖 iOS Apple Health 无数据、Android Samsung Health 失败、Health Connect 问题、React Native 构建失败等。
- 提供商特定问题：如 MyFitnessPal 网关超时、Garmin 数据延迟、Fitbit token 撤销等。
- 调试模式：启用 Terra SDK 详细日志和 HTTP 日志。
- 支持升级：提供状态页、文档、邮件支持及提交支持请求所需信息。
使用方式
该技能以代码示例和排查清单的形式提供解决方案。开发者可根据具体问题类型，参考对应的诊断脚本、修复代码或配置调整。例如，使用健康检查脚本验证 API 连通性，或通过签名调试函数排查 Webhook 签名验证失败。
适用场景
适用于正在集成或已集成 Terra API 的开发者，在遇到连接、同步、Webhook、SDK 或提供商相关故障时，快速定位原因并获取修复方案。
限制
该技能主要针对 Terra API 的常见问题提供排查思路和代码示例，不保证覆盖所有异常情况。部分问题（如 WHOOP、Dexcom 激活）需要联系 Terra 支持。具体提供商的限制和激活要求可能随 Terra 政策变化，建议以官方文档为准。