본문으로 건너뛰기

Student 모듈

학원 학생의 프로필 생성·수정·비활성화, 대량 가져오기(Excel/CSV), CSV 내보내기, 재원생 현황 통계 등을 담당하는 핵심 도메인 모듈입니다.

모듈 개요​

항목내용
Gradle 서브프로젝트modules/student
베이스 패키지com.lumie.student
데이터베이스PostgreSQL (멀티테넌트 RLS, students 테이블)
외부 노출 internal-apiStudentService

주요 책임​

  • 학생 계정(User) 생성 및 프로필 저장
  • 재원/휴원 상태 전환 (isActive 플래그)
  • 전화번호·이름·생년 등 개인 정보 관리
  • 대량 등록(Excel/CSV 업로드) — 동기 처리, Idempotency-Key 지원
  • CSV 스트리밍 내보내기 (OWNER 전용)
  • 등록 추이(월별) 및 퇴원 요약 통계 제공

도메인 모델​

Student 엔티티​

@Entity
@Table(name = "students")
public class Student extends TenantScopedEntity {
    private Long id;
    @Version Long version;          // 낙관적 잠금
    Long userId;                    // auth.users FK
    String userLoginId;             // 로그인 ID (이메일)
    String name;
    String phone;
    String studentHighschool;
    Integer studentBirthYear;
    String parentPhone;
    String studentMemo;
    Boolean isActive;               // 재원 여부
}

TenantScopedEntity 가 tenant_id 컬럼을 제공하며, RLS 정책이 런타임에 테넌트별 행 접근을 제한합니다.

REST API​

기본 경로: /v1/students​

메서드경로설명
POST/v1/students학생 등록 (201 Created)
GET/v1/students목록 조회 (페이지, 검색, 재원여부 필터)
GET/v1/students/\{id\}학생 상세 조회
PATCH/v1/students/\{id\}프로필 수정
DELETE/v1/students/\{id\}학생 삭제
POST/v1/students/\{id\}/deactivate퇴원 처리
POST/v1/students/\{id\}/reactivate재등록 (재원 복귀)
POST/v1/students/\{id\}/reset-password임시 비밀번호 초기화
PATCH/v1/students/\{id\}/login-id로그인 ID 변경
POST/v1/students/batch/deactivate일괄 퇴원 (207 Multi-Status)
POST/v1/students/batch/reactivate일괄 재등록 (207 Multi-Status)
POST/v1/students/batch/delete일괄 삭제 (207 Multi-Status)
POST/v1/students/bulkExcel/CSV 대량 가져오기 (multipart/form-data)
GET/v1/students/export.csvCSV 내보내기 스트리밍 (OWNER 전용)
GET/v1/students/statistics/enrollment-trend월별 등록 추이 (?months=6)
GET/v1/students/statistics/dropout-summary퇴원 요약 통계

정렬 허용 필드 (?sort=)​

createdAt, name, phone, studentHighschool, studentBirthYear

대량 가져오기 (POST /v1/students/bulk)​

  • multipart/form-data 형식, 파라미터명 file
  • 수백 건 이하의 Excel/CSV를 동기로 파싱·삽입하고 BulkImportResult를 반환
  • Idempotency-Key 헤더를 지원 — 파일명·사이즈 해시를 기준으로 중복 요청을 차단

내부 API (libs/internal-api)​

StudentService 인터페이스를 구현한 StudentServiceAdapter가 adapter/in/internal/에 위치합니다. 다른 모듈은 이 인터페이스를 통해서만 학생 정보에 접근합니다.

public interface StudentService {
    Optional<StudentData> getStudent(String tenantSlug, Long studentId);
    StudentListData getStudentsByIds(String tenantSlug, List<Long> studentIds);
    Optional<StudentData> getStudentByPhone(String tenantSlug, String phone);
    StudentListData getStudentsByUserIds(String tenantSlug, List<Long> userIds);
    ValidateStudentResult validateStudent(String tenantSlug, Long studentId);
}

소비 모듈 (in-process 주입):

소비자 모듈사용 목적
examOMR 채점 결과 매칭, 성적 조회 시 학생 정보 조회
notification수신자 전화번호 해석 (sendToClass 흐름)
assignment과제 제출 학생 검증
tuition청구서 학생 연결 검증

멀티테넌시​

students 테이블에 tenant_id BIGINT NOT NULL이 있으며, FORCE ROW LEVEL SECURITY 정책이 lumie_app 런타임 롤에 적용됩니다. 테넌트 컨텍스트 전환이 필요한 어댑터에서는 TenantContextHolder.withinContext(slug, tenantId, action)을 사용합니다.

에러 코드​

코드HTTP설명
STUDENT_001404학생을 찾을 수 없음
STUDENT_002409이미 등록된 학생 (전화번호 중복 등)
STUDENT_003400잘못된 요청 데이터

관련 문서​