Korean Scholarship Search

# Report Format

최종 답변은 changelog처럼 나열하지 말고, 아래 형식을 기본으로 한다.

## 1. Header summary

- 검색 기준일
- 검색 범위
- 총 후보 수
- 지금 지원 가능 수
- 곧 열릴 공고 수
- 마감된 공고 수

## 2. Grouping

1. 지금 지원 가능
2. 곧 열림
3. 조건은 맞지만 마감됨
4. 검증 부족 / 미확인

## 3. Entry format

각 항목은 아래 순서를 유지한다.

- 장학금명
- 기관명 / 기관 유형
- 금액
- 신청기간
- 상태 (`open`, `upcoming`, `closed`, `D-3`)
- 핵심 자격
- 지원 가능 여부 (`가능`, `불확실`, `불가`)
- 공식 공고 링크
- 신청 링크

## 4. Readability rules

- 한 항목에 문장을 너무 길게 쓰지 않는다.
- 핵심 조건은 `/` 로 짧게 끊는다.
- 금액이 불명확하면 `금액 미공개` 라고 적고 공고 원문 링크를 남긴다.
- 확실하지 않은 정보는 `미확인` 으로 표시한다.


# School Discovery Checklist

특정 학교를 주면 아래 표면을 순서대로 확인한다.

이 절차는 서울대 전용이 아니라 전국 모든 `*.ac.kr` 대학에 공통 적용한다.

## 1. 학교 본부

- 학생지원처
- 장학팀 / 장학복지팀
- 학사공지
- 일반공지

검색 예시:

- `site:{school-domain} 장학 공지`
- `site:{school-domain} 학생지원처 장학`
- `site:{school-domain} 학사공지 장학`

## 2. 단과대학

학교명 + 단과대 이름으로 다시 좁힌다.

- 공과대학
- 인문대학
- 사회과학대학
- 경영대학
- 대학원

검색 예시:

- `site:{school-domain} 장학 공과대학`
- `site:{school-domain} 장학생 모집 대학원`

## 3. 학과 / 전공 / 협동과정

학과 홈페이지가 별도 서브도메인 또는 하위 경로일 수 있다.

- 학과 공지사항
- 학부 공지
- 대학원 공지
- 외부 장학 추천 공지

검색 예시:

- `site:{school-domain} "{department-name}" 장학`
- `site:{school-domain} "{department-name}" 공지 장학생`
- `site:{school-domain} "{department-name}" 외부 장학`

## 4. 첨부파일

- PDF, HWP, DOCX 첨부가 있으면 열어 본다.
- 자격/성적/지원구간/금액이 첨부에만 있는 경우가 많다.

## 5. 정리 원칙

- `교내 장학`
- `학과 장학`
- `외부 추천 장학`

이 세 묶음으로 나눠 보여주면 가독성이 좋아진다.


# Search Clues

장학금 공고는 학교/기관마다 제목이 제각각이라서 `장학금` 한 단어만으로는 누락이 많다.

## 1. Core keywords

- 장학
- 장학금
- 장학생
- 장학생 선발
- 장학생 모집
- 장학 안내
- 장학 공고
- 장학 신청

## 2. University-specific clues

- 교내 장학
- 학과 장학
- 외부 장학
- 외부 장학 추천
- 추천장학
- 등록금 감면
- 등록금 면제
- 생활비 지원
- 학업장려비
- 근로장학
- 성적우수 장학
- 신입생 장학
- 계속장학생
- 복지 장학

## 3. Organization-specific clues

- 재단: 장학생 선발, 장학생 모집, 지원사업, 교육지원
- 기업: 인재육성, 장학생 모집, CSR 장학, 사회공헌 장학
- 지자체: 대학생 장학금, 지역인재 장학금, 주민등록 요건, 거주요건
- 한국장학재단: 국가장학금, 푸른등대, 대통령과학장학금, 국가우수장학금, 국가근로장학금

## 4. Attachment clues

본문보다 첨부파일에 핵심 조건이 있는 경우가 많다.

- 모집요강
- 선발요강
- 신청서식
- 제출서류
- 추천서
- 개인정보동의서

## 5. Query expansion examples

- `site:*.ac.kr 외부 장학 추천`
- `site:*.ac.kr 등록금 감면`
- `site:*.ac.kr 생활비 지원 장학`
- `site:*.ac.kr 장학생 선발`
- `site:*.or.kr 장학생 모집`
- `site:*.go.kr 지역인재 장학금`


# Scholarship Source Patterns

한국 장학금 검색은 항상 **공식 공고 우선** 이다.

## 1. Source priority

1. 한국장학재단 (`kosaf.go.kr`)
2. 대학 공식 장학/학사/학생지원 공지 (`*.ac.kr`)
3. 지자체/공공기관 (`*.go.kr`, `*.or.kr`)
4. 재단/기업 공식 공고
5. 비공식 모음글은 lead source 로만 사용

## 2. Search query templates

다음 쿼리를 현재 날짜 기준으로 조합한다. 추가 키워드 단서는 `search-clues.md` 를 같이 본다.

- `site:kosaf.go.kr 장학금 {키워드}`
- `site:kosaf.go.kr 푸른등대 {키워드}`
- `site:*.ac.kr 장학 공고 {학교명}`
- `site:*.ac.kr 장학생 모집 {학교명} {전공}`
- `site:*.or.kr 장학생 선발 {키워드}`
- `site:*.go.kr 장학금 공고 {지역명}`
- `site:{재단도메인} 장학생 모집`

특정 학교 완전 탐색이 필요하면 `school-discovery.md` 절차를 같이 따른다.

## 3. What to extract from each notice

- 장학금명
- 운영기관명
- 기관 유형
- 공고일 / 신청 시작일 / 마감일
- 지원 금액 / 등록금형 / 생활비형 / 혼합형
- 지원 대상: 학교, 학부/대학원, 학년, 전공, 지역
- 성적 조건
- 학자금 지원구간 조건
- 제출서류
- 신청 방식
- 공식 공고 링크
- 공식 신청 링크

## 4. Organization type normalization

- `school`: 대학/대학원/고교 교내 장학
- `foundation`: 민간재단, 복지재단, 교육재단
- `government`: 중앙정부/공공기관
- `local-government`: 광역·기초지자체
- `company`: 기업/기업재단/CSR
- `other`: 위 분류가 애매한 경우

## 5. Eligibility normalization

가능하면 아래 필드로 구조화한다.

- `student_levels`: `highschool`, `undergraduate`, `graduate`, `all`
- `school_kinds`: `highschool`, `college`, `university`, `graduate-school`
- `grade_years`: 숫자 배열
- `majors`: 문자열 배열
- `gpa_min`: 4.5 또는 100점 기준이 섞여 있으면 원문도 같이 남긴다
- `income_band_min`, `income_band_max`
- `notes`: 구조화가 애매한 자격 조건

## 6. Verification rule

- 비공식 요약 페이지는 링크 탐색용으로만 본다.
- 최종 결과에는 공식 공고 링크를 반드시 포함한다.
- 공고 날짜가 오래됐으면 최신 회차/학기 공고를 다시 찾는다.


#!/usr/bin/env python3
"""Filter normalized Korean scholarship records and estimate eligibility."""

from __future__ import annotations

import argparse
import json
import re
import sys
from copy import deepcopy
from datetime import date, datetime, timedelta, timezone
from pathlib import Path
from typing import Any


AMOUNT_KEYS = (
    "annual_krw",
    "per_semester_krw",
    "one