trex-core/docs/srs/index.md

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-066
• 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	Implemented	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

Recent Change Log Summary

• 2026-06-10 :: REQ-056~065 신규 생성(Proposed) (draft-req, dcy-020 자산 중심 슬롯 모델 재설계): 익명 슬롯 풀 → portfolio-hub universe 자산과 1:1 영구 슬롯 + 동시 활성(M) 제어로 substrate 전환. REQ-056(영구 슬롯 스키마·UNIQUE(instance_key,portfolio_id)·trading_date/entry_count 제거), REQ-057(상태머신 inactive↔pending_buy↔holding↔pending_sell·holding 로컬·인스턴스 스코프 lock), REQ-058(universe reconcile 생성/soft-retire/tombstone·degrade 보류·일일 preallocation 폐기), REQ-059(FCFS·M캡·무치환·over-cap), REQ-060(max_active_slots per-instance TOML), REQ-061(intent 자산 키 통일·sell-by-slot_id 폐기), REQ-062(수량 hub 정본+미러·청산 브로커·불일치 해소), REQ-063(slots 단일 뷰), REQ-064(풀→영구 cutover), REQ-065(baseline 정합·폐기 명시). 기존 REQ-002/003/005/006/007/048 등은 폐기/재정의 change-req 동반 예정. 단계적 배치(스키마·상태머신 → reconcile·admission → intent·수량·CLI → cutover) delivery. 전부 Proposed(confirm-req 대기). (draft-req)
• 2026-06-09 :: REQ-048/010 change-req→Implemented (CHG-20260609-01/02, trex-orb-v1 설정 관리 정합, BAT-026): config 디렉터리 기반 설정 관리 도입 — --config 를 이름으로 해석 + --config-path <dir>(기본 ./config) + resolve_config_toml(슬래시 포함 값은 하위호환 명시 경로)(REQ-048), .env 를 config-dir 결정적 해석(--env-file 우선, 없으면 <config_dir>/.env, CWD 무관)으로 변경 + config/.env.example + .gitignore config/* 허용목록(REQ-010). 운영자 CLI 도 --config-path/--env-file 동일 적용. from_env() legacy 루트 .env 폴백 유지로 완전 하위호환(.env 이동은 운영 배포 시 무중단). batch-lite(BAT-026) 단위 23 + 전체 375 passed, ruff clean, 라이브 스모크(name·path 동일 결과) → 둘 다 Implemented. (change-req/confirm-req-implemented)
• 2026-06-09 :: REQ-002/003/006/007/009 change-req (CHG-20260609-01, dcy-019/issue #18, BAT-025): slot-scoped entry_count 추가 + closed 슬롯 직접 재할당. daily_slot/Slot 에 entry_count(기본 0) 필드 + EXPECTED_SLOT_FIELDS + 멱등 마이그레이션 008(REQ-002/006), 상태 머신 closed→pending_buy 신규 전이(8→9 base, ALLOWED_TRANSITIONS 14→15)(REQ-002), _apply_transition_fields closed→pending_buy clean-slate + 모든 →pending_buy 시 entry_count +1(REQ-002), find_allocatable_slot(idle∪closed, entry_count→updated_at→slot_id) selector + in-memory 동등(REQ-006), _admit_buy find_idle_slot→find_allocatable_slot + from_state=slot.status(REQ-007), 테스트 계약 정합(REQ-003), baseline 2문서(data-model/runtime-flows) 정합(REQ-009). 기존 daily_symbol_entries(symbol-scoped) 무관·미변경. 전부 change-req(신규 REQ 없음, OQ-1/2/3). 단위 366 passed(+KIS sandbox 1건은 live .env URL 로 사전 환경 실패·무관), ruff clean. PG 게이트 마이그레이션/드리프트는 라이브 runtime DSN 미사용(파괴적 truncate 회피)·test DSN 자동 검증. 전부 Implemented 유지. (change-req)
• 2026-06-09 :: REQ-032 change-req→Implemented (CHG-20260609-01/02, issue #17, BAT-024): trex-core enter 에 --forced-close-at <ISO8601> (절대시간) 옵션 추가 — 운영자가 매수 진입 명령 하나로 시간 기반 자동청산(forced_close) 시각 지정. CLI 가 buy intent payload 의 기존 forced_close_at 필드에 매핑(계약 REQ-007/021·도메인 REQ-066·forced-close 루프 REQ-037 이미 구현·불변, CLI 노출 갭만 보완). 잘못된 형식 제출 전 거부, 미지정 시 미포함(하위호환). 상대시간(--hold-minutes) 미채택. AC-5/6 신규. batch-lite(BAT-024) 단위 검증 → Implemented. 단위 353 passed, ruff clean. (change-req/confirm-req-implemented)
• 2026-06-08 :: REQ-017/019/029 change-req + REQ-030 Approved→Implemented (dcy-018, BAT-023): ledger write 응답의 권위 cash/quantity 를 portfolio 스냅샷에 write-back(option D 활성화) — 매수/매도 직후 "수량 live·현금 stale" 비대칭 제거. record_trade→LedgerWriteOutcome{result, *_after}+어댑터 cash_balance_after/asset_quantity_after 파싱(new+duplicate)(REQ-017), LedgerWriter SnapshotStore write-back best-effort+pending_cash_delta(REQ-019), 추정 현금 오버레이(cash_estimated 라벨)+슬롯 오버레이 유지(REQ-029, OQ-1 B/OQ-4 i), option D 활성화로 REQ-030 Approved→Implemented. 전부 change-req(신규 REQ 없음, OQ-3 a). portfolio-hub#8(*_after) 동작 중. 단위 350 passed, 인프라 게이트 385 passed, ruff clean. (change-req/confirm-req-implemented)
• 2026-06-10 :: REQ-056~065 Approved → Implemented (confirm-req-implemented): dcy-020 자산 중심 슬롯 모델 4개 배치(BAT-027 α/BAT-028 β/BAT-029 γ/BAT-030 δ, 전부 release-candidate) verification evidence 기준. BAT-030 에서 literal inactive·컬럼 drop·매도 수량 브로커 정본·cutover 도구·baseline 마감 완성, run-the-app 자산 중심 e2e green. 실 운영 cutover(REQ-064)는 REL 단계 운영자 실행.
• 2026-06-10 :: REQ-064 재정의 (change-req CHG-20260610-03): 데이터 보존 cutover → DB 재초기화(trex-core-reset). 마이그레이션 009 부분 유니크 인덱스가 legacy 풀 중복 데이터에 적용 불가한 결함 + dev/페이퍼 컨텍스트 → wipe+자산 중심 재초기화로 대체. 구 trex-core-cutover 도구·테스트 삭제, tests/runtime/test_reset.py 신규. Status Implemented 유지(reset evidence). (BAT-030)