Project

일반

사용자정보

다운로드 (153 KB)

2025/20.개발산출물/02.개발문서(설계서,설치가이드) » IITP-DABT-API_규격서.md

이환희, 2025-12-23 02:02

 

/* PDF 변환 시 페이지 머리글 및 번호 표시 */
@page {
@top-left {
content: "IITP DABT Admin API 규격서";
font-size: 10pt;
color: #666;
font-family: Arial, sans-serif;
}
@bottom-center {
content: counter(page) " / " counter(pages);
font-size: 10pt;
color: #666;
font-family: Arial, sans-serif;
}
}

IITP DABT Admin
API 규격서

문서 버전: 1.0.0
작성일: 2025-11-12
(주)스위트케이

문서 History

버전 일자 작성자 변경 내용 비고
1.0 2025-11-12 (주)스위트케이 최초 작성 전체 API 규격 정의

목차

  1. API 전체 목록

  2. 개요

    • 1.1 프로젝트 소개
    • 1.2 시스템 아키텍처
    • 1.3 주요 기능
    • 1.4 사용 대상

  3. API 기본 정보

    • 2.1 Base URL
    • 2.2 인증 방식
    • 2.3 공통 헤더
    • 2.4 HTTP 상태 코드

  4. 공통 응답 구조

    • 3.1 ApiResponse 구조
    • 3.2 정상 응답
    • 3.3 에러 응답
    • 3.4 페이징 응답

  5. 에러 코드 정의

    • 4.1 에러 코드 체계
    • 4.2 전체 에러 코드 목록

  6. 공통 값 정의

    • 5.1 공통 코드 그룹
    • 5.2 관리자 역할 코드
    • 5.3 작업 유형 코드
    • 5.4 기타 상수

  7. API 상세 규격 - 인증 API

    • 6.1 사용자 인증 API
    • 6.2 관리자 인증 API

  8. API 상세 규격 - 공통 API

    • 7.1 시스템 정보 API

  9. API 상세 규격 - 사용자 API

    • 8.1 회원 관리 API
    • 8.2 FAQ API
    • 8.3 QnA API
    • 8.4 공지사항 API
    • 8.5 OpenAPI 키 관리 API

  10. API 상세 규격 - 관리자 API

    • 9.1 프로필 관리 API
    • 9.2 FAQ 관리 API
    • 9.3 QnA 관리 API
    • 9.4 공지사항 관리 API
    • 9.5 OpenAPI 키 관리 API
    • 9.6 운영자 계정 관리 API (S-Admin 전용)
    • 9.7 사용자 계정 관리 API

  11. API 상세 규격 - 공통 코드 API

    • 10.1 사용자용 조회 API
    • 10.2 관리자용 상세 조회 API
    • 10.3 관리자용 그룹 관리 API
    • 10.4 관리자용 코드 관리 API

  12. 부록

    • 11.1 데이터 타입 규칙
    • 11.2 URL 파라미터 표기법
    • 11.3 페이징 처리
    • 11.4 정렬 (Sorting)
    • 11.5 TypeScript 타입 활용
    • 11.6 자주 사용하는 공통 코드
    • 11.7 보안 기능

0. API 전체 목록

0.1 권한 레벨

본 문서에서 사용되는 권한 레벨은 다음과 같습니다:

권한 설명 인증 필요
Public 누구나 접근 가능 (인증 불필요) X
Public* 선택적 인증 (비로그인 시 제한된 기능, 로그인 시 전체 기능) 선택적
User 사용자 로그인 필요 O
Admin 관리자 로그인 필요 (ADMIN, EDITOR, VIEWER 모두 가능) O
S-Admin 최고 관리자만 접근 가능 (S-ADMIN 전용) O

참고:

  • User 권한: 일반 사용자로 로그인한 경우
  • Admin 권한: 관리자로 로그인한 경우 (역할 무관)
  • S-Admin 권한: 최고 관리자(S-ADMIN, Supper Admin) 역할만 접근 가능

0.2 인증 API

HTTP 엔드포인트 설명 권한
POST /api/auth/user/login 사용자 로그인 Public
POST /api/auth/user/logout 사용자 로그아웃 User
POST /api/auth/user/refresh 사용자 토큰 갱신 Public
POST /api/auth/admin/login 관리자 로그인 Public
POST /api/auth/admin/logout 관리자 로그아웃 Admin
POST /api/auth/admin/refresh 관리자 토큰 갱신 Public

0.3 공통 API

HTTP 엔드포인트 설명 권한
GET /api/common/health 헬스 체크 Public
GET /api/common/version 버전 정보 조회 Public
GET /api/common/jwt-config JWT 설정 정보 조회 Public

0.4 사용자 API

1) 회원 관리

HTTP 엔드포인트 설명 권한
POST /api/user/email/check 이메일 중복 체크 Public
POST /api/user/register 회원가입 Public
GET /api/user/profile 프로필 조회 User
PUT /api/user/profile 프로필 수정 User
PUT /api/user/password 비밀번호 변경 User

2) FAQ

HTTP 엔드포인트 설명 권한
GET /api/user/faq/list FAQ 목록 조회 Public
GET /api/user/faq/:faqId FAQ 상세 조회 Public
GET /api/user/faq/home FAQ 홈 화면용 조회 Public

3) QnA

HTTP 엔드포인트 설명 권한
GET /api/user/qna/list QnA 목록 조회 Public*
GET /api/user/qna/:qnaId QnA 상세 조회 Public*
POST /api/user/qna QnA 등록 User
DELETE /api/user/qna/:qnaId QnA 삭제 User
GET /api/user/qna/home QnA 홈 화면용 조회 Public*

Public: 로그인 선택적 (로그인 시 추가 기능)

4) 공지사항

HTTP 엔드포인트 설명 권한
GET /api/user/notice 공지사항 목록 조회 Public
GET /api/user/notice/:noticeId 공지사항 상세 조회 Public
GET /api/user/notice/home 공지사항 홈 화면용 조회 Public

5) OpenAPI 키 관리

HTTP 엔드포인트 설명 권한
GET /api/user/openapi/keys OpenAPI 키 목록 조회 User
GET /api/user/openapi/keys/:keyId OpenAPI 키 상세 조회 User
POST /api/user/openapi/keys OpenAPI 키 발급 신청 User
DELETE /api/user/openapi/keys/:keyId OpenAPI 키 삭제 User
POST /api/user/openapi/keys/:keyId/extend OpenAPI 키 기간 연장 User

0.5 관리자 API

1) 프로필 관리

HTTP 엔드포인트 설명 권한
GET /api/admin/profile 관리자 프로필 조회 Admin
PUT /api/admin/profile 관리자 프로필 수정 Admin
PUT /api/admin/password 관리자 비밀번호 변경 Admin

2) FAQ 관리

HTTP 엔드포인트 설명 권한
GET /api/admin/faq FAQ 목록 조회 Admin
GET /api/admin/faq/:faqId FAQ 상세 조회 Admin
POST /api/admin/faq FAQ 생성 Admin
PUT /api/admin/faq/:faqId FAQ 수정 Admin
DELETE /api/admin/faq/:faqId FAQ 삭제 Admin
POST /api/admin/faq/delete FAQ 일괄 삭제 Admin

3) QnA 관리

HTTP 엔드포인트 설명 권한
GET /api/admin/qna QnA 목록 조회 Admin
GET /api/admin/qna/:qnaId QnA 상세 조회 Admin
POST /api/admin/qna/:qnaId/answer QnA 답변 등록 Admin
PUT /api/admin/qna/:qnaId QnA 수정 Admin
DELETE /api/admin/qna/:qnaId QnA 삭제 Admin
POST /api/admin/qna/delete QnA 일괄 삭제 Admin
GET /api/admin/qna/status QnA 상태(통계) 조회 Admin

4) 공지사항 관리

HTTP 엔드포인트 설명 권한
GET /api/admin/notice 공지사항 목록 조회 Admin
GET /api/admin/notice/:noticeId 공지사항 상세 조회 Admin
POST /api/admin/notice 공지사항 생성 Admin
PUT /api/admin/notice/:noticeId 공지사항 수정 Admin
DELETE /api/admin/notice/:noticeId 공지사항 삭제 Admin
POST /api/admin/notice/delete 공지사항 일괄 삭제 Admin

5) OpenAPI 키 관리

HTTP 엔드포인트 설명 권한
GET /api/admin/openapi/keys OpenAPI 키 목록 조회 Admin
GET /api/admin/openapi/keys/:keyId OpenAPI 키 상세 조회 Admin
POST /api/admin/openapi/keys OpenAPI 키 생성 Admin
PUT /api/admin/openapi/keys/:keyId OpenAPI 키 수정 (승인/반려) Admin
DELETE /api/admin/openapi/keys/:keyId OpenAPI 키 삭제 Admin
POST /api/admin/openapi/keys/delete OpenAPI 키 일괄 삭제 Admin
POST /api/admin/openapi/keys/:keyId/extend OpenAPI 키 기간 연장 Admin
GET /api/admin/openapi/status OpenAPI 상태(통계) 조회 Admin

6) 운영자 계정 관리 - S-Admin 전용

HTTP 엔드포인트 설명 권한
GET /api/admin/accounts/admin 운영자 계정 목록 조회 S-Admin
GET /api/admin/accounts/admin/:adminId 운영자 계정 상세 조회 S-Admin
POST /api/admin/accounts/admin 운영자 계정 생성 S-Admin
PUT /api/admin/accounts/admin/:adminId 운영자 계정 수정 S-Admin
DELETE /api/admin/accounts/admin/:adminId 운영자 계정 삭제 S-Admin
POST /api/admin/accounts/admin/delete 운영자 계정 일괄 삭제 S-Admin
PUT /api/admin/accounts/admin/:adminId/password 운영자 비밀번호 변경 S-Admin
PUT /api/admin/accounts/admin/:adminId/role 운영자 역할 변경 S-Admin
POST /api/admin/accounts/admin/email/check 운영자 이메일 중복 체크 S-Admin

7) 사용자 계정 관리

HTTP 엔드포인트 설명 권한
GET /api/admin/accounts/user 사용자 계정 목록 조회 Admin
GET /api/admin/accounts/user/:userId 사용자 계정 상세 조회 Admin
POST /api/admin/accounts/user 사용자 계정 생성 Admin
PUT /api/admin/accounts/user/:userId 사용자 계정 수정 Admin
DELETE /api/admin/accounts/user/:userId 사용자 계정 삭제 Admin
POST /api/admin/accounts/user/delete 사용자 계정 일괄 삭제 Admin
PUT /api/admin/accounts/user/:userId/password 사용자 비밀번호 변경 Admin
PUT /api/admin/accounts/user/:userId/status 사용자 상태 변경 Admin
POST /api/admin/accounts/user/email/check 사용자 이메일 중복 체크 Admin

0.6 공통 코드 API

1) 사용자용 조회

HTTP 엔드포인트 설명 권한
GET /api/code/:grpId 그룹별 코드 조회 Public
GET /api/code/:grpId/:codeId 코드 상세 조회 Public
GET /api/code/type/:codeType 타입별 코드 조회 Public
GET /api/code/:grpId/parent 부모 코드 기반 조회 Public

2) 관리자용 상세 조회

HTTP 엔드포인트 설명 권한
GET /api/code/admin/:grpId 그룹별 코드 조회 (상세) Admin
GET /api/code/admin/:grpId/:codeId 코드 상세 조회 (상세) Admin
GET /api/code/admin/type/:codeType 타입별 코드 조회 (상세) Admin
GET /api/code/admin/:grpId/parent 부모 코드 기반 조회 (상세) Admin

3) 관리자용 그룹 관리

HTTP 엔드포인트 설명 권한
GET /api/code/admin/groups 그룹 목록 조회 Admin
POST /api/code/admin/group 그룹 생성 Admin
PUT /api/code/admin/group/:grpId 그룹 수정 Admin
DELETE /api/code/admin/group/:grpId 그룹 삭제 Admin
POST /api/code/admin/groups/delete 그룹 일괄 삭제 Admin

4) 관리자용 코드 관리

HTTP 엔드포인트 설명 권한
POST /api/code/admin/:grpId/code 코드 생성 Admin
PUT /api/code/admin/:grpId/:codeId 코드 수정 Admin
DELETE /api/code/admin/:grpId/:codeId 코드 삭제 Admin
POST /api/code/admin/:grpId/codes/delete 코드 일괄 삭제 Admin

1. 개요

1.1 프로젝트 소개

IITP DABT Admin System은 정보통신기획평가원(IITP)의 데이터 및 Open API 관리 시스템입니다.

본 시스템은 사용자와 관리자를 위한 웹 기반 플랫폼으로, 다음과 같은 핵심 기능을 제공합니다:

  • 사용자의 OpenAPI 인증키 발급 및 관리
  • FAQ, QnA, 공지사항 등 콘텐츠 관리
  • 사용자 및 관리자 계정 관리
  • 공통 코드 관리 시스템

1.2 시스템 아키텍처

시스템은 크게 3개의 패키지로 구성됩니다:

IITP-DABT-Admin/
├── packages/common/     # 공통 타입 및 Validation (FE/BE 공유)
│   ├── types/          # API DTO, 에러 코드, 공통 타입
│   └── validation/     # 공통 Validation 로직
├── fe/                 # Frontend (React + TypeScript)
└── be/                 # Backend (Node.js + Express + TypeScript)
    ├── controllers/    # API 컨트롤러
    ├── services/       # 비즈니스 로직
    └── repositories/   # 데이터베이스 접근
  • Monorepo 구조: 단일 저장소에서 FE/BE/Common 패키지 통합 관리
  • TypeScript 공유 타입: packages/common을 통해 FE와 BE가 동일한 타입 정의 사용
  • Controller-Service-Repository 패턴: BE는 3계층 아키텍처 적용

1.3 주요 기능

1.3.1 사용자 기능

  • 회원 관리: 회원가입, 로그인, 프로필 관리, 비밀번호 변경
  • 콘텐츠 조회: FAQ 조회, 공지사항 조회
  • QnA 관리: 문의 등록, 내 문의 조회, 문의 삭제
  • OpenAPI 키 관리: 인증키 발급 신청, 키 목록 조회, 기간 연장, 키 삭제

1.3.2 관리자 기능

  • 콘텐츠 관리: FAQ, 공지사항 등록/수정/삭제
  • QnA 관리: 사용자 문의에 답변, 문의 관리
  • OpenAPI 키 관리: 인증키 승인/반려, 키 목록 조회 및 관리
  • 계정 관리: 사용자 계정 관리, 운영자 계정 관리 (S-Admin 전용)
  • 공통 코드 관리: 시스템 코드 그룹 및 코드 관리

2. API 기본 정보

2.1 Base URL

시스템은 환경별로 다른 Base URL을 사용합니다.

환경 Base URL 비고
로컬 개발 http://localhost:30000 BE 개발 서버 (FE: localhost:5173)
개발(Dev) http://192.168.60.142/adm 개발 환경
스테이징(Staging) https://staging-api.iitp-dabt.example.com 테스트 환경
운영(Production) https://api.iitp-dabt.example.com 운영 환경

참고:

  • 모든 API 엔드포인트는 Base URL 뒤에 붙여서 사용합니다.
  • 예: POST {Base URL}/api/auth/user/login

2.2 인증 방식

본 시스템은 JWT(JSON Web Token) 기반 인증을 사용합니다.

2.2.1 인증 토큰 종류

토큰 종류 용도 유효 기간 저장 위치
Access Token API 호출 시 인증 15분 메모리 또는 localStorage
Refresh Token Access Token 갱신 7일 httpOnly Cookie 권장

