> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다. - 상태: 확인 안 함 - 작성일: 2026-09-19 - 요약: 파일 서버 조립을 관심사별 설정 다섯 개로 나누는 설계다. - 현재 정본: `docs/fileserver/support-matrix.md` # Fileserver Composition Decomposition ## Goal Close the remaining BOOT-007 drift in app-bootstrap. Redis already follows the documented composition threshold, but Fileserver still has three configurations above the repository rule: - FileserverPlatformAutoConfiguration: 24 @Bean methods; - FileserverStorageConfiguration: 18 @Bean methods; - FileserverServiceConfiguration: 12 @Bean methods. The refactor changes composition ownership only. Bean identities, types, conditions, master-switch semantics and application behavior remain unchanged. ## Master-switch invariant FileserverPlatformAutoConfiguration remains the only auto-configuration entry point and the only place carrying the app.fileserver-platform.enabled master condition. All newly extracted classes are package-private @Configuration(proxyBeanMethods = false) children reachable only through imports below that gated root. None is component-scanned or registered in AutoConfiguration.imports. FileserverStorageConfiguration and FileserverServiceConfiguration remain as zero-bean package-private aggregators so existing composition references remain stable while their internal concerns split. ## Platform split FileserverPlatformAutoConfiguration retains only the strictly gated settings binder and imports: - FileserverCorePolicyConfiguration - FileserverWebProperties - TransferExecutorProperties - UploadPolicy - DownloadPolicy - HttpRangeResolver - ConditionalRequestEvaluator - ContentDispositionFactory - FileserverWebAssemblyConfiguration - request context/problem factories - raw/multipart request mappers - MVC conditional/download response helpers - zero-copy eligibility - FileserverNginxConfiguration - delegation properties - internal URI mapper - download strategy - FileserverProtocolConfiguration - TUS properties/parser/checksum verifier under the existing TUS condition - draft12 properties under the existing draft condition - FileserverObservabilityConfiguration - keyed SafeFileFingerprint under the existing consumer condition - Micrometer FileserverMetricsPort under the existing metrics condition ## Storage split FileserverStorageConfiguration becomes an aggregator importing: - FileserverLocalStorageCoreConfiguration - local storage properties - schema activation - local probe - blocking content store - FileserverStorageGatewayConfiguration - upload, upload-content, download, copy, cleanup and zero-copy gateways - FileserverStorageOperationsConfiguration - storage health - orphan scan - usage probe - reconciliation probe - FileserverVerificationConfiguration - filename policy - file state machine - verification content reader - verification service ## Service split FileserverServiceConfiguration becomes an aggregator importing: - FileserverUploadServiceConfiguration - identifier factory - transfer admission properties/controller - upload/finalize/single-shot services - writer lease coordinator - FileserverDownloadLifecycleConfiguration - download application service - lifecycle service - FileserverMaintenanceServiceConfiguration - cleanup service - reconciliation service - admin service under the existing admin condition ## Compatibility gates - master switch off creates none of the child graph; - master switch on preserves existing bean names/types; - TUS, draft12, metrics/fingerprint and admin sub-feature conditions remain unchanged; - existing FileserverPlatformAutoConfiguration tests continue to compose through the root; - integration composition continues to import only FileserverPlatformAutoConfiguration; - no new public type is introduced; - no configuration in this slice exceeds the documented roughly-eight-bean threshold. ## Verified result - FileserverPlatformAutoConfiguration now declares 1 bean and remains the only Fileserver @AutoConfiguration entry point; - storage and service legacy configuration names remain zero-bean aggregators; - extracted concern configurations are package-private and absent from AutoConfiguration.imports; - every Fileserver production configuration declares at most 7 @Bean methods; - FileserverCompositionArchitectureTest permanently enforces the <= 8 rule and is pinned by ArchRuleDiscoveryContractTest; - focused Fileserver auto-configuration/runtime tests: PASS; - FileserverCompositionIntegrationTest against real PostgreSQL and filesystem: PASS with process-local TESTCONTAINERS_RYUK_DISABLED=true on this remote host; - app-bootstrap Spotless, full TEST, full ARCHITECTURE and full SYSTEM regressions: PASS; - git diff --check: PASS.