Files

T

vifo 7fdd93fc4b docs: 补充支付设计文档、store 字段设计文档及实施计划

2026-06-09 02:02:21 +08:00

23 KiB

Raw Blame History

支付服务（Payment）设计文档

设计日期: 2026-06-08 版本: v1.0 状态: 设计中 适用前端: admin-ui（管理后台）、管理 APP（接口一致） 后端服务: rui-payment-api（端口 9401，网关路径 /payment/**） 后端状态: ⏳ 预留，API 细节待补充

一、背景与目标

1.1 现状

收银系统（rui-cashier）已完成基础订单流程（开台、结账、退款），支付环节目前使用占位接口。需要建立独立的支付服务（rui-payment-api），作为聚合支付网关，统一对接多种第三方支付通道。

1.2 目标

聚合支付网关：统一下单，按支付方式（微信、支付宝、银行卡等）自动路由到对应通道
多通道可配置：支持同时配置多个第三方支付平台，按门店/场景灵活启用
商户进件：商户在我们平台提交进件申请 → 平台审核 → 向第三方（微信、支付宝）提交进件 → 状态跟踪
多端一致：管理后台（Web）和管理 APP 共享同一套后端接口，前端按各自框架实现

1.3 不在范围内

团购券/优惠券核销
会员余额/储值卡支付
对账、清算（后续迭代）
顾客端支付流程（由 cashier-customer 负责，调用本服务下单接口）

二、整体架构

┌───────────────────────────────────────────────────────┐
│                       前端层                           │
├─────────────────────┬─────────────────────────────────┤
│   管理后台 (admin-ui)│      管理 APP (uni-app)         │
│   Vue3 + Element    │      Vue3 语法                   │
├─────────────────────┴─────────────────────────────────┤
│              共享同一套后端 API                          │
│              /payment/admin/**                         │
└────────────────────────┬──────────────────────────────┘
                         │
                         ▼
┌────────────────────────────────────────────────────────┐
│                 rui-gateway (:9300)                     │
│              路由：/payment/** → rui-payment-api        │
└────────────────────────┬───────────────────────────────┘
                         │
                         ▼
┌────────────────────────────────────────────────────────┐
│              rui-payment-api (:9401)                    │
├────────────┬──────────────┬──────────────┬─────────────┤
│  商户管理   │  商户进件     │  支付通道管理  │  交易管理   │
│  Merchant  │  Onboarding  │  Channel     │  Transaction│
├────────────┴──────────────┴──────────────┴─────────────┤
│                  统一下单引擎                            │
│       按 payType 路由到对应第三方支付通道                  │
├────────────────────────────────────────────────────────┤
│   微信支付通道  │  支付宝通道  │  银行卡通道（预留）      │
└────────────────────────────────────────────────────────┘

三、菜单与权限

3.1 菜单结构

{
  "name": "payment",
  "menus": [
    {
      "code": "payment",
      "name": "支付管理",
      "type": 1,
      "icon": "tabler:credit-card",
      "sortNo": 110,
      "children": [
        {
          "code": "payment-merchant",
          "name": "商户管理",
          "type": 2,
          "icon": "tabler:building-bank",
          "path": "/payment/merchant",
          "permission": "payment:merchant:list",
          "sortNo": 1,
          "buttons": [
            { "code": "btn:add", "name": "新增", "permission": "payment:merchant:add" },
            { "code": "btn:edit", "name": "编辑", "permission": "payment:merchant:edit" },
            { "code": "btn:del", "name": "删除", "permission": "payment:merchant:delete" },
            { "code": "btn:detail", "name": "详情", "permission": "payment:merchant:detail" }
          ]
        },
        {
          "code": "payment-onboarding",
          "name": "商户进件",
          "type": 2,
          "icon": "tabler:clipboard-check",
          "path": "/payment/onboarding",
          "permission": "payment:onboarding:list",
          "sortNo": 2,
          "buttons": [
            { "code": "btn:apply", "name": "提交进件", "permission": "payment:onboarding:apply" },
            { "code": "btn:audit", "name": "审核", "permission": "payment:onboarding:audit" },
            { "code": "btn:submit", "name": "提交第三方", "permission": "payment:onboarding:submit" },
            { "code": "btn:detail", "name": "详情", "permission": "payment:onboarding:detail" }
          ]
        },
        {
          "code": "payment-channel",
          "name": "支付通道",
          "type": 2,
          "icon": "tabler:route",
          "path": "/payment/channel",
          "permission": "payment:channel:list",
          "sortNo": 3,
          "buttons": [
            { "code": "btn:add", "name": "新增", "permission": "payment:channel:add" },
            { "code": "btn:edit", "name": "编辑", "permission": "payment:channel:edit" },
            { "code": "btn:status", "name": "启停", "permission": "payment:channel:status" }
          ]
        },
        {
          "code": "payment-transaction",
          "name": "交易记录",
          "type": 2,
          "icon": "tabler:receipt",
          "path": "/payment/transaction",
          "permission": "payment:transaction:list",
          "sortNo": 4
        }
      ]
    }
  ]
}

3.2 权限标识汇总

模块	权限标识	说明
商户	`payment:merchant:list`	查询商户列表
商户	`payment:merchant:add`	新增商户
商户	`payment:merchant:edit`	编辑商户
商户	`payment:merchant:delete`	删除商户
商户	`payment:merchant:detail`	查看商户详情
进件	`payment:onboarding:list`	查询进件列表
进件	`payment:onboarding:apply`	提交进件申请
进件	`payment:onboarding:audit`	审核进件
进件	`payment:onboarding:submit`	提交至第三方
进件	`payment:onboarding:detail`	查看进件详情
通道	`payment:channel:list`	查询支付通道
通道	`payment:channel:add`	新增通道配置
通道	`payment:channel:edit`	编辑通道配置
通道	`payment:channel:status`	启用/禁用通道
交易	`payment:transaction:list`	查询交易记录

四、商户管理

4.1 页面结构

列表页 /payment/merchant

字段	类型	宽度	说明
merchantNo	string	150	商户编号（系统生成）
merchantName	string	150	商户名称
contactName	string	120	联系人
contactPhone	string	130	联系电话
channelCount	number	100	已开通通道数
status	enum	100	状态
createTime	datetime	160	创建时间

查询条件：商户编号、商户名称、状态

操作按钮：新增、编辑、详情、删除

详情页/弹窗：展示商户基础信息 + 已开通通道列表 + 进件记录

4.2 字段定义

interface MerchantDTO {
  id: number
  /** 商户编号（系统生成，如 M202606080001） */
  merchantNo: string
  /** 商户名称 */
  merchantName: string
  /** 商户简称 */
  merchantShortName: string
  /** 联系人 */
  contactName: string
  /** 联系电话 */
  contactPhone: string
  /** 联系邮箱 */
  contactEmail?: string
  /** 商户地址 */
  address?: string
  /** 备注 */
  remark?: string
  /** 状态：0-禁用 1-启用 */
  status: number
  /** 已开通通道数（只读） */
  channelCount?: number
  createTime: string
  updateTime: string
}

