#!/usr/bin/env python3
"""키움증권 REST API 클라이언트 — READ-ONLY.

⚠️ 매매 절대 원칙 (변경 금지)
이 모듈은 조회 전용입니다. 매수·매도·정정·취소 등 주문성 함수를 절대 추가하지 마십시오.
관련 가드: agent SOUL.md "매매 절대 원칙" 섹션, MEMORY: kiwoom_read_only.md.
워치리스트 도달 등 트리거가 발생해도 동작은 텔레그램 알림(별도 모듈)까지만입니다.

자격증명: /Users/snowoyh/.openclaw/credentials/kiwoom.json
계좌 라벨: '일반', 'ISA', '가희_일반', '가희_ISA' — 각 계좌마다 별도 appkey/secretkey 사용.
신규 계좌 추가 시 `<이름>_<상품>` 컨벤션을 유지해야 owner 그룹 prefix 분기가 자동 동작 (리포트의 본인/가희 블록).
"""
from __future__ import annotations

import json
import sys
import threading
import time
import urllib.request
from datetime import datetime, timezone, timedelta
from pathlib import Path

KST = timezone(timedelta(hours=9))

CREDENTIALS = Path('/Users/snowoyh/.openclaw/credentials/kiwoom.json')
WORKSPACE = Path('/Users/snowoyh/.openclaw/agents/stock/workspace')
STATE_DIR = WORKSPACE / 'state'
TOKEN_CACHE_DIR = STATE_DIR / 'kiwoom_tokens'

ENDPOINT_TOKEN = '/oauth2/token'
ENDPOINT_ACNT = '/api/dostk/acnt'
ENDPOINT_STKINFO = '/api/dostk/stkinfo'
ENDPOINT_MRKCOND = '/api/dostk/mrkcond'  # 시세(market condition) — ka10004 호가 등
ENDPOINT_CHART = '/api/dostk/chart'      # 차트 — ka10081 일봉
TR_DEPOSIT = 'kt00001'       # 예수금상세현황요청
TR_ACNT_EVAL = 'kt00004'     # 계좌평가현황요청 (acnt_nm·brch_nm 포함)
TR_TRUST_TRADE = 'kt00015'   # 위탁종합거래내역요청 (tp='1' 입출금 — 당일 추가입금/인출 추출용)
TR_POSITIONS = 'kt00018'     # 계좌평가잔고내역요청 (종목별 상세, 수수료·세금 포함)
TR_TRADE_DIARY = 'ka10170'   # 당일매매일지요청 (round-trip·풀매도 포함, 잔고에 없는 거래도 잡힘)
TR_ORDER_EXEC = 'kt00007'    # 계좌별주문체결내역상세 (주문번호·시각·체결가·체결수량 단위, REST/영웅문 출처 구분)
TR_OPEN_ORDERS = 'ka10075'   # 미체결요청 (활성 미체결만 — 정정/취소 대상 추출용)
TR_STOCK_INFO = 'ka10001'    # 주식기본정보요청 (현재가·등락률) — 단일 종목
TR_WATCHLIST_INFO = 'ka10095'  # 관심종목정보요청 — 다종목 한번에 (`|` 구분, 19종목 0.05s)
TR_STOCK_LIST = 'ka10099'    # 종목정보 리스트 (종목코드·명 전체)
TR_DAILY_CHART = 'ka10081'   # 주식일봉차트조회 (수정주가 포함, 600일치까지)
TR_MINUTE_CHART = 'ka10080'  # 주식분봉차트조회 (1/3/5/10/15/30/45/60분, 한 호출 ~900봉)
TR_INVESTOR_FLOW = 'ka10059' # 종목별투자자기관별 (외국인·기관 일별 매매)

STOCK_CODES_CACHE = STATE_DIR / 'stock_codes.json'


def load_credentials() -> dict:
    if not CREDENTIALS.exists():
        raise SystemExit(
            f'자격증명 파일 없음: {CREDENTIALS}\n'
            f'kiwoom.json.example 복사해서 채우세요.'
        )
    return json.loads(CREDENTIALS.read_text())


def save_credentials(creds: dict) -> None:
    CREDENTIALS.write_text(json.dumps(creds, ensure_ascii=False, indent=2))


def get_account_creds(label: str) -> dict:
    creds = load_credentials()
    accounts = creds.get('accounts', {})
    if label not in accounts:
        raise KeyError(f'알 수 없는 계좌 라벨: {label}. 등록된 라벨: {list(accounts)}')
    return accounts[label]


def base_url() -> str:
    return load_credentials().get('base_url', 'https://api.kiwoom.com').rstrip('/')


def _http_post_json(url: str, body: dict, headers: dict | None = None) -> dict:
    return _http_post_full(url, body, headers)[0]


def _http_post_full(url: str, body: dict, headers: dict | None = None) -> tuple[dict, dict]:
    """POST + return (json body, response headers dict)."""
    data = json.dumps(body).encode('utf-8')
    h = {'Content-Type': 'application/json;charset=UTF-8'}
    if headers:
        h.update(headers)
    req = urllib.request.Request(url, data=data, method='POST', headers=h)
    try:
        with urllib.request.urlopen(req, timeout=15) as r:
            resp_headers = {k.lower(): v for k, v in r.headers.items()}
            return json.loads(r.read().decode('utf-8', 'ignore')), resp_headers
    except urllib.error.HTTPError as e:
        body_text = e.read().decode('utf-8', 'ignore')
        raise RuntimeError(f'HTTP {e.code} {url}: {body_text}') from e


def _token_cache_path(label: str) -> Path:
    return TOKEN_CACHE_DIR / f'{label}.json'


_TOKEN_LOCKS: dict[str, threading.Lock] = {}
_TOKEN_LOCKS_GUARD = threading.Lock()
# force=True 발급 직후 1초 이내에 같은 label로 다시 force 호출이 들어오면 직전 토큰을 reuse.
# behive_web 페이지 로드 시 4계좌 × 다중 TR 병렬 호출 → 한 호출이 8005 받고 force 재발급한 직후
# 다른 thread가 또 force 재발급하면서 키움이 새 토큰 invalidate 시키는 race를 차단.
_FORCE_REUSE_WINDOW_SEC = 1.0


def _label_lock(label: str) -> threading.Lock:
    with _TOKEN_LOCKS_GUARD:
        lock = _TOKEN_LOCKS.get(label)
        if lock is None:
            lock = threading.Lock()
            _TOKEN_LOCKS[label] = lock
        return lock


def issue_token(label: str, force: bool = False) -> str:
    """OAuth 토큰 발급 + 캐싱. 계좌(라벨) 단위로 분리 저장."""
    cache_path = _token_cache_path(label)
    if not force and cache_path.exists():
        cache = json.loads(cache_path.read_text())
        if cache.get('expires_at', 0) - 60 > time.time():
            return cache['access_token']

    with _label_lock(label):
        if cache_path.exists():
            cache = json.loads(cache_path.read_text())
            valid = cache.get('expires_at', 0) - 60 > time.time()
            if valid:
                if not force:
                    return cache['access_token']
                # force=True여도, 직전 N초 이내 다른 thread가 이미 새로 발급했다면 그걸 재사용.
                if time.time() - cache.get('issued_at_ts', 0) < _FORCE_REUSE_WINDOW_SEC:
                    return cache['access_token']

        acc = get_account_creds(label)
        url = base_url() + ENDPOINT_TOKEN
        body = {
            'grant_type': 'client_credentials',
            'appkey': acc['appkey'],
            'secretkey': acc['secretkey'],
        }
        resp = _http_post_json(url, body)
        token = resp.get('token') or resp.get('access_token')
        expires_dt = resp.get('expires_dt')
        expires_in = resp.get('expires_in')
        if not token:
            raise RuntimeError(f'토큰 발급 실패 ({label}): {resp}')
        if expires_dt:
            try:
                dt = datetime.strptime(expires_dt, '%Y%m%d%H%M%S').replace(tzinfo=KST)
                expires_at = dt.timestamp()
            except ValueError:
                expires_at = time.time() + 1800
        elif expires_in:
            expires_at = time.time() + int(expires_in)
        else:
            expires_at = time.time() + 1800
        now_ts = time.time()
        cache_path.parent.mkdir(parents=True, exist_ok=True)
        cache_path.write_text(json.dumps({
            'label': label,
            'access_token': token,
            'expires_at': expires_at,
            'issued_at': datetime.now(KST).isoformat(),
            'issued_at_ts': now_ts,
            'raw': resp,
        }, ensure_ascii=False, indent=2))
        return token


