경매 일일 수집 SOURCE 스타터킷 1.0.0

이 소스는 Codex가 Chromium으로 공식 공개 경매 목록을 조회하고, 조건에 맞는 물건을 엑셀로 저장한 뒤 GPT로 일일 보고서를 작성하는 실습용입니다. 실행파일이 아닙니다. 유료 상품 이용권, API 키, 네이버/Instagram 로그인은 필요하지 않습니다.

1. 준비
Windows PC, Node.js 22 이상, 로컬 폴더를 실행할 수 있는 Codex가 필요합니다. Node 설치 후 Codex를 다시 열고 node --version을 확인합니다. Codex 사용은 본인의 구독/사용량 조건을 따릅니다. 별도 OpenAI API 키나 API 결제 연결은 없습니다.
ZIP을 C:\AuctionDaily 같은 쓰기 가능한 폴더에 풀고 Codex에서 이 폴더를 프로젝트로 엽니다. PowerShell 실행 위치도 그 폴더입니다.

2. 설치와 Chromium 연결
npm ci
npx playwright install chromium
npm run check

check가 ready:true이면 설치된 Chromium 경로와 설정을 확인한 것입니다. 실제 사이트 조회 성공은 다음 run-once에서 확인합니다. Codex는 로컬 Playwright 스크립트를 실행해 Chromium을 제어합니다. 별도 MCP 설치, 원격 디버깅 포트, 개인 Chrome 프로필 연결은 하지 않습니다. 처음 실행되는 Chromium은 이 폴더의 전용 프로필을 사용합니다.

3. 조건 설정
config.json을 수정하거나 Codex에 요청합니다. 기본은 서울특별시 강남구, 아파트, 신건, 최저매각가격 5억원 이하, 표시 면적 20~100㎡, 매일 한국시간 09:00입니다.
- region: 공식 화면에 표시되는 시·도와 시·군·구 전체 이름. 예: 서울특별시 강남구, 경기도 성남시 분당구.
- propertyType: 아파트 / 연립·다세대 / 단독·다가구 / 오피스텔 / 상가·근린생활시설 / 빌딩·업무시설 / 토지 중 한 종류.
- auctionMode: new(유찰 0회), failed(유찰 1회 이상), all(둘 다).
- minPriceKrw, maxPriceKrw: 최저매각가격의 원 단위 숫자. 예: 5억원은 500000000. null이면 해당 하한/상한을 두지 않습니다.
- minAreaM2, maxAreaM2: 법원 표시 면적의 ㎡. 토지는 토지 면적, 건물은 표시된 건물 면적입니다. 전용·연면적을 임의로 동일시하지 않습니다.
- time: 예약에 사용할 한국시간 HH:mm. 이 값만 바꿔서는 예약이 생성되거나 변경되지 않습니다. Codex 예약도 함께 수정합니다.
- maxPages: 1~10. 공식 검색 화면의 조회 범위 안에서 확인할 최대 페이지입니다. 일부만 확인했다면 부분 수집으로 남습니다.
- headless: false이면 Chromium 창이 보입니다. 처음 확인할 때는 false를 유지합니다.

4. 한 번 실행
npm run run-once

실행 결과는 output\YYYY-MM-DD에 저장됩니다.
- auction-items.xlsx: 조건 일치 물건, 확인 필요 물건 2개 시트. 가격은 원, 면적은 ㎡, 날짜는 정렬 가능한 날짜입니다.
- collection.json: 수집 시각·조건·출처·범위와 물건 데이터.
- report-input.json: Codex가 읽을 보고서 입력 자료.
- daily-report.html / daily-report.md: 공식값을 자동 정리한 초안. GPT 설명이 작성되기 전에는 해석 대기라고 표시합니다.

같은 날 같은 조건으로 다시 실행하면 저장된 자료로 파일을 복구하며 법원을 다시 조회하지 않습니다. 같은 날 조건을 바꿔도 새 조회를 강행하지 않습니다. 다음 날 새 조건을 적용합니다. 첫 확인 여부는 이 폴더의 과거 기록과 비교한 것이며 법원 최초 등록일이 아닙니다.

5. GPT 일일 보고서 작성
prompts\daily-task.txt를 Codex에 붙여 넣습니다. Codex는 report-input.json을 읽고 gpt-analysis.json을 작성한 후 다음 명령으로 HTML/Markdown을 완성합니다.
npm run finalize-report -- --date YYYY-MM-DD

