npm package: @koreaedu/curriculum-db
Description: 한국 교육과정 데이터베이스 및 프로그래밍 API
Author: Korea Education Partners
Latest version: 2.1.0

# Curriculum DB

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

[![Status](https://img.shields.io/badge/Status-Production%20Ready-brightgreen)]()
[![Node.js](https://img.shields.io/badge/Node.js-22%2B-green)]()
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7%2B-blue)]()

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

## 주요 기능

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

## 설치

### 요구사항

- **Node.js**: 22.0.0 이상 ([다운로드](https://nodejs.org/))
- **패키지 매니저**: pnpm 권장 (`npm install -g pnpm`)

### 의존성 설치

```bash
pnpm install
```

## 빠른 시작

### npm 패키지로 사용 (권장)

```bash
npm install @jobshopper/curriculum-db
```

```typescript
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 경로 사용

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

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

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

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

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

### Excel 관리

```bash
# 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](./docs/API-REFERENCE.md)를 참조하세요.

## 문서

| 문서 | 설명 |
|------|------|
| [API Reference](./docs/API-REFERENCE.md) | CurriculumDB 전체 API 문서 |
| [User Guide](./docs/USER-GUIDE.md) | 비개발자용 엑셀 편집 가이드 |
| [Error Codes](./docs/ERROR-CODES.md) | 오류 코드 및 해결 방법 |

## 스크립트

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

## 데이터 통계

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

## 기술 스택

- **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