# InvenTree コードリーディングガイドライン

## はじめに

このガイドラインは、InvenTreeのコードベースを効率的に理解するための手引きです。
PythonやTypeScript/Reactに精通していないエンジニアでも、段階的に学習できるよう構成されています。

**対象読者:**
- プロジェクトに新規参画するエンジニア
- 他言語からの経験者
- コードレビューを行う担当者

---

## 1. 言語基礎

> このセクションでは、InvenTreeで使用されている言語の基本構文と概念を解説します。

### 1.1 使用言語・技術スタック

InvenTreeは2つの主要な技術スタックで構成されています:

**バックエンド (Python/Django):**
- Python 3.11+
- Django 5.x
- Django REST Framework (DRF)
- Django Q2 (バックグラウンドタスク)
- Django Allauth (認証)

**フロントエンド (TypeScript/React):**
- TypeScript
- React 19
- Mantine UI (コンポーネントライブラリ)
- TanStack Query (データフェッチング)
- Zustand (状態管理)
- React Router (ルーティング)

### 1.2 Pythonプログラム構造 (バックエンド)

Djangoアプリケーションの基本的なファイル構造:

```python
# ファイル: src/backend/InvenTree/part/models.py:1-10
"""Part database model definitions."""

from __future__ import annotations

import decimal
import hashlib
from django.db import models
from django.utils.translation import gettext_lazy as _
```

**特徴:**
- `from __future__ import annotations`: 型アノテーションの遅延評価を有効化
- `gettext_lazy as _`: 国際化対応のための遅延翻訳関数

### 1.3 TypeScript/Reactプログラム構造 (フロントエンド)

Reactコンポーネントの基本的なファイル構造:

```typescript
// ファイル: src/frontend/src/pages/part/PartDetail.tsx:1-15
import { t } from '@lingui/core/macro';
import {
  ActionIcon,
  Alert,
  Center,
  Grid,
} from '@mantine/core';
import { useQuery } from '@tanstack/react-query';
import { useMemo, useState } from 'react';
import { useNavigate, useParams } from 'react-router-dom';
```

**特徴:**
- `@lingui/core/macro`: 国際化マクロ (翻訳)
- `@mantine/core`: UIコンポーネントライブラリ
- `@tanstack/react-query`: サーバーステート管理
- `react-router-dom`: ルーティング

### 1.4 データ型と変数

**Python (バックエンド):**
```python
# ファイル: src/backend/InvenTree/part/models.py:71-84
class PartCategory(
    InvenTree.models.PluginValidationMixin,
    InvenTree.models.MetadataMixin,
    InvenTree.models.PathStringMixin,
    InvenTree.models.InvenTreeTree,
):
    """PartCategory provides hierarchical organization of Part objects.

    Attributes:
        name: Name of this category
        parent: Parent category
        default_location: Default storage location for parts
    """
```

**TypeScript (フロントエンド):**
```typescript
// ファイル: src/frontend/src/hooks/UseInstance.tsx:13-20
export interface UseInstanceResult {
  instance: any;
  setInstance: (instance: any) => void;
  refreshInstance: () => void;
  refreshInstancePromise: () => Promise<QueryObserverResult<any, any>>;
  instanceQuery: UseQueryResult;
  isLoaded: boolean;
}
```

### 1.5 関数/メソッド定義

**Python (DRF APIビュー):**
```python
# ファイル: src/backend/InvenTree/part/api.py:66-77
class CategoryMixin:
    """Mixin class for PartCategory endpoints."""

    serializer_class = part_serializers.CategorySerializer
    queryset = PartCategory.objects.all()

    def get_queryset(self, *args, **kwargs):
        """Return an annotated queryset for the CategoryDetail endpoint."""
        queryset = super().get_queryset(*args, **kwargs)
        queryset = part_serializers.CategorySerializer.annotate_queryset(queryset)
        return queryset
```

