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

- 规范请求追踪ID生成规则,支持雪花算法或UUID确保唯一性
- 新增时间格式规范,内部使用yyyyMMddHHmmss,交互时需转换格式
- 明确邮储服务开放平台接口校验权益码过期的描述和返回提示区分
- 修改订单初始状态为"服务未预约"(100),预约成功后更新为"服务已预约"(200)
- 细化订单状态流转规则,新增从未预约到已预约状态的变更路径
- 注明服务预约接口幂等策略中code字段与邮储接口rightsCode的映射关系
This commit is contained in:
zhouyonggao 2026-03-13 17:10:16 +08:00
parent e8f2c616d4
commit 75acb12f95
1 changed files with 9 additions and 7 deletions

View File

@ -425,9 +425,11 @@
--- ---
#### 3.1.5 服务状态查询接口 #### 3.1.5 服务状态查询接口(内部接口)
**功能描述**:根据权益码查询服务预约状态 **功能描述**:调用邮储「高端客户权益积分预约服务状态查询接口」,根据权益码查询邮储侧的服务预约状态。用于服务取消、服务预约等流程中验证邮储侧订单状态。
**说明**:此接口为内部调用邮储接口,非对外提供的接口。
**业务规则** **业务规则**
1. 根据权益码查询订单 1. 根据权益码查询订单
@ -961,15 +963,15 @@ ycjfsc:token:psbc
``` ```
1. 接收蓝色兄弟核销回调 1. 接收蓝色兄弟核销回调
2. 更新订单状态为「待通知」(250)记录核销时间 2. 记录核销时间,创建通知任务(task_type=1)
3. 立即响应蓝色兄弟"ok"(快速响应,避免超时) 3. 立即响应蓝色兄弟"ok"(快速响应,避免超时)
4. 异步处理: 4. 异步处理:
- 调用邮储服务完成接口 - 调用邮储服务完成接口
- 成功:更新订单状态为「已完成」(300) - 成功:更新订单状态为「已完成」(300),任务状态为已完成(2)
- 失败:保留状态250,等待重试机制处理 - 失败:任务状态为失败(3),等待重试机制处理
``` ```
**说明**:不使用本地事务,通过重试+补偿+对账三重机制保证最终一致性。 **说明**:不使用本地事务,通过重试+补偿+对账三重机制保证最终一致性。订单状态统一使用100/200/300/400/500五个状态通知处理过程通过通知任务表(ycjfsc_notify_task)进行管理。
**机制二:消息重试策略** **机制二:消息重试策略**
@ -984,7 +986,7 @@ ycjfsc:token:psbc
| 第7次 | 1小时 | 1小时46分40秒 | | 第7次 | 1小时 | 1小时46分40秒 |
| 第8次 | 2小时 | 3小时46分40秒 | | 第8次 | 2小时 | 3小时46分40秒 |
超过8次仍失败标记为「通知异常」(350)人工介入处理。 超过8次仍失败任务保持失败状态,等待告警通知后人工介入处理。
**机制三:定时补偿任务** **机制三:定时补偿任务**