def auth_headers(label: str, tr_id: str | None = None, cont_yn: str = 'N', next_key: str = '') -> dict:
    """인증·TR 헤더 생성. tr_id는 키움 API ID (예: 'kt00018')."""
    h = {
        'Authorization': f'Bearer {issue_token(label)}',
        'Content-Type': 'application/json;charset=UTF-8',
        'cont-yn': cont_yn,
        'next-key': next_key,
    }
    if tr_id:
        h['api-id'] = tr_id
    return h


def list_accounts() -> list[dict]:
    """credentials에 등록된 계좌 목록 (라벨, 계좌번호) 반환."""
    creds = load_credentials()
    return [
        {'label': label, 'account_no': info.get('account_no', '')}
        for label, info in creds.get('accounts', {}).items()
    ]


def _to_int(s) -> int:
    """키움 응답의 zero-padded string → int. 빈 값은 0."""
    if s is None or s == '':
        return 0
    s = str(s).strip()
    neg = s.startswith('-')
    if neg:
        s = s[1:]
    s = s.lstrip('0') or '0'
    return -int(s) if neg else int(s)


def _to_float(s) -> float:
    if s is None or s == '':
        return 0.0
    return float(str(s).strip())


def _clean_code(s: str) -> str:
    """'A005930' → '005930'. 'A' 접두 제거."""
    s = (s or '').strip()
    return s[1:] if s.startswith('A') else s


def _call(label: str, tr_id: str, body: dict, endpoint: str = ENDPOINT_ACNT) -> dict:
    url = base_url() + endpoint
    resp = _http_post_json(url, body, auth_headers(label, tr_id=tr_id))
    if resp.get('return_code', 0) == 0:
        return resp

    msg = str(resp.get('return_msg') or '')
    if '8005' in msg or 'Token이 유효하지 않습니다' in msg:
        issue_token(label, force=True)
        resp = _http_post_json(url, body, auth_headers(label, tr_id=tr_id))
        if resp.get('return_code', 0) == 0:
            return resp

    raise RuntimeError(f'{tr_id} [{label}] 실패: {resp.get("return_msg")} (full={resp})')


def _call_paginated(label: str, tr_id: str, body: dict, list_field: str,
                     endpoint: str = ENDPOINT_ACNT, max_pages: int = 50) -> dict:
    """list 응답이 페이지로 나뉘어 올 수 있는 TR 호출 (cont-yn/next-key 헤더 페이징).

    명세상 모든 list 반환 TR 응답에 `cont-yn`/`next-key` 헤더 정의됨 — 데이터 많으면 'Y'로
    떨어져 다음 페이지 요청 필요. _call은 1페이지만 받으니 종목·거래 많은 계좌에서 누락 위험.

    동작:
    - 첫 페이지를 받아 base 응답으로 두고, 후속 페이지의 `list_field` 만 누적 합치기.
    - 헤더 외 본문 필드(`tot_*` 합계 등)는 첫 페이지 값 유지 — 키움이 합계를 마지막 페이지에만
      넣을 가능성도 있어 위험하지만, 현재 명세 example 보면 합계는 매 페이지 동일하게 옴.
    - max_pages 안전 cap (무한루프 방지).
    - 8005 토큰 만료는 첫 페이지에서만 자동 재시도 (이후 페이지는 토큰 안정 가정).
    """
    url = base_url() + endpoint
    cont_yn = 'N'
    next_key = ''
    base: dict | None = None
    for page in range(max_pages):
        headers = auth_headers(label, tr_id=tr_id, cont_yn=cont_yn, next_key=next_key)
        resp, resp_headers = _http_post_full(url, body, headers)
        if resp.get('return_code', 0) != 0:
            msg = str(resp.get('return_msg') or '')
            if page == 0 and ('8005' in msg or 'Token이 유효하지 않습니다' in msg):
                issue_token(label, force=True)
                headers = auth_headers(label, tr_id=tr_id, cont_yn=cont_yn, next_key=next_key)
                resp, resp_headers = _http_post_full(url, body, headers)
                if resp.get('return_code', 0) != 0:
                    raise RuntimeError(f'{tr_id} [{label}] 실패: {resp.get("return_msg")}')
            else:
                raise RuntimeError(f'{tr_id} [{label}] page={page} 실패: {resp.get("return_msg")}')
        if base is None:
            base = resp
            base.setdefault(list_field, [])
        else:
            base[list_field].extend(resp.get(list_field) or [])
        cy = (resp_headers.get('cont-yn') or '').strip().upper()
        nk = (resp_headers.get('next-key') or '').strip()
        if cy == 'Y' and nk:
            cont_yn = 'Y'
            next_key = nk
            time.sleep(0.15)
        else:
            return base
    raise RuntimeError(f'{tr_id} [{label}] 페이지 한도({max_pages}) 초과')


# ---- 조회 함수 ----

def get_balance(account_label: str) -> dict:
    """예수금·주문가능금액 등 (kt00001)."""
    resp = _call(account_label, TR_DEPOSIT, {'qry_tp': '3'})
    return {
        'label': account_label,
        'entr': _to_int(resp.get('entr')),                   # 예수금
        'd1_entra': _to_int(resp.get('d1_entra')),           # D+1 예수금
        'd2_entra': _to_int(resp.get('d2_entra')),           # D+2 예수금
        'ord_alow_amt': _to_int(resp.get('ord_alow_amt')),   # 주문가능금액
        'pymn_alow_amt': _to_int(resp.get('pymn_alow_amt')), # 출금가능금액
        'repl_amt': _to_int(resp.get('repl_amt')),           # 대용금
        'raw': resp,
    }


def get_account_summary(account_label: str) -> dict:
    """계좌평가현황 (kt00004) — 고객명·지점·추정총자산 포함."""
    resp = _call(account_label, TR_ACNT_EVAL, {'qry_tp': '0', 'dmst_stex_tp': 'KRX'})
    return {
        'label': account_label,
        'acnt_nm': resp.get('acnt_nm', ''),
        'brch_nm': resp.get('brch_nm', ''),
        'entr': _to_int(resp.get('entr')),
        'd2_entra': _to_int(resp.get('d2_entra')),
        'tot_est_amt': _to_int(resp.get('tot_est_amt')),         # 추정총자산
        'aset_evlt_amt': _to_int(resp.get('aset_evlt_amt')),     # 자산평가액
        'tot_pur_amt': _to_int(resp.get('tot_pur_amt')),         # 총매입금액
        'prsm_dpst_aset_amt': _to_int(resp.get('prsm_dpst_aset_amt')),  # 추정예탁자산
        'raw': resp,
    }


