# 画面設計書 13-部品カテゴリ一覧・詳細画面

## 概要

本ドキュメントは、InvenTreeフロントエンドアプリケーションの「部品カテゴリ一覧・詳細画面」に関する設計仕様を記載する。

### 本画面の処理概要

本画面は、部品カテゴリの階層構造を一覧表示し、個別カテゴリの詳細情報を表示・編集するための画面である。カテゴリIDが指定されない場合はトップレベルカテゴリページとして機能する。

**業務上の目的・背景**：在庫管理システムにおいて、部品を論理的なカテゴリ（例：電子部品、機械部品、消耗品等）に分類することで、部品の検索性と管理効率を向上させる。階層構造により、大分類から小分類への段階的な絞り込みが可能となり、数千〜数万点の部品を効率的に管理できる。

**画面へのアクセス方法**：メインナビゲーションの「部品（Parts）」メニューをクリック、またはURL `/part/category/:id?/*` に直接アクセスする。パンくずリストからも階層をたどってアクセス可能。

**主要な操作・処理内容**：
1. カテゴリ一覧の表示（テーブル形式）
2. サブカテゴリの表示と選択
3. カテゴリ内の部品一覧表示（テーブル/パラメトリック表示切替）
4. カテゴリ内の在庫アイテム一覧表示
5. カテゴリパラメータテンプレートの表示・設定
6. カテゴリ情報の編集
7. カテゴリの削除（部品の移動/削除オプション付き）
8. カテゴリのお気に入り登録（スター）

**画面遷移**：
- 遷移元：ホームダッシュボード、他の部品カテゴリ画面
- 遷移先：部品詳細画面、サブカテゴリ画面、在庫アイテム詳細画面

**権限による表示制御**：`part_category`ロールに基づき、表示・編集・削除の可否が制御される。編集ボタンは`hasChangeRole`、削除ボタンは`hasDeleteRole`で制御。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | 部品カテゴリ管理 | 主機能 | 部品カテゴリの一覧表示、編集、削除処理 |
| 2 | 部品マスタ管理 | 遷移先機能 | カテゴリ内部品一覧から部品詳細への遷移 |
| 4 | 部品パラメータ管理 | 補助機能 | カテゴリパラメータテンプレートの表示・設定 |
| 8 | 在庫アイテム管理 | 遷移先機能 | カテゴリ内在庫アイテム一覧の表示・遷移 |

## 画面種別

一覧・詳細（複合）

## URL/ルーティング

`/part/category/:id?/*`

- `:id?` はオプションのカテゴリID
- IDなしの場合はトップレベルカテゴリページ

## 入出力項目

### 入力項目（カテゴリ編集モーダル）

| 項目名 | 項目種別 | データ型 | 必須 | 説明 |
|--------|----------|----------|------|------|
| 名前（Name） | テキスト入力 | 文字列 | ○ | カテゴリ名 |
| 説明（Description） | テキスト入力 | 文字列 | - | カテゴリの説明 |
| 親カテゴリ（Parent） | セレクト | 数値 | - | 親カテゴリのID |
| アイコン（Icon） | アイコン選択 | 文字列 | - | カテゴリアイコン |
| デフォルトロケーション（Default Location） | セレクト | 数値 | - | デフォルトの在庫ロケーション |
| 構造的（Structural） | チェックボックス | 真偽値 | - | 構造的カテゴリフラグ |

### 削除確認モーダル

| 項目名 | 項目種別 | データ型 | 必須 | 説明 |
|--------|----------|----------|------|------|
| 部品アクション（Parts Action） | ラジオ選択 | 文字列 | ○ | 親カテゴリに移動/削除 |
| 子カテゴリアクション（Child Categories Action） | ラジオ選択 | 文字列 | ○ | 親カテゴリに移動/削除 |

## 表示項目

### 詳細パネル（カテゴリ詳細）

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| 名前（Name） | 文字列 | カテゴリ名（アイコン付き） |
| パス（Path） | 文字列 | カテゴリの階層パス |
| 説明（Description） | 文字列 | カテゴリの説明 |
| 親カテゴリ（Parent Category） | リンク | 親カテゴリへのリンク |
| 購読済み（Subscribed） | 真偽値 | お気に入り登録状態 |
| 部品数（Parts） | 数値 | カテゴリ内の部品数 |
| サブカテゴリ数（Subcategories） | 数値 | サブカテゴリの数 |
| 構造的（Structural） | 真偽値 | 構造的カテゴリフラグ |
| 親デフォルトロケーション | リンク | 親カテゴリのデフォルトロケーション |
| デフォルトロケーション（Default Location） | リンク | カテゴリのデフォルトロケーション |

### パネル一覧

