Initial commit: Add project files

2026-08-02 05:15:36 +09:00
commit dcd1322d41
636 changed files with 122352 additions and 0 deletions
@@ -0,0 +1,77 @@
+# 아키텍처 표준: Modular Monolith + Vertical Slice
+
+## 1. 구조적 선택
+
+단일 배포를 유지하되 모듈과 PostgreSQL schema의 소유권을 분리한다. Microservice 분리는 조직·배포·데이터 소유권·SLO가 실제로 독립될 때만 ADR로 검토한다.
+
+```text
+Host
+ ├─ BuildingBlocks
+ ├─ IdentityAccess
+ ├─ SecurityMaster / MarketData / FundamentalsPIT
+ ├─ ResearchFactors / ValuationForecast
+ ├─ SignalEngine
+ ├─ PortfolioRisk / ClientAdvisory
+ ├─ BacktestingEvaluation
+ ├─ ExecutionReconciliation
+ ├─ ReportingNotifications
+ └─ GovernanceAudit
+```
+
+## 2. 의존 방향
+
+- Domain은 FastEndpoints, Dapper, Npgsql, Hangfire, HTTP를 참조하지 않는다.
+- Application은 Domain과 좁은 Port를 사용한다.
+- Infrastructure는 Dapper/Npgsql/Adapter를 구현한다.
+- Host는 composition root다.
+- 모듈 간 Source Table 직접 조회를 금지하고 Contract 또는 승인된 Read Model을 사용한다.
+
+## 3. SOLID의 적용 범위
+
+| 원칙 | 실무 적용 | 금지 |
+|---|---|---|
+| SRP | Endpoint=HTTP, Handler=use case, Policy=decision, Adapter=I/O | God Service, Job 내 정책 |
+| OCP | Policy/DQ/Adapter는 명시적 registry로 추가 | Reflection plugin framework |
+| LSP | Adapter 교체 시 시간·단위·오류 contract test | Mock 성공만으로 교체 승인 |
+| ISP | 작은 Port (`IClock`, `ISellDecisionContextReader`) | 범용 Repository |
+| DIP | Domain은 외부 기술을 모름 | Npgsql type의 Domain 침투 |
+
+추상화는 두 번째 실제 구현과 동일한 변경축이 확인된 후 승격한다.
+
+## 4. Vertical Slice 표준
+
+```text
+Features/<Slice>/
+  Endpoint.cs
+  Request.cs
+  Response.cs
+  Validator.cs
+  Handler/Service.cs
+  Sql.cs
+  Mapper.cs
+  Contracts/
+  Tests/
+  README.md
+```
+
+한 Slice는 Endpoint, DB migration, Event/Job, FE route/component, unit/integration/E2E, metric/alert/runbook까지 완결되어야 Done이다.
+
+## 5. 트랜잭션 경계
+
+생산형 Decision 생성은 같은 PostgreSQL 트랜잭션에서 다음을 수행한다.
+
+1. Idempotency 기존 결과 확인.
+2. 승인된 immutable Context 조회.
+3. 순수 Policy 평가.
+4. Decision append와 hash 저장.
+5. Outbox append.
+6. Commit.
+
+외부 API 호출은 트랜잭션 밖에서 수행하고 Raw immutable store에 먼저 적재한다.
+
+## 6. 정규화와 역정규화
+
+- Write Model: 3NF, append/reversal, valid_from/to, revision.
+- Evidence: 원본 JSONB + 제약/검색에 필요한 핵심 컬럼.
+- Read Model: Owner, ProjectionVersion, SourceWatermark, ContentHash, Rebuild 명령을 가져야 한다.
+- 화면 성능을 이유로 Source Table을 직접 join하는 것을 금지한다.