def get_positions(account_label: str, exchange: str = 'KRX') -> list[dict]:
    """보유종목 목록 (kt00018).

    exchange='KRX': 한국거래소 종가 기준 (잔고 평가 표준).
    exchange='NXT': NXT 우선 가격 (NXT 운영시간 8:00~20:00에 살아 움직임). NXT 미상장 종목은 KRX fallback.
    `cur_prc`·`evlt_amt`·`evltv_prft`·`prft_rt`는 키움 서버에서 해당 거래소 가격으로 재계산되어 반환.
    """
    resp = _call_paginated(account_label, TR_POSITIONS,
                            {'qry_tp': '1', 'dmst_stex_tp': exchange},
                            list_field='acnt_evlt_remn_indv_tot')
    items = resp.get('acnt_evlt_remn_indv_tot', []) or []
    out: list[dict] = []
    for it in items:
        qty = _to_int(it.get('rmnd_qty'))
        if qty == 0:
            continue
        cur_price = _to_int(it.get('cur_prc'))
        pred_close = _to_int(it.get('pred_close_pric'))
        day_change = cur_price - pred_close if pred_close else 0
        day_change_pct = (day_change / pred_close * 100) if pred_close else 0.0
        out.append({
            'code': _clean_code(it.get('stk_cd', '')),
            'name': it.get('stk_nm', ''),
            'qty': qty,
            'trde_able_qty': _to_int(it.get('trde_able_qty')),
            'avg_price': _to_int(it.get('pur_pric')),        # 매입평단
            'cur_price': cur_price,
            'pred_close_pric': pred_close,                   # 전일종가
            'day_change': day_change,                        # 당일 등락 (원)
            'day_change_pct': day_change_pct,                # 당일 등락률 (%)
            'pur_amt': _to_int(it.get('pur_amt')),
            'evlt_amt': _to_int(it.get('evlt_amt')),
            'evltv_prft': _to_int(it.get('evltv_prft')),     # 평가손익
            'prft_rt': _to_float(it.get('prft_rt')),         # 수익률 %
            'poss_rt': _to_float(it.get('poss_rt')),         # 보유비중 %
            'tdy_buyq': _to_int(it.get('tdy_buyq')),
            'tdy_sellq': _to_int(it.get('tdy_sellq')),
        })
    out.sort(key=lambda x: x['evlt_amt'], reverse=True)
    return out


def get_positions_all(exchange: str = 'KRX', labels: list[str] | None = None) -> dict:
    """모든 계좌 종목 조회 — {label: [positions]} 반환. exchange는 get_positions와 동일.
    labels 지정 시 해당 라벨만 순회 (owner 단위 부분 갱신용 — behive_web 자동 갱신이 활용)."""
    accs = list_accounts()
    if labels is not None:
        wanted = set(labels)
        accs = [a for a in accs if a['label'] in wanted]
    return {a['label']: get_positions(a['label'], exchange=exchange) for a in accs}


def get_trade_journal(account_label: str, base_dt: str | None = None) -> list[dict]:
    """당일매매일지 (ka10170) — 잔고에 없는 round-trip·풀매도 거래까지 포함.

    base_dt: YYYYMMDD (None이면 KST 오늘).
    ottks_tp='2' (당일매도 전체 — 보유분 매도 포함). '1'은 round-trip만 잡혀 pl_amt=0이 됨 (2026-05-07 사고).
    ch_crd_tp='0'(현금/신용 전체) 고정.
    빈 응답은 stk_cd가 ''인 placeholder 1건이 옴 — 필터링.
    """
    if base_dt is None:
        base_dt = datetime.now(KST).strftime('%Y%m%d')
    body = {'base_dt': base_dt, 'ottks_tp': '2', 'ch_crd_tp': '0'}
    resp = _call_paginated(account_label, TR_TRADE_DIARY, body, list_field='tdy_trde_diary')
    items = resp.get('tdy_trde_diary') or []
    out: list[dict] = []
    for it in items:
        code = _clean_code(it.get('stk_cd', ''))
        name = (it.get('stk_nm') or '').strip()
        if not code or not name:
            continue  # 빈 placeholder
        out.append({
            'code': code,
            'name': name,
            'buy_qty': _to_int(it.get('buy_qty')),
            'buy_avg': _to_int(it.get('buy_avg_pric')),
            'buy_amt': _to_int(it.get('buy_amt')),
            'sell_qty': _to_int(it.get('sell_qty')),
            'sell_avg': _to_int(it.get('sel_avg_pric')),  # 키움 필드명 'sel_avg_pric' (오타 아님)
            'sell_amt': _to_int(it.get('sell_amt')),
            'pl_amt': _to_int(it.get('pl_amt')),          # 실현손익 (수수료·세금 차감)
            'cmsn_tax': _to_int(it.get('cmsn_alm_tax')),  # 수수료+세금
            'prft_rt': _to_float(str(it.get('prft_rt') or '0').lstrip('+')),
        })
    return out


def get_trade_journal_all(base_dt: str | None = None, labels: list[str] | None = None) -> dict:
    """모든 계좌 당일매매일지 — {label: [trades]} 반환.
    labels 지정 시 해당 라벨만 순회 (owner 단위 부분 갱신용)."""
    accs = list_accounts()
    if labels is not None:
        wanted = set(labels)
        accs = [a for a in accs if a['label'] in wanted]
    return {a['label']: get_trade_journal(a['label'], base_dt) for a in accs}


def get_cash_flow(account_label: str, base_dt: str | None = None) -> list[dict]:
    """당일 입출금 내역 (kt00015 tp='1').

    base_dt: YYYYMMDD (None이면 KST 오늘). 시작/종료 동일 → 그날치만.
    tp='1'(입출금)·gds_tp='0'(전체)로 매매·환전 등은 제외. KRW만 필터.

    반환 행:
      - time:    'HH:MM:SS' (proc_tm 앞 8자리)
      - io_tp:   'IN' | 'OUT'
      - amount:  거래금액 (원, 양수)
      - signed:  +amount (입금) / -amount (출금) — 합산으로 net cash flow 산출
      - rmrk:    적요명 (예: '타사대체입금', '은행이체출금')
      - balance: 거래 후 예수금잔고 (entra_remn)
    """
    if base_dt is None:
        base_dt = datetime.now(KST).strftime('%Y%m%d')
    body = {
        'strt_dt': base_dt,
        'end_dt': base_dt,
        'tp': '1',
        'stk_cd': '',
        'crnc_cd': '',
        'gds_tp': '0',
        'frgn_stex_code': '',
        'dmst_stex_tp': '%',
    }
    resp = _call_paginated(account_label, TR_TRUST_TRADE, body,
                            list_field='trst_ovrl_trde_prps_array')
    items = resp.get('trst_ovrl_trde_prps_array') or []
    out: list[dict] = []
    for it in items:
        crnc = (it.get('crnc_cd') or '').strip()
        if crnc and crnc != 'KRW':
            continue
        io_nm = (it.get('io_tp_nm') or '').strip()
        amount = _to_int(it.get('trde_amt'))
        if amount == 0:
            continue
        # tp='1' 필터에도 io_tp_nm은 한글 라벨로 떨어진다. 입금/출금 키워드로 부호 결정.
        if '입금' in io_nm:
            io_tp, signed = 'IN', amount
        elif '출금' in io_nm:
            io_tp, signed = 'OUT', -amount
        else:
            continue
        proc_tm = (it.get('proc_tm') or '').strip()
        out.append({
            'time': proc_tm[:8],
            'io_tp': io_tp,
            'amount': amount,
            'signed': signed,
            'rmrk': (it.get('rmrk_nm') or '').strip(),
            'balance': _to_int(it.get('entra_remn')),
        })
    return out


def get_cash_flow_all(base_dt: str | None = None, labels: list[str] | None = None) -> dict:
    """모든 계좌 당일 입출금 — {label: [flows]}. labels 지정 시 해당 라벨만."""
    accs = list_accounts()
    if labels is not None:
        wanted = set(labels)
        accs = [a for a in accs if a['label'] in wanted]
    return {a['label']: get_cash_flow(a['label'], base_dt) for a in accs}


