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

2026-02-13 08:05:34 +08:00
commit 3c51f5485d
441 changed files with 117631 additions and 0 deletions
--- a/docs/api-reference/endpoints/tenant_goods_master.md
+++ b/docs/api-reference/endpoints/tenant_goods_master.md
@@ -0,0 +1,591 @@
+# 租户商品主数据（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 在多张表中反复出现（销售明细、可能的库存统计视图等），构成统一的“商品分类维度表”。