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

2026-02-13 08:05:34 +08:00
commit 3c51f5485d
441 changed files with 117631 additions and 0 deletions
--- a/docs/api-reference/tenant_goods_master.md
+++ b/docs/api-reference/tenant_goods_master.md
@@ -0,0 +1,215 @@
+# 租户商品主数据 — 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）
+
+```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` 间接关联本表
+
+<!--
+AI_CHANGELOG:
+- 日期: 2026-02-13
+- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
+- 直接原因: 按标杆文档格式重写高质量 API 参考文档
+- 变更摘要: 新建 docs/api-reference/tenant_goods_master.md，按逻辑分组详解所有 31 个字段，含跨表关联
+- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
+-->