init

2026-07-05 14:43:34 +08:00
commit 17a8027b20
277 changed files with 63794 additions and 0 deletions
@@ -0,0 +1,68 @@
+# 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 实施）