69 lines
1.9 KiB
Markdown
69 lines
1.9 KiB
Markdown
# 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 |
|
||
|
||
## 统一响应结构
|
||
|
||
```jsonc
|
||
{
|
||
"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](v1/hospital.md) |
|
||
| Department | `/departments` | [department.md](v1/department.md) |
|
||
| Doctor | `/doctors` | [doctor.md](v1/doctor.md) |
|
||
| Appointment | `/appointments` | [appointment.md](v1/appointment.md) |
|
||
| Expert | `/experts` | [expert.md](v1/expert.md) |
|
||
| Banner | `/banners` | [banner.md](v1/banner.md) |
|
||
| Config | `/config` | [config.md](v1/config.md) |
|
||
| AdminAuth | `/admin/auth` | [admin-auth.md](v1/admin-auth.md) |
|
||
| Lead | `/leads` · `/admin/leads` | [lead.md](v1/lead.md) |
|
||
|
||
## 变更日志
|
||
|
||
详见 [CHANGELOG.md](CHANGELOG.md)
|
||
|
||
## 同步机制
|
||
|
||
后端改接口 → 见 [SYNC.md](SYNC.md) 工作流（Phase 5 实施）
|