2.2.2 인증 플로우

  1. 로그인: /api/auth/{user|admin}/login으로 로그인 요청
  2. 토큰 수신: 응답으로 token(Access Token)과 refreshToken 수신
  3. API 호출: 이후 모든 인증 필요 API는 Authorization 헤더에 Access Token 포함
  4. 토큰 만료: Access Token 만료 시 (401 에러), Refresh Token으로 갱신
  5. 토큰 갱신: /api/auth/{user|admin}/refresh로 새 Access Token 발급

2.2.3 인증 권한 레벨

권한 레벨 설명 적용 대상
Public 인증 불필요 공지사항 조회, FAQ 조회, 회원가입 등
User 사용자 인증 필요 사용자 로그인 후 이용 가능한 API
Admin 관리자 인증 필요 관리자 권한 필요 (ADMIN, S-ADMIN 모두 가능)
S-Admin 최고 관리자 전용 S-ADMIN 권한만 접근 가능 (운영자 계정 관리 등)

2.3 공통 헤더

2.3.1 요청 헤더

모든 API 요청 시 다음 헤더를 포함해야 합니다:

헤더명 값 필수 여부 설명
Content-Type application/json 필수 (Body 있는 경우) 요청 본문 형식
Authorization Bearer {token} 조건부 (인증 필요 API) Access Token

예시:

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

2.3.2 응답 헤더

응답은 기본적으로 다음 헤더를 포함합니다:

헤더명 값 설명
Content-Type application/json 응답 본문 형식

2.4 HTTP 상태 코드

API는 표준 HTTP 상태 코드를 사용합니다.

상태 코드 의미 설명
200 OK 요청 성공
201 Created 리소스 생성 성공
400 Bad Request 잘못된 요청 (파라미터 오류, Validation 실패)
401 Unauthorized 인증 실패 (토큰 없음, 토큰 만료, 토큰 무효)
403 Forbidden 권한 없음 (인증은 되었으나 접근 권한 없음)
404 Not Found 리소스를 찾을 수 없음
409 Conflict 리소스 충돌 (중복 이메일 등)
500 Internal Server Error 서버 내부 오류
503 Service Unavailable 서비스 일시적 사용 불가 (점검 등)

참고:

  • 모든 응답은 본문에 ApiResponse 형식을 따릅니다. (3. 공통 응답 구조 참조)
  • HTTP 상태 코드와 별개로 errorCode 필드를 통해 상세 오류를 전달합니다. (4장 참조)

3. 공통 응답 구조

모든 API는 일관된 응답 구조를 사용합니다.

3.1 ApiResponse 구조

interface ApiResponse<T = any> {
  success: boolean;         // 성공 여부 (true: 성공, false: 실패)
  data?: T;                 // 응답 데이터 (성공 시)
  errorCode?: number;       // 에러 코드 (실패 시)
  errorMessage?: string;    // 에러 메시지 (실패 시)
}
필드 타입 필수 설명
success boolean O 요청 성공 여부. true: 성공, false: 실패
data T (제네릭) X 성공 시 응답 데이터. 타입은 API마다 다름
errorCode number X 실패 시 에러 코드 (4장의 에러 코드 참조)
errorMessage string X 실패 시 에러 메시지 (한글)

3.2 정상 응답

3.2.1 데이터가 있는 경우

{
  "success": true,
  "data": {
    "userId": 1,
    "email": "user@example.com",
    "name": "홍길동"
  }
}

3.2.2 데이터가 없는 경우 (void)

생성/수정/삭제와 같이 반환 데이터가 없는 경우:

{
  "success": true
}

참고:

  • data 필드가 생략되거나 null일 수 있습니다.
  • 삭제, 수정 등의 API는 보통 data 없이 success: true만 반환합니다.

3.3 에러 응답

요청 실패 시 다음과 같은 형식으로 응답합니다:

{
  "success": false,
  "errorCode": 16000,
  "errorMessage": "사용자를 찾을 수 없습니다."
}
필드 설명
success 항상 false
errorCode 에러 코드 (4장 참조)
errorMessage 사용자에게 표시할 한글 메시지

에러 처리 가이드:

  1. HTTP 상태 코드로 대략적인 오류 유형 파악
  2. errorCode로 정확한 오류 원인 식별
  3. errorMessage를 사용자에게 표시

3.4 페이징 응답

목록 조회 API는 페이징을 지원하며, PaginationRes 구조를 사용합니다.

interface PaginationRes<T> {
  items: T[];              // 현재 페이지의 아이템 목록
  total: number;           // 전체 아이템 수
  page: number;            // 현재 페이지 번호 (1부터 시작)
  limit: number;           // 페이지당 아이템 수
  totalPages: number;      // 전체 페이지 수
}

응답 예시:

{
  "success": true,
  "data": {
    "items": [
      {
        "faqId": 1,
        "question": "OpenAPI 사용 방법은?",
        "answer": "..."
      },
      {
        "faqId": 2,
        "question": "회원가입은 어떻게 하나요?",
        "answer": "..."
      }
    ],
    "total": 25,
    "page": 1,
    "limit": 10,
    "totalPages": 3
  }
}

페이징 요청 파라미터:

목록 조회 API는 다음 Query Parameter를 공통으로 지원합니다:

파라미터 타입 기본값 설명
page number 1 조회할 페이지 번호 (1부터 시작)
limit number 10 페이지당 아이템 수

예시:

  • GET /api/user/faq/list?page=2&limit=20
  • 2페이지를 조회하며, 한 페이지에 20개씩 표시

4. 에러 코드 정의

4.1 에러 코드 체계

에러 코드는 5자리 숫자로 구성되며, 범위별로 의미가 구분됩니다.

범위 카테고리 설명
11xxx 기본 에러 알 수 없는 오류, Validation 오류, DB 오류 등
12xxx 요청 관련 잘못된 요청, 파라미터 오류, 이메일 중복 등
13xxx 시스템 코드 관련 공통 코드 오류 (코드 없음, 생성/수정/삭제 실패 등)
14xxx 인증 관련 로그인 실패, 토큰 만료, 권한 없음 등
16xxx 사용자 관련 사용자 없음, 중복, 비밀번호 오류 등
17xxx 관리자 관련 관리자 없음, 생성/수정/삭제 실패 등
19xxx 서버 관련 내부 서버 오류, 서비스 불가, 점검 모드 등
20xxx 계정 관련 계정 없음, 생성/수정/삭제 실패, 비활성 계정 등
21xxx 공지사항 관련 공지 없음, 생성/수정/삭제 실패 등
22xxx FAQ 관련 FAQ 없음, 생성/수정/삭제 실패 등
23xxx QnA 관련 QnA 없음, 생성/수정/삭제 실패, 권한 없음 등
24xxx OpenAPI 관련 인증키 없음, 생성/수정/삭제 실패, 기간 연장 실패 등

4.2 전체 에러 코드 목록

4.2.1 기본 에러 (11xxx)

코드 HTTP 메시지 설명
11000 500 알 수 없는 오류가 발생했습니다. 예상치 못한 오류
11001 400 입력 데이터가 올바르지 않습니다. Validation 실패
11002 500 데이터베이스 오류가 발생했습니다. DB 쿼리 실패
11003 503 네트워크 오류가 발생했습니다. 네트워크 연결 실패

4.2.2 요청 관련 (12xxx)

코드 HTTP 메시지 설명
12000 400 잘못된 요청입니다. 잘못된 요청 형식
12001 400 필수 필드가 누락되었습니다. 필수 파라미터 누락
12002 400 잘못된 파라미터입니다. 파라미터 형식 오류
12003 408 요청 시간이 초과되었습니다. 타임아웃
12020 409 이미 사용 중인 이메일입니다. 이메일 중복
12021 400 이메일 형식이 올바르지 않습니다. 이메일 형식 오류

4.2.3 시스템 코드 관련 (13xxx)

코드 HTTP 메시지 설명
13000 404 시스템 코드를 찾을 수 없습니다. 코드 없음
13001 500 시스템 코드 생성에 실패했습니다. 코드 생성 실패
13002 500 시스템 코드 수정에 실패했습니다. 코드 수정 실패
13003 500 시스템 코드 삭제에 실패했습니다. 코드 삭제 실패
13004 400 유효하지 않은 시스템 코드입니다. 코드 형식 오류
13005 409 이미 존재하는 시스템 코드입니다. 코드 중복
13006 403 비활성화된 시스템 코드입니다. 사용 불가 코드
13020 404 시스템 코드 그룹을 찾을 수 없습니다. 그룹 없음
13021 500 시스템 코드 그룹 생성에 실패했습니다. 그룹 생성 실패
13022 500 시스템 코드 그룹 수정에 실패했습니다. 그룹 수정 실패
13023 500 시스템 코드 그룹 삭제에 실패했습니다. 그룹 삭제 실패
13024 400 유효하지 않은 시스템 코드 그룹입니다. 그룹 형식 오류
13025 409 이미 존재하는 시스템 코드 그룹입니다. 그룹 중복
13026 403 비활성화된 시스템 코드 그룹입니다. 사용 불가 그룹
13030 404 코드로 시스템 코드 그룹을 찾을 수 없습니다. 코드로 그룹 조회 실패
13031 404 ID로 시스템 코드 그룹을 찾을 수 없습니다. ID로 그룹 조회 실패
13032 404 시스템 코드로 그룹을 찾을 수 없습니다. 시스템 코드로 그룹 조회 실패
13050 404 그룹으로 부모 코드를 찾을 수 없습니다. 부모 코드 없음 (그룹 기준)
13051 404 코드로 부모 코드를 찾을 수 없습니다. 부모 코드 없음 (코드 기준)
13060 404 그룹으로 자식 코드를 찾을 수 없습니다. 자식 코드 없음 (그룹 기준)
13061 404 코드로 자식 코드를 찾을 수 없습니다. 자식 코드 없음 (코드 기준)

4.2.4 인증 관련 (14xxx)

코드 HTTP 메시지 설명
14000 401 로그인이 필요합니다. 인증 필요
14001 401 로그인에 실패했습니다. 아이디와 비밀번호를 확인해주세요. 로그인 실패
14002 500 로그아웃 처리 중 오류가 발생했습니다. 로그아웃 실패
14003 401 세션이 만료되었습니다. 다시 로그인해주세요. 토큰 만료
14004 401 유효하지 않은 토큰입니다. 토큰 무효
14005 403 접근 권한이 없습니다. 권한 없음
14006 401 토큰이 필요합니다. 토큰 누락
14007 401 유효하지 않은 토큰입니다. 토큰 검증 실패
14008 403 접근이 거부되었습니다. 접근 거부

4.2.5 사용자 관련 (16xxx)

코드 HTTP 메시지 설명
16000 404 사용자를 찾을 수 없습니다. 사용자 없음
16001 409 이미 존재하는 사용자입니다. 사용자 중복
16002 400 올바르지 않은 이메일 형식입니다. 이메일 형식 오류
16003 400 올바르지 않은 비밀번호 형식입니다. 비밀번호 형식 오류
16004 400 비밀번호가 너무 약합니다. 비밀번호 강도 부족

4.2.6 관리자 관련 (17xxx)

코드 HTTP 메시지 설명
17000 404 관리자를 찾을 수 없습니다. 관리자 없음
17001 409 이미 존재하는 관리자입니다. 관리자 중복
17002 500 관리자 생성에 실패했습니다. 관리자 생성 실패
17003 500 관리자 수정에 실패했습니다. 관리자 수정 실패
17004 500 관리자 삭제에 실패했습니다. 관리자 삭제 실패
17005 500 비밀번호 변경에 실패했습니다. 비밀번호 변경 실패
17006 500 상태 변경에 실패했습니다. 상태 변경 실패

4.2.7 서버 관련 (19xxx)

코드 HTTP 메시지 설명
19000 500 서버 내부 오류가 발생했습니다. 서버 내부 오류
19001 503 서비스가 일시적으로 사용할 수 없습니다. 서비스 불가
19002 503 시스템 점검 중입니다. 잠시 후 다시 시도해주세요. 점검 중

4.2.8 계정 관련 (20xxx)

코드 HTTP 메시지 설명
20000 404 계정을 찾을 수 없습니다. 계정 없음
20001 500 계정 생성에 실패했습니다. 계정 생성 실패
20002 500 계정 수정에 실패했습니다. 계정 수정 실패
20003 500 계정 삭제에 실패했습니다. 계정 삭제 실패
20005 409 이미 존재하는 계정입니다. 계정 중복
20040 409 이미 사용 중인 이메일입니다. 이메일 중복 (계정)
20050 403 비활성화된 계정입니다. 비활성 계정
20051 400 비밀번호가 올바르지 않습니다. 비밀번호 오류
20060 404 관리자 역할을 찾을 수 없습니다. 관리자 역할 없음

4.2.9 공지사항 관련 (21xxx)

코드 HTTP 메시지 설명
21000 404 공지사항을 찾을 수 없습니다. 공지 없음
21001 500 공지사항 생성에 실패했습니다. 공지 생성 실패
21002 500 공지사항 수정에 실패했습니다. 공지 수정 실패
21003 500 공지사항 삭제에 실패했습니다. 공지 삭제 실패
21004 403 공지사항에 접근할 권한이 없습니다. 공지 접근 거부

4.2.10 FAQ 관련 (22xxx)

코드 HTTP 메시지 설명
22000 404 FAQ를 찾을 수 없습니다. FAQ 없음
22001 500 FAQ 생성에 실패했습니다. FAQ 생성 실패
22002 500 FAQ 수정에 실패했습니다. FAQ 수정 실패
22003 500 FAQ 삭제에 실패했습니다. FAQ 삭제 실패

Q4.2.11 QnA 관련 (23xxx)

코드 HTTP 메시지 설명
23000 404 QnA를 찾을 수 없습니다. QnA 없음
23001 500 QnA 생성에 실패했습니다. QnA 생성 실패
23002 500 QnA 수정에 실패했습니다. QnA 수정 실패
23003 500 QnA 삭제에 실패했습니다. QnA 삭제 실패
23004 500 QnA 답변 등록에 실패했습니다. QnA 답변 실패
23005 403 QnA에 접근할 권한이 없습니다. QnA 접근 거부

4.2.12 OpenAPI 관련 (24xxx)

코드 HTTP 메시지 설명
24000 404 Open API를 찾을 수 없습니다. OpenAPI 키 없음
24001 500 Open API 생성에 실패했습니다. OpenAPI 키 생성 실패
24002 500 Open API 수정에 실패했습니다. OpenAPI 키 수정 실패
24003 500 Open API 삭제에 실패했습니다. OpenAPI 키 삭제 실패
24004 500 Open API 기간 연장에 실패했습니다. OpenAPI 키 연장 실패

5. 공통 값 정의

5.1 공통 코드 그룹

시스템에서 사용하는 공통 코드 그룹 ID입니다.

그룹 ID 그룹명 설명 사용처
sys_admin_roles 관리자 역할 관리자 권한 분류 운영자 계정 관리
sys_data_status 데이터 상태 데이터 활성/비활성 상태 전체 시스템
sys_work_type 작업 유형 작업 유형 분류 (배치/수동/사용자) 로그, 이력 관리
faq_type FAQ 유형 FAQ 분류 FAQ 관리
faq_status FAQ 상태 FAQ 공개/비공개 상태 FAQ 관리
qna_type QnA 유형 QnA 분류 QnA 관리
qna_status QnA 상태 QnA 답변 대기/완료/비공개 상태 QnA 관리
notice_type 공지사항 유형 공지사항 분류 공지사항 관리

5.2 관리자 역할 코드

그룹 ID: sys_admin_roles

