Ch 5. 메뉴·권한·메시지 등록¶

1. 등록이 필요한 이유¶

Ch 4에서 코드를 완성했다면 https://localhost:8000/pt/0101에 직접 접근하면 화면은 뜹니다. 그러나 다음 두 가지는 아직 동작하지 않습니다.

이 챕터에서는 시스템 관리 화면으로 이 두 문제를 해결합니다.

2. 등록 순서 개요¶

뒤 단계가 앞 단계를 참조하므로 6단계 순서를 지켜야 합니다.

[1] SYS0103  메뉴 등록       → sys_menu 테이블에 PT, PT01, PT0101 행 추가
[2] SYS0102  메시지 등록     → sys_message 테이블에 메뉴명/빵조각 메시지 추가
[3] SYS0201  권한 템플릿     → sys_rbac_auth_tmpl에 PT0101 권한 코드 정의
[4] SYS0202  권한 등록       → sys_rbac_auth_name + auth_entry에 권한 그룹 생성
[5] SYS0204  역할 등록       → sys_rbac_role_entry에 역할 ↔ 권한 그룹 연결
[6] SYS0301  사용자에 역할 배정  → 현재 계정에 역할 부여

3. [1] SYS0103 — 메뉴 등록¶

화면 경로: /sys/0103 (메뉴 관리)

메뉴는 3단계 계층 구조입니다.

3.1 PT 최상위 메뉴 추가¶

화면 왼쪽 트리에서 루트(최상위)를 선택하고 메뉴 추가 버튼을 클릭합니다.

3.2 PT01 폴더 추가¶

트리에서 PT를 선택하고 하위 메뉴 추가 버튼을 클릭합니다.

3.3 PT0101 화면 메뉴 추가¶

트리에서 PT01을 선택하고 하위 메뉴 추가 버튼을 클릭합니다.

저장하면 sys_menu 테이블에 다음 3개 행이 생성됩니다.

-- 등록 결과 확인
SELECT id, parent_id, type, url, level FROM sys_menu WHERE id LIKE 'PT%' ORDER BY level;
-- 기대 출력:
-- PT    | ''   | MENU   | null      | 0
-- PT01  | PT   | FOLDER | null      | 1
-- PT0101| PT01 | URL    | /pt/0101  | 2

4. [2] SYS0102 — 메시지 등록¶

화면 경로: /sys/0102 (메시지)

hera-v4의 화면 제목, 메뉴명, 빵조각(breadcrumb)은 모두 DB 메시지 테이블(sys_message)에서 읽어옵니다. 코드에 하드코딩하지 않으므로, 메뉴를 브라우저에 올바른 이름으로 띄우려면 메시지 코드부터 등록합니다.

4.1 등록할 메시지 목록¶

4.2 등록 방법¶

화면에서 신규 등록 버튼을 클릭하고 아래 필드를 입력한 뒤 저장합니다.

5. [3] SYS0201 — 권한 템플릿 등록¶

화면 경로: /sys/0201 (권한 템플릿)

권한 템플릿(sys_rbac_auth_tmpl)은 "이 메뉴에서 어떤 권한들이 존재하는지"를 정의합니다. 나중에 SYS0202에서 권한을 부여할 때 이 템플릿이 체크박스 UI의 기반이 됩니다.

5.1 PT 카테고리 추가¶

트리에서 최상위를 선택하고 카테고리 추가:

5.2 PT01 폴더 추가¶

PT 항목을 선택하고 폴더 추가:

5.3 PT0101 메뉴 항목 추가¶

PT01 항목을 선택하고 메뉴 추가:

저장하면 sys_rbac_auth_tmpl 에 아래 행이 생성됩니다.

SELECT category, id, parent_id, perm1_code, perm2_code, perm3_code, perm4_code
FROM sys_rbac_auth_tmpl WHERE category = 'PT';
-- PT | PT0101 | PT01 | READ | CREATE | UPDATE | DELETE

6. [4] SYS0202 — 권한 등록¶

화면 경로: /sys/0202 (권한 등록)

권한 등록은 "어느 권한 그룹에 PT0101의 어떤 권한을 부여할 것인가"를 결정합니다. sys_rbac_auth_name에 그룹을 만들고, sys_rbac_auth_entry에 메뉴별 체크 항목을 저장합니다.

6.1 신규 권한 그룹 생성¶

신규 등록 버튼 클릭 후 이름 입력:

저장하면 UUID가 자동 생성되어 sys_rbac_auth_name.id가 됩니다.

6.2 PT0101 권한 체크¶

생성된 권한 그룹을 선택하면 우측에 SYS0201에서 등록한 권한 템플릿 트리가 나타납니다.

PT > PT01 > PT0101 항목에서 부여할 권한을 체크합니다.

저장하면 sys_rbac_auth_entry 테이블에 다음 행이 생성됩니다.

SELECT auth_id, category, menu_id, perm1, perm2, perm3, perm4
FROM sys_rbac_auth_entry WHERE category = 'PT' AND menu_id = 'PT0101';
-- {UUID} | PT | PT0101 | PT01 | true | true | true | true

7. [5] SYS0204 — 역할 등록 (권한 그룹 연결)¶

화면 경로: /sys/0204 (역할 등록)

역할(sys_rbac_role_name)은 여러 권한 그룹(sys_rbac_auth_name)을 묶는 단위입니다. 사용자에게는 역할 단위로 부여합니다.

7.1 기존 역할에 권한 그룹 추가 (권장)¶

이미 개발자용 역할이 존재한다면 해당 역할을 열어서 PT 전체 권한 그룹을 추가합니다.

목록에서 역할 선택 → 우측 권한 그룹 패널 → PT 전체 권한 추가 → 저장

