🚀 [기능개선][프로젝트] 프로젝트 전체 폴더 구조 개선 필요

[Cassiiopeia]

📝 현재 문제점

• 폴더 네이밍 컨벤션과 폴더 depth가 현재 5단계로 깊습니다
• 최대한 depth를 짧게 가져가면서 폴더구조를 간단하게 수정해야될것같습니다

🛠️ 해결 방안 / 제안 기능

• 불필요한 중복된 폴더구조를 합치고 모아야합니다

🙋‍♂️ 담당자

• 백엔드: 이름
• 프론트엔드: @Cassiiopeia
• 디자인: 이름

[Cassiiopeia]

Guide by SUH-LAB

브랜치

20260211_#33_프로젝트_전체_폴더_구조_개선_필요

커밋 메시지

프로젝트 전체 폴더 구조 개선 필요 : feat : {변경 사항에 대한 설명} https://github.com/MapSee-Lab/MapSy-FE/issues/33

[Cassiiopeia]

📌 작업 개요

프로젝트 폴더 구조의 depth가 5단계로 깊고 네이밍 컨벤션이 일관되지 않아, 폴더 depth를 최소화하고 불필요한 중복 구조를 통합하는 전체 리팩토링 수행

• 변경 규모: 88개 파일 변경, 3,540줄 삭제
• 관련 커밋: bd1685c (파일 정리)

---

🎯 구현 목표

• 폴더 depth 5단계 → 최대 3~4단계로 축소
• Feature-first + 2-Layer (data / presentation) 아키텍처로 통일
• 불필요한 placeholder 파일 및 빈 폴더 제거
• 코드 생성 파일(.g.dart, .freezed.dart) 재생성을 통한 경로 정합성 확보

---

✅ 구현 내용

1. lib/core/ → lib/common/ 통합 리네이밍

기존 core/ 하위에 network/, errors/, services/device/, services/fcm/ 등으로 세분화되어 있던 구조를 common/ 아래 단순한 카테고리로 통합

변경 전 (기존 구조)	변경 후 (개선 구조)
lib/core/constants/	lib/common/constants/
lib/core/errors/	lib/common/exceptions/
lib/core/network/api_client.dart	lib/common/services/api_client.dart
lib/core/network/auth_interceptor.dart	lib/common/services/auth_interceptor.dart
lib/core/network/error_interceptor.dart	lib/common/services/error_interceptor.dart
lib/core/network/token_storage.dart	lib/common/services/token_storage.dart
lib/core/services/device/device_id_manager.dart	lib/common/services/device_id_manager.dart
lib/core/services/device/device_info_service.dart	lib/common/services/device_info_service.dart
lib/core/services/fcm/firebase_messaging_service.dart	lib/common/services/firebase_messaging_service.dart
lib/core/services/fcm/local_notifications_service.dart	lib/common/services/local_notifications_service.dart

핵심 변경점:

• network/, services/device/, services/fcm/ 3개 하위 폴더 → services/ 하나로 병합
• errors/ → exceptions/로 네이밍 변경 (Dart 컨벤션에 맞춤)
• depth: 4단계(core/services/device/) → 2단계(common/services/)

2. Feature 내부 3-Layer → 2-Layer 축소

기존에 각 feature 내부가 data/datasources/, data/repositories/, domain/entities/, domain/repositories/, domain/usecases/, presentation/providers/ 등으로 세분화된 Clean Architecture 스타일이었으나, 프로젝트 규모에 비해 과도하여 2-Layer로 간소화

Auth Feature:

변경 전	변경 후
auth/data/datasources/auth_remote_datasource.dart	auth/data/auth_remote_datasource.dart
auth/data/repositories/auth_repository_impl.dart	auth/data/auth_repository_impl.dart
auth/domain/repositories/auth_repository.dart	auth/data/auth_repository.dart
auth/domain/entities/onboarding_step.dart	auth/data/onboarding_step.dart
auth/domain/utils/firebase_auth_error_handler.dart	auth/data/firebase_auth_error_handler.dart
auth/presentation/providers/auth_provider.dart	auth/presentation/auth_provider.dart

Home Feature:

변경 전	변경 후
home/data/datasources/home_remote_datasource.dart	home/data/home_remote_datasource.dart
home/data/repositories/home_repository_impl.dart	home/data/home_repository_impl.dart
home/domain/repositories/home_repository.dart	home/data/home_repository.dart
home/domain/entities/content_status.dart	home/data/content_status.dart
home/presentation/providers/home_provider.dart	home/presentation/home_provider.dart

Onboarding Feature:

