# 医院预约挂号后端 API

基于 Node.js + Express 的医院预约挂号小程序后端服务，提供 RESTful API 供小程序及外部系统调用。

## 快速开始

```bash
cd server
npm install
npm start           # 默认监听 3000
npm run dev         # Node 18+ 自动重启
```

## 接口总览

| 类别 | Method | Path | 说明 |
|------|--------|------|------|
| 通用 | GET    | /                                          | 健康检查 |
| 医院 | GET    | /api/hospitals                             | 医院列表 |
| 医院 | GET    | /api/hospitals/:id                         | 医院详情 |
| 科室 | GET    | /api/departments                           | 科室列表 |
| 医生 | GET    | /api/doctors?departmentId=                 | 医生列表（可按科室筛选） |
| 医生 | GET    | /api/doctors/:id                           | 医生详情 |
| 预约 | GET    | /api/appointments?phone=                   | 我的预约（按手机号过滤） |
| 预约 | GET    | /api/appointments/:id                      | 预约详情 |
| 预约 | POST   | /api/appointments                          | 创建预约 |
| 预约 | PUT    | /api/appointments/:id/cancel               | 取消预约 |
| **运营** | **GET**  | **/api/config/home**                    | **首页整体配置**（前端直接消费） |
| **运营** | **PUT**  | **/api/config/home**                    | **整体更新首页配置**（Object.assign 合并） |
| **运营** | PUT    | /api/config/home/hero                      | 更新 Hero 区（标题/副标题/背景） |
| **运营** | PUT    | /api/config/home/hero-experts              | 整体替换 Hero 专家头像列表 |
| **运营** | PUT    | /api/config/home/features                  | 整体替换三栏功能卡 |
| **运营** | PUT    | /api/config/home/expert-team               | 整体替换「专家团队」列表 |
| **运营** | PUT    | /api/config/home/info-banner               | 更新「病情提醒」信息条 |
| **运营** | GET    | /api/banners                               | 轮播图列表 |
| **运营** | POST   | /api/banners                               | 新增轮播图 |
| **运营** | PUT    | /api/banners/:id                           | 更新轮播图 |
| **运营** | DELETE | /api/banners/:id                           | 删除轮播图 |
| **运营** | GET    | /api/admin/experts                         | 专家列表（?enabled=true 过滤） |
| **运营** | GET    | /api/admin/experts/:id                     | 专家详情 |
| **运营** | POST   | /api/admin/experts                         | 新增专家 |
| **运营** | PUT    | /api/admin/experts/:id                     | 更新专家 |
| **运营** | DELETE | /api/admin/experts/:id                     | 删除专家 |
| **运营** | POST   | /api/admin/experts/upload                  | 上传头像（base64 / URL） |

## 界面配置说明

> 运营后台通过上面 **「运营」** 分类的接口管理小程序首页的所有可视资源。
> 前端只需 `GET /api/config/home` 即可拿到首页完整数据并渲染，无需修改代码。

