# 商品分类树 — QueryPrimarySecondaryCategory

> 模块：`TenantGoodsCategory` · ODS 表：`stock_goods_category_tree` · 维度表（全量快照）

---

## 一、接口概述

查询租户级商品分类树，返回完整的两级分类结构（一级大类 + 二级子类），包含分类名称、业务大类归属、库存管理开关等配置。分类树是商品维度的核心维表，所有商品档案、库存记录、销售记录中的分类 ID 均引用本表节点。

| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /TenantGoodsCategory/QueryPrimarySecondaryCategory` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | 无分页（一次返回全部） |
| 时间范围 | 不需要（全量快照） |
| 响应数据路径 | `data.goodsCategoryList` |

---

## 二、请求

### 请求体

无请求参数（`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/ 确认字段覆盖完整

- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行（记录 API 实际返回的数据路径）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过
-->
