Files
trex-core/docs/srs/index.md
T

31 KiB
Raw Blame History

Software Requirement Specification Index

목적

  • 이 문서는 프로젝트의 SRS 운영 기준과 requirement 목록을 관리하는 entry point이다.
  • 개별 requirement의 상세 내용은 타입별 폴더 하위 req-XXX_*.md 파일에서 관리한다.

사용 방법

  1. 새로운 requirement가 필요하면 Next Requirement ID를 확인하고 docs/srs/req-template.md를 복사해 docs/srs/<Type>/req-XXX_<slug>.md 파일을 생성한다.
  2. 초안 작성은 draft-req, 승인 전환은 confirm-req, 변경 대응은 change-req, 구현 완료 전환은 confirm-req-implemented skill을 기준으로 수행한다.
  3. 작성 또는 수정 후 누락과 모호성을 점검한다.
  4. requirement 추가 또는 변경 후 Next Requirement ID, Requirement Register, Recent Change Log Summary를 함께 갱신한다.
  5. Proposed requirement를 승인하려면 승인 준비 상태와 blocker를 점검한다.
  6. Approved requirement는 구현 이슈나 작업 항목으로 연결한다.
  7. 구현과 검증이 끝난 requirement는 confirm-req-implemented skill로 완료 전환 가능 여부를 점검한다.
  8. requirement 변경 시 change-req skill을 기준으로 해당 REQ 파일의 Change Log를 먼저 갱신한 뒤 본문을 수정한다.
  9. 구현 전에는 관련 REQ 파일과 최근 Change Log를 기준으로 변경 범위를 판단한다.

상태 정의

  • Proposed: 초안 상태이며 구현 기준으로 확정되지 않음
  • Approved: 구현 기준으로 승인됨
  • Implemented: 구현과 검증이 완료됨
  • Deprecated: 더 이상 유지하지 않음

Status Transition Evidence

Proposed -> Approved

  • Status, Type, Priority, Owner, Intent, Requirement, Acceptance Criteria, Impacted Area, Change Log가 모두 존재해야 한다.
  • Type은 아래 분류 도표에서 정확하게 하나로 지정되어야 한다.
  • Acceptance Criteria는 구현 판단에 사용할 수 있을 정도로 구체적이어야 한다.
  • 미해결 assumption 또는 open question이 있으면 Notes에 명시하고, 승인 blocker 여부를 판단해야 한다.
  • 승인 전환 시 해당 REQ 파일의 Change Log에 status 변경 사유를 기록해야 한다.

Approved -> Implemented

  • 각 Acceptance Criteria에 대해 test, manual verification, 또는 구현 결과 중 최소 1개의 evidence가 있어야 한다.
  • evidence는 requirement 문서 자체 또는 연결된 구현/검증 결과에서 추적 가능해야 한다.
  • 미충족 Acceptance Criteria가 있으면 Implemented로 전환하지 않는다.
  • 구현 완료 전환 시 잔여 리스크와 미검증 영역이 있으면 Change Log에 기록해야 한다.
  • 상태 전환은 confirm-req-implemented skill을 기준으로 수행한다.

Requirement Change Handling

  • 기존 REQ 본문(Requirement, Acceptance Criteria, Impacted Area)을 수정하기 전에는 새 Change Log 항목을 만든다.
  • Change Log에는 최소한 Acceptance Criteria Delta, Impacted Area Delta, Delivery Trace Delta, Revalidation Impact, Validation Plan이 포함되어야 한다.
  • 변경이 기존 구현 또는 verification evidence를 무효화하면 Implemented requirement는 Approved로 되돌린다.
  • 변경이 승인 전제 자체를 다시 검토하게 만들면 Approved 또는 Implemented requirement를 Proposed로 되돌릴 수 있다.
  • 상태 되돌림이 발생하면 Requirement Register와 Recent Change Log Summary도 함께 갱신한다.

Requirement 타입 분류 도표

