# 세계 반도체·디스플레이 공급망 근거 데이터 v3

기준일: **2026-10-17**. 기존 웨이퍼·DRAM/HBM/NAND·EUV 자료 v2의 1,663개 기록을 보존하고 소재, 부품·기판, 전공정 장비, 장비 서브시스템, 디스플레이, 조립·테스트·후공정을 추가했습니다. 최종 행 수·회사·지표·출처 수는 `data/release_summary.json`을 기준으로 확인하십시오.

## 파일

- `report_ko.html`: 한국어 전체 보고서, 모든 신규 관측값의 인쇄용 계열 표, 기존 자료까지 포함한 오프라인 검색·필터·CSV 다운로드, 여섯 분야 차트와 원문 목록.
- `report_ko.pdf` / `report_ko.txt`: 검색 가능한 전체 인쇄 보고서와 추출 텍스트. 모든 신규 observation_id가 PDF에 포함되는지 검증합니다.
- `semiconductor_expanded.xlsx`: 전체·이번 추가·분야별 데이터, 기업·출처·지표사전·공개 공백. 문자열을 수식으로 실행하지 않습니다.
- `semiconductor_history.sqlite`: observations/sources/companies/metric_dictionary/company_metric_coverage/coverage_gaps 테이블과 확장·검증된 역사자료 뷰.
- `data/all_observations.{jsonl,csv}` / `expanded_observations.{jsonl,csv}`: 전체 자료와 이번 확장 자료. JSONL이 원래 타입과 결측을 가장 명확히 보존합니다.
- `data/rag_facts_ko.jsonl`: 근거·원문 URL·위치·시점 메타데이터를 포함한 RAG용 문장.
- `research/`: 여섯 분야의 큐레이션된 관측값·출처·회사·공백·한국어 해설 JSON. 원문 PDF·HTML 전체 복사본은 배포하지 않습니다.
- `charts/`: 독립 SVG 차트. `baseline/`과 `previous/`에는 이전 보고서·기준 데이터와 재현에 필요한 v2 입력을 보존합니다.
- `MANIFEST.sha256` / `release_verification.json`: 배포 파일 해시 목록과 ZIP 검증 결과. ZIP 내부 파일은 CRC와 각 파일 SHA256, 매니페스트 항목을 검사합니다.

## 해석 규칙

1. **실제 생산, 실제 투입, 출하·판매, 생산능력, 재고, 장비 대수, 금액을 구분합니다.** 매출이나 생산금액을 장비 대수·실물 생산량으로 역산하지 않았습니다.
2. `measurement_family`는 검색 분류입니다. 같은 분류에 속해도 회사·제품·지름·공정·범위·시간 기준이 같다는 뜻이 아닙니다. 시스템·챔버·플랫폼·모듈, 단일 공장·모회사·연결그룹을 분리하십시오.
3. LG Display의 연중 최대 관측 월간 기판 투입은 `physical_input`입니다. 설계능력이나 연간 평균, 완성 패널 출하로 해석하지 않습니다.
4. OSAT 패키징과 테스트에는 같은 다이가 중복될 수 있습니다. 각 공정 물량을 더해 고유 칩 생산량으로 부르지 않습니다. Powertech IC/모듈은 천 개, 웨이퍼레벨은 천 장으로 중국어 원문을 확인했습니다. Huatian WLP는 원문 단위가 장에서 만 장으로 바뀝니다.
5. `value`는 점수치, `value_min`/`value_max`는 한계·범위, `value_text`는 원문 정성 표현입니다. 하한·상한에서 중간값을 만들거나 빈값을 0으로 채우지 않습니다.
6. `status`, `is_forecast`, `estimate_phase`, `record_kind`를 함께 확인합니다. 추정·전망·발표 계획, 샘플·인증·양산, 장비 주문·출하·설치·매출 인식을 구분합니다.
7. 회계연도와 달력연도, 52주/53주, 원통화, 모회사/연결범위, 재작성 버전을 보존합니다. 동일 회사·기간의 여러 원문 버전은 중복 오류가 아닐 수 있습니다. 예: JCET 2021 첨단 패키징 원기준과 2022 공시의 소급 재작성 값.
8. 과거시점 학습에는 **검증된 원문 공개일** `available_date_verified`를 사용합니다. 회계기간 종료일이나 열람일로 대체하지 않습니다. 공개일 미확인 기록은 null을 유지하며 시점 학습에서 제외하거나 추가 조사하십시오.

## 재현

