267 lines
11 KiB
Markdown
267 lines
11 KiB
Markdown
# API 文档（领取与兑奖流程）
|
||
|
||
本文件整理新婚送福活动前端页面所用接口，包括领取流程与兑奖页面改造所需的现有接口与拟新增接口。文档基于当前代码库（com-marriage-client 与 com-admin-client）。
|
||
|
||
## 基本信息
|
||
- 服务与端口：
|
||
- 领取端（com-marriage-client）：`http://localhost:8200`，应用名 `nxfc-marriage-client`
|
||
- 后台端（com-admin-client）：`http://localhost:8000`，应用名 `nxfc-admin-client`
|
||
- 认证：
|
||
- 站点登录与短信验证接口位于 `com-marriage-client` 的 `/marriage/common` 路径下。
|
||
- 后台活动管理接口位于 `com-admin-client` 的 `/admin/activity` 路径下（通常用于管理端）。
|
||
|
||
---
|
||
|
||
## 领取流程页面
|
||
|
||
### 1）活动介绍页
|
||
用于展示当前活动的名称、时间和面额信息。
|
||
|
||
- 拟新增（面向领取端，便于前端直接获取展示数据）
|
||
- 方法：`GET`
|
||
- 路径：`/marriage/activity/current`
|
||
- 入参：无
|
||
- 出参（示例）：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "",
|
||
"data": {
|
||
"activityName": "新婚送福",
|
||
"activityStartTime": "2025-09-15 00:00:00",
|
||
"activityEndTime": "2025-10-31 23:59:59",
|
||
"money": 6000,
|
||
"status": 1
|
||
}
|
||
}
|
||
```
|
||
- 备注：如暂未在领取端提供该接口，可临时通过后台端获取列表接口获得活动信息：
|
||
- 方法：`POST`
|
||
- 路径：`/admin/activity/list`
|
||
- 入参：无
|
||
- 出参：`ResultObject` 包含活动集合，字段参考 `MarriageActivity`。
|
||
|
||
### 2）OCR识别结婚证，自动带出信息，领取二维码页
|
||
为避免用户手动输入，新增 OCR 流程：上传结婚证图片并识别证件信息，前端使用识别结果自动填充表单，再进行短信校验与领取。
|
||
|
||
- OCR 上传图片 [新增]
|
||
- 方法：`POST`
|
||
- 路径：`/marriage/ocr/upload`
|
||
- 入参：`multipart/form-data`，字段：`file`（结婚证图片）
|
||
- 出参（示例）：
|
||
```json
|
||
{ "code": 200, "msg": "", "data": { "uploadId": "ab12cd34..." } }
|
||
```
|
||
- 备注：服务端将图片内容以 Base64 缓存于 Redis（键：`OCR_UPLOAD-{uploadId}`，有效期 10 分钟），不落盘文件。
|
||
|
||
- 发送短信验证码
|
||
- 方法：`POST`
|
||
- 路径：`/marriage/common/sms`
|
||
- 入参：`CommSmsDTO`
|
||
- `mobile`：手机号（必填）
|
||
- `type`：验证码类型，`0`=登录；`1`=兑换领取；`2`=OCR识别（本页使用 `2`） [扩展]
|
||
- 出参（示例）：
|
||
```json
|
||
{ "code": 200, "msg": "", "data": null }
|
||
```
|
||
- 备注：当前实现对 `type=1` 的校验逻辑使用了 `code` 字段比对，可能与期望不一致（代码中以 `MarriageCode::getCode == mobile` 判断重复）。如需严格校验手机号唯一性，可调整实现。
|
||
|
||
- OCR 识别并返回证件信息（供前端自动填充） [新增]
|
||
- 方法：`POST`
|
||
- 路径：`/marriage/ocr/parse`
|
||
- 入参：`OcrParseDTO`
|
||
- `mobile`：手机号（必填）
|
||
- `smsCode`：短信验证码（必填，取自上方 `/sms`，`type=2`）
|
||
- `uploadId`：上传接口返回的标识（必填）
|
||
- 出参（示例）：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "",
|
||
"data": {
|
||
"raw": "<百度OCR原始JSON字符串>",
|
||
"words": ["宁夏回族自治区婚姻登记证", "字号6403812025001056", "男方张三", "女方李四", "登记日期2025-10-01"],
|
||
"parsed": {
|
||
"marriageNo": "6403812025001056",
|
||
"husbandName": "张三",
|
||
"wifeName": "李四",
|
||
"registerDate": "2025-10-01"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
- 备注：前端可将 `parsed.marriageNo` 用于后续校验与领取，将 `husbandName`/`wifeName`用于展示或校验提示；若识别失败，提示重新上传清晰图片。
|
||
|
||
- 领取前校验（生成二维码前的校验与预览）
|
||
- 方法：`POST`
|
||
- 路径：`/marriage/receiveCheck`
|
||
- 入参：`MarriageCodeDTO`
|
||
- `marriageNo`：结婚登记证号（必填，长度≥11，且需符合活动条件）
|
||
- `receiveName`：领取人姓名（必填）
|
||
- `receiveMobile`：领取人手机号（必填）
|
||
- `code`：核销码（必填）
|
||
- `smsCode`：短信验证码（必填，取自上方 `/sms`，`type=2`）
|
||
- `signImage`：领取人电子签名（选填，校验阶段可为空）
|
||
- `salesNo`：站点号（选填，用于落库统计）
|
||
- 出参：`ResultObject<MarriageCodeVO>`，其中包含可用于二维码展示的 `code` 等字段。
|
||
- 业务规则摘要：
|
||
- 校验结婚证号格式与活动条件。
|
||
- 校验手机号、结婚证号、核销码是否已参与或使用过。
|
||
- 校验短信验证码正确性（Redis 缓存键：`VERICODE_MOBILE 1-<mobile>`）。
|
||
|
||
- 确认领取（落库并置为已核销）
|
||
- 方法：`POST`
|
||
- 路径：`/marriage/receiveCode`
|
||
- 入参：`MarriageCodeDTO`
|
||
- 与 `receiveCheck` 基本一致，但 `signImage` 必填（签字图片，建议前端以 Base64 上传）
|
||
- 出参：`ResultObject`（成功返回 200）
|
||
- 落库行为：将 `MarriageCode` 的 `marriageNo`、`receiveName`、`receiveMobile`、`signImage`、`salesNo`、`receiveMoney=6000`、`receiveTime`、`status=1` 写入并更新。
|
||
|
||
### 3）查看已领取二维码页（包括二维码状态）
|
||
支持按站点和月份查看领取列表统计；也建议提供按核销码查询单条状态的接口。
|
||
|
||
- 已有：按站点号与月份分页统计列表
|
||
- 方法：`POST`
|
||
- 路径：`/marriage/codeList`
|
||
- 入参：`MarriageCodeDTO`
|
||
- `salesNo`：站点号（必填）
|
||
- `page`、`size`：分页参数（必填）
|
||
- `dataTime`：月份（格式 `yyyy-MM`，可选，默认当前月）
|
||
- 出参：`ResultObject<MarriageCodeVO>`
|
||
- `codeList`：列表（`MarriageCodeListVO`）
|
||
- `receiveCount`：数量合计（字符串）
|
||
- `receiveAmount`：金额合计（字符串，单位分）
|
||
|
||
- 拟新增：按核销码查询状态（用于二维码状态页）
|
||
- 方法：`POST`
|
||
- 路径：`/marriage/code/status`
|
||
- 入参：
|
||
```json
|
||
{ "code": "xxxxxx" }
|
||
```
|
||
- 出参（示例）：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "",
|
||
"data": {
|
||
"code": "xxxxxx",
|
||
"status": 0,
|
||
"marriageNo": null,
|
||
"receiveName": null,
|
||
"receiveMobile": null,
|
||
"receiveTime": null
|
||
}
|
||
}
|
||
```
|
||
- 备注：`status=0` 未核销；`status=1` 已核销。已核销时返回对应的领取人信息与时间。
|
||
|
||
---
|
||
|
||
## OCR识别流程（免手动输入）
|
||
|
||
### 端到端流程
|
||
1. 前端上传结婚证图片：`POST /marriage/ocr/upload` [新增] → 返回 `uploadId`
|
||
2. 发送短信验证码：`POST /marriage/common/sms`（`type=2`） [扩展]
|
||
3. 识别证件信息：`POST /marriage/ocr/parse`（`mobile`、`smsCode`、`uploadId`） [新增] → 返回 `parsed.marriageNo` 等信息
|
||
4. 自动填充领取表单，走校验与领取：`POST /marriage/receiveCheck` → `POST /marriage/receiveCode`
|
||
|
||
### 安全与权限
|
||
- `POST /marriage/ocr/**` 与 `POST /marriage/common/sms` 已放行匿名访问，用于领取端无登录场景。
|
||
- 后端不存储用户上传的原始图片文件，仅在 Redis 缓存 Base64（10 分钟），减少存储与泄露风险。
|
||
|
||
### 配置项标注
|
||
- 百度 OCR 相关配置（开发环境） [新增]
|
||
- `baidu.ocr.appId`、`baidu.ocr.apiKey`、`baidu.ocr.secretKey`（建议通过环境变量注入）
|
||
- `baidu.ocr.authUrl`（默认：`https://aip.baidubce.com/oauth/2.0/token`）
|
||
- `baidu.ocr.generalUrl`（默认：`https://aip.baidubce.com/rest/2.0/ocr/v1/general_basic`）
|
||
- `baidu.ocr.storagePath`（当前不落盘，仅占位）
|
||
|
||
### 测试说明
|
||
- 集成测试覆盖 OCR 上传与识别接口，使用本地伪服务模拟百度返回 [新增]
|
||
- 测试类：`com-marriage-client/src/test/java/com/jinrui/marriage/client/controller/OcrControllerTest.java`
|
||
- 通过属性重定向百度 URL 到本地：`baidu.ocr.authUrl`、`baidu.ocr.generalUrl`
|
||
- 断言返回的 `parsed.marriageNo` 包含示例字号片段
|
||
|
||
---
|
||
|
||
## 兑奖页面（改为自动带出结婚证号、手机号、姓名）
|
||
|
||
目标：在兑奖页输入（或扫码）核销码后，自动拉取该码对应的 `marriageNo`、`receiveMobile`、`receiveName` 等信息进行表单预填。
|
||
|
||
- 拟新增：根据核销码获取领取信息（用于自动带出）
|
||
- 方法：`POST`
|
||
- 路径：`/marriage/code/info`
|
||
- 入参：
|
||
```json
|
||
{ "code": "xxxxxx" }
|
||
```
|
||
- 出参（示例）：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "",
|
||
"data": {
|
||
"code": "xxxxxx",
|
||
"status": 1,
|
||
"marriageNo": "NX-2025-XXXXXXXXX",
|
||
"receiveName": "张三",
|
||
"receiveMobile": "13800000000",
|
||
"receiveTime": "2025-10-10 12:00:00",
|
||
"salesNo": "1001"
|
||
}
|
||
}
|
||
```
|
||
- 备注：
|
||
- 若未领取（`status=0`），则上述字段为空或不返回；前端可引导先走“领取流程”。
|
||
- 若已领取（`status=1`），则用于自动填充兑奖页的表单，减少重复输入。
|
||
|
||
---
|
||
|
||
## 站点登录（如需）
|
||
用于站点管理后台或业务员端登录。
|
||
|
||
- 发送登录短信验证码（type=0）
|
||
- 方法：`POST`
|
||
- 路径：`/marriage/common/sms`
|
||
- 入参：`CommSmsDTO`（`mobile`，`type=0`）
|
||
- 出参：`ResultObject`
|
||
|
||
- 登录
|
||
- 方法：`POST`
|
||
- 路径：`/marriage/common/login`
|
||
- 入参：`MarrigeLoginDTO`
|
||
- `mobile`、`password`（当前固定为 `88888888`）、`smsCode`
|
||
- 出参：`ResultObject`（包含登录票据与站点信息）
|
||
|
||
---
|
||
|
||
## 返回结构与错误码
|
||
- 所有接口统一返回 `ResultObject`：
|
||
- `code`：业务状态码，`200` 表示成功
|
||
- `msg`：提示信息
|
||
- `data`：实际数据载体（对象或集合）
|
||
- 常见失败信息（摘录）：
|
||
- `结婚证字号不能为空/长度不对/不符合活动条件`
|
||
- `领取人姓名不能为空/领取人手机号不能为空`
|
||
- `核验码不能为空/此代金卷不正确/此代金卷已使用过`
|
||
- `该领取人已领取过新婚送福活动刮刮乐/这个证号已参与过活动`
|
||
- `验证码错误，请重新输入`
|
||
|
||
---
|
||
|
||
## 字段模型参考
|
||
- `MarriageCodeDTO`
|
||
- `marriageNo`、`receiveName`、`code`、`receiveMobile`、`signImage`、`salesNo`、`smsCode`、`dataTime`
|
||
- `CommSmsDTO`
|
||
- `mobile`、`type`（`0` 登录，`1` 兑换领取）
|
||
- `MarriageCodeVO` / `MarriageCodeListVO`
|
||
- 列表与详情视图，包含领取统计与单条领取信息
|
||
|
||
---
|
||
|
||
## 前端配合建议
|
||
- 二维码内容直接使用核销码 `code` 编码，状态页通过 `code/status` 查询。
|
||
- 兑奖页在扫描或输入核销码后，先调用 `code/info` 自动填充，再根据业务需要提交后续操作。
|
||
- 如本地开发环境不具备外网资源（DB/Redis/微信），建议提供 `local` profile，临时屏蔽定时任务与外部依赖，仅用于接口联调与页面开发。
|