kjh2064
5dfb8f3e12
Reorganize documentation following AGENTS.md v16.0 governance (traceability, reproducibility): Structure changes: - CURRENT/ (new) ├─ 00~08.md (v16.0 standards, renamed for clarity) └─ CATALOGS/ (9 CSV files: WBS, decision log, debt register, matrices, catalogs) - LEGACY/ (new, read-only archives) ├─ v11/ (original baseline + hardening analysis) ├─ v12~v15/ (.gitkeep + README for future archiving) - DECISIONS/ (new, ready for ADR usage) - TEMPLATES/ (existing, unchanged) Deletions (consolidated into CURRENT/): - v16_0/ folder (files migrated) - hardening/ folder (contents → LEGACY/v11/) - Root-level v11 files (00~07.md, CSV) Renames (for clarity): - 00_EXECUTIVE_REFERENCE_IMPLEMENTATION.md → 00_EXECUTIVE.md - 01_BRUTAL_ROLE_AUDIT.md → 01_ROLE_AUDIT.md - 02_FRONTEND_ADAPTER_CRUD_STANDARD.md → 02_FE_ADAPTER.md - 03_BACKEND_DATA_SCHEDULER_STANDARD.md → 03_BE_DATA.md - 04_ALGORITHM_MODEL_GOVERNANCE.md → 04_ALGORITHM.md - 05_PROCESS_VIBE_DEBT_CONTROL.md → 05_PROCESS_VIBE_DEBT.md - 06_VALIDATION_TRUTH.md → 06_VALIDATION.md - 07_PACKAGE_ATTACHMENT_POLICY.md → 07_PACKAGE_POLICY.md Updates: - docs/INDEX.md (complete rewrite with navigation) - LEGACY/ folders with README + .gitkeep Benefits: ✅ Clear version management (v16.0 is active, v11~v15 read-only) ✅ No version mixing in root ✅ CURRENT/ as single point of reference for active docs ✅ CATALOGS/ consolidates all data matrices ✅ LEGACY/ preserves history without clutter ✅ Traceability: decision log, tech debt, WBS all linked ✅ DECISIONS/ ready for ADR pattern (future use) Sync with root: - CLAUDE.md references: docs/CURRENT/, docs/INDEX.md ✅ - AGENTS.md references: docs/CURRENT/, traceability ✅ - README.md: Document guide links updated ✅ Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
299 lines
12 KiB
Markdown
299 lines
12 KiB
Markdown
# 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 자동 생성.
|
||
|