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

2026-02-13 08:05:34 +08:00
commit 3c51f5485d
441 changed files with 117631 additions and 0 deletions
--- a/docs/api-reference/store_goods_master.md
+++ b/docs/api-reference/store_goods_master.md
@@ -0,0 +1,258 @@
+# 门店商品库存主数据 — GetGoodsInventoryList
+
+> 模块：`TenantGoods` · ODS 表：`store_goods_master` · 维度表（快照）
+
+---
+
+## 一、接口概述
+
+查询门店级商品库存主数据，包括商品基础信息、分类、库存数量、价格/成本、状态开关、销售表现等。每条记录对应一个门店维度的商品，是商品维度的核心维表。与租户商品档案（`tenant_goods_master`）通过 `tenant_goods_id` 关联，与库存/销售事实表通过 `id`（即 `site_goods_id`）关联。
+
+| 属性 | 值 |
+|------|-----|
+| 完整路径 | `POST /TenantGoods/GetGoodsInventoryList` |
+| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
+| 鉴权 | `Authorization: Bearer <token>` |
+| 分页 | `page` + `limit`（最大 100） |
+| 时间范围 | 不需要（全量快照） |
+
+---
+
+## 二、请求
+
+### 请求体（JSON）
+
+```json
+{
+  "goodsSecondCategoryId": [],
+  "goodsState": 0,
+  "enableStatus": 0,
+  "siteId": [2790685415443269],
+  "existsGoodsStock": 0,
+  "page": 1,
+  "limit": 100
+}
+```
+
+> ⚠️ 注意：`siteId` 参数必须为数组格式 `[sid]`，而非单个整数值。这是本接口的特殊要求。
+
+### 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `goodsSecondCategoryId` | array | 是 | 二级分类 ID 列表，空数组 `[]` = 全部 |
+| `goodsState` | int | 是 | 商品状态筛选。`0` = 全部，`1` = 正常，`2` = 特殊状态 |
+| `enableStatus` | int | 是 | 启用状态筛选。`0` = 全部，`1` = 启用 |
+| `siteId` | array | 是 | 门店 ID **数组**（如 `[2790685415443269]`）。必须为数组格式 |
+| `existsGoodsStock` | int | 是 | 是否有库存筛选。`0` = 全部 |
+| `page` | int | 是 | 页码，从 1 开始 |
+| `limit` | int | 是 | 每页条数，最大 100 |
+
+---
+
+## 三、响应结构
+
+```
+{
+  "code": 200,
+  "data": {
+    "list": [ { ... }, { ... } ],
+    "total": 161
+  }
+}
+```
+
+`data.list` 中每个对象即为一条门店商品记录，共 45 个字段，按逻辑分组说明如下。
+
+---
+
+## 四、响应字段详解（45 个字段）
+
+### 4.1 门店与租户维度
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID，所有记录相同 |
+| `site_id` | int | `2790685415443269` | 门店 ID，与其他业务表一致 |
+| `siteName` | string | `"朗朗桌球"` | 门店名称，冗余展示字段 |
+
+### 4.2 商品标识与分类
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `id` | int | `2793025851560005` | 门店商品 ID（主键）。在其他表中以 `site_goods_id` / `siteGoodsId` 出现，用于关联库存、销售记录 |
+| `tenant_goods_id` | int | `2792178593255301` | 租户级商品 ID（全局商品 ID），对应 `tenant_goods_master.id`。一个全局商品可在多个门店生成多条门店商品 |
+| `goods_name` | string | `"合味道泡面"` | 商品名称，业务展示字段 |
+| `goods_category_id` | int | `2791941988405125` | 一级分类 ID，对应分类树主键，与 `oneCategoryName` 搭配 |
+| `goods_second_category_id` | int | `2793236829620037` | 二级分类 ID，对应分类树子节点，与 `twoCategoryName` 搭配 |
+| `oneCategoryName` | string | `"零食"` | 一级分类名称，与 `goods_category_id` 一一对应 |
+| `twoCategoryName` | string | `"面"` | 二级分类名称，与 `goods_second_category_id` 对应 |
+| `unit` | string | `"桶"` | 计量单位。常见值：包、瓶、个、份、根、盒、杯、桶、盘、支等 |
+| `goods_cover` | string | `"https://oss.ficoo.vip/..."` | 商品图片 URL（OSS 存储） |
+| `pinyin_initial` | string | `"HWDPM,GWDPM"` | 拼音首字母/助记码，多别名逗号分隔，用于前台拼音检索 |
+| `goods_bar_code` | string | `""` | 商品条形码（EAN 等），当前门店未配置，全部为空 |
+
+### 4.3 库存与数量
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `stock` | int | `18` | 当前可用库存数量（以 `unit` 为单位）。可为 0（售罄）或很大（虚拟库存） |
+| `stock_A` | int | `0` | 副单位库存数量（双单位场景如箱/瓶）。当前门店未启用，全部为 0 |
+| `batch_stock_quantity` | int | `43` | 当前批次库存数量（主单位）。有成本价时 `batch_stock_quantity × cost_price ≈ provisional_total_cost` |
+| `sale_num` | int | `104` | 当前统计口径下的销售数量（总销量），与 `total_sales` 一致 |
+| `total_sales` | int | `104` | 累计销售数量。当前与 `sale_num` 相同，字段保留了区间销量 vs 历史总销量的扩展空间 |
+| `safe_stock` | int | `0` | 安全库存量（阈值），低于此值可提示补货。当前未设置，全部为 0 |
+
+### 4.4 价格、成本与金额
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `sale_price` | float | `12.0` | 标准销售价（挂牌价），单位：元（人民币）。实际结算可能打折 |
+| `cost_price` | float | `0.0` | 成本价（单件成本），单位：元。部分为 0（未录入），部分有值如 1.788 |
+| `cost_price_type` | int | `1` | 成本价类型：`1` = 固定成本价（手工维护），`2` = 动态成本价（按采购单平均价结转） |
+| `provisional_total_cost` | float | `0.0` | 暂估总成本，单位：元。有成本价时 ≈ `batch_stock_quantity × cost_price` |
+| `total_purchase_cost` | float | `0.0` | 总采购成本，单位：元。当前与 `provisional_total_cost` 相等，字段为后续结算/重算成本保留空间 |
+| `min_discount_price` | float | `7.0` | 最低允许成交价（限价），单位：元。`0` 表示不设置限价。收银改价时系统校验不低于此值 |
+| `able_discount` | int | `1` | 是否允许参与折扣：`1` = 允许。当前全部为 1 |
+
+### 4.5 时间与销售表现
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `create_time` | string | `"2025-07-16 11:52:51"` | 门店商品档案创建时间 |
+| `update_time` | string | `"2025-11-09 07:23:47"` | 最后修改时间（价格调整、状态变更等） |
+| `days_available` | int | `13` | 商品在架天数/可售天数。`0` 表示刚建档/刚启用 |
+| `average_monthly_sales` | float | `1.32` | 平均月销量（件/月），辅助补货/品类管理的历史行为指标 |
+
+### 4.6 状态与开关
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `goods_state` | int | `1` | 商品基本状态：`1` = 正常，`2` = 特殊状态（新建/停售/未完整启用，通常 stock=0、days_available=0） |
+| `audit_status` | int | `2` | 审核状态：`2` = 审核通过。其他可能值：`0` = 待提交，`1` = 待审核，`3` = 不通过 |
+| `enable_status` | int | `1` | 启用状态：`1` = 启用，`2` = 停用（未出现） |
+| `send_state` | int | `1` | 上架/可售状态：`1` = 可销售/可下单 |
+| `sale_channel` | int | `1` | 销售渠道：`1` = 门店线下渠道 |
+| `is_warehousing` | int | `1` | 是否纳入库存管理：`1` = 参与库存管理 |
+| `is_delete` | int | `0` | 逻辑删除标志：`0` = 未删除，`1` = 已删除 |
+| `freeze` | int | `0` | 冻结状态：`0` = 未冻结。非 0 可能表示"锁库存""禁止出库" |
+| `forbid_sell_status` | int | `1` | 禁止销售状态：`1` = 未禁止（允许销售），`2` = 被禁止 |
+| `able_site_transfer` | int | `2` | 是否允许跨门店调拨：`2` = 不允许（绝大多数），`0` = 未配置 |
+| `custom_label_type` | int | `2` | 自定义标签类型：`2` = 使用自定义标签/分类 |
+| `option_required` | int | `1` | 是否需要选择规格/选项：`1` = 不要求（单规格商品） |
+
+### 4.7 其他辅助
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `remark` | string | `""` | 商品备注（口味说明、供应商等），当前未使用 |
+| `sort` | int | `100` | 排序权重，用于前端商品列表展示排序 |
+
+---
+
+## 五、响应样例（单条记录）
+
+```json
+{
+  "siteName": "朗朗桌球",
+  "oneCategoryName": "零食",
+  "twoCategoryName": "面",
+  "id": 2793025851560005,
+  "tenant_goods_id": 2792178593255301,
+  "site_id": 2790685415443269,
+  "tenant_id": 2790683160709957,
+  "goods_name": "合味道泡面",
+  "goods_cover": "https://oss.ficoo.vip/admin/8M1WM7_1753204221337.jpg",
+  "goods_state": 1,
+  "goods_category_id": 2791941988405125,
+  "unit": "桶",
+  "sale_num": 104,
+  "cost_price": 0.0,
+  "provisional_total_cost": 0.0,
+  "total_purchase_cost": 0.0,
+  "batch_stock_quantity": 43,
+  "sale_price": 12.0,
+  "stock_A": 0,
+  "stock": 18,
+  "create_time": "2025-07-16 11:52:51",
+  "is_delete": 0,
+  "custom_label_type": 2,
+  "goods_second_category_id": 2793236829620037,
+  "total_sales": 104,
+  "remark": "",
+  "audit_status": 2,
+  "update_time": "2025-11-09 07:23:47",
+  "pinyin_initial": "HWDPM,GWDPM",
+  "goods_bar_code": "",
+  "able_discount": 1,
+  "min_discount_price": 7.0,
+  "sort": 100,
+  "freeze": 0,
+  "days_available": 13,
+  "average_monthly_sales": 1.32,
+  "safe_stock": 0,
+  "send_state": 1,
+  "enable_status": 1,
+  "sale_channel": 1,
+  "able_site_transfer": 2,
+  "cost_price_type": 1,
+  "forbid_sell_status": 1,
+  "is_warehousing": 1,
+  "option_required": 1
+}
+```
+
+---
+
+## 六、跨表关联
+
+### 与租户商品档案（`tenant_goods_master`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `tenant_goods_id` | `id` | 门店商品 → 品牌级商品。一个全局商品可在多个门店生成多条门店商品 |
+| `goods_category_id` | `goods_category_id` | 一级分类 ID 一致 |
+| `goods_second_category_id` | `goods_second_category_id` | 二级分类 ID 一致 |
+
+### 与门店销售记录（`store_goods_sales_records`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `id` | `site_goods_id` | 门店商品主键 → 销售明细中的商品 ID |
+| `tenant_goods_id` | `tenant_goods_id` | 全局商品 ID 一致 |
+
+> 本表是维表，销售记录是事实表。
+
+### 与库存汇总（`goods_stock_summary`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `id` | `siteGoodsId` | 门店商品 ID |
+| `goods_category_id` | `goodsCategoryId` | 一级分类 ID |
+| `goods_second_category_id` | `goodsCategorySecondId` | 二级分类 ID |
+| `unit` | `goodsUnit` | 计量单位 |
+
+### 与库存变动（`goods_stock_movements`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `id` | `siteGoodsId` | 门店商品 ID |
+| `goods_category_id` | `goodsCategoryId` | 一级分类 ID |
+
+### 与商品分类树（`stock_goods_category_tree`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `goods_category_id` | `id`（一级节点） | 一级分类主键 |
+| `goods_second_category_id` | `id`（二级节点） | 二级分类主键 |
+
+> 本表提供 `stock`、`batch_stock_quantity`、成本等某一时刻的快照，库存变动表是全量出入库记录，两者互相补充。
+
+<!--
+AI_CHANGELOG:
+- 日期: 2026-02-13
+- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
+- 直接原因: 按标杆文档格式重写高质量 API 参考文档
+- 变更摘要: 新建 docs/api-reference/store_goods_master.md，按逻辑分组详解所有 45 个字段，含跨表关联；特别标注 siteId 必须为数组格式
+- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
+-->