Pular para o conteúdo principal

Chat de apontamentos do compliance

Pedido de replicação para o outro sistema (painel do estabelecimento / white label).

No Amplia isto já está em produção de código (18/09/2026): backend/api/compliance/chat.php, tabela compliance_info_chat, decisão em compliance/decidir.php. Este documento descreve o comportamento para o time que for copiar no outro sistema — não é a fonte da verdade do AMPLIA.

Última atualização: 19/09/2026.


Objetivo​

O analista de compliance pede um complemento (fotos, endereço, faturamento, etc.). Esse pedido vira um apontamento. O estabelecimento precisa de um chat assíncrono na ficha/lista do EC para:

  • ler o apontamento
  • responder com o contexto
  • continuar a conversa no mesmo fio, sem e-mail paralelo

Não usar atualização automática (polling). Para ver mensagem nova da outra ponta, o usuário atualiza a página (F5) ou reabre o chat.


O que o Amplia já faz (referência)​

Na lista de estabelecimentos (dashboard/estabelecimentos):

  1. Ícone roxo de mensagem à esquerda do olho, só se houver informação solicitada ativa.
  2. Clique abre o modal Apontamentos do compliance.
  3. Cada solicitação é um fio (screening_case_id).
  4. A primeira bolha é o apontamento do compliance; as seguintes são respostas.
  5. O estabelecimento envia como ESTABELECIMENTO.
  6. No detalhe do EC há um banner roxo com o texto e o botão Abrir chat dos apontamentos.
  7. O analista também abre o mesmo chat na tela de compliance (botão Chat no KYC), como COMPLIANCE.

O outro sistema precisa do mesmo processo inicial no painel do EC: ícone/caixa quando o compliance comentar, e o mesmo GET/POST do chat.


Processo inicial (obrigatório no outro sistema)​

Este é o gatilho. Sem ele, o chat não aparece.

Compliance escreve a justificativa no Amplia
↓
POST /backend/api/compliance/decidir.php
action = SOLICITAR_INFORMACAO
↓
compliance_cases.status = AGUARDANDO_INFORMACAO
compliance_cases.decision_reason = texto do apontamento
compliance_info_chat ← primeira mensagem (COMPLIANCE)
↓
Listagem/detalhe do EC traz informacao_solicitada
↓
Outro sistema: mostra ícone/caixa de chat naquele EC

Quando mostrar o chat

Só se o estabelecimento tiver:

{
"informacao_solicitada": {
"texto": "Favor encaminhar fotos da operação...",
"status": "AGUARDANDO_INFORMACAO",
"solicitado_em": "2026-09-18 12:27:09"
}
}

Regra:

  • informacao_solicitada.texto preenchido e
  • informacao_solicitada.status em AGUARDANDO_INFORMACAO ou EM_ANALISE

Fallback:

  • screening_status em AGUARDANDO_INFORMACAO ou EM_ANALISE e
  • decision_reason não vazio

Quando o caso for APROVADO ou REPROVADO, informacao_solicitada volta null e o ícone some.

O outro sistema não chama decidir.php. Só reage a informacao_solicitada e abre o chat.


Correção do cadastro (obrigatório)​

Quando o EC corrige/altera o cadastro enquanto o caso está em AGUARDANDO_INFORMACAO:

Usuário salva o estabelecimento
↓
POST /backend/api/estabelecimentos/atualizar-local.php
↓
Se houve campo alterado e o caso mais recente é AGUARDANDO_INFORMACAO:
compliance_cases.status = EM_ANALISE (aguardando análise)
estabelecimento.status = analise_compliance
compliance_info_chat ← mensagem SISTEMA listando os campos
↓
Ícone do chat permanece (status EM_ANALISE + texto do apontamento)
Banner roxo de “informação solicitada” some

A mensagem do sistema tem este formato:

Correção realizada pelo usuário.
O cadastro voltou para aguardando análise.

Campos alterados:
- Razão social
- Endereços

O outro sistema não inventa essa mensagem. Ela já vem no GET do chat (autor_papel: "SISTEMA"). Só precisa renderizar a bolha de sistema e manter o ícone também quando informacao_solicitada.status === "EM_ANALISE".

