Milestones

JULHO/26 - MINEX

# Planejamento Mensal — GeotrixIA, MINEX 3D e Infraestrutura de Imagens **Período:** Julho/2026 **Carga horária total:** **145 horas** **Organização:** uma semana para IA/RAG/API e três semanas adicionais para segregação de dependências, redução das imagens Docker e validação em AKS. **Focos principais:** 1. geração dos JSONL das funcionalidades de análise do MINEX 3D; 2. adaptação e deployment da API `geotrixIA` para os contextos MINEX 2D e MINEX 3D; 3. separação entre imagens de aplicação e imagens de processamento; 4. criação de ambientes `renv` distintos para desenvolvimento e produção; 5. remoção de dependências de processamento das imagens de app; 6. encapsulamento das operações Python/VTK/Qhull utilizadas pelos pods; 7. adoção de multi-stage build; 8. integração e validação das novas imagens em ambiente AKS. **Repositórios no escopo:** - **`meantrix/geotrixapp3d_prod`** - coletor e geração dos JSONL do MINEX 3D; - pacote/app `geotrixViewer`; - revisão de `DESCRIPTION`; - criação do `renv.prod.lock` do app 3D. - **`meantrix/geotrixia`** - API FastAPI; - integração com OpenAI Responses API; - seleção de banco e vector stores por aplicação; - persistência e serviços de chat. - **`meantrix/geotrix3deploy`** - deployment da API `geotrixIA`; - bases Docker; - imagens de app e pod; - ambiente Python de processamento; - manifests e integração com AKS. - **`meantrix/geotrixMap`** - revisão de `DESCRIPTION`; - criação do `renv.prod.lock` do app 2D; - validação das dependências efetivamente necessárias em produção. **Referência estrutural:** JSONL, registry, pipeline RAG e API já existentes para o MINEX 2D. > O fluxo do MINEX 2D já está implementado e será preservado. O trabalho de IA do mês está restrito às funcionalidades de análise do MINEX 3D listadas neste documento e à adaptação do runtime para selecionar explicitamente o contexto correto. A frente de imagens Docker abrange os apps e pods 2D e 3D. ## Princípios técnicos da frente de imagens - separar claramente **build** e **runtime** por multi-stage build; - manter uma família de bases por função (`app` e `proc`), com variantes somente quando houver incompatibilidade real de versão; - não transportar credenciais por `ARG`, `ENV` do Dockerfile ou camadas de build; - injetar secrets apenas no runtime por Kubernetes Secrets, Key Vault ou identidade federada; - utilizar ServiceAccount e RBAC mínimo para acesso ao Kubernetes; - executar os processos finais como usuário não privilegiado; - fixar versões de R, Python, Java, Conda, pacotes e imagens-base; - publicar imagens com tags imutáveis e, no deployment, preferencialmente por digest; - registrar baseline, tamanho, tempo de build, SBOM e vulnerabilidades antes e depois; - tratar Ubuntu 20.04 como compatibilidade legada: sua manutenção exige ESM/Ubuntu Pro ou base interna corrigida; a migração de sistema operacional permanece uma frente separada. --- # 1. Quadro geral de tarefas e tempos | ID | Tarefa | Repositório(s) principal(is) | Tempo | | --------- | ------------------------------------------------------------ | ---------------------------------------------------- | --------: | | **1** | **Geração dos JSONL das funcionalidades de análise do MINEX 3D** | `meantrix/geotrixapp3d_prod` | **24 h** | | **2** | **Adaptação e deployment da API `geotrixIA` para suporte ao MINEX 3D** | `meantrix/geotrixia` e `meantrix/geotrix3deploy` | **16 h** | | **3** | **Criação do `renv.prod.lock` do `geotrixViewer`** | `meantrix/geotrixapp3d_prod` | **12 h** | | **4** | **Criação do `renv.prod.lock` do `geotrixMap`** | `meantrix/geotrixMap` | **8 h** | | **5** | **Refatoração dos `DESCRIPTION` dos apps 2D e 3D** | `meantrix/geotrixMap` e `meantrix/geotrixapp3d_prod` | **8 h** | | **6** | **Criação da `base_image_app` enxuta** | `meantrix/geotrix3deploy` | **12 h** | | **7** | **Multi-stage build das quatro imagens de aplicação** | `meantrix/geotrix3deploy` | **24 h** | | **8** | **Criação da `base_image_proc` e encapsulamento Python de VTK/Qhull** | `meantrix/geotrix3deploy` | **16 h** | | **9** | **Reescrita das imagens de pod sobre a base de processamento** | `meantrix/geotrix3deploy` | **12 h** | | **10** | **Integração, medição e testes das imagens no AKS** | `meantrix/geotrix3deploy` | **13 h** | | **TOTAL** | | | **145 h** | --- # 2. Organização por semana | Semana | Atividades | Horas | | ------------ | ------------------------------------------------------------ | --------: | | **Semana 1** | Tarefa 1 — JSONL MINEX 3D; Tarefa 2 — API, vector stores e deployment | **40 h** | | **Semana 2** | Tarefa 5 — auditoria dos `DESCRIPTION`; Tarefas 3 e 4 — perfis/lockfiles de produção; Tarefa 6 — família `base_image_app` | **40 h** | | **Semana 3** | Tarefa 7 — app images multi-stage; Tarefa 8 — `base_image_proc` e Python nativo | **40 h** | | **Semana 4** | Tarefa 9 — pod images; Tarefa 10 — integração e testes em AKS | **25 h** | | **TOTAL** | | **145 h** | --- # Tarefa 1 — Geração dos JSONL das funcionalidades de análise do MINEX 3D **Repositório:** `meantrix/geotrixapp3d_prod` **Componente principal:** coletor de JSONL e fontes do `GeotrixApp3D` ## Objetivo geral Mapear as funcionalidades disponíveis no módulo `Menu > Analysis` do `GeotrixApp3D` e gerar os arquivos JSONL necessários para o fluxo de RAG da `geotrixIA`, utilizando o mesmo formato, convenções e estrutura já adotados no MINEX 2D. O coletor implementado em `meantrix/geotrixapp3d_prod` deve identificar, para cada funcionalidade, os componentes de interface, entradas esperadas, validações, eventos, funções de processamento, operações de banco, artefatos gerados e referências de código necessárias para permitir rastreabilidade entre app, processamento e resultados. O objetivo não é mapear todo o `GeotrixApp3D`, mas somente as funcionalidades de análise explicitamente listadas neste planejamento. --- ## 1. Funcionalidades no escopo ### 1.1 Important Features Funcionalidade destinada à seleção e análise de importância de variáveis. Algoritmos: - Boruta; - FAMD — Factor Analysis of Mixed Data. Itens a mapear: - seleção do dataset; - definição das variáveis; - variável-alvo, quando aplicável; - parâmetros dos algoritmos; - validações de entrada; - execução; - resultados e artefatos exibidos ao usuário. ### 1.2 Variogram Funcionalidade de cálculo, ajuste e visualização de variogramas. Itens a mapear: - variável analisada; - coordenadas espaciais; - parâmetros de distância; - direção e tolerâncias; - modelos candidatos; - auto-fit; - visualizações; - resultado utilizado pelo Kriging. ### 1.3 Kriging Funcionalidade de interpolação espacial aplicada a dados e modelos de blocos 3D. Itens a mapear: - dados de origem; - variável a interpolar; - campos espaciais; - grid ou block model de destino; - variograma utilizado; - parâmetros de estimação; - deploy; - tracking; - validação; - download e persistência dos resultados; - uso de `autoKrige`. ### 1.4 Mineral Prospecting Funcionalidade de treinamento de modelos de prospecção mineral. Algoritmos: - Random Forest; - Deep Learning; - XGBoost; - Stacked Ensemble. Itens a mapear: - covariáveis; - variável-alvo; - campos espaciais; - divisão de treino e validação; - hiperparâmetros; - deploy; - tracking; - atualização; - download; - exclusão; - artefatos de modelo e resultado. ### 1.5 Apply Mineral Prospecting Funcionalidade de aplicação de modelo de prospecção previamente treinado a um novo dataset 3D. Itens a mapear: - seleção do modelo; - seleção do novo dataset; - compatibilidade entre colunas; - campos obrigatórios; - parâmetros de aplicação; - geração do mapa de favorabilidade; - persistência e download do resultado. ### 1.6 Lithology Classification Funcionalidade de classificação litológica em dados de drillhole. Métodos: - Spectral Clustering; - PAM + DTW; - Deep Learning — CNN. Itens a mapear: - identificação do drillhole; - campos de profundidade ou intervalos; - variáveis utilizadas; - parâmetros de cada método; - treinamento; - tracking; - geração de classes; - artefatos de modelo e resultado. ### 1.7 Apply Lithology Classification Funcionalidade de aplicação de modelo litológico previamente treinado a novos dados de drillhole. Itens a mapear: - modelo selecionado; - novo dataset; - identificação dos drillholes; - campos de profundidade ou intervalos; - compatibilidade das variáveis; - classificação gerada; - persistência e download do resultado. ### 1.8 BoundD Funcionalidade de detecção e definição de fronteiras ou domínios espaciais. Itens a mapear: - camada ou resultado de origem; - campo de classificação ou probabilidade; - parâmetros de detecção; - criação dos domínios; - resultados derivados de classificação litológica ou prospecção mineral. ### 1.9 BVA Funcionalidade de Block Volume Analysis. Itens a mapear: - modelo de blocos; - geometria e dimensões dos blocos; - campos utilizados; - filtros ou domínios; - parâmetros volumétricos; - métricas geradas; - resultados exibidos ou persistidos. --- ## 2. Estrutura dos JSONL Os arquivos devem seguir a mesma separação utilizada no MINEX 2D. ```text ai_agent_jsonl/ ├── registry/ │ ├── app/ │ │ └── <feature>.app.jsonl │ ├── pre/ │ │ └── <feature>.pre.jsonl │ ├── links/ │ │ └── <feature>.link.jsonl │ └── registry_flows.jsonl ├── rag/ │ ├── code/ │ ├── fingerprints/ │ ├── logs/ │ ├── source/ │ └── manifest/ └── evaluation/ ``` ### 2.1 JSONL de app Responsável por descrever: - objetivo da funcionalidade; - localização na interface; - componentes envolvidos; - entradas obrigatórias e opcionais; - valores padrão; - validações; - eventos emitidos e recebidos; - feedback apresentado ao usuário; - resultados esperados; - referências de código e testes. ### 2.2 JSONL de pre Responsável por descrever, quando houver processamento associado: - entrypoint do job; - pacote de processamento; - payload recebido; - etapas da execução; - funções chamadas; - operações de banco; - artefatos esperados; - tracking; - condições de erro; - referências de código e testes. ### 2.3 JSONL de links Responsável por ligar: - ação na interface; - feature do app; - rotina de processamento; - funções backend; - operações de banco; - resultado ou artefato produzido. ### 2.4 Registry de flows O `registry_flows.jsonl` deve registrar a relação entre: - `feature_id`; - flow; - cartão de app; - cartão de pre, quando aplicável; - cartão de links, quando aplicável; - chunks de código; - logs; - fingerprints; - pacote e camada associados. --- ## 3. Regras de geração ### 3.1 Convenções - utilizar prefixo próprio do MINEX 3D nos identificadores; - evitar colisões com os identificadores do MINEX 2D; - manter nomenclatura consistente entre `app`, `pre`, `links` e flows; - registrar apenas funcionalidades e contratos confirmados no código; - criar JSONL de `pre` somente quando houver processamento real associado; - criar JSONL de `links` somente quando houver vínculo efetivo entre app, backend e banco. Exemplos: ```text MINEX3D_ANALYSIS_IMPORTANT_FEATURES MINEX3D_ANALYSIS_VARIOGRAM MINEX3D_ANALYSIS_KRIGING MINEX3D_ANALYSIS_MINERAL_PROSPECTING MINEX3D_ANALYSIS_APPLY_MINERAL_PROSPECTING MINEX3D_ANALYSIS_LITHOLOGY MINEX3D_ANALYSIS_APPLY_LITHOLOGY MINEX3D_ANALYSIS_BOUNDD MINEX3D_ANALYSIS_BVA ``` ### 3.2 Restrições de pastas O coletor deve utilizar somente as raízes explicitamente configuradas para: - código do `GeotrixApp3D`; - rotinas de preparação/processamento referenciadas pelo app; - contratos de banco utilizados pelos fluxos; - testes e documentação associados. Regras obrigatórias: - não utilizar caminhos absolutos nos JSONL; - não incluir arquivos fora das raízes permitidas; - ignorar ambientes, caches, dependências instaladas, builds e dados brutos; - rejeitar referências inexistentes; - não misturar arquivos do MINEX 2D nos artefatos do MINEX 3D; - utilizar o MINEX 2D somente como referência de estrutura e formato. ### 3.3 Entradas esperadas Para cada campo identificado no código, registrar: - nome técnico; - descrição; - tipo esperado; - obrigatoriedade; - valor padrão; - limites; - enumerações; - dependências; - mensagem de validação; - transformação antes do envio ao processamento. --- ## 4. Atividades 1. Revisar os JSONL do MINEX 2D utilizados como modelo. 2. Configurar no coletor as raízes permitidas do MINEX 3D. 3. Identificar os arquivos associados às nove funcionalidades. 4. Identificar schedules, observers, reboots, componentes e funções auxiliares. 5. Identificar entrypoints, funções de processamento e chamadas de banco. 6. Mapear entradas, validações, eventos, outputs e artefatos. 7. Criar os JSONL de `app`. 8. Criar os JSONL de `pre`, quando aplicável. 9. Criar os JSONL de `links`, quando aplicável. 10. Atualizar `registry_flows.jsonl`. 11. Atualizar manifests, chunks e fingerprints. 12. Validar referências e consistência entre os cartões. 13. Criar casos mínimos de avaliação. --- ## 5. Critérios de aceite - As nove funcionalidades estão representadas no registry. - Boruta e FAMD estão identificados dentro de Important Features. - Os quatro algoritmos de Mineral Prospecting estão identificados. - Os três métodos de Lithology Classification estão identificados. - Entradas, validações e resultados estão documentados com base no código. - Cartões `pre` e `links` existem apenas quando houver contrato real. - `feature_id` e flows não possuem duplicatas. - Não existem caminhos absolutos. - Todas as referências apontam para arquivos existentes. - Os JSONL passam na validação estrutural. - `registry_flows.jsonl` está atualizado. - Os artefatos necessários ao RAG são gerados com sucesso. - Os conteúdos do MINEX 2D e MINEX 3D permanecem separados. --- ## 6. Entregáveis - coletor ajustado em `meantrix/geotrixapp3d_prod`; - JSONL de app; - JSONL de pre, quando aplicável; - JSONL de links, quando aplicável; - `registry_flows.jsonl`; - manifests; - chunks e fingerprints; - casos de avaliação; - evidências de validação. --- ## 7. Estimativa de esforço | Bloco | Horas | | --------------------------------------------------------- | -------: | | Revisão do formato do MINEX 2D e preparação do coletor 3D | 2 h | | Levantamento dos arquivos e fluxos | 4 h | | Mapeamento de entradas, validações, funções e outputs | 6 h | | Criação dos JSONL de app | 5 h | | Criação dos JSONL de pre e links | 4 h | | Registry, manifests, geração e validação final | 3 h | | **Total** | **24 h** | --- # Tarefa 2 — Adaptação e deployment da API `geotrixIA` para suporte ao MINEX 3D **Repositórios:** - `meantrix/geotrixia` — implementação da API; - `meantrix/geotrix3deploy` — imagem, manifests e deployment da API. ## Objetivo geral Adaptar a API `geotrixIA` para operar com os contextos MINEX 2D e MINEX 3D, selecionando corretamente o banco e os vector stores correspondentes a cada aplicação, e disponibilizar a versão adaptada no cluster por meio do fluxo de deployment do `geotrix3deploy`. A implementação deve reutilizar o fluxo já existente para o MINEX 2D, evitando duplicação de API. A diferença entre os produtos deve ser resolvida por configuração e por um identificador explícito de aplicação. --- ## 1. Identificação e configuração da aplicação Adicionar `app_id` às operações dependentes de contexto. Valores iniciais: - `minex2d`; - `minex3d`. O `app_id` deve determinar: - configuração de banco; - pool/repository utilizado; - vector stores associados; - metadata; - contexto funcional da conversa. Exemplo conceitual: ```python APP_CONTEXTS = { "minex2d": { "repository": minex2d_repository, "vector_store_ids": [MINEX2D_VECTOR_STORE_ID], }, "minex3d": { "repository": minex3d_repository, "vector_store_ids": [ MINEX3D_APP_VECTOR_STORE_ID, MINEX3D_BACKEND_VECTOR_STORE_ID, ], }, } ``` O banco não deve ser inferido apenas pelo `project_id`. --- ## 2. Seleção de banco Adaptar a camada de persistência da API para: - resolver o contexto por `app_id`; - selecionar credenciais e pool corretos; - utilizar repositories compatíveis com o contrato de chat; - manter pools separados; - impedir fallback silencioso; - retornar erro explícito para configuração ausente; - fechar os pools corretamente no shutdown; - preservar o padrão de chats, mensagens, metadata e `conversation_id`. As adequações devem ocorrer no `geotrixIA`, consumindo os contratos disponíveis para cada banco, sem ampliar o escopo para uma refatoração completa dos pacotes de banco. --- ## 3. Criação dos vector stores do MINEX 3D Criar: ### 3.1 MINEX 3D App Conteúdo: - artefatos de app; - instruções de uso; - entradas e validações; - componentes; - fluxos de interface; - chunks do `GeotrixApp3D`. ### 3.2 MINEX 3D Backend Conteúdo: - artefatos de pre e links; - funções de processamento; - contratos de banco; - tracking; - artefatos; - persistência; - falhas conhecidas. Atividades: - preparar arquivos; - criar os stores; - realizar upload; - validar processamento; - registrar IDs em configuração segura; - atualizar manifest; - executar consultas de smoke test. --- ## 4. Runtime, services e endpoints Adaptar a integração com a Responses API para: - utilizar o store atual no MINEX 2D; - utilizar os dois stores no MINEX 3D; - preservar `conversation_id`; - impedir troca de aplicação no mesmo chat; - registrar `app_id` e stores em metadata. Adaptar os services para: - criar, retomar e fechar chats no banco correto; - salvar mensagens no banco correto; - manter lock e status operacional; - registrar provider, modelo, uso, latência, status e erro. Adicionar `app_id` aos endpoints: - `POST /chat`; - `GET /projects/{project_id}/users/{user_id}/chats`; - `GET /chats/{chat_id}/messages`; - `POST /chats/{chat_id}/close`; - `POST /chats/{chat_id}/delete`. Exemplo: ```json { "app_id": "minex3d", "project_id": "project-id", "user_id": "user@example.com", "message": "Como configurar o variograma?", "feature_code": "MINEX3D_ANALYSIS_VARIOGRAM" } ``` --- ## 5. Deployment da API No `meantrix/geotrix3deploy`: - atualizar ou criar o Dockerfile da API; - declarar ambiente mínimo para FastAPI, Uvicorn, OpenAI, Pydantic e PostgreSQL; - atualizar Service e Deployment; - configurar variáveis e secrets dos dois bancos; - configurar IDs dos vector stores; - manter `readinessProbe` e `livenessProbe` em `/health`; - validar resources request/limit; - aplicar rollout; - executar smoke test pela URL interna do serviço. --- ## 6. Regras obrigatórias ### Proibido - inferir a aplicação apenas pelo `project_id`; - utilizar o banco 2D como fallback; - misturar vector stores; - recriar `conversation_id` de chat ativo; - versionar credenciais ou IDs sensíveis; - manter transação de banco aberta durante chamada externa. ### Obrigatório - `app_id` explícito; - registry central; - seleção conjunta de banco e RAG; - pools independentes; - metadata com aplicação; - erros controlados; - testes unitários sem OpenAI real; - validação do deployment. --- ## 7. Critérios de aceite - `app_id` implementado. - Banco selecionado corretamente. - Chats e mensagens 3D persistidos no banco correto. - Dois vector stores 3D criados e processados. - Runtime usa os stores correspondentes. - `conversation_id` é preservado. - Isolamento 2D/3D validado. - Imagem da API construída. - Deployment disponível no AKS. - `/health` retorna sucesso. - Smoke tests executados. - README e changelog atualizados. --- ## 8. Entregáveis - alterações no `meantrix/geotrixia`; - registry de aplicações; - pools/repositories por contexto; - services e endpoints atualizados; - dois vector stores 3D; - manifest de upload; - Dockerfile da API; - Service e Deployment; - configuração do AKS; - testes e documentação. --- ## 9. Estimativa de esforço | Bloco | Horas | | ------------------------------------------- | -------: | | `app_id`, registry e schemas | 2 h | | Seleção de banco, pool e repository | 3 h | | Criação e carga dos vector stores | 3 h | | Runtime GPT, services e endpoints | 3 h | | Imagem e deployment da API | 3 h | | Testes de isolamento, rollout e smoke tests | 2 h | | **Total** | **16 h** | --- # Tarefa 3 — Criação do `renv.prod.lock` do `geotrixViewer` **Repositório:** `meantrix/geotrixapp3d_prod` **Pacote:** `geotrixViewer` **Arquivo de referência:** `geotrixViewer/renv.lock` ## Objetivo geral Separar o ambiente de produção do ambiente de desenvolvimento do app 3D, removendo do lockfile de produção pacotes de processamento, machine learning, análise e importação que não sejam necessários para inicializar e operar a interface Shiny. O `renv.lock` atual deve continuar representando o ambiente completo de desenvolvimento. Um novo ambiente de produção deve representar apenas as dependências necessárias ao runtime. A implementação preferencial é utilizar um **perfil `renv` de produção**, mantendo o lockfile em `renv/profiles/production/renv.lock`. Caso o pipeline atual exija o nome `renv.prod.lock`, esse arquivo deve ser gerado por script a partir do perfil, evitando manutenção manual de dois estados independentes. --- ## 1. Diagnóstico do lockfile atual O `geotrixViewer/renv.lock` atual (R 4.4.2, ~300 pacotes) inclui grupos que não devem constar na imagem de produção do app: | Grupo | Pacotes identificados no lockfile | Peso estimado instalado | | ---------------------------- | ------------------------------------------------------------ | ----------------------: | | Machine learning / H2O | `h2o` v3.44.0.3, `Boruta`, `ranger`, `caret`, `hardhat`, `gower`, `ipred`, `prodlim`, `ModelMetrics` | ~1,1 GB | | Análise e clustering | `Causata` (via GitHub, deps: `RMySQL`, `XML`, `glmnet`, `foreach`), `RANN`, `clue`, `cluster` | ~150 MB | | Azure SDK | `AzureAuth`, `AzureGraph`, `AzureRMR`, `AzureStor` | ~80 MB | | Importação de dados | `haven`, `readr`, `clock`, `hdf5r` | ~120 MB | | Visualização opcional | `gridExtra`, `gtable` | ~20 MB | | **Total estimado a remover** | | **~1,47 GB** | O problema de origem é que o `renv.lock` foi gerado com `renv::snapshot()` sem `type = "explicit"`, capturando todo o ambiente de desenvolvimento, incluindo pacotes de ML, análise e processamento que são utilizados exclusivamente nos pods. --- ## 2. Implementação prevista Geração do lockfile de produção: ```r # Executar dentro do projeto geotrixViewer, com ambiente limpo renv::snapshot( type = "explicit", # respeita somente DESCRIPTION::Imports packages = NULL, prompt = FALSE ) ``` O resultado deve ser salvo como: ```text geotrixViewer/renv.prod.lock ``` Comparação e evidência: ```r dev <- renv::lockfile_read("renv.lock") prod <- renv::lockfile_read("renv.prod.lock") removidos <- setdiff(names(dev$Packages), names(prod$Packages)) cat(length(removidos), "pacotes removidos do lock de produção:\n") writeLines(sort(removidos)) ``` A comparação deve ser registrada como evidência, distinguindo: - pacotes mantidos em produção; - pacotes exclusivos de desenvolvimento/processamento; - dependências transitivas removidas; - exceções que precisaram permanecer (com justificativa). --- ## 3. Regras - Não remover dependência usada no startup ou runtime real do app. - Não usar somente inspeção visual do `DESCRIPTION`; validar chamadas diretas e dinâmicas no código. - Preservar a versão de R (4.4.2) e os repositórios declarados no lockfile. - Garantir que o lockfile seja reproduzível em ambiente limpo (`renv::restore()` em biblioteca vazia). - Não substituir o `renv.lock` completo de desenvolvimento. --- ## 4. Critérios de aceite - `renv.prod.lock` criado em `geotrixViewer/`. - `renv::restore()` executado com sucesso em biblioteca limpa. - App `geotrixViewer` carrega e atinge readiness com o lockfile de produção. - Pacotes de processamento, ML e importação ausentes do lock de produção quando não forem dependências transitivas ou requisitos comprovados do runtime; toda exceção deve ser documentada. - Diferenças entre dev e prod documentadas com contagem e listagem. - Versão de R no lock exatamente compatível com a variante correspondente da `base_image_app`. - Lockfile versionado no repositório. --- ## 5. Entregáveis - `geotrixViewer/renv.prod.lock`; - script de geração e validação; - relatório de diferenças (pacotes removidos, mantidos, exceções); - evidência de restore limpo (log ou saída de terminal); - atualização do README do pacote. --- ## 6. Estimativa de esforço | Bloco | Horas | | ----------------------------------------------------- | -------: | | Auditoria do lockfile e das dependências reais do app | 3 h | | Geração do lockfile explícito | 2 h | | Ajustes e tratamento de exceções necessárias | 3 h | | Restore limpo e validação do app | 3 h | | Documentação e evidências | 1 h | | **Total** | **12 h** | --- # Tarefa 4 — Criação do `renv.prod.lock` do `geotrixMap` **Repositório:** `meantrix/geotrixMap` **Pacote:** `geotrixMap` **Arquivo de referência:** `geotrixMap/renv.lock` ## Objetivo geral Criar um ambiente de produção enxuto para o app 2D, separando as dependências necessárias à interface das dependências de desenvolvimento, processamento, Azure SDK, relatórios e machine learning. A implementação deve seguir o mesmo padrão do app 3D: perfil `renv` de produção como fonte de verdade e, somente quando necessário para compatibilidade com o pipeline, geração automatizada do arquivo `renv.prod.lock`. --- ## 1. Diagnóstico do lockfile atual O `geotrixMap/renv.lock` atual (R 4.4.2) contém grupos pesados que não devem constar na imagem de produção do app: | Grupo | Pacotes identificados | Peso estimado instalado | | ---------------------------- | ------------------------------------------------------------ | ----------------------: | | Azure SDK | `AzureAuth`, `AzureGraph`, `AzureRMR`, `AzureStor` | ~80 MB | | Machine learning | `Boruta`, `ranger`, `caret` e dependências transitivas | ~700 MB | | Relatórios | `rmarkdown`, `kableExtra`, `blastula` e dependências | ~150 MB | | Geoespacial pesado | `raster` e dependências | ~120 MB | | Backend de dados | `geotrix`, `geotrixdb`, `geotrix2db` (se não carregados no startup) | a validar | | **Total estimado a remover** | | **~1,05 GB** | A mesma causa raiz da Tarefa 3 se aplica: o lockfile foi gerado sem `type = "explicit"`, capturando o ambiente completo de desenvolvimento. --- ## 2. Implementação - gerar `renv.prod.lock` com `renv::snapshot(type = "explicit")`; - manter o `renv.lock` completo para desenvolvimento; - comparar os dois locks e documentar diferenças; - restaurar o lockfile de produção em biblioteca limpa; - inicializar o app e validar os fluxos principais da interface; - documentar exceções com justificativa. --- ## 3. Critérios de aceite - `geotrixMap/renv.prod.lock` criado. - `renv::restore()` executado com sucesso em biblioteca limpa. - App 2D inicializa e atinge readiness. - Pacotes de ML, Azure SDK, relatórios e geoprocessamento ausentes do lock de produção quando confirmado o não uso no runtime; dependências transitivas e exceções devem ser documentadas. - Diferenças dev/prod documentadas. - Lockfile compatível com `base_image_app`. --- ## 4. Entregáveis - `geotrixMap/renv.prod.lock`; - script de geração e comparação; - relatório de diferenças; - evidências de restore e startup; - atualização do README. --- ## 5. Estimativa de esforço | Bloco | Horas | | ------------------------------------------------------- | ------: | | Auditoria de dependências e validação de uso no runtime | 2 h | | Geração e ajuste do lockfile | 2 h | | Restore em biblioteca limpa | 2 h | | Testes do app e documentação | 2 h | | **Total** | **8 h** | --- # Tarefa 5 — Refatoração dos `DESCRIPTION` dos apps 2D e 3D **Repositórios:** - `meantrix/geotrixMap` — arquivo `geotrixMap/DESCRIPTION`; - `meantrix/geotrixapp3d_prod` — arquivo `geotrixViewer/DESCRIPTION`. ## Objetivo geral Reorganizar as dependências dos pacotes para que `Imports` represente somente o runtime obrigatório dos apps, enquanto dependências de processamento, análise, geração de relatórios e desenvolvimento sejam transferidas para `Suggests` quando tecnicamente apropriado. Essa alteração garante que futuras execuções de `renv::snapshot(type = "explicit")` continuem produzindo lockfiles de produção coerentes, sem risco de regressão ao ambiente de dev. --- ## 1. Dependências candidatas no app 2D (`geotrixMap/DESCRIPTION`) O `DESCRIPTION` atual do `geotrixMap` (v2.10.0) lista 56 pacotes em `Imports`. Os candidatos à revisão são: | Pacote/grupo | Ação proposta | Condição | | ------------------------------------------------------------ | --------------------- | ------------------------------------------------------------ | | `geotrix`, `geotrixdb`, `geotrix2db` | mover para `Suggests` | somente se não forem carregados no startup nem chamados diretamente pela UI | | `caret`, `corrp`, `raster` | mover para `Suggests` | processamento/análise utilizado somente em pods | | `rmarkdown`, `kableExtra`, `blastula` | mover para `Suggests` | geração de relatórios fora do fluxo básico da UI | | `ggplot2`, `reshape2` | revisar | manter em `Imports` se chamados diretamente por módulos de UI | | `shinyAce`, `leafem`, `leafpm`, `leaflet.extras`, `leaflet.multiopacity` | revisar | validar se são carregados condicionalmente ou somente em módulos opcionais | | `RCurl` | revisar | validar se permanece necessário com a remoção dos Azure SDKs | ## 2. Dependências candidatas no app 3D (`geotrixViewer/DESCRIPTION`) O `DESCRIPTION` atual do `geotrixViewer` (v5.7.0) lista 47 pacotes em `Imports`. Os candidatos à revisão são: | Pacote/grupo | Ação proposta | Condição | | -------------------------------------- | --------------------- | ------------------------------------------------------------ | | `geotrix3D`, `geotrixdb`, `geotrix3db` | mover para `Suggests` | somente se o processamento ocorrer exclusivamente em pod e não houver chamada direta no startup do app | | `RANN`, `caret`, `corrp` | mover para `Suggests` | processamento/análise utilizado somente em pods | | `rmarkdown`, `kableExtra`, `blastula` | mover para `Suggests` | relatórios opcionais | | `ggplot2`, `reshape2` | revisar | manter em `Imports` se usados diretamente pela UI | | `shinyAce` | revisar | verificar necessidade no runtime da interface | --- ## 3. Validação obrigatória Antes de mover cada pacote: - buscar chamadas `library()`, `require()`, `pkg::fun()` e carregamentos dinâmicos (`loadNamespace`, `requireNamespace`); - verificar uso no `.onLoad`, `.onAttach` e `app_server`; - verificar módulos carregados condicionalmente via `shiny::moduleServer` ou `golem`; - executar `R CMD check --as-cran` após cada alteração; - executar testes dos apps (`testthat`); - executar startup em biblioteca que contenha somente os `Imports` declarados. Dependências utilizadas somente em testes devem permanecer em `Suggests`. --- ## 4. Critérios de aceite - `DESCRIPTION` dos dois apps revisados e versionados. - `Imports` contém somente runtime obrigatório da interface. - `Suggests` contém opcionais, testes, relatórios e processamento. - `R CMD check` executado sem erros causados pela alteração. - Apps inicializam com dependências de produção (somente `Imports`). - `renv.prod.lock` permanece estável após nova geração (`renv::snapshot(type = "explicit")`). --- ## 5. Entregáveis - `DESCRIPTION` atualizado no app 2D (`geotrixMap/DESCRIPTION`); - `DESCRIPTION` atualizado no app 3D (`geotrixViewer/DESCRIPTION`); - evidência de busca de uso (grep/ast de chamadas por pacote); - resultados de `R CMD check` para os dois apps; - testes de inicialização em biblioteca limpa; - documentação da decisão por pacote (manter / mover / excluir). --- ## 6. Estimativa de esforço | Bloco | Horas | | ----------------------------------------------------------- | ------: | | Auditoria do `DESCRIPTION` e chamadas do app 2D | 2 h | | Auditoria do `DESCRIPTION` e chamadas do app 3D | 2 h | | Alterações nos dois `DESCRIPTION` e ajustes de carregamento | 2 h | | `R CMD check` e validação de startup dos dois apps | 2 h | | **Total** | **8 h** | --- # Tarefa 6 — Criação da `base_image_app` enxuta **Repositório:** `meantrix/geotrix3deploy` **Branch de trabalho:** `chat_ia` **Arquivo a criar:** `geotrix3d-terra/docker_deploy/modules/base_image_app/Dockerfile` ## Objetivo geral Criar uma **família de bases de aplicação** contendo R e dependências de runtime da interface, mas sem os componentes de processamento que hoje aumentam o tamanho, o tempo de build e a superfície de manutenção. As bases atuais (`base_image` com R 3.6.3 e `base_image4` com R 4.4.1), ambas localizadas em `geotrix3d-terra/docker_deploy/modules/`, compilam VTK e Qhull a partir do código-fonte via `cmake && make`, instalam Java, Miniconda e o toolchain completo (`gcc-10`, `g++-10`, `gfortran-10`, `libboost-all-dev`, `cmake`), e os deixam presentes na imagem final sem possibilidade de remoção por camadas Docker anteriores. Esses componentes são necessários somente para os pods de processamento e não devem existir nas imagens de aplicação. Como há duas linhas de R em uso, não se deve substituir tudo por uma única imagem com “R estável”. Deve ser adotado um dos caminhos: 1. **preferencial:** descontinuar as variantes R 3.6.3 após validação e manter somente a linha R 4.4.x; 2. **compatibilidade temporária:** gerar `base_image_app-r36` e `base_image_app-r44` a partir do mesmo template, com versões e digests fixos. A família de bases deve ser utilizada por: - `app_image` — localizada em `geotrix3d-terra/docker_deploy/modules/app_image/`; - `app_image2d` — em `geotrix3d-terra/docker_deploy/modules/app_image2d/`; - `app_image4` — em `geotrix3d-terra/docker_deploy/modules/app_image4/`; - `app_image2d4` — em `geotrix3d-terra/docker_deploy/modules/app_image2d4/`. --- ## 1. Componentes que devem permanecer - sistema operacional com suporte de segurança ativo; Ubuntu 20.04 somente como exceção temporária coberta por ESM/Ubuntu Pro ou base interna corrigida; - versão exata de R compatível com cada variante (`r36` ou `r44`), nunca uma versão dinâmica “estável”; - bibliotecas de runtime necessárias aos pacotes de UI — versões de runtime (`.so`), não headers (`-dev`): - `libcairo2`, `libxt6` — renderização gráfica do R; - `libssl1.1`, `libcurl4` — comunicação HTTPS; - `libgeos-c1v5`, `libgdal26`, `libproj15`, `libudunits2-0` — geoespacial runtime; - `libpq5` — cliente PostgreSQL; - `libxml2`, `libsodium23` — parsing e criptografia; - `libmagick++-6.q16-8` — ImageMagick runtime para pacotes de imagem; - `libnetcdf19`, `libhdf5-103` — formatos de dados científicos, runtime apenas; - `libfontconfig1`, `libfreetype6` — fontes para renderização; - Pandoc — quando houver renderização de markdown indispensável no app; - certificados, locale e utilitários mínimos (`wget`, `curl`, `ca-certificates`); - usuário e grupo não privilegiados para executar o app; - imagem-base fixada por tag imutável e digest; - `.dockerignore` para excluir repositórios, caches, locks não utilizados, dados e artefatos locais. ## 2. Componentes que não devem permanecer | Componente | Presente nas bases atuais | Motivo da remoção | | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | | VTK (compilado de fonte) | `base_image` L110–117, `base_image4` L148–155 | utilizado exclusivamente pelos pods; compilação gera +2–4 GB de artefatos em camadas | | Qhull (compilado de fonte) | `base_image` L119–121, `base_image4` L157–159 | idem | | Java / OpenJDK 11 | `base_image` L79–85, `base_image4` L132–138 | necessário somente para H2O nos pods | | Miniconda + ambiente conda | `base_image` L123–146, `base_image4` L162–184 | Python de processamento; apps Shiny não utilizam Python | | CMake | `base_image` L55, `base_image4` L61 | toolchain de compilação, não necessário no runtime | | `libboost-all-dev` | `base_image` L57, `base_image4` L62 | metapacote ~500 MB, necessário somente para compilar VTK | | `libglu1-mesa-dev`, `freeglut3-dev`, `mesa-common-dev`, `libglvnd-dev` | ambas as bases | headers de renderização 3D; apps usam apenas rendering 2D via Cairo | | `gcc-10`, `g++-10`, `gfortran-10` e toolchain | `base_image` L89–99, `base_image4` L100–113 | compiladores; removidos da imagem final pelo multi-stage na Tarefa 7 | | Headers `-dev` de geoespacial | ambas as bases | necessários para compilar pacotes R, não para executá-los; ficam no stage builder da Tarefa 7 | | Cache `apt` em camadas separadas | ambas as bases (múltiplos `RUN apt-get` sem `rm -rf /var/lib/apt/lists/*`) | acumula 200–400 MB de cache em camadas intermediárias | | `VTK.tar.gz`, `qhull.tar.gz` | copiados via `COPY` e jamais removidos antes do `rm -rf` | os arquivos `.tar.gz` ficam em camadas anteriores ao `rm`, não sendo recuperados | --- ## 3. Exemplo estrutural ```dockerfile ARG UBUNTU_IMAGE="<acr>/ubuntu-focal-esm:r44@sha256:<digest-validado>" FROM ${UBUNTU_IMAGE} ENV DEBIAN_FRONTEND=noninteractive \ TZ=UTC \ LC_ALL=en_US.UTF-8 \ LANG=en_US.UTF-8 # Um único RUN consolida atualização, instalação e limpeza na mesma camada RUN apt-get update && apt-get install -y --no-install-recommends \ locales ca-certificates wget curl \ libcairo2 libxt6 libssl1.1 libcurl4 \ libgeos-c1v5 libgdal26 libproj15 libudunits2-0 \ libpq5 libxml2 libsodium23 libfontconfig1 libfreetype6 \ libmagick++-6.q16-8 libnetcdf19 libhdf5-103 \ pandoc lsb-release software-properties-common dirmngr gnupg2 \ && echo "en_US.UTF-8 UTF-8" >> /etc/locale.gen \ && locale-gen \ && wget -qO- https://cloud.r-project.org/bin/linux/ubuntu/marutter_pubkey.asc \ | tee /etc/apt/trusted.gpg.d/cran_ubuntu_key.asc \ && add-apt-repository \ "deb https://cloud.r-project.org/bin/linux/ubuntu $(lsb_release -cs)-cran40/" \ && apt-get update \ && apt-get install -y --no-install-recommends r-base \ && rm -rf /var/lib/apt/lists/* RUN groupadd --gid 10001 meantrix \ && useradd --uid 10001 --gid meantrix --create-home meantrix USER 10001:10001 ``` > O exemplo preserva temporariamente a compatibilidade com Ubuntu 20.04 por meio de uma base interna coberta por ESM. Não se deve reconstruir a variante R 3.6.3 a partir de um repositório CRAN dinâmico: ela deve reutilizar uma base legada fixada por digest ou ser descontinuada. A migração para Ubuntu 22.04/24.04 deve ser tratada em ciclo próprio. > > O conjunto final de bibliotecas deve ser confirmado pelos testes reais de instalação e runtime a partir do `renv.prod.lock` (Tarefas 3 e 4). O exemplo acima representa a arquitetura pretendida, não uma lista imutável. Bibliotecas ausentes serão adicionadas durante os testes da Tarefa 7. --- ## 4. Validações - build concluído sem VTK, Qhull, Java, Miniconda e compiladores; - execução de `R --version` dentro do container; - carregamento das bibliotecas de runtime essenciais (`shiny`, `golem`, `leaflet`, `sf`); - validação com `ldd` das extensões compiladas para detectar bibliotecas compartilhadas ausentes; - instalação de pacote simples no stage builder derivado (validar Tarefa 7); - inspeção de camadas com `docker history --no-trunc <imagem>`; - medição de tamanho com `docker image inspect <imagem>`. --- ## 5. Critérios de aceite - família `base_image_app` construída com sucesso, com variante explícita por versão de R enquanto coexistirem R 3.6.3 e R 4.4.x. - Nenhum componente de processamento presente (VTK, Qhull, Java, Miniconda, compiladores, cmake, boost). - Cache `apt` removido na mesma instrução `RUN`. - Imagem reproduzível a partir do Dockerfile versionado. - Apps conseguem utilizá-la como `ARG BASE_IMAGE` no stage runtime da Tarefa 7. - Tamanho final e número de camadas registrados. - Tags imutáveis e digests registrados no ACR. - Processo final executado como usuário não privilegiado. - Situação de suporte do sistema operacional documentada. --- ## 6. Entregáveis - template/Dockerfile da família `base_image_app`, com targets ou variantes por versão de R; - script ou target de build integrado ao pipeline existente; - documentação de dependências (bibliotecas incluídas e justificativa); - tag publicada no ACR; - relatório de tamanho e camadas. --- ## 7. Estimativa de esforço | Bloco | Horas | | ------------------------------------------------------------ | -------: | | Auditoria das bases atuais (`base_image` e `base_image4`) e identificação de componentes por imagem | 2 h | | Construção do Dockerfile com runtime libs | 4 h | | Ajustes de bibliotecas de runtime identificadas nos testes | 3 h | | Build, medição de tamanho e validação | 2 h | | Documentação e integração inicial ao pipeline | 1 h | | **Total** | **12 h** | --- # Tarefa 7 — Multi-stage build das quatro imagens de aplicação **Repositório:** `meantrix/geotrix3deploy` **Branch de trabalho:** `chat_ia` **Arquivos a modificar:** - `geotrix3d-terra/docker_deploy/modules/app_image/Dockerfile` - `geotrix3d-terra/docker_deploy/modules/app_image2d/Dockerfile` - `geotrix3d-terra/docker_deploy/modules/app_image4/Dockerfile` - `geotrix3d-terra/docker_deploy/modules/app_image2d4/Dockerfile` **Arquivos a criar:** - `geotrix3d-terra/docker_deploy/modules/app_image/docker-entrypoint.sh` (e equivalentes para os outros três módulos) ## Objetivo geral Reescrever as quatro imagens de aplicação utilizando multi-stage build, separando a etapa de compilação e instalação de pacotes R da imagem final de runtime. A lógica compartilhada deve ficar em um template comum, Dockerfile parametrizado ou geração automatizada. Os quatro módulos devem conter apenas diferenças declarativas de versão, pacote principal e comando de inicialização, evitando quatro Dockerfiles independentes e divergentes. --- ## 1. Problemas nos Dockerfiles atuais Os quatro Dockerfiles de app possuem os seguintes problemas em comum: | Problema | Localização nos arquivos atuais | Impacto | | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | | Cada pacote R instalado com `COPY *.tar.gz` + `RUN R -e install_local` separados | `app_image/Dockerfile` L91–124, `app_image2d/Dockerfile` L82–111 | cada par cria uma camada com o `.tar.gz` permanente, pois o arquivo foi copiado em camada anterior | | `apt-get install libhdf5-serial-dev` sem `apt-get update` nem limpeza de cache | `app_image/Dockerfile` L75, `app_image2d/Dockerfile` L56 | instalação instável e cache residual | | `az login` e `az aks get-credentials` executados durante o build | todos os quatro, ex: `app_image/Dockerfile` L62–66 | credenciais gravadas em camada Docker; build não-determinístico e inseguro | | `renv::restore()` usa o lockfile completo de desenvolvimento (~300 pacotes) | todos os quatro, ex: `app_image/Dockerfile` L88 | instala h2o, Boruta, caret e demais pacotes de ML que não são necessários no app | | Headers `-dev` e compiladores herdados da base atual ficam no runtime | ambas as bases + imagens filhas | ~800 MB de toolchain desnecessário na imagem final | | `kubectl` instalado em três instruções `RUN` separadas | `app_image/Dockerfile` L56–60 | gera três camadas para um único binário | | `remotes` e `renv` instalados em `RUN` separados | todos os quatro, ex: `app_image2d/Dockerfile` L72–75 | camadas desnecessárias para bootstrap | --- ## 2. Arquitetura do multi-stage ### Stage `builder` Responsável por: - partir da `base_image_app` (criada na Tarefa 6); - instalar headers de compilação (`-dev`) somente neste stage — eles não chegam ao runtime; - executar `renv::restore()` com `renv.prod.lock` (criado nas Tarefas 3 e 4); - instalar os pacotes internos (`.tar.gz`) com todos os artefatos em uma única camada, removendo os `.tar.gz` na mesma instrução `RUN`; - validar a biblioteca R resultante. ### Stage `runtime` Responsável por: - herdar `base_image_app` como base limpa, sem toolchain; - receber somente a biblioteca R compilada via `COPY --from=builder`; - instalar apenas ferramentas de runtime necessárias (`kubectl` via binário estático, Azure CLI); - executar o app sem toolchain, sem headers, sem `.tar.gz` residuais; - autenticar no Azure somente na inicialização do container, nunca durante o build. --- ## 3. Diferenças por imagem | Imagem | Base prevista | Ambiente R | Pacotes internos de runtime | CMD | | -------------- | ------------------------------------------------------ | ------------------------------------ | ------------------------------------------------------------ | -------------------------- | | `app_image` | `geotrix-app-base:r36` enquanto a linha legada existir | perfil production do `geotrixViewer` | somente pacotes comprovadamente necessários à UI, incluindo `geotrixApp` e `geotrixViewer` | `geotrixViewer::run_app()` | | `app_image4` | `geotrix-app-base:r44` | perfil production do `geotrixViewer` | somente pacotes comprovadamente necessários à UI | `geotrixViewer::run_app()` | | `app_image2d` | `geotrix-app-base:r36` enquanto a linha legada existir | perfil production do `geotrixMap` | somente pacotes comprovadamente necessários à UI, incluindo `geotrixApp` e `geotrixMap` | `geotrixMap::run_app()` | | `app_image2d4` | `geotrix-app-base:r44` | perfil production do `geotrixMap` | somente pacotes comprovadamente necessários à UI | `geotrixMap::run_app()` | Pacotes como `geotrix3D`, `geotrix3db`, `geotrix`, `geotrix2db`, `gstat`, `hdf5r`, `dtwclust`, `caret` e H2O **não devem ser reinstalados manualmente nas app images** após serem removidos do runtime, salvo exceção comprovada pela auditoria da Tarefa 5. Reinstalá-los por `.tar.gz` anularia parte central da redução proposta. Para relatórios PDF, deve haver uma decisão explícita: - **preferencial:** renderização executada em pod/job dedicado; TeX permanece fora da app image; - **exceção:** se o app renderizar PDF durante o runtime, o conjunto mínimo de TeX deverá existir no stage runtime, e não somente no builder. --- ## 4. Exemplo ```dockerfile ARG BASE_IMAGE="meantrix/geotrix-app-base:r44@sha256:<digest-validado>" # ── Stage 1: builder ───────────────────────────────────────────────────────── FROM ${BASE_IMAGE} AS builder # Headers de compilação — ficam SOMENTE neste stage, não chegam ao runtime RUN apt-get update && apt-get install -y --no-install-recommends \ build-essential pkg-config \ libssl-dev libcurl4-openssl-dev \ libhdf5-dev libmagick++-dev \ libharfbuzz-dev libfribidi-dev \ && rm -rf /var/lib/apt/lists/* # renv.prod.lock — gerado na Tarefa 3 ou 4, ~150 pacotes vs ~300 do lock atual COPY renv.prod.lock /renv.lock RUN Rscript -e ' \ install.packages(c("remotes", "renv"), repos="https://cran.r-project.org"); \ renv::restore(lockfile="/renv.lock", library="/usr/local/lib/R/library") \ ' # Artefatos R em diretório próprio; o build context deve ser filtrado por .dockerignore. COPY r-packages/*.tar.gz /pkgs/ RUN Rscript -e ' \ pkgs <- list.files("/pkgs", pattern="\\.tar\\.gz$", full.names=TRUE); \ invisible(lapply(pkgs, remotes::install_local, \ upgrade=FALSE, dependencies=FALSE)); \ ' && rm -rf /pkgs # ── Stage 2: runtime ───────────────────────────────────────────────────────── FROM ${BASE_IMAGE} AS runtime # Somente configurações não sensíveis podem ser definidas no build. ARG POD_IMAGE JOB_NAMESPACE MAX_MEM_DRILL ENV podimage=$POD_IMAGE \ jobnamespace=$JOB_NAMESPACE \ MAX_MEM_DRILL=$MAX_MEM_DRILL \ HOME=/home/meantrix # Credenciais de banco, storage e Azure NÃO entram em ARG/ENV do Dockerfile. # São injetadas no runtime por Kubernetes Secret, CSI/Key Vault ou Workload Identity. # kubectl é mantido apenas se o código atual ainda o exigir. # A versão e o SHA256 devem ser fixados; não utilizar stable.txt em build reprodutível. ARG KUBECTL_VERSION="<versao-validada>" ARG KUBECTL_SHA256="<sha256-validado>" RUN curl -fsSLo /usr/local/bin/kubectl \ "https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/amd64/kubectl" \ && echo "${KUBECTL_SHA256} /usr/local/bin/kubectl" | sha256sum -c - \ && chmod +x /usr/local/bin/kubectl # Copia APENAS a biblioteca R compilada do stage builder # Sem toolchain, sem headers, sem .tar.gz, sem cache apt COPY --from=builder /usr/local/lib/R/library /usr/local/lib/R/library USER root RUN mkdir -p $HOME && chown -R 10001:10001 $HOME COPY docker-entrypoint.sh /docker-entrypoint.sh RUN chmod +x /docker-entrypoint.sh USER 10001:10001 WORKDIR $HOME EXPOSE 3838 ENTRYPOINT ["/docker-entrypoint.sh"] CMD ["R", "-e", "options('shiny.port'=3838, shiny.host='0.0.0.0'); geotrixViewer::run_app()"] ``` --- ## 5. Identidade, RBAC e entrypoint Como o app já é executado dentro do AKS, ele não deve executar `az login` nem `az aks get-credentials`. O acesso ao Kubernetes deve utilizar uma ServiceAccount própria, vinculada a um `Role`/`RoleBinding` restrito ao namespace e aos recursos necessários para criar e consultar os jobs. Para acesso a serviços Azure, utilizar Microsoft Entra Workload Identity. Se ainda houver dependência temporária de secrets, eles devem ser injetados no runtime por Kubernetes Secrets ou CSI/Key Vault, nunca por `ARG` de build. O entrypoint deve permanecer mínimo: ```bash #!/bin/bash set -euo pipefail exec "$@" ``` A Azure CLI deve ser removida das app images, salvo requisito residual documentado. O `kubectl` também deve ser removido quando a submissão de jobs for migrada para cliente da API Kubernetes; enquanto permanecer, deve utilizar automaticamente a configuração in-cluster da ServiceAccount. --- ## 6. Estimativa de redução por imagem Os valores abaixo são baseados na análise dos componentes removidos e servem como referência para as medições da Tarefa 10. | Componente removido da imagem final | `app_image2d` / `app_image2d4` | `app_image` / `app_image4` | | ------------------------------------------------------------ | -----------------------------: | -------------------------: | | Toolchain build (gcc, cmake, headers -dev) herdado da base atual | −800 MB | −800 MB | | renv.lock enxuto (~150 pacotes vs ~300): h2o, Boruta, caret e deps | −1,05 GB | −1,45 GB | | .tar.gz residuais em camadas Docker | −150 MB | −200 MB | | Cache apt não consolidado | −200 MB | −200 MB | | Python/Miniconda (presente na base atual, ausente na base_image_app) | −1,2 GB | −1,2 GB | | VTK/Qhull compilados (presentes na base atual) | −500 MB | −500 MB | | Java/OpenJDK (presente na base atual) | −300 MB | −300 MB | | texlive-latex-extra substituído por base+fonts (somente `*4`) | — | −400 MB | | **Total estimado** | **~4,2 GB** | **~5,05 GB** | --- ## 7. Atividades 1. Criar template comum de multi-stage build. 2. Adaptar os quatro Dockerfiles. 3. Integrar `renv.prod.lock` de cada app. 4. Revisar instalação dos pacotes internos (lista por imagem na seção 3). 5. Consolidar COPY + RUN dos `.tar.gz` em instrução única com limpeza. 6. Remover `az login` e `az aks get-credentials` do build. 7. Criar ServiceAccount e RBAC mínimo para submissão/consulta dos jobs. 8. Remover Azure CLI; manter `kubectl` apenas como compatibilidade temporária, com versão e checksum fixos. 9. Construir as quatro imagens localmente. 10. Testar inicialização local de cada app. 11. Medir tamanho e número de camadas de cada imagem. --- ## 8. Critérios de aceite - Quatro imagens convertidas para multi-stage. - Toolchain de compilação ausente no stage runtime. - `renv.prod.lock` utilizado em cada imagem. - Pacotes internos de backend não reinstalados nas app images, salvo exceções comprovadas. - Pacotes internos de runtime instalados corretamente em cada imagem. - Estratégia de geração de PDF definida e testada no local onde será executada. - Nenhum `.tar.gz` presente na imagem final. - Nenhuma credencial gravada em camada ou no `docker inspect`. - Processos executam como usuário não privilegiado. - ServiceAccount e RBAC mínimo validados. - Apps inicializam e atingem readiness local. - Tamanho final de cada imagem medido e registrado. - Imagens versionadas e enviadas ao ACR. --- ## 9. Entregáveis - quatro Dockerfiles reescritos; - template comum de multi-stage; - entrypoint comum e mínimo reutilizado pelas quatro imagens; - scripts de build; - relatório comparativo de tamanho antes/depois; - tags das imagens no ACR. --- ## 10. Estimativa de esforço | Bloco | Horas | | ------------------------------------------------------------ | -------: | | Template comum e estratégia de build | 4 h | | Adaptação das duas imagens 2D (`app_image2d` e `app_image2d4`) | 5 h | | Adaptação das duas imagens 3D (`app_image` e `app_image4`) | 5 h | | Integração de `renv.prod.lock` e pacotes internos | 4 h | | Entrypoint, Azure CLI e `kubectl` | 2 h | | Builds locais, correções e validação | 4 h | | **Total** | **24 h** | --- # Tarefa 8 — Criação da `base_image_proc` e encapsulamento Python de VTK/Qhull **Repositório:** `meantrix/geotrix3deploy` **Branch de trabalho:** `chat_ia` **Arquivos a criar:** - `geotrix3d-terra/docker_deploy/modules/base_image_proc/Dockerfile` - `geotrix3d-terra/docker_deploy/modules/base_image_proc/environment_proc.yml` - `geotrix3d-terra/docker_deploy/modules/geotrix3d-native/` (pacote Python interno) ## Objetivo geral Criar uma **família de bases de processamento** contendo runtime Java, ambiente Python com VTK e Qhull via Conda (binários pré-compilados), sem compilar essas bibliotecas a partir do código-fonte. Enquanto coexistirem as linhas R 3.6.3 e R 4.4.x, devem existir variantes `geotrix-proc-base:r36` e `geotrix-proc-base:r44` geradas pelo mesmo template. A alternativa preferencial continua sendo descontinuar a linha R 3.6.3 após validação. Também deve ser criado um pacote Python interno (`geotrix3d_native`) que encapsule as funções de VTK e Qhull chamadas pelo R via `reticulate`, reduzindo o acoplamento entre scripts R e detalhes de importação e execução Python. O pacote pode ser inicialmente mantido dentro do `geotrix3deploy` para viabilizar a migração, mas essa organização deve ser tratada como transitória. Como prática de manutenção, o código Python deve evoluir em repositório/pacote próprio ou junto ao código de processamento, enquanto o `geotrix3deploy` consome um artefato versionado. --- ## 1. Problema nas bases atuais As bases `base_image` e `base_image4` compilam VTK e Qhull a partir do código-fonte: ```dockerfile # base_image4/Dockerfile — linhas 148–159 RUN tar -xvf VTK.tar.gz && \ cd VTK && mkdir build && cd ./build && \ cmake .. && make && make install RUN rm -rf VTK RUN tar -xvf qhull.tar.gz && cd qhull && make && make install RUN rm -rf qhull ``` O `rm -rf VTK` e `rm -rf qhull` não recuperam o espaço ocupado pelos artefatos de build: esses artefatos já foram gravados em camadas Docker anteriores e permanecem na imagem para sempre. A única forma de eliminar esse espaço é por multi-stage build, transferindo apenas os binários compilados para o stage final — ou, preferencialmente, substituindo a compilação por pacotes Conda pré-compilados, o que elimina completamente a necessidade de cmake, make e toolchain na imagem de processamento. --- ## 2. Estrutura proposta do pacote Python ```text geotrix3d-terra/docker_deploy/modules/geotrix3d-native/ ├── pyproject.toml ├── geotrix3d_native/ │ ├── __init__.py │ ├── vtk_utils.py │ └── qhull_utils.py └── tests/ ├── test_vtk_utils.py └── test_qhull_utils.py ``` Responsabilidades: - `vtk_utils.py`: wrappers das operações VTK utilizadas pelo R, inventariadas no início desta tarefa; - `qhull_utils.py`: wrappers de geometria e triangulação implementados preferencialmente sobre `scipy.spatial`, que utiliza Qhull internamente; - validação de argumentos de entrada; - conversão previsível entre objetos R (via `reticulate`), NumPy e resultados; - tratamento de erros com mensagens rastreáveis; - testes unitários mínimos para cada wrapper. --- ## 3. Ambiente Conda ```yaml # geotrix3d-terra/docker_deploy/modules/base_image_proc/environment_proc.yml name: geotrix3D_py channels: - conda-forge dependencies: - python=<versao-validada> - vtk=<versao-validada> - qhull=<versao-validada> - numpy=<versao-validada> - scipy=<versao-validada> - pip=<versao-validada> ``` > Utilizar somente o canal `conda-forge`, evitando mistura com `defaults`. Após a validação de compatibilidade, gerar e versionar um lockfile Conda por plataforma; o `environment_proc.yml` permanece como especificação humana, e o lockfile torna o build reproduzível. --- ## 4. Dockerfile ```dockerfile # geotrix3d-terra/docker_deploy/modules/base_image_proc/Dockerfile ARG APP_BASE="meantrix/geotrix-app-base:r44@sha256:<digest-validado>" FROM ${APP_BASE} USER root ENV JAVA_HOME="/usr/lib/jvm/java-11-runtime" # URLs, versões e checksums devem ser fixados e validados. ARG JAVA_RUNTIME_URL="<url-versionada>" ARG JAVA_RUNTIME_SHA256="<sha256-validado>" ARG CONDA_INSTALLER_URL="<url-versionada>" ARG CONDA_INSTALLER_SHA256="<sha256-validado>" RUN wget -q "$JAVA_RUNTIME_URL" -O /tmp/java.tar.gz \ && echo "${JAVA_RUNTIME_SHA256} /tmp/java.tar.gz" | sha256sum -c - \ && mkdir -p /usr/lib/jvm \ && tar -xf /tmp/java.tar.gz -C /usr/lib/jvm \ && rm /tmp/java.tar.gz \ && R CMD javareconf RUN wget -q "$CONDA_INSTALLER_URL" -O /tmp/conda.sh \ && echo "${CONDA_INSTALLER_SHA256} /tmp/conda.sh" | sha256sum -c - \ && bash /tmp/conda.sh -b -p /opt/conda \ && rm /tmp/conda.sh ENV PATH="/opt/conda/bin:${PATH}" # Ambiente Conda com VTK e Qhull pré-compilados + limpeza de cache COPY environment_proc.yml /environment_proc.yml RUN conda env create -f /environment_proc.yml && \ conda clean -afy && \ rm -rf /opt/conda/pkgs/* && \ find /opt/conda/ $ -name '*.a' -o -name '*.js.map' $ -delete # Instalação do pacote Python interno COPY geotrix3d-native /tmp/geotrix3d-native RUN conda run -n geotrix3D_py \ pip install --no-cache-dir /tmp/geotrix3d-native && \ rm -rf /tmp/geotrix3d-native ENV CONDA_DEFAULT_ENV=geotrix3D_py ENV PATH="/opt/conda/envs/geotrix3D_py/bin:/opt/conda/bin:${PATH}" ENV LD_LIBRARY_PATH="/opt/conda/envs/geotrix3D_py/lib:${LD_LIBRARY_PATH}" USER 10001:10001 ``` --- ## 5. Migração do R Uso esperado nos pods após a criação do pacote: ```r library(reticulate) geotrix_native <- import( "geotrix3d_native", convert = FALSE ) result <- geotrix_native$vtk_utils$render_mesh(...) ``` A migração deve cobrir somente as funções de VTK e Qhull efetivamente utilizadas nos pods de processamento. O inventário das funções faz parte do primeiro bloco desta tarefa e deve ser concluído antes da definição da API dos wrappers. --- ## 6. Hipótese de redução do footprint nativo Os valores abaixo são hipóteses de engenharia e devem ser substituídos pela medição das camadas atuais antes da implementação. | Componente substituído | Estimativa atual | Estimativa após substituição | | -------------------------------------------------------- | ---------------: | -----------------------------: | | VTK compilado de fonte + artefatos build em camadas | ~3,0–3,5 GB | ~220 MB (binário conda) | | Qhull compilado + artefatos | ~50 MB | ~5 MB (binário conda) | | cmake + libboost-all-dev (necessários para compilar VTK) | ~1,3 GB | 0 (não necessários com conda) | | gcc-10 + g++-10 + gfortran-10 adicionais | ~500 MB | 0 (não necessários com conda) | | `VTK.tar.gz` + `qhull.tar.gz` em camadas | ~200 MB | 0 | | Cache conda não limpo (presente na base atual) | ~300 MB | 0 (limpeza na mesma instrução) | | **Total dos componentes listados** | **a medir** | **a medir** | --- ## 7. Regras - VTK e Qhull não podem retornar às imagens de app. - A compilação completa de VTK não deve ocorrer na imagem final de nenhuma imagem. - Java deve existir somente onde requerido. Preferir JRE headless no runtime; JDK e headers JNI devem permanecer no builder quando necessários para compilar `rJava`. - Miniconda/Conda deve existir somente nas imagens de processamento. - O pacote `geotrix3d_native` deve ter API estável e testes unitários. - As versões de Python, VTK e Qhull devem ser pinadas no `environment_proc.yml`. - Caches Conda e pip devem ser removidos na mesma instrução `RUN` que os criou. - O pacote Python deve ser instalável sem acesso externo em runtime (instalado durante o build). --- ## 8. Critérios de aceite - família `base_image_proc` construída com sucesso, com variante explícita por versão de R enquanto coexistirem R 3.6.3 e R 4.4.x. - Runtime Java configurado; `rJava` e H2O validados. JDK ausente do runtime quando não for necessário. - Ambiente Conda criado com `geotrix3D_py`. - VTK importável via `import vtk`; operações Qhull validadas por `scipy.spatial.ConvexHull`, `Delaunay` ou `Voronoi`, conforme os wrappers implementados. - Pacote `geotrix3d_native` instalado e importável. - Chamadas de teste pelo R via `reticulate` funcionando. - cmake, libboost-all-dev e toolchain de compilação ausentes da imagem final. - Tamanho e número de camadas medidos e registrados. - Imagem publicada no ACR. --- ## 9. Entregáveis - template/Dockerfile da família `base_image_proc`, com targets ou variantes por versão de R; - `geotrix3d-terra/docker_deploy/modules/base_image_proc/environment_proc.yml`; - lockfile Conda versionado para `linux-64`; - pacote Python `geotrix3d_native` com `vtk_utils.py` e `qhull_utils.py`; - testes unitários Python; - teste de integração R/Python via `reticulate`; - documentação do pacote; - imagem publicada no ACR com tag versionada. --- ## 10. Estimativa de esforço | Bloco | Horas | | ------------------------------------------------------------ | -------: | | Inventário das chamadas atuais de VTK/Qhull nos pods | 3 h | | Criação dos wrappers Python (`vtk_utils.py`, `qhull_utils.py`) | 4 h | | Testes unitários do pacote Python | 2 h | | Ambiente Conda (`environment_proc.yml`) e Dockerfile | 4 h | | Integração com R/`reticulate` e validação | 2 h | | Build, medição de tamanho e documentação | 1 h | | **Total** | **16 h** | --- # Tarefa 9 — Reescrita das imagens de pod sobre a base de processamento **Repositório:** `meantrix/geotrix3deploy` **Branch de trabalho:** `chat_ia` **Arquivos a modificar:** - `geotrix3d-terra/docker_deploy/modules/pod_image/Dockerfile` - `geotrix3d-terra/docker_deploy/modules/pod_image2d/Dockerfile` - `geotrix3d-terra/docker_deploy/modules/pod_image4/Dockerfile` - `geotrix3d-terra/docker_deploy/modules/pod_image2d4/Dockerfile` ## Objetivo geral Reescrever as quatro imagens de processamento para herdar de `base_image_proc`, utilizando multi-stage build para instalar bibliotecas R e pacotes internos sem manter toolchain e resíduos na imagem final. --- ## 1. Problemas nos Dockerfiles atuais das pods Além dos problemas comuns às imagens de app, os Dockerfiles de pod apresentam: | Problema | Localização | Impacto | | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | | `apt-get install libhdf5-serial-dev` sem `apt-get update` e sem limpeza | `pod_image/Dockerfile` L29, `pod_image4/Dockerfile` L29, `pod_image2d4/Dockerfile` L25 | instalação instável; pacote pode não ser encontrado; cache residual | | `install.packages("renv")` e `install.packages("remotes")` em `RUN` separados | todos os quatro, ex: `pod_image4/Dockerfile` L37 e L44 | camadas desnecessárias para bootstrap | | Cada pacote R em `COPY *.tar.gz` + `RUN R -e install_local` separados | todos os quatro | `.tar.gz` residuais em camadas, idem às apps | | VTK/Qhull/Java/Miniconda herdados da base atual, não da `base_image_proc` | herança de `meantrix/geotrix:0.0.3` ou `1.0.0` | duplicação desnecessária; será resolvida pela nova base | | `pip install geotrix3Dpy.tar.gz` sem associação ao ambiente Conda correto | `pod_image/Dockerfile` L22–23, `pod_image4/Dockerfile` L22–23 | pacote instalado fora do ambiente `geotrix3D_py`; falha silenciosa no `reticulate` | --- ## 2. Diferenças por imagem de pod | Imagem | `BASE_IMAGE` atual | `renv.lock` | Pacotes internos | | -------------- | ------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------ | | `pod_image` | `geotrix-proc-base:r36` enquanto a linha legada existir | `renv.lock` completo (mantém H2O, caret etc.) | `gstat`, `hdf5r`, `dtwclust`, `geotrix3D`, `r3d`, `geotrixdb`, `geotrix3db`, `geotrix3dpre` | | `pod_image4` | `geotrix-proc-base:r44` | `renv.lock` completo | `gstat`, `dtwclust`, `geotrix3D`, `r3d`, `geotrixdb`, `geotrix3db`, `geotrix3dpre` | | `pod_image2d` | `geotrix-proc-base:r36` enquanto a linha legada existir | `renv.lock` completo | `gstat`, `hdf5r`, `JLutils`, `geotrix`, `geotrixdb`, `geotrix2db`, `geotrix2dpre` | | `pod_image2d4` | `geotrix-proc-base:r44` | `renv.lock` completo | `JLutils`, `geotrix`, `geotrixdb`, `geotrix2db`, `geotrix2dpre` | > Os pods mantêm o `renv.lock` completo de desenvolvimento, pois precisam de `h2o`, `caret`, `Boruta`, `hdf5r` e demais dependências de processamento que foram movidas para `Suggests` nos apps. --- ## 3. Diretrizes - Stage builder para instalação de pacotes R e compilação. - Stage runtime herdando de `base_image_proc` (criada na Tarefa 8). - Remover recompilações de VTK, Qhull e Java — já presentes na `base_image_proc`. - Remover Miniconda — já presente na `base_image_proc`. - Instalar o pacote `geotrix3d_native` a partir da imagem base (já instalado na `base_image_proc`). - Consolidar `apt-get update`, instalação e limpeza em uma única instrução `RUN`. - Instalar `geotrix3Dpy` no ambiente Conda correto (`geotrix3D_py`), não no Python do sistema. - Executar `R CMD javareconf` no build da base e validar o carregamento de `rJava`/H2O no runtime; não reconfigurar Java a cada inicialização. - Validar integração `reticulate` com o ambiente `geotrix3D_py`. --- ## 4. Exemplo estrutural ```dockerfile ARG PROC_BASE="meantrix/geotrix-proc-base:r44@sha256:<digest-validado>" # ── Stage 1: builder ───────────────────────────────────────────────────────── FROM ${PROC_BASE} AS builder RUN apt-get update && apt-get install -y --no-install-recommends \ build-essential \ libhdf5-dev \ libssl-dev \ libcurl4-openssl-dev \ && rm -rf /var/lib/apt/lists/* COPY renv.lock /renv.lock RUN Rscript -e ' \ install.packages(c("remotes", "renv"), repos="https://cran.r-project.org"); \ renv::restore(lockfile="/renv.lock", library="/usr/local/lib/R/library") \ ' # geotrix3Dpy instalado no ambiente Conda correto COPY python-packages/geotrix3Dpy-*.tar.gz /tmp/geotrix3Dpy.tar.gz RUN conda run -n geotrix3D_py \ pip install --no-cache-dir /tmp/geotrix3Dpy.tar.gz --force --no-deps && \ rm /tmp/geotrix3Dpy.tar.gz # Pacotes R internos ficam em diretório separado para que o artefato Python # não seja enviado por engano ao remotes::install_local(). COPY r-packages/*.tar.gz /pkgs/ RUN Rscript -e ' \ pkgs <- list.files("/pkgs", pattern="\\.tar\\.gz$", full.names=TRUE); \ invisible(lapply(pkgs, remotes::install_local, upgrade=FALSE, dependencies=FALSE)); \ ' && rm -rf /pkgs # ── Stage 2: runtime ───────────────────────────────────────────────────────── FROM ${PROC_BASE} AS runtime COPY --from=builder /usr/local/lib/R/library /usr/local/lib/R/library # O geotrix3Dpy instalado no builder deve ser transportado para o runtime. COPY --from=builder /opt/conda/envs/geotrix3D_py /opt/conda/envs/geotrix3D_py COPY plumber.R /plumber.R USER 10001:10001 EXPOSE 3838 CMD ["bash"] ``` --- ## 5. Testes mínimos por imagem - carregamento do Java (`Sys.getenv("JAVA_HOME")` no R); - carregamento de H2O (`library(h2o); h2o.init()`) quando presente; - import de VTK no ambiente correto (`conda run -n geotrix3D_py python -c "import vtk"`); - import do pacote `geotrix3d_native` (`conda run -n geotrix3D_py python -c "import geotrix3d_native"`); - integração R/Python via `reticulate` com chamada de wrapper; - conexão com banco/storage de staging; - inicialização do entrypoint do job; - gravação de registro de tracking; - geração de artefato mínimo representativo do job. --- ## 6. Critérios de aceite - Quatro pod images reescritas com multi-stage. - Todas herdam `base_image_proc` no stage runtime. - VTK e Qhull não são recompilados; são herdados da base. - Pacotes R de processamento (`h2o`, `caret`, `Boruta`, etc.) disponíveis via `renv.lock` completo. - Java e H2O funcionam nos pods que os requerem. - Integração R/Python via `reticulate` funcionando. - `geotrix3Dpy` instalado no ambiente Conda correto. - Imagens construídas localmente e publicadas no ACR. - Tamanho e tempo de build registrados. --- ## 7. Entregáveis - quatro Dockerfiles de pod reescritos; - scripts de build; - integração do pacote `geotrix3d_native` validada; - logs de smoke test por imagem; - tags das imagens no ACR; - relatório comparativo de tamanho antes/depois. --- ## 8. Estimativa de esforço | Bloco | Horas | | ------------------------------------------------------------ | -------: | | Template de pod multi-stage e inventário das diferenças por imagem | 2 h | | Adaptação das imagens 2D (`pod_image2d` e `pod_image2d4`) | 3 h | | Adaptação das imagens 3D (`pod_image` e `pod_image4`) | 3 h | | Integração Java/Conda/Python/R e correção da instalação do `geotrix3Dpy` | 2 h | | Builds locais e correções | 2 h | | **Total** | **12 h** | --- # Tarefa 10 — Integração, medição e testes das imagens no AKS **Repositório:** `meantrix/geotrix3deploy` **Branch de trabalho:** `chat_ia` ## Objetivo geral Validar as novas bases e imagens em ambiente integrado, atualizar as referências de deployment e comprovar que a redução de dependências não afetou os fluxos dos apps ou dos pods. --- ## 1. Inventário de imagens O ciclo deve contemplar: ### Bases - `base_image_app` — criada na Tarefa 6; - `base_image_proc` — criada na Tarefa 8. ### Apps - `app_image` — Tarefa 7; - `app_image2d` — Tarefa 7; - `app_image4` — Tarefa 7; - `app_image2d4` — Tarefa 7. ### Pods - `pod_image` — Tarefa 9; - `pod_image2d` — Tarefa 9; - `pod_image4` — Tarefa 9; - `pod_image2d4` — Tarefa 9. --- ## 2. Baseline e medições Antes da alteração dos Dockerfiles, registrar as mesmas métricas nas imagens atualmente publicadas no ACR. As faixas estimadas deste planejamento não substituem o baseline real. Para cada imagem: - tamanho comprimido e descomprimido; - número de camadas; - tempo de build; - tempo de push para o ACR; - tempo de pull no cluster; - tempo até readiness; - número de pacotes R instalados (`length(rownames(installed.packages()))`); - presença ou ausência de Java, Python, VTK e Qhull (verificação explícita); - ausência de credenciais em camadas (`docker history --no-trunc` inspecionado); - vulnerabilidades críticas e altas no scanner disponível; - SBOM e provenance/attestation do build, quando suportados pelo pipeline; - usuário efetivo do processo e configuração de filesystem/capabilities. Comandos de referência: ```bash docker image inspect <imagem> docker history --no-trunc <imagem> docker run --rm <imagem> R --version docker run --rm <imagem> Rscript -e 'cat(length(rownames(installed.packages())), "pacotes instalados\n")' docker run --rm <imagem> Rscript -e 'sessionInfo()' ``` --- ## 3. Testes locais ### Apps - startup do app (`Rscript -e 'geotrixMap::run_app()'` ou `geotrixViewer::run_app()`); - carregamento dos pacotes sem erro; - conexão com banco de staging; - leitura de configuração e variáveis de ambiente; - autenticação Azure por Workload Identity, sem service-principal secret no container; - acesso à API Kubernetes por ServiceAccount/RBAC mínimo; `kubectl` apenas quando ainda necessário; - ausência de `h2o`, `Boruta`, `caret`, VTK, Qhull e Java nas imagens de app, salvo exceção de runtime comprovada e documentada. ### Pods - Java disponível e `R CMD javareconf` validado; - H2O inicializa (`h2o.init()`) nas imagens que o requerem; - Conda e ambiente `geotrix3D_py` disponíveis; - VTK importável dentro do ambiente correto; - operações Qhull validadas via `scipy.spatial` e pelo wrapper `geotrix3d_native`; - pacote `geotrix3d_native` importável; - integração R/Python via `reticulate` com chamada de wrapper real; - execução de job mínimo representativo; - geração de artefato; - ausência de Conda e Java nas imagens de app; - execução como usuário não root; - `allowPrivilegeEscalation: false`, capabilities descartadas e filesystem somente leitura quando compatível. --- ## 4. Testes no AKS - publicar todas as imagens no ACR com tags versionadas; - atualizar referências de imagem nos módulos Terraform e/ou manifests em `geotrix3d-terra/`; - criar namespace ou ambiente de staging dedicado; - executar rollout das imagens de app; - executar rollout das imagens de pod; - acompanhar `readinessProbe` e `livenessProbe`; - abrir apps no browser e navegar nos fluxos principais; - disparar jobs a partir do app e verificar execução nos pods; - verificar logs do app e dos pods no AKS; - verificar banco, storage e registros de tracking; - testar rollback para a versão anterior; - registrar resultados de cada verificação. --- ## 5. Metas preliminares de redução As metas abaixo são estimativas técnicas baseadas nos componentes identificados nas Tarefas 6, 7, 8 e 9. Os valores finais devem ser substituídos pelas medições obtidas nos builds. | Imagem | Faixa atual estimada | Meta preliminar | Base da estimativa | | ----------------- | --------------------------------: | ------------------------------: | ------------------------------------------------------------ | | `base_image_app` | nova | **0,75–0,90 GB** | Ubuntu 20.04 + R + runtime libs; sem VTK, Java, Conda | | `base_image_proc` | 6–8 GB (equivalente à base atual) | **2,0–2,5 GB** | Java (~300 MB) + Conda + VTK conda (~220 MB) + R base; sem compilação VTK | | `app_image2d` | 7–9 GB | **1,5–2,0 GB** | base_image_app + renv.prod.lock (~1,05 GB removidos) + multi-stage | | `app_image2d4` | 8–10 GB | **1,8–2,5 GB** | idem + texlive mínimo | | `app_image` | 9–11 GB | **1,8–2,5 GB** | base_image_app + renv.prod.lock (~1,45 GB removidos) + multi-stage | | `app_image4` | 10–12 GB | **2,0–3,0 GB** | idem + texlive mínimo | | `pod_image` | a medir | **meta definida após baseline** | `base_image_proc:r36` + lock completo + multi-stage | | `pod_image2d` | 8–10 GB | **3,0–4,0 GB** | `base_image_proc:r36` + lock completo + multi-stage | | `pod_image4` | 10–12 GB | **3,5–4,5 GB** | `base_image_proc:r44` + lock completo + multi-stage | | `pod_image2d4` | a medir | **meta definida após baseline** | `base_image_proc:r44` + lock completo + multi-stage | Metas percentuais: - app images: redução esperada de aproximadamente **70–80%**, viabilizada pela combinação de `base_image_app` enxuta, `renv.prod.lock` e multi-stage; - pod images: redução esperada de aproximadamente **50–65%**, viabilizada pela substituição da compilação VTK/Qhull por binários Conda e pela adoção de multi-stage; - redução significativa no tempo de build pela eliminação da compilação completa de VTK (~20–40 min por build de base). Esses percentuais não constituem critério isolado de aprovação. A compatibilidade funcional prevalece sobre a redução nominal. --- ## 6. Critérios de aceite - Todas as imagens construídas e publicadas no ACR. - Manifests/Terraform atualizados com as novas referências de imagem. - Apps atingem readiness no AKS. - Pods executam jobs com sucesso. - Banco, storage, tracking e outputs validados. - Rollback testado e documentado. - Baseline anterior e tamanhos/tempos posteriores registrados para todas as imagens. - Nenhuma credencial presente em camadas, configuração da imagem ou build args. - Workload Identity e ServiceAccount/RBAC mínimo validados. - Containers executam como usuário não privilegiado. - Relatório comparativo antes/depois concluído. --- ## 7. Entregáveis - imagens publicadas no ACR; - manifests/Terraform atualizados no repositório; - logs de build e rollout; - SBOM, digests e resultados do scanner; - relatório antes/depois com tamanho, camadas e tempo de build por imagem; - matriz de testes preenchida; - evidências de funcionamento (screenshots, logs); - documentação de rollback; - changelog das alterações. --- ## 8. Estimativa de esforço | Bloco | Horas | | -------------------------------------------------- | -------: | | Build e medição de todas as imagens | 3 h | | Smoke tests locais (apps e pods) | 2 h | | Push ao ACR e atualização dos deployments | 2 h | | Testes dos apps no AKS | 2 h | | Testes dos pods no AKS | 2 h | | Correções finais, rollback e relatório comparativo | 2 h | | **Total** | **13 h** | --- # 3. Dependências entre tarefas ```text Tarefa 1 ───────────────┐ ├─> Tarefa 2 JSONL MINEX 3D │ API + vector stores + deployment │ Tarefa 5 ─> Tarefas 3 e 4 DESCRIPTION perfis/locks production \ / \ / └─> Tarefa 7 App images multi-stage | Tarefa 6 ─────────┘ base_image_app Tarefa 8 base_image_proc + Python | └─> Tarefa 9 Pod images multi-stage | Tarefas 7 e 9 ─────────> Tarefa 10 AKS, medição e validação ``` Na prática, a auditoria dos `DESCRIPTION` e a geração inicial dos lockfiles podem ser executadas de forma iterativa. Os lockfiles somente são considerados finais após a validação das dependências de runtime. --- # 4. Critérios de aceite globais ## 4.1 JSONL e RAG - [ ] Nove funcionalidades de análise mapeadas. - [ ] Entradas e validações documentadas. - [ ] JSONL de app, pre e links criados quando aplicável. - [ ] Registry e manifests atualizados. - [ ] Conteúdo 2D e 3D isolado. ## 4.2 API e deployment - [ ] `app_id` implementado. - [ ] Banco selecionado corretamente. - [ ] Dois vector stores 3D criados. - [ ] Chats isolados por aplicação. - [ ] API implantada no AKS. - [ ] `/health` operacional. ## 4.3 Dependências R - [ ] Perfis/lockfiles de produção criados para os dois apps. - [ ] `renv.lock` de desenvolvimento preservado. - [ ] `DESCRIPTION` revisados. - [ ] Apps inicializam somente com dependências de produção. - [ ] `R CMD check` executado. ## 4.4 Bases e imagens - [ ] `base_image_app` criada. - [ ] `base_image_proc` criada. - [ ] Quatro app images convertidas para multi-stage. - [ ] Quatro pod images convertidas para multi-stage. - [ ] VTK/Qhull ausentes dos apps. - [ ] Java e Conda restritos ao processamento. - [ ] Toolchain ausente dos runtimes. - [ ] Processos finais executam como usuário não root. - [ ] Bases e dependências fixadas por versão/digest. ## 4.5 Python e processamento - [ ] Pacote `geotrix3d_native` criado. - [ ] Wrappers VTK/Qhull testados. - [ ] Integração R/Python validada. - [ ] Pods executam os jobs esperados. ## 4.6 AKS e documentação - [ ] Imagens publicadas. - [ ] Deployments atualizados. - [ ] Readiness e liveness validados. - [ ] Banco, storage e tracking testados. - [ ] Workload Identity e RBAC mínimo validados. - [ ] Rollback documentado. - [ ] Baseline, SBOM, digests e scanner registrados. - [ ] Relatório comparativo concluído. - [ ] README e changelogs atualizados. --- # 5. Premissas para manutenção da estimativa de 145 horas A estimativa pressupõe: - acesso disponível aos repositórios, ACR, AKS, bancos e namespace de staging; - pipeline atual de build e publicação funcional antes da refatoração; - disponibilidade das imagens atuais para levantamento do baseline; - quantidade limitada de operações VTK/Qhull a encapsular, sem reescrita ampla dos algoritmos; - contratos atuais entre app, pods, banco e storage suficientemente estáveis; - ausência de refatoração funcional dos módulos Shiny além do necessário para remover dependências indevidas; - possibilidade de reutilizar ou descontinuar a linha R 3.6.3 sem reconstruir todo o ecossistema legado; - Workload Identity já habilitada no cluster ou habilitável sem mudança estrutural fora do repositório; - existência de testes ou fluxos manuais conhecidos para validar apps e jobs; - disponibilidade de uma janela de staging para rollout e rollback. Caso seja necessário manter simultaneamente todas as variantes legadas, criar muitos wrappers nativos, alterar o mecanismo de submissão de jobs ou habilitar identidade federada no cluster com mudanças adicionais de infraestrutura, o esforço deverá ser reavaliado. --- # 6. Riscos e medidas de controle | Risco | Impacto | Medida de controle | | -------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------ | | Dependência movida para `Suggests`, mas usada no runtime | App não inicia | busca de uso, biblioteca limpa, smoke test | | Lockfile incompatível com a versão de R | Build quebra | fixar versão de R e validar restore isolado | | Biblioteca nativa ausente na base de app | Pacote R não carrega | adicionar somente runtime library comprovadamente necessária | | Incompatibilidade VTK/Conda/reticulate | Job falha | pin de versões e teste R/Python | | Pacote Python não cobre chamada existente | Regressão no processamento | inventário prévio das funções e teste por wrapper | | Azure CLI ou `kubectl` removido indevidamente | App não dispara pods | testar fluxo completo no AKS | | Segredo incluído em layer | Exposição de credencial | autenticação em runtime e inspeção de history | | Redução menor que a estimada | Meta de tamanho não atingida | medir por camada e priorizar resíduos reais | | Divergência entre imagens 2D e 3D | manutenção duplicada | templates comuns e argumentos de build | | Mudança simultânea em muitas imagens | rollback complexo | tags imutáveis, staging e rollout incremental | | Ubuntu 20.04 fora do suporte padrão | ausência de patches e risco de compliance | usar ESM/base corrigida temporariamente e planejar migração | | Uma única base para R 3.6 e R 4.4 | incompatibilidade binária e de pacotes | variantes versionadas ou descontinuação explícita da linha legada | | TeX apenas no builder | relatórios PDF falham no runtime | mover geração para job dedicado ou instalar runtime mínimo de forma explícita | | Ambiente Conda sem lock | builds não reproduzíveis | versões exatas, canal único e lockfile por plataforma | | Pacote Python mantido no repositório de deploy | acoplamento de código e infraestrutura | tratar como solução transitória e extrair para pacote/repositório próprio | --- # 7. Itens fora do escopo Não fazem parte deste planejamento: - refatoração funcional ampla dos apps 2D ou 3D; - mapeamento de funcionalidades fora de `Menu > Analysis`; - reconstrução dos JSONL já validados do MINEX 2D; - substituição do ShinyProxy; - migração de versão do Ubuntu, R ou Kubernetes sem necessidade direta; - reescrita dos algoritmos de processamento; - alteração metodológica dos modelos de ML/geoestatística; - migração definitiva do pacote Python para canal público Conda/PyPI; - testes extensivos de carga e performance; - revisão geral de segurança do cluster além das imagens alteradas.

