项目名称

升鲜宝集成 AI 大模型

文档版本

V1.0

文档日期

2026 年 1 月 28 日

适用对象

管理层、采购、仓储、配送、门店运营、信息化团队

交付范围

供应链业务 AI 分析、自动报表、智能预警、问数助手与接口设计

文档定位

本交付稿用于明确升鲜宝 AI 供应链分析与预警平台的业务范围、指标口径、报表形态、接口边界与实施路径，支持首版 MVP 立项、开发排期与验收。

用户角色

核心诉求

典型使用场景

管理层

快速掌握销售、毛利、库存、损耗和异常风险

查看经营日报、月度复盘、重大预警和趋势分析

采购负责人

控制采购价格、供应商履约和采购计划准确性

查看采购价格异常、供应商评分、采购建议

仓储负责人

保障库存准确、周转合理、临期和损耗可控

查看缺货、积压、临期、库龄和盘点异常

配送负责人

提升配送准时率和差异闭环效率

查看线路延误、缺配错配、签收差异和门店异常反馈

门店运营

关注门店销售、缺货、损耗、收货和毛利问题

查看门店日报、缺货清单、低毛利商品、损耗排行

IT/数据团队

保障数据准确、接口稳定、权限和审计可控

监控任务、接口、日志、数据质量和权限配置

设计目标

报表原型以“管理者看总体、业务负责人看异常、一线人员看待办”为原则，所有报表都支持指标解释、异常追问、明细下钻、导出和预警闭环。

升鲜宝 AI 供应链分析与预警平台
├── 首页经营看板
│   ├── 今日经营 KPI
│   ├── 趋势图与品类贡献
│   ├── 重点异常摘要
│   └── AI 经营建议
├── AI 自动报表
│   ├── 供应链经营日报
│   ├── 采购分析报表
│   ├── 库存分析报表
│   ├── 销售分析报表
│   ├── 毛利损耗报表
│   └── 配送履约报表
├── 预警中心
│   ├── 缺货预警
│   ├── 滞销/临期预警
│   ├── 采购价异常
│   ├── 毛利/损耗异常
│   └── 配送/供应商异常
├── AI 问数助手
│   ├── 自然语言查询
│   ├── 指标解释
│   ├── 异常归因
│   └── 明细下钻
└── 系统配置
    ├── 指标口径
    ├── 预警规则
    ├── 报表模板
    ├── 权限角色
    └── 接口日志

区域

组件

显示内容

交互

顶部筛选区

日期、区域、门店、仓库、品类、供应商

支持默认今日、昨日、本周、本月和自定义日期

筛选后全局刷新，可保存常用筛选

核心 KPI 区

销售额、毛利率、库存金额、缺货 SKU、损耗金额、配送准时率

展示当前值、环比、同比、目标达成率

点击进入指标明细和趋势分析

趋势图区

销售、毛利、库存、损耗趋势

按日/周/月展示，支持品类拆分

点击某点查看当日异常摘要

异常摘要区

重点预警 Top 10

按等级、影响金额、影响门店排序

点击打开预警卡片并处理

AI 建议区

今日经营建议

自动生成 3-5 条可执行建议

支持采纳、忽略、转任务

首页布局草图
┌──────────────────────────────────────────────┐
│ 筛选：日期  区域  门店  仓库  品类  供应商     │
├──────────┬──────────┬──────────┬──────────┤
│ 销售额    │ 毛利率    │ 库存金额  │ 缺货SKU   │
├──────────┴──────────┴──────────┴──────────┤
│ 销售/毛利趋势图       │ 品类贡献/库存结构图      │
├──────────────────────┬──────────────────────┤
│ 重点预警 Top10        │ AI 今日经营建议          │
└──────────────────────┴──────────────────────┘

报表名称

周期

使用对象

核心内容

供应链经营日报

每日

管理层、供应链负责人

经营摘要、销售、毛利、库存、采购、损耗、配送、重点异常、AI 建议

采购分析报表

每日/每周

采购负责人

采购金额、采购均价、价格波动、供应商报价、到货率、采购偏差

库存分析报表

每日

仓储/门店运营

库存金额、周转天数、缺货、高库存、临期、库龄结构、调拨建议

销售分析报表

每日/每周/月

运营、采购、管理层

销售额、销量、品类贡献、商品排行、门店排行、趋势预测

毛利损耗报表

每日/每周

财务、运营、采购

毛利率、低毛利、负毛利、损耗金额、损耗率、原因归因

配送履约报表

每日

配送负责人

准时率、签收差异、缺配错配、线路异常、门店收货异常

供应商履约报表

每周/月

采购、管理层

到货率、准时率、退货率、价格稳定性、综合评分

升鲜宝供应链经营日报
日期：YYYY-MM-DD