**TypeScript (Reactフック):**
```typescript
// ファイル: src/frontend/src/hooks/UseInstance.tsx:32-54
export function useInstance<T = any>({
  endpoint,
  pk,
  params = {},
  defaultValue = {},
  pathParams,
  disabled,
  hasPrimaryKey = true,
}: {
  endpoint: ApiEndpoints;
  pk?: string | number | undefined;
  hasPrimaryKey?: boolean;
  params?: any;
  pathParams?: PathParams;
  disabled?: boolean;
  defaultValue?: any;
}): UseInstanceResult {
  // ...実装
}
```

### 1.6 モジュール/インポート

**Python:**
```python
# ファイル: src/backend/InvenTree/InvenTree/urls.py:19-33
import build.api
import common.api
import company.api
import importer.api
import machine.api
import order.api
import part.api
import plugin.api
import report.api
import stock.api
import users.api
from plugin.urls import get_plugin_urls
from web.urls import cui_compatibility_urls
from web.urls import urlpatterns as platform_urls
```

**TypeScript:**
```typescript
// ファイル: src/frontend/src/pages/part/PartDetail.tsx:44-50
import { ApiEndpoints } from '@lib/enums/ApiEndpoints';
import { ModelType } from '@lib/enums/ModelType';
import { UserRoles } from '@lib/enums/Roles';
import { apiUrl } from '@lib/functions/Api';
import { getDetailUrl } from '@lib/functions/Navigation';
```

---

## 2. プロジェクト固有の概念

> このセクションでは、InvenTree特有の概念を解説します。

### 2.1 Djangoフレームワーク固有の概念

#### Models (モデル)
データベーステーブルを定義するクラス。MPTTを使用した階層構造をサポート。

```python
# ファイル: src/backend/InvenTree/stock/models.py:121-129
class StockLocation(
    InvenTree.models.PluginValidationMixin,
    InvenTree.models.InvenTreeParameterMixin,
    InvenTree.models.InvenTreeBarcodeMixin,
    report.mixins.InvenTreeReportMixin,
    InvenTree.models.PathStringMixin,
    InvenTree.models.MetadataMixin,
    InvenTree.models.InvenTreeTree,
):
```

#### Serializers (シリアライザ)
モデルデータをJSON形式に変換/検証するクラス。

#### Views/APIViews (ビュー)
HTTPリクエストを処理するクラス。DRFのGenericAPIViewを継承。

```python
# ファイル: src/backend/InvenTree/InvenTree/mixins.py:132-150
class ListAPI(generics.ListAPIView):
    """View for list API."""

class ListCreateAPI(CleanMixin, generics.ListCreateAPIView):
    """View for list and create API."""

class RetrieveUpdateAPI(CleanMixin, generics.RetrieveUpdateAPIView):
    """View for retrieve and update API."""
```

### 2.2 Reactフレームワーク固有の概念

#### カスタムフック
状態管理とAPI通信のロジックをカプセル化:

```typescript
// ファイル: src/frontend/src/hooks/UseInstance.tsx:59-116
const instanceQuery = useQuery<T>({
  enabled: !disabled,
  queryKey: [
    'instance',
    endpoint,
    pk,
    JSON.stringify(params),
  ],
  queryFn: async () => {
    const url = apiUrl(endpoint, pk, pathParams);
    return api.get(url, { params }).then((response) => {
      setInstance(response.data);
      return response.data;
    });
  },
});
```

#### Zustand状態管理
グローバルステートの管理:

```typescript
// ファイル: src/frontend/src/states/UserState.tsx:14-40
export const useUserState = create<UserStateProps>((set, get) => ({
  user: undefined,
  is_authed: false,
  setAuthenticated: (authed = true) => {
    set({ is_authed: authed });
    setApiDefaults();
  },
  userId: () => {
    const user: UserProps = get().user as UserProps;
    return user?.pk;
  },
  // ...
}));
```

### 2.3 プロジェクト独自のパターン

#### InvenTreeモデルMixin
再利用可能な機能をMixinとして提供:

