@ds9-solutions/mcp 0.1.0 → 0.2.0

package/content/skills/dart-frog/examples/controller.dart

@@ -0,0 +1,75 @@
+// Caminho: lib/orders/adapter/controllers/order_controller.dart
+import 'dart:io';
+
+import 'package:dart_frog/dart_frog.dart';
+import 'package:fpdart/fpdart.dart';
+
+import '../../../common/exception/exceptions.dart';
+import '../../domain/services/order_service.dart';
+import '../dtos/order_dtos.dart';
+
+/// Adapta HTTP para o domínio; recebido pronto via `context.read`.
+class OrderController {
+  /// Cria o controller com o [_service] injetado pelo middleware.
+  const OrderController(this._service);
+
+  final OrderService _service;
+
+  /// POST /orders — cria um pedido para o usuário autenticado.
+  TaskEither<ClientException, OrderResponse> create(
+    RequestContext context,
+    String requesterId,
+  ) {
+    return TaskEither<ClientException, Object?>.tryCatch(
+      () => context.request.json(),
+      (_, __) => const ClientException(
+        statusCode: HttpStatus.badRequest,
+        message: 'Body JSON inválido.',
+      ),
+    )
+        .flatMap(_toDto)
+        .flatMap(
+          (dto) => _service
+              .create(ownerId: requesterId, total: dto.total!)
+              .mapLeft(_toClient),
+        )
+        .map(OrderResponse.fromDomain);
+  }
+
+  /// GET /orders/:id — retorna um pedido do usuário autenticado.
+  TaskEither<ClientException, OrderResponse> getById(
+    String id,
+    String requesterId,
+  ) {
+    return _service
+        .getOwnedById(id: id, requesterId: requesterId)
+        .mapLeft(_toClient)
+        .map(OrderResponse.fromDomain);
+  }
+
+  TaskEither<ClientException, CreateOrderRequest> _toDto(Object? json) {
+    if (json is! Map<String, Object?>) {
+      return TaskEither.left(const ClientException(
+        statusCode: HttpStatus.badRequest,
+        message: 'O body deve ser um objeto JSON.',
+      ));
+    }
+    final dto = CreateOrderRequest.fromJson(json);
+    final errors = dto.validate();
+    return errors.isEmpty
+        ? TaskEither.right(dto)
+        : TaskEither.left(ClientException(
+            statusCode: HttpStatus.badRequest,
+            message: errors.join(' '),
+          ));
+  }
+
+  ClientException _toClient(BusinessException failure) {
+    return ClientException(
+      statusCode: failure.statusCode,
+      message: failure.statusCode >= 500
+          ? 'Erro interno. Tente novamente.'
+          : failure.message,
+    );
+  }
+}

package/content/skills/dart-frog/examples/dto.dart

@@ -0,0 +1,41 @@
+// Caminho: lib/orders/adapter/dtos/order_dtos.dart (um DTO por arquivo em projetos reais)
+import '../../domain/models/order.dart';
+
+/// Entrada de criação de pedido.
+class CreateOrderRequest {
+  /// Cria a requisição com o [total] informado.
+  const CreateOrderRequest({required this.total});
+
+  /// Converte o JSON recebido; campos ausentes ou inválidos ficam `null`.
+  factory CreateOrderRequest.fromJson(Map<String, Object?> json) {
+    final total = json['total'];
+    return CreateOrderRequest(total: total is num ? total.toDouble() : null);
+  }
+
+  /// Valor total informado pelo cliente.
+  final double? total;
+
+  /// Retorna as mensagens de validação de formato; vazio quando válido.
+  List<String> validate() => [
+        if (total == null) 'O campo "total" é obrigatório e numérico.',
+      ];
+}
+
+/// Saída pública de um pedido.
+class OrderResponse {
+  /// Cria a resposta.
+  const OrderResponse({required this.id, required this.total});
+
+  /// Constrói a resposta a partir do modelo de domínio.
+  factory OrderResponse.fromDomain(Order order) =>
+      OrderResponse(id: order.id, total: order.total);
+
+  /// Identificador do pedido.
+  final String id;
+
+  /// Valor total do pedido.
+  final double total;
+
+  /// Serializa para JSON.
+  Map<String, Object?> toJson() => {'id': id, 'total': total};
+}