코드 ID 코드명 설명 권한 레벨
S-ADMIN 최고 관리자 모든 권한 보유 (운영자 계정 관리 포함) 최고
ADMIN 관리자 콘텐츠 및 사용자 관리 권한 중간
EDITOR 에디터 콘텐츠 편집 권한 제한적
VIEWER 뷰어 조회 전용 권한 최소

참고:

  • S-ADMIN만 운영자 계정 관리 API에 접근 가능합니다.
  • ADMIN, EDITOR, VIEWER는 일반 관리 기능에 접근 가능합니다.

5.3 작업 유형 코드

그룹 ID: sys_work_type

코드 ID 코드명 설명
SYS-BATCH 배치 작업 시스템 자동 실행 작업
SYS-MANUAL 수동 작업 시스템 관리자의 수동 작업
BY-USER 사용자 작업 사용자 직접 수행 작업

5.4 기타 상수

5.4.1 사용자 타입

값 설명
U User (사용자)
A Admin (관리자)

5.4.2 코드 타입

공통 코드의 codeType 필드

값 설명
B Basic (기본 코드)
A Advanced (고급 코드)
S System (시스템 코드)

5.4.3 공지사항 타입

값 설명
G General (일반 공지)
S System (시스템 공지)
E Event (이벤트 공지)

5.4.4 Yes/No 플래그

시스템 전체에서 사용하는 Y/N 플래그:

값 의미 사용 예
Y Yes (예, 활성) useYn: 'Y' (사용 중)
N No (아니오, 비활성) delYn: 'N' (삭제되지 않음)

주요 플래그 필드:

  • useYn: 사용 여부
  • delYn: 삭제 여부
  • publicYn: 공개 여부
  • pinnedYn: 고정 여부
  • secretYn: 비공개 여부
  • answeredYn: 답변 완료 여부
  • activeYn: 활성화 여부

6. API 상세 규격 - 인증 API

인증 API는 사용자와 관리자의 로그인, 로그아웃, 토큰 갱신을 담당합니다.

Base Path: /api/auth

6.1 사용자 인증 API

6.1.1 사용자 로그인

기본 정보

항목 내용
API명 사용자 로그인
엔드포인트 /api/auth/user/login
HTTP 메서드 POST
인증 불필요 (Public)
설명 이메일과 비밀번호로 사용자 로그인

Request Body

interface UserLoginReq {
  email: string;       // 이메일 (필수)
  password: string;    // 비밀번호 (필수)
}
필드 타입 필수 설명 제약사항
email string O 사용자 이메일 이메일 형식
password string O 비밀번호 8~자

Response (성공 시)

interface UserLoginRes {
  token: string;         // Access Token
  refreshToken: string;  // Refresh Token
  user: {
    userId: number;      // 사용자 ID
    name: string;        // 이름
    phone?: string;      // 전화번호 (선택)
  };
}
필드 타입 설명
token string JWT Access Token (15분 유효)
refreshToken string JWT Refresh Token (7일 유효)
user.userId number 사용자 고유 ID
user.name string 사용자 이름
user.phone string 사용자 전화번호 (있는 경우)

발생 가능한 에러

HTTP 에러 코드 설명
401 14001 로그인 실패 (이메일 또는 비밀번호 불일치)
400 12001 필수 필드 누락
400 12021 이메일 형식 오류
403 20050 비활성화된 계정

비고

  • 로그인 성공 시 받은 token과 refreshToken을 안전하게 저장해야 합니다.
  • token은 이후 모든 인증 필요 API 호출 시 Authorization: Bearer {token} 헤더에 포함합니다.

6.1.2 사용자 로그아웃

기본 정보

항목 내용
API명 사용자 로그아웃
엔드포인트 /api/auth/user/logout
HTTP 메서드 POST
인증 필요 (User)
설명 사용자 로그아웃 처리

Request Body

interface UserLogoutReq {
  // 요청 본문 없음 (토큰으로 사용자 식별)
}

Response (성공 시)

interface UserLogoutRes {
  success: boolean;   // 항상 true
  message: string;    // 로그아웃 성공 메시지
}
필드 타입 설명
success boolean 성공 여부 (항상 true)
message string "로그아웃되었습니다."

발생 가능한 에러

HTTP 에러 코드 설명
401 14006 토큰 누락
401 14003 토큰 만료
401 14004 유효하지 않은 토큰
500 14002 로그아웃 처리 중 오류

6.1.3 사용자 토큰 갱신

기본 정보

항목 내용
API명 사용자 토큰 갱신
엔드포인트 /api/auth/user/refresh
HTTP 메서드 POST
인증 불필요 (Refresh Token 사용)
설명 Refresh Token으로 새로운 Access Token 발급

Request Body

interface UserRefreshTokenReq {
  refreshToken: string;  // Refresh Token (필수)
}
필드 타입 필수 설명
refreshToken string O 로그인 시 받은 Refresh Token

Response (성공 시)

interface UserRefreshTokenRes {
  token: string;         // 새로운 Access Token
  refreshToken: string;  // 새로운 Refresh Token
}
필드 타입 설명
token string 새로 발급된 Access Token (15분 유효)
refreshToken string 새로 발급된 Refresh Token (7일 유효)

발생 가능한 에러

HTTP 에러 코드 설명
401 14003 Refresh Token 만료
401 14004 유효하지 않은 Refresh Token
400 12001 Refresh Token 누락

비고

  • Access Token 만료 시(401 에러) 이 API를 호출하여 토큰을 갱신합니다.
  • 새로 받은 토큰으로 기존 토큰을 교체해야 합니다.

6.2 관리자 인증 API

6.2.1 관리자 로그인

기본 정보

항목 내용
API명 관리자 로그인
엔드포인트 /api/auth/admin/login
HTTP 메서드 POST
인증 불필요 (Public)
설명 관리자 ID와 비밀번호로 관리자 로그인

Request Body

interface AdminLoginReq {
  loginId: string;     // 관리자 ID (필수)
  password: string;    // 비밀번호 (필수)
}
필드 타입 필수 설명 제약사항
loginId string O 관리자 로그인 ID 4~20자
password string O 비밀번호 8~자

Response (성공 시)

interface AdminLoginRes {
  token: string;         // Access Token
  refreshToken: string;  // Refresh Token
  admin: {
    adminId: number;     // 관리자 ID
    name: string;        // 이름
    role: string;        // 역할 코드 (S-ADMIN, ADMIN, etc)
    roleName: string;    // 역할 이름 (최고 관리자, 관리자, etc)
  };
}
필드 타입 설명
token string JWT Access Token (15분 유효)
refreshToken string JWT Refresh Token (7일 유효)
admin.adminId number 관리자 고유 ID
admin.name string 관리자 이름
admin.role string 역할 코드 (5.2절 참조)
admin.roleName string 역할 한글명

발생 가능한 에러

HTTP 에러 코드 설명
401 14001 로그인 실패 (ID 또는 비밀번호 불일치)
400 12001 필수 필드 누락
403 20050 비활성화된 관리자 계정
404 17000 관리자를 찾을 수 없음

6.2.2 관리자 로그아웃

기본 정보

항목 내용
API명 관리자 로그아웃
엔드포인트 /api/auth/admin/logout
HTTP 메서드 POST
인증 필요 (Admin)
설명 관리자 로그아웃 처리

Request Body

interface AdminLogoutReq {
  // 요청 본문 없음 (토큰으로 관리자 식별)
}

Response (성공 시)

interface AdminLogoutRes {
  success: boolean;   // 항상 true
  message: string;    // 로그아웃 성공 메시지
}
필드 타입 설명
success boolean 성공 여부 (항상 true)
message string "로그아웃되었습니다."

발생 가능한 에러

HTTP 에러 코드 설명
401 14006 토큰 누락
401 14003 토큰 만료
401 14004 유효하지 않은 토큰
500 14002 로그아웃 처리 중 오류

6.2.3 관리자 토큰 갱신

기본 정보

항목 내용
API명 관리자 토큰 갱신
엔드포인트 /api/auth/admin/refresh
HTTP 메서드 POST
인증 불필요 (Refresh Token 사용)
설명 Refresh Token으로 새로운 Access Token 발급

Request Body

interface AdminRefreshTokenReq {
  refreshToken: string;  // Refresh Token (필수)
}
필드 타입 필수 설명
refreshToken string O 로그인 시 받은 Refresh Token

Response (성공 시)

interface AdminRefreshTokenRes {
  token: string;         // 새로운 Access Token
  refreshToken: string;  // 새로운 Refresh Token
}
필드 타입 설명
token string 새로 발급된 Access Token (15분 유효)
refreshToken string 새로 발급된 Refresh Token (7일 유효)

발생 가능한 에러

HTTP 에러 코드 설명
401 14003 Refresh Token 만료
401 14004 유효하지 않은 Refresh Token
400 12001 Refresh Token 누락

7. API 상세 규격 - 공통 API

공통 API는 시스템 상태 확인 및 설정 정보 조회를 제공합니다.

Base Path: /api/common

7.1 시스템 정보 API

7.1.1 헬스 체크

기본 정보

항목 내용
API명 헬스 체크
엔드포인트 /api/common/health
HTTP 메서드 GET
인증 불필요 (Public)
설명 서버 상태 확인

Query Parameters

없음

Response (성공 시)

interface CommonHealthRes {
  status: 'ok' | 'error';  // 서버 상태
  timestamp: string;        // 현재 시각 (ISO 8601)
  uptime: number;          // 서버 가동 시간 (초)
}
필드 타입 설명
status string 서버 상태 (ok: 정상, error: 오류)
timestamp string 현재 시각 (ISO 8601 형식)
uptime number 서버 가동 시간 (초 단위)

비고

  • 서버 상태 모니터링 및 로드 밸런서 헬스 체크에 사용됩니다.

7.1.2 버전 정보 조회

기본 정보

항목 내용
API명 버전 정보 조회
엔드포인트 /api/common/version
HTTP 메서드 GET
인증 불필요 (Public)
설명 시스템 버전 및 빌드 정보 조회

Query Parameters

없음

Response (성공 시)

interface CommonVersionRes {
  version: string;       // 버전 번호
  buildDate: string;     // 빌드 날짜
  environment: string;   // 환경 (development, staging, production)
}
필드 타입 설명
version string 시스템 버전 (예: "1.0.0")
buildDate string 빌드 날짜 (ISO 8601 형식)
environment string 실행 환경

비고

  • 클라이언트가 서버 버전을 확인하여 호환성을 체크할 때 사용합니다.

7.1.3 JWT 설정 정보 조회

기본 정보

항목 내용
API명 JWT 설정 정보 조회
엔드포인트 /api/common/jwt-config
HTTP 메서드 GET
인증 불필요 (Public)
설명 JWT 토큰 관련 설정 정보 조회

Query Parameters

없음

Response (성공 시)

interface CommonJwtConfigRes {
  accessTokenExpiresIn: string;   // Access Token 만료 시간
  refreshTokenExpiresIn: string;  // Refresh Token 만료 시간
  issuer: string;                 // 토큰 발행자
}
필드 타입 설명
accessTokenExpiresIn string Access Token 유효 기간 (예: "15m")
refreshTokenExpiresIn string Refresh Token 유효 기간 (예: "7d")
issuer string 토큰 발행자 (예: "IITP-DABT")

비고

  • 클라이언트가 토큰 갱신 타이밍을 계산할 때 참고할 수 있습니다.
  • 보안상 민감한 정보(Secret Key 등)는 포함되지 않습니다.

8. API 상세 규격 - 사용자 API

사용자 API는 일반 사용자를 위한 기능을 제공합니다.

Base Path: /api/user

8.1 회원 관리 API

8.1.1 이메일 중복 체크

기본 정보

항목 내용
API명 이메일 중복 체크
엔드포인트 /api/user/email/check
HTTP 메서드 POST
인증 불필요 (Public)
설명 회원가입 전 이메일 중복 여부 확인

Request Body

interface UserCheckEmailReq {
  email: string;  // 확인할 이메일 (필수)
}
필드 타입 필수 설명 제약사항
email string O 확인할 이메일 주소 이메일 형식

Response (성공 시)

interface UserCheckEmailRes {
  isAvailable: boolean;  // 사용 가능 여부
}
필드 타입 설명
isAvailable boolean true: 사용 가능, false: 이미 사용 중

발생 가능한 에러

HTTP 에러 코드 설명
400 12021 이메일 형식 오류
400 12001 이메일 필드 누락

8.1.2 회원가입

기본 정보

항목 내용
API명 회원가입
엔드포인트 /api/user/register
HTTP 메서드 POST
인증 불필요 (Public)
설명 새로운 사용자 계정 생성

Request Body

interface UserRegisterReq {
  email: string;       // 이메일 (필수)
  password: string;    // 비밀번호 (필수)
  name: string;        // 이름 (필수)
  affiliation?: string; // 소속 (선택)
}
필드 타입 필수 설명 제약사항
email string O 이메일 주소 이메일 형식, 고유값
password string O 비밀번호 8~자, 영문+숫자+특수문자 조합
name string O 사용자 이름 2~50자
affiliation string X 소속 기관/회사 최대 100자

Response (성공 시)

interface UserRegisterRes {
  userId: number;       // 생성된 사용자 ID
  email: string;        // 이메일
  name: string;         // 이름
  affiliation?: string; // 소속
}
필드 타입 설명
userId number 생성된 사용자 고유 ID
email string 등록된 이메일
name string 사용자 이름
affiliation string 소속 (입력한 경우)

발생 가능한 에러

HTTP 에러 코드 설명
409 12020 이미 사용 중인 이메일
400 12021 이메일 형식 오류
400 16004 비밀번호가 너무 약함
400 12001 필수 필드 누락

비고

  • 회원가입 완료 후 자동 로그인되지 않습니다. 별도로 로그인 API를 호출해야 합니다.

8.1.3 프로필 조회

기본 정보

항목 내용
API명 사용자 프로필 조회
엔드포인트 /api/user/profile
HTTP 메서드 GET
인증 필요 (User)
설명 로그인한 사용자의 프로필 정보 조회

Response (성공 시)

interface UserProfileRes {
  userId: number;       // 사용자 ID
  email: string;        // 이메일
  name: string;         // 이름
  affiliation?: string; // 소속
  createdAt: string;    // 가입일시 (ISO 8601)
}
필드 타입 설명
userId number 사용자 고유 ID
email string 이메일 주소
name string 사용자 이름
affiliation string 소속 기관/회사
createdAt string 가입일시

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
404 16000 사용자를 찾을 수 없음

8.1.4 프로필 수정

기본 정보

항목 내용
API명 사용자 프로필 수정
엔드포인트 /api/user/profile
HTTP 메서드 PUT
인증 필요 (User)
설명 로그인한 사용자의 프로필 정보 수정

Request Body

interface UserProfileUpdateReq {
  name: string;         // 이름 (필수)
  affiliation?: string; // 소속 (선택)
}
필드 타입 필수 설명 제약사항
name string O 새로운 이름 2~50자
affiliation string X 새로운 소속 최대 100자

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
404 16000 사용자를 찾을 수 없음
400 12001 필수 필드 누락

비고

  • 이메일은 수정할 수 없습니다.

8.1.5 비밀번호 변경

기본 정보

항목 내용
API명 사용자 비밀번호 변경
엔드포인트 /api/user/password
HTTP 메서드 PUT
인증 필요 (User)
설명 로그인한 사용자의 비밀번호 변경

Request Body

interface UserPasswordChangeReq {
  currentPassword: string;  // 현재 비밀번호 (필수)
  newPassword: string;      // 새 비밀번호 (필수)
}
필드 타입 필수 설명 제약사항
currentPassword string O 현재 비밀번호 -
newPassword string O 새로운 비밀번호 8~자, 영문+숫자+특수문자 조합

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
400 20051 현재 비밀번호가 올바르지 않음
400 16004 새 비밀번호가 너무 약함
400 12001 필수 필드 누락

