03. BE/FE 아키텍처 개선안

1. Modular Monolith 경계

단일 배포로 시작하되 module·PostgreSQL schema·namespace·API contract를 분리한다.
모듈은 다른 모듈의 Source Table을 직접 조회하지 않는다.
동기 의존은 좁은 Read Port, 비동기 결합은 Outbox/Inbox Event를 사용한다.
Microservice 분리는 독립 SLO·배포·용량·소유팀이 실제로 필요할 때만 검토한다.

2. Vertical Slice 표준

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를 우선 표시

2.7 KiB Raw Blame History