Módulo: Prótese Capilar – BarberBot

Domínio único • painel administrativo • cadastro de próteses • análise capilar por IA • simulação visual • manutenção recorrente • atualizado em 18/03/2026
pasta base: sistema/painel/paginas/ tabelas: proteses, analise_capilar, simulacoes_protese, manutencoes_protese IA: OpenAI via config.openai_key

Este documento foi montado com base no código real do BarberBot e no dump do banco. O objetivo é deixar o próximo dev confortável para: localizar arquivos, entender o fluxo completo do módulo, saber quais tabelas são impactadas, identificar dependências externas e não quebrar o ciclo prótese → análise → simulação → manutenção.

Navegação rápida

Escopo do módulo

O conjunto de páginas de prótese capilar no BarberBot atende um fluxo específico do negócio: cadastro da prótese vinculada ao cliente, análise capilar com apoio de IA, simulação visual da aplicação e manutenção periódica com previsão de próxima visita e alerta automático.

Importante: a estrutura atual está em domínio único. Não há isolamento multi-tenant no desenho desse módulo. Portanto, quando esta documentação falar em “empresa” ou “configuração”, o comportamento observado é global para a instalação.

Objetivo funcional

  • Registrar modelos de prótese por cliente.
  • Analisar imagem do couro cabeludo e sugerir características técnicas.
  • Gerar simulação visual manual ou por IA.
  • Controlar manutenções futuras e alertar clientes vencidos.

Pontos de entrada

  • sistema/painel/index.php?pag=proteses
  • sistema/painel/index.php?pag=analises
  • sistema/painel/index.php?pag=simulador
  • sistema/painel/index.php?pag=manutencoes

Mapa técnico e pastas

Arquivos principais do painel

Arquivo Responsabilidade
sistema/painel/paginas/proteses.phpTela principal do CRUD de próteses (modal + listagem + busca).
sistema/painel/paginas/analises.phpTela principal da análise capilar, com preview e apoio à IA.
sistema/painel/paginas/simulador.phpTela principal da simulação visual, incluindo seleção de prótese por cliente.
sistema/painel/paginas/manutencoes.phpTela principal do histórico e agendamento de manutenção da prótese.
cron/alerta_manutencao.phpRotina automática para avisar clientes com manutenção vencida.
protese.phpPágina pública do tema prótese capilar no front do site.

Subpastas de suporte

Pasta / arquivo Papel no fluxo
sistema/painel/paginas/proteses/listar.php, salvar.php, excluir.php.
sistema/painel/paginas/analises/listar.php, salvar.php, excluir.php, processar.php, buscar_protese.php.
sistema/painel/paginas/simulador/listar.php, salvar.php, excluir.php, buscar.php, gerar_ia.php, canvas.php, salvar_canvas.php.
sistema/painel/paginas/manutencoes/listar.php, salvar.php, excluir.php.
sistema/painel/images/analises/Armazena fotos brutas da análise capilar.
sistema/painel/images/simulacoes/Armazena foto original e imagem simulada/canvas.
Leitura rápida para manutenção: quem for mexer nesse módulo normalmente precisa abrir primeiro: proteses.php, analises.php, simulador.php, manutencoes.php, depois os respectivos listar.php/salvar.php e por fim o cron/alerta_manutencao.php.

Fluxo funcional real

1. Cadastro da prótese O atendente vincula cliente + modelo + fornecedor + características técnicas.
→
2. Análise capilar É enviada uma foto do couro cabeludo e o sistema pode preencher os campos manualmente ou via IA.
→
3. Simulação visual Usa a foto original e a prótese escolhida para gerar uma imagem simulada por IA ou ajuste fino no canvas.
→
4. Manutenção Registra a manutenção realizada, calcula a próxima data e permite alertar/agendar retorno.

Relação entre os submódulos

  • Prótese é a base de referência técnica para simulação e manutenção.
  • Análise ajuda a decidir características como cor, densidade e nível de falha.
  • Simulador depende de cliente + prótese cadastrada + foto original.
  • Manutenção depende de cliente + prótese e usa dados técnicos para estimar o próximo retorno.
