trex-core/docs/srs/Interface/req-098_alarm-envelope-wire-contract.md

req-098: 알람 envelope wire 계약 정의

• Status: Approved
• Type: Interface
• Priority: High
• Owner: trex-core-dev

Intent

• 제품군 모든 모듈(core/orb/tsl/kdh)이 알람을 발신할 때 사용할 표준 메시지 envelope 스키마를 trex-core가 wire 계약으로 정의하고 docs/interface-contract.md에 명시한다.
• 이 계약은 trex-notifier가 알람을 수집·분류할 때의 파싱 기준이 되며, 다른 모듈 repo(orb/tsl/kdh)와 trex-notifier가 이 문서를 단일 출처(source of truth)로 참조한다.
• 기존 wire 계약(slots RPC/trex.events/trex.control.req)은 일절 변경하지 않는다.

Requirement

• trex-core는 알람 envelope의 표준 JSON 스키마를 아래 필드로 정의하고, docs/interface-contract.md에 신규 섹션 Interface: trex.alerts (알람 채널, dcy-033)으로 버전드 명시해야 한다.
  • source :: str — 알람 발신 모듈 식별자 (예: "trex-core", "trex-orb-v1", "trex-tsl-v1", "kis-data-hub")
  • severity :: "critical" | "warn" | "info" — 등급 (소문자 리터럴)
  • code :: str — 알람 식별 코드 (예: "kill_switch_fired", "fill_price_unresolvable")
  • title :: str — 사람이 읽는 1행 요약
  • fields :: dict[str, any] — 선택 구조화 컨텍스트 (예: {"slot_id": "...", "symbol": "..."})
  • occurred_at :: ISO-8601 datetime string (UTC 또는 KST+09:00 offset 포함)
  • schema_version :: str — 현재 값 "1" (semver 주 버전 문자열; 소비자는 미인식 버전 무시·경고)
• 계약 섹션에 routing key 규약(alarm.{severity}.{source})과 exchange 이름(trex.alerts)을 함께 기술한다.
• 이 스키마를 변경(필드 추가 포함)하면 schema_version을 올리거나 additive 변경 여부를 명시하도록 Update Trigger를 문서에 포함한다.

Acceptance Criteria

1. Given docs/interface-contract.md에 Interface: trex.alerts (알람 채널, dcy-033) 섹션이 존재하지 않을 때, When REQ-098 구현을 완료하면, Then 해당 섹션이 위 7개 필드(source/severity/code/title/fields/occurred_at/schema_version)의 JSON 스키마 명세를 포함해야 한다.
2. Given 섹션이 추가됐을 때, When 명세를 검토하면, Then severity 값이 "critical" | "warn" | "info" 세 리터럴로 제한되고, schema_version="1"이 현재 버전으로 명시되어야 한다.
3. Given 명세가 추가됐을 때, When 기존 interface-contract.md의 다른 섹션(slots RPC/trex.events/trex.control.req/strategy_state)을 검토하면, Then 기존 섹션의 내용이 변경되지 않아야 한다(가산·격리 불변 — diff는 신규 섹션 추가뿐).
4. Given envelope 스키마 명세가 완성됐을 때, When routing key 규약을 확인하면, Then alarm.{severity}.{source} 형식이 명시되어야 한다.
5. Given 명세가 추가됐을 때, When Update Trigger를 확인하면, Then 알람 envelope 스키마 변경(breaking/additive 모두) 시 이 문서를 갱신해야 한다는 트리거가 포함되어야 한다.
6. Given 다른 모듈 repo(orb/tsl/kdh) 개발자가 알람 emitter를 구현할 때, When docs/interface-contract.md의 알람 계약 섹션을 읽으면, Then 자체 trex_core import 없이 envelope 구성에 필요한 모든 정보(필드·타입·필수 여부·schema_version·routing key)를 얻을 수 있어야 한다.

Impacted Area

• Docs: docs/interface-contract.md — 알람 채널 신규 섹션 추가(기존 섹션 불변)
• Modules: 코드 변경 없음(이 REQ는 문서 계약만; emitter 구현은 REQ-100)
• Tests: docs/interface-contract.md diff가 기존 섹션 변경 0임을 확인하는 검증(batch verification 단계에서 수동 검토 또는 diff assertion)

Notes

• 이 REQ는 계약 문서화만 담당한다. envelope을 실제로 직렬화·발행하는 Python 코드(알람 emitter)는 REQ-100이 담당한다.
• fields 값은 opaque dict — core/notifier 모두 내용을 강제 파싱하지 않는다. 각 code별 권장 fields는 ALARM-INVENTORY.md를 참조한다.
• occurred_at 형식: 권장은 KST+09:00 offset-aware ISO-8601(기존 코어 로깅 관례와 통일). UTC도 수용.
• 다른 모듈(orb/tsl/kdh)은 trex_core를 import하지 않는다. 이 계약은 문서 규약이며 런타임 공유 코드가 아니다(Discovery 제약 A-1).
• trex-notifier가 schema_version이 미인식인 envelope을 수신하면 경고 로그 후 무시한다(소비자 책임 — notifier REQ 범위).
• dcy-033 성공기준 S-1(CRITICAL 알람 텔레그램 도달)·S-3(wire 계약 무회귀)의 선행 계약.

Change Log

CHG-20260621-01

• Date: 2026-06-21
• Author: trex-core-dev

Change Summary

• REQ-098 신규 생성(Proposed). dcy-033 FR-1 대응: 알람 envelope wire 계약 문서화.

Intent

• dcy-033(제품군 알람 전달 체계) confirmed Discovery에서 요구하는 표준 알람 envelope 스키마를 trex-core wire 계약으로 정식화한다.

Acceptance Criteria Delta

• Added: AC-1~6 (신규 생성)
• Updated: (없음)
• Removed: (없음)

Impacted Area Delta

• Docs:
  • docs/interface-contract.md 신규 섹션 추가
• Modules:
  • 코드 변경 없음
• Tests:
  • interface-contract diff 검증(기존 섹션 불변 확인)

Delivery Trace Delta

• Batches: (미정, M2 이후 큐잉)
• Releases: (미정)

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: confirm-req 후 batch 편성 시 REQ-099/100/101과 묶어 단일 batch로 처리 예정

Validation Plan

• docs/interface-contract.md에 알람 채널 섹션이 추가됐는지 수동 확인
• 기존 섹션 diff=0 확인(grep 또는 수동 비교)
• 7개 필드·severity 리터럴·schema_version·routing key 규약이 모두 명시됐는지 체크리스트 검토