28 KiB
28 KiB
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
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
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:
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
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:
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:
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:
Granularidade: Por tabela/view/procedure
Metadados extraídos:
- Nome do objeto
- Colunas e tipos
- Foreign keys
- Procedures que referenciam
Indexação de JCL:
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:
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
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:
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:
- Syntax check com parser SQL
- Verificação de tabelas/colunas existentes
- Análise de performance (EXPLAIN)
Validações JCL:
- Syntax check JCL
- Datasets referenciados existem
- PGMs referenciados existem
2.3.3 Output Generator
Formato do Comentário JIRA:
## 🤖 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
# 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
# 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
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)
Framework: React 18+ ou Vue 3+
UI Kit: Tailwind CSS + shadcn/ui
State: React Query ou Pinia
Build: Vite
5.3 Infraestrutura
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
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:
- É uma ferramenta de IDE (autocompletar código), não uma API
- Não possui endpoint público para integração programática
- Não oferece funcionalidade de embeddings ou busca semântica
- 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 JIRA AI Fixer usa Azure OpenAI para automação.
6. Segurança
6.1 Dados Sensíveis
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
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
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
-
Semana 1-2:
- Provisionar infra de desenvolvimento
- Criar forks AI no Bitbucket
- Configurar webhooks JIRA (ambiente de teste)
-
Semana 3-4:
- Implementar connector Bitbucket
- Indexar código de 1 repositório (ACQ-MF-safra-fork)
- Testar embeddings com 5 issues históricas
-
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]