| パネル名 | 表示条件 | 内容 |
|---------|----------|------|
| カテゴリ詳細（Category Details） | 常時 | 上記詳細項目 |
| サブカテゴリ（Subcategories/Part Categories） | 常時 | サブカテゴリ一覧テーブル |
| 部品（Parts） | 常時 | 部品一覧（テーブル/パラメトリック切替） |
| 在庫アイテム（Stock Items） | カテゴリID指定時 | 在庫アイテム一覧テーブル |
| カテゴリパラメータ（Category Parameters） | カテゴリID指定時 | パラメータテンプレート一覧 |

## イベント仕様

### 1-カテゴリ選択

サブカテゴリ一覧から行をクリックした時の処理。

**処理フロー**：
1. 選択されたカテゴリのPKを取得
2. `/part/category/{pk}/` に遷移

### 2-カテゴリ編集

アクションメニューの「Edit Part Category」選択時の処理。

**処理フロー**：
1. 編集モーダルを表示
2. `partCategoryFields` で定義されたフォームフィールドを表示
3. 送信時に `PUT /api/part/category/{id}/` を呼び出し
4. 成功後、インスタンスをリフレッシュ

### 3-カテゴリ削除

アクションメニューの「Delete Part Category」選択時の処理。

**処理フロー**：
1. 削除確認モーダルを表示（部品・子カテゴリの処理方法を選択）
2. 送信時に `DELETE /api/part/category/{id}/` を呼び出し
3. 成功後、親カテゴリまたは `/part/` に遷移

### 4-お気に入り切替

スターボタン押下時の処理。

**処理フロー**：
1. `StarredToggleButton` コンポーネントで処理
2. starred状態をトグル
3. インスタンスをリフレッシュ

### 5-部品一覧表示切替

部品パネルのセグメントコントロールでテーブル/パラメトリック切替。

**処理フロー**：
1. ローカルストレージの `category-parts-view` 値を更新
2. 選択に応じて `PartListTable` または `ParametricPartTable` を表示

### 6-ナビゲーションツリー表示

パンくずリストのアクション押下時の処理。

**処理フロー**：
1. `NavigationTree` コンポーネントを表示
2. カテゴリツリーを `/api/part/category/tree/` から取得
3. 選択したカテゴリに遷移

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| カテゴリ編集 | part_partcategory | UPDATE | カテゴリ情報を更新 |
| カテゴリ削除 | part_partcategory | DELETE | カテゴリを削除（関連処理あり） |
| お気に入り切替 | part_partcategorystar | INSERT/DELETE | スター登録/解除 |

### テーブル別更新項目詳細

#### part_partcategory

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | name | フォーム入力値 | カテゴリ名 |
| UPDATE | description | フォーム入力値 | 説明 |
| UPDATE | parent | フォーム選択値 | 親カテゴリID |
| UPDATE | icon | フォーム選択値 | アイコン名 |
| UPDATE | default_location | フォーム選択値 | デフォルトロケーションID |
| UPDATE | structural | フォーム入力値 | 構造的フラグ |
| DELETE | - | pk = 指定値 | カテゴリ削除 |

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|---------------|------|---------------|
| 確認 | カテゴリ削除時 | Delete Part Category（モーダルタイトル） |
| 選択 | 部品アクション | Move items to parent category / Delete items |
| 選択 | 子カテゴリアクション | Move items to parent category / Delete items |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| カテゴリが見つからない | InstanceDetailコンポーネントが404処理 |
| 権限不足 | 編集/削除ボタンが非表示 |
| API通信エラー | エラー通知を表示 |

## 備考

- カテゴリIDが指定されない場合（`/part/`）はトップレベルカテゴリとして動作
- パンくずリストでカテゴリ階層をナビゲート可能
- カテゴリアイコンは `ApiIcon` コンポーネントで表示
- 部品一覧は `PartListTable`（テーブル）と `ParametricPartTable`（パラメトリック）で切替可能

---

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

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

### 推奨読解順序

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

カテゴリデータの構造とAPIレスポンスを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ApiEndpoints.ts | `src/frontend/lib/enums/ApiEndpoints.ts` | category_list, category_tree エンドポイント定義 |
| 1-2 | ModelType.ts | `src/frontend/lib/enums/ModelType.ts` | ModelType.partcategory の定義 |

**読解のコツ**: カテゴリは階層構造を持ち、`path_detail`パラメータで親カテゴリのパス情報を含めて取得できる。

#### Step 2: エントリーポイントを理解する

画面のメインコンポーネントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CategoryDetail.tsx | `src/frontend/src/pages/part/CategoryDetail.tsx` | メイン画面コンポーネント。useInstance, パネル構成を確認 |

**主要処理フロー**:
1. **57-62行**: URLパラメータからカテゴリIDを取得（オプション）
2. **69-80行**: useInstanceでカテゴリデータを取得
3. **82-178行**: detailsPanel定義（カテゴリ詳細表示）
4. **180-186行**: editCategory（編集モーダル）
5. **201-228行**: deleteCategory（削除モーダル）
6. **230-262行**: categoryActions（アクションボタン群）
7. **269-336行**: panels定義（タブパネル構成）
8. **350-394行**: レンダリング部分

