docs(api): 补充完善虚拟商品充值服务接口文档及任务说明

- 新增接口与任务索引表，明确对外接口、下游接口、上游接口及定时任务
- 增加服务详情查询接口，详细说明功能、业务规则及输入输出字段
- 统一部分接口参数名称由type改为class，明确服务编码含义
- 修改任务类型命名，将取消补偿统一改为作废补偿，确保术语一致性
- 更新数据库表字段及流程图，反映任务类型名称调整
- 丰富订单状态流转说明及异步通知任务处理逻辑

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超时