- `PluginValidationMixin`: プラグインによるバリデーション
- `MetadataMixin`: メタデータ機能
- `PathStringMixin`: パス文字列生成
- `InvenTreeTree`: MPTT階層構造
- `InvenTreeBarcodeMixin`: バーコード機能

#### APIエンドポイント列挙型
フロントエンドでAPIエンドポイントを一元管理:

```typescript
// ファイル: src/frontend/lib/enums/ApiEndpoints.tsx:9-60
export enum ApiEndpoints {
  api_server_info = '',
  user_list = 'user/',
  user_me = 'user/me/',
  // ...
  part_list = 'part/',
  stock_item_list = 'stock/',
}
```

---

## 3. 命名規則

> このセクションでは、プロジェクト全体で使用される命名規則を解説します。

### 3.1 ファイル・ディレクトリ命名

| パターン | 意味 | 例 |
|---------|------|-----|
| `models.py` | Djangoモデル定義 | `part/models.py` |
| `api.py` | REST APIエンドポイント定義 | `part/api.py` |
| `serializers.py` | DRFシリアライザ定義 | `part/serializers.py` |
| `*Detail.tsx` | 詳細ページコンポーネント | `PartDetail.tsx` |
| `*Index.tsx` | 一覧ページコンポーネント | `BuildIndex.tsx` |
| `Use*.tsx` | カスタムフック | `UseInstance.tsx` |
| `*State.tsx` | Zustand状態ストア | `UserState.tsx` |
| `*Table.tsx` | テーブルコンポーネント | `StockItemTable.tsx` |

### 3.2 クラス・関数・変数命名

| プレフィックス/サフィックス | 意味 | 例 |
|---------------------------|------|-----|
| `*Mixin` | 再利用可能な機能クラス | `CategoryMixin` |
| `*Serializer` | DRFシリアライザ | `CategorySerializer` |
| `*Filter` / `*FilterSet` | DRFフィルタセット | `CategoryFilter` |
| `*View` | APIビュークラス | `BarcodeView` |
| `use*` | Reactカスタムフック | `useInstance` |
| `*Props` | React Props型定義 | `UserStateProps` |
| `handle*` | イベントハンドラ | `handleSubmit` |
| `is*` / `has*` | ブール値チェック | `isLoaded`, `hasPermission` |
| `get*` | データ取得関数 | `getDetailUrl` |
| `set*` | データ設定関数 | `setInstance` |

### 3.3 APIエンドポイント命名規則

| パターン | 意味 | 例 |
|---------|------|-----|
| `*_list` | 一覧取得 | `part_list`, `stock_item_list` |
| `*_detail` | 詳細取得 | `part/:id/` |
| `*_create` | 新規作成 | `build_output_create` |
| `*_delete` | 削除 | `build_output_delete` |

---

## 4. ディレクトリ構造

> このセクションでは、プロジェクトのディレクトリ構造を解説します。

```
InvenTree-master/
├── src/
│   ├── backend/                    # Djangoバックエンド
│   │   └── InvenTree/
│   │       ├── InvenTree/          # プロジェクト設定
│   │       │   ├── settings.py     # Django設定
│   │       │   ├── urls.py         # URLルーティング
│   │       │   ├── api.py          # 共通API
│   │       │   └── mixins.py       # 共通Mixin
│   │       ├── part/               # 部品管理アプリ
│   │       ├── stock/              # 在庫管理アプリ
│   │       ├── build/              # 製造管理アプリ
│   │       ├── order/              # 注文管理アプリ
│   │       ├── company/            # 企業管理アプリ
│   │       ├── users/              # ユーザー管理アプリ
│   │       ├── plugin/             # プラグインシステム
│   │       ├── report/             # レポート機能
│   │       └── common/             # 共通機能
│   │
│   └── frontend/                   # Reactフロントエンド
│       ├── src/
│       │   ├── main.tsx            # エントリーポイント
│       │   ├── App.tsx             # Axiosインスタンス設定
│       │   ├── router.tsx          # ルーティング定義
│       │   ├── components/         # 再利用可能コンポーネント
│       │   ├── pages/              # ページコンポーネント
│       │   ├── hooks/              # カスタムフック
│       │   ├── states/             # Zustand状態管理
│       │   ├── tables/             # テーブルコンポーネント
│       │   ├── forms/              # フォームコンポーネント
│       │   ├── contexts/           # Reactコンテキスト
│       │   └── functions/          # ユーティリティ関数
│       └── lib/                    # 共有ライブラリ
│           ├── enums/              # 列挙型定義
│           ├── types/              # 型定義
│           └── functions/          # 共通関数
│
├── docs/                           # ドキュメント
├── contrib/                        # 貢献者向けリソース
└── config/                         # 設定ファイル
```