一、今日经营摘要
今日销售额 XX 万元，较昨日变化 X%；整体毛利率 X%，较昨日变化 X 个百分点。当前库存金额 XX 万元，缺货风险 SKU X 个，高库存 SKU X 个。

二、重点异常
1. 采购价异常：XX 商品采购价较近 7 日均价上涨 X%。
2. 库存风险：XX 商品预计 24 小时内低于安全库存。
3. 毛利风险：XX 商品毛利率低于标准线 X 个百分点。

三、AI 建议
建议优先处理 P0/P1 预警，复核采购价异常商品，调整缺货商品补货计划，并对高库存商品启动促销或调拨。

字段

说明

示例

预警编号

系统自动生成，唯一标识

ALERT-20260529-0001

预警等级

P0/P1/P2/P3

P1 高

预警类型

缺货、滞销、临期、毛利异常等

采购价异常

影响对象

商品、门店、仓库、供应商、线路

上海青 / 华东仓 / 供应商 A

异常事实

系统计算得到的异常描述

今日采购价较近 7 日均价上涨 12.5%

可能原因

AI 结合数据链路给出的原因排序

供应商报价上涨，替代供应商缺货

建议动作

补货、调价、促销、调拨、谈判等

复核报价并对比供应商 B 报价

处理状态

待认领、处理中、已处理、已关闭、已忽略

待认领

责任人

规则配置或系统派单生成

采购主管

预警卡片示例
标题：P1 采购价异常 - 上海青
异常：今日采购价 4.85 元/kg，高于近 7 日均价 4.28 元/kg，涨幅 13.3%。
影响：涉及 6 家门店，预计影响毛利 1,260 元。
原因：供应商 A 报价上调；昨日到货不足导致替代采购。
建议：复核供应商 A 报价；询价供应商 B/C；必要时调整售价或采购量。
操作：认领 | 转任务 | 查看明细 | 关闭

问题类型

用户问题示例

系统处理方式

指标查询

今天销售额是多少？各品类贡献如何？

识别指标、时间和维度，调用指标查询接口并生成解释

异常追问

为什么今天毛利率下降？

调用毛利拆解模型，按成本、售价、损耗、结构变化归因

明细下钻

哪些门店的香蕉缺货风险最高？

过滤商品和预警类型，返回门店列表和风险等级

建议生成

明天叶菜怎么采购？

结合销量预测、库存、供应商履约和采购规则生成建议

报表生成

帮我生成本周供应商履约分析

调用报表生成接口，输出结构化报告和导出链接

问数边界

问数助手不直接访问数据库裸表，而是通过指标服务、权限服务和报表服务获取结构化结果；AI 只负责理解问题、组织查询、解释结果和生成建议。

前端/消息端
  ↓
API 网关
  ↓
认证鉴权服务 ── 权限范围：区域/门店/仓库/供应商/指标
  ↓
业务服务层
  ├── 指标查询服务 metric-service
  ├── 报表生成服务 report-service
  ├── 预警中心服务 alert-service
  ├── 问数助手服务 ai-query-service
  ├── 文件导出服务 export-service
  └── 消息推送服务 message-service
  ↓
数据服务层：指标宽表 / 预警表 / 报表模板 / 业务明细 / 知识库

设计原则

说明

统一认证

所有接口通过 Token 或企业内部 SSO 鉴权，接口层记录用户身份和权限范围

结构化返回

指标、图表、明细、解释和建议分开返回，便于前端展示和二次处理

幂等重试

报表生成、预警处理和消息推送需要支持幂等，避免重复生成或重复通知

异步任务

复杂报表和大范围查询采用任务 ID 方式异步生成，前端轮询或回调获取结果

审计日志

关键查询、导出、预警关闭、规则变更、权限变更均需记录日志

方法

接口路径

接口名称

用途

POST

/api/v1/metrics/query

指标查询

按指标、维度、时间、过滤条件查询经营数据

POST

/api/v1/reports/generate

报表生成

生成日报、周报、专题分析报告

GET

/api/v1/reports/{reportId}

报表详情

查询报表生成状态、摘要和下载地址

GET

/api/v1/alerts

预警列表

按等级、类型、状态、责任人筛选预警

POST

/api/v1/alerts/{alertId}/ack

预警认领

责任人认领或转派预警

POST

/api/v1/alerts/{alertId}/close

预警关闭

提交处理说明并关闭预警

POST

/api/v1/ai/query

AI 问数

自然语言问数、异常追问和建议生成

POST

/api/v1/exports

文件导出

导出 Excel、PDF、Word

POST

/api/v1/webhooks/message

消息回调

接收企业微信/钉钉处理回调或按钮事件

