33 KiB

Raw Blame History

虚拟商品充值服务商系统 - 产品需求文档

1. 功能模块划分

1.1 模块结构

服务商系统
├── 接口服务模块（对接邮储银行服务开放平台）
│   ├── 服务预约接口
│   ├── 服务取消接口
│   ├── 服务完成通知接口
│   ├── 订单过期积分查询接口
│   └── 服务状态查询接口
├── 券码管理模块（对接蓝色兄弟营销开放API）
│   ├── 券码获取功能
│   ├── 券码查询功能
│   ├── 券码作废功能
│   └── 券码状态回调接收
├── 订单管理模块
│   ├── 订单创建
│   ├── 订单状态管理
│   ├── 订单查询
│   └── 订单对账
├── 对账管理模块
│   ├── 对账文件查询
│   ├── 对账文件下载
│   └── 对账数据核对
└── 安全与加密模块
    ├── SM2/SM4加解密（邮储银行）
    ├── RSA/AES加解密（蓝色兄弟）
    └── 签名验签

1.2 模块关系

模块	调用方/被调用方	内部依赖	说明
接口服务模块	被下游邮储银行调用	订单管理模块、券码管理模块	接收邮储银行请求，转发至内部处理
券码管理模块	调用上游蓝色兄弟API	订单管理模块	负责券码全生命周期管理
订单管理模块	-	券码管理模块、对账管理模块	核心业务数据管理
对账管理模块	调用下游邮储银行API	订单管理模块	月度对账处理
安全与加密模块	-	所有模块	提供安全基础能力

2. 功能详细说明

2.1 接口服务模块

2.1.1 服务预约接口

功能描述：接收邮储银行服务开放平台的预约请求，为客户预约虚拟商品充值服务

业务规则：

解密请求报文，验证签名
校验权益码有效性（20分钟有效期）
调用蓝色兄弟API获取券码
创建订单记录，状态设为"已预约"(200)
返回预约成功响应

输入：

字段	类型	必填	说明
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 服务取消接口

功能描述：接收邮储银行服务开放平台的取消请求，取消已预约的服务

业务规则：

校验订单状态必须为"已预约"(200)
调用蓝色兄弟API作废券码
更新订单状态为"已取消"(400)
返回取消成功响应

输入：

字段	类型	必填	说明
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 服务完成通知接口

功能描述：接收蓝色兄弟券码核销回调，主动通知邮储银行服务完成

业务规则：

接收蓝色兄弟券码状态变更回调
当券码状态变为"已核销"(2)时
调用邮储银行服务完成接口
更新订单状态为"已完成"(300)
服务完成状态更新需在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 订单过期积分查询接口

功能描述：查询订单退还时已过期的幸福点信息，用于取消前提醒客户

业务规则：

根据权益码或原交易流水号查询订单
计算订单涉及的总幸福点
计算已过期的幸福点数量
返回过期幸福点提醒信息

输入：

字段	类型	必填	说明
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 服务状态查询接口

功能描述：根据权益码查询服务预约状态

业务规则：

根据权益码查询订单
返回当前服务状态

输入：

字段	类型	必填	说明
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获取虚拟商品券码

业务规则：

生成唯一外部业务号(out_biz_no)
构造请求参数并AES加密
使用RSA私钥签名
调用获取券码接口
保存券码信息与订单关联

输入：

字段	类型	必填	说明
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 券码查询功能

功能描述：查询已获取券码的当前状态

业务规则：

支持通过外部业务号或交易号查询
返回券码完整状态信息

输入：

字段	类型	必填	说明
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)、已过期(4)状态的券码
已核销券码不允许作废

输入：

字段	类型	必填	说明
out_biz_no	String	C	外部业务号，与trade_no二选一
trade_no	String	C	交易号，优先使用

验收标准：

正常状态券码能成功作废
已核销券码作废返回错误
作废成功后券码状态为3

2.2.4 券码状态回调接收

功能描述：接收蓝色兄弟的券码状态变更通知

业务规则：

验证回调签名
解析回调数据
更新本地券码状态
当status=2(已核销)时触发服务完成通知
响应httpCode=200和字符串"ok"

回调重试策略：

首次间隔120s
第二次间隔240s
第三次间隔360s
大于5分钟后间隔5分钟
大于10分钟后间隔10分钟
超过120分钟后不再重试

验收标准：

能正确验证回调签名
状态更新及时准确
核销状态触发服务完成通知
响应格式正确(httpCode=200, body="ok")

2.3 订单管理模块

2.3.1 订单创建

