docs(claude): realestate-lab + agent-office 청약 타겟팅 흐름 보강

- realestate-lab: 자치구 5티어 매칭 모델 / scheduled_collect 4단계 / 신규 컬럼 / notifier.py / 신규 endpoint
- agent-office: RealestateAgent.on_new_matches / 콜백 라우팅 / 신규 환경변수 / 데일리 cron 폐기
- 매칭 점수 모델: 35/10/15/15/25 = 100점 명시

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

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` 필터) |