# Implementacao para Fernando Valentim - Modulo Operacao de Campo e Boletim SPT

Responsavel pelo prototipo: Fabiano / Codex  
Destinatario: Fernando Valentim  
Data do handoff: 05/07/2026  
Status: prototipo navegavel pronto para virar modulo de producao

## 1. Objetivo

Implementar no sistema real um modulo operacional para equipes de sondagem, topografia e fundacoes, usando o celular do operador em campo para:

- acompanhar a jornada da equipe;
- registrar status da OS;
- capturar GPS real do ponto de sondagem;
- preencher boletim SPT;
- selecionar material/camada a partir de biblioteca tecnica;
- registrar criterio de paralisacao;
- gerar relatorio tecnico final de sondagem SPT;
- permitir que o responsavel acompanhe, revise e libere o trabalho pela plataforma.

O conceito e similar ao acompanhamento operacional de apps como Uber, iFood e Rappi, mas aplicado a servicos tecnicos de campo. O objetivo principal nao e entrega/transporte: e rastreabilidade da OS, evidencia tecnica, boletim de campo e relatorio padronizado.

## 2. Artefatos disponiveis

### Prototipo principal

Arquivo:

`C:\Users\Fabiano\Documents\Codex\2026-07-05\c\outputs\modulo-operacao-campo-opcao2.html`

URL local:

`http://127.0.0.1:8898/modulo-operacao-campo-opcao2.html`

### Manual do usuario

HTML:

`C:\Users\Fabiano\Documents\Codex\2026-07-05\c\outputs\manual-usuario-operacao-campo.html`

PDF:

`C:\Users\Fabiano\Documents\Codex\2026-07-05\c\outputs\pdf\manual-usuario-operacao-campo.pdf`

URLs locais:

`http://127.0.0.1:8898/manual-usuario-operacao-campo.html`

`http://127.0.0.1:8898/pdf/manual-usuario-operacao-campo.pdf`

### Resumo visual e tecnico

HTML:

`C:\Users\Fabiano\Documents\Codex\2026-07-05\c\outputs\resumo-conceito-sistema-sondagem.html`

Markdown:

`C:\Users\Fabiano\Documents\Codex\2026-07-05\c\outputs\resumo-desenvolvedor-sistema-sondagem.md`

URL local:

`http://127.0.0.1:8898/resumo-conceito-sistema-sondagem.html`

## 3. Modulos a implementar

### 3.1 App do operador em campo

Deve funcionar em celular e priorizar uso em obra.

Funcionalidades:

- abrir OS atribuida;
- indicar status: a caminho, cheguei, executando, pausado, concluido;
- checklist da jornada;
- registro de km inicial/final;
- fotos da equipe, equipamento, amostras e evidencias;
- assinatura do responsavel em campo;
- abertura do boletim SPT;
- captura de GPS real no ponto exato onde a perfuracao foi iniciada.

Observacao importante: se houver rastreamento em segundo plano, tratar como recurso nativo Android/iOS ou hibrido com permissao adequada. PWA/web simples pode capturar GPS em primeiro plano, mas nao e suficiente para tracking continuo confiavel.

### 3.2 Plataforma do responsavel

Funcionalidades:

- dashboard de operacoes;
- kanban por status: a caminho, em execucao, pausado/atencao, concluido;
- mapa com equipes e pontos;
- alertas: GPS pendente, boletim incompleto, sem atualizacao, fora da area da obra;
- detalhe da equipe e OS;
- acesso ao boletim SPT;
- revisao do relatorio final;
- liberacao para responsavel tecnico/cliente.

### 3.3 Boletim SPT

Campos principais:

- ponto/SP;
- nome livre do SP;
- profundidade do furo;
- profundidade salva;
- presenca de agua;
- profundidade do nivel d'agua;
- parou em;
- profundidade de rocha/matacao;
- GPS real do ponto;
- camadas do perfil;
- material;
- complemento;
- plasticidade;
- cor;
- interpretacao geologica;
- golpes SPT;
- N e N';
- criterio de paralisacao.

