Functions Senior X

Gerencie suas funções e regras da plataforma Senior X de forma eficiente e segura, diretamente do seu VS Code

Esta extensão foi criada para desenvolvedores que trabalham com a Senior X, oferecendo uma interface integrada para visualizar, gerenciar e interagir com suas custom functions e pontos de regra sem precisar sair do editor.

✨ Principais Funcionalidades

• 🔐 Gerenciamento Seguro de Múltiplas Contas e Ambientes: Configure e alterne entre diferentes tenants (desenvolvimento, homologação, produção) com segurança. Suas credenciais são armazenadas de forma segura usando a API SecretStorage do VS Code.
• 👁️ Visualização Centralizada: Explore suas Funcionalidades (API) e Pontos de Regra em uma árvore de visualização dedicada na Activity Bar, com informações claras sobre status, runtime e métricas de execução.
• 🚀 Gestão de Runtime AWS Lambda: Identifique facilmente funções com runtimes desatualizados e atualize-as para a versão mais recente com apenas um clique no menu de contexto.
• ⚡ Ações Rápidas: Ative ou desative endpoints e pontos de regra diretamente pela interface, agilizando o processo de desenvolvimento e depuração.
• 📥 Download e Upload de Código: Baixe o código de funções existentes para desenvolvimento local e faça o upload de novas versões com validações integradas dos arquivos package.json e template.yaml. O upload é realizado de forma segura e eficiente através do Blob Service com URLs pré-assinadas.
• 🌐 Suporte a Múltiplos Idiomas Completo: A interface está disponível em Português (Brasil), Inglês e Espanhol, com um sistema de internacionalização robusto, centralizado e com type safety para evitar erros.
• 🔄 Atualização Inteligente: Mantenha a lista de funções sempre sincronizada com um botão de refresh e recarregamento automático ao trocar de credenciais ou alterar configurações.
• ✅ Validações Type-Safe com Zod: O projeto utiliza Zod para validações, garantindo a consistência dos dados e eliminando a duplicação entre tipos TypeScript e schemas de validação para uma maior robustez.

🚀 Guia de Início Rápido

1. Instale a extensão a partir do VS Code Marketplace.
2. Abra o novo ícone da Senior X na sua Activity Bar.
3. Na nova view, clique em "Configure suas credenciais".
4. No menu que aparecer, selecione "Adicionar Nova Credencial".
5. Siga os passos para configurar o ambiente, tipo de autenticação (Chave de API ou Usuário/Senha), e suas informações de acesso.
6. Após salvar, a extensão fará o login automaticamente. Suas funções e regras aparecerão na view!

🔭 Guia da Interface

A extensão organiza suas funções em duas categorias principais dentro da view "Functions Senior X":

FUNÇÕES
├── 📡 Funcionalidades (API) (3)
│   ├── 🟢 minha-api-ativa 🌐 (nodejs18.x) [8/10]
│   ├── ⚫️ minha-api-inativa 🔄 (nodejs18.x) [0/0]
│   └── 🟡 lambda-desatualizada ➡️ (nodejs16.x) ⚠️ [1/1]
│
└── 🎯 Pontos de Regra (2)
    ├── 🟢 ValidarCliente 🎯 PONTO DE REGRA
    └── ⚫️ ProcessarPedido 🎯 PONTO DE REGRA

Legenda dos Ícones e Indicadores

Status do Endpoint:

• 🟢 Ativo: O endpoint está habilitado e pronto para receber requisições
• ⚫️ Inativo: O endpoint está desabilitado
• 🟡 Desatualizado: O runtime da função AWS Lambda está obsoleto

Tipo de Método:

• 🌐 WEBHOOK: Método de webhook para integrações externas
• 🔄 AROUND: Método que envolve a execução original
• ➡️ AFTER: Método executado após a operação original
• ⬅️ BEFORE: Método executado antes da operação original
• 🎯 PONTO DE REGRA: Ponto de regra configurado

Outros Indicadores:

• [8/10]: Métricas de execução (sucessos/total)
• ⚠️: Indica runtime desatualizado
• (nodejs18.x): Versão do runtime da função

⚙️ Comandos e Ações

Além da interface visual, você pode usar a paleta de comandos (Ctrl+Shift+P):

Ações de Contexto (clique com o botão direito em um item):