### 各ディレクトリの役割

| ディレクトリ | 役割 | 主要ファイル |
|-------------|------|-------------|
| `src/backend/InvenTree/InvenTree/` | Django設定・共通機能 | `settings.py`, `urls.py`, `api.py` |
| `src/backend/InvenTree/part/` | 部品・カテゴリ管理 | `models.py`, `api.py`, `serializers.py` |
| `src/backend/InvenTree/stock/` | 在庫・ロケーション管理 | `models.py`, `api.py` |
| `src/backend/InvenTree/build/` | 製造オーダー管理 | `models.py`, `api.py` |
| `src/backend/InvenTree/order/` | 購買・販売注文管理 | `models.py`, `api.py` |
| `src/backend/InvenTree/plugin/` | プラグインシステム | `plugin.py`, `registry.py` |
| `src/frontend/src/pages/` | ページコンポーネント | `PartDetail.tsx`, `StockDetail.tsx` |
| `src/frontend/src/components/` | 再利用可能UI | `InvenTreeTable.tsx`, `Panel.tsx` |
| `src/frontend/src/hooks/` | カスタムフック | `UseInstance.tsx`, `UseForm.tsx` |
| `src/frontend/src/states/` | 状態管理 | `UserState.tsx`, `SettingsStates.tsx` |
| `src/frontend/lib/enums/` | 共通列挙型 | `ApiEndpoints.tsx`, `ModelType.tsx` |

---

## 5. アーキテクチャ

> このセクションでは、プロジェクトのアーキテクチャパターンを解説します。

### 5.1 全体アーキテクチャ

InvenTreeは**フルスタックWebアプリケーション**として、バックエンドとフロントエンドが分離したアーキテクチャを採用しています。

```
                                    ┌─────────────────────────────────────┐
                                    │         フロントエンド (React)        │
                                    │                                     │
                                    │  ┌─────────┐  ┌─────────┐          │
                                    │  │  Pages  │  │Components│          │
                                    │  └────┬────┘  └────┬────┘          │
                                    │       │           │                │
                                    │  ┌────┴───────────┴────┐           │
                                    │  │   Hooks / States    │           │
                                    │  └──────────┬──────────┘           │
                                    └─────────────┼───────────────────────┘
                                                  │ HTTP/REST API
                                    ┌─────────────┼───────────────────────┐
                                    │         バックエンド (Django)         │
                                    │             │                       │
                                    │  ┌──────────┴──────────┐           │
                                    │  │   REST API Layer    │           │
                                    │  │  (Views/Serializers) │           │
                                    │  └──────────┬──────────┘           │
                                    │             │                       │
                                    │  ┌──────────┴──────────┐           │
                                    │  │   Business Logic    │           │
                                    │  │      (Models)       │           │
                                    │  └──────────┬──────────┘           │
                                    │             │                       │
                                    │  ┌──────────┴──────────┐           │
                                    │  │     Database        │           │
                                    │  │ (PostgreSQL/MySQL)  │           │
                                    │  └─────────────────────┘           │
                                    │                                     │
                                    │  ┌─────────────────────┐           │
                                    │  │   Plugin System     │           │
                                    │  └─────────────────────┘           │
                                    └─────────────────────────────────────┘
```

