# 機能設計書 38-プロジェクトコード管理

## 概要

本ドキュメントは、InvenTreeシステムにおけるプロジェクトコード管理機能の設計を定義する。オーダーや在庫をプロジェクト単位で分類・追跡するためのプロジェクトコードの作成・管理を行う機能を提供する。

### 本機能の処理概要

プロジェクトコード管理機能は、InvenTreeで管理するオーダー（発注、受注、返品）や在庫アイテムを特定のプロジェクトに紐づけて追跡できるようにする。ProjectCodeモデルを通じて、プロジェクトコードの作成・編集・削除および関連データとの紐づけを管理する。

**業務上の目的・背景**：製造業や建設業などでは、複数のプロジェクトを並行して進めることが多い。各プロジェクトに必要な部品や材料を正確に把握し、プロジェクト単位でのコスト管理を行うため、オーダーや在庫をプロジェクトコードで分類する機能が必要。

**機能の利用シーン**：
- 新規プロジェクト開始時のプロジェクトコード登録
- 発注時のプロジェクトコード指定
- プロジェクト別の部品使用状況の確認
- プロジェクト終了時のコード無効化
- プロジェクトコードによる検索・フィルタリング

**主要な処理内容**：
1. プロジェクトコードの作成（コード、説明、責任者）
2. プロジェクトコードの編集・無効化
3. オーダーへのプロジェクトコード紐づけ
4. プロジェクトコードによる検索・フィルタリング
5. プロジェクトコード一覧の管理

**関連システム・外部連携**：
- 発注（PurchaseOrder）
- 受注（SalesOrder）
- 返品（ReturnOrder）
- 製造指示（Build）

**権限による制御**：プロジェクトコードの作成・編集・削除はスタッフ権限が必要。参照は認証済みユーザーが可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 35 | システム設定画面 | 主画面 | プロジェクトコード管理パネル |
| 34 | 管理センター画面 | 参照画面 | グローバル設定パネル |

## 機能種別

CRUD操作 / マスタ管理

## 入力仕様

### プロジェクトコード作成入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| code | str | Yes | プロジェクトコード | 一意性チェック、50文字以内 |
| description | str | No | 説明 | 200文字以内 |
| responsible | int | No | 責任者ユーザーID | 有効なユーザーID |
| metadata | json | No | メタデータ | JSON形式 |

### 入力データソース

- システム設定画面からのフォーム入力
- REST API経由のJSON入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| pk | int | プロジェクトコードID |
| code | str | プロジェクトコード |
| description | str | 説明 |
| responsible | int | 責任者ユーザーID |
| metadata | json | メタデータ |

### 出力先

- REST APIレスポンス（JSON）
- システム設定画面への表示
- データベース（common_projectcode）

## 処理フロー

### 処理シーケンス

```
1. プロジェクトコード作成リクエスト
   └─ 権限チェック（スタッフ権限）
2. バリデーション
   └─ コードの一意性チェック
3. データ保存
   └─ ProjectCodeモデルへの保存
4. レスポンス返却
   └─ 作成されたプロジェクトコード情報
```

### フローチャート

