# 报表系统 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)。