### 首页配置结构（GET /api/config/home 返回）

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "navTitle": "苏州肛泰中医院",
    "hero": {
      "title": "为肛肠/胃肠健康护航",
      "subtitle": "三甲名医亲诊",
      "background": "linear-gradient(180deg, #4ea1ff 0%, #2b80f5 60%, #2572e6 100%)"
    },
    "heroExperts": [
      { "id": "he-1", "name": "王秋萍", "title": "主任医师",
        "avatar": "https://...", "label": "原解放军第 454 医院" }
    ],
    "features": [
      { "id": "f-1", "name": "肛肠中心", "sub": "特色专区",
        "icon": "🩺", "iconColor": "linear-gradient(...)", "link": "/pages/..." }
    ],
    "infoBanner": {
      "texts": ["病情变化及时就诊...", "结合辅助检查..."],
      "buttonText": "免费咨询",
      "buttonLink": "/pages/phone-consult/index"
    },
    "expertTeam": [
      { "id": "et-1", "name": "王秋萍", "title": "主任医师",
        "avatar": "https://...", "tag": "特邀",
        "specialty": "特邀胃肠专家 · 40 年临床经验",
        "link": "/pages/hospital/index" }
    ]
  }
}
```

### 字段说明
- `hero.background` 支持 **CSS 渐变字符串** 或 **图片 URL**（URL 时以 background-image 方式渲染）
- `features[].icon` 使用 emoji（如 🩺 🧬 🖥️）作为图标，避免外部图标资源依赖
- `features[].iconColor` 为 CSS 背景值，例如 `linear-gradient(135deg, #5ed3c0 0%, #2dbfa6 100%)`

## 请求示例

### 更新 Hero 标题
```bash
curl -X PUT http://localhost:3000/api/config/home/hero \
  -H "Content-Type: application/json" \
  -d '{"title":"苏州肛泰中医院","subtitle":"三甲名医亲诊"}'
```

### 新增轮播图
```bash
curl -X POST http://localhost:3000/api/banners \
  -H "Content-Type: application/json" \
  -d '{
    "title": "夏季活动",
    "subtitle": "限时优惠",
    "image": "https://your-cdn.com/banner.jpg",
    "link": "/pages/appointment/index",
    "sort": 1
  }'
```

### 新增专家
```bash
curl -X POST http://localhost:3000/api/admin/experts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "张医生",
    "title": "主任医师",
    "avatar": "https://your-cdn.com/avatar.jpg",
    "department": "肛肠科",
    "intro": "40 年临床经验"
  }'
```

### 上传头像
```bash
# 方式 1: 直接传 URL（推荐 - 配合 CDN / OSS）
curl -X POST http://localhost:3000/api/admin/experts/upload \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-cdn.com/new-avatar.jpg"}'

# 方式 2: 传 base64
curl -X POST http://localhost:3000/api/admin/experts/upload \
  -H "Content-Type: application/json" \
  -d '{"base64":"iVBORw0KGgo...","filename":"avatar.png"}'
```

### 创建预约
```bash
curl -X POST http://localhost:3000/api/appointments \
  -H "Content-Type: application/json" \
  -d '{
    "patientName": "张三",
    "patientAge": 35,
    "patientPhone": "13800138000",
    "date": "2026-06-14",
    "departmentName": "肛肠",
    "symptom": "便血 3 天"
  }'
```

## 如何查看/管理预约人信息

> 预约数据保存在内存 `server/src/data.js` 的 `appointments` 数组中（重启服务会清空，生产环境请改为数据库）。
> 当前没有独立的 Web 管理页面，**所有操作都通过 RESTful API 完成**，可使用 Postman / Apifox / curl 调取。

### 1) 查全部预约（管理员视角）
```bash
curl http://localhost:3000/api/appointments
```

### 2) 按手机号查某位用户的预约
```bash
curl "http://localhost:3000/api/appointments?phone=13800138000"
```

### 3) 查预约统计
```bash
curl http://localhost:3000/api/appointments/stats
# 返回 { total, pending, confirmed, completed, cancelled }
```

### 4) 查单条详情
```bash
curl http://localhost:3000/api/appointments/apt-1718300000000
```

### 5) 状态流转（管理动作）
```bash
# 确认预约
curl -X PUT http://localhost:3000/api/appointments/apt-xxx/confirm

# 标记完成
curl -X PUT http://localhost:3000/api/appointments/apt-xxx/complete

# 取消预约
curl -X PUT http://localhost:3000/api/appointments/apt-xxx/cancel
```

### 6) 调整界面图片/资源
首页所有可视资源（背景图、专家头像、功能卡、信息条文案、轮播图、专家信息）都通过下面这些接口管理，**前端代码无需改动**：

```bash
# 替换首页整体配置（合并写入）
curl -X PUT http://localhost:3000/api/config/home \
  -H "Content-Type: application/json" \
  -d '{ "navTitle": "苏州肛泰中医院", "hero": { "title": "..." } }'

# 更新 Hero 区域
curl -X PUT http://localhost:3000/api/config/home/hero \
  -H "Content-Type: application/json" \
  -d '{ "title":"苏州肛泰中医院", "subtitle":"三甲名医亲诊" }'

# 整体替换 Hero 专家头像列表
curl -X PUT http://localhost:3000/api/config/home/hero-experts \
  -H "Content-Type: application/json" \
  -d '{ "heroExperts": [ { "id":"he-1","name":"王秋萍","title":"主任医师","avatar":"https://...","label":"原解放军第 454 医院" } ] }'

# 整体替换三栏功能卡
curl -X PUT http://localhost:3000/api/config/home/features \
  -H "Content-Type: application/json" \
  -d '{ "features": [ { "id":"f-1","name":"肛肠中心","sub":"特色专区","icon":"🩺","iconColor":"linear-gradient(135deg,#5ed3c0,#2dbfa6)","link":"/pages/appointment/index" } ] }'

# 整体替换「专家团队」列表
curl -X PUT http://localhost:3000/api/config/home/expert-team \
  -H "Content-Type: application/json" \
  -d '{ "expertTeam": [ { "id":"et-1","name":"王秋萍","title":"主任医师","avatar":"https://...","tag":"特邀","specialty":"...","link":"/pages/hospital/index" } ] }'

# 更新「病情提醒」信息条
curl -X PUT http://localhost:3000/api/config/home/info-banner \
  -H "Content-Type: application/json" \
  -d '{ "texts":["病情变化及时就诊","结合辅助检查明确诊断"], "buttonText":"免费咨询", "buttonLink":"/pages/phone-consult/index" }'

# 轮播图增删改查
curl http://localhost:3000/api/banners
curl -X POST http://localhost:3000/api/banners -H "Content-Type: application/json" \
  -d '{ "title":"夏季活动","subtitle":"限时优惠","image":"https://cdn.example.com/banner.jpg","link":"/pages/appointment/index","sort":1 }'
curl -X PUT    http://localhost:3000/api/banners/b-1 -H "Content-Type: application/json" -d '{ "title":"新标题" }'
curl -X DELETE http://localhost:3000/api/banners/b-1

# 专家资源增删改查
curl http://localhost:3000/api/admin/experts
curl -X POST http://localhost:3000/api/admin/experts -H "Content-Type: application/json" \
  -d '{ "name":"张医生","title":"主任医师","avatar":"https://...","department":"肛肠科","intro":"40 年临床经验" }'
curl -X PUT    http://localhost:3000/api/admin/experts/he-1 -H "Content-Type: application/json" -d '{ "name":"新名字" }'
curl -X DELETE http://localhost:3000/api/admin/experts/he-1
```

### 7) 上传图片（接 OSS / CDN）
- **推荐：先用 CDN/OSS 拿到 URL，再调用上面的 PUT 接口把 URL 写进去**
- 也可以直接 `POST /api/admin/experts/upload`，传 `{ url }` 或 `{ base64, filename }`，返回图片 URL

## 数据存储

当前为内存存储（重启后数据清空）。生产环境建议：
- 资源类（首页配置 / Banner / 专家）→ MySQL / PostgreSQL
- 文件类（上传图片）→ 阿里 OSS / 腾讯 COS / 自建静态服务

## 与小程序集成

修改小程序 `src/services/request.ts` 中的 `BASE_URL` 为本服务地址：
```ts
const BASE_URL = 'http://localhost:3000';
```
然后把 `src/services/homeConfig.ts` 等 service 中的 mock 返回替换为 `request()` 调用：
```ts
export const fetchHomeConfig = async (): Promise<HomeConfig> => {
  const res = await request<HomeConfig>({ url: '/config/home' });
  return res.data;
};
```
即可完成从 mock 到真实后端的切换。