118 lines
5.8 KiB
Markdown
118 lines
5.8 KiB
Markdown
# 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/` 目录提供最新响应样本
|