カテゴリ管理機能仕様書
機能概要
カテゴリ管理機能は、ECサイトで扱う商品カテゴリを階層構造で管理するための管理画面機能です。カテゴリの作成、編集、削除、並び替えなどの操作が可能です。
URL: /admin/categories
ナビゲーション: 商品管理グループ（ソート順: 2）
技術スタック: Filament v4, Livewire v3
画面構成
一覧画面（List Categories）
カテゴリの階層構造をツリー表示し、作成、編集、削除などの操作が可能です。
画面レイアウト
- ツリービュー: カテゴリの階層構造を表示
- ヘッダーアクション: 新規作成ボタン（ルートカテゴリとして作成）
ツリービュー機能
表示形式 - 階層構造をツリー形式で表示 - 親子関係を視覚的に表現 - ドラッグ&ドロップで並び替え可能
各カテゴリ項目の表示内容 - カテゴリ名 - 有効/無効アイコン - 編集ボタン - 削除ボタン
フォーム項目
| 項目名 | フィールド名 | 必須 | 最大文字数 | 説明 |
|---|---|---|---|---|
| カテゴリ名 | name |
✅ | 255 | カテゴリの表示名 |
| スラッグ | slug |
✅ | 255 | URL用スラッグ（ユニーク） |
| ロゴ画像 | logo_image |
- | - | カテゴリロゴ画像（単一） |
| 有効 | is_active |
✅ | - | 有効/無効トグル（デフォルト: true） |
| カテゴリ画像（複数） | image |
- | - | カテゴリ画像（最大10枚） |
| カテゴリ説明 | description |
- | - | リッチエディタ対応の説明文 |
画像アップロード機能
ロゴ画像
- 保存先: public/categories/
- ディスク: public
- 最大サイズ: 2048KB
- プレビュー高さ: 100px
- 単一画像のみ
カテゴリ画像（複数）
- 保存先: public/categories/
- ディスク: public
- 最大ファイル数: 10枚
- 並び替え可能（ドラッグ&ドロップ）
- プレビュー高さ: 100px
- レイアウト: グリッド表示
リッチエディタ機能
カテゴリ説明欄では、以下の機能を持つリッチエディタを使用します。
ツールバーボタン - テキスト装飾: 太字、斜体、下線、取り消し線、上付き、下付き、リンク、コード - 見出し: H1, H2, H3 - 配置: 左揃え、中央揃え、右揃え、両端揃え - リスト: 箇条書き、番号付きリスト、引用、コードブロック - 書式: クリア、ハイライト、文字色、リード、スモール - 詳細: 折りたたみ、水平線、グリッド、グリッド削除 - テーブル: テーブル作成、列追加、行追加、セル結合、セル分割、ヘッダー行切り替え、テーブル削除 - ファイル: ファイル添付、HTML編集 - 操作: 元に戻す、やり直し
ファイル添付
- 保存先: public/categories/
- ディスク: public
最小高さ: 200px
バリデーション
| 項目 | ルール |
|---|---|
| カテゴリ名 | 必須、最大255文字 |
| スラッグ | 必須、最大255文字、ユニーク（categoriesテーブル内） |
| 有効 | 必須 |
特別な確認ダイアログ
有効から無効への変更時 - 条件: 現在の状態が「有効」で、新しい状態が「無効」、かつ商品で使用されている場合、かつ子カテゴリがない場合 - 表示内容: 「このカテゴリは{N}件の商品で使用されています。無効にして良いですか。」 - 確認ボタン: 「保存」
子カテゴリがある場合の無効化 - 条件: 子カテゴリが存在する場合 - 動作: 無効化不可（エラー通知を表示） - エラーメッセージ: 「子カテゴリがある場合は無効化できません。先に子カテゴリを削除または移動してください。」
削除確認ダイアログ
商品で使用されている場合 - 表示内容: - 「このカテゴリには{N}件の商品があります。カテゴリを削除すると、商品からカテゴリが解除されます。」 - 「よろしいですか？」
子孫カテゴリが存在する場合 - 表示内容: - 「このカテゴリと、その下の全てのカテゴリを削除します。」 - 「よろしいですか？」
商品も子孫もない場合 - 表示内容: 「このカテゴリを削除してもよろしいですか？」
削除時の処理
- 子孫カテゴリを全て削除（再帰的）
- カテゴリレコードを削除
- 関連商品のカテゴリ関連付けは解除される（商品本体は削除されない）
注意: 商品本体は削除されません。カテゴリ情報のみが解除されます。
バリデーション
フォームバリデーション
| フィールド | ルール | エラーメッセージ |
|---|---|---|
name |
required, max:255 |
カテゴリ名は必須です / カテゴリ名は255文字以内で入力してください |
slug |
required, max:255, unique:categories,slug,{id} |
スラッグは必須です / スラッグは255文字以内で入力してください / このスラッグは既に使用されています |
is_active |
required |
有効フラグは必須です |
ビジネスロジックバリデーション
有効から無効への変更 - 子カテゴリがある場合は無効化不可 - 商品で使用されているカテゴリを無効化する場合、確認ダイアログを表示 - ユーザーが確認した場合のみ無効化を実行
エラーハンドリング
一般的なエラー
- バリデーションエラー: フォーム内にエラーメッセージを表示
- データベースエラー: エラーログに記録し、ユーザーにエラー通知を表示
- ファイルアップロードエラー: アップロード失敗時はエラーメッセージを表示
削除時のエラー
- 子孫カテゴリの削除: 再帰的に全ての子孫カテゴリを削除
- 削除失敗: エラーログに記録し、ユーザーにエラー通知を表示
技術仕様
使用技術
- Filament v4: 管理画面フレームワーク
- Livewire v3: リアクティブコンポーネント
- Alpine.js: クライアント側インタラクション（Livewireに同梱）
ファイル構成
app/Admin/Resources/
├── CategoryResource.php # メインリソースクラス
└── CategoryResource/
├── Pages/
│ └── ListCategories.php # 一覧ページ
└── Components/
└── CategoryTreeResource.php # ツリービューコンポーネント
app/Models/
└── Category.php # モデルクラス
モデル機能
リレーション
- parent(): belongsTo(Category::class) - 親カテゴリ
- children(): hasMany(Category::class) - 子カテゴリ
- products(): belongsToMany(Product::class) - このカテゴリに属する商品
スコープ
- active(): is_active = true のカテゴリを取得
- root(): 親カテゴリがないカテゴリを取得
階層構造
- parent_id カラムを使用
- 無制限階層構造をサポート
- descendantsOf() メソッドで子孫を取得可能
ファイル保存
画像保存先
- ロゴ画像: storage/app/public/categories/
- カテゴリ画像: storage/app/public/categories/
- リッチエディタ添付ファイル: storage/app/public/categories/
ディスク設定
- 使用ディスク: public
- シンボリックリンク: php artisan storage:link で作成済み
UI/UX仕様
ツリービュー - 階層構造を視覚的に表現 - ドラッグ&ドロップで並び替え可能 - 各カテゴリ項目に編集・削除ボタンを表示
画像プレビュー - 高さ: 100px - グリッドレイアウト（カテゴリ画像複数時）
リッチエディタ - 最小高さ: 200px - 全機能付きツールバー
関連機能
商品管理機能との連携
- 商品作成・編集画面でカテゴリを選択可能
- 選択されたカテゴリの祖先カテゴリも自動的に関連付け
- カテゴリ削除時、関連商品のカテゴリ関連付けは解除される（商品本体は削除されない）
フロントエンド表示
- 有効なカテゴリ（
is_active = true）のみフロントエンドで表示 - 階層構造を維持して表示