def get_order_executions(account_label: str, base_dt: str | None = None) -> list[dict]:
    """계좌별 주문체결내역 (kt00007) — 주문번호·시각 단위 행 리스트.

    매매 시점 가드(broker 진실 소스 검증)에 사용. ka10170(종목별 일계 집계)과 달리
    개별 주문건마다 ord_tm·ord_no·체결가·체결수량이 분리되어 시간 기반 가드 가능.

    base_dt: YYYYMMDD (None이면 KST 오늘).
    qry_tp='1': 시간 오름차순. 다른 분기 의미는 키움 문서 미확정이라 '1' 고정.

    반환 행 정규화 필드:
      - ord_no:    주문번호 (예: '0374065')
      - ord_tm:    주문시각 'HH:MM:SS' (체결시각 별도 필드 없음, 주문시각 사용)
      - code:      종목코드 (A 접두 제거)
      - name:      종목명
      - side:      'BUY' | 'SELL' | 'UNKNOWN'  (io_tp_nm 에서 추출)
      - order_qty: 주문수량
      - cntr_qty:  체결수량 (0 이면 미체결)
      - cntr_uv:   체결단가 (0 이면 미체결)
      - ord_uv:    주문단가 (시장가는 0)
      - order_type:'시장가' | '지정가' | 기타
      - exchange:  'KRX' | 'NXT' | 'SOR'
      - comm_src:  주문 출처. 'REST API' (우리 매매) vs '영웅문S#' 등 (사용자 직접 매매)
      - mdfy_cncl: 정정/취소 표식 (빈 값이면 정상)
    """
    if base_dt is None:
        base_dt = datetime.now(KST).strftime('%Y%m%d')
    body = {
        'ord_dt': base_dt,
        'qry_tp': '1',
        'stk_bond_tp': '0',
        'sell_tp': '0',
        'stk_cd': '',
        'fr_ord_no': '',
        'dmst_stex_tp': '%',
    }
    resp = _call_paginated(account_label, TR_ORDER_EXEC, body,
                            list_field='acnt_ord_cntr_prps_dtl')
    items = resp.get('acnt_ord_cntr_prps_dtl') or []
    out: list[dict] = []
    for it in items:
        code = _clean_code(it.get('stk_cd', ''))
        name = (it.get('stk_nm') or '').strip()
        if not code or not name:
            continue  # placeholder 행 스킵
        io_tp = (it.get('io_tp_nm') or '').strip()
        if '매도' in io_tp:
            side = 'SELL'
        elif '매수' in io_tp:
            side = 'BUY'
        else:
            side = 'UNKNOWN'
        out.append({
            'ord_no': (it.get('ord_no') or '').strip(),
            'ord_tm': (it.get('ord_tm') or '').strip(),
            'code': code,
            'name': name,
            'side': side,
            'order_qty': _to_int(it.get('ord_qty')),
            'cntr_qty': _to_int(it.get('cntr_qty')),
            'cntr_uv': _to_int(it.get('cntr_uv')),
            'ord_uv': _to_int(it.get('ord_uv')),
            'order_type': (it.get('trde_tp') or '').strip(),
            'exchange': (it.get('dmst_stex_tp') or '').strip(),
            'comm_src': (it.get('comm_ord_tp') or '').strip(),
            'mdfy_cncl': (it.get('mdfy_cncl') or '').strip(),
        })
    return out


_EXCHANGE_CODE_TO_SUFFIX = {
    '0': '_AL',  # 통합 → SOR
    '1': '',     # KRX
    '2': '_NX',  # NXT
}


def get_open_orders(account_label: str, code: str = '',
                     side: str = 'all', exchange: str = 'all') -> list[dict]:
    """미체결 주문 리스트 (ka10075). 정정/취소 대상 후보 추출용.

    조회 전용 — 주문 행위는 orders 모듈을 거쳐야 함.

    side: 'all' | 'buy' | 'sell'
    exchange: 'all' | 'KRX' | 'NXT'

    반환 행 정규화 필드:
      - account:        account_label (호출자 라벨, 키움 응답엔 없음)
      - ord_no:         주문번호
      - code:           종목코드 (A 접두 제거)
      - name:           종목명
      - side:           'BUY' | 'SELL' | 'UNKNOWN'
      - order_qty:      주문수량
      - order_price:    주문가격 (시장가면 0)
      - unfilled_qty:   미체결수량 (취소 시 잔량 = 이 값)
      - order_type:     trde_tp 문자열 ('시장가' / '지정가' 등)
      - exchange:       'KRX' | 'NXT' | '통합' (stex_tp_txt)
      - exchange_code:  '0' | '1' | '2'
      - routing_suffix: '_AL' | '' | '_NX'  (orders.kiwoom_order 가 그대로 받음)
      - status:         ord_stt (예: '접수')
      - order_time:     'HH:MM:SS' (tm)
    """
    side_map = {'all': '0', 'sell': '1', 'buy': '2'}
    exchange_map = {'all': '0', 'KRX': '1', 'NXT': '2'}
    if side not in side_map:
        raise ValueError(f'invalid side: {side!r}')
    if exchange not in exchange_map:
        raise ValueError(f'invalid exchange: {exchange!r}')
    body = {
        'all_stk_tp': '1' if code else '0',
        'trde_tp': side_map[side],
        'stk_cd': code or '',
        'stex_tp': exchange_map[exchange],
    }
    resp = _call_paginated(account_label, TR_OPEN_ORDERS, body, list_field='oso')
    items = resp.get('oso') or []
    out: list[dict] = []
    for it in items:
        stk_code = _clean_code(it.get('stk_cd', ''))
        ord_no = (it.get('ord_no') or '').strip()
        if not stk_code or not ord_no:
            continue
        io_tp = (it.get('io_tp_nm') or '').strip()
        if '매도' in io_tp:
            s = 'SELL'
        elif '매수' in io_tp:
            s = 'BUY'
        else:
            s = 'UNKNOWN'
        ex_code = (it.get('stex_tp') or '').strip()
        out.append({
            'account': account_label,
            'ord_no': ord_no,
            'code': stk_code,
            'name': (it.get('stk_nm') or '').strip(),
            'side': s,
            'order_qty': _to_int(it.get('ord_qty')),
            'order_price': _to_int(it.get('ord_pric')),
            'unfilled_qty': _to_int(it.get('oso_qty')),
            'order_type': (it.get('trde_tp') or '').strip(),
            'exchange': (it.get('stex_tp_txt') or '').strip(),
            'exchange_code': ex_code,
            'routing_suffix': _EXCHANGE_CODE_TO_SUFFIX.get(ex_code, ''),
            'status': (it.get('ord_stt') or '').strip(),
            'order_time': (it.get('tm') or '').strip(),
        })
    return out


def get_open_orders_all(labels: list[str] | None = None,
                         code: str = '', side: str = 'all',
                         exchange: str = 'all') -> list[dict]:
    """모든 계좌의 미체결 주문 통합 리스트 — 정정/취소 자동 매칭에 사용."""
    if labels is None:
        labels = list(load_credentials().get('accounts', {}).keys())
    rows: list[dict] = []
    for label in labels:
        try:
            rows.extend(get_open_orders(label, code=code, side=side, exchange=exchange))
        except Exception as e:
            print(f'[get_open_orders_all] {label} 실패: {e}', file=sys.stderr)
    return rows


# ---- 시세·종목코드 조회 (매매 아님, READ-ONLY) ----

def _default_account_label() -> str:
    """시세 조회는 어느 계좌 토큰으로든 가능 — 첫 계좌를 사용."""
    accounts = list(load_credentials().get('accounts', {}).keys())
    if not accounts:
        raise RuntimeError('등록된 계좌 없음')
    return accounts[0]


_QUOTE_GATE = threading.Lock()
_QUOTE_LAST_TS = 0.0
# ka10001 한도(키움 통상 ~5 req/sec) 안쪽으로 페이싱. 0.22s 간격 → 약 4.5 req/sec.
# behive_web 동시 발사·watchlist_monitor 연사로 1700:허용된 요청 개수 초과(HTTP 429) 빈발 → 단일 진입점에서 직렬화.
_QUOTE_MIN_INTERVAL = 0.22
_QUOTE_BACKOFF_SEC = 1.0


