PINF_MANAGEMENT/docs/API_REFERENCE.md

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