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