管理画面フォーマット開発編 #8 前編
部署別ロール ─ DepartmentRoleテーブル導入とDB設計

グローバルで一貫したRoleテーブルを保ちながら、部署ごとにロールをカスタマイズするために「DepartmentRole」テーブルを新設

初回公開日2025/9/29

最終更新日2025/9/29

0. はじめに

「管理画面フォーマット開発編」では、UIだけでなくバックエンド開発も徐々に取り込みながら進めてきました。ログイン画面の実装から始まり、JWT＋Cookieによる認証、ユーザ一覧や詳細・新規作成フォーム、プロフィール編集やアバターアップロード、さらにRBACによるロールベースのアクセス制御までを整備してきました。これにより、管理画面として最低限の「ログインできる・ユーザを扱える・権限を分けられる」仕組みがすでに動いています。

部署ごとのロール管理の必要性

実際の業務システムでは、単純な「管理者」「閲覧者」といったロールだけでは足りません。部署ごとに必要な権限は微妙に異なり、呼称や区分も柔軟に調整したい場合があります。たとえば営業部だけに付与する「案件編集」ロールや、部署ごとに色分けされたバッジでロールを見分けたいケースです。こうした要件に対応する仕組みとして、グローバルのRoleを維持しつつ部署単位でカスタマイズ可能な DepartmentRole テーブルを導入します。

前編と後編に分けて進めます

ロールのDB連携は範囲が広く、DBスキーマからPrismaモデル、Server Action、UI改修、ガード処理まで関わります。すべてを一記事で扱うと分量が大きくなるため、今回は 前編（DBとPrisma編） と 後編（Server ActionとUI編） に分けて解説する方針としました。前編では基盤整備を中心に扱い、後編で実際の操作画面やロール管理機能を仕上げていきます。

本記事で扱う範囲

本記事（前編）では、以下の内容を取り扱います。

範囲	内容
要件整理	部署ごとのロール調整とグローバルRoleの関係を明確化
DB設計	DepartmentRoleテーブル導入、Userテーブルへの拡張（departmentRoleId追加）
Prisma更新	schema.prismaへの追記と制約の扱い方
実効ロール	override/customの適用ルールと合成方法

ここまでを押さえることで、次回の「Server Action実装とUI改修」に向けた基盤が完成します。

技術スタック

Tool / Lib	Version	Purpose
React	19.x	UIの土台。コンポーネント/フックで状態と表示を組み立てる
Next.js	15.x	フルスタックFW。App Router/SSR/SSG、動的ルーティング、メタデータ管理
TypeScript	5.x	型安全・補完・リファクタリング
shadcn/ui	latest	RadixベースのUIキット
Tailwind CSS	4.x	ユーティリティファーストCSSで素早くスタイリング
Zod	4.x	スキーマ定義と実行時バリデーション

本記事では、前回の記事 【管理画面フォーマット開発編 #7】部署別ロール ─ DepartmentRoleテーブル導入とDB設計 までのソースコードを引き継いで追加・編集していきます。

1. 要件整理と設計方針

グローバルRoleとDepartmentRoleの役割分担

まず大前提として、既存の Roleテーブルはグローバル共通 です。すべての部署で意味が一貫し、コードや権限フラグは統一されます。一方で、部署ごとに「名前を変えたい」「色を変えたい」「独自のロールを作りたい」というニーズも存在します。そこで新設するのが DepartmentRoleテーブル です。

テーブル	役割
Role	グローバル共通。コード・priority・権限フラグを一元管理する
DepartmentRole	部署単位の調整。グローバルRoleの名称・バッジ色の上書き、または部署専用ロールの追加
User	各ユーザーは `roleId` または `departmentRoleId` のどちらかを参照する

overrideモードとcustomモード

DepartmentRoleは2つの使い方を想定しています。グローバルRoleを基にした「override」と、部署専用に新規作成する「custom」です。

モード	特徴	制約条件
override	グローバルRoleに名前・バッジ色だけ上書きする	Role.priorityや権限フラグは変更不可
custom	部署専用に新規作成。コード・名前・priority・権限を定義できる	priorityは99以下に制限

priorityルール

ロールの強さを示すpriorityは、ガード処理やメニュー表示に直結します。そのため、部署ごとに新規作成できるロールのpriorityは 99以下（ADMIN未満） に制約します。これにより、グローバルで定義される「システム管理者」以上のロールを部署側が勝手に作れないようになります。

