portfolio-hub/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. Approved requirement를 승인하려면 승인 준비 상태와 blocker를 점검한다.
6. Approved requirement는 구현 이슈나 작업 항목으로 연결한다.
7. 구현과 검증이 끝난 requirement는 confirm-req-implemented skill로 완료 전환 가능 여부를 점검한다.
8. requirement 변경 시 change-req skill을 기준으로 해당 REQ 파일의 Change Log를 먼저 갱신한 뒤 본문을 수정한다.
9. 구현 전에는 관련 REQ 파일과 최근 Change Log를 기준으로 변경 범위를 판단한다.

상태 정의

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

Status Transition Evidence

Approved -> 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를 Approved로 되돌릴 수 있다.
• 상태 되돌림이 발생하면 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-057
• Rule: Requirement Register에 있는 가장 큰 REQ 번호보다 정확히 1 커야 한다.

Requirement Register

ID	Title	Type	Status	Priority	Owner	Link
REQ-001	tags 마스터 테이블 도입	Data	Implemented	High	Justin Ko	req-001
REQ-002	assets.tag_ids UUID[] 컬럼 추가	Data	Implemented	High	Justin Ko	req-002
REQ-003	portfolios.tag_ids UUID[] 컬럼 추가 및 portfolio_tags 테이블 제거	Data	Implemented	High	Justin Ko	req-003
REQ-004	tags 마스터 HTTP API	Interface	Implemented	High	Justin Ko	req-004
REQ-005	태그 적용·해제 HTTP API	Interface	Implemented	High	Justin Ko	req-005
REQ-006	portfolio_tags 데이터 마이그레이션	Migration	Implemented	High	Justin Ko	req-006
REQ-007	pfhub tag CLI 명령어	Interface	Implemented	Medium	Justin Ko	req-007
REQ-008	태그 모델 도입 baseline 문서 갱신	Documentation	Implemented	Low	Justin Ko	req-008
REQ-009	assets 테이블 스키마 도입	Data	Implemented	High	Justin Ko	req-009
REQ-010	admin asset catalog CRUD	Interface	Implemented	High	Justin Ko	req-010
REQ-011	portfolios asset_id FK 추가 및 symbol/market 제거	Data	Implemented	High	Justin Ko	req-011
REQ-012	portfolio 생성 CLI catalog 검증	Interface	Implemented	High	Justin Ko	req-012
REQ-013	GET /v1/assets 토큰 타입별 분기 재정의	Interface	Deprecated	High	Justin Ko	req-013
REQ-014	portfolios 데이터 migration	Migration	Implemented	High	Justin Ko	req-014
REQ-015	asset catalog 도입 baseline 문서 갱신	Documentation	Implemented	Low	Justin Ko	req-015
REQ-016	client token 발급 경로 코드 폐지	Interface	Implemented	High	Justin Ko	req-016
REQ-017	service-token rotate unique index 보강	Migration	Implemented	High	Justin Ko	req-017
REQ-018	POST /auth/service-tokens body daemon_id forward 보정	Interface	Implemented	High	Justin Ko	req-018
REQ-019	토큰 surface baseline 문서 정합성 회복	Documentation	Implemented	Medium	Justin Ko	req-019
REQ-020	토큰 발급 권한 매트릭스 정의	Documentation	Implemented	Medium	Justin Ko	req-020
REQ-021	토큰 만료·회전 정책 정의	Documentation	Implemented	Medium	Justin Ko	req-021
REQ-022	daemon deactivation 시 바인딩 service token 자동 revoke	Interface	Implemented	High	Justin Ko	req-022
REQ-023	NULL daemon_id legacy token 마이그레이션 CLI	Interface	Implemented	Medium	Justin Ko	req-023
REQ-024	env admin token 운영 SOP 정의	Documentation	Implemented	Medium	Justin Ko	req-024
REQ-025	POST /v1/portfolios 신설 (토큰 분기 + catalog 검증)	Interface	Implemented	High	Justin Ko	req-025
REQ-026	PATCH /v1/portfolios/{portfolio_id} 신설	Interface	Implemented	High	Justin Ko	req-026
REQ-027	DELETE /v1/portfolios/{portfolio_id} 신설 (soft delete)	Interface	Implemented	High	Justin Ko	req-027
REQ-028	GET /v1/portfolios 신설 (토큰 분기 조회)	Interface	Implemented	High	Justin Ko	req-028
REQ-029	POST /v1/portfolios/{portfolio_id}/ledger/trades 이전	Interface	Implemented	High	Justin Ko	req-029
REQ-030	portfolio tag 적용/해제/조회 v1 라우트	Interface	Implemented	Medium	Justin Ko	req-030
REQ-031	portfolio comment CRUD v1 라우트	Interface	Implemented	Medium	Justin Ko	req-031
REQ-032	portfolio v1 baseline 문서 갱신	Documentation	Implemented	Medium	Justin Ko	req-032
REQ-033	ledger_trades.asset_id → portfolio_id 컬럼명 정합화	Migration	Implemented	Medium	Justin Ko	req-033
REQ-034	LoginRequest 추가 필드 거부 enforcement	Interface	Implemented	Medium	Justin Ko	req-034
REQ-035	GET /health 응답에 db_enabled 필드 추가	Interface	Implemented	Medium	Justin Ko	req-035
REQ-036	portfolio_ledger 회계 원장 통합 마이그레이션 (ledger_trades 흡수/DROP)	Migration	Implemented	High	Justin Ko	req-036
REQ-037	신 path 회계 책임 단일화 + 응답에 portfolio 상태 포함	Interface	Implemented	High	Justin Ko	req-037
REQ-038	레거시 buy/sell endpoint deprecated 표기	Interface	Implemented	Low	Justin Ko	req-038
REQ-039	GET /v1/portfolios/{id}/trades 체결 내역 조회 엔드포인트 신설	Interface	Implemented	High	Justin Ko	req-039
REQ-040	GET /v1/portfolios/{id}/pnl/realized 실현 PnL 집계 엔드포인트 신설	Interface	Implemented	High	Justin Ko	req-040
REQ-041	WAC 기반 cost_basis 산출 및 실현 PnL 계산 로직 (service/domain 계층 격리)	Integration	Implemented	High	Justin Ko	req-041
REQ-042	체결 내역/실현 PnL API 테스트 커버리지 (WAC 시나리오 기댓값 대조, 날짜 필터, 422)	Testing	Implemented	High	Justin Ko	req-042
REQ-043	GET /v1/portfolios/{id}/holdings/cost-basis 현재 보유 평단(WAC) read 엔드포인트 신설	Interface	Implemented	High	Justin Ko	req-043
REQ-044	GET /v1/assets 권한 완화 — require_admin → require_read	Interface	Implemented	High	Justin Ko	req-044
REQ-045	사용자 가용 데몬 목록 read 엔드포인트 신설	Interface	Implemented	High	Justin Ko	req-045
REQ-046	BrokerCredential 도메인 모델 daemon_id 필드 추가	Data	Implemented	High	Justin Ko	req-046
REQ-047	broker_credentials 테이블 daemon-scoped PK 전환 마이그레이션	Migration	Implemented	High	Justin Ko	req-047
REQ-048	기존 user-scoped 인증정보 daemon_id 백필	Migration	Implemented	High	Justin Ko	req-048
REQ-049	GET /v1/user_info daemon-scoped 단일 broker 전달로 확장	Interface	Implemented	High	Justin Ko	req-049
REQ-050	credential CLI --daemon-id 옵션 추가	Interface	Implemented	High	Justin Ko	req-050
REQ-051	브로커 인증정보 보안 격리 — service-token 전용·web 토큰 차단	Non-Functional	Implemented	High	Justin Ko	req-051
REQ-052	사용자 소유 스코프 인증정보 관리 HTTP API	Interface	Implemented	High	Justin Ko	req-052
REQ-053	admin 데몬 CRUD HTTP API	Interface	Implemented	High	Justin Ko	req-053
REQ-054	인증정보 관리 보안 격리 — write-only·secret 미반환·로그 미노출	Non-Functional	Implemented	High	Justin Ko	req-054
REQ-055	GET /v1/portfolios 응답에 전략·시장 메타데이터 노출 (additive)	Interface	Implemented	High	Justin Ko	req-055
REQ-056	owner-scoped 수동 장부 입력 HTTP API	Interface	Proposed	High	Justin Ko	req-056

