1059 lines
33 KiB
Markdown
1059 lines
33 KiB
Markdown
# 虚拟商品充值服务商系统 - 产品需求文档
|
||
|
||
## 1. 功能模块划分
|
||
|
||
### 1.1 模块结构
|
||
|
||
```
|
||
服务商系统
|
||
├── 接口服务模块（对接邮储银行服务开放平台）
|
||
│ ├── 服务预约接口
|
||
│ ├── 服务取消接口
|
||
│ ├── 服务完成通知接口
|
||
│ ├── 订单过期积分查询接口
|
||
│ └── 服务状态查询接口
|
||
├── 券码管理模块（对接蓝色兄弟营销开放API）
|
||
│ ├── 券码获取功能
|
||
│ ├── 券码查询功能
|
||
│ ├── 券码作废功能
|
||
│ └── 券码状态回调接收
|
||
├── 订单管理模块
|
||
│ ├── 订单创建
|
||
│ ├── 订单状态管理
|
||
│ ├── 订单查询
|
||
│ └── 订单对账
|
||
├── 对账管理模块
|
||
│ ├── 对账文件查询
|
||
│ ├── 对账文件下载
|
||
│ └── 对账数据核对
|
||
└── 安全与加密模块
|
||
├── SM2/SM4加解密（邮储银行）
|
||
├── RSA/AES加解密（蓝色兄弟）
|
||
└── 签名验签
|
||
```
|
||
|
||
### 1.2 模块关系
|
||
|
||
| 模块 | 调用方/被调用方 | 内部依赖 | 说明 |
|
||
|------|----------------|---------|------|
|
||
| 接口服务模块 | 被下游邮储银行调用 | 订单管理模块、券码管理模块 | 接收邮储银行请求，转发至内部处理 |
|
||
| 券码管理模块 | 调用上游蓝色兄弟API | 订单管理模块 | 负责券码全生命周期管理 |
|
||
| 订单管理模块 | - | 券码管理模块、对账管理模块 | 核心业务数据管理 |
|
||
| 对账管理模块 | 调用下游邮储银行API | 订单管理模块 | 月度对账处理 |
|
||
| 安全与加密模块 | - | 所有模块 | 提供安全基础能力 |
|
||
|
||
---
|
||
|
||
## 2. 功能详细说明
|
||
|
||
### 2.1 接口服务模块
|
||
|
||
#### 2.1.1 服务预约接口
|
||
|
||
**功能描述**：接收邮储银行服务开放平台的预约请求，为客户预约虚拟商品充值服务
|
||
|
||
**业务规则**：
|
||
1. 解密请求报文，验证签名
|
||
2. 校验权益码有效性（20分钟有效期）
|
||
3. 调用蓝色兄弟API获取券码
|
||
4. 创建订单记录，状态设为"已预约"(200)
|
||
5. 返回预约成功响应
|
||
|
||
**输入**：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| rightsCode | String | M | 兑换预约码，格式：16800G-VN4724-NX874-30VHR |
|
||
| serviceType | String | M | 服务类型编码 |
|
||
| providerCode | String | M | 服务厂商编号 |
|
||
| custName | String | C | 客户名称（电话银行渠道可选） |
|
||
| personalCertTypeCode | String | C | 证件类型 |
|
||
| personalCertNo | String | C | 证件号码 |
|
||
|
||
**输出**：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| respCode | String | M | 返回码，000000表示成功 |
|
||
| respMsg | String | M | 返回信息 |
|
||
| rightsCode | String | C | 兑换预约码 |
|
||
| tradeRespCode | String | M | 业务响应码 |
|
||
| tradeRespMsg | String | M | 业务响应码描述 |
|
||
|
||
**验收标准**：
|
||
- [ ] 能正确解密SM4加密的请求报文
|
||
- [ ] 能正确验证SM2签名
|
||
- [ ] 权益码超过20分钟返回失效错误(161026)
|
||
- [ ] 预约成功后订单状态为200
|
||
- [ ] 预约成功后能获取到蓝色兄弟券码
|
||
|
||
---
|
||
|
||
#### 2.1.2 服务取消接口
|
||
|
||
**功能描述**：接收邮储银行服务开放平台的取消请求，取消已预约的服务
|
||
|
||
**业务规则**：
|
||
1. 校验订单状态必须为"已预约"(200)
|
||
2. 调用蓝色兄弟API作废券码
|
||
3. 更新订单状态为"已取消"(400)
|
||
4. 返回取消成功响应
|
||
|
||
**输入**：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| rightsCode | String | M | 兑换预约码 |
|
||
| serviceType | String | M | 服务类型编码 |
|
||
| providerCode | String | M | 服务厂商编号 |
|
||
|
||
**输出**：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| respCode | String | M | 返回码 |
|
||
| respMsg | String | M | 返回信息 |
|
||
| tradeRespCode | String | M | 业务响应码 |
|
||
| tradeRespMsg | String | M | 业务响应码描述 |
|
||
|
||
**验收标准**：
|
||
- [ ] 非"已预约"状态订单返回错误(161024)
|
||
- [ ] 已完成订单不允许取消(161014)
|
||
- [ ] 取消成功后蓝色兄弟券码状态为已作废(3)
|
||
- [ ] 取消成功后订单状态为400
|
||
|
||
---
|
||
|
||
#### 2.1.3 服务完成通知接口
|
||
|
||
**功能描述**：接收蓝色兄弟券码核销回调，主动通知邮储银行服务完成
|
||
|
||
**业务规则**：
|
||
1. 接收蓝色兄弟券码状态变更回调
|
||
2. 当券码状态变为"已核销"(2)时
|
||
3. 调用邮储银行服务完成接口
|
||
4. 更新订单状态为"已完成"(300)
|
||
5. 服务完成状态更新需在T+2日内完成
|
||
|
||
**输入**：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| rightsCode | String | M | 兑换预约码 |
|
||
| serviceType | String | M | 服务类型编码 |
|
||
| providerCode | String | M | 服务厂商编号 |
|
||
| completionTime | String | M | 实际完成时间，格式：yyyyMMddHHmmss |
|
||
|
||
**输出**：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| respCode | String | M | 返回码 |
|
||
| respMsg | String | M | 返回信息 |
|
||
|
||
**验收标准**：
|
||
- [ ] 能正确接收蓝色兄弟回调通知
|
||
- [ ] 回调验签通过后正确响应"ok"
|
||
- [ ] 服务完成通知在T+2日内发送
|
||
- [ ] 已取消订单不允许完成(161014)
|
||
- [ ] 完成成功后订单状态为300
|
||
|
||
---
|
||
|
||
#### 2.1.4 订单过期积分查询接口
|
||
|
||
**功能描述**：查询订单退还时已过期的幸福点信息，用于取消前提醒客户
|
||
|
||
**业务规则**：
|
||
1. 根据权益码或原交易流水号查询订单
|
||
2. 计算订单涉及的总幸福点
|
||
3. 计算已过期的幸福点数量
|
||
4. 返回过期幸福点提醒信息
|
||
|
||
**输入**：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| rightsCode | String | C | 兑换预约码（已预约取消场景必填） |
|
||
| orgTranSq | String | C | 原交易流水号（已兑换未预约取消场景必填） |
|
||
| cstmName | String | C | 客户名称 |
|
||
| paperType | String | C | 证件类型 |
|
||
| paperId | String | C | 证件号码 |
|
||
|
||
**输出**：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| respCode | String | M | 返回码 |
|
||
| respMsg | String | M | 返回信息 |
|
||
| tranIntglNum | int | C | 交易总幸福点 |
|
||
| ovdueIntglNum | int | C | 已过期的幸福点 |
|
||
| noticeMsg | String | C | 提醒信息文本 |
|
||
|
||
**验收标准**：
|
||
- [ ] 能正确查询订单积分信息
|
||
- [ ] 过期幸福点计算准确
|
||
- [ ] 返回友好的提醒信息
|
||
|
||
---
|
||
|
||
#### 2.1.5 服务状态查询接口
|
||
|
||
**功能描述**：根据权益码查询服务预约状态
|
||
|
||
**业务规则**：
|
||
1. 根据权益码查询订单
|
||
2. 返回当前服务状态
|
||
|
||
**输入**：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| rightsCode | String | M | 兑换权益码 |
|
||
| tranChnl | String | M | 渠道标识 |
|
||
|
||
**输出**：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| respCode | String | M | 返回码 |
|
||
| respMsg | String | M | 返回信息 |
|
||
| serviceState | String | M | 预约服务状态码：100-未预约，200-已预约，300-已完成，400-已取消，500-已过期 |
|
||
| serviceStateMsg | String | M | 预约服务状态描述 |
|
||
|
||
**验收标准**：
|
||
- [ ] 能正确查询订单状态
|
||
- [ ] 状态码与状态描述一致
|
||
|
||
---
|
||
|
||
### 2.2 券码管理模块
|
||
|
||
#### 2.2.1 券码获取功能
|
||
|
||
**功能描述**：调用蓝色兄弟API获取虚拟商品券码
|
||
|
||
**业务规则**：
|
||
1. 生成唯一外部业务号(out_biz_no)
|
||
2. 构造请求参数并AES加密
|
||
3. 使用RSA私钥签名
|
||
4. 调用获取券码接口
|
||
5. 保存券码信息与订单关联
|
||
|
||
**输入**：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| out_biz_no | String | M | 外部业务号，长度2~32位，幂等 |
|
||
| activity_no | String | M | 活动编号，长度32位内 |
|
||
| number | int | M | 数量，只支持1 |
|
||
| account | String | N | 账号 |
|
||
| notify_url | String | N | 回调通知地址 |
|
||
|
||
**输出**：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| out_biz_no | String | M | 外部业务号 |
|
||
| trade_no | String | M | 交易号 |
|
||
| key | String | N | key码 |
|
||
| url | String | N | 短链接 |
|
||
| status | uint8 | M | 状态：1-正常，2-已核销，3-已作废 |
|
||
| valid_begin_time | String | M | key码有效期开始 |
|
||
| valid_end_time | String | M | key码有效期结束 |
|
||
| usable_num | uint32 | M | 可兑换次数 |
|
||
|
||
**验收标准**：
|
||
- [ ] 能正确加密业务参数(AES)
|
||
- [ ] 能正确签名请求(RSA)
|
||
- [ ] 幂等请求返回相同结果
|
||
- [ ] 获取成功后保存券码信息
|
||
|
||
---
|
||
|
||
#### 2.2.2 券码查询功能
|
||
|
||
**功能描述**：查询已获取券码的当前状态
|
||
|
||
**业务规则**：
|
||
1. 支持通过外部业务号或交易号查询
|
||
2. 返回券码完整状态信息
|
||
|
||
**输入**：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| out_biz_no | String | C | 外部业务号，与trade_no二选一 |
|
||
| trade_no | String | C | 交易号，优先使用 |
|
||
|
||
**输出**：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| status | uint8 | M | 状态：1-正常，2-已核销，3-已作废，4-已过期 |
|
||
| usage_num | uint32 | M | 已兑换次数 |
|
||
| usage_time | String | N | 最后一次核销时间 |
|
||
|
||
**验收标准**：
|
||
- [ ] 能正确查询券码状态
|
||
- [ ] 状态信息完整准确
|
||
|
||
---
|
||
|
||
#### 2.2.3 券码作废功能
|
||
|
||
**功能描述**：作废待使用或已过期的券码
|
||
|
||
**业务规则**：
|
||
1. 只能作废待使用(1)、已过期(4)状态的券码
|
||
2. 已核销券码不允许作废
|
||
|
||
**输入**：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| out_biz_no | String | C | 外部业务号，与trade_no二选一 |
|
||
| trade_no | String | C | 交易号，优先使用 |
|
||
|
||
**验收标准**：
|
||
- [ ] 正常状态券码能成功作废
|
||
- [ ] 已核销券码作废返回错误
|
||
- [ ] 作废成功后券码状态为3
|
||
|
||
---
|
||
|
||
#### 2.2.4 券码状态回调接收
|
||
|
||
**功能描述**：接收蓝色兄弟的券码状态变更通知
|
||
|
||
**业务规则**：
|
||
1. 验证回调签名
|
||
2. 解析回调数据
|
||
3. 更新本地券码状态
|
||
4. 当status=2(已核销)时触发服务完成通知
|
||
5. 响应httpCode=200和字符串"ok"
|
||
|
||
**回调重试策略**：
|
||
- 首次间隔120s
|
||
- 第二次间隔240s
|
||
- 第三次间隔360s
|
||
- 大于5分钟后间隔5分钟
|
||
- 大于10分钟后间隔10分钟
|
||
- 超过120分钟后不再重试
|
||
|
||
**验收标准**：
|
||
- [ ] 能正确验证回调签名
|
||
- [ ] 状态更新及时准确
|
||
- [ ] 核销状态触发服务完成通知
|
||
- [ ] 响应格式正确(httpCode=200, body="ok")
|
||
|
||
---
|
||
|
||
### 2.3 订单管理模块
|
||
|
||
#### 2.3.1 订单创建
|
||
|
||
**功能描述**：创建权益服务订单
|
||
|
||
**业务规则**：
|
||
1. 生成唯一订单号
|
||
2. 关联权益码、券码、客户信息
|
||
3. 初始状态为"已预约"(200)
|
||
|
||
**验收标准**：
|
||
- [ ] 订单号全局唯一
|
||
- [ ] 订单信息完整
|
||
|
||
---
|
||
|
||
#### 2.3.2 订单状态管理
|
||
|
||
**功能描述**：管理订单全生命周期状态流转
|
||
|
||
**状态定义**：
|
||
| 状态码 | 状态名称 | 说明 |
|
||
|-------|---------|------|
|
||
| 100 | 服务未预约 | 已兑换但未预约 |
|
||
| 200 | 服务已预约 | 已预约待使用 |
|
||
| 300 | 服务已完成 | 券码已核销 |
|
||
| 400 | 服务已取消 | 用户主动取消 |
|
||
| 500 | 服务已过期 | 超过90天未预约 |
|
||
|
||
**状态流转规则**：
|
||
- 200(已预约) → 300(已完成)：券码核销
|
||
- 200(已预约) → 400(已取消)：用户取消
|
||
- 300(已完成) 和 400(已取消) 为终态，不可变更
|
||
|
||
**验收标准**：
|
||
- [ ] 状态流转符合规则
|
||
- [ ] 终态不可变更
|
||
- [ ] 状态变更有日志记录
|
||
|
||
---
|
||
|
||
#### 2.3.3 订单查询
|
||
|
||
**功能描述**：支持多维度订单查询
|
||
|
||
**查询维度**：
|
||
- 按权益码查询
|
||
- 按订单号查询
|
||
- 按客户信息查询
|
||
- 按状态查询
|
||
- 按时间范围查询
|
||
|
||
**验收标准**：
|
||
- [ ] 支持所有查询维度
|
||
- [ ] 查询结果准确
|
||
|
||
---
|
||
|
||
### 2.4 对账管理模块
|
||
|
||
#### 2.4.1 对账文件查询
|
||
|
||
**功能描述**：查询邮储银行生成的对账文件列表
|
||
|
||
**业务规则**：
|
||
1. 每月3号查询上月对账文件
|
||
2. 只包含服务完成(300)状态的订单
|
||
|
||
**输入**：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| accountingDate | String | M | 会计日期，YYYYMMDD |
|
||
| fileIntfcName | String | M | 文件接口名 |
|
||
|
||
**验收标准**：
|
||
- [ ] 能正确查询对账文件列表
|
||
- [ ] 返回文件ID、名称等完整信息
|
||
|
||
---
|
||
|
||
#### 2.4.2 对账文件下载
|
||
|
||
**功能描述**：下载对账文件内容
|
||
|
||
**输入**：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| fileId | String | M | 文件唯一标识 |
|
||
| fileIntfcName | String | M | 文件接口名 |
|
||
| sm4Key | String | M | 对账文件SM4加密密钥 |
|
||
|
||
**对账文件内容**：
|
||
| 字段 | 说明 |
|
||
|-----|------|
|
||
| 统计月份 | YYYYMMDD |
|
||
| 一分机构序号 | - |
|
||
| 一分机构名称 | - |
|
||
| 网点机构属性 | 01-自营，02-代理 |
|
||
| 积分客户服务编码 | - |
|
||
| 服务内容 | - |
|
||
| 预约时间 | - |
|
||
| 实际完成时间 | - |
|
||
| 权益兑换码 | - |
|
||
|
||
**验收标准**：
|
||
- [ ] 能正确解密对账文件
|
||
- [ ] 能解析对账文件内容
|
||
- [ ] 与本地订单数据核对
|
||
|
||
---
|
||
|
||
### 2.5 安全与加密模块
|
||
|
||
#### 2.5.1 邮储银行加解密（SM2/SM4）
|
||
|
||
**功能描述**：实现与邮储银行通信的加解密
|
||
|
||
**加密规则**：
|
||
1. 随机生成SM4 key
|
||
2. 使用SM4 key对请求报文加密（CBC模式）
|
||
3. 使用邮储银行公钥SM2加密SM4 key
|
||
|
||
**签名规则**：
|
||
1. 拼接：request + encryptKey + accessToken
|
||
2. 使用SM3计算摘要
|
||
3. 使用私钥SM2加密摘要
|
||
|
||
**验收标准**：
|
||
- [ ] SM4加解密正确
|
||
- [ ] SM2加解密正确
|
||
- [ ] SM3签名验签正确
|
||
|
||
---
|
||
|
||
#### 2.5.2 蓝色兄弟加解密（RSA/AES）
|
||
|
||
**功能描述**：实现与蓝色兄弟通信的加解密
|
||
|
||
**业务参数加密规则**：
|
||
1. 业务参数去掉"零"值
|
||
2. 按字母排序转成JSON字符串
|
||
3. 使用应用key进行AES加密
|
||
|
||
**签名规则**：
|
||
1. 拼接：appId + timestamp + ciphertext
|
||
2. 使用私钥RSA签名
|
||
|
||
**验收标准**：
|
||
- [ ] AES加解密正确
|
||
- [ ] RSA签名验签正确
|
||
- [ ] 回调验签正确
|
||
|
||
---
|
||
|
||
## 3. 数据需求
|
||
|
||
### 3.1 数据实体
|
||
|
||
#### 3.1.1 订单表(t_order)
|
||
|
||
| 字段名 | 类型 | 长度 | 必填 | 说明 |
|
||
|-------|------|-----|-----|------|
|
||
| id | bigint | 20 | M | 主键 |
|
||
| order_no | varchar | 32 | M | 订单号 |
|
||
| rights_code | varchar | 32 | M | 权益码 |
|
||
| service_type | varchar | 6 | M | 服务类型 |
|
||
| provider_code | varchar | 4 | M | 服务商编号 |
|
||
| status | int | 3 | M | 订单状态：100/200/300/400/500 |
|
||
| cust_name | varchar | 40 | N | 客户名称 |
|
||
| cert_type | varchar | 2 | N | 证件类型 |
|
||
| cert_no | varchar | 30 | N | 证件号码 |
|
||
| cust_id | varchar | 32 | N | 客户编号 |
|
||
| partner_tx_sri_no | varchar | 24 | M | 合作方交易流水号 |
|
||
| req_time | datetime | - | M | 请求时间 |
|
||
| appointment_time | datetime | - | N | 预约时间 |
|
||
| completion_time | datetime | - | N | 完成时间 |
|
||
| cancel_time | datetime | - | N | 取消时间 |
|
||
| create_time | datetime | - | M | 创建时间 |
|
||
| update_time | datetime | - | M | 更新时间 |
|
||
|
||
#### 3.1.2 券码表(t_coupon)
|
||
|
||
| 字段名 | 类型 | 长度 | 必填 | 说明 |
|
||
|-------|------|-----|-----|------|
|
||
| id | bigint | 20 | M | 主键 |
|
||
| order_id | bigint | 20 | M | 关联订单ID |
|
||
| out_biz_no | varchar | 32 | M | 外部业务号 |
|
||
| trade_no | varchar | 32 | M | 交易号 |
|
||
| key_code | varchar | 64 | N | 券码 |
|
||
| url | varchar | 256 | N | 短链接 |
|
||
| status | int | 1 | M | 状态：1-正常，2-已核销，3-已作废，4-已过期 |
|
||
| activity_no | varchar | 32 | M | 活动编号 |
|
||
| usable_num | int | 10 | M | 总兑换次数 |
|
||
| usage_num | int | 10 | M | 已兑换次数 |
|
||
| valid_begin_time | datetime | - | M | 有效期开始 |
|
||
| valid_end_time | datetime | - | M | 有效期结束 |
|
||
| usage_time | datetime | - | N | 核销时间 |
|
||
| discard_time | datetime | - | N | 作废时间 |
|
||
| create_time | datetime | - | M | 创建时间 |
|
||
| update_time | datetime | - | M | 更新时间 |
|
||
|
||
#### 3.1.3 对账记录表(t_reconciliation)
|
||
|
||
| 字段名 | 类型 | 长度 | 必填 | 说明 |
|
||
|-------|------|-----|-----|------|
|
||
| id | bigint | 20 | M | 主键 |
|
||
| recon_month | varchar | 6 | M | 对账月份YYYYMM |
|
||
| file_id | varchar | 32 | M | 文件ID |
|
||
| file_name | varchar | 128 | M | 文件名 |
|
||
| recon_status | int | 1 | M | 对账状态：0-待对账，1-已对账，2-有差异 |
|
||
| total_count | int | 10 | M | 总记录数 |
|
||
| match_count | int | 10 | M | 匹配记录数 |
|
||
| diff_count | int | 10 | M | 差异记录数 |
|
||
| create_time | datetime | - | M | 创建时间 |
|
||
| update_time | datetime | - | M | 更新时间 |
|
||
|
||
### 3.2 数据规则
|
||
|
||
1. **订单号生成规则**：渠道号(2位) + 日期(8位) + 序列号(8位)
|
||
2. **外部业务号生成规则**：订单号 + 随机数(4位)，保证唯一性和幂等性
|
||
3. **状态流转**：只允许 200→300、200→400 的状态变更
|
||
4. **数据保留**：订单数据保留至少2年
|
||
|
||
---
|
||
|
||
## 4. 流程图
|
||
|
||
### 4.1 服务预约流程
|
||
|
||
```plantuml
|
||
@startuml 服务预约流程
|
||
actor 客户 as Customer
|
||
participant "邮储银行\n服务开放平台" as Bank
|
||
participant "服务商系统" as Provider
|
||
participant "蓝色兄弟\n营销开放API" as LSB
|
||
database "服务商数据库" as DB
|
||
|
||
Customer -> Bank: 1.发起服务预约
|
||
activate Bank
|
||
|
||
Bank -> Provider: 2.调用预约接口\n(SM2/SM4加密)
|
||
activate Provider
|
||
|
||
Provider -> Provider: 3.解密验签\n校验权益码有效性
|
||
|
||
Provider -> LSB: 4.获取券码\n(RSA/AES加密)
|
||
activate LSB
|
||
|
||
LSB -> LSB: 5.生成券码
|
||
|
||
LSB --> Provider: 6.返回券码信息\n(key/url)
|
||
deactivate LSB
|
||
|
||
Provider -> DB: 7.创建订单\n保存券码信息
|
||
activate DB
|
||
DB --> Provider: 8.保存成功
|
||
deactivate DB
|
||
|
||
Provider --> Bank: 9.返回预约成功\n(SM2/SM4加密)
|
||
deactivate Provider
|
||
|
||
Bank --> Customer: 10.显示预约成功\n展示券码/链接
|
||
deactivate Bank
|
||
|
||
@enduml
|
||
```
|
||
|
||
### 4.2 服务完成流程
|
||
|
||
```plantuml
|
||
@startuml 服务完成流程
|
||
actor 客户 as Customer
|
||
participant "蓝色兄弟\n营销开放API" as LSB
|
||
participant "服务商系统" as Provider
|
||
participant "邮储银行\n服务开放平台" as Bank
|
||
database "服务商数据库" as DB
|
||
|
||
Customer -> LSB: 1.使用券码核销
|
||
activate LSB
|
||
|
||
LSB -> LSB: 2.核销券码\n状态变更为已核销(2)
|
||
|
||
LSB -> Provider: 3.回调通知\n券码状态变更
|
||
activate Provider
|
||
|
||
Provider -> Provider: 4.验证回调签名
|
||
|
||
Provider -> DB: 5.更新券码状态
|
||
activate DB
|
||
DB --> Provider: 6.更新成功
|
||
deactivate DB
|
||
|
||
Provider --> LSB: 7.响应"ok"
|
||
deactivate LSB
|
||
|
||
Provider -> Bank: 8.通知服务完成\n(SM2/SM4加密)\n[T+2日内]
|
||
activate Bank
|
||
|
||
Bank -> Bank: 9.更新订单状态\n已预约(200)→已完成(300)
|
||
|
||
Bank --> Provider: 10.返回完成成功
|
||
deactivate Bank
|
||
|
||
Provider -> DB: 11.更新订单状态为300
|
||
deactivate Provider
|
||
|
||
@enduml
|
||
```
|
||
|
||
### 4.3 服务取消流程
|
||
|
||
```plantuml
|
||
@startuml 服务取消流程
|
||
actor 客户 as Customer
|
||
participant "邮储银行\n服务开放平台" as Bank
|
||
participant "服务商系统" as Provider
|
||
participant "蓝色兄弟\n营销开放API" as LSB
|
||
database "服务商数据库" as DB
|
||
|
||
Customer -> Bank: 1.发起服务取消
|
||
activate Bank
|
||
|
||
Bank -> Provider: 2.查询过期积分
|
||
activate Provider
|
||
|
||
Provider -> DB: 3.查询订单积分信息
|
||
activate DB
|
||
DB --> Provider: 4.返回积分信息
|
||
deactivate DB
|
||
|
||
Provider --> Bank: 5.返回过期积分信息
|
||
deactivate Provider
|
||
|
||
alt 存在过期幸福点
|
||
Bank --> Customer: 6a.提示"存在已过期幸福点\n取消后只退还未过期部分"
|
||
Customer -> Bank: 6b.确认取消
|
||
end
|
||
|
||
Bank -> Provider: 7.调用取消接口
|
||
activate Provider
|
||
|
||
Provider -> DB: 8.查询订单和券码
|
||
activate DB
|
||
DB --> Provider: 9.返回订单信息
|
||
deactivate DB
|
||
|
||
Provider -> LSB: 10.作废券码
|
||
activate LSB
|
||
LSB --> Provider: 11.作废成功
|
||
deactivate LSB
|
||
|
||
Provider -> DB: 12.更新订单状态为400
|
||
activate DB
|
||
DB --> Provider: 13.更新成功
|
||
deactivate DB
|
||
|
||
Provider --> Bank: 14.返回取消成功
|
||
deactivate Provider
|
||
|
||
Bank --> Customer: 15.显示取消成功\n已退还XX幸福点
|
||
deactivate Bank
|
||
|
||
@enduml
|
||
```
|
||
|
||
### 4.4 月度对账流程
|
||
|
||
```plantuml
|
||
@startuml 月度对账流程
|
||
participant "定时任务" as Scheduler
|
||
participant "服务商系统" as Provider
|
||
participant "邮储银行\n服务开放平台" as Bank
|
||
database "服务商数据库" as DB
|
||
|
||
Scheduler -> Provider: 1.每月3号触发对账任务
|
||
activate Provider
|
||
|
||
Provider -> Bank: 2.查询对账文件列表\n(上月已完成订单)
|
||
activate Bank
|
||
Bank --> Provider: 3.返回文件列表
|
||
deactivate Bank
|
||
|
||
Provider -> Bank: 4.下载对账文件
|
||
activate Bank
|
||
Bank --> Provider: 5.返回对账文件内容\n(SM4加密)
|
||
deactivate Bank
|
||
|
||
Provider -> Provider: 6.解密对账文件
|
||
|
||
Provider -> DB: 7.查询本地已完成订单
|
||
activate DB
|
||
DB --> Provider: 8.返回订单列表
|
||
deactivate DB
|
||
|
||
Provider -> Provider: 9.数据核对比对
|
||
|
||
alt 存在差异
|
||
Provider -> Provider: 10a.生成差异报告\n人工介入处理
|
||
else 无差异
|
||
Provider -> DB: 10b.更新对账状态为已对账
|
||
end
|
||
|
||
deactivate Provider
|
||
|
||
@enduml
|
||
```
|
||
|
||
### 4.5 错误处理流程
|
||
|
||
```plantuml
|
||
@startuml 错误处理流程
|
||
participant "调用方" as Caller
|
||
participant "服务商系统" as Provider
|
||
participant "下游服务" as Downstream
|
||
database "服务商数据库" as DB
|
||
|
||
Caller -> Provider: 1.发起请求
|
||
activate Provider
|
||
|
||
alt 参数校验失败
|
||
Provider --> Caller: 2a.返回参数错误\n(900001/900002)
|
||
else 签名验证失败
|
||
Provider --> Caller: 2b.返回签名错误\n(900005/900011)
|
||
else 权益码无效
|
||
Provider --> Caller: 2c.返回权益码错误\n(161026/161027)
|
||
else 业务规则不满足
|
||
Provider --> Caller: 2d.返回业务错误\n(161014/161024)
|
||
else 下游服务异常
|
||
Provider -> Downstream: 3.调用下游服务
|
||
activate Downstream
|
||
Downstream --> Provider: 4.返回异常
|
||
deactivate Downstream
|
||
|
||
Provider -> DB: 5.记录异常日志
|
||
Provider --> Caller: 6.返回系统繁忙\n(900000/990172)
|
||
else 处理成功
|
||
Provider -> Downstream: 3.调用下游服务
|
||
activate Downstream
|
||
Downstream --> Provider: 4.返回成功
|
||
deactivate Downstream
|
||
|
||
Provider -> DB: 5.更新业务数据
|
||
Provider --> Caller: 6.返回成功(000000)
|
||
end
|
||
|
||
deactivate Provider
|
||
|
||
@enduml
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 用户故事
|
||
|
||
### 5.1 服务预约
|
||
|
||
#### US-001: 预约虚拟商品服务
|
||
|
||
**As a** 邮储银行高端客户
|
||
**I want** 使用幸福点兑换的权益码预约虚拟商品服务
|
||
**So that** 我可以获得虚拟商品券码并使用
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] Given 有效的权益码（20分钟内），When 调用预约接口，Then 返回预约成功并获得券码
|
||
- [ ] Given 权益码已超过20分钟有效期，When 调用预约接口，Then 返回161026错误码
|
||
- [ ] Given 相同的业务主ID重复请求，When 调用预约接口，Then 返回幂等结果
|
||
|
||
---
|
||
|
||
### 5.2 服务取消
|
||
|
||
#### US-002: 取消已预约服务
|
||
|
||
**As a** 邮储银行高端客户
|
||
**I want** 取消已预约但未使用的服务
|
||
**So that** 我可以退回幸福点
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] Given 订单状态为已预约(200)，When 调用取消接口，Then 券码被作废，订单状态变为400，幸福点退还
|
||
- [ ] Given 订单状态为已完成(300)，When 调用取消接口，Then 返回161014错误码
|
||
- [ ] Given 存在已过期幸福点，When 取消前查询，Then 返回过期积分提醒信息
|
||
|
||
---
|
||
|
||
### 5.3 服务完成
|
||
|
||
#### US-003: 券码核销后服务完成
|
||
|
||
**As a** 服务商系统
|
||
**I want** 在收到券码核销回调后通知邮储银行服务完成
|
||
**So that** 完成服务状态同步，确保对账数据一致
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] Given 收到蓝色兄弟核销回调(status=2)，When 处理回调，Then 在T+2日内通知邮储银行服务完成
|
||
- [ ] Given 订单状态为已取消(400)，When 通知服务完成，Then 邮储银行返回161014错误
|
||
- [ ] Given 回调验签失败，When 处理回调，Then 不触发服务完成通知
|
||
|
||
---
|
||
|
||
### 5.4 服务状态查询
|
||
|
||
#### US-004: 查询服务状态
|
||
|
||
**As a** 邮储银行服务开放平台
|
||
**I want** 查询权益服务当前状态
|
||
**So that** 展示给客户了解服务进展
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] Given 有效的权益码，When 调用状态查询接口，Then 返回正确的状态码和描述
|
||
- [ ] Given 不存在的权益码，When 调用状态查询接口，Then 返回161027错误码
|
||
|
||
---
|
||
|
||
### 5.5 月度对账
|
||
|
||
#### US-005: 下载并核对对账文件
|
||
|
||
**As a** 服务商运营人员
|
||
**I want** 每月下载邮储银行的对账文件并与本地数据核对
|
||
**So that** 确保交易数据一致性，完成结算
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] Given 每月3号，When 触发对账任务，Then 自动下载上月对账文件
|
||
- [ ] Given 对账文件下载成功，When 数据核对，Then 生成对账结果（匹配/差异）
|
||
- [ ] Given 存在对账差异，When 核对完成，Then 生成差异报告供人工处理
|
||
|
||
---
|
||
|
||
## 附录
|
||
|
||
### 附录A：专业术语说明
|
||
|
||
#### A.1 下游系统（邮储银行服务开放平台）
|
||
|
||
| 术语 | 英文 | 说明 |
|
||
|-----|------|------|
|
||
| 幸福点 | Happiness Points | 邮储银行高端客户积分，可兑换权益服务 |
|
||
| 权益码 | Rights Code | 客户兑换权益服务后获得的唯一标识码，格式如：16800G-VN4724-NX874-30VHR |
|
||
| 服务开放平台 | Open Platform | 邮储银行对外开放的API服务平台 |
|
||
| SM2 | SM2 | 国密非对称加密算法，用于密钥交换和数字签名 |
|
||
| SM3 | SM3 | 国密哈希算法，用于消息摘要 |
|
||
| SM4 | SM4 | 国密对称加密算法，用于报文加密 |
|
||
| 业务主ID | busiMainId | 请求的业务唯一标识，规则：渠道号(2位)+日期(8位)+序列号(8位) |
|
||
| 对账 | Reconciliation | 每月核对服务商与银行之间的交易数据一致性 |
|
||
| T+2 | T+2 | 服务完成后2个工作日内需完成状态同步 |
|
||
| 高端客户 | VIP Customer | 邮储银行AUM（资产管理规模）≥50万的客户 |
|
||
| AUM | Assets Under Management | 资产管理规模 |
|
||
|
||
#### A.2 服务商系统（当前系统）
|
||
|
||
| 术语 | 英文 | 说明 |
|
||
|-----|------|------|
|
||
| 合作方交易流水号 | partnerTxSriNo | 服务商生成的交易唯一标识，规则：渠道号(2位)+日期(8位)+序列号(8位) |
|
||
| 订单号 | Order No | 服务商系统内部订单唯一标识 |
|
||
| 服务状态 | Service Status | 订单服务状态：100-未预约，200-已预约，300-已完成，400-已取消，500-已过期 |
|
||
|
||
#### A.3 上游系统（蓝色兄弟营销开放API）
|
||
|
||
| 术语 | 英文 | 说明 |
|
||
|-----|------|------|
|
||
| 蓝色兄弟 | LSB (Lan Se Xiong Di) | 第三方虚拟商品供应商，提供券码服务 |
|
||
| 券码 | Coupon Key | 蓝色兄弟平台生成的虚拟商品兑换码 |
|
||
| RSA | RSA | 非对称加密算法，用于蓝色兄弟接口签名 |
|
||
| AES | AES | 对称加密算法，用于蓝色兄弟业务参数加密 |
|
||
| 外部业务号 | out_biz_no | 调用蓝色兄弟API的幂等标识，长度2~32位 |
|
||
| 交易号 | trade_no | 蓝色兄弟返回的平台交易唯一标识 |
|
||
| 活动编号 | activity_no | 蓝色兄弟平台的营销活动唯一标识 |
|
||
| 券码状态 | Key Status | 券码状态：1-正常，2-已核销，3-已作废，4-已过期 |
|
||
|
||
---
|
||
|
||
### 附录B：接口业务响应码
|
||
|
||
#### B.1 下游系统（邮储银行服务开放平台）响应码
|
||
|
||
**公共响应码**：
|
||
|
||
| 响应码 | 描述 | 处理建议 |
|
||
|-------|------|----------|
|
||
| 000000 | 交易成功 | - |
|
||
| 900000 | 未知系统异常 | 稍后重试或联系技术支持 |
|
||
| 900001 | 非法参数 | 检查请求参数格式 |
|
||
| 900002 | 必填参数缺失 | 补充必填参数 |
|
||
| 900005 | 签名错误 | 检查签名算法和密钥 |
|
||
| 900006 | 请求非法 | 检查请求格式 |
|
||
| 900008 | 幂等错误 | 检查流水号是否重复 |
|
||
| 900011 | 签名验证失败 | 检查签名和公钥 |
|
||
| 990172 | 系统繁忙 | 稍后重试 |
|
||
| 990272 | 系统繁忙 | 稍后重试 |
|
||
| 990772 | 系统繁忙 | 稍后重试 |
|
||
|
||
**权益积分业务响应码**：
|
||
|
||
| 响应码 | 描述 | 处理建议 |
|
||
|-------|------|----------|
|
||
| 161006 | 交易数据不存在 | 检查权益码或流水号 |
|
||
| 161008 | 未知渠道错误 | 检查渠道标识 |
|
||
| 161014 | 服务已完成或取消，不允许再操作 | 业务状态已终结 |
|
||
| 161016 | 无权益服务可操作 | 检查订单状态 |
|
||
| 161024 | 服务未预约，不允许完成或取消操作 | 需先完成预约 |
|
||
| 161026 | 兑换权益码已失效 | 权益码超过20分钟有效期 |
|
||
| 161027 | 兑换权益码错误 | 检查权益码格式 |
|
||
| 161033 | 实际完成时间不满足对账规范 | 检查completionTime格式 |
|
||
| 727101 | 系统异常，请稍后重试 | 稍后重试 |
|
||
| 727102 | 未查询到当前分类的积分信息 | 检查查询条件 |
|
||
| 729006 | 未找到原交易 | 检查原交易流水号 |
|
||
| 729011 | 客户名称不能为空 | 补充客户名称 |
|
||
| 729012 | 客户证件类型不能为空 | 补充证件类型 |
|
||
| 729013 | 证件号码不能为空 | 补充证件号码 |
|
||
| 729024 | 证件号码格式不正确 | 检查证件号码格式 |
|
||
| 729033 | 客户编号格式不正确 | 检查客户编号格式 |
|
||
| 720502 | 原交易流水号不能为空 | 补充原交易流水号 |
|
||
| 720503 | 原交易流水号格式不正确 | 检查流水号格式 |
|
||
| 729809 | 系统繁忙，请稍后再试 | 稍后重试 |
|
||
| 729909 | 不能为空 | 补充必填字段 |
|
||
| 729910 | 格式不正确 | 检查字段格式 |
|
||
| 729917 | 长度不符合要求 | 检查字段长度 |
|
||
| 729918 | 不能包含特殊字符 | 移除特殊字符 |
|
||
| 729922 | 查询结束时间不得小于查询开始时间 | 调整时间范围 |
|
||
| 729928 | 查询起始日期必须在12个月内 | 调整查询日期 |
|
||
|
||
**文件接口响应码**：
|
||
|
||
| 响应码 | 描述 | 处理建议 |
|
||
|-------|------|----------|
|
||
| 062005 | 查询失败，请稍后再试 | 稍后重试 |
|
||
| 063001 | 系统繁忙，请稍后再试 | 稍后重试 |
|
||
|
||
---
|
||
|
||
#### B.2 上游系统（蓝色兄弟营销开放API）响应码
|
||
|
||
**公共响应码**：
|
||
|
||
| code | reason | 描述 | 处理建议 |
|
||
|------|--------|------|----------|
|
||
| 200 | - | 成功 | - |
|
||
| 400 | SIGNATURE_FAIL | 签名错误 | 检查签名密钥和算法 |
|
||
| 400 | SDK_INI_FAIL | SDK错误 | 检查应用配置信息 |
|
||
| 400 | PARAM_FAIL | 参数错误 | 检查业务参数 |
|
||
| 400 | PARAM_DECRYPT_FAIL | 参数解密错误 | 检查加密方式 |
|
||
| 500 | PANIC | 系统错误 | 联系平台处理 |
|
||
|
||
**业务响应码**：
|
||
|
||
| code | reason | 描述 | 处理建议 |
|
||
|------|--------|------|----------|
|
||
| 401 | ACTIVITY_NOT_AUTH | 活动未授权 | 检查活动授权状态 |
|
||
| 401 | MERCHANT_NOT_EXIST | 客户不存在 | 检查客户是否存在 |
|
||
| 401 | MERCHANT_NOT_AUTH | 客户冻结 | 检查客户授权状态 |
|
||
| 401 | MERCHANT_APP_INCOMPLETE | 客户应用配置未完善 | 完善应用配置 |
|
||
| 401 | MERCHANT_APP_NOT_AUTH | 应用不存在 | 检查应用授权状态 |
|
||
| 403 | ACTIVITY_EXPIRE | 活动已结束 | 检查活动有效期 |
|
||
| 403 | ACTIVITY_NOT_AUTH | 活动状态异常 | 检查活动状态（作废/待审核/驳回/暂停/失效/编辑中） |
|
||
| 403 | ACTIVITY_OUT_OF_STOCK | 活动库存不足 | 联系平台补充库存 |
|
||
| 404 | KEY_NOT_EXIST | 券码不存在 | 检查券码或交易号 |
|
||
| 404 | ACTIVITY_NOT_EXIST | 活动不存在 | 检查活动编号 |
|
||
| 404 | MERCHANT_NOT_EXIST | 客户不存在 | 检查app_id |
|
||
| 404 | MERCHANT_APP_NOT_EXIST | 客户应用不存在 | 检查app_id |
|
||
| 404 | MERCHANT_ORDER_NOT_EXIST | 订单记录不存在 | 检查交易号/外部业务号 |
|
||
| 404 | MERCHANT_APP_INCOMPLETE | 客户应用信息未完善 | 完善应用信息 |
|
||
| 503 | KEY_CREATE_FAIL | 券码创建失败 | 稍后重试或联系平台 |
|
||
| 503 | MERCHANT_ORDER_CREATE_FAIL | 订单创建失败 | 稍后重试或联系平台 |
|
||
| 503 | MERCHANT_ORDER_DISCARD_FAIL | 订单作废失败 | 稍后重试或联系平台 |
|
||
| 503 | MERCHANT_ORDER_DISCARD_MQ_FAIL | 订单作废消息失败 | 稍后重试或联系平台 |
|
||
|
||
---
|
||
|
||
#### B.3 服务商系统（当前系统）内部错误码
|
||
|
||
| 错误码 | 描述 | 处理建议 |
|
||
|-------|------|----------|
|
||
| SYS_001 | 系统内部错误 | 检查系统日志，联系技术支持 |
|
||
| SYS_002 | 数据库操作异常 | 检查数据库连接和SQL |
|
||
| SYS_003 | 外部服务调用超时 | 检查网络连接，稍后重试 |
|
||
| BIZ_001 | 订单不存在 | 检查订单号是否正确 |
|
||
| BIZ_002 | 订单状态不允许此操作 | 检查当前订单状态 |
|
||
| BIZ_003 | 券码获取失败 | 检查上游服务状态 |
|
||
| BIZ_004 | 券码作废失败 | 检查券码当前状态 |
|
||
| BIZ_005 | 服务完成通知失败 | 检查下游服务状态，稍后重试 |
|
||
|
||
---
|
||
|
||
### 附录C：服务类型与厂商编码
|
||
|
||
#### C.1 服务类型编码
|
||
|
||
| 服务类型 | 名称 | 类别 |
|
||
|---------|------|------|
|
||
| 210001 | 口腔护理 | 健康服务 |
|
||
| 210002 | 三个月血糖管理 | 健康服务 |
|
||
| 210003 | 三个月血压管理 | 健康服务 |
|
||
| 210004 | 三个月体重管理 | 健康服务 |
|
||
| 220001 | 高铁贵宾厅 | 出行服务 |
|
||
| 220002 | 机场贵宾厅 | 出行服务 |
|
||
| 220003 | 洗车 | 出行服务 |
|
||
| 310001 | 喜马拉雅VIP巅峰会员季卡 | 虚拟会员 |
|
||
| 310002 | 知乎会员季卡 | 虚拟会员 |
|
||
| 1200 | 机场快速通道 | 出行服务 |
|
||
| 1400 | 专车服务（舒适型30公里） | 出行服务 |
|
||
| 1410 | 专车服务（商务型30公里） | 出行服务 |
|
||
| 1420 | 专车服务（舒适型50公里） | 出行服务 |
|
||
| 1430 | 专车服务（商务型50公里） | 出行服务 |
|
||
| 1500 | 代驾服务（20公里及以内） | 出行服务 |
|
||
|
||
#### C.2 服务厂商编号
|
||
|
||
| 编号 | 名称 |
|
||
|-----|------|
|
||
| A101 | 盛大 |
|
||
| B101 | 元化 |
|
||
|
||
#### C.3 渠道标识
|
||
|
||
| 渠道标识 | 名称 |
|
||
|---------|------|
|
||
| 12 | 手机银行 |
|
||
| 17 | 电话银行 |
|
||
| 18 | 微信银行 |
|
||
| 36 | you生活 |
|
||
| 46 | 北京分行 |
|