Preflight de Cloud Run Jobs para inspeção industrial com Claude Code
Revise CSV de inspeção, fotos, aprovações, variáveis e secrets antes de passar ao Cloud Run Jobs.
No fim do turno da noite, a pessoa de qualidade está prestes a entregar o CSV de inspeção e a lista de fotos para o processamento em nuvem. O líder de linha interrompe: esse lote ainda não foi aprovado. O CSV mistura linhas pass, hold e fail; uma URI de foto parece conter nome de operador; a planilha de variáveis de ambiente ainda traz um valor parecido com API key em texto puro. O job talvez rode, mas depois ficará difícil explicar esse envio em auditoria, investigação de defeito ou resposta ao cliente.
Este artigo mostra como criar, com Claude Code, um preflight antes de passar relatórios de inspeção industrial para Cloud Run Jobs. Cloud Run Jobs é voltado a cargas batch: um contêiner inicia, executa tarefas e termina, em vez de ficar ouvindo HTTP. Aqui não conectamos ao Google Cloud. O título está limitado a uma revisão local de contrato antes da execução, não a uma integração ao vivo.
As afirmações técnicas sujeitas a mudança foram conferidas em fontes oficiais: criar Cloud Run Jobs, variáveis de ambiente para jobs, secrets para jobs, identidade de serviço para jobs e Claude Code settings. O teste local prova apenas o contrato de entrada local; não prova autenticação, IAM, acesso a storage ou comportamento em produção.
Pontos principais
- Reúna CSV de inspeção, regras de URI de foto, configuração do Cloud Run Job e checklist de aprovação em uma revisão prévia.
- Peça ao Claude Code para ler colunas, tipos de valor, aprovação, regras de nomes, variáveis de ambiente e fronteira do Secret Manager.
- Deixe pessoas decidirem lote bloqueado, explicação ao cliente, retenção, escopo da conta de serviço e aprovação final de qualidade.
- Comece com fixtures locais fictícios. Este artigo não chama Cloud Run, Cloud Storage, Secret Manager nem MES de fábrica.
- A CTA principal única é treinamento e consultoria para desenhar essa fronteira na empresa.
Fluxo: transformar relatórios de inspeção em contrato de job
O fluxo serve para inspeção visual, dimensional, revisão de equipamentos ou resumo de qualidade no fim do turno. As entradas comuns são inspection_results.csv, lista de URIs de fotos, tabela de variáveis do job batch e checklist de aprovação. MES significa sistema de execução de manufatura, usado para ordens, status de processo e resultados de inspeção.
O primeiro passo não é pedir à IA que decida se o lote está bom. É definir a forma que uma entrada precisa ter antes de entrar no job. Neste exemplo, o CSV deve conter report_id, line_id, product_code, lot_no, measured_value, unit, status, inspector, approved, photo_uri e retention_until. status aceita apenas pass, hold e fail. Linha com approved diferente de yes não entra no input do job.
URIs de foto também não devem virar campo de anotação. Um formato melhor é gs://factory-qc-evidence/line-a/2026-09/LOT-1042/report-QC-9001-01.webp, com linha, mês, lote e ID de relatório. Não coloque nome de operador, e-mail, telefone ou nome completo na chave do objeto. Artigos relacionados cobrem relatório de problema de qualidade na manufatura e revisão de manifesto GKE para manufatura. Aqui focamos no contrato antes do batch cloud.
Depois revisamos a configuração do Cloud Run Job. A documentação do Google Cloud explica que variáveis de ambiente são injetadas como pares chave/valor acessíveis pelo código do contêiner e alerta para não armazenar secrets nelas. Para secrets, use referências do Secret Manager. Se o job acessa APIs do Google Cloud, revise a identidade de serviço, isto é, a conta de serviço usada pelo job. Claude Code monta a tabela; humanos aprovam conta e papéis.
flowchart TD
A[Preparar CSV local de inspeção] --> B[Checar URI de fotos e retenção]
B --> C[Revisar fronteira env/secret do Cloud Run Job]
C --> D[Claude Code gera tabela de achados]
D --> E[Qualidade decide hold/fail]
E --> F[Após aprovação, humano entrega ao gcloud ou CI]
O que fica com Claude Code e o que fica com pessoas
Claude Code deve cuidar das verificações repetíveis do contrato. Ele encontra colunas ausentes, medições não numéricas, linhas sem aprovação, padrões suspeitos em photo_uri, imagens com :latest, serviceAccount como default e variáveis chamadas PASSWORD, TOKEN ou API_KEY. Também ajuda a comparar CSV, JSON do job e checklist lado a lado para gerar a tabela de revisão.
Pessoas decidem responsabilidade de qualidade e risco operacional. Alguém decide se um lote hold será reinspecionado, se o envio para, o que explicar ao cliente, se a retenção das fotos cumpre contrato, quais permissões mínimas a conta recebe e quando um job noturno deve parar. A saída do Claude Code é evidência para decisão, não parecer jurídico, garantia de qualidade ou prova de IAM.
Em permissões, use settings do Claude Code para limitar leitura de arquivos e execução Bash. Deixe .env, CSV produtivo e dados pessoais sem anonimização fora do prompt. Trabalhe primeiro com fixtures fixos e mova apenas a tabela de revisão para o procedimento real. O pedido é “verifique se está pronto para aprovação humana”, não “faça upload”.
Três casos de uso
Use case 1: decidir quais linhas do CSV entram no job
Entrada: CSV de inspeção, definição de colunas, valores permitidos para status, campo de aprovação e data de retenção. O arquivo pode misturar pass, hold e fail.
Saída: tabela de colunas faltantes, datas inválidas, linhas sem aprovação, medições não numéricas e retenção ausente. A saída separa pronto, revisão humana e bloqueado.
Confirmação humana: qualidade decide se linha hold ou fail é excluída, reinspecionada ou escalada para bloqueio de lote.
Use case 2: evitar dados pessoais ou temporários em URIs de foto
Entrada: lista de URIs, regra de nome, ID de linha, lote e ID de relatório. Na pressa, a foto pode guardar nome de operador, dispositivo ou pasta temporária.
Saída: achados de e-mail, telefone, nome legível, private e tmp. Claude Code também propõe uma URI mais segura.
Confirmação humana: o time decide o ID mínimo rastreável, o que fica no registro restrito e quais padrões de chave são permitidos.
Use case 3: revisar a fronteira de secrets do Cloud Run Job
Entrada: JSON de configuração, tabela de variáveis, chaves planejadas para Secret Manager, conta de serviço, retries e timeout.
Saída: tabela mostrando se API_KEY, PASSWORD, TOKEN ou SECRET aparecem em env plano, se há referências secret, se a conta é dedicada e se a imagem evita :latest.
Confirmação humana: administradores cloud decidem recursos do Secret Manager, papéis mínimos e se um job com falha pode ser repetido.
Prompt para copiar
Você é responsável pelo preflight antes de passar um relatório de inspeção industrial a um Cloud Run Job.
Objetivo: alinhar CSV de inspeção, regras de URI de foto, configuração do Job e checklist de aprovação antes da execução.
Entradas:
- Amostra de CSV de inspeção:
- Regra de nome para URI de foto:
- JSON de configuração do Cloud Run Job:
- Checklist de aprovação:
- Regras de retenção e exclusão:
Verifique:
1. Colunas obrigatórias ausentes
2. measured_value não numérico
3. status fora de pass/hold/fail
4. approved diferente de yes
5. photo_uri com nomes, e-mails, telefones, tmp ou private
6. image do Job usando latest
7. env com API_KEY/PASSWORD/TOKEN em texto puro
8. serviceAccount não default e permissões a confirmar
Saída:
- Tabela "pronto", "revisão humana" e "bloqueado"
- Sugestões de correção
- Itens para aprovação humana
- Fronteiras não verificadas
Restrições:
- Não conectar a serviços cloud reais
- Não manter CSV produtivo nem dados pessoais na saída
- Não inserir ClaudeCodeLab, links de treinamento ou CTA do site no artefato gerado
Validador local executável
O código abaixo verifica apenas fixtures fixos do artigo. Ele não chama Cloud Run API, Cloud Storage, Secret Manager, MES ou rede. Se salvar localmente, use tools/inspection-job-preflight.mjs; isso não significa que o arquivo já exista neste repositório.
const requiredColumns = ["report_id","line_id","product_code","lot_no","measured_value","unit","status","inspector","approved","photo_uri","retention_until"];
const inspectionCsv = `report_id,line_id,product_code,lot_no,measured_value,unit,status,inspector,approved,photo_uri,retention_until
QC-9001,line-a,P-441,LOT-1042,0.31,mm,pass,EMP-014,yes,gs://factory-qc-evidence/line-a/2026-09/LOT-1042/report-QC-9001-01.webp,2027-09-30
QC-9002,line-a,P-441,LOT-1042,not-number,mm,hold,EMP-014,no,gs://factory-qc-evidence/private/[email protected],2027-09-30
QC-9003,line-b,P-882,LOT-2099,12.8,N,review,EMP-091,yes,gs://factory-qc-evidence/line-b/tmp/LOT-2099/report-QC-9003.webp,`;
const jobConfig = { name: "inspection-summary-job", image: "asia-northeast1-docker.pkg.dev/factory/prod/inspection-summary:latest", serviceAccount: "default", maxRetries: 3, timeoutSeconds: 1800, env: { REPORT_BUCKET: "factory-qc-evidence", API_KEY: "plain-text-key" }, secrets: { DB_PASSWORD: "projects/123456789/secrets/qc-db-password:2" } };
function parseCsv(text) { const [headerLine, ...rows] = text.trim().split("\n"); const headers = headerLine.split(","); return rows.map((line) => { const values = line.split(","); return Object.fromEntries(headers.map((header, index) => [header, values[index] ?? ""])); }); }
function looksLikeIsoDate(value) { return /^\d{4}-\d{2}-\d{2}$/.test(value) && !Number.isNaN(Date.parse(value)); }
function validateRows(rows) { const issues = []; const allowedStatus = new Set(["pass", "hold", "fail"]); for (const [index, row] of rows.entries()) { const rowNo = index + 1; for (const column of requiredColumns) { if (!(column in row) || row[column].trim() === "") issues.push({ scope: `row ${rowNo}`, severity: "block", message: `missing ${column}` }); } if (!Number.isFinite(Number(row.measured_value))) issues.push({ scope: `row ${rowNo}`, severity: "block", message: "measured_value must be numeric" }); if (!allowedStatus.has(row.status)) issues.push({ scope: `row ${rowNo}`, severity: "block", message: "status must be pass, hold, or fail" }); if (row.status !== "pass" || row.approved !== "yes") issues.push({ scope: `row ${rowNo}`, severity: "review", message: "human approval required before handoff" }); if (!looksLikeIsoDate(row.retention_until)) issues.push({ scope: `row ${rowNo}`, severity: "review", message: "retention_until must be an ISO date" }); if (/@|\b\d{2,4}[- ]\d{2,4}[- ]\d{3,4}\b|private|tmp/i.test(row.photo_uri)) issues.push({ scope: `row ${rowNo}`, severity: "review", message: "photo_uri may expose personal or temporary data" }); } return issues; }
function validateJobConfig(config) { const issues = []; if (/:latest\b/.test(config.image)) issues.push({ scope: "job.image", severity: "block", message: "pin the image tag or digest instead of latest" }); if (!config.serviceAccount || config.serviceAccount === "default") issues.push({ scope: "job.serviceAccount", severity: "block", message: "use a dedicated service account" }); for (const key of Object.keys(config.env ?? {})) { if (/(API_KEY|PASSWORD|TOKEN|SECRET)/i.test(key)) issues.push({ scope: `job.env.${key}`, severity: "block", message: "move secrets to Secret Manager references" }); } if (!config.secrets || Object.keys(config.secrets).length === 0) issues.push({ scope: "job.secrets", severity: "review", message: "list required Secret Manager references" }); if (!Number.isInteger(config.maxRetries) || config.maxRetries < 0 || config.maxRetries > 5) issues.push({ scope: "job.maxRetries", severity: "review", message: "confirm retry count with operations" }); return issues; }
const rows = parseCsv(inspectionCsv);
const report = [...validateRows(rows), ...validateJobConfig(jobConfig)];
console.table(report);
process.exitCode = report.some((item) => item.severity === "block") ? 1 : 0;
Esse código prova apenas parsing local e validação de fixture. Ele não prova que o Job pode ser criado, que a conta tem os papéis corretos, que o secret existe, que a foto existe ou que o batch termina em produção.
Armadilhas e correções
A primeira armadilha é deixar linhas hold passarem porque “alguém olha depois”. A causa é misturar agregação e decisão de qualidade no mesmo batch. Corrija separando pass, hold e fail antes do input; hold e fail vão para fila humana, não para o payload.
A segunda armadilha é usar URI de foto como campo de nota. Nome de operador, e-mail, dispositivo, tmp ou private tornam exclusão e acesso mais difíceis de explicar. Corrija limitando a URI a linha, mês, lote e ID do relatório, e deixando identidade ou motivo em registro restrito.
A terceira armadilha é tratar variável de ambiente e secret como iguais. Cloud Run Jobs permite variáveis, mas o Google Cloud recomenda Secret Manager para segredos. Corrija mantendo apenas ajustes não secretos em env e movendo connection strings, API keys, senhas e tokens para referências secret.
A quarta armadilha é manter serviceAccount: default. A causa é pensar que se o Job roda, as permissões estão desenhadas. Corrija com conta dedicada ao job, papéis mínimos por API Google Cloud e aprovador registrado no checklist.
Medição pequena de ROI
Não invente percentual de economia. Conte trabalho bloqueado. Por duas semanas, registre linhas CSV, problemas bloqueantes, itens de revisão humana, reenvios, tempo entre exportar CSV e handoff, chamadas noturnas. Depois do preflight, meça o mesmo por mais duas semanas. Bons sinais são linhas não aprovadas detectadas cedo, URIs corrigidas, secrets a migrar e devoluções antes do turno da noite.
O objetivo não é dizer que Claude Code sempre economiza minutos fixos. Planta, número de linhas, estrutura de aprovação e frequência do Job mudam o resultado. O primeiro ROI é encontrar entradas que não devem ir ao batch enquanto as pessoas certas ainda estão disponíveis.
Perguntas frequentes
Q. Pode ser um serviço Cloud Run em vez de Job?
A. Use serviço para HTTP contínuo. Use Job quando um contêiner processa um lote e termina. Este artigo cobre só o preflight local antes de Cloud Run Jobs.
Q. Posso mostrar o CSV real ao Claude Code?
A. Comece com fixtures anonimizados. Para CSV produtivo, confirme regras internas de permissão, local, auditoria e colunas proibidas. Isto não é conselho jurídico ou de auditoria.
Q. Colocar o validador no CI basta?
A. Não. CI bloqueia parte do contrato. Aprovação de qualidade, identidade de serviço, Secret Manager, IAM e logs reais exigem revisão separada.
Q. O que entregar ao Claude Code?
A. Fixtures fixos, definição de colunas, regras de nomes, JSON do Job e checklist. Não cole .env, chaves produtivas, dados pessoais sem máscara nem contratos de fornecedores.
Levar para operações
Um preflight cloud de manufatura não é só código. Qualidade, operações, TI e administração cloud precisam separar, com a mesma linguagem, o que a IA verifica e o que pessoas podem parar. Para desenhar fronteira de permissões, tabela de revisão, prompt e planilha ROI em torno de Cloud Run Jobs e CSV de inspeção, use treinamento e consultoria.
O que testei de fato
Testei o validador JavaScript acima com node contra fixtures locais fixos. A saída detecta measured_value não numérico, linhas sem aprovação, status inválido, photo_uri com private e tmp, imagem :latest, conta default e API_KEY em texto puro.
As URLs oficiais revisadas foram criação de Cloud Run Jobs, variáveis de ambiente, secrets, identidade de serviço e Claude Code settings. Não executei gcloud run jobs create, não chamei Cloud Run API, não li Cloud Storage, não acessei Secret Manager, não verifiquei IAM, não conectei MES nem inspecionei CSV produtivo. A evidência vai apenas até a checagem local do contrato de entrada.
Artigos relacionados
Deploy no GCP Cloud Run com Claude Code: guia prático
Publique uma API Node.js segura no Cloud Run com Docker, IAM, secrets, logs e rollback.
Indústria de alimentos: agilize descrições de produto e a checagem de alergênicos com Claude Code
Indústria de alimentos: gere descrições e confira alergênicos com Claude Code. Inclui prompt e script de verificação prontos.
Preflight de CSV de reservas de hotel para nuvem com Claude Code
Revise CSVs de hotel antes da nuvem: dados pessoais, consentimento, chaves de objeto e aprovação.
PDF grátis: cheatsheet do Claude Code
Informe seu e-mail e baixe uma página com comandos, hábitos de revisão e workflows seguros.
Cuidamos dos seus dados e não enviamos spam.
Sobre o autor
Masa
Engenheiro focado em workflows práticos com Claude Code.