App Brick

프론트엔드 atomic brick 상세

App Brick (7종)#

프론트엔드(Flutter feature 패키지)를 구성하는 atomic brick 7종의 상세 레퍼런스입니다. 단일 소스는 coco-de/bricks 저장소의 bricks/registry.yaml이며, 모든 brick은 공통 규약(자기 파일만 생성, barrel 미수정, 생성자 주입 전용)을 따릅니다.

{target}은 application 또는 console, {feature}는 feature 패키지 이름입니다.

entity#

순수 도메인 엔티티를 생성합니다. pattern 변수로 구현 방식을 선택합니다.

변수	설명
`name`	엔티티 이름 (snake_case)
`properties`	필드 목록 — compose는 매니페스트 `models.entities`의 fields를 `name:Type` CSV로 전달
`pattern`	`equatable` \| `freezed` \| `plain`

항목	값
산출 파일	`{name}.dart`, `{name}_test.dart`
배치 경로	`feature/{target}/{feature}/lib/src/domain/entity/`
의존 brick	없음

import 가이드: 같은 feature 내에서는 직접 import, 외부 feature에서는 import 'package:{feature}/domain.dart'. core 경유 금지.

failure#

도메인 Failure sealed class와 메시지 상수를 생성합니다. core의 Failure를 상속합니다.

변수	설명
`name`	failure 이름 (snake_case)
`failure_cases`	sealed class의 케이스 목록

항목	값
산출 파일	`{name}_failure.dart` , `{name}_failure_messages.dart` , `{name}_failure_test.dart`
배치 경로	`feature/{target}/{feature}/lib/src/domain/failure/`
의존 brick	없음

import 가이드: 내부는 직접 import, 외부는 package:{feature}/domain.dart. core 경유 금지.

usecase#

Clean Architecture UseCase를 생성합니다. 생성자 주입 전용이며 getIt을 사용하지 않습니다. usecase_type 3종: standard, auth_required, silent_auth.

변수	설명
`name`	usecase 이름 (snake_case)
`feature_name`	소속 feature 이름
`return_type`	반환 타입
`param_type`	파라미터 형태 (`params_class`이면 별도 params 파일 생성)
`single_param_type`	단일 파라미터일 때의 타입
`usecase_type`	`standard` \| `auth_required` \| `silent_auth`

항목	값
산출 파일	`{name}_usecase.dart` , `{name}_params.dart` (param_type=params_class), `{name}_usecase_test.dart`
배치 경로	`feature/{target}/{feature}/lib/src/domain/usecase/`
의존 brick	`repository` — `I{feature}Repository` 인터페이스를 참조

import 가이드: 내부는 직접 import, 외부는 package:{feature}/domain.dart. core 경유 금지.

repository#

Repository 인터페이스 + 구현체 + 네트워크별 mixin을 생성합니다. 구현체는 생성자 주입을 사용합니다. 산출 파일이 domain·data 하위로 분배되는 유일한 App brick입니다.

변수	설명
`name`	repository 이름 (snake_case)
`feature_name`	소속 feature 이름
`networks`	네트워크 mixin 선택: `serverpod` \| `openapi` \| `graphql` \| `inmemory` (미선택 시 inmemory 폴백)
`methods`	생성할 메서드 목록

항목	값
산출 파일	`domain/repository/i_{name}_repository.dart` , `data/repository/{name}_repository.dart` , `data/repository/mixins/{name}_{network}_mixin.dart` (조건부), `test/{name}_repository_test.dart`
배치 경로	`feature/{target}/{feature}/lib/src/` (domain·data 하위로 분배)
의존 brick	없음

import 가이드: 인터페이스는 package:{feature}/domain.dart로 노출. 구현체는 feature 내부 전용으로 외부 노출 금지 — cross-feature 참조는 인터페이스로만 합니다. core 경유 금지.

bloc#

BLoC 골격(Started/ItemSelected 이벤트)을 생성합니다. usecases를 선언하면 생성자 주입 와이어링이 함께 생성됩니다.

변수	설명
`name`	bloc 이름 (snake_case)
`feature_name`	소속 feature 이름
`usecases`	생성자에 주입할 usecase 목록

항목	값
산출 파일	`{name}/{name}_bloc.dart` , `{name}/{name}_event.dart` , `{name}/{name}_state.dart` , `{name}/bloc.dart` , `{name}/test/{name}_bloc_test.dart`
배치 경로	`feature/{target}/{feature}/lib/src/presentation/bloc/blocs/{name}/`
의존 brick	`usecase` — usecases 선언 시 같은 이름의 `{usecase}Usecase`가 존재해야 함

barrel 동작: 자기 폴더 barrel({name}/bloc.dart)만 생성합니다. 상위 blocs/bloc.dart 등록은 cob 책임입니다.

생성자 주입 패턴 (getIt 미사용 — 생성된 골격의 형태):

class NoticeListBloc extends Bloc<NoticeListEvent, NoticeListState> {
  NoticeListBloc({
    required GetNoticesUsecase getNoticesUsecase,
  })  : _getNoticesUsecase = getNoticesUsecase,
        super(const NoticeListState()) {
    on<NoticeListStarted>(_onStarted);
    on<NoticeListItemSelected>(_onItemSelected);
  }

  final GetNoticesUsecase _getNoticesUsecase;
}

import 가이드: usecase는 blocs/{name}/ 기준 '../../../../domain/usecase/' 상대 import. 외부는 package:{feature}/presentation.dart. core 경유 금지.

page#

Feature 페이지 위젯(HookWidget)을 생성합니다. has_bloc=true면 BlocProvider 래핑이 포함됩니다.

변수	설명
`name`	페이지 이름 (snake_case)
`feature_name`	소속 feature 이름
`has_bloc`	BlocProvider 사용 여부 — true면 같은 이름의 `{name}Bloc` 필요
`page_type`	`list` \| `detail` \| `form` \| `dashboard` \| `empty`
`target`	`application` \| `console`

page_type 5종 변형:

page_type	골격
`list`	목록 페이지
`detail`	상세 페이지
`form`	폼(입력) 페이지
`dashboard`	대시보드 페이지
`empty`	빈 골격 페이지

항목	값
산출 파일	`{name}_page.dart`, `{name}_page_test.dart`
배치 경로	`feature/{target}/{feature}/lib/src/presentation/page/`
의존 brick	`bloc` — has_bloc=true 시 같은 이름의 `{name}Bloc` 필요

라우트 등록: brick은 라우터를 수정하지 않습니다. {app|console}_routes.dart의 // 🔧 AUTO-REGISTER 마커에 대한 등록은 cob compose/cob add 또는 개발자가 수행합니다.

import 가이드: 같은 feature의 bloc은 '../bloc/bloc.dart' 상대 import. 외부는 package:{feature}/presentation.dart. core 경유 금지.

재사용 UI 위젯을 생성합니다. widget_type 3유형: stateless, stateful, hook.

변수	설명
`name`	위젯 이름 (snake_case)
`feature_name`	소속 feature 이름
`widget_type`	`stateless` \| `stateful` \| `hook`
`has_test`	테스트 파일 생성 여부

항목	값
산출 파일	`{name}.dart`, `{name}_test.dart` (has_test)
배치 경로	`feature/{target}/{feature}/lib/src/presentation/widget/`
의존 brick	없음

이름 규칙: 도너 컨벤션을 따라 파일명에 _widget 접미사를 붙이지 않습니다 (예: post_card.dart → PostCard).

import 가이드: 내부는 직접 import, 외부는 package:{feature}/presentation.dart. core 경유 금지.