def _is_quote_rate_limit(err_msg: str) -> bool:
    return 'HTTP 429' in err_msg or '허용된 요청 개수' in err_msg or '1700' in err_msg


def get_stock_quote(code: str, account_label: str | None = None, exchange: str = 'AL') -> dict:
    """주식기본정보 조회 (ka10001). 현재가·전일대비·등락률.

    exchange: 'AL'=KRX+NXT 통합(기본·최신가·통합거래량), 'KRX'=KRX 단독, 'NX'=NXT 단독.
    키움 ATS 변경(2025-03 NextTrade 출범) 이후 종목코드 접미사(`_AL`/`_NX`)로 거래소 지정.
    NXT 미상장 종목에 'AL' 호출 시 KRX 값으로 자동 fallback (서남 등 검증 완료).
    """
    global _QUOTE_LAST_TS
    label = account_label or _default_account_label()
    clean = _clean_code(code)
    stk_cd = f'{clean}_{exchange}' if exchange in ('NX', 'AL') else clean
    url = base_url() + ENDPOINT_STKINFO
    body = {'stk_cd': stk_cd}

    resp = None
    last_err: Exception | None = None
    for attempt in range(2):
        with _QUOTE_GATE:
            wait = _QUOTE_MIN_INTERVAL - (time.time() - _QUOTE_LAST_TS)
            if wait > 0:
                time.sleep(wait)
            try:
                resp, _ = _http_post_full(url, body, auth_headers(label, tr_id=TR_STOCK_INFO))
            except RuntimeError as e:
                _QUOTE_LAST_TS = time.time()
                if _is_quote_rate_limit(str(e)) and attempt == 0:
                    last_err = e
                    resp = None
                else:
                    raise
            else:
                _QUOTE_LAST_TS = time.time()
        if resp is None:
            time.sleep(_QUOTE_BACKOFF_SEC)
            continue
        rc = resp.get('return_code', 0)
        if rc != 0 and _is_quote_rate_limit(str(resp.get('return_msg') or '')) and attempt == 0:
            last_err = RuntimeError(f'{TR_STOCK_INFO} rate-limit: {resp.get("return_msg")}')
            time.sleep(_QUOTE_BACKOFF_SEC)
            resp = None
            continue
        break

    if resp is None:
        raise last_err or RuntimeError(f'{TR_STOCK_INFO} 실패: 응답 없음')
    if resp.get('return_code', 0) != 0:
        raise RuntimeError(f'{TR_STOCK_INFO} 실패: {resp.get("return_msg")} (full={resp})')
    # 키움 현재가 응답은 부호 포함 문자열: "+71200", "-71200", "71200"
    cur_str = str(resp.get('cur_prc') or '0').strip()
    pred_str = str(resp.get('pred_pre') or '0').strip()
    return {
        'code': clean,
        'name': (resp.get('stk_nm') or '').strip(),
        'price': abs(_to_int(cur_str)),  # 키움은 하한가·상한가 표시에만 부호 — 절댓값이 현재가
        'change': _to_int(pred_str),     # 전일대비 (부호 있음)
        'change_pct': _to_float(resp.get('flu_rt')),
        'volume': _to_int(resp.get('trde_qty')),
        'raw': resp,
    }


def get_watchlist_quotes(codes: list[str], account_label: str | None = None,
                          exchange: str = 'AL') -> dict[str, dict]:
    """ka10095 관심종목정보요청 — 다종목 시세 batch (한 콜로 N개).

    19종목 ~0.05s. ka10001×N 대비 rate limit 영향 없음.
    반환: {clean_code: {price, change, change_pct, name}}. 빈 codes면 빈 dict.
    """
    clean_codes = [_clean_code(c) for c in codes if c]
    if not clean_codes:
        return {}
    label = account_label or _default_account_label()
    suffix = f'_{exchange}' if exchange in ('NX', 'AL') else ''
    stk_cd_param = '|'.join(f'{c}{suffix}' for c in clean_codes)
    resp = _call(label, TR_WATCHLIST_INFO, {'stk_cd': stk_cd_param}, endpoint=ENDPOINT_STKINFO)
    out: dict[str, dict] = {}
    for row in resp.get('atn_stk_infr') or []:
        raw_code = (row.get('stk_cd') or '').strip()
        # 응답의 stk_cd는 요청 그대로 suffix 포함 ('294630_AL'). suffix 제거.
        code = raw_code.split('_', 1)[0]
        if not code:
            continue
        out[code] = {
            'code': code,
            'name': (row.get('stk_nm') or '').strip(),
            'price': abs(_to_int(row.get('cur_prc') or '0')),
            'change': _to_int(row.get('pred_pre') or '0'),
            'change_pct': _to_float(row.get('flu_rt')),
            # OHLC — 오늘 단일 캔들용. 키움 응답은 부호 포함 문자열이라 abs 처리.
            'open': abs(_to_int(row.get('open_pric') or '0')),
            'high': abs(_to_int(row.get('high_pric') or '0')),
            'low': abs(_to_int(row.get('low_pric') or '0')),
            'volume': _to_int(row.get('trde_qty') or '0'),
        }
    return out


def get_quote_book(code: str, account_label: str | None = None) -> dict:
    """주식호가 조회 (ka10004) — 10단계 매도/매수 호가 + 잔량.

    매매 아님 — 조회 전용. 호가창 표시·체결 가능성 판단에 사용.
    필드명 함정 (2026-05-07 메모리 reference_kiwoom_endpoints.md):
      - 1호가: `sel_fpr_bid` / `sel_fpr_req`, `buy_fpr_bid` / `buy_fpr_req` (suffix 없음)
      - 2~10호가: `sel_{N}th_pre_bid` / `sel_{N}th_pre_req`, `buy_{N}th_pre_bid` / `buy_{N}th_pre_req`
    가격 응답은 부호 포함 ('+71200') → abs 처리.

    rate limit 보호: ka10001과 동일 `_QUOTE_GATE` 통과 (시세 카테고리 공용).

    반환:
      - code, price(현재가), change(전일대비, 부호), change_pct
      - asks: [{price, qty}] — 1호가(가장 낮은 매도가)부터 10호가 순
      - bids: [{price, qty}] — 1호가(가장 높은 매수가)부터 10호가 순
      - ts: 응답 시각 KST ISO
    """
    global _QUOTE_LAST_TS
    label = account_label or _default_account_label()
    clean = _clean_code(code)
    url = base_url() + ENDPOINT_MRKCOND
    body = {'stk_cd': clean}

    resp: dict | None = None
    last_err: Exception | None = None
    for attempt in range(2):
        with _QUOTE_GATE:
            wait = _QUOTE_MIN_INTERVAL - (time.time() - _QUOTE_LAST_TS)
            if wait > 0:
                time.sleep(wait)
            try:
                resp, _ = _http_post_full(url, body, auth_headers(label, tr_id='ka10004'))
            except RuntimeError as e:
                _QUOTE_LAST_TS = time.time()
                if _is_quote_rate_limit(str(e)) and attempt == 0:
                    last_err = e
                    resp = None
                else:
                    raise
            else:
                _QUOTE_LAST_TS = time.time()
        if resp is None:
            time.sleep(_QUOTE_BACKOFF_SEC)
            continue
        rc = resp.get('return_code', 0)
        if rc != 0 and _is_quote_rate_limit(str(resp.get('return_msg') or '')) and attempt == 0:
            last_err = RuntimeError(f'ka10004 rate-limit: {resp.get("return_msg")}')
            time.sleep(_QUOTE_BACKOFF_SEC)
            resp = None
            continue
        break

    if resp is None:
        raise last_err or RuntimeError('ka10004 실패: 응답 없음')
    if resp.get('return_code', 0) != 0:
        raise RuntimeError(f'ka10004 실패: {resp.get("return_msg")} (full={resp})')

    asks: list[dict] = []
    bids: list[dict] = []

    ap1 = abs(_to_int(resp.get('sel_fpr_bid')))
    aq1 = abs(_to_int(resp.get('sel_fpr_req')))
    if ap1 and aq1:
        asks.append({'price': ap1, 'qty': aq1})
    bp1 = abs(_to_int(resp.get('buy_fpr_bid')))
    bq1 = abs(_to_int(resp.get('buy_fpr_req')))
    if bp1 and bq1:
        bids.append({'price': bp1, 'qty': bq1})
    for i in range(2, 11):
        ap = abs(_to_int(resp.get(f'sel_{i}th_pre_bid')))
        aq = abs(_to_int(resp.get(f'sel_{i}th_pre_req')))
        if ap and aq:
            asks.append({'price': ap, 'qty': aq})
        bp = abs(_to_int(resp.get(f'buy_{i}th_pre_bid')))
        bq = abs(_to_int(resp.get(f'buy_{i}th_pre_req')))
        if bp and bq:
            bids.append({'price': bp, 'qty': bq})

    return {
        'code': clean,
        'price': abs(_to_int(resp.get('cur_prc') or '0')),
        'change': _to_int(resp.get('pred_pre') or '0'),
        'change_pct': _to_float(resp.get('flu_rt')),
        'asks': asks,
        'bids': bids,
        'ts': datetime.now(KST).isoformat(),
        'raw': resp,
    }


