221 lines
8.9 KiB
Markdown
221 lines
8.9 KiB
Markdown
# 退款流水 — GetRefundPayLogList
|
||
|
||
> 模块：`Order` · ODS 表：`refund_transactions` · 事实表（增量）
|
||
|
||
---
|
||
|
||
## 一、接口概述
|
||
|
||
查询门店下已完成的退款支付流水。每条记录对应一笔资金层面的退款交易（资金反向流出），`pay_amount` 全为负数。本表是纯资金维度的退款流水，不含退款原因等业务信息；通过 `relate_type` + `relate_id` 关联到具体业务实体（消费订单、充值记录等）。与支付流水（`payment_transactions`）共用枚举体系，可 UNION 构建统一资金流水视图。
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 完整路径 | `POST /Order/GetRefundPayLogList` |
|
||
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
|
||
| 鉴权 | `Authorization: Bearer <token>` |
|
||
| 分页 | `page` + `limit`（最大 100） |
|
||
| 时间范围 | `startTime` / `endTime`（必填） |
|
||
|
||
---
|
||
|
||
## 二、请求
|
||
|
||
### 请求体（JSON）
|
||
|
||
```json
|
||
{
|
||
"startTime": "2025-11-01 08:00:00",
|
||
"endTime": "2025-11-10 08:00:00",
|
||
"siteId": 2790685415443269,
|
||
"page": 1,
|
||
"limit": 100
|
||
}
|
||
```
|
||
|
||
### 参数说明
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `startTime` | string | 是 | 查询起始时间 |
|
||
| `endTime` | string | 是 | 查询结束时间 |
|
||
| `siteId` | int | 是 | 门店 ID |
|
||
| `page` | int | 是 | 页码，从 1 开始 |
|
||
| `limit` | int | 是 | 每页条数，最大 100 |
|
||
|
||
---
|
||
|
||
## 三、响应结构
|
||
|
||
```
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"list": [ { ... }, { ... } ],
|
||
"total": 11
|
||
}
|
||
}
|
||
```
|
||
|
||
`data.list` 中每个对象即为一条退款流水记录，共 32 个字段（含嵌套 `siteProfile`），按逻辑分组说明如下。
|
||
|
||
---
|
||
|
||
## 四、响应字段详解（32 个字段）
|
||
|
||
### 4.1 主键与门店/租户
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `id` | int | `3089577798995141` | 退款流水记录主键 ID |
|
||
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID |
|
||
| `site_id` | int | `2790685415443269` | 门店 ID |
|
||
| `tenantName` | string | `"朗朗桌球"` | 租户名称，冗余展示字段，与 `siteProfile.shop_name` 一致 |
|
||
| `siteProfile` | object | `{...}` | 门店信息快照（冗余），结构与其他接口一致，不再逐字段展开 |
|
||
|
||
### 4.2 业务关联
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `relate_type` | int | `1` | 关联业务类型枚举。`1` = 结账单退款（当前样本新增）；`2` = 消费类订单退款；`5` = 充值/储值类业务退款（金额通常较大） |
|
||
| `relate_id` | int | `3089548319804869` | 关联业务记录的主键 ID。同一 `relate_id` 可对应多条退款流水（分批退场景） |
|
||
| `pay_sn` | int | `0` | 支付序列号。当前未使用，全部为 0 |
|
||
|
||
### 4.3 金额字段
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `pay_amount` | float | `-8.0` | 退款资金变动金额（元/人民币）。**全部为负数**，绝对值即退款金额。判断退款金额应看此字段的负数值，而非 `refund_amount` |
|
||
| `refund_amount` | float | `0.0` | 实际退款金额字段。当前**未启用**，全部为 0.0。系统直接用 `pay_amount` 负数表示退款额 |
|
||
| `balance_frozen_amount` | float | `0.0` | 会员储值卡退款时暂时冻结的余额金额（元）。当前无会员卡退款，全部为 0 |
|
||
| `card_frozen_amount` | float | `0.0` | 卡被冻结金额（元），与会员卡/储值账户相关。当前未使用 |
|
||
| `round_amount` | float | `0.0` | 舍入/抹零金额（元）。当前未使用 |
|
||
| `channel_fee` | float | `0.0` | 第三方支付渠道手续费（元）。当前未使用 |
|
||
|
||
### 4.4 时间字段
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `create_time` | string | `"2026-02-10 23:41:06"` | 退款流水创建时间 |
|
||
| `pay_time` | string | `"2026-02-10 23:41:06"` | 退款在支付渠道层面实际发生的时间。当前与 `create_time` 完全一致；异步退款场景下二者可能不同 |
|
||
|
||
### 4.5 支付方式与渠道
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `payment_method` | int | `4` | 支付/退款方式枚举。已知值：`2`（某种线上支付渠道）、`4`（另一种支付方式）。与支付流水共用枚举 |
|
||
| `online_pay_channel` | int | `0` | 线上支付渠道枚举。`0` = 线下/默认渠道。当前未出现其他值 |
|
||
| `online_pay_type` | int | `0` | 在线退款类型。`0` = 原路退回。其他值（如退到余额、退到其他银行卡）当前未出现 |
|
||
| `pay_terminal` | int | `1` | 退款终端类型枚举。`1` = 前台收银端。其他值（小程序、自助机等）当前未出现 |
|
||
| `pay_config_id` | int | `0` | 支付配置 ID（商户支付通道配置主键）。当前未使用 |
|
||
| `channel_payer_id` | string | `""` | 支付渠道侧 payer ID（如微信 openid）。当前未使用 |
|
||
| `channel_pay_no` | string | `""` | 第三方支付平台交易号（如微信支付单号）。当前未使用 |
|
||
|
||
### 4.6 会员关联
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `member_id` | int | `0` | 会员 ID。`0` = 非会员退款或未绑定会员。非 0 时对应会员档案表主键 |
|
||
| `member_card_id` | int | `0` | 会员卡账户 ID。`0` = 未退到会员卡。非 0 时对应储值卡列表主键 |
|
||
|
||
### 4.7 状态与标志
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `pay_status` | int | `2` | 退款状态枚举。`2` = 已完成。当前导出仅包含已完成的退款记录 |
|
||
| `action_type` | int | `2` | 行为类型枚举。`2` = 退款。配合 `pay_amount < 0` 确认为退款动作 |
|
||
| `is_revoke` | int | `0` | 是否撤销型退款。`0` = 正常退款；`1` = 撤销类型操作 |
|
||
| `is_delete` | int | `0` | 逻辑删除标记。`0` = 未删除，`1` = 已逻辑删除 |
|
||
| `check_status` | int | `1` | 审核状态。`1` = 已审核/通过。系统支持"退款需审核"流程 |
|
||
|
||
### 4.8 操作相关
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `operator_id` | int | `0` | 执行退款操作的操作员 ID。当前全部为 0（系统未记录或导出未带出） |
|
||
| `cashier_point_id` | int | `0` | 收银点 ID。当前未区分具体收银点 |
|
||
|
||
---
|
||
|
||
## 五、响应样例（单条记录）
|
||
|
||
```json
|
||
{
|
||
"tenantName": "朗朗桌球",
|
||
"siteProfile": { "id": 2790685415443269, "shop_name": "朗朗桌球", "..." : "..." },
|
||
"id": 3089577798995141,
|
||
"site_id": 2790685415443269,
|
||
"tenant_id": 2790683160709957,
|
||
"pay_sn": 0,
|
||
"pay_amount": -8.0,
|
||
"pay_status": 2,
|
||
"pay_time": "2026-02-10 23:41:06",
|
||
"create_time": "2026-02-10 23:41:06",
|
||
"relate_type": 1,
|
||
"relate_id": 3089548319804869,
|
||
"is_revoke": 0,
|
||
"is_delete": 0,
|
||
"online_pay_channel": 0,
|
||
"payment_method": 4,
|
||
"balance_frozen_amount": 0.0,
|
||
"card_frozen_amount": 0.0,
|
||
"member_id": 0,
|
||
"member_card_id": 0,
|
||
"round_amount": 0.0,
|
||
"online_pay_type": 0,
|
||
"action_type": 2,
|
||
"refund_amount": 0.0,
|
||
"cashier_point_id": 0,
|
||
"operator_id": 0,
|
||
"pay_terminal": 1,
|
||
"pay_config_id": 0,
|
||
"channel_payer_id": "",
|
||
"channel_pay_no": "",
|
||
"check_status": 1,
|
||
"channel_fee": 0.0
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、跨表关联
|
||
|
||
### 与支付流水（`payment_transactions`）
|
||
|
||
| 本表字段 | 关联表字段 | 说明 |
|
||
|----------|-----------|------|
|
||
| `relate_type` + `relate_id` | `relate_type` + `relate_id` | 通过共同指向同一业务实体间接关联 |
|
||
| `payment_method` | `payment_method` | 共用支付方式枚举 |
|
||
| `online_pay_channel` | `online_pay_channel` | 共用线上渠道枚举 |
|
||
|
||
> 支付流水 `pay_amount > 0`（进账），退款流水 `pay_amount < 0`（出账）。两者可 UNION 构建统一资金流水视图，通过 `action_type` + `pay_amount` 符号区分方向。
|
||
|
||
### 与结账记录（`settlement_records`）
|
||
|
||
当 `relate_type = 2` 时，`relate_id` 对应结账记录的 `settleList.id`，可追溯退款对应的原始消费订单。
|
||
|
||
### 与充值结算记录（`recharge_settlements`）
|
||
|
||
当 `relate_type = 5` 时，`relate_id` 对应充值业务记录的主键，可追溯退款对应的原始充值订单。
|
||
|
||
### 与会员体系
|
||
|
||
| 本表字段 | 关联表字段 | 说明 |
|
||
|----------|-----------|------|
|
||
| `member_id` | 会员档案 `id` | 会员主键 |
|
||
| `member_card_id` | 储值卡列表主键 | 会员卡账户 |
|
||
|
||
> 当前数据中 `member_id` / `member_card_id` 全部为 0，说明均为非会员卡退款。一旦发生"退到储值卡"场景，这些字段会出现非 0 值，可串联"资金退款 → 会员余额变更 → 卡账户状态"。
|
||
|
||
### 与门店维度
|
||
|
||
`site_id` / `tenant_id` 与所有业务表一致。`siteProfile` 为冗余快照。
|
||
|
||
<!--
|
||
AI_CHANGELOG:
|
||
- 日期: 2026-02-13
|
||
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
|
||
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
|
||
- 变更摘要: 新建 docs/api-reference/refund_transactions.md，按逻辑分组详解所有字段，含跨表关联
|
||
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
|
||
-->
|