어드민 개발 명세 (FRD)¶

디에듀 첫 어드민의 백엔드·프론트 구현 골격이다. 조회 중심의 1단계를 먼저 만들고, 2·3단계는 구조만 미리 잡아 둔다. 대부분은 기존 도메인을 조회·집계하는 일이고, 새로 만드는 건 어드민 계정과 운영 로그 정도다. 단계별 도입·권한축은 prd, 아키텍처는 backend-architecture, 회원 역할 모델은 member를 본다. 고객 관리가 다루는 이메일·휴대폰, 그리고 어드민 계정·비밀번호·권한 운영 값 같은 민감 정보는 본문에 싣지 않고 구조와 권한 정책만 다루며, 실제 값은 운영 DB와 접속 관리(infra)에 둔다.

기술 접근 · 아키텍처¶

별도 어드민 영역(분리된 인증·권한 경계). 1단계는 Read Only — 조회 API만, 조작 API 없음.
어드민 API는 관리자 전용 역할로 보호(일반 사용자 토큰 접근 차단). member 역할(TEACHER/STUDENT/PARENT)과 별개로 어드민 권한축(Master / 관리자 / 운영 사용자) 적용.

처리흐름: - 권한 체크: 요청 → 어드민 인증 → 권한축 검사(메뉴/액션 가시성·쓰기 허용) → 처리. 위험 액션(운영 정책 수정)은 권한 상위 + 단계 게이트(3단계). - 로그 적재: 설정 변경/시스템 이벤트(스터디룸 생성·최대치 도달) 발생 시 운영 로그 기록(변경 전/후 포함).

API · 데이터 모델¶

API (역할별)¶

1단계 조회 엔드포인트(개략): 대시보드 지표 집계, 사용자 목록·검색, 스터디룸 목록·상세(정보/로그). 모두 GET 계열.
2·3단계: 어드민 계정 CRUD, 스터디룸 운영 정책 수정 — 쓰기 엔드포인트는 권한 상위(Master/관리자)로 제한, 비밀번호는 초기화만(직접 변경 불가).
구체 경로·role prefix 확정값은 BE 구현 시 member/studyroom §관련 코드에 반영.

데이터·도메인¶

신규 핵심 도메인 신설보다 기존 도메인 조회·집계 위주: 회원(member), 스터디룸(studyroom), 수업노트·질문/답변·과제·후기.
신규 — 어드민 계정: 권한축(Master/관리자/운영 사용자)·활성화·생성/수정일·연락처. 등록 시 초기 비밀번호 자동 설정.
신규 — 운영 로그: DB ID·일시·변경자(이름+ID)·내용·변경 전/후(없으면 -). 로그 유형 = 설정 변경 로그(인원/용량 제한) + 시스템 로그(스터디룸 생성·최대치 도달). "설명 가능한 운영"의 근거.
검색 키(이름/이메일/휴대폰)는 검색 파라미터로만 사용하며, 노출 값은 권한·마스킹 정책을 따른다(실값 본문 미기재).

의존성 · 영향 범위¶

회원·스터디룸·수업노트·질문/답변·과제·후기 기존 도메인 조회·집계에 의존(신규 쓰기 최소).
접근 계정·시크릿은 접속 관리 infra에 격리.
신고 검수(후기 등) 큐와 콘텐츠 관리 화면 연동.

예외·검증¶

권한 부족 → 403 / 메뉴·액션 비노출. 어드민 계정 등록 시 ID 중복 확인 필수. 비밀번호 직접 변경 불가(초기화만).
조회 우선·위험 기능 후순위 원칙으로, 1단계에서는 파괴적 작업 노출 자체를 차단.

테스트 계획¶

권한별 접근 매트릭스(Master/관리자/운영 사용자 × 조회/쓰기), 로그 적재 정확성(변경 전/후), 검색 필터 정확성, 권한 부족 403, 비밀번호 초기화 경로. → qa-playbook.

작업 분해 (이슈 링크)¶

1단계: 대시보드 집계 API · 사용자 목록/검색 · 스터디룸 목록/상세/로그.
2단계: 어드민 계정 도메인·CRUD·권한축·비밀번호 초기화.
3단계: 스터디룸 운영 정책 수정(개별 항목)·게이트.