216 lines
9.3 KiB
Markdown
216 lines
9.3 KiB
Markdown
# 租户商品主数据 — 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/ 确认字段覆盖完整
|
||
-->
|