Health Detail Insight v3 Contract
Back to API-DOCS
# 健康详情 AI 洞察接口接入规范（主服务）
**协议版本：** `health-detail-v3`（2026-10-09 起为 C4 精简版）
**接口：** `POST /v1/health-detail-insights/generate`
**调用方：** Pulse Server FeedAuto（`CurrentDetailInsightService` 组装，`AiGatewaySubcriber` 发送）
**服务方：** AI Gateway（校验请求，按服务端评级与文案目录确定性生成一段正文，不调用模型）
> 本文是主服务唯一的健康详情接入协议。产品口径见飞书「健康详情页 AI 洞察实现逻辑」第 13 章（2026-10-08 现行口径）。Gateway 不补数据、不重算调用方给的聚合、不拿请求里的范围自己下结论。
## 0. 2026-10-09 变化（整改 C1 / C2）
- **只收 C4 请求。** 不带 `insightContext` 的旧格式请求返回 422；旧的范围判定引擎、上一周期比较、模型润色和模型评审已删除。生产流量自 09-21 起已全部是 C4 请求。
- **占位字段不再要求。** 全 `unavailable` 的基线块、全 `null` 的佩戴数组、24 个空小时点、白天休息占位、`anomalyNights`、`previousPeriod: null`、宠物耐受度等都可以不发；缺省即等同原占位值。10-09 前的 FeedAuto 照发占位时，Gateway 仍按原规则校验并给出完全相同的正文（`tests/unit/test_feedauto_c4_wire.py` 逐份核对）。
- **上线顺序：** Gateway 先于 FeedAuto（新 FeedAuto 的精简请求会被旧 Gateway 拒收）。
- 2026-10-12（第二轮优化 E 批）：吠叫正文讲约时长（与页头主数字、评估、▲% 同一个量），次数放括号；吠叫日视图可带个体上限 `comparison.usualUpper`（只有上限，旧 Gateway 会拒收，所以 Gateway 先上）；今天到此刻的体征 / 吠叫只说平时范围，不下结论。
- 2026-10-10：过渡模式已删除——不再接受 `recent_complete_days`，`last_night` 只用于休息（体征的今天讲全天，用 `today_so_far`）。这两种模式只有 10-08 前的 FeedAuto 发过，留档显示 10-08 起为 0。
## 1. 请求
### 1.1 顶层
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `schemaVersion` | string | 是 | 固定 `health-detail-v3` |
| `userId` / `petId` | string | 是 | 留档时 `petId` 存 HMAC 哈希 |
| `metric` | enum | 是 | `activity` / `rest` / `hr` / `hrv` / `rr` / `bark` |
| `viewWindow` | enum | 是 | `day` / `week`（周一起）/ `month`（自然月） |
| `locale` | enum | 否 | `zh-CN` / `en-US` / `es`，默认 `en-US` |
| `petProfile.name` / `petProfile.species` | string / enum | 是 | 正文用名字；`species` 为 `dog` / `cat` |
| `period.startDate` / `period.endDate` | date | 是 | 宠物所在时区的本地日期 |
| `period.timezone` | string | 是 | IANA 时区 |
| `period.isCompleted` | boolean | 是 | 窗口是否已结束；含今天的窗口为 `false` |
| `period.elapsedNights` / `period.validNights` | integer | 休息、体征的周 / 月必填 | 已过去夜数 / 有合格记录的夜数 |
| `insightContext` | object | 是 | 见 1.2 |
| `suppliedJudgment` | object | 休息、体征必填 | 见 1.3 |
| `metrics` | object | 是 | 见 1.4 |
| `previousPeriod` | null | 否 | 只为旧版 FeedAuto 保留；带对象会被拒收 |
### 1.2 `insightContext`
| 字段 | 说明 |
| --- | --- |
| `mode` | `today_so_far`（今天到此刻）/ `last_night`（休息：08:00 后看今天的标签讲昨夜）/ `selected_window`（选中的历史日或周 / 月） |
| `asOf` | 查看时刻（带偏移的 ISO 8601）；`isCompleted=true` 的窗口必须早于它的本地日期 |
| `observedThrough` | 最近一次上报时刻；`today_so_far` 必填 |
| `factVersion` | 事实指纹 |
| `sourceSnapshot` | 休息的来源快照；带评级时须为完整的 versioned 快照 |
| `baselineProgress` | `validDays` / `requiredDays`：个体范围建立前，日视图说一句进度 |
| `comparison` | 页面同源比较，全部可选、只读：`usualLower` / `usualUpper`（个体范围，仅 personal；吠叫是单侧指标，只给 `usualUpper`，单位秒；其他指标两者成对）、`changePercent`（与页头 ▲% 同值）、`consecutiveUnusualDays`（≥2 才说）、`unusualLowDays` / `unusualHighDays`（活动，两者之和等于关注天数才分开说）、`restRatingFactors`（休息一般 / 较差时的扣分项）、`pageEvaluationBasis`（`personal` / `breed` / `general`） |
### 1.3 `suppliedJudgment`（服务端评级，只认个体范围）
| 指标 | `ruleVersion` | `rating` | 天数字段 |
| --- | --- | --- | --- |
| 休息 | `sleep-rating-c2-v1` | `Good` / `Fair` / `Poor` / null | `ratedNights`、`lowRestDays` |
| 心率 / HRV / 呼吸率 | `vital-judgment-c1-v1` | `normal` / `balanced` / `fluctuating` / `low` / `high` / null | `judgedDays`、`unusualDays` |
| 活动 | `activity-judgment-v1` | `normal` / `fluctuating` / `low` / `high` / null | `judgedDays`、`unusualDays` |
| 吠叫 | `bark-judgment-v1` | `calm` / `active` / `frequent` / null | `judgedDays`、`unusualDays` |
- `rating`、`direction`（-1 / 0 / 1 / null）、`baselineSource` 三个键必须出现（值可为 null）。
- 关注天数是个体范围下 L2 且恶化方向的天数，与页面「异常天数」同口径；还没有评级的窗口天数为 0、关注天数为 null。
- `deteriorating`（可选）：评级方向本身是否算变差；`false` 时只陈述、不给建议。
- 周 / 月：评级天数达到周 3 / 月 10 才给整期结论（0 天关注 → `normal`，≥1 → `attention` 附建议）。
### 1.4 `metrics`（页面同源事实）
| 指标 · 窗口 | 字段 |
| --- | --- |
| 活动 · 日 | `activityTime.activityMinutes`（必填）、`activityTime.activityMinutesGoal`（设了目标时）、`steps.steps` |
| 活动 · 周 / 月 | `activityTime.averageDailyActivityMinutes`（只算已结束的日子，没有则 null）、`activityTime.dailyActivityMinutes`（按日历顺序，未来留 null）、`steps.averageDailySteps` / `steps.dailySteps` |
| 休息 · 日 | `night.startAt` / `night.endAt`（前一天 22:00 到当天 08:00）/ `night.isCompleted`、`night.nightRest.minutes`、`night.interruptions.count`、`night.nightActivity.minutes`、`night.longestRestBlockMinutes`（可为 null）、`night.wearingMinutes`、`day.hourlyRestMinutes`（有白天记录时） |
| 休息 · 周 / 月 | `nightRest.averageMinutes`、`interruptions.averageCount`、`nightActivity.averageMinutes`、`nightlyRestDurations[]`（`nightDate` / `lightMovementMinutes` / `deepRestMinutes`）；有白天记录时 `dailyDayRestMinutes` 与 `dayRest.averageMinutes`（只算已结束的日子） |
| 体征 · 日 | `night`、`nightRest{X}Average` 与 `allDayRest{X}Average`（`value` / `sampleCount`，X = Hr / Rmssd / Rr） |
| 体征 · 周 / 月 | 上述两个均值、`dailyNightRest{X}[]`、`dailyAllDayRest{X}[]`、`aggregationMethod: daily_median_mean_v1`；夜间均值只算 ≥4 个样本的合格夜，全天均值只算已结束的日子 |
| 吠叫 · 日 | `measurementMode: estimated`、`barkDurationSeconds`、`barkEventCount`、`longestBarkEventDurationSeconds` |
| 吠叫 · 周 / 月 | `averageDailyBarkDurationSeconds`、`barkEventCount`、`averageDailyBarkEventCount`、`dailyBarkDurations[]`（`date` / `barkDurationSeconds`） |
## 2. 响应
| 字段 | 说明 |
| --- | --- |
| `insightId` | Gateway 生成 |
| `petId` / `metric` / `viewWindow` / `period` | 原样返回 |
| `status` | `attention` / `normal` / `observation` / `insufficient_data`；`observation` 是中性陈述，不等于正常 |
| `severity` | 关注为 `low`，其余 `none` |
| `summary` | 一段正文：事实句 + 至多一句补充（建议 / 建立进度 / 佩戴提示）；不写等待句、内部用语、算法参数和诊断 |
| `generation` | `ruleId` / `ruleVersion` / `generatedAt` / `aiPolished`（恒为 false） |
422 不回传字段详情，按 `X-Request-ID` 查两端日志。
## 3. 示例
全部来自场景库（`app/health_detail/scenarios.py`，基于 FeedAuto 真实序列化的样本 `app/health_detail/samples/`）；37 个场景的三语正文见演示页、`/api-docs` 与 `scripts/validate_health_detail_journeys.py` 生成的 `report.md`。
### 3.1 心率 · 历史某天 · 在平时范围内
请求：
```json
{
"period": {
"endDate": "2026-09-08",
"timezone": "Asia/Shanghai",
"startDate": "2026-09-08",
"isCompleted": true
},
"petId": "7",
"schemaVersion": "health-detail-v3",
"metric": "hr",
"insightContext": {
"mode": "selected_window",
"comparison": {
"usualUpper": 80.0,
"usualLower": 64.0,
"pageEvaluationBasis": "personal"
},
"asOf": "2026-09-10T15:00+08:00",
"observedThrough": "2026-09-08T08:00+08:00",
"factVersion": "ee84aff0255fb9f96caf24d4bfd238fb17ce5b4a7f46bec69ccc739fa3f962fe"
},
"petProfile": {
"species": "dog",
"name": "Pocky"
},
"suppliedJudgment": {
"unusualDays": 0,
"judgedDays": 1,
"ruleVersion": "vital-judgment-c1-v1",
"rating": "normal",
"baselineSource": "personal",
"direction": 0
},
"metrics": {
"allDayRestHrAverage": {
"sampleCount": 8,
"value": 78.0
},
"night": {
"endAt": "2026-09-08T08:00+08:00",
"startAt": "2026-09-07T22:00+08:00",
"isCompleted": true
},
"nightRestHrAverage": {
"sampleCount": 3,
"value": 78.0
}
},
"locale": "zh-CN",
"userId": "1",
"viewWindow": "day"
}
```
返回：
```json
{
"insightId": "health_detail_example",
"petId": "7",
"metric": "hr",
"viewWindow": "day",
"period": {
"startDate": "2026-09-08",
"endDate": "2026-09-08",
"timezone": "Asia/Shanghai",
"isCompleted": true
},
"status": "normal",
"severity": "none",
"summary": "9月8日，Pocky 的静息心率是 78 次/分，在它平时的范围内（64–80 次/分）。",
"generation": {
"ruleId": "HR_SUPPLIED_JUDGMENT",
"ruleVersion": "health-detail-2026-09-11-r10",
"generatedAt": "2026-10-09T00:00:00Z",
"aiPolished": false
}
}
```
### 3.2 心率 · 已结束的一周 · 都在平时范围内
请求：
```json
{
"period": {
"elapsedNights": 4,
"endDate": "2026-09-13",
"timezone": "Asia/Shanghai",
"startDate": "2026-09-07",
"validNights": 0,
"isCompleted": false
},
"petId": "7",
"schemaVersion": "health-detail-v3",
"metric": "hr",
"insightContext": {
"mode": "selected_window",
"asOf": "2026-09-10T15:00+08:00",
"observedThrough": "2026-09-10T08:00+08:00",
"factVersion": "aa925ec23bdebca62f1f83b70bb713d5b4e067cccb94615589ebe60374a85f40",
"comparison": {
"changePercent": -3.4
}
},
"petProfile": {
"species": "dog",
"name": "Pocky"
},
"suppliedJudgment": {
"unusualDays": 0,
"judgedDays": 5,
"ruleVersion": "vital-judgment-c1-v1",
"rating": null,
"baselineSource": "personal",
"direction": null
},
"metrics": {
"dailyAllDayRestHr": [
{
"date": "2026-09-07",
"sampleCount": 3,
"allDayRestHrAverage": 80.0
},
{
"date": "2026-09-08",
"sampleCount": 3,
"allDayRestHrAverage": 80.0
},
{
"date": "2026-09-09",
"sampleCount": 3,
"allDayRestHrAverage": 80.0
},
{
"date": "2026-09-10",
"sampleCount": 3,
"allDayRestHrAverage": 80.0
},
{
"date": "2026-09-11",
"sampleCount": 0,
"allDayRestHrAverage": null
},
{
"date": "2026-09-12",
"sampleCount": 0,
"allDayRestHrAverage": null
},
{
"date": "2026-09-13",
"sampleCount": 0,
"allDayRestHrAverage": null
}
],
"allDayRestHrAverage": {
"sampleCount": 9,
"value": 80.0
},
"dailyNightRestHr": [
{
"date": "2026-09-07",
"sampleCount": 3,
"nightRestHrAverage": 80.0
},
{
"date": "2026-09-08",
"sampleCount": 3,
"nightRestHrAverage": 80.0
},
{
"date": "2026-09-09",
"sampleCount": 3,
"nightRestHrAverage": 80.0
},
{
"date": "2026-09-10",
"sampleCount": 3,
"nightRestHrAverage": 80.0
},
{
"date": "2026-09-11",
"sampleCount": 0,
"nightRestHrAverage": null
},
{
"date": "2026-09-12",
"sampleCount": 0,
"nightRestHrAverage": null
},
{
"date": "2026-09-13",
"sampleCount": 0,
"nightRestHrAverage": null
}
],
"aggregationMethod": "daily_median_mean_v1",
"nightRestHrAverage": {
"sampleCount": 0,
"value": null
}
},
"locale": "zh-CN",
"userId": "1",
"viewWindow": "week"
}
```
返回：
```json
{
"insightId": "health_detail_example",
"petId": "7",
"metric": "hr",
"viewWindow": "week",
"period": {
"startDate": "2026-09-07",
"endDate": "2026-09-13",
"timezone": "Asia/Shanghai",
"isCompleted": false,
"elapsedNights": 4,
"validNights": 0
},
"status": "normal",
"severity": "none",
"summary": "本周 Pocky 的静息心率平均 80 次/分，比上周低 3%，5 天都在它平时的范围内。",
"generation": {
"ruleId": "HR_SUPPLIED_JUDGMENT",
"ruleVersion": "health-detail-2026-09-11-r10",
"generatedAt": "2026-10-09T00:00:00Z",
"aiPolished": false
}
}
```
### 3.3 休息 · 昨夜较差且连续 2 晚
请求：
```json
{
"period": {
"endDate": "2026-09-10",
"timezone": "Asia/Shanghai",
"startDate": "2026-09-10",
"isCompleted": false
},
"petId": "7",
"schemaVersion": "health-detail-v3",
"metric": "rest",
"insightContext": {
"mode": "last_night",
"comparison": {
"pageEvaluationBasis": "personal",
"restRatingFactors": [
"duration"
],
"consecutiveUnusualDays": 2
},
"asOf": "2026-09-10T15:00+08:00",
"sourceSnapshot": {
"snapshotState": "versioned",
"snapshotId": "rs_e4d748b697b4e5de994d544c58884b6d",
"asOf": 1788998400000,
"computedAt": 1788998400000,
"sourceCompleteness": "complete",
"sourceWatermarks": {
"posture": {
"cursor": null,
"observedThrough": 1788998400000,
"completeThrough": 1788998400000
},
"wear": {
"cursor": null,
"observedThrough": 1788998400000,
"completeThrough": 1788998400000
},
"step": {
"cursor": null,
"observedThrough": 1788998400000,
"completeThrough": 1788998400000
}
},
"aggregateVersion": "rest-detail-v2-c2"
},
"observedThrough": "2026-09-10T08:00+08:00",
"factVersion": "8aa77bd699e369b955b3c23e7d57b77637d303d2d2257d924fbed1293821ecf7"
},
"petProfile": {
"species": "dog",
"name": "Pocky"
},
"suppliedJudgment": {
"lowRestDays": 1,
"ruleVersion": "sleep-rating-c2-v1",
"rating": "Poor",
"ratedNights": 1,
"baselineSource": "personal",
"direction": null
},
"metrics": {
"night": {
"interruptions": {
"count": 5
},
"nightRest": {
"minutes": 210.0
},
"longestRestBlockMinutes": 80.0,
"nightActivity": {
"minutes": 300.0
},
"endAt": "2026-09-10T08:00+08:00",
"startAt": "2026-09-09T22:00+08:00",
"isCompleted": true,
"wearingMinutes": 600.0
}
},
"locale": "zh-CN",
"userId": "1",
"viewWindow": "day"
}
```
返回：
```json
{
"insightId": "health_detail_example",
"petId": "7",
"metric": "rest",
"viewWindow": "day",
"period": {
"startDate": "2026-09-10",
"endDate": "2026-09-10",
"timezone": "Asia/Shanghai",
"isCompleted": false
},
"status": "attention",
"severity": "low",
"summary": "昨夜，Pocky 休息了 3 小时 30 分钟，中间醒了 5 次。睡得不太好，主要是休息时间比平时短，已经连续 2 晚。回看夜里的环境和作息有没有变化，也给它留些安静休息的时间。",
"generation": {
"ruleId": "REST_SUPPLIED_JUDGMENT",
"ruleVersion": "health-detail-2026-09-11-r10",
"generatedAt": "2026-10-09T00:00:00Z",
"aiPolished": false
}
}
```
### 3.4 活动 · 今天离目标还差
请求：
```json
{
"period": {
"endDate": "2026-09-10",
"timezone": "Asia/Shanghai",
"startDate": "2026-09-10",
"isCompleted": false
},
"petId": "7",
"schemaVersion": "health-detail-v3",
"metric": "activity",
"insightContext": {
"mode": "today_so_far",
"asOf": "2026-09-10T15:00+08:00",
"observedThrough": "2026-09-10T08:00+08:00",
"factVersion": "1f2f0d71af4f4b0be54aa1226ae515b0346e26ed364a93a400c51ae405eecbf8"
},
"petProfile": {
"species": "dog",
"name": "Pocky"
},
"suppliedJudgment": null,
"metrics": {
"activityTime": {
"activityMinutes": 10.0,
"activityMinutesGoal": 60.0
}
},
"locale": "zh-CN",
"userId": "1",
"viewWindow": "day"
}
```
返回：
```json
{
"insightId": "health_detail_example",
"petId": "7",
"metric": "activity",
"viewWindow": "day",
"period": {
"startDate": "2026-09-10",
"endDate": "2026-09-10",
"timezone": "Asia/Shanghai",
"isCompleted": false
},
"status": "observation",
"severity": "none",
"summary": "今天到 08:00，Pocky 已经活动了 10 分钟，离每天 1 小时的目标还差 50 分钟。",
"generation": {
"ruleId": "ACTIVITY_IN_PROGRESS_SUMMARY",
"ruleVersion": "health-detail-2026-09-11-r10",
"generatedAt": "2026-10-09T00:00:00Z",
"aiPolished": false
}
}
```
### 3.5 活动 · 本周 1 天偏少、1 天偏多
请求：
```json
{
"period": {
"endDate": "2026-09-13",
"timezone": "Asia/Shanghai",
"startDate": "2026-09-07",
"isCompleted": false
},
"petId": "7",
"schemaVersion": "health-detail-v3",
"metric": "activity",
"insightContext": {
"mode": "selected_window",
"comparison": {
"unusualLowDays": 1,
"changePercent": 12.3,
"unusualHighDays": 1
},
"asOf": "2026-09-10T15:00+08:00",
"observedThrough": "2026-09-10T08:00+08:00",
"factVersion": "c0736b1a2a89d04f65b69ccace8874a80b529a6c255a350ee4aadd86a24903d9"
},
"petProfile": {
"species": "dog",
"name": "Pocky"
},
"suppliedJudgment": {
"unusualDays": 2,
"judgedDays": 3,
"ruleVersion": "activity-judgment-v1",
"rating": null,
"baselineSource": "personal",
"direction": null
},
"metrics": {
"activityTime": {
"averageDailyActivityMinutes": 30.0,
"dailyActivityMinutes": [
30.0,
30.0,
30.0,
10.0,
null,
null,
null
]
}
},
"locale": "zh-CN",
"userId": "1",
"viewWindow": "week"
}
```
返回：
```json
{
"insightId": "health_detail_example",
"petId": "7",
"metric": "activity",
"viewWindow": "week",
"period": {
"startDate": "2026-09-07",
"endDate": "2026-09-13",
"timezone": "Asia/Shanghai",
"isCompleted": false
},
"status": "attention",
"severity": "low",
"summary": "本周有 1 天 Pocky 的活动比平时少、1 天比平时多，日均 30 分钟，比上周多 12%。留意精神、食欲和外出意愿有没有变化。",
"generation": {
"ruleId": "ACTIVITY_SUPPLIED_JUDGMENT",
"ruleVersion": "health-detail-2026-09-11-r10",
"generatedAt": "2026-10-09T00:00:00Z",
"aiPolished": false
}
}
```
### 3.6 吠叫 · 历史某天叫得明显多
请求：
```json
{
"period": {
"endDate": "2026-09-08",
"timezone": "Asia/Shanghai",
"startDate": "2026-09-08",
"isCompleted": true
},
"petId": "7",
"schemaVersion": "health-detail-v3",
"metric": "bark",
"insightContext": {
"mode": "selected_window",
"comparison": {
"usualUpper": 180.0,
"pageEvaluationBasis": "personal"
},
"asOf": "2026-09-10T15:00+08:00",
"observedThrough": "2026-09-08T08:00+08:00",
"factVersion": "05e78c6791135aee436e826b376945a0b99a792d979fdc65341875d0690cfa65"
},
"petProfile": {
"species": "dog",
"name": "Pocky"
},
"suppliedJudgment": {
"unusualDays": 1,
"judgedDays": 1,
"ruleVersion": "bark-judgment-v1",
"rating": "frequent",
"baselineSource": "personal",
"deteriorating": true,
"direction": 1
},
"metrics": {
"measurementMode": "estimated",
"longestBarkEventDurationSeconds": 60.0,
"barkDurationSeconds": 420.0,
"barkEventCount": 14
},
"locale": "zh-CN",
"userId": "1",
"viewWindow": "day"
}
```
返回：
```json
{
"insightId": "health_detail_example",
"petId": "7",
"metric": "bark",
"viewWindow": "day",
"period": {
"startDate": "2026-09-08",
"endDate": "2026-09-08",
"timezone": "Asia/Shanghai",
"isCompleted": true
},
"status": "attention",
"severity": "low",
"summary": "9月8日，Pocky 叫了约 7 分钟（14 次），明显比它平时多（平时一天不超过约 3 分钟）。回看叫声多的时段，看看是否有访客、声音或作息变化。",
"generation": {
"ruleId": "BARK_SUPPLIED_JUDGMENT",
"ruleVersion": "health-detail-2026-09-11-r10",
"generatedAt": "2026-10-09T00:00:00Z",
"aiPolished": false
}
}
```
## 4. 主服务调用检查清单
- 每个请求都带 `insightContext`；休息与体征带 `suppliedJudgment`（还没评级时 `rating` 为 null、天数为 0）。
- 均值只算已结束的日子；逐日数组与窗口等长、按日历顺序，未来的日子留 null。
- 没有可信来源的字段不发，不填 0、不填占位。
- 发送前跑 `CurrentDetailPreflight`；Gateway 仍做完整校验。
- 改了文案目录（`config/health_detail_copy.yaml`）就看一遍三语对照报告，西语上线前请懂西语的同事审阅。