# 租户商品主数据（QueryTenantGoods）

> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本

## 基本信息

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

## 请求参数

| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `costPriceType` | int | `0` | 成本价类型（0=全部） |
| `ableDiscount` | int | `-1` | 是否可折扣（-1=全部） |
| `tenantGoodsStatus` | int | `0` | 商品状态（0=全部） |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |

## 响应字段（共 31 个）

| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `categoryName` | string | '饮料' |
| 2 | `isInSite` | bool | False |
| 3 | `commodityCode` | array | ['10000028'] |
| 4 | `id` | int | 2791925230096261 |
| 5 | `tenant_id` | int | 2790683160709957 |
| 6 | `goods_name` | string | '东方树叶' |
| 7 | `goods_cover` | string | 'https://oss.ficoo.vip/admin/ZwS8fj_1753175129443.jpg' |
| 8 | `goods_state` | int | 1 |
| 9 | `goods_category_id` | int | 2790683528350539 |
| 10 | `unit` | string | '瓶' |
| 11 | `supplier_id` | int | 0 |
| 12 | `create_time` | string | '2025-07-15 17:13:15' |
| 13 | `is_delete` | int | 0 |
| 14 | `goods_second_category_id` | int | 2790683528350540 |
| 15 | `cost_price` | float | 0.0 |
| 16 | `market_price` | float | 8.0 |
| 17 | `pinyin_initial` | string | 'DFSY,DFSX' |
| 18 | `goods_bar_code` | string | '' |
| 19 | `able_discount` | int | 1 |
| 20 | `min_discount_price` | float | 0.0 |
| 21 | `commodity_code` | string | '10000028' |
| 22 | `goods_number` | string | '1' |
| 23 | `update_time` | string | '2025-10-29 23:51:38' |
| 24 | `cost_price_type` | int | 1 |
| 25 | `remark_name` | string | '' |
| 26 | `sale_channel` | int | 1 |
| 27 | `able_site_transfer` | int | 2 |
| 28 | `common_sale_royalty` | int | 0 |
| 29 | `point_sale_royalty` | int | 0 |
| 30 | `is_warehousing` | int | 1 |
| 31 | `out_goods_id` | int | 0 |

## 新增字段（相对本地 JSON 样本）

以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：

| 字段名 | 类型 |
|--------|------|
| `not_sale` | int |

## 详细字段分析

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

二、单条商品档案记录字段说明（31 个字段）

为便于理解，按逻辑分组说明。

1. 主键与租户维度字段

id

类型：int

含义：商品档案主键 ID，唯一标识一条商品。

作用：作为其他业务表（销售明细、库存流水、门店商品表等）的外键，通常以 tenant_goods_id 或类似字段出现。

tenant_id

类型：int

当前值：全表 156 条记录均为同一个值。

含义：租户/品牌 ID。

作用：和其它 JSON 中的 tenant_id / tenantId 一致，用于区分不同商户（本次数据只包含同一租户）。

2. 分类维度字段

categoryName

类型：string

含义：商品一级分类名称（业务可读）。

取值情况：

共 14 种分类名称，出现频次较高的包括：

零食（43 条）

饮料（34 条）

香烟（16 条）

其他2（16 条）

雪糕（13 条）

酒水、球杆、小吃、面、槟榔 等。

说明：纯展示用名称，真实关联通过下面的 goods_category_id / goods_second_category_id 完成。

goods_category_id

类型：int

含义：商品一级分类 ID。

取值情况：

共 9 个不同 ID，例如：

一个 ID 对应 46 条、一个对应 45 条、其他若干个对应 10 条以内。

特征：

明显是“分类维度”的主键，和某个“分类表”关联（本次导出中未单独给出分类表）。

各 ID 与 categoryName 一一对应（同一 ID 对应的名称相同）。

goods_second_category_id

类型：int

含义：商品二级分类 ID。

取值情况：

共 14 个不同 ID，与一级分类进一步细分。

分布上，一般跟 categoryName 的细分类对应，如“饮料”下的不同子类。

使用场景：

在销售明细/统计报表中，用于按二级分类汇总。

小结：

categoryName 是分类名称展示字段；

goods_category_id / goods_second_category_id 是分类 ID，用于与“商品分类维表”关联；

其它业务 JSON（例如商品销售明细）中也出现这两个字段，用来做分类维度联表。

3. 商品基础信息字段

goods_name

类型：string

含义：商品名称（前台展示名称）。

特征：

156 条记录全唯一，例如“东方树叶”“红烧牛肉面”“百威235毫升”“雪碧”“双中支中华”等。

用途：

POS 前台展示、票据打印等。

remark_name

类型：string

当前值：全部为 ""（空字符串）。

