コンテンツにスキップ
sounya docs

管理画面 — マスタデータ管理仕様 (FR-013)

項目内容
対象FRFR-013（管理画面 — マスタデータ管理）
優先度低
ステータス詳細化済み
フェーズPhase 6

概要

運用担当者は管理画面からマスタデータ（品種・ワクチン種類・症状カテゴリ・フード種類）の一覧表示・追加・編集・論理削除を行える。各マスタデータにはシードデータ（プリセット）を用意し、初期セットアップ時に投入する。論理削除により、使用中のマスタデータを参照整合性を保ちつつ非表示化できる。

管理対象マスタデータ

マスタテーブル用途利用FR
品種cat_breedsペット登録時の品種選択FR-003
ワクチン種類vaccine_typesワクチン記録時の種類選択FR-007
症状カテゴリsymptom_categories体調ログ記録時の症状分類FR-008
フード種類food_types食事記録時のフード選択FR-005

シードデータ

品種（cat_breeds）

アイウエオ順で提供する。

name
アビシニアン
アメリカンカール
アメリカンショートヘア
エキゾチックショートヘア
オシキャット
サイベリアン
シャム
シャルトリュー
シンガプーラ
スコティッシュフォールド
スフィンクス
セルカークレックス
ソマリ
ターキッシュアンゴラ
ノルウェージャンフォレストキャット
バーマン
バーミーズ
ヒマラヤン
ブリティッシュショートヘア
ペルシャ
ベンガル
ボンベイ
マンチカン
メインクーン
ラガマフィン
ラグドール
ロシアンブルー
日本猫（和猫）
雑種（ミックス）

ワクチン種類（vaccine_types）

name
3種混合（FVRCP）
4種混合（FVRCP + FeLV）
5種混合（FVRCP + FeLV + Chlamydia）
猫白血病ウイルス（FeLV）単体
狂犬病

症状カテゴリ（symptom_categories）

name
嘔吐
下痢
便秘
食欲不振
くしゃみ
咳
鼻水
目やに
皮膚の異常
脱毛
元気がない
体重減少
過剰な毛づくろい
排尿の異常

フード種類（food_types）

name
ドライフード
ウェットフード（缶詰）
ウェットフード（パウチ）
セミモイストフード
おやつ・トリーツ
サプリメント
療法食
手作り食
ちゅーる系

論理削除

削除方針

マスタデータは論理削除を採用する。既存の健康記録がマスタデータを参照している場合でも、参照整合性を維持しつつマスタを非表示化できる。

操作動作
削除deleted_at に現在日時を設定
復元deleted_at を null に更新

ユーザー向けAPI（既存）での表示

  • マスタ一覧API（GET /api/cat-breeds 等）は deleted_at IS NULL のレコードのみ返す
  • 既に削除済みマスタを参照している健康記録は、そのまま表示される（マスタの name は記録に保持されるため）

DBテーブル変更

全マスタテーブル共通の追加カラム

カラム型備考
deleted_attimestamptz論理削除日時（nullable）
display_orderinteger表示順（nullable、null の場合は name 順）

対象テーブル: cat_breeds, vaccine_types, symptom_categories

food_types（新規）

カラム型備考
idserial主キー
namevarcharフード種類名（一意制約）
display_orderinteger表示順（nullable）
deleted_attimestamptz論理削除日時（nullable）
created_attimestamptz作成日時
updated_attimestamptz更新日時

APIエンドポイント

ユーザー向け（既存 + 新規）

認証必須。deleted_at IS NULL のレコードのみ返す。

メソッドパス概要
GET/api/cat-breeds品種一覧
GET/api/vaccine-typesワクチン種類一覧
GET/api/symptom-categories症状カテゴリ一覧
GET/api/food-typesフード種類一覧（新規）

管理者向け

管理者認証必須。users.list / masterData.* 権限に基づく。

品種・ワクチン種類・症状カテゴリ・フード種類で共通パターン。以下は品種を例示するが、他のマスタも同一パターン。

