diff --git a/CLAUDE.md b/CLAUDE.md index c616977..f531031 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -312,31 +312,64 @@ docker compose up -d - 가사 섹션 태그: `[Verse]`, `[Chorus]`, `[Bridge]`, `[Instrumental]` 등 ### realestate-lab (realestate-lab/) -- 공공데이터포털 API 연동: 한국부동산원 청약홈 분양정보 조회 서비스 +- 공공데이터포털 API 연동: 한국부동산원 청약홈 분양정보 조회 + 자치구 5티어 매칭 + agent-office push 알림 - DB: `/app/data/realestate.db` (announcements, announcement_models, user_profile, match_results, collect_log 테이블) -- 파일 구조: `main.py`, `db.py`, `collector.py`, `matcher.py`, `models.py` +- 파일 구조: `main.py`, `db.py`, `collector.py`, `matcher.py`, `notifier.py`, `models.py` **환경변수** - `DATA_GO_KR_API_KEY`: 공공데이터포털 API 키 (미설정 시 수동 등록만 가능) +- `AGENT_OFFICE_URL`: agent-office 내부 URL (기본 `http://agent-office:8000`) — 신규 매칭 push 대상 +- `REALESTATE_NOTIFY_TIMEOUT`: agent-office push timeout 초 (기본 15) -**스케줄러 job** -- 09:00 매일 — 청약 공고 수집 + 매칭 (`scheduled_collect`) -- 00:00 매일 — 상태 갱신 + 재매칭 (`scheduled_status_update`) +**스케줄러 job (`scheduled_collect` 4단계 흐름)** +- 09:00 매일 — `collect → cleanup → match → notify` + 1. `collect_all()` — 모집공고일 30일 윈도우(`RCRIT_PBLANC_DE_FROM`) 사전 좁힘 + 자치구 추출 + status='완료' skip + 2. `delete_old_completed_announcements(grace_days=90)` — `winner_date + 90일` 경과한 완료 공고 정리 (FK CASCADE로 match_results도 삭제) + 3. `run_matching()` — 자치구 5티어 가중치 + 자격 곡선 적용 + 4. `notify_new_matches()` — `notified_at IS NULL AND match_score >= profile.min_match_score AND profile.notify_enabled`인 매칭을 agent-office로 push +- 00:00 매일 — 상태 갱신 + 재매칭 (`scheduled_status_update`, notifier 미호출) + +**매칭 점수 모델 (총 100점)** +- 지역 35점 — 광역 매칭 시 10점 + 자치구 5티어 가중치(S=25 / A=20 / B=15 / C=10 / D=5) + - `preferred_districts`가 모든 티어 비어있으면 광역 매칭만으로 35점 풀 점수 (legacy 호환) +- 주택유형 10점 — `preferred_types`에 매칭 (binary) +- 면적 15점 — `[min_area, max_area]` 범위 안 모델 1개 이상 (binary) +- 가격 15점 — `max_price` 이하 모델 1개 이상 (binary) +- 자격 25점 — `_check_eligible_types()` 결과 1개 이상이면 15점 + 추가당 5점, 최대 +10 +- reasons 텍스트 예시: `"자치구 S티어: 강남구 (+25)"`, `"광역 일치: 서울"`, `"선호 지역 일치: 서울"` (legacy) + +**user_profile 신규 컬럼 (Task 2026-04-28 마이그레이션)** +- `preferred_districts` TEXT — JSON `{"S":[...], "A":[...], "B":[...], "C":[...], "D":[...]}`. default `'{}'` +- `min_match_score` INTEGER — 알림 임계값. default 70 +- `notify_enabled` INTEGER — 알림 ON/OFF. default 1 + +**announcements / match_results 신규 컬럼** +- `announcements.district` TEXT + `idx_ann_district` 인덱스 — collector가 주소/region_name에서 정규식 파싱 +- `match_results.notified_at` TEXT NULL — agent-office push 성공 시 timestamp 기록 (멱등 마킹) + +**notifier.py 흐름** +1. `get_profile()` → `notify_enabled=False`면 skip, `min_match_score` 가져옴 +2. `get_unnotified_matches(min_score)` — JOIN으로 announcements 정보 포함 (district, status, receipt 등) +3. `POST {AGENT_OFFICE_URL}/api/agent-office/realestate/notify` body=`{"matches": [...]}` +4. 응답 `{sent_ids: [...]}` → `mark_matches_notified(sent_ids)` (notified_at = now) +5. RequestException 시 마킹 안 함 → 다음 사이클 재시도 **realestate-lab API 목록** | 메서드 | 경로 | 설명 | |--------|------|------| -| GET | `/api/realestate/announcements` | 공고 목록 (region, status, house_type, matched_only, sort, page, size) | -| GET | `/api/realestate/announcements/{id}` | 공고 상세 (주택형별 포함) | +| GET | `/api/realestate/announcements` | 공고 목록. 응답에 `district`, `match_score`, `match_reasons`, `eligible_types` 포함 | +| GET | `/api/realestate/announcements/{id}` | 공고 상세 (주택형별 + district 포함) | | POST | `/api/realestate/announcements` | 수동 공고 등록 | | PUT | `/api/realestate/announcements/{id}` | 공고 수정 | +| PATCH | `/api/realestate/announcements/{id}/bookmark` | 북마크 토글 (텔레그램 인라인 키보드 콜백 대상) | | DELETE | `/api/realestate/announcements/{id}` | 공고 삭제 | -| POST | `/api/realestate/collect` | 수동 수집 트리거 | +| DELETE | `/api/realestate/announcements/closed` | status='완료' 공고 일괄 삭제 | +| POST | `/api/realestate/collect` | 수동 수집 트리거 (collect → cleanup → match → notify 전체 흐름) | | GET | `/api/realestate/collect/status` | 마지막 수집 결과 | -| GET | `/api/realestate/profile` | 내 프로필 조회 | -| PUT | `/api/realestate/profile` | 프로필 수정 (upsert) | -| GET | `/api/realestate/matches` | 매칭 결과 목록 | +| GET | `/api/realestate/profile` | 내 프로필 조회 (`preferred_districts`, `min_match_score`, `notify_enabled` 포함) | +| PUT | `/api/realestate/profile` | 프로필 수정 (upsert). body에 `preferred_districts: {S:[],...}`, `min_match_score: 0~100`, `notify_enabled: bool` 수용 | +| GET | `/api/realestate/matches` | 매칭 결과 목록 (응답에 `district`, `status` 포함) | | POST | `/api/realestate/matches/refresh` | 매칭 재계산 | | PATCH | `/api/realestate/matches/{id}/read` | 신규 알림 읽음 처리 | | GET | `/api/realestate/dashboard` | 요약 (진행중 공고수, 신규 매칭수, 다가오는 일정) | @@ -435,17 +468,20 @@ docker compose up -d ### agent-office (agent-office/) - AI 에이전트 가상 오피스 — 2D 픽셀아트 사무실에서 에이전트가 실제 작업 수행 -- stock-lab/music-lab 기존 API를 서비스 프록시로 호출 (직접 DB 접근 없음) +- stock-lab/music-lab/realestate-lab 기존 API를 서비스 프록시로 호출 (직접 DB 접근 없음) - 실시간 상태 동기화: WebSocket (`/api/agent-office/ws`) - 텔레그램 봇: 양방향 알림 + 승인 (인라인 키보드) +- 청약 매칭 알림: realestate-lab이 신규 매칭 발견 시 push → `RealestateAgent.on_new_matches()` → 텔레그램 1통(인라인 [🔖 북마크]/[📄 공고] 또는 [전체 보기] 버튼) - DB: `/app/data/agent_office.db` (agent_config, agent_tasks, agent_logs, telegram_state 테이블) -- 파일 구조: `main.py`, `db.py`, `config.py`, `models.py`, `websocket_manager.py`, `service_proxy.py`, `telegram_bot.py`, `scheduler.py`, `agents/base.py`, `agents/stock.py`, `agents/music.py` +- 파일 구조: `main.py`, `db.py`, `config.py`, `models.py`, `websocket_manager.py`, `service_proxy.py`, `telegram_bot.py`, `scheduler.py`, `agents/base.py`, `agents/stock.py`, `agents/music.py`, `agents/realestate.py`, `telegram/realestate_message.py` **에이전트 FSM 상태**: idle → working → waiting (승인 대기) → reporting → break (휴식) **환경변수** - `STOCK_LAB_URL`: stock-lab 내부 URL (기본 `http://stock-lab:8000`) - `MUSIC_LAB_URL`: music-lab 내부 URL (기본 `http://music-lab:8000`) +- `REALESTATE_LAB_URL`: realestate-lab 내부 URL (기본 `http://realestate-lab:8000`) — 북마크 콜백 프록시 대상 +- `REALESTATE_DASHBOARD_URL`: 텔레그램 [전체 보기] 버튼 URL (기본 `http://localhost:8080/realestate`) - `TELEGRAM_BOT_TOKEN`: 텔레그램 봇 토큰 (미설정 시 알림 비활성화) - `TELEGRAM_CHAT_ID`: 텔레그램 채팅 ID - `TELEGRAM_WEBHOOK_URL`: 텔레그램 Webhook URL @@ -468,6 +504,17 @@ docker compose up -d - 07:30 매일 — 주식 뉴스 요약 (`stock_news_job`) - 매주 월요일 07:00 — 로또 큐레이터 브리핑 (`lotto_curate`) - 60초 간격 — 유휴 에이전트 휴식 체크 (`idle_check_job`) +- ~~09:15 매일 — 청약 매칭 데일리 리포트~~ (Task 2026-04-28에서 폐기. realestate-lab의 push 트리거로 전환) + +**RealestateAgent (`agents/realestate.py`)** +- 진입점: `on_new_matches(matches: list[dict]) -> {sent, sent_ids, message_id}` +- realestate-lab의 push에서 트리거 → `format_realestate_matches()` + `build_match_keyboard()` → `messaging.send_raw()` +- 1~2건이면 풀 카드 + [🔖 북마크]/[📄 공고 보기] 행씩, 3건 이상이면 묶음 카드 + [📋 전체 보기] 단일 URL 버튼 +- 인라인 키보드 콜백 `realestate_bookmark_{id}` → `webhook.py`의 `_handle_realestate_bookmark` → `service_proxy.realestate_bookmark_toggle()` → realestate-lab의 `PATCH /announcements/{id}/bookmark` +- 송신 성공 시 sent_ids 반환 → realestate-lab이 match_results.notified_at 마킹 (멱등) +- 실패 시 sent=0/sent_ids=[]/error 반환 → 마킹 안 됨 → 다음 사이클 재시도 +- `on_command("fetch_matches")`: 수동 트리거 — service_proxy로 매치 가져와 `on_new_matches` 호출 +- `on_schedule`: 폐기 (cron 등록 제거됨) **agent-office API 목록** @@ -483,7 +530,8 @@ docker compose up -d | GET | `/api/agent-office/tasks/{id}` | 작업 상세 | | POST | `/api/agent-office/command` | 에이전트에 명령 전송 | | POST | `/api/agent-office/approve` | 작업 승인/거부 | -| POST | `/api/agent-office/telegram/webhook` | 텔레그램 Webhook 수신 | +| POST | `/api/agent-office/telegram/webhook` | 텔레그램 Webhook 수신 (realestate_bookmark_* 콜백 포함) | +| POST | `/api/agent-office/realestate/notify` | realestate-lab 전용 push 수신 → 텔레그램 송신 | | GET | `/api/agent-office/states` | 전체 에이전트 상태 조회 | | GET | `/api/agent-office/conversation/stats` | 텔레그램 자연어 대화 토큰·캐시 통계 (`days` 필터) |