• Ativar/Desativar Extensão: Habilita ou desabilita um endpoint ou ponto de regra
• Atualizar Runtime da Lambda: Atualiza o runtime de uma função para a versão mais recente disponível na plataforma
• Baixar Código da Função: Realiza o download do código fonte da função para o seu ambiente local
• Fazer Upload da Função: Envia uma nova versão do código da sua máquina para a plataforma

🔧 Configurações da Extensão

Você pode customizar o comportamento da extensão nas configurações do VS Code (settings.json):

• functions-senior-x.backend.url: URL base da plataforma Senior X (utilizada como fallback caso nenhum ambiente customizado esteja ativo)
• functions-senior-x.autoLogin.enabled: Habilita ou desabilita o login automático na inicialização do VS Code

✅ Validações Type-Safe com Zod

Este projeto adota Zod para validações tipadas e mensagens consistentes via i18n em prompts de entrada.

Principais Características:

• z.infer Pattern: Eliminação completa de duplicação entre interfaces TypeScript e schemas Zod
• Validação em Runtime: Schemas robustos para todas as operações da API
• Mensagens Centralizadas: Sistema i18n integrado para mensagens de erro consistentes
• Type Safety: Tipos TypeScript gerados automaticamente dos schemas Zod

🛠️ Padrões de Desenvolvimento

Importações com Alias @

Todas as importações de módulos internos utilizam o alias @/ configurado no tsconfig.json:

// ✅ Padrão correto
import { ConfigManager } from '@/config';
import { AuthService } from '@/api/authService';
import { i18n } from '@/i18n/i18nService';
import { getLogger } from '@/logger/LoggerSingleton';

// ❌ Evite caminhos relativos
import { ConfigManager } from '../config';
import { AuthService } from '../../api/authService';

Este padrão melhora a legibilidade, manutenibilidade e facilita refatorações na estrutura de diretórios.

Arquitetura:

• Schemas Principais: src/models/*.dto.ts - Schemas Zod como fonte única da verdade
• Adaptadores: src/utils/zodSchemas.ts - Funções helper para integração com VS Code
• Validação de API: Todos os serviços usam schema.parse() para validação robusta

Exemplo de Uso:

// Schema como fonte única da verdade
export const LoginResponseSchema = z.object({
  jsonToken: z.string(),
  mfaInfo: z.any().optional(),
});

// Tipo gerado automaticamente
export type LoginResponse = z.infer<typeof LoginResponseSchema>;

// Validação em runtime
const response = LoginResponseSchema.parse(apiResponse);

Siga o guia i18n em docs/2_FEATURES/3_I18N_SYSTEM.md para manter mensagens centralizadas.

🛠️ Desenvolvimento e Contribuição

Configuração do Ambiente

1. Clone o repositório
2. Instale as dependências: npm install
3. Execute os testes: npm run test
4. Compile o projeto: npm run build
5. Execute o linting: npm run lint

Scripts Disponíveis

• npm run build - Build da extensão e webview para produção
• npm run build:full - Build completo + testes
• npm run compile-tests - Compila apenas os testes
• npm run dev - Modo watch da extensão
• npm run dev:webview - Modo watch da webview
• npm run watch-tests - Modo watch para testes
• npm run lint - Executa ESLint e validação i18n
• npm run generate-types - Gera tipos de i18n
• npm run generate-nls - Gera arquivos de tradução

Estrutura do Projeto

src/
├── api/           # Serviços de comunicação com a plataforma
├── commands/      # Comandos da extensão
├── config.ts      # Gerenciamento de configuração
├── constants.ts   # Constantes da aplicação
├── extension.ts   # Ponto de entrada da extensão
├── i18n/          # Sistema de internacionalização
├── models/        # DTOs e schemas Zod
├── providers/     # Tree Data Provider
├── test/          # Testes unitários
└── utils/         # Utilitários diversos

Contribuição

1. Crie uma branch a partir de develop
2. Implemente suas mudanças seguindo os padrões estabelecidos
3. Adicione testes para novas funcionalidades
4. Execute npm run lint para validar qualidade do código
5. Faça commit seguindo conventional commits
6. Abra um Pull Request

Padrões de Código

• TypeScript: Tipagem estrita obrigatória
• Zod: Use z.infer para eliminar duplicação de tipos
• i18n: Todas as strings visíveis devem usar i18n.t()
• Testes: Cobertura mínima de 80% para código novo
• Linting: ESLint deve passar sem warnings

Desenvolvido com ❤️ para a comunidade Senior X