# Data Model: 蓝新金流(NewebPay)线上支付接入

**Feature**: specs/011-newebpay-payment/spec.md
**Date**: 2026-06-22

本文定义新增实体、现有实体扩展与建表 DDL（DDL 同步写入 `updatesql/sql.md`，不直接执行）。

---

## 新增实体

### 1. PosStoreNewebpay（门店蓝新支付凭证）— `pos_store_newebpay`

与 `pos_store` 一对一。记录门店的蓝新申请状态、启用开关、凭证、启用的支付方式。复用 009 `pos_store_ezpay` 的状态机与审计字段约定。

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT PK AUTO | 主键 |
| store_id | BIGINT UK | 关联 pos_store.id（门店），唯一 |
| newebpay_status | INT | 申请状态: 0未申请/1申请中/2已开通 |
| is_enabled | INT | 启用开关: 0停用/1启用（仅 status=2 有意义） |
| merchant_id | VARCHAR(15) | 蓝新商店代号 MerchantID |
| hash_key | VARCHAR(64) | 蓝新 HashKey（32 字节） |
| hash_iv | VARCHAR(32) | 蓝新 HashIV（16 字节） |
| enabled_payments | VARCHAR(50) | 启用的支付方式，逗号分隔：CREDIT,LINEPAY,APPLEPAY |
| apply_time | DATETIME | 提交申请时间（0→1） |
| approved_time | DATETIME | 开通时间（→2） |
| last_verify_result | VARCHAR(240) | 最近一次凭证验证结果 |
| remark | VARCHAR(255) | 备注 |
| create_time | DATETIME | 创建时间 |
| update_time | DATETIME | 更新时间 |
| create_by | VARCHAR(64) | 创建人 |
| update_by | VARCHAR(64) | 更新人 |

**状态机**: `0 未申请 --apply--> 1 申请中 --saveCredentials(验证通过)--> 2 已开通 <--reset--> 1 申请中`；`2 已开通` 下 `toggleEnable` 切换 is_enabled。门店无此行即视为未申请。

**Java 实体**: `ruoyi-system/.../domain/PosStoreNewebpay.java`，MyBatis-Plus 注解（`@TableName("pos_store_newebpay")`、`@TableId(AUTO)`、`@TableField(fill=...)`），与 PosStoreEzpay 一致风格。

---

### 2. PosOrderPayment（支付交易流水）— `pos_order_payment`

每笔蓝新交易一条。承载幂等（按 trade_no）与对账明细。

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT PK AUTO | 主键 |
| dd_id | VARCHAR(64) | 系统订单号（关联 pos_order.dd_id），索引 |
| merchant_order_no | VARCHAR(30) | 商店订单号 MerchantOrderNo（发起生成），索引 |
| trade_no | VARCHAR(20) | 蓝新交易序号 TradeNo（回调获得），唯一索引（幂等键） |
| store_id | BIGINT | 门店ID |
| merchant_id | VARCHAR(15) | 蓝新商店代号（发起时的门店凭证） |
| pay_type | VARCHAR(20) | 支付方式: CREDIT/LINEPAY/APPLEPAY（回调确定） |
| amount | INT | 交易金额（整数元，= 订单 amount） |
| pay_status | INT | 支付状态: 0未支付/1已支付/2失败（对齐 payStatus 语义） |
| auth_code | VARCHAR(20) | 授权码（信用卡回调 Auth） |
| pay_time | DATETIME | 支付完成时间（回调 PayTime） |
| callback_raw | TEXT | 回调原始解密结果（调试/对账） |
| create_time | DATETIME | 创建时间（发起时间） |
| update_time | DATETIME | 更新时间 |

**幂等规则**: 回调按 `trade_no` 查重——已存在且 pay_status=1 则跳过更新（仍返回成功应答）；不存在则新增/更新。
**唯一性**: `trade_no` 建唯一索引（UNIQUE），允许空值（发起时尚无 trade_no）；同一订单多次发起产生多行（不同 merchant_order_no），但同一 trade_no 只对应一行。

**Java 实体**: `ruoyi-system/.../domain/PosOrderPayment.java`，MyBatis-Plus 注解。

---

## 现有实体扩展

### 3. PosOrder（订单）— `pos_order`（不改表结构）

复用现有字段，扩展取值语义：

