# FightRate Development Workflow ## Objetivo Este documento define o padrão de desenvolvimento do FightRate com apoio de IA. O objetivo é evoluir o app com qualidade, reduzir retrabalho, evitar código morto e reaproveitar o que já existe antes de criar novas estruturas. ## Princípio central > Antes de criar algo novo, procure e avalie o que já existe. A IA deve atuar como engenheira disciplinada: entender o problema, auditar o código existente, propor uma solução pequena, implementar em fatias, verificar e revisar. ## Níveis de mudança ### Nível 1 — Ajuste pequeno Use para copy, espaçamento, correção simples ou bug isolado. Fluxo: 1. Mini-spec de 2 a 5 linhas. 2. Editar o menor trecho possível. 3. Compilar ou rodar teste relacionado. 4. Responder com evidência. ### Nível 2 — Feature média Use para melhorias em uma tela, novo comportamento de domínio, persistência pequena ou ajustes de BLE sem mudança arquitetural. Fluxo: 1. Spec curta. 2. Auditoria do existente. 3. Plano em fatias. 4. Teste de domínio quando houver regra de negócio. 5. Implementação incremental. 6. Build/test final. 7. Revisão de código e UI. ### Nível 3 — Feature grande Use para novos fluxos de treino, histórico avançado, dashboards, mudanças de banco importantes, BLE/background tracking ou nova tela grande. Fluxo: 1. Spec completa. 2. Aprovação humana. 3. Plano técnico. 4. Tarefas pequenas com acceptance/verify. 5. Implementação uma tarefa por vez. 6. Revisão final e atualização do roadmap. ## Intake obrigatório Antes de implementar, responder: ```text O que vamos melhorar? Qual problema real isso resolve? Em qual tela/fluxo? Como saberemos que ficou bom? ``` Quando o pedido for vago, converter para critérios testáveis. Exemplo: ```text Pedido: melhorar alertas. Critérios: - usuário configura limite cardíaco; - alerta não dispara sem controle; - vibração/som são opcionais; - UI em PT-BR; - build final passa. ``` ## Auditoria do existente Antes de criar arquivo, classe, componente ou dependência, verificar: ```text Já existe domínio parecido? Já existe state no ViewModel? Já existe componente visual reutilizável? Já existe persistência parecida? Já existe teste relacionado? ``` Pontos comuns de reaproveitamento: ```text HeartRateSampleStore LiveHeartRateViewModel LiveHeartRateUiState HeartRateZones HeartRateForegroundService HomeScreen FightCard MetricTile LiveMetricPill ``` Regra: > Se a IA não consegue explicar por que um arquivo novo precisa existir, ela não deve criar esse arquivo. ## Arquitetura esperada ### Domínio Use `domain/` para regra pura e testável sem Android. Exemplos: ```text RoundTimer.kt HeartRateZones.kt WorkoutSession.kt HeartRateAlertSettings.kt ``` ### Dados Use `data/` para persistência, exportação e acesso local. ```text HeartRateSampleStore.kt HeartRateExporter.kt ``` SQLite local-first continua sendo a fonte de verdade. ### BLE / Android Use `ble/`, `service/` e `system/` para integração Android. Regra importante: > A conexão BLE pertence ao `HeartRateForegroundService`, não ao ViewModel. ### UI Use `ui/screens/`, `ui/live/` e `ui/theme/`. A UI deve consumir estado pronto e não concentrar regra de negócio pesada. ## Padrão de fatias Implementar em fatias pequenas: ```text Fatia 1 — domínio puro Fatia 2 — persistência Fatia 3 — ViewModel/state Fatia 4 — UI Fatia 5 — integração Android/BLE Fatia 6 — revisão ``` Cada fatia deve declarar: ```text Acceptance: o que precisa funcionar. Verify: comando ou checagem que comprova. ``` ## TDD obrigatório quando houver regra Escrever teste antes ou junto para: ```text parser BLE zonas cardíacas timer de rounds resumo de treino alertas janelas temporais estatísticas migração/persistência crítica ``` UI simples não exige TDD pesado, mas exige build e revisão visual/UX. ## Quality gates Antes de concluir qualquer mudança média/grande: ```bash ./gradlew :app:testDebugUnitTest :app:assembleDebug ``` Para domínio específico: ```bash ./gradlew :app:testDebugUnitTest --tests "*NomeDoTeste" ``` Também verificar: ```text - UI visível em PT-BR; - identificadores de código em inglês; - sem código morto óbvio; - sem componente duplicado desnecessário; - sem Canvas custom frágil para gráfico/gauge; - sem dependência nova sem justificativa; - sem quebrar background BLE; - sem alterar minSdk 26 sem aprovação. ``` ## Sempre fazer - Reaproveitar componentes existentes. - Preservar SQLite como fonte local. - Escrever domínio puro para regra de negócio. - Testar domínio antes da UI quando aplicável. - Manter textos visíveis em PT-BR. - Manter código em inglês. - Rodar build final. - Atualizar roadmap/Obsidian quando mudar escopo relevante. ## Perguntar antes - Adicionar dependência nova. - Fazer mudança destrutiva no schema SQLite. - Criar tela grande nova. - Trocar biblioteca de gráfico/UI. - Alterar BLE service/background tracking. - Mudar minSdk, targetSdk, AGP, Kotlin ou Gradle. ## Nunca fazer - Criar gráfico/gauge em Canvas custom sem necessidade clara. - Remover teste falhando só para passar build. - Criar componente novo se um existente resolve. - Deixar código morto “para usar depois”. - Implementar feature sem critério de sucesso. - Alterar texto do app para inglês sem pedido. - Misturar refactor grande com feature. ## Checklist antes de implementar ```text [ ] Existe spec ou mini-spec? [ ] Critérios de sucesso são testáveis? [ ] Arquivos existentes foram auditados? [ ] Componentes reaproveitados foram listados? [ ] Novos arquivos têm responsabilidade clara? [ ] Fatia atual toca no máximo 3–5 arquivos principais? [ ] Há teste para regra de domínio? [ ] Há comando de verificação definido? ``` ## Checklist antes de responder “concluído” ```text [ ] Testes/build rodaram. [ ] Resultado foi registrado. [ ] APK foi localizado quando aplicável. [ ] Roadmap/Obsidian foi atualizado quando aplicável. [ ] Limitações foram declaradas. ``` ## Dependências aprovadas (histórico) Adicionar uma dependência nova continua exigindo aprovação explícita. Esta seção registra as que já passaram pelo gate, com a justificativa de produto: - `react-native-gesture-handler` (aprovado em 2026-06-14) — necessário para gestos nativos de pinch e pan no `TrainingChart` dinâmico (viewport com zoom, pan e tap). O `PanResponder` builtin não tem pinch de 2 dedos e perde precisão fora do viewBox. - `react-native-reanimated` (aprovado em 2026-06-14) — worklets para gestures performáticos em tempo real (atualização do viewport durante o pinch sem travar a thread JS). - `react-native-worklets` (aprovado em 2026-06-14) — peer dep de `react-native-reanimated` 4.x; runtime paralelo a JS. Todas as três exigem a New Architecture habilitada (`newArchEnabled=true` no `android/gradle.properties`) e setup específico: - `react-native-gesture-handler` importado no topo de `index.js` antes de qualquer outro React Native. - App envolto em `GestureHandlerRootView`. - Babel com `react-native-worklets/plugin`.