변경 전	변경 후
onboarding/data/datasources/onboarding_remote_datasource.dart	onboarding/data/onboarding_remote_datasource.dart
onboarding/data/repositories/onboarding_repository_impl.dart	onboarding/data/onboarding_repository_impl.dart
onboarding/domain/repositories/onboarding_repository.dart	onboarding/data/onboarding_repository.dart
onboarding/presentation/providers/onboarding_provider.dart	onboarding/presentation/onboarding_provider.dart

핵심 변경점:

• domain/ 레이어 제거 → Repository 인터페이스와 Entity를 data/로 통합
• datasources/, repositories/, providers/ 하위 폴더 제거 → 파일을 상위 레이어에 직접 배치
• depth: 5단계(features/auth/data/datasources/) → 3단계(features/auth/data/)

3. 라우팅 폴더 리네이밍

변경 전	변경 후
lib/router/app_router.dart	lib/routing/app_router.dart
lib/router/route_paths.dart	lib/routing/route_paths.dart

4. 불필요한 파일 정리

• placeholder 파일 삭제: _placeholder.dart 파일 7개 제거
  • core/utils/_placeholder.dart
  • core/utils/extensions/_placeholder.dart
  • core/widgets/_placeholder.dart
  • auth/data/models/_placeholder.dart
  • auth/data/repositories/_placeholder.dart
  • auth/domain/entities/_placeholder.dart
  • auth/domain/usecases/_placeholder.dart
  • auth/presentation/widgets/_placeholder.dart
• 빈 폴더/레이어 제거: domain/, usecases/, 빈 하위 폴더 전부 삭제
• 코드 생성 파일 제거: 경로 변경으로 무효화된 .g.dart, .freezed.dart 파일 삭제 후 재생성

---

🔧 주요 변경사항 상세

import 경로 전체 수정

폴더 이동에 따라 모든 dart 파일의 import 경로 업데이트. 약 30개 파일에서 import 경로 수정

예시:

// 변경 전
import 'package:mapsy/core/network/api_client.dart';
import 'package:mapsy/core/constants/app_colors.dart';

// 변경 후
import 'package:mapsy/common/services/api_client.dart';
import 'package:mapsy/common/constants/app_colors.dart';

최종 폴더 구조 (개선 후)

lib/
├── main.dart
├── firebase_options.dart
├── routing/                          # router → routing 리네이밍
│   ├── app_router.dart
│   └── route_paths.dart
├── common/                           # core → common 통합
│   ├── constants/                    # 그대로 유지
│   ├── exceptions/                   # errors → exceptions
│   ├── services/                     # network + services/* 통합
│   └── widgets/
└── features/
    ├── auth/
    │   ├── data/                     # datasources/, repositories/, domain/ 통합
    │   │   ├── auth_remote_datasource.dart
    │   │   ├── auth_repository.dart
    │   │   ├── auth_repository_impl.dart
    │   │   ├── firebase_auth_datasource.dart
    │   │   ├── firebase_auth_error_handler.dart
    │   │   ├── onboarding_step.dart
    │   │   └── models/
    │   └── presentation/            # providers/ 제거, 직접 배치
    │       ├── auth_provider.dart
    │       ├── pages/
    │       └── widgets/
    ├── home/                         # 동일 패턴 적용
    └── onboarding/                   # 동일 패턴 적용

---

📊 개선 효과 요약

항목	변경 전	변경 후
최대 폴더 depth	5단계	3~4단계
공통 모듈 분류	5개 폴더 (network/, errors/, services/device/, services/fcm/, constants/)	3개 폴더 (constants/, exceptions/, services/)
Feature 내부 레이어	3-Layer (data/domain/presentation)	2-Layer (data/presentation)
Placeholder 파일	7개	0개
총 삭제 라인	-	3,540줄

---

🧪 테스트 및 검증

• 폴더 이동 후 build_runner로 코드 생성 파일(.g.dart, .freezed.dart) 전체 재생성
• 모든 import 경로 정상 동작 확인
• 앱 빌드 및 실행 정상 동작 확인

---

📌 참고사항

• 커밋 메시지가 이슈 #18로 태깅되어 있으나, 실제 작업 내용은 이슈 🚀 [기능개선][프로젝트] 프로젝트 전체 폴더 구조 개선 필요 #33(프로젝트 전체 폴더 구조 개선)에 해당
• CLAUDE.md 문서도 새로운 폴더 구조에 맞게 업데이트 완료
• 향후 새 feature 추가 시 동일한 2-Layer 패턴(data/ + presentation/) 적용 필요

[Cassiiopeia]

Stable 반영 이슈 완료 처리합니다