# 多发货平台与电子凭证整体链路

## 1. 当前结论

当前系统需要把四类能力拆开理解：

| 模块 | 定位 | 说明 |
| --- | --- | --- |
| 91 卡券 | 订单来源 + 发链接通道 | 91 调用我方下单接口，我方生成领取链接；91 查询订单时拿到领取链接，并发送给用户。 |
| kuaishou-cloud | 发货平台 1 | 已对接，用于发放它支持的皮肤、道具。 |
| kuaishou-feifei | 发货平台 2 | 新增发货平台，作为 kuaishou-cloud 的补充，覆盖 kuaishou-cloud 没有的皮肤、道具。 |
| 快手电子凭证 | 领取流程里的自动核销能力 | 用来替代用户在领取页手动输入核销码的步骤，不替代 91，也不替代发货平台。 |

因此整体设计不是“新增订单来源”，而是：

```text
91 负责进单和把领取链接发给用户
我方领取页负责统一承接用户
kuaishou-cloud / kuaishou-feifei 负责真实发货
快手电子凭证负责把领取页里的核销码输入步骤自动化
```

## 2. 目标链路

```text
91 卡券下单
  -> 我方创建内部订单和履约任务
  -> 按商品选择发货平台
       -> kuaishou-cloud
       -> kuaishou-feifei
  -> 91 卡券查询订单
  -> 我方返回统一 claimUrl
  -> 91 卡券把 claimUrl 发给用户
  -> 用户打开 claimUrl
  -> 系统检查快手电子凭证状态
       -> 已有关联电子凭证：跳过手动输入核销码
       -> 未关联电子凭证：保留兜底处理
  -> 用户继续完成绑定 / 跳转发货平台 H5
  -> 发货平台完成履约
  -> 我方更新任务状态
  -> 我方完成快手电子凭证核销闭环
```

## 3. 91 卡券职责边界

91 卡券仍然只承担两件事：

1. 调用我方异步下单接口，提供 `orderNo`、`productNo`、`buyNum` 等订单信息。
2. 调用我方查询接口，获取最终要发给用户的卡密内容。

这里的卡密内容继续保持为我方统一领取链接：

```text
claimUrl = https://你的域名/#/claim/{token}
```

不要直接把 kuaishou-cloud 绑定链接或 kuaishou-feifei 的 H5 链接返回给 91。原因是领取页需要统一处理：

- 商品最终走哪个发货平台；
- 是否已经通过快手电子凭证完成自动核销；
- 是否需要展示绑定链接、二维码或 H5；
- 异常时如何兜底、重试、转人工。

## 4. 发货平台选择

履约任务创建时，需要根据商品配置选择发货平台：

```text
91 productNo
  -> 商品匹配
  -> 命中 kuaishou-cloud 商品
       -> executor_key = kuaishou_ct_assisted
  -> 命中 kuaishou-feifei 商品
       -> executor_key = kuaishou_feifei
  -> 未命中
       -> 进入待补全 / 人工处理
```

优先级建议先做成可配置规则，不在代码里硬编码。第一阶段可以采用：

1. 显式覆盖规则优先；
2. 再按商品名匹配 kuaishou-cloud；
3. 再按商品名或 `product_code` 匹配 kuaishou-feifei；
4. 都未命中则进入待补全队列。

## 5. kuaishou-feifei 接入方式

kuaishou-feifei 的主要交付物是 `h5.recharge_url`。

创建任务后，系统应向 kuaishou-feifei 创建订单，并把关键字段保存到任务上下文：

```json
{
  "kuaishouFeifei": {
    "platformOrderNo": "内部幂等单号",
    "orderNo": "发货平台内部单号",
    "productCode": "商品编码",
    "rechargeStatus": 15,
    "statusLabel": "待绑定",
    "h5": {
      "rechargeUrl": "http://..."
    },
    "lastSyncedAt": "2026-07-07T00:00:00.000Z"
  }
}
```

领取页根据当前任务的 executor 展示不同内容：

- `kuaishou_ct_assisted`：展示现有 kuaishou-cloud 绑定流程；
- `kuaishou_feifei`：展示或跳转 kuaishou-feifei 的 `h5.recharge_url`；
- `manual_dispatch`：进入人工兜底。