Regras:

- como padrao, abrir com SP01 e SP02;
- permitir criar novo SP com qualquer nome: SP55, SP101, SPT-A, PONTO-01 etc.;
- permitir renomear SP;
- permitir excluir SP, mantendo pelo menos um ponto cadastrado;
- salvar dados por SP;
- ao trocar SP, os dados do SP anterior nao podem sumir;
- ao gerar relatorio, o boletim nao pode perder os dados lancados.

### 3.4 Biblioteca de materiais

Implementar biblioteca configuravel com:

- material;
- genero;
- CG;
- PG;
- tipo;
- interpretacao geologica;
- complemento;
- plasticidade;
- cor.

Uso esperado:

- operador clica em "Selecionar";
- escolhe material/complemento/plasticidade/cor;
- sistema preenche a camada;
- relatorio final usa esta informacao para montar a descricao do material.

### 3.5 Criterio de paralisacao

Opcoes minimas:

- Solicitacao da contratante;
- Impenetravel ao amostrador;
- Limite da sondagem;
- Impenetravel ao trepano de lavagem;
- Outro.

Campos:

- sistema;
- criterio de paralisacao;
- profundidade de paralisacao;
- observacao/texto complementar;
- para trepano de lavagem: 1o 10 min, 2o 10 min, 3o 10 min.

Textos no relatorio:

Para impenetravel ao amostrador:

```text
IMPENETRAVEL AO AMOSTRADOR

FURO PARALISADO CONFORME DESCRITO
NO ITEM 5.2.4.2 DA NORMA NBR6484:2020 -
SOLO - SONDAGEM DE SIMPLES
RECONHECIMENTO COM SPT.
```

Para solicitacao da contratante:

```text
LIMITE DA SONDAGEM CONFORME
SOLICITACAO DA CONTRATANTE
```

Para impenetravel ao trepano de lavagem:

```text
IMPENETRAVEL AO TREPANO DE LAVAGEM

FURO PARALISADO CONFORME DESCRITO NO
ITEM 5.2.4.5 DA NORMA NBR6484:2020 - SOLO -
SONDAGEM DE SIMPLES RECONHECIMENTO
COM SPT.

ENSAIO DE LAVAGEM:
1o 10 min = 2,00 cm
2o 10 min = 1,00 cm
3o 10 min = 0,00 cm
```

## 4. Regra critica: corte de SPT apos paralisacao

Esta regra e obrigatoria.

Quando ocorrer paralisacao em profundidade menor que a profundidade total do boletim, o relatorio final nao pode exibir golpes SPT apos a profundidade efetiva de parada.

Exemplo:

- profundidade salva do furo: 12,00 m;
- paralisacao por rocha/matacao ou impenetravel: 6,10 m;
- boletim pode ate ter linhas de 7 m, 8 m, 9 m por padrao;
- o relatorio final deve exibir somente amostras ate 6 m;
- as linhas/valores de 7 m, 8 m e 9 m nao podem aparecer em golpes, resistencia nem grafico SPT;
- a nota de paralisacao entra a partir de 6,10 m;
- perfil geologico e profundidade da camada devem encerrar em 6,10 m.

Referencia no prototipo:

- `reportSptCutoffDepth()`
- `reportSamplesForFinal()`
- `reportLayersForFinal()`
- `sampleRowPosition()`
- `renderPenetrationTable(maxDepth)`
- `renderResistanceTable(maxDepth)`
- `renderFinalReport()`

Arquivo:

`outputs/modulo-operacao-campo-opcao2.html`

Linhas de referencia atuais:

- regra de corte: perto da linha 4444;
- amostras finais: perto da linha 4461;
- camadas finais: perto da linha 4469;
- renderizacao das tabelas: perto das linhas 5436 a 5468;
- uso no relatorio final: perto das linhas 5595 e 5602.

## 5. GPS real do ponto

O GPS do ponto deve corresponder a localizacao real em campo, no local exato onde a perfuracao foi iniciada.

Regras:

