# API 参考文档

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

## 目录结构

```
docs/api-reference/
├── README.md                 # 本文件（索引）
├── api_registry.json         # API 注册表（标准化参数存储）
├── _api_call_results.json    # API 调用结果（字段提取）
├── summary/                  # 每个 API 一个精简版 .md 文档（字段表 + 跨表关联）
│   ├── assistant_accounts_master.md
│   ├── ...（共 25 个）
│   └── tenant_member_balance_overview.md
├── endpoints/                # 每个 API 一个详细版 .md 文档（完整字段分析）
│   ├── assistant_accounts_master.md
│   ├── ...（共 24 个）
│   └── tenant_member_balance_overview.md
└── samples/                  # 每个 API 的响应样本（Top-5 最全记录 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 |

### 会员统计与总览（待建 ODS 表）

| API | 中文名 | ODS 表 | 字段数 |
|-----|--------|--------|--------|
| [QueryMemberConsumptionStatistics](summary/member_consumption_statistics.md) | 会员消费统计 | `member_consumption_statistics`（待建） | 11 |
| [TenantMemberBalanceOverview](summary/tenant_member_balance_overview.md) | 会员余额总览 | `tenant_member_balance_overview`（待建） | 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/` 目录提供最新响应样本


<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-171500 — API 文档全面重构
- 直接原因: 创建 API 参考文档索引
- 变更摘要: 新建 README.md，包含 25 个 API 端点索引表、关键发现、与旧文档的关系说明
- 风险与验证: 纯文档，无运行时影响

- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: api_registry.json 中 17 个 data_path 修正为实际 API 返回路径；24 个 .md 文档新增响应数据路径行；10 个文档补全 39 个缺失字段
- 变更摘要: api_registry.json data_path 修正（本文件为 JSON 不支持注释，changelog 记录于此）
- 风险与验证: 纯文档变更，api_registry.json 仅被 scripts/ 下比对脚本读取，不影响 ETL 运行时

- 日期: 2026-02-14
- Prompt: P20260214-083000 — 替换 role_area_association 为 member_consumption_statistics + tenant_member_balance_overview ODS 表标注
- 直接原因: role_area_association 非业务数据，替换为 QueryMemberConsumptionStatistics；同步更新索引表和 api_registry.json
- 变更摘要: 索引表"新增 API"章节替换为"会员统计与总览"；api_registry.json 替换 role_area_association 条目、tenant_member_balance_overview ods_table 从 null 改为表名
- 风险与验证: 纯文档变更；验证：python -c "import json; d=json.load(open('docs/api-reference/api_registry.json')); print(len(d))" → 25

- 日期: 2026-02-14
- Prompt: P20260214-130000 — 25 个 API 文档归档至 summary/ + 字段分组修正
- 直接原因: 25 个精简版 API 文档从根目录移至 summary/ 子目录，README 目录结构需同步更新
- 变更摘要: 目录结构树中新增 summary/ 子目录说明
- 风险与验证: 纯文档变更，无运行时影响
-->
