api2/AGENTS.md

AGENTS.md

목적

• 이 저장소에서 작업하는 사람과 코딩 에이전트가 같은 기준으로 개발하도록 돕는 운영 가이드다.
• 불필요한 구조 변경보다 작은 단위의 안전한 수정, 빠른 검증, 명확한 보고를 우선한다.

우선 확인할 규칙

• 기존 구조와 네이밍을 우선 존중하고, 요청 범위 안에서 필요한 만큼만 수정한다.
• 소스코드 변경 요청에서는 바로 구현하지 말고 코드로 보여주기 또는 직접 작성하기 중 원하는 방식을 먼저 확인한다.
• Controller 는 요청/응답 조립과 인증 주체 확인에 집중하고, 복잡한 로직과 DB 처리는 Service 로 넘긴다.
• 응답은 ApiResponse<T> 와 ApiResponseCode 조합을 우선 사용한다.
• 신규/수정되는 Controller, Form, VO에는 Swagger 테스트 편의성을 위해 @Tag, @Operation, @Schema 설명과 예시를 남긴다.
• 변경 후에는 가능하면 테스트 또는 최소 실행 검증 결과를 남기고, 미실행 항목은 사유를 분명히 적는다.

문서 인덱스

구분	문서	경로(URL)
기본	프로젝트 개요	docs/project-overview.md
기본	구조 한눈에 보기	docs/architecture-at-a-glance.md
기본	Core 모듈 설계	docs/core-module-design.md
기본	코드 컨벤션	docs/code-conventions.md
기본	보안 및 응답 규칙	docs/security-and-response.md
기본	설정 및 실행 가이드	docs/runtime-config.md
기본	검증 및 체크리스트	docs/verification-checklist.md
기본	테스트 전략	docs/testing-strategy.md
기본	Codex 작업 규칙	docs/agent-workflow.md
기본	현재 코드베이스 메모	docs/codebase-notes.md
정책	정책서 요약 인덱스	docs/policy/index.md
정책	정책서: 서비스 개요	docs/policy/overview.md
정책	정책서: 회원/권한/인증	docs/policy/membership-and-auth.md
정책	정책서: 캠퍼스/강좌/학습 흐름	docs/policy/campus-and-learning.md
정책	정책서: 콘텐츠/LMS	docs/policy/content-and-lms.md
정책	정책서: 인터페이스/도메인/운영	docs/policy/interfaces-and-operations.md

빠른 판단 가이드

• core standard/bespoke 구조와 이관 기준은 docs/core-module-design.md 를 우선 본다.
• 프로젝트에 처음 참여했거나 core/admin/front 책임을 빠르게 파악해야 하면 docs/architecture-at-a-glance.md 를 먼저 본다.
• 구조, 네이밍, DTO/VO/Form, Mapper 작성 방식은 docs/code-conventions.md 를 우선 본다.
• 인증/인가, 공통 응답, 예외 처리, 응답 코드는 docs/security-and-response.md 를 우선 본다.
• 프로파일, 설정 파일, 로깅, Swagger, 실행 명령은 docs/runtime-config.md 를 우선 본다.
• 테스트 범위, 배포 전 점검, 파일/권한/설정 변경 확인사항은 docs/verification-checklist.md 를 우선 본다.
• 단위 테스트, 통합 테스트, 실제 연동 검증의 범위와 Red-Green 흐름은 docs/testing-strategy.md 를 우선 본다.
• Codex 협업 방식과 응답 원칙은 docs/agent-workflow.md 를 우선 본다.
• 도메인 정책, 역할, 강좌/콘텐츠/LMS 규칙은 docs/policy/ 하위 문서를 우선 본다.

정책서 핵심 요약

• 서비스는 alist.co.kr 메인 서비스, a-campus.co.kr 캠퍼스 메인, class.a-campus.co.kr 교사용, student.a-campus.co.kr 학생용, admin.alist.co.kr 백오피스/CMS로 분리 운영한다.
• 회원 유형은 관리자, 교사, 학생, 수강생으로 구분하며, 수강생은 캠퍼스 초대 기반 준회원이고 학생 전환 및 ID 병합 정책이 존재한다.
• 교사만 캠퍼스를 생성할 수 있고 캠퍼스는 단일 캠퍼스형과 복합 캠퍼스형으로 나뉜다. 복합 캠퍼스형은 관리자 승인 후 운영한다.
• 캠퍼스 계층은 캠퍼스 -> 클래스 -> 강좌(Lecture) 구조이며, 강좌는 교재 1종과 1:1 매칭되고 학생/수강생 초대, 과제/평가, 학습 관리의 기준 단위다.
• 교사 회원은 Live 상태에서 단수 캠퍼스만 소속 가능하고, 수강생도 Live 상태에서 단수 캠퍼스만 소속 가능하다. 본인 인증을 마친 학생은 복수 캠퍼스 소속이 가능하다.
• 강좌 운영 중 학생 중도 초대와 상태 변경이 가능하며, 탈퇴/종료 시 교사 화면에서는 학습 이력과 산출물이 숨김 처리된다.
• 콘텐츠는 교재 자료, 스마트 콘텐츠, 평가 문항, 온라인 학습/과제/평가로 구성되며 접근 권한과 학습 관리 범위가 회원 유형별로 다르다.
• 학습 관리는 진도, 수행 여부, 정오답, 성취도, 변화 추이, 오답 노트, 포트폴리오까지 포함한다. 과제/평가/온라인 학습 데이터가 주요 관리 대상이다.
• 캠퍼스 개인화는 캠퍼스 명칭, 직접 접속 도메인, 로고, GNB 색상 기준으로 제공하며, 정책서상 해외 임대/제휴 확장을 고려한 도메인 구조를 가진다.
• 기존 서비스 회원 DB와 학습 이력은 완전 마이그레이션 대상이 아니므로 최초 로그인 연동, 레거시 병행 운영, 데이터 재구조화 정책을 함께 고려해야 한다.

프로젝트 핵심 정보

• 프로젝트 유형: Gradle 기반 Spring Boot 멀티모듈 모놀리식
• Java 버전: 21
• Spring Boot 버전: 3.5.10
• 모듈: 01-api-core, 02-api-admin, 03-api-front
• admin 포트: 8111, 실행 진입점: com.alist.api.admin.ApiAdminApplication
• front 포트: 8112, 실행 진입점: com.alist.api.front.ApiFrontApplication