- operador deve acionar "Atualizar GPS" ou equivalente;
- usar geolocation do aparelho;
- salvar latitude, longitude, precisao, data/hora, origem e usuario;
- diferenciar GPS real de coordenada digitada;
- impedir geracao/liberacao do relatorio se o GPS real estiver pendente;
- mostrar precisao em metros;
- salvar por SP.

Campos sugeridos:

- `latitude`;
- `longitude`;
- `accuracy_m`;
- `captured_at`;
- `captured_by_user_id`;
- `source`: `gps-real`, `manual`, `importado`;
- `device_id`;
- `work_order_id`;
- `spt_point_id`.

## 6. Persistencia e modelo de dados sugerido

Tabelas principais:

- `users`
- `teams`
- `vehicles`
- `equipment`
- `projects`
- `work_orders`
- `field_assignments`
- `field_events`
- `location_points`
- `photos`
- `client_signatures`
- `spt_points`
- `spt_bulletins`
- `spt_layers`
- `spt_samples`
- `materials_library`
- `material_complements`
- `material_plasticities`
- `material_colors`
- `paralysis_criteria`
- `report_exports`
- `technical_approvals`
- `audit_logs`

### Exemplo de estrutura minima

```sql
CREATE TABLE spt_points (
  id UUID PRIMARY KEY,
  work_order_id UUID NOT NULL,
  name VARCHAR(80) NOT NULL,
  depth_m NUMERIC(8,2),
  depth_saved BOOLEAN DEFAULT FALSE,
  stopped_at VARCHAR(80),
  rock_depth_m NUMERIC(8,2),
  water_presence BOOLEAN DEFAULT FALSE,
  water_depth_m NUMERIC(8,2),
  latitude NUMERIC(11,8),
  longitude NUMERIC(11,8),
  gps_accuracy_m NUMERIC(8,2),
  gps_source VARCHAR(30),
  gps_captured_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL,
  updated_at TIMESTAMP NOT NULL
);

CREATE TABLE spt_layers (
  id UUID PRIMARY KEY,
  spt_point_id UUID NOT NULL,
  position INTEGER NOT NULL,
  start_m NUMERIC(8,2) NOT NULL,
  end_m NUMERIC(8,2) NOT NULL,
  material VARCHAR(160),
  complement VARCHAR(160),
  plasticity VARCHAR(120),
  color_name VARCHAR(120),
  color_hex VARCHAR(20),
  geo_code VARCHAR(20)
);

CREATE TABLE spt_samples (
  id UUID PRIMARY KEY,
  spt_point_id UUID NOT NULL,
  sample_number INTEGER NOT NULL,
  depth_m NUMERIC(8,2) NOT NULL,
  g1 INTEGER,
  p1 NUMERIC(8,2),
  g2 INTEGER,
  p2 NUMERIC(8,2),
  g3 INTEGER,
  p3 NUMERIC(8,2),
  n_initial INTEGER,
  n_final INTEGER
);

CREATE TABLE spt_paralysis (
  id UUID PRIMARY KEY,
  spt_point_id UUID NOT NULL,
  system_label VARCHAR(120),
  criterion VARCHAR(120),
  stop_depth_m NUMERIC(8,2),
  observation TEXT,
  wash_1_cm NUMERIC(8,2),
  wash_2_cm NUMERIC(8,2),
  wash_3_cm NUMERIC(8,2)
);
```

## 7. APIs sugeridas

### OS e jornada

- `GET /api/work-orders/:id`
- `POST /api/work-orders/:id/status`
- `POST /api/work-orders/:id/checklist`
- `POST /api/work-orders/:id/photos`
- `POST /api/work-orders/:id/signature`

### GPS

- `POST /api/spt-points/:id/gps`
- `GET /api/spt-points/:id/gps`

### Boletim SPT

- `GET /api/work-orders/:id/spt-points`
- `POST /api/work-orders/:id/spt-points`
- `PATCH /api/spt-points/:id`
- `DELETE /api/spt-points/:id`
- `POST /api/spt-points/:id/save-depth`
- `GET /api/spt-points/:id/bulletin`
- `PUT /api/spt-points/:id/bulletin`