#### Step 3: パネルコンポーネントを理解する

各パネルで使用されるテーブルコンポーネントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | PartCategoryTable.tsx | `src/frontend/src/tables/part/PartCategoryTable.tsx` | サブカテゴリ一覧テーブル |
| 3-2 | PartTable.tsx | `src/frontend/src/tables/part/PartTable.tsx` | 部品一覧テーブル |
| 3-3 | ParametricPartTable.tsx | `src/frontend/src/tables/part/ParametricPartTable.tsx` | パラメトリック表示テーブル |
| 3-4 | StockItemTable.tsx | `src/frontend/src/tables/stock/StockItemTable.tsx` | 在庫アイテム一覧テーブル |
| 3-5 | PartCategoryTemplateTable.tsx | `src/frontend/src/tables/part/PartCategoryTemplateTable.tsx` | カテゴリパラメータテンプレート |

#### Step 4: フォームと共通コンポーネントを理解する

フォームフィールド定義と共通コンポーネントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | PartForms.tsx | `src/frontend/src/forms/PartForms.tsx` | partCategoryFields関数 |
| 4-2 | NavigationTree.tsx | `src/frontend/src/components/nav/NavigationTree.tsx` | カテゴリツリーナビゲーション |
| 4-3 | PanelGroup.tsx | `src/frontend/src/components/panels/PanelGroup.tsx` | タブパネルグループ |

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

```
CategoryDetail (CategoryDetail.tsx:57)
    │
    ├─ useParams() - URLからカテゴリID取得
    │
    ├─ useInstance(ApiEndpoints.category_list)
    │      └─ GET /api/part/category/{id}/ - カテゴリ詳細取得
    │
    ├─ useEditApiFormModal (180-186行)
    │      └─ PUT /api/part/category/{id}/ - カテゴリ編集
    │
    ├─ useDeleteApiFormModal (201-228行)
    │      └─ DELETE /api/part/category/{id}/ - カテゴリ削除
    │
    ├─ NavigationTree
    │      └─ GET /api/part/category/tree/ - カテゴリツリー取得
    │
    └─ PanelGroup
           ├─ detailsPanel (カテゴリ詳細)
           │      └─ DetailsTable
           │
           ├─ PartCategoryTable (サブカテゴリ)
           │      └─ InvenTreeTable
           │
           ├─ PartListTable / ParametricPartTable (部品)
           │      └─ InvenTreeTable
           │
           ├─ StockItemTable (在庫アイテム)
           │      └─ InvenTreeTable
           │
           └─ PartCategoryTemplateTable (カテゴリパラメータ)
                  └─ InvenTreeTable
```

### データフロー図

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

URL パラメータ ───▶ CategoryDetail ───▶ 画面表示
(:id)                     │
                          ▼
                   useInstance()
                          │
                          ▼
                   GET /api/part/category/{id}/
                          │
                          ▼
                   Django Backend
                          │
                          ▼
                   part_partcategory テーブル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CategoryDetail.tsx | `src/frontend/src/pages/part/CategoryDetail.tsx` | ソース | 部品カテゴリ画面メインコンポーネント |
| PartCategoryTable.tsx | `src/frontend/src/tables/part/PartCategoryTable.tsx` | ソース | サブカテゴリ一覧テーブル |
| PartTable.tsx | `src/frontend/src/tables/part/PartTable.tsx` | ソース | 部品一覧テーブル |
| ParametricPartTable.tsx | `src/frontend/src/tables/part/ParametricPartTable.tsx` | ソース | パラメトリック部品テーブル |
| StockItemTable.tsx | `src/frontend/src/tables/stock/StockItemTable.tsx` | ソース | 在庫アイテムテーブル |
| PartCategoryTemplateTable.tsx | `src/frontend/src/tables/part/PartCategoryTemplateTable.tsx` | ソース | カテゴリパラメータテンプレートテーブル |
| PartForms.tsx | `src/frontend/src/forms/PartForms.tsx` | ソース | 部品関連フォームフィールド定義 |
| NavigationTree.tsx | `src/frontend/src/components/nav/NavigationTree.tsx` | ソース | ナビゲーションツリーコンポーネント |
| PanelGroup.tsx | `src/frontend/src/components/panels/PanelGroup.tsx` | ソース | タブパネルグループコンポーネント |
| SegmentedControlPanel.tsx | `src/frontend/src/components/panels/SegmentedControlPanel.tsx` | ソース | セグメント切替パネル |
| ApiIcon.tsx | `src/frontend/src/components/items/ApiIcon.tsx` | ソース | APIアイコン表示コンポーネント |
| StarredToggleButton.tsx | `src/frontend/src/components/buttons/StarredToggleButton.tsx` | ソース | スター切替ボタン |