Painel -> página principal do módulo
       -> AJAX/POST para salvar/listar/processar
       -> PDO / MySQL
       -> imagens em /sistema/painel/images
       -> retorno HTML ou JSON para o front

Banco de dados do módulo

Tabela proteses

id, cliente, modelo, cor, densidade, tamanho, observacoes, data_cad, usuario, fornecedor

Tabela analise_capilar

id, cliente, foto, cor_detectada, densidade_detectada, grau_falha, sugestao_protese, observacoes, data_analise

Tabela simulacoes_protese

id, cliente, id_protese, foto_original, imagem_simulada, observacoes, data_simulacao

Tabela manutencoes_protese

id, id_protese, cliente, data_manutencao, tipo, produtos_utilizados, observacoes, proxima_manutencao, usuario,
alerta_manutencao_enviado, data_alerta_manutencao, tipo_pele, nivel_sudorese, clima, tipo_adesivo
Relacionamentos observados no código: proteses.cliente → clientes.id, proteses.fornecedor → fornecedores.id, analise_capilar.cliente → clientes.id, simulacoes_protese.cliente → clientes.id, simulacoes_protese.id_protese → proteses.id, manutencoes_protese.cliente → clientes.id, manutencoes_protese.id_protese → proteses.id.

Submódulo: Próteses

Arquivos

  • sistema/painel/paginas/proteses.php — tela principal, modal e JS de listagem.
  • sistema/painel/paginas/proteses/listar.php — tabela HTML com paginação e ações.
  • sistema/painel/paginas/proteses/salvar.php — insert/update via PDO.
  • sistema/painel/paginas/proteses/excluir.php — exclusão do registro.

O que ele grava

  • Cliente dono da prótese.
  • Modelo, cor, densidade e tamanho.
  • Fornecedor vinculado.
  • Observações técnicas.

Fluxo resumido

proteses.php
  -> abrir modal
  -> enviar formulário para proteses/salvar.php
  -> recarregar listagem via proteses/listar.php
Ponto de atenção: no estado atual observado, o insert de proteses/salvar.php grava data_cad, mas não preenche o campo usuario, embora a tabela exija esse dado no schema.

Submódulo: Análise capilar

Arquivos

  • sistema/painel/paginas/analises.php — tela com preview, ficha técnica e gatilho para IA.
  • sistema/painel/paginas/analises/salvar.php — upload da foto e persistência do laudo.
  • sistema/painel/paginas/analises/processar.php — envia imagem para IA e devolve JSON com diagnóstico.
  • sistema/painel/paginas/analises/buscar_protese.php — busca a prótese mais recente do cliente para pré-preencher dados.
  • sistema/painel/paginas/analises/listar.php — listagem do histórico.

Contrato esperado da IA

{
  "cor_detectada": "...",
  "densidade_detectada": "...",
  "grau_falha": "...",
  "sugestao_protese": "...",
  "observacoes": "..."
}

Dependência externa

O processamento usa config.openai_key e faz chamada HTTP para https://api.openai.com/v1/responses com imagem em base64.

Comportamento útil para o dev: buscar_protese.php tenta localizar a última prótese do cliente para sugerir modelo, cor, densidade, tamanho e observacoes.
Ponto de atenção: o upload de imagem valida por extensão, mas a manutenção do módulo fica mais segura se também validar MIME real, tamanho máximo e regravar o nome do arquivo sempre.

Submódulo: Simulador

Arquivos

  • sistema/painel/paginas/simulador.php — tela principal da simulação.
  • sistema/painel/paginas/simulador/salvar.php — upload da foto original e imagem simulada manual.
  • sistema/painel/paginas/simulador/gerar_ia.php — usa IA para editar a foto original com base nos dados da prótese.
  • sistema/painel/paginas/simulador/canvas.php — editor visual para ajuste fino.
  • sistema/painel/paginas/simulador/salvar_canvas.php — persiste a imagem final em PNG base64.
  • sistema/painel/paginas/simulador/buscar.php — devolve paths de imagem para preview.
  • sistema/painel/paginas/simulador/listar.php — listagem do histórico de simulações.

Fluxo prático