4.3 状态枚举

值	名称	说明
0	禁用	商户被禁用，无法交易
1	启用	正常状态

五、商户进件

5.1 业务流程

商户提交进件申请
       │
       ▼
  平台初审（内部审核）
       │
   ┌───┴───┐
   │       │
 驳回    通过
   │       │
   ▼       ▼
 退回     提交第三方
 修改        │
        ┌───┴───┐
        │       │
     进件中   进件失败
        │       │
        ▼       ▼
     进件成功  查看原因 → 修改后重新提交

5.2 页面结构

列表页 /payment/onboarding

字段	类型	宽度	说明
merchantName	string	150	商户名称
channelName	string	120	目标通道
submitterName	string	120	提交人
status	enum	120	进件状态
auditStatus	enum	120	内部审核状态
thirdPartyStatus	enum	120	第三方状态
submitTime	datetime	160	提交时间
updateTime	datetime	160	更新时间

查询条件：商户名称、目标通道、进件状态、提交时间范围

操作按钮：提交进件、审核、提交第三方、查看详情

进件申请弹窗/页面：

分步表单，包含以下信息区域：

5.2.1 基础信息

字段	类型	必填	说明
merchantId	select	✅	关联商户（下拉选择）
channelType	select	✅	目标通道（微信/支付宝/银行卡）
merchantType	select	✅	商户类型（企业/个体工商户/小微商户）
merchantName	input	✅	商户名称（营业执照上的名称）
merchantShortName	input	✅	商户简称（对外展示）
licenseNo	input	✅	营业执照号
licenseExpireDate	date	✅	营业执照有效期
licensePhoto	upload	✅	营业执照照片

5.2.2 法人信息

字段	类型	必填	说明
legalPersonName	input	✅	法人姓名
legalPersonIdNo	input	✅	法人身份证号
legalPersonIdFront	upload	✅	身份证正面
legalPersonIdBack	upload	✅	身份证反面
legalPersonIdExpire	date	✅	身份证有效期

5.2.3 结算信息

字段	类型	必填	说明
settleType	select	✅	结算方式（对公/对私）
bankName	input	✅	开户银行
bankBranch	input	✅	开户支行
bankAccountNo	input	✅	银行账号
bankAccountName	input	✅	户名
bankLicensePhoto	upload	条件	开户许可证（对公必填）

5.2.4 其他材料

字段	类型	必填	说明
storePhotos	upload	✅	门店照片（支持多张）
extraMaterials	upload	❌	补充材料（支持多张）
remark	textarea	❌	备注

