# logistics-dashboard

**Repository Path**: Vincentor/logistics-dashboard

## Basic Information

- **Project Name**: logistics-dashboard
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-27
- **Last Updated**: 2026-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NEXUS Logistics AI — 物流智能分析与需求预测系统

本系统是专为物流与供应链场景打造的企业级全栈 **AI 驱动分析与预测仪表盘**。系统基于统一的 2025 年度物流运单数据集（`mock_logistics_data.csv`），深度支持三个维度的运营智能：

1. **描述性分析 (Descriptive Analytics)**：实时业务 KPI 指标大屏、多维动态交互图表（运量趋势、承运商履约 SLA、状态分布、区域/仓库履约效率）及多维度过滤切片。
2. **诊断性分析 (Diagnostic Analytics / AI 智能助理)**：自然语言人机对话界面。AI 层作为智能路由和编排中心，将自然语言解析为结构化执行计划（AST），调用底层确定性计算引擎完成聚合与计算，动态匹配图表类型，并输出完整的 SQL 等价语句与数据血缘解释。
3. **预测性与规范性分析 (Predictive & Prescriptive Analytics)**：基于时间序列历史数据的统计预测引擎（Holt-Winters 双重指数平滑、OLS 线性回归、移动平均 SMA），并结合订货提前期与服务水平（95%/99%）提供规范性库存行动建议（安全库存、再订货点 ROP、推荐补货批量）。

---

## 1. 系统架构与关键设计决策

### 1.1 系统架构图

```
+-----------------------------------------------------------------------------------+
|                                  用户交互层 (UI)                                  |
|   管理驾驶舱大屏  |  AI 诊断智能助手  |  需求预测与库存规划  |  What-If 场景模拟器 |
+-----------------------------------------------------------------------------------+
                                          │
                                          ▼
+-----------------------------------------------------------------------------------+
|                            AI 编排与意图路由层                                     |
|  - 自然语言语义解析与实体提取 (承运商、SKU、品类、时间窗口、运送状态等)             |
|  - 智能工具路由判定: [查询分析工具 (Query Tool)] vs [预测规划工具 (Forecast Tool)] |
|  - 结构化参数标准化 (AST) 与动态图表自动推荐                                      |
+------------------------------------+----------------------------------------------+
                                     │
                 ┌───────────────────┴───────────────────┐
                 ▼                                       ▼
+---------------------------------+     +------------------------------------------+
|       查询分析工具 (Query Tool)  |     |        需求预测工具 (Forecast Tool)      |
|  - KPI 聚合计算与过滤引擎       |     |  - Holt-Winters 双重指数平滑模型 (水平+趋势) |
|  - 时间序列多粒度汇总 (周/月)   |     |  - OLS 最小二乘法线性趋势回归模型         |
|  - 承运商/仓库/区域履约 SLA 排名|     |  - 简单移动平均 (SMA-3) 模型              |
|  - AST 执行计划与 SQL 等价生成  |     |  - 安全库存 (SS) 与再订货点 (ROP) 优化算法|
+---------------------------------+     +------------------------------------------+
                 │                                       │
                 └───────────────────┬───────────────────┘
                                     ▼
+-----------------------------------------------------------------------------------+
|                               统一底层数据集层                                    |
|       400 条 2025 全年真实运单 (355 种 SKU, 8 大品类, 9 家承运商, 9 大履约中心)   |
+-----------------------------------------------------------------------------------+
```

### 1.2 关键架构设计原则

1. **AI 作为路由与编排中心，绝非数据源头**：
   - AI 层负责理解用户意图、提取实体参数并生成抽象语法树（AST）。
   - 所有统计、汇总、率值计算与预测运算均由后端的**确定性数学与数据计算引擎**执行，杜绝大模型数字幻觉。
2. **开箱即用与零配置运行**：
   - 内置轻量高效的高精度语义解析引擎，部署上线无需强制绑定第三方外部 API Key，零依赖即可完整运行所有功能。同时预留了外部大模型接入配置扩展能力。
3. **完全可解释性与数据可溯源性**：
   - 每一条 AI 输出的回答或图表，均附带：
     - 所应用的过滤条件（时间范围、品类、状态等）
     - 执行耗时（毫秒级）与处理记录数
     - 结构化 AST 计划与等价 SQL 语句
     - 原始运单记录下钻表格与一键 CSV 导出