package/content/skills/dart-frog/examples/error_response.dart

@@ -0,0 +1,35 @@
+// Caminho: lib/common/http/error_response.dart
+import 'dart:io';
+
+import 'package:dart_frog/dart_frog.dart';
+
+import '../exception/exceptions.dart';
+
+/// Converte falhas das camadas no formato único de erro da API.
+abstract final class ErrorResponse {
+  /// Resposta para uma [ClientException].
+  static Response fromClient(ClientException failure) =>
+      _json(failure.statusCode, failure.message);
+
+  /// Resposta para uma [MiddlewareException].
+  static Response fromMiddleware(MiddlewareException failure) =>
+      _json(failure.statusCode, failure.message);
+
+  static Response _json(int statusCode, String message) {
+    return Response.json(
+      statusCode: statusCode,
+      body: {
+        'error': {'code': _codeFor(statusCode), 'message': message},
+      },
+    );
+  }
+
+  static String _codeFor(int statusCode) => switch (statusCode) {
+        HttpStatus.badRequest => 'bad_request',
+        HttpStatus.unauthorized => 'unauthorized',
+        HttpStatus.forbidden => 'forbidden',
+        HttpStatus.notFound => 'not_found',
+        HttpStatus.methodNotAllowed => 'method_not_allowed',
+        _ => statusCode >= 500 ? 'internal_error' : 'error',
+      };
+}

package/content/skills/dart-frog/examples/exceptions.dart

@@ -0,0 +1,60 @@
+// Caminho: lib/common/exception/exceptions.dart
+// Camadas de erro fixas do padrão DS9.
+
+/// Falha de regra de negócio ou de persistência (services e repositories).
+class BusinessException implements Exception {
+  /// Cria uma falha de negócio.
+  const BusinessException({
+    required this.domainName,
+    required this.statusCode,
+    required this.message,
+    required this.error,
+    required this.stackTrace,
+  });
+
+  /// Contexto de negócio onde a falha ocorreu (ex.: `order`).
+  final String domainName;
+
+  /// Código HTTP associado à falha.
+  final int statusCode;
+
+  /// Mensagem segura para o cliente.
+  final String message;
+
+  /// Causa original; nunca deve ser enviada ao cliente.
+  final Object error;
+
+  /// Stack trace original, usado apenas em log.
+  final StackTrace stackTrace;
+}
+
+/// Falha de entrada ou acesso, exposta pelo controller ao cliente.
+class ClientException implements Exception {
+  /// Cria uma falha de cliente.
+  const ClientException({required this.statusCode, required this.message});
+
+  /// Código HTTP da resposta.
+  final int statusCode;
+
+  /// Mensagem segura para o cliente.
+  final String message;
+}
+
+/// Falha ocorrida em um middleware (autenticação, autorização, rate limit).
+class MiddlewareException implements Exception {
+  /// Cria uma falha de middleware.
+  const MiddlewareException({
+    required this.statusCode,
+    required this.message,
+    this.stackTrace,
+  });
+
+  /// Código HTTP da resposta.
+  final int statusCode;
+
+  /// Mensagem segura para o cliente.
+  final String message;
+
+  /// Stack trace original, usado apenas em log.
+  final StackTrace? stackTrace;
+}

package/content/skills/dart-frog/examples/middleware_composition.dart

