SimpleHR project

관리자 등급 및 권한 관리 스펙

conceptedited by Cairni · 방금 · AIv8

개요

Simple HR 프로젝트의 관리자 모드에서 관리자 계정을 등급별로 관리하고 권한을 제어하는 스펙이다. 0608 수정사항과 0612 수정사항에 따라 기업 가입 시 4종 관리자 등급이 자동 생성되며, 일반관리자의 부서별 조회 권한 제한 로직이 명확히 정의되어 있다. 0702 수정사항에서 조직관리자의 메뉴 접근 권한 문제 및 최고관리자 역할 전환 절차가 추가로 확인·수정되었다. 0709 수정사항에서는 관리자 등급 변경 미반영, 최초 등록자 최고관리자 권한 유지, 결재선 변경 미적용, 조직관리자 부서 범위 제한 등 다수의 버그가 신규 접수되었다. 0714 수정사항에서 관리자별 권한 구분, 세션 캐시로 인한 권한 유지 문제, 조직관리자 부서 범위 제한, 인사담당·재무담당 별도 권한 등이 추가로 수정·확인되었다. 0715 수정사항에서 관리자 설정의 별도 권한(인사, 급여) 항목 제거가 미완료 과제로 접수되었으며, 결재선 변경 미적용 이슈는 결재선 미선택 시 자동 결재선이 적용되는 구조임을 명시하는 안내 텍스트를 추가하여 부분 해소되었다.

관리자 등급 구분

순서	등급	설명
1	최고관리자	전사 모든 부서·직원 관리 권한, 관리자 변경 권한 포함
2	조직관리자	소속 부서 직원만 관리 가능; 메뉴 접근 권한은 유형관리 UI에서 별도 조정 필요
3	중간관리자	특정 조직 범위 내 관리 권한
4	일반관리자	권한 조직에만 조회 권한, 부서 스코프 제한 적용

기업 가입 시 자동 생성

새로운 기업이 Simple HR에 가입할 때, bootstrap_admin_employee 함수가 실행되면서 다음이 자동으로 진행된다: fix-task-0612.md

관리자 등급 자동 생성: 최고관리자, 조직관리자, 중간관리자, 일반관리자 4종이 자동 생성됨
첫 관리자 직원 설정: 가입 즉시 첫 번째 관리자 직원의 admin_role_id가 최고관리자로 자동 설정됨
권한 설정 단순화: 기업 관리자가 별도로 유형 관리 > 최고 관리자 생성 단계를 거칠 필요 없음

권한 범위 정의

최고관리자

전사 모든 부서, 직원 관리 가능
관리자 등급 및 권한 배정 담당
부서 스코프 제한 없음
일반관리자를 최고관리자로 변경 가능

조직관리자 · 중간관리자

지정된 조직 범위 내에서만 관리 권한 보유
권한 조직 범위 내 직원 조회 및 관리 가능
조직관리자 부서 범위 제한 (0714 수정 완료): 조직관리자는 소속 부서 직원만 조회 가능하도록 수정. 근로계약서 목록/요약/만료예정 API에 admin scope 필터링 적용. fix-task-0714 (26년 07월 14일 수정사항)
메뉴 권한 이슈 (0702 확인): 현재 모든 기본 역할의 menu_keys가 ["*"](전체 허용)으로 설정되어 있어, 조직관리자도 모든 메뉴에 접근 가능한 상태. 유형관리 UI에서 조직관리자의 메뉴 접근 권한을 명시적으로 조정해야 해결됨. fix-task-0702 (26년 07월 02일 수정사항)
근로계약서·근태 접근 제한 (0714 수정 완료): 근로계약서와 근태 데이터는 최고관리자, 인사담당, 재무담당만 조회 가능하도록 수정. 조직관리자는 근로계약서 탭과 발송 버튼이 권한 없을 시 숨겨짐. fix-task-0714 (26년 07월 14일 수정사항)

일반관리자 (권한 조직 제한)

권한 조직 배정 여부에 따른 동작:

권한 조직 배정됨 (1개 이상): 지정된 부서만 직원 조회 가능
권한 조직 미배정 (0개): 직원 조회 불가

적용 범위:

직원관리: 권한 조직 범위 내 직원만 표시
임직원 정보, 메시지 보내기: 부서 스코프 제한 없음 (전사 직원 조회 가능)

권한 변경:

최고관리자만 일반관리자를 최고관리자로 변경 가능 fix-task-0608.md

최고관리자 역할 전환 절차 (0702 확인)

관리자 등급 변경 관련 이슈

