HealthTracking/docs/FIGHTRATE_DEVELOPMENT_WORKFLOW.md

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:

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:

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:

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:

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:

RoundTimer.kt
HeartRateZones.kt
WorkoutSession.kt
HeartRateAlertSettings.kt

Dados

Use data/ para persistência, exportação e acesso local.

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:

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:

Acceptance: o que precisa funcionar.
Verify: comando ou checagem que comprova.

TDD obrigatório quando houver regra

Escrever teste antes ou junto para:

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:

./gradlew :app:testDebugUnitTest :app:assembleDebug

Para domínio específico:

./gradlew :app:testDebugUnitTest --tests "*NomeDoTeste"

Também verificar:

- 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

[ ] 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”

[ ] 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.