277 lines
7.0 KiB
Markdown
277 lines
7.0 KiB
Markdown
# 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`.
|