수집·엑셀은 프로그램이 수행하며, 해석 문장은 Codex의 GPT 모델이 작성합니다. 날짜·원본 해시·물건 연결이 다른 결과는 거절됩니다. 문장 자체가 실제 근거와 맞는지는 Codex가 원문과 대조합니다. 파일에 적힌 웹사이트 문구는 자료일 뿐, 실행 지시로 취급하지 않습니다.

6. 매일 1회 예약
첫 실행과 보고서 확인을 마친 뒤 prompts\schedule-request.txt를 Codex에 붙여 넣어 같은 로컬 프로젝트의 매일 예약을 요청합니다. 예약이 만들어졌는지 Codex 예약 화면에서 시간을 확인합니다. 이 ZIP이나 config.json만으로 예약이 자동 설치되지는 않습니다. 설정을 바꾸면 Codex 예약도 함께 변경합니다.
실행 시각에는 PC가 켜져 있고 절전 상태가 아니며, Codex 앱이 실행되고 인터넷에 연결돼 있어야 합니다. 앱 종료·절전·네트워크 오류로 놓친 실행이 반드시 자동 보충된다고 가정하지 않습니다. 복귀 후 run-once를 직접 실행해도 같은 날 중복 조회는 막습니다.
조건 변경: config.json의 지역·종류·금액·면적을 수정합니다. 예약은 매일 이 파일을 읽습니다. 당일 이미 수집했다면 다음 날부터 적용됩니다.
시간 변경: config.json의 time을 바꾸고 Codex에 '이 프로젝트 경매 예약 시간을 config.json의 time에 맞춰 변경해 줘'라고 요청합니다. 예약 목록의 실제 시간이 바뀌었는지도 확인합니다.
일시중지: Codex 예약 목록에서 해당 경매 작업을 일시중지합니다. 재개할 때 같은 작업을 다시 활성화해 중복 예약을 만들지 않습니다. config.json을 지우거나 time을 빈칸으로 바꾸는 방식으로 중지하지 않습니다.

7. 범위와 중단 대응
법원 검색 화면의 기본 매각기일 범위(통상 실행일~14일 뒤)를 읽습니다. 정확한 날짜는 결과에 표시됩니다. 전국의 모든 신규 접수 경매를 수집한 것이 아닙니다. 복합 매각·지분·불명확한 면적은 확인 필요로 분리합니다. 등기·권리·임대차·실거래·건축물대장·수익률 분석은 이 무료 킷에 포함하지 않습니다.
페이지 이동은 최소 15초 간격입니다. 이는 차단 방지를 보장하는 수치가 아닙니다. 429가 나오면 서버가 정한 Retry-After 이상 대기하며 반복 조회하지 않습니다. CAPTCHA/접근 제한은 즉시 중지하고 직접 확인합니다. 브라우저·IP·계정을 바꿔 우회하지 않습니다.
일시 실패 원인을 해결한 후 명시 재시도: npm run run-once -- --retry-failed
추가 확인 보류를 직접 해결했을 때만: npm run release -- --confirm-site-ready
release는 자동 재실행하지 않으며 서버가 지정한 429 대기시간을 줄이지 않습니다. 부분 수집 결과도 당일 저장 결과로 유지합니다. 다음 날 조건을 좁히거나 maxPages를 조정합니다.

8. 파일 관리
.state에는 실행 잠금·관측 이력·이 킷 전용 Chromium 프로필만 저장됩니다. 개인 브라우저 로그인 정보는 가져오지 않습니다. 출력 폴더와 .state를 임의로 지우면 중복 방지 이력도 사라집니다. 문제 해결을 위해 상태를 삭제하지 말고 Codex에 오류 코드를 전달하세요.
업데이트 전 config.json, .state, output을 보존합니다. 소스 파일만 교체하며 다른 제품의 데이터 폴더와 합치지 않습니다.

라이브러리
Playwright 1.63.0: Apache-2.0, https://github.com/microsoft/playwright
ExcelJS 4.4.0: MIT, https://github.com/exceljs/exceljs
설치되는 각 라이브러리의 LICENSE는 node_modules에 포함됩니다. 다운로드 ZIP은 의존성·브라우저·개인 프로필을 포함하지 않으며 npm ci와 Chromium 설치가 필요합니다.

공식 출처
대한민국 법원 법원경매정보: https://www.courtauction.go.kr/
Node.js 설치: https://nodejs.org/en/download
Playwright Chromium 설치: https://playwright.dev/docs/browsers