POST /api/v1/metrics/query
Request:
{
  "metrics": ["sales_amount", "gross_margin_rate", "inventory_amount"],
  "dimensions": ["date", "category"],
  "dateRange": {"start": "2026-05-01", "end": "2026-05-29"},
  "filters": {"regionCode": "EAST", "storeCodes": ["S001", "S002"]},
  "compare": ["previous_period", "same_period_last_year"]
}

Response:
{
  "traceId": "req-20260529-001",
  "data": [
    {"date": "2026-05-29", "category": "水果", "sales_amount": 386000, "gross_margin_rate": 0.218, "inventory_amount": 156000}
  ],
  "summary": "水果品类销售额较昨日增长 6.8%，毛利率下降 0.7 个百分点。"
}

POST /api/v1/reports/generate
Request:
{
  "reportType": "supply_chain_daily",
  "reportDate": "2026-05-29",
  "scope": {"regionCode": "ALL"},
  "outputFormats": ["docx", "pdf", "xlsx"],
  "includeDetails": true
}

Response:
{
  "reportId": "RPT-20260529-0001",
  "status": "processing",
  "estimatedSeconds": 30
}

GET /api/v1/alerts?level=P0,P1&status=open&date=2026-05-29
Response:
{
  "total": 18,
  "items": [
    {
      "alertId": "ALERT-20260529-0001",
      "level": "P1",
      "type": "purchase_price_abnormal",
      "title": "上海青采购价异常",
      "fact": "今日采购价较近 7 日均价上涨 13.3%",
      "impactAmount": 1260,
      "owner": "采购主管",
      "status": "open",
      "suggestion": "复核供应商报价，并对比替代供应商。"
    }
  ]
}

POST /api/v1/ai/query
Request:
{
  "question": "今天哪些商品毛利异常？原因是什么？",
  "context": {"date": "2026-05-29", "regionCode": "ALL"},
  "returnMode": "answer_with_table"
}

Response:
{
  "answer": "今日共有 12 个商品毛利率低于预警线，主要集中在水果和叶菜品类。",
  "tables": [{"name": "低毛利商品清单", "columns": ["商品", "毛利率", "标准毛利率", "原因"], "rows": []}],
  "followUpQuestions": ["查看影响金额最高的商品", "生成调价建议", "按门店拆分"]
}

模型层

表名

说明

关键字段

维度层

dim_product

商品维度

product_code, product_name, category_code, spec, unit, shelf_life_days

维度层

dim_store

门店维度

store_code, store_name, region_code, manager, status

维度层

dim_supplier

供应商维度

supplier_code, supplier_name, category_scope, status

事实层

fact_sales_detail

销售明细

biz_date, store_code, product_code, qty, amount, price, promotion_flag

事实层

fact_purchase_detail

采购明细

order_no, supplier_code, product_code, purchase_qty, purchase_price, received_qty

事实层

fact_inventory_snapshot

库存快照

snapshot_time, warehouse_code, store_code, product_code, stock_qty, stock_amount, batch_no

事实层

fact_delivery_detail

配送明细

delivery_no, route_code, product_code, outbound_qty, received_qty, planned_arrival_time, actual_arrival_time

事实层

fact_loss_detail

损耗明细

biz_date, store_code, product_code, loss_qty, loss_amount, loss_reason

应用层

app_alert_event

预警事件

alert_id, alert_type, level, target_type, target_id, fact, reason, suggestion, owner, status

应用层

app_report_task

报表任务

report_id, report_type, report_date, status, file_url, created_by

对象

推送内容

推送渠道

触发条件

管理层

经营日报摘要、P0/P1 重大预警、月度复盘

企业微信/钉钉/邮件

定时或重大异常触发

采购负责人

采购价异常、供应商到货异常、采购偏差

企业微信/钉钉/系统消息

规则触发或日报生成

仓储负责人

缺货、积压、临期、库龄、盘点异常

企业微信/钉钉/系统消息

库存快照计算后触发

配送负责人

线路延误、签收差异、缺配错配

企业微信/钉钉/系统消息

配送节点回传后触发

门店负责人

门店缺货、损耗异常、收货异常、低毛利商品

企业微信/钉钉/小程序

门店范围内预警触发

集成项

说明

测试重点

业务系统接口

对接采购、库存、销售、配送、损耗和财务系统

字段完整性、增量同步、失败重试

指标服务

统一计算并提供指标查询接口

口径准确性、权限过滤、性能

AI 服务

对接大模型、知识库和提示词模板

回答准确性、上下文限制、异常解释质量

报表服务

按模板生成 Word/PDF/Excel/HTML 报表

格式一致性、生成时效、导出链接

消息服务

对接企业微信、钉钉、邮件、短信

推送成功率、按钮回调、重复通知控制

权限与审计

统一登录、权限校验和日志记录

越权拦截、操作留痕、导出审计