@@ -0,0 +1,34 @@
+// Caminho: routes/api/orders/_middleware.dart
+// Composição do contexto: ÚNICO lugar onde service/repository/controller são criados.
+import 'package:dart_frog/dart_frog.dart';
+import 'package:my_api/orders/adapter/controllers/order_controller.dart';
+import 'package:my_api/orders/adapter/repository/order_repository.dart';
+import 'package:my_api/orders/domain/ports/order_repository_port.dart';
+import 'package:my_api/orders/domain/services/order_service.dart';
+
+OrderRepositoryPort? _repository;
+OrderService? _service;
+OrderController? _controller;
+
+/// Provê o controller de pedidos para as rotas deste ramo.
+///
+/// Quem depende vem primeiro: controller → service → repository.
+/// O `OrderDataSource` é provido por um middleware acima (ex.: `routes/_middleware.dart`).
+Handler middleware(Handler handler) {
+  return handler
+      .use(
+        provider<OrderController>(
+          (context) => _controller ??= OrderController(context.read<OrderService>()),
+        ),
+      )
+      .use(
+        provider<OrderService>(
+          (context) => _service ??= OrderService(context.read<OrderRepositoryPort>()),
+        ),
+      )
+      .use(
+        provider<OrderRepositoryPort>(
+          (context) => _repository ??= OrderRepository(context.read<OrderDataSource>()),
+        ),
+      );
+}

package/content/skills/dart-frog/examples/model.dart

@@ -0,0 +1,20 @@
+// Caminho: lib/orders/domain/models/order.dart
+import 'package:equatable/equatable.dart';
+
+/// Pedido do domínio; não conhece HTTP, DTO nem persistência.
+class Order extends Equatable {
+  /// Cria um pedido.
+  const Order({required this.id, required this.ownerId, required this.total});
+
+  /// Identificador único do pedido.
+  final String id;
+
+  /// Identificador do usuário dono do pedido.
+  final String ownerId;
+
+  /// Valor total do pedido.
+  final double total;
+
+  @override
+  List<Object?> get props => [id, ownerId, total];
+}

package/content/skills/dart-frog/examples/port.dart

@@ -0,0 +1,17 @@
+// Caminho: lib/orders/domain/ports/order_repository_port.dart
+import 'package:fpdart/fpdart.dart';
+
+import '../../../common/exception/exceptions.dart';
+import '../models/order.dart';
+
+/// Contrato de acesso a pedidos exigido pelo domínio.
+abstract interface class OrderRepositoryPort {
+  /// Busca o pedido [id]; o `Right` é `null` quando não existe.
+  TaskEither<BusinessException, Order?> findById(String id);
+
+  /// Persiste um novo pedido do usuário [ownerId] com o valor [total].
+  TaskEither<BusinessException, Order> create({
+    required String ownerId,
+    required double total,
+  });
+}

package/content/skills/dart-frog/examples/repository.dart

@@ -0,0 +1,56 @@
+// Caminho: lib/orders/adapter/repository/order_repository.dart
+// Agnóstico de persistência: o acesso real fica atrás de [OrderDataSource],
+// implementado conforme a skill de persistência do projeto.
+import 'dart:io';
+
+import 'package:fpdart/fpdart.dart';
+
+import '../../../common/exception/exceptions.dart';
+import '../../domain/models/order.dart';
+import '../../domain/ports/order_repository_port.dart';
+
+/// Fonte de dados de pedidos (adapter de infraestrutura).
+abstract interface class OrderDataSource {
+  /// Lê o pedido [id]; retorna `null` se não existir.
+  Future<Order?> read(String id);
+
+  /// Grava um pedido e retorna o registro criado.
+  Future<Order> insert({required String ownerId, required double total});
+}
+
+/// Implementa o port de pedidos sobre uma [OrderDataSource].
+class OrderRepository implements OrderRepositoryPort {
+  /// Cria o repository com a [_dataSource] injetada pelo middleware.
+  const OrderRepository(this._dataSource);
+
+  final OrderDataSource _dataSource;
+
+  @override
+  TaskEither<BusinessException, Order?> findById(String id) {
+    return TaskEither.tryCatch(
+      () => _dataSource.read(id),
+      (error, stackTrace) => _failure('Falha ao consultar o pedido.', error, stackTrace),
+    );
+  }
+
+  @override
+  TaskEither<BusinessException, Order> create({
+    required String ownerId,
+    required double total,
+  }) {
+    return TaskEither.tryCatch(
+      () => _dataSource.insert(ownerId: ownerId, total: total),
+      (error, stackTrace) => _failure('Falha ao criar o pedido.', error, stackTrace),
+    );
+  }
+
+  BusinessException _failure(String message, Object error, StackTrace stackTrace) {
+    return BusinessException(
+      domainName: 'order',
+      statusCode: HttpStatus.internalServerError,
+      message: message,
+      error: error,
+      stackTrace: stackTrace,
+    );
+  }
+}

