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');
// → 서울대학교의 모든 학과 목록

// 성취기준 검색 (과목/단원 정보 포함)
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 데이터베이스 (4.6MB)
├── src/
│   ├── curriculum-db.ts      # CurriculumDB 서비스 클래스
│   ├── types.ts              # TypeScript 타입 정의
│   ├── index.ts              # 모듈 진입점
│   └── utils/
│       ├── case-converter.ts # snake_case → camelCase 변환
│       └── search-helpers.ts # 검색 유틸리티
├── scripts/
│   ├── 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)→ 학과 ← 대학

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.major | 학과 | get, getByUniversity, search |

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

문서

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

스크립트

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

데이터 통계

| 항목 | 개수 | |------|------| | 교육과정 | 3개 | | 교과군 | 26개 | | 과목 | 170개 | | 단원 | 672개 | | 성취기준 | 3,069개 | | 학교 (초/중/고) | 12,530개 | | 대계열 | 7개 | | 중계열 | 102개 | | 대학 | 220개 | | 학과 | 7,694개 |

기술 스택

• 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