# 법원경매 자동분석 시스템 (경기도) — 설치 가이드

매일 08:00, 경기도 법원경매 물건 중 경쟁력 있는 TOP 10의 수익률·리스크 분석 보고서(PDF)를
이메일로 자동 수신하는 완전 자동화 시스템.

- **백엔드**: Python 3.11 (크롤링/스코어링/LLM 권리분석/ROI/보고서/발송)
- **사용자 화면**: PHP 8+ (대시보드/물건검색/보고서 이력/시스템 상태)
- **DB**: MySQL 8.0

## 1. DB 생성
```bash
mysql -u root -p < db/schema.sql
mysql -u root -p -e "CREATE USER 'auction'@'localhost' IDENTIFIED BY '비밀번호';
GRANT ALL ON auction_ax.* TO 'auction'@'localhost'; FLUSH PRIVILEGES;"
```

## 2. Python 백엔드 설치 (/opt/auction 기준)
```bash
sudo mkdir -p /opt/auction && sudo cp -r . /opt/auction && cd /opt/auction
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
playwright install chromium
playwright install-deps          # Ubuntu 의존 패키지
# WeasyPrint 의존성 (Ubuntu)
sudo apt install -y libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 fonts-noto-cjk
```

## 3. config.yaml 설정 (CHANGE_ME 항목 필수)
- `db.password` : MySQL 비밀번호
- `molit.api_key` : 공공데이터포털(data.go.kr)에서 "국토교통부 아파트 매매 실거래가" 활용신청 후 발급 (무료)
- `llm.api_key` : OpenAI API 키 (platform.openai.com) — 기본 모델 gpt-4o-mini
- `report.*` : 수신 메일주소, SMTP 계정 (Gmail은 앱 비밀번호 사용)

## 4. 단계별 수동 테스트
```bash
venv/bin/python run.py crawl    # 수집 (30분~1시간 소요)
venv/bin/python run.py score
venv/bin/python run.py risk
venv/bin/python run.py roi
venv/bin/python run.py report   # output/에 PDF 생성 확인
venv/bin/python run.py send
```

## 5. cron 등록 (완전 자동화)
```bash
sudo useradd -r auction 2>/dev/null; sudo chown -R auction:auction /opt/auction
sudo cp cron/auction-pipeline.cron /etc/cron.d/auction-pipeline
```

## 6. PHP 대시보드 배포
```bash
sudo cp -r web /var/www/html/auction
# web/config.php 의 DB 정보, OUTPUT_DIR(/opt/auction/output) 확인
```
접속: `http://서버주소/auction/` → 기본계정 **admin / admin1234 (즉시 변경!)**
비밀번호 변경: `php -r "echo password_hash('새비밀번호', PASSWORD_DEFAULT);"` 결과를
`UPDATE web_users SET password_hash='...' WHERE username='admin';` 으로 반영.
Apache에서 output 디렉토리 읽기권한 필요: `sudo chmod -R o+r /opt/auction/output`

## 7. 운영 시 주의사항
1. **크롤러 선택자 조정**: `crawler/court_auction.py` 상단 `SELECTORS`는 법원경매정보
   사이트 실제 구조에 맞춰 최초 1회 조정 필요. 사이트 개편 시 이 블록만 수정.
2. **구조변경 경보**: 수집 실패율 20% 초과 시 admin_email로 자동 경보.
3. **낙찰가 예측**: 초기 2~3개월은 규칙 기반(낙찰가율). 낙찰 결과가 100건 이상 쌓이면
   매월 1일 자동으로 XGBoost 모델 학습/전환 (`models/train_bid_model.py`).
4. **폴백 정책**: 어떤 단계가 실패해도 08:00에 메일은 반드시 발송됨
   (전일 데이터 폴백 / 축약 보고서 / 최소한 실패 알림).
5. **요청 지연 준수**: config의 request_delay를 줄이지 말 것 (IP 차단 시 전체 중단).
6. 중기적으로 지지옥션/스피드옥션 유료 API 전환 검토 권장 (크롤러 유지보수 비용 상쇄).

## 디렉토리 구조
```
/opt/auction/            # Python 백엔드
├── run.py               # CLI 진입점
├── config.yaml          # 전체 설정 (경기도)
├── crawler/             # 법원경매 크롤러 + 국토부 실거래가 API
├── analysis/            # 스코어링 / LLM 권리분석 / ROI
├── report/              # PDF 생성 / 메일 발송 / 헬스체크
├── models/              # XGBoost 학습 (train_bid_model.py)
├── db/                  # schema.sql, DB 헬퍼
├── cron/                # crontab 파일
└── output/              # 일자별 PDF 보고서

/var/www/html/auction/   # PHP 대시보드
├── index.php            # 오늘의 TOP 10
├── items.php            # 물건 검색 (소재지/종류/리스크 필터)
├── item_detail.php      # 물건 상세 (권리분석 + 3시나리오 수익률 + 원문)
├── reports.php          # 보고서 이력 + PDF 다운로드
└── status.php           # 파이프라인 모니터링
```