현상 1 (0714 정상 동작 확인): 직원관리 > 관리자관리에서 관리자 상세 드로어로 등급 변경 후 저장하면 DB에 반영되고 목록에도 즉시 갱신됨. fix-task-0714 (26년 07월 14일 수정사항)
현상 2 (0714 수정 완료): 최초 등록자(최고관리자)를 조직관리자로 변경해도 최고관리자 권한으로 보이던 문제 — DB 반영은 정상이었으나 브라우저 세션 캐시가 갱신되지 않아 재로그인 전까지 이전 권한 유지됨. 권한 변경 시 "재로그인하면 적용됩니다" 안내 토스트 추가. fix-task-0714 (26년 07월 14일 수정사항)
추가 확인: 이상재 팀장이 조직관리자로 변경되었으나 전체가 보인 이유는 실서버에서 본사의 조직장으로 설정되어 있기 때문. 권한 조직이 "관리자가 속한 조직 및 하위 조직"이면 본사 하위 전체 부서가 포함되어 전사 데이터가 조회됨 — 코드 버그가 아닌 설정 문제. fix-task-0714 (26년 07월 14일 수정사항)
현상 3 (0715 부분 해소): 최고관리자가 결재선을 변경해도 기존 조직관리자에게 결재가 가도록 유지되어 수정이 적용되지 않음. 원인: 결재선 미선택 시 조직도 기반 자동 결재선(본사 조직장=조직관리자)이 적용됨. 결재선 템플릿 수정과 자동 결재선은 별개 시스템. 결재선 드롭다운에 amber 색상 안내 텍스트 추가하여 미선택 시 자동 결재선 적용됨을 명시. fix-task-0709 fix-task-0715 수정사항
현상 4 (0715 미완료): 관리자 설정에서 별도 권한(인사, 급여) 항목 제거 — 미구현 상태로 개발 대기 중. fix-task-0715 수정사항

최초 가입한 최고관리자를 조직관리자로 변경하려면, 기업 내 최고관리자가 반드시 1명 이상 유지되어야 함
절차: 다른 직원을 먼저 최고관리자로 지정 → 새 최고관리자가 기존 최고관리자의 역할을 조직관리자로 변경
본인 역할 변경은 시스템에서 차단됨 (이미 정상 동작 중) fix-task-0702 (26년 07월 02일 수정사항)

관리자 등급 등록 시 주의사항

권한 조직 설정 방식

직접 부서 선택: 커스텀 관리자 유형 설정 시 "권한 조직"에서 조회 가능 부서를 직접 선택해야 해당 부서 직원만 조회됨 fix-task-0714 (26년 07월 14일 수정사항)
자동 배정: 부서를 선택하지 않고 "관리자가 속한 조직 및 하위 조직"을 선택하면 관리자의 소속 부서 및 하위 부서 전체가 자동으로 배정됨 — 본사 조직장인 경우 전사 데이터가 조회될 수 있으므로 주의 fix-task-0714 (26년 07월 14일 수정사항)

관리자 > 관리자 등록 화면에서 최고관리자를 선택하여 등록할 때, 다음 조건이 모두 충족되어야 정상 등록된다:

1.admin_role_id: 최고관리자 역할로 설정
2.admin_level: 1(최고관리자 레벨) 이어야 함
3.is_system: True로 설정되어야 함

이전 버그: Bootstrap 과정에서 admin_role_id만 최고관리자로 설정하고 admin_level은 3(부서장)으로 방치하여 권한 체크 실패 발생

수정 내용: _get_actor_admin_level() 함수에서 is_system=True일 경우 무조건 1을 반환하도록 동기화 + 에러 코드별 토스트 메시지 추가

권한 접근 오류 처리

메뉴 접근 권한이 없는 페이지에 접근할 경우, 기존 에러 화면 대신 "접근 권한이 없습니다" 안내 메시지를 표시하도록 수정 완료. fix-task-0702 (26년 07월 02일 수정사항)

수정 완료 항목

cairni:kanban

