# ACI JIRA AI Fixer - Documento Técnico **Versão:** 1.1 **Data:** 2026-02-18 **Atualização:** Azure OpenAI obrigatório para compliance **Classificação:** Interno - Equipe Técnica --- ## 1. Visão Geral ### 1.1 Objetivo Desenvolver um sistema de inteligência artificial que integra com JIRA e Bitbucket para automatizar a análise de Support Cases, identificar módulos afetados no código-fonte (COBOL/SQL/JCL), propor correções e documentar soluções automaticamente. ### 1.2 Escopo - **Produtos:** ACQ-MF (Acquirer) e ICG-MF (Interchange) - **Repositórios:** Forks específicos por cliente (ex: ACQ-MF-safra-fork, ICG-MF-safra-fork) - **Issues:** Support Cases no JIRA - **Linguagens:** COBOL, SQL, JCL ### 1.3 Arquitetura de Alto Nível ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ ACI JIRA AI FIXER - ARQUITETURA │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────┐ │ │ │ JIRA │ │ │ │ gojira.tsacorp│ │ │ │ .com │ │ │ └───────┬───────┘ │ │ │ Webhook (issue_created, issue_updated) │ │ ▼ │ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ │ EVENT PROCESSOR │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ │ │ Queue │ │ Filter │ │ Issue Classifier │ │ │ │ │ │ (Redis) │──▶ (Support │──▶ (Produto, Módulo, │ │ │ │ │ │ │ │ Cases) │ │ Severidade) │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │ │ └───────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ │ CODE INTELLIGENCE ENGINE │ │ │ │ │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │ │ │ │ │ Bitbucket │ │ Code Index │ │ Context │ │ │ │ │ │ Connector │ │ (Embeddings) │ │ Builder │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ bitbucket. │ │ - COBOL procs │ │ - CALLs │ │ │ │ │ │ tsacorp.com │ │ - SQL tables │ │ - COPYBOOKs │ │ │ │ │ │ │ │ - JCL jobs │ │ - Includes │ │ │ │ │ └─────────────────┘ └─────────────────┘ └──────────────┘ │ │ │ │ │ │ │ │ Repositórios: │ │ │ │ ├── ACQ-MF (base) │ │ │ │ │ └── ACQ-MF-safra-fork (cliente) │ │ │ │ │ └── ACQ-MF-safra-ai (IA) ← NOVO │ │ │ │ ├── ICG-MF (base) │ │ │ │ │ └── ICG-MF-safra-fork (cliente) │ │ │ │ │ └── ICG-MF-safra-ai (IA) ← NOVO │ │ │ └───────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ │ FIX GENERATION ENGINE │ │ │ │ │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │ │ │ │ │ LLM Engine │ │ Fix Validator │ │ Output │ │ │ │ │ │ │ │ │ │ Generator │ │ │ │ │ │ - GPT-4o │ │ - Syntax check │ │ │ │ │ │ │ │ - Claude 3.5 │ │ - COBOL rules │ │ - JIRA │ │ │ │ │ │ - Fallback │ │ - SQL lint │ │ comment │ │ │ │ │ │ │ │ - JCL validate │ │ - PR/Branch │ │ │ │ │ └─────────────────┘ └─────────────────┘ └──────────────┘ │ │ │ └───────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌───────────────┴───────────────┐ │ │ ▼ ▼ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ JIRA │ │ Bitbucket │ │ │ │ Comment │ │ Pull Request│ │ │ │ (Análise + │ │ (Fork AI) │ │ │ │ Sugestão) │ │ │ │ │ └──────────────┘ └──────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` --- ## 2. Componentes Detalhados ### 2.1 Event Processor #### 2.1.1 JIRA Webhook Receiver ```yaml Endpoint: POST /api/webhook/jira Eventos: - jira:issue_created - jira:issue_updated Filtros: - issueType: "Support Case" - project: ["ACQ", "ICG"] Autenticação: Webhook Secret (HMAC-SHA256) ``` #### 2.1.2 Queue System ```yaml Tecnologia: Redis + Bull Queue Filas: - jira-events: Eventos brutos do JIRA - analysis-jobs: Jobs de análise pendentes - fix-generation: Geração de correções Retry Policy: - Max attempts: 3 - Backoff: exponential (1min, 5min, 15min) Dead Letter Queue: jira-events-dlq ``` #### 2.1.3 Issue Classifier Responsável por extrair metadados da issue: ```python class IssueClassifier: def classify(self, issue: JiraIssue) -> ClassifiedIssue: return ClassifiedIssue( produto=self._detect_product(issue), # ACQ-MF ou ICG-MF modulo=self._detect_module(issue), # Autorização, Clearing, etc. severidade=self._detect_severity(issue), # P1, P2, P3 keywords=self._extract_keywords(issue), # Termos técnicos stack_trace=self._parse_stack_trace(issue), affected_programs=self._detect_programs(issue) ) ``` ### 2.2 Code Intelligence Engine #### 2.2.1 Bitbucket Connector ```yaml Base URL: https://bitbucket.tsacorp.com API Version: REST 1.0 (Bitbucket Server) Autenticação: Personal Access Token ou OAuth Operações: - Clone/Pull: Sparse checkout (apenas diretórios relevantes) - Read: Conteúdo de arquivos específicos - Branches: Criar/listar branches no fork AI - Pull Requests: Criar PR do fork AI → fork cliente ``` **Estrutura de Acesso por Repo:** | Repositório | Permissão IA | Uso | |-------------|--------------|-----| | ACQ-MF (base) | READ | Referência, padrões | | ACQ-MF-safra-fork | READ | Código atual cliente | | ACQ-MF-safra-ai | WRITE | Branches e commits IA | | ICG-MF (base) | READ | Referência, padrões | | ICG-MF-safra-fork | READ | Código atual cliente | | ICG-MF-safra-ai | WRITE | Branches e commits IA | #### 2.2.2 Code Index (Embeddings) **⚠️ IMPORTANTE: Azure OpenAI Embeddings (Obrigatório)** O cliente possui requisitos de compliance que exigem que os dados de código-fonte não sejam processados por APIs públicas. Por isso, **obrigatoriamente** utilizamos Azure OpenAI Embeddings: ```yaml Provedor: Azure OpenAI (dados permanecem no tenant Azure do cliente) Modelo: text-embedding-ada-002 ou text-embedding-3-large Região: Brazil South (recomendado) ou East US Compliance: Dados não são usados para treinar modelos Microsoft Contrato: Enterprise Agreement existente da ACI ``` **Por que não usar GitHub Copilot para embeddings?** - GitHub Copilot é uma ferramenta de IDE, não possui API para integração - Não oferece funcionalidade de indexação ou busca semântica - Não há como usar Copilot para buscar código relevante programaticamente **Indexação de Código COBOL:** ```yaml Granularidade: Por PROGRAM-ID / SECTION / PARAGRAPH Metadados extraídos: - PROGRAM-ID - COPY statements (dependências) - CALL statements (programas chamados) - FILE-CONTROL (arquivos acessados) - SQL EXEC (tabelas/queries) - Working Storage (variáveis principais) Modelo de Embedding: Azure OpenAI text-embedding-3-large Vector DB: Qdrant (self-hosted na infra ACI) ou Azure AI Search Dimensões: 3072 Índice separado por: produto + cliente ``` **Indexação de SQL:** ```yaml Granularidade: Por tabela/view/procedure Metadados extraídos: - Nome do objeto - Colunas e tipos - Foreign keys - Procedures que referenciam ``` **Indexação de JCL:** ```yaml Granularidade: Por JOB / STEP Metadados extraídos: - JOB name - PGM executados - DD statements (datasets) - PARM passados - Dependências (JCL INCLUDEs) ``` #### 2.2.3 Context Builder Monta o contexto relevante para o LLM analisar: ```python class ContextBuilder: def build_context(self, issue: ClassifiedIssue) -> AnalysisContext: # 1. Busca programas mencionados na issue mentioned_programs = self._search_by_keywords(issue.keywords) # 2. Busca programas similares a issues passadas similar_issues = self._find_similar_issues(issue) # 3. Expande dependências (COPYBOOKs, CALLs) dependencies = self._expand_dependencies(mentioned_programs) # 4. Busca regras de negócio configuradas business_rules = self._get_business_rules(issue.produto) # 5. Monta contexto final (respeitando limite de tokens) return AnalysisContext( primary_code=mentioned_programs[:5], # Max 5 programas principais dependencies=dependencies[:10], # Max 10 dependências similar_fixes=similar_issues[:3], # Max 3 exemplos business_rules=business_rules, total_tokens=self._count_tokens() ) ``` ### 2.3 Fix Generation Engine #### 2.3.1 LLM Engine ```yaml Primary: Azure OpenAI GPT-4o (dados não saem do ambiente Azure) Fallback: Azure OpenAI GPT-4 Turbo Gateway: LiteLLM (unified interface) Configuração: temperature: 0.2 # Baixa para código max_tokens: 4096 top_p: 0.95 ``` **Nota sobre GitHub Copilot:** O cliente possui GitHub Copilot, porém esta ferramenta é destinada ao uso no IDE pelos desenvolvedores. O Copilot **não possui API pública** para integração em sistemas automatizados e **não oferece funcionalidade de embeddings/indexação**. Por isso, a solução utiliza Azure OpenAI para todas as operações de IA. **Prompt Template para COBOL:** ``` Você é um especialista em sistemas de pagamentos mainframe, especificamente nos produtos ACI Acquirer (ACQ-MF) e Interchange (ICG-MF). ## Contexto do Sistema {business_rules} ## Issue Reportada {issue_description} ## Código Atual {code_context} ## Histórico de Fixes Similares {similar_fixes} ## Tarefa Analise a issue e: 1. Identifique a causa raiz provável 2. Localize o(s) programa(s) afetado(s) 3. Proponha uma correção específica 4. Explique o impacto da mudança ## Regras - Mantenha compatibilidade com COBOL-85 - Preserve a estrutura de copybooks existente - Não altere interfaces com outros sistemas sem explicitar - Documente todas as alterações propostas ## Formato de Resposta {response_format} ``` #### 2.3.2 Fix Validator **Validações COBOL:** ```yaml Syntax: - Compilação com GnuCOBOL (syntax check) - Verificação de copybooks referenciados Semântica: - CALLs para programas existentes - Variáveis declaradas antes do uso - PIC clauses compatíveis Estilo: - Indentação padrão (área A/B) - Naming conventions da ACI - Comentários obrigatórios ``` **Validações SQL:** ```yaml - Syntax check com parser SQL - Verificação de tabelas/colunas existentes - Análise de performance (EXPLAIN) ``` **Validações JCL:** ```yaml - Syntax check JCL - Datasets referenciados existem - PGMs referenciados existem ``` #### 2.3.3 Output Generator **Formato do Comentário JIRA:** ```markdown ## 🤖 Análise Automática - AI Fixer ### 📋 Resumo [Descrição concisa do problema identificado] ### 🔍 Causa Raiz Identificada [Explicação técnica da causa] ### 📁 Arquivos Afetados | Arquivo | Tipo | Alteração | |---------|------|-----------| | ACQAUTH.CBL | COBOL | Modificação na SECTION 3000-VALIDATE | | ACQAUTH.CPY | COPYBOOK | Sem alteração | ### 💡 Correção Proposta ```cobol [Código da correção] ``` ### ⚠️ Impacto - [Lista de impactos] ### 📊 Confiança - **Score:** 85% - **Base:** 3 issues similares encontradas ### 🔗 Ações - [Link para PR no Bitbucket] (se aplicável) - [Link para branch com correção] --- *Gerado automaticamente por ACI JIRA AI Fixer v1.0* *Review humano obrigatório antes de merge* ``` --- ## 3. Estrutura de Repositórios (Fork AI) ### 3.1 Criação dos Forks AI ```bash # Estrutura proposta no Bitbucket projects/ ├── ACQ/ │ ├── ACQ-MF # Produto base (existente) │ ├── ACQ-MF-safra-fork # Fork cliente (existente) │ └── ACQ-MF-safra-ai # Fork IA (NOVO) │ ├── ICG/ │ ├── ICG-MF # Produto base (existente) │ ├── ICG-MF-safra-fork # Fork cliente (existente) │ └── ICG-MF-safra-ai # Fork IA (NOVO) ``` ### 3.2 Fluxo de Branches ``` ACQ-MF-safra-fork (cliente) │ │ fork ▼ ACQ-MF-safra-ai (IA) │ ├── main (sync com cliente) │ └── ai-fix/JIRA-1234-descricao │ │ Pull Request ▼ ACQ-MF-safra-fork (cliente) │ │ Review + Approve ▼ merge ``` ### 3.3 Convenção de Commits ``` [AI-FIX] JIRA-1234: Descrição curta do fix Problema: - Descrição do problema original Solução: - O que foi alterado e por quê Arquivos modificados: - src/cobol/ACQAUTH.CBL (linha 1234-1256) Confiança: 85% Gerado por: ACI JIRA AI Fixer v1.0 Co-authored-by: ai-fixer@aci.com ``` ### 3.4 Permissões Recomendadas | Usuário/Grupo | ACQ-MF (base) | Fork Cliente | Fork AI | |---------------|---------------|--------------|---------| | ai-fixer-svc | READ | READ | WRITE | | devs-aci | WRITE | WRITE | READ | | tech-leads | ADMIN | ADMIN | ADMIN | --- ## 4. Interface de Configuração (Admin Panel) ### 4.1 Funcionalidades ``` ┌─────────────────────────────────────────────────────────────┐ │ ACI AI FIXER - ADMIN │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Dashboard │ │ Config │ │ Logs │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ 📊 Dashboard │ │ ├── Issues processadas (hoje/semana/mês) │ │ ├── Taxa de acerto (fixes aceitos) │ │ ├── Tempo médio de análise │ │ └── Fila atual │ │ │ │ ⚙️ Configurações │ │ ├── Regras de Negócio │ │ │ └── [Editor de regras por módulo] │ │ ├── Mapeamento de Módulos │ │ │ └── [Keywords → Programas] │ │ ├── Exemplos de Fixes │ │ │ └── [Issues resolvidas como referência] │ │ ├── Restrições │ │ │ └── [Arquivos/módulos que IA não pode alterar] │ │ └── Conexões │ │ ├── JIRA (webhook URL, credentials) │ │ └── Bitbucket (repos, tokens) │ │ │ │ 📝 Logs │ │ ├── Histórico de análises │ │ ├── Erros e exceções │ │ └── Audit trail (quem aprovou o quê) │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### 4.2 Configuração de Regras de Negócio ```yaml # Exemplo de configuração por módulo modulos: autorizacao: descricao: "Módulo de autorização de transações" programas: - ACQAUTH* - ACQVALD* keywords: - autorização - auth - decline - aprovação regras: - "Transações acima de 10000 requerem validação adicional" - "Códigos de resposta seguem padrão ISO 8583" restricoes: - "Não alterar interface com HOST sem aprovação" clearing: descricao: "Módulo de clearing e settlement" programas: - ICGCLR* - ICGSET* keywords: - clearing - settlement - arquivo retorno regras: - "Arquivos de clearing seguem layout CNAB" ``` ### 4.3 API do Admin Panel ```yaml # Endpoints principais POST /api/config/rules - Criar/atualizar regras de negócio GET /api/config/modules - Listar módulos configurados POST /api/config/examples - Adicionar exemplo de fix GET /api/dashboard/stats - Métricas de uso GET /api/logs/analyses - Histórico de análises POST /api/manual/analyze - Trigger análise manual de uma issue ``` --- ## 5. Stack Tecnológico ### 5.1 Backend ```yaml Runtime: Python 3.11+ Framework: FastAPI Async: asyncio + httpx Queue: Redis 7+ com Bull Queue (via Python-RQ ou Celery) Database: PostgreSQL 15+ (metadados, configurações, logs) Vector DB: Qdrant 1.7+ (self-hosted) Cache: Redis ``` ### 5.2 Frontend (Admin Panel) ```yaml Framework: React 18+ ou Vue 3+ UI Kit: Tailwind CSS + shadcn/ui State: React Query ou Pinia Build: Vite ``` ### 5.3 Infraestrutura ```yaml Container: Docker + Docker Compose Orquestração: Docker Swarm (inicial) ou Kubernetes (escala) CI/CD: Bitbucket Pipelines Reverse Proxy: Traefik ou nginx SSL: Let's Encrypt Monitoramento: Prometheus + Grafana Logs: ELK Stack ou Loki ``` ### 5.4 Integrações Externas ```yaml LLM (Azure OpenAI - OBRIGATÓRIO): Primary: Azure OpenAI GPT-4o Fallback: Azure OpenAI GPT-4 Turbo Região: Brazil South ou East US Gateway: LiteLLM (suporta Azure OpenAI nativamente) Compliance: Dados não usados para treino, ficam no tenant Azure Embeddings (Azure OpenAI - OBRIGATÓRIO): Modelo: Azure OpenAI text-embedding-3-large Alternativa: Azure OpenAI text-embedding-ada-002 Vector DB: Qdrant (self-hosted) ou Azure AI Search JIRA: API: REST API v2 (Server) Auth: Personal Access Token Bitbucket: API: REST API 1.0 (Server) Auth: Personal Access Token ``` **⚠️ Nota sobre GitHub Copilot:** O cliente possui licenças de GitHub Copilot, porém esta ferramenta **não é aplicável** para esta solução porque: 1. É uma ferramenta de IDE (autocompletar código), não uma API 2. Não possui endpoint público para integração programática 3. Não oferece funcionalidade de embeddings ou busca semântica 4. Não permite indexar ou consultar repositórios de código O GitHub Copilot continuará sendo usado pelos desenvolvedores no dia-a-dia, enquanto a solução ACI AI Fixer usa Azure OpenAI para automação. --- ## 6. Segurança ### 6.1 Dados Sensíveis ```yaml Código fonte: - Processado em memória, não persistido em disco - Embeddings armazenados em Qdrant (criptografado at-rest) - Logs sanitizados (sem código completo) Credenciais: - Vault (HashiCorp) ou AWS Secrets Manager - Rotação automática de tokens - Audit log de acessos LLM e Embeddings: - OBRIGATÓRIO: Azure OpenAI (dados não saem do tenant Azure) - Dados não são usados para treinar modelos da Microsoft - Compliance com políticas corporativas ACI - Região Brazil South para menor latência ``` ### 6.2 Rede ```yaml Deployment: - Rede interna (não exposto à internet) - Comunicação HTTPS/TLS 1.3 - Firewall: apenas JIRA e Bitbucket podem acessar webhooks Autenticação: - Admin Panel: SSO via SAML/OIDC (integrar com AD da ACI) - API: JWT tokens com expiração curta - Webhooks: HMAC-SHA256 signature verification ``` ### 6.3 Compliance ```yaml Requisitos: - [ ] Segregação de dados por cliente/fork - [ ] Audit trail completo (quem, quando, o quê) - [ ] Retenção de logs configurável - [ ] Opção de processamento 100% on-premise - [ ] Documentação de fluxo de dados ``` --- ## 7. Estimativas ### 7.1 Timeline de Desenvolvimento | Fase | Duração | Entregas | |------|---------|----------| | **1. Setup Inicial** | 2 semanas | Infra, repos, CI/CD básico | | **2. Integrações** | 3 semanas | JIRA webhook, Bitbucket connector | | **3. Code Intelligence** | 4 semanas | Indexação COBOL/SQL/JCL, embeddings | | **4. Fix Engine** | 3 semanas | LLM integration, prompt engineering | | **5. Output & PR** | 2 semanas | JIRA comments, Bitbucket PRs | | **6. Admin Panel** | 2 semanas | Dashboard, configurações | | **7. Testes & Ajustes** | 2 semanas | Validação com issues reais | | **Total MVP** | **18 semanas** | ~4.5 meses | ### 7.2 Equipe Sugerida | Função | Quantidade | Dedicação | |--------|------------|-----------| | Tech Lead | 1 | 100% | | Backend Developer | 2 | 100% | | Frontend Developer | 1 | 50% | | DevOps | 1 | 25% | | **Total** | **5** | | ### 7.3 Custos Operacionais Mensais (Estimativa) | Item | Custo/Mês | |------|-----------| | LLM APIs (10 issues × ~$3/issue) | ~$30 | | Infra (VPS/On-premise) | $200-500 | | Vector DB (Qdrant self-hosted) | $0 (infra) | | **Total** | **~$230-530/mês** | *Nota: Volume baixo (5-10 issues/mês) resulta em custo operacional mínimo.* --- ## 8. Riscos Técnicos e Mitigações | Risco | Probabilidade | Impacto | Mitigação | |-------|---------------|---------|-----------| | LLM gera fix incorreto | Alta | Alto | Human review obrigatório, confidence score | | Contexto COBOL insuficiente | Média | Alto | RAG com copybooks, exemplos de fixes | | Latência alta | Baixa | Médio | Queue assíncrona, feedback visual | | Bitbucket API rate limit | Baixa | Baixo | Cache agressivo, sparse checkout | | Segurança (código exposto) | Média | Alto | Azure OpenAI ou self-hosted LLM | --- ## 9. Métricas de Sucesso ### 9.1 KPIs Técnicos | Métrica | Target MVP | Target 6 meses | |---------|------------|----------------| | Taxa de análises bem-sucedidas | 80% | 95% | | Fixes aceitos (sem modificação) | 30% | 50% | | Fixes aceitos (com ajustes) | 50% | 70% | | Tempo médio de análise | < 5 min | < 2 min | | Uptime do sistema | 95% | 99% | ### 9.2 KPIs de Negócio | Métrica | Target | |---------|--------| | Redução tempo de análise inicial | 50% | | Issues com sugestão útil | 70% | | Satisfação da equipe | > 4/5 | --- ## 10. Próximos Passos 1. **Semana 1-2:** - Provisionar infra de desenvolvimento - Criar forks AI no Bitbucket - Configurar webhooks JIRA (ambiente de teste) 2. **Semana 3-4:** - Implementar connector Bitbucket - Indexar código de 1 repositório (ACQ-MF-safra-fork) - Testar embeddings com 5 issues históricas 3. **Semana 5-6:** - Integrar LLM (GPT-4o) - Desenvolver prompts específicos para COBOL - Validar outputs com equipe técnica --- **Documento preparado para revisão técnica.** *Contato: [Equipe de Desenvolvimento]*