비고

  • 비밀번호 변경 후 기존 토큰은 유효하지만, 보안을 위해 재로그인을 권장합니다.

8.2 FAQ API

8.2.1 FAQ 목록 조회

기본 정보

항목 내용
API명 FAQ 목록 조회 (사용자용)
엔드포인트 /api/user/faq/list
HTTP 메서드 GET
인증 불필요 (Public)
설명 FAQ 목록 조회 (페이징 지원)

Query Parameters

필드 타입 필수 설명 기본값
page number X 페이지 번호 1
limit number X 페이지당 항목 수 10
faqType string X FAQ 유형 필터 -
search string X 검색어 (질문/답변 내용) -

Response (성공 시)

interface UserFaqListRes extends PaginationRes<UserFaqItem> {
  items: UserFaqItem[];
  total: number;
  page: number;
  limit: number;
  totalPages: number;
}

interface UserFaqItem {
  faqId: number;       // FAQ ID
  faqType: string;     // FAQ 유형
  question: string;    // 질문
  answer: string;      // 답변
  hitCnt: number;      // 조회수
  sortOrder: number;   // 정렬 순서
}

비고

  • 비활성 FAQ는 조회되지 않습니다.
  • sortOrder가 낮을수록 상위에 표시됩니다.

8.2.2 FAQ 상세 조회

기본 정보

항목 내용
API명 FAQ 상세 조회 (사용자용)
엔드포인트 /api/user/faq/:faqId
HTTP 메서드 GET
인증 불필요 (Public)
설명 특정 FAQ의 상세 정보 조회 (조회수 증가)

URL Parameters

필드 타입 필수 설명
faqId number O FAQ ID

Response (성공 시)

interface UserFaqDetailRes {
  faq: UserFaqItem;  // FAQ 정보
}

발생 가능한 에러

HTTP 에러 코드 설명
404 22000 FAQ를 찾을 수 없음

비고

  • 조회 시 hitCnt가 1 증가합니다.

8.2.3 FAQ 홈 화면용 조회

기본 정보

항목 내용
API명 FAQ 홈 화면용 조회
엔드포인트 /api/user/faq/home
HTTP 메서드 GET
인증 불필요 (Public)
설명 홈 화면에 표시할 주요 FAQ 목록 조회 (최대 10개)

Response (성공 시)

interface UserFaqHomeRes {
  faqs: UserFaqItem[];  // FAQ 목록 (최대 10개)
}

비고

  • 정렬 순서가 낮은 순서대로 최대 10개 반환됩니다.
  • 페이징 없이 고정된 개수만 반환됩니다.

8.3 QnA API

8.3.1 QnA 목록 조회

기본 정보

항목 내용
API명 QnA 목록 조회 (사용자용)
엔드포인트 /api/user/qna/list
HTTP 메서드 GET
인증 선택적 (Public + Optional User)
설명 QnA 목록 조회 (로그인 시 내 비공개 글 포함)

Query Parameters

필드 타입 필수 설명 기본값
page number X 페이지 번호 1
limit number X 페이지당 항목 수 10
qnaType string X QnA 유형 필터 -
search string X 검색어 (제목/내용) -
sort string X 정렬 (createdAt-desc, hit-desc) createdAt-desc
mineOnly boolean X 내 문의만 조회 false

Response (성공 시)

interface UserQnaListRes extends PaginationRes<UserQnaListItem> {
  items: UserQnaListItem[];
  total: number;
  page: number;
  limit: number;
  totalPages: number;
}

interface UserQnaListItem {
  qnaId: number;        // QnA ID
  qnaType: string;      // QnA 유형
  title: string;        // 제목
  secretYn: string;     // 비공개 여부 (Y/N)
  writerName: string;   // 작성자명
  answeredYn: string;   // 답변 완료 여부 (Y/N)
  createdAt: string;    // 작성일시
  hitCnt?: number;      // 조회수
  isMine?: boolean;     // 내 글 여부 (로그인 시)
}

비고

  • 비로그인 시: 공개 글만 조회
  • 로그인 시: 공개 글 + 내 비공개 글 조회
  • isMine 필드는 로그인 시에만 포함됩니다.

8.3.2 QnA 상세 조회

기본 정보

항목 내용
API명 QnA 상세 조회 (사용자용)
엔드포인트 /api/user/qna/:qnaId
HTTP 메서드 GET
인증 선택적 (Public + Optional User)
설명 특정 QnA의 상세 정보 조회 (답변 포함)

URL Parameters

필드 타입 필수 설명
qnaId number O QnA ID

Response (성공 시)

interface UserQnaDetailRes {
  qna: UserQnaDetailItem;  // QnA 정보
}

interface UserQnaDetailItem {
  qnaId: number;
  qnaType: string;
  title: string;
  content: string;          // 질문 내용
  secretYn: string;
  writerName: string;
  answeredYn: string;
  answerContent?: string;   // 답변 내용
  createdAt: string;
  answeredAt?: string;      // 답변일시
  hitCnt?: number;
  isMine?: boolean;         // 내 글 여부
}

발생 가능한 에러

HTTP 에러 코드 설명
404 23000 QnA를 찾을 수 없음
403 23005 비공개 글 접근 권한 없음

비고

  • 비공개 글은 작성자 본인만 조회 가능합니다.
  • 조회 시 hitCnt가 1 증가합니다.

8.3.3 QnA 등록

기본 정보

항목 내용
API명 QnA 등록 (사용자용)
엔드포인트 /api/user/qna
HTTP 메서드 POST
인증 필요 (User)
설명 새로운 QnA 등록

Request Body

interface UserQnaCreateReq {
  qnaType: string;       // QnA 유형 (필수)
  title: string;         // 제목 (필수)
  content: string;       // 내용 (필수)
  secretYn?: string;     // 비공개 여부 (기본값: 'N')
  writerName?: string;   // 작성자명 (선택, 없으면 사용자 이름 사용)
}
필드 타입 필수 설명 제약사항
qnaType string O QnA 유형 코드 공통 코드 참조
title string O 제목 최대 200자
content string O 질문 내용 최대 2000자
secretYn string X 비공개 여부 (Y/N) 기본값: N
writerName string X 작성자명 최대 50자

Response (성공 시)

interface UserQnaCreateRes {
  qnaId: number;  // 생성된 QnA ID
}
필드 타입 설명
qnaId number 생성된 QnA 고유 ID

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
400 12001 필수 필드 누락
500 23001 QnA 생성 실패

8.3.4 QnA 삭제

기본 정보

항목 내용
API명 QnA 삭제 (사용자용)
엔드포인트 /api/user/qna/:qnaId
HTTP 메서드 DELETE
인증 필요 (User)
설명 본인이 작성한 QnA 삭제

URL Parameters

필드 타입 필수 설명
qnaId number O 삭제할 QnA ID

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
404 23000 QnA를 찾을 수 없음
403 23005 본인이 작성한 글만 삭제 가능
500 23003 QnA 삭제 실패

비고

  • 본인이 작성한 QnA만 삭제할 수 있습니다.

8.3.5 QnA 홈 화면용 조회

기본 정보

항목 내용
API명 QnA 홈 화면용 조회
엔드포인트 /api/user/qna/home
HTTP 메서드 GET
인증 선택적 (Public + Optional User)
설명 홈 화면에 표시할 최신 QnA 목록 조회 (최대 10개)

Response (성공 시)

interface UserQnaHomeRes {
  qnas: UserQnaItem[];  // QnA 목록 (최대 10개, 공개글만)
}

비고

  • 최신 순으로 최대 10개 반환됩니다.
  • 비공개 글은 제외됩니다.

8.4 공지사항 API

8.4.1 공지사항 목록 조회

기본 정보

항목 내용
API명 공지사항 목록 조회 (사용자용)
엔드포인트 /api/user/notice
HTTP 메서드 GET
인증 불필요 (Public)
설명 공지사항 목록 조회 (고정 공지 우선 표시)

Query Parameters

필드 타입 필수 설명 기본값
page number X 페이지 번호 1
limit number X 페이지당 항목 수 10
noticeType string X 공지 유형 필터 (G/S/E) -
publicOnly boolean X 공개 공지만 조회 true
includeExpired boolean X 만료된 공지 포함 false

Response (성공 시)

interface UserNoticeListRes extends PaginationRes<UserNoticeListItem> {
  items: UserNoticeListItem[];
  total: number;
  page: number;
  limit: number;
  totalPages: number;
}

interface UserNoticeListItem {
  noticeId: number;       // 공지 ID
  title: string;          // 제목
  noticeType: 'G' | 'S' | 'E';  // 공지 유형
  pinnedYn: 'Y' | 'N';    // 고정 여부
  startDt?: string;       // 게시 시작일
  endDt?: string;         // 게시 종료일
  postedAt: string;       // 게시일시
}

공지 유형 (noticeType)

값 설명
G General (일반 공지)
S System (시스템 공지)
E Event (이벤트 공지)

비고

  • 고정 공지(pinnedYn: 'Y')가 최상단에 표시됩니다.
  • 게시 기간(startDt ~ endDt)이 설정된 경우 기간 내 공지만 표시됩니다.

8.4.2 공지사항 상세 조회

기본 정보

항목 내용
API명 공지사항 상세 조회 (사용자용)
엔드포인트 /api/user/notice/:noticeId
HTTP 메서드 GET
인증 불필요 (Public)
설명 특정 공지사항의 상세 정보 조회

URL Parameters

필드 타입 필수 설명
noticeId number O 공지 ID

Response (성공 시)

interface UserNoticeDetailRes {
  notice: UserNoticeItem;  // 공지 정보
}

interface UserNoticeItem {
  noticeId: number;
  title: string;
  content: string;          // 공지 내용 (HTML 가능)
  noticeType: 'G' | 'S' | 'E';
  pinnedYn: 'Y' | 'N';
  startDt?: string;
  endDt?: string;
  postedAt: string;
}

발생 가능한 에러

HTTP 에러 코드 설명
404 21000 공지사항을 찾을 수 없음
403 21004 비공개 공지 접근 거부

8.4.3 공지사항 홈 화면용 조회

기본 정보

항목 내용
API명 공지사항 홈 화면용 조회
엔드포인트 /api/user/notice/home
HTTP 메서드 GET
인증 불필요 (Public)
설명 홈 화면에 표시할 주요 공지사항 목록 조회 (최대 5개)

Response (성공 시)

interface UserNoticeHomeRes {
  notices: UserNoticeItem[];  // 공지 목록 (최대 5개)
}

비고

  • 고정 공지 우선, 최신 순으로 최대 5개 반환됩니다.

8.5 OpenAPI 키 관리 API

8.5.1 OpenAPI 키 목록 조회

기본 정보

항목 내용
API명 OpenAPI 키 목록 조회 (사용자용)
엔드포인트 /api/user/openapi/keys
HTTP 메서드 GET
인증 필요 (User)
설명 로그인한 사용자의 OpenAPI 인증키 목록 조회

Response (성공 시)

interface UserOpenApiListRes {
  authKeys: UserOpenApiKeyItem[];  // 인증키 목록
}

interface UserOpenApiKeyItem {
  keyId: number;           // 키 ID
  authKey: string;         // 인증키 (마스킹 처리됨)
  activeYn: string;        // 활성 상태 (Y: 승인, N: 대기/반려, P: 승인대기)
  startDt?: string;        // 유효 시작일
  endDt?: string;          // 유효 종료일
  keyName: string;         // API 이름
  keyDesc: string;         // API 사용 목적
  keyRejectReason?: string; // 반려 사유
  activeAt?: string;       // 승인일시
  latestAccAt?: string;    // 최근 사용일시
  createdAt: string;       // 신청일시
  updatedAt?: string;      // 수정일시
}

activeYn 상태 값

값 설명
Y 승인됨 (사용 가능)
N 반려됨
P 승인 대기 중

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요

8.5.2 OpenAPI 키 상세 조회

기본 정보

항목 내용
API명 OpenAPI 키 상세 조회 (사용자용)
엔드포인트 /api/user/openapi/keys/:keyId
HTTP 메서드 GET
인증 필요 (User)
설명 특정 OpenAPI 인증키의 상세 정보 조회

URL Parameters

필드 타입 필수 설명
keyId number O 키 ID

Response (성공 시)

interface UserOpenApiDetailRes {
  authKey: UserOpenApiKeyItem;  // 인증키 정보
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
404 24000 OpenAPI 키를 찾을 수 없음
403 14005 본인의 키만 조회 가능

8.5.3 OpenAPI 키 발급 신청

기본 정보

항목 내용
API명 OpenAPI 키 발급 신청
엔드포인트 /api/user/openapi/keys
HTTP 메서드 POST
인증 필요 (User)
설명 새로운 OpenAPI 인증키 발급 신청 (관리자 승인 필요)

Request Body

interface UserOpenApiCreateReq {
  keyName: string;   // API 이름 (필수)
  keyDesc: string;   // API 사용 목적 (필수)
  startDt?: string;  // 유효 시작일 (선택)
  endDt?: string;    // 유효 종료일 (선택)
}
필드 타입 필수 설명 제약사항
keyName string O API 이름 최대 120자
keyDesc string O API 사용 목적 최대 600자
startDt string X 유효 시작일 (ISO 8601) -
endDt string X 유효 종료일 (ISO 8601) -

Response (성공 시)

interface UserOpenApiCreateRes {
  keyId: number;    // 생성된 키 ID
  authKey: string;  // 생성된 인증키 (최초 1회만 전체 표시)
}
필드 타입 설명
keyId number 생성된 키 고유 ID
authKey string 생성된 인증키 (관리자 승인 후 활성화)

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
400 12001 필수 필드 누락
500 24001 OpenAPI 키 생성 실패

비고

  • 키 발급 신청 후 관리자 승인이 필요합니다.
  • 최초 발급 시에만 전체 인증키가 표시되므로 안전하게 보관해야 합니다.

8.5.4 OpenAPI 키 삭제

기본 정보

항목 내용
API명 OpenAPI 키 삭제
엔드포인트 /api/user/openapi/keys/:keyId
HTTP 메서드 DELETE
인증 필요 (User)
설명 본인의 OpenAPI 인증키 삭제

URL Parameters

필드 타입 필수 설명
keyId number O 삭제할 키 ID

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
404 24000 OpenAPI 키를 찾을 수 없음
403 14005 본인의 키만 삭제 가능
500 24003 OpenAPI 키 삭제 실패

비고

  • 삭제된 키는 복구할 수 없습니다.

8.5.5 OpenAPI 키 기간 연장

기본 정보

항목 내용
API명 OpenAPI 키 기간 연장
엔드포인트 /api/user/openapi/keys/:keyId/extend
HTTP 메서드 POST
인증 필요 (User)
설명 본인의 OpenAPI 인증키 유효 기간 연장 신청

URL Parameters

필드 타입 필수 설명
keyId number O 연장할 키 ID

Request Body

interface UserOpenApiExtendReq {
  startDt?: string;  // 새로운 시작일 (선택)
  endDt?: string;    // 새로운 종료일 (선택)
}
필드 타입 필수 설명
startDt string X 새로운 유효 시작일 (ISO 8601)
endDt string X 새로운 유효 종료일 (ISO 8601)

Response (성공 시)

interface UserOpenApiExtendRes {
  startDt?: string;  // 연장된 시작일
  endDt?: string;    // 연장된 종료일
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
404 24000 OpenAPI 키를 찾을 수 없음
403 14005 본인의 키만 연장 가능
500 24004 OpenAPI 키 연장 실패

9. API 상세 규격 - 관리자 API

관리자 API는 시스템 관리자를 위한 관리 기능을 제공합니다.

Base Path: /api/admin

권한 레벨:

