KArtSell.Aegis/docs/LEGACY/v11/00_STRATEGIC_HARDENING_REPORT.md

K-ArtSell Aegis v11.1 전략적 하드닝 제안

상태: IMPLEMENTATION_DELTA / STATIC_REVIEWED_NOT_BUILD_VERIFIED
기준선: SI 누적 통합 실행기준서 v10.0 + K-ArtSell 12.2 연구 번들 + v11 구현 가속 패키지
운영 경계: 투자자문형 우선 · 자동주문 OFF · RESEARCH_CANDIDATE_NOT_PRODUCTION

1. 결론

v10.0과 v11 패키지를 다시 쓰지 않는다. Baseline Preservation + Delta + Supersession + Traceability 원칙으로 v11.1 하드닝 Delta를 추가한다.

우선순위는 다음과 같다.

1. 연구 결과 재현성 복구: 원시 데이터 manifest, checksum, Python lock, 실행 이미지 digest.
2. PIT·기업행사·총수익·비용·상폐·FX 데이터 정합성.
3. Scalar position 제거와 Lot/Cycle 기반 매도·재진입 상태기계.
4. EvidenceSnapshot → SellDecision → Recommendation → Review → Publish → Outcome의 불변 추적.
5. BE/FE/Job/DB를 Slice 단위로 끝내는 Vertical Slice.
6. Shadow 일평가와 운영 무결성. 자동주문은 별도 승인 전까지 구현·활성화 금지.

2. 첨부 소스에서 확인한 핵심 결함

P0

• 연구 번들에 원시 데이터와 환경 lock이 없어 제3자 clean-room 재현이 불가능하다.
• Python v12_positions()가 기존 Core와 신규 Tactical lot을 하나의 entry/peak/floor로 혼합한다.
• 한국 기업행사를 정수비율 추정으로 과거 전체에 소급 적용한다.
• 총수익·PIT 재무/컨센서스·상폐수익·세금·FX가 불완전하다.
• 자본바닥 비용이 함수 계약이 아니라 전역 상수에 묶여 결과 라벨과 실제 계산이 달라질 수 있다.
• v11 템플릿의 연구 평가 Endpoint가 AllowAnonymous()이고, Handler·Evidence 검증·DB 저장·Outbox가 없다.
• FE CI는 pnpm-lock.yaml을 요구하지만 패키지에 lockfile이 없다.

P1

• 매도 정책이 Hard impairment, gap, two-close 3개만 구현되어 survival·집중/유동성·기회비용이 누락됐다.
• 매도비중의 단위가 “현재 lot 대비 비율”인지 “포트폴리오 절대비중”인지 계약이 모호하다.
• Reentry 상태기계가 REENTERED → WATCH/OPEN 다단계 전이를 표현하지 못한다.
• Evidence 불변 trigger는 있으나 SignalDecision 불변 trigger가 빠져 있다.
• Architecture Test가 Generic Repository 문자열 탐지만 수행한다.
• FE가 API contract를 수동 중복 정의하고, retry 시 Idempotency-Key를 새로 만들어 동일 명령의 재시도 의미를 깨뜨린다.

3. SOLID의 현장 적용

원칙	적용	과유불급 차단
S	Endpoint=HTTP, Handler=유스케이스/트랜잭션, Policy=순수 결정, Adapter=외부 I/O	God Service, Job 내 정책 로직 금지
O	Policy/DQ/Adapter는 명시적 registry로 추가하되 우선순위와 계약은 고정	임의 plugin framework, reflection 기반 자동 발견 금지
L	KRX/DART/KIS Adapter 대체 시 동일 시간·단위·오류 contract test	mock 통과만으로 공급원 대체 금지
I	IMarketDataSource, IFilingSource, IEvidenceReader, IClock 등 좁은 Port	범용 Repository/IServiceProvider 노출 금지
D	Domain은 Npgsql/Hangfire/HTTP를 모른다	Infrastructure type이 Domain으로 침투하는 것 금지

추상화는 두 번째 실제 구현과 동일한 변경축이 확인된 뒤 승격한다. 한 번 쓰는 interface, generic repository, 범용 mediator wrapper는 만들지 않는다.

4. 알고리즘 고도화

4.1 생산 경계

생산 엔진은 점수 합산기가 아니라 순서가 고정된 결정 상태기계다.

HARD_IMPAIRMENT → PORTFOLIO_SURVIVAL → DYNAMIC_PROFIT_FLOOR → CONCENTRATION_LIQUIDITY → OPPORTUNITY_COST → REENTRY_OPTION

상위 사유는 하위 기대수익으로 상쇄하지 않는다. 모든 결정은 다음 Version Set을 남긴다.

• PolicyId, PolicyVersion
• EvidenceId, DatasetId, DataHash
• ModelVersion, ConfigVersion, CodeSha
• AsOf, PublishedAtCutoff, TradableSession
• 입력 단위, rounding, 허용오차, 반대증거

4.2 Lot/Cycle 모델