種別	priority範囲	管理主体
システム管理者系	100以上	グローバル
部署ローカル系	99以下	DepartmentRole

XORルール（roleId と departmentRoleId）

Userモデルでは、ユーザーが参照できるのは roleId（グローバルRole） または departmentRoleId（部署ローカルRole） のいずれかです。同時指定は許されず、XOR制約 を付けることで整合性を保ちます。

text

User
 ├─ roleId (グローバルRole)      → Role.id を参照
 └─ departmentRoleId (部署ロール) → DepartmentRole.id を参照
※ 両方同時にはNULL不可

設計方針のまとめ

今回の設計方針を整理すると次の通りです。

項目	方針
Roleテーブル	グローバル共通。変更不可。コード・priority・権限フラグを一元管理
DepartmentRoleテーブル	部署単位の調整。override（名称・色のみ上書き）とcustom（新規作成）をサポート
priorityルール	customは99以下に制約し、ADMIN以上はグローバルのみ定義可能
Userテーブル	`roleId` または `departmentRoleId` のどちらか一方を参照（XOR制約）

2. DB設計とマイグレーション

部署ごとのロール調整を可能にするため、グローバル共通の Role を維持しつつ、部署単位で上書き／新規作成を担う DepartmentRole を追加します。ユーザーは Role か DepartmentRole のどちらか一方を参照できるようにし、整合性は制約で担保します。

ER図と責務分担（Role / DepartmentRole / Userの関係）

Role・DepartmentRole・Userの関係を文字図で示すと次のようになります。

txt

Role (グローバル)
 ├─ id
 ├─ code / name / priority / 権限フラグ
 └─ users (roleId経由)

DepartmentRole (部署別)
 ├─ id
 ├─ departmentId
 ├─ roleId (override用: グローバル参照)
 ├─ code / name / priority (custom用)
 └─ users (departmentRoleId経由)

User
 ├─ departmentId
 ├─ roleId (グローバル参照)
 └─ departmentRoleId (部署参照)
   ※ roleId と departmentRoleId は XOR制約

DepartmentRole テーブルの定義

DepartmentRole は 2モード を1テーブルで表現します。override は「名称・バッジ色のみ上書き」、custom は「部署固有の新規ロール作成（priority ≤ 99）」です。

フィールド	型	必須	用途/説明
id	UUID	✔︎	主キー
displayId	String	✔︎	表示用ID（シーケンス + “DR”）
departmentId	UUID	✔︎	部署参照
roleId	UUID		override用：参照先のグローバルRole
nameOverride	String		override用：名称の上書き
badgeColorOverride	String		override用：バッジ色の上書き
code	String		custom用：部署ローカルのロールコード（部署内一意）
name	String		custom用：部署ローカルのロール名
priority	Int		custom用：99以下に制約
canDownloadData	Boolean		custom用：データDL権限
canEditData	Boolean		custom用：データ編集権限
isEnabled	Boolean	✔︎	部署視点の利用可否（初期 true）
createdAt / updatedAt	DateTime	✔︎	タイムスタンプ

User テーブルの拡張（XOR）

User は Role または DepartmentRole のどちらか一方を参照します。編集フォーム／サーバ側バリデーションの両方で XOR を強制します。

text

User
├─ departmentId
├─ roleId?            # 参照：Role.id
└─ departmentRoleId?  # 参照：DepartmentRole.id
※ (roleId が NULL) XOR (departmentRoleId が NULL)

制約ルール（整合性保護）

整合性と一貫性を担保するため、次の制約を設けます。

区分	内容
override一意	`(departmentId, roleId)` を一意（部署×対象Roleに対して1定義まで）
custom一意	`(departmentId, code)` を一意（部署内で同コード重複禁止）
priority上限	custom の `priority ≤ 99` を DB 制約で保証
User の XOR	`roleId` と `departmentRoleId` の同時指定禁止（DB制約 + フォーム/SA での二重検証）
部署整合性	`User.departmentId = DepartmentRole.departmentId` をアプリ側で必ず検証

マイグレーションの流れ

ゼロダウンタイムを意識し、既存ユーザーの roleId を尊重しつつ段階導入します。

DepartmentRole テーブル作成（シーケンス・displayId・一意制約・CHECK制約を設定）
User に departmentRoleId 追加（インデックス付与、roleId との XOR 制約追加）
既存データはそのまま稼働（全ユーザーは引き続き roleId を参照）
必要な部署から順に override/custom を投入（isEnabled やコード規約で運用）
将来、必要ユーザーのみ departmentRoleId へ移行（E2Eを含む移行テストを実施）

