Flutter 팀 핸드북

일관된 히스토리 관리를 위해 다음 규칙을 준수합니다.

유지보수와 확장이 용이한 구조를 위해 클린 아키텍처를 따릅니다.

// 예시: 전역 상태(Session)와 화면 ViewModel(LoginViewModel)의 상호작용
// 1. 전역 상태 정의
@Riverpod(keepAlive: true)
class Session extends _$Session { ... }

// 2. 화면 ViewModel에서 전역 상태 업데이트
@riverpod
class LoginViewModel extends _$LoginViewModel {
  Future login(...) async {
    // ... 로그인 성공 후 ...
    ref.read(sessionProvider.notifier).login(user);
  }
}

// 3. 다른 화면에서 전역 상태 참조
class ProfilePage extends ConsumerWidget {
  Widget build(BuildContext context, WidgetRef ref) {
    final user = ref.watch(sessionProvider);
    // ...
  }
}

• 파일 이름: snake_case.dart
• 비공개 멤버(Private Members): 이름 앞에 _를 붙여 해당 파일 외부에서의 접근을 막습니다. 캡슐화를 통해 위젯이나 클래스 내부의 상태와 로직을 보호합니다.

  // 예시: StatefulWidget에서 내부 상태 관리
  class MyCheckbox extends StatefulWidget { ... }
  
  class _MyCheckboxState extends State {
    // _isChecked는 이 State 클래스 외부에서 직접 접근 불가
    bool _isChecked = false; 
  
    // _toggleCheckbox 메서드 또한 외부에서 직접 호출 불가
    void _toggleCheckbox() {
      setState(() {
        _isChecked = !_isChecked;
      });
    }
    ...
  }

• 재사용 가능한 위젯(Reusable Widgets):

  위젯은 독립적이고 재사용 가능하게 작성하여 중복을 줄이고 일관성을 높입니다.

  나쁜 예 1: UI 반복

  // ListView 안에서 동일한 구조의 위젯이 반복됨
  ListView.builder(
    itemCount: users.length,
    itemBuilder: (context, index) {
      // 복잡한 위젯 구조가 여기에 그대로 노출됨
      return Card(
        child: ListTile(
          leading: CircleAvatar(child: Text(users[index].name[0])),
          title: Text(users[index].name),
          subtitle: Text(users[index].email),
        ),
      );
    },
  );

  좋은 예 1: 위젯 추출

  // 반복되는 UI를 별도의 위젯으로 추출
  ListView.builder(
    itemCount: users.length,
    itemBuilder: (context, index) {
      // UserProfileCard 위젯으로 책임을 위임하여 코드가 간결해짐
      return UserProfileCard(user: users[index]);
    },
  );
  
  // 재사용 가능한 위젯
  class UserProfileCard extends StatelessWidget {
    final User user;
    const UserProfileCard({super.key, required this.user});
    // ... 위젯 구현
  }

  나쁜 예 2: 특정 상태에 의존

  // 위젯이 특정 ViewModel Provider를 직접 참조함
  class UserAvatar extends ConsumerWidget {
    @override
    Widget build(BuildContext context, WidgetRef ref) {
      // profileViewModelProvider에 강하게 결합되어 다른 곳에서 재사용 불가
      final user = ref.watch(profileViewModelProvider).user;
      return CircleAvatar(backgroundImage: NetworkImage(user.avatarUrl));
    }
  }

  좋은 예 2: 데이터 주입

  // 필요한 데이터(avatarUrl)를 생성자를 통해 주입받음
  class UserAvatar extends StatelessWidget {
    final String avatarUrl;
    const UserAvatar({super.key, required this.avatarUrl});
  
    @override
    Widget build(BuildContext context) {
      // 주입받은 데이터로 위젯을 그리므로 어디서든 재사용 가능
      return CircleAvatar(backgroundImage: NetworkImage(avatarUrl));
    }
  }

• 공통 위젯: 여러 화면에서 사용될 공통 위젯은 팀장과 상의 후 /common/presentation/widgets 하위에 app_위젯이름.dart 형식으로 생성/수정합니다.

앱의 자원과 경로를 중앙에서 관리하여 일관성을 유지하고 추후 유지보수를 용이하게 합니다.

• 이미지: 모든 이미지 경로는 /core/constants/app_images.dart에 static const 문자열로 정의 후 참조합니다.
• 문자열: UI에 표시되는 모든 텍스트는 /core/constants/app_strings.dart에 정의 후 참조합니다. (국제화 대응)
• 경로 이름 (GoRouter): 모든 라우트 경로는 /core/constants/app_routes.dart에 정의합니다.
• 라우터 설정: 새로운 화면 추가 시, /core/router/router.dart 파일에 GoRoute()를 추가하여 경로를 등록합니다.

1. 1

   작업 가져오기

   Jira 티켓을 'In Progress'로 이동하고 착수일을 기록합니다.

2. 2

   사전 확인

   요구사항, Figma 디자인, 공통 위젯 존재 여부를 확인합니다.

3. 3

   구현

   모든 개발 컨벤션을 준수하여 코드를 작성합니다.

4. 4

   코드 제출 및 리뷰

   커밋 후 Pull Request(PR)를 생성하고 리뷰를 요청합니다.

5. 5

   작업 완료

   리뷰 승인 및 Merge 후 Jira 티켓을 'Done'으로 이동합니다.