# API 参考文档

> 飞球 ETL 系统上游 SaaS API 的标准化文档。
> 自动生成于 2026-02-13，基于实时 API 调用 + 本地 JSON 样本。

## 目录结构

```
docs/api-reference/
├── README.md                 # 本文件（索引）
├── api_registry.json         # API 注册表（标准化参数存储）
├── _api_call_results.json    # API 调用结果（字段提取）
├── endpoints/                # 每个 API 一个 .md 文档
│   ├── assistant_accounts_master.md
│   ├── ...（共 25 个）
│   └── tenant_member_balance_overview.md
└── samples/                  # 每个 API 的响应样本（单条记录 JSON）
    ├── assistant_accounts_master.json
    ├── ...
    └── tenant_member_balance_overview.json
```

## API 总览（25 个接口）

### 人事管理

| API | 中文名 | ODS 表 | 字段数 |
|-----|--------|--------|--------|
| [SearchAssistantInfo](endpoints/assistant_accounts_master.md) | 助教账号主数据 | `assistant_accounts_master` | 61 |
| [GetOrderAssistantDetails](endpoints/assistant_service_records.md) | 助教服务流水 | `assistant_service_records` | 64 |
| [GetAbolitionAssistant](endpoints/assistant_cancellation_records.md) | 助教撤销记录 | `assistant_cancellation_records` | 13 |

### 订单与结算

| API | 中文名 | ODS 表 | 字段数 |
|-----|--------|--------|--------|
| [GetAllOrderSettleList](endpoints/settlement_records.md) | 结账记录 | `settlement_records` | 92 |
| [GetSiteTableOrderDetails](endpoints/table_fee_transactions.md) | 台费流水 | `table_fee_transactions` | 39 |
| [GetTaiFeeAdjustList](endpoints/table_fee_discount_records.md) | 台费优惠记录 | `table_fee_discount_records` | 20 |
| [GetOrderSettleTicketNew](endpoints/settlement_ticket_details.md) | 结账小票明细 | `settlement_ticket_details` | ⚠️ 不可用 |

### 支付与退款

| API | 中文名 | ODS 表 | 字段数 |
|-----|--------|--------|--------|
| [GetPayLogListPage](endpoints/payment_transactions.md) | 支付流水 | `payment_transactions` | 11 |
| [GetRefundPayLogList](endpoints/refund_transactions.md) | 退款流水 | `refund_transactions` | 32 |
| [GetRechargeSettleList](endpoints/recharge_settlements.md) | 充值结算记录 | `recharge_settlements` | 92 |

### 会员

| API | 中文名 | ODS 表 | 字段数 |
|-----|--------|--------|--------|
| [GetTenantMemberList](endpoints/member_profiles.md) | 会员档案 | `member_profiles` | 15 |
| [GetTenantMemberCardList](endpoints/member_stored_value_cards.md) | 会员储值卡 | `member_stored_value_cards` | 68 |
| [GetMemberCardBalanceChange](endpoints/member_balance_changes.md) | 会员余额变动 | `member_balance_changes` | 25 |

### 优惠券与团购

| API | 中文名 | ODS 表 | 字段数 |
|-----|--------|--------|--------|
| [GetOfflineCouponConsumePageList](endpoints/platform_coupon_redemption_records.md) | 平台券核销记录 | `platform_coupon_redemption_records` | 26 |
| [QueryPackageCouponList](endpoints/group_buy_packages.md) | 团购套餐定义 | `group_buy_packages` | 35 |
| [GetSiteTableUseDetails](endpoints/group_buy_redemption_records.md) | 团购核销记录 | `group_buy_redemption_records` | 43 |

### 商品与库存

| API | 中文名 | ODS 表 | 字段数 |
|-----|--------|--------|--------|
| [QueryTenantGoods](endpoints/tenant_goods_master.md) | 租户商品主数据 | `tenant_goods_master` | 31 |
| [GetGoodsSalesList](endpoints/store_goods_sales_records.md) | 门店商品销售记录 | `store_goods_sales_records` | 50 |
| [GetGoodsInventoryList](endpoints/store_goods_master.md) | 门店商品库存主数据 | `store_goods_master` | 45 |
| [QueryPrimarySecondaryCategory](endpoints/stock_goods_category_tree.md) | 商品分类树 | `stock_goods_category_tree` | 2 |
| [QueryGoodsOutboundReceipt](endpoints/goods_stock_movements.md) | 库存出入库流水 | `goods_stock_movements` | 19 |
| [GetGoodsStockReport](endpoints/goods_stock_summary.md) | 库存汇总报表 | `goods_stock_summary` | 14 |

### 台桌

| API | 中文名 | ODS 表 | 字段数 |
|-----|--------|--------|--------|
| [GetSiteTables](endpoints/site_tables_master.md) | 台桌主数据 | `site_tables_master` | 25 |

### 新增 API（尚未建 ODS 表）

| API | 中文名 | ODS 表 | 字段数 |
|-----|--------|--------|--------|
| [QueryRoleAreaAssociation](endpoints/role_area_association.md) | 角色区域关联 | 无 | 1 |
| [TenantMemberBalanceOverview](endpoints/tenant_member_balance_overview.md) | 会员余额总览 | 无 | 9 |

## 关键发现

### 分页参数差异
- 大多数端点接受 `page` + `limit`
- `GetAllOrderSettleList`、`GetRechargeSettleList`、`GetPayLogListPage` 拒绝 `pageSize`/`pageNo`（HTTP 1400），必须用 `limit`
- `limit` 最大值为 100

### 特殊参数格式
- `GetGoodsInventoryList` 的 `siteId` 必须为数组格式 `[sid]`
- `GetGoodsSalesList` 需要 `isSalesBind`/`goodsSalesType` 业务过滤参数
- `QueryPackageCouponList` 的 `areaId` 为数组格式

### 响应结构差异
- 大多数端点：`{code, data: {list: [...], total}}`
- `settlement_records` / `recharge_settlements`：`{code, data: {settleList: [{siteProfile, settleList: {...}}]}}`
- `stock_goods_category_tree`：`{code, data: {goodsCategoryList: [...]}}`
- `payment_transactions` / `refund_transactions`：记录中嵌套 `siteProfile` 对象

## 与旧文档的关系

旧文档位于 `docs/test-json-doc/`（已废弃），包含：
- `*.json` — 本地 JSON 样本文件（仍可用于离线回放）
- `*-Analysis.md` — 详细字段分析文档（内容已迁移至本目录各端点文档的"详细字段分析"章节）

新文档优势：
- 标准化结构（请求参数表 + 响应字段表 + 详细分析）
- `api_registry.json` 提供机器可读的 API 定义
- `samples/` 目录提供最新响应样本