타입 정의 예시
Configuration 설정 옵션, 커스터마이징 포인트 설정 파라미터, 환경 변수, 옵션 항목
Data 데이터 구조, 저장/로드, 파일 형식, 스키마 설정 파일 형식, DB 스키마, API 구조
Deployment 배포 방식, 운영 절차, 배포 환경 컨테이너 배포, 스택 관리, 운영 가이드
Documentation 문서 작성, 가이드, 매뉴얼, 안내서 사용자 가이드, API 문서, 튜토리얼
Exception 오류 처리, 예외 복구, 재시도 전략 오류 복구, 검증 실패 처리, 폴백 전략
Installation 시스템 설치, 환경 구성, 초기화 절차 Docker 이미지 빌드, DB 마이그레이션, 사전 조건 설정
Integration 외부 시스템 연동, 플러그인, 확장 3rd party 연동, 플러그인 인터페이스
Interface 사용자 상호작용 방식 (UI, API, CLI, 제어방식) CLI 명령어, API 엔드포인트, 웹 UI 기능
Migration 데이터 이전, 버전 업그레이드 데이터 마이그레이션, 버전 호환성
Non-Functional 성능, 보안, 확장성, 호환성, 신뢰성 성능 목표, 보안 정책, 확장성
Testing 테스트 전략, QA 요구사항, 검증 방식 테스트 커버리지, 회귀 테스트, 수락 기준

Requirement 작성 규칙

  • 각 requirement는 고유 ID를 가진다. 예: REQ-001
  • 다음 신규 requirement 번호의 source of truth는 이 문서의 Next Requirement ID 섹션이다.
  • 새 requirement를 추가하거나 ID 충돌이 발생할 수 있는 변경을 했으면 Next Requirement ID를 함께 갱신한다.
  • 각 requirement는 Type을 명시해야 한다. 위 분류 도표 중 정확하게 하나로 선택하며, docs/srs/<Type>/ 폴더명도 같은 문자열을 사용한다.
  • 각 requirement는 Intent, Requirement, Acceptance Criteria, Impacted Area를 반드시 포함한다.
  • 모호한 표현("개선한다", "적절히 처리한다") 대신 관찰 가능하고 test 가능한 문장을 사용한다.
  • requirement 변경 사항은 해당 REQ 파일의 Change Log에 기록한다.
  • requirement 변경 시 영향 받는 batch/release와 재검증 필요 여부를 Change Log에 남긴다.
  • Recent Change Log Summary는 최신 5건만 유지한다.
  • status 전환은 Status Transition Evidence 기준을 따른다.

Next Requirement ID

  • Current: REQ-116
  • Rule: Requirement Register에 있는 가장 큰 REQ 번호보다 정확히 1 커야 한다.

Requirement Register

