Agracta — registros de ensaios de campo
PWA de pesquisa agrícola para ensaios de campo e de laboratório sob BPL: mapa de
satélite com as quadras georreferenciadas, estudos com protocolo vivo, aplicações
com memória de cálculo, avaliações, fotos, estatística no próprio aparelho,
trilha de auditoria e índices de vegetação NDVI / NDRE / GNDVI do Sentinel‑2.
Funciona offline e sincroniza pelo Firebase.
Rodar localmente
- Abrir o app: sirva a pasta (recomendado, habilita GPS/PWA) —
python3 -m http.server 8080 e acesse http://localhost:8080.
(Também abre com 2 cliques no index.html, mas aí GPS/instalação ficam bloqueados pelo navegador.)
- NDVI (opcional): rode o proxy do Sentinel‑2 —
python3 ndvi-proxy.py (na 1ª vez ele pede o Client ID/Secret do Copernicus e salva em ndvi-credenciais.json).
As camadas públicas Landsat, SMAP e NASA FIRMS ficam em
Mapa → Ferramentas do mapa → Satélite e usam esse mesmo proxy.
Não precisam de conta individual nem das credenciais do Sentinel.
Consulte SATELITES.md para dados, limites e publicação.
Onde mora cada coisa
Não há build: o site é servido do jeito que está no repositório, e cada arquivo
abaixo é baixado pelo aparelho como está.
A tela principal (index.html)
O index.html carrega as bibliotecas e a maior parte dos motores puros antes do
app.js; os módulos que se penduram nele vêm depois. A barra de baixo tem,
nesta ordem: Mapa, Conhecimento, Hoje, Agenda, Buscar e Menu.
| Área | Arquivos |
|---|
| Entrada, acesso e nuvem | acesso-horario.js (nada aparece antes do login; janela de horário por técnico) · firebase-config.js · firebase-sync.js (login, sincronização local-first, histórico de versões; a parte de nuvem do Painel Admin) |
| Coordenação da interface | app.js — quadras, estudos, aplicações, avaliações, Hoje e Agenda, cópias e recuperação, Painel Admin. É o arquivo grande (~25 mil linhas); dividi-lo por área é a frente 3 da lapidação |
| Mapa | ui-campo.js / ui-campo.css (gaveta de ferramentas, NDVI com faixa de datas, botões Mapa e Menu) · mapa-medir.js (grupos de parcelas provisórios) · mapa-inicio.js ("abrir o app em") · notas-local.js (onde cada nota foi lançada) · croqui-livre.js e croqui-parcelas.js (parcelas no mapa) |
| Satélites públicos | satelites.js / satelites.css (temperatura Landsat, umidade SMAP e focos de calor FIRMS) · vendor/satelites-core.js (área, datas, cena e distância dos focos às quadras) · satelites_backend.py (provedores públicos, chamado pelo proxy) — ver SATELITES.md |
| Embrapa (AgroAPI) | agroapi.js / agroapi.css (Bioinsumos e ZARC no Conhecimento, ClimAPI no clima) · vendor/agroapi-core.js · agroapi_backend.py (credencial da aplicação no servidor) — ver AGROAPI.md |
| Estudo e protocolo | protocolo-menu.js (o protocolo num lugar só) · protocolo-avaliacoes.js · aplicacoes-recolhiveis.js · calculadora-drone.js · campo-inteligente.js (clima e nota estranha na hora) · colonia-medida.js (colônia medida na foto) |
| Fotos e relatório | fotos-estudo.js · galeria-fotos.js · relatorio-estudo.js (abrem as páginas isoladas galeria-local.html e relatorio-local.html) |
| Trilha BPL | eventos-app.js (eventos formais ao lado da trilha de sempre) · trilha-formal.js (a trilha na ficha do estudo) |
| Conhecimento | integracoes.js (+ integracoes-fontes.js) · conhecimento-canonico.js (aba "Entre estudos") · estudo-pagina.js (página do estudo) · alvos-catalogo.js |
| Patrocinadores (Menu › Administração) | integracoes-clientes.js — que resultados cada patrocinador consulta; abre na mesma moldura do Conhecimento, sem as abas |
| Ver no campo (sob demanda) | campo-3d.js / campo-3d.css · campo-3d-exportar.js e campo-3d-realista.js (PNG e MP4). Não estão no index.html: entram no primeiro uso |
| Clima | clima-pagina.js / clima-pagina.css |
| Estatística | estatistica.js (núcleo em JS) · estatistica/ (motor em Python rodando no navegador pelo Pyodide, com service worker próprio; o código Python fica em estatistica/bioengine/) |
| iPhone | iphone.js (devolve a página ao lugar quando o iOS a deixa deslocada: teclado, girar no iOS 27) · o ajuste anti-zoom só do iOS fica no <head> do index.html, logo depois do viewport |
Páginas separadas
croqui.html (croqui das quadras para o relatório), prancha.html (prancha de
resultados), cliente.html + cliente.js (consulta do patrocinador, sem acesso ao
workspace), galeria-local.html + galeria-local.js (fotos das parcelas, só no
aparelho), relatorio-local.html + relatorio-local.js (relatório do estudo) e
probit.html + probit.js (análise probit da bancada: o botão Probit na ficha
do laboratório; motor em vendor/probit-core.js).
Motores puros e bibliotecas (vendor/)
- Motores do Agracta —
vendor/<nome>-core.js: as contas, sem DOM, testáveis
no Node. O app só pinta e grava; a regra mora no motor. Exemplos:
biocalc-campo-core.js (calda), biocalc-lab-core.js (bancada),
aplicacao-core.js, dose-core.js, avaliacao-core.js, agenda-core.js,
protocolo-vivo-core.js, versoes-core.js, mascara-core.js (cor das quadras
no mapa), croqui-campo-core.js, eventos-core.js, observacao-core.js,
probit-core.js (probit/logit como no PoloPlus, com autoteste contra o livro).
- Bibliotecas de terceiros — Leaflet e plugins, Three.js
(
three-agracta.min.js), Firebase (*-compat.js), SheetJS (xlsx.full.min.js),
JSZip e mp4-muxer.js.
vendor/quadras-default.js — reserva vazia para instalações novas; a geometria
operacional vem do armazenamento autenticado ou do próprio aparelho.
Visual
styles.css é a base (extraída do antigo index.html). Por cima dela, na ordem
do index.html: theme-2026.css (camada visual de campo), ui-campo.css,
profundidade.css, interface-neutra.css (superfícies, vidro, azul royal e
azul de seleção, nos dois temas — os tokens --skin-*), tipografia.css
(Arial em todas as páginas, sem fonte baixada; não toca o <text> das figuras)
e cores-padrao.css (cores de estado, carregada por último). Os outros .css
são de uma tela só (integracoes.css, estudo-pagina.css, clima-pagina.css,
fotos-estudo.css, croqui-parcelas.css, protocolo-*.css, campo-3d.css).
Áreas seguras do iPhone. O index.html pede viewport-fit=cover: a página vai
até as bordas e env(safe-area-inset-*) diz quanto a ilha e o indicador ocupam.
Tudo que encosta numa borda soma essa medida — inclusive painel que flutua acima
da barra de baixo (bottom: calc(80px + env(safe-area-inset-bottom, 0px))), porque
a barra cresce com o indicador. O tests/test_iphone.js reprova regra fixa com
distância do chão em px sem a área segura. Campo decimal é type="text" com
inputmode="decimal" (o type="number" do Safari trata a vírgula diferente a
cada versão do iOS); campo inteiro é type="number" com inputmode="numeric".
Fora da tela
| O quê | Onde |
|---|
| PWA (instalável e offline) | manifest.webmanifest, sw.js, icon-*.png, apple-touch-icon.png (o do iPhone: opaco, 180 × 180 — transparência ele pinta de preto) |
| Proxy de satélite, clima e solo (Python, roda no Render) | ndvi-proxy.py, render.yaml, requirements.txt |
| Regras e configuração do banco | firestore.rules, firestore.indexes.json, firebase.json, .firebaserc |
| Dados embarcados (Agrofit, EPPO) | data/ |
| Planilhas-modelo de protocolo | modelos/ |
| Ferramentas de manutenção (atualizar Agrofit e EPPO, baixar relevo) | tools/ |
| Atualização automática do Agrofit/EPPO e CI dos PRs | .github/workflows/ |
| Testes | tests/ (ver "Testes e portão") |
| O que mudou em cada publicação | LEIA-ME.txt |
| Especificação, roadmap e guias por função | docs/ (índice em docs/README.md) |
Testes e portão
O conferir.sh é o portão antes de publicar: confere a sintaxe dos scripts, roda
todos os testes e confere as versões do cache. Responde PODE SUBIR ou NÃO
SUBA e por quê. No Mac, o duplo clique em Conferir antes de publicar.command
roda o mesmo portão.
npm install uma vez (traz o jsdom e o IndexedDB simulado dos testes de tela);
depois npm test, que é bash conferir.sh.- Num pull request:
bash conferir.sh --pull-request (o CI roda este).
- Os testes moram em
tests/: test_*.js (Node) e test_*.py (Python).
Rodam a partir da raiz: node tests/test_agenda_calendario.js.
- Também em
tests/: as regras do banco no emulador (*-rules.cjs,
sync-firestore.cjs), o motor estatístico em Python (motor_*.py, que o
test_motor_python.js roda no Pyodide) e os ajudantes state-harness.cjs
(o app num contexto de teste) e check-assets.cjs (o portão usa).
- Teste novo de motor:
tests/test_<nome>.js, ao lado dos outros. Um test_*.js
deixado na raiz não roda, e o portão reprova a publicação por isso.
- Regras do banco no emulador:
npm run test:regras (precisa de Java; o CI roda).
Segurança
ndvi-credenciais.json (segredo do Copernicus) não é versionado (ver .gitignore).
O acesso é controlado em duas camadas. Na tela, o app fica invisível até a
autenticação e volta a ficar invisível fora do horário liberado. No banco, as
firestore.rules recusam leitura e escrita para quem não é membro ativo ou está
fora da própria janela de horário — é essa camada que protege o dado de verdade,
já que os arquivos do site são estáticos e públicos.
O horário de cada técnico fica em members/{email}.janela e é editado no Painel
Admin.
As regras sobem pelo CI, não à mão. O merge que muda o firestore.rules
dispara "Regras do banco — publicar": testes no emulador → espera aprovação no
ambiente regras-producao → publica e confere. Aprove depois de abrir o app
novo em cada aparelho. Toda segunda, "Regras do banco — conferir" compara o que
está no ar com o repositório. Configuração e caminho de volta:
docs/VALIDACAO-SISTEMA.md, apêndice A.
Publicar
- App → GitHub Pages (estático, https), direto do
main: o que entra no main
está no ar.
- Proxy NDVI → servidor (ex.: Render) — GitHub Pages não roda Python.
- Multiusuário → Firebase Authentication + Cloud Firestore.
Toda publicação que muda um arquivo do app:
- sobe o
?v= desse arquivo no index.html e na lista ASSETS do sw.js
(os dois iguais);
- sobe o
CACHE do sw.js (agracta-app-vNNN) e o registro sw.js?v=NNN no
index.html — sem isso o aparelho instalado continua com a versão velha;
- ganha uma entrada no topo do
LEIA-ME.txt: o que mudou, por quê e o que
conferir depois de subir.
O conferir.sh confere que o index.html e o sw.js pedem as mesmas versões e,
no modo publicação, que o CACHE é diferente do que está no ar. Ele ainda não
percebe um arquivo alterado cujo ?v= ficou igual.
Persistência local-first
O Agracta salva primeiro no aparelho e usa a nuvem como sincronização:
- o estado ativo permanece no armazenamento local;
- um checkpoint completo adicional é mantido no IndexedDB;
- o Firestore recebe documentos separados por local, quadra, estudo,
aplicação, avaliação e lançamento;
- alterações feitas sem internet ficam marcadas no checkpoint do Agracta;
- quando a conexão volta, o aplicativo relê a revisão e reconcilia as pendências;
- dados e revisão são enviados juntos em uma transação. Se outro aparelho
alterar a base, a reconciliação é refeita antes de tentar novamente.
As regras do Firestore exigem essa gravação atômica (syncProtocol: 3). Clientes
antigos precisam atualizar o aplicativo antes de voltar a enviar; seu trabalho
local permanece no aparelho. Uma falha de leitura ou envio mantém a pendência,
sem publicar um estado parcial nem uma revisão falsa.
Backups automáticos incluem observações e registros de exclusão. O cofre também
inclui as fotos das observações disponíveis neste aparelho; antes de excluir uma
observação, o app confirma a cópia da imagem. Para transferir os dados a outro
aparelho por exportação, preserve também os arquivos locais das fotos. Além da
cópia em localStorage, até dez versões recentes ficam no cofre IndexedDB,
acessíveis pelo mesmo menu de backups. Restaurar/importar um backup cria uma nova
geração persistente: uma cópia antiga de outro aparelho não desfaz a restauração.
Backups legados não passam a conter fotos que nunca foram guardadas neles.
Validação: npm test e npm run test:regras (emulador local, nunca produção).
O limite de tamanho de transação do Firestore continua aplicável: se um envio
excedê-lo, a transação falha inteira e os dados permanecem locais, pendentes.
O IndexedDB interno do Firestore permanece desativado. O Agracta já possui seu
próprio cofre durável, evitando duas filas offline concorrentes no navegador.
Se Firebase ou internet estiverem indisponíveis, o trabalho de campo continua.
O selo mostra salvo neste aparelho até a sincronização voltar.
Configurar o Firebase
-
Crie um projeto Firebase e um aplicativo Web.
-
Ative Authentication por e-mail/senha e Cloud Firestore.
-
Copie a configuração Web para firebase-config.js.
-
Faça login no CLI e publique as regras:
npx firebase-tools login
npx firebase-tools use SEU_PROJECT_ID
npx firebase-tools deploy --only firestore
As fotos ficam no aparelho; a nuvem recebe os metadados das observações.
Fragmentos antigos no Firestore continuam disponíveis para migração local,
mas a sincronização não grava novas imagens nem apaga esses fragmentos.
