ASAP_PROJECT

高速データ分析・可視化システム - Django + Pandas + TailwindCSS で構築された売上・在庫データ管理プラットフォーム

🚀 クイックスタート

1. 必要な環境

• Python 3.13+
• uv (Rust 製高速パッケージマネージャー)

2. セットアップ

# リポジトリをクローン
git clone <repository-url>
cd ASAP_Project

# 仮想環境を有効化
source .venv/bin/activate

# 依存関係をインストール（uvを使用）
uv sync

# データベースを初期化（既に適用済みの場合はスキップ可能）
uv run python manage.py migrate

# 開発サーバーを起動
uv run python manage.py runserver

3. アクセス

ブラウザで http://127.0.0.1:8000 にアクセス

📊 主な機能

• 📁 CSV データインポート: 得意先、商品、取引、在庫データの一括取り込み
• 📈 データ可視化: 商品別・月次売上グラフの自動生成
• 🔍 データ分析: Pandas を活用した高速データ処理
• 📱 レスポンシブ UI: デスクトップ・モバイル対応の統一 UI

🛠️ 技術スタック

• Backend: Django 5.2.4 (Python Web フレームワーク)
• Data Processing: Pandas 2.3.1 (データ分析・処理)
• Visualization: Matplotlib 3.10.3 (グラフ生成) + 日本語フォント対応
• Frontend: TailwindCSS (コンポーネント指向 CSS)
• Package Manager: uv (Rust 製高速パッケージマネージャー)

🎯 uv による開発

uv とは

Rust 製の高速 Python パッケージマネージャー。従来の pip/pipenv より10-100 倍高速

基本コマンド

# パッケージの追加（pip installの代替）
uv add package_name

# 開発サーバー起動
uv run python manage.py runserver

# マイグレーション
uv run python manage.py makemigrations
uv run python manage.py migrate

# 管理者ユーザー作成
uv run python manage.py createsuperuser

# 静的ファイル収集
uv run python manage.py collectstatic

📁 プロジェクト構造

ASAP_Project/
├── ASAP/                   # Django設定
├── asap_app/               # メインアプリケーション
│   ├── features/           # 機能別モジュール
│   │   ├── imports/        # CSVインポート機能
│   │   ├── lists/          # リスト、ページネーション機能
│   │   └── graphs/         # グラフ生成機能
│   ├── views/              # ビュー（機能別分割）
│   ├── models/             # データモデル（機能別分割）
│   ├── templatetags/       # カスタムテンプレートタグ
│   ├── utils/              # 共通処理、ユーティリティ
├── templates/              # テンプレート（高度に最適化済み）
│   ├── asap_app/           # ページテンプレート
│   ├── commons/            # ベースレイアウト
│   └── components/         # 再利用可能コンポーネント
├── static/                 # 静的ファイル
└── pyproject.toml          # uv設定ファイル

🎨 テンプレート設計

✨ 高度に最適化されたコンポーネント設計

• 150 行以上のコード削減と95%重複排除を実現
• 統一されたアイコンシステムとテーブルコンポーネント

📁 テンプレート構造

templates/
├── asap_app/           # 各ページのメインテンプレート
│   ├── index.html      # ダッシュボード
│   ├── import.html     # データインポート
│   ├── graph_*.html    # グラフ表示ページ
│   └── setting.html    # 設定ページ
├── commons/            # ベースレイアウト
│   └── base.html       # 共通レイアウト
└── components/         # 再利用可能コンポーネント
    ├── icons/          # 統一アイコンシステム
    ├── tables/         # テーブルコンポーネント
    ├── menu.html       # ナビゲーション
    └── header.html     # ヘッダー

🛠️ 使用方法

<!-- アイコンの使用 -->
{% include 'components/icons/chart-icon.html' %}

<!-- 統一テーブル -->
{% include 'components/tables/unified-table.html' %}

<!-- テンプレートタグの使用 -->
{% render_menu %}
{% render_controller tbl title "paginate" %}

📝 開発ガイドライン

データモデル

• Client: 得意先マスター（コード、名称、住所、登録日）
• Product: 商品マスター（商品コード、名称、メーカー情報）
• Transaction: 取引データ（売上、数量、日付）
• Stock: 在庫データ

ビュー設計

• common_views.py: ダッシュボード、設定、リスト表示
• import_views.py: CSV 取り込み機能
• graph_views.py: グラフ・チャート生成

開発の進め方

1. 新機能追加: 機能別に views モジュールを分割
2. テンプレート作成: 既存コンポーネントを活用
3. データ処理: Pandas ベースの import 基底クラスを継承

README に追記するなら、開発ガイドラインの最後あたりに「import 規約」として明記すると分かりやすいです。たとえばこんな感じでどうでしょう 👇

---

📦 import 規約

• 外部で使用する 変数・関数・クラス は、必ず __init__.py に定義してから呼び出してください。
• 各モジュールから直接 import するのではなく、__init__.py を経由した 明示的なエクスポート を徹底してください。

# ❌ NG
from asap_app.features.dataframes import df_stock

# ✅ OK (__init__.py 経由)
from asap_app.features import df_stock

こうすることで、

• モジュール公開範囲を明確化
• 循環参照の防止
• import 経路の統一
• リファクタリング時の影響範囲を最小化

が期待できます。

🔗 関連ドキュメント

• CLAUDE.md: Claude Code 用の詳細開発ガイド
• TEMPLATE_DESIGN.md: テンプレート設計の詳細仕様

---

💡 初回セットアップで問題が発生した場合は、uv の公式ドキュメントを確認するか、仮想環境の再作成を試してください。