章のまとめ

Role はグローバル共通 、 DepartmentRole は部署単位の上書き/新規ロール を担う。
User は XOR （Role or DepartmentRole のどちらか一方）。
custom の priority は 99 以下 、override は 名称・色のみ 上書き。
段階導入で既存運用を止めない設計にする。

3. Prismaモデルの更新

前章で整理したDB設計を、Prismaのスキーマファイルに反映します。Prismaでは制約やCHECKの一部を直接表現できないため、Prismaモデルで表現できる範囲はPrismaに任せ、残りはマイグレーションSQLで補完 する方針をとります。

DepartmentRoleモデル

まずは DepartmentRole のモデルを schema.prisma に追記します。
このモデルは override と custom の両モードを1テーブルで表現します。

prisma

model DepartmentRole {
  id        String   @id @default(uuid())
  displayId String   @unique @default(dbgenerated("generate_display_id('department_role_display_id_seq','DR')")) @db.VarChar(10)
  createdAt DateTime @default(now()) @db.Timestamptz
  updatedAt DateTime @updatedAt @db.Timestamptz

  departmentId String
  department   Department @relation(fields: [departmentId], references: [id], onDelete: Restrict)

  // override モード
  roleId              String? 
  role                Role?   @relation(fields: [roleId], references: [id], onDelete: Restrict)
  nameOverride        String?
  badgeColorOverride  String?
  isEnabled           Boolean @default(true)

  // custom モード
  code            String?   @db.VarChar(50)
  name            String?
  priority        Int?
  badgeColor      String?
  canDownloadData Boolean?
  canEditData     Boolean?
  isSystem        Boolean?
  remarks         String?

  users User[]

  @@unique([departmentId, roleId])
  @@unique([departmentId, code])
  @@index([departmentId])
  @@index([roleId])
}

この定義では、override/customの両方を許容しています。ただしXORやpriorityの上限など、Prismaモデルで表現できない部分は マイグレーションSQLでCHECK制約を追加 します。

Userモデルの拡張

Userモデルには departmentRoleId を追加し、RoleかDepartmentRoleのどちらか一方を参照できるようにします。

prisma

model User {
  id        String    @id @default(uuid())
  displayId String    @unique @default(dbgenerated("generate_display_id('user_display_id_seq','US')")) @db.VarChar(10)
  isActive  Boolean   @default(true)
  createdAt DateTime  @default(now()) @db.Timestamptz
  updatedAt DateTime  @updatedAt      @db.Timestamptz
  deletedAt DateTime?                  @db.Timestamptz

  departmentId     String
  roleId           String
  email            String 
  hashedPassword   String
  name             String
  phone            String?
  remarks          String?
  departmentRoleId  String? // ← 追加

  // ログイン失敗ロック
  failedLoginCount Int       @default(0)
  lockedUntil      DateTime? @db.Timestamptz

  // アバター画像
  avatar           String?   // UUID＋拡張子を格納

  // リレーション
  department Department @relation(fields: [departmentId], references: [id], onDelete: Restrict)
  role       Role       @relation(fields: [roleId], references: [id], onDelete: Restrict)
  // ↓追加
  departmentRole    DepartmentRole? @relation(fields: [departmentRoleId], references: [id], onDelete: Restrict)


  // Session への逆側（双方向）リレーション
  sessions Session[] @relation("UserSessions")

  /// 逆リレーション: このユーザーが出したメール変更申請
  emailChangeRequests    EmailChangeRequest[]

  // 部署内メール一意（ログインキー）
  @@unique([departmentId, email])
  @@index([departmentId])
  @@index([roleId])
  // ↓追加
  @@index([departmentRoleId])
  @@index([isActive])
  @@index([createdAt])
}

これによりユーザーは roleId か departmentRoleId のどちらかを参照可能になります。
両方同時は不可であり、この制約はSQLで追加します。

Departmentモデルの修正

Departmentは多数の DepartmentRole を持つため、逆リレーションを追加します。

prisma