### 5.2 レイヤー構成

| レイヤー | 責務 | 代表的なファイル |
|---------|------|-----------------|
| **Presentation (フロントエンド)** | UI表示、ユーザー操作 | `pages/*.tsx`, `components/*.tsx` |
| **State Management** | クライアント状態管理 | `states/*.tsx`, `hooks/*.tsx` |
| **API Layer** | REST API定義 | `*/api.py`, `*/serializers.py` |
| **Business Logic** | ビジネスロジック | `*/models.py` |
| **Data Access** | データベースアクセス | Django ORM |
| **Plugin System** | 拡張機能 | `plugin/*.py` |

### 5.3 データフロー

#### 読み取りフロー (Read)
1. ユーザーがページにアクセス
2. `useInstance`フックがTanStack Queryを使用してAPIリクエスト
3. Django REST APIがリクエストを受信
4. シリアライザがモデルデータを変換
5. JSONレスポンスを返却
6. フロントエンドが状態を更新しUIを再描画

#### 書き込みフロー (Write)
1. ユーザーがフォームを送信
2. `useApiFormModal`フックがPOST/PATCHリクエストを送信
3. Django REST APIがリクエストを検証
4. シリアライザがデータをバリデーション
5. モデルがデータベースに保存
6. 成功レスポンスを返却
7. TanStack Queryがキャッシュを無効化し再取得

---

## 6. 主要コンポーネント

> このセクションでは、主要なコンポーネントとその連携を解説します。

### 6.1 エントリーポイント

**バックエンド:**
```python
# ファイル: src/backend/InvenTree/manage.py
# Django管理コマンドのエントリーポイント
```

```python
# ファイル: src/backend/InvenTree/InvenTree/urls.py:52-86
apipatterns = [
    path('admin/', include(common.api.admin_api_urls)),
    path('bom/', include(part.api.bom_api_urls)),
    path('build/', include(build.api.build_api_urls)),
    path('company/', include(company.api.company_api_urls)),
    path('part/', include(part.api.part_api_urls)),
    path('stock/', include(stock.api.stock_api_urls)),
    # ...
]
```

**フロントエンド:**
```typescript
// ファイル: src/frontend/src/main.tsx:124-130
ReactDOMClient.createRoot(
  document.getElementById('root') as HTMLElement
).render(
  <React.StrictMode>
    <MainView />
  </React.StrictMode>
);
```

### 6.2 ビジネスロジック (モデル層)

Djangoモデルがビジネスロジックの中心:

```python
# ファイル: src/backend/InvenTree/part/models.py:71-84
class PartCategory(
    InvenTree.models.PluginValidationMixin,
    InvenTree.models.MetadataMixin,
    InvenTree.models.PathStringMixin,
    InvenTree.models.InvenTreeTree,
):
    """PartCategory provides hierarchical organization of Part objects."""

    ITEM_PARENT_KEY = 'category'
    EXTRA_PATH_FIELDS = ['icon']
```

### 6.3 データアクセス (API層)

DRF ViewとSerializerの組み合わせ:

```python
# ファイル: src/backend/InvenTree/part/api.py:66-77
class CategoryMixin:
    """Mixin class for PartCategory endpoints."""

    serializer_class = part_serializers.CategorySerializer
    queryset = PartCategory.objects.all()
```

### 6.4 フロントエンドコンポーネント

**ページコンポーネント:**
```typescript
// ファイル: src/frontend/src/pages/part/PartDetail.tsx:114-150
function RevisionSelector({
  part,
  options
}: {
  part: any;
  options: any[];
}) {
  const navigate = useNavigate();
  // UI実装
}
```

