jackyu66gitandCursor
2fb1dfee14
Archive the differentiated YuXinGu product docs, AI engineering system, design contract, and Go/Vue scaffold. Next execution prioritizes Cece-parity over early innovation (see .ai/product/STRATEGY.md). Co-authored-by: Cursor <cursoragent@cursor.com>
61 lines
1.0 KiB
Markdown
61 lines
1.0 KiB
Markdown
# 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`。
|