# 商品分类树（QueryPrimarySecondaryCategory）

> 自动生成于 2026-02-13 | 数据来源：实时 API

## 基本信息

| 属性 | 值 |
|------|-----|
| 接口路径 | `TenantGoodsCategory/QueryPrimarySecondaryCategory` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/TenantGoodsCategory/QueryPrimarySecondaryCategory` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `stock_goods_category_tree` |
| 分页方式 | 无分页 |
| 时间范围 | 不需要 |

## 请求参数

无（`body: null`）

## 响应字段（共 2 个）

| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `total` | int | 0 |
| 2 | `goodsCategoryList` | array | [{'id': 2790683528350533, 'tenant_id': 2790683160709957, ... |

## 详细字段分析

> 以下内容迁移自旧版 `stock_goods_category_tree-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。

一、文件内容类型与整体结构

实际内容类型判断

从文件内部结构看，这个 JSON 并不是“库存变化明细流水”，而是：

一个用于库存模块的 “商品分类（含业务大类）树形配置”。

顶层对象是商品分类列表 goodsCategoryList。

每条记录表示一个“商品分类节点”，支持父子层级（大类 / 子类）。

所有分类都标记了 is_warehousing = 1，说明这些分类下的商品会进入库存管理。

结合文件名可以推断：
库存变化界面的筛选条件中需要“按商品分类过滤”，这个文件就是该页面请求返回的“分类维度数据”。

二、分类节点结构与字段说明

分类节点字段集合（父子完全一致，共 11 个字段）：

id
tenant_id
category_name
alias_name
pid
business_name
tenant_goods_business_id
open_salesman
categoryBoxes
sort
is_warehousing

1. 标识与层级关系字段
1.1 id

类型：int

含义：分类节点主键 ID（在商品分类维度中的唯一标识）。

特征：

父子节点各有独立的 id，互不重复。

全表总共有 26 个不同的 id（9 个根节点 + 17 个子节点）。

1.2 pid

类型：int

含义：父级分类 ID。

取值规则：

对于根节点：pid = 0。

对于子节点：pid = 对应父节点的 id。

树结构示例（部分）：

根：器材（id=2790683528350535, pid=0）

子：皮头（pid=2790683528350535）

子：球杆（pid=2790683528350535）

子：其他（pid=2790683528350535）

根：酒水（id=2790683528350539, pid=0）

子：饮料、酒水、茶水、咖啡、加料、洋酒（pid 都等于根节点 id）

结构结论：id + pid 组成了标准的父子树关系，可以不依赖 categoryBoxes，直接自下而上追溯父级。

1.3 categoryBoxes

类型：list

含义：子分类数组。

特征：

根节点 categoryBoxes 为非空，包含若干子节点。

子节点的 categoryBoxes 一律为空数组 []，树深度为 2 层。

作用：

是对 id/pid 关系的树形展开，方便前端直接渲染树，无需自己拼接层级。

从结构角度看，同一层级关系既可以通过 pid 还原，也可以直接通过 categoryBoxes 读取，属于冗余表示。

总结：
树结构的 核心外键关系 为 pid 指向父节点的 id；categoryBoxes 为“展开后的子节点列表”，两者信息完全一致，只是展现形式不同。

2. 租户维度字段
2.1 tenant_id

类型：int

含义：租户 ID（品牌/商户 ID）。

取值：

所有节点（父子合计 26 条）的 tenant_id 完全相同。

说明：

因为本次导出只有一个门店，tenant_id 在所有 JSON 中都是同一个值，用来标识“朗朗桌球”所在的商户。

没有 site_id 字段，说明商品分类是在“租户层级”共享的，而非每个门店单独一套分类（本店只有一个门店，这一点在结果上体现为统一）。

3. 分类名称类字段
3.1 category_name

类型：string

含义：分类名称（实际业务分类名称）。

观测到的不同值（共 18 个）：

一级大类：槟榔、器材、酒水、水果、零食、雪糕、香烟、其他、小吃

二级子类：槟榔、皮头、球杆、其他、饮料、酒水、茶水、咖啡、加料、洋酒、果盘、零食、面、雪糕、香烟、其他2、小吃

说明：

分类名称用于商品档案、销售记录等的分类显示，是前台展示的主要维度之一。

二级分类丰富了同一业务线下的细分类型（例如“酒水”下面拆成“饮料/酒水/茶水/咖啡/加料/洋酒”）。

3.2 alias_name

类型：string

观测值：全部为 ""（空字符串）。

含义：

预留的“别名”字段，可用于：

分类别名；

简称（如“热饮”→“热”）。

当前门店未使用此功能。

4. 业务大类维度字段

这是本文件中很重要的一组结构信息，用于把多个细分类归入同一业务线。

4.1 business_name

类型：string

含义：业务大类名称。

观测值（共 9 个，与根节点的类别一致）：

槟榔、器材、酒水、水果、零食、雪糕、香烟、其他、小吃

特征：

根节点的 business_name 等于自身的 category_name；

子节点的 business_name 等于其所在的根节点的 category_name：

例：饮料、茶水、咖啡、加料、洋酒等的 business_name 都是 "酒水"；

皮头、球杆、器材-其他的 business_name 都是 "器材"；

面、果盘、零食 的 business_name 都是 "水果" 或 "零食" 等（根据挂载位置）。

结构结论：

business_name 明确了业务线/业务大类，即便子分类名称不同，仍属于同一业务线。

4.2 tenant_goods_business_id

类型：int

含义：业务大类 ID。

分组情况（按 business_name 聚合）：

槟榔 → 1 个 ID