package/content/skills/dart-frog/examples/route_collection.dart

@@ -0,0 +1,25 @@
+// Caminho: routes/api/orders/index.dart  ->  /api/orders
+// Rotas dentro de routes/ importam via `package:` (fora de lib/ não há import relativo).
+import 'dart:io';
+
+import 'package:dart_frog/dart_frog.dart';
+import 'package:my_api/common/http/error_response.dart';
+import 'package:my_api/common/middleware/auth_middleware.dart';
+import 'package:my_api/orders/adapter/controllers/order_controller.dart';
+
+/// Despacha o método HTTP; sem regra de negócio nem dependências instanciadas.
+Future<Response> onRequest(RequestContext context) async {
+  final controller = context.read<OrderController>();
+  final user = context.read<AuthenticatedUser>();
+
+  switch (context.request.method) {
+    case HttpMethod.post:
+      final result = await controller.create(context, user.id).run();
+      return result.match(
+        ErrorResponse.fromClient,
+        (order) => Response.json(statusCode: HttpStatus.created, body: order.toJson()),
+      );
+    case _:
+      return Response(statusCode: HttpStatus.methodNotAllowed);
+  }
+}

package/content/skills/dart-frog/examples/route_item.dart

@@ -0,0 +1,24 @@
+// Caminho: routes/api/orders/[id].dart  ->  /api/orders/:id
+import 'dart:io';
+
+import 'package:dart_frog/dart_frog.dart';
+import 'package:my_api/common/http/error_response.dart';
+import 'package:my_api/common/middleware/auth_middleware.dart';
+import 'package:my_api/orders/adapter/controllers/order_controller.dart';
+
+/// O parâmetro de caminho chega como argumento posicional [id].
+Future<Response> onRequest(RequestContext context, String id) async {
+  final controller = context.read<OrderController>();
+  final user = context.read<AuthenticatedUser>();
+
+  switch (context.request.method) {
+    case HttpMethod.get:
+      final result = await controller.getById(id, user.id).run();
+      return result.match(
+        ErrorResponse.fromClient,
+        (order) => Response.json(body: order.toJson()),
+      );
+    case _:
+      return Response(statusCode: HttpStatus.methodNotAllowed);
+  }
+}

package/content/skills/dart-frog/examples/route_test.dart

@@ -0,0 +1,33 @@
+// Caminho: test/routes/api/orders/index_test.dart
+// Rota testada como função, com RequestContext mockado; sempre cobre o 405.
+import 'dart:io';
+
+import 'package:dart_frog/dart_frog.dart';
+import 'package:mocktail/mocktail.dart';
+import 'package:test/test.dart';
+
+import '../../../../routes/api/orders/index.dart' as route;
+import 'package:my_api/common/middleware/auth_middleware.dart';
+import 'package:my_api/orders/adapter/controllers/order_controller.dart';
+
+class _MockRequestContext extends Mock implements RequestContext {}
+
+class _MockOrderController extends Mock implements OrderController {}
+
+void main() {
+  late _MockRequestContext context;
+
+  setUp(() {
+    context = _MockRequestContext();
+    when(() => context.read<OrderController>()).thenReturn(_MockOrderController());
+    when(() => context.read<AuthenticatedUser>()).thenReturn(const AuthenticatedUser(id: 'u1'));
+  });
+
+  test('retorna 405 para método não suportado', () async {
+    when(() => context.request).thenReturn(Request.delete(Uri.parse('http://localhost/api/orders')));
+
+    final response = await route.onRequest(context);
+
+    expect(response.statusCode, equals(HttpStatus.methodNotAllowed));
+  });
+}