| 字段 | 现状 | 本期用法 |
|------|------|----------|
| dd_id | 订单号 | 派生 MerchantOrderNo = "NB" + dd_id |
| amount | 订单合计金额(Integer 元) | 蓝新支付金额（含运费，与发票 amount−freight 不同） |
| pay_type | 支付方式(1-5越南旧值) | 新增取值 `"6"` = 蓝新在线支付（发起时写入） |
| pay_status | 0未支付/1已支付/2已退款 | 回调成功置 1（沿用） |
| pay_url | 支付地址 | 存蓝新 gatewayUrl（兜底/记录） |
| md_id | 门店ID | 决定用哪个门店的蓝新凭证发起交易 |

**不改表结构**，无 DDL。payType 取值扩展在代码层（常量/枚举）体现。

---

## DDL（写入 updatesql/sql.md，不直接执行）

```sql
-- 2026-06-22 蓝新金流支付接入 - 门店蓝新凭证表
CREATE TABLE pos_store_newebpay (
  id BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键',
  store_id BIGINT NOT NULL COMMENT '关联 pos_store.id(门店)',
  newebpay_status INT NOT NULL DEFAULT 0 COMMENT '申请状态:0未申请/1申请中/2已开通',
  is_enabled INT NOT NULL DEFAULT 1 COMMENT '启用开关:0停用/1启用',
  merchant_id VARCHAR(15) DEFAULT NULL COMMENT '蓝新商店代号 MerchantID',
  hash_key VARCHAR(64) DEFAULT NULL COMMENT '蓝新 HashKey(32字节)',
  hash_iv VARCHAR(32) DEFAULT NULL COMMENT '蓝新 HashIV(16字节)',
  enabled_payments VARCHAR(50) DEFAULT 'CREDIT' COMMENT '启用支付方式:CREDIT,LINEPAY,APPLEPAY',
  apply_time DATETIME DEFAULT NULL COMMENT '申请时间',
  approved_time DATETIME DEFAULT NULL COMMENT '开通时间',
  last_verify_result VARCHAR(240) DEFAULT NULL COMMENT '最近验证结果',
  remark VARCHAR(255) DEFAULT NULL COMMENT '备注',
  create_time DATETIME DEFAULT NULL COMMENT '创建时间',
  update_time DATETIME DEFAULT NULL COMMENT '更新时间',
  create_by VARCHAR(64) DEFAULT NULL COMMENT '创建人',
  update_by VARCHAR(64) DEFAULT NULL COMMENT '更新人',
  PRIMARY KEY (id),
  UNIQUE KEY uk_store_id (store_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='门店蓝新金流支付凭证';

-- 2026-06-22 蓝新金流支付接入 - 支付交易流水表
CREATE TABLE pos_order_payment (
  id BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键',
  dd_id VARCHAR(64) NOT NULL COMMENT '系统订单号(关联 pos_order.dd_id)',
  merchant_order_no VARCHAR(30) NOT NULL COMMENT '商店订单号 MerchantOrderNo',
  trade_no VARCHAR(20) DEFAULT NULL COMMENT '蓝新交易序号 TradeNo(幂等键)',
  store_id BIGINT DEFAULT NULL COMMENT '门店ID',
  merchant_id VARCHAR(15) DEFAULT NULL COMMENT '蓝新商店代号',
  pay_type VARCHAR(20) DEFAULT NULL COMMENT '支付方式:CREDIT/LINEPAY/APPLEPAY',
  amount INT DEFAULT NULL COMMENT '交易金额(整数元)',
  pay_status INT NOT NULL DEFAULT 0 COMMENT '支付状态:0未支付/1已支付/2失败',
  auth_code VARCHAR(20) DEFAULT NULL COMMENT '授权码',
  pay_time DATETIME DEFAULT NULL COMMENT '支付完成时间',
  callback_raw TEXT COMMENT '回调原始解密结果',
  create_time DATETIME DEFAULT NULL COMMENT '创建时间',
  update_time DATETIME DEFAULT NULL COMMENT '更新时间',
  PRIMARY KEY (id),
  UNIQUE KEY uk_trade_no (trade_no),
  KEY idx_dd_id (dd_id),
  KEY idx_merchant_order_no (merchant_order_no)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='蓝新支付交易流水';
```

注：`uk_trade_no` 唯一索引在 MySQL 下允许多个 NULL（发起时 trade_no 为空），回调写入时保证唯一。

---

## 实体关系

```
pos_store 1 ──── 1 pos_store_newebpay   (门店蓝新凭证)
pos_store 1 ──── ∞ pos_order             (门店订单)
pos_order 1 ──── ∞ pos_order_payment     (一订单多次发起支付,每发起一行)
                                   ↑
                        trade_no 唯一(回调幂等)
```