• PositionLot: 수량·원가·세금 lot·개설/종료.
• CycleState: entry, peak, floor, breach count, last sell/buy.
• ProtectionState: 보호 활성화와 단조 floor.
• ReentryWatch: 매도 원인, 대기, 조건, 단계, 만료.
• 재진입은 새 CycleId와 새 Lot을 생성한다.
• Hard impairment는 자동 재진입을 금지한다.

4.3 매도 수량 계약

SellRatioOfLot와 TargetPortfolioWeightAfter를 분리한다. API/DB/UI에서 단순 sell_fraction 하나를 사용하지 않는다.

• SellRatioOfLot: 현재 lot 수량 중 매도 비율, 0~1.
• SellQuantity: 주문 단위 반영 후 실제 제안 수량.
• TargetPortfolioWeightAfter: 매도 후 목표 포트폴리오 비중.
• StrategicCoreFloorWeight: 포트폴리오 절대비중.

이 구분이 없으면 Core floor와 부분매도 비율을 잘못 비교하게 된다.

4.4 기대효용

opaque score를 금지하고 구성요소를 저장한다.

• P10/P50/P90 기대수익
• ES95
• 영구가치훼손 확률 × LGD
• marginal portfolio risk
• liquidity/slippage/tax/FX
• replacement lower-confidence edge
• reentry option loss

Opportunity sell은 순우위 신뢰하단이 0을 초과하고 IPS·유동성·세금 제약을 통과한 경우만 허용한다.

4.5 연구와 생산의 분리

Python 연구 코드는 생산 엔진에서 호출하지 않는다. Python과 .NET은 동일 Golden Vector와 Policy ID만 공유한다.

• Python: 대규모 탐색, walk-forward, CSCV/PBO, DSR, bootstrap.
• .NET: 승인된 순수 정책, Evidence/Decision/Audit, Shadow 운영.
• 결과 비교: manifest + deterministic seed + tolerance.

5. 데이터 정합성·정규화·역정규화

5.1 계층

1. L0 Source Manifest: 권리·schema/version·SLA·timezone·단위.
2. L1 Raw Immutable: payload/hash/event/published/ingested.
3. L2 Canonical PIT: 가격·기업행사·재무·컨센서스·비용 revision.
4. L3 Quality/Lineage: DQ·quarantine·watermark·dataset manifest.
5. L4 Feature/Evidence: feature/forecast/risk/evidence hash.
6. L5 Transaction/Audit: ledger/decision/review/publication/fill/outcome.
7. L6 Read Model: 화면·리포트 projection.
8. L7 Artifact: backtest/model card/release evidence.

5.2 정규화 원칙

• 원장·현금·lot: 3NF + append/reversal.
• PIT 가격/재무/공시: source + published_at + revision + hash.
• 추천/승인/공개: 현재상태와 이력 분리.
• 설정/수수료: valid_from/to; current flag 단독 사용 금지.
• Evidence: JSONB 원문 + 검색/제약에 필요한 핵심 컬럼 승격.

5.3 역정규화 허용 조건

Read Model에만 허용하며 반드시 다음을 가진다.

• Owner
• ProjectionVersion
• SourceWatermark
• RefreshedAt/StaleAt
• Rebuild command
• Lineage
• 권한 scope

Source table을 화면에서 임의 join하거나 current value를 복제하지 않는다.

5.4 DB 강제 규칙

• schema-qualified SQL, 명시적 column, SELECT * 금지.
• Evidence/Decision/Audit update/delete 차단 trigger.
• 시간 범위 overlap exclusion 또는 사전 검증.
• Idempotency unique key.
• Outbox pending index와 lease/attempt/dead-letter.
• DbUp fresh/upgrade/re-run/failure rehearsal.

6. BE 고도화

6.1 Slice 표준

Features/<Slice>/
  Endpoint.cs
  Request.cs
  Response.cs
  Validator.cs
  Handler.cs
  Policy.cs
  Sql.cs
  Mapper.cs
  Contracts/
  Jobs/
  Tests/
  README.md

Endpoint는 EvidenceId, 모델버전, 정책 임계값을 클라이언트에서 그대로 신뢰하지 않는다. 요청은 업무 식별자와 as-of만 받고 Handler가 승인된 Evidence와 Version Set을 조회한다.

6.2 트랜잭션

동일 PostgreSQL transaction에서 다음을 처리한다.

1. Idempotency claim.
2. Evidence/lot/cycle as-of 조회.
3. 순수 Policy 평가.
4. Decision append.
5. Outbox append.
6. commit.

외부 API 호출은 transaction 밖에서 수행하고 raw result를 먼저 저장한다.

6.3 Outbox/Inbox

• Event payload는 최소키와 schema version만 포함.
• consumer별 Inbox unique key.
• 재처리는 동일 결과 또는 no-op.
• poison event는 dead-letter와 운영 승인 후 replay.
• 이벤트가 Job을 직접 호출하지 않고 readiness/command를 만든다.

