# YDP 管理后台对接文档

面向管理后台前端。C 端充值见 [YDP 充值前端对接文档](./ydp_pay_frontend.md)。

协议约定与现有后台相同：`POST`、管理员登录态、`snake_case`、枚举可传数字或字符串名。

YDP 接入复用现有「充值渠道管理」「提现银行管理」「提现列表/导出/自动下发」，**没有单独一套 YDP 配置页。** 需要做的是：下拉框补枚举、列表能展示/筛选 YDP、运营能启停和改限额。

种子数据**默认全部禁用**。没打开之前，C 端看不到 YDP 充值，提现列表也不会出现 YDP 导出项。

## 1. 新增枚举

| 用在 | 枚举 | 数字值 | 含义 |
| --- | --- | ---: | --- |
| 充值渠道 `pay_type` | `PAY_TYPE_YDP` | **20** | YDP 充值 |
| 提现银行渠道 `channel_type` | `TYPE_YDP` | **5** | YDP 代付映射 |
| 提现导出/自动下发 `pay_platform` | `PAY_PLATFORM_YDP` | **7** | YDP 打款 |

所有出现 Jaya / EasyPay 的下拉，都要加上 YDP。响应可能是数字或字符串名，两种都认。

```ts
const PAY_TYPE_YDP = 20;
const CHANNEL_TYPE_YDP = 5;
const PAY_PLATFORM_YDP = 7;

function isYdpPayType(v: string | number) {
  return v === 20 || v === "PAY_TYPE_YDP";
}
function isYdpChannelType(v: string | number) {
  return v === 5 || v === "TYPE_YDP";
}
function isYdpPayPlatform(v: string | number) {
  return v === 7 || v === "PAY_PLATFORM_YDP";
}
```

## 2. 充值渠道

接口与现有充值渠道页相同，只是 `pay_type` 多了 `20`。

| 操作 | 接口 |
| --- | --- |
| 列表 | `POST /v1/man/deposit/channel/list` |
| 新增 | `POST /v1/man/deposit/channel/create` |
| 更新 | `POST /v1/man/deposit/channel/update` |
| 删除 | `POST /v1/man/deposit/channel/delete` |

筛 YDP：

```json
{ "offset": 0, "limit": 50, "pay_type": 20 }
```

迁移已写入 3 条（`is_disabled = true`）：

| name | display_name | params | min_amount | max_amount | sort |
| --- | --- | --- | ---: | ---: | ---: |
| `ydp-qris` | YDP QRIS | `{"payment":"ydidnqris"}` | 10000 | 50000000 | 40 |
| `ydp-dana` | YDP DANA | `{"payment":"ydidndana"}` | 10000 | 50000000 | 39 |
| `ydp-va` | YDP VA | `{"payment":"ydidnva"}` | 10000 | 50000000 | 38 |

### 2.1 打开某条充值渠道

`UpdateDepositChannel` 把 `is_disabled` 改为 `false`。C 端列表立刻能看到；关掉则 C 端消失，且 `ydp/create` 会被服务端拒绝。

限额 `min_amount` / `max_amount` 单位是 **IDR**，`0` 表示不限。改限额后，C 端列表和下单都会按新限额拦截。

### 2.2 `params`（必填）

YDP 只用 `payment`，不要套 Jaya 的 `method` 或 Unispay 的 `pay_type`。

允许值（大小写不敏感，建议小写）：

- `ydidnqris`
- `ydidndana`
- `ydidnva`

```json
{
  "id": 123,
  "name": "ydp-qris",
  "display_name": "YDP QRIS",
  "pay_type": 20,
  "params": { "payment": "ydidnqris" },
  "min_amount": 10000,
  "max_amount": 50000000,
  "sort": 40,
  "is_disabled": false
}
```

`display_name` 是 C 端按钮文案。`name` 仅后台识别。

不要新增第四种 `payment`：服务端白名单只认上面三个，C 端下单会失败。三条渠道的 `payment` 也不要互相改乱（例如 QRIS 渠道改成 `ydidndana`）。

## 3. 提现银行映射

用户绑卡名单仍是 Jaya 主表，后台不需要给用户端加「YDP 银行」。要做的是：在**已有银行**上打开 YDP 渠道映射。