Python 3, pandas, xlsxwriter, openpyxl, Playwright, lxml 및 시스템 Chromium, Poppler(`pdfinfo`, `pdftotext`, `pdftoppm`)가 필요합니다. Linux 한국어 PDF에는 Noto CJK 글꼴을 권장합니다.

```bash
python scripts/build_supply_chain.py
python scripts/build_supply_chain_report.py
python scripts/validate_and_package.py
```

차트 생성 코드는 `scripts/build_supply_chain_charts.py` 또는 배포된 차트 작성 스크립트가 있으면 사용하고, 원단위 SVG 여섯 개를 `charts/{materials,components_substrates,frontend_equipment,subsystems,displays,backend_osat}.svg`에 둡니다. HTML은 차트를 base64로 포함하므로 네트워크 없이 열립니다. 브라우저 검증은 `set_content`로 로드하며 외부 원문 방문을 자동 수행하지 않습니다. 환경에 따라 Chromium 실행에 네트워크 샌드박스 권한이 필요할 수 있습니다.

검증 단계는 `--exports-only`, `--report-only`, `--package-only`로 개별 재실행할 수 있습니다. 독립 QA 파일이 존재하면 `all_checks_passed: true`일 때 최종 ZIP을 생성합니다. 원문 재검토와 구조·직렬화·UI 검증의 범위를 각 검증 JSON에서 구분합니다. 환경 재생성 전에 수행한 원문 대조를 이번 환경에서 새로 수행했다고 표시하지 않습니다.

## SQLite 예시

```sql
SELECT company_name, metric_ko, period, value, value_min, value_max,
       unit, product_or_technology, scope, source_url
FROM expanded_only
WHERE industry_stage = 'displays' AND is_forecast = 0;

SELECT company_name, metric, period, value, unit, available_date_verified
FROM verified_historical_numeric
WHERE available_date_verified <= '2024-12-31'
  AND measurement_family IN ('physical_output', 'physical_shipments');
```

`verified_historical_numeric`는 공개일과 수치·전망 상태를 기반으로 한 편의 뷰이며 회사 간 비교 가능성이나 원문 내용 전체의 정확성을 자동 보증하지 않습니다. 재배포·모델 학습에 사용할 때는 각 원문과 데이터 제공자의 이용조건을 확인하십시오.


## VLSI Market 공개 API

사이트의 관측 데이터 API는 `https://market.vlsi.kr/api/production-history`입니다. 공급망 회사 디렉터리용 `/api/supply-chain`과는 반환 구조가 다르므로 아래 관측 API를 사용하십시오.

```text
/api/production-history?view=meta
/api/production-history?release=latest&stage=displays&family=physical_shipments&forecast=exclude&limit=200
/api/production-history?company=BESI&forecast=exclude&format=jsonl
/api/production-history?available_by=2024-12-31&forecast=exclude&format=csv
/api/production-history?view=gaps&release=latest&stage=materials
```

- `view`: observations(기본), sources, companies, metrics, coverage, gaps, meta.
- `release`: latest=이번 v3 추가만, all=전체, expanded=v1 이후 추가 전체(v2+v3), baseline=최초 웨이퍼 v1. `baseline`은 v2 전체1,663행을 뜻하지 않습니다.
- `company`, `category`, `metric`, `status`, `kind`, `stage`, `family`: `view=meta`가 반환하는 필터 ID를 사용합니다. `q`는 통합검색입니다.
- `forecast`: all(기본), exclude(전망 제외), only(전망만). `available_by=YYYY-MM-DD`는 검증된 원문 공개일 기준이며 공개일 null인 자료를 포함하지 않습니다.
- JSON은 `limit` 기본40/최대200과 `offset`으로 페이지를 이동합니다. `filteredCount`는 전체 조건 일치 수, `count`는 이번 응답 수입니다.
- `format=csv` 또는 `format=jsonl`은 필터에 일치하는 전체 자료를 반환하며 JSON 페이지 제한을 적용하지 않습니다. CSV는 원단위·경계값·출처·범위를 함께 유지합니다.
- `view=gaps`는 company, stage, q, release 필터를 사용하며 관측값 전용 필터를 함께 보내면400오류를 반환합니다. 알 수 없는 필터 이름/ID와 중복 파라미터도400오류입니다.
- 원문 날짜 필터나 `verified_historical_numeric` 뷰는 지표의 경제적 비교 가능성을 보증하지 않습니다. 제품·공정·단위·스냅샷·원문 버전을 함께 확인해야 합니다.