API 接口文档
在线浏览：http://124.221.67.199:3000/api/docs/ OpenAPI JSON：http://124.221.67.199:3000/api/docs.json
基础约定
| 项 | 约定 |
|---|---|
| 基地址 | http://<host>:3000/api/v1 |
| 版本 | v1（Phase 1 起所有接口） |
| 请求方法 | GET / POST / PUT / DELETE |
| 请求格式 | Content-Type: application/json |
| 字符集 | UTF-8 |
统一响应结构
{
"code": 0, // 0 = 成功，其他 = 业务错误
"message": "ok", // 业务消息
"data": { ... } // 业务数据
}
状态码
| 状态码 | 含义 | 出现场景 |
|---|---|---|
| 200 | 成功 | 接口正常返回 |
| 400 | 参数错误 | 缺字段、格式不对、校验失败 |
| 401 | 鉴权失败 | token 缺失/失效/密码错误 |
| 404 | 资源不存在 | 找不到 ID 对应的资源 |
| 500 | 服务器内部错误 | 异常抛出 |
业务错误统一用 HTTP 200 +
code !== 0表示，仅在资源未找到时使用 404。
鉴权
管理后台接口需要 JWT Bearer Token：
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxxxx
通过 POST /api/v1/admin/auth/login 获得 token。
业务模块
| 模块 | 路径前缀 | 文档 |
|---|---|---|
| Hospital | /hospitals |
hospital.md |
| Department | /departments |
department.md |
| Doctor | /doctors |
doctor.md |
| Appointment | /appointments |
appointment.md |
| Expert | /experts |
expert.md |
| Banner | /banners |
banner.md |
| Config | /config |
config.md |
| AdminAuth | /admin/auth |
admin-auth.md |
| Lead | /leads · /admin/leads |
lead.md |
变更日志
详见 CHANGELOG.md
同步机制
后端改接口 → 见 SYNC.md 工作流（Phase 5 实施）