4. **统一响应式状态管理**：
   - 驾驶舱 KPI、时间趋势图、状态环形图、承运商排行榜与 What-If 模拟器完全共享统一数据集视图。

---

## 2. 核心功能与模块说明

### 2.1 管理驾驶舱大屏 (描述性分析)

- **核心 KPI 指标卡**：
  - **总运单数 (Total Orders)**：400 单（2025 全年）。
  - **已妥投运单 (Delivered Orders)**：304 单（占总单量 76.0%）。
  - **延迟运单 (Delayed Orders)**：55 单（延迟率 13.8%）。
  - **在途/异常运单 (In Transit / Exception)**：27 单在途，11 单异常，3 单取消。
  - **准时妥投率 (On-Time Delivery Rate)**：**84.7%**（计算公式：$\frac{\text{Delivered}}{\text{Delivered} + \text{Delayed}} \times 100\%$）。
  - **平均履约时效 (Average Delivery Time)**：**3.25 天**（成功妥投订单的平均下单至交付天数）。
  - **总销售额 (Total Order Value)**：**$13,695.87**（客单均价 $34.24）。
- **多维动态交互图表**：
  - **订单量与延迟趋势图**：支持按“月度 (Monthly)”与“周度 (Weekly ISO)”一键平滑切换。
  - **履约状态分布环形图**：展示妥投、延迟、在途、异常订单占比与百分比。
  - **承运商绩效天梯榜**：支持按“订单运量 (Volume)”、“延迟率 (Delay Rate %)”与“配送时效 (Avg Days)”多模式实时排序。
  - **履约网络多维分析**：支持区域 (`US-E`, `US-W`, `EU`, `US-C`, `UK`)、履约仓库 (`LON-FC1`, `EWR-DC1`, `SFO-DC2` 等) 与 8 大商品品类的运量与延迟率对比。
- **多维度切片过滤栏**：
  - 时间预设标签（`全部 2025`, `近 3 个月`, `上个月`, `Q1–Q4 季度`）
  - 承运商、运送状态、区域、仓库、品类、促销订单及全局搜索。

---

### 2.2 AI 智能诊断 Copilot (诊断性分析)

支持用户以自然语言提出各种业务诊断问题，系统自动执行**意图识别 $\to$ 工具选择 $\to$ 确定性计算 $\to$ 动态图表生成 $\to$ 结果呈现与解释**：

| 用户查询示例 | 路由工具 | 提取实体与执行逻辑 | 动态图表输出 |
| :--- | :--- | :--- | :--- |
| **"Show delayed orders by week for the last 3 months"**<br>*(查看近3个月按周维度的延迟订单)* | **Query Tool**<br>(查询分析) | 过滤时间为 Q4（2025-10-01 至 2025-12-31），按 ISO 周聚合 `delayed_count` | 周度延迟趋势折线图 |
| **"Which carrier has the highest delay rate?"**<br>*(哪家承运商的延迟率最高？)* | **Query Tool**<br>(查询分析) | 计算各承运商延迟占比，得出 **USPS** 延迟率最高达 **49.0%**（49单中11单延迟） | 承运商延迟率对比柱状图 |
| **"How many orders were delivered late last month?"**<br>*(上个月有多少订单延迟交付？)* | **Query Tool**<br>(查询分析) | 时间锁定 2025 年 12 月，统计 `status == 'delayed'` 数量（共 3 单） | 月度概览卡片 |
| **"What is the average delivery time by carrier?"**<br>*(各承运商的平均交付时长是多少？)* | **Query Tool**<br>(查询分析) | 按承运商聚合计算交付时长（天数） | 承运商时效对比柱状图 |

---

### 2.3 需求预测与库存规划工作台 (预测与规范性分析)

支持针对单一 SKU、特定商品品类或整体业务量进行未来 1~12 个月（默认 4 个月）的需求预测与库存策略推荐：