def get_stock_basic(code: str, account_label: str | None = None) -> dict:
    """ka10001 기본정보를 분석 보고서용으로 정리.

    get_stock_quote가 시세 4필드(price·change·pct·volume)만 뽑는 반면,
    이 함수는 분석에 필요한 시고저·52주·시총·PER/PBR/ROE/EPS/BPS·회전율까지 노출.
    같은 TR이지만 보고서·뷰가 raw 파싱 코드를 직접 들고 다닐 필요 없게 wrapper로 둠.

    회전율(turnover_rate): trde_qty / flo_stk * 100. ka10001은 일일 회전율 필드 미제공이라
    상장주식수로 직접 계산. flo_stk는 천 주 단위가 아니라 주(株) 단위라 그대로 나눔.
    """
    q = get_stock_quote(code, account_label=account_label, exchange='AL')
    raw = q.get('raw') or {}

    # ka10001 flo_stk는 천 주 단위 (예: 5846279 = 5,846,279,000주)
    listed_thousand = _to_int(raw.get('flo_stk'))
    listed = listed_thousand * 1000
    volume = _to_int(raw.get('trde_qty'))
    turnover_rate = (volume / listed * 100.0) if listed > 0 else 0.0

    return {
        'code': q['code'],
        'name': q['name'],
        'price': q['price'],
        'change': q['change'],
        'change_pct': q['change_pct'],
        'open': abs(_to_int(raw.get('open_pric'))),
        'high': abs(_to_int(raw.get('high_pric'))),
        'low': abs(_to_int(raw.get('low_pric'))),
        'prev_close': abs(_to_int(raw.get('base_pric'))),
        'volume': volume,
        'listed_shares': listed,
        'market_cap': _to_int(raw.get('mac')),       # 시가총액 (억원)
        'high_52w': abs(_to_int(raw.get('250hgst'))),
        'high_52w_dt': (raw.get('250hgst_pric_dt') or '').strip(),
        'low_52w': abs(_to_int(raw.get('250lwst'))),
        'low_52w_dt': (raw.get('250lwst_pric_dt') or '').strip(),
        'per': _to_float(raw.get('per')),
        'pbr': _to_float(raw.get('pbr')),
        'eps': _to_int(raw.get('eps')),
        'bps': _to_int(raw.get('bps')),
        'roe': _to_float(raw.get('roe')),
        'turnover_rate': turnover_rate,
        'foreign_holding_pct': _to_float(raw.get('for_exh_rt')),  # 외국인 보유비율
        # 수익성 (최근 결산 기준, 억원 단위) — EPS×상장주식수 ≈ 당기순이익으로 단위 검증됨
        'sales': _to_int(raw.get('sale_amt')),         # 매출액
        'op_profit': _to_int(raw.get('bus_pro')),      # 영업이익
        'net_profit': _to_int(raw.get('cup_nga')),     # 당기순이익
        'ev_ebitda': _to_float(raw.get('ev')),         # EV/EBITDA 배수
        'capital': _to_int(raw.get('cap')),            # 자본금 (억원)
        'par_value': _to_int(raw.get('fav')),          # 액면가
        'par_unit': (raw.get('fav_unit') or '').strip(),   # 액면가 단위 (원 등)
        'settle_month': _to_int(raw.get('setl_mm')),   # 결산월
        'dist_rate': _to_float(raw.get('dstr_rt')),    # 유통주식 비율 (%)
        'raw': raw,
    }


def get_daily_candles(code: str, count: int = 250, base_dt: str | None = None,
                       account_label: str | None = None) -> list[dict]:
    """주식 일봉 차트 (ka10081). 수정주가 기준.

    base_dt: 'YYYYMMDD' 기준일 (생략 시 키움이 최신일로 처리).
    count: 반환할 최대 일봉 수 (최신부터 잘라서 반환). 키움은 한 호출에 ~600일치.

    반환: 최신순(내림차순)으로 정렬된 list of dict:
      {date, open, high, low, close, volume, value, turnover_rate}
    가격 필드는 모두 abs() 처리 (키움은 상하한 표시에만 부호 사용).
    """
    label = account_label or _default_account_label()
    if not base_dt:
        # ka10081은 base_dt 필수 — 비어있으면 오늘(Asia/Seoul) 채움
        from datetime import datetime
        try:
            from zoneinfo import ZoneInfo
            base_dt = datetime.now(ZoneInfo('Asia/Seoul')).strftime('%Y%m%d')
        except Exception:
            base_dt = datetime.now().strftime('%Y%m%d')
    body = {
        'stk_cd': _clean_code(code),
        'base_dt': base_dt,
        'upd_stkpc_tp': '1',  # 수정주가 사용
    }
    resp = _call(label, TR_DAILY_CHART, body, endpoint=ENDPOINT_CHART)
    rows = resp.get('stk_dt_pole_chart_qry') or []
    out: list[dict] = []
    for row in rows[:count]:
        out.append({
            'date': (row.get('dt') or '').strip(),
            'open': abs(_to_int(row.get('open_pric'))),
            'high': abs(_to_int(row.get('high_pric'))),
            'low': abs(_to_int(row.get('low_pric'))),
            'close': abs(_to_int(row.get('cur_prc'))),
            'volume': _to_int(row.get('trde_qty')),
            'value': _to_int(row.get('trde_prica')),       # 거래대금 (백만원)
            'turnover_rate': _to_float(row.get('trde_tern_rt')),  # 일별 회전율 (%)
        })
    return out


def get_minute_candles(code: str, tic_scope: int = 5, today_only: bool = True,
                        account_label: str | None = None) -> list[dict]:
    """주식 분봉 차트 (ka10080). 수정주가 기준.

    tic_scope: 1/3/5/10/15/30/45/60 분. 한 호출에 ~900봉 (5분봉 ≈ 11일치).
    today_only: True 면 오늘 봉만 추출.

    반환: 시간 오름차순 list of dict — {date, time, open, high, low, close, volume}
    date='YYYYMMDD', time='HHMMSS'.
    """
    label = account_label or _default_account_label()
    body = {
        'stk_cd': _clean_code(code),
        'tic_scope': str(tic_scope),
        'upd_stkpc_tp': '1',
    }
    resp = _call(label, TR_MINUTE_CHART, body, endpoint=ENDPOINT_CHART)
    rows = resp.get('stk_min_pole_chart_qry') or []
    from datetime import datetime
    try:
        from zoneinfo import ZoneInfo
        today = datetime.now(ZoneInfo('Asia/Seoul')).strftime('%Y%m%d')
    except Exception:
        today = datetime.now().strftime('%Y%m%d')
    out: list[dict] = []
    for row in rows:
        ctm = (row.get('cntr_tm') or '').strip()
        date = ctm[:8] if len(ctm) >= 8 else ''
        if today_only and date != today:
            continue
        out.append({
            'date': date,
            'time': ctm[8:14] if len(ctm) >= 14 else '',
            'open': abs(_to_int(row.get('open_pric'))),
            'high': abs(_to_int(row.get('high_pric'))),
            'low': abs(_to_int(row.get('low_pric'))),
            'close': abs(_to_int(row.get('cur_prc'))),
            'volume': _to_int(row.get('trde_qty')),
        })
    # 키움 응답은 최신순 → 오름차순으로
    out.reverse()
    return out


