Reconciliation
broker(거래소/증권사)와 내부 DB가 동일한 포지션을 가지고 있어야 정상 운영입니다. 비동기 fill, 네트워크 지연, 부분 체결 등으로 둘 사이가 어긋날 수 있고, 이때 UI는 Reconciliation 알림을 띄웁니다.
📸 Reconciliation 알림 (추후 자동 캡처 예정)
어디에서 보이나
| 위치 | 동작 |
|---|---|
| Positions 페이지 상단 | 빨간 배너로 "Position drift detected: BTC/USDT (broker 0.05 vs db 0.04)" |
| Telegram 알림 | 5분 이상 지속 시 자동 알림 |
| Grafana Mismatch panel | 시계열 그래프 |
일반적인 불일치 유형
| 유형 | 원인 | 자동 복구 |
|---|---|---|
| Phantom in DB | broker에서 청산됐지만 DB에는 OPEN | 5분 후 reconciler가 close 처리 |
| Phantom in broker | DB에는 없는 broker 포지션 | 알림만, 수동 import 필요 |
| Quantity drift | 부분 체결 누락 | 5분 후 broker 수량으로 sync |
| Price drift | mark price 불일치 | UI는 broker 값 우선 |
자동 reconciler
src/execution/reconciler.py가 60초 주기로 broker.get_positions() 결과와 DB를 비교합니다.
| 동작 | 트리거 |
|---|---|
update | 수량 차이 ≤ 0.001% 이내 |
force_close | broker에 없는 DB 포지션 |
alert_only | DB에 없는 broker 포지션 |
운영 가이드는 position-reconciler 운영 문서를 참고하세요.
수동 조치
UI는 알림만 보여주며, 수동 reconcile은 다음 명령으로 실행합니다.
python -m src.execution.reconciler --user-id 123 --asset-class crypto --force
자주 묻는 질문
Q. 알림이 자주 뜹니다.
A. 부분 체결이 잦은 알트코인일 수 있습니다. 60초 주기 reconciler가 정상 흡수합니다. 5분 이상 지속이면 운영 점검이 필요합니다.
Q. 모의투자(KIS)에서도 reconcile이 동작하나요?
A. 네. 단, KIS 모의투자는 야간에 broker 포지션이 초기화되므로 다음 영업일 시작 시 phantom 알림이 흔합니다.
Q. broker_order_events와는 어떤 관계인가요?
A. reconciler는 broker_order_events를 source-of-truth로 사용해 어떤 주문이 누락됐는지 역추적합니다. Audit log 참고.