Guia para IA — Gerar ficha de adapter (T2)

Este documento descreve passo a passo como um agente de IA deve gerar uma ficha técnica de adapter em mm-core-projects-docs, usando o mesmo processo aplicado na ficha de referência TOTVS.

:::info Escopo

• Entrada: adapter_key (ex.: totvs, onelaudos, warelineApi).
• Fonte da verdade: código em mm-pacs-public-api (não inventar comportamento).
• Saída: docs/interfaceReference/integrations/{adapter-key}/index.md + atualização do README.
• Não é escopo: alterar código da Public API, gerar OpenAPI (swaggerDocs.json), rodar sync/regen. :::

---

1. Pré-requisitos

1.1 Repositórios

Os dois repos devem estar acessíveis (pastas irmãs ou paths absolutos):

text
Projetos/
├── mm-core-projects-docs/     ← escrever a ficha aqui
└── mm-pacs-public-api/        ← ler código aqui

1.2 Confirmar classificação

Só gere ficha nesta pasta se a integração for T2 (Mobilemed envia dados ao RIS/HIS via adapter).

Se o adapter também tiver rotas inbound específicas (parceiro chama a Mobilemed), documente-as na ficha como complemento T1, mas não confunda com a referência OpenAPI em docs/openapi/public-api/.

1.3 Ficha de referência

Antes de escrever, leia a ficha concluída:

• TOTVS — Ficha de Integração

Use a mesma estrutura de seções, nível de detalhe e tom.

---

2. Entrada do agente

O prompt mínimo deve conter:

text
adapter_key: {chave exata de adapters/index.js}

Opcional (melhora a ficha):

text
cliente_ou_tenant: {nome}
owner_squad: {squad}
tarefa_bitrix: {URL}

Se adapter_key não existir em adapters/index.js, pare e reporte erro — não crie pasta com chave inventada.

---

3. Passo a passo no mm-pacs-public-api

Execute na ordem abaixo. Use busca (grep, glob, leitura de arquivo) — não assuma comportamento de memória.

Passo 1 — Validar a chave

Arquivo: adapters/index.js

• Confirme que {adapter_key} existe no module.exports.
• Anote o nome da classe (ex.: TotvsAdapter → arquivo adapters/TotvsAdapter.js).
• Respeite camelCase (warelineApi, não wareline-api).

Passo 2 — Ler o adapter

Arquivo: adapters/{Nome}Adapter.js

Extrair:

O quê	Como
Métodos estáticos	apply, notify, getRequests, _validateToken, convertUrlVariable, etc.
Payload outbound	Objeto retornado por apply() ou notify()
Ramificações	if (additional_settings.*), formatos alternativos de body
Dependências	Services, MongoDB, conversão de laudo (ReportConvertedService)
Campos de config usados	integration.config.*, integration.config.additional_settings.*

:::warning Regra Todo campo de payload e config citado na ficha deve existir no código. Se não encontrou, escreva a confirmar (responsável / data) — nunca invente. :::

Passo 3 — Descobrir rotas gateway relacionadas

Comandos sugeridos:

bash
# Nome do adapter / sistema no repositório
rg -i "{adapter_key}|{NomeSistema}" mm-pacs-public-api/routes mm-pacs-public-api/controllers

# Referências diretas ao adapter
rg "adapters\[.*{adapter_key}|config\.adapter === \"{adapter_key}\"" mm-pacs-public-api

Arquivos prioritários:

