在准备环境前提交次全部更改。

2026-02-19 08:35:13 +08:00
parent ded6dfb9d8
commit 4eac07da47
1387 changed files with 6107191 additions and 33002 deletions
--- a/apps/etl/connectors/feiqiu/docs/api-reference/README.md
+++ b/apps/etl/connectors/feiqiu/docs/api-reference/README.md
@@ -0,0 +1,149 @@
+# 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/ 子目录说明
+- 风险与验证: 纯文档变更，无运行时影响
+-->