# TOOLS.md - Local Notes

가계부 관련 파일·스크립트·발신번호 메모. 모든 경로는 `agents/budget/workspace/` 기준.

## Whooing

- 가계부 시스템: https://whooing.com
- **웹훅 URL:** `/Users/snowoyh/.openclaw/credentials/whooing.json` 의 `webhook_url` 필드.
  형식: `https://whooing.com/webhook/s/xxxx-xxxx-xxxx-xxxx`
- 웹훅 페이로드 종류:
  - **raw 문자**: `message=<원문>` 보내면 후잉이 알아서 파싱
  - **구조화 JSON**: `{entry_date, item, money, left, right, memo}` (left=차변, right=대변)
- 결제 취소/승인취소도 같이 전송해야 후잉에서 -금액으로 상쇄됨.

## State

- `state/whooing_synced.json` — `{ "last_message_at": <ISO>, "last_synced_at": "ISO" }`. dedupe 기준.
- `state/whooing_account_map.json` — 발신번호 → 후잉 매핑. `confirmed: true`인 엔트리만 후잉으로 자동 전송. `confirmed: false`는 발견 시 로그만 남기고 사용자 확인 대기.
- `state/whooing_accounts.json` — **관리자님 후잉 계정과목 차트** (자산/부채/순자산/비용/수익 + carrier→결제수단 매핑). 구조화 입력으로 left/right 채울 때 항상 이 파일에서 정확한 계정명을 끌어쓴다. 차트에 없는 계정명은 후잉이 거부하므로 절대 추측해 보내지 말 것.
- `state/whooing_failures.json` — 후잉이 4xx/5xx로 거절한 건. 수동 확인용.

## Scripts (python3)

- `skills/whooing-sync/scripts/whooing_sync.py` — iMessage 결제문자 → 후잉 웹훅 POST. launchd `ai.openclaw.budget.whooing-sync` 가 매시 0/15/30/45분 실행 (OpenClaw cron 아님). ⚠️ **on-demand 실행은 스크립트 직접 호출이 아니라 `launchctl kickstart -p gui/$(id -u)/ai.openclaw.budget.whooing-sync` + 로그 확인** — 내 세션은 게이트웨이 node 를 TCC responsible process 로 물고 있어 `imsg` 가 Messages DB 를 못 읽는다. FDA 필수(`/opt/homebrew/bin/imsg`). 페어 매칭 로직 내장 — 자세한 건 `skills/whooing-sync/SKILL.md`.
- `skills/whooing-sync/scripts/imsg_cli.py` — `imsg` CLI 공용 래퍼(`run_json`/`chats`). stderr·returncode 를 판정해 FDA 누락을 파싱 에러로 둔갑시키지 않는다. `whooing_sync.py`·`gahee_reminder.py` 가 공유.
- `skills/whooing-sync/scripts/whooing_manual.py` — iMessage 없이 한 건 직접 등록. structured(`--item/--money/--left/--right [--date] [--memo]`) 또는 raw(`--message`). structured는 `whooing_accounts.json` 차트 검증 후 POST.
- `skills/whooing-sync/scripts/whooing_balance.py` — 후잉 OpenAPI로 자산/부채/자본 잔액 조회. 옵션: `--section-id`, `--as-of YYYY-MM-DD`, `--json`. 크리덴셜은 `credentials/whooing.json`의 `api` 블록(app_id/token/signature).

## 발신번호

`state/whooing_account_map.json`이 정답. 아래는 사람이 읽기 쉬운 요약.

**확인됨 (관리자님이 직접 확인):**

| 발신처 | 발신번호 |
|--------|---------|
| 하나 계좌이체 | `+8215991111` |
| 신한은행 | `+8215778000` |
| 신한카드 | `+8215447000` (※ 과거 오타 `+8215447200` 쓴 적 있음 — 실사용 X, 현재 confirmed=false 로 대기) |

**추정 (모델 사전지식 기반, 실제 메시지 들어오면 confirmed로 승격 필요):**

| 발신처 | 추정 발신번호 |
|--------|--------------|
| 삼성카드 | `+8215888900` |
| KB국민카드 | `+8215881688` |
| 현대카드 | `+8215776200` |
| 롯데카드 | `+8215888100` |
| 하나카드 | `+8218001111` |
| 우리카드 | `+8215889955` |
| BC카드 | `+8215884000` |
| NH농협카드 | `+8216444000` |
| 카카오페이 | `+8216447405` |
| 네이버페이 | `+8215883819` |
| 토스 | `+8215994905` |
| KB국민은행 | `+8215889999` |
| 우리은행 | `+8215885000` |
| NH농협은행 | `+8216613000` |
| 카카오뱅크 | `+8215993333` |

**정책:** 미확인 번호 메시지가 들어오면 무시 또는 `failures.json`에 "unmapped"로 기록만 한다. 잘못된 자동 등록을 막기 위함.

## 관리자님 관련

- 가계부 질문이 들어오면 먼저 `state/whooing_synced.json`과 `whooing_failures.json`을 본다.
- 잔액·계정 총합은 `whooing_balance.py`로 조회한다. 후잉 OpenAPI(`bs.json`/`accounts.json`/`sections.json`) 연동 완료.

## Playwright MCP (브라우저 자동화)

OpenClaw가 `openclaw.json` 의 MCP 서버 `playwright`로 노출. 도구는 `playwright__browser_*` prefix로 약 23개.

- **탐색:** `navigate / navigate_back / tabs / wait_for`
- **관찰:** `snapshot` (접근성 트리 — 클릭 대상 ref 식별에 **우선 사용**) / `take_screenshot` / `console_messages` / `network_requests` / `network_request`
- **조작:** `click / type / fill_form / press_key / hover / select_option / drag / drop / file_upload / handle_dialog / resize / close`
- **평가:** `evaluate` (페이지 JS 컨텍스트) / `run_code_unsafe` (Playwright 코드 직접 — **RCE 등급, 마지막 수단**)

**표준 흐름:** `navigate` → `snapshot`으로 ref 확보 → `click`/`type`/`fill_form` → `wait_for`로 결과 대기 → `snapshot` 또는 `network_requests`로 검증. 스크린샷은 사람 보고용이지 다음 동작 분기 근거로 쓰지 말 것.

**운영 특성:**
- 기본값 `--headless --isolated`. 매 세션 쿠키·로그인 폐기.
- 영속 로그인 필요한 사이트는 시도 전 **코디에게 `user-data-dir` 분리·등록 요청**.
- 첫 호출 시 npx spawn 1~2초 지연.
- 은행·카드사 공동인증서·간편비밀번호 화면이 나오면 **즉시 중단하고 관리자님께 보고**, 우회 시도 X.

**활용 시나리오 (골디 맥락):**
- 후잉 웹 직접 분개 수정/삭제 — 현재 inbox·webhook 단방향 한계 보완용. **영속 로그인 필요** → 코디에게 user-data-dir 분리 요청 후 진행
- 카드사 웹 청구서 PDF 수집 (월별 명세 검증·보조). 공동인증서·간편비번 화면 진입 시 중단
- 우선순위는 항상 **API · iMessage 결제문자 → 후잉 webhook 자동 동기화**. 브라우저는 자동 흐름이 못 메꾸는 잔여 영역만
