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,72 @@
+# 03. BE/FE 아키텍처 개선안
+
+## 1. Modular Monolith 경계
+
+- 단일 배포로 시작하되 module·PostgreSQL schema·namespace·API contract를 분리한다.
+- 모듈은 다른 모듈의 Source Table을 직접 조회하지 않는다.
+- 동기 의존은 좁은 Read Port, 비동기 결합은 Outbox/Inbox Event를 사용한다.
+- Microservice 분리는 독립 SLO·배포·용량·소유팀이 실제로 필요할 때만 검토한다.
+
+## 2. Vertical Slice 표준
+
+```text
+Features/<Slice>/
+  Endpoint.cs
+  Request.cs / Response.cs
+  Validator.cs
+  Handler.cs
+  Policy.cs
+  Sql.cs / Mapper.cs
+  Jobs/
+  Contracts/
+  Tests/
+  README.md  # traceability
+```
+
+Endpoint는 HTTP, Handler는 use case/transaction, Policy는 순수 결정, Adapter는 외부 I/O만 담당한다.
+
+## 3. Dapper·DB 원칙
+
+- Generic Repository 금지
+- schema-qualified SQL, 명시적 column, cancellation token
+- Write는 3NF/append/revision, Read는 projection
+- Evidence·Audit는 update/delete 차단
+- DbUp migration은 module별 순번·checksum·fresh/upgrade test
+- SELECT `*` 금지, PIT query는 `published_at <= cutoff`와 revision resolver 필수
+
+## 4. Hangfire
+
+Hangfire는 비즈니스 결정자가 아니라 승인된 Application Command의 반복 실행기다.
+
+- JobRunId, Scope, IdempotencyKey, Watermark, Version Set, Input/Output Hash
+- transient/permanent/DQ/business-hold retry class 분리
+- q-research/q-backfill은 고객 SLA queue와 격리
+- Job이 다른 Job을 직접 호출하지 않고 Event 또는 readiness gate로 연결
+- 재처리는 overwrite가 아니라 새 Dataset/Revision 생성
+
+## 5. FE 상태 소유권
+
+| 상태 | 소유자 |
+|---|---|
+| API 서버상태·cache·stale·retry | TanStack Query |
+| session·role·UI preference | Pinia |
+| form | vee-validate + Zod |
+| URL filter/selection | vue-router query/params |
+| 대량 업무표 | AG Grid server row model |
+
+Pinia에 API 응답을 복제하거나, 화면마다 401/409/422/429/503 처리를 다시 만들지 않는다.
+
+## 6. FE 컴포넌트 승격 기준
+
+공용 컴포넌트는 시각적 유사성이 아니라 동일한 업무 의미·상태·권한·접근성·테스트가 반복될 때만 만든다.
+
+필수 공통: `QueryStateBoundary`, `PermissionGuard`, `DataGridShell`, `CrudForm`, `VersionConflictDialog`, `DataFreshnessBadge`.
+
+도메인 공통: `EvidencePanel`, `ProtectionFloorPanel`, `ReentryTimeline`, `ApprovalPanel`, `VersionSetPanel`, `GateChecklist`.
+
+## 7. 관측성
+
+- HTTP/Job/SQL/Outbox를 correlationId·JobRunId·EvidenceId로 연결
+- Serilog structured logging, OpenTelemetry trace/metric
+- PII·token·API key는 log/tag 금지
+- 운영 dashboard는 batch SLA, DQ quarantine, duplicate, recon break, model drift를 우선 표시