升鲜宝 AI 报表原型与接口设计报表模板、交互原型、数据接口与集成规范（一）---升鲜宝生鲜配送供应链管理系统源代码服务

升鲜宝 AI 报表原型与接口设计

报表模板、交互原型、数据接口与集成规范

|----------|---------------------------------|
| 项目名称 | 升鲜宝集成 AI 大模型 |
| 文档版本 | V1.0 |
| 文档日期 | 2026 年 1 月 28 日 |
| 适用对象 | 管理层、采购、仓储、配送、门店运营、信息化团队 |
| 交付范围 | 供应链业务 AI 分析、自动报表、智能预警、问数助手与接口设计 |
| 文档定位 本交付稿用于明确升鲜宝 AI 供应链分析与预警平台的业务范围、指标口径、报表形态、接口边界与实施路径，支持首版 MVP 立项、开发排期与验收。 ||

1. 设计目标与用户角色

|----------|----------------------|---|---|
| 用户角色 | 核心诉求 | 典型使用场景 ||
| 管理层 | 快速掌握销售、毛利、库存、损耗和异常风险 | 查看经营日报、月度复盘、重大预警和趋势分析 ||
| 采购负责人 | 控制采购价格、供应商履约和采购计划准确性 | 查看采购价格异常、供应商评分、采购建议 ||
| 仓储负责人 | 保障库存准确、周转合理、临期和损耗可控 | 查看缺货、积压、临期、库龄和盘点异常 ||
| 配送负责人 | 提升配送准时率和差异闭环效率 | 查看线路延误、缺配错配、签收差异和门店异常反馈 ||
| 门店运营 | 关注门店销售、缺货、损耗、收货和毛利问题 | 查看门店日报、缺货清单、低毛利商品、损耗排行 ||
| IT/数据团队 | 保障数据准确、接口稳定、权限和审计可控 | 监控任务、接口、日志、数据质量和权限配置 ||
| 设计目标 报表原型以"管理者看总体、业务负责人看异常、一线人员看待办"为原则，所有报表都支持指标解释、异常追问、明细下钻、导出和预警闭环。 |||

2. 产品功能地图

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

3. 经营看板原型

|----------|--------------------------------|-----------------------|---|---|
| 区域 | 组件 | 显示内容 | 交互 ||
| 顶部筛选区 | 日期、区域、门店、仓库、品类、供应商 | 支持默认今日、昨日、本周、本月和自定义日期 | 筛选后全局刷新，可保存常用筛选 ||
| 核心 KPI 区 | 销售额、毛利率、库存金额、缺货 SKU、损耗金额、配送准时率 | 展示当前值、环比、同比、目标达成率 | 点击进入指标明细和趋势分析 ||
| 趋势图区 | 销售、毛利、库存、损耗趋势 | 按日/周/月展示，支持品类拆分 | 点击某点查看当日异常摘要 ||
| 异常摘要区 | 重点预警 Top 10 | 按等级、影响金额、影响门店排序 | 点击打开预警卡片并处理 ||
| AI 建议区 | 今日经营建议 | 自动生成 3-5 条可执行建议 | 支持采纳、忽略、转任务 ||
| 首页布局草图 ┌──────────────────────────────────────────────┐ │ 筛选：日期区域门店仓库品类供应商 │ ├──────────┬──────────┬──────────┬──────────┤ │ 销售额 │ 毛利率 │ 库存金额 │ 缺货SKU │ ├──────────┴──────────┴──────────┴──────────┤ │ 销售/毛利趋势图 │ 品类贡献/库存结构图 │ ├──────────────────────┬──────────────────────┤ │ 重点预警 Top10 │ AI 今日经营建议 │ └──────────────────────┴──────────────────────┘ ||||

4. 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 预警，复核采购价异常商品，调整缺货商品补货计划，并对高库存商品启动促销或调拨。 |

5. 预警中心原型

|--------|---------------------|---|---|
| 字段 | 说明 | 示例 ||
| 预警编号 | 系统自动生成，唯一标识 | 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；必要时调整售价或采购量。操作：认领 | 转任务 | 查看明细 | 关闭 |||

6. 自然语言问数原型

|----------|-------------------|---|---|
| 问题类型 | 用户问题示例 | 系统处理方式 ||
| 指标查询 | 今天销售额是多少？各品类贡献如何？ | 识别指标、时间和维度，调用指标查询接口并生成解释 ||
| 异常追问 | 为什么今天毛利率下降？ | 调用毛利拆解模型，按成本、售价、损耗、结构变化归因 ||
| 明细下钻 | 哪些门店的香蕉缺货风险最高？ | 过滤商品和预警类型，返回门店列表和风险等级 ||
| 建议生成 | 明天叶菜怎么采购？ | 结合销量预测、库存、供应商履约和采购规则生成建议 ||
| 报表生成 | 帮我生成本周供应商履约分析 | 调用报表生成接口，输出结构化报告和导出链接 ||
| 问数边界 问数助手不直接访问数据库裸表，而是通过指标服务、权限服务和报表服务获取结构化结果；AI 只负责理解问题、组织查询、解释结果和生成建议。 |||

