租户商品主数据 — QueryTenantGoods
模块：TenantGoods · ODS 表：tenant_goods_master · 维度表（全量快照）
一、接口概述
查询租户（品牌）级别的商品主数据，包括商品基础信息、分类归属、价格配置、成本类型、库存管理开关等。每条记录对应一个品牌级商品定义，是商品维度的顶层主档。门店级商品（store_goods_master）通过 tenant_goods_id 引用本表的 id，实现"一个全局商品 → 多个门店商品"的映射。
| 属性 |
值 |
| 完整路径 |
POST /TenantGoods/QueryTenantGoods |
| Base URL |
https://pc.ficoo.vip/apiprod/admin/v1/ |
| 鉴权 |
Authorization: Bearer <token> |
| 分页 |
page + limit（最大 100） |
| 时间范围 |
不需要（全量快照） |
二、请求
请求体（JSON）
参数说明
| 参数 |
类型 |
必填 |
说明 |
costPriceType |
int |
是 |
成本价类型筛选。0 = 全部，1 = 固定成本价，2 = 动态成本价 |
ableDiscount |
int |
是 |
是否可折扣筛选。-1 = 全部，1 = 允许折扣 |
tenantGoodsStatus |
int |
是 |
商品状态筛选。0 = 全部，1 = 正常/上架 |
page |
int |
是 |
页码，从 1 开始 |
limit |
int |
是 |
每页条数，最大 100 |
三、响应结构
data.list 中每个对象即为一条租户商品记录，共 31 个字段，按逻辑分组说明如下。
四、响应字段详解（31 个字段）
4.1 主键与租户维度
| 字段 |
类型 |
示例 |
说明 |
id |
int |
2791925230096261 |
商品档案主键 ID，唯一标识一条品牌级商品。在门店商品表（store_goods_master）中以 tenant_goods_id 引用，在销售记录中同名出现 |
tenant_id |
int |
2790683160709957 |
租户/品牌 ID，所有记录相同。与其他业务表的 tenant_id 一致 |
4.2 分类维度
| 字段 |
类型 |
示例 |
说明 |
categoryName |
string |
"饮料" |
一级分类名称（业务可读展示字段）。共约 14 种：零食、饮料、香烟、其他2、雪糕、酒水、球杆、小吃、面、槟榔等 |
goods_category_id |
int |
2790683528350539 |
一级分类 ID，与分类树（stock_goods_category_tree）中的 id 对应。共 9 个不同值，与 categoryName 一一映射 |
goods_second_category_id |
int |
2790683528350540 |
二级分类 ID，共 14 个不同值。对应分类树中 pid 为一级分类 ID 的子节点 |
4.3 商品基础信息
| 字段 |
类型 |
示例 |
说明 |
goods_name |
string |
"东方树叶" |
商品名称，POS 前台展示、票据打印用。156 条记录全唯一 |
goods_number |
string |
"1" |
商品内部编码（自定义货号），所有记录不重复，用于内部手工输入或导入导出匹配 |
unit |
string |
"瓶" |
计量单位。常见值：包、瓶、个、份、根、盒、杯、桶、盘、支等（约 12 种） |
goods_cover |
string |
"https://oss.ficoo.vip/..." |
商品封面图片 URL（OSS 存储），用于前端展示 |
pinyin_initial |
string |
"DFSY,DFSX" |
拼音首字母/助记码，多别名用逗号分隔。用于前台拼音码快速检索 |
goods_bar_code |
string |
"" |
商品条形码（EAN 等），当前门店未维护，全部为空 |
remark_name |
string |
"" |
商品备注名/别名，预留字段，当前未使用 |
commodity_code |
string |
"10000028" |
商品编码（对外编码），多条商品可共用同一编码，属于"系列编码"而非主键 |
commodityCode |
array |
["10000028"] |
与 commodity_code 相同信息的数组形式（冗余存储），支持一商品多编码场景。当前列表长度均为 1 |
4.4 价格与折扣
| 字段 |
类型 |
示例 |
说明 |
market_price |
float |
8.0 |
商品标价/售价（标准销售单价），单位：元（人民币）。POS 系统默认销售价格 |
cost_price |
float |
0.0 |
成本价格，单位：元。大部分为 0.0（未录入），少数有值如 2.0、2.5、3.0 |
cost_price_type |
int |
1 |
成本价类型枚举：1 = 固定成本价（手工维护），2 = 动态成本价（按采购单平均价结转） |
min_discount_price |
float |
0.0 |
最低允许成交价（限价），单位：元。0.0 表示未设置底价。收银改价时系统校验不低于此值 |
able_discount |
int |
1 |
是否允许参与折扣：1 = 允许。当前所有商品均可打折 |
4.5 库存与门店配置
| 字段 |
类型 |
示例 |
说明 |
is_warehousing |
int |
1 |
是否纳入库存管理：1 = 参与库存管理，0 = 不参与（如纯虚拟商品）。当前全部为 1 |
isInSite |
bool |
false |
是否在当前门店启用/上架。本接口为租户级视角，全部为 false；门店级上架状态在 store_goods_master 中维护 |
able_site_transfer |
int |
2 |
是否允许门店间调拨：2 = 不允许（绝大多数），0 = 未配置（个别记录） |
sale_channel |
int |
1 |
销售渠道类型：1 = 门店线下渠道。当前唯一值 |
goods_state |
int |
1 |
商品状态：1 = 正常/上架。当前所有商品均为正常状态 |
4.6 佣金与提成
| 字段 |
类型 |
示例 |
说明 |
common_sale_royalty |
int |
0 |
普通销售提成配置，当前未启用，全部为 0 |
point_sale_royalty |
int |
0 |
积分销售提成/积分赠送规则配置，当前未启用，全部为 0 |
4.7 供应商
| 字段 |
类型 |
示例 |
说明 |
supplier_id |
int |
0 |
供应商 ID，用于关联供应商档案。当前所有商品未挂接供应商，全部为 0 |
out_goods_id |
int |
0 |
外部系统商品 ID（对接第三方平台用），当前未启用，全部为 0 |
4.8 时间与删除状态
| 字段 |
类型 |
示例 |
说明 |
create_time |
string |
"2025-07-15 17:13:15" |
商品档案创建时间 |
update_time |
string|null |
"2025-10-29 23:51:38" |
最近修改时间。null 表示自创建以来未被修改（约 28 条为 null） |
is_delete |
int |
0 |
逻辑删除标志：0 = 未删除，1 = 已删除（保留档案但前台不展示） |
五、响应样例（单条记录）
六、跨表关联
与门店商品档案（store_goods_master）
| 本表字段 |
关联表字段 |
说明 |
id |
tenant_goods_id |
品牌级商品 → 门店级商品。一个全局商品可在多个门店生成多条门店商品记录 |
goods_category_id |
goods_category_id |
一级分类 ID 一致 |
goods_second_category_id |
goods_second_category_id |
二级分类 ID 一致 |
unit |
unit |
计量单位一致 |
与门店销售记录（store_goods_sales_records）
| 本表字段 |
关联表字段 |
说明 |
id |
tenant_goods_id |
品牌级商品 ID，用于追溯销售明细对应的全局商品定义 |
goods_category_id |
tenant_goods_category_id |
一级分类 ID |
与商品分类树（stock_goods_category_tree）
| 本表字段 |
关联表字段 |
说明 |
goods_category_id |
id（一级节点） |
一级分类主键 |
goods_second_category_id |
id（二级节点） |
二级分类主键 |
与库存相关表
store_goods_master.id（门店商品 ID）通过 tenant_goods_id 回溯到本表- 库存汇总（
goods_stock_summary）和库存变动（goods_stock_movements）通过 siteGoodsId 关联门店商品，再经 tenant_goods_id 间接关联本表