**テーブルコンポーネント:**
```typescript
// ファイル: src/frontend/src/tables/InvenTreeTable.tsx:65-77
export function InvenTreeTable<T extends Record<string, any>>({
  url,
  tableState,
  tableData,
  columns,
  props
}: Readonly<{
  url?: string;
  tableState: TableState;
  tableData?: any[];
  columns: TableColumn<T>[];
  props: InvenTreeTableProps<T>;
}>) {
```

### 6.5 ユーティリティ/共通機能

**状態管理 (Zustand):**
```typescript
// ファイル: src/frontend/src/states/UserState.tsx:14-40
export const useUserState = create<UserStateProps>((set, get) => ({
  user: undefined,
  is_authed: false,
  // ...メソッド定義
}));
```

**カスタムフック:**
```typescript
// ファイル: src/frontend/src/hooks/UseInstance.tsx:32-54
export function useInstance<T = any>({
  endpoint,
  pk,
  params = {},
}: {
  endpoint: ApiEndpoints;
  pk?: string | number | undefined;
}): UseInstanceResult {
  // API通信ロジック
}
```

---

## 7. よく使われるパターン

> このセクションでは、コード内で頻出するパターンを解説します。

### パターン一覧

| パターン | 説明 | 出現頻度 | 代表的なファイル |
|---------|------|---------|-----------------|
| Mixin継承 | 機能の再利用 | 高 | `models.py` |
| DRF ViewSet | REST API実装 | 高 | `api.py` |
| カスタムフック | ロジックのカプセル化 | 高 | `hooks/*.tsx` |
| Zustand Store | グローバル状態管理 | 中 | `states/*.tsx` |
| TanStack Query | サーバーステート管理 | 高 | `hooks/*.tsx` |
| 列挙型定義 | 定数の型安全管理 | 高 | `lib/enums/*.tsx` |

### 各パターンの詳細

#### パターン1: Django Mixin継承

**目的:** 複数のモデルで共通の機能を再利用

**実装例:**
```python
// ファイル: src/backend/InvenTree/stock/models.py:121-129
class StockLocation(
    InvenTree.models.PluginValidationMixin,      # プラグインバリデーション
    InvenTree.models.InvenTreeParameterMixin,    # パラメータ機能
    InvenTree.models.InvenTreeBarcodeMixin,      # バーコード機能
    report.mixins.InvenTreeReportMixin,          # レポート機能
    InvenTree.models.PathStringMixin,            # パス文字列
    InvenTree.models.MetadataMixin,              # メタデータ
    InvenTree.models.InvenTreeTree,              # 階層構造(MPTT)
):
```

**解説:** 各Mixinは特定の機能を提供し、モデルクラスに多重継承されます。

#### パターン2: TanStack Query + カスタムフック

**目的:** API通信とキャッシュ管理のカプセル化

**実装例:**
```typescript
// ファイル: src/frontend/src/hooks/UseInstance.tsx:59-75
const instanceQuery = useQuery<T>({
  enabled: !disabled,
  queryKey: ['instance', endpoint, pk],
  queryFn: async () => {
    const url = apiUrl(endpoint, pk, pathParams);
    return api.get(url, { params }).then((response) => {
      setInstance(response.data);
      return response.data;
    });
  },
});
```

**解説:** `queryKey`でキャッシュを一意に識別し、`queryFn`でデータ取得を実行します。

#### パターン3: Zustand状態管理

**目的:** グローバル状態の管理と永続化

**実装例:**
```typescript
// ファイル: src/frontend/src/states/UserState.tsx:14-40
export const useUserState = create<UserStateProps>((set, get) => ({
  user: undefined,
  setUser: (newUser) => set({ user: newUser }),
  getUser: () => get().user,
  checkUserRole: (role, permission) => {
    const user = get().user;
    return user?.roles[role]?.includes(permission) ?? false;
  },
}));
```

**解説:** `create`で状態ストアを作成し、`set`で状態更新、`get`で現在の状態を取得します。

---

## 8. 業務フロー追跡の実践例

> このセクションでは、実際の業務フローをコードで追跡する方法を解説します。

