@devix-tecnologia/directus-extension-inframe

# Instruções do GitHub Copilot para Extensão Directus inFrame ## Sobre o Projeto Este é um projeto de extensão do tipo **Module** para o Directus CMS, voltado para visualização de conteúdo em iframes. A extensão permite aos usuários configurar e visualizar sites externos dentro do painel administrativo do Directus. ## Arquitetura e Tecnologias - **Framework**: Vue 3 com Composition API - **Build**: Directus Extensions SDK - **Linguagem**: TypeScript - **Linting**: ESLint com configuração para Vue - **Formatação**: Prettier - **Gerenciador de Pacotes**: pnpm ## Estrutura do Projeto ``` src/ ├── index.ts # Definição principal do módulo Directus ├── List.vue # Componente de listagem principal ├── types.ts # Definições de tipos TypeScript ├── shims.d.ts # Declarações de tipos para Vue ├── components/ │ ├── ItemDetail.vue # Componente de detalhes do item │ └── NavMenu.vue # Componente de menu de navegação └── utils/ └── useFetchItems.ts # Composable para buscar dados ``` ## Convenções de Código ### TypeScript - Use sempre tipagem estrita - Defina interfaces para objetos complexos em `types.ts` - Use tipos do Directus quando disponíveis (`@directus/types`) ### Vue 3 - **SEMPRE** use Composition API com `<script setup>` - Use composables para lógica reutilizável (padrão `use*`) - Componentes devem ter nomes em PascalCase - Props devem ser tipadas com interfaces do TypeScript ### Padrões de Nomenclatura - Arquivos de componentes: PascalCase (ex: `ItemDetail.vue`) - Composables: camelCase iniciando com "use" (ex: `useFetchItems.ts`) - Variáveis e funções: camelCase - Constantes: UPPER_SNAKE_CASE - Interfaces: PascalCase com prefixo "I" opcional ### Estrutura de Componentes Vue ```vue <template>  </template> <script setup lang="ts"> // Imports // Props/Emits definitions // Composables usage // Reactive data // Computed properties // Methods // Lifecycle hooks </script> <style scoped> /* Componente-specific styles */ </style> ``` ## Integração com Directus ### Módulo Definition - O módulo é definido em `src/index.ts` usando `defineModule` - ID do módulo: `'inframe'` - Nome exibido: `'Relatórios'` - Ícone: `'document_scanner'` ### Rotas - Rota principal (`''`): Lista de itens (componente `List.vue`) - Rota dinâmica (`':id'`): Detalhes do item (componente `ItemDetail.vue`) ### Estrutura de Dados Esperada A extensão espera uma coleção chamada `inframe` com os seguintes campos: - `id`: Identificador único - `sort`: Ordem de exibição - `status`: Status do item - `icon`: Ícone do item - `url`: URL do iframe - `thumbnail`: Imagem de miniatura - `translations.languages_code`: Código do idioma - `translations.title`: Título traduzido ## Guidelines para Desenvolvimento ### Ao Criar Novos Componentes 1. Sempre usar TypeScript com tipagem estrita 2. Implementar Composition API com `<script setup>` 3. Adicionar props tipadas quando necessário 4. Usar composables para lógica compartilhada 5. Seguir padrões de nomenclatura estabelecidos ### Ao Trabalhar com APIs - Use composables para encapsular lógica de API - Implemente tratamento de erros adequado - Use tipos TypeScript para respostas da API - Considere loading states e error states ### Estilização - Use CSS scoped nos componentes - Siga os padrões de design do Directus - Use variáveis CSS quando possível - Mantenha consistência visual ### Tratamento de Erros - Sempre implemente tratamento de erros - Use try/catch em operações assíncronas - Forneça feedback adequado ao usuário - Log erros para debugging quando necessário ## Comandos Disponíveis - `pnpm run build`: Build para produção - `pnpm run dev`: Build em modo desenvolvimento com watch - `pnpm run lint`: Verificar código com ESLint - `pnpm run lint:fix`: Corrigir problemas do ESLint automaticamente - `pnpm run format`: Formatar código com Prettier - `pnpm run format:check`: Verificar formatação ## Commits Semânticos Use sempre commits semânticos com mensagens em **português**. Siga o padrão [Conventional Commits](https://www.conventionalcommits.org/): ### Formato ``` <tipo>[escopo opcional]: <descrição> [corpo opcional] [rodapé(s) opcional(is)] ``` ### Tipos de Commit - **feat**: Nova funcionalidade - **fix**: Correção de bug - **docs**: Mudanças na documentação - **style**: Mudanças que não afetam o significado do código (espaços, formatação, etc.) - **refactor**: Mudança de código que não corrige bug nem adiciona funcionalidade - **perf**: Mudança de código que melhora performance - **test**: Adição ou correção de testes - **chore**: Mudanças em ferramentas de build, dependências, etc. - **ci**: Mudanças em arquivos de CI/CD ### Exemplos ```bash feat: adiciona componente de filtro avançado fix: corrige renderização do iframe em dispositivos móveis docs: atualiza README com instruções de instalação style: aplica formatação prettier nos componentes refactor: reorganiza estrutura de pastas dos utils perf: otimiza carregamento de dados da API test: adiciona testes unitários para NavMenu chore: atualiza dependências do projeto ci: configura workflow de deploy automático ``` ### Quebras de Compatibilidade Para mudanças que quebram compatibilidade, adicione `!` após o tipo ou inclua `BREAKING CHANGE:` no rodapé: ```bash feat!: remove suporte ao Directus v9 feat: adiciona nova API BREAKING CHANGE: a nova API não é compatível com versões anteriores ``` ## Considerações de Segurança - A extensão trabalha com iframes, portanto atenção às políticas CSP - Em produção, configure adequadamente `CONTENT_SECURITY_POLICY_DIRECTIVES__FRAME_SRC` - Valide URLs antes de exibir em iframes - Considere sandbox attributes para iframes quando apropriado ## Debugging e Desenvolvimento - Use o modo de desenvolvimento (`pnpm run dev`) para hot reload - Verifique os logs do browser para erros de JavaScript - Use Vue DevTools para debugging de componentes - Teste sempre em diferentes resoluções e navegadores