34 KiB

Raw Blame History

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

1. 功能模块划分

1.1 模块结构

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

1.2 模块关系

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

2. 公共响应规范

2.1 响应结构

所有接口统一使用以下响应结构：

{
  "code": 0,
  "msg": "成功",
  "traceId": "请求追踪ID",
  "data": {
    // 业务数据
  }
}

字段	类型	必填	说明
code	int	M	公共响应码，0表示成功，非0表示失败
msg	String	M	响应描述信息，当code!=0时为错误信息
traceId	String	M	请求追踪ID，用于问题排查
data	Object	C	业务数据，成功时返回

2.2 公共响应码

响应码	描述	说明
0	成功	业务处理成功
1	系统异常	系统内部错误，请稍后重试
2	参数错误	请求参数校验失败
3	签名错误	签名验证失败
4	业务错误	业务规则校验失败

3. 功能详细说明

3.1 接口服务模块

3.1.1 服务预约接口

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

业务规则：

对request进行AES解密，解析出type(服务编码)、code(权益码)、mac(客户id)
对code(权益码)进行幂等验证：
- 若订单状态为「服务已预约(200)」，直接返回预约成功（与正常请求返回一致）
- 若订单状态为「服务未预约(100)」，继续执行后续流程（更新订单，不新增）
- 若订单状态为其他状态，返回服务已预约
查询数据库验证服务编码(type)是否存在（数据库中维护邮储服务编码与营销平台活动的映射关系）如果不存在返回暂不支持此服务
请求邮储服务开放平台接口验证权益码是否过期如果过期： 1、CRM渠道返回 "二维码20分钟内有效，现已超时失效，请联系理财经理重新生成二维码！ 2、手机银行渠道返回 “当前页面停置时间过长，请您重新进入该页面”
创建/更新订单记录（订单状态：服务未预约）
请求邮储服务开放平台接口发起预约：
- 预约成功或返回161010(交易已预约)：继续执行步骤7
- 其他情况：订单状态保持「服务未预约(100)」，返回预约失败
请求蓝色兄弟营销平台获取券码链接（使用相同交易号和参数请求）：
- 请求成功：更新订单状态为「服务已预约(200)」，返回预约成功响应
- 请求异常：订单状态保持「服务未预约(100)」，返回预约失败

输入：

字段	类型	必填	说明
request	String	M	AES加密字符串，解密后格式：type=服务编码&code=权益码&mac=加密后的客户id
channel	String	M	渠道标识：12-手机银行，17-电话银行，41-CRM零售
tranChnl	String	M	渠道标识：12-手机银行，17-电话银行，41-CRM零售
backUrl	String	C	返回手机银行的地址，可为空
instType	String	M	客户自营代理属性：01-自营，02-代理
provinceInstNo	String	M	客户归属一分机构号

输出（data字段内容）：

字段	类型	必填	说明
url	String	M	蓝色兄弟营销平台的兑换地址
tranChnl	String	M	渠道标识
instType	String	M	客户自营代理属性
backUrl	String	C	返回手机银行的地址

验收标准：

能正确解密AES加密的request参数
能正确解析解密后的参数（type、code、mac）
预约成功后返回蓝色兄弟兑换地址(url)
响应正确透传tranChnl、instType、backUrl

3.1.2 服务取消接口

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

业务规则：

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

输入：

字段	类型	必填	说明
rightsCode	String	M	兑换预约码
serviceType	String	M	服务类型编码
providerCode	String	M	服务厂商编号

输出（data字段内容）：

字段	类型	必填	说明
tradeRespCode	String	M	业务响应码
tradeRespMsg	String	M	业务响应码描述

验收标准：

非“已预约”状态订单返回错误(161024)
已完成订单不允许取消(161014)
取消成功后蓝色兄弟券码状态为已作废(3)
取消成功后订单状态为400

3.1.3 服务完成通知接口

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

业务规则：

接收蓝色兄弟券码状态变更回调
当券码状态变为"已核销"(2)时
调用邮储银行服务完成接口
更新订单状态为"已完成"(300)
服务完成状态更新需在T+2日内完成

输入：

字段	类型	必填	说明
rightsCode	String	M	兑换预约码
serviceType	String	M	服务类型编码
providerCode	String	M	服务厂商编号
completionTime	String	M	实际完成时间，格式：yyyyMMddHHmmss

输出（data字段内容）：

字段	类型	必填	说明
-	-	-	无业务数据，仅返回公共响应

验收标准：

能正确接收蓝色兄弟回调通知
回调验签通过后正确响应"ok"
服务完成通知在T+2日内发送
已取消订单不允许完成(161014)
完成成功后订单状态为300

