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

docs/api-reference/endpoints/store_goods_master.md

@@ -0,0 +1,747 @@
+# 门店商品库存主数据（GetGoodsInventoryList）
+
+> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
+
+## 基本信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `TenantGoods/GetGoodsInventoryList` |
+| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/TenantGoods/GetGoodsInventoryList` |
+| 请求方法 | `POST` |
+| Content-Type | `application/json` |
+| 鉴权方式 | Bearer Token（`Authorization` 头） |
+| ODS 对应表 | `store_goods_master` |
+| 分页方式 | `page` + `limit`（最大 100） |
+| 时间范围 | 不需要 |
+
+## 请求参数
+
+| 参数名 | 类型 | 示例值 | 说明 |
+|--------|------|--------|------|
+| `goodsSecondCategoryId` | array | `[]` | 二级分类 ID 列表（空=全部） |
+| `goodsState` | int | `0` | 商品状态（0=全部） |
+| `enableStatus` | int | `0` | 启用状态（0=全部） |
+| `siteId` | array | `[2790685415443269]` | 门店 ID |
+| `existsGoodsStock` | int | `0` | 是否有库存（0=全部） |
+| `page` | int | `1` | 页码（从 1 开始） |
+| `limit` | int | `100` | 每页条数（最大 100） |
+
+## 响应字段（共 45 个）
+
+| # | 字段名 | 类型 | 示例值 |
+|---|--------|------|--------|
+| 1 | `siteName` | string | '朗朗桌球' |
+| 2 | `oneCategoryName` | string | '零食' |
+| 3 | `twoCategoryName` | string | '面' |
+| 4 | `id` | int | 2793025851560005 |
+| 5 | `tenant_goods_id` | int | 2792178593255301 |
+| 6 | `site_id` | int | 2790685415443269 |
+| 7 | `tenant_id` | int | 2790683160709957 |
+| 8 | `goods_name` | string | '合味道泡面' |
+| 9 | `goods_cover` | string | 'https://oss.ficoo.vip/admin/8M1WM7_1753204221337.jpg' |
+| 10 | `goods_state` | int | 1 |
+| 11 | `goods_category_id` | int | 2791941988405125 |
+| 12 | `unit` | string | '桶' |
+| 13 | `sale_num` | int | 104 |
+| 14 | `cost_price` | float | 0.0 |
+| 15 | `provisional_total_cost` | float | 0.0 |
+| 16 | `total_purchase_cost` | float | 0.0 |
+| 17 | `batch_stock_quantity` | int | 43 |
+| 18 | `sale_price` | float | 12.0 |
+| 19 | `stock_A` | int | 0 |
+| 20 | `stock` | int | 18 |
+| 21 | `create_time` | string | '2025-07-16 11:52:51' |
+| 22 | `is_delete` | int | 0 |
+| 23 | `custom_label_type` | int | 2 |
+| 24 | `goods_second_category_id` | int | 2793236829620037 |
+| 25 | `total_sales` | int | 104 |
+| 26 | `remark` | string | '' |
+| 27 | `audit_status` | int | 2 |
+| 28 | `update_time` | string | '2025-11-09 07:23:47' |
+| 29 | `pinyin_initial` | string | 'HWDPM,GWDPM' |
+| 30 | `goods_bar_code` | string | '' |
+| 31 | `able_discount` | int | 1 |
+| 32 | `min_discount_price` | float | 7.0 |
+| 33 | `sort` | int | 100 |
+| 34 | `freeze` | int | 0 |
+| 35 | `days_available` | int | 13 |
+| 36 | `average_monthly_sales` | float | 1.32 |
+| 37 | `safe_stock` | int | 0 |
+| 38 | `send_state` | int | 1 |
+| 39 | `enable_status` | int | 1 |
+| 40 | `sale_channel` | int | 1 |
+| 41 | `able_site_transfer` | int | 2 |
+| 42 | `cost_price_type` | int | 1 |
+| 43 | `forbid_sell_status` | int | 1 |
+| 44 | `is_warehousing` | int | 1 |
+| 45 | `option_required` | int | 1 |
+
+## 新增字段（相对本地 JSON 样本）
+
+以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：
+
+| 字段名 | 类型 |
+|--------|------|
+| `commodity_code` | string |
+| `goodsStockWarningInfo` | object |
+| `not_sale` | int |
+| `time_slot_sale` | int |
+
+## 详细字段分析
+
+> 以下内容迁移自旧版 `store_goods_master-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
+
+二、记录级字段详解（45 个字段逐一说明）
+
+我按“维度分类”来拆，确保每个字段都覆盖到。
+
+1. 门店/租户维度
+
+tenant_id
+
+类型：int
+
+含义：租户/品牌 ID。同一品牌下多个门店共享一个 tenant_id。
+
+枚举情况：本文件中为单一固定值（同一品牌）。
+
+site_id
+
+类型：int
+
+含义：门店 ID。
+
+枚举情况：本文件中为单一固定值（同一家门店“朗朗桌球”），和其它 JSON 中的 site_id 一致。
+
+siteName
+
+类型：string
+
+观察值：全为 "朗朗桌球"
+
+含义：门店名称，是对 site_id 的冗余展示，方便直接阅读，无需再去关联门店档案。
+
+2. 商品标识和分类维度
+
+id
+
+类型：int
+
+含义：门店商品 ID，门店维度的商品主键。
+
+用途：在其它文件中经常以 site_goods_id 的名字出现，与这里的 id 一致，用来关联库存记录、销售记录等。
+
+tenant_goods_id
+
+类型：int
+
+含义：租户/品牌维度的商品 ID，相当于“全局商品 ID”。
+
+用途：用于跨门店或与“商品档案（商品档案.json）”对齐时使用。
+
+goods_name
+
+类型：string
+
+含义：商品名称，例如“合味道泡面”“地道肠”“麻将房茶位费”等。
+
+用途：业务展示字段，历史流水里也会冗余存一份商品名。
+
+goods_category_id
+
+类型：int
+
+含义：商品一级分类 ID。
+
+用途：
+
+对应“分类表”（在库存变化记录 2 等文件里）中的主键。
+
+与 oneCategoryName 搭配使用。
+
+goods_second_category_id
+
+类型：int
+
+含义：商品二级分类 ID。
+
+用途：
+
+同样对应分类表中的某个分类 id，其 pid 为一级分类。
+
+与 twoCategoryName 搭配使用。
+
+oneCategoryName
+
+类型：string
+
+含义：一级分类名称，如“零食”“酒水”“服务费”等。
+
+说明：与 goods_category_id 一一对应，是易读文本字段。
+
+twoCategoryName
+
+类型：string
+
+含义：二级分类名称，如“面”“洋酒”“纸巾”等。
+
+说明：与 goods_second_category_id 对应。
+
+unit
+
+类型：string
+
+观察值示例："包", "瓶", "个", "份", "根", "杯", "盒", "桶", "盘", "支" 等。
+
+含义：商品计量单位（销售单位）。
+
+goods_bar_code
+
+类型：string
+
+观察值：当前导出中全部为空字符串。
+
+含义：商品条形码（如 EAN-13 编码），用于扫码销售。此字段设计为可填，但此店目前未配置。
+
+goods_cover
+
+类型：string
+
+含义：商品图片 URL（如 OSS 对象存储地址），用于前端展示商品图片。
+
+pinyin_initial
+
+类型：string
+
+观察值示例："HWDPM,GWDPM", "HJM", "DDC", "QJF150", "15YHGBL" 等。
+
+含义：商品名称的拼音首字母缩写，有时多个别名用逗号分隔。
+
+作用：
+
+用于前端按拼音检索、排序，加快模糊搜索（输入字母即可搜到商品）。
+
+3. 库存与数量相关字段
+
+stock
+
+类型：int
+
+含义：当前可用库存数量（以 unit 为单位）。
+
+特征：可以是 0（库存卖完），也可以非常大（例如纸巾、茶位费这种按“份”计的虚拟库存设定）。
+
+stock_A
+
+类型：int
+
+观察值：本文件全部为 0。
+
+含义（系统设计）：副单位库存数量。如果商品存在双单位（例如箱/瓶），stock_A 通常用于记录副单位库存。当前门店没有启用副单位库存管理，因此为 0。
+
+batch_stock_quantity
+
+类型：int
+
+含义：当前“批次”的库存数量（主单位）。
+
+典型特征：
+
+与 stock 和历史销量有强相关：
+
+对于长期在售商品，batch_stock_quantity 通常大于等于 stock，两者差额可理解为：本批次进货数量减去该批次已消耗数量。
+
+对于刚建档但未真正建立采购记录的商品，可能只是 1 等占位值。
+
+结构性结论：
+
+在有成本价的商品上，batch_stock_quantity × cost_price ≈ provisional_total_cost，说明它是“当前成本批次”的数量基数。
+
+sale_num
+
+类型：int
+
+含义：在当前统计口径下的销售数量（总销量，单位同 unit）。
+
+特征：和 total_sales 完全一致（当前导出时的统计口径下），说明两者是同一统计周期。
+
+total_sales
+
+类型：int
+
+含义（从命名看）：累计销售数量。
+
+实际：当前数据中 total_sales == sale_num，说明此接口的统计区间 = “截至当前的全部历史”，因此数量一致。
+
+结构意义：如果将来系统只查询一段时间，则 sale_num 可能是区间销量，total_sales 可能是历史总销量；字段保留了扩展空间。
+
+safe_stock
+
+类型：int
+
+观察值：全部为 0。
+
+含义：安全库存量（阈值），低于该值时系统可以提示补货。
+
+当前门店尚未设置安全库存，所以全部为 0，仅起到结构占位作用。
+
+4. 价格、成本与金额相关字段
+
+sale_price
+
+类型：float
+
+含义：商品标准销售价（挂牌价），单位为元。
+
+说明：实际结算时可能会打折或用券抵扣，但这个字段表示“定价”。
+
+cost_price
+
+类型：float
+
+含义：商品成本价（单件成本）。
+
+观察：
+
+部分商品为 0（未录入或通过其它方式结转成本），
+
+部分商品为正数，比如“地道肠” cost_price=1.788。
+
+cost_price_type
+
+类型：int，枚举
+
+观察值：
+
+1：154 条
+
+2：7 条
+
+含义（结合成本字段推测）：
+
+1 代表使用“固定成本价”（手工维护的 cost_price），provisional_total_cost 按“数量 × cost_price”算。
+
+2 代表使用“动态成本价”（例如按采购单平均价结转），当前导出中这部分商品 provisional_total_cost 多为 0，说明成本尚未按采购单结转。
+
+provisional_total_cost
+
+类型：float
+
+含义：暂估总成本，单位为元。
+
+观测规律：
+
+对于有成本价的商品，provisional_total_cost ≈ batch_stock_quantity × cost_price（四舍五入差 0.00X 级别）。
+
+结构上的作用：
+
+用于在不逐条展开采购明细的前提下，快速给出当前库存价值的估算。
+
+total_purchase_cost
+
+类型：float
+
+含义：总采购成本，单位为元。
+
+当前数据：与 provisional_total_cost 完全相等。
+
+解释：
+
+从名字看，“total_purchase_cost” 更偏向“已确认采购成本”，而“provisional_total_cost” 更偏向“暂估成本”；在你这份导出中两者还没有区分开来，但字段为后续做结算/重算成本保留了结构空间。
+
+min_discount_price
+
+类型：float
+
+观察值：有的为 0，有的明显小于等于 sale_price（如 sale_price=12, min_discount_price=7）。
+
+含义：最低允许成交价（限价）。
+
+用法逻辑（推测）：
+
+收银/后台手动改价时，系统会校验最终成交价是否 ≥ min_discount_price，低于此价格则不允许成交或需要额外权限。
+
+为 0 时，可能表示“不设置限价/由其它规则控制”。
+
+able_discount
+
+类型：int，枚举
+
+观察值：全部为 1。
+
+含义（结合命名）：
+
+是否允许参与折扣。当前全部为 1，说明所有商品都允许打折。
+
+若系统开启限制，可能会出现 0=不参与任何折扣策略的商品。
+
+5. 时间与销售表现相关字段
+
+create_time
+
+类型：string，格式 YYYY-MM-DD HH:MM:SS
+
+含义：门店商品档案创建时间（商品在门店建立档案的时间点）。
+
+update_time
+
+类型：string
+
+含义：最后一次修改该商品档案的时间（包括价格调整、状态变更等）。
+
+days_available
+
+类型：int
+
+观察值示例：0、1、2、3、12、13、56、100、400、500、2875 等，大范围分布。
+
+含义（结构推断很明确）：
+
+商品“在架天数”或“可售天数”，大致等于当前时间减去首次上架时间。
+
+为 0 的多数是刚建档/刚启用不久的商品。
+
+average_monthly_sales
+
+类型：float
+
+观察值：如 1.32、0.42、13.06、0.16 等。
+
+含义：平均月销量（件/月），根据某个统计周期内的销售数据折算而来。
+
+结构特征：
+
+实际计算公式系统内部掌握即可，你这边只需知道该字段是“历史行为汇总指标”，不参与账务，只是帮助做补货/品类管理的辅助指标。
+
+6. 状态与开关类字段
+
+这类字段很多都是“0/1/2 枚举标志”，需要集中看清。
+
+goods_state
+
+类型：int，枚举
+
+观察值：
+
+1：152 条
+
+2：9 条
+
+结构性判断：
+
+1：正常状态（主流值）。
+
+2：特殊状态（例如“新建未完全启用”、“停售但未下架”等）——这 9 条商品特点是：stock=0、batch_stock_quantity=1、days_available=0，说明它们处于一种“建档但未形成完整库存/销售”的边缘状态。
+
+和 enable_status、send_state 叠加使用，共同确定对外是否可售。
+
+audit_status
+
+类型：int，枚举
+
+观察值：全部为 2。
+
+含义（典型业务语义）：
+
+2：审核通过。
+
+其他值（未在本数据中出现）可能是 0=待提交，1=待审核，3=审核不通过等。
+
+说明：代表这批商品档案已经通过审核，才允许参与业务。
+
+enable_status
+
+类型：int，枚举
+
+观察值：全部为 1。
+
+含义（结合名称与常见编码）：
+
+1：启用。
+
+可能存在 2：停用（未在本数据中出现，但可以推断）。
+
+作用：控制商品档案是否参与任何业务（库存、销售等）。
+
+send_state
+
+类型：int，枚举
+
+观察值：全部为 1。
+
+含义（命名趋近“上架状态/可售状态”）：
+
+1：可销售/可下单。
+
+其它值可能表示“停售”“仅内部使用”等，本数据暂未出现。
+
+备注：和 enable_status、goods_state 一起使用，表达商品对外可售的综合状态。
+
+sale_channel
+
+类型：int，枚举
+
+观察值：全部为 1。
+
+含义：销售渠道类型。
+
+常见模式：
+
+1 可能代表“门店堂食/线下”；
+
+其他值（未出现）可能代表“外卖/线上商城/第三方平台”等。
+
+is_warehousing
+
+类型：int，枚举
+
+观察值：全部为 1。
+
+含义：是否纳入库存管理。
+
+1：启用库存管理（会有出入库流水）。
+
+其他值（0/2）在你其它文件中出现过，一般代表“不计库存”或“历史遗留编码”。
+
+当前门店所有商品都启用了库存管理。
+
+is_delete
+
+类型：int，枚举
+
+观察值：全部为 0。
+
+含义：逻辑删除标志。
+
+0：未删除（有效档案）；
+
+1：已删除（逻辑上删除，不再参与业务，但历史流水保留）。
+
+freeze
+
+类型：int，枚举
+
+观察值：全部为 0。
+
+含义：冻结状态。
+
+0：未冻结；
+
+非 0（未出现在当前数据中）可能表示“锁库存”“禁止出库”等特殊状态。
+
+forbid_sell_status
+
+类型：int，枚举
+
+观察值：全部为 1。
+
+命名上是“禁止销售状态”，结合常见模式：
+
+1：未禁止（允许销售）；
+
+2：被禁止销售（即使上架也不能卖）。
+
+当前门店没有被单独禁售的商品。
+
+able_site_transfer
+
+类型：int，枚举
+
+观察值：
+
+2：160 条
+
+0：1 条
+
+含义（结合命名与值分布）：
+
+表示是否允许跨门店调拨或跨站点共享库存。
+
+2 多半表示“不允许跨店调拨”；0 可能是“未配置/默认值”。
+
+当前门店商品基本都不允许做跨店调拨。
+
+custom_label_type
+
+类型：int，枚举
+
+观察值：全部为 2。
+
+含义（推测）：自定义标签类型。
+
+1：使用系统默认标签（未出现）；
+
+2：使用自定义标签/分类（当前所有商品都为 2）。
+
+从字段名看，和一二级分类、标签打印等功能有关。
+
+option_required
+
+类型：int，枚举
+
+观察值：全部为 1。
+
+含义（推测）：是否需要在销售时选择规格/选项。
+
+1：不要求额外选项（单规格商品）；
+
+若出现其他值，可能代表“必须选择配料/口味/规格”等。
+
+当前门店把所有商品都当作“单规格”处理，未开启复杂选项体系。
+
+able_discount（前面已分析）
+
+类型：int，枚举
+
+观察值：全部为 1，表示所有商品允许参与折扣。
+
+**send_state / enable_status / goods_state 综合说明：
+
+这三个字段都与商品状态相关，但侧重点不同：
+
+goods_state：商品基本状态（建档层面的状态）。
+
+enable_status：是否启用这条商品档案。
+
+send_state：是否在销售端可下单。
+
+当前数据看：绝大多数商品是完全“正常可售”的状态（1/1/1），有少数 goods_state = 2 的边缘状态商品，其他两个字段依然是启用和可售，说明 goods_state 主要用于后台管理上的状态区分。
+
+7. 其它辅助字段
+
+remark
+
+类型：string
+
+观察值：全部为空字符串。
+
+含义：商品备注（可以写口味说明、供应商、注意事项等）。当前尚未使用。
+
+sort
+
+类型：int
+
+观察值：如 100、120 等。
+
+含义：排序权重，用于前端商品列表展示时的排版顺序，数值越小/越大哪个优先，具体规则看系统设定（一般是数值越小排序越靠前）。
+
+batch_stock_quantity / total_purchase_cost / provisional_total_cost 关系补充
+
+对于成本价非 0 的商品，大致满足：
+
+total_purchase_cost ≈ batch_stock_quantity × cost_price
+
+provisional_total_cost ≈ total_purchase_cost
+
+说明：
+
+这套字段主要服务于库存价值估算，和盈利分析无关，是为后续进销存对账、成本核算准备的结构。
+
+三、字段枚举与可能取值小结
+
+为方便后续开发或建模使用，枚举字段集中整理如下（仅基于当前导出数据推断）：
+
+goods_state：
+
+1：正常状态（主流值）
+
+2：特殊状态（新建/停售/未完整启用，配合 stock=0、days_available=0）
+
+audit_status：
+
+2：审核通过（当前唯一值）
+
+enable_status：
+
+1：启用（当前唯一值；停用值未出现在数据中）
+
+send_state：
+
+1：可销售（当前唯一值）
+
+sale_channel：
+
+1：线下门店渠道（当前唯一值）
+
+is_warehousing：
+
+1：参与库存管理（当前唯一值）
+
+is_delete：
+
+0：未删除（当前唯一值）
+
+freeze：
+
+0：未冻结（当前唯一值）
+
+forbid_sell_status：
+
+1：未被禁止销售（当前唯一值）
+
+able_site_transfer：
+
+2：不允许跨店/跨站点调拨（绝大多数记录）
+
+0：未配置（个别记录）
+
+cost_price_type：
+
+1：固定成本价
+
+2：动态成本价（暂未生成实际成本）
+
+custom_label_type：
+
+2：自定义标签（当前唯一值）
+
+option_required：
+
+1：不要求额外选项（单规格商品）
+
+able_discount：
+
+1：允许参与折扣（当前唯一值）
+
+四、从结构角度看，这个文件在整体数据体系中的位置
+
+虽然你目前只要求这个文件本身的字段分析，但结合之前已看过的其它 JSON，可以从字段结构看出以下几条重要关系（纯结构角度，不做任何金额/盈利分析）：
+
+与“商品档案（全局）”的关系
+
+tenant_goods_id 对应全局商品档案中的 id，表示“品牌维度”的商品。
+
+id 则是“门店维度”的商品 ID，对应其它文件中的 site_goods_id。
+
+这说明：
+
+一个全局商品可以在多个门店下产生多个 id（门店商品），各自维护自己的库存、定价、状态。
+
+与库存类文件的关系
+
+在“库存变化记录”“库存汇总”等文件中，字段 siteGoodsId 就是这里的 id，goodsCategoryId/goodsSecondCategoryId 就是这里的 goods_category_id/goods_second_category_id。
+
+也就是说：
+
+门店商品档案 = 商品“主档”；
+
+库存变化记录 = 商品“流水”；
+
+库存汇总 = 商品“统计汇总”。
+
+本文件提供的 stock、batch_stock_quantity、成本相关字段是某一时刻的快照，而库存变动表是全量出入库记录，两者在结构上互相补充。
+
+与销售类文件的关系
+
+“门店销售记录.json” 中的 site_goods_id 与本文件的 id 对应，tenant_goods_id 也一致。
+
+销售记录只记录每一笔销售的数量和金额；而“门店商品档案”提供了商品的基础信息和聚合信息（如 sale_num、average_monthly_sales等）。
+
+从结构角度看，商品档案是维表，销售记录是事实表。
+
+与分类结构的关系
+
+goods_category_id、goods_second_category_id + oneCategoryName、twoCategoryName 在库存分类文件中也有完全对应的 ID 和名称。
+
+整个系统的分类树（父子关系）由分类表维护，这里只是把“已经归类好”的结果冗余在商品档案里，便于业务侧直接使用。