メソッドパス概要必要権限
GET/api/admin/cat-breeds品種一覧（削除済み含む）masterData.list
POST/api/admin/cat-breeds品種追加masterData.create
PATCH/api/admin/cat-breeds/:id品種更新masterData.update
DELETE/api/admin/cat-breeds/:id品種論理削除masterData.delete
POST/api/admin/cat-breeds/:id/restore品種復元masterData.update

同様のパターンで以下も提供:

  • /api/admin/vaccine-types
  • /api/admin/symptom-categories
  • /api/admin/food-types

GET /api/admin/cat-breeds — 品種一覧（管理者向け）

削除済みを含む全レコードを返す。

パラメータ型必須デフォルト説明
includeDeletedboolean-truefalse の場合、削除済みを除外
{
  "data": [
    {
      "id": 1,
      "name": "アメリカンショートヘア",
      "displayOrder": 3,
      "deletedAt": null,
      "usageCount": 15,
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z"
    },
    {
      "id": 30,
      "name": "旧品種名",
      "displayOrder": null,
      "deletedAt": "2026-02-01T00:00:00Z",
      "usageCount": 2,
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-02-01T00:00:00Z"
    }
  ]
}
  • usageCount: この品種を参照しているペット数。削除時の影響範囲を確認するため表示

POST /api/admin/cat-breeds — 品種追加

// リクエスト
{
  "name": "トンキニーズ",
  "displayOrder": 15
}
フィールド型必須バリデーション
namevarchar○1〜100文字、一意
displayOrderinteger-0以上の整数
  • 成功時: 201 Created
  • 名前が重複: 409 Conflict

PATCH /api/admin/cat-breeds/:id — 品種更新

{
  "name": "トンキニーズ（更新）",
  "displayOrder": 16
}
  • 成功時: 200 OK
  • 名前が重複: 409 Conflict

DELETE /api/admin/cat-breeds/:id — 品種論理削除

  • 成功時: 204 No Content
  • 既に削除済み: 409 Conflict
  • レスポンスに使用中件数の警告を含む（確認用）

POST /api/admin/cat-breeds/:id/restore — 品種復元

  • 成功時: 200 OK
  • 削除されていない場合: 409 Conflict

認可ルール

  • ユーザー向けAPI: 認証済みユーザーなら誰でも閲覧可能
  • 管理者向けAPI: users.role = 'admin' かつ masterData.* 権限が必要
  • 権限がない操作: 403 Forbidden

エッジケース

  • 使用中のマスタデータを削除した場合 → 論理削除のため既存の参照は維持される。ユーザー向けの選択肢からは非表示になるが、既に登録済みの記録には影響しない
  • 同名のマスタデータを追加しようとした場合 → 409 Conflict
  • 削除済みのマスタと同名を追加しようとした場合 → 409 Conflict（削除済みを復元してから更新するフローを推奨）
  • 全マスタが削除された場合 → ユーザー向け一覧は空配列を返す。「その他」の自由入力（breed_other 等）で対応可能
  • displayOrder が未設定の場合 → name のアルファベット/五十音順でソート
  • シードデータの再投入 → 冪等に設計（既に存在する名前はスキップ）

拡張予定（現時点ではスコープ外）

  • マスタデータのインポート/エクスポート（CSV）
  • マスタデータの変更履歴（監査ログ）
  • マスタデータのアイコン/画像設定
  • 病院名のマスタ化（FR-006の自由入力テキストをマスタ管理に移行）
  • マスタデータのカテゴリ分け（ワクチンのコア/ノンコア分類等）

検証方法

  • 管理者がマスタデータの一覧を取得でき、削除済みを含むこと
  • マスタデータの追加が成功し、ユーザー向けAPIに反映されること
  • マスタデータの更新が成功すること
  • マスタデータの論理削除後にユーザー向けAPIから非表示になること
  • 論理削除後に既存の健康記録が影響を受けないこと
  • 削除済みマスタの復元が成功し、ユーザー向けAPIに再表示されること
  • 重複名のマスタデータ追加が拒否されること
  • usageCount が正しく計算されること
  • displayOrder によるソートが正しく動作すること
  • シードデータが初期セットアップで正しく投入されること
  • 一般ユーザーが管理者APIにアクセスした場合に 403 が返ること
  • 権限がない管理者の操作に 403 が返ること