기숙사

기숙사(happydorm.sejong.ac.kr)가 공개로 주는 일주일 식단과 공지 목록을 받습니다. 로그인이 필요 없습니다. 식단을 메시지로 만드는 예시는 기숙사·학식 봇, 공통 규칙은 공통 규칙입니다.

요청 파라미터

파라미터	타입	필수	기본값	설명
`location` (`dormitory_menu`, `dormitory_notices`)	문자열	선택	`SJ`	기숙사 위치 구분 값
`page` (`dormitory_notices`)	정수	선택	`1`	공지 쪽 번호
`rows` (`dormitory_notices`)	정수	선택	`10`	한 쪽에 받을 공지 건수
`keyword` (`dormitory_notices`)	문자열	선택	`""`	제목 검색어. 비우면 전체

이름 표기: Python은 snake_case, Node.js와 Java는 camelCase입니다. Node.js는 dormitoryMenu(location = 'SJ'), dormitoryNotices({ page, rows, keyword, location })로 받습니다. Java는 선택 인자를 생략한 dormitoryMenu(), dormitoryNotices()와 전부 받는 dormitoryMenu(String location), dormitoryNotices(int page, int rows, String keyword, String location)가 있고, 검색어 없이 부를 때는 ""를 넘깁니다.
학교 요청(식단): POST https://happydorm.sejong.ac.kr/food/indexFoodList.do, 폼 locgbn=<location>.
학교 요청(공지): POST https://happydorm.sejong.ac.kr/bbs/getBbsList.do, 폼 cPage, rows, bbs_locgbn, bbs_id=notice, sType=subject, sWord.
응답은 JSON인데 콘텐츠 타입이 text/html이라 라이브러리는 본문을 항상 JSON으로 읽습니다.

응답 데이터 구조

dormitory_menu는 DormitoryMenuDay의 목록(7일치)입니다 (필드 이름은 Python 기준, Node.js와 Java는 camelCase). 학교 데이터는 바뀌므로 값은 예시입니다.

[
  {
    "date": "2026-03-02",
    "breakfast": "밥 국 반찬",
    "lunch": "밥 국 주반찬 김치",
    "dinner": "밥 국 주반찬 김치",
    "alternative": "간편식 교환"
  }
]

dormitory_notices는 DormitoryNotices 객체 하나입니다.

{
  "total": 120,
  "pinned": [
    { "id": "1001", "title": "고정 공지 제목", "date": "2026-03-01", "views": 300, "file_name": "안내.png" }
  ],
  "items": [
    { "id": "1000", "title": "일반 공지 제목", "date": "2026-02-28", "views": 80, "file_name": "" }
  ]
}

기숙사 모델에는 extra가 없습니다. 값이 없으면 빈 문자열이고 views와 total은 0입니다.

식단 (`DormitoryMenuDay`)

필드	학교 키	설명
`date`	`fo_date1`~`7`	날짜
`breakfast`	`fo_menu_mor1`~`7`	조식
`lunch`	`fo_menu_lun1`~`7`	중식
`dinner`	`fo_menu_eve1`~`7`	석식
`alternative`	`fo_sub_menu1`~`7`	대체 메뉴

메뉴 문자열은 학교 원문이라 한 칸에 반찬 여러 개가 이어져 있을 수 있습니다. 라이브러리는 나누지 않습니다.

공지 (`DormitoryNotices`와 `DormitoryNotice`)

필드	학교 키	설명
`total`	`totalCount[0].cnt`	전체 건수 (정수)
`pinned`	`topList`	고정 공지 목록
`items`	`list`	일반 공지 목록

공지 한 건:

필드	학교 키	설명
`id`	`seq`	공지 번호
`title`	`subject`	제목
`date`	`regdate`	등록일
`views`	`visitcnt`	조회수 (정수)
`file_name`	`file_name1`	첨부 파일 이름 (없으면 빈 문자열)

작성자 필드(regname, regid)는 읽지 않고 결과에도 없습니다.

실패 동작

메서드와 인자(위치, 쪽, 건수, 검색어)마다 하루(기본 86400초) 캐시합니다. 호출당 요청은 한 번입니다.
학교 실패는 마지막 캐시 값, 없으면 식단은 빈 목록, 공지는 total 0과 빈 목록인 객체입니다. 입력 오류로 예외를 던지지 않습니다.
응답에서 root 배열이 없거나 비어 있으면 식단과 공지 모두 실패입니다.
공지만의 예외: topList, list, totalCount가 없으면 장애가 아니라 「결과 없음」으로 보고 빈 목록과 total 0을 돌려줍니다. 검색어에 맞는 공지가 없는 경우를 장애로 취급하지 않기 위해서입니다.

알려진 한계

location은 기본값 SJ만 쓰는 것을 전제로 합니다. 다른 값은 직접 호출해 보고 쓰세요.
학교가 식단을 올리기 전 주말 등에는 오늘 날짜가 목록에 없을 수 있습니다. 호출하는 쪽에서 처리하세요 (기숙사·학식 봇은 첫날을 대신 보여 줍니다).
빈 목록은 「공지·식단이 없음」과 「학교 쪽 문제」를 구분하지 못합니다.
공지 본문은 제공하지 않습니다. 제목, 날짜, 조회수, 첨부 파일 이름만 받습니다.
계약 원본: spec/PUBLIC_DATA.md

예시 코드

List<DormitoryMenuDay> menuDays = publicData.dormitoryMenu();            // 7일치
DormitoryNotices notices = publicData.dormitoryNotices(1, 3, "", "SJ"); // 1쪽, 3건

menu_days = public_data.dormitory_menu()      # 7일치
notices = public_data.dormitory_notices(rows=3)  # 최신 3건
for notice in notices.items:
    print(notice.date, notice.title)

const menuDays = await publicData.dormitoryMenu(); // 7일치
const notices = await publicData.dormitoryNotices({ rows: 3 }); // 최신 3건

기숙사