@the-bearded-bear/claude-craft 3.0.0

package/Dev/i18n/pt/Flutter/rules/02-architecture.md

@@ -0,0 +1,455 @@
+# Arquitetura Flutter - Clean Architecture & Melhores Práticas
+
+## Princípio Central
+
+A arquitetura Flutter deve seguir os princípios de **Clean Architecture** popularizados por Robert C. Martin (Uncle Bob), adaptados ao contexto Flutter/Dart.
+
+**Objetivos**:
+- Separação de Responsabilidades
+- Máxima testabilidade
+- Independência de framework
+- Independência de UI
+- Independência de banco de dados
+- Manutenibilidade e escalabilidade
+
+---
+
+## Visão Geral: Clean Architecture
+
+### As 3 Camadas Principais
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                   PRESENTATION                          │
+│  (UI, Gerenciamento de Estado, Navegação)              │
+│                                                         │
+│  - Pages (Telas)                                        │
+│  - Widgets                                              │
+│  - BLoC / Riverpod / Provider                          │
+│  - View Models                                          │
+│                                                         │
+│  Depende de: DOMAIN                                     │
+└─────────────────────────────────────────────────────────┘
+                         ↓
+┌─────────────────────────────────────────────────────────┐
+│                      DOMAIN                             │
+│  (Lógica de Negócio, Entidades, Casos de Uso)          │
+│                                                         │
+│  - Entities (modelos puros de negócio)                 │
+│  - Use Cases (lógica de negócio)                       │
+│  - Interfaces de Repository                            │
+│                                                         │
+│  Depende de NADA (camada mais pura)                    │
+└─────────────────────────────────────────────────────────┘
+                         ↑
+┌─────────────────────────────────────────────────────────┐
+│                       DATA                              │
+│  (Fontes de Dados, Repositories, Models)               │
+│                                                         │
+│  - Models (serialização)                               │
+│  - Data Sources (Remote, Local)                        │
+│  - Implementações de Repository                        │
+│                                                         │
+│  Depende de: DOMAIN (implementa interfaces)            │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Regra de Dependência
+
+**CRUCIAL**: As dependências devem sempre apontar para dentro.
+
+```
+PRESENTATION → DOMAIN ← DATA
+     ↓                    ↑
+  Depende de          Depende de
+```
+
+---
+
+## Estrutura Completa de Pastas
+
+### Organização Recomendada
+
+```
+lib/
+├── core/                           # Funcionalidades compartilhadas
+│   ├── constants/                  # Constantes globais
+│   │   ├── api_constants.dart
+│   │   ├── app_constants.dart
+│   │   └── storage_constants.dart
+│   │
+│   ├── errors/                     # Tratamento de erros
+│   │   ├── exceptions.dart
+│   │   └── failures.dart
+│   │
+│   ├── extensions/                 # Extensões Dart
+│   │   ├── build_context_extension.dart
+│   │   ├── date_time_extension.dart
+│   │   └── string_extension.dart
+│   │
+│   ├── network/                    # Configuração de rede
+│   │   ├── api_client.dart
+│   │   ├── network_info.dart
+│   │   └── interceptors/
+│   │       ├── auth_interceptor.dart
+│   │       └── logging_interceptor.dart
+│   │
+│   ├── theme/                      # Tema do app
+│   │   ├── app_theme.dart
+│   │   ├── colors.dart
+│   │   ├── text_styles.dart
+│   │   └── dimensions.dart
+│   │
+│   ├── utils/                      # Utilitários
+│   │   ├── validators.dart
+│   │   ├── formatters.dart
+│   │   └── helpers.dart
+│   │
+│   └── widgets/                    # Widgets reutilizáveis
+│       ├── app_button.dart
+│       ├── app_text_field.dart
+│       ├── loading_indicator.dart
+│       └── error_widget.dart
+│
+├── features/                       # Funcionalidades de negócio
+│   │
+│   ├── authentication/             # Feature: Autenticação
+│   │   ├── data/
+│   │   │   ├── datasources/
+│   │   │   │   ├── auth_local_datasource.dart
+│   │   │   │   └── auth_remote_datasource.dart
+│   │   │   ├── models/
+│   │   │   │   ├── login_request_model.dart
+│   │   │   │   ├── login_response_model.dart
+│   │   │   │   └── user_model.dart
+│   │   │   └── repositories/
+│   │   │       └── auth_repository_impl.dart
+│   │   │
+│   │   ├── domain/
+│   │   │   ├── entities/
+│   │   │   │   └── user.dart
+│   │   │   ├── repositories/
+│   │   │   │   └── auth_repository.dart
+│   │   │   └── usecases/
+│   │   │       ├── login.dart
+│   │   │       ├── logout.dart
+│   │   │       ├── register.dart
+│   │   │       └── get_current_user.dart
+│   │   │
+│   │   └── presentation/
+│   │       ├── bloc/
+│   │       │   ├── auth_bloc.dart
+│   │       │   ├── auth_event.dart
+│   │       │   └── auth_state.dart
+│   │       ├── pages/
+│   │       │   ├── login_page.dart
+│   │       │   └── register_page.dart
+│   │       └── widgets/
+│   │           ├── login_form.dart
+│   │           └── social_login_buttons.dart
+│   │
+│   ├── products/                   # Feature: Produtos
+│   │   ├── data/
+│   │   │   ├── datasources/
+│   │   │   │   ├── product_local_datasource.dart
+│   │   │   │   └── product_remote_datasource.dart
+│   │   │   ├── models/
+│   │   │   │   └── product_model.dart
+│   │   │   └── repositories/
+│   │   │       └── product_repository_impl.dart
+│   │   │
+│   │   ├── domain/
+│   │   │   ├── entities/
+│   │   │   │   └── product.dart
+│   │   │   ├── repositories/
+│   │   │   │   └── product_repository.dart
+│   │   │   └── usecases/
+│   │   │       ├── get_products.dart
+│   │   │       ├── get_product_detail.dart
+│   │   │       └── search_products.dart
+│   │   │
+│   │   └── presentation/
+│   │       ├── bloc/
+│   │       │   ├── product_list/
+│   │       │   │   ├── product_list_bloc.dart
+│   │       │   │   ├── product_list_event.dart
+│   │       │   │   └── product_list_state.dart
+│   │       │   └── product_detail/
+│   │       │       ├── product_detail_bloc.dart
+│   │       │       ├── product_detail_event.dart
+│   │       │       └── product_detail_state.dart
+│   │       ├── pages/
+│   │       │   ├── product_list_page.dart
+│   │       │   └── product_detail_page.dart
+│   │       └── widgets/
+│   │           ├── product_card.dart
+│   │           ├── product_grid.dart
+│   │           └── product_search_bar.dart
+│   │
+│   └── [other_features]/          # Outras features...
+│
+├── config/                         # Configuração
+│   ├── routes/
+│   │   ├── app_router.dart
+│   │   └── route_names.dart
+│   └── env/
+│       ├── env.dart
+│       └── env_config.dart
+│
+├── dependency_injection.dart       # Configuração de DI (get_it/injectable)
+└── main.dart                       # Ponto de entrada
+```
+
+---
+
+## Camada DOMAIN: O Núcleo do Negócio
+
+### 1. Entities
+
+**Papel**: Objetos puros de negócio, sem lógica de persistência ou apresentação.
+
+**Características**:
+- Imutáveis (prefira `@immutable` ou `@freezed`)
+- Sem dependências externas
+- Sem anotações JSON
+- Igualdade baseada em conteúdo (use `Equatable`)
+
+```dart
+// lib/features/products/domain/entities/product.dart
+
+import 'package:equatable/equatable.dart';
+
+/// Representa um produto no domínio de negócio.
+///
+/// Esta classe é uma entidade pura sem dependências externas.
+class Product extends Equatable {
+  /// Identificador único do produto
+  final String id;
+
+  /// Nome do produto
+  final String name;
+
+  /// Descrição detalhada
+  final String description;
+
+  /// Preço em centavos (evita problemas com float)
+  final int priceInCents;
+
+  /// URL da imagem principal
+  final String imageUrl;
+
+  /// Categoria do produto
+  final String category;
+
+  /// Estoque disponível
+  final int stock;
+
+  /// Data de criação
+  final DateTime createdAt;
+
+  const Product({
+    required this.id,
+    required this.name,
+    required this.description,
+    required this.priceInCents,
+    required this.imageUrl,
+    required this.category,
+    required this.stock,
+    required this.createdAt,
+  });
+
+  /// Retorna o preço formatado em euros
+  String get formattedPrice {
+    final euros = priceInCents / 100;
+    return '${euros.toStringAsFixed(2)} €';
+  }
+
+  /// Indica se o produto está em estoque
+  bool get isInStock => stock > 0;
+
+  /// Indica se o estoque está baixo (< 10)
+  bool get isLowStock => stock > 0 && stock < 10;
+
+  @override
+  List<Object?> get props => [
+        id,
+        name,
+        description,
+        priceInCents,
+        imageUrl,
+        category,
+        stock,
+        createdAt,
+      ];
+}
+```
+
+**Alternativa com Freezed** (recomendado para menos boilerplate):
+
+```dart
+// lib/features/products/domain/entities/product.dart
+
+import 'package:freezed_annotation/freezed_annotation.dart';
+
+part 'product.freezed.dart';
+
+@freezed
+class Product with _$Product {
+  const Product._(); // Construtor privado para métodos customizados
+
+  const factory Product({
+    required String id,
+    required String name,
+    required String description,
+    required int priceInCents,
+    required String imageUrl,
+    required String category,
+    required int stock,
+    required DateTime createdAt,
+  }) = _Product;
+
+  // Getters customizados
+  String get formattedPrice {
+    final euros = priceInCents / 100;
+    return '${euros.toStringAsFixed(2)} €';
+  }
+
+  bool get isInStock => stock > 0;
+  bool get isLowStock => stock > 0 && stock < 10;
+}
+```
+
+### 2. Interfaces de Repository
+
+**Papel**: Contratos definindo como acessar dados, sem implementação.
+
+**Características**:
+- Classe abstrata ou interface pura
+- Retorna `Either<Failure, Success>` (com dartz) ou `Result<T>`
+- Assíncrono com `Future`
+- Nomenclatura: `[Entity]Repository`
+
+```dart
+// lib/features/products/domain/repositories/product_repository.dart
+
+import 'package:dartz/dartz.dart';
+import '../../../../core/errors/failures.dart';
+import '../entities/product.dart';
+
+/// Interface para acessar dados de produtos.
+///
+/// Esta interface define o contrato que qualquer
+/// implementação concreta do repositório de produtos deve respeitar.
+abstract class ProductRepository {
+  /// Recupera a lista de todos os produtos.
+  ///
+  /// Retorna [Right<List<Product>>] em caso de sucesso,
+  /// ou [Left<Failure>] em caso de erro.
+  Future<Either<Failure, List<Product>>> getProducts({
+    int page = 1,
+    int limit = 20,
+  });
+
+  /// Recupera um produto pelo seu ID.
+  ///
+  /// Retorna [Right<Product>] se o produto existir,
+  /// ou [Left<Failure>] se não encontrado ou erro.
+  Future<Either<Failure, Product>> getProductById(String id);
+
+  /// Busca produtos por nome ou descrição.
+  ///
+  /// [query]: Termo de busca
+  /// [category]: Filtro opcional de categoria
+  Future<Either<Failure, List<Product>>> searchProducts({
+    required String query,
+    String? category,
+  });
+
+  /// Recupera produtos de uma categoria específica.
+  Future<Either<Failure, List<Product>>> getProductsByCategory(
+    String category, {
+    int page = 1,
+    int limit = 20,
+  });
+}
+```
+
+**Alternativa com Result<T>** (sem dartz):
+
+```dart
+// lib/core/utils/result.dart
+@freezed
+class Result<T> with _$Result<T> {
+  const factory Result.success(T data) = Success<T>;
+  const factory Result.failure(String error) = Failure<T>;
+}
+
+// Uso no repository
+abstract class ProductRepository {
+  Future<Result<List<Product>>> getProducts({
+    int page = 1,
+    int limit = 20,
+  });
+
+  Future<Result<Product>> getProductById(String id);
+}
+```
+
+### 3. Use Cases
+
+**Papel**: Encapsular lógica de negócio para uma ação específica.
+
+**Princípio**: Um Use Case = Uma ação de negócio
+
+**Características**:
+- Único método público: `call()`
+- Recebe repository via injeção de dependência
+- Contém validações e regras de negócio
+- Nomenclatura: Verbo no infinitivo (GetProducts, CreateOrder, etc.)
+
+```dart
+// lib/features/products/domain/usecases/get_products.dart
+
+import 'package:dartz/dartz.dart';
+import '../../../../core/errors/failures.dart';
+import '../entities/product.dart';
+import '../repositories/product_repository.dart';
+
+/// Recupera a lista paginada de produtos.
+///
+/// Este use case gerencia a lógica de negócio para recuperar produtos,
+/// incluindo validação de parâmetros.
+class GetProducts {
+  final ProductRepository repository;
+
+  GetProducts(this.repository);
+
+  /// Executa o use case.
+  ///
+  /// [page]: Número da página (começa em 1)
+  /// [limit]: Número de itens por página (máx 100)
+  ///
+  /// Retorna [Right<List<Product>>] em caso de sucesso,
+  /// ou [Left<Failure>] em caso de erro.
+  Future<Either<Failure, List<Product>>> call({
+    int page = 1,
+    int limit = 20,
+  }) async {
+    // Validação de parâmetros de negócio
+    if (page < 1) {
+      return const Left(ValidationFailure('Página deve ser >= 1'));
+    }
+
+    if (limit < 1 || limit > 100) {
+      return const Left(ValidationFailure('Limite deve estar entre 1 e 100'));
+    }
+
+    // Delegação ao repository
+    return await repository.getProducts(page: page, limit: limit);
+  }
+}
+```
+
+---
+
+*Esta arquitetura garante separação clara de responsabilidades, facilita testes e permite evolução progressiva do código.*

