Files

ouhaolan f935832c9e info

2026-02-27 09:47:06 +08:00

46 KiB

Raw Blame History

报表系统 API 接口文档

参数名	类型	必填	说明
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 支持两种形态：

二维数组：data = [[列配置数组], [行数据数组]]
- data[0]：列配置（每项含 title、keys/key、orders/order、labelKey、colorKey）
- data[1]：行数据 list，每项为一条品类/中类数据（含 title/name、value1、value2、…、value1date、value2date、…、tag、tagcolor、titleName、titleValue 等）
一维数组（混合）：含 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 更多。

路由与查询条件

入口: 仪表盘「中类销售排名 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 表为准，无需改动。

请求参数

与统一查询参数设计一致。

特殊说明：若使用 executeProcedureWithData 方式调用，需额外传递：

reportId: 固定为 6
name: 存储过程/接口名，KPI 为 YDY_AI_GET_SPDP1

返回值类型

{
  "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 渲染卡片。

请求参数

与统一查询参数设计一致。

供应商表现 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。

{
  "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 品类表现与品类诊断接口，仅展示形式变为卡片列表。

4. 中类销售排名 Top 5

4.1 中类销售排名 Top 5 接口

接口信息

接口路径: /api/reportpage/executeProcedureWithData
存储过程名: YDY_AI_GET_SPDP3
请求方式: GET
接口说明: 获取中类销售排名 Top5；仪表盘以饼图形式展示，饼图居中偏上，图例在底部横向排列；饼图标签仅显示百分比，图例显示「名称占比%」；点击饼图扇区可跳转品类诊断页；悬停显示详情卡片（销量信息）。

请求参数

与统一查询参数设计一致，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：销量值（用于饼图展示）

数据解析逻辑：

分离列配置（含 keys 字段）和数据行（不含 keys 字段）
从列配置中找到 keys="title" 的列（对应 name）和 keys="value1" 的列（对应 value）
从数据行中提取 title 作为名称，value1 作为销量值
按销量降序排序，计算各中类的销量占比，取前 5 条用于饼图展示

返回值示例

{
  "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 品类分析页面查询接口使用同一查询接口与同一返回值结构。

查询接口

接口路径: GET /api/reportpage/executeProcedureWithData
存储过程名: YDY_AI_GET_SPDP3（与品类分析页 7.1 一致）
请求参数: 与统一查询参数设计一致，不传 ghsdm；传 rq_s、rq_e、ckdm、pp、dalei、jj、zhonglei、p、username 等。

返回值结构

与 3.1 供应商表现与品类诊断接口 / 7.1 品类分析页面查询接口一致：{ 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 等。

{
  "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 定位当前商品）。

请求参数

与统一查询参数设计一致，并增加以下列表专用参数：

参数名	类型	必填	说明	示例
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 + 当前查询条件，返回商品悬浮卡片所需的完整字段（图片、条码、颜色、尺码库存、价格、销售/库存、售罄率、折扣、生命周期等）。

请求参数

在统一查询参数设计基础上，增加并要求以下参数：

参数名	类型	必填	说明	示例
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 商品明细列表接口的行数据做展示兜底，但字段可能缺失（如 barcode、sizes、purchasePrice 等）。

示例数据（与页面展示一致）

{
  "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 商品明细列表接口，可选传 productCode 参数定位当前商品。

请求参数：在统一查询参数基础上增加：

keyword：款号/名称搜索（可选）
pageNum：页码（默认 1）
pageSize：每页条数（默认 20）
productCode：当前商品款号（可选，用于定位当前商品）

展示方式：产品卡片页以卡片形式展示商品列表，每个卡片包含商品图片、名称、款号、颜色、季节、类目、上市天数、销量、销售额、库存、周转、售罄率、折扣、尺码状态、生命周期、供货商等信息。

说明：与仪表盘商品明细列表使用相同的数据接口和数据结构，只是展示方式不同（表格 vs 卡片）。

示例数据（与页面展示一致）

{
  "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 品类表现与品类诊断接口（统一）。
请求参数：与统一查询参数一致。
返回：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. 通用响应格式

所有接口统一使用以下响应格式:

{
  "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）。

46 KiB Raw Blame History Unescape Escape

报表系统 API 接口文档

目录

1. 查询条件

2. 顶部数据选项卡

3. 供应商表现 (Top 10) / 品类诊断（共用同一接口）

4. 中类销售排名 Top 5

5. 商品明细列表

6. 品类诊断列表（与品类表现共用接口）

7. 品类分析页面（category-diagnostic）

7.1 品类分析页面查询接口

接口信息

请求参数

返回值结构

路由与查询条件

1. 查询条件

1.0 统一查询参数设计

1.1 下拉选项接口

2. 顶部数据选项卡

2.1 KPI 指标数据接口

接口信息

请求参数

返回值类型

字段含义

3. 供应商表现 (Top 10) / 品类诊断（共用同一接口）

3.1 供应商表现与品类诊断接口（统一）

接口信息

返回值结构（data 为二维数组）

请求参数

供应商表现 Top 10 表格：列配置与动态列

返回值结构（统一字段，品类诊断共用）

示例数据（与页面展示一致）

数据用途说明

3.2 供应商表现 (Top 10) 更多

4. 中类销售排名 Top 5

4.1 中类销售排名 Top 5 接口

接口信息

请求参数

返回值结构

返回值示例

数据用途说明

4.2 中类销售排名 Top 5 更多（品类分析卡片页）

查询接口

返回值结构

示例数据（与页面展示一致）

5. 商品明细列表

5.1 商品明细列表接口

接口信息

请求参数

数据用途说明

5.2 商品明细列表鼠标悬浮框

5.2.1 商品悬浮详情接口（按产品 code 查询）

接口信息

请求参数

返回值结构

示例数据（与页面展示一致）

5.3 商品明细列表更多

示例数据（与页面展示一致）

字段含义

6. 品类诊断列表（与品类表现共用接口）

附录

A. 通用响应格式

B. 错误码说明

C. 日期格式说明

D. 金额单位说明

E. 分页说明

F. 筛选条件说明

46 KiB

Raw Blame History