功能描述：创建权益服务订单

业务规则：

生成唯一订单号
关联权益码、券码、客户信息
初始状态为"已预约"(200)

验收标准：

订单号全局唯一
订单信息完整

2.3.2 订单状态管理

功能描述：管理订单全生命周期状态流转

状态定义：

状态码	状态名称	说明
100	服务未预约	已兑换但未预约
200	服务已预约	已预约待使用
300	服务已完成	券码已核销
400	服务已取消	用户主动取消
500	服务已过期	超过90天未预约

状态流转规则：

200(已预约) → 300(已完成)：券码核销
200(已预约) → 400(已取消)：用户取消
300(已完成) 和 400(已取消) 为终态，不可变更

验收标准：

状态流转符合规则
终态不可变更
状态变更有日志记录

2.3.3 订单查询

功能描述：支持多维度订单查询

查询维度：

按权益码查询
按订单号查询
按客户信息查询
按状态查询
按时间范围查询

验收标准：

支持所有查询维度
查询结果准确

2.4 对账管理模块

2.4.1 对账文件查询

功能描述：查询邮储银行生成的对账文件列表

业务规则：

每月3号查询上月对账文件
只包含服务完成(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）

功能描述：实现与邮储银行通信的加解密

加密规则：

随机生成SM4 key
使用SM4 key对请求报文加密（CBC模式）
使用邮储银行公钥SM2加密SM4 key

签名规则：

拼接：request + encryptKey + accessToken
使用SM3计算摘要
使用私钥SM2加密摘要

验收标准：

SM4加解密正确
SM2加解密正确
SM3签名验签正确

2.5.2 蓝色兄弟加解密（RSA/AES）

功能描述：实现与蓝色兄弟通信的加解密

业务参数加密规则：

业务参数去掉"零"值
按字母排序转成JSON字符串
使用应用key进行AES加密

签名规则：

拼接：appId + timestamp + ciphertext
使用私钥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 数据规则

订单号生成规则：渠道号(2位) + 日期(8位) + 序列号(8位)
外部业务号生成规则：订单号 + 随机数(4位)，保证唯一性和幂等性
状态流转：只允许 200→300、200→400 的状态变更
数据保留：订单数据保留至少2年

4. 流程图

4.1 服务预约流程

@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 服务完成流程

@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 服务取消流程

@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 月度对账流程

@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 错误处理流程

@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	北京分行

33 KiB Raw Blame History Unescape Escape

虚拟商品充值服务商系统 - 产品需求文档

1. 功能模块划分

1.1 模块结构

1.2 模块关系

2. 功能详细说明

2.1 接口服务模块

2.1.1 服务预约接口

2.1.2 服务取消接口

2.1.3 服务完成通知接口

2.1.4 订单过期积分查询接口

2.1.5 服务状态查询接口

2.2 券码管理模块

2.2.1 券码获取功能

2.2.2 券码查询功能

2.2.3 券码作废功能

2.2.4 券码状态回调接收

2.3 订单管理模块

2.3.1 订单创建

2.3.2 订单状态管理

2.3.3 订单查询

2.4 对账管理模块

2.4.1 对账文件查询

2.4.2 对账文件下载

2.5 安全与加密模块

2.5.1 邮储银行加解密（SM2/SM4）

2.5.2 蓝色兄弟加解密（RSA/AES）

3. 数据需求

3.1 数据实体

3.1.1 订单表(t_order)

3.1.2 券码表(t_coupon)

3.1.3 对账记录表(t_reconciliation)

3.2 数据规则

4. 流程图

4.1 服务预约流程

4.2 服务完成流程

4.3 服务取消流程

4.4 月度对账流程

4.5 错误处理流程

5. 用户故事

5.1 服务预约

US-001: 预约虚拟商品服务

5.2 服务取消

US-002: 取消已预约服务

5.3 服务完成

US-003: 券码核销后服务完成

5.4 服务状态查询

US-004: 查询服务状态

5.5 月度对账

US-005: 下载并核对对账文件

附录

附录A：专业术语说明

A.1 下游系统（邮储银行服务开放平台）

A.2 服务商系统（当前系统）

A.3 上游系统（蓝色兄弟营销开放API）

附录B：接口业务响应码

B.1 下游系统（邮储银行服务开放平台）响应码

B.2 上游系统（蓝色兄弟营销开放API）响应码

B.3 服务商系统（当前系统）内部错误码

附录C：服务类型与厂商编码

C.1 服务类型编码

C.2 服务厂商编号

C.3 渠道标识

33 KiB

Raw Blame History