含义（从命名推断）：商品备注名/别名，通常用来配置简写或特殊显示名称。

当前门店尚未使用该字段，字段设计为将来扩展预留。

goods_number

类型：string

含义：商品内部编码（自定义货号/系统货号）。

特征：

所有 156 条记录均不重复，例如 "1", "2", "3", "4", ...，还有 "10", "11" 等。

使用场景：

作为内部手工输入编码、或导入导出时的匹配字段。

pinyin_initial

类型：string

含义：拼音首字母/助记码。

特征：

156 条记录全不同，如 'DFSY,DFSX', 'HSNRM,GSNRM', 'SRC', 'BW235HS', 'SP' 等；

格式有的是拼音首字母组合，有的是字母+数字混合，说明可能用于多关键字检索。

用途：

前台“拼音码搜索”用的检索字段。

unit

类型：string

含义：计量单位。

取值（共 12 种左右）：

常见：包、瓶、个、份、根、盒、杯、桶、盘、支 等。

用途：

决定库存单位、销售单位（例如“按瓶卖”还是“按包卖”）。

goods_cover

类型：string

含义：商品封面图片 URL 地址。

特征：

共 123 个不同 URL，其中部分同一商品系列共享一张图片（例如某个 URL 出现 34 次）。

用途：

用于前端展示商品图片。

goods_bar_code

类型：string

当前值：全部为 ""（空）。

含义：商品条码（EAN 等），目前未维护。

说明：

字段设计上是用来对接扫码枪的，但当前门店商品条码没有录入。

out_goods_id

类型：int

当前值：全部为 0。

含义（推测）：外部系统商品 ID（对接第三方平台使用，如外卖、线上商城等）。

当前未启用外部对接，因此全部为 0。

commodity_code

类型：string

含义：商品编码（通常为对外商品编码或条码）。

特征：

共 35 种取值，其中：

"10000" 出现 85 条；

"100000" 出现 35 条；

还有 "100017", "100026", "0000000", "10000028", "10000002" 等。

说明：

多条不同 id 的商品可以共用同一个 commodity_code，说明它是某种“系列编码”或“外部编码”而非商品主键。

commodityCode

类型：list（列表内只有一个字符串元素）

示例：['10000']，['100000'] 等。

含义：

与 commodity_code 是同一信息的数组形式（冗余存储），便于支持一个商品对应多个编码的场景。

当前实际使用中，一条记录只有一个编码，因此列表长度均为 1。

4. 价格与折扣相关字段

market_price

类型：float

含义：商品标价 / 售价（标准销售单价）。

特征：

共 45 个不同价格，常见价格如 2、5、6、8、10、12、15、18、20、28 等。

用途：

POS 系统默认销售价格，结算时的基础价格。

min_discount_price

类型：float

含义：该商品允许售卖的最低价格（底价）。

特征：

共 41 个不同价格，分布包括 0.0（32 条）、6、4、15、7、8、5、10、3、28 等。

说明：

0.0 可能表示“未设置底价”或“按系统默认规则”。

cost_price

类型：float

含义：成本价格。

特征：

大部分为 0.0（152 条），少数为 2.0, 2.5, 3.0 等。

说明：

当前门店对绝大多数商品未录入成本，仅为少数商品录入了成本价。

该字段用于库存核算、成本统计等场景（本次不做金额分析，仅说明结构）。

cost_price_type

类型：int（枚举）

取值：

1：149 条

2：7 条

含义（推测）：

不同的成本价格来源或计算方式，如：

1：手工录入成本；

2：按最近进货价/加权平均价等自动计算。

具体含义需参考系统字典，但可以确定是“成本类型枚举”。

able_discount

类型：int（枚举）

当前值：全部为 1

含义（推测）：是否允许参与折扣/打折。

1：允许折扣；

其它值（当前未出现）可能代表“禁止打折”。

当前所有商品均标记为可打折。

sale_channel

类型：int（枚举）

当前值：全部为 1

含义（推测）：销售渠道类型，如“门店堂食/线下零售/线上小程序”等的一种编码。

现有数据只有一个值，说明本门店目前仅通过一种渠道销售这些商品。

5. 库存 / 仓储与门店相关字段

is_warehousing

类型：int（枚举）

当前值：全部为 1

含义（推测）：是否启用库存管理。

1：该商品纳入库存管理；

0：不纳入库存管理（例如纯虚拟商品）。

当前所有商品都处于“有库存管理”的状态。

isInSite

类型：bool

当前值：全部为 False

含义（从命名推测）：是否在当前门店启用/上架。

现象：

虽然导出指定了某个门店，但这里全部为 False，说明这个文件更偏向“租户级商品库视角”，而不是“门店已上架商品视角”；

