@ds9-solutions/mcp 0.1.0 → 0.3.0

package/content/skills/driftorm/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: driftorm
+description: Convenções e boas práticas do Drift, a biblioteca de banco de dados type-safe para Dart e Flutter (SQLite e Postgres). Use ao criar, editar, revisar ou testar tabelas, consultas, DAOs, migrations ou a classe de banco em projetos que dependem de drift.
+---
+
+# Drift best practices
+
+Baseado na documentação oficial: https://drift.simonbinder.eu (repositório simolus3/drift, `drift` 2.35.x).
+
+## Princípio central
+
+O Drift gera código a partir do schema que você declara. O schema é a fonte da verdade: tabelas em Dart (ou SQL em arquivos `.drift`), uma classe de banco central e o `build_runner` gerando o resto. Toda mudança de schema é uma migration versionada e testada.
+
+## Setup
+
+| Alvo | Dependências | Dev dependencies |
+|---|---|---|
+| Flutter | `drift`, `drift_flutter`, `path_provider` | `drift_dev`, `build_runner` |
+| Dart (SQLite) | `drift`, `sqlite3` | `drift_dev`, `build_runner` |
+| Dart (Postgres) | `drift`, `postgres`, `drift_postgres` | `drift_dev`, `build_runner` |
+
+- `dart run build_runner build` gera o código uma vez. Durante o desenvolvimento, use `dart run build_runner watch`.
+- Para Postgres, configure `sql: dialects: [postgres]` no `build.yaml`. Por padrão o gerador só emite SQL de SQLite.
+
+## Regras
+
+### Classe de banco
+
+1. **Uma classe `@DriftDatabase(tables: [...], daos: [...])`** que estende `_$NomeDatabase`, com `part 'arquivo.g.dart';`.
+2. **O construtor aceita um `QueryExecutor` opcional**: `AppDatabase([QueryExecutor? e]) : super(e ?? _openConnection());`. Isso permite injetar um banco em memória nos testes.
+3. **Use uma única instância (singleton) por arquivo de banco.** Abrir a mesma classe várias vezes sobre o mesmo arquivo quebra os streams e gera aviso em runtime. Forneça a instância por DI (Riverpod, get_it, provider).
+4. **Abra a conexão fora da thread principal.** No Flutter, use `driftDatabase(name: ...)`, do `drift_flutter`. Em Dart puro, use `NativeDatabase.createInBackground(File(...))`. Ambos rodam o SQLite em isolate.
+5. **Feche com `await db.close()`** no fim do ciclo de vida (testes, shutdown do servidor).
+
+### Tabelas
+
+6. **Uma tabela é uma classe que estende `Table`**, com colunas declaradas como `late final campo = tipo()();`. Os parênteses finais são obrigatórios.
+7. **Colunas são não-nulas por padrão.** Use `.nullable()` só quando `null` tiver significado de domínio.
+8. **Chave primária:** `integer().autoIncrement()()` para o caso comum. Para outros casos, sobrescreva `Set<Column> get primaryKey => {...}` (só com `=>` e literal de set).
+9. **Prefira `clientDefault()` a `withDefault()`.** O `clientDefault` é calculado em Dart e não exige migration. O `withDefault` altera o schema.
+10. **Chaves estrangeiras com `.references(Tabela, #coluna, onDelete: ...)`.** No SQLite elas vêm desligadas, então ative com `PRAGMA foreign_keys = ON` no `beforeOpen`.
+11. **Garanta integridade no schema:** `.unique()`, `uniqueKeys` para unicidade composta, `.check(expr)` para validação. Prefira `check` a `withLength`, que só valida em Dart.
+12. **Crie índices com `@TableIndex(name: ..., columns: {#col})`** para colunas muito filtradas. Chave primária, `unique` e alvo de FK já têm índice.
+13. **Em projeto novo, armazene `DateTime` como texto ISO-8601** com `store_date_time_values_as_text: true` no `build.yaml`. O padrão é timestamp Unix em segundos, sem fuso e sem frações.
+14. **Reaproveite colunas comuns** (`id`, `createdAt`) com mixins de tabela.
+15. **Enums e tipos próprios** usam `intEnum<T>()`, `textEnum<T>()` ou `TypeConverter`, em vez de conversão manual espalhada pelo código.
+16. **Rode o gerador de novo** sempre que mudar tabelas, DAOs ou o annotation do banco.
+
+### Consultas e escrita
+
+17. **Insira com `Companion.insert(...)`**, que torna obrigatórios só os campos sem default. Para atualização parcial, use `Companion(campo: Value(x))`.
+18. **Use a API tipada** (`select`, `into`, `update`, `delete`, joins, manager) antes de SQL cru. Quando precisar de SQL, prefira arquivos `.drift`, que o gerador valida em tempo de build. `customSelect` fica como último recurso e precisa de `readsFrom` para funcionar com `watch`.
+19. **`get()` para leitura única e `watch()` para UI reativa.** O stream já emite o valor atual ao ser escutado, então não combine `get()` com `watch()`.
+20. **`getSingle()` lança erro se não houver exatamente uma linha.** Quando a ausência é um caso válido, use `getSingleOrNull()` ou `watchSingleOrNull()`.
+
+### Organização
+
+21. **Separe as consultas por domínio em DAOs:** `@DriftAccessor(tables: [...])` estendendo `DatabaseAccessor<AppDatabase>` com o mixin gerado. Registre os DAOs em `daos:` no `@DriftDatabase`.
+22. **Não exponha a classe de banco para a UI ou para os handlers.** Exponha DAOs ou repositórios que retornam modelos e streams.
+
+### Transações
+
+23. **Operações que precisam ser atômicas vão em `transaction(() async { ... })`.**
+24. **Faça `await` em todas as chamadas dentro da transação.** Query sem `await` pode rodar depois do fechamento e causar perda de dados ou crash. Não agende timers que usem o banco dentro da transação.
+25. **Streams criados fora da transação só são notificados no commit.** Não escute fora da transação um stream criado dentro dela.
+
+### Migrations
+
+26. **Toda mudança de schema exige incrementar o `schemaVersion` e escrever uma migration.** O Drift não altera bancos existentes sozinho.
+27. **Use o fluxo guiado `make-migrations`.** Registre o banco em `databases:` no `build.yaml` e rode `dart run drift_dev make-migrations` **antes** da primeira mudança, para salvar o schema inicial. Depois, a cada mudança, incremente a versão e rode o comando de novo.
+28. **Escreva as migrations com `stepByStep(from1To2: ..., from2To3: ...)`**, usando o `schema` recebido e nunca as tabelas atuais da classe. Extraia o `stepByStep` para um getter de extensão em `GeneratedDatabase`, para não referenciar o schema atual por acidente.
+29. **Rode os testes de migration gerados** (em `test/drift/`) e versione a pasta `drift_schemas/` no Git.
+30. **Evite consultas dentro de callbacks de migration.** Se precisar, rode-as só depois de o schema chegar ao estado que elas esperam.
+31. **Pragmas e seed vão no `beforeOpen`**, que roda a cada abertura. Use `details.wasCreated` e `details.hadUpgrade` para condicionar o seed.
+
+### Testes
+
+32. **Teste com `NativeDatabase.memory()`**, abrindo no `setUp` e fechando no `tearDown`. Em widget tests do Flutter, envolva com `DatabaseConnection(..., closeStreamsSynchronously: true)`.
+
+## Exemplos
+
+### Tabelas, banco e conexão (Flutter)
+
+```dart
+// lib/database/database.dart
+import 'package:drift/drift.dart';
+import 'package:drift_flutter/drift_flutter.dart';
+import 'package:path_provider/path_provider.dart';
+
+import 'database.steps.dart';
+
+part 'database.g.dart';
+
+mixin AutoIncrementingPrimaryKey on Table {
+  late final id = integer().autoIncrement()();
+}
+
+class Categories extends Table with AutoIncrementingPrimaryKey {
+  late final name = text().unique()();
+}
+
+@TableIndex(name: 'todo_category', columns: {#category})
+class TodoItems extends Table with AutoIncrementingPrimaryKey {
+  // Coluna que se referencia no check precisa de tipo explícito.
+  late final Column<String> title =
+      text().check(title.length.isBiggerThanValue(0))();
+  late final done = boolean().clientDefault(() => false)();
+  late final category = integer()
+      .nullable()
+      .references(Categories, #id, onDelete: KeyAction.setNull)();
+  late final createdAt = dateTime().clientDefault(DateTime.now)();
+}
+
+@DriftDatabase(tables: [Categories, TodoItems], daos: [TodosDao])
+class AppDatabase extends _$AppDatabase {
+  AppDatabase([QueryExecutor? executor]) : super(executor ?? _openConnection());
+
+  @override
+  int get schemaVersion => 2;
+
+  @override
+  MigrationStrategy get migration => MigrationStrategy(
+        onUpgrade: _schemaUpgrade,
+        beforeOpen: (details) async {
+          await customStatement('PRAGMA foreign_keys = ON');
+        },
+      );
+
+  static QueryExecutor _openConnection() {
+    return driftDatabase(
+      name: 'app_database',
+      native: const DriftNativeOptions(
+        databaseDirectory: getApplicationSupportDirectory,
+      ),
+    );
+  }
+}
+
+extension Migrations on GeneratedDatabase {
+  OnUpgrade get _schemaUpgrade => stepByStep(
+        from1To2: (m, schema) async {
+          await m.createTable(schema.categories);
+          await m.addColumn(schema.todoItems, schema.todoItems.category);
+        },
+      );
+}
+```
+
+### DAO com stream e transação
+
+```dart
+// lib/database/todos_dao.dart
+import 'package:drift/drift.dart';
+
+import 'database.dart';
+
+part 'todos_dao.g.dart';
+
+@DriftAccessor(tables: [TodoItems, Categories])
+class TodosDao extends DatabaseAccessor<AppDatabase> with _$TodosDaoMixin {
+  TodosDao(super.attachedDatabase);
+
+  Stream<List<TodoItem>> watchPending() {
+    return (select(todoItems)
+          ..where((t) => t.done.equals(false))
+          ..orderBy([(t) => OrderingTerm.desc(t.createdAt)]))
+        .watch();
+  }
+
+  Future<int> add(String title) {
+    return into(todoItems).insert(TodoItemsCompanion.insert(title: title));
+  }
+
+  Future<void> deleteCategory(int categoryId) {
+    return transaction(() async {
+      await (update(todoItems)..where((t) => t.category.equals(categoryId)))
+          .write(const TodoItemsCompanion(category: Value(null)));
+      await (delete(categories)..where((c) => c.id.equals(categoryId))).go();
+    });
+  }
+}
+```
+
+### Conexão Postgres (backend Dart)
+
+```dart
+import 'dart:io';
+
+import 'package:drift_postgres/drift_postgres.dart';
+import 'package:postgres/postgres.dart' as pg;
+
+QueryExecutor openPostgres() {
+  final env = Platform.environment;
+  return PgDatabase(
+    endpoint: pg.Endpoint(
+      host: env['DB_HOST']!,
+      database: env['DB_NAME']!,
+      username: env['DB_USER'],
+      password: env['DB_PASSWORD'],
+    ),
+  );
+}
+```
+
+### Teste
+
+```dart
+import 'package:drift/drift.dart';
+import 'package:drift/native.dart';
+import 'package:test/test.dart';
+
+import 'package:my_app/database/database.dart';
+
+void main() {
+  late AppDatabase db;
+
+  setUp(() {
+    db = AppDatabase(
+      DatabaseConnection(
+        NativeDatabase.memory(),
+        closeStreamsSynchronously: true,
+      ),
+    );
+  });
+
+  tearDown(() => db.close());
+
+  test('watchPending emite o item recém-criado', () async {
+    final stream = db.todosDao.watchPending();
+    await db.todosDao.add('Escrever testes');
+
+    final items = await stream.first;
+    expect(items.map((t) => t.title), contains('Escrever testes'));
+  });
+}
+```
+
+## Checklist de revisão
+
+- [ ] Mudou tabela, DAO ou annotation? O `build_runner` foi rodado de novo?
+- [ ] Mudou o schema? O `schemaVersion` foi incrementado, o `make-migrations` foi rodado e existe um passo `fromXToY` testado?
+- [ ] A migration usa `schema.*` e não as tabelas atuais da classe?
+- [ ] Existe uma única instância do banco, injetada por DI?
+- [ ] A conexão usa `driftDatabase` ou `createInBackground`?
+- [ ] FKs no SQLite têm `PRAGMA foreign_keys = ON`?
+- [ ] Toda chamada dentro de `transaction` tem `await`?
+- [ ] Defaults usam `clientDefault`, salvo quando o default precisa estar no schema?
+- [ ] `getSingle` é usado só onde a linha certamente existe?
+- [ ] Os testes usam `NativeDatabase.memory()` e fecham o banco no `tearDown`?