3.1.4 订单过期积分查询接口

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

业务规则：

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

输入：

字段	类型	必填	说明
rightsCode	String	C	兑换预约码（已预约取消场景必填）
orgTranSq	String	C	原交易流水号（已兑换未预约取消场景必填）
cstmName	String	C	客户名称
paperType	String	C	证件类型
paperId	String	C	证件号码

输出（data字段内容）：

字段	类型	必填	说明
tranIntglNum	int	C	交易总幸福点
ovdueIntglNum	int	C	已过期的幸福点
noticeMsg	String	C	提醒信息文本

验收标准：

能正确查询订单积分信息
过期幸福点计算准确
返回友好的提醒信息

3.1.5 服务状态查询接口

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

业务规则：

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

输入：

字段	类型	必填	说明
rightsCode	String	M	兑换权益码
tranChnl	String	M	渠道标识

输出（data字段内容）：

字段	类型	必填	说明
serviceState	String	M	预约服务状态码：100-未预约，200-已预约，300-已完成，400-已取消，500-已过期
serviceStateMsg	String	M	预约服务状态描述

验收标准：

能正确查询订单状态
状态码与状态描述一致

3.2 券码管理模块

3.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)
幂等请求返回相同结果
获取成功后保存券码信息

3.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	最后一次核销时间

验收标准：

能正确查询券码状态
状态信息完整准确

3.2.3 券码作废功能

功能描述：作废待使用或已过期的券码

业务规则：

只能作废待使用(1)、已过期(4)状态的券码
已核销券码不允许作废

输入：

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

验收标准：

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

3.2.4 券码状态回调接收

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

业务规则：

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

回调重试策略：

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

验收标准：

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

3.3 订单管理模块

3.3.1 订单创建

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

业务规则：

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

验收标准：

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

3.3.2 订单状态管理

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

状态定义：

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

状态流转规则：

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

验收标准：

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

3.3.3 订单查询

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

查询维度：

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

验收标准：

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

3.4 对账管理模块

3.4.1 对账文件查询

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

业务规则：

每月3号查询上月对账文件
只包含服务完成(300)状态的订单

输入：

字段	类型	必填	说明
accountingDate	String	M	会计日期，YYYYMMDD
fileIntfcName	String	M	文件接口名

验收标准：

能正确查询对账文件列表
返回文件ID、名称等完整信息

3.4.2 对账文件下载

功能描述：下载对账文件内容

输入：

字段	类型	必填	说明
fileId	String	M	文件唯一标识
fileIntfcName	String	M	文件接口名
sm4Key	String	M	对账文件SM4加密密钥

对账文件内容：

字段	说明
统计月份	YYYYMMDD
一分机构序号	-
一分机构名称	-
网点机构属性	01-自营，02-代理
积分客户服务编码	-
服务内容	-
预约时间	-
实际完成时间	-
权益兑换码	-

验收标准：

能正确解密对账文件
能解析对账文件内容
与本地订单数据核对

3.5 安全与加密模块

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

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

服务预约请求AES解密规则：

算法/模式/填充：AES/CBC/PKCS5Padding
Key长度：16位
IV长度：16位
编码方式：Base64
解密后格式：type=服务编码&code=权益码&mac=加密后的客户id

服务开放平台SM4加密规则：

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

服务开放平台签名规则：

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

验收标准：

AES解密正确（服务预约请求）
SM4加解密正确
SM2加解密正确
SM3签名验签正确

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

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

业务参数加密规则：

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

签名规则：

拼接：appId + timestamp + ciphertext
使用私钥RSA签名

验收标准：

AES加解密正确
RSA签名验签正确
回调验签正确

4. 数据需求

4.1 数据实体

4.1.1 订单表(ycjfsc_order)

字段名	类型	长度	必填	说明
id	bigint	20	M	主键
order_no	varchar	32	M	系统内部订单号
code	varchar	32	M	权益码(邮储订单号)
out_trade_no	varchar	32	N	请求上游营销平台的交易号
partner_tx_sri_no	varchar	24	M	请求邮储服务平台的流水号
type	varchar	6	M	服务类型
provider_code	varchar	4	M	服务商编号（邮储分配的固定值）
status	int	3	M	内部订单状态：0异常 100 未预约 200已预约 300已完成 400已取消 500已过期