ID Title Type Status Priority Owner Link
REQ-001 trex-core Python 프로젝트 부트스트랩 Installation Implemented High project maintainers req-001
REQ-002 slot 순수 도메인 이식 및 공개 API 확정 Interface Implemented High project maintainers req-002
REQ-003 slot 도메인 단위테스트 이식 및 컬럼 계약 가드 Testing Implemented High project maintainers req-003
REQ-004 baseline 문서 planned→실제 정합 Documentation Implemented Medium project maintainers req-004
REQ-005 슬롯 코어 데몬 런타임 부트스트랩 Installation Implemented High project maintainers req-005
REQ-006 PostgreSQL SlotRepository 영속화 + 스키마 Data Implemented High project maintainers req-006
REQ-007 intent 제출 HTTP API + 멱등 Interface Implemented High project maintainers req-007
REQ-008 슬롯 read-only 조회 HTTP API Interface Implemented High project maintainers req-008
REQ-009 데몬/API/영속화 baseline 문서 정합 Documentation Implemented Medium project maintainers req-009
REQ-010 데몬 설정 .env 파일 로딩 Configuration Implemented Medium project maintainers req-010
REQ-011 BrokerPort 추상화 + paper/stub async 더블 Integration Implemented High project maintainers req-011
REQ-012 KIS Open API 브로커 어댑터 Integration Implemented High project maintainers req-012
REQ-013 주문 집행 루프 (claim·송신·체결·롤백) Integration Implemented High project maintainers req-013
REQ-014 주문 핸드오프 durability + reconciliation Exception Implemented High project maintainers req-014
REQ-015 브로커/집행 baseline 문서 정합 Documentation Implemented Medium project maintainers req-015
REQ-016 KIS 인증 토큰 Redis 캐시 Integration Implemented Medium project maintainers req-016
REQ-017 LedgerPort 추상화 + portfolio-hub 어댑터 + stub Integration Implemented High project maintainers req-017
REQ-018 체결→원장 기록 (집행 루프 fill hook) Integration Implemented High project maintainers req-018
REQ-019 ledger outbox durability + correlation_id 멱등 Exception Implemented High project maintainers req-019
REQ-020 ledger 레이어 baseline 문서 정합 Documentation Implemented Medium project maintainers req-020
REQ-021 messaging 토폴로지 + 메시지 계약 매핑 Integration Implemented High project maintainers req-021
REQ-022 messaging transport 포트 + RabbitMQ 어댑터 + stub + sync+thread daemon Integration Implemented High project maintainers req-022
REQ-023 messaging delivery 신뢰성 (effectively-once + durable + DLQ + publisher confirms) Exception Implemented High project maintainers req-023
REQ-024 RabbitMQ 가용성 degrade 정책 (버퍼링 금지 + 보수적 중단 + core 안전 매도 독립) Non-Functional Implemented High project maintainers req-024
REQ-025 HTTP /v1 API 완전 제거 (healthz 포함, HTTP 표면 0) Interface Implemented High project maintainers req-025
REQ-026 messaging 레이어 baseline 문서 정합 Documentation Implemented Medium project maintainers req-026
REQ-027 portfolio-hub read 포트 + 어댑터 + stub Integration Implemented High project maintainers req-027
REQ-028 종목 스냅샷 read 메시지 계약 + envelope + degraded 신호 Interface Deprecated High project maintainers req-028
REQ-029 자산 선별(slot overlay) + view 모드 + strategy_key 필터 Interface Implemented High project maintainers req-029
REQ-030 일일 스냅샷 스케줄러 + 옵션 D 현금/포지션 갱신 Integration Implemented High project maintainers req-030
REQ-031 포지션 정합 검증 + warning 마스킹 Exception Implemented High project maintainers req-031
REQ-032 런타임 pause/resume 제어 (+운영자 CLI 표면) Interface Implemented Medium project maintainers req-032
REQ-033 스냅샷 read 레이어 baseline 문서 정합 Documentation Implemented Medium project maintainers req-033
REQ-034 per-slot 워치독 — snapshot RPC 기반 전략 모듈 활성 감지 Interface Implemented High project maintainers req-034
REQ-035 슬롯 가격 임계값 도메인 필드 + DB 마이그레이션 Data Implemented High project maintainers req-035
REQ-036 자동 매도 내부 경로 — SlotService.sell + idempotency Interface Implemented High project maintainers req-036
REQ-037 forced_close_at 만기 자동 매도 루프 Integration Implemented High project maintainers req-037
REQ-038 stop-loss·take-profit KIS 가격 polling + 트리거 Integration Implemented High project maintainers req-038
REQ-039 장 마감 강제 청산 (TREX_MARKET_CLOSE_LIQUIDATION_TIME) Integration Implemented High project maintainers req-039
REQ-040 update_thresholds intent RPC 액션 Interface Implemented High project maintainers req-040
REQ-041 safety-sell 환경 설정 — 5종 env var Configuration Implemented High project maintainers req-041
REQ-042 safety-sell baseline 문서 정합 Documentation Implemented Medium project maintainers req-042
REQ-043 trex.control.req 제어 채널 + action dispatch Interface Implemented High project maintainers req-043
REQ-044 kill-switch day-scoped 제외 store + 마이그레이션 Data Implemented High project maintainers req-044
REQ-045 kill-switch 실행 — 범위별 holding 즉시 청산 + 이력 Interface Implemented High project maintainers req-045
REQ-046 kill-switch 당일 제외 masking + 자동해제 + resume Interface Implemented High project maintainers req-046
REQ-047 kill-switch baseline 문서 정합 Documentation Implemented Medium project maintainers req-047
REQ-048 per-instance TOML 설정 로더 + --config 필수 Configuration Implemented High project maintainers req-048
REQ-049 instance_key 기반 동적 큐명 + default 하위호환 Interface Implemented High project maintainers req-049
REQ-050 trex.direct(topic) + trex.broadcast(fanout) exchange + 바인딩 Integration Implemented High project maintainers req-050
REQ-051 multi-instance topology baseline 문서 정합 Documentation Implemented Medium project maintainers req-051
REQ-052 safety-sell per-slot 재시도 쿨다운 + 영속 거부 경고 Integration Implemented High project maintainers req-052
REQ-053 safety-sell 재시도 쿨다운 env 설정 2종 Configuration Implemented Medium project maintainers req-053
REQ-054 safety-sell 쿨다운 runtime-flows 정합 Documentation Implemented Low project maintainers req-054
REQ-055 closed 슬롯 ↔ ledger_outbox 누락 운영 점검 쿼리 Exception Implemented Medium project maintainers req-055
REQ-056 자산 영구 슬롯 스키마 재설계 + 마이그레이션 Data Implemented High project maintainers req-056
REQ-057 자산 영구 슬롯 상태머신 재정의 + 인스턴스 스코프 advisory lock Interface Implemented High project maintainers req-057
REQ-058 universe 기반 슬롯 lifecycle reconcile (생성/soft-retire/tombstone) Integration Implemented High project maintainers req-058
REQ-059 활성 capacity 제어 + 신호 기반 admission (FCFS·M캡·무치환·over-cap) Interface Implemented High project maintainers req-059
REQ-060 동시 활성 최대치(max_active_slots) per-instance TOML 설정 Configuration Implemented High project maintainers req-060
REQ-061 intent 계약 자산(portfolio_id) 키 통일 + 중복/무효 규칙 Interface Implemented High project maintainers req-061
REQ-062 수량 hub 정본+로컬 미러 + holding↔broker/hub 불일치 해소 Integration Implemented High project maintainers req-062
REQ-063 운영자 표면 단일화 — slots = 자산 포지션 단일 뷰 Interface Implemented Medium project maintainers req-063
REQ-064 풀 모델 → 자산 중심 DB 재초기화 (구 cutover) Migration Implemented High project maintainers req-064
REQ-065 자산 중심 모델 baseline 문서 정합 + 풀 모델 폐기 명시 Documentation Implemented Medium project maintainers req-065
REQ-066 보유 자산 포지션 사이징 — 증액·부분 감액 (수량/avg_price 재계산) Interface Implemented High project maintainers req-066
REQ-067 포지션 사이징 baseline 문서 정합 Documentation Implemented Medium project maintainers req-067
REQ-068 intent 실행 정책 계약 — timeout_sec + slippage_pct Interface Implemented High project maintainers req-068
REQ-069 주문 timeout 집행 + 취소-체결 race 처리 Integration Implemented High project maintainers req-069
REQ-070 slippage 보호 지정가 집행 Integration Implemented High project maintainers req-070
REQ-071 운영자 강제 취소 백스톱 (trex-core cancel) Interface Implemented Medium project maintainers req-071
REQ-072 실행 정책 baseline 문서 정합 Documentation Implemented Medium project maintainers req-072
REQ-073 전략 read 표면 — trex.slots.req RPC 계약 (filter/spy, snapshot.req 즉시 교체) Interface Implemented High project maintainers req-073
REQ-074 슬롯 단일 행 스키마 — 자산·워치독·overlay 흡수 + 필드별 정본 라벨 Data Implemented High project maintainers req-074
REQ-075 slots read 표면 baseline 문서 정합 Documentation Implemented Medium project maintainers req-075
REQ-076 watchdog timeout per-instance TOML 설정 Configuration Implemented High project maintainers req-076
REQ-077 중장기 인스턴스 운영 프로파일 — 표준 TOML 레시피 + 기동 검증 Configuration Implemented High project maintainers req-077
REQ-078 중장기 운영 baseline 문서 정합 — 보호 규칙 경계 + forced_close_at 미사용 Documentation Implemented Medium project maintainers req-078
REQ-079 Slot strategy-state 저장소 — slot_strategy_state 테이블 + StrategyStateStore + occupancy_seq·version CAS Data Implemented High project maintainers req-079
REQ-080 trex.slots.strategy_state.set write RPC 계약 — occupancy_seq·version CAS Interface Implemented High project maintainers req-080
REQ-081 슬롯 occupancy_seq 정합성 가드 + close 시 strategy_state 삭제 불변식 Data Implemented High project maintainers req-081
REQ-082 strategy-state baseline 문서 정합 — read/write/삭제 흐름 + occupancy_seq 가드 Documentation Implemented Medium project maintainers req-082
REQ-083 KRX 호가단위(tick) 산출 유틸 — 가격→tick + 배수 내림/올림 Integration Implemented High project maintainers req-083
REQ-084 구조화 로깅 기반 — ISO8601(KST)·레벨·Loki JSON·correlation id Non-Functional Implemented High project maintainers req-084
REQ-085 주문 결과 로깅 — submit/체결/거부 일관 tailable 로그 Integration Implemented High project maintainers req-085
REQ-086 청산 reason+actor 동반 노출 — 안전망/전략 구분 가시화 Interface Implemented Medium project maintainers req-086
REQ-087 주문 거부 ERROR 가시성 — 조용한 롤백 제거 Non-Functional Implemented High project maintainers req-087
REQ-088 운영 조회 CLI — 보유·오늘 체결·실현 PnL·대기 주문 Interface Implemented High project maintainers req-088
REQ-089 운영자 런북 — docs/operations.md 신설 Documentation Implemented Medium project maintainers req-089
REQ-090 관측성 baseline 문서 정합 — 로깅/관측성·PnL 조회 흐름 Documentation Implemented Medium project maintainers req-090
REQ-091 이벤트 발행 재시도 + 강제 재연결 (idle 후 첫 발행 무유실) Exception Implemented High project maintainers req-091
REQ-092 발행 전용 연결 idle keepalive (서버 측 heartbeat 사망 예방) Exception Implemented High project maintainers req-092
REQ-093 DLQ 가시성/경보 + emit 실패 경보 (trex.events.dlq 관측성) Exception Implemented High project maintainers req-093
REQ-094 이벤트 발행 신뢰성 baseline 문서 정합 (runtime-flows / project-structure / operations 갱신) Documentation Implemented Medium project maintainers req-094
REQ-095 체결가 0/None 지정가 백필 가드 (슬롯 평단 + 원장 price) Exception Implemented High trex-core-dev req-095
REQ-096 체결가 백필·0가격 통과 WARN 로깅 Exception Implemented High trex-core-dev req-096
REQ-097 알람(alert) 능력 검토 스파이크 산출물 Documentation Implemented Medium trex-core-dev req-097
REQ-098 알람 envelope wire 계약 정의 Interface Implemented High trex-core-dev req-098
REQ-099 trex.alerts AMQP exchange 토폴로지 + 가산·격리 불변식 Integration Implemented High trex-core-dev req-099
REQ-100 trex-core 알람 emitter — CRITICAL code 발신 배선 Integration Implemented High trex-core-dev req-100
REQ-101 알람 발신 흐름 baseline 문서 정합 Documentation Implemented Medium trex-core-dev req-101
REQ-102 reconcile-warning durable store — slot_id/pid 키 별도 테이블 Data Implemented High trex-core-dev req-102
REQ-103 차단형 reconcile — B/C 불일치 슬롯 reconcile-warning 전이 Integration Implemented High trex-core-dev req-103
REQ-104 전략 차단 게이트 — pause ∨ reconcile-warning OR 게이트 (안전망 예외) Interface Implemented High trex-core-dev req-104
REQ-105 trex-core sync 명령 — 슬롯 수량을 브로커에 맞춰 갱신 + warning 해제 (INACTIVE→HOLDING OQ-A) Interface Implemented High trex-core-dev req-105
REQ-106 trex-core verify 명령 — C 불일치 슬롯 재대조 + warning 해제 (C 전용 OQ-C) Interface Implemented High trex-core-dev req-106
REQ-107 차단/해제 전이 식별 로깅 + 고영향 불일치 알람 Exception Implemented High trex-core-dev req-107
REQ-108 차단형 reconcile 비기능 요건 — 내구성·회귀 방지·자동 정정 금지·wire 계약 최소 침습 Non-Functional Implemented High trex-core-dev req-108
REQ-109 portfolio-hub /pnl/realized read 포트 메서드 + HTTP 어댑터 Integration Implemented High trex-core-dev req-109
REQ-110 운영 리포트 WAC 실현손익 통합 — 전 인스턴스 공통 Interface Implemented High trex-core-dev req-110
REQ-111 운영 리포트 — portfolio-hub 미가용 시 실현손익 섹션 에러 degrade Exception Implemented High trex-core-dev req-111
REQ-112 portfolio-hub broker credential read 포트 메서드 + HTTP 어댑터 Integration Implemented High trex-core-dev req-112
REQ-113 KISConfig 소스 우선순위 — portfolio-hub fetch 1차 + env break-glass + opt-in Configuration Approved High trex-core-dev req-113
REQ-114 그날-시작 로드 게이트 — fail-closed 신규 진입 차단 + 알람 Integration Implemented High trex-core-dev req-114
REQ-115 그날-시작 장중 무중단 보장 — 그날 고정 인증정보 캐시 + portfolio-hub 장애 비중단 Non-Functional Approved High trex-core-dev req-115