-- 결과 확인
SELECT rn.name, an.name AS auth_name
FROM sys_rbac_role_name rn
JOIN sys_rbac_role_entry re ON re.id = rn.id
JOIN sys_rbac_auth_name an ON an.id = re.auth_id
WHERE rn.name = '개발자 역할';
-- 개발자 역할 | PT 전체 권한

7.2 신규 역할 생성 (별도 역할이 필요한 경우)¶

신규 등록 → 역할명 입력 → 권한 그룹 추가 → 저장

생성 후 PT 전체 권한 그룹을 연결합니다.

8. [6] SYS0301 — 사용자에 역할 배정¶

화면 경로: /sys/0301 (사용자 관리)

역할을 현재 로그인 계정에 부여합니다.

1. 사용자 목록에서 본인 계정 선택
2. 우측 역할 탭 열기
3. PT 개발자 역할 (또는 추가한 역할) 선택 → 배정
4. 저장

9. 화면 접속 확인¶

재로그인 후 다음 순서로 확인합니다.

10. DB로 보는 전체 연결 구조¶

6단계 등록이 만들어내는 DB 레코드와 연결 관계입니다.

erDiagram
    sys_menu {
        varchar id PK
        varchar parent_id
        varchar type
        varchar url
    }
    sys_message {
        varchar message_code PK
        varchar message_name
        varchar message_type
        varchar locale
    }
    sys_rbac_auth_tmpl {
        varchar category PK
        varchar id PK
        varchar parent_id PK
        varchar perm1_code
        varchar perm2_code
        varchar perm3_code
        varchar perm4_code
    }
    sys_rbac_auth_name {
        varchar id PK
        varchar name
    }
    sys_rbac_auth_entry {
        varchar auth_id PK
        varchar menu_id PK
        boolean perm1
        boolean perm2
        boolean perm3
        boolean perm4
    }
    sys_rbac_role_name {
        varchar id PK
        varchar name
    }
    sys_rbac_role_entry {
        varchar id PK
        varchar auth_id PK
    }

    sys_menu ||--o{ sys_rbac_auth_tmpl : "menu_id 참조"
    sys_menu ||--o{ sys_rbac_auth_entry : "menu_id 참조"
    sys_rbac_auth_name ||--o{ sys_rbac_auth_entry : "auth_id"
    sys_rbac_role_name ||--o{ sys_rbac_role_entry : "id"
    sys_rbac_auth_name ||--o{ sys_rbac_role_entry : "auth_id"

실제 생성 데이터 요약¶

-- [1] SYS0103: 메뉴
INSERT INTO sys_menu (id, parent_id, type, url, level) VALUES
    ('PT',    '',    'MENU',   null,       0),
    ('PT01',  'PT',  'FOLDER', null,       1),
    ('PT0101','PT01','URL',    '/pt/0101', 2);

-- [2] SYS0102: 메시지
INSERT INTO sys_message (message_code, message_name, message_type, locale) VALUES
    ('MENU.PT',         'PT 관리',           'MENU',       'ko'),
    ('MENU.PT01',       'PT 기본관리',        'MENU',       'ko'),
    ('MENU.PT0101',     '가상 코드 관리',     'MENU',       'ko'),
    ('PT0101.BREADCRUMB', 'PT 관리 / 가상 코드 관리', 'BREADCRUMB', 'ko');

-- [3] SYS0201: 권한 템플릿
INSERT INTO sys_rbac_auth_tmpl (category, id, parent_id, perm1_code, perm2_code, perm3_code, perm4_code)
    VALUES ('PT', 'PT0101', 'PT01', 'READ', 'CREATE', 'UPDATE', 'DELETE');

-- [4] SYS0202: 권한 그룹 + 권한 항목
INSERT INTO sys_rbac_auth_name (id, name) VALUES ('{UUID}', 'PT 전체 권한');
INSERT INTO sys_rbac_auth_entry (auth_id, category, menu_id, parent_menu_id, perm1, perm2, perm3, perm4, ...)
    VALUES ('{UUID}', 'PT', 'PT0101', 'PT01', true, true, true, true, ...);

-- [5] SYS0204: 역할에 권한 그룹 추가
INSERT INTO sys_rbac_role_entry (id, auth_id) VALUES ('{역할 UUID}', '{권한 UUID}');

11. 권한 코드 변환 원리¶

hera-v4 보안 설정이 sys_rbac_auth_tmpl의 권한 코드를 Spring Security ROLE로 어떻게 바꾸는지 알면 @PreAuthorize 어노테이션을 직관적으로 작성할 수 있습니다.

[DB] sys_rbac_auth_tmpl.id        = PT0101
[DB] sys_rbac_auth_tmpl.perm1_code = READ
     ↓  변환 규칙: ROLE_{ID}_{PERM_CODE}
[Spring Security] ROLE_PT0101_READ
     ↓
[코드] @PreAuthorize("hasRole('ROLE_PT0101_READ')")

새 메뉴를 추가할 때도 권한 코드를 따로 외울 필요 없이 ROLE_{메뉴ID}_{템플릿에_등록한_PERM_CODE} 패턴 하나만 기억하면 충분합니다.

12. 이 챕터 요약¶

Ch 1. hera-v4 읽는 법      — 14모듈 구조, 두 가지 요청 흐름 이해
Ch 2. 로컬 환경 셋업       — JDK 25, 라이선스, hera-webapp 로컬 실행
Ch 3. sys0101 깊이 보기    — 8단계 요청 흐름을 코드로 추적
Ch 4. 가상 코드 관리 만들기 — 13개 파일로 신규 CRUD 메뉴 구현
Ch 5. 메뉴·권한·메시지 등록 — DB 등록으로 메뉴 노출 + 권한 적용