Due by July 31, 2026

0% complete0 open 0 closed

JUNHO/26 - MINEX

# Planejamento Mensal — GeotrixIA / MINEX 3D **Período:** Junho/2026 **Foco:** Agente de IA, mapeamento de funcionalidades, API de chat, deployment Kubernetes e widget de IA no `geotrixMap`. **Referências:** `geotrixIA#ia_chat` · `geotrix3deploy#98` · `geotrixMap#dev` **Apps e pacotes no escopo:** - **Frontend/App:** `geotrixMap` — integração do widget de IA no app. - **IA:** `geotrixIA` — pacote Python com API de chat persistente. - **Infraestrutura:** `geotrix3deploy` — deployment Kubernetes via Bash/Terraform. > Observação de escopo: este documento organiza o planejamento mensal do ciclo de Junho/2026. Quando já existirem artefatos iniciais, o esforço previsto deve ser entendido como revisão, complementação, integração, testes e validação, e não necessariamente como desenvolvimento integral do zero. --- ## 1. Quadro geral de tarefas e tempos | ID | Tarefa | Foco principal | Tempo estimado | | --------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -------------: | | **1** | **Consolidação dos JSONL já mapeados no registry** | Revisão, padronização e validação dos JSONL existentes para as features principais | **12 h** | | **2** | **Mapeamento das funcionalidades faltantes do `geotrixMap`** | Levantamento e criação dos JSONL ainda ausentes, priorizando cobertura funcional e rastreabilidade | **24 h** | | **3** | **Pacote Python `geotrixia`** | Consolidação da API FastAPI, persistência de chat, integração com OpenAI Responses API, testes e documentação | **44 h** | | **4** | **Deployment Kubernetes da geotrixIA** | Docker, Bash, Terraform, Service/Deployment Kubernetes, configuração interna e smoke tests | **25 h** | | **5** | **Widget de IA no `geotrixMap`** | Componente Lit `mx-ia-chat`, integração com API, contexto do projeto e testes de frontend | **30 h** | | **TOTAL** | | | **135 h** | --- # Tarefa 1 — Consolidação dos JSONL já mapeados no registry ## Objetivo geral Revisar, complementar e validar os arquivos JSONL já existentes em `ai_agent_jsonl/registry`, garantindo que as principais features do `geotrixMap` estejam descritas de forma padronizada, rastreável e compatível com o fluxo de RAG da `geotrixIA`. Como parte dos JSONL já existe, o esforço previsto não deve ser tratado como criação integral do zero. O foco é verificar consistência, corrigir lacunas, validar contratos e atualizar os índices necessários para reprocessamento do RAG. --- ## 1. Features no escopo Os seguintes pares de JSONL já existem em `ai_agent_jsonl/registry/app` e `ai_agent_jsonl/registry/pre` e precisam ser revisados e validados: | Feature | App JSONL | Pre JSONL | | -------------------------------------------- | ---------------------------- | ---------------------------- | | `apply` — aplicação de modelo | `apply.app.jsonl` | `apply.pre.jsonl` | | `apply_inpainting` — aplicação de inpainting | `apply_inpainting.app.jsonl` | `apply_inpainting.pre.jsonl` | | `correlations` — correlações e quick view | `correlations.app.jsonl` | `correlations.pre.jsonl` | | `deep_learning` — treino de rede neural | `deep_learning.app.jsonl` | `deep_learning.pre.jsonl` | | `famd` — Factor Analysis of Mixed Data | `famd.app.jsonl` | `famd.pre.jsonl` | | `inpainting` — treino de inpainting | `inpainting.app.jsonl` | `inpainting.pre.jsonl` | | `ldm` — Linear Directional Mean | `ldm.app.jsonl` | `ldm.pre.jsonl` | | `opt` — Optimal Grid Size | `opt.app.jsonl` | `opt.pre.jsonl` | | `random_forest` — treino Random Forest | `random_forest.app.jsonl` | `random_forest.pre.jsonl` | | `stacked_ensemble` — Stacked Ensemble | `stacked_ensemble.app.jsonl` | `stacked_ensemble.pre.jsonl` | | `varimp` — Important Features / Boruta | `varimp.app.jsonl` | `varimp.pre.jsonl` | | `xgboost` — treino XGBoost | `xgboost.app.jsonl` | `xgboost.pre.jsonl` | --- ## 2. Atividades 1. Revisar a completude dos JSONL de app, verificando campos como `feature_id`, `feature_code`, `feature_type`, `component_tag`, `properties`, `events_emitted`, `events_received`, `validation_rules` e `test_refs`. 2. Revisar a completude dos JSONL de pre, conferindo contratos de servidor, payloads de entrada e saída e vínculo com módulos do backend `geotrix3dpre`. 3. Validar os JSONL contra Observers, schedules e reboots correspondentes no `geotrixMap/dev`. 4. Corrigir `feature_id`, `feature_code` e `feature_type` no `feature_registry.jsonl`, evitando duplicatas e inconsistências de nomenclatura. 5. Atualizar o `rag_setup_manifest.json` com fontes ausentes ou ajustes necessários para reindexação. --- ## 3. Critérios de aceite - 12 pares de JSONL revisados e validados. - `feature_registry.jsonl` atualizado, sem duplicatas e com campos obrigatórios. - `rag_setup_manifest.json` compatível com as fontes efetivamente utilizadas. - Validação cruzada aprovada contra o código-fonte do `geotrixMap/dev`. - Evidências mínimas de validação registradas para revisão. --- ## 4. Entregáveis - JSONL revisados em `ai_agent_jsonl/registry/app/`. - JSONL revisados em `ai_agent_jsonl/registry/pre/`. - `feature_registry.jsonl` atualizado. - `rag_setup_manifest.json` atualizado. - Evidências de validação em `ai_agent_jsonl/logs/` ou diretório equivalente. --- ## 5. Estimativa de esforço | Bloco | Horas | | --------------------------------------------------------- | -------: | | Revisão dos JSONL de app já existentes | 3 h | | Revisão dos JSONL de pre já existentes | 3 h | | Validação cruzada contra código-fonte do `geotrixMap/dev` | 4 h | | Atualização de registry, manifest e evidências | 2 h | | **Total** | **12 h** | --- # Tarefa 2 — Mapeamento das funcionalidades faltantes do `geotrixMap` ## Objetivo geral Mapear e criar os arquivos JSONL de rastreabilidade para as funcionalidades do `geotrixMap/dev` que ainda não possuem cobertura adequada no registry. O objetivo é ampliar a capacidade do agente de IA de reconhecer, explicar e contextualizar operações do app, sem depender de leitura bruta e desestruturada do código-fonte em tempo de consulta. O esforço foi reduzido em relação ao planejamento anterior porque parte do padrão de JSONL já está estabelecida pela Tarefa 1, permitindo reaproveitar schema, convenções e estrutura de validação. --- ## 1. Funcionalidades identificadas como faltantes | Feature | Arquivo(s) principal(is) no `geotrixMap/R` | Feature code sugerido | | ----------------------------------------------------- | ------------------------------------------------------------ | --------------------------- | | `boruta` — seleção de variáveis Boruta | `reboot.boruta.R`, `schedule.boruta.R` | `GEOTRIXMAP_BORUTA` | | `mineral_prospecting` — prospecção mineral | `Observer.MineralProspecting.R`, `schedule.mineral.R`, `reboot.mineral.R` | `GEOTRIXMAP_MINERAL` | | `add_layers` — adição de camadas ao projeto | `Observer.AddLayers.R` | `GEOTRIXMAP_ADD_LAYERS` | | `filter_layer` — filtro de camadas | `Observer.filterLayer.R` | `GEOTRIXMAP_FILTER_LAYER` | | `merge_layers` — mesclagem de camadas | `Observer.mergeLayers.R` | `GEOTRIXMAP_MERGE_LAYERS` | | `resize_grid` — redimensionamento de grid | `Observer.resizeGrid.R` | `GEOTRIXMAP_RESIZE_GRID` | | `voronoi` — diagrama de Voronoi | `Observer.vonoroi.R` | `GEOTRIXMAP_VORONOI` | | `reclassify_lithology` — reclassificação litológica | `Observer.ReclassifyLithology.R` | `GEOTRIXMAP_RECLASSIFY` | | `open_project` — abertura de projeto | `Observer.OpenProject.R`, `project.openProject.R` | `GEOTRIXMAP_OPEN_PROJECT` | | `create_project` — criação de projeto | `project.createProject.R`, `update_project.createProject.R` | `GEOTRIXMAP_CREATE_PROJECT` | | `delete_project` — exclusão de projeto | `project.deleteProject.R` | `GEOTRIXMAP_DELETE_PROJECT` | | `download_layer` — download de camada | `project.downloadLayer.R` | `GEOTRIXMAP_DOWNLOAD_LAYER` | | `delete_layer` — exclusão de camada | `project.deleteLayer.R` | `GEOTRIXMAP_DELETE_LAYER` | | `rename_layer` — renomear camada | `project.renameLayer.R` | `GEOTRIXMAP_RENAME_LAYER` | | `add_formula` — adição de fórmula | `Observer.addFormula.R` | `GEOTRIXMAP_ADD_FORMULA` | | `add_target` — adição de target | `Observer.addTarget.R`, `project.AddTarget.R` | `GEOTRIXMAP_ADD_TARGET` | | `results` — painel de resultados, download e exclusão | `app_results.R`, `app_results_render.R`, `download_results.R`, `delete_results.*.R` | `GEOTRIXMAP_RESULTS` | | `app_viewer` — visualizador de camadas | `app_viewer.R` | `GEOTRIXMAP_VIEWER` | | `app_analysis` — aba de análise | `app_analysis.R` | `GEOTRIXMAP_ANALYSIS` | | `app_edit` — aba de edição | `app_edit.R`, `app_editor.R` | `GEOTRIXMAP_EDIT` | | `model_create` — criação de modelo | `model.createModel.R` | `GEOTRIXMAP_MODEL_CREATE` | | `model_import` — importação de modelo | `model.importModel.R` | `GEOTRIXMAP_MODEL_IMPORT` | | `send_email` — envio de email de notificação | `send_email.R` | `GEOTRIXMAP_EMAIL` | | `schedule_system` — agendamento de jobs | `Observer.schedule.R`, `Dispatcher.R`, `Queue.R`, `Listener.R` | `GEOTRIXMAP_SCHEDULE` | | `app_shell` — estrutura geral do app, UI e servidor | `App.R`, `app_ui.R`, `app_server.R`, `app_run.R`, `app_home.R` | `GEOTRIXMAP_SHELL` | | `report` — geração de relatórios LaTeX e Markdown | `app_ui_report_latex.R`, `app_ui_report_markdown.R`, `app_ui_report_utils.R` | `GEOTRIXMAP_REPORT` | --- ## 2. Atividades 1. Realizar varredura funcional dos arquivos R relacionados às features acima. 2. Identificar entradas do usuário, estados internos, eventos emitidos, eventos recebidos, payloads e outputs exibidos na interface. 3. Criar JSONL de app para as funcionalidades faltantes, respeitando o schema já validado na Tarefa 1. 4. Criar JSONL de pre somente para funcionalidades com contrato efetivo com backend ou rotina de processamento associada. 5. Atualizar `feature_registry.jsonl` com as novas features. 6. Atualizar `rag_setup_manifest.json` com as novas fontes. 7. Validar se os JSONL criados permitem rastreabilidade mínima entre feature, UI, backend e testes. --- ## 3. Critérios de aceite - Funcionalidades faltantes mapeadas com JSONL de app quando aplicável. - JSONL de pre criado apenas quando houver contrato backend relevante. - `feature_registry.jsonl` atualizado e sem duplicatas. - `rag_setup_manifest.json` cobrindo as novas fontes. - Schema compatível com os JSONL existentes. - Revisão técnica aprovada antes do merge. --- ## 4. Entregáveis - JSONL novos em `ai_agent_jsonl/registry/app/`. - JSONL novos em `ai_agent_jsonl/registry/pre/`, quando aplicável. - `feature_registry.jsonl` atualizado. - `rag_setup_manifest.json` atualizado. - Evidências de validação dos principais grupos funcionais. --- ## 5. Estimativa de esforço | Bloco | Horas | | --------------------------------------------------- | -------: | | Varredura e agrupamento funcional das 26 features | 6 h | | JSONL de app — projeto, camadas e edição | 5 h | | JSONL de app — análise, modelos e processamento | 5 h | | JSONL de app — shell, resultados, schedule e report | 5 h | | JSONL de pre, registry, manifest e validação final | 3 h | | **Total** | **24 h** | --- # Tarefa 3 — Pacote Python `geotrixia` ## Objetivo geral Consolidar o pacote Python `geotrixia` como runtime leve de API para chats persistentes por usuário e projeto, orquestrando PostgreSQL, OpenAI Responses API e endpoints HTTP via FastAPI para consumo pelo widget do `geotrixMap`. O objetivo não é criar uma aplicação monolítica nem carregar o RAG local dentro da API. A API deve permanecer leve, com persistência de conversa, controle de execução, tratamento padronizado de erros e integração com o serviço de IA. --- ## 1. Escopo de implementação ## 1.1 Módulo `geotrixia.db` Responsável pela camada de persistência PostgreSQL e compatibilidade com o padrão de banco utilizado por `geotrixDB/geotrix2db`. Itens previstos: - configuração de conexão PostgreSQL por variáveis separadas de ambiente; - pool de conexões com `psycopg`; - helpers de query para leitura, escrita e retorno de registros; - modelos de dados para sessão de chat e mensagens; - repositório de chat com operações sobre `project_has_chats`, `chats` e `chat_messages`; - lock operacional por chat para evitar reenvio concorrente; - atualização parcial de `metadata` em JSONB, preservando dados já existentes. ## 1.2 Módulo `geotrixia.gpt` Responsável pela integração com a OpenAI Responses API. Itens previstos: - runtime de chat via Responses API; - persistência e reaproveitamento de `conversation_id` entre turnos; - timeout configurável por chamada; - controle para não criar nova conversa quando já houver chat ativo; - separação entre chamada ao provider e transações de banco, evitando transação aberta durante chamada externa. ## 1.3 Módulo `geotrixia.services` Responsável pela regra de negócio do fluxo de chat. Itens previstos: - `GeotrixiaChatService` como orquestrador principal; - criação, retomada e fechamento de chats; - envio de mensagem ao provider; - bloqueio de execução concorrente com status operacional; - liberação de lock em sucesso e erro controlado; - registro de uso, latência, status do provider e mensagens de erro em `metadata`; - configuração de timeout e stale lock via arquivo de configuração ou ambiente. ## 1.4 Módulo `geotrixia.api` Responsável pela exposição HTTP da API. Endpoints previstos: - `GET /health` - `POST /chat` - `GET /projects/{project_id}/users/{user_id}/chats` - `GET /chats/{chat_id}/messages` - `POST /chats/{chat_id}/close` - `POST /chats/{chat_id}/delete` Itens complementares: - schemas Pydantic de request/response; - registry de erros padronizados; - payloads de erro no formato `{"error": {"code": "...", "message": "..."}}`; - separação entre erro de validação, erro de execução, erro de lock e erro do provider. ## 1.5 Módulo `geotrixia.utils` Responsável por utilitários auxiliares e reaproveitamento do fluxo de preparação do RAG. Itens previstos: - extração de código a partir de `registry/pre`; - parsing e validação de JSONL; - helpers de configuração; - rotinas auxiliares para setup de RAG/File Search quando aplicável ao fluxo de preparação. ## 1.6 Testes A suite de testes deve cobrir o comportamento central sem depender de OpenAI real ou PostgreSQL real. Grupos previstos: - testes da camada PostgreSQL com fakes; - testes do repositório de chat, incluindo CRUD, lock e merge de JSONB; - testes dos modelos de dados; - testes do `ChatService`, incluindo sucesso, erro, timeout e lock concorrente; - testes dos endpoints FastAPI com `TestClient`; - testes do runtime Responses API com provider fake; - testes de utilitários de JSONL, extração de código e configuração. ## 1.7 Packaging, ambiente e documentação Itens previstos: - `setup.py` com dependências declaradas; - `env.yml` ou `env.api.yml` para ambiente Conda; - `pytest.ini`; - `.envrc` ou instrução equivalente para variáveis de desenvolvimento; - `config.txt` sem credenciais; - `README.md` com arquitetura, endpoints, persistência de conversa, configuração de banco, setup de RAG/File Search e fluxo esperado em Kubernetes; - `CHANGELOG.md` com registro da versão. --- ## 2. Regras obrigatórias ## Proibido - Usar `DATABASE_URL` como configuração única de banco. - Armazenar credenciais em `config.txt`. - Criar novo `conversation_id` quando já existir chat persistente ativo. - Manter transação de banco aberta durante chamada à OpenAI. - Carregar NLTK, Tika, SentenceTransformers ou RAG local no runtime da API. ## Obrigatório - Configuração por variáveis separadas: `DB_USER`, `DB_PASSWORD`, `DB_HOST`, `DB_NAME`, `DB_PORT`. - Compatibilidade com o padrão de banco `project_has_chats.request → chats.request → chat_messages.chat_id`. - Merge parcial de `metadata` JSONB. - Testes sem dependência de serviços externos reais. - Tratamento padronizado de erro para consumo pelo frontend. - Documentação mínima para execução local e em Kubernetes. --- ## 3. Critérios de aceite - Endpoints principais respondendo corretamente na suite de testes. - Fluxo de chat persistente funcionando com reaproveitamento de `conversation_id`. - Lock operacional funcionando: bloqueia reenvio e libera em sucesso ou erro. - Metadata registrada corretamente em `chats.metadata` e `chat_messages.metadata`. - Testes executando sem OpenAI real e sem PostgreSQL real. - Ambiente empacotável para uso posterior no deployment. - README descrevendo arquitetura, endpoints e variáveis necessárias. --- ## 4. Entregáveis - Módulos em `geotrixia/db/`. - Módulos em `geotrixia/gpt/`. - Módulos em `geotrixia/services/`. - Módulos em `geotrixia/api/`. - Utilitários em `geotrixia/utils/`. - Arquivo de registry de erros em `geotrixia/data/`, quando aplicável. - Testes automatizados em `tests/`. - Arquivos de ambiente e empacotamento. - `README.md` e `CHANGELOG.md`. --- ## 5. Estimativa de esforço | Bloco | Horas | | ------------------------------------------------------------ | -------: | | Camada `db`: conexão, models, repository, CRUD, lock e merge JSONB | 9 h | | Camada `gpt`: Responses API, `conversation_id`, timeout e isolamento de transação | 6 h | | Camada `services`: fluxo de chat, status operacional, metadata e hardening | 8 h | | Camada `api`: FastAPI, endpoints, schemas e erros padronizados | 8 h | | Camada `utils`: extração, JSONL, configuração e apoio ao RAG/File Search | 4 h | | Testes com fakes para banco, provider, serviço e API | 7 h | | Packaging, ambiente, README e changelog | 2 h | | **Total** | **44 h** | --- # Tarefa 4 — Deployment Kubernetes da geotrixIA ## Objetivo geral Criar e validar a infraestrutura necessária para disponibilizar a API `geotrixIA` como serviço independente no cluster AKS existente, seguindo os padrões já utilizados no `geotrix3deploy`. A API deve rodar como deployment interno, exposta por `ClusterIP`, acessível pelos pods do `geotrixMap` pela URL interna do serviço. O deployment deve ser reprodutível por Bash e compatível com os módulos Terraform existentes. --- ## 1. Escopo de implementação ## 1.1 Bash e imagem Docker Itens previstos: - script de deploy da API `geotrixIA`, seguindo o padrão dos scripts existentes do `geotrix3d-bash`; - validação pré-execução de variáveis e arquivos necessários; - autenticação no AKS e ACR; - build e push da imagem da API; - renderização de template Kubernetes; - aplicação do manifesto no cluster; - validação de rollout e instruções de smoke test. Imagem Docker: - imagem baseada em ambiente Conda/Micromamba ou equivalente já utilizado no projeto; - instalação do pacote `geotrixia` empacotado; - ambiente mínimo para FastAPI, Uvicorn, OpenAI, Pydantic e Psycopg; - exposição da porta `8000`; - comando de inicialização via Uvicorn. ## 1.2 Kubernetes Itens previstos: - `Service` interno do tipo `ClusterIP`; - `Deployment` para a API; - `readinessProbe` e `livenessProbe` em `/health`; - configuração de resources request/limit; - `imagePullSecrets` para ACR; - `terminationGracePeriodSeconds` e `preStop` para encerramento controlado; - variáveis de ambiente necessárias para banco, OpenAI e runtime. ## 1.3 Terraform — Docker deploy Itens previstos: - módulo Terraform para build/push da imagem `geotrixia-api`; - variáveis para ACR, nome da imagem, versão, caminho da imagem e credenciais necessárias; - passagem de parâmetros de banco e runtime; - outputs com nome final da imagem. ## 1.4 Terraform — AKS deploy Itens previstos: - recursos Terraform para criar ou atualizar `Service` e `Deployment` da API; - variáveis para nome, namespace, porta, imagem e recursos da API; - outputs com nome do serviço, URL interna e nome do deployment; - integração ao módulo de service já existente quando aplicável. ## 1.5 Integração com ShinyProxy e documentação Itens previstos: - atualização do `application.yml` quando necessária para apontar para a nova versão do app e imagens associadas; - documentação mínima do fluxo de deploy; - registro em `CHANGELOG.md`; - comandos de teste pós-deploy. --- ## 2. Critérios de aceite - Build da imagem `geotrixia-api` concluído sem erros. - Push para ACR bem-sucedido. - Service e Deployment Kubernetes aplicados no cluster. - `kubectl rollout status` concluindo com sucesso. - `GET /health` respondendo `200` após deploy. - URL interna do serviço disponível para consumo pelo `geotrixMap`. - Outputs Terraform corretos para service, URL e deployment. - Documentação mínima de execução e validação disponível. --- ## 3. Entregáveis - Script Bash de deploy da API. - Dockerfile da API. - Arquivo de ambiente mínimo da API. - Template Kubernetes da API. - Módulo Terraform para build/push da imagem. - Atualizações em `docker_deploy`. - Atualizações em `aks_deploy`. - Atualização do `application.yml`, quando aplicável. - README ou seção de documentação do deployment. - Entrada no `CHANGELOG.md`. --- ## 4. Estimativa de esforço | Bloco | Horas | | ------------------------------------------------------------ | -------: | | Script Bash de deploy, validações, build, push, apply e rollout | 5 h | | Dockerfile e ambiente mínimo da API | 3 h | | Template Kubernetes com Service, Deployment, probes e resources | 3 h | | Terraform `docker_deploy`: módulo, variáveis e outputs | 5 h | | Terraform `aks_deploy`: Service, Deployment, variáveis e outputs | 5 h | | Integração com ShinyProxy, README e CHANGELOG | 2 h | | Smoke tests, ajustes de ambiente e validação final | 2 h | | **Total** | **25 h** | --- # Tarefa 5 — Widget de IA no `geotrixMap` ## Objetivo geral Criar o widget de IA como Web Component Lit integrado ao `geotrixjs` do `geotrixMap`, permitindo que o usuário interaja com a `geotrixIA` sem sair do contexto do app. O widget deve consumir a API FastAPI da `geotrixIA`, enviar contexto do projeto e do módulo ativo, exibir respostas do agente e permitir retomada de sessões de chat. --- ## 1. Escopo funcional ## 1.1 Interface do chat Itens previstos: - painel de chat flutuante ou sidebar; - botão de abrir e fechar; - campo de entrada com suporte a múltiplas linhas; - envio por botão ou tecla `Enter`; - listagem de mensagens com distinção visual entre usuário e agente; - scroll automático; - indicador de loading enquanto a resposta é processada; - estado de erro com mensagem amigável e opção de reenvio; - botão de cópia para respostas longas. ## 1.2 Gestão de sessão Itens previstos: - criação automática de chat na primeira mensagem; - listagem de chats anteriores por projeto e usuário; - retomada de chat existente; - fechamento de chat; - bloqueio de reenvio enquanto uma mensagem estiver em processamento. ## 1.3 Contexto e personalização Itens previstos: - envio de `project_id`, `user_id` e `feature_code` em cada mensagem; - atualização do `feature_code` conforme o módulo ativo no `geotrixMap`; - integração com o mapeamento do `feature_registry.jsonl`; - configuração da URL da API por atributo ou variável de ambiente; - ausência de credenciais no frontend. --- ## 2. Diretriz arquitetural ## 2.1 Componente raiz Componente principal: - `mx-ia-chat` Responsabilidades: - gerenciar ciclo de vida do chat; - consumir a API `geotrixIA` via `fetch`; - receber `project-id`, `user-id`, `feature-code` e `api-url`; - emitir eventos como `ia-chat-opened`, `ia-chat-closed`, `ia-message-sent` e `ia-message-received`; - encapsular interface no Shadow DOM. ## 2.2 Subcomponentes previstos - `mx-ia-chat-panel` — painel principal com mensagens e input. - `mx-ia-chat-message` — renderização individual de mensagens. - `mx-ia-chat-session-list` — listagem e seleção de chats anteriores. - `mx-ia-chat-loading` — indicador de processamento. - `mx-ia-chat-error` — estado de erro com ação de reenvio. ## 2.3 Integração com o `geotrixMap` - O `geotrixjs` deve registrar e instanciar o widget no shell do app. - O app deve repassar `project_id`, `user_id` e `feature_code` via bridge Shiny → JS. - A URL da API deve apontar para o service interno da `geotrixIA` no ambiente Kubernetes. - O componente não deve realizar chamadas diretas à OpenAI. --- ## 3. Regras obrigatórias ## Proibido - Chamar OpenAI diretamente pelo frontend. - Armazenar token ou credencial no navegador. - Fazer polling desnecessário. - Permitir múltiplos envios concorrentes da mesma mensagem. ## Obrigatório - Tratamento explícito de timeout e erro de rede. - Estado de loading bloqueando reenvio. - `disconnectedCallback` cancelando requisições pendentes. - Shadow DOM nos componentes. - Testes unitários cobrindo os principais fluxos. --- ## 4. Critérios de aceite - Widget abre e fecha sem interferir no layout do app. - Primeira mensagem cria chat automaticamente via API. - `feature_code` do módulo ativo é enviado corretamente. - Respostas do agente são exibidas com formatação básica. - Estados de loading, erro e reenvio funcionam corretamente. - Sessões anteriores podem ser listadas e retomadas. - Testes cobrem criação de chat, envio de mensagem, retomada de sessão e erro de rede. - Zero erros relevantes no console. --- ## 5. Entregáveis - `mx-ia-chat`. - `mx-ia-chat-panel`. - `mx-ia-chat-message`. - `mx-ia-chat-session-list`. - `mx-ia-chat-loading`. - `mx-ia-chat-error`. - Testes unitários do widget. - JSONL de rastreabilidade do widget. - README técnico com atributos, eventos e configuração da URL. - Evidências de teste/cobertura. --- ## 6. Estimativa de esforço | Bloco | Horas | | ----------------------------------------------------------- | -------: | | Componente raiz `mx-ia-chat` e integração inicial com API | 5 h | | Interface de chat: mensagens, input, scroll, loading e erro | 7 h | | Gestão de sessão: criação, listagem, retomada e fechamento | 7 h | | Injeção de contexto e bridge Shiny → JS | 5 h | | Testes unitários dos componentes e fluxos principais | 4 h | | Documentação, JSONL do widget e evidências | 2 h | | **Total** | **30 h** | --- # Critérios de aceite globais ## 1. Mapeamento JSONL - [ ] JSONL existentes revisados e padronizados. - [ ] Funcionalidades faltantes do `geotrixMap/dev` mapeadas. - [ ] `feature_registry.jsonl` atualizado e sem duplicatas. - [ ] `rag_setup_manifest.json` atualizado. - [ ] Validação cruzada com código-fonte realizada. ## 2. Pacote `geotrixia` - [ ] API FastAPI com endpoints principais funcionando. - [ ] Chat persistente por usuário/projeto. - [ ] Reaproveitamento correto de `conversation_id`. - [ ] Lock operacional funcionando. - [ ] Metadata de execução registrada. - [ ] Testes com fakes passando sem serviços externos. - [ ] README com arquitetura, configuração e execução. ## 3. Deployment - [ ] Imagem da API buildada e enviada ao ACR. - [ ] Service e Deployment ativos no AKS. - [ ] `/health` respondendo `200`. - [ ] URL interna disponível para consumo pelo app. - [ ] Terraform e Bash compatíveis com o padrão do repositório. - [ ] Documentação mínima de deploy disponível. ## 4. Widget de IA - [ ] Widget integrado ao `geotrixMap`. - [ ] Mensagens enviadas e recebidas pela API. - [ ] Contexto de projeto, usuário e feature enviado corretamente. - [ ] Sessões de chat listadas e retomadas. - [ ] Estados de loading e erro implementados. - [ ] Testes principais passando. ---

