Guia 03 - IA Frontend - Angular CRUD Completo

Guia 03 - IA Frontend - Angular CRUD Completo

Objetivo

Este guia orienta uma LLM a gerar o frontend Angular canonico para um recurso CRUD que ja publica corretamente o contrato metadata-driven do praxis-metadata-starter.

O objetivo nao e montar “qualquer tela Angular que compile”. O objetivo e gerar um host alinhado ao runtime oficial da plataforma:

Ordem de leitura para a LLM

Este guia so deve ser usado depois que o backend ja publicar corretamente o contrato metadata-driven.

Use esta ordem:

  1. GUIA-01-AI-BACKEND-APLICACAO-NOVA.md
  2. GUIA-02-AI-BACKEND-CRUD-METADATA.md
  3. este guia
  4. CHECKLIST-VALIDACAO-IA.md

Nenhum passo deste guia depende de consultar app externo.

Hierarquia canonica

  1. praxis-metadata-starter
  2. praxis-ui-angular

O starter nao redefine semantica de frontend. Ele orienta o consumo correto do runtime oficial Angular.

Quando usar este guia

Use este guia quando a LLM precisar gerar a parte frontend de um recurso CRUD ja exposto pelo backend Praxis.

Este guia cobre:

Quando nao usar este guia

Este guia nao e o lugar correto para:

Se o pedido for apenas uma lista remota simples, praxis-table pode bastar. Se o pedido for um CRUD completo, prefira praxis-crud.

O que a LLM deve receber como entrada

No minimo:

  1. nome do recurso frontend
  2. resourcePath canonico do backend
  3. idField
  4. estrategia de abertura: modal, route ou drawer
  5. rota Angular desejada
  6. endpointKey quando houver mais de uma API configurada

Exemplo:

Gere o frontend Angular de CRUD completo para o recurso abaixo.

Entrada:
- Recurso: Funcionarios
- resourcePath: human-resources/funcionarios
- idField: id
- endpointKey: HumanResources
- rota da lista: /funcionarios
- rota de visualizacao: /funcionarios/view/:id
- openMode padrao: modal

Dependencias frontend minimas

Para um CRUD completo:

npm i @angular/animations @angular/cdk @angular/material
npm i @praxisui/core @praxisui/table @praxisui/dynamic-form @praxisui/crud

Para um app Angular novo, a prova operacional desta rodada mostrou que o baseline real tambem precisa incluir:

npm i @praxisui/ai @google/generative-ai

Motivo:

Nao assumir que as quatro libs principais bastam sozinhas em um app Angular novo.

Referencia operacional validada nesta rodada:

Contratos canonicos de runtime

1. resourcePath

No runtime Angular atual, o resourcePath segue o formato:

human-resources/funcionarios

Se API_URL ja aponta para /api, mantenha o resourcePath relativo ao dominio do recurso e nao repita o prefixo api/.

2. API_URL

O app host precisa fornecer o token API_URL.

Exemplo minimo:

import { ApplicationConfig } from '@angular/core';
import { API_URL, type ApiUrlConfig } from '@praxisui/core';

export const appConfig: ApplicationConfig = {
  providers: [
    {
      provide: API_URL,
      useFactory: (): ApiUrlConfig => {
        const origin =
          typeof window !== 'undefined' && window.location
            ? window.location.origin
            : 'http://127.0.0.1:4200';
        return {
          default: { baseUrl: origin, path: '/api', version: '' },
        } as ApiUrlConfig;
      },
    },
  ],
};

Se houver endpoint dedicado por dominio:

{
  provide: API_URL,
  useFactory: (): ApiUrlConfig => {
    const origin =
      typeof window !== 'undefined' && window.location
        ? window.location.origin
        : 'http://127.0.0.1:4200';
    return {
      default: { baseUrl: origin, path: '/api', version: '' },
      humanResources: { baseUrl: origin, path: '/api', version: '' },
    } as ApiUrlConfig;
  },
}

Para app Angular novo fora do workspace oficial, prefira baseUrl = window.location.origin.

Para app novo, o bootstrap tambem deve prover:

3. providePraxisGlobalConfigBootstrap()

Nao faz parte do baseline minimo de um host CRUD novo.

So use esse bootstrap quando o host realmente integrar praxis-config-starter e precisar de config remota em /api/praxis/config/**.

4. GenericCrudService

Regras canonicas:

Fluxo de schema

O frontend oficial consome:

Tambem usa:

Padrao canonico para CRUD completo

lista + acoes:
  praxis-crud
    -> praxis-table
    -> crudContext estavel
    -> create/view/edit/delete

formulario:
  praxis-dynamic-form
    -> schema-driven
    -> usa GenericCrudService quando depende de resourcePath/resourceId

Arquivos minimos do frontend

Para um app Angular novo, gere no minimo:

Prompt recomendado para IA

Voce esta gerando o frontend Angular canonico para um recurso CRUD Praxis.

Use apenas o contrato metadata-driven ja publicado pelo backend.
Considere praxis-ui-angular como runtime canonico.

Gere:
- host com praxis-crud para a lista principal
- praxis-dynamic-form para view/edit quando houver rota
- API_URL coerente
- resource.path e idField corretos
- create/view/edit/delete conectados ao fluxo canonico

Nao invente wrappers locais nem duplicacoes de contrato.

Entrada:
- resourcePath: {resource-path}
- idField: {id-field}
- endpointKey: {endpoint-key}
- rota da lista: {list-route}
- rota de view: {view-route}
- openMode padrao: {open-mode}

Checklist minimo

Antes de concluir:

Validacao minima recomendada

Quando o workspace Angular tiver node_modules de Windows, prefira executar via cmd.exe /c.

Quando a prova usar um app Angular novo fora do workspace oficial, a validacao minima deve incluir:

npm run build
npm start -- --host 127.0.0.1 --port 4305

Evidencias esperadas:

Se houver trilha browser-level complementar, trate-a como validacao separada do baseline material acima.

Referencias publicas