## 6. 快手电子凭证的嵌入点

旧流程中，用户打开领取链接后需要手动输入快手核销码：

```text
用户打开 claimUrl
  -> 输入核销码
  -> 我方校验 / 核销
  -> 继续绑定或发货
```

新流程中，快手电子凭证用于把这一步自动化：

```text
用户打开 claimUrl
  -> 系统查任务上下文中的电子凭证信息
  -> 如果已有关联的 oid / token / eticketId
       -> 自动认为核销凭证已就绪
       -> 跳过手动输入核销码
  -> 继续进入发货平台绑定 / H5
```

电子凭证信息建议沉淀在 task context 中：

```json
{
  "kuaishouIndustryVoucher": {
    "oid": "快手订单号",
    "token": "订单维度授权 token",
    "eticketId": "电子凭证 id",
    "status": "UNUSED",
    "certActualStartTime": 0,
    "certActualEndTime": 0,
    "verifiedAt": null,
    "consumedAt": null
  }
}
```

注意：快手电子凭证不是新的订单来源。它只服务领取流程中的核销自动化。

## 7. 核销完成时机

电子凭证不应该在用户刚打开领取页时就立刻标记为已消费。

推荐时机：

```text
发货平台实际履约成功
  -> 我方更新 task 为 completed / redeemed
  -> 我方触发快手电子凭证核销回调
  -> 电子凭证状态更新为 CONSUMED
```

这样可以避免用户打开链接但未完成绑定时，快手侧已经显示核销成功。

不同发货平台的成功判定：

| 发货平台 | 成功判定 |
| --- | --- |
| kuaishou-cloud | 当前发货流程完成，任务进入完成态。 |
| kuaishou-feifei | 查询或异步通知返回 `recharge_status = 30`。 |

失败时：

- 发货平台失败：任务进入 `manual_review` 或 `failed`；
- 电子凭证保持 `UNUSED`，不要误核销；
- 需要人工确认时再做销毁、退款或补发。

## 8. 现有代码需要调整的方向

当前项目已经有以下基础能力：

- 91 卡券下单和查询；
- kuaishou-cloud 发货流程；
- 快手电子凭证 `send-code / query-code / destroy-code / consume-code` 接口骨架；
- 领取页手动输入核销码流程。

后续需要把它们串起来：

1. 91 查询仍返回统一 `claimUrl`。
2. 商品匹配支持多发货平台。
3. kuaishou-feifei 新增独立 executor 和 API client。
4. 领取页根据 task executor 展示对应发货流程。
5. 快手电子凭证状态进入 task context，用于跳过手动输入核销码。
6. 发货成功后再触发快手电子凭证核销。
7. 保留手动输入核销码作为异常兜底，而不是主路径。

## 9. 数据关联

91 订单和快手电子凭证之间需要稳定关联。

优先方案：

```text
91 orderNo == 快手电子凭证 oid
```

如果不相等，则需要额外映射关系，例如：

```text
91 orderNo
  -> 内部 order.id
  -> task.id
  -> 快手电子凭证 oid / eticketId / token
```

没有这层映射，领取页无法可靠判断当前用户对应哪一张快手电子凭证，也就无法稳定跳过手动核销码输入步骤。

## 10. 真实测试订单复盘

2026-07-07 的真实测试请求验证了优先关联方案成立。

### 10.1 请求时序

```text
10:16:43  91 卡券异步下单
          orderNo = 2618800083429561
          productNo = 套装-Alan Walker
          buyNum = 1

10:16:46  快手电子凭证 send-code
          oid = 2618800083429561
          itemTitle = 测试连接1111
          itemId = 26692927860114
          skuId = 188718171010114
          eticketId = 2038

10:17:13  91 卡券查询订单
          orderStatus = 10
          cards = ''

10:17:44  91 卡券再次查询订单
          orderStatus = 10
          cards = ''
```

### 10.2 已验证事实

这笔真实单中：

```text
91 orderNo = 2618800083429561
快手电子凭证 oid = 2618800083429561
```

因此可以用 `orderNo / oid` 作为 91 订单和快手电子凭证的主关联键。

同时也验证了另一个重要事实：