Recent Change Log Summary

  • 2026-06-28 :: REQ-112/114 Approved → Implemented, REQ-113/115 Approved 유지(confirm-req-implemented, dcy-036/BAT-053): BAT-053 PR #34 머지(01655ab). QC PASS-WITH-NOTES(opus, blocker 0). 745 passed/0 회귀. REQ-112(fetch 포트+어댑터+stub AC-18 완료), REQ-114(fail-closed 게이트 AC-19, BuyIntent 차단/SellIntent 통과 비대칭·CRITICAL 알람·opt-in off 비활성 완료). REQ-113/115 스캐폴드 완료 — KISBroker 런타임 재조립(REQ-113 AC-2, REQ-115 AC-1) M3 후속 batch 연기.
  • 2026-06-28 :: REQ-112~115 Proposed → Approved(confirm-req 팀장 승인): dcy-036 FR/NFR 추적·AC testable·blocker 0. 진입 fail-closed/청산·DISPATCHED 통과 비대칭(REQ-114 AC-4/5), 그날 고정 캐시·ledger 무손실(REQ-115), TradingContext 원자 read(REQ-112), opt-in 회귀차단(REQ-113 AC-1). OQ-4(trex-notifier) Deferred. 선행 의존 portfolio-hub dcy-010(머지완료). 다음=suggest-batch-reqs.
  • 2026-06-26 :: REQ-109111 Approved → Implemented (confirm-req-implemented, dcy-035): BAT-052 머지(PR #33, 81d06d9) 완료. QC PASS. 717 passed/47 skipped/0 fail. REQ-109(portfolio-hub /pnl/realized 포트+어댑터+stub AC-16), REQ-110(WAC 운영리포트 통합 AC-17, CHG-20260626-02 buy_fee편입 반영), REQ-111(degrade AC-15) 전 AC 검증 완료. M3 배포 대기.
  • 2026-06-26 :: REQ-102~108 Approved → Implemented (confirm-req-implemented, dcy-034): BAT-050(core-A, PR #31 ced7eda) + BAT-051(core-B, PR #32 07b393d) origin/main 머지 완료. QC(opus) PASS + 팀장 confirm-batch-verification. 최종 683 passed/47 skipped/0 fail. 차단형 reconcile(REQ-102·103), 전략 차단 게이트(REQ-104), sync/verify CLI(REQ-105·106), 차단/해제 로깅+알람(REQ-107), NFR(REQ-108) 전 AC 검증 완료. M3 배포 대기.
  • 2026-06-26 :: REQ-109~111 신규 생성(Proposed, draft-req dcy-035): 멀티데이 실현 PnL — WAC 기반 운영 리포트. REQ-109(portfolio-hub /pnl/realized read 포트+어댑터+stub), REQ-110(운영 리포트 WAC 실현손익 통합: 전 인스턴스 공통, 매수일 수수료 별도, completeness 경고), REQ-111(portfolio-hub 미가용 시 실현손익 섹션 에러 degrade, 폴백 없음). NFR-1(wire 불변)/NFR-3(데몬 격리)은 REQ-111 AC/Notes 흡수. NFR-2(일중 WAC==net 회귀)는 REQ-110 AC-2 흡수. OQ-2(기간)/OQ-3(수수료 출처)/OQ-4(N콜) design 인계.