xrlms/src/app/api/README.md

API 엔드포인트 문서

이 문서는 데이터베이스에 데이터를 생성하는 API 엔드포인트를 설명합니다.

📋 API 목록

1. 사용자 API (/api/users)

POST - 사용자 생성

POST /api/users
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "hashed_password",
  "name": "홍길동",
  "phone": "010-1234-5678",
  "gender": "M",
  "birthdate": "1990-01-01",
  "role": "LEARNER",  // 또는 "ADMIN"
  "status": "ACTIVE"  // 또는 "INACTIVE"
}

응답:

{
  "message": "사용자가 성공적으로 생성되었습니다.",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "홍길동",
    ...
  }
}

GET - 사용자 목록 조회

GET /api/users?role=LEARNER&status=ACTIVE&page=1&limit=10

쿼리 파라미터:

• role: 필터링할 역할 (LEARNER, ADMIN)
• status: 필터링할 상태 (ACTIVE, INACTIVE)
• page: 페이지 번호 (기본값: 1)
• limit: 페이지당 항목 수 (기본값: 10)

---

2. 교육과정 API (/api/courses)

POST - 교육과정 생성

POST /api/courses
Content-Type: application/json

{
  "courseName": "웹 개발 기초",
  "instructorId": "instructor_uuid",
  "createdById": "admin_uuid"  // 선택사항, 기본값: instructorId
}

응답:

{
  "message": "교육과정이 성공적으로 생성되었습니다.",
  "course": {
    "id": "uuid",
    "courseName": "웹 개발 기초",
    "instructor": { ... },
    "createdBy": { ... }
  }
}

GET - 교육과정 목록 조회

GET /api/courses?instructorId=uuid&page=1&limit=10

---

3. 강좌 API (/api/lessons)

POST - 강좌 생성

POST /api/lessons
Content-Type: application/json

{
  "courseId": "course_uuid",
  "lessonName": "HTML 기초",
  "learningGoal": "HTML의 기본 문법을 이해하고 활용할 수 있다.",
  "createdById": "admin_uuid"  // 선택사항
}

응답:

{
  "message": "강좌가 성공적으로 생성되었습니다.",
  "lesson": {
    "id": "uuid",
    "lessonName": "HTML 기초",
    "course": { ... },
    "createdBy": { ... }
  }
}

GET - 강좌 목록 조회

GET /api/lessons?courseId=uuid&page=1&limit=10

---

4. 공지사항 API (/api/notices)

POST - 공지사항 생성

POST /api/notices
Content-Type: application/json

{
  "title": "공지사항 제목",
  "content": "공지사항 내용",
  "writerId": "admin_uuid",
  "hasAttachment": false  // 선택사항
}

응답:

{
  "message": "공지사항이 성공적으로 생성되었습니다.",
  "notice": {
    "id": "uuid",
    "title": "공지사항 제목",
    "content": "공지사항 내용",
    "writer": { ... }
  }
}

GET - 공지사항 목록 조회

GET /api/notices?writerId=uuid&page=1&limit=10

---

🔧 사용 예시

JavaScript/TypeScript (fetch)

// 사용자 생성
const response = await fetch('/api/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'hashed_password',
    name: '홍길동',
    role: 'LEARNER',
  }),
});

const data = await response.json();
console.log(data);

cURL

# 사용자 생성
curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "hashed_password",
    "name": "홍길동",
    "role": "LEARNER"
  }'

---

⚠️ 주의사항

1. 비밀번호 해시화: 실제 프로덕션에서는 비밀번호를 해시화하여 저장해야 합니다.
2. 인증/인가: 현재 API는 인증이 없습니다. 프로덕션에서는 JWT나 세션 기반 인증을 추가해야 합니다.
3. 에러 처리: 모든 API는 적절한 에러 응답을 반환합니다.
4. 데이터 검증: 필수 필드 검증이 포함되어 있습니다.

---

📝 다음 단계

• 인증 미들웨어 추가
• 비밀번호 해시화 로직 추가
• 파일 업로드 API 추가 (공지사항 첨부파일 등)
• 수정/삭제 API 추가
• 상세 조회 API 추가