package/content/skills/dart-frog/examples/service.dart

@@ -0,0 +1,51 @@
+// Caminho: lib/orders/domain/services/order_service.dart
+import 'dart:io';
+
+import 'package:fpdart/fpdart.dart';
+
+import '../../../common/exception/exceptions.dart';
+import '../models/order.dart';
+import '../ports/order_repository_port.dart';
+
+/// Regras de negócio de pedidos.
+class OrderService {
+  /// Cria o serviço com o [_repository] injetado pelo middleware.
+  const OrderService(this._repository);
+
+  final OrderRepositoryPort _repository;
+
+  /// Busca o pedido [id] e garante que pertence a [requesterId].
+  TaskEither<BusinessException, Order> getOwnedById({
+    required String id,
+    required String requesterId,
+  }) {
+    return _repository.findById(id).flatMap((order) {
+      if (order == null) return TaskEither.left(_failure(HttpStatus.notFound, 'Pedido não encontrado.'));
+      if (order.ownerId != requesterId) {
+        return TaskEither.left(_failure(HttpStatus.forbidden, 'Acesso negado.'));
+      }
+      return TaskEither.right(order);
+    });
+  }
+
+  /// Cria um pedido para [ownerId]; rejeita [total] não positivo.
+  TaskEither<BusinessException, Order> create({
+    required String ownerId,
+    required double total,
+  }) {
+    if (total <= 0) {
+      return TaskEither.left(_failure(HttpStatus.badRequest, 'O total deve ser positivo.'));
+    }
+    return _repository.create(ownerId: ownerId, total: total);
+  }
+
+  BusinessException _failure(int statusCode, String message) {
+    return BusinessException(
+      domainName: 'order',
+      statusCode: statusCode,
+      message: message,
+      error: message,
+      stackTrace: StackTrace.current,
+    );
+  }
+}

package/content/skills/dart-frog/examples/service_test.dart

@@ -0,0 +1,55 @@
+// Caminho: test/orders/domain/services/order_service_test.dart
+// Service testado com fake do port, sem banco real.
+import 'dart:io';
+
+import 'package:fpdart/fpdart.dart';
+import 'package:test/test.dart';
+
+import 'package:my_api/common/exception/exceptions.dart';
+import 'package:my_api/orders/domain/models/order.dart';
+import 'package:my_api/orders/domain/ports/order_repository_port.dart';
+import 'package:my_api/orders/domain/services/order_service.dart';
+
+class _FakeRepository implements OrderRepositoryPort {
+  _FakeRepository(this.stored);
+
+  final Order? stored;
+
+  @override
+  TaskEither<BusinessException, Order?> findById(String id) => TaskEither.right(stored);
+
+  @override
+  TaskEither<BusinessException, Order> create({
+    required String ownerId,
+    required double total,
+  }) =>
+      TaskEither.right(Order(id: '1', ownerId: ownerId, total: total));
+}
+
+void main() {
+  group('OrderService.getOwnedById', () {
+    test('retorna Left 404 quando o pedido não existe', () async {
+      final service = OrderService(_FakeRepository(null));
+
+      final result = await service.getOwnedById(id: '1', requesterId: 'u1').run();
+
+      expect(result.getLeft().toNullable()?.statusCode, HttpStatus.notFound);
+    });
+
+    test('retorna Left 403 quando o pedido é de outro usuário', () async {
+      final service = OrderService(_FakeRepository(const Order(id: '1', ownerId: 'u2', total: 5)));
+
+      final result = await service.getOwnedById(id: '1', requesterId: 'u1').run();
+
+      expect(result.getLeft().toNullable()?.statusCode, HttpStatus.forbidden);
+    });
+
+    test('retorna Right quando o pedido pertence ao usuário', () async {
+      final service = OrderService(_FakeRepository(const Order(id: '1', ownerId: 'u1', total: 5)));
+
+      final result = await service.getOwnedById(id: '1', requesterId: 'u1').run();
+
+      expect(result.isRight(), isTrue);
+    });
+  });
+}

