Regenera G10 — Colaboradores Offline

1) Objetivo

Permitir que colaboradores da Eko's, como equipe técnica e operacional, consigam visitar fazendas diferentes e utilizar o mesmo app já existente para produtores e funcionários do produtor.

O app deve continuar sendo único. A diferença será apenas o comportamento conforme o account_type retornado no pareamento/login.

Para usuários do tipo colaborador, o app deve identificar a fazenda dinamicamente por meio da leitura de qualquer QR Code G10 disponível no local. Após identificar o cliente e a participação G10, o app deve reaproveitar a mesma tela já existente do produtor para exibir dados da fazenda, cultura, quantidade de plantas e geocerca.

2) Regra principal

O colaborador não deve selecionar manualmente a fazenda antes de ler o QR Code. O próprio QR Code é quem identifica o contexto da operação.

Fluxo correto:
Ler QR Code → app localiza no cache → identifica fazenda/G10 → mostra dados → registra operação

Isso evita erro humano, porque o colaborador pode visitar mais de uma fazenda no mesmo dia. Se houvesse seleção manual, ele poderia selecionar uma fazenda e ler QR Code de outra.

3) Reaproveitamento da tela existente do produtor

Não deve ser criada uma nova tela exclusiva para colaboradores exibirem dados da fazenda. O app deve reaproveitar a estrutura que já existe para o produtor.

A tela atual que já exibe os dados abaixo deve ser usada também na versão colaborador:

dados da fazenda;
cultura;
idade do pomar;
variedade da planta;
porta-enxerto;
quantidade de plantas da área tratada;
geocerca;
mapa/polígono da área.

A única diferença é a origem do contexto ativo:

Produtor / funcionário do produtor
→ contexto vem do device token

Colaborador
→ contexto vem da leitura de qualquer QR Code G10 salvo no cache offline

4) Fluxo operacional do colaborador

Colaborador abre o app.
Se houver internet, o app executa automaticamente f=sincronizacao_offline.
ERP identifica que o device é account_type=colaborador.
ERP retorna QR Codes ativos de todas as fazendas G10.
ERP retorna dados básicos das fazendas, participações G10 e geocercas.
App salva tudo no banco offline local.
Colaborador chega na fazenda, mesmo sem internet.
Na tela do colaborador, toca em Identificar Cliente.
App abre a câmera.
Colaborador lê qualquer QR Code G10 disponível naquela fazenda.
App procura o QR Code no cache offline local.
Se encontrar, app identifica cliente_id e id_g10_participacao.
App define o contexto ativo da fazenda.
App abre a mesma tela já existente usada pelo produtor.
Colaborador visualiza dados da fazenda, cultura, quantidade de plantas e geocerca.
Colaborador executa a operação necessária.
Se estiver offline, o evento fica na fila local.
Quando voltar internet, app envia os eventos pendentes ao ERP.

5) Botão Identificar Cliente

Para usuários do tipo colaborador, a tela inicial deve exibir um botão principal:

Identificar Cliente

Esse botão deve abrir a câmera e permitir a leitura de qualquer QR Code G10 ativo disponível na fazenda.

O QR Code pode ser de:

página pública;
kit de entrega;
coleta de solo;
coleta de folha;
preparo Eko's Bio;
aplicação, caso exista no fluxo.

O QR Code não será usado para selecionar manualmente uma fazenda. Ele será usado apenas como chave para localizar no cache offline qual cliente/G10 está vinculado àquele código.

QR Code lido
→ procurar no cache local
→ localizar cliente_id e id_g10_participacao
→ definir contexto ativo
→ abrir tela existente do produtor

6) Contexto ativo da fazenda

Para produtor e funcionário do produtor, o contexto ativo vem diretamente do device token.

{
  "cliente_id_ativo": 664,
  "id_g10_participacao_ativo": 2,
  "origem_contexto": "device_token"
}

Para colaborador, o contexto ativo deve ser definido após a leitura de um QR Code G10.

{
  "cliente_id_ativo": 664,
  "id_g10_participacao_ativo": 2,
  "origem_contexto": "qrcode",
  "qrcode_id": 10,
  "tipo_conteudo": "kit_entrega"
}

Após definir esse contexto, o app deve abrir a mesma tela de dados/geocerca já usada pelo produtor, apenas passando o cliente_id_ativo e o id_g10_participacao_ativo identificados.

Caso o colaborador visite outra fazenda, basta tocar novamente em Identificar Cliente e ler um QR Code da nova fazenda.

7) Endpoint de sincronização offline

POST https://agroecologia.grupoekos.com.br/router/action.php

Headers

X-APP-KEY: <APP_KEY_FIXA_DO_APP>
X-DEVICE-TOKEN: <DEVICE_TOKEN_DO_APARELHO>

Body

action=apiG10
f=sincronizacao_offline
last_sync_at=YYYY-MM-DD HH:MM:SS