  • Admin: 일반 관리자 권한 (ADMIN, EDITOR, VIEWER 모두 접근 가능)
  • S-Admin: 최고 관리자 권한 (S-ADMIN만 접근 가능, 운영자 계정 관리)

9.1 프로필 관리 API

9.1.1 관리자 프로필 조회

기본 정보

항목 내용
API명 관리자 프로필 조회
엔드포인트 /api/admin/profile
HTTP 메서드 GET
인증 필요 (Admin)
설명 로그인한 관리자의 프로필 정보 조회

Response (성공 시)

interface AdminProfileRes {
  adminId: number;        // 관리자 ID
  loginId: string;        // 로그인 ID
  name: string;           // 이름
  role: string;           // 역할 코드
  roleName?: string;      // 역할 이름
  affiliation?: string;   // 소속
  createdAt: string;      // 생성일시
}
필드 타입 설명
adminId number 관리자 고유 ID
loginId string 로그인 ID
name string 관리자 이름
role string 역할 코드 (S-ADMIN, ADMIN 등)
roleName string 역할 한글명
affiliation string 소속
createdAt string 계정 생성일시

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
404 17000 관리자를 찾을 수 없음

9.1.2 관리자 프로필 수정

기본 정보

항목 내용
API명 관리자 프로필 수정
엔드포인트 /api/admin/profile
HTTP 메서드 PUT
인증 필요 (Admin)
설명 로그인한 관리자의 프로필 정보 수정

Request Body

interface AdminProfileUpdateReq {
  name: string;          // 이름 (필수)
  affiliation?: string;  // 소속 (선택)
}
필드 타입 필수 설명 제약사항
name string O 새로운 이름 2~50자
affiliation string X 새로운 소속 최대 100자

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
404 17000 관리자를 찾을 수 없음
400 12001 필수 필드 누락

비고

  • 로그인 ID와 역할은 수정할 수 없습니다.

9.1.3 관리자 비밀번호 변경

기본 정보

항목 내용
API명 관리자 비밀번호 변경
엔드포인트 /api/admin/password
HTTP 메서드 PUT
인증 필요 (Admin)
설명 로그인한 관리자의 비밀번호 변경

Request Body

interface AdminPasswordChangeReq {
  currentPassword: string;  // 현재 비밀번호 (필수)
  newPassword: string;      // 새 비밀번호 (필수)
}
필드 타입 필수 설명 제약사항
currentPassword string O 현재 비밀번호 -
newPassword string O 새로운 비밀번호 8~자, 영문+숫자+특수문자 조합

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
400 20051 현재 비밀번호가 올바르지 않음
400 16004 새 비밀번호가 너무 약함
400 12001 필수 필드 누락
500 17005 비밀번호 변경 실패

9.2 FAQ 관리 API

관리자는 FAQ 콘텐츠를 생성, 수정, 삭제할 수 있습니다.

9.2.1 FAQ 목록 조회

기본 정보

항목 내용
API명 FAQ 목록 조회 (관리자용)
엔드포인트 /api/admin/faq
HTTP 메서드 GET
인증 필요 (Admin)
설명 FAQ 목록 조회 (비활성 포함, 관리 정보 포함)

Query Parameters

필드 타입 필수 설명 기본값
page number X 페이지 번호 1
limit number X 페이지당 항목 수 10
faqType string X FAQ 유형 필터 -
search string X 검색어 (질문 내용) -
useYn string X 사용 여부 필터 (Y/N) -

Response (성공 시)

interface AdminFaqListRes extends PaginationRes<AdminFaqListItem> {
  items: AdminFaqListItem[];
  total: number;
  page: number;
  limit: number;
  totalPages: number;
}

interface AdminFaqListItem {
  faqId: number;
  faqType: string;
  question: string;
  hitCnt: number;
  sortOrder: number;
  useYn: string;       // 사용 여부
  createdAt: string;
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요

9.2.2 FAQ 상세 조회

기본 정보

항목 내용
API명 FAQ 상세 조회 (관리자용)
엔드포인트 /api/admin/faq/:faqId
HTTP 메서드 GET
인증 필요 (Admin)
설명 특정 FAQ의 전체 정보 조회 (관리 정보 포함)

URL Parameters

필드 타입 필수 설명
faqId number O FAQ ID

Response (성공 시)

interface AdminFaqDetailRes {
  faq: AdminFaqItem;  // FAQ 전체 정보
}

interface AdminFaqItem {
  faqId: number;
  faqType: string;
  question: string;
  answer: string;
  hitCnt: number;
  sortOrder: number;
  useYn: string;
  createdAt: string;
  updatedAt?: string;
  createdBy?: string;
  updatedBy?: string;
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 22000 FAQ를 찾을 수 없음

9.2.3 FAQ 생성

기본 정보

항목 내용
API명 FAQ 생성 (관리자용)
엔드포인트 /api/admin/faq
HTTP 메서드 POST
인증 필요 (Admin)
설명 새로운 FAQ 생성

Request Body

interface AdminFaqCreateReq {
  faqType: string;    // FAQ 유형 (필수)
  question: string;   // 질문 (필수)
  answer: string;     // 답변 (필수)
  sortOrder?: number; // 정렬 순서 (선택)
  useYn?: string;     // 사용 여부 (기본값: 'Y')
}
필드 타입 필수 설명 제약사항
faqType string O FAQ 유형 코드 공통 코드 참조
question string O 질문 최대 500자
answer string O 답변 최대 2000자
sortOrder number X 정렬 순서 기본값: 0
useYn string X 사용 여부 (Y/N) 기본값: Y

Response (성공 시)

interface AdminFaqCreateRes {
  faqId: number;  // 생성된 FAQ ID
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
400 12001 필수 필드 누락
500 22001 FAQ 생성 실패

9.2.4 FAQ 수정

기본 정보

항목 내용
API명 FAQ 수정 (관리자용)
엔드포인트 /api/admin/faq/:faqId
HTTP 메서드 PUT
인증 필요 (Admin)
설명 FAQ 정보 수정

URL Parameters

필드 타입 필수 설명
faqId number O 수정할 FAQ ID

Request Body

interface AdminFaqUpdateReq {
  faqType?: string;
  question?: string;
  answer?: string;
  sortOrder?: number;
  useYn?: string;
}
필드 타입 필수 설명
faqType string X 새로운 FAQ 유형
question string X 새로운 질문
answer string X 새로운 답변
sortOrder number X 새로운 정렬 순서
useYn string X 사용 여부

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 22000 FAQ를 찾을 수 없음
500 22002 FAQ 수정 실패

9.2.5 FAQ 삭제

기본 정보

항목 내용
API명 FAQ 삭제 (관리자용)
엔드포인트 /api/admin/faq/:faqId
HTTP 메서드 DELETE
인증 필요 (Admin)
설명 특정 FAQ 삭제

URL Parameters

필드 타입 필수 설명
faqId number O 삭제할 FAQ ID

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 22000 FAQ를 찾을 수 없음
500 22003 FAQ 삭제 실패

9.2.6 FAQ 일괄 삭제

기본 정보

항목 내용
API명 FAQ 일괄 삭제 (관리자용)
엔드포인트 /api/admin/faq/delete
HTTP 메서드 POST
인증 필요 (Admin)
설명 여러 FAQ를 한 번에 삭제

Request Body

interface AdminFaqListDeleteReq {
  faqIds: number[];  // 삭제할 FAQ ID 목록 (필수)
}
필드 타입 필수 설명
faqIds number[] O 삭제할 FAQ ID 배열

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
400 12001 faqIds 필드 누락
500 22003 FAQ 삭제 실패

9.3 QnA 관리 API

관리자는 사용자 문의에 답변하고 QnA를 관리할 수 있습니다.

9.3.1 QnA 목록 조회

기본 정보

항목 내용
API명 QnA 목록 조회 (관리자용)
엔드포인트 /api/admin/qna
HTTP 메서드 GET
인증 필요 (Admin)
설명 QnA 목록 조회 (모든 글 조회 가능)

Query Parameters

필드 타입 필수 설명 기본값
page number X 페이지 번호 1
limit number X 페이지당 항목 수 10
search string X 검색어 (제목/내용) -
status string X 답변 상태 (Y: 완료, N: 대기) -
sort string X 정렬 createdAt-desc

Response (성공 시)

interface AdminQnaListRes extends PaginationRes<AdminQnaListItem> {
  items: AdminQnaListItem[];
  total: number;
  page: number;
  limit: number;
  totalPages: number;
}

interface AdminQnaListItem {
  qnaId: number;
  userId: number;      // 작성자 사용자 ID
  qnaType: string;
  title: string;
  secretYn: string;
  writerName: string;
  answeredYn: string;  // 답변 완료 여부
  createdAt: string;
  answeredAt?: string; // 답변일시
  hitCnt?: number;
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요

9.3.2 QnA 상세 조회

기본 정보

항목 내용
API명 QnA 상세 조회 (관리자용)
엔드포인트 /api/admin/qna/:qnaId
HTTP 메서드 GET
인증 필요 (Admin)
설명 특정 QnA의 전체 정보 조회 (답변 포함)

URL Parameters

필드 타입 필수 설명
qnaId number O QnA ID

Response (성공 시)

interface AdminQnaDetailRes {
  qna: AdminQnaDetailItem;
}

interface AdminQnaDetailItem {
  qnaId: number;
  userId: number;
  qnaType: string;
  title: string;
  content: string;
  secretYn: string;
  writerName: string;
  answeredYn: string;
  answerContent?: string;
  createdAt: string;
  answeredAt?: string;
  answeredBy?: number;  // 답변자 ID
  updatedAt?: string;
  deletedAt?: string;
  createdBy?: string;
  updatedBy?: string;
  deletedBy?: string;
  hitCnt?: number;
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 23000 QnA를 찾을 수 없음

9.3.3 QnA 답변 등록

기본 정보

항목 내용
API명 QnA 답변 등록 (관리자용)
엔드포인트 /api/admin/qna/:qnaId/answer
HTTP 메서드 POST
인증 필요 (Admin)
설명 사용자 문의에 답변 등록

URL Parameters

필드 타입 필수 설명
qnaId number O QnA ID

Request Body

interface AdminQnaAnswerReq {
  answer: string;       // 답변 내용 (필수)
  answeredBy?: string;  // 답변자 (선택)
}
필드 타입 필수 설명 제약사항
answer string O 답변 내용 최대 2000자
answeredBy string X 답변자 이름 최대 50자

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 23000 QnA를 찾을 수 없음
400 12001 답변 내용 누락
500 23004 QnA 답변 등록 실패

비고

  • 답변 등록 시 answeredYn이 자동으로 Y로 변경됩니다.

9.3.4 QnA 수정

기본 정보

항목 내용
API명 QnA 수정 (관리자용)
엔드포인트 /api/admin/qna/:qnaId
HTTP 메서드 PUT
인증 필요 (Admin)
설명 QnA 정보 수정 (질문 또는 답변 수정)

URL Parameters

필드 타입 필수 설명
qnaId number O 수정할 QnA ID

Request Body

interface AdminQnaUpdateReq {
  title?: string;
  content?: string;
  answerContent?: string;
  updatedBy?: string;
}
필드 타입 필수 설명
title string X 새로운 제목
content string X 새로운 질문 내용
answerContent string X 새로운 답변 내용
updatedBy string X 수정자

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 23000 QnA를 찾을 수 없음
500 23002 QnA 수정 실패

9.3.5 QnA 삭제

기본 정보

항목 내용
API명 QnA 삭제 (관리자용)
엔드포인트 /api/admin/qna/:qnaId
HTTP 메서드 DELETE
인증 필요 (Admin)
설명 특정 QnA 삭제

URL Parameters

필드 타입 필수 설명
qnaId number O 삭제할 QnA ID

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 23000 QnA를 찾을 수 없음
500 23003 QnA 삭제 실패

9.3.6 QnA 일괄 삭제

기본 정보

항목 내용
API명 QnA 일괄 삭제 (관리자용)
엔드포인트 /api/admin/qna/delete
HTTP 메서드 POST
인증 필요 (Admin)
설명 여러 QnA를 한 번에 삭제

Request Body

interface AdminQnaListDeleteReq {
  qnaIds: number[];  // 삭제할 QnA ID 목록 (필수)
}
필드 타입 필수 설명
qnaIds number[] O 삭제할 QnA ID 배열

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
400 12001 qnaIds 필드 누락
500 23003 QnA 삭제 실패

9.3.7 QnA 상태(통계) 조회

기본 정보

항목 내용
API명 QnA 상태 조회 (관리자용)
엔드포인트 /api/admin/qna/status
HTTP 메서드 GET
인증 필요 (Admin)
설명 QnA 답변 상태 통계 조회 (대시보드용)

Response (성공 시)

interface AdminQnaStatusRes {
  total: number;       // 전체 QnA 수
  answered: number;    // 답변 완료 수
  unanswered: number;  // 답변 대기 수
}
필드 타입 설명
total number 전체 QnA 개수
answered number 답변 완료된 QnA 개수
unanswered number 답변 대기 중인 QnA 개수

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요

비고