model Department {
  id        String    @id @default(uuid())
  displayId String    @unique @default(dbgenerated("generate_display_id('department_display_id_seq','DP')")) @db.VarChar(10)
  isActive  Boolean   @default(true)
  createdAt DateTime  @default(now()) @db.Timestamptz
  updatedAt DateTime  @updatedAt      @db.Timestamptz
  deletedAt DateTime?                  @db.Timestamptz

  // ログイン用コード（人間入力・推測困難な固定文字列）
  code String @unique

  branchId String
  name     String
  phone    String?
  remarks  String?

  // リレーション
  branch        Branch         @relation(fields: [branchId], references: [id], onDelete: Restrict)
  contacts      Contact[]
  subscriptions Subscription[]
  users         User[]
  // ↓追加
  departmentRoles DepartmentRole[]

   /// 逆リレーション: 部署に紐づく許可ドメイン一覧
  allowedDomains         AllowedEmailDomain[] 
  /// 逆リレーション: 部署配下ユーザーのメール変更申請
  emailChangeRequests    EmailChangeRequest[] 

  @@index([branchId])
  @@index([isActive])
  @@index([createdAt])
}

Roleモデルの修正

Roleも DepartmentRole に参照されるため、逆リレーションを追加します。

prisma

model Role {
  id        String    @id @default(uuid())
  displayId String    @unique @default(dbgenerated("generate_display_id('role_display_id_seq','RL')")) @db.VarChar(10)
  isActive  Boolean   @default(true)
  createdAt DateTime  @default(now()) @db.Timestamptz
  updatedAt DateTime  @updatedAt      @db.Timestamptz
  deletedAt DateTime?                  @db.Timestamptz

  code            String  @unique // 例: ADMIN / EDITOR / VIEWER ...
  name            String
  priority        Int
  badgeColor      String?
  isSystem        Boolean @default(false)
  canDownloadData Boolean
  canEditData     Boolean
  remarks         String?

  users User[]
  // ↓追加
  departmentRoles DepartmentRole[]

  @@index([priority])
  @@index([isActive])
}

マイグレーション実行手順

ここまで定義したら、マイグレーションを生成・修正・適用します。

zsh

# マイグレーションファイルの生成
npx prisma migrate dev --create-only --name add_department_role

このコマンドで prisma/migrations/xxxx_add_department_role/migration.sql が生成されます。
生成されたSQLには、以下の制約を手動で追加します。

マイグレーションSQLの修正例

追記が必要なのは下記の4箇所になります。（追記）と記載したSQL文を追加します。

sql

-- （追記）先頭に追加、displayId用シーケンスを先に作成
CREATE SEQUENCE IF NOT EXISTS "public".department_role_display_id_seq;

-- 省略

-- AlterTable
ALTER TABLE "public"."User" ADD COLUMN     "departmentRoleId" TEXT,
ALTER COLUMN "displayId" SET DEFAULT generate_display_id('user_display_id_seq','US');

-- （追記）User の XOR制約（roleId と departmentRoleId の同時指定禁止）
ALTER TABLE "public"."User"
  ADD CONSTRAINT user_role_xor CHECK (
    ("roleId" IS NOT NULL) <> ("departmentRoleId" IS NOT NULL)
  );

-- CreateTable
CREATE TABLE "public"."DepartmentRole" (
    "id" TEXT NOT NULL,
    "displayId" VARCHAR(10) NOT NULL DEFAULT generate_display_id('department_role_display_id_seq','DR'),
    "createdAt" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "updatedAt" TIMESTAMPTZ NOT NULL,
    "departmentId" TEXT NOT NULL,
    "roleId" TEXT,
    "nameOverride" TEXT,
    "badgeColorOverride" TEXT,
    "isEnabled" BOOLEAN NOT NULL DEFAULT true,
    "code" VARCHAR(50),
    "name" TEXT,
    "priority" INTEGER,
    "badgeColor" TEXT,
    "canDownloadData" BOOLEAN,
    "canEditData" BOOLEAN,
    "isSystem" BOOLEAN,
    "remarks" TEXT,

    CONSTRAINT "DepartmentRole_pkey" PRIMARY KEY ("id")
);

-- （追記）DepartmentRole の priority 制約
ALTER TABLE "public"."DepartmentRole"
  ADD CONSTRAINT department_role_priority_cap CHECK (
    "priority" IS NULL OR "priority" <= 99
  );

