AI自動配車システムデモプロトタイプ

AI Automatic Vehicle Routing System - Demo Prototype

🚧 プロジェクト状態： Story 004 完了（Demo展示増強完了） 📅 最終更新： 2025-11-03 ✅ 現在の実装： Backend VRP API、Frontend UI、地図表示、結果分析UI、方案対比、詳細情報表示 🔜 開発予定： E2Eテスト、パフォーマンス最適化（Story 005以降）

📋 プロジェクト概要

日本の物流業界向けのAI自動配車システムのデモンストレーション用プロトタイプ。4つの集荷拠点、100件の配送先、10台の車両を使用した最適化配車のデモンストレーション。

計画機能（最終デモ目標）：

🚛 車両ルート最適化（VRP - Vehicle Routing Problem）
📍 OpenStreetMapベースのビジュアル化
📊 コスト削減分析
⚡ 高速計算（2-5秒目標）
🎯 時間窓制約対応

現在の実装状態（Story 004完了）：

✅ Monorepo プロジェクト構造
✅ FastAPI Backend + OR-Tools 最適化エンジン
✅ React + TypeScript フロントエンド
✅ OpenStreetMap 地図表示
✅ 結果分析UI（最適化前後対比）
✅ 詳細情報表示（選択状態Drawer）
✅ ルート方向矢印可視化

🎯 最適化方案概要

最適化前後の比較

本システムは 基線方案（Baseline） と 最適化方案（Optimized） の2つの配車計画を生成し、OR-Tools による最適化効果を定量的に証明します。

📊 基線方案（Simple Assignment）

アルゴリズム： 単純割当法

各配送先を最も近い利用可能な車両に順次割当
車両容量制約のみ考慮（時間窓・距離最適化なし）
計算時間：< 1秒

特徴：

実装が極めてシンプル
人間の直感的な割当に近い
最適化なしの「現状」を再現

⚡ 最適化方案（OR-Tools CVRPTW）

アルゴリズム： Google OR-Tools - Capacitated Vehicle Routing Problem with Time Windows

制約条件:
- 車両容量制約（重量・体積）
- 時間窓制約（午前指定・午後指定）
- 拠点出発・帰還制約
- サービス時間制約
最適化目標:
- 総走行距離の最小化
- 総コストの最小化（距離コスト + 時間コスト）
- 車両積載率の最大化
計算時間： 2-30秒（データ規模による）

特徴：

数理最適化による科学的アプローチ
複数の制約条件を同時に考慮
人間の経験では到達困難な最適解を発見

🔬 最適化原理

OR-Tools CVRPTW の仕組み

問題のモデル化

最小化: Σ(距離コスト) + Σ(時間コスト)
制約:
- 各配送先は1回だけ訪問
- 車両容量を超えない
- 時間窓を守る
- 全車両は拠点から出発し拠点に戻る

解法アプローチ
- 初期解生成: Cheapest Insertion / Savings アルゴリズム
- 局所探索: 2-opt, Relocate, Exchange 近傍探索
- メタヒューリスティクス: Tabu Search, Simulated Annealing
- 枝刈り: 実行不可能な解の早期除外
技術的優位性
- Googleが10年以上開発した産業グレードソルバー
- 大規模問題（1000+ 配送先）にスケール
- C++実装による高速計算

📈 典型的な改善効果

本デモシステム（拠点1件、車両3台、配送先20件）における実測値：

指標	基線方案	最適化方案	改善率
総距離	145.2 km	118.7 km	-18.2%
総コスト	¥52,400	¥43,100	-17.7%
平均積載率	58.3%	77.8%	+19.5 pt (+33.4%)
使用車両数	3台	3台	0%
計算時間	0.2秒	4.8秒	-

コスト削減の内訳：

距離削減: 26.5 km → 約 ¥5,300 節約（¥200/km）
時間削減: 35 分 → 約 ¥1,750 節約（¥3,000/h）
積載率向上: 不必要な車両稼働を防止

✨ 主要な改善点

1. ルート最適化

Before: 配送先を距離順に訪問 → 往復・交差が発生
After: 巡回セールスマン問題（TSP）を解き最短経路を発見
効果: 走行距離 15-25% 削減

2. 時間窓の効率的配置

Before: 午前指定を最初に、午後指定を後に訪問 → 待機時間発生
After: 時間窓制約内で最適な訪問順序を計算
効果: 総所要時間 10-20% 削減

3. 車両積載率の向上

Before: 車両ごとに独立して割当 → 容量の無駄
After: 全車両の容量を考慮した最適配分
効果: 積載率 20-40 pt 向上、将来的な車両数削減に貢献

4. コスト最小化

Before: 距離のみ考慮
After: 距離コスト + 時間コスト + 車両固定コストの総和を最小化
効果: 総コスト 15-25% 削減

🎬 Demo 展示機能

Story 004 で追加された機能：