def get_investor_flow(code: str, days: int = 20, account_label: str | None = None) -> list[dict]:
    """종목별 투자자별 일별 매매 (ka10059). 외국인·기관 수급용.

    days: 최신부터 자를 일수. 키움 응답은 기본 ~100일치.
    unit_tp='1000': 단위 천 주. 수량 부호 = 순매수(+)/순매도(-).
    trde_tp='0': 순매수 기준.

    반환: 최신순 list of dict — {date, close, change, change_pct, volume, individual, foreign, institution, pension, ...}
    수량은 천 주 단위 그대로.
    """
    label = account_label or _default_account_label()
    # ka10059 dt 필수 — 빈 값 불가. 오늘(Asia/Seoul) 기준으로 채움
    from datetime import datetime
    try:
        from zoneinfo import ZoneInfo
        today = datetime.now(ZoneInfo('Asia/Seoul')).strftime('%Y%m%d')
    except Exception:
        today = datetime.now().strftime('%Y%m%d')
    body = {
        'dt': today,
        'stk_cd': _clean_code(code),
        'amt_qty_tp': '2',         # 1=금액, 2=수량
        'trde_tp': '0',            # 0=순매수, 1=매수, 2=매도
        'unit_tp': '1000',         # 단위 (천 주)
    }
    resp = _call(label, TR_INVESTOR_FLOW, body, endpoint=ENDPOINT_STKINFO)
    rows = resp.get('stk_invsr_orgn') or []
    out: list[dict] = []
    for row in rows[:days]:
        out.append({
            'date': (row.get('dt') or '').strip(),
            'close': abs(_to_int(row.get('cur_prc'))),
            'change': _to_int(row.get('pred_pre')),
            # flu_rt는 ×100 형태 ('-196' = -1.96%) — _to_float은 그대로 받고 호출자가 /100
            'change_pct_raw': _to_int(row.get('flu_rt')),
            'volume': _to_int(row.get('acc_trde_qty')),
            'individual': _to_int(row.get('ind_invsr')),       # 개인
            'foreign': _to_int(row.get('frgnr_invsr')),        # 외국인
            'institution': _to_int(row.get('orgn')),           # 기관 합계
            'fnnc_invt': _to_int(row.get('fnnc_invt')),        # 금융투자
            'insurance': _to_int(row.get('insrnc')),           # 보험
            'invtrt': _to_int(row.get('invtrt')),              # 투신
            'bank': _to_int(row.get('bank')),                  # 은행
            'pension': _to_int(row.get('penfnd_etc')),         # 연기금
            'private_fund': _to_int(row.get('samo_fund')),     # 사모펀드
            'etc_corp': _to_int(row.get('etc_corp')),          # 기타법인
        })
    return out


def _load_code_cache() -> dict:
    """종목코드 캐시 dict {name: {code, name, market}} 반환. 없으면 빈 dict."""
    if not STOCK_CODES_CACHE.exists():
        return {}
    try:
        return json.loads(STOCK_CODES_CACHE.read_text()).get('stocks', {}) or {}
    except Exception:
        return {}


def refresh_stock_codes(account_label: str | None = None) -> dict:
    """ka10099로 KOSPI+KOSDAQ 전체 상장종목 리스트 캐싱. 페이지네이션 처리.

    캐시 저장 필드 (2026-05-07 확장):
    - code, name, market (기존)
    - nxt_enable: bool — ka10099 응답 nxtEnable=='Y' 변환. NXT 가드 정확화에 사용
    - state: str — 종목상태 (예: '관리종목', '정리매매', '증거금100%')
    - order_warning: str — 투자유의 (0/1/2/3/4/5, ka10099 명세 참조)
    """
    label = account_label or _default_account_label()
    url = base_url() + ENDPOINT_STKINFO
    result: dict[str, dict] = {}
    for mrkt_tp, market_name in [('0', 'KOSPI'), ('10', 'KOSDAQ')]:
        cont_yn = 'N'
        next_key = ''
        for _ in range(50):  # safety cap on pagination loops
            headers = auth_headers(label, tr_id=TR_STOCK_LIST, cont_yn=cont_yn, next_key=next_key)
            resp, resp_headers = _http_post_full(url, {'mrkt_tp': mrkt_tp}, headers)
            if resp.get('return_code', 0) != 0:
                raise RuntimeError(f'{TR_STOCK_LIST} ({market_name}) 실패: {resp.get("return_msg")}')
            items = resp.get('list') or []
            for it in items:
                code = _clean_code(it.get('code', ''))
                name = (it.get('name') or '').strip()
                if code and name:
                    result[name] = {
                        'code': code,
                        'name': name,
                        'market': market_name,
                        'nxt_enable': str(it.get('nxtEnable') or '').strip().upper() == 'Y',
                        'state': (it.get('state') or '').strip(),
                        'order_warning': str(it.get('orderWarning') or '0').strip(),
                    }
            cy = (resp_headers.get('cont-yn') or '').strip().upper()
            nk = (resp_headers.get('next-key') or '').strip()
            if cy == 'Y' and nk:
                cont_yn = 'Y'
                next_key = nk
                time.sleep(0.15)
            else:
                break
    STOCK_CODES_CACHE.parent.mkdir(parents=True, exist_ok=True)
    STOCK_CODES_CACHE.write_text(json.dumps({
        'refreshed_at': datetime.now(KST).isoformat(),
        'count': len(result),
        'stocks': result,
    }, ensure_ascii=False, indent=2))
    return result


def lookup_stock_meta(code: str) -> dict | None:
    """6자리 종목코드 → 캐시된 메타 dict (또는 None).

    캐시는 종목명 기반이라 코드 검색은 O(N). ~3500종목 수준이라 매 호출 직접 순회.
    캐시 미스 또는 캐시 자체가 없으면 None — 호출자가 fallback 결정.
    """
    clean = _clean_code(code or '')
    if not clean:
        return None
    for info in _load_code_cache().values():
        if info.get('code') == clean:
            return info
    return None


def resolve_stock_code(name_or_code: str) -> dict:
    """이름 또는 6자리 코드 → {code, name, market}. 캐시 매칭 실패 시 1회 lazy refresh.

    이름 매칭은 공백 무시 ("은선물" == "은 선물" — KRX 종목명 공백 표기 불일치 흡수).
    """
    s = (name_or_code or '').strip()
    if not s:
        raise ValueError('빈 입력')
    # 6자리 숫자 → 코드로 간주
    if s.isdigit() and len(s) == 6:
        for info in _load_code_cache().values():
            if info.get('code') == s:
                return info
        # 캐시에 없으면 ka10001로 이름만 끌어옴 (KRX 단독 — NXT 미상장 종목 보호)
        q = get_stock_quote(s, exchange='KRX')
        return {'code': s, 'name': q.get('name') or '', 'market': '?'}
    norm = lambda x: ''.join((x or '').split())
    s_n = norm(s)

    def _match(cache: dict) -> tuple[dict | None, list[dict]]:
        # 정확 매칭 (공백 정규화 후)
        for name, info in cache.items():
            if norm(name) == s_n:
                return info, []
        # 부분 매칭 (공백 정규화 후)
        partial = [info for name, info in cache.items() if s_n in norm(name)]
        return None, partial

    cache = _load_code_cache()
    exact, partial = _match(cache)
    if exact:
        return exact
    if len(partial) == 1:
        return partial[0]
    # lazy refresh (캐시 비었거나 매칭 실패 시 1회만)
    if not cache or not partial:
        print(f'[stock-codes] 캐시 갱신 중...', file=sys.stderr)
        refresh_stock_codes()
        cache = _load_code_cache()
        exact, partial = _match(cache)
        if exact:
            return exact
        if len(partial) == 1:
            return partial[0]
    if len(partial) > 1:
        raise KeyError(f'종목 매칭 다중: "{s}" → {[p["name"] for p in partial[:5]]}')
    raise KeyError(f'종목 매칭 실패: "{s}" (캐시 {len(cache)}종목)')