```text
91 productNo = 套装-Alan Walker
快手 itemTitle = 测试连接1111
```

两者不一定相同。因此，发什么皮肤、走哪个发货平台，应该以 91 的 `productNo` 为准；快手电子凭证的 `itemTitle / itemId / skuId` 主要用于凭证关系、快手侧订单信息和核销闭环，不应该直接用于决定发货商品。

### 10.3 当前断点

当前系统在这笔单上的表现：

```text
91 下单结果：
ignored = true
ignoreReason = unconfigured_items
orderId = 2487
orderStatus = 10
cards = ''

快手电子凭证结果：
result = 1
eticketId = 2038
status = UNUSED
```

说明：

1. 91 订单已经进入系统，但因为 `套装-Alan Walker` 没命中现有履约配置，所以进入待补全队列。
2. 快手电子凭证已经发码成功，但当前实现没有把 `eticketId = 2038` 绑定回 91 订单的履约上下文。
3. 91 查询只看 `provider = 91kaquan` 的订单和任务，因此看不到快手电子凭证链路创建或返回的状态。
4. 因为 91 订单没有可交付的 `claimUrl`，所以持续返回 `orderStatus = 10` 和空 `cards`。

### 10.4 实现修正方向

`kuaishou-industry/send-code` 收到请求后，不能只按 `provider = kuaishou-industry` 自己创建孤立订单。它需要优先做关联：

```text
send-code.oid
  -> 查找 91 订单 platformOrderId = oid
  -> 找到：把电子凭证信息写入该 91 订单对应 task / context
  -> 未找到：暂存电子凭证待关联，或创建待关联记录
```

如果 91 订单仍是 `pending_config`，则需要在后续补全商品履约配置后，同时带上已收到的电子凭证信息。

最终目标：

```text
91 订单 task
  -> context.kuaishouIndustryVoucher.eticketId = 2038
  -> context.kuaishouIndustryVoucher.oid = 2618800083429561
  -> context.kuaishouIndustryVoucher.status = UNUSED
  -> 领取页打开时跳过手动核销码输入
  -> 发货完成后触发电子凭证核销
```

## 11. 电子凭证券号生成与核销幂等

接入电子凭证的核心目的，是减少用户在领取页手动输入快手核销码的步骤。因此，系统返回给快手的电子凭证 `eticket.id` 需要成为后续查询、销毁、核销都能稳定使用的业务券号。

### 11.1 当前逻辑

当前实现中，`send-code` 返回的 `eticket.id` 来自本地 task id：

```text
eticket.id = fulfillment_tasks.id
```

真实测试单中：

```text
eticket.id = 2038
```

这说明当前“核销码/券号”不是快手生成的，而是我方创建 task 后，把 task id 当作电子凭证 id 返回给快手。

这个方式有两个问题：

1. task 属于当前实现里的 `kuaishou-industry` 孤立订单链，尚未绑定到 91 订单 task。
2. task id 虽然全局唯一，但它和任务生命周期耦合太强；后续如果任务重建、补配置、切换发货平台，会影响电子凭证反查和幂等。

### 11.2 推荐目标

电子凭证券号应该满足：

| 要求 | 说明 |
| --- | --- |
| 全局唯一 | 不同订单、不同数量拆分出的券不能重复。 |
| 幂等稳定 | 同一个 `oid` 重复 `send-code`，必须返回同一批 `eticket.id`。 |
| 可反查 | `query-code / destroy-code / consume-code` 带回 `eticket.id` 时，能找到原始订单、task 和发货状态。 |
| 可延迟绑定 | 如果快手 `send-code` 早于 91 task 准备完成，券号也能先落库，后续再绑定 task。 |
| 可核销 | 发货完成后，能用同一张券更新为 `CONSUMED`，并记录核销流水。 |

### 11.3 推荐数据模型

建议新增独立的电子凭证券表，而不是继续只依赖 task id：

