750 lines
28 KiB
Markdown
750 lines
28 KiB
Markdown
# 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]*
|