feat(naver-fetch): 스캐폴딩 + config

2026-07-10 10:21:03 +09:00
parent 9abca3eeab
commit 6b0e91342c
8 changed files with 1205 additions and 0 deletions
--- a/services/naver-fetch/PLAN.md
+++ b/services/naver-fetch/PLAN.md
@@ -0,0 +1,979 @@
+# naver-fetch 워커 구현 계획
+
+> **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:** 네이버 매물을 가정 IP에서 fetch해 NAS로 전달하는 `naver-fetch` 워커를 구현한다 — Playwright로 Bearer 토큰 획득 → httpx로 동별 article fetch → NAS `listings-ingest`로 raw 전달 + heartbeat.
+
+**Architecture:** FastAPI + asyncio 워커(trade-monitor·insta-render 관례). `naver_client`가 Playwright(토큰)+httpx(fetch)를 캡슐화, `fetch_worker`가 2~3h 주간 스케줄로 오케스트레이션. 얇은 프록시(파싱은 NAS). heartbeat는 fetcher 전용 스키마(epoch ts).
+
+**Tech Stack:** Python 3.12, FastAPI, playwright==1.48.0(async, chromium), httpx(async), redis.asyncio, pytest + pytest-asyncio + respx. WSL2 Docker.
+
+**설계 원본:** `services/naver-fetch/DESIGN.md` · 권위 계약: web-backend `realestate-lab/docs/superpowers/specs/2026-07-09-naver-listing-worker-design.md`.
+
+## Global Constraints
+
+- Python `3.12`, `playwright==1.48.0` (async API, chromium).
+- **얇은 프록시** — raw article 그대로 전달, 파싱/매칭/알림/dedup은 NAS.
+- 인증: `.env` `INTERNAL_API_KEY` → `X-Internal-Key` 헤더(render 워커 공유키). (스펙 §config의 `REALESTATE_INTERNAL_KEY`와 상충 — BE 메시지 우선, 배포 전 확인.)
+- heartbeat 키 `worker:naver-fetch:heartbeat`, TTL **EX45**, kind `fetcher`, **epoch ts**: `{name,kind,state:idle|fetching,ts,last_fetch_at,listings_pushed,errors}`.
+- ingest `fetched_at`은 **ISO UTC 문자열**(`YYYY-MM-DDTHH:MM:SSZ`).
+- 스케줄: 주간창(기본 08:00~20:00 KST) 안에서 `FETCH_INTERVAL_HOURS`(기본 2.5) 간격.
+- 테스트 실행: `C:\Users\jaeoh\AppData\Local\Programs\Python\Python312\python.exe -m pytest services/naver-fetch/tests -q` (web-ai 루트). 이하 `python` = 이 경로.
+- 커밋: **web-ai repo에서만**. Docker 포트 **18716**.
+- Spike 검증됨(2026-07-10): Playwright 토큰 인터셉트 + httpx `/api/articles` 200 + articleList.
+
+---
+
+## File Structure
+
+| 파일 | 책임 |
+|------|------|
+| `services/naver-fetch/config.py` | `Settings` + `load_settings()` |
+| `services/naver-fetch/nas_client.py` | `NASClient`: get_targets / post_ingest (X-Internal-Key) |
+| `services/naver-fetch/naver_client.py` | `NaverClient`: acquire_token(Playwright) + fetch_articles(httpx) |
+| `services/naver-fetch/fetch_worker.py` | `FetchState`, `in_daytime`, `run_cycle`, `fetch_loop`, `build_heartbeat`, `heartbeat_loop` |
+| `services/naver-fetch/main.py` | FastAPI lifespan + `/health` |
+| `services/naver-fetch/conftest.py` | services/ 루트 sys.path |
+| `services/naver-fetch/tests/*` | 단위 테스트 |
+| `services/naver-fetch/Dockerfile` | Playwright 베이스(insta-render 관례) + `_shared` |
+| `services/naver-fetch/requirements.txt`, `.env.example`, `pytest.ini` | |
+| `services/docker-compose.yml` (수정) | `naver-fetch` 서비스(18716) |
+
+---
+
+### Task 1: 스캐폴딩 + config
+
+**Files:**
+- Create: `services/naver-fetch/requirements.txt`, `conftest.py`, `pytest.ini`, `tests/__init__.py`, `config.py`
+- Test: `services/naver-fetch/tests/test_config.py`
+
+**Interfaces:**
+- Produces: `Settings` dataclass fields `nas_base_url:str, internal_api_key:str, redis_url:str, fetch_interval_hours:float, daytime_start:str, daytime_end:str, naver_real_estate_type:str, naver_token_url:str, naver_headless:bool`. `load_settings() -> Settings`.
+
+- [ ] **Step 1: 스캐폴딩**
+
+`services/naver-fetch/requirements.txt`:
+```
+fastapi==0.115.6
+uvicorn[standard]==0.34.0
+playwright==1.48.0
+redis>=5.0
+httpx>=0.27
+pytest>=8.0
+pytest-asyncio>=0.24
+respx>=0.21
+```
+
+`services/naver-fetch/conftest.py`:
+```python
+"""services/ 루트를 sys.path에 추가 — from _shared... import 가능하게."""
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+```
+
+`services/naver-fetch/pytest.ini`:
+```
+[pytest]
+asyncio_mode = auto
+```
+
+`services/naver-fetch/tests/__init__.py`: (빈 파일)
+
+- [ ] **Step 2: 실패 테스트** — `services/naver-fetch/tests/test_config.py`
+
+```python
+"""Settings env 로드."""
+from config import load_settings
+
+
+def test_defaults(monkeypatch):
+    for k in ("NAS_BASE_URL", "INTERNAL_API_KEY", "REDIS_URL", "FETCH_INTERVAL_HOURS",
+              "DAYTIME_START", "DAYTIME_END", "NAVER_REAL_ESTATE_TYPE",
+              "NAVER_TOKEN_URL", "NAVER_HEADLESS"):
+        monkeypatch.delenv(k, raising=False)
+    s = load_settings()
+    assert s.nas_base_url == "http://192.168.45.54:18500"
+    assert s.fetch_interval_hours == 2.5
+    assert s.daytime_start == "08:00" and s.daytime_end == "20:00"
+    assert s.naver_headless is True
+    assert "new.land.naver.com" in s.naver_token_url
+
+
+def test_override(monkeypatch):
+    monkeypatch.setenv("INTERNAL_API_KEY", "sekret")
+    monkeypatch.setenv("FETCH_INTERVAL_HOURS", "3")
+    monkeypatch.setenv("NAVER_HEADLESS", "0")
+    s = load_settings()
+    assert s.internal_api_key == "sekret"
+    assert s.fetch_interval_hours == 3.0
+    assert s.naver_headless is False
+```
+
+- [ ] **Step 3: 실패 확인**
+
+Run: `python -m pytest services/naver-fetch/tests/test_config.py -q`
+Expected: FAIL — `ModuleNotFoundError: No module named 'config'`
+
+- [ ] **Step 4: config.py 구현**
+
+```python
+"""Settings — 환경변수 로드."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+_DEFAULT_TOKEN_URL = (
+    "https://new.land.naver.com/houses?ms=37.489,126.921,16&a=APT:ABYG:JGC:PRE&e=RETAIL"
+)
+
+
+@dataclass
+class Settings:
+    nas_base_url: str
+    internal_api_key: str
+    redis_url: str
+    fetch_interval_hours: float
+    daytime_start: str
+    daytime_end: str
+    naver_real_estate_type: str
+    naver_token_url: str
+    naver_headless: bool
+
+
+def load_settings() -> Settings:
+    return Settings(
+        nas_base_url=os.getenv("NAS_BASE_URL", "http://192.168.45.54:18500"),
+        internal_api_key=os.getenv("INTERNAL_API_KEY", ""),
+        redis_url=os.getenv("REDIS_URL", "redis://192.168.45.54:6379"),
+        fetch_interval_hours=float(os.getenv("FETCH_INTERVAL_HOURS", "2.5")),
+        daytime_start=os.getenv("DAYTIME_START", "08:00"),
+        daytime_end=os.getenv("DAYTIME_END", "20:00"),
+        naver_real_estate_type=os.getenv("NAVER_REAL_ESTATE_TYPE", "APT:ABYG:JGC:PRE"),
+        naver_token_url=os.getenv("NAVER_TOKEN_URL", _DEFAULT_TOKEN_URL),
+        naver_headless=os.getenv("NAVER_HEADLESS", "1") == "1",
+    )
+```
+
+- [ ] **Step 5: 통과 확인**
+
+Run: `python -m pytest services/naver-fetch/tests/test_config.py -q`
+Expected: PASS (2 passed)
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add services/naver-fetch/requirements.txt services/naver-fetch/conftest.py services/naver-fetch/pytest.ini services/naver-fetch/tests/__init__.py services/naver-fetch/config.py services/naver-fetch/tests/test_config.py services/naver-fetch/DESIGN.md services/naver-fetch/PLAN.md
+git commit -m "feat(naver-fetch): 스캐폴딩 + config"
+```
+
+---
+
+### Task 2: nas_client
+
+**Files:**
+- Create: `services/naver-fetch/nas_client.py`
+- Test: `services/naver-fetch/tests/test_nas_client.py`
+
+**Interfaces:**
+- Produces `NASClient`:
+  - `__init__(base_url, api_key, timeout=15.0)`
+  - `async get_targets() -> dict` (GET `/api/internal/realestate/targets`)
+  - `async post_ingest(fetched_at: str, batches: list[dict]) -> dict` (POST `/api/internal/realestate/listings-ingest`)
+  - `async close()`
+
+- [ ] **Step 1: 실패 테스트** — `services/naver-fetch/tests/test_nas_client.py`
+
+```python
+"""NASClient — targets/ingest + X-Internal-Key (respx)."""
+import json as _json
+
+import httpx
+import respx
+
+from nas_client import NASClient
+
+BASE = "http://nas.test"
+
+
+@respx.mock
+async def test_get_targets_sends_key():
+    route = respx.get(f"{BASE}/api/internal/realestate/targets").mock(
+        return_value=httpx.Response(200, json={
+            "dongs": [{"dong": "신대방동", "cortar_no": "1159010100"}],
+            "deal_types": ["전세", "매매"], "page_limit": 2}))
+    c = NASClient(BASE, "KEY")
+    tg = await c.get_targets()
+    assert tg["page_limit"] == 2
+    assert tg["dongs"][0]["cortar_no"] == "1159010100"
+    assert route.calls.last.request.headers["X-Internal-Key"] == "KEY"
+    await c.close()
+
+
+@respx.mock
+async def test_post_ingest_payload():
+    captured = {}
+
+    def _resp(request):
+        captured.update(_json.loads(request.content))
+        return httpx.Response(200, json={"received": 3, "new": 2, "matched": 1})
+
+    respx.post(f"{BASE}/api/internal/realestate/listings-ingest").mock(side_effect=_resp)
+    c = NASClient(BASE, "KEY")
+    batches = [{"dong": "신대방동", "articles": [{"articleNo": "1"}, {"articleNo": "2"}]}]
+    out = await c.post_ingest("2026-07-10T05:00:00Z", batches)
+    assert out == {"received": 3, "new": 2, "matched": 1}
+    assert captured["fetched_at"] == "2026-07-10T05:00:00Z"
+    assert captured["batches"] == batches
+    await c.close()
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python -m pytest services/naver-fetch/tests/test_nas_client.py -q`
+Expected: FAIL — `ModuleNotFoundError: No module named 'nas_client'`
+
+- [ ] **Step 3: nas_client.py 구현**
+
+```python
+"""NAS realestate 내부 계약 — X-Internal-Key + retry."""
+from __future__ import annotations
+
+import asyncio
+import logging
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+_MAX_ATTEMPTS = 3
+_RETRY_STATUSES = {429, 500, 502, 503, 504}
+
+
+class NASClient:
+    def __init__(self, base_url: str, api_key: str, timeout: float = 15.0):
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._client = httpx.AsyncClient(timeout=timeout)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def get_targets(self) -> dict:
+        return await self._request("GET", "/api/internal/realestate/targets")
+
+    async def post_ingest(self, fetched_at: str, batches: list[dict]) -> dict:
+        return await self._request(
+            "POST", "/api/internal/realestate/listings-ingest",
+            json={"fetched_at": fetched_at, "batches": batches})
+
+    async def _request(self, method: str, path: str, **kwargs) -> dict:
+        url = f"{self._base_url}{path}"
+        headers = {"X-Internal-Key": self._api_key}
+        for attempt in range(_MAX_ATTEMPTS):
+            try:
+                resp = await self._client.request(method, url, headers=headers, **kwargs)
+                if resp.status_code in _RETRY_STATUSES and attempt < _MAX_ATTEMPTS - 1:
+                    await asyncio.sleep(2 ** attempt)
+                    continue
+                resp.raise_for_status()
+                return resp.json()
+            except httpx.TimeoutException:
+                if attempt < _MAX_ATTEMPTS - 1:
+                    await asyncio.sleep(2 ** attempt)
+                    continue
+                raise
+        raise RuntimeError("retry exhausted")
+```
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python -m pytest services/naver-fetch/tests/test_nas_client.py -q`
+Expected: PASS (2 passed)
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add services/naver-fetch/nas_client.py services/naver-fetch/tests/test_nas_client.py
+git commit -m "feat(naver-fetch): NAS realestate 클라이언트 (targets/ingest)"
+```
+
+---
+
+### Task 3: naver_client (Playwright 토큰 + httpx fetch)
+
+**Files:**
+- Create: `services/naver-fetch/naver_client.py`
+- Test: `services/naver-fetch/tests/test_naver_client.py`
+
+**Interfaces:**
+- Produces `NaverClient`:
+  - `__init__(real_estate_type: str, token_url: str, headless: bool = True, timeout: float = 20.0)`
+  - `async acquire_token() -> None` — Playwright로 `self._token`(Bearer str), `self._cookies`(str) 설정. 실패 시 `RuntimeError`. (실브라우저 — 단위테스트 제외, spike/첫운영 검증)
+  - `async fetch_articles(cortar_no: str, page: int = 1) -> dict` — httpx GET, raw JSON dict. 토큰 없으면 `RuntimeError`.
+  - `async close()`
+
+- [ ] **Step 1: 실패 테스트** — `services/naver-fetch/tests/test_naver_client.py`
+
+```python
+"""NaverClient.fetch_articles — httpx 경로 (respx). acquire_token은 실브라우저라 제외."""
+import httpx
+import pytest
+import respx
+
+from naver_client import NaverClient
+
+API = "https://new.land.naver.com/api/articles"
+
+
+def _client():
+    return NaverClient(real_estate_type="APT:ABYG", token_url="https://x", headless=True)
+
+
+async def test_fetch_requires_token():
+    c = _client()
+    with pytest.raises(RuntimeError):
+        await c.fetch_articles("1159010100", 1)
+    await c.close()
+
+
+@respx.mock
+async def test_fetch_articles_request_and_parse():
+    captured = {}
+
+    def _resp(request):
+        captured["auth"] = request.headers.get("authorization")
+        captured["cookie"] = request.headers.get("cookie")
+        captured["url"] = str(request.url)
+        return httpx.Response(200, json={
+            "isMoreData": True,
+            "articleList": [{"articleNo": "111", "articleName": "테스트아파트"}]})
+
+    respx.get(API).mock(side_effect=_resp)
+    c = _client()
+    c._token = "Bearer TESTJWT"          # acquire_token 우회(단위테스트)
+    c._cookies = "NNB=abc; page_uid=xyz"
+    out = await c.fetch_articles("1159010100", page=2)
+    assert out["articleList"][0]["articleNo"] == "111"
+    assert captured["auth"] == "Bearer TESTJWT"
+    assert captured["cookie"] == "NNB=abc; page_uid=xyz"
+    assert "cortarNo=1159010100" in captured["url"]
+    assert "page=2" in captured["url"]
+    assert "realEstateType=APT" in captured["url"]
+    await c.close()
+
+
+@respx.mock
+async def test_fetch_non_200_raises():
+    respx.get(API).mock(return_value=httpx.Response(429, json={"code": "TOO_MANY_REQUESTS"}))
+    c = _client()
+    c._token = "Bearer X"
+    with pytest.raises(httpx.HTTPStatusError):
+        await c.fetch_articles("1159010100", 1)
+    await c.close()
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python -m pytest services/naver-fetch/tests/test_naver_client.py -q`
+Expected: FAIL — `ModuleNotFoundError: No module named 'naver_client'`
+
+- [ ] **Step 3: naver_client.py 구현**
+
+```python
+"""Naver land client — Playwright 토큰 획득 + httpx article fetch."""
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+_UA = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+       "(KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36")
+_API = "https://new.land.naver.com/api/articles"
+
+
+class NaverClient:
+    def __init__(self, real_estate_type: str, token_url: str,
+                 headless: bool = True, timeout: float = 20.0):
+        self._ret = real_estate_type
+        self._token_url = token_url
+        self._headless = headless
+        self._client = httpx.AsyncClient(timeout=timeout)
+        self._token: str | None = None
+        self._cookies: str = ""
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def acquire_token(self) -> None:
+        """new.land.naver.com 로드 → XHR Authorization 헤더 인터셉트."""
+        from playwright.async_api import async_playwright
+
+        captured: dict[str, str] = {}
+        async with async_playwright() as p:
+            browser = await p.chromium.launch(headless=self._headless)
+            try:
+                ctx = await browser.new_context(user_agent=_UA, locale="ko-KR")
+                page = await ctx.new_page()
+
+                def on_request(req):
+                    auth = req.headers.get("authorization")
+                    if auth and "bearer" in auth.lower() and "auth" not in captured:
+                        captured["auth"] = auth
+
+                page.on("request", on_request)
+                try:
+                    await page.goto(self._token_url, wait_until="networkidle", timeout=45000)
+                except Exception:
+                    logger.warning("naver token goto 지연/부분 실패 — 캡처 계속")
+                await page.wait_for_timeout(4000)
+                cookies = await ctx.cookies()
+                self._cookies = "; ".join(f"{c['name']}={c['value']}" for c in cookies)
+            finally:
+                await browser.close()
+
+        token = captured.get("auth")
+        if not token:
+            raise RuntimeError("naver Bearer token 획득 실패")
+        self._token = token
+        logger.info("naver token 획득 (len=%d)", len(token))
+
+    async def fetch_articles(self, cortar_no: str, page: int = 1) -> dict:
+        if not self._token:
+            raise RuntimeError("token 없음 — acquire_token 먼저 호출")
+        params = {
+            "cortarNo": cortar_no, "order": "rank", "realEstateType": self._ret,
+            "tradeType": "", "rentPriceMin": 0, "rentPriceMax": 900000000,
+            "priceMin": 0, "priceMax": 900000000, "areaMin": 0, "areaMax": 900000000,
+            "showArticle": "false", "sameAddressGroup": "false",
+            "priceType": "RETAIL", "page": page,
+        }
+        headers = {
+            "authorization": self._token, "user-agent": _UA,
+            "referer": "https://new.land.naver.com/",
+            "accept": "application/json, text/plain, */*",
+            "accept-language": "ko-KR,ko;q=0.9", "cookie": self._cookies,
+        }
+        resp = await self._client.get(_API, params=params, headers=headers)
+        resp.raise_for_status()
+        return resp.json()
+```
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python -m pytest services/naver-fetch/tests/test_naver_client.py -q`
+Expected: PASS (3 passed)
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add services/naver-fetch/naver_client.py services/naver-fetch/tests/test_naver_client.py
+git commit -m "feat(naver-fetch): NaverClient (Playwright 토큰 + httpx fetch)"
+```
+
+---
+
+### Task 4: fetch_worker (오케스트레이션 + heartbeat)
+
+**Files:**
+- Create: `services/naver-fetch/fetch_worker.py`
+- Test: `services/naver-fetch/tests/test_fetch_worker.py`
+
+**Interfaces:**
+- Consumes: `NASClient`, `NaverClient`, `config.Settings`.
+- Produces:
+  - `class FetchState` — `.state="idle"`, `.last_fetch_at=None`, `.listings_pushed=0`, `.errors=0`
+  - `in_daytime(now: datetime, start: str, end: str) -> bool`
+  - `async run_cycle(nas, naver, state, settings) -> None`
+  - `async fetch_loop(nas, naver, state, settings) -> None`
+  - `build_heartbeat(state) -> str` (JSON)
+  - `async heartbeat_loop(redis, state, interval=15, ttl=45) -> None`
+
+- [ ] **Step 1: 실패 테스트** — `services/naver-fetch/tests/test_fetch_worker.py`
+
+```python
+"""fetch_worker — 주간창/조립/격리/heartbeat."""
+import datetime as dt
+import json
+from zoneinfo import ZoneInfo
+
+from fetch_worker import FetchState, in_daytime, run_cycle, build_heartbeat
+from config import load_settings
+
+KST = ZoneInfo("Asia/Seoul")
+
+
+def _kst(hh, mm):
+    return dt.datetime(2026, 7, 10, hh, mm, tzinfo=KST)
+
+
+def test_in_daytime_boundaries():
+    assert in_daytime(_kst(8, 0), "08:00", "20:00") is True
+    assert in_daytime(_kst(19, 59), "08:00", "20:00") is True
+    assert in_daytime(_kst(20, 0), "08:00", "20:00") is False
+    assert in_daytime(_kst(7, 59), "08:00", "20:00") is False
+
+
+class _FakeNAS:
+    def __init__(self, targets):
+        self._targets = targets
+        self.ingested = None
+
+    async def get_targets(self):
+        return self._targets
+
+    async def post_ingest(self, fetched_at, batches):
+        self.ingested = {"fetched_at": fetched_at, "batches": batches}
+        return {"received": sum(len(b["articles"]) for b in batches), "new": 1, "matched": 1}
+
+
+class _FakeNaver:
+    def __init__(self, fail_dongs=None):
+        self._fail = fail_dongs or set()
+        self.token_acquired = False
+
+    async def acquire_token(self):
+        self.token_acquired = True
+
+    async def fetch_articles(self, cortar_no, page=1):
+        if cortar_no in self._fail:
+            raise RuntimeError("naver 429")
+        return {"isMoreData": False,
+                "articleList": [{"articleNo": f"{cortar_no}-{page}"}]}
+
+
+async def test_run_cycle_assembles_batches_and_ingests():
+    nas = _FakeNAS({"dongs": [{"dong": "신대방동", "cortar_no": "1159010100"},
+                              {"dong": "봉천동", "cortar_no": "1162010100"}],
+                    "deal_types": ["매매"], "page_limit": 1})
+    naver = _FakeNaver()
+    state = FetchState()
+    await run_cycle(nas, naver, state, load_settings())
+    assert naver.token_acquired is True
+    assert nas.ingested is not None
+    dongs = [b["dong"] for b in nas.ingested["batches"]]
+    assert dongs == ["신대방동", "봉천동"]
+    assert state.listings_pushed == 2
+    assert state.last_fetch_at is not None
+    assert state.state == "idle"
+    assert nas.ingested["fetched_at"].endswith("Z")
+
+
+async def test_run_cycle_dong_failure_isolated():
+    nas = _FakeNAS({"dongs": [{"dong": "A", "cortar_no": "1159010100"},
+                              {"dong": "B", "cortar_no": "1162010100"}],
+                    "page_limit": 1})
+    naver = _FakeNaver(fail_dongs={"1159010100"})
+    state = FetchState()
+    await run_cycle(nas, naver, state, load_settings())
+    assert nas.ingested is not None            # 실패해도 ingest 진행
+    assert state.errors >= 1
+    batches = {b["dong"]: b["articles"] for b in nas.ingested["batches"]}
+    assert batches["A"] == []                   # 실패 동 빈 배열
+    assert len(batches["B"]) == 1               # 성공 동
+
+
+async def test_run_cycle_token_failure_skips_ingest():
+    class _BadNaver(_FakeNaver):
+        async def acquire_token(self):
+            raise RuntimeError("token 실패")
+
+    nas = _FakeNAS({"dongs": [], "page_limit": 1})
+    state = FetchState()
+    await run_cycle(nas, _BadNaver(), state, load_settings())
+    assert nas.ingested is None
+    assert state.errors == 1
+    assert state.state == "idle"
+
+
+def test_build_heartbeat_schema():
+    state = FetchState()
+    state.state = "fetching"
+    state.listings_pushed = 7
+    d = json.loads(build_heartbeat(state))
+    assert d["name"] == "naver-fetch"
+    assert d["kind"] == "fetcher"
+    assert d["state"] == "fetching"
+    assert isinstance(d["ts"], int)
+    assert d["last_fetch_at"] is None
+    assert d["listings_pushed"] == 7
+    assert d["errors"] == 0
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python -m pytest services/naver-fetch/tests/test_fetch_worker.py -q`
+Expected: FAIL — `ModuleNotFoundError: No module named 'fetch_worker'`
+
+- [ ] **Step 3: fetch_worker.py 구현**
+
+```python
+"""오케스트레이션 — 주간 스케줄 fetch + fetcher heartbeat."""
+from __future__ import annotations
+
+import asyncio
+import datetime as dt
+import json
+import logging
+from zoneinfo import ZoneInfo
+
+logger = logging.getLogger(__name__)
+KST = ZoneInfo("Asia/Seoul")
+HEARTBEAT_KEY = "worker:naver-fetch:heartbeat"
+
+
+class FetchState:
+    """fetch_loop가 갱신, heartbeat_loop가 읽는 공유 상태."""
+    def __init__(self):
+        self.state = "idle"                 # idle | fetching
+        self.last_fetch_at: int | None = None
+        self.listings_pushed = 0
+        self.errors = 0
+
+
+def _parse_hhmm(s: str) -> dt.time:
+    hh, mm = s.split(":")
+    return dt.time(int(hh), int(mm))
+
+
+def in_daytime(now: dt.datetime, start: str, end: str) -> bool:
+    t = now.timetz().replace(tzinfo=None)
+    return _parse_hhmm(start) <= t < _parse_hhmm(end)
+
+
+def _epoch_now() -> int:
+    return int(dt.datetime.now(dt.timezone.utc).timestamp())
+
+
+def _iso_utc_now() -> str:
+    return dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+async def run_cycle(nas, naver, state, settings) -> None:
+    state.state = "fetching"
+    try:
+        await naver.acquire_token()
+    except Exception:
+        logger.exception("naver 토큰 획득 실패")
+        state.errors += 1
+        state.state = "idle"
+        return
+    try:
+        tg = await nas.get_targets()
+    except Exception:
+        logger.exception("targets 조회 실패")
+        state.errors += 1
+        state.state = "idle"
+        return
+
+    dongs = tg.get("dongs", [])
+    page_limit = int(tg.get("page_limit", 1))
+    batches: list[dict] = []
+    for d in dongs:
+        cortar = d.get("cortar_no")
+        dong = d.get("dong")
+        articles: list[dict] = []
+        try:
+            for page in range(1, page_limit + 1):
+                resp = await naver.fetch_articles(cortar, page)
+                articles += resp.get("articleList", [])
+                if not resp.get("isMoreData"):
+                    break
+        except Exception:
+            logger.exception("naver fetch 실패 dong=%s", dong)
+            state.errors += 1
+        batches.append({"dong": dong, "articles": articles})
+
+    fetched_at = _iso_utc_now()
+    try:
+        r = await nas.post_ingest(fetched_at, batches)
+        logger.info("ingest received=%s new=%s matched=%s",
+                    r.get("received"), r.get("new"), r.get("matched"))
+    except Exception:
+        logger.exception("listings-ingest 실패")
+        state.errors += 1
+        state.state = "idle"
+        return
+
+    state.listings_pushed += sum(len(b["articles"]) for b in batches)
+    state.last_fetch_at = _epoch_now()
+    state.state = "idle"
+
+
+async def fetch_loop(nas, naver, state, settings) -> None:
+    interval = dt.timedelta(hours=settings.fetch_interval_hours)
+    last_run: dt.datetime | None = None
+    logger.info("naver-fetch loop 시작 interval=%.1fh 주간창 %s-%s",
+                settings.fetch_interval_hours, settings.daytime_start, settings.daytime_end)
+    while True:
+        try:
+            now = dt.datetime.now(KST)
+            if in_daytime(now, settings.daytime_start, settings.daytime_end) and (
+                    last_run is None or (now - last_run) >= interval):
+                await run_cycle(nas, naver, state, settings)
+                last_run = now
+        except asyncio.CancelledError:
+            logger.info("fetch_loop cancelled")
+            raise
+        except Exception:
+            logger.exception("fetch_loop iteration 실패")
+        await asyncio.sleep(300)
+
+
+def build_heartbeat(state) -> str:
+    return json.dumps({
+        "name": "naver-fetch", "kind": "fetcher", "state": state.state,
+        "ts": _epoch_now(), "last_fetch_at": state.last_fetch_at,
+        "listings_pushed": state.listings_pushed, "errors": state.errors,
+    })
+
+
+async def heartbeat_loop(redis, state, interval: int = 15, ttl: int = 45) -> None:
+    logger.info("naver-fetch heartbeat 시작 ttl=%ds", ttl)
+    while True:
+        try:
+            await redis.set(HEARTBEAT_KEY, build_heartbeat(state), ex=ttl)
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            logger.exception("heartbeat 발신 실패")
+        await asyncio.sleep(interval)
+```
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python -m pytest services/naver-fetch/tests/test_fetch_worker.py -q`
+Expected: PASS (5 passed)
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add services/naver-fetch/fetch_worker.py services/naver-fetch/tests/test_fetch_worker.py
+git commit -m "feat(naver-fetch): fetch_worker (run_cycle/loop/heartbeat)"
+```
+
+---
+
+### Task 5: main.py (FastAPI lifespan + /health)
+
+**Files:**
+- Create: `services/naver-fetch/main.py`
+- Test: `services/naver-fetch/tests/test_health.py`
+
+**Interfaces:**
+- Consumes: `config.load_settings`, `NASClient`, `NaverClient`, `fetch_worker.*`, `redis.asyncio`.
+- Produces: FastAPI `app` + `health()` → `{"ok": True, "service": "naver-fetch"}`.
+
+- [ ] **Step 1: 실패 테스트** — `services/naver-fetch/tests/test_health.py`
+
+```python
+"""/health — 핸들러 직접 검증."""
+from main import health
+
+
+def test_health():
+    assert health() == {"ok": True, "service": "naver-fetch"}
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python -m pytest services/naver-fetch/tests/test_health.py -q`
+Expected: FAIL — `ModuleNotFoundError: No module named 'main'`
+
+- [ ] **Step 3: main.py 구현**
+
+```python
+"""naver-fetch FastAPI entry — lifespan(fetch_loop + heartbeat_loop) + /health."""
+from __future__ import annotations
+
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+
+import redis.asyncio as aioredis
+from fastapi import FastAPI
+
+import fetch_worker
+from config import load_settings
+from nas_client import NASClient
+from naver_client import NaverClient
+
+logging.basicConfig(level=logging.INFO,
+                    format="%(asctime)s %(name)s %(levelname)s %(message)s")
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    settings = load_settings()
+    nas = NASClient(settings.nas_base_url, settings.internal_api_key)
+    naver = NaverClient(settings.naver_real_estate_type, settings.naver_token_url,
+                        settings.naver_headless)
+    state = fetch_worker.FetchState()
+    redis = aioredis.from_url(settings.redis_url, decode_responses=False)
+
+    ft = asyncio.create_task(fetch_worker.fetch_loop(nas, naver, state, settings))
+    hb = asyncio.create_task(fetch_worker.heartbeat_loop(redis, state))
+    logger.info("naver-fetch lifespan 시작")
+    try:
+        yield
+    finally:
+        for t in (ft, hb):
+            t.cancel()
+            try:
+                await t
+            except asyncio.CancelledError:
+                pass
+        await naver.close()
+        await nas.close()
+        await redis.aclose()
+        logger.info("naver-fetch lifespan 종료")
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+@app.get("/health")
+def health():
+    return {"ok": True, "service": "naver-fetch"}
+```
+
+- [ ] **Step 4: 통과 확인 + 전체 스위트**
+
+Run: `python -m pytest services/naver-fetch/tests -q`
+Expected: PASS (config 2 + nas 2 + naver 3 + fetch_worker 5 + health 1 = 13)
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add services/naver-fetch/main.py services/naver-fetch/tests/test_health.py
+git commit -m "feat(naver-fetch): FastAPI lifespan + heartbeat 배선 + /health"
+```
+
+---
+
+### Task 6: 배포 (Dockerfile + compose + .env.example)
+
+**Files:**
+- Create: `services/naver-fetch/Dockerfile`, `services/naver-fetch/.env.example`
+- Modify: `services/docker-compose.yml`
+
+**Interfaces:** 없음(배포). 검증 `docker compose config`.
+
+- [ ] **Step 1: Dockerfile** — `services/naver-fetch/Dockerfile` (insta-render Chromium 관례 복제)
+
+```dockerfile
+FROM python:3.12-slim-bookworm
+ENV PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+# Chromium 런타임 deps (Debian 12 / bookworm) — insta-render 관례
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates tzdata fonts-noto-cjk \
+    libnss3 libnspr4 libdbus-1-3 libatk1.0-0 libatk-bridge2.0-0 \
+    libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 \
+    libxfixes3 libxrandr2 libgbm1 libxshmfence1 libpango-1.0-0 \
+    libcairo2 libasound2 libatspi2.0-0 \
+ && rm -rf /var/lib/apt/lists/*
+
+COPY naver-fetch/requirements.txt /app/
+RUN pip install --no-cache-dir --timeout 600 --retries 5 -r requirements.txt
+RUN playwright install chromium
+
+# 공통 heartbeat 등 모듈 (services/_shared) — 빌드 컨텍스트 . 필요
+COPY _shared /app/_shared
+COPY naver-fetch/. /app/
+ENV PYTHONPATH=/app
+
+EXPOSE 8000
+CMD ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "1"]
+```
+
+- [ ] **Step 2: .env.example** — `services/naver-fetch/.env.example`
+
+```
+# naver-fetch — realestate 매물 fetch 워커
+
+REDIS_URL=redis://192.168.45.54:6379
+NAS_BASE_URL=http://192.168.45.54:18500
+# render 워커 공유키 (X-Internal-Key)
+INTERNAL_API_KEY=
+
+# 스케줄 (KST)
+FETCH_INTERVAL_HOURS=2.5
+DAYTIME_START=08:00
+DAYTIME_END=20:00
+
+# 네이버
+NAVER_REAL_ESTATE_TYPE=APT:ABYG:JGC:PRE
+NAVER_HEADLESS=1
+# NAVER_TOKEN_URL=  # 기본값(new.land.naver.com houses) 사용
+```
+
+- [ ] **Step 3: docker-compose.yml에 서비스 추가**
+
+`services/docker-compose.yml`의 `trade-monitor` 블록 뒤(파일 끝, 들여쓰기 2칸)에 추가:
+
+```yaml
+  naver-fetch:
+    build:
+      context: .
+      dockerfile: naver-fetch/Dockerfile
+    container_name: naver-fetch
+    restart: unless-stopped
+    ports:
+      - "18716:8000"
+    environment:
+      - TZ=Asia/Seoul
+      - REDIS_URL=${REDIS_URL:-redis://192.168.45.54:6379}
+      - NAS_BASE_URL=${NAS_BASE_URL:-http://192.168.45.54:18500}
+      - INTERNAL_API_KEY=${INTERNAL_API_KEY:-}
+      - FETCH_INTERVAL_HOURS=${FETCH_INTERVAL_HOURS:-2.5}
+      - DAYTIME_START=${DAYTIME_START:-08:00}
+      - DAYTIME_END=${DAYTIME_END:-20:00}
+      - NAVER_REAL_ESTATE_TYPE=${NAVER_REAL_ESTATE_TYPE:-APT:ABYG:JGC:PRE}
+      - NAVER_HEADLESS=${NAVER_HEADLESS:-1}
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
+      interval: 60s
+      timeout: 5s
+      retries: 3
+```
+
+- [ ] **Step 4: compose 검증**
+
+Run: `cd services && docker compose config` (실패 시 YAML 들여쓰기 육안 확인)
+Expected: `naver-fetch` 서비스 파싱, 포트 18716.
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add services/naver-fetch/Dockerfile services/naver-fetch/.env.example services/docker-compose.yml
+git commit -m "feat(naver-fetch): Dockerfile(Playwright) + compose 서비스(18716) + .env.example"
+```
+
+---
+
+## Self-Review
+
+**1. Spec coverage:**
+- §4 `GET /targets` → Task 2 `get_targets` + Task 4 사용. ✅
+- §4 `POST /listings-ingest`(fetched_at ISO, batches) → Task 2 `post_ingest` + Task 4 조립. ✅
+- §4.4 heartbeat(EX45, kind=fetcher, epoch ts, 필드) → Task 4 `build_heartbeat`/`heartbeat_loop`. ✅
+- 워커 루프(targets→네이버 fetch→ingest) → Task 4 `run_cycle`. ✅
+- 네이버 Bearer 토큰(Playwright) + fetch → Task 3. ✅
+- 스케줄(주간 2~3h) → Task 4 `in_daytime` + `fetch_loop`. ✅
+- 얇은 프록시(raw 전달) → Task 4(파싱 없음, articleList 그대로). ✅
+- 배포(_shared COPY, Playwright, 18716) → Task 6. ✅
+
+**2. Placeholder scan:** 실제 코드/명령/기대출력 기재. TODO 없음. ✅
+
+**3. Type consistency:** `FetchState`(state/last_fetch_at/listings_pushed/errors)가 Task 4 생성 ↔ `build_heartbeat` 소비 일치. `NaverClient`(acquire_token/fetch_articles) Task 3 정의 ↔ Task 4 `run_cycle` 호출 일치. `NASClient`(get_targets/post_ingest) Task 2 ↔ Task 4 일치. fetched_at ISO 문자열/heartbeat ts epoch 구분 유지. ✅
+
+**미해결 플래그(DESIGN §11):** INTERNAL_API_KEY vs REALESTATE_INTERNAL_KEY(배포 전 BE 확인), 헤드리스 탐지, deal_types 미사용(NAS 필터), 토큰 만료 재획득.