56a6e2da93
- 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 문서 지도 갱신
113 lines
7.1 KiB
Markdown
113 lines
7.1 KiB
Markdown
# DMF Crawler — 문서 정본(SSOT)
|
|
|
|
> 이 디렉터리는 프로젝트의 **단일 정본(Single Source of Truth)** 이다.
|
|
> 조사·결정·설계는 전부 여기에 기록한다. 코드는 문서를 따르고, 문서에 없는 결정은 없는 결정이다.
|
|
|
|
**프로젝트 루트**: `D:\workspace\DMF_Crawler`
|
|
**문서 시작일**: 2026-09-02
|
|
|
|
---
|
|
|
|
## 문서 규칙
|
|
|
|
1. **정보를 흘리지 않는다.** 조사 중 확인한 URL·저장소·논문·플래그·수치는 요약하며 버리지 말고 문서에 남긴다. 부록의 출처 표가 그 장치다.
|
|
2. **한 사실은 한 문서에만 산다.** 다른 문서는 링크로 참조하고 복사하지 않는다. 중복은 곧 불일치가 된다.
|
|
3. **지어내지 않는다.** 확인하지 못한 것은 `⚠️ 미검증` 표시를 달고 남긴다. 삭제하지 않는다.
|
|
4. **미해결 항목은 문서 끝 체크박스로 관리한다.** 해결되면 본문으로 옮기고 체크박스를 지운다.
|
|
5. **코드는 완결적으로 쓴다.** 생략 부호(`...`)를 쓰지 않는다. 복붙하면 동작해야 한다.
|
|
6. **결정에는 근거를 붙인다.** 아키텍처 결정은 `design/01-architecture.md` 의 ADR 표에 기록한다.
|
|
|
|
---
|
|
|
|
## 문서 지도
|
|
|
|
### 최상위
|
|
|
|
| 문서 | 무엇을 결정하는가 |
|
|
|---|---|
|
|
| **`00-REQUIREMENTS.md`** | **요구사항 정본.** R1~R8, N1~N8, 비목표, 온보딩=복구 통합 원칙. **여기서 시작한다.** |
|
|
| `00-PROJECT-OVERVIEW.md` | 프로젝트 개요, 성공 기준, 로드맵, 리스크, 용어집 |
|
|
|
|
### `research/` — 조사 정본
|
|
|
|
| 문서 | 무엇을 결정하는가 |
|
|
|---|---|
|
|
| `01-dmf-domain-and-sources.md` | 무엇을 크롤링하는가. DMF 제도, 등록번호 체계, 소스 URL·파라미터·컬럼, 수집 대상 필드 확정안 |
|
|
| `02-benchmark-github-projects.md` | 어떤 구조를 베낄 것인가. 유사 프로젝트 벤치마킹, 채택/기각 결정, 모듈 경계 |
|
|
| `03-crawling-theory-and-papers.md` | 어떻게 크롤링할 것인가. 크롤러 이론, 증분·변경 감지, 추출 기법, 크롤링 정책 확정안 |
|
|
| `04-anti-bot-and-legal.md` | 차단당하지 않고 합법적으로 수집하는 법. 봇 탐지 원리, 정중한 크롤러 규칙, 판례·법적 리스크 |
|
|
| `05-ai-cli-headless-comparison.md` | AI CLI 대안 비교와 headless 파이프라인 설계 원칙 (참고용) |
|
|
| **`05a-agy-cli-ssot.md`** | **채택 CLI `agy` 의 모든 것.** 설치·인증·headless·플래그·권한·함정. 공식 문서 + 로컬 실측 |
|
|
| `06-xlsx-linking-and-formatting.md` | xlsx 시트 연동·서식 기법의 원리와 레시피 |
|
|
| `07-pharma-excel-dashboard-design.md` | 의약 정보를 한눈에 보게 만드는 대시보드 설계 원칙과 시트 구성안 |
|
|
| `08-windows-scheduling-and-resilience.md` | Windows 스케줄링·재부팅 내성·알림 기법 조사 정본 |
|
|
| `09-agy-bootstrap-and-provisioning.md` | `agy` 자동 설치·인증 부트스트랩·프롬프트 창 설계 |
|
|
| `10-agy-agent-integration-patterns.md` | `agy` 를 파이프라인에 넣는 유스케이스별 통합 패턴 |
|
|
| **`11-tdd-red-and-design-audit-theory.md`** | **TDD·E2E RED·디자인 감사 이론 근거 SSOT. Kent Beck/GDS/Google/Playwright/WCAG/NN/g/Vercel/LLM-TDD 논문 기반** |
|
|
|
|
### `design/` — 설계 확정
|
|
|
|
| 문서 | 무엇을 결정하는가 |
|
|
|---|---|
|
|
| **`00-DATA-SOURCE-DECISION.md`** | **어디서 데이터를 받는가.** 공식 Open API 채택 결정, API 완전 명세, 변경 탐지 판정 규칙 |
|
|
| **`00b-baseline-data-analysis.md`** | **기존 프로토타입 산출물 전수 분석.** 9,084건 실측, 등록번호 유일성, 발급일자의 의미, 데이터 품질 문제, 확정 결정 D1~D12 |
|
|
| `01-architecture.md` | **전체 구조 확정안.** ADR, 디렉터리 트리, 모듈 계약, 데이터 흐름, CLI, 설정, 실패 대응표, 의존성, 구현 순서 |
|
|
| `02-data-model.md` | 데이터 모델, SQLite 스키마, 등록번호 파싱, 변경 탐지 알고리즘, 품질 검증 |
|
|
| `03-xlsx-report-spec.md` | 리포트 완전 명세. 시트별 컬럼·서식·수식·링크, 대시보드 셀 레이아웃, 디자인 토큰, 생성 코드 |
|
|
| `04-onboarding-wizard.md` | 더블클릭 온보딩 마법사. 전제 조건 검사, API 키 입력, agy 설치·로그인, 화면 설계, 복구 모드 |
|
|
| **`07-tdd-red-system.md`** | **프로젝트 TDD/RED 운영 체계 SSOT. No RED No Code, E2E, xlsx/GUI 디자인 감사 RED, 통폐합·삭제 원칙** |
|
|
|
|
### `ops/` — 운영
|
|
|
|
| 문서 | 무엇을 결정하는가 |
|
|
|---|---|
|
|
| `01-scheduling-and-resilience.md` | 06:00 배치 등록, 재부팅 내성, 워치독, 로그, 일상 운영 절차, 신규 PC 설치 절차 |
|
|
| `02-failure-alerting.md` | 장애 알림 채널·등급·문구·버튼 액션, `agy` 재로그인 유도, 에스컬레이션 |
|
|
| `03-api-usage-policy.md` | 공공데이터 API 이용 제약, 트래픽 계산, 인증키 만료 대응, 오류 코드 대응표 |
|
|
| `04-official-data-request-channels.md` | 공식 데이터 제공 요청·승인 절차. 제공신청, 정보공개청구, 식약처 문의, 요청 문구 초안 |
|
|
| **`05-release-and-versioning.md`** | **버전·git 태그·릴리스 절차 정본.** SemVer 규칙, `dist/`와 `src/`의 구분, 최종 사용자 zip 배포, 원격 저장소(`git.chanpaca.net`) 규칙 |
|
|
|
|
---
|
|
|
|
## 저장소 최상위 문서
|
|
|
|
`docs/` 밖, 저장소 루트에 있는 문서들이다. 역할이 다르므로 위 표에 넣지 않는다.
|
|
|
|
| 문서 | 무엇을 결정하는가 |
|
|
|---|---|
|
|
| `README.md` | 사용자(비개발자) 대상 설치·실행·장애 대응 가이드 |
|
|
| `AGENTS.md` | AI coding agent 작업 지침 진입점(TDD/RED 원칙) |
|
|
| `CHANGELOG.md` | 버전별 사용자 체감 변경 이력 |
|
|
| `LICENSE` | 라이선스 고지 |
|
|
|
|
---
|
|
|
|
## 읽는 순서
|
|
|
|
**처음 오는 사람**: `00-REQUIREMENTS.md` → `design/00-DATA-SOURCE-DECISION.md` → `design/01-architecture.md`
|
|
|
|
**구현하는 사람**: `design/07-tdd-red-system.md` → `design/01-architecture.md` → `design/00b-baseline-data-analysis.md` → `design/02-data-model.md` → `design/03-xlsx-report-spec.md` → `research/05a-agy-cli-ssot.md`
|
|
|
|
**운영하는 사람**: `ops/01-scheduling-and-resilience.md` → `ops/02-failure-alerting.md`
|
|
|
|
**법적 검토가 필요한 사람**: `research/04-anti-bot-and-legal.md`
|
|
|
|
---
|
|
|
|
## 조사 원본 보관
|
|
|
|
정제 전 웹 리서치 원본(WebFetch 428건, WebSearch 224건의 결과)은 세션 스크래치패드에 있다.
|
|
정제된 내용은 위 `research/` 문서들에 들어갔으므로, 원본은 출처 추적이 필요할 때만 참조한다.
|
|
|
|
```
|
|
C:\Users\encep\AppData\Local\Temp\claude\D--workspace-DMF-Crawler\<session>\scratchpad\raw\agent-*.md
|
|
```
|
|
|
|
> ⚠️ 스크래치패드는 임시 디렉터리다. 장기 보존이 필요하면 `docs/research/_raw/` 로 옮긴다.
|
|
|
|
---
|
|
|
|
## 보안 주의
|
|
|
|
- `agy` 의 OAuth 토큰은 `~/.gemini/antigravity-cli/antigravity-oauth-token` 에 **평문**으로 있다. 이 파일 경로는 문서화하되 **내용은 절대 문서·로그·저장소에 남기지 않는다.**
|
|
- 공공데이터포털 API 키, 웹훅 URL 등 비밀은 `.env` 에 두고 `.gitignore` 로 제외한다. 문서에는 키 이름만 적는다.
|