| 操作 | 接口 |
| --- | --- |
| 主表（含各渠道映射） | `POST /v1/man/withdraw/bank/list` |
| 渠道映射列表 | `POST /v1/man/withdraw/bank/channel/list` |
| 更新一条映射 | `POST /v1/man/withdraw/bank/channel/update` |
| 按银行整表设置 | `POST /v1/man/withdraw/bank/channel/set` |

筛 YDP 映射：

```json
{ "offset": 0, "limit": 500, "channel_type": 5 }
```

`WithdrawBankChannel` 字段：

| 字段 | 说明 |
| --- | --- |
| `channel_type` | YDP = `5` |
| `code` | YDP 代付银行码（如 BCA=`014`，DANA=`10002`） |
| `bank_id` | 主表银行 id；**`0` = 未映射，无法用来打款** |
| `is_disabled` | `true` 时该银行不能走 YDP |
| `min_amount` / `max_amount` | 单笔 IDR；影响提现列表能否出现 YDP 导出项 |

迁移已 seed 约 112 条 YDP 映射，**默认全禁用**。与 Jaya 同名的银行一般已带 `bank_id`；YDP 独有、主表没有的银行 `bank_id = 0`，要先绑到主表再启用。

### 3.1 打开某银行的 YDP 代付

对目标映射 `UpdateWithdrawBankChannel`：

```json
{
  "id": 456,
  "channel_type": 5,
  "code": "014",
  "bank_id": 2,
  "is_disabled": false,
  "min_amount": 10000,
  "max_amount": 300000000
}
```

`code` 必须是 YDP 文档里的代付银行码，不要填 Jaya/EasyPay 的码。

主表银行 `is_disabled` 只影响用户能不能绑这个名字；YDP 能否打款看的是 **YDP 渠道行** 的 `is_disabled` 和 `bank_id`。

## 4. 提现列表 / 导出 / 自动下发

现有提现页即可，补上平台 `7`。

### 4.1 列表

`POST /v1/man/withdrawal/list`

每条提现的 `export_types` 会包含当前能走的平台。银行映射已启用、金额在 YDP 限额内时，会出现 `7` / `PAY_PLATFORM_YDP`。

按钮展示建议：`export_types` 含 YDP 才显示「YDP 导出 / YDP 自动下发」。

也可用请求里的 `export_type = 7` 筛「可走 YDP 的单」。

### 4.2 批量导出

`POST /v1/man/withdrawal/batch/export`

```json
{ "no": ["W1", "W2"], "type": 7 }
```

导出 Excel 列为 YDP 代付字段（`merchant_order_id` / `amount` / `payment` / `method` / `to` / `bankcode` 等），与 Jaya 表头不同，不要复用 Jaya 解析。

`payment` 列由服务端按卡类型填写（银行卡 `ydidnqris`，钱包 `ydidndana`），后台不用再配。

### 4.3 自动下发

`POST /v1/man/auto/withdraw`

```json
{
  "pay_platform": 7,
  "audit_infos": [{ "id": 10001, "comment": "YDP" }]
}
```

`id` 是提现单 **数字 id**，不是单号。`pay_platform` 必须是 `7`。

成功后状态变为处理中；到账靠 YDP 回调或下面的刷新。

### 4.4 刷新状态

`POST /v1/man/withdraw/refresh`

```json
{ "ids": [10001] }
```

对 YDP 处理中的单会去查 YDP，终态则更新为已到账或失败。

## 5. 后台 UI 改动清单

1. 充值渠道：`pay_type` 下拉增加 **YDP (20)**；`params` 编辑支持 `payment`。
2. 提现银行渠道：`channel_type` 下拉增加 **YDP (5)**；列表能按 5 筛选。
3. 提现列表：`export_types` / 导出类型 / 自动下发平台增加 **YDP (7)**。
4. 打开 YDP 前确认映射 `bank_id > 0` 且 `code` 正确。
5. 商户号、密钥、`base_url` 在服务端 yaml，**不在后台页面配**。没配时自动下发会失败，页面可提示「YDP 未开通」。

## 6. 不要做的事

- 不要给 C 端提现银行列表加 YDP 选项
- 不要把 Jaya 的 `method` 写进 YDP 充值 `params`
- 不要在未启用映射时对单子点 YDP 自动下发
- 不要改 `pay_type` / `channel_type` 的既有数字（Jaya 仍是 15 / 1）