# 后端 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/*` 路由与管理员鉴权。
- 内容模块目前无写接口，后台管理若需编辑视频/文章需补齐写接口。