ipad/API.md

# API文档

URL 以及 接口结构仅供参考。无需完全对应

## 接口定义（JSON 请求 / 响应）

### 1.1 发送验证码 `POST /api/v1/auth/send-code`
- `传入 手机号`
- **请求**
```json
{
  "phone": "18888888888"
}
```
- **响应**
```json
{
  "code": 200,
  "message": "验证码已发送",
  "data": {
    "expiresIn": 300
  }
}
```

### 1.2 登录 `POST /api/v1/auth/login`
- `传入 手机号 验证码`
- **请求**
```json
{
  "phone": "18888888888",
  "code": "123456"
}
```
- **响应**
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "jwt-token",
    "user": {
      "id": "user_001",
      "name": "操作员",
      "role": "admin",
      "permissions": [
        "view_revenue",
        "view_exam",
        "manage_meal_status",
        "edit_notes"
      ]
    }
  }
}
```

### 2.1 获取今日体检统计 `GET /api/v1/home/daily-stats`
- `获取：今日预约人数 已签到人数 在检人数 已打印导检单数量 已完成人数 已用餐人数`
- **响应**
```json
{
  "code": 200,
  "data": {
    "dailyAppointment": 80,
    "signedIn": 60,
    "inExam": 25,
    "guidePrinted": 40,
    "completed": 30,
    "meal": 15
  }
}
```

### 3.1 获取营收统计（管理员）`GET /api/v1/home/revenue-stats`
- `获取：体检收入 加项收入 整体收入 目标收入`
- **响应**
```json
{
  "code": 200,
  "data": {
    "examRevenue": 86000,
    "addonRevenue": 12400,
    "totalRevenue": 98400,
    "targetRevenue": 120000,
    "gap": 21600
  }
}
```

### 4.1 获取 B1 数据 `GET /api/v1/home/b1-dashboard`
- `获取：当前客户总数 待检人数 在检人数`
- `列表：科室 医生 已检人数 已检部位数 总时长 平均时长`
- **响应**
```json
{
  "code": 200,
  "data": {
    "summary": {
      "totalClients": 33,
      "waiting": 10,
      "inExam": 10
    },
    "rows": [
      {
        "department": "B超1",
        "doctor": "张医生",
        "examinedCount": 6,
        "examinedParts": 18,
        "totalDuration": 90,
        "avgDuration": 15,
        "inExam": 2,
        "waiting": 2
      }
    ]
  }
}
```

### 5.1 获取北3数据 `GET /api/v1/home/north3-dashboard`
- `获取：今日家医生数 分配客户数 面诊数`
- `列表：家医 面诊率 分配客户数 面诊数`
- **响应**
```json
{
  "code": 200,
  "data": {
    "summary": {
      "totalDoctors": 3,
      "totalAssigned": 45,
      "consultations": 26
    },
    "rows": [
      {
        "doctor": "刘医生",
        "assignmentCount": 15,
        "consultations": 9,
        "consultRate": 0.6
      }
    ]
  }
}
```

### 7.1 获取体检客户列表 `GET /api/v1/exam/clients`
- `条件：时间段，如 8:00 ~ 12:00 到 12:00 ~ 17:00（或者上午0下午1）`
- `条件：用户等级，如高客 普客 散客 团客`
- `条件：登记情况，如已登记 未登记`
- `获取：套餐名称 渠道 状态 签到时间（耗时起始时间） 是否已签到 已加项数量 是否打印体检单`
- **查询参数**
```json
{
  "timeRange": "08:00-12:00",
  "level": "高客",
  "customerType": "团客",
  "signStatus": "已登记",
  "search": "张",
  "page": 1,
  "pageSize": 20
}
```
- **响应**
```json
{
  "code": 200,
  "data": {
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "list": [
      {
        "id": "A001",
        "name": "张伟",
        "packageName": "高端入职体检套餐",
        "channel": "团体客户",
        "status": "体检中",
        "signedIn": true,
        "signTime": "2025-11-18 08:55",
        "elapsed": "00:45",
        "addonCount": 2,
        "guidePrinted": true,
        "timeSlot": "上午",
        "level": "VIP",
        "vipType": "高客",
        "customerType": "团客"
      }
    ]
  }
}
```

### 8.1 获取体检客户详情 `GET /api/v1/exam/clients/{clientId}`
- `基础信息：姓名 身份证 手机号 性别 年龄 客户级别 渠道 婚姻 家医 团标签`
- `体检进度：已查项目 未查项目 弃检项目 延期项目`
- `历史记录`
- `加项内容`
- `该次体检是否上传身份证（或已上传的身份证信息）`
- `该次体检是否已签名（或已上传的签名图片）`
- `体检知情同意书`
- `可选的加项列表（可以用字段表明已经支付后的加项）`
- `导检单PDF`
- **响应**
```json
{
  "code": 200,
  "data": {
    "id": "A001",
    "basicInfo": {
      "name": "张伟",
      "idCard": "4401********1234",
      "mobile": "137****9988",
      "gender": "男",
      "age": 35,
      "level": "VIP",
      "channel": "团检",
      "maritalStatus": "未婚",
      "familyDoctor": "李医生",
      "groupTag": "团检"
    },
    "progress": {
      "checkedItems": ["签到", "更衣"],
      "pendingItems": ["家医面诊"],
      "abandonedItems": [],
      "deferredItems": []
    },
    "history": [],
    "addonSummary": [
      {
        "name": "肿瘤标志物筛查",
        "paid": true,
        "tags": [
          {
            "title": "热门",
            "type": 1,
          },
          {
            "title": "肺结节筛查",
            "type": 2,
          },
          {
            "title": "医生推荐",
            "type": 3,
          },
          {
            "title": "渠道八折",
            "type": 4,
          }
        ],
        "originalPrice": "320.00",
        "currentPrice": "240.00"
      }
    ],
    "idCardUploaded": true,
    "idCardImages": {
      "front": "https://...",
      "back": "https://..."
    },
    "consentSigned": true,
    "consentImage": "https://...",
    "consentDocumentUrl": "https://...",
    "addonOptions": [
      {
        "id": "addon_001",
        "name": "甲状腺彩超",
        "price": 300,
        "paid": false
      }
    ],
    "guidePdfUrl": "https://example.com/guides/A001.pdf"
  }
}
```

### 8.2 上传身份证 `POST /api/v1/exam/clients/{clientId}/id-card`
- `具体用户上传身份证正面、反面`
- **请求**
```json
{
  "frontImage": "base64-front",
  "backImage": "base64-back"
}
```
- **响应**
```json
{
  "code": 200,
  "message": "身份证上传成功"
}
```

### 8.5 上传体检同意书签名 `POST /api/v1/exam/clients/{clientId}/consent`
- `上传体检同意书签名图片`
- **请求**
```json
{
  "signatureImage": "base64-signature",
  "documentVersion": "v1.0"
}
```
- **响应**
```json
{
  "code": 200,
  "message": "签名已保存"
}
```

### 8.6 生成加项订单 `POST /api/v1/exam/clients/{clientId}/addon-orders`
- `选择加项内容后获取订单号以及支付二维码`
- **请求**
```json
{
  "addonIds": ["addon_001", "addon_002"],
  "paymentMethod": "wechat_qr", // 如果是聚合码则取消
}
```
- **响应**
```json
{
  "code": 200,
  "data": {
    "orderId": "order_001",
    "amount": 800,
    "qrcodeUrl": "https://example.com/pay/order_001.png",
    "expiresIn": 300
  }
}
```

### 8.7 查询订单支付状态 `GET /api/v1/payments/{orderId}`
- `根据订单号查询 是否已经支付成功（HTTP或SSE）`
- **响应**
```json
{
  "code": 200,
  "data": {
    "orderId": "order_001",
    "status": "paid",
    "paidAt": "2025-11-18T09:20:00+08:00"
  }
}
```
- **SSE（可选）** `GET /api/v1/payments/{orderId}/events`
  - 服务端推送字段：`event`=`status`, `data`=`{"status":"paid"}`。

### 9.0 获取客服咨询信息 `GET /api/v1/support/info`
- `获取 标题 内容 图片`
- **响应**
```json
{
  "code": 200,
  "data": {
    "title": "客服咨询 · 圆圆客服台卡",
    "content": "一站式健康服务说明",
    "imageUrl": "https://example.com/assets/support-card.png"
  }
}
```

### 9.1 获取用餐状态列表 `GET /api/v1/meals`
- `条件 全部 已用餐 未用餐 姓名 体检号`
- **查询参数**
```json
{
  "status": "all",
  "clientName": "张",
  "clientId": "A001"
}
```
- **响应**
```json
{
  "code": 200,
  "data": [
    {
      "id": "A001",
      "name": "张伟",
      "status": "体检中",
      "mealStatus": "done",
      "mealTime": "2025-11-18 09:30"
    }
  ]
}
```

### 9.2 更新用餐状态 `POST /api/v1/meals/{clientId}`
- `更新指定用户用餐状态`
- **请求**
```json
{
  "mealStatus": "done"
}
```
- **响应**
```json
{
  "code": 200,
  "message": "用餐状态已更新"
}
```

### 9.3 获取太平 VIP 认证二维码 `GET /api/v1/support/taiping-vip`
- `获取 标题 内容 图片`
- **响应**
```json
{
  "code": 200,
  "data": {
    "title": "太平 VIP 认证",
    "content": "扫描二维码完成认证",
    "imageUrl": "https://example.com/assets/taiping-vip.png"
  }
}
```

### 10.1 获取报告寄送登记二维码 `GET /api/v1/support/report-delivery`
- `获取 客服名称 图片`
- **响应**
```json
{
  "code": 200,
  "data": {
    "serviceName": "圆圆客服",
    "imageUrl": "https://example.com/assets/delivery-qrcode.png"
  }
}
```

### 10.2 报告寄送登记 `POST /api/v1/support/report-delivery`
- `传入 收件人 手机号 地址`
- **请求**
```json
{
  "recipient": "李四",
  "phone": "13800000000",
  "address": "上海市浦东新区世纪大道100号10楼",
  "remark": "加急寄送"
}
```
- **响应**
```json
{
  "code": 200,
  "message": "寄送信息已保存",
  "data": {
    "deliveryId": "delivery_001"
  }
}
```

### 10.3 保存操作员备注 `POST /api/v1/notes`
- `保存操作员备注内容`
- **请求**
```json
{
  "operatorId": "user_001",
  "content": "客户希望下午完成全部项目"
}
```
- **响应**
```json
{
  "code": 200,
  "message": "备注已保存"
}
```

### 10.4 获取操作员备注 `GET /api/v1/notes`
- `获取操作员备注内容`
- **响应**
```json
{
  "code": 200,
  "data": [
    {
      "operatorId": "user_001",
      "content": "客户希望下午完成全部项目",
      "createdAt": "2025-11-18 10:00:00"
    }
  ]
}
```