### Camadas e amostras

- `POST /api/spt-points/:id/layers`
- `PATCH /api/spt-layers/:id`
- `DELETE /api/spt-layers/:id`
- `POST /api/spt-points/:id/samples`
- `PATCH /api/spt-samples/:id`
- `DELETE /api/spt-samples/:id`

### Relatorio

- `POST /api/spt-points/:id/reports/generate`
- `GET /api/spt-points/:id/reports/latest`
- `POST /api/spt-points/:id/reports/approve`
- `GET /api/report-exports/:id/download`

## 8. Geracao do relatorio final

O relatorio deve seguir o layout visual de referencia do prototipo e imagens anexadas pelo Fabiano:

- titulo: `SONDAGEM DE SIMPLES RECONHECIMENTO DO SOLO COM SPT - NBR 6484/2020`;
- cabecalho com cliente, obra, local, GPS, inicio, termino, datum, coordenadas;
- grafico SPT;
- profundidade;
- ensaio de penetracao;
- resistencia a penetracao;
- interpretacao geologica;
- perfil geologico;
- profundidade da camada;
- descricao do material;
- nivel d'agua;
- avanco.

Implementar geracao oficial no backend. O HTML pode servir como referencia visual, mas producao deve preferir PDF gerado no servidor, com versionamento e auditoria.

## 9. Offline e sincronizacao

O app de campo deve funcionar em locais sem internet.

Obrigatorio:

- salvar localmente os dados lancados;
- fila de sincronizacao;
- sinalizar conflito quando a mesma OS/SP for editada por mais de uma pessoa;
- preservar horario local e horario de sincronizacao;
- nao permitir perda de boletim ao fechar app, trocar SP ou gerar relatorio.

Estados sugeridos:

- `draft_local`;
- `pending_sync`;
- `synced`;
- `conflict`;
- `approved`;
- `exported`.

## 10. Regras de UX importantes

- Tela inicial do operador deve ser operacional, nao uma landing page.
- Botoes devem ser claros e grandes para celular.
- Campo de GPS deve indicar se e real, pendente ou manual.
- SP deve aceitar nome livre.
- Acoes destrutivas, como excluir SP/camada/amostra, devem pedir confirmacao.
- Material deve ser escolhido por biblioteca, reduzindo digitacao.
- Ao salvar profundidade do furo, o sistema deve ajustar a quantidade de amostras SPT ate a profundidade inteira aplicavel.
- Se o furo paralisar em 6,10 m, nao criar/exibir golpes de 7 m em diante no relatorio final.

## 11. Checklist de aceite

### Ponto/SP

- [ ] Sistema abre com SP01 e SP02.
- [ ] Usuario consegue criar SP55, SP101 ou nome livre.
- [ ] Usuario consegue renomear SP.
- [ ] Usuario consegue excluir SP, mantendo pelo menos um ponto.
- [ ] Dados ficam salvos por SP.
- [ ] Trocar SP nao apaga o boletim anterior.

### Profundidade e SPT

- [ ] Usuario salva profundidade do furo.
- [ ] Sistema libera amostras SPT conforme profundidade salva.
- [ ] Usuario consegue remover amostras quando necessario.
- [ ] N e N' sao recalculados ao alterar golpes.

### Camadas

- [ ] Usuario adiciona camada.
- [ ] Usuario remove camada.
- [ ] Linhas do relatorio acompanham a remocao/adicao de camadas.
- [ ] Perfil geologico acompanha inicio/fim das camadas.

### Material

- [ ] Biblioteca abre com material, complemento, plasticidade, cor e interpretacao.
- [ ] Selecionar item preenche a camada.
- [ ] Descricao final do relatorio usa os dados selecionados.

### GPS

- [ ] GPS real e capturado pelo aparelho.
- [ ] Latitude, longitude, precisao e horario sao salvos.
- [ ] Relatorio nao e liberado com GPS pendente.
- [ ] GPS e salvo por SP.