#### 支持的预测模型与数学原理：
1. **Holt-Winters 双重指数平滑模型 (Level + Trend)**：
   $$L_t = \alpha y_t + (1-\alpha)(L_{t-1} + T_{t-1})$$
   $$T_t = \beta(L_t - L_{t-1}) + (1-\beta)T_{t-1}$$
   $$\hat{y}_{t+h} = L_t + h \cdot T_t$$
   *优势：动态自适应近期需求波动，赋予最新数据更高权重。*

2. **OLS 最小二乘法线性回归模型 (Linear Trend Regression)**：
   $$y_t = \beta_0 + \beta_1 t + \epsilon_t$$
   *优势：拟合全年稳态线性增长或下降趋势。*

3. **简单移动平均模型 (Simple Moving Average, SMA-3)**：
   $$\hat{y}_{t+h} = \frac{1}{k} \sum_{i=1}^k y_{t-i+1} \quad (k=3)$$
   *优势：平滑短期异常脉冲，保留近期基线需求。*

#### 规范性库存优化策略 (Prescriptive Inventory Plan)：
- **提前期需求 (Lead Time Demand, $LTD$)**：
  $$LTD = \bar{d}_{\text{daily}} \times L = \frac{\bar{d}_{\text{monthly}}}{30} \times L$$
- **安全库存 (Safety Stock, $SS$)**：
  $$SS = Z \times \sigma_d \times \sqrt{\frac{L}{30}}$$
  *（在 95% 服务水平下 $Z=1.65$；99% 服务水平下 $Z=2.33$）*
- **再订货点 (Reorder Point, $ROP$)**：
  $$ROP = LTD + SS$$
- **推荐补货批量 (Suggested Order Batch)**：
  $$\text{Batch Size} = \text{月度预测均值} + SS$$

---

### 2.4 "What-If" 场景模拟实验室 (Bonus 特性)

支持交互式滑动调节三大变量，实时模拟极端工况对供应链网络的影响：
1. **承运商延迟恶化/优化 (-50% ~ +100%)**：模拟运力受阻或航道拥堵对综合妥投 SLA 的冲击。
2. **促销与需求激增 (-30% ~ +100%)**：模拟大促活动中销量激增对营收与备货量的拉动。
3. **交付提前期漂移 (-2天 ~ +5天)**：模拟海关清关变慢或港口拥堵对安全库存缓冲的需求。

---

## 3. 技术栈与工程规范

- **核心框架**：Next.js 16 (App Router, React 19, Server Components & Dynamic Route Handlers)
- **开发语言**：TypeScript 5.x（严格类型推导，全覆盖数据模型）
- **样式方案**：Tailwind CSS v4 + 现代深色玻璃拟态 (Glassmorphism)
- **图表套件**：轻量级响应式 SVG 交互图表引擎（零水合失真，带动态 Tooltip）
- **测试框架**：TypeScript / Tsx 自动化验证套件 + Python 端到端 HTTP 集成测试
- **容器与部署**：多阶段构建 Dockerfile, Docker Compose, Vercel 配置文件

---

## 4. 本地安装与启动指南

### 环境要求
- **Node.js**：18.x, 20.x, 22.x 或更高版本（已在 Node v23.9.0 上验证通过）
- **npm**：9.x 或更高版本

### 快速启动步骤

```bash
# 1. 进入项目根目录
cd d:\test\logistics-dashboard

# 2. 安装项目依赖
npm install

# 3. 执行全自动化验证测试套件 (包含 38 项核心测试断言)
npm run test

# 4. 启动本地开发服务器
npm run dev

# 5. 在浏览器中打开系统访问
http://localhost:3000
```

> **提示**：如果 3000 端口已被占用，Next.js 会自动切换到 3001 端口，终端会提示对应访问地址。

### 生产环境构建与启动

```bash
# 构建生产环境高优产物
npm run build

# 启动生产服务
npm start
```

### Docker 容器化部署

```bash
# 方式 1: 直接使用 Dockerfile 构建并运行
docker build -t logistics-ai-dashboard .
docker run -d -p 3000:3000 --name logistics-app logistics-ai-dashboard

# 方式 2: 使用 Docker Compose 一键拉起
docker-compose up -d
```

---

## 5. 自动化测试与验证结果

执行 `npm run test`，验证套件覆盖了底层数据集、KPI 准确性、多维聚合、自然语言解析路由及预测算法：