  • 관리자 대시보드에서 미답변 문의 현황을 확인할 때 사용합니다.

9.4 공지사항 관리 API

관리자는 공지사항을 생성, 수정, 삭제할 수 있습니다.

9.4.1 공지사항 목록 조회

기본 정보

항목 내용
API명 공지사항 목록 조회 (관리자용)
엔드포인트 /api/admin/notice
HTTP 메서드 GET
인증 필요 (Admin)
설명 공지사항 목록 조회 (비공개 포함, 관리 정보 포함)

Query Parameters

필드 타입 필수 설명 기본값
page number X 페이지 번호 1
limit number X 페이지당 항목 수 10
noticeType string X 공지 유형 필터 (G/S/E) -
publicYn string X 공개 여부 필터 (Y/N) -
pinnedYn string X 고정 여부 필터 (Y/N) -
search string X 검색어 (제목 내용) -

Response (성공 시)

interface AdminNoticeListRes extends PaginationRes<AdminNoticeListItem> {
  items: AdminNoticeListItem[];
  total: number;
  page: number;
  limit: number;
  totalPages: number;
}

interface AdminNoticeListItem {
  noticeId: number;
  title: string;
  noticeType: 'G' | 'S' | 'E';
  pinnedYn: 'Y' | 'N';
  publicYn: 'Y' | 'N';
  postedAt: string;
  startDt?: string;
  endDt?: string;
  createdAt: string;
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요

9.4.2 공지사항 상세 조회

기본 정보

항목 내용
API명 공지사항 상세 조회 (관리자용)
엔드포인트 /api/admin/notice/:noticeId
HTTP 메서드 GET
인증 필요 (Admin)
설명 특정 공지사항의 전체 정보 조회 (관리 정보 포함)

URL Parameters

필드 타입 필수 설명
noticeId number O 공지 ID

Response (성공 시)

interface AdminNoticeDetailRes {
  notice: AdminNoticeItem;
}

interface AdminNoticeItem {
  noticeId: number;
  title: string;
  content: string;
  noticeType: 'G' | 'S' | 'E';
  pinnedYn: 'Y' | 'N';
  publicYn: 'Y' | 'N';
  postedAt: string;
  startDt?: string;
  endDt?: string;
  createdBy?: string;
  updatedBy?: string;
  createdAt: string;
  updatedAt?: string;
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 21000 공지사항을 찾을 수 없음

9.4.3 공지사항 생성

기본 정보

항목 내용
API명 공지사항 생성 (관리자용)
엔드포인트 /api/admin/notice
HTTP 메서드 POST
인증 필요 (Admin)
설명 새로운 공지사항 생성

Request Body

interface AdminNoticeCreateReq {
  title: string;            // 제목 (필수)
  content: string;          // 내용 (필수)
  noticeType: 'G' | 'S' | 'E';  // 공지 유형 (필수)
  pinnedYn?: 'Y' | 'N';     // 고정 여부
  publicYn?: 'Y' | 'N';     // 공개 여부
  startDt?: string;         // 게시 시작일
  endDt?: string;           // 게시 종료일
  createdBy?: string;       // 작성자
}
필드 타입 필수 설명 제약사항
title string O 제목 최대 200자
content string O 내용 (HTML 가능) 최대 5000자
noticeType string O 공지 유형 G, S, E
pinnedYn string X 고정 여부 기본값: N
publicYn string X 공개 여부 기본값: Y
startDt string X 게시 시작일 (ISO 8601) -
endDt string X 게시 종료일 (ISO 8601) -
createdBy string X 작성자 최대 50자

Response (성공 시)

interface AdminNoticeCreateRes {
  noticeId: number;  // 생성된 공지 ID
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
400 12001 필수 필드 누락
500 21001 공지사항 생성 실패

9.4.4 공지사항 수정

기본 정보

항목 내용
API명 공지사항 수정 (관리자용)
엔드포인트 /api/admin/notice/:noticeId
HTTP 메서드 PUT
인증 필요 (Admin)
설명 공지사항 정보 수정

URL Parameters

필드 타입 필수 설명
noticeId number O 수정할 공지 ID

Request Body

interface AdminNoticeUpdateReq {
  title?: string;
  content?: string;
  noticeType?: 'G' | 'S' | 'E';
  pinnedYn?: 'Y' | 'N';
  publicYn?: 'Y' | 'N';
  startDt?: string;
  endDt?: string;
  updatedBy?: string;
}

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 21000 공지사항을 찾을 수 없음
500 21002 공지사항 수정 실패

9.4.5 공지사항 삭제

기본 정보

항목 내용
API명 공지사항 삭제 (관리자용)
엔드포인트 /api/admin/notice/:noticeId
HTTP 메서드 DELETE
인증 필요 (Admin)
설명 특정 공지사항 삭제

URL Parameters

필드 타입 필수 설명
noticeId number O 삭제할 공지 ID

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 21000 공지사항을 찾을 수 없음
500 21003 공지사항 삭제 실패

9.4.6 공지사항 일괄 삭제

기본 정보

항목 내용
API명 공지사항 일괄 삭제 (관리자용)
엔드포인트 /api/admin/notice/delete
HTTP 메서드 POST
인증 필요 (Admin)
설명 여러 공지사항을 한 번에 삭제

Request Body

interface AdminNoticeListDeleteReq {
  noticeIds: number[];  // 삭제할 공지 ID 목록 (필수)
}

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
400 12001 noticeIds 필드 누락
500 21003 공지사항 삭제 실패

9.5 OpenAPI 키 관리 API

관리자는 사용자의 OpenAPI 인증키를 승인/반려하고 관리할 수 있습니다.

9.5.1 OpenAPI 키 목록 조회

기본 정보

항목 내용
API명 OpenAPI 키 목록 조회 (관리자용)
엔드포인트 /api/admin/openapi/keys
HTTP 메서드 GET
인증 필요 (Admin)
설명 모든 사용자의 OpenAPI 인증키 목록 조회

Query Parameters

필드 타입 필수 설명 기본값
page number X 페이지 번호 1
limit number X 페이지당 항목 수 10
userId number X 사용자 ID 필터 -
activeYn string X 활성 상태 필터 -
searchKeyword string X 검색어 (키 이름) -
pendingOnly boolean X 승인 대기만 조회 false

Response (성공 시)

interface AdminOpenApiListRes extends PaginationRes<AdminOpenApiKeyListItem> {
  items: AdminOpenApiKeyListItem[];
  total: number;
  page: number;
  limit: number;
  totalPages: number;
}

interface AdminOpenApiKeyListItem {
  keyId: number;
  userId: number;
  authKey: string;      // 마스킹 처리됨
  activeYn: string;     // Y: 승인, N: 반려, P: 대기
  startDt?: string;
  endDt?: string;
  delYn: string;
  keyName: string;
  activeAt?: string;
  latestAccAt?: string;
  createdAt: string;
}

activeYn 상태 값

값 설명
Y 승인됨
N 반려됨
P 승인 대기 중

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요

9.5.2 OpenAPI 키 상세 조회

기본 정보

항목 내용
API명 OpenAPI 키 상세 조회 (관리자용)
엔드포인트 /api/admin/openapi/keys/:keyId
HTTP 메서드 GET
인증 필요 (Admin)
설명 특정 OpenAPI 인증키의 전체 정보 조회

URL Parameters

필드 타입 필수 설명
keyId number O 키 ID

Response (성공 시)

interface AdminOpenApiDetailRes {
  authKey: AdminOpenApiKeyItem;
}

interface AdminOpenApiKeyItem {
  keyId: number;
  userId: number;
  authKey: string;
  activeYn: string;
  startDt?: string;
  endDt?: string;
  delYn: string;
  keyName: string;
  keyDesc: string;
  keyRejectReason?: string;  // 반려 사유
  activeAt?: string;
  latestAccAt?: string;
  createdAt: string;
  updatedAt?: string;
  deletedAt?: string;
  createdBy: string;
  updatedBy?: string;
  deletedBy?: string;
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 24000 OpenAPI 키를 찾을 수 없음

9.5.3 OpenAPI 키 생성

기본 정보

항목 내용
API명 OpenAPI 키 생성 (관리자용)
엔드포인트 /api/admin/openapi/keys
HTTP 메서드 POST
인증 필요 (Admin)
설명 관리자가 직접 OpenAPI 인증키 생성

Request Body

interface AdminOpenApiCreateReq {
  userId: number;       // 사용자 ID (필수)
  keyName: string;      // API 이름 (필수)
  keyDesc: string;      // 사용 목적 (필수)
  startDt?: string;     // 유효 시작일
  endDt?: string;       // 유효 종료일
  createdBy: string;    // 생성자 (필수)
}

Response (성공 시)

interface AdminOpenApiCreateRes {
  keyId: number;    // 생성된 키 ID
  authKey: string;  // 생성된 인증키
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 16000 사용자를 찾을 수 없음
400 12001 필수 필드 누락
500 24001 OpenAPI 키 생성 실패

9.5.4 OpenAPI 키 수정 (승인/반려)

기본 정보

항목 내용
API명 OpenAPI 키 수정 (관리자용)
엔드포인트 /api/admin/openapi/keys/:keyId
HTTP 메서드 PUT
인증 필요 (Admin)
설명 OpenAPI 인증키 정보 수정 (승인/반려 처리)

URL Parameters

필드 타입 필수 설명
keyId number O 수정할 키 ID

Request Body

interface AdminOpenApiUpdateReq {
  keyName?: string;
  keyDesc?: string;
  startDt?: string;
  endDt?: string;
  activeYn?: string;        // 승인 상태 (Y: 승인, N: 반려)
  rejectReason?: string;    // 반려 사유 (activeYn이 N일 때 필수)
  updatedBy: string;        // 수정자 (필수)
}
필드 타입 필수 설명
keyName string X 새로운 API 이름
keyDesc string X 새로운 사용 목적
startDt string X 새로운 시작일
endDt string X 새로운 종료일
activeYn string X 승인 상태 (Y: 승인, N: 반려)
rejectReason string X 반려 사유 (반려 시 필수)
updatedBy string O 수정자

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 24000 OpenAPI 키를 찾을 수 없음
400 12001 필수 필드 누락
500 24002 OpenAPI 키 수정 실패

비고

  • activeYn을 Y로 변경하면 키가 승인되어 사용 가능해집니다.
  • activeYn을 N으로 변경하면 반려되며, rejectReason 필드가 필수입니다.

9.5.5 OpenAPI 키 삭제

기본 정보

항목 내용
API명 OpenAPI 키 삭제 (관리자용)
엔드포인트 /api/admin/openapi/keys/:keyId
HTTP 메서드 DELETE
인증 필요 (Admin)
설명 특정 OpenAPI 인증키 삭제

URL Parameters

필드 타입 필수 설명
keyId number O 삭제할 키 ID

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 24000 OpenAPI 키를 찾을 수 없음
500 24003 OpenAPI 키 삭제 실패

9.5.6 OpenAPI 키 일괄 삭제

기본 정보

항목 내용
API명 OpenAPI 키 일괄 삭제 (관리자용)
엔드포인트 /api/admin/openapi/keys/delete
HTTP 메서드 POST
인증 필요 (Admin)
설명 여러 OpenAPI 인증키를 한 번에 삭제

Request Body

interface AdminOpenApiListDeleteReq {
  keyIds: number[];  // 삭제할 키 ID 목록 (필수)
}

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
400 12001 keyIds 필드 누락
500 24003 OpenAPI 키 삭제 실패

9.5.7 OpenAPI 키 기간 연장

기본 정보

항목 내용
API명 OpenAPI 키 기간 연장 (관리자용)
엔드포인트 /api/admin/openapi/keys/:keyId/extend
HTTP 메서드 POST
인증 필요 (Admin)
설명 OpenAPI 인증키 유효 기간 연장

URL Parameters

필드 타입 필수 설명
keyId number O 연장할 키 ID

Request Body

interface AdminOpenApiExtendReq {
  startDt?: string;     // 새로운 시작일
  endDt?: string;       // 새로운 종료일
  updatedBy: string;    // 수정자 (필수)
}

Response (성공 시)

interface AdminOpenApiExtendRes {
  startDt?: string;  // 연장된 시작일
  endDt?: string;    // 연장된 종료일
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 24000 OpenAPI 키를 찾을 수 없음
500 24004 OpenAPI 키 연장 실패

9.5.8 OpenAPI 상태(통계) 조회

기본 정보

항목 내용
API명 OpenAPI 상태 조회 (관리자용)
엔드포인트 /api/admin/openapi/status
HTTP 메서드 GET
인증 필요 (Admin)
설명 OpenAPI 인증키 상태 통계 조회 (대시보드용)

Response (성공 시)

interface AdminOpenApiStatsRes {
  total: number;      // 전체 키 수
  active: number;     // 승인된 키 수
  expired: number;    // 만료된 키 수
  inactive: number;   // 비활성/반려된 키 수
  pending: number;    // 승인 대기 중인 키 수
}
필드 타입 설명
total number 전체 OpenAPI 키 개수
active number 승인되어 사용 가능한 키 개수
expired number 유효 기간이 만료된 키 개수
inactive number 비활성 또는 반려된 키 개수
pending number 승인 대기 중인 키 개수

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요

비고

  • 관리자 대시보드에서 OpenAPI 승인 대기 현황을 확인할 때 사용합니다.

9.6 운영자 계정 관리 API (S-Admin 전용)

권한: S-ADMIN만 접근 가능

운영자 계정을 생성, 수정, 삭제하고 역할을 관리합니다.

9.6.1 운영자 계정 목록 조회

기본 정보

항목 내용
API명 운영자 계정 목록 조회
엔드포인트 /api/admin/accounts/admin
HTTP 메서드 GET
인증 필요 (S-Admin)
설명 운영자 계정 목록 조회

Query Parameters

필드 타입 필수 설명 기본값
page number X 페이지 번호 1
limit number X 페이지당 항목 수 10
search string X 검색어 (ID/이름) -
status string X 상태 필터 -
role string X 역할 필터 -
affiliation string X 소속 필터 -

Response (성공 시)

interface AdminAccountListRes extends PaginationRes<AdminAccountListItem> {
  items: AdminAccountListItem[];
  total: number;
  page: number;
  limit: number;
  totalPages: number;
}

interface AdminAccountListItem {
  adminId: number;
  loginId: string;
  name: string;
  role: string;
  roleName: string;
  status: string;
  delYn: string;
  createdAt: string;
  lastLoginAt?: string;
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 S-Admin 권한 필요

9.6.2 운영자 계정 상세 조회

기본 정보

항목 내용
API명 운영자 계정 상세 조회
엔드포인트 /api/admin/accounts/admin/:adminId
HTTP 메서드 GET
인증 필요 (S-Admin)
설명 특정 운영자 계정의 전체 정보 조회

URL Parameters

필드 타입 필수 설명
adminId number O 운영자 ID

Response (성공 시)

interface AdminAccountDetailRes {
  admin: AdminAccount;
}

interface AdminAccount {
  adminId: number;
  loginId: string;
  name: string;
  role: string;
  roleName: string;
  affiliation?: string;
  description?: string;
  note?: string;
  status: string;
  delYn: string;
  createdAt: string;
  updatedAt?: string;
  deletedAt?: string;
  lastLoginAt?: string;
  createdBy: string;
  updatedBy?: string;
  deletedBy?: string;
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 S-Admin 권한 필요
404 17000 관리자를 찾을 수 없음

9.6.3 운영자 계정 생성

기본 정보

항목 내용
API명 운영자 계정 생성
엔드포인트 /api/admin/accounts/admin
HTTP 메서드 POST
인증 필요 (S-Admin)
설명 새로운 운영자 계정 생성

Request Body

interface AdminAccountCreateReq {
  loginId: string;      // 로그인 ID (필수)
  password: string;     // 비밀번호 (필수)
  name: string;         // 이름 (필수)
  role: string;         // 역할 코드 (필수)
  affiliation?: string; // 소속
  description?: string; // 설명
  note?: string;        // 비고
  status?: string;      // 상태 (기본값: 활성)
}
필드 타입 필수 설명 제약사항
loginId string O 로그인 ID 4~20자, 고유값
password string O 비밀번호 8~자, 영문+숫자+특수문자
name string O 이름 2~50자
role string O 역할 코드 (S-ADMIN, ADMIN 등) 공통 코드 참조
affiliation string X 소속 최대 100자
description string X 설명 최대 200자
note string X 비고 최대 500자
status string X 상태 기본값: 활성

Response (성공 시)

interface AdminAccountCreateRes {
  adminId: number;  // 생성된 운영자 ID
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 S-Admin 권한 필요
409 17001 이미 존재하는 로그인 ID
400 12001 필수 필드 누락
500 17002 운영자 계정 생성 실패

9.6.4 운영자 계정 수정

기본 정보

항목 내용
API명 운영자 계정 수정
엔드포인트 /api/admin/accounts/admin/:adminId
HTTP 메서드 PUT
인증 필요 (S-Admin)
설명 운영자 계정 정보 수정

URL Parameters

필드 타입 필수 설명
adminId number O 수정할 운영자 ID

Request Body

interface AdminAccountUpdateReq {
  name?: string;
  role?: string;
  affiliation?: string;
  description?: string;
  note?: string;
  status?: string;
}

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 S-Admin 권한 필요
404 17000 관리자를 찾을 수 없음
500 17003 운영자 계정 수정 실패

비고

  • 로그인 ID는 수정할 수 없습니다.

9.6.5 운영자 계정 삭제

기본 정보

항목 내용
API명 운영자 계정 삭제
엔드포인트 /api/admin/accounts/admin/:adminId
HTTP 메서드 DELETE
인증 필요 (S-Admin)
설명 운영자 계정 삭제

URL Parameters

필드 타입 필수 설명
adminId number O 삭제할 운영자 ID

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 S-Admin 권한 필요
404 17000 관리자를 찾을 수 없음
500 17004 운영자 계정 삭제 실패

비고

