pet-web/scan-page-api.md

扫码页接口文档

本文聚焦终端用户在扫码页（即通过二维码 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. 返回二维码基础数据 + 绑定的人员或宠物信息

• 成功响应示例：

  {
  "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

• 请求体：

  {
  "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 必填）：

  {
  "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 条

• 响应：

  {
  "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