初始提交：飞球 ETL 系统全量代码

2026-02-13 08:05:34 +08:00
commit 3c51f5485d
441 changed files with 117631 additions and 0 deletions
--- a/docs/api-reference/stock_goods_category_tree.md
+++ b/docs/api-reference/stock_goods_category_tree.md
@@ -0,0 +1,215 @@
+# 商品分类树 — QueryPrimarySecondaryCategory
+
+> 模块：`TenantGoodsCategory` · ODS 表：`stock_goods_category_tree` · 维度表（全量快照）
+
+---
+
+## 一、接口概述
+
+查询租户级商品分类树，返回完整的两级分类结构（一级大类 + 二级子类），包含分类名称、业务大类归属、库存管理开关等配置。分类树是商品维度的核心维表，所有商品档案、库存记录、销售记录中的分类 ID 均引用本表节点。
+
+| 属性 | 值 |
+|------|-----|
+| 完整路径 | `POST /TenantGoodsCategory/QueryPrimarySecondaryCategory` |
+| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
+| 鉴权 | `Authorization: Bearer <token>` |
+| 分页 | 无分页（一次返回全部） |
+| 时间范围 | 不需要（全量快照） |
+
+---
+
+## 二、请求
+
+### 请求体
+
+无请求参数（`body: null`）。
+
+---
+
+## 三、响应结构
+
+> ⚠️ 注意：本接口响应结构特殊，数据位于 `data.goodsCategoryList`（而非常见的 `data.list`）。
+
+```
+{
+  "code": 200,
+  "data": {
+    "total": 0,
+    "goodsCategoryList": [
+      {
+        "id": ...,
+        "category_name": "槟榔",
+        "categoryBoxes": [
+          { "id": ..., "category_name": "槟榔", "categoryBoxes": [] }
+        ]
+      },
+      ...
+    ]
+  }
+}
+```
+
+`data.goodsCategoryList` 为一级分类节点数组（当前 9 个根节点），每个根节点的 `categoryBoxes` 包含其二级子分类（共 17 个子节点）。树深度固定为 2 层。
+
+`data.total` 当前固定为 `0`，不反映实际分类数量。
+
+---
+
+## 四、响应字段详解
+
+### 4.1 顶层字段
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `total` | int | `0` | 固定为 0，不反映实际分类数量 |
+| `goodsCategoryList` | array | `[{...}, ...]` | 一级分类节点数组，每个节点包含完整的分类信息和子分类列表 |
+
+### 4.2 分类节点字段（父子节点结构完全一致，共 11 个字段）
+
+#### 标识与层级关系
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `id` | int | `2790683528350533` | 分类节点主键 ID，父子节点各有独立 ID，互不重复。全表共 26 个（9 根 + 17 子） |
+| `pid` | int | `0` | 父级分类 ID。根节点 `pid = 0`；子节点 `pid` = 对应父节点的 `id` |
+| `tenant_id` | int | `2790683160709957` | 租户 ID，所有节点相同。分类在租户层级共享，无门店级差异 |
+| `categoryBoxes` | array | `[{...}]` | 子分类数组。根节点包含子节点列表；子节点的 `categoryBoxes` 一律为空数组 `[]`。与 `id`/`pid` 关系冗余，方便前端直接渲染树 |
+
+#### 分类名称
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `category_name` | string | `"槟榔"` | 分类名称。一级大类：槟榔、器材、酒水、果盘、零食、雪糕、香烟、其他、小吃。二级子类如：皮头、球杆、饮料、茶水、咖啡、洋酒、面、其他2 等 |
+| `alias_name` | string | `""` | 分类别名/简称，预留字段，当前全部为空 |
+
+#### 业务大类维度
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `business_name` | string | `"槟榔"` | 业务大类名称。根节点等于自身 `category_name`；子节点继承所属根节点的名称。共 9 种：槟榔、器材、酒水、水果、零食、雪糕、香烟、其他、小吃 |
+| `tenant_goods_business_id` | int | `2790683528317766` | 业务大类 ID，每个 `business_name` 对应唯一一个 ID。根节点和子节点共享同一值 |
+
+#### 配置开关
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `open_salesman` | int | `2` | 营业员/导购提成开关：`2` = 关闭（当前全部统一）。预留按分类差异化配置 |
+| `is_warehousing` | int | `1` | 是否参与库存管理：`1` = 参与。当前所有分类均启用库存管理 |
+| `sort` | int | `1` | 排序序号，用于前端展示顺序。多数为 0，少数为 1 |
+
+---
+
+## 五、响应样例（精简版，展示 2 个根节点）
+
+```json
+{
+  "total": 0,
+  "goodsCategoryList": [
+    {
+      "id": 2790683528350533,
+      "tenant_id": 2790683160709957,
+      "category_name": "槟榔",
+      "alias_name": "",
+      "pid": 0,
+      "business_name": "槟榔",
+      "tenant_goods_business_id": 2790683528317766,
+      "open_salesman": 2,
+      "categoryBoxes": [
+        {
+          "id": 2790683528350534,
+          "tenant_id": 2790683160709957,
+          "category_name": "槟榔",
+          "alias_name": "",
+          "pid": 2790683528350533,
+          "business_name": "槟榔",
+          "tenant_goods_business_id": 2790683528317766,
+          "open_salesman": 2,
+          "categoryBoxes": [],
+          "sort": 0,
+          "is_warehousing": 1
+        }
+      ],
+      "sort": 1,
+      "is_warehousing": 1
+    },
+    {
+      "id": 2790683528350539,
+      "tenant_id": 2790683160709957,
+      "category_name": "酒水",
+      "alias_name": "",
+      "pid": 0,
+      "business_name": "酒水",
+      "tenant_goods_business_id": 2790683528317768,
+      "open_salesman": 2,
+      "categoryBoxes": [
+        {
+          "id": 2790683528350540,
+          "tenant_id": 2790683160709957,
+          "category_name": "饮料",
+          "alias_name": "",
+          "pid": 2790683528350539,
+          "business_name": "酒水",
+          "tenant_goods_business_id": 2790683528317768,
+          "open_salesman": 2,
+          "categoryBoxes": [],
+          "sort": 0,
+          "is_warehousing": 1
+        }
+      ],
+      "sort": 0,
+      "is_warehousing": 1
+    }
+  ]
+}
+```
+
+---
+
+## 六、跨表关联
+
+### 与门店商品档案（`store_goods_master`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `id`（一级节点） | `goods_category_id` | 一级分类主键 |
+| `id`（二级节点） | `goods_second_category_id` | 二级分类主键 |
+| `tenant_goods_business_id` | — | 业务大类 ID，可用于按业务线聚合商品 |
+
+### 与租户商品档案（`tenant_goods_master`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `id`（一级节点） | `goods_category_id` | 一级分类主键 |
+| `id`（二级节点） | `goods_second_category_id` | 二级分类主键 |
+
+### 与库存汇总（`goods_stock_summary`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `id`（一级节点） | `goodsCategoryId` | 一级分类 ID |
+| `id`（二级节点） | `goodsCategorySecondId` | 二级分类 ID |
+
+### 与库存变动（`goods_stock_movements`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `id`（一级节点） | `goodsCategoryId` | 一级分类 ID |
+| `id`（二级节点） | `goodsSecondCategoryId` | 二级分类 ID |
+
+### 与门店销售记录（`store_goods_sales_records`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `id` | `tenant_goods_category_id` | 分类 ID |
+| `tenant_goods_business_id` | `tenant_goods_business_id` | 业务大类 ID |
+
+> 本表是标准的分类维表，构成三层结构：租户（`tenant_id`）→ 业务线（`tenant_goods_business_id`）→ 具体分类（`id` + 父子层级）。
+
+<!--
+AI_CHANGELOG:
+- 日期: 2026-02-13
+- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
+- 直接原因: 按标杆文档格式重写高质量 API 参考文档
+- 变更摘要: 新建 docs/api-reference/stock_goods_category_tree.md，详解分类树结构（11 个节点字段），明确 goodsCategoryList 特殊响应结构，含跨表关联
+- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
+-->