  • 자기 자신의 계정은 삭제할 수 없습니다.

9.6.6 운영자 계정 일괄 삭제

기본 정보

항목 내용
API명 운영자 계정 일괄 삭제
엔드포인트 /api/admin/accounts/admin/delete
HTTP 메서드 POST
인증 필요 (S-Admin)
설명 여러 운영자 계정을 한 번에 삭제

Request Body

interface AdminAccountListDeleteReq {
  adminIds: number[];  // 삭제할 운영자 ID 목록 (필수)
}

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 S-Admin 권한 필요
400 12001 adminIds 필드 누락
500 17004 운영자 계정 삭제 실패

9.6.7 운영자 비밀번호 변경

기본 정보

항목 내용
API명 운영자 비밀번호 변경
엔드포인트 /api/admin/accounts/admin/:adminId/password
HTTP 메서드 PUT
인증 필요 (S-Admin)
설명 운영자 계정의 비밀번호 강제 변경

URL Parameters

필드 타입 필수 설명
adminId number O 운영자 ID

Request Body

interface AdminAccountPasswordChangeReq {
  newPassword: string;  // 새 비밀번호 (필수)
}

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 S-Admin 권한 필요
404 17000 관리자를 찾을 수 없음
400 16004 새 비밀번호가 너무 약함
500 17005 비밀번호 변경 실패

비고

  • S-Admin은 현재 비밀번호 없이 다른 운영자의 비밀번호를 강제로 변경할 수 있습니다.

9.6.8 운영자 역할 변경

기본 정보

항목 내용
API명 운영자 역할 변경
엔드포인트 /api/admin/accounts/admin/:adminId/role
HTTP 메서드 PUT
인증 필요 (S-Admin)
설명 운영자의 역할 변경

URL Parameters

필드 타입 필수 설명
adminId number O 운영자 ID

Request Body

interface AdminAccountRoleUpdateReq {
  role: string;     // 새로운 역할 (필수)
  reason?: string;  // 변경 사유
}
필드 타입 필수 설명
role string O 새로운 역할 코드 (S-ADMIN, ADMIN 등)
reason string X 역할 변경 사유

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 S-Admin 권한 필요
404 17000 관리자를 찾을 수 없음
404 20060 유효하지 않은 역할 코드
500 17003 역할 변경 실패

비고

  • 자기 자신의 역할은 변경할 수 없습니다.

9.6.9 운영자 이메일(로그인ID) 중복 체크

기본 정보

항목 내용
API명 운영자 이메일 중복 체크
엔드포인트 /api/admin/accounts/admin/email/check
HTTP 메서드 POST
인증 필요 (S-Admin)
설명 운영자 계정 생성 전 로그인 ID 중복 확인

Request Body

interface AdminAccountCheckEmailReq {
  loginId: string;  // 확인할 로그인 ID (필수)
}

Response (성공 시)

interface AdminAccountCheckEmailRes {
  available: boolean;  // 사용 가능 여부
}
필드 타입 설명
available boolean true: 사용 가능, false: 이미 사용 중

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 S-Admin 권한 필요
400 12001 loginId 필드 누락

9.7 사용자 계정 관리 API

권한: Admin (S-ADMIN, ADMIN 모두 접근 가능)

관리자가 일반 사용자 계정을 관리합니다.

9.7.1 사용자 계정 목록 조회

기본 정보

항목 내용
API명 사용자 계정 목록 조회
엔드포인트 /api/admin/accounts/user
HTTP 메서드 GET
인증 필요 (Admin)
설명 사용자 계정 목록 조회

Query Parameters

필드 타입 필수 설명 기본값
page number X 페이지 번호 1
limit number X 페이지당 항목 수 10
search string X 검색어 (이메일/이름) -
status string X 상태 필터 -
email string X 이메일 필터 -

Response (성공 시)

interface UserAccountListRes extends PaginationRes<UserAccountListItem> {
  items: UserAccountListItem[];
  total: number;
  page: number;
  limit: number;
  totalPages: number;
}

interface UserAccountListItem {
  userId: number;
  loginId: string;        // 이메일
  name: string;
  status: string;
  latestKeyCreatedAt?: string;
  latestLoginAt?: string;
  keyCount: number;       // OpenAPI 키 개수
  delYn: string;
  createdAt: string;
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요

9.7.2 사용자 계정 상세 조회

기본 정보

항목 내용
API명 사용자 계정 상세 조회
엔드포인트 /api/admin/accounts/user/:userId
HTTP 메서드 GET
인증 필요 (Admin)
설명 특정 사용자 계정의 전체 정보 조회

URL Parameters

필드 타입 필수 설명
userId number O 사용자 ID

Response (성공 시)

interface UserAccountDetailRes {
  user: UserAccount;
}

interface UserAccount {
  userId: number;
  loginId: string;
  name: string;
  status: string;
  affiliation?: string;
  note?: string;
  latestKeyCreatedAt?: string;
  latestLoginAt?: string;
  keyCount: number;
  delYn: string;
  createdAt: string;
  updatedAt?: string;
  deletedAt?: string;
  createdBy: string;
  updatedBy?: string;
  deletedBy?: string;
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 16000 사용자를 찾을 수 없음

9.7.3 사용자 계정 생성

기본 정보

항목 내용
API명 사용자 계정 생성
엔드포인트 /api/admin/accounts/user
HTTP 메서드 POST
인증 필요 (Admin)
설명 관리자가 사용자 계정 생성

Request Body

interface UserAccountCreateReq {
  loginId: string;      // 이메일 (필수)
  password: string;     // 비밀번호 (필수)
  name: string;         // 이름 (필수)
  affiliation?: string; // 소속
  note?: string;        // 비고 (관리용)
  status?: string;      // 상태 (기본값: 활성)
}

Response (성공 시)

interface UserAccountCreateRes {
  userId: number;  // 생성된 사용자 ID
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
409 12020 이미 사용 중인 이메일
400 12001 필수 필드 누락
500 20001 사용자 계정 생성 실패

9.7.4 사용자 계정 수정

기본 정보

항목 내용
API명 사용자 계정 수정
엔드포인트 /api/admin/accounts/user/:userId
HTTP 메서드 PUT
인증 필요 (Admin)
설명 사용자 계정 정보 수정

URL Parameters

필드 타입 필수 설명
userId number O 수정할 사용자 ID

Request Body

interface UserAccountUpdateReq {
  name?: string;
  status?: string;
  affiliation?: string;
  note?: string;
}

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 16000 사용자를 찾을 수 없음
500 20002 사용자 계정 수정 실패

비고

  • 이메일(로그인 ID)은 수정할 수 없습니다.

9.7.5 사용자 계정 삭제

기본 정보

항목 내용
API명 사용자 계정 삭제
엔드포인트 /api/admin/accounts/user/:userId
HTTP 메서드 DELETE
인증 필요 (Admin)
설명 사용자 계정 삭제

URL Parameters

필드 타입 필수 설명
userId number O 삭제할 사용자 ID

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 16000 사용자를 찾을 수 없음
500 20003 사용자 계정 삭제 실패

9.7.6 사용자 계정 일괄 삭제

기본 정보

항목 내용
API명 사용자 계정 일괄 삭제
엔드포인트 /api/admin/accounts/user/delete
HTTP 메서드 POST
인증 필요 (Admin)
설명 여러 사용자 계정을 한 번에 삭제

Request Body

interface UserAccountListDeleteReq {
  userIds: number[];  // 삭제할 사용자 ID 목록 (필수)
}

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
400 12001 userIds 필드 누락
500 20003 사용자 계정 삭제 실패

9.7.7 사용자 비밀번호 변경

기본 정보

항목 내용
API명 사용자 비밀번호 변경
엔드포인트 /api/admin/accounts/user/:userId/password
HTTP 메서드 PUT
인증 필요 (Admin)
설명 사용자의 비밀번호 강제 변경

URL Parameters

필드 타입 필수 설명
userId number O 사용자 ID

Request Body

interface UserAccountPasswordChangeReq {
  newPassword: string;  // 새 비밀번호 (필수)
}

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 16000 사용자를 찾을 수 없음
400 16004 새 비밀번호가 너무 약함
500 20002 비밀번호 변경 실패

비고

  • 관리자는 현재 비밀번호 없이 사용자의 비밀번호를 강제로 변경할 수 있습니다.

9.7.8 사용자 상태 변경

기본 정보

항목 내용
API명 사용자 상태 변경
엔드포인트 /api/admin/accounts/user/:userId/status
HTTP 메서드 PUT
인증 필요 (Admin)
설명 사용자 계정의 상태 변경 (활성/비활성)

URL Parameters

필드 타입 필수 설명
userId number O 사용자 ID

Request Body

interface UserAccountStatusUpdateReq {
  status: string;    // 새로운 상태 (필수)
  reason?: string;   // 변경 사유
}
필드 타입 필수 설명
status string O 새로운 상태 (활성/비활성 등)
reason string X 상태 변경 사유

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 16000 사용자를 찾을 수 없음
500 20002 상태 변경 실패

비고

  • 계정을 비활성화하면 사용자는 로그인할 수 없습니다.

9.7.9 사용자 이메일 중복 체크

기본 정보

항목 내용
API명 사용자 이메일 중복 체크
엔드포인트 /api/admin/accounts/user/email/check
HTTP 메서드 POST
인증 필요 (Admin)
설명 사용자 계정 생성 전 이메일 중복 확인

Request Body

interface UserAccountCheckEmailReq {
  email: string;  // 확인할 이메일 (필수)
}

Response (성공 시)

interface UserAccountCheckEmailRes {
  available: boolean;  // 사용 가능 여부
}
필드 타입 설명
available boolean true: 사용 가능, false: 이미 사용 중

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
400 12001 email 필드 누락
400 12021 이메일 형식 오류

10. API 상세 규격 - 공통 코드 API

공통 코드 API는 시스템 전체에서 사용되는 코드 그룹 및 코드 값을 관리합니다.

Base Path: /api/code

공통 코드 구조:

  • 그룹 (Group): 코드들의 집합 (예: sys_admin_roles, faq_type)
  • 코드 (Code): 그룹 내의 개별 코드 값 (예: S-ADMIN, ADMIN)

API 분류:

  • 10.1: 사용자용 조회 API (제한된 정보만 제공)
  • 10.2: 관리자용 상세 조회 API (관리 정보 포함)
  • 10.3: 관리자용 그룹 관리 API (생성/수정/삭제)
  • 10.4: 관리자용 코드 관리 API (생성/수정/삭제)

10.1 사용자용 조회 API

10.1.1 그룹별 코드 조회

기본 정보

항목 내용
API명 그룹별 코드 조회 (사용자용)
엔드포인트 /api/code/:grpId
HTTP 메서드 GET
인증 불필요 (Public)
설명 특정 그룹에 속한 코드 목록 조회 (활성 코드만)

URL Parameters

필드 타입 필수 설명
grpId string O 조회할 그룹 ID (예: sys_admin_roles)

Response DTO

interface CommonCodeByGroupRes {
  codes: CommonCode[];  // 코드 목록
}

interface CommonCode {
  grpId: string;         // 그룹 ID
  grpNm: string;         // 그룹명
  codeId: string;        // 코드 ID
  codeNm: string;        // 코드명
  parentGrpId?: string;  // 부모 그룹 ID (계층 구조인 경우)
  parentCodeId?: string; // 부모 코드 ID (계층 구조인 경우)
  codeType: 'B' | 'A' | 'S';  // 코드 타입
  codeLvl?: number;      // 코드 레벨 (계층 구조인 경우)
  sortOrder?: number;    // 정렬 순서
  codeDes?: string;      // 코드 설명
}

발생 가능한 에러

HTTP 에러 코드 설명
404 13020 시스템 코드 그룹을 찾을 수 없음

10.1.2 코드 상세 조회

기본 정보

항목 내용
API명 코드 상세 조회 (사용자용)
엔드포인트 /api/code/:grpId/:codeId
HTTP 메서드 GET
인증 불필요 (Public)
설명 특정 코드의 상세 정보 조회

URL Parameters

필드 타입 필수 설명
grpId string O 그룹 ID
codeId string O 코드 ID

Response DTO

interface CommonCodeByIdRes {
  code: CommonCode;  // 코드 정보
}

발생 가능한 에러

HTTP 에러 코드 설명
404 13000 시스템 코드를 찾을 수 없음

10.1.3 타입별 코드 조회

기본 정보

항목 내용
API명 타입별 코드 조회 (사용자용)
엔드포인트 /api/code/type/:codeType
HTTP 메서드 GET
인증 불필요 (Public)
설명 특정 타입의 모든 코드 조회

URL Parameters

필드 타입 필수 설명 가능한 값
codeType string O 코드 타입 B, A, S

Response DTO

interface CommonCodeByTypeRes {
  codes: CommonCode[];  // 코드 목록
}

10.1.4 부모 코드 기반 조회 (계층형)

기본 정보

항목 내용
API명 부모 코드 기반 조회 (사용자용)
엔드포인트 /api/code/:grpId/parent
HTTP 메서드 GET
인증 불필요 (Public)
설명 특정 부모 코드의 하위 코드 조회 (계층 구조)

URL Parameters

필드 타입 필수 설명
grpId string O 그룹 ID

Query Parameters

필드 타입 필수 설명
parentCodeId string X 부모 코드 ID (없으면 최상위 코드 조회)

Response DTO

interface CommonCodeByParentRes {
  codes: CommonCode[];  // 코드 목록
}

10.2 관리자용 상세 조회 API

10.2.1 그룹별 코드 조회 (관리자용)

기본 정보

항목 내용
API명 그룹별 코드 조회 (관리자용)
엔드포인트 /api/code/admin/:grpId
HTTP 메서드 GET
인증 필요 (Admin)
설명 특정 그룹의 모든 코드 조회 (관리 정보 포함, 비활성 코드 포함)

URL Parameters

필드 타입 필수 설명
grpId string O 그룹 ID

Response DTO

interface CommonCodeByGroupDetailRes {
  codes: CommonCodeDetail[];  // 코드 목록 (상세 정보)
}

interface CommonCodeDetail {
  grpId: string;
  grpNm: string;
  codeId: string;
  codeNm: string;
  parentGrpId?: string;
  parentCodeId?: string;
  codeType: 'B' | 'A' | 'S';
  codeLvl?: number;
  sortOrder?: number;
  useYn?: 'Y' | 'N';      // 사용 여부
  delYn?: 'Y' | 'N';      // 삭제 여부
  codeDes?: string;
  memo?: string;           // 관리자 메모
  createdAt?: string;      // 생성일시
  updatedAt?: string;      // 수정일시
  deletedAt?: string;      // 삭제일시
  createdBy?: string;      // 생성자
  updatedBy?: string;      // 수정자
  deletedBy?: string;      // 삭제자
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 13020 시스템 코드 그룹을 찾을 수 없음

10.2.2 코드 상세 조회 (관리자용)

기본 정보

항목 내용
API명 코드 상세 조회 (관리자용)
엔드포인트 /api/code/admin/:grpId/:codeId
HTTP 메서드 GET
인증 필요 (Admin)
설명 특정 코드의 전체 정보 조회 (관리 정보 포함)

URL Parameters

필드 타입 필수 설명
grpId string O 그룹 ID
codeId string O 코드 ID

Response DTO

interface CommonCodeByIdDetailRes {
  code: CommonCodeDetail;  // 코드 상세 정보
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 13000 시스템 코드를 찾을 수 없음

10.2.3 타입별 코드 조회 (관리자용)

기본 정보

항목 내용
API명 타입별 코드 조회 (관리자용)
엔드포인트 /api/code/admin/type/:codeType
HTTP 메서드 GET
인증 필요 (Admin)
설명 특정 타입의 모든 코드 조회 (관리 정보 포함)

URL Parameters

필드 타입 필수 설명 가능한 값
codeType string O 코드 타입 B, A, S

Response DTO

interface CommonCodeByTypeDetailRes {
  codes: CommonCodeDetail[];  // 코드 목록
}

10.2.4 부모 코드 기반 조회 (관리자용)

기본 정보

항목 내용
API명 부모 코드 기반 조회 (관리자용)
엔드포인트 /api/code/admin/:grpId/parent
HTTP 메서드 GET
인증 필요 (Admin)
설명 특정 부모 코드의 하위 코드 조회 (관리 정보 포함)

URL Parameters

필드 타입 필수 설명
grpId string O 그룹 ID

Query Parameters

필드 타입 필수 설명
parentCodeId string X 부모 코드 ID

Response DTO

interface CommonCodeByParentDetailRes {
  codes: CommonCodeDetail[];  // 코드 목록
}

10.3 관리자용 그룹 관리 API

10.3.1 그룹 목록 조회

기본 정보

항목 내용
API명 그룹 목록 조회 (관리자용)
엔드포인트 /api/code/admin/groups
HTTP 메서드 GET
인증 필요 (Admin)
설명 모든 코드 그룹 목록 조회

Query Parameters

필드 타입 필수 설명
search string X 그룹 ID 또는 그룹명으로 검색
useYn string X 사용 여부 필터 (Y, N)
sort string X 정렬 기준 (기본값: 그룹 ID 오름차순)

Response DTO

interface CommonCodeGroupsRes {
  groups: CommonCodeGroup[];  // 그룹 목록
}

interface CommonCodeGroup {
  grpId: string;       // 그룹 ID
  grpNm: string;       // 그룹명
  codeType?: 'B' | 'A' | 'S';  // 코드 타입
  codeCount: number;   // 그룹 내 코드 개수
  createdAt?: string;  // 생성일시
  updatedAt?: string;  // 수정일시
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요

10.3.2 그룹 생성

기본 정보

항목 내용
API명 그룹 생성 (관리자용)
엔드포인트 /api/code/admin/group
HTTP 메서드 POST
인증 필요 (Admin)
설명 새로운 코드 그룹 생성 (코드 포함)

Request Body

interface CommonCodeGroupCreateReq {
  grpId: string;        // 그룹 ID (필수)
  grpNm: string;        // 그룹명 (필수)
  codeType: 'B' | 'A' | 'S';  // 코드 타입 (필수)
  codeDes?: string;     // 그룹 설명
  codes: Array<{        // 초기 코드 목록 (필수)
    codeId: string;     // 코드 ID
    codeNm: string;     // 코드명
    parentCodeId?: string;  // 부모 코드 ID (계층 구조)
    codeLvl?: number;   // 코드 레벨
    sortOrder?: number; // 정렬 순서
    codeDes?: string;   // 코드 설명
  }>;
}
필드 타입 필수 설명
grpId string O 그룹 ID (고유값, 변경 불가)
grpNm string O 그룹명
codeType string O 코드 타입 (B: 기본, A: 고급, S: 시스템)
codeDes string X 그룹 설명
codes array O 초기 코드 목록 (최소 1개 이상)

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
409 13025 이미 존재하는 그룹 ID
400 12001 필수 필드 누락
500 13021 그룹 생성 실패

10.3.3 그룹 수정

기본 정보

항목 내용
API명 그룹 수정 (관리자용)
엔드포인트 /api/code/admin/group/:grpId
HTTP 메서드 PUT
인증 필요 (Admin)
설명 코드 그룹 정보 수정 (그룹명, 설명만 수정 가능)

URL Parameters

필드 타입 필수 설명
grpId string O 수정할 그룹 ID

Request Body

interface CommonCodeGroupUpdateReq {
  grpNm: string;      // 그룹명 (필수)
  codeDes?: string;   // 그룹 설명
}
필드 타입 필수 설명
grpNm string O 새로운 그룹명
codeDes string X 새로운 그룹 설명

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 13020 그룹을 찾을 수 없음
500 13022 그룹 수정 실패

비고