| appointment_time | datetime | - | N | 预约成功时间 | | mac | varchar | 40 | N | 加密后的客户id | | channel | varchar | 4 | M | 渠道标识：12-手机银行，17-电话银行，41-CRM零售 | | tran_chnl | varchar | 4 | M | 渠道标识：12-手机银行，17-电话银行，41-CRM零售 | | back_url | varchar | 256 | N | 返回手机银行的地址 | | inst_type | varchar | 2 | M | 客户自营代理属性：01-自营，02-代理 | | province_inst_no | varchar | 20 | M | 客户归属一分机构号 | | key_code | varchar | 64 | N | 券码 | | url | varchar | 125 | N | 短链接 | | key_status | int | 1 | N | 券码状态：0-待生成 1-正常，2-已核销，3-已作废，4-已过期 | | key_issue_time | datetime | - | N | key码发放成功时间 | | activity_no | varchar | 32 | N | 活动编号 | | key_valid_begin_time | datetime | - | N | 券码有效期开始 | | key_valid_end_time | datetime | - | N | 券码有效期结束 | | key_usage_time | datetime | - | N | 核销时间 | | key_discard_time | datetime | - | N | 作废时间 | | update_time | datetime | - | M | 更新时间 | | create_time | datetime | - | M | 创建时间 |