具体含义可能是“是否已同步到某个特定门店”，当前视图可能没启用这个标志。

able_site_transfer

类型：int（枚举）

取值：

2：155 条

0：1 条

含义（推测）：

字面意思是“是否允许门店间调拨/门店级操作”：

2：允许（或默认可调拨）；

0：不允许。

值使用 2 而非 1，说明内部枚举可能是多态（例如 1=未配置、2=允许、0=禁止），具体需结合系统配置才可精准解释。

当前有一条商品配置为 0，与其他商品行为可能存在差异。

goods_state

类型：int（枚举）

当前值：全部为 1

含义（推测）：商品状态（上架/下架等）。

1：正常/上架；

其他值（本数据未出现）可能表示下架、停用等状态。

6. 佣金 / 提成 / 积分相关字段

common_sale_royalty

类型：int

当前值：全部为 0

含义（推测）：普通销售提成比例或提成金额的配置字段。

当前门店未在商品档案上配置员工提成规则，全部为 0。

point_sale_royalty

类型：int

当前值：全部为 0

含义（推测）：积分销售提成/积分赠送规则相关配置。

当前同样未启用。

说明：
这两个字段与促销、积分、提成等高级功能相关，当前仅作为预留字段存在，未实际配置。

7. 供应商相关字段

supplier_id

类型：int

当前值：全部为 0

含义：供应商 ID，用于关联到供应商档案。

当前所有商品都未挂接具体供应商（或门店未使用供应链管理模块）。

8. 时间与删除状态字段

create_time

类型：string（时间）

格式：YYYY-MM-DD HH:MM:SS

含义：商品档案创建时间。

特征：

156 条记录全部有值，全部唯一。

update_time

类型：string 或 null

含义：商品档案最近一次修改时间。

分布：

null（或 None）：28 条，表示自创建以来未被修改；

其余为不同时刻的更新时间。

用途：

用于增量同步、数据对账等（只需要处理 update_time 大于某个时间点的记录）。

is_delete

类型：int（枚举）

当前值：全部为 0

含义：逻辑删除标志。

0：未删除（有效商品）；

1：已删除（逻辑删除，保留档案但前台不再展示）。

当前所有商品均处于“未删除”状态。

三、结构关系与设计线索（从字段/结构角度，不做金额或经营分析）

从 商品档案.json 的字段设计，可以看出以下几点与系统整体结构密切相关的线索：

“租户级商品库”与“门店级商品视图”的区分

tenant_id 存在，但没有 site_id 字段，且 isInSite 全为 False，is_warehousing 全为 1。

说明这一份是 租户维度的商品主档（Brand/集团统一商品列表），而不是某个门店独立维护的商品清单。

门店层的启用/下架、门店特有售价等，很可能在另一张“门店商品表”（比如带 siteId 的 orderGoods 或 siteGoods 表）中维护，这份只是底层档案。

与“商品销售明细/门店销售记录”的关联点

在另一个 JSON 中（门店商品销售明细），出现了 oneCategoryName, twoCategoryName, goods_category_id, goods_second_category_id 等字段。

可以推断：

销售明细中用 tenant_goods_id 或类似字段引用本表的 id；

用 goods_category_id / goods_second_category_id 建立分类维度统计；

goods_name、commodity_code、unit 等在销售明细中会“快照冗余”，方便查询和展示。

与“库存/仓储模块”的接口设计

is_warehousing 全为 1，说明所有商品都被纳入库存管理范围；

cost_price、cost_price_type、supplier_id 等字段，是典型的库存/进销存用途字段；

这意味着：另有库存流水 JSON（如入库单、出库单、盘点记录等），会通过商品 id（或 out_goods_id）与本表关联。

对接外部系统和扫码收银的预留

goods_bar_code 虽然目前为空，但字段设计表明系统支持条码扫描销售；

out_goods_id 预留了外部商品 ID，对接第三方平台（外卖、统一商品库等）时会使用；

commodity_code/commodityCode 强调了一个商品可以有多种编码的可能（当前只有单元素列表）。

可扩展的促销与提成机制

虽然 common_sale_royalty、point_sale_royalty 当前都为 0，但和“助教流水”“销售记录”中的推广/提成字段组合起来，可以构成统一的提成规则体系；

able_discount、min_discount_price、sale_channel 这几个字段一起，构成了商品在不同渠道、不同活动下允许打折的边界控制。

分类维度的稳定主数据角色

categoryName + goods_category_id + goods_second_category_id 说明分类层级已经固化：至少支持“两级分类”；

这些分类 ID 在多张表中反复出现（销售明细、可能的库存统计视图等），构成统一的“商品分类维度表”。