Curriculum DB

한국 교육과정 데이터베이스 및 프로그래밍 API

SQLite 기반의 교육과정, 과목, 성취기준, 대학, 학과, 학교 데이터를 관리하고 조회할 수 있는 TypeScript 라이브러리입니다.

주요 기능

• CurriculumDB API: TypeScript로 교육 데이터 조회
• Excel 연동: DB ↔ Excel 양방향 변환
• FTS5 검색: 한글 전문 검색 지원
• 데이터 검증: 4단계 검증 시스템

설치

요구사항

• Node.js: 22.0.0 이상 (다운로드)
• 패키지 매니저: pnpm 권장 (npm install -g pnpm)

의존성 설치

pnpm install

빠른 시작

npm 패키지로 사용 (권장)

npm install @jobshopper/curriculum-db

import { createCurriculumDB } from '@jobshopper/curriculum-db';

// 패키지에 포함된 기본 DB 사용 (경로 생략 시 자동 적용)
const db = createCurriculumDB();

// 대학 검색
const universities = db.university.search('서울대');
// → [{ id: 'hz-university::13', name: '서울대학교' }]

// 학과 조회 (계열 정보 포함)
const majors = db.major.getByUniversity('hz-university::13');
// → [{ id: '...', name: '컴퓨터공학과', categories: [...] }, ...]

// 학교 검색 (이름 또는 주소)
const schools = db.school.search('서울고등');
// → [{ id: '...', name: '서울고등학교', address: '...' }, ...]

// 성취기준 검색 (과목/단원 정보 포함)
const standards = db.achievement.search('생태계');
for (const std of standards) {
  console.log(`[${std.subjectName}] ${std.id}: ${std.description}`);
}
// → [통합과학2] 10통과2-02-01: 생태계 구성 요소와...

db.close();

커스텀 DB 경로 사용

import { createCurriculumDB } from '@jobshopper/curriculum-db';

// 직접 DB 경로 지정
const db = createCurriculumDB('/path/to/your/curriculum-db.db');

직접 인스턴스 생성 (싱글톤 없이)

import { CurriculumDB, DBPath } from '@jobshopper/curriculum-db';

// 싱글톤 없이 직접 생성
const db = new CurriculumDB(DBPath);

Excel 관리

# DB → Excel 내보내기
pnpm export

# Excel 데이터 검증
pnpm validate

# Excel → DB 가져오기
pnpm import

프로젝트 구조

curriculum-db/
├── data/
│   └── curriculum-db.db      # SQLite 데이터베이스
├── src/
│   ├── curriculum-db.ts      # CurriculumDB 서비스 클래스
│   ├── types.ts              # TypeScript 타입 정의
│   ├── index.ts              # 모듈 진입점
│   └── utils/
│       ├── case-converter.ts # snake_case → camelCase 변환
│       └── search-helpers.ts # 검색 유틸리티
├── scripts/
│   ├── sync-from-extraction.ts # extraction DB → 패키지 DB 동기화
│   ├── export-to-excel.ts      # DB → Excel 내보내기
│   ├── import-from-excel.ts    # Excel → DB 가져오기
│   └── validate-excel.ts       # Excel 데이터 검증
├── templates/
│   └── curriculum-data.xlsx  # Excel 템플릿 (pnpm export로 생성)
└── docs/
    ├── API-REFERENCE.md      # API 상세 문서
    ├── USER-GUIDE.md         # 사용자 가이드
    └── ERROR-CODES.md        # 오류 코드 참조

데이터 구조

교과 데이터

교육과정 → 교과군 → 과목 → 단원 → 성취기준

학교 데이터

학교 (초/중/고등학교) - id, name, address

대학/학과 데이터

대계열 → 중계열 ←(N:M)→ 학과 ← 대학

학교 데이터

학교 (id, name, address)

API 네임스페이스