package/Dev/i18n/pt/Flutter/rules/03-coding-standards.md

@@ -0,0 +1,247 @@
+# Padrões de Codificação Flutter/Dart
+
+## Princípio Central
+
+Siga o **Effective Dart**: o guia oficial para estilo e melhores práticas em Dart.
+
+Referências:
+- [Effective Dart: Style](https://dart.dev/guides/language/effective-dart/style)
+- [Effective Dart: Documentation](https://dart.dev/guides/language/effective-dart/documentation)
+- [Effective Dart: Usage](https://dart.dev/guides/language/effective-dart/usage)
+- [Effective Dart: Design](https://dart.dev/guides/language/effective-dart/design)
+
+---
+
+## Convenções de Nomenclatura
+
+### 1. Arquivos e Pastas
+
+**Regra**: `snake_case` para todos os arquivos e pastas.
+
+```
+✅ BOM
+lib/features/user_profile/presentation/pages/edit_profile_page.dart
+lib/core/utils/string_validators.dart
+test/features/authentication/auth_bloc_test.dart
+
+❌ RUIM
+lib/features/UserProfile/presentation/pages/EditProfilePage.dart
+lib/core/utils/StringValidators.dart
+test/features/authentication/authBlocTest.dart
+```
+
+**Exceções**:
+- README.md, CHANGELOG.md (convenções Markdown)
+- Makefile, Dockerfile (convenções Unix)
+
+### 2. Classes, Enums, Typedefs, Extensions
+
+**Regra**: `UpperCamelCase` (PascalCase)
+
+```dart
+✅ BOM
+class UserProfile {}
+class HttpClient {}
+enum OrderStatus { pending, confirmed, shipped }
+typedef ValidationCallback = bool Function(String);
+extension StringExtension on String {}
+mixin NetworkMixin {}
+
+❌ RUIM
+class userProfile {}
+class HTTPClient {}  // A menos que seja um acrônimo padrão (HTTP, URL, ID)
+enum orderStatus {}
+typedef validationCallback = bool Function(String);
+```
+
+**Acrônimos**: Trate como palavras normais
+
+```dart
+✅ BOM
+class HttpRequest {}
+class ApiClient {}
+class DbHelper {}
+class IoUtils {}
+
+❌ RUIM
+class HTTPRequest {}
+class APIClient {}
+class DBHelper {}
+class IOUtils {}
+```
+
+### 3. Variáveis, Funções, Parâmetros
+
+**Regra**: `lowerCamelCase`
+
+```dart
+✅ BOM
+String userName;
+int itemCount;
+void calculateTotalPrice() {}
+final isAuthenticated = true;
+const maxRetryAttempts = 3;
+
+❌ RUIM
+String user_name;
+int ItemCount;
+void CalculateTotalPrice() {}
+final IsAuthenticated = true;
+const MAX_RETRY_ATTEMPTS = 3;
+```
+
+### 4. Constantes
+
+**Regra**: `lowerCamelCase` (sem SCREAMING_CASE)
+
+```dart
+✅ BOM
+const defaultTimeout = Duration(seconds: 30);
+const apiBaseUrl = 'https://api.example.com';
+const maxFileSize = 5 * 1024 * 1024; // 5 MB
+
+// Em uma classe
+class ApiConstants {
+  static const baseUrl = 'https://api.example.com';
+  static const timeout = Duration(seconds: 30);
+}
+
+❌ RUIM
+const DEFAULT_TIMEOUT = Duration(seconds: 30);
+const API_BASE_URL = 'https://api.example.com';
+const MAX_FILE_SIZE = 5 * 1024 * 1024;
+```
+
+### 5. Membros Privados
+
+**Regra**: Prefixo com underscore `_`
+
+```dart
+✅ BOM
+class MyClass {
+  String _privateField;
+
+  void _privateMethod() {}
+
+  String get _privateGetter => _privateField;
+}
+
+// Arquivos internos do pacote
+lib/src/_internal_helper.dart
+
+❌ RUIM
+class MyClass {
+  String privateField; // Não é privado!
+
+  void privateMethod() {} // Público!
+}
+```
+
+---
+
+## Formatação e Estilo
+
+### 1. Comprimento de Linha
+
+**Regra**: Máximo de 80 caracteres por linha.
+
+```dart
+✅ BOM
+final user = User(
+  id: '123',
+  name: 'John Doe',
+  email: 'john@example.com',
+  phoneNumber: '+33612345678',
+);
+
+❌ RUIM
+final user = User(id: '123', name: 'John Doe', email: 'john@example.com', phoneNumber: '+33612345678');
+```
+
+**Configuração**: `.editorconfig` ou configurações da IDE
+
+```
+[*.dart]
+max_line_length = 80
+```
+
+### 2. Indentação
+
+**Regra**: 2 espaços (SEM tabs).
+
+```dart
+✅ BOM
+class MyClass {
+  void myMethod() {
+    if (condition) {
+      doSomething();
+    }
+  }
+}
+
+❌ RUIM
+class MyClass {
+    void myMethod() {  // 4 espaços
+        if (condition) {
+            doSomething();
+        }
+    }
+}
+```
+
+### 3. Chaves
+
+**Regra**: Sempre use chaves, mesmo para linhas únicas.
+
+```dart
+✅ BOM
+if (condition) {
+  doSomething();
+}
+
+for (var item in items) {
+  print(item);
+}
+
+❌ RUIM
+if (condition)
+  doSomething();
+
+for (var item in items) print(item);
+```
+
+### 4. Vírgulas Finais
+
+**Regra**: Sempre adicione vírgula final para listas multi-linha.
+
+```dart
+✅ BOM
+final colors = [
+  Colors.red,
+  Colors.blue,
+  Colors.green,
+]; // Vírgula final → Dart formatter organiza automaticamente
+
+Widget build(BuildContext context) {
+  return Column(
+    children: [
+      Text('Line 1'),
+      Text('Line 2'),
+      Text('Line 3'),
+    ], // Vírgula final
+  );
+}
+
+❌ RUIM
+final colors = [
+  Colors.red,
+  Colors.blue,
+  Colors.green // Sem vírgula → formatter coloca tudo em uma linha
+];
+```
+
+**Por quê**: O Dart formatter usa vírgulas finais para decidir a formatação.
+
+---
+
+*Estes padrões garantem código Flutter consistente, legível e manutenível.*