package/content/skills/dart-frog/references/checklist.md

@@ -0,0 +1,31 @@
+# Dart Frog — Checklist de review detalhado
+
+## Pré-requisitos
+- [ ] `dart_frog` e `fpdart` presentes no `pubspec.yaml` (senão, o usuário foi informado e autorizou a instalação).
+- [ ] Estrutura existente preservada; padrão aplicado ao código novo.
+
+## Inegociáveis
+- [ ] Contratos de port/service/repository/controller retornam `TaskEither`.
+- [ ] Operações que podem lançar usam `TaskEither.tryCatch`.
+- [ ] Toda rota termina o `switch` com `case _` → 405.
+- [ ] Dependências compostas só em `_middleware.dart` (`provider`/`context.read`).
+- [ ] `BusinessException`, `ClientException`, `MiddlewareException` nas camadas certas.
+- [ ] Domínio agnóstico de persistência (só ports).
+
+## Camadas
+- [ ] Rota fina; só a rota executa `.run()`.
+- [ ] Controller não acessa persistência nem tem regra de negócio.
+- [ ] Service sem HTTP, `RequestContext` ou SDK.
+- [ ] Repository sem regra de negócio; falhas convertidas em `BusinessException`.
+- [ ] Autorização de recurso no service, não no middleware.
+
+## Erros e segurança
+- [ ] Sem stack trace, SQL, `error` original ou mensagem de SDK na resposta.
+- [ ] Formato `{error:{code,message}}` único.
+- [ ] Segredos no ambiente; nada sensível em logs.
+- [ ] Papel/perfil do cliente nunca confiado sem validação no servidor.
+
+## Qualidade
+- [ ] Skill `dart` seguida (`///` nas declarações públicas, nomenclatura, OOP).
+- [ ] Arquivos gerados regenerados e não editados à mão.
+- [ ] Testes: service, controller, rota (com 405).

package/content/skills/dart-frog/references/error-handling.md

@@ -0,0 +1,48 @@
+# Dart Frog — Erros (referência)
+
+Complementa a seção 5 do `SKILL.md`. Exemplos: `examples/exceptions.dart`, `error_response.dart`.
+
+## Camadas fixas
+
+| Exceção | Quem lança (`Left`) | Campos |
+|---|---|---|
+| `BusinessException` | service, repository | `domainName`, `statusCode`, `message`, `error`, `stackTrace` |
+| `ClientException` | controller | `statusCode`, `message` |
+| `MiddlewareException` | middleware | `statusCode`, `message`, `stackTrace?` |
+
+- `message` é **sempre** segura para o cliente. `error` e `stackTrace` são só para log.
+- Ao converter entre camadas, preserve o `statusCode`. Para `5xx`, a mensagem ao cliente é genérica.
+- Não use `Exception` genérica como falha de `TaskEither`.
+
+## Status HTTP
+
+| Situação | Status |
+|---|---|
+| Entrada inválida, body malformado | 400 |
+| Não autenticado ou credencial inválida | 401 |
+| Autenticado sem permissão (ex.: recurso de outro usuário) | 403 |
+| Recurso inexistente | 404 |
+| Método não suportado | 405 |
+| Conflito de estado | 409 |
+| Falha interna ou de persistência | 500 |
+| Criação com sucesso | 201 |
+
+## Formato único
+
+```json
+{ "error": { "code": "not_found", "message": "Pedido não encontrado." } }
+```
+
+## Nunca
+
+- Enviar stack trace, SQL, causa original (`error`), caminhos, credenciais ou mensagens de SDK.
+- Devolver `f.error.toString()` ao cliente.
+- Capturar erro e responder sucesso vazio.
+- Logar tokens, documentos, e-mail, telefone ou conteúdo sensível completo.
+
+## Onde cada falha nasce
+
+- Formato de body/query/params: controller/DTO (`400`).
+- Regra de negócio e autorização de recurso: service (`403`/`404`/`409`).
+- Persistência ou integração: repository (`500`, com `error` original preservado).
+- Autenticação e rate limit: middleware (`401`/`429`).