| 네임스페이스 | 설명 | 주요 메서드 | |-------------|------|------------| | db.curriculum | 교육과정 | get, list, getByVersionAndLevel | | db.subjectCategory | 교과군 | get, list, getByCurriculum | | db.subject | 과목 | get, list, search | | db.unit | 단원 | get, getBySubject (성취기준 포함), search | | db.achievement | 성취기준 | get, search, getWithContext | | db.school | 학교 (초/중/고) | get, list, search, searchByAddress, count | | db.majorParentCategory | 대계열 | get, list, getByName | | db.majorCategory | 중계열 | get, getByParent, search | | db.university | 대학 | get, getByName, search | | db.school | 학교 | get, list, search | | db.major | 학과 | get, getByUniversity, search |

상세 문서는 docs/API-REFERENCE.md를 참조하세요.

문서

| 문서 | 설명 | |------|------| | API Reference | CurriculumDB 전체 API 문서 | | User Guide | 비개발자용 엑셀 편집 가이드 | | Error Codes | 오류 코드 및 해결 방법 |

스크립트

| 명령어 | 설명 | |--------|------| | pnpm sync | extraction DB → 패키지 DB 동기화 | | pnpm export | DB → Excel 내보내기 | | pnpm validate | Excel 데이터 검증 | | pnpm import | Excel → DB 가져오기 | | pnpm test | 테스트 실행 | | pnpm typecheck | TypeScript 타입 체크 |

수동 추가 학교 (Manual Schools)

학교알리미(schoolinfo.go.kr) 공시에 등록되지 않은 학교는 수동으로 추가한다. 주로 신설 학교가 아직 공시 미반영인 경우에 해당한다.

ID 규칙

• 형식: {지역코드 3자리}9901 (7자리 숫자)
• 앞 3자리 지역코드는 학교알리미 공식 코드의 앞자리를 그대로 따른다
• suffix 9901은 "manual add" 식별자 — 공식 코드와 충돌하지 않도록 예약

주소 표기

공식 학교알리미 데이터와 동일하게 시/도 + 구/군 수준으로 축약한다 (예: 서울특별시 동작구, 강원특별자치도 원주시). 도로명 주소는 저장하지 않는다.

추가 절차

1. SQLite 직접 INSERT + FTS 재구축

   sqlite3 data/curriculum-db.db <<SQL
   INSERT INTO school (id, name, address) VALUES ('XXXXXXX', '학교명', '시도 구군');
   INSERT INTO school_fts(school_fts) VALUES('rebuild');
   SQL

2. package.json 패치 버전 bump
3. pnpm test 로 기존 테스트 통과 확인
4. 데이터 커밋 + 문서 커밋(이 섹션 이력 갱신) + v{version} tag
5. npm publish
6. 소비 측(hzpro-dev 등)의 pnpm catalog/pnpm-workspace.yaml 갱신 + pnpm install

이력

| ID | 학교명 | 지역 | 추가일 | 커밋 | |----|--------|------|--------|------| | 7019901 | 흑석고등학교 | 서울특별시 동작구 | 2026-03-26 | b8f8204 | | 7319901 | 인천이음고등학교 | 인천광역시 서구 | 2026-03-26 | b8f8204 | | 9309901 | 세종캠퍼스고등학교 | 세종특별자치시 | 2026-03-26 | b8f8204 | | 7819901 | 섬강고등학교 | 강원특별자치도 원주시 | 2026-04-23 | v2.1.1 |

데이터 통계

| 항목 | 개수 | |------|------| | 교육과정 | 4개 | | 교과군 | 27개 | | 과목 | 263개 | | 단원 | 998개 | | 성취기준 | 3,069개 | | 학교 (초/중/고) | 12,534개 | | 대계열 | 7개 | | 중계열 | 102개 | | 대학 | 220개 | | 학과 | 7,694개 | | 학교 | 12,534개 |

기술 스택

• Runtime: Node.js 22+
• Language: TypeScript 5.7+
• Database: SQLite 3 (better-sqlite3)
• Search: FTS5 with trigram tokenizer
• Excel: @e965/xlsx (SheetJS fork)
• Test: Vitest

라이선스

MIT