1. 관리자 콘솔 사용하기
구독·결제 시스템의 관리자 콘솔은 구독 현황을 보고, 결제를 관리하고, 서비스와 요금제를 설정하는 웹 화면입니다. 이 문서는 콘솔에 처음 들어가는 방법(로그인)과 화면 전체 구조, 그리고 두 가지 역할에 따라 보이는 메뉴 차이를 안내합니다.
🍎
1.1 로그인하기
관리자 콘솔의 모든 화면은 로그인을 해야 볼 수 있습니다. 로그인하지 않은 상태로 콘솔 주소에 접속하면 자동으로 로그인 화면으로 이동합니다.
로그인 절차
- 브라우저에서 콘솔 로그인 주소(
/admin/login)에 접속합니다. - 이메일과 비밀번호를 입력합니다. 비밀번호 칸 오른쪽의 눈 아이콘을 누르면 입력한 비밀번호를 잠깐 확인할 수 있습니다.
- 로그인 버튼을 누릅니다. 이메일과 비밀번호가 모두 입력되기 전에는 버튼이 회색(비활성)으로 눌리지 않으며, 두 칸을 모두 채우면 자동으로 활성화됩니다.
- 로그인에 성공하면 대시보드 화면으로 들어갑니다.
💡참고: 로그인 폼 아래의 「전체 매뉴얼 보기 (사용자·개발자)」 링크로 로그인 전에도 이 매뉴얼을 새 창에서 열 수 있습니다.
로그인 화면의 공지사항
로그인 카드 아래에는 공지사항 카드가 표시됩니다. 시스템 관리자가 콘솔의 공지사항 메뉴에서 작성한 글(배포내역·서버작업내역 등) 중 게시 상태인 최근 5건이 최신순으로 나옵니다.
- 각 공지 앞에는 타입 배지(배포/작업/알림/기타)가 붙어 공지 성격을 한눈에 구분할 수 있습니다.
- 공지를 누르면 화면의 50% 크기 모달 창으로 본문이 열립니다(마크다운 공지는 서식 적용). × 버튼·바깥 영역 클릭·ESC 키로 닫습니다. 읽기만 가능하며 로그인 전 누구나 볼 수 있습니다.
- 게시된 공지가 하나도 없으면 공지사항 카드 자체가 나타나지 않습니다.
- 공지 작성·수정·삭제 방법은 아래 공지사항 관리를 참고하세요.
로그인에 실패하면 화면 위쪽에 빨간 안내 문구가 나타납니다. 자주 보게 되는 메시지는 다음과 같습니다.
| 상황 | 화면에 나오는 안내 |
|---|---|
| 이메일이나 비밀번호가 틀림 | 이메일 또는 비밀번호가 올바르지 않습니다 |
| 잠긴 계정으로 로그인 시도 | 계정이 잠겼습니다. 잠시 후 다시 시도해주세요 |
| 사용 중지된 계정 | 비활성화된 계정입니다. 관리자에게 문의하세요 |
| 비밀번호를 아직 설정하지 않은 계정 | 비밀번호 설정이 필요합니다. 안내 메일을 확인해주세요 |
| 같은 IP에서 짧은 시간에 너무 많이 시도 | 로그인 시도가 너무 많습니다. 잠시 후 다시 시도해주세요 |
⚠️주의: 비밀번호를 5번 연속 틀리면 계정이 15분간 잠깁니다(잠기는 순간에는 일반 실패 안내가 나오고, 그다음 시도부터 "계정이 잠겼습니다" 안내가 표시됩니다). 잠겨 있는 동안에는 올바른 비밀번호를 넣어도 들어갈 수 없으며, 15분이 지나면 자동으로 풀립니다. 또한 같은 IP에서 1분에 10회를 넘겨 시도하면 잠시 로그인 시도가 차단됩니다. (5회·15분은 기본값으로, 전체 관리자가 전체 설정에서 조정할 수 있습니다.)
참고: 로컬 개발 환경(
environment == "dev")에서는 편의를 위해 로그인 폼에 개발용 이메일·비밀번호가 미리 채워질 수 있습니다. 스테이징(stg)·운영(prod) 등 외부에 노출되는 환경에서는 자동입력이 동작하지 않으므로, 실제 콘솔에서는 항상 직접 입력해야 합니다.
처음 로그인 — 비밀번호 설정
새로 계정을 만들었거나 비밀번호 재설정을 요청한 경우, 이메일로 비밀번호 설정 링크가 전달됩니다.
- 이메일에서 받은 링크를 브라우저로 엽니다.
- 새 비밀번호(10자 이상)와 비밀번호 확인을 같게 입력합니다.
- 설정 버튼을 누릅니다. 완료되면 로그인 화면으로 이동하며, 이제 새 비밀번호로 로그인할 수 있습니다.
⚠️주의: 이 설정 링크는 한 번만 사용할 수 있습니다. 유효시간은 받은 경로에 따라 다릅니다 — 계정 생성·관리자가 보낸 재설정 메일은 48시간, 로그인 화면에서 본인이 요청한 메일은 2시간입니다. 이미 사용했거나 시간이 지난 링크를 다시 열면 설정 화면이 열리지 않고, "만료되었거나 이미 사용된 링크입니다" 안내와 함께 로그인 화면으로 이동합니다. 그럴 때는 아래 비밀번호 찾기로 다시 요청하세요.
참고: 비밀번호 재설정을 완료하면, 다른 기기·다른 브라우저에 남아 있던 로그인도 모두 자동으로 로그아웃됩니다.
비밀번호를 잊어버렸을 때 — 비밀번호 찾기
관리자에게 요청하지 않고 직접 재설정할 수 있습니다.
- 로그인 화면 아래의 「비밀번호를 잊으셨나요?」를 누릅니다.
- 가입하신 이메일 주소를 입력하고 재설정 링크 받기를 누릅니다.
- 메일함에서 「비밀번호 재설정하기」 버튼을 눌러 링크를 엽니다.
- 새 비밀번호(10자 이상)와 비밀번호 확인을 같게 입력하고 저장합니다.
- 로그인 화면으로 이동하면 새 비밀번호로 로그인합니다.
| 항목 | 내용 |
|---|---|
| 링크 유효시간 | 2시간 (관리자가 보낸 재설정 메일 48시간과 다릅니다) |
| 사용 횟수 | 1회 — 사용하면 즉시 무효가 됩니다 |
| 요청 제한 | 같은 이메일로 시간당 5회까지. 초과분은 메일이 발송되지 않습니다 |
| 로그인 중인 세션 | 요청만으로는 로그아웃되지 않습니다. 실제로 비밀번호를 바꾼 시점에 모든 기기에서 로그아웃됩니다 |
💡안내 문구가 항상 같은 이유: 가입 여부와 관계없이 "가입된 계정이 있으면 링크를 보냈습니다"라고만 표시됩니다. 응답이 달라지면 로그인하지 않고도 특정 이메일의 가입 여부를 확인할 수 있기 때문입니다. 메일이 오지 않으면 ① 주소를 정확히 입력했는지 ② 스팸함 ③ 계정이 정지·삭제 상태는 아닌지 순으로 확인하고, 그래도 안 되면 시스템 관리자에게 문의하세요.
참고: 정지(DISABLED)·삭제된 계정은 이 방법으로 되살릴 수 없습니다(관리자만 복구 가능). 로그인 실패로 잠긴 계정은 비밀번호를 재설정하면 잠금도 함께 풀립니다.
로그아웃
화면 왼쪽 아래(사용자 블록 밑)의 로그아웃 버튼을 누르면 즉시 로그아웃되고 로그인 화면으로 돌아갑니다.
💡참고: 세션은 30분간 활동이 없으면 자동 로그아웃되고, 활동이 있더라도 로그인 후 12시간이 지나면 절대 만료되어 다시 로그인해야 합니다(보안상 세션 수명 제한).
참고: 세션이 만료된 뒤에는 브라우저의 뒤로가기 버튼을 눌러도 이전 관리자 화면이 다시 보이지 않고 로그인 화면으로 이동합니다. 관리자 화면은 브라우저에 캐시되지 않도록 설정되어 있어(
Cache-Control: no-store), 뒤로가기 시에도 항상 서버가 로그인 상태를 다시 확인합니다.
내 정보(프로필) 수정
화면 왼쪽 아래의 내 이메일(사용자 블록) 을 누르면 내 정보 화면(/admin/profile)으로 이동합니다. 역할(시스템 관리자/서비스 담당자)과 무관하게 누구나 사용할 수 있습니다.
- 기본 정보: 이메일(로그인 아이디)·전화번호를 수정합니다. 이메일 변경 시 중복 여부를 확인합니다.
- 비밀번호 변경: 현재 비밀번호를 확인한 뒤 새 비밀번호로 변경합니다. 변경하면 보안을 위해 다른 기기의 로그인이 모두 해제됩니다(현재 기기는 유지).
없는 주소·권한 없는 주소로 접근하면
- 로그인하지 않은 상태: 로그인 화면과 매뉴얼 페이지만 접근할 수 있습니다. 콘솔(
/admin/...) 주소로 접근하면 로그인 화면으로 이동합니다. - 로그인한 상태: 존재하지 않는 주소나 권한이 없는 주소(예: 서비스 담당자가 SYSTEM_ADMIN 전용 메뉴 URL을 직접 입력)로 접근하면 404 페이지가 표시됩니다. 페이지의 홈으로 버튼을 누르면 홈(
/→ 대시보드)으로 돌아갑니다. - 브라우저로 없는 주소에 접근하면: 콘솔 밖의 존재하지 않는 주소를 브라우저로 열어도 원시 JSON(
{"detail":"Not Found"})이 아니라 홈으로 링크가 있는 404 페이지가 표시됩니다(사람이 주소를 잘못 입력한 경우 안내). - 외부 서비스용 API 클라이언트(요청 헤더
Accept: application/json)의 404 등 오류 응답은 이 규칙과 무관하게 기존 JSON 형식 그대로 유지됩니다.
1.2 두 가지 역할 — 무엇을 볼 수 있나
관리자 계정에는 두 가지 역할이 있습니다. 역할에 따라 볼 수 있는 메뉴와 데이터 범위가 다릅니다.
- SYSTEM_ADMIN 전체 관리자 — 모든 서비스와 모든 데이터에 접근합니다.
- SERVICE_MANAGER 서비스 담당자 — 자신이 담당하는 서비스만 보고 관리합니다.
역할별 차이 한눈에 보기
| 항목 | SYSTEM_ADMIN 전체 관리자 | SERVICE_MANAGER 서비스 담당자 |
|---|---|---|
| 대시보드 | 볼 수 있음 (전체 기준) | 볼 수 있음 (담당 서비스 기준) |
| 구독 | 모든 서비스의 구독 | 담당 서비스의 구독만 |
| 결제 | 모든 서비스의 결제 | 담당 서비스의 결제만 |
| 정산 | 볼 수 있음 | 담당 서비스 기준 |
| 요금제 | 볼 수 있음 | 담당 서비스 기준 |
| 서비스 (등록·키 발급) | 볼 수 있음 | 메뉴에 보이지 않음 |
| 계정(관리자) 관리 | 볼 수 있음 | 메뉴에 보이지 않음 |
| 공지사항 관리 | 볼 수 있음 | 메뉴에 보이지 않음 |
| 전체 설정 | 볼 수 있음 | 메뉴에 보이지 않음 |
| 감사 로그 | 볼 수 있음 | 메뉴에 보이지 않음 |
⚠️중요: 서비스 담당자가 자신의 담당 범위를 벗어난 구독에 주소를 직접 입력해 접근하더라도 "찾을 수 없음"으로 처리됩니다. 다른 서비스의 정보가 있는지 여부조차 노출하지 않기 위한 안전장치입니다.
쉽게 말하면, 전체 관리자는 "건물 전체 마스터키", 서비스 담당자는 "내 사무실 열쇠"를 가진 것과 같습니다.
1.3 전체 메뉴 구조
로그인하면 왼쪽에 메뉴(사이드바)가 보입니다. 맨 위 브랜드 영역에는 Payment 로고 옆에 최신 배포 공지 제목(공지사항의 배포 타입 게시글 중 최신 1건)이 회색 작은 글씨로 표시되어, 현재 서버가 어떤 배포 버전인지 어느 화면에서든 확인할 수 있습니다(게시된 배포 공지가 없으면 표시되지 않음). 그 아래 현재 시각(한국 시간) 이 초 단위로 갱신되어 표시되고, 이어지는 메뉴는 두 묶음으로 나뉩니다.
현황 (모든 역할에게 보임)
| 메뉴 | 하는 일 |
|---|---|
| 대시보드 | 구독·결제·매출 현황을 그래프와 숫자로 요약해서 봅니다. (SYSTEM_ADMIN에게는 상단에 운영 점검 배너가 뜰 수 있습니다 — 최근 30일 이메일 발송 실패·수동 검토 필요 건수를 보여주고, 클릭하면 감사 목록에서 해당 항목만 필터해 조치할 수 있습니다.) |
| 구독 | 구독 목록을 검색·필터링하고, 구독 상세에서 강제취소·만료일 연장·재결제를 합니다. → 구독 관리 |
| 결제 | 개별 결제 내역을 확인합니다. |
| 정산 | 기간별 매출·정산 현황을 봅니다. |
| 요금제 | 요금제를 만들고 가격·결제주기·할인 등을 설정합니다. |
관리 (전체 관리자에게만 보임)
| 메뉴 | 하는 일 |
|---|---|
| 서비스 | 구독·결제를 사용할 서비스를 등록하고, 서비스 키를 발급합니다. 서비스 상세에서 등록 카드(카드 보관함)도 봅니다. → 카드 관리 |
| 계정 | 관리자 계정을 만들고 역할(전체 관리자/서비스 담당자)을 부여합니다. |
| 전체 설정 | 접근 허용 IP 등 시스템 전반 설정을 관리합니다. |
| 감사 로그 | 누가 언제 무엇을 했는지 기록을 조회합니다. |
| 공지사항 | 로그인 화면에 노출할 공지(배포내역·서버작업내역)를 작성·수정·삭제합니다. → 공지사항 관리 |
💡참고: 서비스 담당자로 로그인하면 "관리" 묶음(서비스·계정·전체 설정·감사 로그)은 메뉴에 아예 나타나지 않습니다.
1.4 공통 UI — 화면 어디나 비슷한 요소들
콘솔의 여러 화면은 같은 방식으로 동작합니다. 한 번 익히면 모든 화면에서 똑같이 쓸 수 있습니다.
- 목록 화면: 위쪽에 검색창과 필터(드롭다운)가 있고, 그 아래 표가 나옵니다. 표의 각 행을 클릭하면 그 항목의 상세 화면으로 이동합니다.
- 정렬: 표 머리글 중 정렬 가능한 항목(예: 등록일, 만료일)을 누르면 오름차순/내림차순으로 정렬됩니다.
- 페이지 넘김: 표 아래의 이전·숫자·다음 버튼으로 페이지를 넘깁니다. "총 N건 중 몇–몇" 표시로 전체 개수를 확인할 수 있습니다.
- 검색·필터 초기화: 검색어나 필터를 하나라도 쓰면 "초기화" 링크가 나타나며, 누르면 모든 조건이 풀립니다.
- 날짜 필터: 구독·결제·정산 등 목록의 날짜(기간) 필터는 오늘까지만 선택할 수 있습니다. 미래 날짜는 달력에서 비활성화됩니다(정산의 월 선택기도 이번 달까지). 또한 종료일은 시작일보다 앞으로, 시작일은 종료일보다 뒤로 선택할 수 없습니다(달력에서 해당 범위 비활성화).
- 상태 배지: 구독·결제·카드의 상태는 색깔 배지로 표시됩니다. 예: 활성 비활성
- 위험한 동작의 확인창: 강제취소·카드 비활성화처럼 영향이 큰 버튼을 누르면, 실행 전에 "정말 하시겠어요?" 확인창이 한 번 더 뜹니다. 확인창(모달)이 떠 있는 동안에는 뒤 화면의 스크롤과 클릭이 잠깁니다 — 모달을 닫아야 원래 화면을 조작할 수 있습니다.
- 엑셀 다운로드: 목록 화면에는 현재 검색·필터 조건을 그대로 담아 엑셀로 내려받는 버튼이 있습니다.
- 매뉴얼 열기: 화면 상단 오른쪽의 책 아이콘을 누르면 이 매뉴얼(사용·개발 매뉴얼)이 새 창(탭) 으로 열립니다.
- 다크/라이트 모드: 화면 상단 오른쪽의 달/해 아이콘 버튼을 누르면 누를 때마다 어두운 화면(다크)과 밝은 화면(라이트)이 즉시 전환됩니다. 선택은 이 브라우저에 저장되어 다음에 접속해도 유지되며, 처음에는 사용 중인 OS 설정(다크 모드 여부)을 따릅니다.
- 컴팩트 뷰: 상단 오른쪽의 컴팩트 뷰 체크박스를 켜면 표·여백이 촘촘해져 한 화면에 더 많은 행이 보입니다. 선택은 이 브라우저에 저장되어 유지됩니다.
💡팁: 표에서 무언가를 자세히 보고 싶으면, 버튼을 찾기 전에 일단 그 줄을 클릭해 보세요. 대부분 상세 화면으로 바로 이동합니다.
1.5 공지사항 관리 (전체 관리자 전용)
로그인 화면에 노출되는 공지(배포내역·서버작업내역 안내)를 관리하는 게시판입니다. 왼쪽 메뉴 관리 → 공지사항(/admin/notices)에서 사용하며, 전체 관리자(SYSTEM_ADMIN)만 접근할 수 있습니다.
공지 작성
- 공지사항 목록에서 공지 작성 버튼을 누릅니다.
- 타입을 선택합니다 — 배포 / 작업 / 알림 / 기타 중 하나. 로그인 화면과 목록에 배지로 표시되어 공지 성격을 구분합니다.
- 작업 타입을 선택하면 작업 시작·종료 일시(KST) 입력란이 나타나며 둘 다 필수입니다. 시작일시는 종료일시보다 늦을 수 없습니다(입력 중·저장 시 모두 검사).
- 마크다운으로 작성을 체크하면 본문이 마크다운 문서(굵게, 목록, 표 등)로 표시됩니다. 보안을 위해 본문 안의 HTML 태그는 동작하지 않고 글자 그대로 보입니다.
- 제목(200자 이내)과 내용(10,000자 이내)을 입력합니다. 두 칸 모두 필수입니다.
- 게시 체크박스를 확인합니다 — 체크(기본값)하면 저장 즉시 로그인 화면에 노출되고, 해제하면 저장은 되지만 노출되지 않습니다(임시 저장 용도).
- 상단노출 체크박스 — 체크하면 어드민 전 페이지·로그인 화면 상단 배너에 공지가 노출됩니다. 작업 타입도 이 체크박스가 배너 노출을 결정하며, 체크된 작업 공지는 추가로 종료일시가 지날 때까지만 표시됩니다(기간이 지나면 자동으로 내려감). 다른 타입은 체크를 해제할 때까지 계속 노출됩니다. 상단노출된 작업 공지는 외부 서비스도 무인증 API(
GET /api/v1/work-notices)로 받아 자기 화면 배너로 띄울 수 있습니다(샘플 서비스가 실제 사용). 목록에서는 상단 배지로 확인할 수 있습니다. - 작성 버튼을 누르면 목록으로 돌아가며 완료 표시가 나옵니다.
💡참고: 목록 위의 타입 드롭다운으로 특정 타입(배포/작업/알림/기타)의 공지만 걸러 볼 수 있습니다.
수정·삭제
- 목록에서 공지 행을 클릭하면 수정 화면으로 이동합니다. 제목·내용·게시 여부를 바꾸고 저장을 누릅니다.
- 수정 화면 오른쪽 아래의 삭제 버튼으로 공지를 삭제합니다(확인창이 한 번 더 뜹니다). 삭제는 되돌릴 수 없습니다.
- 게시를 잠시 내리고 싶으면 삭제 대신 게시 체크를 해제하고 저장하세요 — 로그인 화면에서만 사라지고 글은 남습니다.
동작 규칙
- 로그인 화면에는 게시 상태의 최근 5건만 최신순으로 표시됩니다.
- 상단 배너 노출은 상단노출 체크박스로 결정됩니다 — 배너에서 내리려면 수정 화면에서 상단노출을 해제하세요. 작업(WORK) 공지는 상단노출을 켠 상태라도 종료일시가 지나면 배너에서 자동으로 내려갑니다(공지 글 자체는 리스트에 남습니다). 목록 화면에서도 제목 아래에 작업 기간이 작게 표시됩니다.
- 공지 작성/수정 화면은 화면 폭의 80%를 사용합니다(본문을 넓게 편집).
- 공지 작성·수정·삭제는 모두 감사 로그에 기록되며(공지사항 작성/수정/삭제), 상세 칸에 제목·타입·게시 상태가, 시각 칸에 작업 시각이 함께 남습니다.
- 로그인 화면은 로그인 전 누구나 볼 수 있는 화면입니다 — 공지에는 내부 비밀 정보(키·비밀번호·내부 주소 등)를 적지 마세요.
🔗