# 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 표준

```text
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 자동 생성.