KR Embassy Links Collection Plan

This content is not available in your language yet.

1. 프로젝트 개요

1.1 목적

대한민국 외교부 홈페이지(https://www.mofa.go.kr/www/index.do)에서 모든 재외공관(대사관, 총영사관, 분관, 출장소) 링크를 추출하여 구조화된 데이터셋으로 생성합니다.

1.2 배경

외교부 홈페이지는 지역별로 재외공관 목록을 제공
각 공관의 링크는 정부 공식 정보로 신뢰성이 높음
국가별, 지역별 분류가 이미 구조화되어 있음
향후 외교부 공식 뉴스 및 공지사항 수집의 기반 데이터로 활용

1.3 범위

데이터 소스: https://www.mofa.go.kr/www/index.do
대상 국가: country=kr (대한민국)
수집 대상: 모든 재외공관 링크
- 대사관 (Embassy)
- 총영사관 (Consulate General)
- 분관 (Branch Office)
- 출장소 (Liaison Office)
- 대표부 (Representative Office)

2. 데이터 소스 분석

2.1 페이지 구조 분석

외교부 홈페이지는 다음과 같은 구조로 재외공관을 분류:

대륙별 분류:
- 동북아시아 (Northeast Asia)
- 동남아시아/서남아시아태평양 (Southeast Asia Southwest Asia and pacific)
- 북미 (North America)
- 중남미 (Latin America)
- 유럽 (Europe)
- 아프리카 (Sub-Saharan Africa)
- 중동 (Middle East·North Africa)
- 러시아·중앙아시아 (Russia·Central Asia)

2.2 링크 추출 대상

각 대륙 섹션 내에서:

공관명 (예: “주일본 대한민국 대사관”)
링크 URL (공관 상세 페이지 또는 홈페이지)
지역 정보 (대륙, 국가)
공관 유형 (대사관/총영사관/분관/출장소)

2.3 예상 데이터 규모

예상 공관 수: 약 180-200개 (대사관 + 총영사관 + 분관 + 출장소)
데이터 크기: 약 50-100KB (JSON 형식)
Chunk 필요성: 단일 파일로 충분 (10MB 이하)

3. Category 및 Content 파라미터 결정

3.1 Category 파라미터 분석

옵션 1: `category=news` ❌

부적절한 이유:
- 대사관 링크는 뉴스 콘텐츠가 아님
- 링크 목록 자체는 정보성 데이터
- 향후 뉴스 수집과 혼동 가능

옵션 2: `category=government` ✅ (추천)

적절한 이유:
- 외교부는 정부 기관
- 재외공관은 정부 공식 기관
- 정부 공식 정보로 분류 가능

옵션 3: `category=official` ✅ (대안)

적절한 이유:
- 공식 기관 정보
- 정부/공공기관 구분 가능

옵션 4: `category=diplomatic` ✅ (대안)

적절한 이유:
- 외교 관련 특화 카테고리
- 명확한 의미 전달

3.2 Content 파라미터 분석

현재 프로젝트 구조를 확인한 결과, content 파라미터는 선택적입니다:

일부 경로: country={cc}/category={cat}/content={nature}/date=YYYY-MM-DD/
실제 사용: country={cc}/category={cat}/date=YYYY-MM-DD/ (content 생략 가능)

옵션 1: `content=link` ✅ (추천)

링크 목록 데이터임을 명확히 표현
간단하고 직관적

옵션 2: `content=embassy` ✅ (대안)

대사관 정보임을 명확히 표현
특화된 의미

옵션 3: Content 파라미터 생략 ✅ (가장 간단)

현재 프로젝트 구조에서 content는 선택적
category=government만으로도 충분히 의미 전달

3.3 최종 결정

추천 구조 (Option A - Content 포함):

research/datasets/country=kr/category=government/content=link/date=2026-01-28/raw_0001.json

대안 구조 (Option B - Content 생략):

research/datasets/country=kr/category=government/date=2026-01-28/raw_0001.json

권장사항:

Option B (Content 생략) 권장
- 현재 프로젝트의 실제 사용 패턴과 일치
- 경로 깊이 감소 (3-5 레벨 제한 준수)
- category=government만으로도 충분히 의미 전달

4. 폴더 구조 설계

4.1 최종 경로 구조

research/datasets/
└── country=kr/
    └── category=government/
        └── date=2026-01-28/
            ├── raw_0001.json
            └── raw_metadata.json

4.2 경로 구성 요소

파라미터	값	설명
`country`	`kr`	대한민국 (ISO 3166-1 alpha-2)
`category`	`government`	정부/공공기관 카테고리
`date`	`YYYY-MM-DD`	수집 일자 (오늘 날짜)
파일명	`raw_0001.json`	첫 번째 청크 (단일 파일 예상)
메타데이터	`raw_metadata.json`	청크 메타데이터

4.3 파일명 규칙 준수

✅ 날짜는 디렉토리에만 포함 (date=YYYY-MM-DD/)
✅ 파일명은 raw_NNNN.json 형식 (날짜 없음)
✅ 연속된 시퀀스 번호 (raw_0001.json)
✅ 소문자 및 snake_case 준수

5. 데이터 수집 전략

5.1 웹 스크래핑 접근 방법

방법 1: HTML 파싱 (추천)

도구: cheerio (Node.js) 또는 BeautifulSoup (Python)
장점:
- 빠른 처리 속도
- 외교부 페이지 구조가 안정적
- JavaScript 렌더링 불필요
단점:
- HTML 구조 변경 시 파싱 로직 수정 필요

방법 2: 브라우저 자동화

도구: Puppeteer 또는 Playwright
장점:
- JavaScript 렌더링 지원
- 동적 콘텐츠 처리 가능
단점:
- 느린 처리 속도
- 리소스 사용량 높음
- 외교부 페이지는 정적이므로 불필요

5.2 링크 추출 로직

페이지 로드: https://www.mofa.go.kr/www/index.do
대륙별 섹션 탐색:
- 각 대륙 섹션의 <ul> 또는 <div> 요소 찾기
공관 링크 추출:
- <a> 태그에서 href 속성 추출
- 링크 텍스트에서 공관명 추출
- 공관 유형 파싱 (대사관/총영사관/분관/출장소)
데이터 정규화:
- 상대 경로를 절대 경로로 변환
- 중복 제거
- 유효성 검증

5.3 데이터 스키마 설계

{
  "meta": {
    "dataset_id": "kr-government-2026-01-28-0001",
    "country": "kr",
    "category": "government",
    "collected_at": "2026-01-28T12:00:00Z",
    "source_url": "https://www.mofa.go.kr/www/index.do",
    "source_type": "mofa_official",
    "total_records": 185,
    "engine": {
      "name": "embassy-link-collector",
      "version": "1.0.0"
    }
  },
  "records": [
    {
      "embassy_name": "주일본 대한민국 대사관",
      "embassy_name_en": "Embassy of the Republic of Korea in Japan",
      "url": "https://overseas.mofa.go.kr/jp-ko/index.do",
      "embassy_type": "embassy",
      "region": "동북아시아",
      "region_en": "Northeast Asia",
      "country_code": "jp",
      "city": "도쿄",
      "city_en": "Tokyo",
      "normalized_domain": "overseas.mofa.go.kr",
      "discovery_method": "mofa_official_list",
      "collected_at": "2026-01-28T12:00:00Z"
    }
  ]
}

5.4 공관 유형 분류

한글	영문	embassy_type	설명
대사관	Embassy	`embassy`	주재국 대표 기관
총영사관	Consulate General	`consulate_general`	지역별 영사 업무
분관	Branch Office	`branch`	총영사관 하위 기관
출장소	Liaison Office	`liaison`	임시/특수 업무
대표부	Representative Office	`representative`	국제기구 대표

6. Chunking 전략

6.1 Chunk 크기 결정

예상 데이터 크기: 50-100KB
Chunk 크기 제한: 10-20MB (프로젝트 규칙)
결론: 단일 파일로 충분 (raw_0001.json)

6.2 Chunking 규칙

단일 파일 생성:
- 모든 공관 링크를 하나의 JSON 파일에 저장
- 파일명: raw_0001.json
메타데이터 생성:
- raw_metadata.json 생성
- 총 레코드 수, 총 크기, SHA-256 해시 포함
확장성 고려:
- 향후 공관 수가 증가하거나 추가 정보가 포함되면
- 10MB 초과 시 자동으로 raw_0002.json 생성하도록 설계

6.3 메타데이터 파일 구조

{
  "partition": "country=kr/category=government/date=2026-01-28",
  "totalRecords": 185,
  "totalCapacity": 87543,
  "chunks": [
    {
      "filename": "raw_0001.json",
      "size": 87543,
      "sha256": "abc123...",
      "recordCount": 185,
      "recordRange": {
        "start": 0,
        "end": 184
      }
    }
  ],
  "createdAt": "2026-01-28T12:00:00Z",
  "source": {
    "url": "https://www.mofa.go.kr/www/index.do",
    "type": "mofa_official"
  }
}

7. 구현 단계

7.1 Phase 1: 데이터 수집 스크립트 개발

파일 위치: dev/collect-kr-embassy-links.ts (또는 .py)

기능:

외교부 페이지 HTML 다운로드
HTML 파싱 및 링크 추출
데이터 정규화 및 검증
JSON 형식으로 변환

의존성:

Node.js: cheerio, axios (또는 node-fetch)
Python: beautifulsoup4, requests

7.2 Phase 2: Chunking 및 저장

파일 위치: dev/chunk-embassy-data.ts (또는 기존 chunking 스크립트 활용)

기능:

수집된 데이터를 프로젝트 스키마에 맞게 변환
10MB 기준으로 자동 chunking (현재는 단일 파일)
raw_metadata.json 생성
research/datasets/country=kr/category=government/date=YYYY-MM-DD/ 경로에 저장

7.3 Phase 3: 검증 및 테스트

검증 항목:

모든 대륙의 공관이 포함되었는지 확인
링크 유효성 검증 (HTTP 상태 코드 확인)
중복 제거 확인
JSON 스키마 검증
파일 크기 및 메타데이터 일치 확인

7.4 Phase 4: R2 업로드

기존 업로드 스크립트 활용:

dev/upload-to-r2.ts 사용
country=kr, category=government 필터 적용

8. 기술 스택 및 도구

8.1 추천 스택 (Node.js)

// 의존성
{
  "cheerio": "^1.0.0",      // HTML 파싱
  "axios": "^1.6.0",        // HTTP 요청
  "zod": "^4.3.6",          // 스키마 검증
  "tsx": "^4.19.2"          // TypeScript 실행
}

8.2 대안 스택 (Python)

# 의존성
beautifulsoup4>=4.12.0
requests>=2.31.0
pydantic>=2.0.0  # 스키마 검증

9. 에러 처리 및 예외 상황

9.1 예상 에러 시나리오

네트워크 에러:
- 재시도 로직 (최대 3회, exponential backoff)
- 타임아웃 설정 (30초)
HTML 구조 변경:
- 파싱 실패 시 명확한 에러 메시지
- 수동 확인 필요 알림
링크 유효성 실패:
- 404/403 등 실패 링크는 별도 로그에 기록
- 메인 데이터셋에는 포함하되 validated: false 플래그 추가
데이터 크기 초과:
- 10MB 초과 시 자동 chunking
- 메타데이터에 chunk 정보 기록

9.2 로깅 전략

성공 로그: 수집된 공관 수, 처리 시간
경고 로그: 유효성 검증 실패 링크
에러 로그: 파싱 실패, 네트워크 에러

10. 검증 및 테스트 계획

10.1 단위 테스트

HTML 파싱 로직 테스트
링크 정규화 테스트
공관 유형 분류 테스트
JSON 스키마 검증 테스트

10.2 통합 테스트

전체 수집 프로세스 테스트
Chunking 로직 테스트
메타데이터 생성 테스트

10.3 수동 검증

수집된 공관 수가 예상 범위 내인지 확인 (180-200개)
각 대륙별 공관 수 확인
샘플 링크 접근 테스트

11. 향후 확장 계획

11.1 추가 정보 수집

각 공관의 상세 정보 페이지에서 추가 메타데이터 수집
- 주소, 전화번호, 이메일
- 담당 업무 영역
- 공관장 정보

11.2 정기 업데이트

주기적 재수집 스크립트 (월 1회)
변경사항 감지 및 알림
버전 관리 (날짜별 파티션)

11.3 다른 정부 기관 확장

다른 정부 부처 공식 링크 수집
공공기관 링크 수집
category=government 하위에 다양한 소스 추가

12. 일정 및 마일스톤

12.1 개발 일정 (예상)

단계	작업	예상 시간
Phase 1	데이터 수집 스크립트 개발	2-3시간
Phase 2	Chunking 및 저장 로직	1-2시간
Phase 3	검증 및 테스트	1-2시간
Phase 4	R2 업로드 및 최종 검증	1시간
총계		5-8시간

12.2 마일스톤

13. 참고 자료

13.1 프로젝트 규칙

13.2 관련 파일

src/lib/path/path-builders.ts - 경로 생성 함수
dev/upload-to-r2.ts - R2 업로드 스크립트
research/README.md - Research 데이터 구조 설명

13.3 외부 리소스

부록 A: Category 파라미터 최종 결정

결정: `category=government` ✅

이유:

외교부는 정부 기관
재외공관은 정부 공식 기관
향후 다른 정부 부처 데이터와 일관성 유지
news와 명확히 구분

Content 파라미터: 생략 ✅

이유:

현재 프로젝트 구조에서 content는 선택적
경로 깊이 감소 (3-5 레벨 제한 준수)
category=government만으로도 충분히 의미 전달

최종 경로 구조

research/datasets/country=kr/category=government/date=2026-01-28/raw_0001.json