chore: 저장소 구조 정리 및 문서화, 첫 커밋

- src/dist 산출물 분리 원칙 정리(.gitignore, .gitattributes)
- 루트 및 주요 폴더(config/scripts/prompts/tests/src, 런타임 폴더 5종)에
  안내용 README.md 추가
- CHANGELOG.md, LICENSE, docs/ops/05-release-and-versioning.md 추가
- docs/README.md 문서 지도 갱신

docs/00-REQUIREMENTS.md

@@ -0,0 +1,247 @@
+# DMF Crawler — 요구사항 정본
+
+> **이 문서의 역할**: 사용자가 제시한 모든 요구를 한 곳에 모은 **요구사항 SSOT**. 설계·구현은 이 문서를 만족해야 하고, 이 문서에 없는 기능은 만들지 않는다. 새 요구가 나오면 여기에 먼저 추가한다.
+
+**최종 갱신**: 2026-09-03
+**요구 출처**: 대화 세션 (2026-09-02~2026-09-03)
+
+---
+
+## 0. 한눈에 보기
+
+- 매일 **06:00** 자동 실행. **재부팅해도 살아남는다.**
+- 데이터는 인증키가 있을 때 **식약처 공식 Open API** 로 받는다. 인증키가 없거나 사용자가 `browser` 모드를 고르면 **AGY가 headful/visible Chrome 으로 의약품안전나라 xlsx 를 다운로드**한다.
+- **공공데이터포털 인증키는 선택**이다. 키가 없어도 기존 자료 리포트 생성·온보딩·스케줄 설치는 막지 않는다. 키가 없으면 최신 수집은 AGY headful 브라우저 경로를 먼저 시도하고, 실패하면 마지막 성공 자료로 리포트를 만든다.
+- 결과는 **탭별로 연동된, 디자인이 예쁜 xlsx**. 의약 정보를 **한눈에** 볼 수 있어야 한다.
+- `agy` 사용은 두 갈래다. **수집용 AGY는 headful/visible Chrome** 을 조작하고, **AI 요약은 선택 기능**으로 사용자가 켠 경우에만 headless/non-interactive 로 호출한다. **Google 로그인은 선택**이며 최초 실행/기본 온보딩에서 먼저 요구하지 않는다.
+- **쓰는 사람은 개발자가 아니다.** 더블클릭 한 번으로 설치·설정이 끝나야 한다.
+- **문제가 생기면 창이 떠서 무엇이 왜 안 됐고 어떻게 고치는지 알려준다.** 조용히 실패하지 않는다.
+- 온보딩 마법사와 오류 복구 창은 **같은 컴포넌트**다.
+- **이 프로젝트는 스크래치가 아니다.** 이미 API 로 수집해 xlsx 를 만드는 프로토타입이 돌고 있었고(`DMF_현황.xlsx`, 9,084건), 이 작업은 그것의 개선이다. 기준선 분석은 [`design/00b-baseline-data-analysis.md`](./design/00b-baseline-data-analysis.md).
+
+---
+
+## 1. 기능 요구사항
+
+### R1. 데이터 수집
+
+| ID | 요구 | 완료 판정 기준 | 상태 |
+|---|---|---|---|
+| R1.1 | 식약처 DMF(원료의약품 등록) 데이터를 매일 수집한다 | 매일 전량 스냅샷이 저장소에 적재됨 | 설계 완료 |
+| R1.2 | 인증키가 있으면 공식 Open API 를 우선 소스로 쓴다 | API 키가 있으면 API 전량 수집이 동작함 | ✅ 확정 |
+| R1.3 | 인증키가 없거나 사용자가 `browser` 모드를 고르면 AGY가 **headful/visible Chrome** 으로 의약품안전나라 xlsx 를 다운로드한다 | `source.mode=auto` + 키 없음 또는 `source.mode=browser` 에서 AGY headful 수집 경로가 실행됨. 2026-09-03 수동 smoke 9,816건 성공 | ✅ 구현+수동 smoke |
+| R1.4 | headful 수집은 차단 우회·스텔스·curl/headless 직접 호출을 쓰지 않는다 | AGY 프롬프트/호출 계약에 visible Chrome, chrome-devtools MCP, curl/headless 금지가 들어감 | ✅ 구현 |
+| R1.5 | 수집 완결성을 검증한다 | API 는 `totalCount`, headful xlsx 는 다운로드 완료·zip/XML·행 수 검증 통과 후에만 diff 수행 | ✅ 구현 |
+
+> **주의**: 기존 설계는 공식 API 단일 소스였으나, 사용자 요구에 따라 AGY headful 브라우저 xlsx 수집 경로를 복구한다. 봇 차단은 실측상 강하지 않았지만, headful 방식이 차단 가능성을 0으로 보장하지는 않는다. 차단 우회·스텔스 기법은 구현하지 않는다.
+
+### R2. 변경 탐지
+
+| ID | 요구 | 완료 판정 기준 |
+|---|---|---|
+| R2.1 | 전일 대비 **신규 / 변경 / 취하** 를 탐지한다 | 세 유형이 각각 별도 목록으로 산출됨 |
+| R2.2 | 불완전 수집 시 **취하 오판을 하지 않는다** | 안전장치 5개 조건을 모두 통과해야 diff 수행 |
+| R2.3 | 성분명·업체명 표기 흔들림을 정규화해 동일 레코드를 오탐하지 않는다 | 정규화 규칙 통과 후 비교 |
+
+### R3. 리포트 (xlsx)
+
+| ID | 요구 | 완료 판정 기준 |
+|---|---|---|
+| R3.1 | **탭(시트)별로 서로 연동된** 워크북을 생성한다 | 목차↔각 시트 하이퍼링크 양방향 동작 |
+| R3.2 | **디자인이 예쁘다** | 색 팔레트·폰트·여백이 문서 토큰과 일치, 기본 서식 잔재 없음 |
+| R3.3 | 의약 정보를 **한눈에** 파악할 수 있다 | 대시보드 시트에서 5초 안에 오늘의 상황 파악 가능 |
+| R3.4 | 시각화가 들어간다 | KPI 타일, 추이 차트, 스파크라인, 조건부 서식 |
+| R3.5 | 사용자가 파일을 열어둔 상태에서도 배치가 실패하지 않는다 | 원자적 교체 또는 대체 파일명 폴백 |
+
+### R4. AI 통합 (`agy`)
+
+| ID | 요구 | 완료 판정 기준 |
+|---|---|---|
+| R4.1 | **Google Antigravity CLI (`agy`)** 를 쓴다. 다른 CLI 가 아니다 | 수집용/요약용 모두 `agy -p --output-format json` 호출 |
+| R4.2 | 수집용 `agy` 는 headful/visible Chrome 을 조작한다 | `source.mode=browser` 또는 auto+키 없음에서 chrome-devtools MCP 기반 프롬프트 사용. 권한은 `mcp(chrome-devtools/*)`, `execute_url(nedrug.mfds.go.kr)`만 허용 |
+| R4.3 | AI 요약을 켠 경우 headless / non-interactive 로 동작한다 | 사용자가 AI 요약을 활성화한 뒤 사람 개입 없이 배치에서 실행 |
+| R4.4 | `agy` 가 없으면 **사용자에게 먼저 물어본 뒤** 부트스트랩·설치한다 | 수집용 browser 모드 또는 AI 요약 사용 선택 시 설치 진행, 거절/나중에는 기존 자료 리포트 생성 계속 |
+| R4.5 | AI/AGY 가 실패해도 **리포트는 생성된다** | `agy` 강제 실패 상태에서도 마지막 성공 자료 또는 API 자료로 xlsx 산출 |
+| R4.6 | AI 산출물은 실무자용 한국어 요약·해석이다 | 변경 브리핑, 이상 해석, 정규화 보조 |
+
+### R5. 스케줄링과 내구성
+
+| ID | 요구 | 완료 판정 기준 |
+|---|---|---|
+| R5.1 | 매일 **06:00** 에 실행된다 | 7일 연속 06:00±5분 실행 기록 |
+| R5.2 | **PC 를 재부팅해도** 스케줄이 유지되고 자동 실행된다 | 재부팅 후 다음 06:00 정상 실행 |
+| R5.3 | 실행 시각에 PC 가 꺼져 있었다면 켜진 뒤 **가능한 한 빨리 실행**한다 | 놓친 작업 실행 옵션 활성 |
+| R5.4 | 배치가 죽어도 스스로 재시도한다 | 실패 시 재시작 정책 동작 |
+| R5.5 | 중복 실행되지 않는다 | 동시 기동 시 후발 인스턴스 종료 |
+| R5.6 | 워치독이 배치 미실행을 감지한다 | heartbeat 미갱신 시 경보 |
+
+### R6. 온보딩 — 비개발자용 설치·설정
+
+> **전제**: 이 시스템을 쓰는 사람은 개발자가 아니다. API 키가 뭔지, 환경변수가 뭔지 모른다.
+
+| ID | 요구 | 완료 판정 기준 |
+|---|---|---|
+| R6.1 | **더블클릭 한 번**으로 실행되는 파일이 있다 | 탐색기에서 더블클릭 시 GUI 기동 |
+| R6.2 | 실행하면 **Windows 다이얼로그(GUI)** 가 뜬다. 콘솔 명령을 치게 하지 않는다 | 검은 콘솔 창이 보이지 않음 |
+| R6.3 | **API 키가 없으면 다이얼로그에서 입력**받고 안전하게 저장한다 | 키 미설정 상태에서 입력→저장→검증 완료 |
+| R6.4 | API 키 **발급 페이지로 가는 버튼**이 있다 | 클릭 시 브라우저로 발급 페이지 열림 |
+| R6.5 | 입력한 키를 **즉시 실제 API 호출로 검증**한다 | 잘못된 키는 저장되지 않고 안내 표시 |
+| R6.6 | **AI 요약 사용 여부를 먼저 묻고**, 사용자가 켠 경우에만 `agy` 설치를 진행한다 (진행률 표시) | Google 로그인을 먼저 요구하지 않는다. 거절/나중에는 WARN 없이 리포트 경로 진행 |
+| R6.7 | **Google 로그인은 선택**이다. AI 요약 또는 headful 브라우저 수집을 사용할 때만 로그인/AGY 준비를 유도한다 | 공식 API 키가 있거나 기존 성공 자료만으로 리포트 생성할 때는 Google 로그인 없이 진행 가능 |
+| R6.8 | 준비가 끝나면 **06:00 작업 등록**까지 제안한다 | 버튼 클릭으로 스케줄 등록 완료 |
+| R6.9 | 이미 다 준비된 상태면 **간단한 화면 + "지금 실행" 버튼** | 재실행 시 체크 통과 화면 표시 |
+
+### R7. 오류 알림과 복구 안내
+
+> **핵심**: 온보딩이 끝난 뒤에도 문제는 생긴다. OAuth 로그인이 풀리고, API 키가 만료되고, 네트워크가 끊긴다. 그때 **강제로 창이 떠서** 사용자에게 알려야 한다.
+
+| ID | 요구 | 완료 판정 기준 |
+|---|---|---|
+| R7.1 | 배치가 실패하면 **Windows 알림**이 뜬다 | 실패 유발 시 알림 표시 확인 |
+| R7.2 | 심각한 오류는 **강제로 창(모달 다이얼로그)** 이 뜬다. 토스트만으로 끝내지 않는다 | OAuth 만료·API 키 무효 상황에서 창 표시 |
+| R7.3 | 알림은 문제·원인·해결·다음 행동을 담되, 화면 문구는 자연스러운 한국어로 쓴다 | `무엇:/왜:/어떻게:/다음:` 같은 AI식 라벨 없이도 사용자가 지금 할 일을 이해함 |
+| R7.4 | **`agy` OAuth 로그인이 풀린 경우**를 감지하고 재로그인을 유도한다 | 토큰 무효화 후 실행 시 로그인 창 유도 |
+| R7.5 | **API 키가 유효하지 않게 된 경우**를 감지하고 재입력을 유도한다 | 잘못된 키로 실행 시 입력 창 유도 |
+| R7.6 | 알림 창에서 **바로 고칠 수 있다**. 별도 문서를 찾게 하지 않는다 | 창의 버튼으로 복구 완료 가능 |
+| R7.7 | **막다른 골목이 없다.** 모든 오류 화면은 다음 행동을 제시한다 | 모든 오류 경로에 액션 버튼 존재 |
+| R7.8 | 알림이 폭주하지 않는다 | 동일 오류 반복 시 쿨다운 적용 |
+| R7.9 | 서비스/배치가 내려가면 그 사실 자체를 알린다 | 워치독이 미실행 감지 시 경보 |
+
+### R8. 운영 편의
+
+| ID | 요구 | 완료 판정 기준 |
+|---|---|---|
+| R8.1 | 로그가 남는다 (실행 ID, 시작·종료, 건수, 소요, 오류, 토큰 사용량) | 매 실행 로그 파일 생성 |
+| R8.2 | 수동 재실행이 쉽다 | GUI 버튼 또는 단일 명령 |
+| R8.3 | 특정 날짜 백필이 가능하다 | 과거 데이터 재처리 명령 동작 |
+| R8.4 | 새 PC 에 설치하는 절차가 문서화돼 있다 | 문서만 보고 설치 완료 가능 |
+
+---
+
+## 2. 비기능 요구사항
+
+| ID | 요구 | 기준 |
+|---|---|---|
+| N1 | 법적 안전성 | robots.txt 준수, 공식 API 이용약관 준수, 출처 표시 |
+| N2 | 무인 운영 | 사람 개입 없이 30일 연속 동작 |
+| N3 | 실패 가시성 | 실패를 사용자가 **24시간 안에** 인지 |
+| N4 | 복구 용이성 | 대부분의 장애를 **5분 안에** GUI 로 복구 |
+| N5 | 의존성 최소 | 브라우저 자동화·무거운 프레임워크 배제 |
+| N6 | 이식성 | 다른 Windows PC 로 폴더 복사 + 온보딩으로 이전 가능 |
+| N7 | 보안 | API 키·OAuth 토큰을 로그·저장소·문서에 남기지 않음 |
+| N8 | 유지보수성 | 6개월 뒤 본인이 읽고 고칠 수 있는 구조 |
+
+---
+
+## 3. 비목표 (이번에 하지 않는 것)
+
+| 항목 | 이유 |
+|---|---|
+| 웹 대시보드 | xlsx 로 충분. 요구에 없음 |
+| 다중 사용자·권한 관리 | 1인 운영 도구 |
+| 실시간 모니터링 | 일 1회 배치로 충분 |
+| 해외 소스(FDA/EDQM/PMDA) 연동 | 확장 지점으로만 기록. 1차 범위 밖 |
+| HTML 크롤링·차단 우회 | 공식 API 로 대체됨 (`design/00-DATA-SOURCE-DECISION.md`) |
+| 클라우드 배포 | 로컬 PC 운영이 요구사항 |
+| 모바일 알림 | Windows 알림으로 충분. 웹훅은 선택 확장 |
+
+---
+
+## 4. 온보딩 = 복구, 하나의 컴포넌트
+
+**설계 원칙**: 온보딩 마법사(R6)와 오류 복구 창(R7)은 **분리된 두 프로그램이 아니라 같은 컴포넌트의 두 진입 모드**다.
+
+| 진입 모드 | 트리거 | 화면 상태 |
+|---|---|---|
+| **최초 설정** | 사용자가 `설정.bat` 더블클릭, 설정 파일 없음 | 전체 체크리스트, 미충족 항목 다수 |
+| **재설정** | 사용자가 언제든 더블클릭 | 전체 체크리스트, 대부분 통과 |
+| **복구** | 배치 실패 → 알림 클릭 또는 자동 기동 | **실패한 항목만 강조된** 체크리스트 + 원인 설명 |
+| **점검** | 워치독이 이상 감지 | 진단 결과 화면 |
+
+이 통합이 주는 이점:
+- 사용자는 **화면 하나만 기억하면 된다.**
+- 진단 로직이 한 곳에 있어 온보딩과 복구가 어긋나지 않는다.
+- 새 전제 조건이 생기면 한 곳만 고치면 온보딩과 복구에 동시 반영된다.
+
+### 복구 시나리오별 동작
+
+| 실패 | 감지 방법 | 알림 등급 | 창을 강제로 띄우는가 | 창에서 할 수 있는 것 |
+|---|---|---|---|---|
+| `agy` OAuth 로그인 만료 | AI 요약을 켠 상태에서 `agy -p` 응답의 `status`/`error`, 종료 코드 | WARN | 아니오 | AI 요약 끄기, 나중에 로그인, 리포트는 계속 생성 |
+| API 키 무효·만료 | API `resultCode` 오류 분기 | CRITICAL | **예** | 키 재입력, 발급 페이지 열기 |
+| API 키 미설정 | 저장소에 키 없음 | CRITICAL | **예** | 키 입력 |
+| `agy` 미설치·삭제됨 | 바이너리 경로 확인 실패 | CRITICAL | **예** | 재설치 버튼 |
+| 일일 트래픽 초과 | API 오류 코드 | WARN | 아니오 (토스트) | 내일 재시도 안내 |
+| `agy` 쿼터 소진 | `agy` 오류 응답 | WARN | 아니오 | AI 없이 리포트 생성됨 안내 |
+| 네트워크 단절 | 연결 실패 | WARN | 아니오 | 재시도 안내 |
+| xlsx 파일 잠김 | 파일 쓰기 실패 | WARN | 아니오 | 대체 파일 경로 안내 |
+| 수집 완결성 실패 | 건수 불일치 | WARN | 아니오 | diff 미수행 안내 |
+| 배치 미실행 (워치독) | heartbeat 미갱신 | CRITICAL | **예** | 지금 실행, 작업 상태 확인 |
+| 연속 3일 실패 | 실행 로그 집계 | CRITICAL | **예** | 진단 결과 표시 |
+| 작업 스케줄러 등록 소실 | 작업 조회 실패 | CRITICAL | **예** | 재등록 버튼 |
+
+> **강제 창 표시의 제약**: 배치가 사용자 세션에서 실행되면 창을 띄울 수 있다. 세션이 잠겨 있거나 로그오프 상태면 창이 보이지 않으므로, **창 표시 + 지속 알림 + 다음 로그온 시 재표시**를 함께 건다. 구현은 `ops/02-failure-alerting.md`.
+
+---
+
+## 5. 요구사항 추적표
+
+각 요구가 어느 문서에서 설계되는지.
+
+| 요구 | 설계 문서 |
+|---|---|
+| R1 데이터 수집 | `design/00-DATA-SOURCE-DECISION.md`, `design/00b-baseline-data-analysis.md`, `design/01-architecture.md` |
+| R2 변경 탐지 | `design/02-data-model.md`, `design/00b-baseline-data-analysis.md` §6 |
+| R3 리포트 | `design/03-xlsx-report-spec.md`, `research/06`, `research/07` |
+| R4 AI 통합 | `research/05a-agy-cli-ssot.md`, `research/09`, `research/10` |
+| R5 스케줄링 | `ops/01-scheduling-and-resilience.md`, `research/08` |
+| R6 온보딩 | `design/04-onboarding-wizard.md` |
+| R7 오류 알림·복구 | `ops/02-failure-alerting.md`, `design/04-onboarding-wizard.md` |
+| R8 운영 편의 | `ops/01-scheduling-and-resilience.md` |
+| N1 법적 안전성 | `research/04-anti-bot-and-legal.md`, `ops/03-api-usage-policy.md`, `ops/04-official-data-request-channels.md` |
+| N2 무인 운영 | `ops/01-scheduling-and-resilience.md`, `ops/02-failure-alerting.md` |
+| N3 실패 가시성 | `ops/02-failure-alerting.md` |
+| N4 복구 용이성 | `design/04-onboarding-wizard.md` (온보딩=복구 통합, 4절) |
+| N5 의존성 최소 | `design/01-architecture.md` ADR |
+| N6 이식성 | `design/04-onboarding-wizard.md`, `ops/01-scheduling-and-resilience.md` |
+| N7 보안 | `design/04-onboarding-wizard.md` (시크릿 저장), `research/05a-agy-cli-ssot.md` §4.2 |
+| N8 유지보수성 | `design/01-architecture.md` ADR |
+
+---
+
+## 6. 요구 변경 이력
+
+| 일자 | 변경 | 사유 |
+|---|---|---|
+| 2026-09-02 | 초기 요구 수립 (R1~R5) | 프로젝트 시작 |
+| 2026-09-02 | AI CLI 를 `agy` 로 확정, 자동 부트스트랩 요구 추가 (R4.1, R4.3) | 사용자 지정 |
+| 2026-09-02 | 데이터 소스를 크롤링 → 공식 Open API 로 전환 (R1.2, R1.3) | `robots.txt` 전면 금지 확인 + 공식 API 발견 |
+| 2026-09-02 | 비개발자용 온보딩 마법사 요구 추가 (R6 전체) | 사용자가 API 키 개념을 모른다는 전제 |
+| 2026-09-02 | 오류 시 강제 창 표시 요구 추가 (R7.2, R7.4, R7.5) | 온보딩 후 발생하는 장애도 안내 필요 |
+| 2026-09-02 | 온보딩과 복구를 단일 컴포넌트로 통합하는 원칙 수립 (4절) | 사용자 경험 일관성 |
+| 2026-09-02 | **기존 프로토타입 존재 확인.** 스크래치 → 개선 작업으로 성격 변경 | 사용자가 `DMF_현황.xlsx` 제공 |
+| 2026-09-02 | R2.1 변경 탐지가 API 7필드로 가능함을 실측 확인 | `발급일자` 가 최종 갱신일로 이동, 웹-API 756건 차이 |
+| 2026-09-02 | N2~N8 추적표 행 추가 (누락 보정) | 문서 감사에서 지적 |
+
+---
+
+## 부록. 미확정 / 사용자 확인 필요
+
+**기존 프로토타입 관련 (우선순위 높음)**
+
+- [ ] `DMF_현황.xlsx` 를 만든 **수집 스크립트가 어디에 있는가?** 있다면 재사용·개선의 출발점이 된다.
+- [ ] **공식 API 최신 수집을 쓸 것인가?** 공공데이터포털 인증키는 선택이다. 키가 없어도 기존 자료 리포트 생성은 계속되며, 최신 공식 API 수집이 필요할 때만 `serviceKey` 를 등록한다.
+- [ ] 이 파일이 카카오톡으로 전달된 경위 — 본인이 만든 것인가, 다른 사람이 만든 것인가.
+- [ ] `신규` 시트의 기대 동작이 "당일 신규만"인가 "최근 N일"인가.
+- [ ] `갱신이력` 시트에 추가로 기록하고 싶은 항목 (변경건수, 취하건수, 소요시간, 오류).
+
+**운영 관련**
+
+- [ ] 리포트를 받아보는 사람이 몇 명인가? 파일 공유 방식은? (공유 폴더, 이메일, 수동)
+- [ ] 워치리스트(관심 성분·업체) 가 필요한가? 있다면 초기 목록은?
+- [ ] 리포트 보관 기간과 위치는?
+- [ ] PC 가 밤에 꺼지는가? 절전 모드인가? (WakeToRun 설정 결정에 필요)
+- [ ] 해외 소스(FDA/EDQM/PMDA)를 언제 붙일 계획인가?
+- [ ] 이메일·메신저 알림이 추가로 필요한가?
+
+> 과거 데이터 항목은 해소됐다. 프로토타입이 이미 9,084건을 2026-09-02 기준선으로 적재해 두었으므로, 오늘부터 diff 가 바로 동작한다.