# 租户商品主数据 — 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 ` | | 分页 | `page` + `limit`（最大 100） | | 时间范围 | 不需要（全量快照） | --- ## 二、请求 ### 请求体（JSON） ```json { "costPriceType": 0, "ableDiscount": -1, "tenantGoodsStatus": 0, "page": 1, "limit": 100 } ``` ### 参数说明 | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | `costPriceType` | int | 是 | 成本价类型筛选。`0` = 全部，`1` = 固定成本价，`2` = 动态成本价 | | `ableDiscount` | int | 是 | 是否可折扣筛选。`-1` = 全部，`1` = 允许折扣 | | `tenantGoodsStatus` | int | 是 | 商品状态筛选。`0` = 全部，`1` = 正常/上架 | | `page` | int | 是 | 页码，从 1 开始 | | `limit` | int | 是 | 每页条数，最大 100 | --- ## 三、响应结构 ``` { "code": 200, "data": { "list": [ { ... }, { ... } ], "total": 156 } } ``` `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` = 已删除（保留档案但前台不展示） | --- ## 五、响应样例（单条记录） ```json { "categoryName": "饮料", "isInSite": false, "commodityCode": ["10000028"], "id": 2791925230096261, "tenant_id": 2790683160709957, "goods_name": "东方树叶", "goods_cover": "https://oss.ficoo.vip/admin/ZwS8fj_1753175129443.jpg", "goods_state": 1, "goods_category_id": 2790683528350539, "unit": "瓶", "supplier_id": 0, "create_time": "2025-07-15 17:13:15", "is_delete": 0, "goods_second_category_id": 2790683528350540, "cost_price": 0.0, "market_price": 8.0, "pinyin_initial": "DFSY,DFSX", "goods_bar_code": "", "able_discount": 1, "min_discount_price": 0.0, "commodity_code": "10000028", "goods_number": "1", "update_time": "2025-10-29 23:51:38", "cost_price_type": 1, "remark_name": "", "sale_channel": 1, "able_site_transfer": 2, "common_sale_royalty": 0, "point_sale_royalty": 0, "is_warehousing": 1, "out_goods_id": 0 } ``` --- ## 六、跨表关联 ### 与门店商品档案（`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` 间接关联本表