### 8.1 フロー追跡の基本手順

1. エントリーポイントを特定
2. 処理の流れを追跡（呼び出し関係を追う）
3. データの変換を確認
4. 最終的な出力を確認

### 8.2 フロー追跡の実例

#### 例1: 部品詳細ページの表示

**概要:** ユーザーが部品詳細ページにアクセスした際のデータ取得フロー

**処理フロー:**
```
router.tsx → PartDetail.tsx → useInstance → API Request → part/api.py → part/models.py → Database
```

**詳細な追跡:**

1. **ルーティング定義** (`src/frontend/src/router.tsx:166`)
   ```typescript
   <Route path=':id/*' element={<PartDetail />} />
   ```

2. **ページコンポーネント初期化** (`src/frontend/src/pages/part/PartDetail.tsx:90`)
   ```typescript
   import { useInstance } from '../../hooks/UseInstance';
   // URLパラメータからIDを取得
   const { id } = useParams();
   ```

3. **データ取得フック呼び出し** (`src/frontend/src/hooks/UseInstance.tsx:59-75`)
   ```typescript
   const instanceQuery = useQuery<T>({
     queryKey: ['instance', endpoint, pk],
     queryFn: async () => {
       const url = apiUrl(endpoint, pk);
       return api.get(url).then((response) => response.data);
     },
   });
   ```

4. **API処理 (バックエンド)** (`src/backend/InvenTree/part/api.py`)
   ```python
   class CategoryMixin:
       serializer_class = part_serializers.CategorySerializer
       queryset = PartCategory.objects.all()
   ```

5. **モデルからデータ取得** (`src/backend/InvenTree/part/models.py`)
   ```python
   # Django ORMがデータベースクエリを実行
   ```

### 8.3 フロー追跡チェックリスト

- [ ] エントリーポイントを特定したか
- [ ] ルーティング設定を確認したか
- [ ] コンポーネントの依存関係を把握したか
- [ ] カスタムフックの動作を理解したか
- [ ] API呼び出し先を特定したか
- [ ] シリアライザの変換処理を確認したか
- [ ] モデルのビジネスロジックを確認したか
- [ ] エラーハンドリングを確認したか

---

## 9. 設計書の参照順序

> このセクションでは、プロジェクト理解のための設計書参照順序を案内します。

### 9.1 目的別ロードマップ

#### 全体像を把握したい場合
1. `README.md` - プロジェクト概要
2. `src/backend/InvenTree/InvenTree/urls.py` - APIエンドポイント一覧
3. `src/frontend/src/router.tsx` - フロントエンドルーティング
4. 各アプリの`models.py` - データモデル理解

#### 特定機能を理解したい場合
1. 該当機能の`models.py` - データ構造
2. 該当機能の`api.py` - APIエンドポイント
3. 該当機能の`serializers.py` - データ変換
4. 関連するフロントエンドページコンポーネント

#### フロントエンド改修を行う場合
1. `src/frontend/src/router.tsx` - ルーティング確認
2. 該当ページの`*Detail.tsx`または`*Index.tsx`
3. 関連する`hooks/*.tsx` - カスタムフック
4. `src/frontend/lib/enums/ApiEndpoints.tsx` - APIエンドポイント

#### バックエンド改修を行う場合
1. 該当アプリの`models.py` - モデル定義
2. 該当アプリの`serializers.py` - シリアライザ
3. 該当アプリの`api.py` - APIビュー
4. `src/backend/InvenTree/InvenTree/urls.py` - URL登録確認

### 9.2 ドキュメント一覧

| ドキュメント | 概要 | 参照タイミング |
|-------------|------|---------------|
| `README.md` | プロジェクト概要、セットアップ手順 | 初回参照 |
| `CONTRIBUTING.md` | 貢献ガイドライン | 開発開始時 |
| `SECURITY.md` | セキュリティポリシー | セキュリティ関連作業時 |
| `pyproject.toml` | Pythonプロジェクト設定 | 依存関係確認時 |
| `package.json` | フロントエンド依存関係 | フロントエンド作業時 |