-- （追記）DepartmentRole の override/custom XOR制約
ALTER TABLE "public"."DepartmentRole"
  ADD CONSTRAINT department_role_mode_check CHECK (
    (
      "roleId" IS NOT NULL AND
      "code" IS NULL AND "name" IS NULL AND "priority" IS NULL AND
      "badgeColor" IS NULL AND "canDownloadData" IS NULL AND "canEditData" IS NULL AND "isSystem" IS NULL
    )
    OR
    (
      "roleId" IS NULL AND
      "code" IS NOT NULL AND "name" IS NOT NULL AND "priority" IS NOT NULL
    )
  );

-- 省略

この修正で、DepartmentRoleのモードが常に明示的になり、UserがグローバルRoleか部署Roleのどちらか一方を持つことを保証できます。

マイグレーション適用と検証

修正が終わったら、マイグレーションを適用し、型を再生成します。

zsh

# マイグレーション適用
npx prisma migrate dev

# Prisma Client 再生成
npx prisma generate

適用後は、Prisma Clientから prisma.departmentRole.findMany() や
prisma.user.findMany({ include: { departmentRole: true } }) を実行して整合性を確認します。
既存ユーザーは引き続き roleId を参照しているため、移行の影響はありません。

章のまとめ

DepartmentRoleモデルを追加し、override/custom両対応を表現
Userに departmentRoleId を追加し、RoleとのXORを設計
Department と Role に逆リレーションを追加し、クエリをシンプル化
マイグレーション生成後に priority制約・override/custom XOR・UserのXOR をSQLで追記
適用後、既存データを維持したまま新しい構造に移行可能

これにより、スキーマ上もアプリケーション上も安全な設計になります。

4. 実効ロールの合成（effective role）

この章では、 データベースに反映済みのスキーマ を前提に、画面やガードで用いる「実効ロール（effective role）」をどのように合成するかを定義・実装します。グローバル Role と部署単位の DepartmentRole（override/custom）を統一インターフェースで扱えるようにし、以降の Server Action／UI 実装の土台にします。

合成規則の整理

実効ロールは、 「どのIDを参照しているか」 と 「DepartmentRole が override か custom か」 に応じて決定します。表示名やバッジ色の扱いなど、細かな挙動を明示します。

ケース	ベース	上書き(override)	priority	canEdit / canDownload	備考
User.roleId のみ	Role	DepartmentRole があれば name/badgeColor	Role	Role	見た目だけ差し替え可
User.departmentRoleId (override)	Role	name/badgeColor	Role	Role	Role値を信頼、表記のみ部署で変更
User.departmentRoleId (custom)	DR	なし	DR	DR	部署ローカル定義（priority ≤ 99）

意思決定の流れ

下図は、ユーザーの参照先と DR のモードに応じて、どの値を採用するかのフローです。

txt

[入力] departmentId, user.roleId?, user.departmentRoleId?
        │
        ├─ departmentRoleId がある？
        │       │
        │       ├─ YES → DepartmentRole を取得
        │       │       ├─ roleId が NULL → custom:
        │       │       │       実効 = DR の code/name/priority/badge/can*
        │       │       └─ roleId が有 → override:
        │       │               実効 = Role をベースに name/badgeColor を DR で上書き
        │       │
        │       └─ 戻り値: effective role
        │
        └─ NO → roleId を使う
                │
                ├─ Role を取得
                ├─ 同 departmentId の DepartmentRole(override) があれば
                │     name/badgeColor のみ上書き（あれば）
                └─ 戻り値: effective role

データ取得の最小戦略

クライアント／ガードでの呼び出し頻度が高いため、 1回の合成で必要十分 なフィールドだけに絞って取得します。

Role: code, name, priority, badgeColor, canEditData, canDownloadData
DepartmentRole(override): nameOverride, badgeColorOverride, isEnabled
DepartmentRole(custom): code, name, priority, badgeColor, canEditData, canDownloadData, isEnabled

isEnabled=false の DR は ログイン中ユーザーに割り当てられていた場合の扱い を運用で決めます（ここでは「実効ロールは返すがUIで警告」方針を前提）。

実装（ユーティリティの作成）

ユーティリティはサーバー専用で実装します。配置例は src/lib/auth/effective-role.ts。
戻り値は UI/ガード双方で使いやすい最小セットに揃えます。

// src/lib/auth/effective-role.ts
import "server-only";
import { prisma } from "@/lib/database";

