feature-presentation

/cc-flutter:feature:presentation {feature_name} {entity_name} [--options]

Analyze existing Presentation Layer patterns using Serena MCP:
- feature/community/app/lib/src/presentation/bloc/post_list/post_list_bloc.dart
- feature/community/app/lib/src/presentation/bloc/post_list/post_list_event.dart
- feature/community/app/lib/src/presentation/bloc/post_list/post_list_state.dart

part of '{feature}_list_bloc.dart';

/// {Feature} 목록 이벤트
@immutable
sealed class {Feature}ListEvent {
  const {Feature}ListEvent();

  // Factory constructors (Public API)
  const factory {Feature}ListEvent.loadRequested() = _LoadRequested;
  const factory {Feature}ListEvent.refreshRequested() = _RefreshRequested;
  const factory {Feature}ListEvent.categoryChanged({
    {Entity}Category? category,
  }) = _CategoryChanged;
}

// Private implementation classes
@immutable
final class _LoadRequested extends {Feature}ListEvent {
  const _LoadRequested();
}

@immutable
final class _RefreshRequested extends {Feature}ListEvent {
  const _RefreshRequested();
}

@immutable
final class _CategoryChanged extends {Feature}ListEvent {
  const _CategoryChanged({this.category});
  final {Entity}Category? category;
}

part of '{feature}_list_bloc.dart';

/// {Feature} 목록 상태
@immutable
sealed class {Feature}ListState {
  const {Feature}ListState({
    required this.{entity}s,
    required this.currentSort,
    this.currentCategory,
  });

  final List<{Entity}> {entity}s;
  final {Entity}Category? currentCategory;
  final {Entity}SortType currentSort;
}

@immutable
final class {Feature}ListInitial extends {Feature}ListState {
  const {Feature}ListInitial()
      : super({entity}s: const [], currentSort: {Entity}SortType.latest);
}

@immutable
final class {Feature}ListLoading extends {Feature}ListState { ... }

@immutable
final class {Feature}ListLoaded extends {Feature}ListState {
  // ... hasMore, total 추가
  // copyWith 메서드 포함
}

@immutable
final class {Feature}ListError extends {Feature}ListState {
  // ... message 추가
}

import 'package:dependencies/dependencies.dart';

part '{feature}_list_event.dart';
part '{feature}_list_state.dart';

/// {Feature} 목록 BLoC
class {Feature}ListBloc extends BlocSignal<{Feature}ListEvent, {Feature}ListState> {
  {Feature}ListBloc({
    Get{Entity}sUsecase? get{Entity}sUsecase,
  }) : _get{Entity}sUsecase = get{Entity}sUsecase ?? const Get{Entity}sUsecase(),
       super(initialState: const {Feature}ListInitial()) {
    on<_LoadRequested>(_onLoadRequested);
    on<_RefreshRequested>(_onRefreshRequested);
  }

  final Get{Entity}sUsecase _get{Entity}sUsecase;

  Future<void> _onLoadRequested(
    _LoadRequested event,
    void Function({Feature}ListState) emit,
  ) async {
    emit({Feature}ListLoading(...));

    // ✅ UseCase call
    final result = await _get{Entity}sUsecase(
      Get{Entity}sParams(
        limit: _pageSize,
        offset: _currentOffset,
        category: stateValue.currentCategory,
      ),
    );

    result.fold(
      (failure) {
        if (!isClosed) {  // ✅ BLoC closed check
          emit({Feature}ListError(message: failure.message ?? '오류'));
        }
      },
      ({entity}ListResult) {
        if (!isClosed) {
          emit({Feature}ListLoaded(...));
        }
      },
    );
  }
}

void main() {
  late MockGet{Entity}sUsecase mockUsecase;

  setUpAll(registerFallbackValues);

  setUp(() {
    mockUsecase = MockGet{Entity}sUsecase();
  });

  blocSignalTest<{Feature}ListBloc, {Feature}ListState>(
    '로드 성공 시 {Feature}ListLoaded 상태',
    build: () => {Feature}ListBloc(
      get{Entity}sUsecase: mockUsecase,  // ✅ Direct mock injection
    ),
    setUp: () {
      when(() => mockUsecase(any()))
        .thenAnswer((_) async => Right(testResult));
    },
    act: (bloc) => bloc.add(const {Feature}ListEvent.loadRequested()),
    expect: () => [
      isA<{Feature}ListLoading>(),
      isA<{Feature}ListLoaded>(),
    ],
  );
}

class {Feature}Page extends StatelessWidget {
  const {Feature}Page({super.key});

  @override
  Widget build(BuildContext context) {
    return BlocSignalProvider(
      create: (context) =>
          {Feature}ListBloc()..add(const {Feature}ListEvent.loadRequested()),
      child: const {Feature}View(),
    );
  }
}

class {Feature}View extends StatelessWidget {
  const {Feature}View({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('{Feature}')),
      body: BlocSignalBuilder<{Feature}ListBloc, {Feature}ListState>(
        builder: (context, state) {
          return switch (state) {
            {Feature}ListInitial() => const SizedBox.shrink(),
            {Feature}ListLoading() => const Center(child: Loading()),
            {Feature}ListLoaded(:final {entity}s) => ListView.builder(...),
            {Feature}ListError(:final message) => EmptyState(
              tone: CoreEmptyStateTone.failure,
              title: Text(message),
            ),
          };
        },
      ),
    );
  }
}