package/content/skills/flutter/SKILL.md

@@ -0,0 +1,419 @@
+---
+name: flutter
+description: Padrões de arquitetura, código e qualidade para apps Flutter com Provider, go_router e fpdart. Use ao criar, editar, revisar ou testar arquivos em lib/ ou test/ de um projeto Flutter, como features, providers, services, models, views, rotas, tema ou testes.
+---
+
+# Flutter best practices
+
+Arquitetura em camadas com **Provider + ChangeNotifier**, **go_router** e **fpdart** (`TaskEither`/`Either`), alinhada ao guia oficial de arquitetura do Flutter (MVVM com camada de dados) e ao Effective Dart.
+
+## Stack
+
+- **Estado:** `provider` com `ChangeNotifier`. Não misture Riverpod, Bloc ou GetX.
+- **Navegação:** `go_router`.
+- **Erros e async:** `fpdart`. Operações que podem falhar retornam `TaskEither`, nunca `Future` que lança exceção entre camadas.
+- **Configuração:** `flutter_dotenv` (`.env`) ou `--dart-define`. Nunca coloque segredos ou URLs fixas no código.
+- **Lints:** `flutter_lints`.
+
+## Estrutura de pastas
+
+```
+lib/
+├── main.dart              # bootstrap + composição de dependências
+├── components/            # features
+│   └── <feature>/
+│       ├── models/
+│       ├── providers/     # ChangeNotifier (ViewModel)
+│       ├── services/      # acesso a dados via ports (pode ter dtos/ e mappers/)
+│       ├── views/         # telas
+│       │   └── components/  # widgets exclusivos da feature
+│       └── components/    # subfeatures, com a mesma estrutura
+└── shared/
+    ├── components/        # widgets reutilizáveis (buttons, inputs, widgets...)
+    ├── constraints/       # AppConstraints (bordas, breakpoints, limites)
+    ├── errors/            # Failure, exceções e Log
+    ├── infra/             # armazenamento local etc.
+    ├── models/
+    ├── providers/         # rotas e sessão
+    ├── services/          # implementações de infraestrutura
+    │   └── ports/         # contratos abstratos (HTTP, storage, push...)
+    ├── theme/             # paleta + extensão de ThemeData
+    ├── typography/        # AppTypography.of(context)
+    └── utils/
+```
+
+1. **Diretamente em `lib/`** só podem existir `components/`, `shared/`, `main.dart` e arquivos gerados de configuração (por exemplo, `firebase_options.dart`).
+2. **Na raiz de cada feature** (e de cada subfeature em `components/`), as únicas pastas permitidas são `models`, `providers`, `services`, `views` e `components`.
+3. **Use `components/` para subfeatures** quando a feature se divide por perfil ou área (por exemplo, `admin/components/reports`).
+
+## Camadas e fluxo de dados
+
+```
+View ──context.read/watch──▶ Provider ──▶ Service ──▶ Port (shared/services/ports)
+ ▲   .run() + match/fold      TaskEither<Failure, T>   TaskEither<Exception, T>   ▲
+ └──────── AppSnackBars ◀──── Log.print + Failure ◀───────────────────────────────┘
+                                                        implementado em shared/services
+```
+
+4. **Ports** são classes `abstract` em `shared/services/ports/` e retornam `TaskEither<Exception, T>`. As implementações concretas ficam em `shared/services/`.
+5. **Services de feature** recebem *ports* pelo construtor, nunca a implementação concreta. Eles convertem JSON em model e retornam `TaskEither<Exception, T>`, sem estado, sem `notifyListeners` e sem `BuildContext`.
+6. **Providers** estendem `ChangeNotifier` e recebem o service pelo construtor. Guardam estado privado exposto por getters e retornam `TaskEither<Failure, T>` (normalmente `Unit`). Em erro, registram com `Log` e devolvem a `Failure` do domínio.
+7. **Views** usam `context.read<T>()` para ações e `context.watch<T>()` para estado. Executam com `.run()` e tratam o resultado com `.match(...)` ou `.fold(...)`.
+8. **fpdart em toda fronteira entre camadas:**
+   - Em `views → providers`, a view consome com `.run()` **e** `.match`, `.fold`, `.getOrElse`, `.isLeft` ou `.isRight`. Só `mapLeft` não basta, porque ignora o caminho de sucesso.
+   - Em `providers → services`, o arquivo importa `package:fpdart/fpdart.dart` e trabalha com `TaskEither` ou `Either`.
+   - Em `services → shared/services`, vale a mesma regra.
+9. **Direção única de dependência.** Uma view nunca importa um service, e um provider nunca importa uma view. A lógica de negócio fica fora dos widgets.
+10. **Crie uma camada de *use case*** só quando a lógica for complexa ou compartilhada entre providers. Caso contrário, ela fica no provider ou no service.
+
+## Regras de código
+
+### Documentação e estilo
+
+11. **Toda declaração tem `///` logo acima:** classes, construtores, métodos, getters, funções, enums, extensions, mixins, typedefs e campos de classe. Variáveis locais estão isentas. Siga o Effective Dart: primeira frase curta terminada em ponto, campos descritos com substantivo e booleanos começando com "Indica se...".
+12. **Não use `var`.** Use `final`, `const` ou tipo explícito.
+13. **Todo arquivo passa por `dart format`.** Código fora do formato não é commitado.
+14. **`flutter analyze --fatal-infos` precisa passar limpo.** Não use `// ignore` sem justificativa no próprio comentário.
+15. **Importe pelo caminho do pacote** (`package:<app>/...`). Use alias (`as admin`, `as customer`) quando houver nomes de classe iguais em features diferentes.
+16. **Ao mudar dependências, versione o `pubspec.lock`**, e no CI use `flutter pub get --enforce-lockfile`.
+
+### Models
+
+17. **Models são classes imutáveis**, com campos `final`, construtor `const` e `factory fromJson(Map<String, dynamic>)` defensivo (`?.toString() ?? ''`, `DateTime.tryParse`). Nada de `dynamic` vazando para fora do model.
+18. **Textos de exibição derivados** (rótulo, tradução, ícone) ficam em getters do model ou em `shared/utils`, nunca espalhados pela view.
+19. **DTOs e mappers** ficam em `services/dtos/` e `services/mappers/` quando o formato da API difere do model de domínio.
+
+### Erros e logs
+
+20. **`Failure` é uma `sealed class`** em `shared/errors/failure.dart`, com uma subclasse por domínio (`AuthFailure`, `LoadingFailure`, `ValidationFailure`, `GeneralFailure`...). Use a do domínio certo. Se faltar uma, crie a subclasse em vez de reaproveitar outra.
+21. **A mensagem da `Failure` é texto para o usuário**, claro e sem detalhe técnico. O detalhe técnico vai para o log, com `origin` (classe), `method`, `error` e `stack`.
+22. **Não use `print` nem `debugPrint` soltos.** Centralize em um `Log` com níveis (Debug, Info, Warning, Error, Critical) sobre `dart:developer`. Nunca registre tokens, senhas ou dados pessoais sensíveis.
+
+### Estado e injeção de dependência
+
+23. **A composição é explícita em `main.dart`.** Ela instancia os ports concretos, depois os services e por fim os providers, sempre por construtor. Não use service locator.
+24. **Escopo dos providers:**
+    - Globais (auth, sessão) ficam no `MultiProvider` acima do `MaterialApp.router`.
+    - Providers de uma área ficam com `ChangeNotifierProvider.value` no `ShellRoute` dessa área.
+    - Providers de tela efêmera são criados no `builder` da `GoRoute`.
+25. **Carga inicial** acontece em `initState` com `WidgetsBinding.instance.addPostFrameCallback((_) => _load())`.
+26. **Depois de qualquer `await` na view**, confira `if (!mounted) return;` (ou `context.mounted`) antes de usar o `context`.
+27. **Paralelize com `Future.wait`** somente chamadas independentes, e trate cada resultado com tipo explícito, sem `as List<T>`.
+28. **Exponha coleções como somente leitura** (`List.unmodifiable`) e só chame `notifyListeners()` quando o estado mudar de fato.
+
+### Navegação
+
+29. **Paths são constantes em uma classe `RoutesMapping`.** Nunca escreva string de rota solta na view.
+30. **Toda `GoRoute` tem `name`.** Navegue com `context.go(...)` ou `context.push(...)` usando `RoutesMapping`.
+31. **Autenticação e acesso** são decididos no `redirect` do `GoRouter`, com `refreshListenable` apontando para o provider de auth. Não faça checagem de login dentro das telas.
+32. **Áreas com navegação própria** (por perfil, com bottom bar) usam `ShellRoute` com `navigatorKey` dedicado.
+33. **Push notifications e deep links** passam por um único método do gerenciador de rotas.
+
+### UI, tema e acessibilidade
+
+34. **Cores vêm de uma `enum` de paleta** (com getter `color`) **e de uma extensão de `ThemeData`** (`Theme.of(context).primary`). Evite `Colors.*` e hexadecimais na view.
+35. **Textos usam `AppTypography.of(context).<estilo>(...)`**, que escolhe entre mobile e tablet. Evite `TextStyle(fontSize: ...)` solto.
+36. **Botões, inputs, modais e snackbars** usam os componentes de `shared/components` ou os estilos expostos pela extensão de tema. Raio de borda, breakpoints e limites ficam em `AppConstraints`.
+37. **Feedback ao usuário** passa por `AppSnackBars.showSuccess`, `showError` e `showWarning`.
+38. **Layout responsivo** decide com `AppConstraints.isMobile` ou `isTablet` no nível da tela, e com `LayoutBuilder` dentro dos widgets.
+39. **Widgets pequenos e `const`:** quebre a tela em widgets dentro de `views/components/` em vez de métodos `_buildX()` gigantes.
+40. **Acessibilidade:** ícones clicáveis têm `tooltip` ou `Semantics`, e ícones informativos têm `semanticLabel`.
+
+### Testes
+
+41. **Testes ficam em `test/`, espelhando `lib/`**, com sufixo `_test.dart`.
+42. **Services são testados com um *fake* do port** (uma classe que implementa o contrato). Providers são testados com o service real sobre esse port fake. Não acesse rede nem serviços externos em teste unitário.
+43. **Widgets são testados com `testWidgets`**, envolvendo a tela em `MaterialApp` e `ChangeNotifierProvider.value`. Use `pump` para mudanças simples e `pumpAndSettle` para animações e operações async.
+
+## Fluxo para criar uma feature
+
+- [ ] **1. Pasta.** Crie `lib/components/<feature>/` com `models/`, `services/`, `providers/` e `views/`.
+- [ ] **2. Model.** Crie a classe imutável com `fromJson` defensivo.
+- [ ] **3. Port.** Se precisar de infraestrutura nova, crie o contrato em `shared/services/ports/` e a implementação em `shared/services/`.
+- [ ] **4. Service.** Receba os ports pelo construtor e retorne `TaskEither<Exception, T>`.
+- [ ] **5. Provider.** Estenda `ChangeNotifier`, guarde o estado privado e use `TaskEither.tryCatch`, `Log` e a `Failure` do domínio.
+- [ ] **6. View.** Leia com `context.watch`, aja com `context.read` e consuma com `.run()` + `.match`.
+- [ ] **7. Rota.** Adicione a constante em `RoutesMapping` e a `GoRoute` nomeada.
+- [ ] **8. DI.** Instancie o service e o provider em `main.dart` e registre no escopo certo.
+- [ ] **9. Testes.** Teste o service com port fake, o provider e o widget principal.
+- [ ] **10. Validação:**
+
+```bash
+dart format lib test
+flutter analyze --fatal-infos
+flutter test
+```
+
+## Exemplos (feature ilustrativa: tarefas)
+
+### Port
+
+```dart
+// lib/shared/services/ports/app_http_port.dart
+import 'package:fpdart/fpdart.dart';
+
+/// Contrato de acesso HTTP à API do app.
+abstract class AppHttpPort {
+  /// Executa um GET em [path] e converte a resposta com [fromJson].
+  TaskEither<Exception, T> get<T>(String path, T Function(dynamic) fromJson);
+}
+```
+
+### Model
+
+```dart
+// lib/components/tasks/models/task_model.dart
+
+/// Representa uma tarefa do usuário.
+class TaskModel {
+  /// Identificador da tarefa.
+  final String id;
+
+  /// Título exibido na lista.
+  final String title;
+
+  /// Data de conclusão, quando houver.
+  final DateTime? doneAt;
+
+  /// Cria uma tarefa imutável.
+  const TaskModel({required this.id, required this.title, this.doneAt});
+
+  /// Constrói a tarefa a partir do JSON da API.
+  factory TaskModel.fromJson(Map<String, dynamic> json) {
+    return TaskModel(
+      id: json['id']?.toString() ?? '',
+      title: json['title']?.toString() ?? '',
+      doneAt: DateTime.tryParse(json['done_at']?.toString() ?? ''),
+    );
+  }
+
+  /// Indica se a tarefa foi concluída.
+  bool get isDone => doneAt != null;
+}
+```
+
+### Service
+
+```dart
+// lib/components/tasks/services/tasks_service.dart
+import 'package:fpdart/fpdart.dart';
+import 'package:my_app/components/tasks/models/task_model.dart';
+import 'package:my_app/shared/services/ports/app_http_port.dart';
+
+/// Acessa os dados de tarefas.
+class TasksService {
+  /// Porta HTTP para a API.
+  final AppHttpPort _httpPort;
+
+  /// Cria o serviço com a porta HTTP injetada.
+  TasksService(this._httpPort);
+
+  /// Busca as tarefas do usuário autenticado.
+  TaskEither<Exception, List<TaskModel>> getTasks() {
+    return _httpPort.get<List<TaskModel>>('/tasks', (json) {
+      final List<dynamic> list = json is List
+          ? json
+          : (json['data'] ?? <dynamic>[]) as List<dynamic>;
+      return list
+          .map((item) => TaskModel.fromJson(item as Map<String, dynamic>))
+          .toList();
+    });
+  }
+}
+```
+
+### Provider
+
+```dart
+// lib/components/tasks/providers/tasks_provider.dart
+import 'package:flutter/foundation.dart';
+import 'package:fpdart/fpdart.dart';
+import 'package:my_app/components/tasks/models/task_model.dart';
+import 'package:my_app/components/tasks/services/tasks_service.dart';
+import 'package:my_app/shared/errors/failure.dart';
+import 'package:my_app/shared/errors/log.dart';
+
+/// Gerencia o estado da tela de tarefas.
+class TasksProvider extends ChangeNotifier {
+  /// Serviço de acesso às tarefas.
+  final TasksService _service;
+
+  /// Cria o provider com o serviço injetado.
+  TasksProvider(this._service);
+
+  /// Tarefas carregadas.
+  List<TaskModel> _tasks = const [];
+
+  /// Indica se as tarefas estão sendo carregadas.
+  bool _isLoading = false;
+
+  /// Tarefas carregadas, somente leitura.
+  List<TaskModel> get tasks => List.unmodifiable(_tasks);
+
+  /// Indica se as tarefas estão sendo carregadas.
+  bool get isLoading => _isLoading;
+
+  /// Carrega as tarefas e notifica a tela.
+  TaskEither<Failure, Unit> load() {
+    return TaskEither.tryCatch(
+      () async {
+        _setLoading(true);
+        try {
+          final result = await _service.getTasks().run();
+          _tasks = result.getOrElse((error) => throw error);
+          return unit;
+        } finally {
+          _setLoading(false);
+        }
+      },
+      (error, stack) {
+        Log.print<Error>(
+          message: 'Erro ao carregar tarefas',
+          origin: 'TasksProvider',
+          method: 'load',
+          error: error,
+          stack: stack,
+        );
+        return const LoadingFailure('Não foi possível carregar suas tarefas.');
+      },
+    );
+  }
+
+  /// Atualiza o indicador de carregamento e notifica os ouvintes.
+  void _setLoading(bool value) {
+    _isLoading = value;
+    notifyListeners();
+  }
+}
+```
+
+### View
+
+```dart
+// lib/components/tasks/views/tasks_view.dart
+import 'package:flutter/material.dart';
+import 'package:my_app/components/tasks/providers/tasks_provider.dart';
+import 'package:my_app/shared/components/widgets/app_snackbars.dart';
+import 'package:my_app/shared/theme/app_theme.dart';
+import 'package:my_app/shared/typography/app_typography.dart';
+import 'package:provider/provider.dart';
+
+/// Tela com a lista de tarefas.
+class TasksView extends StatefulWidget {
+  /// Cria a tela de tarefas.
+  const TasksView({super.key});
+
+  /// Cria o estado da tela.
+  @override
+  State<TasksView> createState() => _TasksViewState();
+}
+
+/// Estado da tela de tarefas.
+class _TasksViewState extends State<TasksView> {
+  /// Agenda a carga inicial após o primeiro frame.
+  @override
+  void initState() {
+    super.initState();
+    WidgetsBinding.instance.addPostFrameCallback((_) => _load());
+  }
+
+  /// Carrega as tarefas e mostra erro amigável em caso de falha.
+  Future<void> _load() async {
+    final result = await context.read<TasksProvider>().load().run();
+    if (!mounted) return;
+    result.match(
+      (failure) => AppSnackBars.showError(context, failure.message),
+      (_) {},
+    );
+  }
+
+  /// Monta a lista de tarefas.
+  @override
+  Widget build(BuildContext context) {
+    final provider = context.watch<TasksProvider>();
+    final typography = AppTypography.of(context);
+
+    if (provider.isLoading) {
+      return Center(
+        child: CircularProgressIndicator(color: Theme.of(context).primary),
+      );
+    }
+
+    return ListView.separated(
+      padding: const EdgeInsets.all(16),
+      itemCount: provider.tasks.length,
+      separatorBuilder: (_, _) => const SizedBox(height: 8),
+      itemBuilder: (context, index) {
+        final task = provider.tasks[index];
+        return ListTile(
+          title: Text(task.title, style: typography.topic()),
+          trailing: Icon(
+            task.isDone ? Icons.check_circle : Icons.schedule,
+            color: Theme.of(context).primary,
+            semanticLabel: task.isDone ? 'Concluída' : 'Pendente',
+          ),
+        );
+      },
+    );
+  }
+}
+```
+
+### Teste do service com port fake
+
+```dart
+// test/components/tasks/services/tasks_service_test.dart
+import 'package:flutter_test/flutter_test.dart';
+import 'package:fpdart/fpdart.dart';
+import 'package:my_app/components/tasks/services/tasks_service.dart';
+import 'package:my_app/shared/services/ports/app_http_port.dart';
+
+/// Porta HTTP falsa que devolve uma resposta fixa.
+class _FakeHttpPort implements AppHttpPort {
+  /// Cria a porta com a resposta a devolver.
+  _FakeHttpPort(this.response);
+
+  /// Resposta JSON simulada.
+  final Object response;
+
+  /// Devolve a resposta simulada convertida pelo [fromJson].
+  @override
+  TaskEither<Exception, T> get<T>(String path, T Function(dynamic) fromJson) =>
+      TaskEither.of(fromJson(response));
+}
+
+void main() {
+  test('converte a lista da API em TaskModel', () async {
+    final service = TasksService(
+      _FakeHttpPort({
+        'data': [
+          {'id': '1', 'title': 'Revisar PR', 'done_at': '2026-05-10'},
+        ],
+      }),
+    );
+
+    final result = await service.getTasks().run();
+
+    final tasks = result.getOrElse((error) => throw error);
+    expect(tasks.single.title, 'Revisar PR');
+    expect(tasks.single.isDone, isTrue);
+  });
+}
+```
+
+## Evite
+
+- **`Failure` genérica ou errada:** por exemplo, `AuthFailure` para erro de carregamento.
+- **Estilos fixos na view:** `Colors.white`, `TextStyle(fontSize: 16)`, `Colors.grey.shade300`.
+- **Casts depois de `Future.wait`:** algo como `results[0] as List<T>`.
+- **Import duplicado** do mesmo arquivo com e sem alias.
+- **Declarações sem `///`.**
+- **Consumo de `TaskEither` só com `mapLeft`**, que ignora o caminho de sucesso.
+- **`try/catch` dentro da view** para tratar erro de provider. O erro já chega como `Failure`.
+
+## Referências
+
+- Guia de arquitetura do Flutter: https://docs.flutter.dev/app-architecture
+- Testes no Flutter: https://docs.flutter.dev/testing/overview
+- Effective Dart: https://dart.dev/effective-dart
+- Skills oficiais do Flutter: https://github.com/flutter/skills