```text
kuaishou_industry_vouchers
  id                     BIGSERIAL PRIMARY KEY
  voucher_code           TEXT UNIQUE NOT NULL
  oid                    TEXT NOT NULL
  order_id               BIGINT NULL
  task_id                BIGINT NULL
  unit_index             INTEGER NOT NULL
  token                  TEXT NOT NULL
  status                 TEXT NOT NULL      -- UNUSED / CONSUMED / DESTROYED
  valid_start_time       BIGINT NOT NULL
  valid_end_time         BIGINT NOT NULL
  consume_serial_num     TEXT NOT NULL DEFAULT ''
  consumed_at            TIMESTAMPTZ NULL
  destroyed_at           TIMESTAMPTZ NULL
  raw_payload_json       JSONB NOT NULL DEFAULT '{}'::jsonb
  created_at             TIMESTAMPTZ NOT NULL
  updated_at             TIMESTAMPTZ NOT NULL

唯一约束：
  UNIQUE(oid, unit_index)
  UNIQUE(voucher_code)
```

券号生成建议：

```text
voucher_code = String(kuaishou_industry_vouchers.id)
```

理由：

- 数字字符串兼容性最好；
- 数据库主键保证不重复；
- 重复 `send-code` 时通过 `UNIQUE(oid, unit_index)` 找回原记录，返回原 `voucher_code`；
- 不依赖 task 是否已经创建。

如果后续确认快手完全支持任意字符串，也可以升级为带前缀的业务券号，例如：

```text
voucher_code = KSEV-{oid}-{unitIndex}
```

但第一阶段建议优先使用数字字符串，降低快手侧兼容风险。

### 11.4 send-code 幂等规则

`send-code` 处理流程应改为：

```text
收到 oid + num
  -> 按 oid 查 91 订单
  -> 为 unitIndex = 1..num 创建或获取 voucher
       -> 已存在：复用原 voucher_code
       -> 不存在：新建 voucher
  -> 如果 91 task 已存在：绑定 voucher.task_id
  -> 如果 91 task 未存在：voucher 保持待绑定
  -> 返回 etickets[{ id: voucher_code, status: voucher.status }]
```

重复通知时，必须返回相同结果：

```text
第一次 send-code:
  oid = 2618800083429561
  num = 1
  eticket.id = 2038

第二次 send-code:
  oid = 2618800083429561
  num = 1
  eticket.id 仍然 = 2038
```

### 11.5 有效期生成规则

真实测试单里快手没有传 `certActualStartTime / certActualEndTime`，并且 `certStartTime / certEndTime` 也可能都是 0。当前系统返回了：

```text
validStartTime = 0
validEndTime = 0
```

例如 2026-07-07 11:16:58 的真实请求：

```text
certExpireType = 3
certExpDays = 3
certStartTime = 0
certEndTime = 0
certActualStartTime = 0
certActualEndTime = 0
```

这种场景应理解为“购买成功后固定有效天数”，用 `certExpDays` 生成有效期。建议按以下优先级生成：

```text
validStartTime:
  1. certActualStartTime > 0
  2. certStartTime > 0
  3. 当前时间毫秒

validEndTime:
  1. certActualEndTime > 0
  2. certEndTime > 0
  3. certStartTime + certExpDays * 86400000
  4. 当前时间 + certExpDays * 86400000
```

如果 `certExpDays` 也为空，则使用保守默认值，例如 3 天。

对于上面的真实请求，返回给快手的电子凭证应类似：

```text
validStartTime = send-code 处理时的当前毫秒时间戳
validEndTime = validStartTime + 3 * 86400000
```

### 11.6 后续核销规则

发货完成后，不再要求用户输入快手核销码，而是系统根据 voucher 主动完成核销闭环：

```text
发货平台履约成功
  -> 找到 task 绑定的 voucher
  -> 检查 voucher.status = UNUSED
  -> 生成稳定 consume_serial_num
  -> 调用快手电子凭证核销回调
  -> 成功后更新 voucher.status = CONSUMED
  -> 更新 task 为 completed / redeemed
```

核销流水号也必须幂等：

```text
consume_serial_num = CONSUME-{voucher_code}
```

这样即使核销回调重试，也不会生成多条不同流水。

销毁规则：

```text
destroy-code
  -> 按 oid + eticket.id 找 voucher
  -> 未找到：按快手要求仍可返回成功
  -> 已 CONSUMED：不应直接改为 DESTROYED，进入人工确认
  -> UNUSED：更新为 DESTROYED
```
