Modelo de dados

Os dados da plataforma são organizados em torno da Propriedade (fazenda). Cada token dá acesso aos dados de uma única fazenda. Dentro dela existem:

Estrutura agrícola: Talhões (glebes), Safras (crop) e Talhões de Safra (cropGlebe).
Cadastros: Empresas (fornecedor/cliente), Elementos (catálogo de insumos, defensivos, etc.).
Patrimônios: Máquinas, pivots, silos, bens imobilizados; abastecimentos e manutenções.
Atividades: Planejamentos de atividade e realizações, sempre vinculadas a uma safra.
Estoque: Locais de estoque, itens e movimentações.
Financeiro: Contas bancárias, categorias financeiras, lançamentos e parcelas.
Clima: Registros climáticos.

Safra, Talhão e Talhão de Safra

A estrutura agrícola associa onde se cultiva (talhão) com quando se cultiva (safra). Três recursos trabalham juntos:

Talhão (Glebe)

Talhão é a área física da fazenda: cadastro permanente (nome, área em ha, tag, etc.). Ex.: "Talhão 01", "Talhão Norte".

Na API: /pub/v1/glebes/{glebeKey}, /pub/v1/glebes/filter.

Safra (crop)

Safra (crop) é um ciclo produtivo: período de cultivo com datas, nome e tipo de cultura (soja, milho, etc.). Ex.: "Soja 22/23". Agrupa os talhões de safra daquele ciclo.

Na API: /pub/v1/crops/{cropKey}, /pub/v1/crops/filter.

Talhão de Safra (cropGlebe)

Talhão de Safra (cropGlebe) é o talhão físico dentro daquela safra. O mesmo talhão pode participar de várias safras; cada participação é um Talhão de Safra com sua própria chave.

Na API: /pub/v1/crop-glebes/{cropGlebeKey}, /pub/v1/crops/{cropKey}/crop-glebes/filter.

flowchart TB subgraph fisico [Cadastro físico] G1[Talhão 01] G2[Talhão 02] end subgraph temporal [Ciclos produtivos] C1[Safra Soja 22/23] C2[Safra Milho 23] end subgraph vinculos [Talhões de Safra] CG1[Talhão 01 na Soja 22/23] CG2[Talhão 02 na Soja 22/23] CG3[Talhão 01 na Milho 23] end G1 --> CG1 G1 --> CG3 G2 --> CG2 C1 --> CG1 C1 --> CG2 C2 --> CG3

Relação entre todos os recursos

As atividades pertencem sempre a uma safra.

flowchart TB subgraph propriedade ["Propriedade"] Farm["Propriedade"] end subgraph nivel_fazenda ["Recursos da fazenda"] Crop["Safra"] Glebe["Talhão"] Company["Empresa fornecedor/cliente"] Catalog["Catálogo"] Asset["Patrimônio"] StockLoc["Locais de estoque"] BankAcc["Contas"] FinCat["Categorias financeiras"] Tag["Tags"] Weather["Clima"] end subgraph nivel_safra ["Recursos da safra"] CropGlebe["Talhão de Safra"] Activity["Atividade"] HarvestLog["Colheita"] end Farm --> Crop Farm --> Glebe Farm --> Company Farm --> Catalog Farm --> Asset Farm --> StockLoc Farm --> BankAcc Farm --> FinCat Farm --> Tag Farm --> Weather Crop --> CropGlebe Glebe --> CropGlebe Crop --> Activity Crop --> HarvestLog Activity --> ActivityLog["Realizações"]

Além dessas: catálogo tem Elementos; locais de estoque têm itens e movimentações; contas e categorias têm lançamentos e parcelas; patrimônio tem eventos; empresa (fornecedor/cliente) aparece em pedidos de compra.

Hierarquia principal (resumida)

Propriedade como raiz, estrutura agrícola e atividades vinculadas à safra.

flowchart TB Propriedade["Propriedade"] Safras["Safras"] Glebes["Talhões"] CropGlebes["Talhões de Safra"] Atividades["Atividades"] Empresas["Empresa fornecedor/cliente"] Elementos["Elementos"] Propriedade --> Safras Propriedade --> Glebes Propriedade --> Empresas Propriedade --> Elementos Safras --> CropGlebes Glebes --> CropGlebes Safras --> Atividades

Empresas = empresa (fornecedor/cliente). Talhões = talhão (glebe).

Fluxo de uso típico

Ordem lógica: obter a propriedade, depois safras e talhões/talhões de safra, em seguida atividades, estoque e financeiro.

flowchart TB A[Obter propriedade] --> B[Listar safras e áreas] B --> C[Planejamentos e realizações de atividade] C --> D[Estoque e lançamentos financeiros]

Exemplos de fluxos

Consultar propriedade e safras: GET da propriedade (/pub/v1/farms), depois listar ou filtrar safras e talhões de safra (/pub/v1/crops/filter, /pub/v1/crop-glebes/filter).
Registrar realização de atividade: Operações de atividades (obter planejamento, criar/atualizar realização) e, se aplicável, movimentações de estoque e lançamentos financeiros. Para o passo a passo, consulte no Swagger as tags Atividades, Movimentações de Estoque e Lançamentos Financeiros.

Para a especificação completa das operações e schemas: Operações da API (Swagger).