diff --git a/.qoder/rules/requirements.md b/.qoder/rules/requirements.md index 5823ef5..5a96fba 100644 --- a/.qoder/rules/requirements.md +++ b/.qoder/rules/requirements.md @@ -7,12 +7,35 @@ description: 生成需求文档的时候需要 ## 文档结构要求 -必须且仅包含以下4个章节,顺序固定: +必须且仅包含以下6个章节,顺序固定: 1. **功能模块划分**: 明确的模块结构和模块关系 2. **功能详细说明**: 每个功能的具体描述、业务规则、验收标准 -3. **数据需求**: 数据实体、字段定义、数据规则 -4. **流程图**: 使用 PlantUml 语法实现,清晰展示业务流程和逻辑 +3. **用户故事**: 从用户视角描述需求和期望价值 +4. **数据需求**: 数据实体、字段定义、数据规则 +5. **流程图**: 使用 PlantUml 语法实现,清晰展示业务流程和逻辑 +6. **附录**: 业务术语表及其他补充说明 + +## 用户故事格式 + +采用标准用户故事格式: + +``` +作为 [用户角色]，我希望 [功能需求]，以便 [业务价值] +``` + +- **用户角色**: 明确的角色定义（如：普通用户、管理员、运营人员） +- **功能需求**: 具体的功能期望 +- **业务价值**: 该功能带来的价值或解决的问题 + +## 附录要求 + +### 业务术语表 + +| 术语 | 定义 | 示例 | +|------|------|------| +| 术语名称 | 准确的业务定义 | 具体使用示例 | + ## 需求描述要求 diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..82fc3d2 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,7 @@ +{ + "plantuml.commandArgs": [ + + ], + "plantuml.server": "https://www.plantuml.com/plantuml" +} + diff --git a/docs/待办 b/docs/待办 new file mode 100644 index 0000000..1bf0c92 --- /dev/null +++ b/docs/待办 @@ -0,0 +1,7 @@ +1、确认每个接口的需求、业务逻辑、字段规则、相关数据表、状态流转、参数、返回值、状态码、错误信息是否正常 + +2、检查是否存在未处理的异常情况 +3、检查是否存在未处理的边界情况 +4、检查是否存在未处理的错误信息 +5、确保不会造成亏损 +6、确保对账单的准确性 diff --git a/docs/需求概述.md b/docs/需求概述.md new file mode 100644 index 0000000..3da2685 --- /dev/null +++ b/docs/需求概述.md @@ -0,0 +1,1058 @@ +# 虚拟商品充值服务商系统 - 产品需求文档 + +## 1. 功能模块划分 + +### 1.1 模块结构 + +``` +服务商系统 +├── 接口服务模块（对接邮储银行服务开放平台） +│ ├── 服务预约接口 +│ ├── 服务取消接口 +│ ├── 服务完成通知接口 +│ ├── 订单过期积分查询接口 +│ └── 服务状态查询接口 +├── 券码管理模块（对接蓝色兄弟营销开放API） +│ ├── 券码获取功能 +│ ├── 券码查询功能 +│ ├── 券码作废功能 +│ └── 券码状态回调接收 +├── 订单管理模块 +│ ├── 订单创建 +│ ├── 订单状态管理 +│ ├── 订单查询 +│ └── 订单对账 +├── 对账管理模块 +│ ├── 对账文件查询 +│ ├── 对账文件下载 +│ └── 对账数据核对 +└── 安全与加密模块 + ├── SM2/SM4加解密（邮储银行） + ├── RSA/AES加解密（蓝色兄弟） + └── 签名验签 +``` + +### 1.2 模块关系 + +| 模块 | 上游依赖 | 下游依赖 | 说明 | +|------|---------|---------|------| +| 接口服务模块 | 邮储银行服务开放平台 | 订单管理模块、券码管理模块 | 接收邮储银行请求，转发至内部处理 | +| 券码管理模块 | 订单管理模块 | 蓝色兄弟营销开放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 | 北京分行 | diff --git a/trans_hub b/trans_hub new file mode 160000 index 0000000..58ca26a --- /dev/null +++ b/trans_hub @@ -0,0 +1 @@ +Subproject commit 58ca26af6747fbd1fe2ca358fa2311d22c7051f9