Roles & Permissions

역할 4종과 CRUD 권한, 가드 사용법을 설명합니다.

사용자는 하나의 역할을 가지며, 역할은 roles 테이블에서 관리합니다. 화면의 접근 제어는 역할 이름으로 합니다.

Roles

id	name	설명	CRUD
1	MASTER	시스템 전체 관리자	`CRUD`
2	OWNER	자신이 소유한 데이터 관리	`CRUD`
3	VIEWER	조회 전용 사용자	`R`
4	WRITER	데이터 작성 및 수정 사용자	`CRU`

Permission matrix

역할	Create	Read	Update	Delete
MASTER	가능	가능	가능	가능
OWNER	가능	가능	가능	가능 (본인 소유 데이터)
VIEWER	불가	가능	불가	불가
WRITER	가능	가능	가능	정책에 따라 제한

실제 권한 범위는 서비스의 정책에 맞게 정하세요. 특히 OWNER는 본인 소유 데이터만 관리하도록 제한하는 것이 안전합니다.

Change roles in one place

프론트의 역할 정의는 src/meerkit/roles.ts 한 파일입니다. 역할 이름이나 설명이 바뀌면 여기만 고치세요.

src/meerkit/roles.ts

export const ROLES = [
  { id: 1, name: "MASTER", description: "시스템 전체 관리자", crud: "CRUD" },
  { id: 2, name: "OWNER", description: "자신이 소유한 데이터 관리", crud: "CRUD" },
  { id: 3, name: "VIEWER", description: "조회 전용 사용자", crud: "R" },
  { id: 4, name: "WRITER", description: "데이터 작성 및 수정 사용자", crud: "CRU" },
] as const;

export const ADMIN_ROLE = "MASTER";

How a check works

로그인하면 GET /users/me가 내 정보와 역할을 돌려줍니다.
프론트의 가드와 훅이 user.roles(여러 개일 수 있음)를 보고 화면을 보여 줄지 정합니다. hasRole(user, "MASTER"), isAdminUser(user)를 쓰세요.
데이터를 요청하면 서버가 같은 역할을 다시 검사하고 허용될 때만 응답합니다.

1~2번은 사용자 경험을, 3번은 실제 보안을 담당합니다. 둘 중 하나만으로는 안전하지 않습니다.

Protect a page

관리자만 볼 수 있는 화면은 RequireRole로 감쌉니다.

tsx

import { RequireRole, ADMIN_ROLE } from "@/meerkit";

export default function Page() {
  return (
    <RequireRole role={ADMIN_ROLE}>
      <AdminDashboard />
    </RequireRole>
  );
}

Check in code

tsx

const { user, isAdmin } = useAuth();

if (user?.role.name === "WRITER") {
  // 작성 버튼 표시
}

화면에서 버튼을 숨기는 것만으로는 보호가 되지 않습니다. 모든 보호는 FastAPI 백엔드에서도 반드시 검증해야 합니다.

Assign roles

회원가입 시 기본 역할은 서버가 자동으로 부여합니다.
역할 변경은 관리자(MASTER)만 할 수 있습니다. /admin/members의 역할 선택 상자를 사용합니다.
사용자당 역할은 하나이며, 변경하면 이전 역할은 대체됩니다.