# 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 实施）