Metadata-Version: 2.4
Name: contracts-hj3415
Version: 0.5.2
Summary: DTO pakages for hj3415
Keywords: example,demo
Author-email: Hyungjin Kim <hj3415@gmail.com>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Typing :: Typed
License-File: LICENSE

# 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
        
        를 사용
        
    

