feat(execution,obs): 호가단위 스냅(dcy-030/#28) + 운영 관측성(dcy-029/#29) + REL-007 환류

dcy-030 (issue #28, P0 체결 복구): - REQ-083 KRX 호가단위(tick) 순수 유틸 (domain/pricing.py) - REQ-070 CHG: 슬리피지 실효가 호가단위 스냅 — 상한 준수(매수 floor/매도 ceil) + band<1tick 하한/상한 보장 + 부동소수 epsilon 가드. 147700→148400/54500→54700. - BAT-044 release-candidate dcy-029 (issue #29, 운영 관측성): - REQ-084 구조화 로깅 기반 (runtime/logging_setup.py): ISO8601 KST·레벨·Loki JSON ·correlation id(slot_id) - REQ-085 주문 결과 로깅 (event=order_submit|fill|reject) - REQ-087 거부 ERROR 가시성 (조용한 롤백 제거) - REQ-086 청산 reason+actor 동반 노출 (안전망/전략 구분, 신규 필드 없음) - REQ-088 운영 조회 CLI report (application/operator_report.py, 보유·오늘 체결 ·실현 PnL net·대기, direct-DB) - REQ-089 운영자 런북 docs/operations.md - REQ-090 baseline 정합 (runtime-flows·project-structure·interface-contract) - BAT-045(P0)·BAT-046(P1) release-candidate REL-007: confirmed → feedback-captured (운영 인스턴스 라이브 검증 + #28/#29 환류 정규화). BAT-037~041 released. 검증: 537 passed, 47 skipped, 회귀 0, ruff clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-16 13:19:31 +09:00
parent e0d4e71304
commit d8d9021260
48 changed files with 2461 additions and 58 deletions
@@ -0,0 +1,54 @@
+# req-084: 구조화 로깅 기반 — ISO8601(KST) 타임스탬프 + 레벨 + Loki JSON + correlation id
+
+- Status: Implemented
+- Type: Non-Functional
+- Priority: High
+- Owner: project maintainers
+
+## Intent
+- 모든 로그 라인에 시각·레벨이 없어 타임라인 재구성이 불가능했던 문제를 해결한다. ISO8601(KST) 타임스탬프 + 레벨 prefix를 전 로그에 부여하고, Loki 적재용 구조화(JSON) 출력 옵션과 correlation id(intent→order→fill) 전파를 도입해 한 거래의 로그를 단일 키로 묶는다. (dcy-029 FR-1, FR-7)
+
+## Requirement
+- 데몬 기동(및 reset CLI)의 로깅 설정을 단일 지점으로 모아, 모든 로그 라인에 **ISO8601 타임스탬프(KST, Asia/Seoul, 환경 TZ 비의존)** + **로그 레벨** prefix를 부여한다.
+- 환경 변수(`TREX_LOG_FORMAT`, 기본 `text`)로 출력 포맷을 선택한다: `text`(사람용 한 줄) / `json`(Loki 적재용 구조화 — 최소 `ts`, `level`, `logger`, `msg`, 가능하면 `correlation_id`).
+- **correlation id 전파**: contextvar 기반으로 현재 처리의 correlation id를 보관하고, 로깅 필터가 모든 레코드에 주입한다. intent 수락 시 intent_id(또는 그로부터 파생한 키)를 correlation id로 설정해, 같은 거래의 intent·order·fill 로그가 동일 id를 공유한다. id 미설정 시 빈 값/생략으로 안전하게 동작한다.
+- 기존 로깅 호출부(`_log.info/...`)는 메시지를 바꾸지 않아도 새 포맷·correlation id가 자동 적용되어야 한다(호출부 광범위 수정 불요).
+
+## Acceptance Criteria
+1. Given 로깅 설정 적용 후 임의 로그 1줄, When 출력, Then ISO8601(KST) 타임스탬프 + 레벨 + 메시지를 포함한다.
+2. Given `TREX_LOG_FORMAT=json`, When 로그 출력, Then 한 줄이 유효 JSON이며 `ts`/`level`/`logger`/`msg` 키를 포함한다.
+3. Given `TREX_LOG_FORMAT` 미설정/`text`, When 로그 출력, Then 사람용 한 줄 포맷(타임스탬프+레벨+메시지)이다.
+4. Given correlation id가 설정된 컨텍스트, When 로그 출력, Then 레코드(및 JSON `correlation_id`)에 그 id가 포함된다.
+5. Given correlation id 미설정, When 로그 출력, Then 예외 없이 빈/생략 correlation id로 출력된다.
+6. Given KST 타임스탬프, When 컨테이너 TZ가 UTC여도, Then 타임스탬프는 KST(+09:00) 기준이다.
+
+## Impacted Area
+- Docs: docs/runtime-flows.md(로깅/관측성 흐름 — REQ-090과 공동), docs/project-structure.md(신규 로깅 모듈)
+- Modules: 신규 `trex_core/runtime/logging_setup.py`(포맷터+JSON+correlation id 필터·contextvar) 후보, `trex_core/runtime/daemon.py`·`trex_core/runtime/reset.py`(basicConfig 대체), intent 수락 경로(correlation id set)
+- Tests: 로그 포맷터 단위(text/json/KST/correlation id), 설정 적용 단위
+
+## Notes
+- 기존 `logging.basicConfig(level=INFO)`(daemon.py·reset.py)는 format 미지정으로 타임스탬프·레벨 prefix가 없었다(dcy-029 현재상태).
+- correlation id 전파 깊이(전 경로 완전 전파 vs 핵심 경로)는 batch design에서 확정. 최소 intent admission→order dispatch 로깅 연결을 보장한다.
+- 출처: dcy-029 FR-1·FR-7, OQ-2(Loki In Scope), A-4(배포 Loki 사용 전제).
+
+## Change Log
+
+### CHG-20260616-01
+- Date: 2026-06-16
+- Author: Justin Ko
+
+#### Change Summary
+- dcy-029 FR-1·FR-7로부터 최초 생성(Proposed).
+
+### CHG-20260616-02
+- Date: 2026-06-16
+- Author: Justin Ko
+- Type: status
+- Summary: Proposed → **Approved** (confirm-req). 필수 필드·구체 AC 충족, source dcy-029(confirmed, Open OQ 0) 정합. dcy-029 P0/P1 batch 편성 예정.
+
+### CHG-20260616-IMPL
+- Date: 2026-06-16
+- Author: Justin Ko
+- Type: status
+- Summary: Approved → **Implemented** (confirm-req-implemented, BAT-045 release-candidate, dcy-029 P0). 근거: 단위 AC 매핑(logging_setup text/json/KST/cid/idempotent, execution 주문 결과 submit/fill/reject + cid=slot_id + 거부 ERROR). 35 passed(logging+execution_policy), 전체 529 passed/47 skipped 회귀 0, ruff clean. 실 Loki 적재는 release 운영 검증 위임. Blocking Issues 없음.
@@ -0,0 +1,53 @@
+# req-087: 주문 거부 ERROR 가시성 — 조용한 롤백 제거
+
+- Status: Implemented
+- Type: Non-Functional
+- Priority: High
+- Owner: project maintainers
+
+## Intent
+- 주문 거부 시 `execution._rollback`이 슬롯을 조용히 전이(`slot_transition_log`에만 기록)해 호가단위 거부(#28)가 로그에 안 보였다. 거부를 **ERROR 레벨 로그**로 즉시 가시화해 반복 거부를 운영자가 즉시 인지하게 한다. (dcy-029 FR-4)
+
+## Requirement
+- 주문 거부로 인한 롤백(`pending_buy→inactive` / `pending_sell→holding`) 시 **ERROR 레벨** 로그를 남긴다. 라인은 side, symbol, slot_id, 거부 사유를 포함한다(REQ-085 order_reject 라인과 동일 지점·동일 키, 레벨만 ERROR).
+- correlation id(REQ-084)가 있으면 함께 남긴다.
+- 알림 전송 채널(claude-bus/외부 webhook 등)은 본 REQ 범위 밖이다(dcy-029 OQ-3 Deferred) — ERROR 로그까지만.
+- 정상 체결/정상 전이 경로의 로그 레벨은 바꾸지 않는다(거부 경로만 ERROR).
+
+## Acceptance Criteria
+1. Given 매수 주문 거부, When 롤백(pending_buy→inactive), Then ERROR 레벨 로그(side/symbol/slot_id/사유)가 남는다.
+2. Given 매도 주문 거부, When 롤백(pending_sell→holding), Then ERROR 레벨 로그가 남는다.
+3. Given 정상 체결, When 전이, Then ERROR 로그가 남지 않는다(거부 경로만 ERROR).
+4. Given `TREX_LOG_FORMAT=json`, When 거부, Then `level=ERROR` + 사유 키가 구조화 출력된다.
+5. Given 반복 거부 N회, When grep `level=ERROR`/`event=order_reject`, Then N건 모두 가시화된다.
+6. Given 알림 채널, When 거부, Then 본 반복에서는 전송 채널을 호출하지 않는다(Deferred, 로그까지만).
+
+## Impacted Area
+- Docs: docs/runtime-flows.md(주문 집행 거부 가시성)
+- Modules: trex_core/application/execution.py(`_rollback`/거부 경로 ERROR 로그), REQ-084·085와 협조
+- Tests: tests/application/test_execution* (거부 ERROR caplog 단위, 정상 경로 비-ERROR)
+
+## Notes
+- REQ-085(주문 결과 로깅)와 동일한 reject 지점에서 협조 — REQ-085는 일관 키, 본 REQ는 거부 라인의 ERROR 레벨 보장.
+- 출처: dcy-029 FR-4, OQ-3(알림 Deferred).
+
+## Change Log
+
+### CHG-20260616-01
+- Date: 2026-06-16
+- Author: Justin Ko
+
+#### Change Summary
+- dcy-029 FR-4로부터 최초 생성(Proposed).
+
+### CHG-20260616-02
+- Date: 2026-06-16
+- Author: Justin Ko
+- Type: status
+- Summary: Proposed → **Approved** (confirm-req). 필수 필드·구체 AC 충족, source dcy-029(confirmed, Open OQ 0) 정합. dcy-029 P0/P1 batch 편성 예정.
+
+### CHG-20260616-IMPL
+- Date: 2026-06-16
+- Author: Justin Ko
+- Type: status
+- Summary: Approved → **Implemented** (confirm-req-implemented, BAT-045 release-candidate, dcy-029 P0). 근거: 단위 AC 매핑(logging_setup text/json/KST/cid/idempotent, execution 주문 결과 submit/fill/reject + cid=slot_id + 거부 ERROR). 35 passed(logging+execution_policy), 전체 529 passed/47 skipped 회귀 0, ruff clean. 실 Loki 적재는 release 운영 검증 위임. Blocking Issues 없음.