DMF_Crawler/docs/00-REQUIREMENTS.md

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.

---

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 가 바로 동작한다.