# 支付服务（Payment）设计文档

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

---

## 一、背景与目标

### 1.1 现状

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

### 1.2 目标

1. **聚合支付网关**：统一下单，按支付方式（微信、支付宝、银行卡等）自动路由到对应通道
2. **多通道可配置**：支持同时配置多个第三方支付平台，按门店/场景灵活启用
3. **商户进件**：商户在我们平台提交进件申请 → 平台审核 → 向第三方（微信、支付宝）提交进件 → 状态跟踪
4. **多端一致**：管理后台（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 菜单结构

```json
{
  "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 字段定义

```typescript
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 字段定义

```typescript
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 交互规则

1. **提交进件**：填写信息 → 提交内部审核（状态 → 待审核）
2. **内部审核**：审核通过 → 状态变为审核通过；驳回 → 填写原因，状态变为审核驳回
3. **提交第三方**：审核通过后，可提交至第三方（状态 → 审核中）
4. **状态同步**：第三方回调更新状态（成功/失败）
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 字段定义

```typescript
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 字段定义

```typescript
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` | 交易详情 |

---

## 十、待补充项

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

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

---

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