5.3 字段定义

interface MerchantOnboardingDTO {
  id: number
  /** 关联商户 ID */
  merchantId: number
  /** 目标通道类型 */
  channelType: ChannelType
  /** 商户类型：1-企业 2-个体工商户 3-小微商户 */
  merchantType: number
  /** 商户名称（营业执照） */
  merchantName: string
  /** 商户简称 */
  merchantShortName: string
  /** 营业执照号 */
  licenseNo: string
  /** 营业执照有效期 */
  licenseExpireDate: string
  /** 营业执照照片（文件 ID） */
  licensePhoto: number
  /** 法人姓名 */
  legalPersonName: string
  /** 法人身份证号 */
  legalPersonIdNo: string
  /** 身份证正面（文件 ID） */
  legalPersonIdFront: number
  /** 身份证反面（文件 ID） */
  legalPersonIdBack: number
  /** 身份证有效期 */
  legalPersonIdExpire: string
  /** 结算方式：1-对公 2-对私 */
  settleType: number
  /** 开户银行 */
  bankName: string
  /** 开户支行 */
  bankBranch: string
  /** 银行账号 */
  bankAccountNo: string
  /** 户名 */
  bankAccountName: string
  /** 开户许可证（文件 ID，对公必填） */
  bankLicensePhoto?: number
  /** 门店照片（文件 ID 数组） */
  storePhotos: number[]
  /** 补充材料（文件 ID 数组） */
  extraMaterials?: number[]
  /** 内部审核状态 */
  auditStatus: AuditStatus
  /** 第三方进件状态 */
  thirdPartyStatus: ThirdPartyStatus
  /** 第三方返回的商户号 */
  thirdPartyMerchantNo?: string
  /** 第三方返回原因（失败时） */
  thirdPartyRejectReason?: string
  /** 审核人 */
  auditorName?: string
  /** 审核时间 */
  auditTime?: string
  /** 审核意见 */
  auditRemark?: string
  /** 提交人 */
  submitterName?: string
  /** 提交时间 */
  submitTime?: string
  remark?: string
  createTime: string
  updateTime: string
}

5.4 状态枚举

内部审核状态 AuditStatus

值	名称	说明
0	待提交	草稿，尚未提交审核
1	待审核	已提交，等待平台审核
2	审核通过	平台审核通过
3	审核驳回	平台审核驳回，可修改后重新提交

第三方进件状态 ThirdPartyStatus

值	名称	说明
0	未提交	尚未提交至第三方
1	审核中	第三方审核中
2	进件成功	第三方审核通过，获得商户号
3	进件失败	第三方审核驳回
4	已冻结	第三方冻结商户

5.5 交互规则

提交进件：填写信息 → 提交内部审核（状态 → 待审核）
内部审核：审核通过 → 状态变为审核通过；驳回 → 填写原因，状态变为审核驳回
提交第三方：审核通过后，可提交至第三方（状态 → 审核中）
状态同步：第三方回调更新状态（成功/失败）
重新提交：审核驳回或第三方失败时，可修改后重新走流程

六、支付通道管理

6.1 页面结构

列表页 /payment/channel

字段	类型	宽度	说明
channelName	string	150	通道名称
channelType	enum	120	通道类型
channelProvider	string	150	通道提供方
merchantCount	number	100	关联商户数
status	enum	100	状态
createTime	datetime	160	创建时间

查询条件：通道名称、通道类型、状态

操作按钮：新增通道、编辑、启用/禁用

通道配置弹窗：

字段	类型	必填	说明
channelName	input	✅	通道名称（如"微信支付-主通道"）
channelType	select	✅	通道类型（见枚举）
channelProvider	select	✅	通道提供方（微信/支付宝/银联等）
appId	input	✅	应用 ID（AppId/MchId）
merchantId	input	✅	商户号
apiVersion	input	❌	API 版本
certFile	upload	条件	证书文件（部分通道需要）
notifyUrl	input	✅	回调通知地址
remark	textarea	❌	备注
status	radio	✅	状态（启用/禁用）

6.2 字段定义

interface PayChannelDTO {
  id: number
  /** 通道名称 */
  channelName: string
  /** 通道类型 */
  channelType: ChannelType
  /** 通道提供方 */
  channelProvider: string
  /** 应用 ID */
  appId: string
  /** 商户号 */
  merchantId: string
  /** API 版本 */
  apiVersion?: string
  /** 证书文件（文件 ID） */
  certFile?: number
  /** 回调通知地址 */
  notifyUrl: string
  /** 关联商户数（只读） */
  merchantCount?: number
  /** 状态：0-禁用 1-启用 */
  status: number
  remark?: string
  createTime: string
  updateTime: string
}

6.3 状态枚举