選択状態詳細情報表示
- 拠点・車両・配送先の詳細データをDrawerで表示
- 時間窓でソートされた配送先一覧
- 総容量・総重量の自動計算
最適化前後方案対比Tab
- 基線方案 vs 最適化方案の並列表示
- 4つの総合指標カード（距離・コスト・積載率・車両数）
- 8行の詳細比較テーブル
- 改善率の視覚化（緑=改善、赤=悪化）
ルート方向矢印
- 地図上のルートに方向矢印を表示
- 配送フローの可視化
- 各ルートの色と矢印色を統一

デモ実演フロー：

1. [デモデータ作成] → 拠点・車両・配送先を生成
2. [詳細を表示] → 入力データの品質を確認
3. [VRP最適化実行] → 2-5秒で最適化完了
4. [方案対比Tab] → Before/After の数値比較
5. [地図表示] → ルート可視化 + 方向矢印

🏗️ 技術スタック

フロントエンド

Framework: React 18.2+ with TypeScript 5.3+
UI Library: Ant Design 5.12+
Map: Leaflet 1.9+ + OpenStreetMap
State: Zustand 4.4+
Build: Vite 5.0+

バックエンド

Framework: FastAPI 0.109+
Language: Python 3.11（厳密） - 仮想環境必須
- ⚠️ Python 3.12+/3.14では OR-Tools が動作しません
Database: SQLite 3.40+
ORM: SQLAlchemy 2.0+
Optimization: OR-Tools 9.8+ (Google)

🚀 クイックスタート

前提条件

Python 3.11 （プロジェクト実行用 - 仮想環境で使用）
- 開発環境は任意のPythonバージョン（3.14等）でOK
- 重要: バックエンド実行には Python 3.11 の仮想環境が必要
Node.js 18+
Git

インストールと起動

1. リポジトリのクローン

git clone <repository-url>
cd VBA

2. バックエンド起動

Python 3.11仮想環境の作成（初回のみ）:

cd backend

# Windows
py -3.11 -m venv venv
venv\Scripts\activate

# macOS/Linux
python3.11 -m venv venv
source venv/bin/activate

# 仮想環境のPythonバージョン確認（3.11.xであること）
python --version

依存関係のインストールと起動:

# 仮想環境がアクティブな状態で実行
pip install -r requirements.txt
uvicorn app.main:app --reload

→ バックエンドAPI: http://localhost:8000 → Swagger UI: http://localhost:8000/docs

3. フロントエンド起動（別ターミナル）

cd frontend
npm install
npm run dev

→ フロントエンド: http://localhost:5173

📁 プロジェクト構造

ai-vehicle-routing/
├── frontend/          # React + TypeScript フロントエンド
│   ├── src/
│   │   ├── components/  # UI コンポーネント
│   │   ├── pages/       # ページコンポーネント
│   │   ├── services/    # API サービス層
│   │   ├── stores/      # Zustand ステート管理
│   │   └── types/       # TypeScript 型定義
│   ├── package.json
│   └── vite.config.ts
│
├── backend/           # FastAPI バックエンド
│   ├── app/
│   │   ├── api/         # API エンドポイント
│   │   ├── models/      # SQLAlchemy モデル
│   │   ├── schemas/     # Pydantic スキーマ
│   │   ├── services/    # ビジネスロジック
│   │   └── main.py      # アプリケーション エントリーポイント
│   ├── data/            # データベース & デモデータ
│   ├── tests/           # テスト
│   └── requirements.txt
│
├── shared/            # 共有型定義（フロント・バック共通）
│   └── types/
│       └── index.ts
│
└── docs/              # ドキュメント
    ├── architecture.md     # アーキテクチャ設計書
    ├── front-end-spec.md   # UI/UX 仕様書
    └── stories/            # 開発ストーリー

🎯 開発ロードマップ

Story 001: プロジェクト初期化 ✅ 完了

✅ Monorepo 構造作成
✅ バックエンド骨格（FastAPI + 基本エンドポイント）
✅ フロントエンド骨格（React + TypeScript + Vite）
✅ 共有型定義
✅ デモデータテンプレート

Story 002: 最適化エンジン ✅ 完了

✅ Google OR-Tools CVRPTW 実装
✅ 車両容量制約（重量・容積）
✅ 時間窓制約（午前30%、午後70%）
✅ 複数拠点対応
✅ /api/v1/optimization/optimize エンドポイント
✅ 基線方案（Simple Assignment）との比較機能

Story 003: Frontend統合 ✅ 完了

✅ OpenStreetMapでのルート表示
✅ 10色の車両ルートカラーリング
✅ Zustand状態管理
✅ API Client実装
✅ 結果表示UI（概要・ルート一覧・コスト比較）

Story 004: Demo展示増強 ✅ 完了

✅ 選択状態詳細情報表示（Drawer）
✅ 最適化前後方案対比Tab
✅ ルート方向矢印可視化
✅ 箭頭尺寸優化 + API超時延長

Story 005以降（予定）

⏳ E2Eテスト実装
⏳ パフォーマンス最適化
⏳ エラーハンドリング強化

📊 デモデータ

