# 扫码页接口文档

本文聚焦终端用户在扫码页（即通过二维码 URL 访问的 H5或小程序页面）所需的开放接口，方便前端快速集成展示、补充信息及安全校验。

## 1. 基础信息
- **根地址**：`/api`
- **二维码相关前缀**：`/api/qr`
- **人员/宠物信息前缀**：`/api/person`、`/api/pet`
- **扫码记录前缀**：`/api/scan`
- **认证**：扫码页接口均无需 JWT；带有 `hasRole(UserRole.ADMIN)` 的后台接口未在本文档描述
- **请求头**：`Content-Type: application/json`
- **二维码类型**：`person`（人员）、`pet`（宠物/物品），来自 `QrType` 枚举

---

## 2. 推荐调用流程
1. 前端解析二维码中的 `qrCode` 参数
2. 调用【获取二维码信息】接口，展示二维码基本信息和绑定资料
3. 若需补充位置或地址，再调用【补充扫描记录】接口
4. 若用户需维护数据，先调【验证维护码】确认身份，再调用对应的更新接口
5. 可选：调用【最近扫描记录】展示访问信息

---

## 3. 接口清单概览

| 接口 | 方法 | 路径 | 作用 | 说明 |
| --- | --- | --- | --- | --- |
| 获取二维码信息 | GET | `/api/qr/info` | 查询二维码及绑定数据，并自动记录一次扫描 | 最常用；返回 `qrType` 与 `info` |
| 验证维护码 | POST | `/api/qr/verify` | 校验用户输入的维护码 | 通过后才允许调用更新接口 |
| 补充扫描记录 | POST | `/api/scan/create` | 保存带经纬度/地址的扫描记录 | 可追加精确定位 |
| 最近扫描记录 | GET | `/api/scan/recent` | 查询某二维码最近 N 次扫描 | 可用于展示访客列表 |
| 获取人员信息 | GET | `/api/person/get` | 直接返回人员信息实体 | 作为 `qr/info` 的兜底 |
| 获取宠物信息 | GET | `/api/pet/get` | 直接返回宠物/物品信息实体 | 作为 `qr/info` 的兜底 |

---

## 4. 接口详情

### 4.1 获取二维码信息
- **方法/路径**：`GET /api/qr/info`
- **查询参数**：
  - `qrCode` *(string, required)*：二维码编号
- **行为**：
  1. 校验 `qrCode`，缺失返回 400
  2. 自动记录一次扫描（记录请求 IP、User-Agent）
  3. 返回二维码基础数据 + 绑定的人员或宠物信息
- **成功响应示例**：
```json
{
  "id": 12,
  "qrCode": "QR2025ABC...",
  "qrType": "person",
  "isActivated": true,
  "scanCount": 42,
  "info": {
    "id": 8,
    "qrCodeId": 12,
    "photoUrl": "https://...",
    "name": "张三",
    "gender": "male",
    "phone": "13800000000",
    "specialNote": "有心脏病",
    "emergencyContactName": "李四",
    "emergencyContactPhone": "13900000000",
    "remark": "..."
  }
}
```
- **错误响应**：
  - 400 `{ "message": "请提供二维码参数" }`
  - 500 `{ "message": "获取信息失败" }`

### 4.2 验证维护码
- **方法/路径**：`POST /api/qr/verify`
- **请求体**：
```json
{
  "qrCode": "QR2025ABC...",
  "maintenanceCode": "AB12CD34"
}
```
- **说明**：
  - 维护码与二维码生成时随机分配，服务端使用 bcrypt 存储；请通过 HTTPS 传输
  - 校验通过返回 `{ "message": "验证成功", "valid": true }`
  - 维护码错误：401 `{ "message": "维护码错误" }`
  - 其它异常：500 `{ "message": "验证失败" }`
- **后续操作**：前端可在成功后提交人员或宠物信息更新：
  - `PUT /api/person/update`
  - `PUT /api/pet/update`
  - 两者请求体均需携带 `qrCode` 与 `maintenanceCode`，字段约束参考对应 DTO

### 4.3 补充扫描记录
- **方法/路径**：`POST /api/scan/create`
- **请求体**（各字段均为可选，除 `qrCode` 必填）：
```json
{
  "qrCode": "QR2025ABC...",
  "latitude": 31.2304,
  "longitude": 121.4737,
  "address": "上海市黄浦区XX路XXX号",
  "ipAddress": "手动覆盖 IP",
  "userAgent": "自定义 UA"
}
```
- **处理逻辑**：
  - 若未提供 `ipAddress` / `userAgent`，自动回退为请求源信息
  - 保存记录时会同步递增 `scanCount`
- **响应**：201 `{ "message": "扫描记录创建成功", "data": { ...scanRecord } }`
- **常见错误**：
  - 400 `{ "message": "创建失败" }`（参数校验不通过或二维码不存在）

### 4.4 最近扫描记录
- **方法/路径**：`GET /api/scan/recent`
- **查询参数**：
  - `qrCode` *(string, required)*
  - `limit` *(number, optional, default=10)*：返回最近 N 条
- **响应**：
```json
{
  "qrCode": "QR2025ABC...",
  "count": 5,
  "records": [
    {
      "id": 1001,
      "scanTime": "2025-11-28T02:12:11.123Z",
      "latitude": 31.2304,
      "longitude": 121.4737,
      "address": "上海市...",
      "ipAddress": "1.2.3.4",
      "userAgent": "Mozilla/5.0 ..."
    }
  ]
}
```
- **错误**：缺参返回 400，查询异常返回 500

### 4.5 获取人员/宠物信息（兜底）
- `GET /api/person/get?qrCode=...`
- `GET /api/pet/get?qrCode=...`
- **用途**：当需要根据 `qrType` 分别渲染或在 `/api/qr/info` 出错时兜底查询
- **响应**：直接返回对应实体；未录入信息则返回 404 `{ "message": "人员信息不存在" }` / `{ "message": "宠物/物品信息不存在" }`

---

## 5. 响应码对照

| 状态码 | 说明 | 常见场景 |
| --- | --- | --- |
| 200 | OK | 查询或验证成功 |
| 201 | Created | 扫描记录创建成功 |
| 400 | Bad Request | 缺失参数 / DTO 校验失败 |
| 401 | Unauthorized | 维护码错误 |
| 404 | Not Found | 未配置人员/宠物资料 |
| 500 | Internal Server Error | 未知异常 |

---

## 6. 开发提示
- `qrCode` 大小写敏感，需与生成规则一致（`QR` 前缀 + 时间戳 + 随机串）
- 维护码为 8 位字母数字组合，用户侧应妥善保存并通过 HTTPS 传输
- DTO 对经纬度、手机号、邮箱等均有限制，前端提交前应做基础校验
- 后续如需扩展扫码页能力（例如展示更多统计），可追加后台接口或在 Swagger（`/documentation`, dev 环境）中查阅其它 API