export type EffectiveRole = {
  code: string; // 表示やロギングに使用（customはDR.code、override/roleIdのみはRole.code）
  name: string; // 表示名（override適用済み）
  priority: number; // ガード判定に使用
  badgeColor: string | null; // バッジ表示（override適用済み）
  canEditData: boolean; // 書き込み系ガード
  canDownloadData: boolean; // エクスポート系ガード
  isEnabledInDepartment: boolean; // 部署視点の使用可否（DRが無ければ true）
  source: "role" | "override" | "custom"; // どの経路で合成されたか
};

type Input =
  | { departmentId: string; roleId: string; departmentRoleId?: undefined }
  | { departmentId: string; roleId?: undefined; departmentRoleId: string };

/**
 * 実効ロール合成
 * - roleId のみ    : Role をベースに、あれば override の name/badge を適用
 * - departmentRole : custom なら DR 値、override なら Role 値 + name/badge 上書き
 */
export async function getEffectiveRole(
  input: Input,
): Promise<EffectiveRole | null> {
  const { departmentId } = input;

  if (input.departmentRoleId) {
    const dr = await prisma.departmentRole.findUnique({
      where: { id: input.departmentRoleId },
      select: {
        isEnabled: true,
        // custom 用
        code: true,
        name: true,
        priority: true,
        badgeColor: true,
        canDownloadData: true,
        canEditData: true,
        // override 用
        roleId: true,
        nameOverride: true,
        badgeColorOverride: true,
        // 参照 Role 情報
        role: {
          select: {
            code: true,
            name: true,
            priority: true,
            badgeColor: true,
            canDownloadData: true,
            canEditData: true,
          },
        },
      },
    });

    if (!dr) return null;

    // custom: roleId が NULL
    if (!dr.roleId) {
      // priority, can* は DR の値が必須（DB制約により存在）
      return {
        code: dr.code ?? "UNKNOWN",
        name: dr.name ?? "Unnamed",
        priority: dr.priority ?? 0,
        badgeColor: dr.badgeColor ?? null,
        canEditData: dr.canEditData ?? false,
        canDownloadData: dr.canDownloadData ?? false,
        isEnabledInDepartment: dr.isEnabled,
        source: "custom",
      };
    }

    // override: Role をベースに name/badge を上書き
    const r = dr.role;
    if (!r) return null;

    return {
      code: r.code,
      name: dr.nameOverride ?? r.name,
      priority: r.priority,
      badgeColor: dr.badgeColorOverride ?? r.badgeColor ?? null,
      canEditData: r.canEditData,
      canDownloadData: r.canDownloadData,
      isEnabledInDepartment: dr.isEnabled,
      source: "override",
    };
  }

  // roleId のみ
  if (input.roleId) {
    // Role を取得しつつ、同 department の override があれば1件拾う
    const r = await prisma.role.findUnique({
      where: { id: input.roleId },
      select: {
        code: true,
        name: true,
        priority: true,
        badgeColor: true,
        canDownloadData: true,
        canEditData: true,
        departmentRoles: {
          where: { departmentId, roleId: { not: null } },
          take: 1,
          select: {
            isEnabled: true,
            nameOverride: true,
            badgeColorOverride: true,
          },
        },
      },
    });
    if (!r) return null;

    const ov = r.departmentRoles[0]; // 0 or 1
    return {
      code: r.code,
      name: ov?.nameOverride ?? r.name,
      priority: r.priority,
      badgeColor: ov?.badgeColorOverride ?? r.badgeColor ?? null,
      canEditData: r.canEditData,
      canDownloadData: r.canDownloadData,
      isEnabledInDepartment: ov ? ov.isEnabled : true,
      source: ov ? "override" : "role",
    };
  }

  return null;
}

上記コードのポイント

型安全：引数 Input をユニオンで定義し、roleId と departmentRoleId のどちらか必須を型で表現。
最小選択：必要なフィールドのみ select。クエリオーバーを避け、レスポンスを軽く。
source フラグ：UIやログで「どの経路で合成されたか」を可視化。運用トラブルシュートに有効。
isEnabledInDepartment：無効化された override/custom をUIで注記できるよう保持。

メニュー判定・ガード連携

この節のゴールは、I/Fを一切変えずに「実効ロール（Role＋DepartmentRoleの合成結果）」を運用へ反映することです。鍵は src/lib/auth/user-snapshot.tsの getUserSnapshot() の内部で rolePriority 等を“実効値”に置き換える こと。