---

## 10. トラブルシューティング

> このセクションでは、コードリーディング時によくある問題と解決法を解説します。

### よくある疑問と回答

#### Q: APIエンドポイントがどこで定義されているか分からない
A:
1. バックエンド: `src/backend/InvenTree/InvenTree/urls.py`でapipatterns配列を確認
2. フロントエンド: `src/frontend/lib/enums/ApiEndpoints.tsx`で列挙型を確認

#### Q: モデル間のリレーションが分からない
A: 各モデルの`ForeignKey`や`TreeForeignKey`を確認。MPTTを使用している階層モデルは`InvenTreeTree`を継承しています。

#### Q: フロントエンドの状態管理が分からない
A:
- グローバル状態: `src/frontend/src/states/`のZustandストア
- サーバーステート: TanStack Queryを使用したカスタムフック (`hooks/*.tsx`)
- ローカル状態: コンポーネント内の`useState`

#### Q: プラグインシステムの仕組みが分からない
A: `src/backend/InvenTree/plugin/`ディレクトリを参照。`plugin.py`がベースクラス、`registry.py`がプラグイン管理を担当。

### デバッグのヒント

**バックエンド:**
- Django Debug Toolbar (開発モード)
- `structlog`によるログ出力
- DRF Browsable API (`/api/`にブラウザでアクセス)

**フロントエンド:**
- React DevTools
- TanStack Query DevTools
- ブラウザの開発者ツール (Network タブ)

---

## 付録

### A. 用語集

| 用語 | 説明 |
|-----|------|
| Part | 部品/パーツ |
| StockItem | 在庫アイテム |
| StockLocation | 在庫ロケーション/保管場所 |
| BOM (Bill of Materials) | 部品表 |
| Build Order | 製造オーダー |
| Purchase Order | 購買注文 |
| Sales Order | 販売注文 |
| Supplier Part | サプライヤー部品 |
| Manufacturer Part | メーカー部品 |
| MPTT | Modified Preorder Tree Traversal (階層データ管理) |
| DRF | Django REST Framework |
| TanStack Query | サーバーステート管理ライブラリ (旧React Query) |
| Zustand | 軽量な状態管理ライブラリ |
| Mantine | React UIコンポーネントライブラリ |

### B. 主要ファイル一覧

| ファイル/ディレクトリ | 説明 | 主な内容 |
|---------------------|------|---------|
| `src/backend/InvenTree/InvenTree/settings.py` | Django設定 | データベース、認証、ログ設定 |
| `src/backend/InvenTree/InvenTree/urls.py` | URLルーティング | APIエンドポイント定義 |
| `src/backend/InvenTree/part/models.py` | 部品モデル | Part, PartCategory定義 |
| `src/backend/InvenTree/stock/models.py` | 在庫モデル | StockItem, StockLocation定義 |
| `src/frontend/src/main.tsx` | フロントエンドエントリー | アプリケーション初期化 |
| `src/frontend/src/router.tsx` | ルーティング | ページコンポーネントマッピング |
| `src/frontend/src/states/UserState.tsx` | ユーザー状態 | 認証・権限管理 |
| `src/frontend/lib/enums/ApiEndpoints.tsx` | APIエンドポイント | 全APIエンドポイント列挙 |

### C. 参考資料

- [Django公式ドキュメント](https://docs.djangoproject.com/)
- [Django REST Framework公式ドキュメント](https://www.django-rest-framework.org/)
- [React公式ドキュメント](https://react.dev/)
- [TanStack Query公式ドキュメント](https://tanstack.com/query/)
- [Zustand公式ドキュメント](https://github.com/pmndrs/zustand)
- [Mantine公式ドキュメント](https://mantine.dev/)
- [InvenTree公式ドキュメント](https://docs.inventree.org/)