  • 그룹 ID는 수정할 수 없습니다.
  • 그룹에 속한 코드는 이 API로 수정할 수 없습니다 (10.4 참조).

10.3.4 그룹 삭제

기본 정보

항목 내용
API명 그룹 삭제 (관리자용)
엔드포인트 /api/code/admin/group/:grpId
HTTP 메서드 DELETE
인증 필요 (Admin)
설명 코드 그룹 삭제 (그룹 내 모든 코드도 함께 삭제)

URL Parameters

필드 타입 필수 설명
grpId string O 삭제할 그룹 ID

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 13020 그룹을 찾을 수 없음
500 13023 그룹 삭제 실패

비고

  • 그룹 삭제 시 그룹 내 모든 코드도 함께 삭제됩니다.
  • 시스템에서 사용 중인 중요 그룹은 삭제할 수 없습니다.

10.3.5 그룹 일괄 삭제

기본 정보

항목 내용
API명 그룹 일괄 삭제 (관리자용)
엔드포인트 /api/code/admin/groups/delete
HTTP 메서드 POST
인증 필요 (Admin)
설명 여러 그룹을 한 번에 삭제

Request Body

interface CommonCodeGroupListDeleteReq {
  grpIds: string[];  // 삭제할 그룹 ID 목록 (필수)
}
필드 타입 필수 설명
grpIds string[] O 삭제할 그룹 ID 배열

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
400 12001 grpIds 필드 누락
500 13023 그룹 삭제 실패

10.4 관리자용 코드 관리 API

10.4.1 코드 생성

기본 정보

항목 내용
API명 코드 생성 (관리자용)
엔드포인트 /api/code/admin/:grpId/code
HTTP 메서드 POST
인증 필요 (Admin)
설명 특정 그룹에 새로운 코드 추가

URL Parameters

필드 타입 필수 설명
grpId string O 그룹 ID

Request Body

interface CommonCodeCodeCreateReq {
  codeId: string;        // 코드 ID (필수)
  codeNm: string;        // 코드명 (필수)
  parentCodeId?: string; // 부모 코드 ID (계층 구조인 경우)
  codeLvl?: number;      // 코드 레벨
  sortOrder?: number;    // 정렬 순서
  codeDes?: string;      // 코드 설명
}
필드 타입 필수 설명
codeId string O 코드 ID (그룹 내 고유값)
codeNm string O 코드명
parentCodeId string X 부모 코드 ID (계층 구조)
codeLvl number X 코드 레벨 (1부터 시작)
sortOrder number X 정렬 순서 (기본값: 0)
codeDes string X 코드 설명

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 13020 그룹을 찾을 수 없음
409 13005 이미 존재하는 코드 ID
400 12001 필수 필드 누락
500 13001 코드 생성 실패

10.4.2 코드 수정

기본 정보

항목 내용
API명 코드 수정 (관리자용)
엔드포인트 /api/code/admin/:grpId/:codeId
HTTP 메서드 PUT
인증 필요 (Admin)
설명 코드 정보 수정

URL Parameters

필드 타입 필수 설명
grpId string O 그룹 ID
codeId string O 수정할 코드 ID

Request Body

interface CommonCodeCodeUpdateReq {
  codeNm: string;      // 코드명 (필수)
  codeDes?: string;    // 코드 설명
  sortOrder?: number;  // 정렬 순서
}
필드 타입 필수 설명
codeNm string O 새로운 코드명
codeDes string X 새로운 코드 설명
sortOrder number X 새로운 정렬 순서

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 13000 코드를 찾을 수 없음
500 13002 코드 수정 실패

비고

  • 코드 ID는 수정할 수 없습니다.

10.4.3 코드 삭제

기본 정보

항목 내용
API명 코드 삭제 (관리자용)
엔드포인트 /api/code/admin/:grpId/:codeId
HTTP 메서드 DELETE
인증 필요 (Admin)
설명 특정 코드 삭제

URL Parameters

필드 타입 필수 설명
grpId string O 그룹 ID
codeId string O 삭제할 코드 ID

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 13000 코드를 찾을 수 없음
500 13003 코드 삭제 실패

비고

  • 시스템에서 사용 중인 중요 코드는 삭제할 수 없습니다.

10.4.4 코드 일괄 삭제

기본 정보

항목 내용
API명 코드 일괄 삭제 (관리자용)
엔드포인트 /api/code/admin/:grpId/codes/delete
HTTP 메서드 POST
인증 필요 (Admin)
설명 특정 그룹 내 여러 코드를 한 번에 삭제

URL Parameters

필드 타입 필수 설명
grpId string O 그룹 ID

Request Body

interface CommonCodeListDeleteReq {
  codeIds: string[];  // 삭제할 코드 ID 목록 (필수)
}
필드 타입 필수 설명
codeIds string[] O 삭제할 코드 ID 배열

Response (성공 시)

{
  "success": true
}

발생 가능한 에러

HTTP 에러 코드 설명
401 14000 인증 필요
403 14005 관리자 권한 필요
404 13020 그룹을 찾을 수 없음
400 12001 codeIds 필드 누락
500 13003 코드 삭제 실패

11. 부록

11.1 데이터 타입 규칙

1) 날짜/시간 형식

모든 날짜 및 시간 필드는 ISO 8601 형식을 사용합니다.

형식 예시 설명
날짜 + 시간 2025-11-04T14:30:00Z UTC 기준
날짜 + 시간 (타임존) 2025-11-04T23:30:00+09:00 한국 시간 (KST)
날짜만 2025-11-04 시간 정보 없음

2) 문자열 길이 제약

필드 유형 최소 길이 최대 길이 비고
이름 (name) 2 50 한글/영문
이메일 (email) - 100 이메일 형식 검증
로그인 ID (loginId) 4 20 영문/숫자
비밀번호 (password) 8 20 영문+숫자+특수문자 조합
제목 (title) - 200 -
짧은 내용 - 500 -
긴 내용 (content) - 5000 HTML 포함 가능
소속 (affiliation) - 100 -
설명 (description) - 200 -
비고 (note) - 500 -

3) 숫자 타입

필드 유형 타입 범위 비고
ID number 1 ~ 양의 정수
페이지 번호 (page) number 1 ~ 기본값: 1
페이지 크기 (limit) number 1 ~ 100 기본값: 10
정렬 순서 (sortOrder) number 0 ~ 낮을수록 우선
조회수 (hitCnt) number 0 ~ -

11.2 URL 파라미터 표기법

1) Path Parameter

URL 경로에 포함되는 동적 값으로, : 접두사를 사용합니다.

형식: /api/resource/:paramName

예시:

  • /api/admin/faq/:faqId → /api/admin/faq/123
  • /api/code/:grpId/:codeId → /api/code/sys_admin_roles/S-ADMIN

2) Query Parameter

URL 쿼리 문자열로 전달되는 값으로, ? 뒤에 key=value 형태로 작성합니다.

형식: /api/resource?param1=value1&param2=value2

예시:

  • /api/user/faq/list?page=1&limit=10&search=키워드
  • /api/admin/qna?status=N&sort=createdAt-desc

특수 문자 인코딩:

  • 공백: %20 또는 +
  • 한글: URL 인코딩 필요 (UTF-8)

11.3 페이징 처리

1) 파라미터

파라미터 타입 기본값 설명
page number 1 조회할 페이지 번호 (1부터 시작)
limit number 10 페이지당 항목 수 (최대 100)

2) 응답 구조

interface PaginationRes<T> {
  items: T[];         // 현재 페이지의 아이템 목록
  total: number;      // 전체 아이템 수
  page: number;       // 현재 페이지 번호
  limit: number;      // 페이지당 아이템 수
  totalPages: number; // 전체 페이지 수
}

3) 계산 공식

totalPages = Math.ceil(total / limit)

예시:

  • 전체 아이템 25개, limit 10 → totalPages = 3
  • 1페이지: items[0-9]
  • 2페이지: items[10-19]
  • 3페이지: items[20-24]

11.4 정렬 (Sorting)

일부 목록 조회 API는 sort 파라미터를 지원합니다.

형식 

sort={필드명}-{방향}
방향 설명
asc 오름차순 (Ascending)
desc 내림차순 (Descending)

예시

  • sort=createdAt-desc: 생성일시 내림차순 (최신순)
  • sort=hitCnt-desc: 조회수 내림차순 (인기순)
  • sort=sortOrder-asc: 정렬 순서 오름차순

11.5 TypeScript 타입 활용

1) packages/common 사용법

본 프로젝트는 FE와 BE가 동일한 타입 정의를 공유합니다.

// packages/common에서 타입 import
import {
  ApiResponse,
  API_URLS,
  UserLoginReq,
  UserLoginRes,
  ErrorCode
} from '@iitp-dabt/common';

// API 호출 (FE)
const response: ApiResponse<UserLoginRes> = await fetch(
  API_URLS.AUTH.USER.LOGIN,
  {
    method: 'POST',
    body: JSON.stringify(loginData)
  }
);

// 타입 안전성 보장
if (response.success) {
  const token = response.data.token;  // 타입 추론됨
}

2) API URL 상수 사용

import { API_URLS, FULL_API_URLS } from '@iitp-dabt/common';

// 방법 1: 조합형
const url = `${API_URLS.USER.BASE}${API_URLS.USER.FAQ.LIST}`;
// 결과: "/api/user/faq/list"

// 방법 2: 완전한 URL 사용
const url = FULL_API_URLS.USER.FAQ.LIST;
// 결과: "/api/user/faq/list"

3) 에러 코드 처리

import { ErrorCode, ErrorMetaMap } from '@iitp-dabt/common';

// 에러 처리
if (!response.success) {
  const errorCode = response.errorCode;
  const errorInfo = ErrorMetaMap[errorCode];

  console.log(`에러 발생: ${errorInfo.message} (${errorInfo.statusCode})`);
}

11.6 자주 사용하는 공통 코드

1) FAQ 유형

코드 ID 코드명 설명
(참조) (참조) 공통 코드 faq_type 그룹 참조

2) QnA 유형

코드 ID 코드명 설명
(참조) (참조) 공통 코드 qna_type 그룹 참조

3) 공지사항 유형

코드 ID 코드명 설명
G 일반 공지 General Notice
S 시스템 공지 System Notice
E 이벤트 공지 Event Notice

4) 관리자 역할

코드 ID 코드명 권한 레벨 설명
S-ADMIN 최고 관리자 최고 모든 권한 보유 (운영자 계정 관리 포함)
ADMIN 관리자 중간 콘텐츠 및 사용자 관리 권한
EDITOR 에디터 제한적 콘텐츠 편집 권한
VIEWER 뷰어 최소 조회 전용 권한

11.7 보안 기능

1) 적용된 보안 기능

인증 및 권한:

  • JWT(JSON Web Token) 기반 인증 시스템
  • Access Token (15분) / Refresh Token (7일) 분리
  • bcrypt를 사용한 비밀번호 해싱 (Salt Rounds: 10)
  • 역할 기반 권한 관리 (Public/User/Admin/S-Admin)

로깅 및 감사:

  • 로그인 성공/실패 이력 기록 (IP 주소, User Agent 포함)
  • API 호출 로그 자동 기록 (accessLogMiddleware)
  • 사용자 행동 이력 추적 (sysLogUserAccess)

데이터 보호:

  • 비밀번호 평문 저장 금지 (bcrypt 해싱)
  • 환경 변수 암호화 (decrypt 유틸리티)
  • CORS 설정을 통한 출처 제한

2) 비밀번호 정책

  • 최소 8자
  • 영문 대소문자, 숫자, 특수문자 조합 필수
  • bcrypt를 사용한 단방향 해싱
(9-9/39)