これにより、既存のsrc/lib/auth/guard.ssr.tsで実施しているガード判定関数である guardHrefOrRedirect() は従来どおり user だけを返し、ページやサイドバーは user.rolePriority をそのまま使う だけで、正しくRBACが効きます。

txt

# データフロー（変更は user-snapshot の内部実装のみ）
Cookie → Session復元 → userId
   → getUserSnapshot(userId)   # ここで getEffectiveRole を内部呼び出し
      → user.roleCode / rolePriority / canEditData / canDownloadData を「実効値」に
         ↓
guardHrefOrRedirect(href) は これまで通り { ok, user } を返す
ページ側 / サイドバー側は user.rolePriority を使って `filterMenuRecordsByPriority` を適用（現状のまま）

// src/lib/auth/user-snapshot.ts
import { prisma } from "@/lib/database";
import type { AuthUserSnapshot } from "./types";
import { getEffectiveRole } from "./effective-role";

/**
 * セッションで得られた userId から、Context 用の最小スナップショットを作る。
 * PII を最小化し、重い JOIN は避け、必要な列だけ select する。
 */
export async function getUserSnapshot(
  userId: string,
): Promise<AuthUserSnapshot | null> {
  const user = await prisma.user.findUnique({
    where: { id: userId },
    select: {
      id: true,
      name: true,
      email: true,
      avatar: true,
      departmentId: true,
      roleId: true,
      departmentRoleId: true,
      // 既存I/Fではロール権限はスナップショットに投影するので、
      // 「DB生のRole値」に依存せず、この後に「実効ロール」で上書きする。
    },
  });

  if (!user) return null;

  // 実効ロールを“内部で”合成（スナップショットI/Fには必要な値だけを反映）
  const eff = await getEffectiveRole(
    user.departmentRoleId
      ? {
          departmentId: user.departmentId,
          departmentRoleId: user.departmentRoleId,
        }
      : { departmentId: user.departmentId, roleId: user.roleId! },
  );
  if (!eff) return null;

  return {
    userId: user.id,
    name: user.name,
    email: user.email,
    avatarUrl: user.avatar ? `/avatar/${user.id}` : null,
    roleCode: eff.code, // ← 実効ロールの code を適用
    rolePriority: eff.priority, // ← 実効ロールの priority を適用
    canEditData: eff.canEditData, // ← 実効ロールの権限フラグを適用
    canDownloadData: eff.canDownloadData, // ← 実効ロールの権限フラグを適用
  };
}

説明

返却I/F（AuthUserSnapshot）は増減なし。roleCode / rolePriority / canEditData / canDownloadData に 実効値を入れるだけ。

テスト観点（最小セット）

ユニットテスト・E2Eの双方で、代表的なケースを押さえます。

ケース	入力（user参照）	期待される結果
roleId のみ	Role: ADMIN	source=role, name=Role.name, priority=Role.priority
roleId + override 定義あり	Role: EDITOR + DR(override)	source=override, name/badge=override適用
departmentRoleId (custom)	DR(custom)	source=custom, priority/can* は DR 値
isEnabled=false	いずれか	isEnabledInDepartment=false（UIで警告／制限）
参照崩れ	不正ID	null 返却（呼び出し側で 401/403 ハンドリング）

章のまとめ

実効ロールは Role を基点 に、部署側の override/custom を合成して一貫API化。
UI・ガードは EffectiveRole のみを意識すればよい設計に収束。
source と isEnabledInDepartment を保持することで、運用時の見える化や段階的移行が容易になる。

5. まとめと次回予告

この前編では、グローバル Role と部署単位 DepartmentRole を組み合わせる仕組みを設計し、DBスキーマ・Prismaモデル・マイグレーション、さらに「実効ロール（effective role）」の合成処理までを実装しました。これにより、ユーザーは roleId または departmentRoleId を持ちつつ、画面やガードからは常に 統一された rolePriority / 権限フラグ を利用できるようになりました。

本記事で押さえたポイント

項目	内容
DB設計	DepartmentRole テーブルを新設し、override/custom の両モードを定義
Prismaモデル	User/Department/Role にリレーションを追加し、整合性を保証
マイグレーション	priority 制約や XOR 制約を SQL レベルで補完
実効ロールの合成	Role と DepartmentRole を統合し、UI/ガードから統一的に参照可能にした
スナップショット統合	`getUserSnapshot()` 内で実効ロールを反映し、I/F変更なしで利用可能化

この設計のメリット