Arquivo	Por quê
routes/exam.js (e outros em routes/)	Rotas HTTP dedicadas
controllers/exam.controllers.js	Handlers (redirect, notify, recebimento de pedido)
controllers/*.controllers.js	Rotas específicas de outros domínios

Monte a tabela Rotas envolvidas com: direção (inbound/outbound), método, path, função.

Passo 4 — Mapear acao do middleware

Arquivo: middlewares/validate-integration.js

• O middleware traduz req.path → valor de acao em tb_integracao_config.
• Exemplos: /exam/redirect → REDIRECT, /exam/notify → NOTIFY.
• Rotas fora do switch usam filterConfig = "" (integração sem filtro por ação).

Associe cada rota outbound à acao correta na ficha.

Passo 5 — Entender o fluxo de execução outbound

Arquivo: services/exam.service.js

Método do service	Quando	Método do adapter
redirect()	POST /exam/redirect, acao=REDIRECT	adapter.apply()
notify()	POST /exam/notify, acao=NOTIFY	adapter.notify() (ou default)
Outros	Ver grep no adapter	getRequests, etc.

Leia o trecho completo do método usado pelo adapter alvo:

• Como monta reportOptions (reportFormat, base64)
• Como resolve autenticação outbound (TOKEN, BASIC_AUTH, DEFAULT)
• Como envia (tipo_envio: JSON, FORMDATA, XML)
• Uso de additional_settings.alternativeMethod, headers_adicionais

Arquivo complementar: controllers/exam.controllers.js — funções redirect, notify, handlers inbound.

Passo 6 — ENUMs e configuração de banco

Arquivo: models/IntegrationConfig.js

Copie na ficha somente ENUMs reais:

• acao: NOTIFY, REDIRECT, RECEIVE_ATTACHMENT, etc.
• reportFormat: HTML, RTF, PDF, TEXT
• tipo_envio: JSON, FORMDATA, XML
• auth_type: TOKEN, BASIC_AUTH, DEFAULT

Arquivo: models/Integration.js (e variantes IntegrationOne.js) — campos de tb_integracao usados no fluxo (token, client_token, automatic_retry, headers_adicionais, etc.).

Passo 7 — Rotas inbound e persistência auxiliar

Se o adapter depende de dados prévios (ex.: pedido recebido antes do laudo):

1. Busque controllers/services relacionados (ex.: recebePedidoTotvs, criaPedidoTotvs).
2. Leia schemas MongoDB em mongodb/ se aplicável.
3. Documente pré-requisito no diagrama de sequência e na seção Contrato.

Passo 8 — OpenAPI (link, não duplicar)

Arquivo: swaggerDocs.json (no repo public-api ou specs/public-api/swaggerDocs.json no docs)

• Busque paths relacionados ao adapter.
• Se existir MDX gerado em docs/openapi/public-api/, linkar na ficha (ex.: Integra exame).
• Se rota existir no código mas não no swagger, marque com admonition :::caution OpenAPI (como na ficha TOTVS).

---

4. Passo a passo no mm-core-projects-docs

Passo 9 — Criar o arquivo da ficha

Caminho:

text
docs/interfaceReference/integrations/{adapter-key}/index.md

Frontmatter obrigatório:

yaml
---
title: {Nome legível} — Integração outbound
description: Ficha técnica do adapter {adapter-key} (Mobilemed → {sistema}).
sidebar_position: {número}
---

Passo 10 — Preencher seções (template)

Reproduza todas as seções abaixo. Adapte conteúdo ao adapter; mantenha headings.

markdown
# {Nome} — Ficha de Integração

{Parágrafo introdutório — 1–2 frases}

<a class="button button--primary" href="/docs/openapi/public-api/{slug-openapi}">Referência OpenAPI — {MÉTODO} {rota}</a>

:::info Classificação
- T1 / T2 conforme aplicável
:::

## Identificação
(tabela: tipo, adapter_key, classe, cliente, status, owner, contato, última revisão)

## Escopo
### Fluxo completo
(diagrama mermaid sequenceDiagram ou flowchart)

### Rotas envolvidas
(tabela: direção, método, rota, acao, função)

### Ambientes
(homolog/prod + headers gateway)

## Configuração (banco)
(tabela tb_integracao / tb_integracao_config — só campos relevantes ao adapter)

## Autenticação
(inbound gateway + outbound para RIS)

## Contrato
### Inbound (se houver)
(JSON exemplo anonimizado + comportamento)

### Outbound
(JSON exemplo(s) anonimizado(s) — um bloco por variante de payload)

### Erros comuns
(tabela erro → causa, extraída do código throw/messages)

### Idempotência / retry
(automatic_retry, RetryService, comportamento de reenvio)

## Operação
(tabela: arquivos de código, logs, monitoramento)

## Evidências
(homologação — sem PHI)

## Rastreio
(Bitrix, PRs, URL publicada)

Passo 11 — Regras de redação

Regra	Detalhe
Campos desconhecidos	a confirmar (responsável / data) ou não se aplica
Dados sensíveis	Nunca tokens, senhas, CPF/nome real de paciente
Payloads	Exemplos fictícios claramente anonimizados
Links internos	Caminhos Docusaurus /docs/..., não paths de arquivo
Diagramas	Mermaid quando o fluxo tiver ≥ 3 atores ou ramificações
Admonitions	:::info, :::caution para gaps OpenAPI ou pré-requisitos

Passo 12 — Atualizar README

Arquivo: docs/interfaceReference/integrations/README.md

Adicione linha na tabela Fichas existentes:

markdown
| `{adapter_key}` | documentado | [{Nome}](/docs/interfaceReference/integrations/{adapter-key}) |

Passo 13 — (Opcional) Backlog

Se existir docs/documents/Integrations/fluxo-documentacao-integracoes.md, marque o adapter como documentado no backlog (§13).

---

5. Validação antes de concluir

Checklist que o agente deve executar:

• adapter_key existe em adapters/index.js
• Arquivo criado em docs/interfaceReference/integrations/{adapter-key}/index.md
• Todas as seções obrigatórias presentes (identificação → rastreio)
• Rotas citadas existem em routes/ ou swaggerDocs.json
• acao conferida com validate-integration.js
• ENUMs conferidos com IntegrationConfig.js
• Payload(s) outbound batem com retorno de apply() / notify() no código
• Nenhum token, senha ou PHI nos exemplos
• README atualizado com link para a nova ficha
• (Recomendado) pnpm build no mm-core-projects-docs sem erro

---

6. O que o agente NÃO deve fazer

Proibido	Motivo
Inventar valores de ENUM	Quebram operação real (acao, reportFormat, etc.)
Editar swaggerDocs.json nesta tarefa	Escopo separado (T1 / OpenAPI)
Rodar pnpm sync:public-apis	Não necessário para ficha T2
Editar MDX em docs/openapi/public-api/	Arquivos gerados automaticamente
Alterar sidebars.ts	Sidebar de interfaceReference é autogenerated
Commitar credenciais ou dados de paciente	Segurança / LGPD
Criar ficha para default sem solicitação explícita	Adapter genérico, baixo valor documental

---

7. Mapa rápido de arquivos (public-api)

Objetivo	Onde olhar
Chave do adapter	adapters/index.js
Lógica do adapter	adapters/{Nome}Adapter.js
Rotas HTTP	routes/*.js
Handlers	controllers/*.controllers.js
Redirect / notify	services/exam.service.js
Middleware token/acao	middlewares/validate-integration.js
ENUMs de config	models/IntegrationConfig.js
Integração (token, retry)	models/Integration.js
OpenAPI pública	swaggerDocs.json
Persistência auxiliar	mongodb/*.js, services/*.service.js

---

8. Prompt modelo (copiar para o agente)

text
Tarefa: gerar ficha T2 de adapter no Docusaurus.

Siga integralmente:
docs/interfaceReference/integrations/guia-ia-ficha-adapter.md

adapter_key: {CHAVE}

Repositórios:
- mm-pacs-public-api: {caminho}
- mm-core-projects-docs: {caminho}

Entregáveis:
1. docs/interfaceReference/integrations/{CHAVE}/index.md
2. Atualizar docs/interfaceReference/integrations/README.md

Referência de qualidade: docs/interfaceReference/integrations/totvs/index.md

Regras:
- Ler código; não inventar ENUMs, rotas ou payloads.
- Campos desconhecidos → "a confirmar".
- Exemplos anonimizados, sem credenciais.
- Incluir diagrama mermaid se o fluxo for bidirecional ou ramificado.

---

9. Definition of Done (ficha T2)

• Ficha publicável em Interface Reference → Integrações (Adapters)
• README da pasta atualizado
• Conteúdo rastreável ao código-fonte (paths citados na seção Operação)
• Gaps documentados (OpenAPI ausente, campos a confirmar)
• Pronto para vincular em PR de docs + tarefa Bitrix (URL /docs/interfaceReference/integrations/{adapter-key})