# 租户商品主数据 — 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） |
| 时间范围 | 不需要（全量快照） |
| 响应数据路径 | `data.tenantGoodsList` |

---

## 二、请求

### 请求体（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 个字段，按 9 个逻辑分组说明如下。

---

## 四、响应字段详解（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） |

### 4.9 状态与删除标志

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `is_delete` | int | `0` | 逻辑删除标志：`0` = 未删除，`1` = 已删除（保留档案但前台不展示） |
| `not_sale` | integer | `2` | 是否禁售：`2` = 否（正常销售），`1` = 是（禁止销售）。与 `goods_state` 配合使用 |

---

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

```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/ 确认字段覆盖完整

- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行；补全 1 个缺失字段（commoditycode）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过

- 日期: 2026-02-14
- Prompt: P20260214-130000 — 25 个 API 文档归档至 summary/ + 字段分组修正
- 直接原因: 4.8"时间与删除状态"组混入 not_sale（禁售标志）和 is_delete（删除标志），与时间无关
- 变更摘要: 4.8 拆分为"时间元数据"（2 字段）和 4.9"状态与删除标志"（2 字段）；not_sale 说明补充完整
- 风险与验证: 纯文档分组调整，无运行时影响；验证：统计各组字段数总和 = 31
-->
