docs(api): 更新接口响应和订单状态规则文档

- 规范请求追踪ID生成规则,支持雪花算法或UUID确保唯一性
- 新增时间格式规范,内部使用yyyyMMddHHmmss,交互时需转换格式
- 明确邮储服务开放平台接口校验权益码过期的描述和返回提示区分
- 修改订单初始状态为"服务未预约"(100),预约成功后更新为"服务已预约"(200)
- 细化订单状态流转规则,新增
This commit is contained in:
zhouyonggao 2026-03-13 17:09:24 +08:00
parent ec186dc3b5
commit e8f2c616d4
1 changed files with 13 additions and 5 deletions

View File

@ -120,9 +120,13 @@
|-----|------|-----|------|
| code | int | M | 公共响应码0表示成功非0表示失败 |
| msg | String | M | 响应描述信息当code!=0时为错误信息 |
| traceId | String | M | 请求追踪ID用于问题排查 |
| traceId | String | M | 请求追踪ID用于问题排查。生成规则使用雪花算法或UUID确保全局唯一 |
| data | Object | C | 业务数据,成功时返回 |
### 2.3 时间格式规范
系统内部统一使用 `yyyyMMddHHmmss` 格式存储和传输时间字段。与上游蓝色兄弟系统交互时需进行格式转换(蓝色兄弟使用 `yyyy-MM-dd HH:mm:ss` 格式)。
### 2.2 公共响应码
| 响应码 | 描述 | 说明 |
@ -158,7 +162,7 @@
- 若订单状态为「服务已取消(400)」,返回"服务已取消"
- 若订单状态为「服务已完成(300)」,返回"服务已生效"
- 若订单状态为「服务已过期(500)」,返回"服务已过期"
5. 请求邮储服务开放平台接口验证权益码是否过期
5. 请求邮储服务开放平台「高端客户权益积分预约服务状态查询接口验证权益码是否过期
如果过期:
1、CRM渠道返回 "二维码20分钟内有效现已超时失效请联系理财经理重新生成二维码
2、手机银行渠道返回 "当前页面停置时间过长,请您重新进入该页面"
@ -621,7 +625,7 @@
**业务规则**
1. 生成唯一订单号
2. 关联权益码、券码、客户信息
3. 初始状态为"已预约"(200)
3. 初始状态为"服务未预约"(100),预约成功后更新为"服务已预约"(200)
**验收标准**
- [ ] 订单号全局唯一
@ -869,7 +873,11 @@
1. **订单号生成规则**:渠道号(2位) + 日期(8位) + 序列号(8位)
2. **外部业务号生成规则**:订单号 + 随机数(4位),保证唯一性和幂等性
3. **状态流转**:只允许 200→300、200→400、200→500 的状态变更
3. **状态流转**
- 100(未预约) → 200(已预约):预约成功
- 200(已预约) → 300(已完成):券码核销
- 200(已预约) → 400(已取消):用户取消
- 200(已预约) → 500(已过期):券码过期(根据上游券码状态决定)
4. **数据保留**订单数据保留至少2年
---
@ -1006,7 +1014,7 @@ ycjfsc:token:psbc
| 接口/操作 | 幂等键 | 幂等策略 |
|----------|-------|----------|
| 服务预约 | 权益码(code) | 相同权益码重复请求返回相同结果 |
| 服务预约 | 权益码(code) | 相同权益码重复请求返回相同结果内部统一使用code字段调用邮储接口时映射为rightsCode |
| 服务取消 | 权益码(rightsCode) | 已取消订单重复请求直接返回成功 |
| 服务完成通知 | 权益码(rightsCode) | 已完成订单重复请求直接返回成功 |
| 券码获取 | 外部业务号(out_biz_no) | 相同业务号返回相同券码 |