```text
======================================================
   NEXUS LOGISTICS AI - AUTOMATED VERIFICATION SUITE  
======================================================

[1] DATASET INTEGRITY & DESCRIPTIVE KPIS:
  ✓ PASS: Parsed exactly 400 records from dataset
  ✓ PASS: Total orders matches 400
  ✓ PASS: Delivered orders equals 304
  ✓ PASS: Delayed orders equals 55
  ✓ PASS: In transit orders equals 27
  ✓ PASS: Exception orders equals 11
  ✓ PASS: Canceled orders equals 3
  ✓ PASS: On-time delivery rate is 84.7%
  ✓ PASS: Average delivery time is 3.25 days
  ✓ PASS: Active carriers count equals 9

[2] QUERY ENGINE & MULTI-DIMENSIONAL AGGREGATIONS:
  ✓ PASS: Aggregated volume across all 12 months
  ✓ PASS: Carrier comparison covers all 9 carriers
  ✓ PASS: FedEx is top carrier by volume

[3] AI ORCHESTRATION & NATURAL LANGUAGE QUERY ROUTING:
  ✓ PASS: Q1 routed to Query Tool (dimension: time_week, metric: delayed_count)
  ✓ PASS: Q2 routed to Query Tool (dimension: carrier, metric: delay_rate)
  ✓ PASS: Q3 routed to Query Tool (startDate: 2025-12-01)
  ✓ PASS: Q4 routed to Forecasting Tool (entity: CRAYON-0008, horizon: 4 mo)
  ✓ PASS: Q5 routed to Forecasting Tool (entity: PAPER)

[4] PREDICTIVE DEMAND FORECASTING & PRESCRIPTIVE INVENTORY MATH:
  ✓ PASS: Exponential smoothing generates 4-month horizon
  ✓ PASS: Forecast reflects upward historical trajectory
  ✓ PASS: Linear regression identifies positive demand slope
  ✓ PASS: Calculates positive safety stock buffer
  ✓ PASS: Reorder point exceeds safety stock
  ✓ PASS: Applies 95% service level standard

[5] END-TO-END AI ORCHESTRATION EXECUTION PIPELINE:
  ✓ PASS: End-to-end execution completed
  ✓ PASS: Structured plan generates valid SQL lineage
  ✓ PASS: Dynamic chart configuration rendered

======================================================
  VERIFICATION RESULTS: 38 PASSED, 0 FAILED (100% 通过)
======================================================
```

---

## 6. 假设条件与系统边界说明

### 假设条件 (Assumptions)：
1. **数据集时间跨度**：所有 400 条运单数据分布在 2025 自然年（`2025-01-01` 至 `2025-12-31`）。相对时间表达（如“近 3 个月”）锚定于 2025 年第四季度（10月~12月）。
2. **妥投率计算口径**：准时率仅基于已有明确交付状态的订单进行统计，即 $\frac{\text{已妥投}}{\text{已妥投} + \text{延迟}}$。在途与异常订单计入独立指标。
3. **履约时长计算**：仅针对状态为 `delivered` 且具备有效交付时间的运单，计算 `delivery_date - order_date`（均值为 3.25 天）。

### 限制与当前未支持特性 (Limitations)：
1. **多重递归嵌套复杂子查询**：类似“找出所有延迟率高于英国区域仓库平均延迟率的承运商所承运的商品品类”这类多层嵌套查询，目前系统会解构为主实体聚合进行处理。
2. **外部实时交通/天气数据源**：目前预测与分析均基于企业自身历史运单日志，未接入实时 GPS 传感器或外部气象 API。

---

## 7. 未来演进规划 (Future Roadmap)

1. **AutoML 智能模型选型**：引入基于 AIC / BIC 信息准则的自动超参数调优，在 ARIMA、Prophet 与 Holt-Winters 间自动选择最优预测器。
2. **多级履约网络库存动态再平衡 (Multi-Echelon Rebalancing)**：根据各区域仓储饱和度与预测需求，自动给出跨仓调拨建议。
3. **实时流数据接入**：接入 Kafka / Flink 消息流，支持海量 IoT 运单轨迹与实时温控/延误告警。
4. **碳足迹与绿色物流评估**：根据承运商运送路线与交通工具类型，计算每票订单的碳排放预估。