---

## 7. 监控与可观测性

### 7.1 健康检查端点

合作伙伴必须实现一个健康检查（Health Check）端点，SyncBridge 每隔 60 秒会对其发起轮询：

```
GET /health
```

**正常响应**（HTTP 200）：

```json
{
  "status": "healthy",
  "version": "2.4.0",
  "uptime_seconds": 864000,
  "dependencies": {
    "database": "healthy",
    "cache": "healthy",
    "message_queue": "healthy"
  }
}
```

**降级响应**（HTTP 200，含降级状态）：

```json
{
  "status": "degraded",
  "version": "2.4.0",
  "issues": [
    {
      "component": "cache",
      "status": "unhealthy",
      "message": "Redis connection pool exhausted",
      "since": "2026-04-10T11:30:00Z"
    }
  ]
}
```

### 7.2 指标端点

合作伙伴应该暴露一个兼容 Prometheus 的指标端点：

```
GET /metrics
```

**必须上报的指标**：

| 指标 | 类型 | 说明 |
|------|------|------|
| `syncbridge_entities_received_total` | Counter | 通过推送接收到的实体总数 |
| `syncbridge_entities_sent_total` | Counter | 通过拉取发送的实体总数 |
| `syncbridge_sync_duration_seconds` | Histogram | 同步操作耗时 |
| `syncbridge_errors_total` | Counter | 按类型统计的错误总数 |
| `syncbridge_webhook_deliveries_total` | Counter | 收到的 Webhook 投递总数 |
| `syncbridge_active_connections` | Gauge | 当前活跃连接数 |

### 7.3 日志记录要求

合作伙伴必须记录所有与 SyncBridge API 的交互日志，并包含以下上下文字段，以便故障排查：

| 字段 | 说明 |
|------|------|
| `request_id` | 请求中 `X-SyncBridge-Request-Id` 请求头的值 |
| `batch_id` | 实体同步操作的批次标识符 |
| `correlation_id` | 跨多个服务的端到端关联 ID |
| `partner_id` | 合作伙伴的客户端 ID |
| `timestamp` | 日志条目的 ISO 8601 时间戳 |
| `duration_ms` | 请求处理耗时（毫秒） |
| `status_code` | HTTP 响应状态码 |

---

## 8. 数据格式规范

### 8.1 时间戳

所有时间戳均采用 UTC 时区的 ISO 8601 格式：

```
2026-04-10T08:15:30Z
2026-04-10T08:15:30.123Z
```

合作伙伴必须同时接受秒精度和毫秒精度的时间戳。响应中应该在条件允许时使用毫秒精度。

### 8.2 实体 ID 格式

实体 ID 必须是全局唯一的字符串，并满足以下约束：

- 最大长度：128 个字符
- 允许的字符：字母、数字、连字符、下划线
- 不得以连字符或下划线开头
- 区分大小写

推荐格式：`{type_prefix}_{uuid_v4}`（例如：`contact_a1b2c3d4-e5f6-7890-abcd-ef1234567890`）

### 8.3 分页

所有列表端点均采用基于游标的分页方式。游标是一个不透明字符串，应该在后续请求中原样传回。合作伙伴不得尝试解码或自行构造游标。

**分页参数**：

| 参数 | 说明 |
|------|------|
| `limit` | 每页返回的条目数（默认：100，最大：500） |
| `cursor` | 上一次响应返回的不透明游标 |

**分页响应字段**：

| 字段 | 说明 |
|------|------|
| `cursor` | 下一页的游标（若为最后一页则为 null） |
| `has_more` | 布尔值，表示是否还有更多分页 |
| `total_estimate` | 总数估算值（可能不精确） |

### 8.4 字段映射配置

合作伙伴可通过仪表盘或 API 配置自身 Schema 与 SyncBridge 标准 Schema 之间的字段映射：

```
PUT /mappings/{entity_type}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "entity_type": "contact",
  "mappings": [
    {
      "source_field": "full_name",
      "target_field": "name",
      "transform": "none"
    },
    {
      "source_field": "email_address",
      "target_field": "email",
      "transform": "lowercase"
    },
    {
      "source_field": "created_date",
      "target_field": "created_at",
      "transform": "iso8601"
    },
    {
      "source_field": "department.name",
      "target_field": "department",
      "transform": "flatten"
    }
  ],
  "unmapped_field_policy": "passthrough"
}
```

**可用转换操作**：

| 转换操作 | 说明 |
|----------|------|
| `none` | 直接传递原始值 |
| `lowercase` | 将字符串转为小写 |
| `uppercase` | 将字符串转为大写 |
| `iso8601` | 解析并规范化为 ISO 8601 UTC 格式 |
| `flatten` | 使用点分表示法从嵌套对象中提取值 |
| `array_join` | 将数组元素拼接为逗号分隔的字符串 |
| `string_split` | 将逗号分隔的字符串拆分为数组 |
| `hash_sha256` | 单向哈希（用于 PII（个人身份信息）脱敏） |
| `mask` | 保留最后 4 位，其余字符全部掩码处理 |
| `custom` | 由合作伙伴提供的自定义 JavaScript 转换函数 |

---

## 9. 测试与沙箱

### 9.1 沙箱环境

SyncBridge 提供功能完整的沙箱环境，供集成测试使用：

- **基础 URL**：`https://sandbox.syncbridge.io/api/v2/`
- **令牌端点**：`https://sandbox.syncbridge.io/oauth/token`
- **速率限制**：与生产环境相同（以便测试速率限制处理逻辑）
- **数据保留**：沙箱数据每 30 天清除一次

### 9.2 测试夹具

SyncBridge 通过沙箱 API 提供预置的测试夹具：

```
GET /sandbox/fixtures
Authorization: Bearer {sandbox_token}
```

可用的测试夹具包括：

- `basic_contacts` — 50 个字段各异的联系人实体
- `large_batch` — 1000 个实体，用于批次处理测试
- `schema_evolution` — 跨多个 Schema 版本的实体
- `error_scenarios` — 专门用于触发特定错误码的实体
- `unicode_stress` — 包含 CJK 字符、Emoji 及从右到左（RTL）文本的实体

### 9.3 集成测试检查清单

合作伙伴必须通过以下集成测试，方可上线：

| # | 测试项 | 说明 | 端点 |
|---|--------|------|------|
| 1 | 认证流程 | 完整的 OAuth 令牌交换 | `/oauth/token` |
| 2 | 推送同步 | 接收并处理包含 100 个实体的批次 | `/entities/sync` |
| 3 | 拉取同步 | 返回自指定时间戳起已修改的实体 | `/entities` |
| 4 | 接收 Webhook | 处理 Webhook 投递并返回 200 | Webhook URL |
| 5 | 验证 Webhook | 正确验证 Webhook 签名 | Webhook URL |
| 6 | 速率限制处理 | 优雅处理 429 响应 | 任意端点 |
| 7 | Schema 注册 | 成功注册实体 Schema | `/schemas/{type}` |
| 8 | 错误处理 | 对无效请求返回规范的错误格式 | 任意端点 |
| 9 | 健康检查 | 返回包含依赖信息的正常状态 | `/health` |
| 10 | 幂等性 | 使用相同幂等键正确处理重复请求 | `/entities/sync` |
| 11 | 分页 | 正确分页遍历大型结果集 | `/entities` |
| 12 | 并发同步 | 处理 10 个并发同步请求 | `/entities/sync` |