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