Backstage Plugin ARB Backend

Plugin de backend dinâmico para o Backstage que integra com Azure DevOps Git para gerenciar projetos ARB (Arquitetura Review Board).

Funcionalidades

• API REST completa para gerenciar projetos ARB
• Integração com Azure DevOps Git como persistência
• Auditoria automática de todas as alterações
• Armazenamento em JSON no repositório Git

Endpoints da API

Health Check

GET /api/arb/v1/health

Listar todos os projetos

GET /api/arb/v1/arb

Buscar projeto específico

GET /api/arb/v1/arb/:id

Criar novo projeto

POST /api/arb/v1/arb
Content-Type: application/json

{
  "nome": "Nome do Projeto",
  "responsavel": "Nome do Responsável",
  "status": "Em Análise",
  "motivo": "",
  "observacoes": "",
  "dataApresentacao": "2025-12-02",
  "linkDocumentacao": "https://...",
  "linkGravacao": "https://...",
  "numeroChamado": "",
  "aprovacoes": {
    "arquitetura": false,
    "infra": false,
    "seguranca": false,
    "finops": false,
    "identidades": false,
    "monitoria": false
  }
}

Atualizar projeto

PUT /api/arb/v1/arb/:id
Content-Type: application/json

{
  "status": "Aprovado",
  "aprovacoes": {
    "arquitetura": true
  }
}

Deletar projeto

DELETE /api/arb/v1/arb/:id

Configuração

1. Instalar o plugin

Adicione o plugin ao seu projeto Backstage:

# No diretório do backend do Backstage
cd packages/backend
yarn add @internal/backstage-plugin-arb-backend

2. Configurar app-config.yaml

Adicione a configuração do Azure DevOps:

arb:
  azureDevOps:
    organization: 'myorganization'
    project: 'Plataformas'
    repository: 'arb-projects'
    # Token de acesso pessoal (recomendado usar variável de ambiente)
    # token: ${AZURE_DEVOPS_PAT}

3. Configurar Personal Access Token (PAT)

Crie um PAT no Azure DevOps com permissões de Code (Read & Write):

1. Acesse: https://dev.azure.com/myorganization/_usersSettings/tokens
2. Clique em "New Token"
3. Dê um nome (ex: "Backstage ARB Plugin")
4. Selecione escopo: Code (Read & Write)
5. Copie o token gerado

Configure o token como variável de ambiente:

# Linux/Mac
export AZURE_DEVOPS_PAT="seu-token-aqui"

# Windows PowerShell
$env:AZURE_DEVOPS_PAT="seu-token-aqui"

# Windows CMD
set AZURE_DEVOPS_PAT=seu-token-aqui

4. Registrar o plugin no backend

No arquivo packages/backend/src/index.ts, adicione:

import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

// ... outros plugins ...

// Plugin ARB
backend.add(import('@internal/backstage-plugin-arb-backend'));

backend.start();

5. Estrutura do Repositório Git

O plugin espera que o repositório Azure DevOps tenha a seguinte estrutura:

arb-projects/
├── 1.json
├── 2.json
├── 3.json
└── ...

Cada arquivo JSON representa um projeto ARB com ID sequencial.

Modelo de Dados

Projeto ARB

{
  nome: string;
  responsavel: string;
  status: string;
  motivo: string;
  observacoes: string;
  dataApresentacao: string;
  linkDocumentacao: string;
  linkGravacao: string;
  numeroChamado: string;
  aprovacoes: {
    arquitetura: boolean;
    infra: boolean;
    seguranca: boolean;
    finops: boolean;
    identidades: boolean;
    monitoria: boolean;
  };
  auditoria: Array<{
    dataHora: string;
    usuario: string;
    tipoAcao: 'CRIACAO' | 'ALTERACAO' | 'EXCLUSAO';
    detalhes: string;
    camposAlterados?: Record<string, {
      anterior?: any;
      novo?: any;
    }>;
  }>;
  dataCriacao: string;
  ultimaModificacao: string;
  tableData?: {
    id: string;
    uuid?: string;
  };
}

Desenvolvimento

Estrutura do Projeto

plugin-backend-arb-backstage/
├── src/
│   ├── service/
│   │   ├── AzureDevOpsService.ts  # Serviço de integração com Azure DevOps
│   │   └── router.ts              # Rotas Express da API
│   ├── types.ts                   # Tipos TypeScript
│   ├── plugin.ts                  # Definição do plugin
│   └── index.ts                   # Exportações públicas
├── package.json
├── tsconfig.json
└── README.md

Build

yarn build

Testes

yarn test

Lint

yarn lint

Auditoria

Todas as operações (criação, atualização, exclusão) são automaticamente auditadas:

• Usuário: Identificado do contexto da requisição ou 'guest'
• Data/Hora: Timestamp ISO 8601
• Tipo de Ação: CRIACAO, ALTERACAO ou EXCLUSAO
• Detalhes: Descrição textual da operação
• Campos Alterados: Valores anterior e novo (apenas para alterações)

Segurança

• O token PAT do Azure DevOps deve ser armazenado como variável de ambiente
• Nunca commite o token no código ou configuração
• Use políticas de autenticação do Backstage para proteger os endpoints
• O endpoint /health é público por padrão

Troubleshooting

Erro: "Azure DevOps Personal Access Token não configurado"

Configure a variável de ambiente AZURE_DEVOPS_PAT com seu token.

Erro: "Configuração 'arb' não encontrada"

Verifique se o app-config.yaml contém a seção arb com as configurações do Azure DevOps.

Erro 401 ao acessar Azure DevOps

Verifique se:

• O token PAT é válido e não expirou
• O token tem permissões de Code (Read & Write)
• A organização, projeto e repositório estão corretos

Arquivos JSON não encontrados

Verifique se:

• O repositório existe no Azure DevOps
• A branch main existe
• Há pelo menos um arquivo JSON no formato {id}.json

Licença

Apache-2.0

Suporte

Para questões ou problemas, abra uma issue no repositório do projeto.