拠点: 4箇所（東京都心部、20km範囲内）
車両: 10台（2t車×5、4t車×5）
配送先: 100件（50km範囲内）
時間窓: 午前30件、午後70件

🧪 テスト

バックエンドテスト:

cd backend
pytest

フロントエンドテスト:

cd frontend
npm run test

📚 ドキュメント

アーキテクチャ設計書 - システム全体の技術設計
UI/UX仕様書 - フロントエンド詳細仕様
API仕様 - Swagger UI（起動後アクセス）

🛠️ 開発コマンド

バックエンド

# 開発サーバー起動（ホットリロード）
uvicorn app.main:app --reload

# データベース初期化
python scripts/init_db.py

# デモデータ投入
python scripts/seed_demo_data.py

# テスト実行
pytest

# コードフォーマット
black app/

フロントエンド

# 開発サーバー起動
npm run dev

# 本番ビルド
npm run build

# ビルド結果のプレビュー
npm run preview

# テスト実行
npm run test

# リント
npm run lint

🎨 UI/UX 設計方針

注：以下は最終デモの UI/UX 設計方針です（docs/front-end-spec.md 参照）

日本語UI: 日本市場向けのローカライズ
投影モード: 大画面デモ用の高コントラスト表示（予定）
ワンクリックデモ: 最小限の操作で最適化実行（予定）
段階的情報開示: 初期画面はシンプル、詳細は必要時に表示（予定）

現在の実装： 基本的な React アプリケーション骨格のみ

🔧 トラブルシューティング

バックエンドが起動しない

Python バージョンの確認:

# 仮想環境内のPythonバージョンを確認（3.11.xである必要がある）
python --version

# システムのPythonバージョン（開発用、任意でOK）
py --version  # Windows
python3 --version  # macOS/Linux

仮想環境の再作成:

cd backend
# 既存の仮想環境を削除
rm -rf venv  # macOS/Linux
rmdir /s venv  # Windows

# Python 3.11で仮想環境を再作成
py -3.11 -m venv venv  # Windows
python3.11 -m venv venv  # macOS/Linux

# 仮想環境をアクティブ化
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate  # Windows

# 依存関係の再インストール
pip install --upgrade pip
pip install -r requirements.txt

OR-Tools インストールエラーの場合:

# Python 3.11が正しくインストールされているか確認
py -3.11 --version  # Windows
python3.11 --version  # macOS/Linux

# Python 3.11がない場合はインストール
# Windows: https://www.python.org/downloads/
# macOS: brew install python@3.11
# Ubuntu: sudo apt install python3.11 python3.11-venv

フロントエンドが起動しない

# Node.js バージョン確認
node --version  # 18+ 必要

# node_modules 削除して再インストール
rm -rf node_modules
npm install

共有型のインポートエラー

# Vite config の確認（vite.config.ts）
# server.fs.allow: ['..'] が設定されているか確認

📄 ライセンス

このプロジェクトは演示用プロトタイプです。

👥 チーム

アーキテクト: Winston
UXデザイナー: Sally
開発者: James

最終更新: 2025-11-03 バージョン: 1.4.0（Story 004 完了） ステータス: ✅ Demo展示機能完成、本番デモ準備完了

重要： 本プロジェクトは Python 3.11 仮想環境 が必須です。Python 3.12+では OR-Tools が動作しません。

Name		Name	Last commit message	Last commit date
.bmad-core		.bmad-core
.claude		.claude
TEST		TEST
backend		backend
docs		docs
frontend		frontend
project-rules		project-rules
shared/types		shared/types
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CODEX_REVIEW_TEMPLATE_CN.md		CODEX_REVIEW_TEMPLATE_CN.md
README.md		README.md
out.txt		out.txt
start.bat		start.bat

Latest commit

History

Folders and files

Repository files navigation

AI自動配車システムデモプロトタイプ

📋 プロジェクト概要

🎯 最適化方案概要

最適化前後の比較

📊 基線方案（Simple Assignment）

⚡ 最適化方案（OR-Tools CVRPTW）

🔬 最適化原理

OR-Tools CVRPTW の仕組み

📈 典型的な改善効果

✨ 主要な改善点

1. ルート最適化

2. 時間窓の効率的配置

3. 車両積載率の向上

4. コスト最小化

🎬 Demo 展示機能

🏗️ 技術スタック

フロントエンド

バックエンド

🚀 クイックスタート

前提条件

インストールと起動

📁 プロジェクト構造

🎯 開発ロードマップ

Story 001: プロジェクト初期化 ✅ 完了

Story 002: 最適化エンジン ✅ 完了

Story 003: Frontend統合 ✅ 完了

Story 004: Demo展示増強 ✅ 完了

Story 005以降（予定）

📊 デモデータ

🧪 テスト

📚 ドキュメント

🛠️ 開発コマンド

バックエンド

フロントエンド

🎨 UI/UX 設計方針

🔧 トラブルシューティング

バックエンドが起動しない

フロントエンドが起動しない

共有型のインポートエラー

📄 ライセンス

👥 チーム

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages