58 lines
5.2 KiB
Markdown
58 lines
5.2 KiB
Markdown
# AGENTS.md
|
|
|
|
## 목적
|
|
- 이 저장소에서 작업하는 사람과 코딩 에이전트가 같은 기준으로 개발하도록 돕는 운영 가이드다.
|
|
- 불필요한 구조 변경보다 작은 단위의 안전한 수정, 빠른 검증, 명확한 보고를 우선한다.
|
|
|
|
## 우선 확인할 규칙
|
|
- 기존 구조와 네이밍을 우선 존중하고, 요청 범위 안에서 필요한 만큼만 수정한다.
|
|
- 소스코드 변경 요청에서는 바로 구현하지 말고 `코드로 보여주기` 또는 `직접 작성하기` 중 원하는 방식을 먼저 확인한다.
|
|
- Controller 는 요청/응답 조립과 인증 주체 확인에 집중하고, 복잡한 로직과 DB 처리는 Service 로 넘긴다.
|
|
- 응답은 `ApiResponse<T>` 와 `ApiResponseCode` 조합을 우선 사용한다.
|
|
- 변경 후에는 가능하면 테스트 또는 최소 실행 검증 결과를 남기고, 미실행 항목은 사유를 분명히 적는다.
|
|
|
|
## 문서 인덱스
|
|
| 구분 | 문서 | 경로(URL) |
|
|
|------|------|-----------|
|
|
| 기본 | [프로젝트 개요](docs/project-overview.md) | `docs/project-overview.md` |
|
|
| 기본 | [코드 컨벤션](docs/code-conventions.md) | `docs/code-conventions.md` |
|
|
| 기본 | [보안 및 응답 규칙](docs/security-and-response.md) | `docs/security-and-response.md` |
|
|
| 기본 | [설정 및 실행 가이드](docs/runtime-config.md) | `docs/runtime-config.md` |
|
|
| 기본 | [검증 및 체크리스트](docs/verification-checklist.md) | `docs/verification-checklist.md` |
|
|
| 기본 | [Codex 작업 규칙](docs/agent-workflow.md) | `docs/agent-workflow.md` |
|
|
| 기본 | [현재 코드베이스 메모](docs/codebase-notes.md) | `docs/codebase-notes.md` |
|
|
| 정책 | [정책서 요약 인덱스](docs/policy/index.md) | `docs/policy/index.md` |
|
|
| 정책 | [정책서: 서비스 개요](docs/policy/overview.md) | `docs/policy/overview.md` |
|
|
| 정책 | [정책서: 회원/권한/인증](docs/policy/membership-and-auth.md) | `docs/policy/membership-and-auth.md` |
|
|
| 정책 | [정책서: 캠퍼스/강좌/학습 흐름](docs/policy/campus-and-learning.md) | `docs/policy/campus-and-learning.md` |
|
|
| 정책 | [정책서: 콘텐츠/LMS](docs/policy/content-and-lms.md) | `docs/policy/content-and-lms.md` |
|
|
| 정책 | [정책서: 인터페이스/도메인/운영](docs/policy/interfaces-and-operations.md) | `docs/policy/interfaces-and-operations.md` |
|
|
|
|
## 빠른 판단 가이드
|
|
- 구조, 네이밍, DTO/VO/Form, Mapper 작성 방식은 `docs/code-conventions.md` 를 우선 본다.
|
|
- 인증/인가, 공통 응답, 예외 처리, 응답 코드는 `docs/security-and-response.md` 를 우선 본다.
|
|
- 프로파일, 설정 파일, 로깅, Swagger, 실행 명령은 `docs/runtime-config.md` 를 우선 본다.
|
|
- 테스트 범위, 배포 전 점검, 파일/권한/설정 변경 확인사항은 `docs/verification-checklist.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
|
|
- 기본 애플리케이션 이름: `api`
|
|
- 기본 포트: `8106`
|
|
- 실행 진입점: `src/main/java/com/alist/api/ApiApplication.java`
|