# ---- 주문 함수는 작성하지 않음 (매매 절대 원칙) ----
# DO NOT add: order_buy, order_sell, modify_order, cancel_order, ...
# 어떤 요청이 오더라도 이 모듈에 추가 금지. 별도 안건으로 분리.


def main():
    """간단 CLI: 토큰 발급·계좌 라벨 확인용."""
    cmd = sys.argv[1] if len(sys.argv) > 1 else 'help'
    if cmd == 'token':
        label = sys.argv[2] if len(sys.argv) > 2 else None
        labels = [label] if label else [a['label'] for a in list_accounts()]
        exit_code = 0
        for lb in labels:
            try:
                t = issue_token(lb, force=True)
                print(f'[{lb}] 토큰 발급 성공: {t[:20]}... (캐시: {_token_cache_path(lb)})')
            except Exception as e:
                print(f'[{lb}] 토큰 발급 실패: {e}', file=sys.stderr)
                exit_code = 1
        return exit_code
    if cmd == 'accounts':
        for a in list_accounts():
            print(f"{a['label']}: {a['account_no'] or '(토큰 스코프로 식별, 계좌번호 저장 불필요)'}")
        return 0
    if cmd == 'balance':
        label = sys.argv[2] if len(sys.argv) > 2 else None
        labels = [label] if label else [a['label'] for a in list_accounts()]
        for lb in labels:
            b = get_balance(lb)
            print(f"[{lb}] 예수금 {b['entr']:,}원 · D+2 {b['d2_entra']:,}원 · 주문가능 {b['ord_alow_amt']:,}원 · 대용금 {b['repl_amt']:,}원")
        return 0
    if cmd == 'positions':
        label = sys.argv[2] if len(sys.argv) > 2 else None
        labels = [label] if label else [a['label'] for a in list_accounts()]
        for lb in labels:
            items = get_positions(lb)
            print(f"\n[{lb}] 보유 {len(items)}종목")
            for p in items:
                sign = '+' if p['evltv_prft'] >= 0 else ''
                print(f"  {p['name']:<14} ({p['code']}) {p['qty']:>5}주 평단 {p['avg_price']:>8,} 현재 {p['cur_price']:>8,} 평가 {p['evlt_amt']:>12,} 손익 {sign}{p['evltv_prft']:>10,} ({p['prft_rt']:+.2f}%)")
        return 0
    if cmd == 'summary':
        for lb in [a['label'] for a in list_accounts()]:
            s = get_account_summary(lb)
            print(f"[{lb}] {s['acnt_nm']}({s['brch_nm']}) · 추정총자산 {s['tot_est_amt']:,}원 · 자산평가액 {s['aset_evlt_amt']:,}원 · 매입 {s['tot_pur_amt']:,}원")
        return 0
    if cmd == 'quote':
        if len(sys.argv) < 3:
            print('usage: quote <name_or_code>', file=sys.stderr)
            return 2
        info = resolve_stock_code(sys.argv[2])
        q = get_stock_quote(info['code'])
        sign = '+' if q['change'] >= 0 else ''
        print(f"{q['name']} ({q['code']}) {q['price']:,}원 ({sign}{q['change']:,}원, {q['change_pct']:+.2f}%) · 거래량 {q['volume']:,}")
        return 0
    if cmd == 'resolve':
        if len(sys.argv) < 3:
            print('usage: resolve <name_or_code>', file=sys.stderr)
            return 2
        info = resolve_stock_code(sys.argv[2])
        print(f"{info['name']} ({info['code']}) · {info.get('market','?')}")
        return 0
    if cmd == 'refresh-codes':
        stocks = refresh_stock_codes()
        print(f"종목코드 캐시 갱신 완료: {len(stocks)}종목 → {STOCK_CODES_CACHE}")
        return 0
    if cmd == 'journal':
        # journal [label] [YYYYMMDD] — 당일매매일지 (round-trip·풀매도 포함)
        label = sys.argv[2] if len(sys.argv) > 2 else None
        base_dt = sys.argv[3] if len(sys.argv) > 3 else None
        labels = [label] if label else [a['label'] for a in list_accounts()]
        for lb in labels:
            trades = get_trade_journal(lb, base_dt)
            print(f"\n[{lb}] 매매 {len(trades)}건")
            for t in trades:
                parts = []
                if t['buy_qty']:
                    parts.append(f"매수 {t['buy_qty']:,}주 @ {t['buy_avg']:,}원 ({t['buy_amt']:,}원)")
                if t['sell_qty']:
                    parts.append(f"매도 {t['sell_qty']:,}주 @ {t['sell_avg']:,}원 ({t['sell_amt']:,}원)")
                pl_str = f"실현 {t['pl_amt']:+,}원 ({t['prft_rt']:+.2f}%)" if t['sell_qty'] else ''
                print(f"  {t['name']} ({t['code']}) · {' / '.join(parts)} · 수수료·세금 {t['cmsn_tax']:,}원 {pl_str}")
        return 0
    if cmd == 'cashflow':
        # cashflow [label] [YYYYMMDD] — 당일 입출금 내역 (kt00015 tp='1')
        label = sys.argv[2] if len(sys.argv) > 2 else None
        base_dt = sys.argv[3] if len(sys.argv) > 3 else None
        labels = [label] if label else [a['label'] for a in list_accounts()]
        for lb in labels:
            flows = get_cash_flow(lb, base_dt)
            net = sum(f['signed'] for f in flows)
            cash_in = sum(f['amount'] for f in flows if f['io_tp'] == 'IN')
            cash_out = sum(f['amount'] for f in flows if f['io_tp'] == 'OUT')
            print(f"\n[{lb}] 입출금 {len(flows)}건 · 입금 {cash_in:,}원 · 출금 {cash_out:,}원 · 순 {net:+,}원")
            for f in flows:
                print(f"  {f['time']} · {f['io_tp']:>3} {f['amount']:,}원 · {f['rmrk']}")
        return 0
    if cmd == 'open':
        # open [label] [code] — 미체결 주문 (ka10075)
        label = sys.argv[2] if len(sys.argv) > 2 else None
        code = sys.argv[3] if len(sys.argv) > 3 else ''
        labels = [label] if label else [a['label'] for a in list_accounts()]
        for lb in labels:
            rows = get_open_orders(lb, code=code)
            print(f"\n[{lb}] 미체결 {len(rows)}건")
            for r in rows:
                price = f"{r['order_price']:,}원" if r['order_price'] else r['order_type']
                print(f"  ord_no={r['ord_no']} · {r['name']} ({r['code']}) {r['side']} {r['order_qty']}주 @ {price} · 미체결 {r['unfilled_qty']} · {r['exchange']} · {r['status']} · {r['order_time']}")
        return 0
    print(__doc__, file=sys.stderr)
    print('\nusage: kiwoom_client.py {token [label] | accounts | balance [label] | positions [label] | summary | quote <name|code> | resolve <name|code> | refresh-codes | journal [label] [YYYYMMDD] | cashflow [label] [YYYYMMDD] | open [label] [code]}', file=sys.stderr)
    return 2


if __name__ == '__main__':
    sys.exit(main())