6.4 Hangfire

Queue를 다음처럼 분리한다.

• q-control
• q-market-data
• q-fundamentals
• q-feature-risk
• q-recommendation
• q-evaluation
• q-reconciliation
• q-research
• q-backfill

모든 Job은 JobRunId, ScopeKey, IdempotencyKey, Watermark, Version Set, input/output hash를 가진다. DQ/business-hold는 transient retry와 분리한다.

6.5 보안

• /internal/* 익명 접근 금지.
• 자동주문 Capability는 코드와 설정 모두 기본 OFF.
• Swagger는 dev 또는 승인된 운영자만.
• maker-checker와 SoD를 endpoint/DB/audit에서 동시에 검증.
• secret/PII/token은 log, trace tag, fixture, prompt에 금지.

7. FE 고도화

7.1 상태 소유권

• 서버 상태: TanStack Query.
• 세션/role/UI preference: Pinia.
• form: vee-validate + Zod.
• filter/selection: router query/params.
• 대량 표: AG Grid server-side row model.

Pinia에 API 응답을 복제하지 않는다.

7.2 공통 상태 계약

LOADING, EMPTY, PARTIAL, STALE, WARN, ERROR, UNAUTHORIZED, FORBIDDEN, CONFLICT, EXPIRED, READONLY를 공통 컴포넌트로 처리한다.

7.3 계약과 멱등

• OpenAPI에서 DTO를 생성하거나 versioned contract를 단일 관리한다.
• submit 시 한 번 생성한 Idempotency-Key를 동일 retry에 재사용한다.
• 409는 VersionConflictDialog, 422는 field/summary mapping, 429/503은 retry-after를 표시한다.
• 고객 화면은 연구용 내부 evaluate endpoint를 호출하지 않는다.

7.4 컴포넌트화

공용 승격은 동일 업무 의미·상태·권한·접근성·테스트가 반복될 때만 한다.

공통: QueryStateBoundary, PermissionGuard, DataGridShell, CrudForm, VersionConflictDialog, DataFreshnessBadge.

도메인: EvidencePanel, ProtectionFloorPanel, ReentryTimeline, ApprovalPanel, VersionSetPanel, GateChecklist.

8. 바이브코딩·홀루시네이션 통제

• 채팅은 Source of Truth가 아니다.
• AI는 Policy ID, DB column, API, threshold를 발명하지 않는다.
• 모든 PR에 Source / Assumption / Unknown / Decision Required를 기록한다.
• 실행하지 않은 build/test/migration을 통과했다고 기록하지 않는다.
• 리팩터링 전 characterization test를 먼저 고정한다.
• 한 PR은 한 Slice 또는 한 리팩터링 목적만 가진다.
• AI 생성 migration은 fresh/upgrade/re-run과 DBA review 없이는 병합하지 않는다.
• 알고리즘 변경은 Golden/OOS/cost×2/false-exit/reentry/ES/ModelCard를 동시에 갱신한다.

9. 기술부채 운영

• P0는 기능 개발보다 먼저 처리한다.
• 각 Sprint 용량의 15~20%를 승인된 기술부채에 배정한다.
• Debt는 Risk, Interest, Owner, Due, Remediation, Exit Test를 가진다.
• “나중에 정리”가 아니라 해당 Slice의 Definition of Done에 포함한다.
• 무기한 예외는 금지하고 expiry와 재승인을 둔다.

10. 16 Sprint 개선 로드맵

기존 32주 기준은 유지하되 Release Train으로 묶는다.

Train	Sprint	목표	핵심 Gate
R0 Foundation	S0~S3	재현성, CI, PIT/CA/비용, ledger	build/lock/replay/lookahead 0
R1 Sell/Reentry	S4~S5	Evidence, Lot/Cycle, 매도/재진입	Golden/state/invariant
R2 Advisory MVP	S6~S8	IPS, 추천, 검토, 공개, 결과	maker-checker/E2E/audit
R3 Portfolio Intelligence	S9~S11	risk, rebalance, buy/replacement, scorecard	constraint/NO_ACTION/Shadow
R4 Pilot Hardening	S12~S15	KIS capability OFF, recon, security, DR, cutover	duplicate 0/recon/DR/rollback

Critical Path를 벗어난 대시보드·상품탐색 선행 구현은 제한한다.

11. 템플릿 적용 판정

첨부 v11 템플릿은 교육용 walking skeleton으로는 유효하지만 Implementation-ready 기준에는 미달한다. 다음 조건을 만족한 뒤 기준 템플릿으로 승격한다.

• 실제 .NET SDK/pnpm에서 restore/build/test green.
• lockfile과 dependency audit.
• 익명 internal endpoint 제거.
• Handler/Validator/DB/Outbox/Idempotency 구현.
• SignalDecision 불변 DB trigger.
• Architecture/Data/Integration/Replay/E2E test 추가.
• FE 11-state, auth, conflict, stable idempotency.
• Release Evidence Pack 자동 생성.