通道类型 ChannelType

值	名称	说明
WECHAT	微信支付	微信 JSAPI / H5 / Native / APP
ALIPAY	支付宝	支付宝网页/APP/扫码
BANK_CARD	银行卡	银行卡支付（预留）

通道提供方 ChannelProvider

值	名称	说明
WECHAT_DIRECT	微信直连	直接对接微信支付
ALIPAY_DIRECT	支付宝直连	直接对接支付宝
LAKALA	拉卡拉	聚合支付服务商
SHOULIANGBA	收钱吧	聚合支付服务商
OTHER	其他	其他聚合支付服务商

通道提供方后续可扩展，前端建议做成可配置的字典。

七、交易记录

7.1 页面结构

列表页 /payment/transaction（只读）

字段	类型	宽度	说明
transactionNo	string	180	交易流水号
merchantName	string	150	商户名称
channelName	string	120	支付通道
payType	enum	100	支付方式
amount	money	120	交易金额
fee	money	100	手续费
status	enum	100	交易状态
payTime	datetime	160	支付时间
createTime	datetime	160	创建时间

查询条件：交易流水号、商户名称、支付方式、交易状态、时间范围

操作：查看详情

7.2 字段定义

interface TransactionDTO {
  id: number
  /** 交易流水号 */
  transactionNo: string
  /** 关联商户 ID */
  merchantId: number
  /** 商户名称（冗余） */
  merchantName: string
  /** 支付通道 ID */
  channelId: number
  /** 通道名称（冗余） */
  channelName: string
  /** 支付方式 */
  payType: ChannelType
  /** 交易金额（元） */
  amount: number
  /** 手续费（元） */
  fee: number
  /** 交易状态 */
  status: TransactionStatus
  /** 第三方交易号 */
  thirdPartyTransactionNo?: string
  /** 支付时间 */
  payTime?: string
  /** 关联的业务订单号 */
  bizOrderNo?: string
  /** 退款金额（元） */
  refundAmount?: number
  /** 备注 */
  remark?: string
  createTime: string
  updateTime: string
}

7.3 状态枚举

交易状态 TransactionStatus

值	名称	说明
0	待支付	已创建，等待支付
1	支付中	正在处理
2	支付成功	支付完成
3	支付失败	支付失败
4	已关闭	超时关闭或手动关闭
5	已退款	全额退款
6	部分退款	部分退款

八、统一下单流程（前端视角）

顾客端（cashier-customer）         支付服务（rui-payment-api）        第三方
        │                                │                            │
        │  1. 发起支付                     │                            │
        │  (payType, amount,              │                            │
        │   merchantId, bizOrderNo)       │                            │
        │ ──────────────────────────────► │                            │
        │                                 │  2. 按 payType 路由通道      │
        │                                 │  3. 创建交易记录             │
        │                                 │ ──────────────────────────► │
        │                                 │  4. 调用第三方下单           │
        │  5. 返回支付参数                  │                            │
        │  (二维码/跳转URL/支付SDK参数)     │                            │
        │ ◄────────────────────────────── │                            │
        │                                 │                            │
        │  6. 顾客完成支付                  │                            │
        │                                 │ ◄────────────────────────── │
        │                                 │  7. 第三方回调通知           │
        │                                 │  8. 更新交易状态             │
        │  9. 查询支付结果                  │                            │
        │ ──────────────────────────────► │                            │
        │  10. 返回支付结果                 │                            │
        │ ◄────────────────────────────── │                            │

统一下单和支付回调的具体 API 定义待后端整理后补充。

九、前端页面清单

页面	路由	说明
商户列表	`/payment/merchant`	商户 CRUD
商户详情	`/payment/merchant/:id`	商户信息 + 通道 + 进件记录
进件列表	`/payment/onboarding`	进件记录查询
进件申请	`/payment/onboarding/apply`	分步表单（新开页面）
进件详情	`/payment/onboarding/:id`	进件详情 + 状态跟踪
支付通道列表	`/payment/channel`	通道配置管理
通道配置	`/payment/channel/:id?`	新增/编辑通道
交易记录	`/payment/transaction`	交易查询（只读）
交易详情	`/payment/transaction/:id`	交易详情

十、待补充项

以下内容由后端整理后补充，前端文档标记为占位：

API 接口定义：各模块的请求路径、请求参数、响应结构
统一下单接口：下单、查询、回调的完整 API 定义
通道配置参数：不同通道的特定配置字段（如微信的 v3 密钥、支付宝的私钥等）
对账相关：对账单查询、差异处理（后续迭代）
文件上传：进件材料的 bizType 定义（参考 API设计规范.md 第 13 节存储服务）

下一步: 后端整理 API 细节后，更新本文档的待补充项，然后前端可开始实现页面。

23 KiB Raw Blame History Unescape Escape