diff --git a/docs/需求文档-PRD.md b/docs/需求文档-PRD.md index 9fe8266..b4aa9e6 100644 --- a/docs/需求文档-PRD.md +++ b/docs/需求文档-PRD.md @@ -1,5 +1,61 @@ # 虚拟商品充值服务商系统 - 产品需求文档 +## 接口与任务索引 + +### 对外提供的接口(被邮储银行调用) + +| 接口名称 | 说明 | 文档位置 | +|---------|------|----------| +| 服务预约接口 | 接收预约请求,获取券码链接 | [3.1.1](#311-服务预约接口) | +| 服务取消接口 | 接收取消请求,作废券码 | [3.1.2](#312-服务取消接口) | +| 订单过期积分查询接口 | 查询过期幸福点信息 | [3.1.4](#314-订单过期积分查询接口) | +| 服务详情查询接口 | 获取券码链接展示服务详情 | [3.1.6](#316-服务详情查询接口) | + +### 调用下游的接口(调用邮储银行API) + +| 接口名称 | 说明 | 文档位置 | +|---------|------|----------| +| 权益码有效性验证接口 | 验证权益码是否过期 | [3.1.1](#311-服务预约接口) | +| 服务预约接口 | 发起预约请求 | [3.1.1](#311-服务预约接口) | +| 预约服务状态查询接口 | 查询邮储侧服务状态 | [3.1.2](#312-服务取消接口) | +| 预约取消接口 | 发起取消请求 | [3.1.2](#312-服务取消接口) | +| 服务完成接口 | 通知邮储服务完成 | [3.1.3](#313-服务完成通知接口) | + +### 调用上游的接口(调用蓝色兄弟API) + +| 接口名称 | 说明 | 文档位置 | +|---------|------|----------| +| 券码获取接口 | 获取虚拟商品券码 | [3.2.1](#321-券码获取功能) | +| 券码查询接口 | 查询券码当前状态 | [3.2.2](#322-券码查询功能) | +| 券码作废接口 | 作废待使用/已过期券码 | [3.2.3](#323-券码作废功能) | +| 券码状态回调 | 接收券码状态变更通知 | [3.2.4](#324-券码状态回调接收) | + +### 定时任务 + +| 任务名称 | 执行频率 | 说明 | 文档位置 | +|---------|----------|------|----------| +| 券码状态同步 | 每小时 | 主动查询券码状态,创建对应处理任务 | [6.2](#62-券码状态同步流程) | +| 通知任务重试 | 每5分钟 | 扫描失败任务,按退避策略重试 | [6.2.1](#621-通知任务执行流程) | +| 失败任务告警 | 每10分钟 | 扫描超过最大重试次数的任务,发送告警(不再本系统实现,外部有监控系统,在监控系统中实现) | [5.2.5](#525-数据一致性监控) | + +### 异步通知任务 + +| 任务类型 | task_type | 触发来源 | 处理逻辑 | +|----------|-----------|----------|----------| +| 服务完成通知 | 1 | 回调/主动查询 | 调用邮储服务完成接口 → 订单状态改为300 | +| 过期处理 | 2 | 主动查询 | 调用邮储预约取消接口 → 订单状态改为500 | +| 作废补偿 | 3 | 主动查询 | 调用邮储预约取消接口 → 订单状态改为400 | + +### 订单状态流转 + +``` +100(未预约) → 200(已预约) → 300(已完成) + → 400(已取消) + → 500(已过期) +``` + +--- + ## 1. 功能模块划分 ### 1.1 模块结构 @@ -119,7 +175,7 @@ **输入**: | 字段 | 类型 | 必填 | 说明 | |-----|------|-----|------| -| type | String | M | 服务编码,用于查询数据库获取AES解密密钥 | +| class | String | M | 服务编码,用于查询数据库获取AES解密密钥 | | request | String | M | AES加密字符串,解密后格式:type=服务编码&code=权益码&mac=加密后的客户id | | channel | String | M | 渠道标识:12-手机银行,17-电话银行,41-CRM零售 | | tranChnl | String | M | 渠道标识:12-手机银行,17-电话银行,41-CRM零售 | @@ -221,6 +277,7 @@ **输入**: | 字段 | 类型 | 必填 | 说明 | |-----|------|-----|------| +| class | String | M | 服务编码,用于查询数据库获取AES解密密钥 | | request | String | M | AES加密字符串,解密后格式:type=服务编码&code=权益码&mac=加密后的客户id | | channel | String | M | 渠道标识:12-手机银行,17-电话银行,41-CRM零售 | | tranChnl | String | M | 渠道标识:12-手机银行,17-电话银行,41-CRM零售 | @@ -366,6 +423,39 @@ --- +#### 3.1.6 服务详情查询接口 + +**功能描述**:提供给邮储银行跳转服务详情页面,根据参数获取上游券码链接展示服务详情 + +**业务规则**: +1. 解密request参数获取服务编码、权益码、客户ID +2. 根据权益码查询订单获取券码链接 +3. 返回券码链接用于页面展示 + +**输入**: +| 字段 | 类型 | 必填 | 说明 | +|-----|------|-----|------| +| class | String | M | 服务编码,用于查询数据库获取AES解密密钥 | +| request | String | M | AES加密字符串,解密后格式:type=服务编码&code=权益码&mac=加密后的客户id | +| channel | String | M | 渠道标识:12-手机银行 17-电话银行 41-CRM零售 | +| tranChnl | String | M | 交易渠道:12-手机银行 17-电话银行 41-CRM零售 | +| backUrl | String | M | 返回手机银行的地址,用于客户返回操作 | +| instType | String | O | 机构类型:01-自营 02-代理(积分系统计划2026年0107上线) | +| provinceInstNo | String | O | 客户归属一分机构号(积分系统计划2026年0107上线) | + +**输出**(data字段内容): +| 字段 | 类型 | 必填 | 说明 | +|-----|------|-----|------| +| codeUrl | String | M | 券码链接,用于展示服务详情 | +| backUrl | String | M | 返回手机银行的地址 | + +**验收标准**: +- [ ] 能正确解密request参数 +- [ ] 能正确查询订单获取券码链接 +- [ ] 权益码不存在时返回错误提示 + +--- + ### 3.2 券码管理模块 #### 3.2.1 券码获取功能 @@ -659,7 +749,7 @@ | code | varchar | 32 | M | 权益码(邮储订单号) | | out_trade_no | varchar | 32 | N | 请求上游营销平台的交易号 | | partner_tx_sri_no | varchar | 24 | M | 请求邮储服务平台的流水号 | -| type | varchar | 6 | M | 服务类型 | +| type | varchar | 6 | M | 服务编码 | | provider_code | varchar | 4 | M | 服务商编号(邮储分配的固定值) | | status | int | 3 | M | 内部订单状态:100未预约 200已预约 300已完成 400已取消 500已过期 | | appointment_time | datetime | - | N | 预约成功时间 | @@ -689,7 +779,7 @@ | id | bigint | 20 | M | 主键 | | order_no | varchar | 32 | M | 关联订单号 | | code | varchar | 32 | M | 权益码 | -| task_type | int | 1 | M | 任务类型:1-服务完成通知 2-过期处理 3-取消补偿 | +| task_type | int | 1 | M | 任务类型:1-服务完成通知 2-过期处理 3-作废补偿 | | trigger_source | int | 1 | M | 触发来源:1-回调通知 2-主动查询 | | status | int | 1 | M | 任务状态:0-待执行 1-执行中 2-已完成 3-失败 | | retry_count | int | 3 | M | 重试次数,默认0 | @@ -705,7 +795,7 @@ |-----------|------|----------| | 1 | 服务完成通知 | 调用邮储服务完成接口 → 订单状态改为300 | | 2 | 过期处理 | 调用邮储预约取消接口 → 订单状态改为500 | -| 3 | 取消补偿 | 调用邮储预约取消接口 → 订单状态改为400 | +| 3 | 作废补偿 | 调用邮储预约取消接口 → 订单状态改为400 | #### 4.1.4 对账记录表(ycjfsc_reconciliation) @@ -853,7 +943,7 @@ ycjfsc:token:psbc | 任务 | 执行频率 | 处理逻辑 | |-----|---------|----------| -| 券码状态同步 | 每小时 | 扫描状态=200(已预约)的订单,查询蓝色兄弟券码状态:已核销(2)→创建服务完成任务,已作废(3)→创建取消补偿任务,已过期(4)→创建过期处理任务 | +| 券码状态同步 | 每小时 | 扫描状态=200(已预约)的订单,查询蓝色兄弟券码状态:已核销(2)→创建服务完成任务,已作废(3)→创建作废补偿任务,已过期(4)→创建过期处理任务 | | 通知任务重试 | 每5分钟 | 扫描状态=3(失败)且未超过最大重试次数的任务,按退避策略重试 | | 失败任务告警 | 每10分钟 | 扫描超过最大重试次数的任务,发送告警通知 | @@ -1046,7 +1136,7 @@ while (遍历订单?) is (有) elseif (已作废 3) then :检查是否已有通知任务; if (任务存在?) then (否) - :创建通知任务\n(type=3 取消补偿); + :创建通知任务\n(type=3 作废补偿); endif elseif (已过期 4) then :检查是否已有通知任务; @@ -1077,7 +1167,7 @@ stop | 券码状态 | 任务类型 | 处理逻辑 | |----------|----------|----------| | 已核销(2) | 服务完成通知(1) | 调用邮储服务完成接口 → 订单状态改为300 | -| 已作废(3) | 取消补偿(3) | 调用邮储预约取消接口 → 订单状态改为400 | +| 已作废(3) | 作废补偿(3) | 调用邮储预约取消接口 → 订单状态改为400 | | 已过期(4) | 过期处理(2) | 调用邮储预约取消接口 → 订单状态改为500 | | 正常(1) | - | 跳过,等待用户使用 | @@ -1098,7 +1188,7 @@ while (遍历任务?) is (有) :调用邮储服务完成接口; elseif (type=2 过期处理) then :调用邮储预约取消接口; - else (type=3 取消补偿) + else (type=3 作废补偿) :调用邮储预约取消接口; endif note right: 5s超时