UI側は単純化
ページやサイドバーは、従来通り user.rolePriority を参照するだけで RBAC が効く。
既存コードの影響最小化
guardHrefOrRedirect() の戻り値や AuthUserSnapshot の型は変更なし。
拡張性の確保
今後部署単位のロール追加や名称変更があっても、DBに投入するだけで即時反映可能。

次回（後編）の内容

次回は Server Action と UI での実装 に進みます。実効ロールの仕組みを活用して、部署ごとのロールを実際に管理できる画面とAPIを作り込みます。

項目	内容
Server Action	DepartmentRole の作成・更新・削除、override/custom のバリデーション
管理UI	`/masters/roles` ページに DepartmentRole 一覧と編集フォームを追加
ガード処理	Server Action 側で priority / 権限チェックを行い、安全な操作を保証

後編を終えると、「部署単位で調整可能な RBAC」 が管理画面に実装され、現場の柔軟な運用に耐える仕組みが完成します。

参考文献

本記事の設計・実装を進めるにあたり、以下の公式ドキュメントや参考資料を参照しました。

分類	リンク
Prisma	Prisma Schema Reference
Prisma	Relations in Prisma
PostgreSQL	PostgreSQL: Documentation
PostgreSQL	PostgreSQL – Constraints
Next.js	Next.js App Router Documentation
Next.js	Server-only Modules
TypeScript	Utility Types
RBAC	Role-Based Access Control (NIST Standard)

この記事の執筆・編集担当

松本孝太郎

DELOGs編集部/中年新米プログラマー

ここ数年はReact&MUIのフロントエンドエンジニアって感じでしたが、Next.jsを学んで少しずつできることが広がりつつあります。その実践記録をできるだけ共有していければと思っています。

▼ 関連記事

[管理画面フォーマット開発編 #7] ユーザ管理UIをDB連携する

ユーザ一覧表示・新規登録・編集フォームをDBと連動させ、ユーザデータを操作できる形へ

2025/9/28公開

[管理画面フォーマット開発編 #6] RBAC調整 ─ ページ単位のアクセス制御を実装する

これまでメニュー表示に適用していたRBACを、各ページのアクセス制御に拡張

2025/9/23公開

[管理画面フォーマット開発編 #6] RBAC調整 ─ ページ単位のアクセス制御を実装するのイメージ

[管理画面フォーマット開発編 #5] ユーザプロフィール更新

プロフィール編集機能を拡張し「アバター削除」「メールアドレス変更新（メールでの本人認証＋管理者承認）」「パスワード変更」を実装

2025/9/21公開

[管理画面フォーマット開発編 #4] Server Actionで実装するアバター画像のアップロードと表示

ユーザープロフィールに欠かせないアバター画像を、安全にアップロード・表示する仕組みを構築

2025/9/16公開

[管理画面フォーマット開発編 #3] AuthProviderでログイン済みユーザー情報を全体共有

ログイン成功直後に取得したユーザー情報をAuthProvider（Client Context）でアプリ全体に配布

2025/9/12公開

管理画面フォーマット開発編 #8 前編部署別ロール ─ DepartmentRoleテーブル導入とDB設計

0. はじめに

部署ごとのロール管理の必要性

前編と後編に分けて進めます

本記事で扱う範囲

技術スタック

1. 要件整理と設計方針

グローバルRoleとDepartmentRoleの役割分担

overrideモードとcustomモード

priorityルール

XORルール（roleId と departmentRoleId）

設計方針のまとめ

2. DB設計とマイグレーション

ER図と責務分担（Role / DepartmentRole / Userの関係）

DepartmentRole テーブルの定義

User テーブルの拡張（XOR）

制約ルール（整合性保護）

マイグレーションの流れ

章のまとめ

3. Prismaモデルの更新

DepartmentRoleモデル

Userモデルの拡張

Departmentモデルの修正

Roleモデルの修正

マイグレーション実行手順

マイグレーションSQLの修正例

マイグレーション適用と検証

章のまとめ

4. 実効ロールの合成（effective role）

合成規則の整理

意思決定の流れ

データ取得の最小戦略

実装（ユーティリティの作成）

メニュー判定・ガード連携

テスト観点（最小セット）

章のまとめ

5. まとめと次回予告

本記事で押さえたポイント

この設計のメリット

次回（後編）の内容

参考文献

管理画面フォーマット開発編 #8 前編
部署別ロール ─ DepartmentRoleテーブル導入とDB設計