package/content/skills/dart-frog/references/fpdart-taskeither.md

@@ -0,0 +1,53 @@
+# Dart Frog — `fpdart` e `TaskEither` (referência)
+
+Complementa a seção 4 do `SKILL.md`. Exemplos: `examples/repository.dart`, `service.dart`, `controller.dart`.
+
+## Pré-requisito: `fpdart` instalado
+
+1. Procure `fpdart` em `dependencies` no `pubspec.yaml`.
+2. Se não estiver, **informe que ele é obrigatório para seguir o padrão DS9** e peça autorização para instalar: `dart pub add fpdart`.
+3. Não gere código fora do padrão para contornar a ausência.
+
+## Regras
+
+- Todo contrato de camada que pode falhar retorna `TaskEither<Falha, T>`: `BusinessException` (port/service/repository), `ClientException` (controller).
+- Operação assíncrona que pode lançar vai dentro de `TaskEither.tryCatch(run, onError)`; `onError` converte a causa (`error`, `stackTrace`) na exceção da camada, sem perder a causa original.
+- Composição com `map`, `flatMap` e `mapLeft`. Regra violada: `TaskEither.left(...)`; sucesso: `TaskEither.right(...)`.
+- **Só a rota executa** (`.run()`), e usa `match` para produzir a `Response`.
+- Funções puras e sem I/O (validações locais, construtores, `toJson`) podem retornar valores comuns, ou `Either` quando houver falha de validação.
+- Proibido: `throw` que escape da camada, `catch (_)` amplo, `Exception` genérica como falha, falha convertida em sucesso vazio.
+
+## Padrões
+
+```dart
+// 1) Acesso externo (repository)
+TaskEither<BusinessException, Order?> findById(String id) => TaskEither.tryCatch(
+      () => _dataSource.read(id),
+      (error, stackTrace) => BusinessException(
+        domainName: 'order',
+        statusCode: HttpStatus.internalServerError,
+        message: 'Falha ao consultar o pedido.',
+        error: error,
+        stackTrace: stackTrace,
+      ),
+    );
+
+// 2) Regra de negócio (service)
+_repository.findById(id).flatMap(
+      (order) => order == null ? TaskEither.left(_notFound(id)) : TaskEither.right(order),
+    );
+
+// 3) Troca de camada de erro (controller)
+_service.getOwnedById(id: id, requesterId: userId).mapLeft(_toClient).map(OrderResponse.fromDomain);
+
+// 4) Execução (rota)
+final result = await controller.getById(id, user.id).run();
+return result.match(ErrorResponse.fromClient, (order) => Response.json(body: order.toJson()));
+```
+
+## Cuidados
+
+- Mantenha as cadeias legíveis: se passar de 3 ou 4 etapas, extraia métodos privados nomeados.
+- Não misture `Future` simples e `TaskEither` no mesmo contrato.
+- Teste `Left` e `Right` explicitamente (`result.isLeft()`, `result.getLeft()`, `result.getRight()`).
+- Esta é a exceção funcional aceita pela skill `dart`: vale só para os contratos entre camadas. O restante continua orientado a objetos.