O campo last_sync_at é opcional. Quando enviado, o ERP pode retornar apenas dados criados ou atualizados após essa data.

8) Regra por tipo de usuário

Tipo	O que recebe na sincronização
`produtor`	Recebe somente dados e QR Codes da própria fazenda.
`produtor_funcionario`	Recebe somente dados e QR Codes da fazenda vinculada ao produtor.
`colaborador`	Recebe dados e QR Codes ativos de todas as fazendas participantes do G10.

9) Dados retornados para colaborador

Para o colaborador operar offline, a sincronização deve retornar dados leves, separados por blocos. Não devem ser retornadas imagens, PDFs, trajetos completos ou histórico pesado.

{
  "success": true,
  "msg": "Sincronização offline realizada com sucesso.",
  "data": {
    "server_time": "2026-06-25 08:00:00",
    "device_id": 999,
    "cliente_id": 112,
    "account_type": "colaborador",
    "ttl_qr_horas": 48,

    "qrcodes": [],
    "fazendas": [],
    "geocercas": []
  }
}

10) Bloco `qrcodes`

Contém todos os QR Codes ativos que o colaborador poderá ler no campo.

{
  "qrcode_id": 10,
  "referencia": "KIT PEDIDO 1500",
  "qrcode": "CONTEUDO_DO_QRCODE",
  "tipo_conteudo": "kit_entrega",
  "nome_tabela": "pedidos",
  "id_tabela": 1500,
  "status": 1,
  "cliente_id": 664,
  "id_g10_participacao": 2,
  "updated_at": "2026-06-25 07:50:00"
}

Tipos esperados

tipo_conteudo	Uso	Vínculo
`kit_entrega`	Registrar kit de entrega.	`pedidos`
`preparo_bio`	Registrar preparo Eko´s Bio.	`pedidos`
`coleta_analise_solo`	Registrar coleta de solo.	`pedidos`
`coleta_analise_folha`	Registrar coleta de folha.	`pedidos`
`pagina_publica`	Identificar área/talhão G10.	`g10_participacoes`

11) Bloco `fazendas`

Contém os dados básicos das fazendas/participações G10 vinculadas aos QR Codes retornados.

{
  "cliente_id": 664,
  "razao_social": "FAZENDA MODELO",
  "cidade": "Araras",
  "uf": "SP",
  "idade_pomar": "8",
  "variedade_planta": "Pera Rio",
  "porta_enxerto": "Swingle",
  "id_g10_participacao": 2,
  "unidade_referencia": "G10 - 02"
}

12) Bloco `geocercas`

Contém a geocerca da fazenda para o app exibir no mapa mesmo sem internet.

{
  "id_geocerca": 1,
  "cliente_id": 664,
  "id_g10_participacao": 2,
  "descricao": "Talhão 9",
  "qtde_plantas_area_tratada": 450,
  "poligonos": [
    {
      "latitude": -21.86456790,
      "longitude": -47.49966836,
      "ordem": 1
    },
    {
      "latitude": -21.86449821,
      "longitude": -47.49988561,
      "ordem": 2
    }
  ]
}

13) Como o app deve usar offline

Ao ler um QR Code sem internet, o app deve procurar o conteúdo lido no banco local.

qrcode lido → procurar em qrcodes.qrcode

Se encontrar, o app usa:

qrcodes.cliente_id para localizar a fazenda.
qrcodes.id_g10_participacao para localizar a unidade G10.
geocercas.id_g10_participacao para exibir o polígono no mapa.
tipo_conteudo para decidir qual operação executar.

A validação definitiva continuará acontecendo no ERP quando o app voltar a ter internet e enviar o evento pendente.

14) O que não deve ser carregado nessa sincronização

Fotos ou imagens em base64.
Metadados de fotos.
PDFs.
Trajetos completos de aplicação.
Histórico completo de análises.
Resultados detalhados de indicadores.

Esses dados devem ser carregados em endpoints próprios, sob demanda, quando houver internet.

15) Resumo para o desenvolvedor

O app continua sendo único para produtor, funcionário do produtor e colaborador.
A tela de dados da fazenda/geocerca já existente para produtor deve ser reaproveitada.
Não deve ser criada uma tela duplicada para colaborador.
Colaborador pareia uma única vez com account_type=colaborador.
Ao abrir o app com internet, a sincronização offline roda automaticamente.
A sincronização retorna QR Codes, fazendas e geocercas.
No campo, o colaborador toca em Identificar Cliente.
O app lê qualquer QR Code G10 da fazenda.
O app procura o QR Code no cache offline.
Encontrando o QR Code, define cliente_id_ativo e id_g10_participacao_ativo.
Depois abre a mesma tela do produtor usando esse contexto ativo.
Não existe seleção manual de fazenda.
Fotos, PDFs, trajetos e arquivos pesados ficam fora dessa sincronização.