11 KiB
11 KiB
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）：
- 认证：
- 站点登录与短信验证接口位于
com-marriage-client的/marriage/common路径下。 - 后台活动管理接口位于
com-admin-client的/admin/activity路径下（通常用于管理端）。
- 站点登录与短信验证接口位于
领取流程页面
1）活动介绍页
用于展示当前活动的名称、时间和面额信息。
- 拟新增（面向领取端，便于前端直接获取展示数据）
- 方法：
GET - 路径：
/marriage/activity/current - 入参：无
- 出参（示例）：
{ "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（结婚证图片） - 出参（示例）：
{ "code": 200, "msg": "", "data": { "uploadId": "ab12cd34..." } } - 备注：服务端将图片内容以 Base64 缓存于 Redis（键：
OCR_UPLOAD-{uploadId}，有效期 10 分钟），不落盘文件。
- 方法：
-
发送短信验证码
- 方法：
POST - 路径：
/marriage/common/sms - 入参：
CommSmsDTOmobile：手机号（必填）type：验证码类型，0=登录；1=兑换领取；2=OCR识别（本页使用2） [扩展]
- 出参（示例）：
{ "code": 200, "msg": "", "data": null } - 备注：当前实现对
type=1的校验逻辑使用了code字段比对，可能与期望不一致（代码中以MarriageCode::getCode == mobile判断重复）。如需严格校验手机号唯一性，可调整实现。
- 方法：
-
OCR 识别并返回证件信息（供前端自动填充） [新增]
- 方法：
POST - 路径：
/marriage/ocr/parse - 入参：
OcrParseDTOmobile：手机号（必填）smsCode：短信验证码（必填，取自上方/sms，type=2）uploadId：上传接口返回的标识（必填）
- 出参（示例）：
{ "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 - 入参：
MarriageCodeDTOmarriageNo：结婚登记证号（必填，长度≥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 - 入参：
MarriageCodeDTOsalesNo：站点号（必填）page、size：分页参数（必填）dataTime：月份（格式yyyy-MM，可选，默认当前月）
- 出参：
ResultObject<MarriageCodeVO>codeList：列表（MarriageCodeListVO）receiveCount：数量合计（字符串）receiveAmount：金额合计（字符串，单位分）
- 方法：
-
拟新增：按核销码查询状态（用于二维码状态页）
- 方法：
POST - 路径：
/marriage/code/status - 入参：
{ "code": "xxxxxx" } - 出参（示例）：
{ "code": 200, "msg": "", "data": { "code": "xxxxxx", "status": 0, "marriageNo": null, "receiveName": null, "receiveMobile": null, "receiveTime": null } }
- 方法：
-
备注：
status=0未核销；status=1已核销。已核销时返回对应的领取人信息与时间。
OCR识别流程（免手动输入）
端到端流程
- 前端上传结婚证图片：
POST /marriage/ocr/upload[新增] → 返回uploadId - 发送短信验证码：
POST /marriage/common/sms（type=2） [扩展] - 识别证件信息：
POST /marriage/ocr/parse（mobile、smsCode、uploadId） [新增] → 返回parsed.marriageNo等信息 - 自动填充领取表单，走校验与领取：
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 - 入参：
{ "code": "xxxxxx" } - 出参（示例）：
{ "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 - 入参：
MarrigeLoginDTOmobile、password（当前固定为88888888）、smsCode
- 出参：
ResultObject（包含登录票据与站点信息）
- 方法：
返回结构与错误码
- 所有接口统一返回
ResultObject：code：业务状态码，200表示成功msg：提示信息data：实际数据载体（对象或集合）
- 常见失败信息（摘录）：
结婚证字号不能为空/长度不对/不符合活动条件领取人姓名不能为空/领取人手机号不能为空核验码不能为空/此代金卷不正确/此代金卷已使用过该领取人已领取过新婚送福活动刮刮乐/这个证号已参与过活动验证码错误，请重新输入
字段模型参考
MarriageCodeDTOmarriageNo、receiveName、code、receiveMobile、signImage、salesNo、smsCode、dataTime
CommSmsDTOmobile、type（0登录，1兑换领取）
MarriageCodeVO/MarriageCodeListVO- 列表与详情视图，包含领取统计与单条领取信息
前端配合建议
- 二维码内容直接使用核销码
code编码，状态页通过code/status查询。 - 兑奖页在扫描或输入核销码后，先调用
code/info自动填充，再根据业务需要提交后续操作。 - 如本地开发环境不具备外网资源（DB/Redis/微信），建议提供
localprofile，临时屏蔽定时任务与外部依赖，仅用于接口联调与页面开发。