# 03 REST API 规范

## URL

- 前缀：`/api/v1`。
- 资源名词复数、层级清晰：

```
GET    /api/v1/users
GET    /api/v1/users/:id
POST   /api/v1/users
PUT    /api/v1/users/:id
DELETE /api/v1/users/:id
```

动作型可用子路径：`POST /api/v1/reports/decode`。

## 统一响应

成功：

```json
{ "code": 0, "message": "success", "data": {} }
```

失败（HTTP 可用 4xx/5xx，body 仍带业务码）：

```json
{ "code": 10001, "message": "user not found" }
```

## 错误码段（约定）

| 段 | 含义 |
|---|---|
| 0 | 成功 |
| 1xxxx | 通用 / 参数 / 认证 |
| 2xxxx | 用户与档案 |
| 3xxxx | 报告与量表 |
| 4xxxx | 订单与会员 |
| 5xxxx | AI / 陪伴 |

具体码表维护在 `apps/docs/api-errors.md`（随功能追加）。

## 分页

```
GET /api/v1/scales?page=1&page_size=20
```

`data` 建议：

```json
{ "list": [], "total": 0, "page": 1, "page_size": 20 }
```

## 版本与文档

- 破坏性变更升 `/api/v2` 或并行兼容期。
- 同步更新 `proto/openapi.yaml`。