Selecionar cliente
  -> carregar próteses do cliente
  -> enviar foto original
  -> gerar imagem simulada (manual / IA / canvas)
  -> salvar em simulacoes_protese

Dependências

  • Pasta sistema/painel/images/simulacoes/ precisa existir e ser gravável.
  • gerar_ia.php depende de config.openai_key.
  • canvas.php usa a própria foto original como base para ajuste fino.
Ponto crítico: no código observado, simulador/gerar_ia.php monta consulta com interpolação direta do $id na cláusula WHERE. Em manutenção futura, prefira prepare() + bind.

Submódulo: Manutenção

Arquivos

  • sistema/painel/paginas/manutencoes.php — tela principal com formulário e histórico.
  • sistema/painel/paginas/manutencoes/salvar.php — grava a manutenção e calcula a próxima data.
  • sistema/painel/paginas/manutencoes/listar.php — lista histórico e marca status visual.
  • sistema/painel/paginas/manutencoes/excluir.php — exclui registro.
  • cron/alerta_manutencao.php — envia alerta para clientes vencidos.

Lógica técnica relevante

Quando proxima_manutencao vem vazia, o sistema calcula automaticamente com base em: tipo_pele, nivel_sudorese, clima e tipo_adesivo. 

base = 15 dias
ajustes por pele / sudorese / clima / adesivo
limite mínimo = 5 dias
resultado = data_manutencao + dias calculados

Alertas

  • listar.php mostra badge visual para vencida, vence hoje ou em dia.
  • alerta_manutencao.php procura registros vencidos e usa ajax/api-texto.php para disparo WhatsApp.
  • Após o envio, o script marca alerta_manutencao_enviado e data_alerta_manutencao.
Ponto de atenção: assim como em proteses, o schema possui usuario em manutencoes_protese. Quem alterar o fluxo deve conferir se o usuário logado está sendo persistido corretamente.

Dependências e integrações

Dependências internas

  • ../conexao.php / ../../../conexao.php em praticamente todos os endpoints.
  • verificar.php para acesso ao painel.
  • verificar-permissoes.php para liberar proteses, analises, simulador, manutencoes.
  • config para chave da IA.

Dependências externas

  • API OpenAI para análise e simulação por IA.
  • WhatsApp via ajax/api-texto.php para alertas de manutenção.
  • Pasta de upload gravável no servidor.
  • cURL habilitado no PHP.

Pontos críticos de manutenção

  1. Não quebrar o contrato de retorno: alguns endpoints devolvem HTML pronto e outros devolvem JSON. O front depende disso.
  2. Cuidado com uploads: as pastas analises e simulacoes precisam existir, ser legíveis e graváveis.
  3. Não remover a ligação com cliente: o módulo inteiro depende da chave do cliente para listagem e vinculação da prótese.
  4. IA depende de configuração: se openai_key estiver ausente, análise e geração de imagem falham.
  5. O cron depende do envio por texto: antes de alterar alerta_manutencao.php, conferir ajax/api-texto.php.
  6. Permissões do painel: se o menu sumir, revisar verificar-permissoes.php e a tabela de acessos/permissões.
  7. Há pontos a endurecer: sanitização de upload, persistência de usuário e consulta interpolada em gerar_ia.php.
Resumo honesto para o próximo dev: o módulo já está funcional, mas a manutenção segura exige atenção especial em SQL, uploads, chave da IA, permissões e cron de alerta.

Checklist para alteração segura

  • Confirmar se a mudança afeta proteses, analise_capilar, simulacoes_protese ou manutencoes_protese.
  • Verificar se existe impacto em upload de imagem.
  • Validar se a resposta do endpoint continua no mesmo formato esperado pelo JS atual.
  • Testar com cliente sem prótese, cliente com prótese e cliente com manutenção vencida.
  • Se mexer em IA, revisar prompt, timeout e leitura de config.openai_key.
  • Se mexer em manutenção, testar também o cron alerta_manutencao.php.
  • Rodar revisão manual no painel antes de publicar.

Sugestão prática: se a alteração for grande, documentar no mesmo padrão desta página o que mudou no banco, nos arquivos e no fluxo. Isso reduz muito o custo da próxima manutenção.