init

2026-02-10 22:06:40 +08:00
commit 11a2b8f9d1
3 changed files with 351 additions and 0 deletions
--- a/docs/API_REFERENCE.md
+++ b/docs/API_REFERENCE.md
@@ -0,0 +1,231 @@
+# 后端 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/*` 路由与管理员鉴权。
+- 内容模块目前无写接口，后台管理若需编辑视频/文章需补齐写接口。