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-089: 운영자 런북 — docs/operations.md 신설
+
+- Status: Implemented
+- Type: Documentation
+- Priority: Medium
+- Owner: project maintainers
+
+## Intent
+- trex-core에 사람 운영자용 문서(배포·디버깅·CLI 사용법)가 없다. 운영 런북 `docs/operations.md`를 신설해 신규 운영자가 배포·실행, 상태/PnL 조회, 거부·미체결 디버깅을 그 문서만으로 수행하게 한다. (dcy-029 FR-8)
+
+## Requirement
+- `docs/operations.md`를 신설하고 최소 4영역을 포함한다:
+  1. **배포/실행**: 필수 env(`TREX_POSTGRESQL_DSN`/`TREX_RABBITMQ_URL`/`TREX_BROKER` 등), `--config`/`--env-file`, 기동·종료, 테스트 DB 안전 절차.
+  2. **운영자 CLI 사용법**: `pause/resume/slots/universe/enter/exit/cancel` + 신설 조회/PnL 서브커맨드(REQ-088).
+  3. **로깅/관측성 사용법**: 타임스탬프·레벨, 주문 결과 로그 grep(`event=order_submit|fill|reject`), `TREX_LOG_FORMAT=json`/Loki·correlation id, 청산 reason+actor 해석(REQ-086).
+  4. **디버깅/트러블슈팅**: 거부 ERROR 확인, 미체결 진단, DB 상태 조회(daily_slot/ledger_outbox), 자주 겪는 증상→원인→조치.
+- 기존 `.claude/skills/run-trex-core-daemon/SKILL.md`의 사실 자료(env 표·launch·troubleshooting)를 사람용 문서로 추출·정리하고, 본 반복(REQ-084~088) 관측성 기능 사용법을 반영한다.
+
+## Acceptance Criteria
+1. Given docs/operations.md, When 확인, Then 배포/실행 절차(env·config·기동·종료)가 포함돼 있다.
+2. Given 운영자 CLI 절, When 확인, Then 기존 서브커맨드 + 신설 조회/PnL(REQ-088) 사용법이 있다.
+3. Given 로깅/관측성 절, When 확인, Then 타임스탬프·주문결과 grep·JSON/Loki·correlation id·reason+actor 해석이 있다.
+4. Given 디버깅 절, When 확인, Then 거부 ERROR 확인·미체결 진단·DB 조회 가이드가 있다.
+5. Given 신규 운영자, When 런북만 참고, Then 데몬 배포·CLI 조회·거부 디버깅을 수행할 수 있다(4영역 모두 충족).
+
+## Impacted Area
+- Docs: docs/operations.md(신설), 참조: .claude/skills/run-trex-core-daemon/SKILL.md
+- Modules: 없음(문서)
+- Tests: 없음(문서 — verification은 4영역 포함 리뷰 체크)
+
+## Notes
+- 본 REQ는 REQ-084~088 구현 사용법을 문서화하므로 그 REQ들과 같은 batch(P1) 후반에 작성한다.
+- 출처: dcy-029 FR-8.
+
+## Change Log
+
+### CHG-20260616-01
+- Date: 2026-06-16
+- Author: Justin Ko
+
+#### Change Summary
+- dcy-029 FR-8로부터 최초 생성(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-046 release-candidate, dcy-029 P1). 근거: 단위/문서 AC 매핑(REQ-086 reason+actor 로그·interface-contract; REQ-088 operator_report 집계·net PnL·KST 경계·CLI report; REQ-089 docs/operations.md 4영역; REQ-090 runtime-flows·project-structure 정합). 14 passed(report+safety_sell), 전체 537 passed/47 skipped 회귀 0, ruff clean. report direct-DB·Loki 실 적재는 release 운영 검증 위임. Blocking Issues 없음.
@@ -0,0 +1,54 @@
+# req-090: 관측성 baseline 문서 정합 — 로깅/관측성·PnL 조회 흐름
+
+- Status: Implemented
+- Type: Documentation
+- Priority: Medium
+- Owner: project maintainers
+
+## Intent
+- dcy-029가 런타임 로깅·청산 분류·PnL 조회 흐름을 바꾸므로 baseline 문서를 실제 구현과 정합시킨다. (dcy-029 FR-6)
+
+## Requirement
+- `docs/runtime-flows.md`에 다음 흐름을 추가/갱신한다:
+  - 구조화 로깅 기반(ISO8601 KST 타임스탬프·레벨·JSON/Loki·correlation id, REQ-084).
+  - 주문 결과 로깅(submit/fill/reject 일관 라인, REQ-085) 및 거부 ERROR 가시성(REQ-087).
+  - 청산 reason+actor 동반 노출(REQ-086).
+  - 운영자 조회 CLI(보유/오늘 체결/실현 PnL/대기 주문, REQ-088).
+- `docs/project-structure.md`에 신규 로깅 모듈(REQ-084) 책임을 반영한다.
+- baseline 문서는 전체 흐름을 복제하지 않고 구현된 제약·진입점만 정합 수준으로 기술한다.
+
+## Acceptance Criteria
+1. Given runtime-flows.md, When 갱신 후, Then 구조화 로깅·correlation id 흐름이 기술돼 있다.
+2. Given runtime-flows.md, When 갱신 후, Then 주문 결과 로깅·거부 ERROR·청산 reason+actor·PnL 조회 CLI가 기술돼 있다.
+3. Given project-structure.md, When 갱신 후, Then 신규 로깅 모듈이 모듈 트리에 반영돼 있다.
+4. Given baseline 문서, When 확인, Then 실제 구현(REQ-084~088)과 모순이 없다.
+
+## Impacted Area
+- Docs: docs/runtime-flows.md, docs/project-structure.md
+- Modules: 없음(문서)
+- Tests: 없음(문서 — verification은 정합 리뷰)
+
+## Notes
+- 본 REQ는 P1 batch 구현 완료 후 정합한다(REQ-084~088 결과 반영).
+- 출처: dcy-029 FR-6.
+
+## Change Log
+
+### CHG-20260616-01
+- Date: 2026-06-16
+- Author: Justin Ko
+
+#### Change Summary
+- dcy-029 FR-6로부터 최초 생성(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-046 release-candidate, dcy-029 P1). 근거: 단위/문서 AC 매핑(REQ-086 reason+actor 로그·interface-contract; REQ-088 operator_report 집계·net PnL·KST 경계·CLI report; REQ-089 docs/operations.md 4영역; REQ-090 runtime-flows·project-structure 정합). 14 passed(report+safety_sell), 전체 537 passed/47 skipped 회귀 0, ruff clean. report direct-DB·Loki 실 적재는 release 운영 검증 위임. Blocking Issues 없음.