```mermaid
flowchart TD
    A[プロジェクトコード作成リクエスト] --> B{スタッフ権限?}
    B -->|No| C[403エラー]
    B -->|Yes| D{コード一意性チェック}
    D -->|重複| E[400エラー]
    D -->|OK| F[ProjectCode保存]
    F --> G[レスポンス返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-38-01 | コード一意性 | プロジェクトコードはシステム全体で一意 | コード作成・更新時 |
| BR-38-02 | 機能有効化 | PROJECT_CODES_ENABLED設定で機能全体の有効/無効を制御 | 全操作 |
| BR-38-03 | 責任者任意 | 責任者の設定は任意 | コード作成・更新時 |
| BR-38-04 | カスケード参照 | プロジェクトコード削除時は参照先をnullに設定 | 削除時 |

### 計算ロジック

特になし（マスタデータ管理）

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| コード作成 | common_projectcode | INSERT | プロジェクトコード作成 |
| コード更新 | common_projectcode | UPDATE | プロジェクトコード更新 |
| コード削除 | common_projectcode | DELETE | プロジェクトコード削除 |
| コード取得 | common_projectcode | SELECT | プロジェクトコード取得 |

### テーブル別操作詳細

#### common_projectcode

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | code, description, responsible_id, metadata | 入力値 | codeは一意 |
| UPDATE | description, responsible_id, metadata | 入力値 | |
| DELETE | pk | 削除対象ID | 参照先はnull設定 |
| SELECT | - | 各種検索条件 | |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 400 | ValidationError | コードが重複 | 別のコードを使用 |
| 403 | PermissionDenied | スタッフ権限なし | スタッフ権限を付与 |
| 404 | NotFound | コードが存在しない | コードIDを確認 |

### リトライ仕様

特別なリトライ仕様は不要。

## トランザクション仕様

- プロジェクトコードの作成・更新・削除は個別のトランザクションで処理

## パフォーマンス要件

- プロジェクトコード一覧取得：ページネーション対応
- コード検索：コードによるインデックス検索

## セキュリティ考慮事項

- プロジェクトコードの変更はスタッフ権限が必要
- 責任者は有効なユーザーのみ設定可能

## 備考

関連設定:
- PROJECT_CODES_ENABLED: プロジェクトコード機能の有効/無効

プロジェクトコードを参照できるモデル:
- PurchaseOrder（発注）
- SalesOrder（受注）
- ReturnOrder（返品）
- Build（製造指示）

---

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

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

プロジェクトコードモデルの定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | models.py | `src/backend/InvenTree/common/models.py` | ProjectCodeクラスの定義 |

**読解のコツ**:
- codeフィールドは一意（unique=True）
- responsibleはUserモデルへのForeignKey（SET_NULL）
- metadataはInvenTreeMetadataModelを継承

#### Step 2: APIエンドポイントを理解する

プロジェクトコード管理のREST APIを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | api.py | `src/backend/InvenTree/common/api.py` | ProjectCodeList, ProjectCodeDetail |

**主要処理フロー**:
- ProjectCodeList: プロジェクトコード一覧取得・作成
- ProjectCodeDetail: 個別プロジェクトコードの取得・更新・削除

#### Step 3: 関連モデルとの連携を理解する

プロジェクトコードを参照するモデルを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | models.py | `src/backend/InvenTree/order/models.py` | Order基底クラスのproject_codeフィールド |

**主要処理フロー**:
- PurchaseOrder, SalesOrder, ReturnOrderにproject_code ForeignKeyが定義
- on_delete=SET_NULLでプロジェクトコード削除時はnullに設定

### プログラム呼び出し階層図

```
ProjectCodeList API
    │
    ├─ GET: プロジェクトコード一覧取得
    │      └─ フィルタリング・ページネーション
    │
    └─ POST: プロジェクトコード作成
           ├─ 権限チェック
           ├─ バリデーション（一意性チェック）
           └─ ProjectCode.save()

ProjectCodeDetail API
    │
    ├─ GET: プロジェクトコード詳細取得
    │
    ├─ PATCH/PUT: プロジェクトコード更新
    │      └─ バリデーション
    │
    └─ DELETE: プロジェクトコード削除
           └─ 参照先のnull設定はDBレベルで処理
```

### データフロー図

```
[入力]                    [処理]                           [出力]

コード作成要求 ───▶ 権限チェック ───▶ バリデーション
        │                                      │
        │                                      ▼
        │                              一意性チェック
        │                                      │
        │                                      ▼
        │                              ProjectCode保存
        │                                      │
        └──────────────────────────────────────┘
                                               │
                                               ▼
                                        APIレスポンス

オーダー作成 ───▶ project_code指定 ───▶ ForeignKey設定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| models.py | `src/backend/InvenTree/common/models.py` | ソース | ProjectCodeモデル |
| api.py | `src/backend/InvenTree/common/api.py` | ソース | プロジェクトコードAPI |
| serializers.py | `src/backend/InvenTree/common/serializers.py` | ソース | シリアライザ |
| models.py | `src/backend/InvenTree/order/models.py` | ソース | Order基底クラス（参照元） |