### Paralisacao

- [ ] Usuario seleciona criterio de paralisacao.
- [ ] Texto tecnico correto aparece no relatorio.
- [ ] Se parou em 6,10 m, nao aparecem golpes de 7 m, 8 m ou superiores.
- [ ] Perfil e camadas encerram na profundidade de paralisacao.
- [ ] Nota de paralisacao aparece abaixo da profundidade de parada.

### Relatorio

- [ ] Gerar relatorio nao apaga o boletim.
- [ ] Relatorio segue o layout de referencia.
- [ ] Grafico SPT respeita as amostras validas.
- [ ] Tabela de golpes e resistencia respeita a profundidade final/paralisacao.
- [ ] PDF final fica versionado e auditavel.

## 12. Casos de teste obrigatorios

### Caso 1 - Furo normal ate 12 m

Entrada:

- profundidade: 12 m;
- sem paralisacao;
- amostras 1 a 12.

Esperado:

- relatorio mostra golpes de 1 m a 12 m;
- perfil geologico vai ate 12 m.

### Caso 2 - Impenetravel em 6,10 m

Entrada:

- profundidade do furo: 12 m;
- criterio: impenetravel ao amostrador;
- profundidade de paralisacao: 6,10 m;
- camadas ate 6,10 m;
- boletim possui amostras padrao ate 12 m.

Esperado:

- relatorio mostra somente amostras 1, 2, 3, 4, 5 e 6;
- nao mostra 7 m, 8 m, 9 m, 10 m, 11 m, 12 m nas colunas de golpes/resistencia;
- nota `IMPENETRAVEL AO AMOSTRADOR` aparece a partir de 6,10 m;
- perfil geologico encerra em 6,10 m.

### Caso 3 - Solicitacao da contratante em 1,35 m

Entrada:

- criterio: solicitacao da contratante;
- profundidade de paralisacao: 1,35 m.

Esperado:

- relatorio mostra a camada ate 1,35 m;
- nota `LIMITE DA SONDAGEM CONFORME SOLICITACAO DA CONTRATANTE`;
- nao mostra golpes posteriores.

### Caso 4 - Trepano de lavagem

Entrada:

- criterio: impenetravel ao trepano de lavagem;
- profundidade de paralisacao informada;
- tempos de lavagem preenchidos.

Esperado:

- relatorio mostra texto do item 5.2.4.5;
- mostra os tres tempos de lavagem;
- nao mostra golpes apos a profundidade de parada.

## 13. Sugestao de fases

### Fase 1 - MVP tecnico

- CRUD de OS;
- CRUD de SP;
- boletim SPT;
- camadas;
- amostras;
- GPS real;
- relatorio HTML/PDF;
- dashboard simples.

### Fase 2 - Operacao em campo

- app mobile/hibrido;
- offline;
- sincronizacao;
- fotos;
- assinatura;
- notificacoes.

### Fase 3 - Plataforma de gestao

- mapa em tempo real;
- alertas;
- liberacao tecnica;
- historico/auditoria;
- exportacao oficial PDF/XLSM.

### Fase 4 - Produto robusto

- biblioteca configuravel por empresa;
- permissoes por perfil;
- integracao com financeiro/faturamento;
- relatorios por obra;
- indicadores de produtividade.

## 14. Observacoes finais para implementacao

- O prototipo atual usa HTML, CSS, JavaScript e `localStorage`. Em producao, migrar estado para backend e banco de dados.
- Nao perder dados ao gerar relatorio e regra central.
- Todo dado tecnico deve ter auditoria: usuario, horario, origem e SP.
- GPS precisa respeitar permissao do usuario e finalidade operacional.
- O relatorio deve ser fiel ao modelo visual apresentado pelo Fabiano, principalmente perfil estratigrafico, camadas, golpes SPT e criterio de paralisacao.
- A regra de impenetravel/paralisacao e obrigatoria: depois da profundidade de parada nao deve aparecer golpe SPT.