🐈

# 1.4 Django × Vue 業務システムのフォルダ構成と設計ルール

に公開
Django
Vue.js
tech

業務システム刷新におけるフォルダ構成と設計ルール

業務システム刷新の中で最初に検討したのが「どういう構成で作るか」。
Django × Vue のプロジェクトでは 標準的な構成をベースに、責務ごとに整理する 方針を取った。

ここでは実際のフォルダ構成を例に示し、なぜ分割が重要なのかを説明する。

Django 側の構成

今回の刷新プロジェクトのディレクトリは以下のようになっている。

backend/
├─ accounts/          # 認証・ユーザー管理
│  ├─ models/
│  │  ├─ user.py
│  │  ├─ dept.py
│  │  ├─ role.py
│  │  ├─ user_dept.py
│  │  └─ user_role.py
│  ├─ serializers/
│  │  └─ auth.py
│  └─ views/
│     └─ auth.py
├─ core/              # 共通機能（メニュー、部署・ロール、添付ファイルなど）
│  ├─ models/
│  │  ├─ menu.py
│  │  ├─ menu_dept.py
│  │  └─ attachments.py
│  ├─ serializers/
│  │  └─ menu.py
│  └─ views/
│     └─ menu.py
├─ notice/            # お知らせ管理
│  ├─ models/
│  │  ├─ notice.py
│  │  └─ notice_category.py
│  ├─ serializers/
│  │  └─ notice.py
│  └─ views/
│     └─ notice.py
└─ project/           # プロジェクト設定
   ├─ settings.py
   ├─ urls.py
   └─ asgi.py / wsgi.py

ポイント

  • accounts
    認証やユーザー管理に関するコードをまとめる。
    さらに models/ を細かく分けており、user.py / dept.py / role.py といった単位で整理。
    これによって「User-Dept 関連はどこに書くか？ → user_dept.py」とすぐに判断できる。

  • core
    全体共通で使う仕組みを集約。メニューや部署別の表示制御、添付ファイル管理など。
    業務アプリから横断的に利用するものをここに入れる。

  • notice
    業務アプリのひとつ。お知らせやカテゴリーを個別のモデルファイルに分けている。

Vue 側の構成

frontend/
├─ src/
│  ├─ api/            # axios ラッパと API 呼び出し
│  ├─ components/     # 再利用 UI 部品
│  │  └─ notice/
│  │     ├─ CategoryDialog.vue
│  │     └─ NoticeDialog.vue
│  ├─ router/         # Vue Router 設定
│  ├─ store/          # Vuex / Pinia ストア
│  │  ├─ auth.js
│  │  └─ ui.js
│  ├─ views/          # 画面単位
│  │  ├─ HomeView.vue
│  │  └─ LoginView.vue
│  └─ App.vue

Vue 側も同様に、views（画面）と components（部品）を分離 し、UI 部品を整理。
API 呼び出しは src/api にまとめ、状態管理は src/store に切り出している。

なぜ分けるのか？

業務システム刷新において重要なのは、最初のフォルダ設計。

  • 後から変えるのは大変
    構成を後で変更するとテストの書き直しが必要になり、コストが跳ね上がる。

  • 見やすさ・保守性
    models.py に全部詰め込むと「どこに何があるのか分からない」状態になる。
    モデルを細かくファイル分割することで、見通しが良くなる。

  • チーム開発での共通認識
    「user_dept モデルはどこに置くか？」といった取り決めを最初に決めておかないと、開発者ごとにバラバラになり、レビューや改修で混乱する。

👉 特に今回の例では、

  • 部署やロールは accounts.models
  • 共通のメニューや添付は core.models

といった整理を行い、境界を最初に定義することを徹底した。

なぜ user_dept を accounts 側に置いたのか？

実際の開発で迷うのが「ユーザーと部署の関係（user_dept）はどこに置くべきか？」という問題。

  • dept（部署）は 組織情報 なので core に置くこともできる
  • user（ユーザー）は accounts に置くのが自然
  • では、ユーザーと部署の中間テーブル はどちらに属するのか？

👉 結論として、user_dept は accounts 側に置いた。

理由は以下の通り：

  1. 認証・ユーザー管理に密接に関わるため
    実際の権限判定やログイン後のメニュー制御で最も利用されるのは「ユーザー → 部署」の関係なので、ユーザー管理の一部として捉えるのが自然。

  2. 責務を分けやすい
    部署自体は core にあってもいいが、「誰が所属しているか」 はユーザー管理の一部と位置づけた。

  3. チーム開発での共通認識を保つため
    「部署」そのものは core 側に定義し、
    「ユーザーと部署の関係」は accounts 側に定義する、というルールを明確化した。

AI 活用における注意点

ここで紹介したように、Django 側・Vue 側の構成をきっちり整理しても、
AI はこのフォルダ構成を完璧に覚えてくれるわけではない。

  • AI が「user_dept モデル」を生成するとき、accounts/models/user_dept.py に置くべきなのか、core/models/dept.py に置くべきなのかを勝手に判断してしまう
  • 出力されたコードは正しそうに見えても、自分たちが決めた構成ルールに従っているかどうかを人間がチェックする必要がある
  • 特にチーム開発では、AI の提案をそのまま反映すると、後から見直すときに必ず混乱する

👉 だからこそ、最初に決めたフォルダ構成とルールをチームで共通認識として持ち、AI が出力したコードをその基準で確認する ことが不可欠。

AI はコードを書く速度を飛躍的に上げてくれるが、整合性を担保するのは人間の設計思考 である。

全体まとめ

  • Django 側は「accounts」「core」「業務アプリごと」に分割
  • Vue 側は「views」「components」「api」「store」に整理
  • モデル・ビュー・シリアライザを分けるだけでなく、さらにドメイン単位でファイルを分割することが重要
  • AI 活用時には、このルールに沿って整合性を確認する作業が欠かせない

最初にフォルダ構成をしっかり決めておけば、後からの拡張やチーム開発でも迷いがなくなる。
逆に「全部 models.py / views.py に書いてしまう」のは、短期的には楽でも長期的に必ず負債になる。

Discussion