Não enviar autor_papel: "SISTEMA" no POST — isso é só do backend do Amplia.


Onde as mensagens são salvas​

Tudo fica no banco do Amplia, na tabela compliance_info_chat. Não há outro destino (arquivo, e-mail, outro banco).

Cada Enviar faz INSERT em:

ColunaConteúdo
idPK
estabelecimento_idEC da conversa
screening_case_idFio (= compliance_cases.id)
user_idQuem digitou
autor_papelCOMPLIANCE, ESTABELECIMENTO ou SISTEMA
mensagemTexto
created_atData/hora de Brasília

O apontamento original também fica em compliance_cases.decision_reason. As respostas do EC existem somente em compliance_info_chat.

DDL:

CREATE TABLE `compliance_info_chat` (
`id` INT NOT NULL AUTO_INCREMENT,
`estabelecimento_id` INT NOT NULL,
`screening_case_id` INT NULL,
`user_id` INT NULL,
`autor_papel` VARCHAR(20) NOT NULL DEFAULT 'ESTABELECIMENTO',
`mensagem` TEXT NOT NULL,
`created_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
KEY `idx_cic_ec` (`estabelecimento_id`, `created_at`),
KEY `idx_cic_case` (`screening_case_id`, `created_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4

Horário (Brasília)​

Gravar e exibir em America/Sao_Paulo (-03:00). Não usar UTC na tela.

No Amplia:

  • PHP: date_default_timezone_set('America/Sao_Paulo')
  • MySQL na conexão: SET time_zone = 'America/Sao_Paulo' (fallback SET time_zone = '-03:00')
  • Insert do chat: datetime gerado em America/Sao_Paulo, não NOW() solto no fuso do servidor
  • Front: toLocaleString('pt-BR', { timeZone: 'America/Sao_Paulo' })

UTC 15:27 equivale a 12:27 em Brasília. O outro sistema deve mostrar 12:27, não 15:27.


Papéis​

autor_papelQuemUso
COMPLIANCEAnalistaAbre o apontamento e pode complementar
ESTABELECIMENTOPainel do EC (outro sistema)Responde o apontamento
SISTEMAAmpliaCorreção do cadastro; lista os campos alterados

No outro sistema, enviar sempre "autor_papel": "ESTABELECIMENTO". O Amplia só grava COMPLIANCE se o usuário tiver permissão de compliance. SISTEMA não é enviado pelo cliente.


APIs (mesmo backend do Amplia)​

Base: {APP_URL}/backend/api/
Auth: sessão cookie do usuário logado.
Envelope: { "status": "success", "message": "...", "data": { ... } }

1. Saber se deve mostrar o chat​

Campos já vêm no EC:

  • GET /backend/api/estabelecimentos/listar-locais.php
  • GET /backend/api/estabelecimentos/detalhes.php?estabelecimento_id={id}
CampoUso
informacao_solicitadaobjeto ou null — gatilho do ícone
informacao_solicitada.textoTexto do apontamento
informacao_solicitada.statusAGUARDANDO_INFORMACAO ou EM_ANALISE
informacao_solicitada.solicitado_emQuando o compliance pediu
screening_case_idFio ativo (opcional no POST)
screening_statusStatus do caso mais recente
decision_reasonMesmo texto do apontamento

2. Abrir o chat​

GET /backend/api/compliance/chat.php?estabelecimento_id={id}&_={timestamp}

Headers de resposta no Amplia: Cache-Control: no-store. O cliente também deve pedir sem cache (cache: 'no-store').

Resposta (data):

{
"estabelecimento_id": 123,
"estabelecimento_nome": "PSA PREMIUM",
"thread_ativa_id": 45,
"pode_responder_como_compliance": false,
"threads": [
{
"screening_case_id": 45,
"status": "AGUARDANDO_INFORMACAO",
"ativo": true,
"solicitado_em": "2026-09-18 12:27:09",
"apontamento": "Favor encaminhar fotos da operação...",
"mensagens": [
{
"id": 0,
"autor_papel": "COMPLIANCE",
"autor_nome": "Compliance",
"mensagem": "Favor encaminhar fotos da operação...",
"created_at": "2026-09-18 12:27:09",
"is_apontamento": true
},
{
"id": 88,
"autor_papel": "ESTABELECIMENTO",
"autor_nome": "Fabio Cardoso",
"mensagem": "Ajustes realizados no sistema...",
"created_at": "2026-09-18 12:27:09",
"is_apontamento": false
}
]
}
]
}

Um item em threads = uma solicitação. ativo: true é o fio corrente. is_apontamento: true é o recado original.

3. Enviar resposta​

POST /backend/api/compliance/chat.php
Content-Type: application/json
{
"estabelecimento_id": 123,
"screening_case_id": 45,
"autor_papel": "ESTABELECIMENTO",
"mensagem": "Ajustes realizados no sistema, era apenas casa decimal errada"
}

Se screening_case_id vier vazio, o backend usa o caso mais recente daquele EC. A resposta do POST é o mesmo JSON do GET (lista atualizada). Não precisa recarregar a página para ver a própria mensagem; para ver a da outra ponta, F5.

4. Compliance solicitar informação (já no Amplia)​

POST /backend/api/compliance/decidir.php
{
"compliance_id": 10,
"action": "SOLICITAR_INFORMACAO",
"reason": "Favor encaminhar fotos da operação da empresa..."
}

Ações: APROVAR, REPROVAR, SOLICITAR_INFORMACAO. reason obrigatório.


UX para replicar​

  1. Ícone de comentário na lista/card do EC, só com informacao_solicitada ativa.
  2. Clique abre modal/painel Apontamentos do compliance.
  3. Cabeçalho do fio: data + selo “Aguardando informação” se ativo.
  4. Bolha do apontamento à esquerda (compliance), com rótulo Apontamento.
  5. Bolha Sistema (centro) quando o EC corrigir o cadastro, listando os campos.
  6. Respostas do EC à direita.
  7. Textarea + Enviar. Enter envia; Shift+Enter quebra linha.
  8. Vários fios: accordion; o ativo é thread_ativa_id.
  9. Scroll na área das mensagens (histórico longo não pode cortar texto).
  10. Espaço visível entre a última mensagem e o campo de envio.
  11. Sem polling e sem overlay de loading a cada poucos segundos (isso faz a tela piscar).
  12. F5 / reabrir o chat busca de novo no servidor (GET sem cache). Não exigir logout/login.

Referência no Amplia: components/popup_chat_compliance.php e assets/js/pages/compliance/compliance-chat.js.


Checklist do outro sistema​

  • Ler informacao_solicitada na listagem/detalhe do EC
  • Mostrar ícone/caixa com AGUARDANDO_INFORMACAO ou EM_ANALISE + texto
  • Ao clicar, GET /backend/api/compliance/chat.php?estabelecimento_id=
  • Um fio por screening_case_id, apontamento em evidência
  • Renderizar bolha SISTEMA (correção do cadastro + campos alterados)
  • POST com autor_papel: "ESTABELECIMENTO"
  • Gravação efetiva em compliance_info_chat (mesmo backend)
  • Horário de Brasília (America/Sao_Paulo) na gravação e na tela
  • GET sem cache; F5 mostra mensagens novas
  • Scroll nas mensagens e folga acima do composer
  • Sem atualização automática que pisque a tela

Arquivos no Amplia​

ArquivoPapel
backend/api/compliance/decidir.phpCompliance solicita informação
backend/src/services/compliance/compliance_screening_service.phpStatus + informacao_solicitada
backend/api/compliance/chat.phpGET/POST do chat
backend/src/services/compliance/compliance_chat_service.phpListar, enviar, gravar apontamento e correção do cadastro
backend/api/estabelecimentos/atualizar-local.phpCorreção do EC → EM_ANALISE + mensagem SISTEMA
backend/config/database.phpFuso America/Sao_Paulo na conexão
database/migrations/20260918_compliance_info_chat.phpTabela compliance_info_chat
components/popup_chat_compliance.phpModal
assets/js/pages/compliance/compliance-chat.jsAbrir, listar, enviar
frontend/pages/estabelecimentos/lista.phpÍcone na lista do EC
frontend/pages/compliance/index.phpChat do analista