73 lines
2.7 KiB
Markdown
73 lines
2.7 KiB
Markdown
# 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를 우선 표시
|