diff --git a/docs/superpowers/plans/2026-04-28-realestate-targeting-enhancement.md b/docs/superpowers/plans/2026-04-28-realestate-targeting-enhancement.md
new file mode 100644
index 0000000..b4ea1b9
--- /dev/null
+++ b/docs/superpowers/plans/2026-04-28-realestate-targeting-enhancement.md
@@ -0,0 +1,2198 @@
+# 청약 서비스 타겟팅 고도화 구현 계획
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** realestate-lab의 수집·매칭을 자치구 5티어 가중치 기반으로 정교화하고, agent-office를 통해 신규 매칭 발견 즉시 텔레그램 푸시 한다.
+
+**Architecture:** realestate-lab은 09:00 cron에서 `collect → 정리 → 매칭 → notifier 푸시` 순으로 진행. notifier는 임계값 통과한 미알림 매칭을 모아 agent-office의 `/api/agent-office/realestate/notify` 엔드포인트로 HTTP push. agent-office의 `RealestateAgent.on_new_matches()`가 텔레그램 메시지 fmt + 인라인 키보드 빌드 + 송신 후 `notified_at`를 마킹. 데일리 리포트 cron은 폐기.
+
+**Tech Stack:** Python 3.12 / FastAPI / SQLite (WAL) / APScheduler / requests / pytest / unittest.mock / aiogram-style raw Telegram Bot API.
+
+**스펙 참조:** `docs/superpowers/specs/2026-04-28-realestate-targeting-enhancement-design.md`
+
+---
+
+## Task 1: realestate-lab 테스트 환경 셋업 (DB 경로 환경변수 + conftest)
+
+테스트가 운영 DB(`/app/data/realestate.db`)를 건드리지 않도록 환경변수로 DB 경로 오버라이드 가능하게 만든다.
+
+**Files:**
+- Modify: `realestate-lab/app/db.py:10` (DB_PATH 환경변수화)
+- Create: `realestate-lab/tests/__init__.py`
+- Create: `realestate-lab/tests/conftest.py`
+- Create: `realestate-lab/tests/test_db_basic.py` (smoke test)
+
+- [ ] **Step 1: DB_PATH를 환경변수로 변경**
+
+`realestate-lab/app/db.py:10` 수정.
+
+기존:
+```python
+DB_PATH = "/app/data/realestate.db"
+```
+
+변경:
+```python
+import os
+DB_PATH = os.getenv("REALESTATE_DB_PATH", "/app/data/realestate.db")
+```
+
+`os` import는 파일 상단의 import 블록에 추가.
+
+- [ ] **Step 2: tests 디렉토리 패키지 표시**
+
+`realestate-lab/tests/__init__.py` 생성. 비어 있는 파일.
+
+- [ ] **Step 3: conftest.py 생성 — 임시 DB 픽스처**
+
+`realestate-lab/tests/conftest.py`:
+
+```python
+import os
+import sys
+import tempfile
+import pytest
+
+# 테스트 임시 DB 경로를 import 전에 주입
+_TMP_DB = tempfile.mktemp(suffix=".db")
+os.environ["REALESTATE_DB_PATH"] = _TMP_DB
+
+# app 패키지 import 가능하게 PYTHONPATH 보정
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+
+@pytest.fixture(autouse=True)
+def _clean_db():
+ """각 테스트마다 DB 초기화."""
+ if os.path.exists(_TMP_DB):
+ os.remove(_TMP_DB)
+ from app.db import init_db
+ init_db()
+ yield
+ if os.path.exists(_TMP_DB):
+ os.remove(_TMP_DB)
+```
+
+- [ ] **Step 4: smoke test 작성**
+
+`realestate-lab/tests/test_db_basic.py`:
+
+```python
+def test_init_db_creates_tables():
+ from app.db import _conn
+ with _conn() as conn:
+ tables = {row[0] for row in conn.execute(
+ "SELECT name FROM sqlite_master WHERE type='table'"
+ )}
+ assert "announcements" in tables
+ assert "announcement_models" in tables
+ assert "user_profile" in tables
+ assert "match_results" in tables
+ assert "collect_log" in tables
+```
+
+- [ ] **Step 5: 테스트 실행 확인**
+
+Run: `cd realestate-lab && python -m pytest tests/ -v`
+Expected: 1 passed
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add realestate-lab/app/db.py realestate-lab/tests/__init__.py realestate-lab/tests/conftest.py realestate-lab/tests/test_db_basic.py
+git commit -m "test(realestate): add pytest harness with isolated SQLite fixture"
+```
+
+---
+
+## Task 2: realestate-lab DB 스키마 마이그레이션
+
+`user_profile`에 3 컬럼, `announcements`에 `district`, `match_results`에 `notified_at` 추가. `init_db()` 안에서 try/except 패턴으로 운영 DB 무중단 마이그레이션.
+
+**Files:**
+- Modify: `realestate-lab/app/db.py` (init_db 내부 ALTER 추가, _profile_row_to_dict 확장, PROFILE_COLUMNS 확장)
+- Test: `realestate-lab/tests/test_db_migration.py`
+
+- [ ] **Step 1: 마이그레이션 단위 테스트 작성 (실패 예상)**
+
+`realestate-lab/tests/test_db_migration.py`:
+
+```python
+def test_user_profile_has_new_columns():
+ from app.db import _conn
+ with _conn() as conn:
+ cols = {row["name"] for row in conn.execute("PRAGMA table_info(user_profile)")}
+ assert "preferred_districts" in cols
+ assert "min_match_score" in cols
+ assert "notify_enabled" in cols
+
+
+def test_announcements_has_district():
+ from app.db import _conn
+ with _conn() as conn:
+ cols = {row["name"] for row in conn.execute("PRAGMA table_info(announcements)")}
+ assert "district" in cols
+
+
+def test_match_results_has_notified_at():
+ from app.db import _conn
+ with _conn() as conn:
+ cols = {row["name"] for row in conn.execute("PRAGMA table_info(match_results)")}
+ assert "notified_at" in cols
+
+
+def test_district_index_exists():
+ from app.db import _conn
+ with _conn() as conn:
+ idx = {row["name"] for row in conn.execute(
+ "SELECT name FROM sqlite_master WHERE type='index'"
+ )}
+ assert "idx_ann_district" in idx
+
+
+def test_profile_defaults():
+ from app.db import upsert_profile, get_profile
+ upsert_profile({"name": "테스트"})
+ profile = get_profile()
+ assert profile["preferred_districts"] == {}
+ assert profile["min_match_score"] == 70
+ assert profile["notify_enabled"] is True
+```
+
+- [ ] **Step 2: 테스트 실행 — 실패 확인**
+
+Run: `cd realestate-lab && python -m pytest tests/test_db_migration.py -v`
+Expected: 5 failed (컬럼 없음, default 미적용)
+
+- [ ] **Step 3: announcements 테이블에 district 컬럼 + 인덱스 마이그레이션**
+
+`realestate-lab/app/db.py` 의 `init_db()` 안, `idx_ann_region` 인덱스 생성 다음 줄에 추가.
+
+찾을 위치 (현재 코드):
+```python
+ conn.execute("CREATE INDEX IF NOT EXISTS idx_ann_region ON announcements(region_name);")
+
+ # ── 마이그레이션: is_bookmarked 컬럼 추가 ──
+```
+
+다음과 같이 수정:
+```python
+ conn.execute("CREATE INDEX IF NOT EXISTS idx_ann_region ON announcements(region_name);")
+
+ # ── 마이그레이션: district 컬럼 + 인덱스 추가 ──
+ try:
+ conn.execute("SELECT district FROM announcements LIMIT 1")
+ except Exception:
+ conn.execute("ALTER TABLE announcements ADD COLUMN district TEXT")
+ conn.execute("CREATE INDEX IF NOT EXISTS idx_ann_district ON announcements(district);")
+
+ # ── 마이그레이션: is_bookmarked 컬럼 추가 ──
+```
+
+- [ ] **Step 4: user_profile에 3 컬럼 마이그레이션**
+
+`init_db()`의 user_profile CREATE 문 뒤에 추가. 현재 `match_results` CREATE 문 시작 부분 직전에 끼워 넣음.
+
+찾을 위치:
+```python
+ );
+ """)
+
+ # ── match_results ────────────────────────────────────────────────
+```
+
+(이 직전이 user_profile CREATE 종료점)
+
+다음과 같이 추가:
+```python
+ );
+ """)
+
+ # ── 마이그레이션: user_profile 신규 3컬럼 ──
+ for col, ddl in (
+ ("preferred_districts", "ALTER TABLE user_profile ADD COLUMN preferred_districts TEXT NOT NULL DEFAULT '{}'"),
+ ("min_match_score", "ALTER TABLE user_profile ADD COLUMN min_match_score INTEGER NOT NULL DEFAULT 70"),
+ ("notify_enabled", "ALTER TABLE user_profile ADD COLUMN notify_enabled INTEGER NOT NULL DEFAULT 1"),
+ ):
+ try:
+ conn.execute(f"SELECT {col} FROM user_profile LIMIT 1")
+ except Exception:
+ conn.execute(ddl)
+
+ # ── match_results ────────────────────────────────────────────────
+```
+
+- [ ] **Step 5: match_results에 notified_at 컬럼 마이그레이션**
+
+`init_db()`의 match_results CREATE 직후에 추가.
+
+찾을 위치:
+```python
+ UNIQUE(announcement_id, model_id)
+ );
+ """)
+
+ # ── collect_log ──────────────────────────────────────────────────
+```
+
+다음과 같이 변경:
+```python
+ UNIQUE(announcement_id, model_id)
+ );
+ """)
+
+ # ── 마이그레이션: notified_at 컬럼 추가 ──
+ try:
+ conn.execute("SELECT notified_at FROM match_results LIMIT 1")
+ except Exception:
+ conn.execute("ALTER TABLE match_results ADD COLUMN notified_at TEXT")
+
+ # ── collect_log ──────────────────────────────────────────────────
+```
+
+- [ ] **Step 6: PROFILE_COLUMNS와 _profile_row_to_dict, upsert_profile에 신규 필드 처리**
+
+`realestate-lab/app/db.py`의 `_profile_row_to_dict` 함수 (현재 파일 라인 ~536)를 다음과 같이 수정:
+
+```python
+def _profile_row_to_dict(r) -> Dict[str, Any]:
+ d = {}
+ for c in r.keys():
+ val = r[c]
+ if c in ("is_homeless", "is_householder", "has_dependents", "is_newlywed",
+ "has_newborn", "is_first_home", "notify_enabled"):
+ d[c] = bool(val) if val is not None else None
+ elif c in ("preferred_regions", "preferred_types"):
+ d[c] = json.loads(val) if val else []
+ elif c == "preferred_districts":
+ d[c] = json.loads(val) if val else {}
+ else:
+ d[c] = val
+ return d
+```
+
+`PROFILE_COLUMNS` 상수 (현재 라인 ~560)를 다음과 같이 확장:
+
+```python
+PROFILE_COLUMNS = {
+ "name", "age", "is_homeless", "is_householder",
+ "subscription_months", "subscription_amount", "family_members",
+ "has_dependents", "children_count", "is_newlywed", "marriage_months",
+ "has_newborn", "is_first_home", "income_level",
+ "preferred_regions", "preferred_types", "preferred_districts",
+ "min_area", "max_area", "max_price",
+ "min_match_score", "notify_enabled",
+}
+```
+
+`upsert_profile` 함수 안에서 list 처리 분기는 이미 있으므로, dict 분기를 추가해야 한다. 현재 코드:
+
+```python
+ if isinstance(v, bool):
+ updates[k] = 1 if v else 0
+ elif isinstance(v, list):
+ updates[k] = json.dumps(v)
+ else:
+ updates[k] = v
+```
+
+다음과 같이 수정:
+
+```python
+ if isinstance(v, bool):
+ updates[k] = 1 if v else 0
+ elif isinstance(v, (list, dict)):
+ updates[k] = json.dumps(v)
+ else:
+ updates[k] = v
+```
+
+- [ ] **Step 7: 테스트 실행 — 통과 확인**
+
+Run: `cd realestate-lab && python -m pytest tests/test_db_migration.py tests/test_db_basic.py -v`
+Expected: 6 passed
+
+- [ ] **Step 8: 커밋**
+
+```bash
+git add realestate-lab/app/db.py realestate-lab/tests/test_db_migration.py
+git commit -m "feat(realestate-db): add district / notify / 5tier columns with migration"
+```
+
+---
+
+## Task 3: realestate-lab DB 신규 함수 3종
+
+`delete_old_completed_announcements`, `get_unnotified_matches`, `mark_matches_notified`.
+
+**Files:**
+- Modify: `realestate-lab/app/db.py` (함수 3종 추가)
+- Test: `realestate-lab/tests/test_db_functions.py`
+
+- [ ] **Step 1: 테스트 작성 — delete_old_completed_announcements**
+
+`realestate-lab/tests/test_db_functions.py`:
+
+```python
+import json
+from datetime import date, timedelta
+from app.db import _conn
+
+
+def _seed_announcement(house_nm, status, winner_date=None, hmno="HM1", pno="P1"):
+ with _conn() as conn:
+ conn.execute("""
+ INSERT INTO announcements (house_manage_no, pblanc_no, house_nm, status, winner_date, source)
+ VALUES (?, ?, ?, ?, ?, 'manual')
+ """, (hmno, pno, house_nm, status, winner_date))
+ return conn.execute("SELECT id FROM announcements WHERE house_manage_no=?", (hmno,)).fetchone()["id"]
+
+
+def test_delete_old_completed_removes_expired():
+ from app.db import delete_old_completed_announcements
+ old = (date.today() - timedelta(days=100)).isoformat()
+ _seed_announcement("OldA", "완료", old, hmno="OLD", pno="1")
+ deleted = delete_old_completed_announcements(grace_days=90)
+ assert deleted == 1
+
+
+def test_delete_old_completed_keeps_recent():
+ from app.db import delete_old_completed_announcements
+ recent = (date.today() - timedelta(days=30)).isoformat()
+ _seed_announcement("RecentA", "완료", recent, hmno="REC", pno="1")
+ deleted = delete_old_completed_announcements(grace_days=90)
+ assert deleted == 0
+
+
+def test_delete_old_completed_keeps_active():
+ from app.db import delete_old_completed_announcements
+ old = (date.today() - timedelta(days=200)).isoformat()
+ _seed_announcement("ActiveA", "청약중", old, hmno="ACT", pno="1")
+ deleted = delete_old_completed_announcements(grace_days=90)
+ assert deleted == 0
+
+
+def test_delete_old_completed_keeps_null_winner_date():
+ from app.db import delete_old_completed_announcements
+ _seed_announcement("NullA", "완료", None, hmno="NULL", pno="1")
+ deleted = delete_old_completed_announcements(grace_days=90)
+ assert deleted == 0 # winner_date NULL은 안전 보존
+
+
+def test_get_unnotified_matches_filters_by_score_and_null():
+ from app.db import get_unnotified_matches
+ aid = _seed_announcement("MatchA", "청약중", hmno="MA", pno="1")
+ with _conn() as conn:
+ # 임계값 미만
+ conn.execute("""
+ INSERT INTO match_results (announcement_id, model_id, match_score, match_reasons, eligible_types, is_new)
+ VALUES (?, NULL, 50, '[]', '[]', 1)
+ """, (aid,))
+ # 임계값 통과 — 미알림
+ conn.execute("""
+ INSERT INTO match_results (announcement_id, model_id, match_score, match_reasons, eligible_types, is_new)
+ VALUES (?, 1, 80, '[]', '[]', 1)
+ """, (aid,))
+ # 임계값 통과 — 이미 알림됨
+ conn.execute("""
+ INSERT INTO match_results (announcement_id, model_id, match_score, match_reasons, eligible_types, is_new, notified_at)
+ VALUES (?, 2, 90, '[]', '[]', 1, '2026-04-01T00:00:00.000Z')
+ """, (aid,))
+
+ matches = get_unnotified_matches(min_score=70)
+ assert len(matches) == 1
+ assert matches[0]["match_score"] == 80
+ assert matches[0]["house_nm"] == "MatchA"
+
+
+def test_mark_matches_notified_sets_timestamp():
+ from app.db import mark_matches_notified
+ aid = _seed_announcement("NotifyA", "청약중", hmno="NT", pno="1")
+ with _conn() as conn:
+ cur = conn.execute("""
+ INSERT INTO match_results (announcement_id, model_id, match_score, match_reasons, eligible_types, is_new)
+ VALUES (?, NULL, 80, '[]', '[]', 1)
+ """, (aid,))
+ match_id = cur.lastrowid
+
+ mark_matches_notified([match_id])
+
+ with _conn() as conn:
+ row = conn.execute("SELECT notified_at FROM match_results WHERE id = ?", (match_id,)).fetchone()
+ assert row["notified_at"] is not None
+```
+
+- [ ] **Step 2: 테스트 실행 — 실패 확인**
+
+Run: `cd realestate-lab && python -m pytest tests/test_db_functions.py -v`
+Expected: 6 failed (함수 미정의)
+
+- [ ] **Step 3: db.py에 함수 3종 추가**
+
+`realestate-lab/app/db.py` 파일의 `delete_closed_announcements` 함수 다음에 추가 (현재 라인 ~408 인근).
+
+찾을 위치:
+```python
+def delete_closed_announcements() -> int:
+ """status='완료' 공고 일괄 삭제. 삭제된 건수 반환."""
+ with _conn() as conn:
+ cur = conn.execute("DELETE FROM announcements WHERE status = '완료'")
+ return cur.rowcount
+```
+
+직후에 추가:
+
+```python
+def delete_old_completed_announcements(grace_days: int = 90) -> int:
+ """winner_date + grace_days 경과한 status='완료' 공고를 삭제.
+ winner_date가 NULL인 행은 안전하게 보존(수동 검토 대상).
+ match_results는 FK CASCADE로 자동 삭제. 삭제된 건수 반환.
+ """
+ with _conn() as conn:
+ cur = conn.execute(
+ """
+ DELETE FROM announcements
+ WHERE status = '완료'
+ AND winner_date IS NOT NULL
+ AND date(winner_date) < date('now', ?)
+ """,
+ (f"-{grace_days} days",),
+ )
+ return cur.rowcount
+```
+
+같은 파일의 `mark_match_read` 함수 다음에 추가 (현재 라인 ~660 인근). 찾을 위치:
+
+```python
+def mark_match_read(match_id: int) -> bool:
+ with _conn() as conn:
+ cur = conn.execute("UPDATE match_results SET is_new = 0 WHERE id = ?", (match_id,))
+ return cur.rowcount > 0
+```
+
+직후에 추가:
+
+```python
+def get_unnotified_matches(min_score: int) -> List[Dict[str, Any]]:
+ """notified_at IS NULL AND match_score >= min_score 인 매칭과 공고 정보 조인 반환."""
+ with _conn() as conn:
+ rows = conn.execute("""
+ SELECT m.id, m.announcement_id, m.match_score, m.match_reasons, m.eligible_types,
+ a.house_nm, a.region_name, a.district, a.address,
+ a.receipt_start, a.receipt_end, a.winner_date,
+ a.house_secd, a.is_speculative_area, a.is_price_cap, a.pblanc_url
+ FROM match_results m
+ JOIN announcements a ON a.id = m.announcement_id
+ WHERE m.notified_at IS NULL
+ AND m.match_score >= ?
+ ORDER BY m.match_score DESC
+ """, (min_score,)).fetchall()
+ items = []
+ for r in rows:
+ d = {c: r[c] for c in r.keys()}
+ d["match_reasons"] = json.loads(d["match_reasons"]) if d["match_reasons"] else []
+ d["eligible_types"] = json.loads(d["eligible_types"]) if d["eligible_types"] else []
+ items.append(d)
+ return items
+
+
+def mark_matches_notified(match_ids: List[int]) -> None:
+ """주어진 match_results IDs의 notified_at을 현재 시각으로 일괄 업데이트."""
+ if not match_ids:
+ return
+ placeholders = ",".join("?" for _ in match_ids)
+ with _conn() as conn:
+ conn.execute(
+ f"UPDATE match_results SET notified_at = strftime('%Y-%m-%dT%H:%M:%fZ','now') "
+ f"WHERE id IN ({placeholders})",
+ match_ids,
+ )
+```
+
+- [ ] **Step 4: 테스트 실행 — 통과 확인**
+
+Run: `cd realestate-lab && python -m pytest tests/test_db_functions.py -v`
+Expected: 6 passed
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add realestate-lab/app/db.py realestate-lab/tests/test_db_functions.py
+git commit -m "feat(realestate-db): add notify queue + 90-day grace cleanup"
+```
+
+---
+
+## Task 4: realestate-lab collector 변경
+
+`_extract_district` 추가, 모집공고일 윈도우 사전 좁힘, `완료` 상태 skip.
+
+**Files:**
+- Modify: `realestate-lab/app/collector.py`
+- Test: `realestate-lab/tests/test_collector.py`
+
+- [ ] **Step 1: _extract_district 단위 테스트 작성**
+
+`realestate-lab/tests/test_collector.py`:
+
+```python
+def test_extract_district_seoul_full_address():
+ from app.collector import _extract_district
+ parsed = {"address": "서울특별시 강남구 도곡동 123-45", "region_name": None}
+ assert _extract_district(parsed) == "강남구"
+
+
+def test_extract_district_seoul_short():
+ from app.collector import _extract_district
+ parsed = {"address": None, "region_name": "서울 송파구"}
+ assert _extract_district(parsed) == "송파구"
+
+
+def test_extract_district_busan_returns_none():
+ from app.collector import _extract_district
+ parsed = {"address": "부산광역시 해운대구 우동", "region_name": None}
+ assert _extract_district(parsed) is None
+
+
+def test_extract_district_empty_returns_none():
+ from app.collector import _extract_district
+ parsed = {"address": "", "region_name": ""}
+ assert _extract_district(parsed) is None
+
+
+def test_extract_district_seoul_county():
+ from app.collector import _extract_district
+ parsed = {"address": "서울 강서구", "region_name": None}
+ assert _extract_district(parsed) == "강서구"
+
+
+def test_extract_district_prefers_address_over_region():
+ from app.collector import _extract_district
+ parsed = {"address": "서울특별시 마포구 합정동", "region_name": "서울 강남구"}
+ assert _extract_district(parsed) == "마포구"
+```
+
+- [ ] **Step 2: 테스트 실행 — 실패 확인**
+
+Run: `cd realestate-lab && python -m pytest tests/test_collector.py -v`
+Expected: 6 failed (`_extract_district` 미정의)
+
+- [ ] **Step 3: collector.py에 _extract_district 추가**
+
+`realestate-lab/app/collector.py`의 import 블록 변경:
+
+```python
+import os
+import re
+import logging
+from datetime import date, timedelta
+import requests
+from typing import List, Dict, Any
+```
+
+(`re`, `date`, `timedelta` 추가)
+
+기존 `_parse_apt_detail` 함수 위에 정규식 + 헬퍼 함수 추가:
+
+```python
+DISTRICT_PATTERN = re.compile(r"(?:서울특별시|서울시|서울)\s+(\S+?(?:구|군))")
+
+
+def _extract_district(parsed: Dict[str, Any]) -> str | None:
+ """파싱된 공고에서 자치구를 추출. 서울 외 지역·실패 시 None."""
+ for src in (parsed.get("address"), parsed.get("region_name")):
+ if not src:
+ continue
+ m = DISTRICT_PATTERN.search(src)
+ if m:
+ return m.group(1)
+ return None
+```
+
+- [ ] **Step 4: 테스트 실행 — 통과 확인**
+
+Run: `cd realestate-lab && python -m pytest tests/test_collector.py -v`
+Expected: 6 passed
+
+- [ ] **Step 5: collect_all 통합 테스트 추가 — 완료 skip + 윈도우**
+
+`realestate-lab/tests/test_collector.py` 파일 끝에 추가:
+
+```python
+from datetime import date, timedelta
+from unittest.mock import patch
+
+
+def test_collect_skips_completed_status(monkeypatch):
+ """winner_date가 과거인 응답은 status='완료'로 판정되어 upsert되지 않는다."""
+ from app import collector
+ from app.db import _conn
+
+ monkeypatch.setenv("DATA_GO_KR_API_KEY", "TEST")
+ # 모듈 상수도 갱신
+ monkeypatch.setattr(collector, "API_KEY", "TEST")
+
+ past_winner = (date.today() - timedelta(days=10)).strftime("%Y-%m-%d")
+
+ fake_detail_rows = [{
+ "HOUSE_MANAGE_NO": "DONE-1",
+ "PBLANC_NO": "01",
+ "HOUSE_NM": "완료된단지",
+ "HSSPLY_ADRES": "서울특별시 강남구",
+ "RCEPT_BGNDE": "2026-01-01",
+ "RCEPT_ENDDE": "2026-01-05",
+ "PRZWNER_PRESNATN_DE": past_winner,
+ }]
+
+ def fake_call(endpoint, params=None):
+ if "Detail" in endpoint:
+ return fake_detail_rows
+ return []
+
+ monkeypatch.setattr(collector, "_api_call", fake_call)
+ collector.collect_all()
+
+ with _conn() as conn:
+ rows = conn.execute("SELECT * FROM announcements WHERE house_manage_no='DONE-1'").fetchall()
+ assert len(rows) == 0
+
+
+def test_collect_stores_district_for_seoul_announcement(monkeypatch):
+ from app import collector
+ from app.db import _conn
+
+ monkeypatch.setenv("DATA_GO_KR_API_KEY", "TEST")
+ monkeypatch.setattr(collector, "API_KEY", "TEST")
+
+ future_start = (date.today() + timedelta(days=10)).strftime("%Y-%m-%d")
+ future_end = (date.today() + timedelta(days=15)).strftime("%Y-%m-%d")
+ future_winner = (date.today() + timedelta(days=30)).strftime("%Y-%m-%d")
+
+ fake_detail = [{
+ "HOUSE_MANAGE_NO": "SEOUL-1",
+ "PBLANC_NO": "01",
+ "HOUSE_NM": "강남단지",
+ "HSSPLY_ADRES": "서울특별시 강남구 도곡동 1",
+ "RCEPT_BGNDE": future_start,
+ "RCEPT_ENDDE": future_end,
+ "PRZWNER_PRESNATN_DE": future_winner,
+ }]
+
+ def fake_call(endpoint, params=None):
+ if "Detail" in endpoint:
+ return fake_detail
+ return []
+
+ monkeypatch.setattr(collector, "_api_call", fake_call)
+ collector.collect_all()
+
+ with _conn() as conn:
+ row = conn.execute("SELECT district, status FROM announcements WHERE house_manage_no='SEOUL-1'").fetchone()
+ assert row["district"] == "강남구"
+ assert row["status"] in ("청약예정", "청약중")
+
+
+def test_collect_passes_date_window_param(monkeypatch):
+ from app import collector
+
+ monkeypatch.setenv("DATA_GO_KR_API_KEY", "TEST")
+ monkeypatch.setattr(collector, "API_KEY", "TEST")
+
+ captured_params = []
+
+ def fake_call(endpoint, params=None):
+ captured_params.append(params or {})
+ return []
+
+ monkeypatch.setattr(collector, "_api_call", fake_call)
+ collector.collect_all()
+
+ expected_from = (date.today() - timedelta(days=30)).strftime("%Y%m%d")
+ detail_calls = [p for p in captured_params if "RCRIT_PBLANC_DE_FROM" in p]
+ assert detail_calls, "detail 엔드포인트 호출에 윈도우 파라미터가 없음"
+ assert detail_calls[0]["RCRIT_PBLANC_DE_FROM"] == expected_from
+```
+
+- [ ] **Step 6: 통합 테스트 실행 — 실패 확인**
+
+Run: `cd realestate-lab && python -m pytest tests/test_collector.py -v -k "test_collect"`
+Expected: 3 failed (윈도우/완료/district 미적용)
+
+- [ ] **Step 7: collect_all 본문 변경 — 윈도우 + skip + district**
+
+`realestate-lab/app/collector.py`의 `collect_all` 함수를 다음과 같이 수정:
+
+기존:
+```python
+def collect_all() -> Dict[str, Any]:
+ """모든 엔드포인트를 순회하며 공고 + 모델 데이터를 수집·저장한다."""
+ if not API_KEY:
+ logger.warning("API 키 미설정 — 수집 중단")
+ save_collect_log(0, 0, "API 키 미설정")
+ return {"new_count": 0, "total_count": 0}
+
+ total_count = 0
+ new_count = 0
+
+ for detail_ep, model_ep in DETAIL_ENDPOINTS:
+ # 공고 상세 수집
+ detail_rows = _api_call(detail_ep)
+ for raw in detail_rows:
+ try:
+ parsed = _parse_apt_detail(raw)
+ # 일정 정보가 하나도 없는 공고는 건너뜀
+ has_dates = any(parsed.get(f) for f in (
+ "receipt_start", "receipt_end", "spsply_start",
+ "gnrl_rank1_start", "winner_date", "contract_start",
+ ))
+ if not has_dates:
+ continue
+ _, is_new = upsert_announcement(parsed)
+ total_count += 1
+ if is_new:
+ new_count += 1
+ except Exception as e:
+ logger.error("공고 upsert 실패 [%s]: %s", detail_ep, e)
+```
+
+변경:
+```python
+def collect_all() -> Dict[str, Any]:
+ """모든 엔드포인트를 순회하며 공고 + 모델 데이터를 수집·저장한다.
+ 모집공고일 30일 이전 데이터는 API 파라미터로 사전 좁힘.
+ status='완료'로 판정되는 응답은 저장하지 않음.
+ """
+ if not API_KEY:
+ logger.warning("API 키 미설정 — 수집 중단")
+ save_collect_log(0, 0, "API 키 미설정")
+ return {"new_count": 0, "total_count": 0}
+
+ today = date.today()
+ date_from = (today - timedelta(days=30)).strftime("%Y%m%d")
+
+ total_count = 0
+ new_count = 0
+ skipped_completed = 0
+
+ for detail_ep, model_ep in DETAIL_ENDPOINTS:
+ # 공고 상세 수집 — API에 모집공고일 윈도우 파라미터 전달
+ # 일부 엔드포인트는 파라미터 미지원일 수 있어 무시되지만 응답에 영향 없음
+ detail_rows = _api_call(detail_ep, params={"RCRIT_PBLANC_DE_FROM": date_from})
+ for raw in detail_rows:
+ try:
+ parsed = _parse_apt_detail(raw)
+ parsed["district"] = _extract_district(parsed)
+
+ # 일정 정보가 하나도 없는 공고는 건너뜀 (기존)
+ has_dates = any(parsed.get(f) for f in (
+ "receipt_start", "receipt_end", "spsply_start",
+ "gnrl_rank1_start", "winner_date", "contract_start",
+ ))
+ if not has_dates:
+ continue
+
+ # status='완료'면 저장하지 않음 (자원 절감)
+ from .db import compute_status
+ status = compute_status(
+ parsed.get("receipt_start", "") or "",
+ parsed.get("receipt_end", "") or "",
+ parsed.get("winner_date", "") or "",
+ )
+ if status == "완료":
+ skipped_completed += 1
+ continue
+
+ _, is_new = upsert_announcement(parsed)
+ total_count += 1
+ if is_new:
+ new_count += 1
+ except Exception as e:
+ logger.error("공고 upsert 실패 [%s]: %s", detail_ep, e)
+```
+
+- [ ] **Step 8: upsert_announcement에 district 컬럼 처리 — db.py 변경**
+
+`realestate-lab/app/db.py`의 `upsert_announcement` 함수의 INSERT 컬럼 목록과 ON CONFLICT 절에 `district`를 추가.
+
+찾을 위치 (`INSERT INTO announcements` 부분):
+```python
+ conn.execute("""
+ INSERT INTO announcements (
+ house_manage_no, pblanc_no, house_nm, house_secd, house_dtl_secd,
+ rent_secd, region_code, region_name, address, total_units,
+```
+
+다음과 같이 변경:
+```python
+ conn.execute("""
+ INSERT INTO announcements (
+ house_manage_no, pblanc_no, house_nm, house_secd, house_dtl_secd,
+ rent_secd, region_code, region_name, district, address, total_units,
+```
+
+VALUES 블록도 변경:
+기존:
+```python
+ ) VALUES (
+ :house_manage_no, :pblanc_no, :house_nm, :house_secd, :house_dtl_secd,
+ :rent_secd, :region_code, :region_name, :address, :total_units,
+```
+
+변경:
+```python
+ ) VALUES (
+ :house_manage_no, :pblanc_no, :house_nm, :house_secd, :house_dtl_secd,
+ :rent_secd, :region_code, :region_name, :district, :address, :total_units,
+```
+
+ON CONFLICT 절에도 추가. 찾을 위치:
+```python
+ region_code=excluded.region_code,
+ region_name=excluded.region_name,
+ address=excluded.address,
+```
+
+다음과 같이 변경:
+```python
+ region_code=excluded.region_code,
+ region_name=excluded.region_name,
+ district=excluded.district,
+ address=excluded.address,
+```
+
+마지막으로, `upsert_announcement` 함수 시작부에 district 기본값 보정 추가. 함수 첫 줄 직후:
+
+```python
+def upsert_announcement(data: Dict[str, Any]) -> tuple:
+ """공고 upsert — house_manage_no + pblanc_no 기준. Returns (dict, is_new: bool)."""
+ data.setdefault("district", None) # 수동 등록 등에서 누락 시 안전 처리
+ status = compute_status(
+ ...
+```
+
+`ANNOUNCEMENT_COLUMNS` 상수에도 추가:
+
+```python
+ANNOUNCEMENT_COLUMNS = {
+ "house_nm", "house_secd", "house_dtl_secd", "rent_secd",
+ "region_code", "region_name", "district", "address", "total_units",
+ ...
+}
+```
+
+- [ ] **Step 9: 테스트 실행 — 통과 확인**
+
+Run: `cd realestate-lab && python -m pytest tests/test_collector.py -v`
+Expected: 9 passed
+
+- [ ] **Step 10: 커밋**
+
+```bash
+git add realestate-lab/app/collector.py realestate-lab/app/db.py realestate-lab/tests/test_collector.py
+git commit -m "feat(realestate-collector): 30-day window + district extraction + completed skip"
+```
+
+---
+
+## Task 5: realestate-lab matcher 5티어 + 자격 점수 재배분
+
+지역 35점(광역 10 + 자치구 가중 25), 자격 25점(첫 자격 15 + 추가 5씩 최대 +10).
+
+**Files:**
+- Modify: `realestate-lab/app/matcher.py`
+- Test: `realestate-lab/tests/test_matcher.py`
+
+- [ ] **Step 1: 지역·자격 점수 단위 테스트 작성**
+
+`realestate-lab/tests/test_matcher.py`:
+
+```python
+def test_region_score_no_districts_full_when_region_match():
+ """자치구 미설정: 광역 일치 시 35점."""
+ from app.matcher import _region_score
+ profile = {"preferred_regions": ["서울"], "preferred_districts": {}}
+ ann = {"region_name": "서울특별시", "district": None}
+ score, _ = _region_score(profile, ann)
+ assert score == 35
+
+
+def test_region_score_no_districts_zero_when_region_mismatch():
+ from app.matcher import _region_score
+ profile = {"preferred_regions": ["서울"], "preferred_districts": {}}
+ ann = {"region_name": "부산광역시", "district": None}
+ score, _ = _region_score(profile, ann)
+ assert score == 0
+
+
+def test_region_score_s_tier_district():
+ """광역 매칭 + S티어 자치구: 10 + 25 = 35."""
+ from app.matcher import _region_score
+ profile = {
+ "preferred_regions": ["서울"],
+ "preferred_districts": {"S": ["강남구"], "A": [], "B": [], "C": [], "D": []},
+ }
+ ann = {"region_name": "서울특별시", "district": "강남구"}
+ score, _ = _region_score(profile, ann)
+ assert score == 35
+
+
+def test_region_score_a_tier_district():
+ """광역 매칭 + A티어 자치구: 10 + 20 = 30."""
+ from app.matcher import _region_score
+ profile = {
+ "preferred_regions": ["서울"],
+ "preferred_districts": {"S": [], "A": ["송파구"], "B": [], "C": [], "D": []},
+ }
+ ann = {"region_name": "서울특별시", "district": "송파구"}
+ score, _ = _region_score(profile, ann)
+ assert score == 30
+
+
+def test_region_score_d_tier_district():
+ """광역 매칭 + D티어 자치구: 10 + 5 = 15."""
+ from app.matcher import _region_score
+ profile = {
+ "preferred_regions": ["서울"],
+ "preferred_districts": {"S": [], "A": [], "B": [], "C": [], "D": ["도봉구"]},
+ }
+ ann = {"region_name": "서울특별시", "district": "도봉구"}
+ score, _ = _region_score(profile, ann)
+ assert score == 15
+
+
+def test_region_score_district_set_but_not_listed():
+ """광역 매칭 + 자치구 5티어 어디에도 없음: 10점만."""
+ from app.matcher import _region_score
+ profile = {
+ "preferred_regions": ["서울"],
+ "preferred_districts": {"S": ["강남구"], "A": [], "B": [], "C": [], "D": []},
+ }
+ ann = {"region_name": "서울특별시", "district": "강서구"}
+ score, _ = _region_score(profile, ann)
+ assert score == 10
+
+
+def test_eligibility_score_zero_when_empty():
+ from app.matcher import _eligibility_score
+ assert _eligibility_score([]) == 0
+
+
+def test_eligibility_score_one_type_returns_15():
+ from app.matcher import _eligibility_score
+ assert _eligibility_score(["일반1순위"]) == 15
+
+
+def test_eligibility_score_two_types_returns_20():
+ from app.matcher import _eligibility_score
+ assert _eligibility_score(["일반1순위", "특별-신혼부부"]) == 20
+
+
+def test_eligibility_score_caps_at_25():
+ from app.matcher import _eligibility_score
+ assert _eligibility_score(["a", "b", "c", "d", "e"]) == 25
+```
+
+- [ ] **Step 2: 테스트 실행 — 실패 확인**
+
+Run: `cd realestate-lab && python -m pytest tests/test_matcher.py -v`
+Expected: 10 failed
+
+- [ ] **Step 3: matcher.py에 신규 함수 추가**
+
+`realestate-lab/app/matcher.py` 파일 상단 (logger 정의 후, _HOUSE_TYPE_MAP 위)에 추가:
+
+```python
+TIER_WEIGHTS = {"S": 1.00, "A": 0.80, "B": 0.60, "C": 0.40, "D": 0.20}
+
+
+def _region_score(profile: Dict[str, Any], ann: Dict[str, Any]) -> tuple[int, list[str]]:
+ """지역 점수 계산. 광역 10점 + 자치구 5티어 가중치 0~25점.
+ 자치구 기준 미설정 시 광역 매칭만으로 35점 풀 점수(기존 호환).
+ """
+ region_name = ann.get("region_name") or ""
+ district = ann.get("district") or ""
+ preferred_regions = profile.get("preferred_regions") or []
+ preferred_districts = profile.get("preferred_districts") or {}
+
+ region_match = bool(region_name and any(r in region_name for r in preferred_regions))
+ if not region_match:
+ return 0, []
+
+ has_districts = any(preferred_districts.get(t) for t in TIER_WEIGHTS)
+ if not has_districts:
+ return 35, [f"선호 지역 일치: {region_name}"]
+
+ score = 10
+ reasons = [f"광역 일치: {region_name}"]
+ for tier, weight in TIER_WEIGHTS.items():
+ if district and district in (preferred_districts.get(tier) or []):
+ tier_score = round(25 * weight)
+ score += tier_score
+ reasons.append(f"자치구 {tier}티어: {district} (+{tier_score})")
+ break
+ return score, reasons
+
+
+def _eligibility_score(eligible_types: List[str]) -> int:
+ """자격 점수 0~25. 첫 자격 15점 + 추가 자격당 5점, 최대 +10."""
+ if not eligible_types:
+ return 0
+ return 15 + min((len(eligible_types) - 1) * 5, 10)
+```
+
+- [ ] **Step 4: _compute_score 본문 교체 — 새 함수 호출 통합**
+
+`realestate-lab/app/matcher.py`의 `_compute_score` 함수 본문을 다음과 같이 교체:
+
+```python
+def _compute_score(
+ profile: Dict[str, Any],
+ ann: Dict[str, Any],
+ models: List[Dict[str, Any]],
+) -> Dict[str, Any]:
+ """매칭 점수(0-100)와 사유를 계산한다.
+ 배분: 지역 35 / 유형 10 / 면적 15 / 가격 15 / 자격 25.
+ """
+ score = 0
+ reasons: List[str] = []
+
+ # 1. 지역 (35점) — 광역 + 자치구 5티어
+ region_score, region_reasons = _region_score(profile, ann)
+ score += region_score
+ reasons.extend(region_reasons)
+
+ # 2. 주택유형 (10점) — binary
+ preferred_types = profile.get("preferred_types") or []
+ house_secd = ann.get("house_secd") or ""
+ type_name = _HOUSE_TYPE_MAP.get(house_secd, house_secd)
+ if type_name and type_name in preferred_types:
+ score += 10
+ reasons.append(f"선호 유형 일치: {type_name}")
+
+ # 3. 면적 (15점) — binary, 범위 안 모델 1개라도 있으면 통과
+ min_area = profile.get("min_area")
+ max_area = profile.get("max_area")
+ if min_area is not None and max_area is not None and models:
+ for m in models:
+ supply_area = m.get("supply_area")
+ if supply_area is not None and min_area <= supply_area <= max_area:
+ score += 15
+ reasons.append(f"희망 면적 범위 내 모델 존재 ({supply_area}㎡)")
+ break
+
+ # 4. 가격 (15점) — binary, 예산 이하 모델 1개라도 있으면 통과
+ max_price = profile.get("max_price")
+ if max_price is not None and models:
+ for m in models:
+ top_amount = m.get("top_amount")
+ if top_amount is not None and top_amount <= max_price:
+ score += 15
+ reasons.append(f"예산 범위 내 모델 존재 (최고가 {top_amount:,}만원)")
+ break
+
+ # 5. 자격 (25점) — 첫 자격 15 + 추가당 5
+ eligible_types = _check_eligible_types(profile, ann)
+ elig_score = _eligibility_score(eligible_types)
+ if elig_score > 0:
+ score += elig_score
+ reasons.append(f"자격 유형 {len(eligible_types)}개: {', '.join(eligible_types)}")
+
+ return {
+ "match_score": score,
+ "match_reasons": reasons,
+ "eligible_types": eligible_types,
+ }
+```
+
+- [ ] **Step 5: 테스트 실행 — 통과 확인**
+
+Run: `cd realestate-lab && python -m pytest tests/test_matcher.py -v`
+Expected: 10 passed
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add realestate-lab/app/matcher.py realestate-lab/tests/test_matcher.py
+git commit -m "feat(realestate-matcher): 5-tier district weighting + eligibility curve"
+```
+
+---
+
+## Task 6: realestate-lab Profile API 확장
+
+`ProfileUpdate` Pydantic 모델에 3 필드 추가. `models.py`만 수정하면 main.py 흐름은 자동 반영(이미 PROFILE_COLUMNS 기반).
+
+**Files:**
+- Modify: `realestate-lab/app/models.py`
+- Test: `realestate-lab/tests/test_profile_api.py`
+
+- [ ] **Step 1: API 통합 테스트 작성**
+
+`realestate-lab/tests/test_profile_api.py`:
+
+```python
+from fastapi.testclient import TestClient
+
+
+def test_profile_update_accepts_new_fields():
+ from app.main import app
+ client = TestClient(app)
+ body = {
+ "name": "테스트",
+ "preferred_districts": {
+ "S": ["강남구", "서초구"],
+ "A": ["송파구"],
+ "B": [],
+ "C": [],
+ "D": [],
+ },
+ "min_match_score": 75,
+ "notify_enabled": True,
+ }
+ resp = client.put("/api/realestate/profile", json=body)
+ assert resp.status_code == 200
+ data = resp.json()
+ assert data["preferred_districts"]["S"] == ["강남구", "서초구"]
+ assert data["min_match_score"] == 75
+ assert data["notify_enabled"] is True
+
+
+def test_profile_get_returns_defaults_for_new_fields():
+ from app.main import app
+ from app.db import upsert_profile
+ upsert_profile({"name": "기본"})
+
+ client = TestClient(app)
+ resp = client.get("/api/realestate/profile")
+ assert resp.status_code == 200
+ data = resp.json()
+ assert data["preferred_districts"] == {}
+ assert data["min_match_score"] == 70
+ assert data["notify_enabled"] is True
+```
+
+- [ ] **Step 2: 테스트 실행 — 실패 확인**
+
+Run: `cd realestate-lab && python -m pytest tests/test_profile_api.py -v`
+Expected: 2 failed (모델에 필드 없음 → 422 또는 dict 직렬화 실패)
+
+- [ ] **Step 3: ProfileUpdate 모델에 필드 추가**
+
+`realestate-lab/app/models.py` 파일의 import 변경:
+
+```python
+from typing import Optional, List, Dict
+from pydantic import BaseModel, Field
+```
+
+`ProfileUpdate` 클래스 끝에 필드 추가:
+
+```python
+class ProfileUpdate(BaseModel):
+ # ... 기존 필드 그대로
+ name: Optional[str] = None
+ age: Optional[int] = None
+ is_homeless: Optional[bool] = None
+ is_householder: Optional[bool] = None
+ subscription_months: Optional[int] = None
+ subscription_amount: Optional[int] = None
+ family_members: Optional[int] = None
+ has_dependents: Optional[bool] = None
+ children_count: Optional[int] = None
+ is_newlywed: Optional[bool] = None
+ marriage_months: Optional[int] = None
+ has_newborn: Optional[bool] = None
+ is_first_home: Optional[bool] = None
+ income_level: Optional[str] = None
+ preferred_regions: Optional[List[str]] = None
+ preferred_types: Optional[List[str]] = None
+ min_area: Optional[float] = None
+ max_area: Optional[float] = None
+ max_price: Optional[int] = None
+ # 신규
+ preferred_districts: Optional[Dict[str, List[str]]] = None
+ min_match_score: Optional[int] = Field(default=None, ge=0, le=100)
+ notify_enabled: Optional[bool] = None
+```
+
+- [ ] **Step 4: 테스트 실행 — 통과 확인**
+
+Run: `cd realestate-lab && python -m pytest tests/test_profile_api.py -v`
+Expected: 2 passed
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add realestate-lab/app/models.py realestate-lab/tests/test_profile_api.py
+git commit -m "feat(realestate-profile): expose 5tier districts + min_match_score + notify_enabled"
+```
+
+---
+
+## Task 7: realestate-lab notifier.py 신규
+
+agent-office로 push 트리거. 임계값 + notify_enabled 필터 + 멱등 마킹.
+
+**Files:**
+- Create: `realestate-lab/app/notifier.py`
+- Create: `realestate-lab/tests/test_notifier.py`
+
+- [ ] **Step 1: notifier 단위 테스트 작성**
+
+`realestate-lab/tests/test_notifier.py`:
+
+```python
+from unittest.mock import patch, MagicMock
+
+
+def _seed_profile_and_match(score, notify_enabled=True, threshold=70):
+ from app.db import _conn, upsert_profile
+ upsert_profile({
+ "name": "u",
+ "notify_enabled": notify_enabled,
+ "min_match_score": threshold,
+ })
+ with _conn() as conn:
+ conn.execute("""
+ INSERT INTO announcements (house_manage_no, pblanc_no, house_nm, status, source)
+ VALUES ('NF1', '01', '단지', '청약중', 'manual')
+ """)
+ ann_id = conn.execute("SELECT id FROM announcements WHERE house_manage_no='NF1'").fetchone()["id"]
+ conn.execute("""
+ INSERT INTO match_results (announcement_id, model_id, match_score, match_reasons, eligible_types, is_new)
+ VALUES (?, NULL, ?, '[]', '[]', 1)
+ """, (ann_id, score))
+ match_id = conn.execute("SELECT id FROM match_results WHERE announcement_id=?", (ann_id,)).fetchone()["id"]
+ return match_id
+
+
+def test_notify_skips_when_disabled():
+ from app import notifier
+ _seed_profile_and_match(score=80, notify_enabled=False)
+ with patch.object(notifier, "requests") as r:
+ result = notifier.notify_new_matches()
+ assert r.post.call_count == 0
+ assert result["sent"] == 0
+ assert result.get("skipped") == "notify_disabled"
+
+
+def test_notify_filters_below_threshold():
+ from app import notifier
+ _seed_profile_and_match(score=60, threshold=70)
+ with patch.object(notifier, "requests") as r:
+ result = notifier.notify_new_matches()
+ assert r.post.call_count == 0
+ assert result["sent"] == 0
+
+
+def test_notify_pushes_and_marks_notified():
+ from app import notifier
+ from app.db import _conn
+
+ match_id = _seed_profile_and_match(score=80, threshold=70)
+
+ fake_resp = MagicMock()
+ fake_resp.json.return_value = {"sent": 1, "sent_ids": [match_id]}
+ fake_resp.raise_for_status.return_value = None
+
+ with patch.object(notifier.requests, "post", return_value=fake_resp) as post:
+ result = notifier.notify_new_matches()
+
+ assert post.call_count == 1
+ args, kwargs = post.call_args
+ assert "/api/agent-office/realestate/notify" in args[0]
+ assert kwargs["json"]["matches"][0]["id"] == match_id
+
+ with _conn() as conn:
+ row = conn.execute("SELECT notified_at FROM match_results WHERE id=?", (match_id,)).fetchone()
+ assert row["notified_at"] is not None
+ assert result["sent"] == 1
+
+
+def test_notify_does_not_mark_on_failure():
+ from app import notifier
+ from app.db import _conn
+ import requests as real_requests
+
+ match_id = _seed_profile_and_match(score=80, threshold=70)
+
+ def boom(*a, **k):
+ raise real_requests.RequestException("agent-office down")
+
+ with patch.object(notifier.requests, "post", side_effect=boom):
+ result = notifier.notify_new_matches()
+
+ with _conn() as conn:
+ row = conn.execute("SELECT notified_at FROM match_results WHERE id=?", (match_id,)).fetchone()
+ assert row["notified_at"] is None
+ assert result["sent"] == 0
+ assert "error" in result
+```
+
+- [ ] **Step 2: 테스트 실행 — 실패 확인**
+
+Run: `cd realestate-lab && python -m pytest tests/test_notifier.py -v`
+Expected: 4 failed (모듈 없음)
+
+- [ ] **Step 3: notifier.py 작성**
+
+`realestate-lab/app/notifier.py`:
+
+```python
+"""신규 매칭을 agent-office로 push하여 텔레그램 알림을 트리거한다."""
+import os
+import logging
+import requests
+
+from .db import get_profile, get_unnotified_matches, mark_matches_notified
+
+logger = logging.getLogger("realestate-lab")
+
+AGENT_OFFICE_URL = os.getenv("AGENT_OFFICE_URL", "http://agent-office:8000")
+NOTIFY_TIMEOUT_SECONDS = int(os.getenv("REALESTATE_NOTIFY_TIMEOUT", "15"))
+
+
+def notify_new_matches() -> dict:
+ """프로필의 임계값을 통과한 미알림 매칭을 agent-office로 push한다.
+
+ 응답이 200이고 sent_ids가 비어있지 않으면 해당 IDs의 notified_at을 마킹.
+ 실패 시 마킹하지 않아 다음 사이클에서 재시도된다.
+ """
+ profile = get_profile()
+ if not profile:
+ return {"sent": 0, "skipped": "no_profile"}
+
+ if not profile.get("notify_enabled"):
+ return {"sent": 0, "skipped": "notify_disabled"}
+
+ threshold = profile.get("min_match_score") or 70
+ matches = get_unnotified_matches(threshold)
+ if not matches:
+ return {"sent": 0}
+
+ url = f"{AGENT_OFFICE_URL}/api/agent-office/realestate/notify"
+ try:
+ resp = requests.post(url, json={"matches": matches}, timeout=NOTIFY_TIMEOUT_SECONDS)
+ resp.raise_for_status()
+ body = resp.json()
+ except requests.RequestException as e:
+ logger.error("agent-office push 실패: %s", e)
+ return {"sent": 0, "error": str(e)}
+
+ sent_ids = body.get("sent_ids") or []
+ if sent_ids:
+ mark_matches_notified(sent_ids)
+ logger.info("알림 송신: %d건", len(sent_ids))
+ return body
+```
+
+- [ ] **Step 4: 테스트 실행 — 통과 확인**
+
+Run: `cd realestate-lab && python -m pytest tests/test_notifier.py -v`
+Expected: 4 passed
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add realestate-lab/app/notifier.py realestate-lab/tests/test_notifier.py
+git commit -m "feat(realestate-notifier): push unnotified matches to agent-office"
+```
+
+---
+
+## Task 8: realestate-lab scheduled_collect 흐름 통합
+
+`scheduled_collect`에 정리 + notifier 호출 추가.
+
+**Files:**
+- Modify: `realestate-lab/app/main.py`
+- Test: `realestate-lab/tests/test_scheduled_flow.py`
+
+- [ ] **Step 1: 흐름 통합 테스트 작성**
+
+`realestate-lab/tests/test_scheduled_flow.py`:
+
+```python
+from unittest.mock import patch
+
+
+def test_scheduled_collect_calls_cleanup_and_notifier():
+ from app import main as app_main
+
+ calls = []
+
+ def fake_collect():
+ calls.append("collect")
+ return {"new_count": 0, "total_count": 0}
+
+ def fake_cleanup(grace_days=90):
+ calls.append(("cleanup", grace_days))
+ return 0
+
+ def fake_match():
+ calls.append("match")
+
+ def fake_notify():
+ calls.append("notify")
+ return {"sent": 0}
+
+ with patch.object(app_main, "collect_all", side_effect=fake_collect), \
+ patch.object(app_main, "delete_old_completed_announcements", side_effect=fake_cleanup), \
+ patch.object(app_main, "run_matching", side_effect=fake_match), \
+ patch.object(app_main, "notify_new_matches", side_effect=fake_notify):
+ app_main.scheduled_collect()
+
+ assert calls == ["collect", ("cleanup", 90), "match", "notify"]
+```
+
+- [ ] **Step 2: 테스트 실행 — 실패 확인**
+
+Run: `cd realestate-lab && python -m pytest tests/test_scheduled_flow.py -v`
+Expected: 1 failed (notify_new_matches/delete_old_completed import 안 됨)
+
+- [ ] **Step 3: main.py 수정**
+
+`realestate-lab/app/main.py`의 import 블록에 추가:
+
+```python
+from .db import (
+ init_db, get_announcements, get_announcement, create_announcement,
+ update_announcement, delete_announcement, delete_closed_announcements, toggle_bookmark,
+ update_all_statuses,
+ get_profile, upsert_profile, get_matches, mark_match_read,
+ get_last_collect_log, get_dashboard,
+ delete_old_completed_announcements, # NEW
+)
+from .collector import collect_all
+from .matcher import run_matching
+from .notifier import notify_new_matches # NEW
+from .models import AnnouncementCreate, AnnouncementUpdate, ProfileUpdate
+```
+
+`scheduled_collect` 함수 수정:
+
+기존:
+```python
+def scheduled_collect():
+ """매일 09:00 — 수집 + 매칭"""
+ logger.info("스케줄 수집 시작")
+ collect_all()
+ run_matching()
+ logger.info("스케줄 수집 + 매칭 완료")
+```
+
+변경:
+```python
+def scheduled_collect():
+ """매일 09:00 — 수집 + 정리 + 매칭 + 알림 push"""
+ logger.info("스케줄 수집 시작")
+ collect_all()
+ deleted = delete_old_completed_announcements(grace_days=90)
+ if deleted:
+ logger.info("정리: %d건 삭제", deleted)
+ run_matching()
+ notify_new_matches()
+ logger.info("스케줄 수집 + 매칭 + 알림 완료")
+```
+
+`_run_collect_and_match`도 통일성을 위해 같은 흐름 적용:
+
+기존:
+```python
+def _run_collect_and_match():
+ if not _collect_lock.acquire(blocking=False):
+ logger.info("수집 이미 진행 중 — 건너뜀")
+ return
+ try:
+ collect_all()
+ run_matching()
+ finally:
+ _collect_lock.release()
+```
+
+변경:
+```python
+def _run_collect_and_match():
+ if not _collect_lock.acquire(blocking=False):
+ logger.info("수집 이미 진행 중 — 건너뜀")
+ return
+ try:
+ collect_all()
+ delete_old_completed_announcements(grace_days=90)
+ run_matching()
+ notify_new_matches()
+ finally:
+ _collect_lock.release()
+```
+
+- [ ] **Step 4: 테스트 실행 — 통과 확인**
+
+Run: `cd realestate-lab && python -m pytest tests/test_scheduled_flow.py -v`
+Expected: 1 passed
+
+- [ ] **Step 5: 전체 회귀 검증**
+
+Run: `cd realestate-lab && python -m pytest tests/ -v`
+Expected: 모든 테스트 통과
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add realestate-lab/app/main.py realestate-lab/tests/test_scheduled_flow.py
+git commit -m "feat(realestate): wire cleanup + notifier into scheduled flow"
+```
+
+---
+
+## Task 9: agent-office 텔레그램 fmt + messaging 헬퍼
+
+청약 매칭 메시지 포맷터(묶음/풀 카드) + 인라인 키보드 빌더 + 송신 헬퍼.
+
+**Files:**
+- Create: `agent-office/app/telegram/realestate_message.py`
+- Create: `agent-office/tests/test_realestate_message.py`
+
+- [ ] **Step 1: 테스트 작성**
+
+`agent-office/tests/test_realestate_message.py`:
+
+```python
+def test_format_realestate_match_full_card_single():
+ from app.telegram.realestate_message import format_realestate_matches
+ matches = [{
+ "id": 1,
+ "match_score": 90,
+ "house_nm": "디에이치 강남",
+ "region_name": "서울특별시",
+ "district": "강남구",
+ "is_speculative_area": "Y",
+ "is_price_cap": "Y",
+ "receipt_start": "2026-05-15",
+ "receipt_end": "2026-05-19",
+ "match_reasons": ["광역 일치", "자치구 S티어: 강남구 (+25)", "예산 범위"],
+ "eligible_types": ["일반1순위", "특별-신혼부부"],
+ "pblanc_url": "https://example.com/p/1",
+ }]
+ text = format_realestate_matches(matches)
+ assert "디에이치 강남" in text
+ assert "90점" in text
+ assert "강남구" in text
+ assert "2026-05-15" in text
+
+
+def test_format_realestate_match_compact_when_three_or_more():
+ from app.telegram.realestate_message import format_realestate_matches
+ matches = [
+ {"id": i, "match_score": 90 - i, "house_nm": f"단지{i}", "district": "강남구",
+ "region_name": "서울특별시", "receipt_start": "2026-05-15", "receipt_end": "2026-05-19",
+ "match_reasons": [], "eligible_types": [], "pblanc_url": ""}
+ for i in range(3)
+ ]
+ text = format_realestate_matches(matches)
+ assert "3건" in text or "3" in text
+ for i in range(3):
+ assert f"단지{i}" in text
+
+
+def test_build_keyboard_single_match_has_bookmark_and_url():
+ from app.telegram.realestate_message import build_match_keyboard
+ matches = [{"id": 42, "pblanc_url": "https://example.com/p/42"}]
+ kb = build_match_keyboard(matches)
+ rows = kb["inline_keyboard"]
+ flat = [b for row in rows for b in row]
+ assert any(b.get("callback_data", "").startswith("realestate_bookmark_42") for b in flat)
+ assert any(b.get("url") == "https://example.com/p/42" for b in flat)
+
+
+def test_build_keyboard_multi_matches_uses_dashboard_link():
+ from app.telegram.realestate_message import build_match_keyboard
+ matches = [{"id": i, "pblanc_url": ""} for i in range(3)]
+ kb = build_match_keyboard(matches)
+ flat = [b for row in kb["inline_keyboard"] for b in row]
+ # 3건 이상이면 [전체 보기] 단일 URL 버튼
+ assert any("전체" in b.get("text", "") for b in flat)
+
+
+def test_build_keyboard_empty_returns_none():
+ from app.telegram.realestate_message import build_match_keyboard
+ assert build_match_keyboard([]) is None
+```
+
+- [ ] **Step 2: 테스트 실행 — 실패 확인**
+
+Run: `cd agent-office && python -m pytest tests/test_realestate_message.py -v`
+Expected: 5 failed (모듈 없음)
+
+- [ ] **Step 3: realestate_message.py 작성**
+
+`agent-office/app/telegram/realestate_message.py`:
+
+```python
+"""청약 매칭 알림 — 텔레그램 메시지 포맷터 + 인라인 키보드 빌더."""
+import os
+from html import escape as _h
+from typing import Optional
+
+DASHBOARD_URL = os.getenv("REALESTATE_DASHBOARD_URL", "https://example.com/realestate")
+
+_TIER_BADGE = {"S": "S", "A": "A", "B": "B", "C": "C", "D": "D"}
+
+
+def _format_one_compact(m: dict) -> str:
+ score = m.get("match_score", 0)
+ name = _h(m.get("house_nm") or "(제목 없음)")
+ district = m.get("district") or ""
+ region = m.get("region_name") or ""
+ where = f"{region.split()[0] if region else ''} {district}".strip() or "위치 미상"
+ rstart = m.get("receipt_start") or ""
+ rend = m.get("receipt_end") or ""
+ return (
+ f"⭐ {score}점 — {name}\n"
+ f"📍 {_h(where)} 📅 {_h(rstart)} ~ {_h(rend)}"
+ )
+
+
+def _format_one_full(m: dict) -> str:
+ score = m.get("match_score", 0)
+ name = _h(m.get("house_nm") or "(제목 없음)")
+ district = m.get("district") or ""
+ region = m.get("region_name") or ""
+ flags = []
+ if m.get("is_speculative_area") == "Y":
+ flags.append("투기과열")
+ if m.get("is_price_cap") == "Y":
+ flags.append("분양가상한제")
+ flag_str = f" ({', '.join(flags)})" if flags else ""
+
+ rstart = m.get("receipt_start") or ""
+ rend = m.get("receipt_end") or ""
+ elig = m.get("eligible_types") or []
+ reasons = m.get("match_reasons") or []
+
+ where = f"{region.split()[0] if region else ''} {district}".strip() or "위치 미상"
+
+ lines = [
+ f"⭐ {score}점 — {name}",
+ f"📍 {_h(where)}{_h(flag_str)}",
+ f"📅 청약 {_h(rstart)} ~ {_h(rend)}",
+ ]
+ if elig:
+ lines.append(f"✓ 자격: {_h(', '.join(elig))}")
+ if reasons:
+ lines.append(f"💡 {_h(' / '.join(reasons[:4]))}")
+ return "\n".join(lines)
+
+
+def format_realestate_matches(matches: list[dict]) -> str:
+ """매칭 목록을 텔레그램 HTML 메시지로 변환.
+ 1~2건은 풀 카드, 3건 이상은 묶음 카드(상위 5건).
+ """
+ if not matches:
+ return "🏢 새 청약 매칭이 없습니다."
+
+ if len(matches) <= 2:
+ body = "\n\n".join(_format_one_full(m) for m in matches)
+ return f"🏢 새 청약 매칭 {len(matches)}건\n━━━━━━━━━━\n\n{body}"
+
+ top = matches[:5]
+ body = "\n\n".join(_format_one_compact(m) for m in top)
+ suffix = f"\n\n…외 {len(matches) - 5}건" if len(matches) > 5 else ""
+ return f"🏢 새 청약 매칭 {len(matches)}건\n━━━━━━━━━━\n\n{body}{suffix}"
+
+
+def build_match_keyboard(matches: list[dict]) -> Optional[dict]:
+ """1~2건: 매치별 [북마크][공고 보기] 행. 3건 이상: [전체 보기] 단일 행."""
+ if not matches:
+ return None
+
+ if len(matches) <= 2:
+ rows = []
+ for m in matches:
+ buttons = [{
+ "text": "🔖 북마크",
+ "callback_data": f"realestate_bookmark_{m['id']}",
+ }]
+ url = m.get("pblanc_url")
+ if url:
+ buttons.append({"text": "📄 공고 보기", "url": url})
+ rows.append(buttons)
+ return {"inline_keyboard": rows}
+
+ return {
+ "inline_keyboard": [[
+ {"text": "📋 전체 보기", "url": DASHBOARD_URL},
+ ]],
+ }
+```
+
+- [ ] **Step 4: 테스트 실행 — 통과 확인**
+
+Run: `cd agent-office && python -m pytest tests/test_realestate_message.py -v`
+Expected: 5 passed
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add agent-office/app/telegram/realestate_message.py agent-office/tests/test_realestate_message.py
+git commit -m "feat(agent-office-telegram): realestate match formatter + keyboard"
+```
+
+---
+
+## Task 10: agent-office RealestateAgent.on_new_matches + endpoint
+
+신규 메소드 추가, endpoint 추가, on_schedule는 폐기 표시(cron 등록 빠지면 호출 안 됨, fetch_matches 명령은 on_new_matches 직접 호출로 단순화).
+
+**Files:**
+- Modify: `agent-office/app/agents/realestate.py`
+- Modify: `agent-office/app/main.py` (endpoint 추가)
+- Test: `agent-office/tests/test_realestate_agent.py`
+
+- [ ] **Step 1: 에이전트 + endpoint 테스트 작성**
+
+`agent-office/tests/test_realestate_agent.py`:
+
+```python
+import os
+import sys
+import tempfile
+
+_TMP = tempfile.mktemp(suffix=".db")
+os.environ["AGENT_OFFICE_DB_PATH"] = _TMP
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+
+import asyncio
+from unittest.mock import AsyncMock, patch
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _init_db():
+ if os.path.exists(_TMP):
+ os.remove(_TMP)
+ from app.db import init_db
+ init_db()
+ yield
+
+
+def test_on_new_matches_returns_empty_when_no_matches():
+ from app.agents.realestate import RealestateAgent
+
+ agent = RealestateAgent()
+ result = asyncio.run(agent.on_new_matches([]))
+ assert result == {"sent": 0, "sent_ids": []}
+
+
+def test_on_new_matches_sends_telegram_and_returns_ids():
+ from app.agents.realestate import RealestateAgent
+ from app.telegram import messaging
+
+ matches = [{
+ "id": 7, "match_score": 80, "house_nm": "단지A",
+ "region_name": "서울특별시", "district": "강남구",
+ "receipt_start": "2026-05-01", "receipt_end": "2026-05-05",
+ "match_reasons": [], "eligible_types": [], "pblanc_url": "https://x.test/7",
+ }]
+
+ fake_send = AsyncMock(return_value={"ok": True, "message_id": 123})
+ with patch.object(messaging, "send_raw", fake_send):
+ agent = RealestateAgent()
+ result = asyncio.run(agent.on_new_matches(matches))
+
+ assert result["sent"] == 1
+ assert result["sent_ids"] == [7]
+ assert result["message_id"] == 123
+ fake_send.assert_awaited_once()
+ args, kwargs = fake_send.call_args
+ text = args[0]
+ assert "단지A" in text
+
+
+def test_on_new_matches_telegram_failure_returns_zero():
+ from app.agents.realestate import RealestateAgent
+ from app.telegram import messaging
+
+ matches = [{
+ "id": 8, "match_score": 80, "house_nm": "단지B",
+ "region_name": "서울", "district": "송파구",
+ "receipt_start": "", "receipt_end": "",
+ "match_reasons": [], "eligible_types": [], "pblanc_url": "",
+ }]
+
+ fake_send = AsyncMock(return_value={"ok": False, "description": "401"})
+ with patch.object(messaging, "send_raw", fake_send):
+ agent = RealestateAgent()
+ result = asyncio.run(agent.on_new_matches(matches))
+
+ assert result["sent"] == 0
+ assert result["sent_ids"] == []
+ assert "error" in result
+
+
+def test_endpoint_calls_agent_on_new_matches():
+ from fastapi.testclient import TestClient
+ from app.main import app
+ from app.agents.realestate import RealestateAgent
+
+ fake = AsyncMock(return_value={"sent": 1, "sent_ids": [99], "message_id": 1})
+ with patch.object(RealestateAgent, "on_new_matches", fake):
+ client = TestClient(app)
+ resp = client.post(
+ "/api/agent-office/realestate/notify",
+ json={"matches": [{"id": 99, "match_score": 80}]},
+ )
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["sent"] == 1
+ assert body["sent_ids"] == [99]
+```
+
+- [ ] **Step 2: 테스트 실행 — 실패 확인**
+
+Run: `cd agent-office && python -m pytest tests/test_realestate_agent.py -v`
+Expected: 4 failed (메소드/endpoint 없음)
+
+- [ ] **Step 3: agents/realestate.py 수정 — on_new_matches 추가, on_schedule 단순화**
+
+`agent-office/app/agents/realestate.py` 전체 파일을 다음 내용으로 교체:
+
+```python
+from .base import BaseAgent
+from ..db import create_task, update_task_status, add_log
+from .. import service_proxy
+from ..telegram import messaging
+from ..telegram.realestate_message import format_realestate_matches, build_match_keyboard
+
+
+class RealestateAgent(BaseAgent):
+ """부동산 청약 에이전트.
+
+ realestate-lab이 신규 매칭 발견 시 /realestate/notify로 push해 트리거됨.
+ on_new_matches가 메인 진입점. on_schedule은 사용하지 않음(cron 폐기).
+ """
+
+ agent_id = "realestate"
+ display_name = "청약 애널리스트"
+
+ async def on_new_matches(self, matches: list[dict]) -> dict:
+ """신규 매칭 N건을 텔레그램 1통으로 푸시.
+ 성공 시 sent_ids 반환 → realestate-lab이 notified_at 마킹.
+ 실패 시 sent=0, sent_ids=[] 반환 → 다음 사이클 재시도.
+ """
+ if not matches:
+ return {"sent": 0, "sent_ids": []}
+
+ task_id = create_task(self.agent_id, "notify_matches", {"count": len(matches)})
+
+ try:
+ text = format_realestate_matches(matches)
+ keyboard = build_match_keyboard(matches)
+ await self.transition("reporting", f"매칭 {len(matches)}건 알림", task_id)
+
+ tg = await messaging.send_raw(text, reply_markup=keyboard)
+ if not tg.get("ok"):
+ update_task_status(task_id, "failed", {"error": tg.get("description")})
+ await self.transition("idle", "알림 실패")
+ return {"sent": 0, "sent_ids": [], "error": tg.get("description")}
+
+ sent_ids = [m["id"] for m in matches if "id" in m]
+ update_task_status(task_id, "succeeded", {
+ "sent": len(matches),
+ "telegram_message_id": tg.get("message_id"),
+ })
+ await self.transition("idle", f"매칭 {len(matches)}건 알림 완료")
+ return {
+ "sent": len(matches),
+ "sent_ids": sent_ids,
+ "message_id": tg.get("message_id"),
+ }
+ except Exception as e:
+ add_log(self.agent_id, f"on_new_matches failed: {e}", "error", task_id)
+ update_task_status(task_id, "failed", {"error": str(e)})
+ await self.transition("idle", f"오류: {e}")
+ return {"sent": 0, "sent_ids": [], "error": str(e)}
+
+ async def on_command(self, command: str, params: dict) -> dict:
+ if command == "fetch_matches":
+ try:
+ matches = await service_proxy.realestate_matches(limit=20)
+ if not matches:
+ return {"ok": True, "message": "매칭 없음"}
+ result = await self.on_new_matches(matches)
+ return {"ok": True, "result": result}
+ except Exception as e:
+ return {"ok": False, "message": str(e)}
+
+ if command == "dashboard":
+ try:
+ data = await service_proxy.realestate_dashboard()
+ return {"ok": True, "dashboard": data}
+ except Exception as e:
+ return {"ok": False, "message": str(e)}
+
+ return {"ok": False, "message": f"Unknown command: {command}"}
+
+ async def on_approval(self, task_id: str, approved: bool, feedback: str = "") -> None:
+ pass
+```
+
+- [ ] **Step 4: main.py에 endpoint 추가**
+
+`agent-office/app/main.py`를 열고 다른 라우트들이 정의된 곳에 다음 endpoint를 추가한다. 정확한 위치는 다른 `/api/agent-office/...` 경로 근처. 만약 RealestateAgent가 registry로 관리된다면 그 패턴을 따르고, 아니면 직접 인스턴스화.
+
+먼저 agent dispatch 패턴을 확인해야 한다. `agent-office/app/main.py`에서 다른 에이전트가 어떻게 호출되는지 본다 (예: stock 에이전트의 명령 처리). 그 패턴에 맞춰 RealestateAgent 인스턴스를 얻고 `on_new_matches` 호출.
+
+다음 엔드포인트를 추가:
+
+```python
+from .agents.realestate import RealestateAgent
+from pydantic import BaseModel
+from typing import List, Dict, Any
+
+
+class RealestateNotifyBody(BaseModel):
+ matches: List[Dict[str, Any]]
+
+
+_realestate_agent_singleton: RealestateAgent | None = None
+
+
+def _get_realestate_agent() -> RealestateAgent:
+ global _realestate_agent_singleton
+ if _realestate_agent_singleton is None:
+ _realestate_agent_singleton = RealestateAgent()
+ return _realestate_agent_singleton
+
+
+@app.post("/api/agent-office/realestate/notify")
+async def realestate_notify(body: RealestateNotifyBody):
+ agent = _get_realestate_agent()
+ return await agent.on_new_matches(body.matches)
+```
+
+> ⚠️ **구현 시 검증**: agent-office가 이미 에이전트 인스턴스 registry/dispatcher를 가지고 있다면 (`agents/__init__.py` 또는 `main.py` 상단), 그 패턴을 따르고 위의 singleton 패턴은 사용하지 않는다. 기존 패턴이 없을 때만 위 코드 그대로 사용. 다른 에이전트(stock/music/lotto)의 인스턴스 관리 방식을 먼저 grep해서 확인할 것: `cd agent-office && grep -rn "StockAgent\|MusicAgent\|LottoAgent" app/main.py app/agents/__init__.py`.
+
+- [ ] **Step 5: 테스트 실행 — 통과 확인**
+
+Run: `cd agent-office && python -m pytest tests/test_realestate_agent.py -v`
+Expected: 4 passed
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add agent-office/app/agents/realestate.py agent-office/app/main.py agent-office/tests/test_realestate_agent.py
+git commit -m "feat(agent-office): realestate on_new_matches + /notify endpoint"
+```
+
+---
+
+## Task 11: agent-office scheduler에서 realestate cron 제거 + 콜백 라우팅
+
+데일리 09:15 cron 등록 제거. 인라인 키보드 콜백(`realestate_bookmark_*`)을 텔레그램 webhook에서 처리해 realestate-lab으로 프록시.
+
+**Files:**
+- Modify: `agent-office/app/scheduler.py`
+- Modify: `agent-office/app/telegram/webhook.py` (또는 callback 라우팅 위치)
+- Modify: `agent-office/app/service_proxy.py` (북마크 토글 헬퍼 추가)
+
+- [ ] **Step 1: scheduler에서 realestate cron 제거**
+
+`agent-office/app/scheduler.py`를 열어 realestate 관련 add_job 호출을 찾는다 (예: `realestate_agent.on_schedule` 등록부). 해당 라인을 제거하고 import도 정리.
+
+찾는 패턴 예시:
+```python
+scheduler.add_job(realestate_agent.on_schedule, "cron", hour=9, minute=15, id="realestate_daily")
+```
+
+이 라인과 관련 import를 삭제한다. 만약 RealestateAgent import가 다른 곳에서 안 쓰이면 import도 함께 제거.
+
+- [ ] **Step 2: 콜백 핸들러 위치 확인**
+
+Run: `cd agent-office && grep -rn "callback_query\|callback_data" app/telegram/`
+
+다음을 확인:
+- `webhook.py` 또는 `router.py`에서 `callback_query`를 받아 처리하는 함수
+- 현재 패턴(예: `approve_*`, `reject_*` 콜백 처리 방식)
+
+- [ ] **Step 3: service_proxy에 북마크 토글 추가**
+
+`agent-office/app/service_proxy.py` 끝에 추가:
+
+```python
+async def realestate_bookmark_toggle(announcement_id: int) -> dict:
+ """realestate-lab의 PATCH /api/realestate/announcements/{id}/bookmark 호출."""
+ url = f"{REALESTATE_LAB_URL}/api/realestate/announcements/{announcement_id}/bookmark"
+ async with httpx.AsyncClient(timeout=10) as client:
+ resp = await client.patch(url)
+ resp.raise_for_status()
+ return resp.json()
+```
+
+(상단의 `REALESTATE_LAB_URL`, `httpx` import는 이미 service_proxy에 있을 것이므로 신규 환경변수만 docker-compose의 agent-office 환경에 노출. 만약 없다면 다음 라인을 service_proxy 상단에 추가:)
+
+```python
+REALESTATE_LAB_URL = os.getenv("REALESTATE_LAB_URL", "http://realestate-lab:8000")
+```
+
+- [ ] **Step 4: 콜백 라우팅에 realestate_bookmark 처리 추가**
+
+webhook 또는 router의 `callback_query` 디스패처에 다음 분기를 추가 (정확한 함수명은 step 2에서 확인한 위치에 맞춤):
+
+```python
+if data.startswith("realestate_bookmark_"):
+ try:
+ ann_id = int(data.removeprefix("realestate_bookmark_"))
+ except ValueError:
+ return {"ok": False, "message": "잘못된 콜백 데이터"}
+ try:
+ await service_proxy.realestate_bookmark_toggle(ann_id)
+ await messaging.send_raw(f"🔖 북마크 토글 완료 (#{ann_id})")
+ return {"ok": True}
+ except Exception as e:
+ await messaging.send_raw(f"⚠️ 북마크 실패: {e}")
+ return {"ok": False, "error": str(e)}
+```
+
+> ⚠️ **위치 적응 필요**: step 2에서 확인한 콜백 디스패처의 기존 분기 스타일에 맞춰 통합. 기존 분기가 `if data.startswith("approve_"): ... elif data.startswith("reject_"): ...` 라면 `elif`로 추가.
+
+- [ ] **Step 5: 콜백 라우팅 단위 테스트**
+
+`agent-office/tests/test_realestate_callback.py`:
+
+```python
+import os
+import sys
+import tempfile
+from unittest.mock import AsyncMock, patch
+
+_TMP = tempfile.mktemp(suffix=".db")
+os.environ["AGENT_OFFICE_DB_PATH"] = _TMP
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+
+def test_callback_realestate_bookmark_calls_proxy():
+ """callback_data 'realestate_bookmark_42' 가 service_proxy.realestate_bookmark_toggle(42) 를 호출."""
+ import asyncio
+ from app import service_proxy
+ from app.telegram import webhook # 실제 모듈명에 맞춰 수정 필요
+
+ fake = AsyncMock(return_value={"ok": True})
+ with patch.object(service_proxy, "realestate_bookmark_toggle", fake):
+ # webhook의 callback dispatcher를 직접 호출. 정확한 함수 시그니처는 step 2 확인 결과로 채움.
+ # 예시: await webhook.handle_callback({"data": "realestate_bookmark_42", ...})
+ result = asyncio.run(webhook.handle_callback({"data": "realestate_bookmark_42", "from": {"id": 1}, "id": "cb1"}))
+
+ fake.assert_awaited_once_with(42)
+```
+
+> ⚠️ **테스트 시그니처 적응**: step 2에서 확인한 콜백 핸들러의 정확한 함수명·인자에 맞춰 수정. 이 테스트는 realistic stub이며 실제 webhook 모듈 구조에 맞게 업데이트해야 통과.
+
+- [ ] **Step 6: 회귀 검증**
+
+Run: `cd agent-office && python -m pytest tests/ -v`
+Expected: 모든 기존 테스트 통과 + 신규 추가분 통과
+
+- [ ] **Step 7: 커밋**
+
+```bash
+git add agent-office/app/scheduler.py agent-office/app/telegram/ agent-office/app/service_proxy.py agent-office/tests/test_realestate_callback.py
+git commit -m "feat(agent-office): drop daily realestate cron + bookmark callback routing"
+```
+
+---
+
+## Task 12: docker-compose 환경변수 + 통합 검증
+
+`AGENT_OFFICE_URL`을 realestate-lab 환경에 추가, `REALESTATE_LAB_URL`이 agent-office에 없으면 추가.
+
+**Files:**
+- Modify: `docker-compose.yml`
+- Modify: `.env.example`
+
+- [ ] **Step 1: docker-compose.yml의 realestate-lab 서비스에 AGENT_OFFICE_URL 추가**
+
+`docker-compose.yml`에서 `realestate-lab` 서비스 정의를 찾고, `environment:` 블록에 추가:
+
+```yaml
+ realestate-lab:
+ # ... 기존
+ environment:
+ # ... 기존
+ AGENT_OFFICE_URL: http://agent-office:8000
+```
+
+- [ ] **Step 2: docker-compose.yml의 agent-office 서비스에 REALESTATE_LAB_URL 추가 (없는 경우)**
+
+agent-office 서비스 environment에:
+
+```yaml
+ agent-office:
+ # ... 기존
+ environment:
+ # ... 기존
+ REALESTATE_LAB_URL: http://realestate-lab:8000
+ REALESTATE_DASHBOARD_URL: ${REALESTATE_DASHBOARD_URL:-http://localhost:8080/realestate}
+```
+
+- [ ] **Step 3: .env.example에 신규 변수 명시**
+
+`.env.example` 파일 끝에 추가 (이미 있는 변수와 중복 없는지 확인):
+
+```bash
+# 청약 알림 — agent-office push
+AGENT_OFFICE_URL=http://agent-office:8000
+REALESTATE_LAB_URL=http://realestate-lab:8000
+REALESTATE_DASHBOARD_URL=http://localhost:8080/realestate
+REALESTATE_NOTIFY_TIMEOUT=15
+```
+
+- [ ] **Step 4: 두 서비스 전체 회귀 검증**
+
+Run:
+```bash
+cd realestate-lab && python -m pytest tests/ -v
+cd ../agent-office && python -m pytest tests/ -v
+```
+
+Expected: 모든 테스트 통과
+
+- [ ] **Step 5: 운영 배포 sanity check (수동, 선택)**
+
+NAS 배포 후 (`git push`로 자동), 다음 시나리오 수동 검증:
+
+1. `PUT /api/realestate/profile` body에 `preferred_districts`/`min_match_score`/`notify_enabled` 포함하여 저장 → 200, 응답에 새 필드 반영
+2. `POST /api/realestate/collect` 트리거 → 수집 후 `GET /api/realestate/announcements?region=서울` 시 `district` 필드 포함, `완료` 공고 없음
+3. 매칭 점수 70점 이상이고 미알림인 매치 1건 이상 존재 시 → 텔레그램에 메시지 도착, 인라인 키보드 표시
+4. 텔레그램 [🔖 북마크] 클릭 → realestate-lab의 `is_bookmarked` 토글 확인
+5. `notify_enabled=false`로 변경 후 `POST /collect` → 텔레그램 푸시 미발생
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add docker-compose.yml .env.example
+git commit -m "chore(deploy): wire realestate↔agent-office URLs for push notify"
+```
+
+---
+
+## 완료 기준
+
+- 모든 task의 테스트 통과 (`realestate-lab/tests/`, `agent-office/tests/`)
+- 회귀 없이 기존 endpoint 동작 유지
+- 매칭 점수 모델: 35 + 10 + 15 + 15 + 25 = 100점 일관
+- realestate-lab 09:00 cron이 `collect → cleanup → match → notify` 순으로 동작
+- agent-office 09:15 데일리 cron 제거됨
+- 텔레그램에 신규 매칭 알림 + 인라인 키보드 동작
+- `match_results.notified_at` 멱등 마킹
+
+---
+
+## 참고 — 후속 별도 plan
+
+- `web-ui` 프론트 자치구 5티어 입력 UI (별도 frontend plan)
+- 청약 가점 vs 공고별 예상 커트라인 비교 (외부 데이터 의존성 연구)
+- 서울 외 광역(부산 해운대구 등) 자치구 파싱 확장
+- `POST /notifications/resend` (임계값 변경 후 재발송)
+- 자치구별 매칭 분포 대시보드 위젯