232 lines
4.5 KiB
Markdown
232 lines
4.5 KiB
Markdown
# 后端 API 文档（当前实现）
|
||
|
||
## 基础信息
|
||
- Base URL：`http://localhost:5010/api`
|
||
- 认证方式：JWT Bearer Token
|
||
- Header 示例：
|
||
```
|
||
Authorization: Bearer <token>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
## 通用响应结构
|
||
- 成功：
|
||
```
|
||
{"status":"success","message":"...","data":{...}}
|
||
```
|
||
- 错误：
|
||
```
|
||
{"status":"error","message":"..."}
|
||
```
|
||
|
||
## 时间与日期格式
|
||
- 日期：`YYYY-MM-DD`
|
||
- 时间：ISO8601（如 `2025-12-20T08:30:00`）
|
||
|
||
## 认证与用户
|
||
### 发送手机号验证码
|
||
- POST `/auth/phone/code`
|
||
- 请求字段：
|
||
- `phone` string 手机号
|
||
- 成功返回：`data.code`（仅开发模式下返回）
|
||
|
||
### 手机号验证码登录
|
||
- POST `/auth/phone/login`
|
||
- 请求字段：
|
||
- `phone` string
|
||
- `code` string
|
||
- 成功返回：
|
||
- `data.token` string
|
||
- `data.user` object
|
||
- `data.need_set_password` boolean
|
||
|
||
### 手机号密码登录
|
||
- POST `/auth/password/login`
|
||
- 请求字段：
|
||
- `phone` string
|
||
- `password` string（8-16 位，需包含字母与数字）
|
||
- 成功返回：
|
||
- `data.token` string
|
||
- `data.user` object
|
||
- `data.need_set_password` boolean
|
||
|
||
### 设置密码
|
||
- POST `/auth/password/setup`
|
||
- 需要登录
|
||
- 请求字段：
|
||
- `password` string
|
||
- 成功返回：`data.user`
|
||
|
||
### 更新昵称
|
||
- PUT `/auth/profile`
|
||
- 需要登录
|
||
- 请求字段：
|
||
- `name` string
|
||
- 成功返回：`data.user`
|
||
|
||
### 微信登录（可选）
|
||
- POST `/auth/wechat`
|
||
- 请求字段：
|
||
- `code` string
|
||
|
||
## 宝宝管理
|
||
### 列表
|
||
- GET `/babies`
|
||
- 需要登录
|
||
|
||
### 创建
|
||
- POST `/babies`
|
||
- 需要登录
|
||
- 请求字段：
|
||
- `name` string
|
||
- `gender` string（仅支持“男”“女”）
|
||
- `birthday` string（YYYY-MM-DD）
|
||
- `dueDate` string（可选）
|
||
- `gestationalWeeks` number（可选）
|
||
- `note` string（可选）
|
||
|
||
### 详情
|
||
- GET `/babies/{id}`
|
||
- 需要登录
|
||
|
||
### 更新
|
||
- PUT `/babies/{id}`
|
||
- 需要登录
|
||
- 字段与创建一致，均为可选更新
|
||
|
||
### 删除
|
||
- DELETE `/babies/{id}`
|
||
- 需要登录
|
||
|
||
## 成长记录
|
||
### 列表
|
||
- GET `/babies/{babyId}/growth`
|
||
- 需要登录
|
||
- Query：
|
||
- `metric` string（可选）
|
||
- `start` string ISO8601（可选）
|
||
- `end` string ISO8601（可选）
|
||
|
||
### 创建
|
||
- POST `/babies/{babyId}/growth`
|
||
- 需要登录
|
||
- 请求字段：
|
||
- `metric` string
|
||
- `value` number
|
||
- `unit` string
|
||
- `recordedAt` string ISO8601（可选）
|
||
- `note` string（可选）
|
||
|
||
### 更新
|
||
- PUT `/growth/{id}`
|
||
- 需要登录
|
||
- 字段与创建一致，均为可选更新
|
||
|
||
### 删除
|
||
- DELETE `/growth/{id}`
|
||
- 需要登录
|
||
|
||
## 预约管理
|
||
### 列表
|
||
- GET `/appointments`
|
||
- 需要登录
|
||
- Query：
|
||
- `status` string（可选）
|
||
|
||
### 创建
|
||
- POST `/appointments`
|
||
- 需要登录
|
||
- 请求字段：
|
||
- `clinic` string
|
||
- `department` string
|
||
- `scheduledAt` string ISO8601
|
||
- `remindAt` string ISO8601（可选）
|
||
- `status` string（可选，默认 pending）
|
||
- `note` string（可选）
|
||
- `babyId` number（可选）
|
||
|
||
### 更新
|
||
- PUT `/appointments/{id}`
|
||
- 需要登录
|
||
- 字段与创建一致，均为可选更新
|
||
|
||
### 删除
|
||
- DELETE `/appointments/{id}`
|
||
- 需要登录
|
||
|
||
### 更新状态
|
||
- PATCH `/appointments/{id}/status`
|
||
- 需要登录
|
||
- 请求字段：
|
||
- `status` string
|
||
|
||
## 内容管理（只读）
|
||
### 视频列表
|
||
- GET `/content/videos`
|
||
- 需要登录
|
||
- Query：
|
||
- `page` number
|
||
- `per_page` number
|
||
- `search` string（标题/简介）
|
||
- `category` string
|
||
|
||
### 视频详情
|
||
- GET `/content/videos/{id}`
|
||
- 需要登录
|
||
- 说明：会增加 `views` 计数
|
||
|
||
### 文章列表
|
||
- GET `/content/articles`
|
||
- 需要登录
|
||
- Query：
|
||
- `page` number
|
||
- `per_page` number
|
||
- `search` string（标题/正文）
|
||
- `category` string
|
||
|
||
### 文章详情
|
||
- GET `/content/articles/{id}`
|
||
- 需要登录
|
||
|
||
## 聊天与 AI
|
||
### 发送消息
|
||
- POST `/chat/send`
|
||
- 需要登录
|
||
- 请求字段：
|
||
- `content` string
|
||
- `babyId` number（可选）
|
||
- `messageId` string（可选）
|
||
- `history` array（可选）
|
||
- `metadata` object（可选）
|
||
- `params` object（可选）
|
||
|
||
### 历史记录
|
||
- GET `/chat/history`
|
||
- 需要登录
|
||
- Query：
|
||
- `page` number
|
||
- `per_page` number
|
||
- `babyId` number（可选）
|
||
|
||
### 清空历史
|
||
- DELETE `/chat/history`
|
||
- 需要登录
|
||
- Query：
|
||
- `babyId` number（可选）
|
||
|
||
## 健康检查
|
||
- GET `/health`
|
||
- GET `/`
|
||
|
||
## 常见错误码
|
||
- 400 参数错误
|
||
- 401 认证失败或 token 失效
|
||
- 404 资源不存在
|
||
- 500 服务端异常
|
||
- 502 AI 服务异常（`/chat/send`）
|
||
|
||
## 管理端缺口说明
|
||
- 当前所有业务接口均以“用户本人”为作用域。
|
||
- 需要管理端能力时，建议新增 `/api/admin/*` 路由与管理员鉴权。
|
||
- 内容模块目前无写接口，后台管理若需编辑视频/文章需补齐写接口。
|