4.1.2 对账记录表(ycjfsc_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	更新时间

4.1.3 服务编码映射表(ycjfsc_service_activity_mapping)

字段名	类型	长度	必填	说明
id	bigint	20	M	主键
service_type	varchar	6	M	邮储服务编码
service_name	varchar	64	M	服务名称
activity_no	varchar	32	M	营销平台活动编号
activity_name	varchar	64	N	活动名称
aes_key	varchar	32	M	AES加密密钥（16位）
aes_iv	varchar	32	M	AES加密向量（16位）
create_time	datetime	-	M	创建时间
update_time	datetime	-	M	更新时间

4.2 数据规则

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

5. 非功能性需求

5.1 性能要求

5.1.1 响应时间要求

接口类型	P95	P99	说明
服务预约接口	< 300ms	< 500ms	含上游券码获取
服务取消接口	< 200ms	< 400ms	含上游券码作废
服务状态查询接口	< 100ms	< 200ms	优先读缓存
券码状态回调接口	< 100ms	< 200ms	快速响应后异步处理

5.1.2 并发处理能力

指标	要求	说明
日常TPS	≥ 100	正常业务峰值
峰值TPS	≥ 500	活动期间峰值
单机QPS	≥ 200	支持水平扩展

5.1.3 缓存设计

缓存策略：

缓存对象	缓存类型	过期策略	更新策略	说明
服务编码映射表	本地缓存 + Redis	本地5分钟，Redis 30分钟	配置变更主动刷新	高频读取，变更少
订单信息	Redis	24小时	状态变更时更新	按权益码缓存
券码信息	Redis	跟随订单	状态变更时更新	与订单关联存储
邮储AccessToken	Redis	有效期前5分钟刷新	定时刷新	避免过期

缓存Key设计：

# 服务编码映射
ycjfsc:service:mapping:{serviceType}

# 订单缓存（按权益码）
ycjfsc:order:code:{rightsCode}

# 订单缓存（按订单号）
ycjfsc:order:no:{orderNo}

# AccessToken
ycjfsc:token:psbc

缓存穿透防护：

空值缓存：查询不存在的数据时缓存空值，过期时间60秒
布隆过滤器：权益码存在性预判（可选）

5.1.4 高质量代码实现要求

连接池管理：HTTP客户端、数据库、Redis均需配置合理的连接池
超时控制：所有外部调用设置合理超时（连接超时3s，读超时10s）
熔断降级：上游服务异常时快速失败，避免雪崩
异步处理：非核心链路异步化（如日志记录、监控上报）
批量操作：对账等批量场景使用批量查询/更新

5.2 数据一致性要求

5.2.1 核心一致性场景

场景描述：蓝色兄弟券码已核销（用户已完成充值兑换），必须通知邮储银行服务完成，否则会造成资金损失。

风险点：

回调通知邮储失败
回调成功但本地状态更新失败
系统宕机导致通知丢失

5.2.2 一致性保障机制

机制一：异步消息 + 最终一致

1. 接收蓝色兄弟核销回调
2. 更新订单状态为「待通知」(250)，记录核销时间
3. 立即响应蓝色兄弟"ok"（快速响应，避免超时）
4. 异步处理：
   - 调用邮储服务完成接口
   - 成功：更新订单状态为「已完成」(300)
   - 失败：保留状态250，等待重试机制处理

说明：不使用本地事务，通过重试+补偿+对账三重机制保证最终一致性。

机制二：消息重试策略

重试次数	间隔时间	累计时间
第1次	10秒	10秒
第2次	30秒	40秒
第3次	1分钟	1分40秒
第4次	5分钟	6分40秒
第5次	10分钟	16分40秒
第6次	30分钟	46分40秒
第7次	1小时	1小时46分40秒
第8次	2小时	3小时46分40秒

超过8次仍失败，标记为「通知异常」(350)，人工介入处理。

机制三：定时补偿任务

任务	执行频率	处理逻辑
待通知订单扫描	每5分钟	扫描状态=250且超过1分钟未处理的订单，重新发起通知
异常订单告警	每10分钟	扫描状态=350的订单，发送告警通知
券码状态同步	每小时	查询蓝色兄弟券码状态，同步本地订单状态

机制四：对账兜底

每日凌晨对账：比对本地「已核销」订单与邮储「已完成」状态
发现不一致：自动重新发起服务完成通知
月度对账：与邮储对账文件核对，确保无遗漏

5.2.3 订单状态扩展

为支持一致性保障，扩展订单状态：

状态码	状态名称	说明
100	服务未预约	已兑换但未预约
200	服务已预约	已预约待使用
250	待通知邮储	券码已核销，待通知邮储
300	服务已完成	券码已核销且已通知邮储
350	通知异常	通知邮储多次失败，需人工处理
400	服务已取消	用户主动取消
500	服务已过期	超过有效期未使用

5.2.4 幂等性设计

接口/操作	幂等键	幂等策略
服务预约	权益码(code)	相同权益码重复请求返回相同结果
服务取消	权益码(rightsCode)	已取消订单重复请求直接返回成功
服务完成通知	权益码(rightsCode)	已完成订单重复请求直接返回成功
券码获取	外部业务号(out_biz_no)	相同业务号返回相同券码
回调处理	交易号(trade_no)	相同交易号仅处理一次

5.2.5 数据一致性监控

告警指标：

指标	阈值	告警级别
待通知订单积压	> 10笔	P2
通知异常订单	> 0笔	P1
通知失败率	> 1%	P2
对账差异	> 0笔	P1

5.3 可用性要求

指标	要求
系统可用性	≥ 99.9%
单点故障	无单点，支持多实例部署
故障恢复	RTO < 5分钟，RPO = 0

5.4 安全要求

传输安全：所有外部通信使用HTTPS
数据脱敏：日志中客户敏感信息脱敏处理
密钥管理：加密密钥通过配置中心管理，定期轮换
访问控制：接口签名验证，防止非法调用

6. 流程图

6.1 服务预约流程

TODO

6.2 服务完成流程

TODO

6.3 服务取消流程

TODO

6.4 月度对账流程

TODO

6.5 错误处理流程

TODO

附录

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

34 KiB Raw Blame History Unescape Escape

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

1. 功能模块划分

1.1 模块结构

1.2 模块关系

2. 公共响应规范

2.1 响应结构

2.2 公共响应码

3. 功能详细说明

3.1 接口服务模块

3.1.1 服务预约接口

3.1.2 服务取消接口

3.1.3 服务完成通知接口

3.1.4 订单过期积分查询接口

3.1.5 服务状态查询接口

3.2 券码管理模块

3.2.1 券码获取功能

3.2.2 券码查询功能

3.2.3 券码作废功能

3.2.4 券码状态回调接收

3.3 订单管理模块

3.3.1 订单创建

3.3.2 订单状态管理

3.3.3 订单查询

3.4 对账管理模块

3.4.1 对账文件查询

3.4.2 对账文件下载

3.5 安全与加密模块

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

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

4. 数据需求

4.1 数据实体

4.1.1 订单表(ycjfsc_order)

4.1.2 对账记录表(ycjfsc_reconciliation)

4.1.3 服务编码映射表(ycjfsc_service_activity_mapping)

4.2 数据规则

5. 非功能性需求

5.1 性能要求

5.1.1 响应时间要求

5.1.2 并发处理能力

5.1.3 缓存设计

5.1.4 高质量代码实现要求

5.2 数据一致性要求

5.2.1 核心一致性场景

5.2.2 一致性保障机制

5.2.3 订单状态扩展

5.2.4 幂等性设计

5.2.5 数据一致性监控

5.3 可用性要求

5.4 安全要求

6. 流程图

6.1 服务预约流程

6.2 服务完成流程

6.3 服务取消流程

6.4 月度对账流程

6.5 错误处理流程

附录

附录A：专业术语说明

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

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

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

附录B：接口业务响应码

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

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

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

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

C.1 服务类型编码

C.2 服务厂商编号

C.3 渠道标识

34 KiB

Raw Blame History