Recent Change Log Summary

• 2026-07-14: REQ-056 신규 생성 Proposed (draft-req) — dcy-012 confirmed Discovery 근거. 신규 POST /v1/portfolios/{portfolio_id}/ledger/manual + action enum(INVEST, BUFFER_OUT, BUFFER_IN, BUY, SELL, WITHDRAW, PROFIT, REVERSAL) owner-scoped user/session API 계약. 기존 /ledger/trades는 daemon/service-token broker write 전용으로 보존. 부족 cash/quantity/buffer 409, daemon-managed confirmation 409 MANUAL_WRITE_REQUIRES_CONFIRMATION, after-snapshot/history fields, cumulative_profit_withdrawn 및 PROFIT 순입금액 미포함 의미 포함. confirm-req(팀장 승인) 대기.
• 2026-07-04: REQ-055 신규 생성 Implemented (draft-req) — trex-tvr-v1 dcy-001 confirmed Discovery 근거. GET /v1/portfolios 응답에 active_strategy_id·strategy_name·strategy_params·markets additive 노출. DB 마이그레이션 불필요(기존 컬럼·테이블 활용), N+1 금지·파싱 에러 격리(500 금지) 포함. confirm-req(팀장 승인) 대기.
• 2026-06-28: REQ-052/053/054 Approved → Implemented (confirm-req-implemented) — BAT-022 PR #19 mergeCommit 1b78c18, QC PASS-WITH-NOTES(opus, blocker 0). 565 passed(+leak 테스트), AC 전건·secret 미반환·소유 스코프·REQ-051 회귀 PASS. Major 보안 #3(owner 재할당 credential leak) 원자화 수정(83e6dde) 반영 — 단일 트랜잭션+선삭제+leak 방지 테스트 3종. REQ-053 owner 재할당 원자화 수정 명시.
• 2026-06-28: REQ-052/053/054 Approved → Approved (confirm-req 팀장 승인) — dcy-011 추적·AC testable·blocker 0. 소유 스코프 음성(REQ-052 AC-6/9/10)·owner 재할당+인증정보 무효화(REQ-053 AC-4/5)·secret 미반환·로그 미노출·REQ-051 회귀(REQ-054) 확인. admin도 인증정보는 소유 스코프 전용(self-service 결정 정합). 엔드포인트 경로(OQ-1/2) design 위임. 다음=suggest-batch-reqs.
• 2026-06-28: REQ-047 Approved → Implemented (confirm-req-implemented) — BAT-021 PR #18 머지(7164f9e), 실 dev PG 통합검증 AC-1~7 PASS(Step1→backfill→Step2→downgrade), QC PASS-WITH-NOTES(blocker 0). Step2(PK 전환) 실 운영 DB 적용은 별도 release 결재 게이트(런북 docs/runbooks/bat-021-req047-step2-migration-runbook.md 엄수, 배포순서 Step1→backfill→Step2→코드배포, alembic stamp 사전확인). 운영 적용 시 AC-3/4/5 실운영 evidence 재확보.