refactor(arch): 백오피스 확장성 개선을 위한 공통 경계 정리 #696
Description
Summary
프론트엔드/백엔드 모두 목표 아키텍처 문서와 실제 구현 사이의 드리프트가 커지고 있다. 특히 권한 UI 제어, workspace 전환, multi-service package 경계, 계정/설정 폼 표준, MVC validation 경계, IAM service 분해, workspace API 중복이 겹치면서 백오피스 기능 확장 비용이 빠르게 증가하는 상태다.
대표 근거:
- FE 권한 DOM 후처리:
frontend/app/src/features/auth/index.ts - FE workspace full reload:
frontend/app/src/entities/workspace/store.ts - FE 거대 export surface:
frontend/app/package.json - FE 계정/설정 레거시 폼:
frontend/app/src/pages/account/setting/auth-tab.tsx,frontend/app/src/pages/account/profile/security-tab.tsx - FE 거대 grid adapter:
frontend/app/src/shared/grid/lib/tabulator-adapter.ts - BE validation drift:
backend/iam/src/main/kotlin/io/deck/iam/controller/UserController.kt,backend/iam/src/main/kotlin/io/deck/iam/controller/AccountController.kt - BE invalid input silent ignore:
backend/iam/src/main/kotlin/io/deck/iam/service/UserService.kt - BE god service:
backend/iam/src/main/kotlin/io/deck/iam/service/UserService.kt - BE workspace controller duplication:
backend/app/src/main/kotlin/io/deck/app/controller/WorkspaceController.kt,backend/app/src/main/kotlin/io/deck/app/controller/MyWorkspaceController.kt - BE app module guard gap:
backend/app/src/test/kotlin/io/deck/app/ModuleStructureTest.kt
Goal
백오피스 프로그램으로서의 확장성을 높이기 위해 공통 경계와 검증 규약을 정리한다. 신규 기능 추가 시 기존 레거시 패턴 복제를 강요하지 않는 상태를 목표로 한다.
Non-Goals
- 신규 도메인 기능 추가
- unrelated UI redesign
- 대규모 일괄 리네이밍
Tasks
- FE 권한 경계 정리:
features/auth의 DOM 후처리 기반 권한 제어를 제거하고AppAbility/Authorized*/useAuthorizedAction경계로 통합한다. - FE workspace runtime 정리: workspace 전환 시
window.location.reload()에 의존하지 않도록 선택 상태와 데이터 invalidation 경계를 재설계한다. - FE account/settings 폼 표준화:
account/profile,account/setting계열의 mutation 폼을 RHF + zod + overlay hook 패턴으로 수렴시킨다. - FE grid adapter 분해:
tabulator-adapter의 mount/query/selection/native-event/observer 책임을 분리 가능한 단위로 쪼갠다. - FE multi-service package 슬림화:
@deck/appexport surface를 재분류하고 서비스 앱이 실제로 의존해야 하는 최소 공개 API를 정의한다. - FE 서비스 설정 정리:
meetpie,deskpie의 private alias 노출(#app)과 직접적인 shell 결합을 단계적으로 제거한다. - BE MVC validation 규약 통일:
@RequestBody+@Valid, method validation, DTO Bean Validation 적용 기준을 통일하고 계약 테스트를 추가한다. - BE settings raw-input validation 수정: 잘못된
locale/timezone/dateFormat입력이 조용히 무시되지 않고 명시적 400으로 반환되도록 바꾼다. - BE IAM 서비스 분해 계획 수립 및 착수:
UserService를 command/query/use-case 단위로 나누는 리팩터링 기준을 정의하고 첫 분해를 수행한다. - BE workspace API 중복 제거: admin/my-workspace 흐름을 policy 기반 공통 application service로 수렴한다.
- BE 모듈 경계 테스트 강화:
app모듈 예외를 whitelist 기반으로 축소하고 구조 검증을 더 엄격하게 만든다. - 회귀 검증 추가: 위 변경들에 대해 아키텍처 테스트, validation contract test, 주요 FE 회귀 테스트를 추가한다.
Acceptance Criteria
- 런타임 화면 코드에서 DOM 후처리 기반 권한 숨김 로직이 제거된다.
- workspace 변경이 전체 페이지 reload 없이 반영된다.
- account/settings mutation 폼은 RHF 기반 패턴 또는 문서화된 예외로 정리된다.
- 서비스 앱이
@deck/app에 과도하게 결합되지 않도록 공개 surface가 정리된다. - 보호되는 backend DTO 입력은 MVC 경계에서 검증된다.
- invalid settings input은 silent ignore 대신 구조화된 400 응답을 반환한다.
- workspace API 중복 정리가
#355와 충돌 없이 정리되거나 해당 이슈를 대체/흡수한다. - 후속 구현 PR이 기능별로 쪼개질 수 있을 정도로 경계와 작업 단위가 분명해진다.