---
url: /docs/api-docs/v1/admin/interpret.md
---
# interpret — 解读报告（5 action）

> 前缀：`/api/v1/admin/interpret/`
> 权限：`INTERPRET_READ`（health-data / body-composition / report-list / report-detail）· `INTERPRET_WRITE`（write）
> 角色：**三角色共享**（super / operator / it 全 ✅ — P3 矩阵修正：跨角色业务协作）
> 代码：`src/app/admin/interface/api/interpret_mgmt.py` + `application/usecase/interpret_mgmt.py`

## 3.8.1 health-data —— 用户健康数据

`GET /api/v1/admin/interpret/health-data/{user_id}` · 权限 `INTERPRET_READ`

**响应 data**：

| 字段 | 类型 | 说明 |
|---|---|---|
| `user_id` | string | 用户 |
| `measurements` | array | 测量记录 `[{type, value, unit, measured_at}]` |

**错误码**：`40201602` 健康数据缺失（INTERPRET\_HEALTH\_DATA\_MISSING — 数据为空时数据源抛出）。

## 3.8.2 body-composition —— 用户体成分

`GET /api/v1/admin/interpret/body-composition/{user_id}` · 权限 `INTERPRET_READ`

**响应 data**：`{ "user_id": ..., "body_composition": { ... } }`

**错误码**：`40201603` 体测数据缺失。

## 3.8.3 report-list —— 解读报告列表

`GET /api/v1/admin/interpret/report-list` · 权限 `INTERPRET_READ`

**Query 参数**：

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `page` | int | ⬜ | 1 | ≥1 |
| `page_size` | int | ⬜ | 20 | 1~100 |
| `status` | string | ⬜ | — | `pending` | `ai_generated` | `interpreted` |
| `user_id` | string | ⬜ | — | 按用户过滤 |

**响应 data**：`{ total, page, page_size, items: [ReportSummary] }`

`ReportSummary` 字段：`{id, user_id, report_type, status, has_ai_interpretation, interpreted_at, created_at}`

**错误码**：`40201001` page/page\_size < 1。

## 3.8.4 report-detail —— 报告详情

`GET /api/v1/admin/interpret/report-detail/{report_id}` · 权限 `INTERPRET_READ`

**响应 data**：

| 字段 | 类型 | 说明 |
|---|---|---|
| `report` | object | 全字段 |
| `health_data` | array | null | 健康数据（数据缺失时 null） |
| `body_composition` | object | null | 体成分（数据缺失时 null） |
| `ai_interpretation` | string | null | AI 初稿 |

**错误码**：`40201601`（404）报告不存在 · `40201602` 健康数据缺失 · `40201603` 体成分数据缺失（缺失分支抛错；字段类型保持 nullable 兼容存量）。

## 3.8.5 write —— 撰写解读（人工）

`POST /api/v1/admin/interpret/write` · 权限 `INTERPRET_WRITE`

**请求 body**：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `report_id` | string | ✅ | 目标报告（`pending` / `ai_generated` 状态） |
| `content` | string | ✅ | 解读正文 |
| `references` | string\[] | null | ⬜ | 引用条目 |

**响应 data**：`{ "success": true, "interpretation_id": "<id>" }`

**错误码**：

| code | 场景 |
|---|---|
| `40201601` | 报告不存在（404） |
| `40201604` | 已被审核（重复操作） |
| `40201001` | content 缺失 / 参数非法 |

**状态机**：`pending` / `ai_generated` →（write）→ `interpreted` + audit 闭环。

***

**本域错误码汇总**：`40201601`-`40201604`（§6.8）。通用失败见 [admin 总览](/api-docs/v1/admin/)。