Overdue by 1 month(s)

•

Due by June 30, 2026

0% complete0 open 0 closed

Minex - Maio/26

# MINEX MAIO 2026 ## status : NÃO APROVADO --- # 📑 Resumo de Planejamento: MINEX 3D — MAIO 2026 **Período:** Maio/2026 **Foco:** Lit/Frontend · Refatoração de componentes · Viewer 3D (refatoração isolada) **Refs:** `geotrix3d#010` · `minex_qa#018` · `arch_migration#005` **Apps e Pacotes no escopo:** - **Frontend:** `geotrixMap3D` (Lit Web Components). - **Backend:** `geotrix3dpre` (R/C++). --- ## 1. Quadro Geral de Tarefas e Tempos | ID | Tarefa | Foco Principal | Tempo Estimado | | --------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -------------: | | **1** | **Refatoração isolada do Viewer (Visualizador de Objetos 3D)** | Refactor completo do componente de visualização 3D em Lit, isolado do restante da aplicação | **50 horas** | | **2** | **Migração Lit das funcionalidades de Analysis e Results** | Refactor dos painéis e widgets de análise, resultados e exportação para Web Components | **50 horas** | | **3** | **Remodelagem Lit da casca do app 3D e componentes transversais** | Shell, navbar, tabsets, modais, open project e about da versão 3D | **30 horas** | | **4** | **Testes em nuvem, cobertura e entrega** | Gerar build de produção, rodar testes e validar cobertura | **10 horas** | | **TOTAL** | | | **140 horas** | --- ## Tarefa 1 — Refatoração isolada do Viewer (Visualizador de Objetos 3D) ### Objetivo geral Refatorar o componente de visualização de objetos 3D — o **Viewer** — de forma completamente isolada do restante da aplicação, tornando-o um Web Component autossuficiente, testável e reutilizável. Esta tarefa é tratada de forma isolada porque o Viewer possui: * lógica de renderização 3D própria (e.g., Three.js ou WebGL); * ciclo de vida desacoplado dos demais painéis; * dependências de estado específicas (câmera, cena, objetos carregados); * necessidade de testes independentes dos demais componentes. --- ### 1. Escopo funcional do Viewer #### 1.1 Renderização e câmera 1. **Carregamento de objetos 3D** (formatos suportados: OBJ, GLTF, PLY e similares) 2. **Controles de câmera** (orbit, pan, zoom) 3. **Reset de câmera** para posição padrão 4. **Toggle de wireframe / sólido / transparência** 5. **Iluminação e sombras** configuráveis 6. **Eixos e grid de referência** #### 1.2 Interação e seleção 7. **Seleção de objetos/faces** por clique 8. **Destaque visual** do objeto selecionado 9. **Painel de propriedades** do objeto selecionado (nome, vértices, faces, bounding box) 10. **Exportação de captura de tela** do canvas 3D #### 1.3 Integração com o app 11. **Evento de objeto selecionado** (`viewer-object-selected`) emitido para o shell 12. **Atualização reativa** da cena ao receber novos objetos via propriedade Lit 13. **Loading state** com spinner durante carregamento de modelos grandes 14. **Error state** com mensagem amigável quando o arquivo não pode ser renderizado --- ### 2. Diretriz arquitetural #### 2.1 Componente raiz * `mx-viewer-3d` Responsabilidades: * encapsular o canvas WebGL/Three.js dentro do Shadow DOM; * receber `objects` como propriedade Lit (array de descritores); * emitir `viewer-object-selected` ao selecionar um objeto; * emitir `viewer-ready` após a cena estar carregada; * expor método público `resetCamera()`; * gerenciar o ciclo de vida da cena (criação, atualização, destruição). #### 2.2 Subcomponentes * `mx-viewer-toolbar` — controles de câmera, wireframe, eixos, captura * `mx-viewer-properties-panel` — propriedades do objeto selecionado * `mx-viewer-loading-overlay` — estado de carregamento * `mx-viewer-error-state` — estado de erro #### 2.3 Regras obrigatórias **Proibido** * acesso direto ao DOM externo via `querySelector`; * estado global fora do componente sem contrato explícito; * dependência imperativa do Shiny para controle da cena; * vazamento de eventos de mouse para o documento raiz. **Obrigatório** * Shadow DOM em todos os subcomponentes; * state-driven rendering com Lit; * `CustomEvent` documentados para integração; * ciclo de vida `disconnectedCallback` limpa a cena 3D; * encapsulamento total de estilos. --- ### 3. Critérios de teste #### 3.1 Testes unitários Lit Cada subcomponente deve ter, no mínimo: * renderização inicial com props padrão; * renderização com props populadas; * dispatch do evento correto ao selecionar objeto; * exibição correta dos estados: loading, error, ready; * reset de câmera via método público; * bloqueio de interação durante loading. #### 3.2 Testes de integração Fluxos mínimos: * `mx-viewer-3d` recebe array de objetos e renderiza a cena; * seleção de objeto dispara `viewer-object-selected` com payload correto; * troca de objeto atualiza o painel de propriedades; * arquivo inválido exibe `mx-viewer-error-state`; * reset de câmera retorna para posição padrão. #### 3.3 Metas de qualidade * **Cobertura Lit/logic ≥ 80%** * **Zero erros de console** * **Contratos de eventos documentados** * **Canvas isolado no Shadow DOM — sem vazamento para o documento** * **Destruição correta da cena no `disconnectedCallback`** --- ### 4. Entregáveis da Tarefa 1 * `src/components/viewer/mx-viewer-3d/` * `src/components/viewer/mx-viewer-toolbar/` * `src/components/viewer/mx-viewer-properties-panel/` * `src/components/viewer/mx-viewer-loading-overlay/` * `src/components/viewer/mx-viewer-error-state/` * `src/components/viewer/__tests__/` * `registry/app/viewer.app.json` * `registry/tests/viewer.tests.json` * `README.md` técnico com API do componente * evidências em `production/frontend/viewer/` --- ### 5. Estimativa de esforço da Tarefa 1 | Bloco | Horas | | ------------------------------------------------------------ | ----: | | Setup isolado: canvas, cena, ciclo de vida | 10h | | Controles de câmera e interação (orbit, pan, zoom, wireframe) | 10h | | Seleção de objetos e painel de propriedades | 10h | | Integração reativa (propriedades Lit + eventos) | 8h | | Testes unitários e de integração | 8h | | Documentação, contratos e entregáveis | 4h | **Total: 50 horas** --- ## Tarefa 2 — Migração Lit das funcionalidades de Analysis e Results ### Objetivo geral Migrar os painéis e widgets de **Analysis** e **Results** do Minex 3D para a arquitetura de Web Components (Lit), eliminando dependências de manipulação imperativa do DOM e criando componentes isolados, rastreáveis, testáveis e reutilizáveis. Esta tarefa é a frente de refactor dedicada às funcionalidades analíticas e de visualização de resultados da versão 3D do app. --- ### 1. Escopo funcional #### 1.1 Analysis 1. **Correlation** (incluindo Quick View de duas variáveis) 2. **Important Features** 3. **Factor Analysis of Mixed Data (FAMD)** 4. **Optimal Grid Size** 5. **Linear Directional Mean** #### 1.2 Results e exportação 6. **Results Panel** — listagem e navegação por resultados 7. **Export Widget** — exportação de resultados em formatos suportados 8. **Comparison View** — comparação side-by-side de dois resultados 9. **Layer Toggle no Results** — visibilidade de camadas a partir dos resultados --- ### 2. Diretriz arquitetural Cada unidade migrada deve ter: * `component_tag` * `@property` e `@state` bem definidos * `events_emitted` e `events_received` documentados * `validation_rules` explícitas * `server_contract` com schema do payload * `test_refs` vinculados #### Regras obrigatórias **Proibido** * `classList.toggle` para orquestrar visibilidade; * `querySelector` para obter estado de outro componente; * validação espalhada entre DOM e servidor sem contrato. **Obrigatório** * state-driven rendering; * template condicional do Lit; * contratos de evento com `CustomEvent`; * Shadow DOM e encapsulamento de estilo; * composição por subcomponentes. --- ### 3. Agrupamento por complexidade #### 3.1 Componentes complexos * `mx-correlation-panel` (inclui Quick View) * `mx-results-panel` * `mx-comparison-view` Características: múltiplos submodos, integração com Viewer 3D, payloads ricos. #### 3.2 Componentes intermediários * `mx-important-features-panel` * `mx-famd-panel` * `mx-export-widget` * `mx-layer-toggle-results` #### 3.3 Componentes padronizados * `mx-optimal-grid-panel` * `mx-linear-directional-mean-panel` --- ### 4. Critérios de aceite * Cobertura Lit/logic ≥ 80% * Zero erros de console * Contratos de payload documentados * Sem dependência crítica de manipulação direta do DOM * UI navegável por teclado nos fluxos principais * Results Panel integrado com o Viewer 3D via eventos --- ### 5. Entregáveis da Tarefa 2 * `src/components/analysis/` * `src/components/results/` * `src/components/__tests__/` * `registry/app/<feature_id>.app.json` por componente * `registry/tests/<feature_id>.tests.json` por componente * `README.md` técnico por grupo * evidências em `production/frontend/analysis/` e `production/frontend/results/` --- ### 6. Estimativa de esforço da Tarefa 2 | Bloco | Horas | | ---------------------------------------------- | ----: | | Componentes padronizados (2 painéis) | 10h | | Componentes intermediários (4 painéis) | 18h | | Componentes complexos (3 painéis) | 16h | | Integração com Viewer 3D e contratos de evento | 6h | **Total: 50 horas** --- ## Tarefa 3 — Remodelagem Lit da casca do app 3D e componentes transversais ### Objetivo geral Executar a remodelagem Lit das partes transversais do Minex 3D que organizam navegação, contexto, orientação de uso e interação global, incluindo: * **Shell estrutural** do app 3D * **Navbar** * **Tabsets principais** * **Modal manager global** * **Open Project** (versão 3D) * **Helper Panel** (suporte e contexto) * **About** (documentação e FAQ) O objetivo é criar uma **camada estrutural Lit** que estabilize navegação, comunicação entre áreas e gerenciamento de estado de alto nível, servindo de base para os refactors das Tarefas 1 e 2. --- ### 1. Escopo funcional #### 1.1 Shell estrutural 1. **App Shell Lit** (`mx-app-shell-3d`) 2. **Navbar** (`mx-main-navbar-3d`) 3. **Tabsets principais** (`mx-tabset`, `mx-tab`, `mx-tab-panel`) 4. **Gerência de sidebar / panel host** 5. **Modal manager global** (`mx-modal-host`) #### 1.2 Componentes transversais de negócio 6. **Open Project 3D** — carregamento, metadados, layers, warning panel 7. **Helper Panel** — busca contextual, seções por funcionalidade, parâmetros explicados 8. **About** — documentação, FAQ, links de suporte, seções colapsáveis #### 1.3 Elementos transversais de UX 9. **Modais de confirmação** 10. **Modais de loading / erro / sucesso** 11. **Componentes compartilhados** (cards, alertas, placeholders, estados vazios) --- ### 2. Critérios de aceite #### 2.1 Técnicos * Estado global explícito e documentado * Modal manager operacional * Navegação por abas sem hacks de DOM * Navbar e tabsets desacoplados da implementação Shiny imperativa * Compatibilidade com Viewer 3D e painéis migrados nas Tarefas 1 e 2 #### 2.2 UX * Feedback claro de aba ativa * Carregamento previsível * Warning panel do Open Project integrado * Modais consistentes * Helper Panel reutilizável e acessível #### 2.3 Testes * Testes unitários de shell, navbar e tabsets * Testes unitários de modais * Testes de integração do fluxo Open Project 3D * Testes do Helper Panel * Testes de troca de aba e abertura/fechamento de modal --- ### 3. Entregáveis da Tarefa 3 * `src/components/shell/` * `src/components/navbar/` * `src/components/tabset/` * `src/components/modals/` * `src/components/open-project/` * `src/components/help-panel/` * `src/components/about/` * `src/shared/` * `__tests__/` * `README.md` técnico por grupo * evidências de cobertura e integração em `production/frontend/shell/` --- ### 4. Estimativa de esforço da Tarefa 3 | Bloco | Horas | | ----------------------------------------------------- | ----: | | App shell + estado global + contratos de evento | 6h | | Navbar + tabsets | 5h | | Modal manager + modais compartilhados | 5h | | Open Project 3D (carregamento, layers, warning panel) | 6h | | Helper Panel + About + documentação | 5h | | Ajustes de integração com Viewer e Analysis | 3h | **Total: 30 horas** --- ## Tarefa 4 — Testes em nuvem, cobertura e entrega ### Objetivo geral Gerar o build de produção dos pacotes refatorados, executar os testes em ambiente de nuvem e garantir que a cobertura dos componentes Lit atinja o padrão exigido (≥ 80%). --- ### 1. Atividades * **Build de produção:** compilar e empacotar todos os componentes Lit refatorados * **Testes em nuvem:** executar a suite completa (unitários + integração) no ambiente de CI/CD * **Coverage report:** gerar relatório de cobertura (`coverage/index.html`, `coverage/coverage-frontend.xml`) * **Métricas:** registrar tempos de execução em `metrics/test_times.csv` * **Changelog:** atualizar changelog e versionar documentação * **Validação:** confirmar que todos os critérios de aceite das Tarefas 1, 2 e 3 estão satisfeitos --- ### 2. Critérios de aceite * Build de produção sem erros * Cobertura ≥ 80% em todos os componentes Lit refatorados * Zero erros de console em produção * Evidências de execução auditáveis (`production/frontend/cmd_output.txt`) * Changelog atualizado e versionado --- ### 3. Estimativa de esforço da Tarefa 4 | Bloco | Horas | | ----------------------------------- | ----: | | Build e empacotamento | 2h | | Testes em nuvem e análise de falhas | 4h | | Coverage report e métricas | 2h | | Changelog e documentação final | 2h | **Total: 10 horas** --- ## Resumo e Milestones (Maio/2026) | **Tarefa** | **Foco** | **Total** | | ------------------------------------------- | --------------------------------------------------- | --------: | | **1. Refatoração isolada do Viewer 3D** | Viewer como Web Component autossuficiente | **50 h** | | **2. Migração Lit de Analysis e Results** | Painéis analíticos e de resultados em Lit | **50 h** | | **3. Remodelagem Lit da casca do app 3D** | Shell, navbar, tabsets, modais, open project, about | **30 h** | | **4. Testes em nuvem, cobertura e entrega** | Build, CI/CD, coverage, changelog | **10 h** | | **TOTAL ESTIMADO** | | **140 h** | --- ## Critérios de Aceite Globais (Definition of Done) 1. **Viewer 3D:** - [ ] `mx-viewer-3d` renderiza objetos 3D a partir de propriedades Lit sem manipulação direta do DOM externo. - [ ] Seleção de objeto emite `viewer-object-selected` com payload correto. - [ ] Cena é destruída corretamente no `disconnectedCallback` (sem memory leak). - [ ] Cobertura Lit ≥ 80% nos subcomponentes do Viewer. 2. **Analysis e Results:** - [ ] Todos os painéis de Analysis funcionam como Web Components independentes. - [ ] Results Panel integra com o Viewer 3D via eventos documentados. - [ ] Cobertura Lit/logic ≥ 80% em todos os componentes migrados. - [ ] Zero dependência de `querySelector` para orquestrar estado entre painéis. 3. **Casca do app 3D:** - [ ] Shell estrutural gerencia navegação sem hacks de DOM. - [ ] Modal manager controla confirmações, loading e feedbacks globais. - [ ] Open Project 3D carrega projeto, exibe layers e warning panel corretamente. - [ ] Navbar e tabsets desacoplados do Shiny imperativo. 4. **Qualidade geral:** - [ ] Build de produção sem erros. - [ ] Cobertura ≥ 80% em todos os componentes refatorados. - [ ] Zero erros de console em produção. - [ ] Changelog atualizado e evidências de execução auditáveis. --- ## Ordem sugerida de execução 1. **Tarefa 3** — Casca do app (base estrutural necessária para as demais) 2. **Tarefa 1** — Viewer 3D (isolado; pode rodar em paralelo com Tarefa 3) 3. **Tarefa 2** — Analysis e Results (depende da casca e do Viewer) 4. **Tarefa 4** — Testes em nuvem e entrega

Overdue by 2 month(s)

•

Due by May 29, 2026

0% complete0 open 0 closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

JULHO/26 - MINEX

JUNHO/26 - MINEX

Minex - Maio/26

List view

JULHO/26 - MINEX

JUNHO/26 - MINEX

Minex - Maio/26