ZQYY.FQ-ETL/docs/api-reference/endpoints/tenant_goods_master.md

租户商品主数据（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 在多张表中反复出现（销售明细、可能的库存统计视图等），构成统一的“商品分类维度表”。