root/ZQYY.FQ-ETL

Fork 0

Files

Neo 3c51f5485d 初始提交：飞球 ETL 系统全量代码

2026-02-13 08:05:34 +08:00

9.3 KiB

Raw Permalink Blame History

租户商品主数据 — 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": 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` = 已删除（保留档案但前台不展示）

五、响应样例（单条记录）

{
  "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 间接关联本表

9.3 KiB Raw Permalink Blame History Unescape Escape