[개발]AGENTS 문서 업데이트

2026-04-24 10:58:14 +09:00
parent 88c3a4364b
commit 6cae972c0c
14 changed files with 608 additions and 182 deletions
@@ -0,0 +1,83 @@
+# 정책서: 캠퍼스/강좌/학습 흐름
+
+## 캠퍼스 개요
+- A★캠퍼스는 A*List 교재를 활용한 상호 교수·학습 활동을 위한 온라인 공간이다.
+- 서비스 대상은 A*List 회원인 교사와 학생이며, 운영자는 캠퍼스 인터페이스와 관련 지원 기능을 제공한다.
+- 캠퍼스 개인화 요소는 캠퍼스 명칭, 직접 접속 도메인, 로고, GNB 색상이다.
+
+## 캠퍼스 생성 정책
+- 캠퍼스 생성 주체는 교사 회원이다.
+- 단일 캠퍼스형은 생성 즉시 운영 가능하다.
+- 복합 캠퍼스형은 교사 생성 후 관리자 승인 절차를 거친 뒤 운영 가능하다.
+- 관리자(Back Office)도 캠퍼스를 직접 생성할 수 있다.
+
+## 캠퍼스 유형
+- 단일 캠퍼스형: 1인 교사 공부방 또는 단일 학원형
+- 복합 캠퍼스형: 동일 브랜드 하위 가맹 캠퍼스를 갖는 학원형
+
+## 캠퍼스 계층 구조
+- 캠퍼스
+- 클래스
+- 강좌(Lecture)
+
+## 계층별 의미
+- 캠퍼스: 운영 단위, 교재/교사/학생/설정 관리의 상위 개념
+- 클래스: 교사 1인 기준의 운영 단위
+- 강좌: 교재 + 복수 학생 기준의 실제 교수·학습 수행 단위
+
+## 강좌 정책
+- 강좌와 교재는 1:1 관계다
+- 교재 1종은 단일 ISBN 한 권이 아니라 학습 연관성을 가진 교재 묶음일 수 있다
+- 동일 학생이어도 교재가 바뀌면 새 강좌 생성
+- 동일 교재여도 학생 구성이 바뀌면 새 강좌 생성
+- 강좌 복사 기능을 제공하며 수업 중 강좌도 복사 가능하다
+- Live 상태 강좌 수는 제한될 수 있고 종료 강좌를 포함한 총 강좌 수는 무제한이다
+
+## 강좌 생명주기
+- 강의 준비중
+- 강의 중
+- 강의 종료
+- 학생 기준 상태로는 수강 대기중, 수강 중, 수강 종료가 별도로 존재한다
+
+## 강좌 운영 규칙
+- 강좌 생성 시 교재 선택, 학생 초대, 수업 코스 설계, 과제/평가 생성이 함께 이뤄진다
+- 운영 중 학생 중도 초대가 가능하다
+- 운영 중 학생 상태를 이용 중지 또는 수강 종료로 변경할 수 있다
+- 학생이 운영 중간에 가입하면 이전 과제/평가도 미수행 상태로 제시한다
+- 상태 변경 시 학생과 학부모에게 알림이 발송된다
+
+## 교사 업무 흐름
+- 캠퍼스 생성 또는 초대 가입
+- 캠퍼스 개인화 설정
+- 교재 선택 및 클래스/강좌 생성
+- 학생/수강생 초대
+- 타임라인 기반 수업 코스 설계
+- 과제/평가 출제
+- 제출 관리, 채점, 피드백
+- 학습 현황 및 보고서 생성
+
+## 학생/수강생 학습 흐름
+- 초대 URL/초대 코드 기반 강좌 가입 또는 학생 회원 자기주도학습 시작
+- 수업 참여
+- 과제 수행 및 제출
+- 평가 수행 및 제출
+- 복습 및 자기주도학습
+- 학습 결과/성취도 확인
+
+## 과제/평가 정책
+- 과제/평가는 강좌 단위로 출제한다
+- 학생은 온라인 과제 뷰어 또는 온라인 학습 콘텐츠 뷰어에서 수행한다
+- 제출 기한과 수행률 관리가 필요하다
+- 교사는 채점 및 피드백을 입력한다
+- 알림장, 이메일, 앱 푸시, SMS가 보조 수단으로 사용된다
+
+## SMS 정책
+- 캠퍼스 초대, 학습 알림, 보고서 발송 등에 SMS를 병행 사용할 수 있다
+- SMS 수량은 캠퍼스 마스터가 구매/충전하는 구조다
+- 발송 성공 시 수량이 차감된다
+- 백오피스에서 수량 충전 기능을 제공한다
+
+## 개발 해석 포인트
+- 캠퍼스, 클래스, 강좌는 이름이 비슷하지만 역할이 다르므로 테이블/DTO/응답 모델을 명확히 분리해야 한다
+- 강좌는 실제 학습 데이터와 과제/평가의 기준 단위이므로, API 설계 시 강좌 식별자를 중심으로 묶는 것이 자연스럽다
+- 초대, 가입, 탈퇴, 종료, 상태 변경은 회원 상태와 강좌 소속 상태를 구분해 처리해야 한다
@@ -0,0 +1,75 @@
+# 정책서: 콘텐츠/LMS
+
+## 콘텐츠 범주
+- 수업 자료: PPT, Lesson Plan, Syllabus, Scope & Sequence, Teacher Guide, Script, Worksheet, Word Test 등
+- 평가 자료: Test Sheet, 단원 평가, 중간/최종 평가, 평가 문항, 내신 수행평가 자료
+- 멀티미디어: MP3, MP4, 온라인 PPT, 온라인 클래스, 플래시 카드
+- 솔루션형 콘텐츠: 교사용 e-Book, 온라인 평가, 온라인 OMR 평가, Voca*List, 클래스 카드, 레벨 테스트
+- 교사 보유 자료: PDF, MP3, MP4 업로드 자료
+
+## 콘텐츠 생산과 활용
+- CMS에서 콘텐츠 분류 체계, 메타데이터, 자료 등록, 대량 등록, 미리 보기를 관리한다
+- 교사는 수업 뷰어에서 문서형 자료, URL, 온라인 콘텐츠, 과제, 평가를 통합적으로 사용한다
+- 학생은 온라인 학습 콘텐츠 뷰어와 과제/평가 뷰어에서 콘텐츠를 수행한다
+- 평가지는 별도 생성 솔루션(Test Generator)으로 출제, 편집, 출력한다
+
+## 콘텐츠 메타데이터
+- 콘텐츠는 교재, 시리즈, 레벨, 학년, 난이도, CEFR, Lexile, AR 등 학습 레벨 메타데이터를 가진다
+- 교재 레벨 메타는 백오피스/CMS에서 별도로 관리한다
+- 메타데이터는 검색, 교재 노출, 학습 추천, 보고서 분류에 영향을 줄 수 있다
+
+## 콘텐츠 접근 권한
+- 교사: 대부분의 수업 자료와 교사용 자료, 수업 뷰어 기능 접근 가능
+- 학생: 제한된 수업 자료와 멀티미디어, 온라인 학습 콘텐츠 접근 가능
+- 수강생: 강좌 기반 학습 활동 위주로 제한된 권한을 가진다
+- 학생용 I/F에서는 기본 권한 자료와 교사가 추가 허용한 자료를 함께 노출할 수 있다
+
+## 주요 솔루션과 기능
+- 교수자용 수업 뷰어
+  - E-Book, PDF, PPSX, Audio, Video, URL, 온라인 콘텐츠 연동
+  - 확대/축소, 그리기, 북마크, 메모, 타이머, 주사위, 스포트라이트 등 보조 기능
+- 온라인 학습 콘텐츠 뷰어
+  - 문제 풀이, 게임형 활동, Audio/Video 재생, Drawing, Recording, 타이머
+- 학습자용 온라인 과제 뷰어
+  - 답안 입력, 자동 채점, 제출
+  - 입력, 그림, 녹음, 이미지/음원/영상 업로드
+  - OMR/온라인 평가 수행
+- 평가지 생성 솔루션
+  - 문항 검색, 문항 수/유형 설정, 사용자 문항 추가, PDF 생성, 출력
+- 학습 분석 보고서
+  - 레벨테스트, 교재별, Unit별 보고서 생성
+
+## 학습 관리 대상
+- 레벨테스트
+- 온라인 학습 콘텐츠
+- 온라인 평가
+- 온라인 과제
+- 클래스 과제
+
+## 학습 관리 영역
+- 정량 관리
+  - 학습 횟수
+  - 회차별 학습 시간
+  - 전체/평균 학습 시간
+  - 단위 학습 수행 여부
+- 성취 관리
+  - 정오답
+  - 학습 진도
+  - 전체 성취도
+  - SKILL별 성취도
+  - 성취도 변화 추이
+- 산출물 관리
+  - 오답 노트
+  - 학습 산출물 데이터
+  - 유사 문항 학습
+  - 포트폴리오
+
+## 시각화 및 보고
+- 대시보드 I/F와 학습 분석 보고서가 주요 표현 수단이다
+- 학생별/강좌별 현황, 성취도, 수행률, 레벨테스트 결과 시각화가 중요하다
+- 교사 화면에서는 강좌별 관리와 학생별 관리가 모두 필요하다
+
+## 개발 해석 포인트
+- 콘텐츠 자체 메타데이터와 학습 수행 데이터는 분리 저장하는 편이 좋다
+- 학습 관리 영역은 단순 진도율이 아니라 성취도·산출물·포트폴리오까지 포함하므로 조회 API가 넓어질 가능성이 높다
+- 학생용 권한은 `회원 유형`, `강좌 소속 여부`, `교사 공유 여부`의 조합으로 판단해야 한다
@@ -0,0 +1,22 @@
+# 정책서 요약 인덱스
+
+원본 정책서: `D:/work/project/202601_alist/document/00_정책서/이퍼블릭_AList 교수학습지원 통합 플랫폼 구축_정책 설계_Ver 0.29.pdf`
+
+## 문서 구성
+- [서비스 개요](overview.md)
+- [회원/권한/인증](membership-and-auth.md)
+- [캠퍼스/강좌/학습 흐름](campus-and-learning.md)
+- [콘텐츠/LMS](content-and-lms.md)
+- [인터페이스/도메인/운영](interfaces-and-operations.md)
+
+## 빠른 요약
+- 플랫폼은 메인 서비스, 캠퍼스 메인, 교사용 캠퍼스, 학생용 캠퍼스, 백오피스/CMS로 분리된다.
+- 핵심 도메인은 회원, 캠퍼스, 클래스, 강좌, 콘텐츠, 과제/평가, 학습 관리다.
+- 정책서상 주요 제약은 회원 유형별 권한 차등, 캠퍼스 소속 제한, 강좌-교재 1:1 관계, 캠퍼스 개인화 도메인, 레거시 병행 운영이다.
+- 실제 개발 판단에서는 이 문서 묶음을 기능 정의서보다 `도메인 정책서`로 취급하는 것이 적합하다.
+
+## 개발 시 우선 참고 포인트
+- 회원 가입, 초대, 상태값, 로그인, 권한 분기는 `membership-and-auth.md`
+- 캠퍼스 생성, 계층 구조, 강좌 정책, 과제/평가 흐름은 `campus-and-learning.md`
+- 콘텐츠 유형, 접근 권한, 뷰어/솔루션, LMS 지표는 `content-and-lms.md`
+- 화면 경계, 도메인 구조, 메뉴 범위, 서버/이관 정책은 `interfaces-and-operations.md`
@@ -0,0 +1,82 @@
+# 정책서: 인터페이스/도메인/운영
+
+## 인터페이스별 역할
+- 메인 서비스(`alist.co.kr`)
+  - 교재/자료, 스마트 콘텐츠, 지원 센터, 마이페이지, 교사 지원 서비스 중심
+- 캠퍼스 메인(`a-campus.co.kr`)
+  - 서비스 소개, 이용 방법, 체험하기, 캠퍼스 진입
+- 캠퍼스 교사용(`class.a-campus.co.kr`)
+  - 강좌/학생/학습/알림/수업준비/캠퍼스 관리 중심
+- 캠퍼스 학생용(`student.a-campus.co.kr`)
+  - 오늘 학습, 셀프 스터디, 나의 학습, 알림방 중심
+- 백오피스/CMS(`admin.alist.co.kr`)
+  - 운영 관리, 교재/콘텐츠/CMS, 파트너, 홍보, 문의, 통계 관리
+
+## 교사용 I/F 핵심 메뉴
+- 강좌 관리
+- 학생 관리
+- 학습 관리
+- 소통방
+- 수업 준비
+- 마이페이지
+- 역할에 따라 가맹 캠퍼스 관리, 캠퍼스 관리, 공지 관리 등 추가 메뉴 노출
+
+## 학생용 I/F 핵심 메뉴
+- 오늘 학습
+- 셀프 스터디
+- 나의 학습
+- 알림방
+- 마이페이지
+- 학생만 `학습 교재 추가`, `교재 추가` 같은 자기주도학습 확장 기능 사용 가능
+
+## 백오피스/CMS 핵심 메뉴
+- 관리자/권한 관리
+- 메뉴 관리
+- 파트너/유통업체 관리
+- A*List/A★캠퍼스 메인 관리
+- 팝업, 이벤트, FAQ, 세미나, 게시판, 1:1 문의
+- 교재 분류/레벨 메타 관리
+- 교재 관리, 캠퍼스 서비스 교재 관리
+- 콘텐츠 저작/관리, 온라인 콘텐츠 관리, 제휴사 콘텐츠 관리
+- 학습 관리, 통계 관리
+
+## 도메인 정책
+- 메인 서비스와 캠퍼스 서비스 도메인을 분리한다
+- 캠퍼스 생성 시 개인화 도메인을 제공한다
+- 기본 URL 구조는 `/home/...`, 임대/개인화 URL 구조는 `/{campusId}/...` 이다
+- 학생용 기본 자기주도학습 화면은 `student.a-campus.co.kr/home` 이다
+- 개인화 도메인은 서버 부하 분산, 확장성, 운영 편의성을 고려한 정책이다
+
+## 캠퍼스 개인화 도메인 개발 정책
+- 정책서에는 Next.js 자동 라우팅 + 미들웨어 + 템플릿 파일 자동 생성 방식이 예시로 제시된다
+- 핵심 요구사항은 다음과 같다
+- 관리자에서 캠퍼스 ID 등록 시 개인화 경로가 반영될 것
+- 캠퍼스 ID별 로고/헤더/GNB 스타일을 동적으로 적용할 것
+- 허용된 캠퍼스 ID만 접근 가능하도록 제어할 것
+- 기본 사용자와 임대/브랜드 사용자의 URL 흐름을 분리할 것
+
+## 서버/소프트웨어 구성
+- Web / WAS / DB / File Storage / Legacy / 관리 서버를 분리한 구성을 기본으로 본다
+- 정책서 권장 스택
+  - Web: Linux, Apache 2.4, Node.js / Next.js
+  - WAS: Linux, Apache/Tomcat 9.x, JDK/OpenJDK, Spring Boot, Gradle, MyBatis, Swagger
+  - DB: Linux, MariaDB 10.6 이상
+- Legacy 서버는 기존 회원 로그인 연계와 앱 유지 목적상 일정 기간 병행 운영한다
+
+## 데이터 이관 정책
+- 교재 정보, 수업 자료, e-Book, 온라인 PPT, 레벨테스트, 문항, 내신 수행평가, 세미나, 교재 소개 등은 재구조화 후 이관 대상이다
+- 기존 회원 DB는 품질 이슈와 암호화 방식 차이로 직접 이관이 어렵다
+- 기존 앱 화면, 일부 ASP 기반 화면, 구 LMS 학습 이력은 신규 구조와 차이가 커서 병행 운영 또는 별도 연계가 필요하다
+- 온라인 PPT는 변환기(PPT to HTML)를 거쳐 탑재한다
+
+## 서비스 오픈 정책
+- 개발
+- 알파 테스트
+- 베타 테스트
+- 서비스 오픈 및 운영
+- 일정 기간 기존 서비스 시스템 병행 운영
+
+## 개발 해석 포인트
+- 정책서의 화면 메뉴는 단순 네비게이션이 아니라 권한/역할/도메인 경계 정의에 가깝다
+- 도메인과 URL 구조는 운영 정책과 강하게 연결돼 있으므로 하드코딩보다 설정/데이터 기반 관리가 적합하다
+- 레거시 병행 운영과 최초 로그인 연동은 회원 기능 수정 시 항상 영향 범위를 같이 봐야 한다
@@ -0,0 +1,74 @@
+# 정책서: 회원/권한/인증
+
+## 회원 유형
+- 관리자
+- 일반 관리자
+- 마스터 관리자
+- 교사
+- 학생
+- 수강생
+
+## 회원 유형 정의
+- 교사: 정회원 사용자. 본인 인증과 이메일 인증을 거치며 메인 서비스와 교사용 캠퍼스 I/F 사용
+- 학생: 정회원 사용자. 본인 인증 또는 부모 동의 인증과 이메일 인증을 거치며 메인 서비스와 학생용 캠퍼스 I/F 사용
+- 수강생: 준회원 사용자. 캠퍼스 초대 기반 가입이며 본인 인증 없이 학생용 캠퍼스 I/F 중심으로 사용
+- 학부모: 독립 회원이 아니라 학생/수강생의 부가 정보 항목이다
+
+## 인증 및 가입 정책
+- 교사 가입: 서비스 직접 방문, 휴대폰 본인 인증, 이메일 인증
+- 학생 가입: 서비스 직접 방문, 부모 동의 인증 포함 휴대폰 인증, 이메일 인증
+- 수강생 가입: 캠퍼스 초대 URL + 초대 코드 기반 가입, 학생용 I/F 접근 계정 생성
+- 관리자 계정: 개발 또는 마스터 관리자 등록 방식
+
+## 인터페이스 접근 권한
+- 관리자: 백오피스/CMS 접근, 메뉴별 권한 차등
+- 교사: 메인 서비스 + 캠퍼스 교사용 I/F 접근
+- 학생: 메인 서비스 + 학생용 I/F 접근, 일부 메뉴 제한
+- 수강생: 학생용 I/F 중심 접근, 메인 서비스 권한 없음 또는 제한
+- 학생/수강생은 같은 학생용 I/F를 사용하지만 권한 범위는 다르다
+
+## 캠퍼스 소속 정책
+- 교사 회원은 온라인 캠퍼스 역할과 무관하게 Live 상태에서 단수의 캠퍼스에만 소속 가능
+- 수강생은 Live 상태에서 단수의 캠퍼스에만 소속 가능
+- 본인 인증을 마친 학생은 복수 캠퍼스 소속 가능
+- 교사 비회원은 캠퍼스 생성 또는 선생님 역할 소속이 불가하며, 초대 가입 시에도 A*List 회원 가입이 필요하다
+
+## 캠퍼스 내 역할
+- 캠퍼스 마스터: 캠퍼스 생성자, 운영/관리 권한 보유
+- 가맹 캠퍼스장: 복합 캠퍼스 하위 지점 운영 역할
+- 선생님: 클래스 및 강좌 운영 주체
+- 학생: 학습 수행 주체
+
+## 회원 상태값
+- 정상(Live)
+- 휴면
+- 병합
+- 탈퇴 요청
+- 탈퇴
+
+## 상태 변경 정책
+- 1년 이상 접속 이력 없으면 휴면 전환
+- 휴면 후 2년간 해제 없으면 탈퇴 처리
+- 탈퇴 요청 후 30일 경과 시 데이터 삭제
+- 병합 상태는 ID 통합 후 미사용 계정 처리 상태
+
+## 탈퇴/복구 정책
+- 교사는 하위 강좌가 모두 종료 상태일 때만 탈퇴 요청 가능
+- 학생/수강생은 수강 중 강좌가 있어도 탈퇴 가능하지만 안내가 필요하다
+- 탈퇴 시 강좌 가입 상태는 종료(탈퇴)로 바뀌고 교사 화면에서는 학습 이력/산출물이 숨김 처리된다
+- 휴면 해제와 탈퇴 번복은 로그인 후 이메일/휴대폰 인증으로 복구한다
+
+## 회원 전환 및 ID 병합
+- 수강생은 모바일 본인 인증 또는 부모 인증 후 학생으로 전환 가능
+- 전환 시 클래스/강좌 정보와 학습 이력은 유지한다
+- 학생/수강생은 ID 병합 기능 제공 대상이다
+- 교사는 ID 병합 대상이 아니다
+
+## 레거시 회원 정책
+- 기존 A*List, eLearning Town 회원은 최초 로그인 시 레거시 DB 조회 후 신규 시스템 기준으로 보완 입력 및 저장한다
+- 레거시 비밀번호 체계상 DB 직접 마이그레이션이 어려워 최초 로그인 연동이 중요하다
+
+## 개발 해석 포인트
+- `회원 유형`, `인증 여부`, `캠퍼스 역할`, `캠퍼스 소속 상태`는 분리된 개념으로 모델링하는 편이 안전하다
+- 학생과 수강생은 UI는 유사하지만 권한과 소속 정책이 다르므로 같은 enum 하나로 단순화하면 후속 정책 충돌 가능성이 높다
+- 탈퇴와 캠퍼스 소속 종료, 강좌 종료는 별도 상태 전이로 다뤄야 한다
@@ -0,0 +1,38 @@
+# 정책서: 서비스 개요
+
+## 서비스 목적
+- A*List는 교재 기반 교수·학습 지원 통합 플랫폼이다.
+- 핵심 제공 가치는 교사용 수업 자료 제공, 스마트 콘텐츠/솔루션 제공, 교사 지원 서비스, 온라인 캠퍼스 기반 교수·학습 활동 지원이다.
+- 운영 주체는 A*List 서비스 운영자이며, 실사용자는 교사와 학생이다.
+
+## 서비스 구성 축
+- 메인 서비스: 교재/자료 소개, 스마트 콘텐츠, 교사 지원 서비스 제공
+- A★캠퍼스: 교사·학생이 실제 교수·학습 활동을 수행하는 온라인 캠퍼스
+- 백오피스/CMS: 플랫폼 운영, 콘텐츠 관리, 파트너/교재/회원/통계 관리
+- 해외 확장: 영어 홍보 사이트, 해외 임대(이식) 서비스, 제휴/유통업체 운영
+
+## 주요 인터페이스
+- `www.alist.co.kr`: 메인 서비스
+- `www.a-campus.co.kr`: 캠퍼스 서비스 메인
+- `class.a-campus.co.kr/{campusId}`: 캠퍼스 교사용 I/F
+- `student.a-campus.co.kr/{campusId}`: 캠퍼스 학생용 I/F
+- `student.a-campus.co.kr/home`: 캠퍼스 미소속 학생의 자기주도학습 I/F
+- `admin.alist.co.kr`: 관리자(Back Office / CMS) I/F
+- `eng.alist.co.kr`: 영어 홍보 I/F
+
+## 역할별 큰 흐름
+- 교사: 회원 가입 후 캠퍼스 생성 또는 캠퍼스 초대 가입, 교재 선택, 수업 설계, 학생 초대, 과제/평가 관리, 학습 관리 수행
+- 학생: 본인 인증 기반 정회원으로 가입 가능, 자기주도학습과 캠퍼스 강좌 활동 수행
+- 수강생: 캠퍼스 초대 기반 준회원으로 가입하며 강좌 기반 학습 활동 위주로 이용
+- 관리자/유통업체: 캠퍼스 생성 승인, 교재/콘텐츠 관리, 파트너 및 운영 정책 관리
+
+## 서비스 환경 정책
+- 메인 서비스와 캠퍼스 메인은 PC Web 중심이며 태블릿/모바일은 보기 위주로 제한되는 화면이 있다.
+- 캠퍼스 교사용 I/F는 PC 중심, 캠퍼스 학생용 I/F는 Web + Hybrid App 배포를 전제한다.
+- 학생용 앱은 국내 기준 Google Play, Apple Store 배포를 고려한다.
+- 해외 임대 서비스는 국가별 서비스 환경에 따라 App 배포 여부를 별도 판단한다.
+
+## 개발 해석 포인트
+- 이 플랫폼은 단순 콘텐츠 사이트가 아니라 `회원 + 캠퍼스 + 강좌 + 학습 데이터`를 중심으로 동작하는 LMS 성격이 강하다.
+- 교사용과 학생용 인터페이스가 명확히 분리되어 있으므로 메뉴, 권한, 응답 데이터도 같은 기준으로 나눠 설계해야 한다.
+- 해외 임대/제휴 확장을 전제로 하므로 도메인, 캠퍼스 개인화, 메뉴 노출, 권한 모델에 고정값을 박아 넣지 않는 편이 안전하다.