id: "REQ-283" title: "Exposição de CRUD via API RESTful para os módulos básicos do Core" status: "ready-for-intake" date: "2026-10-19" author: "architect" target_repo: "conn2flow" batch: "BATCH-292" topology: "triade" autonomy: "autonomo_monitorado"

REQ-283: Exposição de CRUD via API RESTful para os módulos básicos do Core

1. Motivação e Contexto

O Conn2Flow possui uma camada de API (/_api/) que hoje atende prioritariamente à infraestrutura, rotinas mobile de autenticação (api/auth/*), deploy de projetos (api/project/*), atualizações do sistema (api/system/*) e sincronização distribuída (api/modulo-distribuido/*).

No entanto, nenhum dos 35 módulos administrativos básicos do Core possui operações de CRUD (Listar, Ler, Criar, Atualizar, Excluir, Alterar Status e Clonar) expostas via API para clientes externos, ferramentas de linha de comando ou agentes autônomos de IA.

Esta requisição formaliza o plano de trabalho e o desenho arquitetural para habilitar uma API RESTful padronizada, segura (RBAC) e extensível para todos os módulos básicos do Core.

2. Levantamento e Diagnóstico dos Módulos

2.1. Módulos que já possuem API (ou endpoints dedicados):

1. admin-atualizacoes: possui endpoints em api/system/* (update, recover, files, rollback, conflicts, resolve), mas voltados ao processo de atualização de versão do gestor, e não ao CRUD genérico de registros.

2. perfil-usuario: possui endpoints em api/auth/* (login, logout, me, modules) e rotina de PATs (Personal Access Tokens), mas sem CRUD exposto para gestão completa dos dados do perfil.

3. admin-environment: possui regras de permissão para a API (acesso-administrador-a-api) e validação de tokens, mas sem operações CRUD.

4. dashboard: atua como agregador e organizador visual de widgets, consumido internamente pelo painel.

2.2. Módulos Básicos que NÃO possuem API de CRUD (Total: 31 módulos):

• Conteúdo e Recursos Web (10 módulos):

  • admin-paginas: páginas do site, HTML, CSS, visibilidade, links privados.

  • admin-layouts: layouts base do site e do sistema.

  • admin-componentes: componentes modulares reaproveitáveis.

  • admin-templates: templates de blocos e páginas.

  • variables: variáveis globais e de layout do sistema.

  • admin-categorias: taxonomia e hierarquia de categorias.

  • admin-arquivos: upload e gerenciamento de arquivos de mídia/assets.

  • menus: estrutura e nós de navegação.

  • galleries: galerias de imagens e itens visuais.

  • pages-index: índices e agregações de páginas.

• Publisher / Blog e Notícias (4 módulos):

  • publisher: publicações, artigos e notícias.

  • publisher-pages: páginas de publicação.

  • publisher-index: índices de busca e listagem de posts.

  • publisher-highlights: posts e conteúdos em destaque.

• Formulários e Leads (4 módulos):

  • forms: construtor de formulários, campos e regras de validação.

  • forms-submissions: submissões recebidas.

  • forms-search: índices de busca em formulários.

  • contatos: mensagens recebidas pelo canal de contato.

• Identidade, Acesso e Permissões (2 módulos):

  • usuarios: cadastro de administradores do sistema.

  • usuarios-perfis: grupos de permissão e perfis de acesso (RBAC).

• Recursos de IA (3 módulos):

  • admin-ia: servidores e provedores de IA cadastrados.

  • admin-modos-ia: modos operacionais de IA.

  • admin-prompts-ia: biblioteca de prompts de IA.

• Administração Estrutural e Sistema (8 módulos):

  • admin-cron: tarefas agendadas do sistema.

  • modulos: cadastro de módulos.

  • modulos-grupos: agrupamentos de menu.

  • modulos-operacoes: operações e permissões granulares.

  • cookie-consent: configurações de consentimento LGPD.

  • dashboard-pages: páginas de lousa/dashboard.

  • admin-plugins: catálogo de plugins do sistema.

  • interface: configurações de temas e interface visual.

3. Desenho Arquitetural Recomendado: Motor Canônico api-crud

Em vez de criar 31 controladores e rotinas redundantes, a solução canônica recomendada consiste em criar um Motor Canônico de CRUD (api-crud.php) integrado ao roteador de api.php.

3.1. Reutilização de Metadados Existentes

Cada módulo em gestor/modulos/{id}/{id}.json já possui a seção "tabela":

• tabela.nome: nome da tabela no banco SQL.

• tabela.id: coluna identificadora alfanumérica (slug/id).

• tabela.id_numerico: chave primária inteira autoincremento.

• tabela.status: coluna de status (A, I, D).

• tabela.versao: coluna de controle de concorrência e versão.

• tabela.data_criacao / tabela.data_modificacao: auditoria temporal.

3.2. Mapeamento RESTful Padronizado

Para qualquer módulo acessado via /_api/{modulo-id}/:

• GET /_api/{modulo-id}/: listagem paginada (parâmetros: page, per_page, sort, order, search, status).

• GET /_api/{modulo-id}/{id}: leitura detalhada de um registro específico (por ID alfanumérico ou numérico).

• POST /_api/{modulo-id}/: criação de novo registro, com validação de campos obrigatórios e gravação de metadados.

• PUT /_api/{modulo-id}/{id} (ou PATCH): atualização parcial ou total de registro existente, com incremento de versão.

• DELETE /_api/{modulo-id}/{id}: exclusão lógica (status = 'D') ou definitiva de acordo com a configuração do módulo.

• POST /_api/{modulo-id}/{id}/status: alternância rápida de status (A ativo / I inativo).

• POST /_api/{modulo-id}/{id}/clone: clonagem de registro existente.

3.3. Governança de Segurança e RBAC

• Autenticação: Suporte nativo a tokens PAT (Bearer c2f_pat_...) e tokens OAuth2.

• Autorização (RBAC): O motor valida contra usuarios_perfis_modulos se o perfil do usuário possui acesso ao módulo, e contra usuarios_perfis_modulos_operacoes se a ação requer permissão especial.

• Auditoria: Registro automático de usuário criador/modificador e data nos padrões do Core.

3.4. Ciclo de Vida e Hooks Específicos

Módulos que requerem efeitos colaterais (ex: admin-paginas invalidando caches e recompilando Tailwind; admin-arquivos processando upload de mídia multipart) interceptam o ciclo através de hooks canônicos declarados em {modulo}.json:

• before_create / after_create

• before_update / after_update

• before_delete / after_delete

4. Plano de Trabalho (Slices de Implementação)

• Fase 1 (Core Engine & RBAC - BATCH-292):

  • Criação da biblioteca gestor/bibliotecas/api-crud.php.

  • Integração do fallback inteligente em gestor/controladores/api/api.php para rotear chamadas de módulos para o motor de CRUD.

  • Implementação do validador de RBAC por perfil (usuarios_perfis_modulos).

  • Suíte de testes unitários PHPUnit cobrindo os verbos GET, POST, PUT, DELETE, status e clone em módulo padrão (ex: admin-categorias).

• Fase 2 (Módulos de Conteúdo Web - BATCH-293):

  • Habilitação e validação de CRUD via API para admin-paginas, admin-layouts, admin-componentes, admin-templates, variables, admin-categorias, admin-arquivos, menus, galleries e pages-index.

  • Implementação dos hooks de pós-salvamento necessários (recompilação de cache e variáveis).

• Fase 3 (Módulos de Publisher, Formulários e Contatos - BATCH-294):

  • Habilitação e testes para publisher, publisher-pages, publisher-index, publisher-highlights.

  • Habilitação para forms, forms-submissions, forms-search e contatos.

• Fase 4 (Módulos de Usuários, Permissões, IA e Sistema - BATCH-295):

  • Habilitação para usuarios, usuarios-perfis, admin-ia, admin-modos-ia, admin-prompts-ia.

  • Habilitação para admin-cron, dashboard-pages, cookie-consent e modulos.

• Fase 5 (Documentação OpenAPI e Testes E2E - BATCH-296):

  • Especificação OpenAPI (Swagger JSON/YAML) para os endpoints gerados.

  • Testes automatizados ponta-a-ponta (E2E) com requisições HTTP reais usando tokens PAT.

5. Critérios de Aceite

• [ ] O motor canônico api-crud.php responde requisições RESTful para módulos com metadado "tabela" válido.

• [ ] Autenticação com Personal Access Token (c2f_pat_...) e validação RBAC ativas em todas as rotas de módulo.

• [ ] Retorno padronizado em JSON com envelope status, message, data e timestamp.

• [ ] Códigos HTTP adequados: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict.

• [ ] Testes automatizados cobrindo todos os fluxos de CRUD.