器材 → 1 个 ID

酒水 → 1 个 ID

水果 → 1 个 ID

零食 → 1 个 ID

雪糕 → 1 个 ID

香烟 → 1 个 ID

其他 → 1 个 ID

小吃 → 1 个 ID
（即每个 business_name 对应唯一一个 tenant_goods_business_id）

特征：

根节点和子节点共享同一个 tenant_goods_business_id（按业务线划分）。

例如：

“酒水”根节点和其所有子节点“饮料/酒水/茶水/咖啡/加料/洋酒”都有同一个 tenant_goods_business_id。

结构意义：

构成三层结构：

租户 → tenant_id

业务线 → tenant_goods_business_id + business_name

具体分类 → id + category_name（含父子层级）

库存变化明细、销售明细可以：

按 id 统计（细分类别）；

按 tenant_goods_business_id 聚合（业务大类视角）。

5. 营业员与库存开关字段
5.1 open_salesman

类型：int，枚举。

观测值：全部为 2（共 26 条记录）。

含义（结合命名推断）：

是否启用“营业员”或“导购提成”相关的功能开关。

通常设计上会是类似：

1：开启；

2：关闭；

也可能是反过来，具体以系统配置为准。

数据特征：

全部为同一个值，说明当前门店所有这些分类在“库存变化”模块中采用统一的营业员开关策略，并无针对分类的差异化策略。

结构结论：

这是一个未来可以按分类差异化配置营业员/提成逻辑的预留字段；当前没有分类级别的差异。

5.2 is_warehousing

类型：int，枚举。

观测值：全部为 1。

含义（结合命名）：

是否“走库存 / 参与仓储管理”：

1：参与库存管理；

其他值（推测有 0）：不参与库存（如服务类商品、手工费用、补差价等）。

结构含义：

本文件可视为“所有参与库存管理的商品分类清单”，因此均为 1。

不走库存的分类要么不在本列表，要么在其他配置中 is_warehousing = 0。

6. 排序字段
6.1 sort

类型：int

根节点：

观测值：0 或 1。

子节点：

观测值：0 或 1。

含义：

分类的排序序号，用于前端展示顺序的控制。

数值越小可能越靠前（具体排序规则由前端或服务端设定）。

数据特征：

多数为 0，只有极少数为 1，说明基本上未对分类做精细排序，仅对个别分类做了简单调整。

三、结构关系与与其它数据的潜在关联

虽然这个文件本身不包含“库存变动明细”，但从字段设计可以看出它在整个系统里的位置。

1. 与“库存变化记录1（明细）”的关系（结构推断）

真正的库存变动流水（商品加减库存）记录中，一般会有：

goods_id / sku_id

category_id 或 category_name

tenant_goods_business_id 或 business_name

这里的分类树提供了“类别维度”，用于：

在库存变化列表界面按分类过滤；

在报表中按大类/小类统计库存变化。

结构链接（推断）：

库存变化记录表中的 category_id ↔ 本表的 id。

或者通过 tenant_goods_business_id 进行业务大类聚合。

2. 与“商品档案/门店商品”数据的关系（结构推断）

商品档案（某一 JSON 文件中）常见字段会有：

category_id（商品分类 ID，外键指向这里的 id）；

tenant_goods_business_id（商品所属的业务线，外键指向这里的业务大类）。

结构作用：

确保商品 → 分类树 → 库存统计 之间能通过统一的分类维表联动。

3. 与“门店销售记录 / 出入库记录”的关系（结构推断）

销售记录、出库记录、退货记录等，往往只记录 goods_id，通过商品档案再关联到分类：

销售流水 → 商品档案（goods_id） → 分类 ID（category_id） → 本文件分类树。

本文件在整个数据体系中，是一个标准的维表（分类维度），并不是事实流水表。

四、结构层面的关键信息与线索（不涉及任何盈利或数据指标分析）

树形分类深度为 2 层

根节点 9 个，每个根节点下 0~数个子节点。

没有更深层级（所有子节点的 categoryBoxes 均为空）。

这表明当前门店的分类设计比较扁平：业务大类 + 一层子类 已满足日常库存管理需求。

业务线与分类层级分离设计

通过 business_name + tenant_goods_business_id 定义业务大类；

通过 category_name + id + pid 定义分类树；

子分类的 business_name 固定继承根业务大类，不随子分类名称改变。

这种设计的好处：

可以在报表中按业务线分析（例如“酒水线整体的库存变化”）；

在操作界面可按细分类（如“洋酒”“饮料”）细分过滤。

库存参与与业务开关统一配置

所有分类 is_warehousing = 1，说明“库存变化记录”页面只关心走库存的商品；

所有分类 open_salesman = 2 表示在这一模块中对营业员相关逻辑采用统一开关，不做细分类别区分。

若未来启用无需库存的分类（如服务、台费），很可能不会出现在本文件或会有 is_warehousing = 0 的节点。

租户级共享分类，无门店级差异字段

分类结构中没有 site_id，只有 tenant_id；

对于多门店场景，意味着：同一租户下所有门店共享同一套商品分类结构。

对你当前这个“单店”来说，结果等价于“门店唯一分类配置”，但结构上已经为多店共用做了准备。

冗余字段为前端展示和扩展留空间

alias_name：可用来做别名/简称，本店未用。

table_area_id、card_type_ids 等类似字段在其他文件中已有类似设计模式；这里的 open_salesman、is_warehousing 也是这一类开关/扩展型字段。

这些字段使系统在不改动核心数据结构的情况下，可以增加更多维度的控制（如按分类控制提成、按分类控制是否走库存）。



