# PRO-SEJONGPEIA

> 세종대 개발에 필요한 모든 것을 한 번에. 학번 인증부터 학과·강의·학사일정·학식까지, Java · Python · Node.js 라이브러리.
> Everything you need to build on Sejong University. Student login, departments, lectures, calendar and cafeterias for Java, Python and Node.js.

하위 호환을 보장하지 않으니 버전을 정확히 고정하세요. 비밀번호는 서버에서만 다루고 저장하거나 로그에 남기지 마세요. 아래는 한국어 문서 목록이고, 영어 문서는 "English" 구역에 있습니다.

No backward-compatibility promise: pin the exact version. Handle passwords on a server only and never store or log them. The Korean docs are listed first, the English docs follow in the "English" section.

## 시작하기

- [소개](https://cassiiopeia.github.io/pro-sejongpeia/start/introduction/): pro-sejongpeia는 세종대학교 포털 로그인과 로그인 없이 쓰는 학교 데이터를 Java, Python, Node.js에서 같은 모양으로 쓰게 해 주는 오픈소스 라이브러리입니다.
- [빠른 시작](https://cassiiopeia.github.io/pro-sejongpeia/start/quickstart/): Java, Python, Node.js에서 라이브러리를 설치하고 학생 인증과 학교 데이터를 처음 호출하는 방법입니다.

## 가이드

- [학생 인증 붙이기](https://cassiiopeia.github.io/pro-sejongpeia/guides/student-verification/): 가입 폼의 학번과 비밀번호로 세종대 재학 여부를 확인하고 학번, 이름, 학과만 가져오는 예시를 세 언어로 보여 줍니다.
- [학과·강의 검색](https://cassiiopeia.github.io/pro-sejongpeia/guides/department-lecture-search/): 학과 목록과 개설강좌를 JSON으로 내려주는 작은 서버를 Java, Python, Node.js로 만들고, 응답 데이터 구조와 주의점을 정리합니다.
- [학사일정 위젯](https://cassiiopeia.github.io/pro-sejongpeia/guides/academic-calendar/): 오늘부터 30일 안의 학부 학사일정을 시작일 순으로 보여 주는 위젯 예시를 Java, Python, Node.js로 보여 줍니다.
- [기숙사·학식 봇](https://cassiiopeia.github.io/pro-sejongpeia/guides/dormitory-cafeteria-bot/): 오늘의 기숙사 식단, 학식, 기숙사 공지를 메시지 문자열로 만드는 안내 봇 예시를 Java, Python, Node.js로 보여 줍니다.
- [코딩 에이전트와 함께 쓰기](https://cassiiopeia.github.io/pro-sejongpeia/guides/agents/): Claude Code, Cursor, Codex 같은 코딩 에이전트에게 이 라이브러리의 사용법을 알려 주는 파일(llms.txt, llms-full.txt, api.json)과 바로 붙여 넣을 프롬프트, 주의할 점을 정리합니다.

## 학교 데이터 레퍼런스

- [공통 규칙](https://cassiiopeia.github.io/pro-sejongpeia/data/overview/): 학교 데이터 메서드가 공유하는 클라이언트, 결과 값 규칙, 캐시, 실패 격리, 요청 방식을 정리합니다.
- [학과·학기 코드](https://cassiiopeia.github.io/pro-sejongpeia/data/codes/): 소속 분류, 학기, 학과, 이수 구분, 선택 영역 코드표를 로그인 없이 학교 값 그대로 받는 메서드 5개를 설명합니다.
- [개설강좌](https://cassiiopeia.github.io/pro-sejongpeia/data/lectures/): 학과, 과목명, 교수명으로 개설강좌를 검색하고 모두 비우면 그 학기 전체를 받는 lectures 메서드를 설명합니다.
- [학사일정 (학부·대학원)](https://cassiiopeia.github.io/pro-sejongpeia/data/calendar/): 학부 학사일정과 대학원 사이트별 학사일정을 날짜와 제목으로 받는 calendar, graduate_calendar 메서드를 설명합니다.
- [기숙사](https://cassiiopeia.github.io/pro-sejongpeia/data/dormitory/): 기숙사 일주일 식단(조식·중식·석식)과 공지 목록을 로그인 없이 받는 dormitory_menu, dormitory_notices 메서드를 설명합니다.
- [학식](https://cassiiopeia.github.io/pro-sejongpeia/data/cafeteria/): 학식 식당별 메뉴와 가격을 받는 cafeteria_menu, 식당 목록을 모아 주는 cafeteria_places 메서드를 설명합니다.
- [캠퍼스 장소](https://cassiiopeia.github.io/pro-sejongpeia/data/campus-places/): 건물과 편의시설의 이름, 위치(위도·경도), 안내 정보를 받는 campus_places 메서드를 설명합니다.
- [비교과 프로그램](https://cassiiopeia.github.io/pro-sejongpeia/data/extracurricular/): 기간별 비교과 프로그램 일정을 분류, 장소와 함께 받는 extracurricular_events 메서드를 설명합니다.
- [교육과정](https://cassiiopeia.github.io/pro-sejongpeia/data/curriculum/): 학과 코드와 과목 번호로 권장 학년·학기, 이수 구분, 학점, 교과목 개요를 받는 curriculum_courses 메서드를 설명합니다.

## 인증 레퍼런스

- [인증 메서드](https://cassiiopeia.github.io/pro-sejongpeia/auth/methods/): 통합·DHC·SIS 인증과 학사 업무 기간 조회의 메서드 이름을 Java, Python, Node.js 별로 정리하고 각각이 보장하는 것을 설명합니다.
- [결과 필드](https://cassiiopeia.github.io/pro-sejongpeia/auth/result-fields/): 통합, DHC, SIS 인증 결과의 필드와 타입, 고전독서 하위 표, SIS 학교 코드, null과 빈 문자열의 규칙을 정리합니다.
- [에러 코드](https://cassiiopeia.github.io/pro-sejongpeia/auth/error-codes/): 인증 호출이 던지는 10개 에러 코드의 의미와 원인, 계정 잠금 대응, 세 언어의 에러 분기 예시를 정리합니다.
- [설정](https://cassiiopeia.github.io/pro-sejongpeia/auth/configuration/): 제한 시간, 로그인 재시도, 인증서 검증 설정을 Java, Python, Node.js 별로 정리하고 Spring 없이 쓰는 Java의 TLS 주의점을 설명합니다.
- [원문·extra 옵션](https://cassiiopeia.github.io/pro-sejongpeia/auth/raw-and-extra/): 학교 원문 응답을 받는 원문 옵션과 이름 붙지 않은 SIS 필드를 받는 extra 옵션의 사용법, 제외되는 민감 키, 안전 주의사항을 설명합니다.
- [학사 업무 기간](https://cassiiopeia.github.io/pro-sejongpeia/auth/business-periods/): 본인 SIS의 학사일정조회 화면이 주는 업무별 허용 기간을 조회하는 방법, 요청 파라미터, 결과 필드, 에러를 설명합니다.

## 이해하기

- [레거시 TLS](https://cassiiopeia.github.io/pro-sejongpeia/understand/legacy-tls/): 세종 포털이 허용하는 유일한 TLS 암호가 최신 JDK, Python, Node.js 기본 설정에서 막혀 있는 이유와 언어별로 이를 푸는 방법을 설명합니다.
- [방화벽과 User-Agent](https://cassiiopeia.github.io/pro-sejongpeia/understand/firewall-user-agent/): 기본 라이브러리 User-Agent를 방화벽이 막고 User-Agent가 없으면 404가 나오는 문제와, 라이브러리가 식별 가능한 User-Agent를 보내는 방식을 설명합니다.
- [SSO 흐름](https://cassiiopeia.github.io/pro-sejongpeia/understand/sso-flow/): 포털 로그인 한 번으로 DHC, SIS, 포털 메인을 조회하는 통합 인증의 요청 순서와 쿠키, 리다이렉트 처리를 설명합니다.
- [로그인 판정과 계정 잠금 방지](https://cassiiopeia.github.io/pro-sejongpeia/understand/login-verdict/): 포털이 200 응답 안의 스크립트 값으로 로그인 결과를 알려 주는 방식과 판정값별 에러 코드, 계정을 잠그지 않기 위한 재시도 규칙을 설명합니다.
- [실패 격리와 캐시](https://cassiiopeia.github.io/pro-sejongpeia/understand/failure-isolation-cache/): 한 정보 출처가 실패해도 나머지가 동작하게 하는 격리 규칙과, 학교 서버에 부담을 주지 않는 캐시·요청 합치기 동작을 설명합니다.
- [매일 도는 실제 포털 점검](https://cassiiopeia.github.io/pro-sejongpeia/understand/daily-live-check/): 매일 실제 포털에 로그인해 세 언어의 결과를 비교하고, 로그인 없이 학교 공개 데이터의 응답 모양을 점검하는 워크플로우가 실제로 하는 일을 설명합니다.

## 기여하기

- [새 정보 출처 추가하기](https://cassiiopeia.github.io/pro-sejongpeia/contribute/add-data-source/): 학교가 공개로 주는 새 정보를 세 언어에 추가하는 7단계 절차와 코드 위치, 의존 규칙, 안전 규칙을 설명합니다.
- [레포 구조](https://cassiiopeia.github.io/pro-sejongpeia/contribute/structure/): 레포 폴더 구성, 개발 환경 명령, 실제 포털 테스트 방법, 포털 변경 대응 규칙, 문서 언어 규칙, 기능 노출 체크리스트를 정리합니다.
- [이슈와 PR](https://cassiiopeia.github.io/pro-sejongpeia/contribute/issues-and-prs/): 이슈를 먼저 올리는 방법, 올리면 안 되는 정보, 라벨과 Discussions, 보안 신고, PR 규칙, 라이선스를 정리합니다.

## 더 보기

- [API 안정성](https://cassiiopeia.github.io/pro-sejongpeia/api-stability/): 공개 API의 범위, 버전 번호의 의미, 세 언어가 같게 유지하는 것, 학교가 바뀔 때의 대응, 안전하게 쓰는 방법을 솔직하게 정리합니다.
- [FAQ](https://cassiiopeia.github.io/pro-sejongpeia/faq/): 세종대 로그인 API 유무, 비밀번호 저장, 요구 사항, 인증 실패와 계정 잠금, 빈 목록의 의미, 캐시 주기 같은 자주 묻는 질문에 답합니다.

## English

### Start

- [Introduction](https://cassiiopeia.github.io/pro-sejongpeia/en/start/introduction/): pro-sejongpeia is an open-source library that gives Java, Python and Node.js the same Sejong University portal login and login-free school data.
- [Quick start](https://cassiiopeia.github.io/pro-sejongpeia/en/start/quickstart/): Install the library in Java, Python or Node.js and make your first student verification and school data calls.

### Guides

- [Add student verification](https://cassiiopeia.github.io/pro-sejongpeia/en/guides/student-verification/): Check Sejong enrollment from the student ID and password of a sign-up form and keep only student ID, name and major, in three languages.
- [Department and lecture search](https://cassiiopeia.github.io/pro-sejongpeia/en/guides/department-lecture-search/): Build a small server in Java, Python or Node.js that returns departments and course listings as JSON, with the response data structure and notes.
- [Academic calendar widget](https://cassiiopeia.github.io/pro-sejongpeia/en/guides/academic-calendar/): Show the undergraduate academic events of the next 30 days ordered by start date, with a widget example in Java, Python and Node.js.
- [Dormitory and cafeteria bot](https://cassiiopeia.github.io/pro-sejongpeia/en/guides/dormitory-cafeteria-bot/): Build today's dormitory menu, cafeteria menus and dormitory notices as message strings, with a bot example in Java, Python and Node.js.
- [Using with coding agents](https://cassiiopeia.github.io/pro-sejongpeia/en/guides/agents/): Files (llms.txt, llms-full.txt, api.json) that teach coding agents such as Claude Code, Cursor and Codex how to use this library, ready-to-paste prompts, and what to watch for.

### School data reference

- [Common rules](https://cassiiopeia.github.io/pro-sejongpeia/en/data/overview/): The client, result value rules, cache, failure isolation and request handling shared by the school data methods.
- [Department and term codes](https://cassiiopeia.github.io/pro-sejongpeia/en/data/codes/): Five methods that return organization category, term, department, course type and selective domain code tables as the school serves them, without login.
- [Course listings](https://cassiiopeia.github.io/pro-sejongpeia/en/data/lectures/): The lectures method searches a term's courses by department, course name or instructor, and returns the whole term when all are left empty.
- [Academic calendar (undergraduate and graduate)](https://cassiiopeia.github.io/pro-sejongpeia/en/data/calendar/): The calendar and graduate_calendar methods return undergraduate and per-site graduate school academic calendars with dates and titles.
- [Dormitory](https://cassiiopeia.github.io/pro-sejongpeia/en/data/dormitory/): The dormitory_menu and dormitory_notices methods return the weekly dormitory menu (breakfast, lunch, dinner) and notice list without login.
- [Cafeterias](https://cassiiopeia.github.io/pro-sejongpeia/en/data/cafeteria/): The cafeteria_menu method returns a cafeteria's menu and prices, and cafeteria_places builds the cafeteria list.
- [Campus places](https://cassiiopeia.github.io/pro-sejongpeia/en/data/campus-places/): The campus_places method returns buildings and facilities with names, coordinates (latitude and longitude) and guide information.
- [Extracurricular programs](https://cassiiopeia.github.io/pro-sejongpeia/en/data/extracurricular/): The extracurricular_events method returns extracurricular programs for a period with category, location and detail link.
- [Curriculum](https://cassiiopeia.github.io/pro-sejongpeia/en/data/curriculum/): The curriculum_courses method returns the suggested year and term, course type, credits and course overview from a department code and course number.

### Authentication reference

- [Authentication methods](https://cassiiopeia.github.io/pro-sejongpeia/en/auth/methods/): Method names of the integrated, DHC and SIS logins and the academic business periods lookup in Java, Python and Node.js, and what each one guarantees.
- [Result fields](https://cassiiopeia.github.io/pro-sejongpeia/en/auth/result-fields/): Fields and types of the integrated, DHC and SIS results, the classic reading sub-tables, SIS school codes, and the rules for null versus empty string.
- [Error codes](https://cassiiopeia.github.io/pro-sejongpeia/en/auth/error-codes/): Meaning and typical cause of the 10 error codes an authentication call throws, account lock guidance, and error handling examples in three languages.
- [Configuration](https://cassiiopeia.github.io/pro-sejongpeia/en/auth/configuration/): Timeout, login retry and certificate verification settings in Java, Python and Node.js, plus the TLS caveat for using the Java library without Spring.
- [Raw response and extra options](https://cassiiopeia.github.io/pro-sejongpeia/en/auth/raw-and-extra/): How to use the raw option that returns the school's raw response and the extra option that returns unnamed SIS fields, the always-excluded keys and safety notes.
- [Academic business periods](https://cassiiopeia.github.io/pro-sejongpeia/en/auth/business-periods/): How to fetch the per-business allowed periods that the student's own SIS academic schedule screen shows, with request parameters, result fields and errors.

### Understand

- [Legacy TLS](https://cassiiopeia.github.io/pro-sejongpeia/en/understand/legacy-tls/): Why the only TLS cipher the Sejong portal accepts is blocked by default in current JDK, Python and Node.js, and how the library re-enables it in each language.
- [Firewall and User-Agent](https://cassiiopeia.github.io/pro-sejongpeia/en/understand/firewall-user-agent/): Why the firewall blocks default library User-Agents and some sites answer 404 without one, and how the library sends an identifying User-Agent on every request.
- [SSO flow](https://cassiiopeia.github.io/pro-sejongpeia/en/understand/sso-flow/): The request order, cookies and redirect handling of the integrated authentication that reads DHC, SIS and the portal main page with a single portal login.
- [Login verdict and account lock protection](https://cassiiopeia.github.io/pro-sejongpeia/en/understand/login-verdict/): How the portal reports the login result in a script value inside a 200 response, the error code for each verdict, and the retry rules that keep accounts from being locked.
- [Failure isolation and cache](https://cassiiopeia.github.io/pro-sejongpeia/en/understand/failure-isolation-cache/): The isolation rules that keep one data source failing from affecting the rest, and the cache and request merging that avoid putting load on the school servers.
- [Daily live portal check](https://cassiiopeia.github.io/pro-sejongpeia/en/understand/daily-live-check/): What the daily workflow actually does: sign in to the live portal and compare the three languages, and check the response shape of public school data without login.

### Contribute

- [Add a new data source](https://cassiiopeia.github.io/pro-sejongpeia/en/contribute/add-data-source/): The 7-step procedure for adding new public school data to all three languages, with code locations, dependency rules and safety rules.
- [Repository structure](https://cassiiopeia.github.io/pro-sejongpeia/en/contribute/structure/): Repository folders, development commands, live-portal tests, the rule for portal changes, documentation languages and the feature exposure checklist.
- [Issues and pull requests](https://cassiiopeia.github.io/pro-sejongpeia/en/contribute/issues-and-prs/): How to open an issue first, what never to post, labels and Discussions, private security reports, pull request rules and the license.

### More

- [API stability](https://cassiiopeia.github.io/pro-sejongpeia/en/api-stability/): What is public API, what the version number means, what the three languages keep identical, what happens when the school changes, and how to use it safely.
- [FAQ](https://cassiiopeia.github.io/pro-sejongpeia/en/faq/): Answers on the Sejong login API, password storage, requirements, authentication failures and locked accounts, what an empty list means and the cache period.

## 기계가 읽는 파일 (Machine-readable)

- [api.json](https://cassiiopeia.github.io/pro-sejongpeia/api.json): 공개 메서드 목록: 세 언어 이름, 인자와 기본값, 반환 모델 필드, 실패 동작, 캐시, 로그인 필요 여부 / Public method list: names in three languages, parameters and defaults, return model fields, failure behavior, cache, login requirement
- [llms-full.txt](https://cassiiopeia.github.io/pro-sejongpeia/llms-full.txt): 한국어 문서 전체를 한 파일로 / All Korean docs in one file
- [llms-full.en.txt](https://cassiiopeia.github.io/pro-sejongpeia/llms-full.en.txt): 영어 문서 전체를 한 파일로 / All English docs in one file

## 저장소 (Repository)

- [AGENTS.md](https://github.com/Cassiiopeia/pro-sejongpeia/blob/main/AGENTS.md): 이 저장소에 기여하는 에이전트용 규칙: 구조, 의존 규칙, 테스트 명령, 새 출처 추가 절차 / Rules for agents contributing to this repository: layout, dependency rule, test commands, how to add a source
- [spec/api-index.json](https://github.com/Cassiiopeia/pro-sejongpeia/blob/main/spec/api-index.json): api.json 의 원본 (손으로 관리, 구현과 어긋나면 CI 가 실패) / Source of api.json (hand-maintained; CI fails if it drifts from the implementations)
- [spec/PUBLIC_DATA.md](https://github.com/Cassiiopeia/pro-sejongpeia/blob/main/spec/PUBLIC_DATA.md): 공개 데이터 계약: 요청, 필드 대응, 값 규칙 (영어) / Public data contract: requests, field mapping, value rules