kjh2064
5dfb8f3e12
Reorganize documentation following AGENTS.md v16.0 governance (traceability, reproducibility): Structure changes: - CURRENT/ (new) ├─ 00~08.md (v16.0 standards, renamed for clarity) └─ CATALOGS/ (9 CSV files: WBS, decision log, debt register, matrices, catalogs) - LEGACY/ (new, read-only archives) ├─ v11/ (original baseline + hardening analysis) ├─ v12~v15/ (.gitkeep + README for future archiving) - DECISIONS/ (new, ready for ADR usage) - TEMPLATES/ (existing, unchanged) Deletions (consolidated into CURRENT/): - v16_0/ folder (files migrated) - hardening/ folder (contents → LEGACY/v11/) - Root-level v11 files (00~07.md, CSV) Renames (for clarity): - 00_EXECUTIVE_REFERENCE_IMPLEMENTATION.md → 00_EXECUTIVE.md - 01_BRUTAL_ROLE_AUDIT.md → 01_ROLE_AUDIT.md - 02_FRONTEND_ADAPTER_CRUD_STANDARD.md → 02_FE_ADAPTER.md - 03_BACKEND_DATA_SCHEDULER_STANDARD.md → 03_BE_DATA.md - 04_ALGORITHM_MODEL_GOVERNANCE.md → 04_ALGORITHM.md - 05_PROCESS_VIBE_DEBT_CONTROL.md → 05_PROCESS_VIBE_DEBT.md - 06_VALIDATION_TRUTH.md → 06_VALIDATION.md - 07_PACKAGE_ATTACHMENT_POLICY.md → 07_PACKAGE_POLICY.md Updates: - docs/INDEX.md (complete rewrite with navigation) - LEGACY/ folders with README + .gitkeep Benefits: ✅ Clear version management (v16.0 is active, v11~v15 read-only) ✅ No version mixing in root ✅ CURRENT/ as single point of reference for active docs ✅ CATALOGS/ consolidates all data matrices ✅ LEGACY/ preserves history without clutter ✅ Traceability: decision log, tech debt, WBS all linked ✅ DECISIONS/ ready for ADR pattern (future use) Sync with root: - CLAUDE.md references: docs/CURRENT/, docs/INDEX.md ✅ - AGENTS.md references: docs/CURRENT/, traceability ✅ - README.md: Document guide links updated ✅ Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2.7 KiB
2.7 KiB
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를 우선 표시