class {Entity}Card extends StatelessWidget {
  const {Entity}Card({
    required this.{entity},
    this.onTap,
    super.key,  // ✅ Always last
  });

  final {Entity} {entity};
  final VoidCallback? onTap;

  @override
  Widget build(BuildContext context) { ... }
}

testWidgets('{엔티티} 목록 표시', (tester) async {
  when(() => mockRepository.get{Entity}s(...))
    .thenAnswer((_) async => Right(testResult));

  await tester.pumpWidget(const MaterialApp(home: {Feature}Page()));
  await tester.pumpAndSettle();

  expect(find.byType({Entity}Card), findsNWidgets(2));
});

@TypedGoRoute<{Feature}Route>(path: '/{feature}')
class {Feature}Route extends GoRouteData with ${Feature}Route {
  const {Feature}Route();

  static RouteBase get base => ${feature}Route;

  @override
  MaterialPage<void> buildPage(BuildContext context, GoRouterState state) {
    return const MaterialPage<void>(child: {Feature}Page());
  }
}

abstract class {Feature}RouteName {
  static const String path = '/{feature}';
}

// feature/{feature_name}/{app,console}/widgetbook/lib/src/use_case/{entity}_card_use_case.dart
@widgetbook.UseCase(
  name: 'Default',
  type: {Entity}Card,
  path: '[App]/{Feature}',   // 대괄호는 세그먼트 하나를 감싼다 ('[App/{Feature}]' 아님)
)
Widget build{Entity}CardUseCase(BuildContext context) {
  return {Entity}Card(
    {entity}: const {Entity}(id: 1, title: '테스트', ...),
  );
}

# Write BDD tests
/cc-flutter:bdd:generate {feature_name} --location {location}

app/{app}/integration_test/
├── features/
│   ├── {feature}_list.feature
│   ├── {feature}_detail.feature
│   └── {feature}_form.feature
├── step/
│   └── {feature}_steps.dart
└── scenarios/
    └── {feature}_{scenario}_test.dart

Feature: {feature} List # {feature} 목록
  As a user, I want to view the {feature} list. # 사용자로서 {feature} 목록을 보고 싶습니다

  @smoke
  Scenario: List loads successfully # 목록 로딩 성공
    Given the app is running # 앱이 실행 중입니다
    When I navigate to the {feature} page # {feature} 페이지로 이동합니다
    Then the {feature} list is displayed # {feature} 목록이 보입니다

feature/{feature_name}/{app,console}/lib/src/presentation/
├── bloc/{feature}_list/
│   ├── {feature}_list_bloc.dart
│   ├── {feature}_list_event.dart
│   └── {feature}_list_state.dart
├── page/
│   └── {feature}_page.dart
├── widget/
│   └── {entity}_card.dart

feature/{feature_name}/{app,console}/lib/src/route/{feature}_route.dart

feature/{feature_name}/{app,console}/test/src/
├── golden/  # 기준 스냅샷·gallery 수집 배선 포함
├── bdd/     # co_bdd 모드: .feature·step·생성 widget 테스트
└── presentation/
    ├── bloc/{feature}_list_bloc_test.dart
    └── page/{feature}_page_test.dart

app/{app}/integration_test/                # 실행 앱 여정/명시적 수기 Patrol legacy
├── features/
│   ├── {feature}_list.feature
│   ├── {feature}_detail.feature
│   └── {feature}_form.feature
├── step/{feature}_steps.dart
└── scenarios/{feature}_{scenario}_test.dart

feature/{feature_name}/{app,console}/widgetbook/lib/src/use_case/  # 별도 역할 소유 패키지
├── {entity}_card_use_case.dart
└── {feature}_page_use_case.dart

// Event: sealed class + factory + private implementation
sealed class {Feature}ListEvent {
  const factory {Feature}ListEvent.loadRequested() = _LoadRequested;
}

final class _LoadRequested extends {Feature}ListEvent {
  const _LoadRequested();
}

// BLoC: Optional Constructor Injection
class {Feature}ListBloc extends BlocSignal<...> {
  {Feature}ListBloc({
    Get{Entity}sUsecase? get{Entity}sUsecase,
  }) : _get{Entity}sUsecase = get{Entity}sUsecase ?? const Get{Entity}sUsecase(),
       super(...);

  final Get{Entity}sUsecase _get{Entity}sUsecase;

  Future<void> _onLoadRequested(...) async {
    final result = await _get{Entity}sUsecase(params);
    if (!isClosed) { emit(...); }  // ✅ Closed check
  }
}

// ❌ getIt usage prohibited
// create: (_) => getIt<{Feature}Bloc>(),

// ❌ Key? key 패턴 금지
// const {Entity}Card({Key? key}) : super(key: key);

const {Entity}Card({
  required this.{entity},  // required 먼저
  this.onTap,              // optional 다음
  super.key,               // ✅ super.key 마지막
});