refactor: Reorganize docs folder structure for clarity and version management (PR 3c)

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>
2026-08-02 05:49:29 +09:00
parent 5e50ec6991
commit 5dfb8f3e12
205 changed files with 135 additions and 10178 deletions
@@ -0,0 +1,298 @@
+# 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 자동 생성.
+