{
  "title": "관리자 관리 수정 현황",
// 0709 버그 항목은 미해결(대기) 컬럼 참조
  "columns": [
    {
      "name": "완료",
      "color": "green",
      "items": [
        {
          "text": "기업 가입 시 4종 관리자 등급 자동 생성 (bootstrap_admin_employee에 _ensure_default_admin_roles 추가)",
          "ref": "[[src:fix-task-0612.md]]"
        },
        {
          "text": "첫 관리자 직원의 admin_role_id를 최고관리자로 자동 설정",
          "ref": "[[src:fix-task-0612.md]]"
        },
        {
          "text": "일반관리자를 최고관리자로 변경 가능하도록 수정",
          "ref": "[[src:fix-task-0608.md]]"
        },
        {
          "text": "일반관리자 권한 조직 미배정 시 조회 안내 메시지 추가",
          "ref": "[[src:fix-task-0608.md]]"
        },
        {
          "text": "메뉴 권한 없는 페이지 접근 시 '접근 권한이 없습니다' 안내 표시로 수정",
          "ref": "[[src:fix-task-0702 (26년 07월 02일 수정사항)]]"
        },
        {
          "text": "최초 최고관리자 → 조직관리자 역할 전환 절차 확인 완료 (본인 역할 변경 차단, 신규 최고관리자 먼저 지정 방식)",
          "ref": "[[src:fix-task-0702 (26년 07월 02일 수정사항)]]"
        },
        {
          "text": "관리자 권한 구분 수정 — 근로계약서·근태는 최고관리자·인사담당·재무담당만 조회 가능, 조직관리자는 소속 부서만 조회",
          "ref": "[[src:fix-task-0714 (26년 07월 14일 수정사항)]]"
        },
        {
          "text": "권한 변경 시 세션 캐시 미갱신 문제 — 재로그인 안내 토스트 추가",
          "ref": "[[src:fix-task-0714 (26년 07월 14일 수정사항)]]"
        },
        {
          "text": "관리자 등급 변경 정상 동작 확인 (0714)",
          "ref": "[[src:fix-task-0714 (26년 07월 14일 수정사항)]]"
        },
        {
          "text": "계약서 목록/요약/만료예정 API에 admin scope 필터링 적용 (조직관리자 부서 범위 제한)",
          "ref": "[[src:fix-task-0714 (26년 07월 14일 수정사항)]]"
        },
        {
          "text": "최고관리자 등록 시 admin_level과 is_system 동기화, 에러 토스트 메시지 추가",
          "ref": ""
        }
      ]
    },
    {
      "name": "미해결 (버그 접수)",
      "color": "red",
      "items": [
        {
          "text": "관리자 등급 변경 후 실제 반영 안 됨 (직원관리 > 관리자관리)",
          "ref": "[[src:fix-task-0709]]"
        },
        {
          "text": "최초 등록자(최고관리자)를 조직관리자로 변경해도 최고관리자 권한 유지됨",
          "ref": "[[src:fix-task-0709]]"
        },
        {
          "text": "결재선 변경 후 미적용 — amber 안내 텍스트 추가로 부분 해소, 자동 결재선 구조는 별개 시스템으로 유지",
          "ref": "[[src:fix-task-0715 수정사항]]"
        },
        {
          "text": "(미완료) 관리자 설정에서 별도 권한(인사, 급여) 항목 제거",
          "ref": "[[src:fix-task-0715 수정사항]]"
        },
        {
          "text": "(미완료) 인사관리자/급여관리자 별도 권한 설정 시 관련 메뉴 자동 열림 미구현",
          "ref": "[[src:fix-task-0714 (26년 07월 14일 수정사항)]]"
        }
      ]
    }
  ]
}

관리자 등급 계층도

참고

일반관리자는 권한 조직 배정 여부에 따라 조회 범위가 결정된다. 2026년 06월 기준, 권한이 없는 경우 안내 메시지가 추가되어 사용자 혼란을 줄이도록 개선되었다. fix-task-0608.md 기업 신규 가입 시에는 bootstrap_admin_employee 함수가 자동으로 4종 관리자 등급을 생성하므로, 사용자가 추가 설정 없이 즉시 관리자 권한 체계를 활용할 수 있다. fix-task-0612.md 최고관리자 등록 시 admin_level과 is_system 필드가 반드시 동기화되어야 하며, 이전 데이터의 불일치는 배포 전 프로덕션 DB 데이터 보정이 필요하다. 조직관리자의 메뉴 접근 권한은 현재 전체 허용(["*"]) 상태이므로, 운영자가 유형관리 UI에서 직접 권한을 조정해야 한다. 또한 탭 단위 숨김 외에 직원 상세 내 근로계약서 발송 버튼 등 세부 항목까지 권한 체계를 연결하는 방식은 추가 논의가 필요하다. fix-task-0702 (26년 07월 02일 수정사항) 2026년 07월 09일 기준 접수된 버그 중, 관리자 등급 변경 미반영 및 세션 캐시 권한 유지 문제·조직관리자 부서 범위 제한은 0714 수정사항에서 해결되었다. 결재선 변경 미적용 이슈는 0715에서 결재선 드롭다운에 amber 안내 텍스트를 추가하여 부분 해소되었으며(자동 결재선 구조는 별개 시스템으로 유지), 결재 관리 스펙 참조. fix-task-0709 fix-task-0714 (26년 07월 14일 수정사항) fix-task-0715 수정사항 관리자 설정의 별도 권한(인사, 급여) 항목 제거 및 인사담당·재무담당의 별도 권한(전사 메뉴 자동 열림)은 아직 미구현 상태로 추가 개발이 필요하다.