7. 接口总体设计

|----------|---|---|
| 前端/消息端 ↓ API 网关 ↓ 认证鉴权服务 ── 权限范围：区域/门店/仓库/供应商/指标 ↓ 业务服务层 ├── 指标查询服务 metric-service ├── 报表生成服务 report-service ├── 预警中心服务 alert-service ├── 问数助手服务 ai-query-service ├── 文件导出服务 export-service └── 消息推送服务 message-service ↓ 数据服务层：指标宽表 / 预警表 / 报表模板 / 业务明细 / 知识库 ||
| 设计原则 | 说明 ||
| 统一认证 | 所有接口通过 Token 或企业内部 SSO 鉴权，接口层记录用户身份和权限范围 ||
| 结构化返回 | 指标、图表、明细、解释和建议分开返回，便于前端展示和二次处理 ||
| 幂等重试 | 报表生成、预警处理和消息推送需要支持幂等，避免重复生成或重复通知 ||
| 异步任务 | 复杂报表和大范围查询采用任务 ID 方式异步生成，前端轮询或回调获取结果 ||
| 审计日志 | 关键查询、导出、预警关闭、规则变更、权限变更均需记录日志 ||

8. 核心 API 设计

|--------|--------------------------------|----------|----------------------|
| 方法 | 接口路径 | 接口名称 | 用途 |
| 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 个百分点。" } |

报表生成接口示例

预警查询接口示例

AI 问数接口示例

|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 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": $"查看影响金额最高的商品", "生成调价建议", "按门店拆分"$ } |

9. 数据模型与字段约定

|---------|-------------------------|--------|--------------------------------------------------------------------------------------------------------------|
| 模型层 | 表名 | 说明 | 关键字段 |
| 维度层 | 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 |

10. 消息推送与权限安全

|--------|------------------------|--------------|-----------|
| 对象 | 推送内容 | 推送渠道 | 触发条件 |
| 管理层 | 经营日报摘要、P0/P1 重大预警、月度复盘 | 企业微信/钉钉/邮件 | 定时或重大异常触发 |
| 采购负责人 | 采购价异常、供应商到货异常、采购偏差 | 企业微信/钉钉/系统消息 | 规则触发或日报生成 |
| 仓储负责人 | 缺货、积压、临期、库龄、盘点异常 | 企业微信/钉钉/系统消息 | 库存快照计算后触发 |
| 配送负责人 | 线路延误、签收差异、缺配错配 | 企业微信/钉钉/系统消息 | 配送节点回传后触发 |
| 门店负责人 | 门店缺货、损耗异常、收货异常、低毛利商品 | 企业微信/钉钉/小程序 | 门店范围内预警触发 |

权限控制

角色权限：按管理层、采购、仓储、配送、门店、财务、IT 等角色配置功能权限。
数据权限：按区域、门店、仓库、供应商、品类和指标敏感级别控制访问范围。
操作权限：预警关闭、规则修改、报表导出、接口调用需单独授权并记录审计日志。
敏感信息保护：供应商报价、毛利、成本等敏感字段需设置查看和导出权限。
AI 安全边界：提示词中自动注入用户权限范围，禁止越权查询和跨角色泄露。

11. 部署集成与测试验收

|---------|------------------------------|--------------------|
| 集成项 | 说明 | 测试重点 |
| 业务系统接口 | 对接采购、库存、销售、配送、损耗和财务系统 | 字段完整性、增量同步、失败重试 |
| 指标服务 | 统一计算并提供指标查询接口 | 口径准确性、权限过滤、性能 |
| AI 服务 | 对接大模型、知识库和提示词模板 | 回答准确性、上下文限制、异常解释质量 |
| 报表服务 | 按模板生成 Word/PDF/Excel/HTML 报表 | 格式一致性、生成时效、导出链接 |
| 消息服务 | 对接企业微信、钉钉、邮件、短信 | 推送成功率、按钮回调、重复通知控制 |
| 权限与审计 | 统一登录、权限校验和日志记录 | 越权拦截、操作留痕、导出审计 |

测试用例建议

构造采购价上涨 15% 的样本，验证采购价异常预警是否触发、等级是否正确、建议是否合理。
构造未来 2 日预测销量高于当前库存的样本，验证缺货预警、补货建议和推送对象。
构造负毛利商品样本，验证毛利异常归因是否能拆解采购成本、售价和促销因素。
构造配送计划时间晚于实际签收的样本，验证配送延误、线路统计和责任人推送。
使用不同角色账号查询同一报表，验证数据权限过滤和敏感字段控制。