contracts-hj3415 0.5.3

DTO pakages for hj3415

Contracts-hj3415

1) 3가지 Envelope DTO (정확한 타입명 / 파일 경로)

A. NfsEnvelopeDTO

• 파일: contracts_hj3415/common/envelope.py

• 타입명: class NfsEnvelopeDTO(TypedDict)

필드

• topic: Literal["nfs"]

• key: CodeKey  (contracts_hj3415/common/types.py에서 CodeKey = str)

• asof: datetime

• payload: NfsPayloadDTO  (contracts_hj3415/nfs/payloads.py)

• meta: EnvelopeMeta  (contracts_hj3415/common/types.py)

팩토리

• make_nfs_envelope(...) -> NfsEnvelopeDTO (contracts_hj3415/common/envelope.py)

---

B. UniverseEnvelopeDTO

• 파일: contracts_hj3415/common/envelope.py

• 타입명: class UniverseEnvelopeDTO(TypedDict)

필드

• topic: Literal["universe"]

• key: Universe (contracts_hj3415/universe/types.py의 Universe = Literal["KRX300"])

• asof: datetime

• payload: UniversePayloadDTO (contracts_hj3415/universe/payloads.py)

• meta: EnvelopeMeta

팩토리

• make_universe_envelope(...) -> UniverseEnvelopeDTO (contracts_hj3415/common/envelope.py)

---

C. AnalysisEnvelopeDTO

• 파일: contracts_hj3415/common/envelope.py

• 타입명: class AnalysisEnvelopeDTO(TypedDict)

필드

• topic: Literal["analysis"]

• key: CodeKey (str)

• asof: datetime

• payload: AnalysisPayloadDTO (contracts_hj3415/analysis/payloads.py)

• meta: EnvelopeMeta

팩토리

• make_analysis_envelope(...) -> AnalysisEnvelopeDTO (contracts_hj3415/common/envelope.py)

---

2) 공통 타입(정확한 타입명 / 파일 경로)

common/types.py

• 파일: contracts_hj3415/common/types.py

타입들

• Topic = Literal["nfs", "universe", "analysis"]

• CodeKey = str

• Num = float | int | None

• Source = Literal["", "scraper2", "krx", "analyser2"]

• class EnvelopeMeta(TypedDict, total=False):

  • source: Source

  • trace_id: str

  • note: str

  • tags: list[str]

---

3) payload 유니온(정확한 타입명 / 파일 경로)

A. NFS payload

• 파일: contracts_hj3415/nfs/payloads.py

• 타입명: NfsPayloadDTO

NfsPayloadDTO = C101Payload | C103Payload | C104Payload | C106Payload | C108Payload

각 payload 정의 파일:

• contracts_hj3415/nfs/c101.py → C101Payload (필드: endpoint: Literal["c101"], blocks: C101Blocks)

• contracts_hj3415/nfs/c103.py → C103Payload (필드: endpoint: Literal["c103"], blocks, labels)

• contracts_hj3415/nfs/c104.py → C104Payload

• contracts_hj3415/nfs/c106.py → C106Payload

• contracts_hj3415/nfs/c108.py → C108Payload

공통 키/엔드포인트 타입:

• 파일: contracts_hj3415/nfs/types.py

  • Endpoint = Literal["c101","c103","c104","c106","c108"]

  • MetricKey = str

  • PeriodKey = str

  • BlockKey = ... (각 C101~C108 블록 리터럴 유니온)

---

B. Universe payload

• 파일: contracts_hj3415/universe/payloads.py

• 타입명: UniversePayloadDTO = KRX300Payload

• KRX300Payload 정의: contracts_hj3415/universe/krx300.py

  • class UniverseItem(TypedDict, total=False): code/name/market/meta

  • class KRX300Payload(TypedDict): source, universe, blocks: list[UniverseItem]

• Universe 타입: contracts_hj3415/universe/types.py (Universe = Literal["KRX300"])

---

C. Analysis payload

• 파일: contracts_hj3415/analysis/payloads.py

• 타입명: AnalysisPayloadDTO = FeaturesPayload

• FeaturesPayload 정의: contracts_hj3415/analysis/features.py

  • service: Literal["features"]

  • endpoint: Endpoint (nfs Endpoint 사용)

  • blocks: dict[MetricKey, LatestAndTtm]

• AnalysisService 타입: contracts_hj3415/analysis/types.py

  • AnalysisService = Literal["features","red"] (현재 payload는 features만 연결돼 있음)

---

4) 앞으로 “모든 프로젝트 코딩 시” 적용 기준

너희 모노레포에서 “프로젝트 간 통신”은 앞으로 무조건 아래처럼만:

• scraper2 → db2 : NfsEnvelopeDTO

• krx → db2 : UniverseEnvelopeDTO

• analyser2 → db2 : AnalysisEnvelopeDTO

• 그 외 어떤 프로젝트 간 이동도 이 3종 envelope 중 하나로만 주고받기

그리고 생성은 원칙적으로:

• contracts_hj3415/common/envelope.py의

  • make_nfs_envelope

  • make_universe_envelope

  • make_analysis_envelope

    를 사용