baison/yudao-ui-admin-vue3
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
13fe5d9124afabd9a93debcb5e0cec5b98e16939
yudao-ui-admin-vue3/src/views/ydoyun/report/lijun/reportpage6/API接口文档.md

1007 lines
46 KiB
Markdown
Raw Normal View History

info
2026-02-27 09:47:06 +08:00
# 报表系统 API 接口文档
## 目录
### 1. 查询条件
- [统一查询参数设计](#10-统一查询参数设计)
- [下拉选项接口](#11-下拉选项接口)
### 2. 顶部数据选项卡
- [KPI 指标数据接口](#21-kpi-指标数据接口)
### 3. 供应商表现 (Top 10) / 品类诊断（共用同一接口）
- [供应商表现与品类诊断接口（统一）](#31-供应商表现与品类诊断接口统一)
- [供应商表现 (Top 10) 更多](#32-供应商表现-top-10-更多)
### 4. 中类销售排名 Top 5
- [中类销售排名 Top 5 接口](#41-中类销售排名-top-5-接口)
- [中类销售排名 Top 5 更多](#42-中类销售排名-top-5-更多)
### 5. 商品明细列表
- [商品明细列表接口](#51-商品明细列表接口)
- [商品明细列表鼠标悬浮框](#52-商品明细列表鼠标悬浮框)
- [商品明细列表更多](#53-商品明细列表更多)
### 6. 品类诊断列表（与品类表现共用接口）
- 数据来源与 [3.1 品类表现与品类诊断接口](#31-品类表现与品类诊断接口统一) 相同，仅展示形式不同（卡片列表）。
### 7. 品类分析页面（category-diagnostic）
- [品类分析页面查询接口](#71-品类分析页面查询接口)
#### 7.1 品类分析页面查询接口
**品类分析页面**（路径 `/reports/lijun/category-diagnostic`）用于展示中类销售排名 Top 5 的详情，以卡片列表形式展示各品类/中类的诊断结果。
#### 接口信息
- **接口路径**: `/api/reportpage/executeProcedureWithData`
- **请求方式**: GET
- **存储过程名**: `YDY_AI_GET_SPDP3`
- **接口说明**: 获取品类分析卡片列表数据；返回所有品类/中类的 list，用于卡片列表展示。
#### 请求参数
与 [统一查询参数设计](#10-统一查询参数设计) 一致，**不传 ghsdm**。
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| reportId | number | 是 | 固定 6 |
| name | string | 是 | 固定 `YDY_AI_GET_SPDP3` |
| rq_s | string | 是 | 开始日期 YYYY-MM-DD |
| rq_e | string | 是 | 结束日期 YYYY-MM-DD |
| ckdm | string | 否 | 门店代码，多选逗号分隔 |
| pp | string | 否 | 品牌代码，多选逗号分隔 |
| dalei | string | 否 | 大类代码，多选逗号分隔 |
| jj | string | 否 | 季节代码，多选逗号分隔 |
| zhonglei | string | 否 | 中类，默认空字符串 |
| p | string | 否 | 秘钥，默认 "123" |
| username | string | 否 | 当前登录用户 |
| ghsdm | string | **不传** | 品类分析页不传；供应商详情页传单个供应商 code |
#### 返回值结构
与供应商详情页**完全一致**：`{ code, msg, data }`，其中 **data** 支持两种形态：
1. **二维数组**：`data = [[列配置数组], [行数据数组]]`
- `data[0]`：列配置（每项含 title、keys/key、orders/order、labelKey、colorKey）
- `data[1]`：行数据 list，每项为一条品类/中类数据（含 title/name、value1、value2、…、value1date、value2date、…、tag、tagcolor、titleName、titleValue 等）
2. **一维数组**（混合）：含 `keys` 的项为列配置，其余为行数据。
前端使用方式：`const columns = data[0]`，`const list = data[1]`；品类分析页用 list 渲染卡片列表，卡片布局包含标题、titleName/titleValue、检测指标/实际结果/基准参考表格。
**针对「中类销售排名 Top 5 更多」**：该页面即品类分析卡片页，查询接口与本节一致（使用 `YDY_AI_GET_SPDP3`，不传 ghsdm）。**返回值结构**及**与页面展示一致的示例数据**（列配置 keys、行数据 title/tag/tagcolor/titleName/titleValue、value1/value1date/value1tag/value1color 等）见 [4.2 中类销售排名 Top 5 更多](#42-中类销售排名-top-5-更多)。
#### 路由与查询条件
- **入口**: 仪表盘「中类销售排名 Top 5」点击「更多」，或直接访问 `/reports/lijun/category-diagnostic`
- **Query 参数**: rq、rq2、ckdm、pp、season、zgj、category、line（与统一查询参数一致），页面加载时从 URL 读取并带入请求。
---
## 1. 查询条件
### 1.0 统一查询参数设计
仪表盘及各子页（中类排名、品类诊断、商品明细、产品卡片）共用一套查询条件，多选参数以**逗号分隔字符串**传给后端。
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| rq / rq_s | string | 是 | 开始日期，格式 YYYY-MM-DD | "2025-01-20" |
| rq2 / rq_e | string | 是 | 结束日期，格式 YYYY-MM-DD | "2025-01-27" |
| ckdm | string | 否 | 门店代码，多选时逗号分隔；可从字典 ljsm_kehu 获取 | "" 或 "S1,S2" |
| pp | string | 否 | 品牌代码，多选时逗号分隔；从 executeTable(pinpai) 获取 | "" 或 "P1,P2" |
| season | string | 否 | 季节代码，多选时逗号分隔；从 executeTable(jijie) 获取 | "" 或 "J1,J2" |
| zgj | string | 否 | 正特价：1=正价，0=特价，多选逗号分隔 | "" 或 "1,0" |
| category | string | 否 | 大类代码，多选时逗号分隔；从 executeTable(dalei) 获取 | "" 或 "D1,D2" |
| line | string | 否 | 线路代码，多选时逗号分隔；从 executeTable(xianlu) 获取 | "" 或 "L1,L2" |
| zhonglei | string | 否 | 中类，默认空字符串 | "" |
| username | string | 否 | 当前登录用户，用于权限与审计 | "admin" |
**说明**：前端多选组件得到数组后，传参时转为逗号拼接，例如 `ckdm: ['S1','S2']` → `ckdm: "S1,S2"`；空数组传空字符串表示不按该维度筛选。
---
### 1.1 下拉选项接口
仪表盘及各子页的下拉选项（品牌、季节、大类、线路、门店）统一通过 **executeTable** 获取。
- **接口路径**: `GET /api/reportpage/executeTable`
- **请求参数**: `{ reportId: 6, tableName: string }`
| tableName | 说明 | 前端用途 | 返回字段映射示例 |
|-----------|------|----------|------------------|
| pinpai | 品牌 | 品牌多选/单选 | PPMC → label, PPDM → value |
| jijie | 季节 | 季节多选 | JJMC → label, JJDM → value |
| dalei | 大类 | 大类/品类多选 | DLMC → label, DLDM → value |
| xianlu 或 line | 线路 | 线路多选 | XLMC/name → label, XLDM/code → value |
| ljsm_kehu | 门店 | 门店多选 | 字典 label/value |
- **reportId** 固定为 **6**。返回为数组或 `{ data/list/rows }` 包裹的数组，前端取 list 后按上表映射为 `{ label, value }[]`。
---
## 2. 顶部数据选项卡
### 2.1 KPI 指标数据接口
#### 接口信息
- **接口路径**: `/api/report/product-dashboard/kpi` 或 使用 **executeProcedureWithData**（reportId=6, name='YDY_AI_GET_SPDP1'）
- **请求方式**: `GET`（executeProcedureWithData 为 GET，若独立接口可为 POST）
- **接口说明**: 获取商品仪表板顶部 KPI 卡片数据：销售总额、平均折扣率、季末售罄率、库存周转、连带率。数据格式与下表一致，**顶部数据卡片数据格式以本节及 kpiCardData 表为准，无需改动**。
#### 请求参数
与 [统一查询参数设计](#10-统一查询参数设计) 一致。
**特殊说明**：若使用 `executeProcedureWithData` 方式调用，需额外传递：
- `reportId`: 固定为 `6`
- `name`: 存储过程/接口名，KPI 为 `YDY_AI_GET_SPDP1`
#### 返回值类型
```json
{
"code": 200,
"msg": "查询成功",
"data": {
"kpiList": [
{
"title": "销售总额 (GMV)",
"unit": "¥",
"value": "842.5",
"valueSuffix": "w",
"trendText": 12,
"trend": "up",
"desc": "目标达成 92%",
"rawValue": 8425000,
"targetValue": 9150000,
"achievementRate": 92,
"miniBars": "33,50,40,75,100,67,50"
},
{
"title": "平均折扣率",
"unit": "%",
"value": "8.2",
"valueSuffix": "折",
"trendText": -0.3,
"trend": "down",
"desc": "毛利空间健康",
"bottomText": "正价占比: 65%",
"rawValue": 8.2,
"targetValue": 8.5
},
{
"title": "季末售罄率",
"unit": "%",
"value": "68.5",
"valueSuffix": "%",
"trendText": 5.2,
"trend": "up",
"desc": "同比提升",
"progress": 68.5,
"rawValue": 68.5,
"targetValue": 70
},
{
"title": "库存周转",
"unit": "Days",
"value": "135",
"trendText": -10,
"trend": "down",
"desc": "效率优化",
"bottomText": "库销比: 4.2 (偏高)",
"rawValue": 135,
"targetValue": 120
},
{
"title": "连带率 (UPT)",
"unit": "件/单",
"value": "1.85",
"trendText": 0.1,
"trend": "up",
"desc": "搭配推荐有效",
"bottomText": "客单价: ¥1,299",
"rawValue": 1.85,
"targetValue": 2.0
}
]
}
}
```
#### 字段含义
| 字段 | 格式 | 必填 | 含义 |
|------|------|------|------|
| code | number | 是 | 响应码：200 表示成功 |
| msg | string | 是 | 响应消息 |
| data.kpiList | array | 是 | KPI 列表 |
| kpiList[].title | string | 是 | 指标标题（如“销售总额 (GMV)”） |
| kpiList[].unit | string | 否 | 单位（如“¥”“%”“Days”“件/单”） |
| kpiList[].value | string | 是 | 展示值（已格式化字符串） |
| kpiList[].valueSuffix | string | 否 | 后缀（如“w”“折”“%”） |
| kpiList[].trendText | number | 是 | 趋势变化值（数值本身，前端据此展示箭头与颜色） |
| kpiList[].trend | string | 是 | 趋势方向：`up` / `down` |
| kpiList[].desc | string | 否 | 描述文案（如“目标达成 92%”） |
| kpiList[].rawValue | number | 否 | 原始值（便于前端二次计算/格式化） |
| kpiList[].targetValue | number | 否 | 目标值 |
| kpiList[].achievementRate | number | 否 | 达成率（百分比 0–100） |
| kpiList[].miniBars | string | 否 | 迷你柱状图数据：逗号分隔数字字符串（仅 GMV 使用） |
| kpiList[].progress | number | 否 | 进度条数值 0–100（仅季末售罄率使用） |
| kpiList[].bottomText | string | 否 | 底部补充说明（如正价占比/库销比/客单价等） |
- **trend**：仅 `up` / `down`，所有指标必填；前端根据 trend 显示箭头与颜色。
- **miniBars**：仅销售总额返回，逗号分隔数字，前端自动加 %，≥100 深色、<100 浅色。
- **progress**：仅季末售罄率返回，0–100。
- **bottomText**：平均折扣率、库存周转、连带率可返回；其他不返回。
---
## 3. 供应商表现 (Top 10) / 品类诊断（共用同一接口）
### 3.1 供应商表现与品类诊断接口（统一）
**供应商表现 (Top 10)** 与 **品类诊断列表** 使用同一接口、同一返回值结构。仪表盘「供应商表现」取前 10 条以表格展示；品类诊断页使用同一接口返回的 list 以卡片列表展示。
#### 接口信息
- **接口路径**: `/api/report/product-dashboard/category-performance` 或 **executeProcedureWithData**（reportId=6, name=**YDY_AI_GET_SPDP2**）
- **请求方式**: GET / POST
- **接口说明**: 获取供应商表现/品类诊断数据，返回结构一致。用于仪表盘「供应商表现 (Top 10)」表格与品类诊断页卡片列表。
#### 返回值结构（data 为二维数组）
接口整体仍为 `{ code, msg, data }`，**其他结构不变**。仅 **data** 改为**二维数组**：
- **data**: `[[列配置数组], [行数据数组]]`
- **第一组** `data[0]`：列配置数组（与下表「列配置」结构一致）。
- **第二组** `data[1]`：行数据数组（list），每行为一条品类对象，字段与「返回值结构（统一字段）」一致。
前端使用方式：`const columns = data[0]`，`const list = data[1]`；仪表盘取 list 前 10 条做表格，品类诊断页用 list 渲染卡片。
#### 请求参数
与 [统一查询参数设计](#10-统一查询参数设计) 一致。
#### 供应商表现 Top 10 表格：列配置与动态列
**列配置** `categoryColumns`（后端返回）：表头与列按此配置渲染，列数不固定。
| 字段名 | 格式 | 必填 | 含义 |
|--------|------|------|------|
| title | string | 是 | 列标题（中文名，直接作为表头显示） |
| key | string | 是 | 该列取值字段名（行数据中对应 key 的值显示在单元格） |
| order | number | 否 | 列排序；数字越小越靠前，用于控制显示顺序 |
| labelKey | string | 否 | 标签取值字段名；有值时在单元格内显示标签，**不单独占一列**；支持**多值逗号拼接**，与 colorKey 一一对应 |
| colorKey | string | 否 | 标签颜色取值字段名；取值为 `up`/`down`/`flat` 或 `green`/`red`/`yellow`；支持**多值逗号拼接**，与 labelKey 按顺序一一对应 |
**行数据** `categoryList`：每行为一条对象。对每一列配置，单元格显示 `row[key]`；若该列配置了 `labelKey` 且 `row[labelKey]` 有值，则在同格内显示标签，颜色由 `row[colorKey]` 决定。**标签与颜色支持多值**：`labelKey`、`colorKey` 对应字段可为逗号分隔字符串，前端按逗号拆成多组，每组「标签 + 颜色」一一对应渲染多个标签。携带“标签”“颜色”的字段仅用于展示标签与颜色，不作为单独列显示。
**示例（单值）**：`{ supplier: "A公司", supplierLabel: "上升", supplierColor: "up" }` → 单元格为「A公司 上升」（「上升」为绿色标签）。
**示例（多值拼接）**：`{ supplier: "A公司", supplierLabel: "上升,持续突破", supplierColor: "up,up" }` → 单元格为「A公司 上升 持续突破」（两个标签均为绿色）。
#### 返回值结构（统一字段，品类诊断共用）
每条数据可包含以下字段；**供应商表现 Top 10** 的列由列配置 + list 动态决定。
| 字段名 | 格式 | 必填 | 含义 |
|--------|------|------|------|
| categoryId | string | 是 | 品类ID |
| name | string | 是 | 品类名称 |
| label | string | 否 | 标签（文字）；支持**多值逗号拼接**，与 trend 按顺序一一对应，如 `"上升,持续突破"` |
| trend | string | 否 | 标签颜色状态；支持**多值逗号拼接**，与 label 一一对应，如 `"up,up"`；单值为 `up`/`down`/`flat`（绿/红/黄） |
| grossProfit | number | 否 | 毛利 |
| grossMarginRate | number | 否 | 毛利率 |
| turnoverDays | number | 否 | 周转天 |
| status | string | 否 | 状态（0全部、1低毛利、2缺货、3积压可多选用,拼接） |
| salesCount | number | 否 | 销量 |
| salesAmount | number | 否 | 销售额 |
| inventoryCount | number | 否 | 库存量 |
| inventoryCost | number | 否 | 库存成本 |
| inventoryTagAmount | number | 否 | 库存吊销额 |
| digestionRate | number | 否 | 消化率 |
| turnoverRate | number | 否 | 动销率 |
| salesCountRef | number | 否 | 销量基准参考 |
| salesAmountRef | number | 否 | 销售额基准参考 |
| inventoryCountRef | number | 否 | 库存量基准参考 |
| inventoryCostRef | number | 否 | 库存成本基准参考 |
| inventoryTagAmountRef | number | 否 | 库存吊销额基准参考 |
| digestionRateRef | number | 否 | 消化率基准参考 |
| turnoverRateRef | number | 否 | 动销率基准参考 |
#### 示例数据（与页面展示一致）
`data` 为**二维数组**：第一组为列配置，第二组为行数据 list。
```json
{
"code": 200,
"msg": "查询成功",
"data": [
[
{ "title": "供应商", "key": "supplier", "order": 1, "labelKey": "supplierLabel", "colorKey": "supplierColor" },
{ "title": "毛利率", "key": "grossMarginRate", "order": 2, "labelKey": "grossMarginRateLabel", "colorKey": "grossMarginRateColor" },
{ "title": "动销率", "key": "turnoverRate", "order": 3, "labelKey": "turnoverRateLabel", "colorKey": "turnoverRateColor" },
{ "title": "销售额", "key": "salesAmount", "order": 4, "labelKey": "salesAmountLabel", "colorKey": "salesAmountColor" }
],
[
{
"categoryId": "C001",
"name": "女装 - 连衣裙",
"label": "销量领先",
"trend": "up",
"supplier": "杭州女装供应链",
"supplierLabel": "上升,持续突破",
"supplierColor": "up,up",
"grossProfit": 1238500,
"grossMarginRate": 42,
"grossMarginRateLabel": "良好",
"grossMarginRateColor": "up",
"turnoverDays": 28,
"status": "0",
"salesCount": 12500,
"salesAmount": 2948750,
"inventoryCount": 12500,
"inventoryCost": 1850000,
"inventoryTagAmount": 3200000,
"digestionRate": 68,
"turnoverRate": 55,
"salesCountRef": 11200,
"salesAmountRef": 2650000,
"inventoryCountRef": 11800,
"inventoryCostRef": 1720000,
"inventoryTagAmountRef": 2980000,
"digestionRateRef": 65,
"turnoverRateRef": 52
},
{
"categoryId": "C002",
"name": "女装 - 休闲裤",
"label": "稳步运行",
"trend": "flat",
"grossProfit": 703300,
"grossMarginRate": 38,
"turnoverDays": 35,
"status": "0",
"salesCount": 8900,
"salesAmount": 1853500,
"inventoryCount": 9800,
"inventoryCost": 1420000,
"inventoryTagAmount": 2450000,
"digestionRate": 62,
"turnoverRate": 48,
"salesCountRef": 8200,
"salesAmountRef": 1690000,
"inventoryCountRef": 9500,
"inventoryCostRef": 1380000,
"inventoryTagAmountRef": 2350000,
"digestionRateRef": 59,
"turnoverRateRef": 45
},
{
"categoryId": "C003",
"name": "女装 - 风衣/外套",
"grossProfit": 606600,
"grossMarginRate": 40,
"turnoverDays": 52,
"status": "3",
"salesCount": 3200,
"salesAmount": 1516500,
"inventoryCount": 8500,
"inventoryCost": 1180000,
"inventoryTagAmount": 2000000,
"digestionRate": 58,
"turnoverRate": 52,
"salesCountRef": 2850,
"salesAmountRef": 1350000,
"inventoryCountRef": 9200,
"inventoryCostRef": 1250000,
"inventoryTagAmountRef": 2150000,
"digestionRateRef": 55,
"turnoverRateRef": 48
},
{
"categoryId": "C004",
"name": "女装 - 衬衫",
"grossProfit": 363960,
"grossMarginRate": 36,
"turnoverDays": 42,
"status": "1",
"salesCount": 6800,
"salesAmount": 1011000,
"inventoryCount": 7200,
"inventoryCost": 920000,
"inventoryTagAmount": 1580000,
"digestionRate": 52,
"turnoverRate": 45,
"salesCountRef": 6400,
"salesAmountRef": 950000,
"inventoryCountRef": 7500,
"inventoryCostRef": 960000,
"inventoryTagAmountRef": 1620000,
"digestionRateRef": 50,
"turnoverRateRef": 42
}
]
]
}
```
说明：最外层为 `{ code, msg, data }`；`data` 为长度为 2 的数组，`data[0]` 为列配置，`data[1]` 为 list。
#### 数据用途说明
- **仪表盘「供应商表现 (Top 10)」**：请求本接口，取 `data[0]`（列配置）与 `data[1]`（行数据 list）前 10 条；表头与列按 `data[0]` 渲染（每列 title、key，可选 labelKey、colorKey）。**筛选项**：从当前 list 中收集每条数据的 `label`（按逗号拆分）去重后，与「全部」一起作为筛选条件（如：全部、销量领先、持续突破、低毛利…）；选中某标签时仅显示该行 `label` 包含该标签的条目。点击行可跳转品类诊断。
- **品类诊断页**：请求本接口，用同一 `data[1]`（list）渲染卡片列表；卡片展示上述全部指标及基准参考列，带升降箭头。
### 3.2 供应商表现 (Top 10) 更多
点击「更多」跳转品类诊断页，仍调用 [3.1 品类表现与品类诊断接口](#31-品类表现与品类诊断接口统一)，仅展示形式变为卡片列表。
---
## 4. 中类销售排名 Top 5
### 4.1 中类销售排名 Top 5 接口
#### 接口信息
- **接口路径**: `/api/reportpage/executeProcedureWithData`
- **存储过程名**: `YDY_AI_GET_SPDP3`
- **请求方式**: GET
- **接口说明**: 获取中类销售排名 Top5；仪表盘以**饼图**形式展示，饼图居中偏上，图例在底部横向排列；饼图标签仅显示百分比，图例显示「名称 占比%」；点击饼图扇区可跳转品类诊断页；悬停显示详情卡片（销量信息）。
#### 请求参数
与 [统一查询参数设计](#10-统一查询参数设计) 一致，**zhonglei 固定为空字符串**。
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| reportId | number | 是 | 固定 6 |
| name | string | 是 | 固定 `YDY_AI_GET_SPDP3` |
| rq_s | string | 是 | 开始日期 YYYY-MM-DD |
| rq_e | string | 是 | 结束日期 YYYY-MM-DD |
| ckdm | string | 否 | 门店代码，多选逗号分隔 |
| pp | string | 否 | 品牌代码，多选逗号分隔 |
| dalei | string | 否 | 大类代码，多选逗号分隔 |
| jj | string | 否 | 季节代码，多选逗号分隔 |
| zgj | string | 否 | 正特价，多选逗号分隔（1=正价，0=特价） |
| line | string | 否 | 线路代码，多选逗号分隔 |
| zhonglei | string | 否 | 中类，**固定为空字符串 ''** |
| p | string | 否 | 秘钥，默认 "123" |
| username | string | 否 | 当前登录用户 |
#### 返回值结构
返回格式：`{ code, msg, data }`，其中 **data** 为一维数组（混合格式）：
- **列配置项**（含 `keys` 字段）：前几项为列配置
- `keys="title"`：对应 name（中类名称），数据行中对应 `title` 字段
- `keys="value1"`：对应 value（销量），数据行中对应 `value1` 字段
- **数据行**（不含 `keys` 字段）：后续项为数据行
- `title`：中类名称
- `value1`：销量值（用于饼图展示）
**数据解析逻辑**：
1. 分离列配置（含 `keys` 字段）和数据行（不含 `keys` 字段）
2. 从列配置中找到 `keys="title"` 的列（对应 name）和 `keys="value1"` 的列（对应 value）
3. 从数据行中提取 `title` 作为名称，`value1` 作为销量值
4. 按销量降序排序，计算各中类的销量占比，取前 5 条用于饼图展示
#### 返回值示例
```json
{
"code": 0,
"msg": "",
"data": [
{
"keys": "title",
"title": "name",
"orders": 1
},
{
"keys": "value1",
"title": "value",
"orders": 2
},
{
"title": "K休闲裤类",
"value1": 394
},
{
"title": "外套类",
"value1": 254
},
{
"title": "棉衣类",
"value1": 229
}
]
}
```
#### 数据用途说明
- **仪表盘「中类销售排名 Top 5」**：以饼图展示，前端通过数据映射逻辑获取各中类的销量，计算占比后取前 5 条绘制扇区；悬停显示销量信息；点击扇区跳转品类诊断页。
- **点击「更多」**：跳转品类诊断页，携带当前查询条件。
### 4.2 中类销售排名 Top 5 更多（品类分析卡片页）
点击「中类销售排名 Top 5」的「更多」进入**品类分析**页（路径 `/reports/lijun/category-diagnostic`），以卡片列表展示各品类/中类的诊断结果。该页面与 [7.1 品类分析页面查询接口](#71-品类分析页面查询接口) 使用**同一查询接口**与**同一返回值结构**。
#### 查询接口
- **接口路径**: `GET /api/reportpage/executeProcedureWithData`
- **存储过程名**: `YDY_AI_GET_SPDP3`（与品类分析页 7.1 一致）
- **请求参数**: 与 [统一查询参数设计](#10-统一查询参数设计) 一致，**不传 ghsdm**；传 rq_s、rq_e、ckdm、pp、dalei、jj、zhonglei、p、username 等。
#### 返回值结构
与 [3.1 供应商表现与品类诊断接口](#31-供应商表现与品类诊断接口统一) / [7.1 品类分析页面查询接口](#71-品类分析页面查询接口) 一致：`{ code, msg, data }`，其中 **data** 为长度为 2 的数组：
- **data[0]**：列配置数组。每项为 `{ title, key/keys, order/orders, labelKey?, colorKey? }`。第一列一般为品类名称（如 key 为 `title`），后续列为检测指标（如 key 为 `value1`、`value2`…）。前端用其生成卡片内「检测指标 / 实际结果 / 基准参考」表格。
- **data[1]**：行数据 list。每条对应一张品类诊断卡片，字段需与列配置及页面展示一致。
**行数据每条（与页面展示一致）**：
| 字段 | 类型 | 说明 |
|------|------|------|
| title / name | string | 卡片标题（品类/中类名称） |
| tag | string | 状态标签，逗号分隔（如 `"低毛利,缺货"`），用于卡片左上角标签 |
| tagcolor | string | 标签/边框颜色，逗号分隔（如 `"red,down"`），与 tag 顺序对应；含 down/red 时卡片边框为红 |
| titleName / titleValue | string | 卡片右上角「名称: 值」（如 周转天: 28） |
| key | number/string | 某指标实际值，key 与列配置中 key 一致（如 value1、value2） |
| key+date | string | 该指标基准参考值，展示在「基准参考」列 |
| key+tag | string | 可选，该指标标签（如「上升」），逗号分隔多值 |
| key+color | string | 可选，该指标颜色（up/down/flat 或 green/red），逗号分隔，与 key+tag 对应；用于升降箭头与标签样式 |
说明：列配置中除第一列外的每一列，若行数据中存在对应 `col.key + 'date'` 且非空，则卡片内展示一行「检测指标 = col.title / 实际结果 = row[col.key] / 基准参考 = row[col.key+date]」，并可带升降箭头（由 key+color 推断）及小标签（由 key+tag、key+color 解析）。
#### 示例数据（与页面展示一致）
以下示例对应品类分析卡片页的展示：列配置为「品类 + 销量 + 销售额 + 库存量」，行数据含 title、tag、tagcolor、titleName、titleValue 及 value1/value1date、value2/value2date 等。
```json
{
"code": 200,
"msg": "查询成功",
"data": [
[
{ "title": "品类", "keys": "title", "orders": 0 },
{ "title": "销量", "keys": "value1", "orders": 1 },
{ "title": "销售额", "keys": "value2", "orders": 2 },
{ "title": "库存量", "keys": "value3", "orders": 3 }
],
[
{
"title": "女装 - 连衣裙",
"tag": "低毛利",
"tagcolor": "red",
"titleName": "周转天",
"titleValue": "28",
"value1": 12500,
"value1date": "11,200",
"value1tag": "上升",
"value1color": "up",
"value2": 2948750,
"value2date": "2,650,000",
"value2tag": "上升",
"value2color": "up",
"value3": 12500,
"value3date": "11,800",
"value3tag": "下降",
"value3color": "down"
},
{
"title": "女装 - 休闲裤",
"tag": "稳步运行",
"tagcolor": "flat",
"titleName": "周转天",
"titleValue": "35",
"value1": 8900,
"value1date": "8,200",
"value2": 1853500,
"value2date": "1,690,000",
"value3": 9800,
"value3date": "9,500"
},
{
"title": "女装 - 风衣/外套",
"tag": "积压",
"tagcolor": "down",
"titleName": "周转天",
"titleValue": "52",
"value1": 3200,
"value1date": "2,850",
"value2": 1516500,
"value2date": "1,350,000",
"value3": 8500,
"value3date": "9,200",
"value3tag": "下降",
"value3color": "down"
}
]
]
}
```
说明：最外层为 `{ code, msg, data }`；`data[0]` 为列配置（支持 title、keys、orders；前端会取 keys 作为 key、orders 作为 order），`data[1]` 为行数据 list。卡片标题取 `row.title ?? row.name`，标签取 `row.tag` 按逗号拆分，右上角取 `row.titleName`、`row.titleValue`；表格每行由列配置（除首列）中该行存在 `key+date` 的列动态生成，实际结果取 `row[key]`，基准参考取 `row[key+date]`，箭头与标签由 `row[key+tag]`、`row[key+color]` 解析。
---
## 5. 商品明细列表
### 5.1 商品明细列表接口
#### 接口信息
- **接口路径**: `/api/report/product-dashboard/product-list` 或 **executeProcedureWithData**（reportId=6, name 由后端约定）
- **请求方式**: `GET` / `POST`
- **接口说明**: 获取商品明细列表数据，包含销售、库存、售罄率、折扣率、尺码状态、生命周期等；用于仪表盘表格与产品卡片页（可选 productCode 定位当前商品）。
#### 请求参数
与 [统一查询参数设计](#10-统一查询参数设计) 一致，并增加以下列表专用参数：
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| keyword | string | 否 | 关键词搜索（款号/名称） | "" 或 "GZ6596Z" |
| pageNum | number | 否 | 页码，默认 1 | 1 |
| pageSize | number | 否 | 每页条数，默认 20 | 20 |
| productCode | string | 否 | 商品款号（用于定位当前商品） | "" 或 "54000008" |
#### 数据用途说明
- **仪表盘「商品明细列表」**：表格列包括商品信息（图+名称+货号+颜色+季节）、类目/波段、销量、销售额、库存、周转、售罄率（进度条）、折扣率、断码监控（尺码芯片）、生命周期、供货商、操作；支持关键词搜索（款号/名称）、分页展示。
### 5.2 商品明细列表鼠标悬浮框
鼠标悬停在商品明细列表的表格行上时，展示商品详情悬浮卡片。
**数据来源**：建议使用「按产品 code 查询商品悬浮详情接口」单独查询，避免商品列表接口字段不足或分页导致的数据不全；同时确保**必须携带产品 code** 精确查询。
#### 5.2.1 商品悬浮详情接口（按产品 code 查询）
##### 接口信息
- **接口路径**: `GET /api/reportpage/executeProcedureWithData`
- **请求方式**: GET
- **存储过程名**: `YDY_AI_GET_SPMX_DETAIL`（建议；后端可按实际命名）
- **接口说明**: 根据**产品款号 code** + 当前查询条件，返回商品悬浮卡片所需的完整字段（图片、条码、颜色、尺码库存、价格、销售/库存、售罄率、折扣、生命周期等）。
##### 请求参数
在 [统一查询参数设计](#10-统一查询参数设计) 基础上，增加并要求以下参数：
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| reportId | number | 是 | 固定 6 | 6 |
| name | string | 是 | 固定 `YDY_AI_GET_SPMX_DETAIL` | "YDY_AI_GET_SPMX_DETAIL" |
| code | string | **是** | 产品款号/货号（悬浮卡片必须携带） | "54000008" |
| rq_s | string | 是 | 开始日期 YYYY-MM-DD | "2025-01-20" |
| rq_e | string | 是 | 结束日期 YYYY-MM-DD | "2025-01-27" |
| ckdm | string | 否 | 门店代码，多选逗号分隔 | "S1,S2" |
| pp | string | 否 | 品牌代码，多选逗号分隔 | "P1,P2" |
| dalei | string | 否 | 大类代码，多选逗号分隔 | "D1,D2" |
| jj | string | 否 | 季节代码，多选逗号分隔 | "J1,J2" |
| zgj | string | 否 | 正/特价，多选逗号分隔 | "1,0" |
| line | string | 否 | 线路代码，多选逗号分隔 | "L1,L2" |
| p | string | 否 | 秘钥，默认 "123" | "123" |
| username | string | 否 | 当前登录用户 | "admin" |
##### 返回值结构
`{ code, msg, data }`，其中 `data` 为一个对象（单商品详情），字段与页面展示一致。
**悬浮卡片展示字段**：
- **商品图片**：`imageUrl`
- **款号**：`code`
- **条码**：`barcode`
- **颜色**：`color`
- **进价/卖价**：`purchasePrice` / `sellingPrice`
- **毛利率**：`grossMargin`（可选，0-1 小数；若不传，前端可用 `purchasePrice/sellingPrice` 计算展示）
- **类目**：`category`
- **上市天数**：`daysOnMarket`
- **销量/销售额/库存/周转**：`salesCount` / `salesAmount` / `inventoryCount` / `turnoverText`
- **售罄率**：`selloutRate`（进度条颜色由 `selloutRateStatus` 在前端映射）
- **折扣**：`discount`
- **尺码剩余数量**：`sizes`（数组，显示每个尺码的库存状态）
- **断码**：`sizeStatusText`
- **生命周期**：`lifecycle`（标签，类型由 `lifecycleType` 控制）
**说明**：
- **必须带 code 查询**：悬浮卡片不依赖列表行数据是否完整。
- **兼容兜底**：若后端暂未提供本接口，前端可先用 [5.1 商品明细列表接口](#51-商品明细列表接口) 的行数据做展示兜底，但字段可能缺失（如 barcode、sizes、purchasePrice 等）。
##### 示例数据（与页面展示一致）
```json
{
"code": 200,
"msg": "查询成功",
"data": {
"name": "GZ6596Z 法式收腰连衣裙",
"code": "54000008",
"barcode": "6901234567890",
"color": "黑色",
"season": "25春 一波段",
"category": "女装 / 连衣裙",
"supplierName": "杭州女装供应链有限公司",
"imageUrl": "https://img.alicdn.com/imgextra/i1/2215397650053/O1CN01kQKs0S1COq3OWK7Wb_!!2215397650053.jpg",
"purchasePrice": 168,
"sellingPrice": 399,
"grossMargin": 0.579,
"daysOnMarket": 35,
"salesCount": 320,
"salesAmount": 85200,
"inventoryCount": 120,
"turnoverDays": 15,
"turnoverText": "周转: 15天 (极快)",
"turnoverStatus": "success",
"selloutRate": 78,
"selloutRateStatus": "danger",
"discount": "9.5折",
"discountStatus": "info",
"sizes": [
{ "label": "S", "status": "out", "title": "S码 缺货", "stock": 0 },
{ "label": "M", "status": "out", "title": "M码 缺货", "stock": 0 },
{ "label": "L", "status": "low", "title": "L码 紧张", "stock": 8 },
{ "label": "XL", "status": "ok", "title": "XL码 充足", "stock": 45 }
],
"sizeStatusText": "缺核心码",
"sizeStatusStatus": "danger",
"lifecycle": "爆发成长期",
"lifecycleType": "success",
"lifecycleIcon": "fa-solid:fire-alt"
}
}
```
### 5.3 商品明细列表更多
点击商品明细列表的表格行，跳转到「查看更多产品卡片」页面。
**数据来源**：使用 [5.1 商品明细列表接口](#51-商品明细列表接口)，可选传 `productCode` 参数定位当前商品。
**请求参数**：在统一查询参数基础上增加：
- `keyword`：款号/名称搜索（可选）
- `pageNum`：页码（默认 1）
- `pageSize`：每页条数（默认 20）
- `productCode`：当前商品款号（可选，用于定位当前商品）
**展示方式**：产品卡片页以卡片形式展示商品列表，每个卡片包含商品图片、名称、款号、颜色、季节、类目、上市天数、销量、销售额、库存、周转、售罄率、折扣、尺码状态、生命周期、供货商等信息。
**说明**：与仪表盘商品明细列表使用相同的数据接口和数据结构，只是展示方式不同（表格 vs 卡片）。
#### 示例数据（与页面展示一致）
```json
{
"code": 200,
"msg": "查询成功",
"data": {
"list": [
{
"name": "GZ6596Z 法式收腰连衣裙",
"code": "54000008",
"color": "黑色",
"season": "25春 一波段",
"category": "女装 / 连衣裙",
"daysOnMarket": 35,
"salesAmount": 85200,
"salesCount": 320,
"inventoryCount": 120,
"turnoverText": "周转: 15天 (极快)",
"turnoverStatus": "success",
"selloutRate": 78,
"selloutRateStatus": "danger",
"discount": "9.5折",
"discountStatus": "info",
"sizes": [
{ "label": "S", "status": "out", "title": "S码 缺货", "stock": 0 },
{ "label": "M", "status": "out", "title": "M码 缺货", "stock": 0 },
{ "label": "L", "status": "low", "title": "L码 紧张", "stock": 8 },
{ "label": "XL", "status": "ok", "title": "XL码 充足", "stock": 45 }
],
"sizeStatusText": "缺核心码",
"sizeStatusStatus": "danger",
"lifecycle": "爆发成长期",
"lifecycleType": "success",
"lifecycleIcon": "fa-solid:fire-alt",
"actionText": "补货",
"actionType": "primary",
"barcode": "6901234567890",
"purchasePrice": 168,
"sellingPrice": 399,
"imageUrl": "https://img.alicdn.com/imgextra/i1/2215397650053/O1CN01kQKs0S1COq3OWK7Wb_!!2215397650053.jpg",
"supplierName": "杭州女装供应链有限公司"
},
{
"name": "7537X 双面呢大衣",
"code": "54000321",
"color": "驼色",
"season": "24冬 三波段",
"category": "女装 / 外套",
"daysOnMarket": 120,
"salesAmount": 22000,
"salesCount": 18,
"inventoryCount": 850,
"turnoverText": "周转: 280天 (滞销)",
"turnoverStatus": "info",
"selloutRate": 15,
"selloutRateStatus": "warning",
"discount": "6.0折",
"discountStatus": "danger",
"sizes": [
{ "label": "S", "status": "ok", "title": "S码 充足", "stock": 210 },
{ "label": "M", "status": "ok", "title": "M码 充足", "stock": 220 },
{ "label": "L", "status": "ok", "title": "L码 充足", "stock": 215 },
{ "label": "XL", "status": "ok", "title": "XL码 充足", "stock": 205 }
],
"sizeStatusText": "库存齐色齐码",
"sizeStatusStatus": "info",
"lifecycle": "严重滞销",
"lifecycleType": "danger",
"lifecycleIcon": "ep:circle-close",
"actionText": "调价",
"actionType": "warning",
"barcode": "6901234567891",
"supplierName": "上海大衣制造厂",
"purchasePrice": 580,
"sellingPrice": 1299,
"imageUrl": "https://img.alicdn.com/imgextra/i2/2215397650053/O1CN01kQKs0S1COq3OWK7Wb_!!2215397650053.jpg"
}
],
"total": 156,
"pageNum": 1,
"pageSize": 20
}
}
```
#### 字段含义
| 字段 | 格式 | 必填 | 含义 |
|------|------|------|------|
| code | number | 是 | 响应码：200 表示成功 |
| msg | string | 是 | 响应消息 |
| data.list | array | 是 | 商品明细列表 |
| data.total | number | 是 | 总记录数（分页用） |
| data.pageNum | number | 是 | 当前页码 |
| data.pageSize | number | 是 | 每页条数 |
| list[].name | string | 是 | 商品名称 |
| list[].code | string | 是 | 款号/货号 |
| list[].color | string | 是 | 颜色 |
| list[].season | string | 是 | 季节/波段 |
| list[].category | string | 是 | 类目 |
| list[].daysOnMarket | number | 是 | 上市天数 |
| list[].salesAmount | number | 是 | 销售额（单位：分） |
| list[].salesCount | number | 是 | 销量（件） |
| list[].inventoryCount | number | 是 | 库存量（件） |
| list[].turnoverText | string | 是 | 周转展示文案（如“周转: 15天 (极快)”） |
| list[].turnoverStatus | string | 是 | 周转展示状态（success/warning/danger/info），由前端映射为样式 |
| list[].selloutRate | number | 是 | 售罄率（0–100） |
| list[].selloutRateStatus | string | 是 | 售罄率展示状态（success/warning/danger/info），由前端映射为样式与进度条颜色 |
| list[].discount | string | 是 | 折扣文案（如“9.5折”） |
| list[].discountStatus | string | 否 | 折扣展示状态（success/warning/danger/info），由前端映射为样式 |
| list[].sizes | array | 是 | 尺码状态数组 |
| sizes[].label | string | 是 | 尺码（S/M/L/XL…） |
| sizes[].status | string | 是 | 尺码状态（out/low/warn/ok），由前端映射为样式类（红/橙/黄/灰） |
| sizes[].title | string | 是 | 悬浮提示（如“S码 缺货”） |
| sizes[].stock | number | 否 | 该尺码剩余数量 |
| sizes[].outOfStock | boolean | 否 | 是否缺货 |
| list[].sizeStatusText | string | 是 | 断码说明文案 |
| list[].sizeStatusStatus | string | 是 | 断码展示状态（success/warning/danger/info），由前端映射为样式 |
| list[].lifecycle | string | 是 | 生命周期文案 |
| list[].lifecycleType | string | 是 | 生命周期标签类型（success/danger/info/warning） |
| list[].lifecycleIcon | string | 是 | 生命周期图标名 |
| list[].actionText | string | 是 | 操作按钮文案 |
| list[].actionType | string | 是 | 操作按钮类型（primary/warning/default/danger） |
| list[].productId | string | 否 | 商品 ID |
| list[].imageUrl | string | 否 | 商品图片 URL |
| list[].turnoverDays | number | 否 | 周转天数（数值） |
| list[].grossMargin | number | 否 | 毛利率（0–1，小数） |
| list[].barcode | string | 否 | 条码 |
| list[].purchasePrice | number | 否 | 进价（元） |
| list[].sellingPrice | number | 否 | 卖价（元） |
| list[].supplierName | string | 否 | 供货商名称 |
---
## 6. 品类诊断列表（与品类表现共用接口）
品类诊断页与「供应商表现 (Top 10)」使用**同一接口**、**同一返回值结构**。
- **接口**：见 [3.1 品类表现与品类诊断接口（统一）](#31-品类表现与品类诊断接口统一)。
- **请求参数**：与统一查询参数一致。
- **返回**：`data` 为二维数组 `[[列配置], [list]]`；`data[0]` 为列配置，`data[1]` 为行数据 list；品类表现表格按列配置动态渲染；品类诊断共用 list 结构（品类名称、毛利、毛利率、周转天、状态、销量、销售额、库存量、库存成本、库存吊销额、消化率、动销率及对应基准参考字段）。
**品类诊断页展示**：品类分析页（路径 `/reports/lijun/category-diagnostic`）用上述 list（`data[1]`）渲染卡片列表；卡片头部为品类名称、状态标签（由 `status` 解析）、周转天等；指标表格三列「检测指标 / 实际结果 / 基准参考」，对应销量、销售额、库存量、库存成本、库存吊销额、消化率、动销率及带 `Ref` 的基准参考，升降箭头由实际值与参考值比较得出。
**品类代码说明**（`dalei` 参数值）:
- `"1"` - 女装 `"2"` - 男装 `"3"` - 童装 `"4"` - 鞋区 `"5"` - 内衣睡衣 `"6"` - 床上用品 `"7"` - 皮具箱包 `"8"` - 百货 `"9"` - 礼品区 `"A"` - 游戏厅 `"B"` - 联营 `"0"` - 玩具 `"C"` - 辅料
---
---
## 附录
### A. 通用响应格式
所有接口统一使用以下响应格式:
```json
{
"code": 200, // 响应码: 200-成功, 400-参数错误, 500-服务器错误
"msg": "查询成功", // 响应消息
"data": {} // 响应数据
}
```
### B. 错误码说明
| 错误码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 401 | 未授权, 需要登录 |
| 403 | 无权限访问 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
### C. 日期格式说明
- 所有日期参数统一使用格式: `YYYY-MM-DD`
- 示例: `2025-01-27`
- 时区: 服务器时区
### D. 金额单位说明
- 所有金额字段统一使用 **分** 作为单位
- 前端显示时需要转换为元: `金额(元) = 金额(分) / 100`
- 示例: 后端返回 `8425000` 分, 前端显示为 `84250.00` 元
### E. 分页说明
- `pageNum`: 页码, 从1开始
- `pageSize`: 每页数量, 默认20
- 返回数据包含 `total` 总记录数, 用于前端分页组件
### F. 筛选条件说明
- `"all"` 表示不筛选, 查询全部
- 多个值使用数组传递, 如: `["1", "2"]`
- 空数组 `[]` 等同于 `"all"`
---
**文档版本**: v1.7
**最后更新**: 2025-01-25
**维护人员**: 开发团队
**v1.7 更新说明**：
- **供应商表现与品类诊断统一接口**：供应商表现 (Top 10) 与品类诊断列表共用同一接口；接口返回 `data` 为二维数组 `[[列配置], [list]]`，第一组为列、第二组为行数据；供应商表现表格按列配置 + list 动态渲染（每列：名称、标签、颜色）。
**v1.6 更新说明**：
- **简化请求参数说明**：所有接口的请求参数统一引用「统一查询参数设计」部分，不再在每个接口中重复叙述。仅保留特殊参数说明（如 KPI 接口的 reportId/name、商品明细列表的分页参数等）。
**v1.5 更新说明**：
- **删除不使用的接口文档**：删除 BCG 矩阵接口文档，因为页面中已不再显示 BCG 矩阵图表。
**v1.4 更新说明**：
- **按页面功能模块重新组织文档结构**：按照实际页面功能模块划分，分为查询条件、顶部数据选项卡、供应商表现 (Top 10)、中类销售排名 Top 5、商品明细列表、品类诊断列表等模块；每个模块包含主接口和相关的"更多"页面接口说明。
- **新增页面功能说明**：
- **供应商表现 (Top 10) 更多**：说明点击"更多"按钮跳转到品类诊断页
- **中类销售排名 Top 5 更多**：说明点击"更多"按钮跳转到品类诊断页
- **商品明细列表鼠标悬浮框**：说明悬浮卡片展示的字段和数据来源
- **商品明细列表更多**：说明点击表格行跳转到产品卡片页
- **目录结构优化**：按照页面功能模块组织，便于前端开发人员快速找到对应页面的接口文档。
**v1.3 更新说明**：
- **重新组织文档结构**：按照功能模块划分，分为基础模块、仪表盘模块、商品管理模块、品类分析模块；更新目录结构，按模块组织接口，便于查找和维护。
- **接口模块化重组**：
- **基础模块**：统一查询参数设计、下拉选项接口
- **仪表盘模块**：KPI 指标、中类销售排名 Top5、供应商表现 (Top 10)
- **商品管理模块**：商品明细列表接口
- **品类分析模块**：品类诊断列表接口
**v1.2 更新说明**：
- **新增 1.3 供应商表现 (Top 10) 接口**：表格按后端返回的列配置与行数据动态渲染；每列支持名称、标签、颜色；支持筛选和展开/收起。
- **更新 1.2 中类销售排名 Top5 接口**：更新接口说明，明确以饼图形式展示，饼图标签仅显示百分比，图例在底部横向排列；更新数据用途说明，明确饼图展示方式和交互。
**v1.1 更新说明**：
- 新增「0. 统一查询参数设计」，仪表盘及各子页共用 rq_s/rq_e、ckdm、pp、jj、dalei、line、zgj、username，多选以逗号分隔。
- 1.1 KPI 接口：补充 kpiCardData 表结构及与顶部数据卡片一致的响应示例（trend 仅 up/down，miniBars/progress/bottomText 按指标区分）。
- 新增 1.3 中类销售排名 Top5、1.4 商品明细列表（含 productCode、keyword、分页）的查询接口与参数。
- 2.1 品类诊断列表请求参数改为统一查询参数。
- 新增「3. 下拉选项接口」executeTable（reportId=6，tableName: pinpai/jijie/dalei/xianlu/line/ljsm_kehu）。
Reference in New Issue Copy Permalink