diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..1d4f5a8 --- /dev/null +++ b/.env.example @@ -0,0 +1,39 @@ +# Server +JIRA_URL=https://gojira.tsacorp.com +JIRA_TOKEN=your_jira_token +JIRA_WEBHOOK_SECRET=random_secret_for_webhook_validation + +BITBUCKET_URL=https://bitbucket.tsacorp.com +BITBUCKET_TOKEN=your_bitbucket_token + +# LLM (Production - Azure OpenAI) +AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com +AZURE_OPENAI_KEY=your_azure_key +AZURE_OPENAI_MODEL=gpt-4o +AZURE_OPENAI_EMBEDDING_MODEL=text-embedding-3-large + +# LLM (Development - OpenRouter Free) +OPENROUTER_API_KEY=your_openrouter_key +OPENROUTER_MODEL=meta-llama/llama-3.3-70b-instruct:free + +# Use Azure (production) or OpenRouter (development) +LLM_PROVIDER=openrouter + +# Database +DATABASE_URL=postgresql://aci:aci@localhost:5432/aci_fixer +# For development with SQLite: +# DATABASE_URL=sqlite:///./aci_fixer.db + +# Redis +REDIS_URL=redis://localhost:6379 + +# Embeddings (local MiniLM or Azure) +EMBEDDING_PROVIDER=local +# EMBEDDING_PROVIDER=azure + +# Portal +PORTAL_SECRET_KEY=change_this_to_random_string +PORTAL_ADMIN_EMAIL=admin@example.com + +# Logging +LOG_LEVEL=INFO diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..342e9a8 --- /dev/null +++ b/.gitignore @@ -0,0 +1,96 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg + +# PyInstaller +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ + +# Translations +*.mo +*.pot + +# Environments +.env +.env.local +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# IDEs +.idea/ +.vscode/ +*.swp +*.swo +*~ + +# Node.js +node_modules/ +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# Build outputs +portal/dist/ +portal/build/ +*.log + +# Database +*.db +*.sqlite + +# Local config +.env.local +.env.*.local + +# OS +.DS_Store +Thumbs.db + +# Secrets +*.pem +*.key +secrets/ diff --git a/README.md b/README.md index 9e3dfe7..9aac86b 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,119 @@ -# aci-ai-fixer +# ACI AI Fixer -AI system for automated JIRA Support Case analysis with COBOL/SQL/JCL code intelligence \ No newline at end of file +AI system for automated JIRA Support Case analysis with COBOL/SQL/JCL code intelligence. + +## Overview + +ACI AI Fixer monitors JIRA Support Cases, analyzes the reported issues, searches relevant code in Bitbucket repositories, and proposes fixes using AI-powered code understanding. + +## Architecture + +``` +JIRA (webhook) → Event Processor → Code Intelligence → Fix Generator → Output (JIRA + PR) +``` + +## Stack + +- **Backend:** Python 3.11+ / FastAPI +- **Vector DB:** Qdrant (embeddings) +- **Queue:** Redis + Bull +- **Database:** PostgreSQL +- **LLM:** Azure OpenAI GPT-4o / OpenRouter (dev) +- **Embeddings:** MiniLM-L6-v2 (local) / Azure OpenAI (prod) + +## Project Structure + +``` +aci-ai-fixer/ +├── api/ # FastAPI backend +│ ├── main.py +│ ├── routers/ +│ │ ├── webhook.py # JIRA/Bitbucket webhooks +│ │ ├── issues.py # Issue management +│ │ └── config.py # Configuration API +│ ├── services/ +│ │ ├── jira.py # JIRA client +│ │ ├── bitbucket.py # Bitbucket client +│ │ ├── llm.py # LLM orchestration +│ │ └── embeddings.py # Code indexing +│ └── models/ +├── portal/ # React admin UI +│ ├── src/ +│ └── package.json +├── workers/ # Background processors +│ ├── analyzer.py +│ └── indexer.py +├── tests/ +├── docker-compose.yml +├── .env.example +└── README.md +``` + +## Quick Start + +```bash +# Clone +git clone https://gitea.startdata.com.br/startdata/aci-ai-fixer.git +cd aci-ai-fixer + +# Configure +cp .env.example .env +# Edit .env with your credentials + +# Run (development) +docker compose up -d + +# Access portal +open https://localhost:8080 +``` + +## Development + +### Requirements + +- Python 3.11+ +- Node.js 20+ +- Docker & Docker Compose +- Redis +- PostgreSQL (or SQLite for dev) + +### Local Setup + +```bash +# Backend +cd api +python -m venv venv +source venv/bin/activate +pip install -r requirements.txt +uvicorn main:app --reload + +# Portal +cd portal +npm install +npm run dev +``` + +## Configuration + +All configuration is done via the Admin Portal or environment variables: + +| Variable | Description | Required | +|----------|-------------|----------| +| `JIRA_URL` | JIRA Server URL | Yes | +| `JIRA_TOKEN` | JIRA API Token | Yes | +| `BITBUCKET_URL` | Bitbucket Server URL | Yes | +| `BITBUCKET_TOKEN` | Bitbucket Access Token | Yes | +| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI endpoint | Yes (prod) | +| `AZURE_OPENAI_KEY` | Azure OpenAI API key | Yes (prod) | +| `OPENROUTER_API_KEY` | OpenRouter key | Yes (dev) | +| `DATABASE_URL` | PostgreSQL connection | Yes | +| `REDIS_URL` | Redis connection | Yes | + +## License + +Proprietary - StartData Tecnologia + +## Contact + +- **Email:** startdata.tecnologia@gmail.com +- **Developer:** OpenClaw AI Assistant diff --git a/api/Dockerfile b/api/Dockerfile new file mode 100644 index 0000000..8af5068 --- /dev/null +++ b/api/Dockerfile @@ -0,0 +1,21 @@ +FROM python:3.11-slim + +WORKDIR /app + +# Install system dependencies +RUN apt-get update && apt-get install -y \ + gcc \ + && rm -rf /var/lib/apt/lists/* + +# Install Python dependencies +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt + +# Copy application +COPY . . + +# Expose port +EXPOSE 8000 + +# Run +CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"] diff --git a/api/main.py b/api/main.py new file mode 100644 index 0000000..a8618da --- /dev/null +++ b/api/main.py @@ -0,0 +1,53 @@ +""" +ACI AI Fixer - FastAPI Backend +""" +from fastapi import FastAPI +from fastapi.middleware.cors import CORSMiddleware +from contextlib import asynccontextmanager +import logging + +from routers import webhook, issues, config + +logging.basicConfig(level=logging.INFO) +logger = logging.getLogger(__name__) + + +@asynccontextmanager +async def lifespan(app: FastAPI): + """Startup and shutdown events.""" + logger.info("🚀 ACI AI Fixer starting up...") + # Initialize database, connections, etc. + yield + logger.info("👋 ACI AI Fixer shutting down...") + + +app = FastAPI( + title="ACI AI Fixer", + description="AI system for automated JIRA Support Case analysis", + version="0.1.0", + lifespan=lifespan, +) + +# CORS for portal +app.add_middleware( + CORSMiddleware, + allow_origins=["*"], # Configure properly in production + allow_credentials=True, + allow_methods=["*"], + allow_headers=["*"], +) + +# Include routers +app.include_router(webhook.router, prefix="/api/webhook", tags=["webhook"]) +app.include_router(issues.router, prefix="/api/issues", tags=["issues"]) +app.include_router(config.router, prefix="/api/config", tags=["config"]) + + +@app.get("/") +async def root(): + return {"status": "ok", "service": "ACI AI Fixer", "version": "0.1.0"} + + +@app.get("/health") +async def health(): + return {"status": "healthy"} diff --git a/api/requirements.txt b/api/requirements.txt new file mode 100644 index 0000000..5d5e369 --- /dev/null +++ b/api/requirements.txt @@ -0,0 +1,12 @@ +fastapi>=0.109.0 +uvicorn[standard]>=0.27.0 +httpx>=0.26.0 +pydantic>=2.5.0 +python-dotenv>=1.0.0 +redis>=5.0.0 +sqlalchemy>=2.0.0 +alembic>=1.13.0 +asyncpg>=0.29.0 +qdrant-client>=1.7.0 +sentence-transformers>=2.2.0 +numpy>=1.26.0 diff --git a/api/routers/__init__.py b/api/routers/__init__.py new file mode 100644 index 0000000..22227cf --- /dev/null +++ b/api/routers/__init__.py @@ -0,0 +1,4 @@ +"""API Routers package.""" +from . import webhook, issues, config + +__all__ = ["webhook", "issues", "config"] diff --git a/api/routers/config.py b/api/routers/config.py new file mode 100644 index 0000000..3cff622 --- /dev/null +++ b/api/routers/config.py @@ -0,0 +1,134 @@ +""" +Configuration management API. +""" +from fastapi import APIRouter, HTTPException +from pydantic import BaseModel +from typing import Optional, List, Dict, Any +import logging + +logger = logging.getLogger(__name__) +router = APIRouter() + + +class IntegrationConfig(BaseModel): + jira_url: Optional[str] = None + jira_token: Optional[str] = None + jira_projects: List[str] = [] + bitbucket_url: Optional[str] = None + bitbucket_token: Optional[str] = None + llm_provider: str = "openrouter" # openrouter | azure + azure_endpoint: Optional[str] = None + azure_key: Optional[str] = None + azure_model: str = "gpt-4o" + openrouter_key: Optional[str] = None + openrouter_model: str = "meta-llama/llama-3.3-70b-instruct:free" + embedding_provider: str = "local" # local | azure + + +class RepositoryConfig(BaseModel): + url: str + name: str + ai_fork_name: Optional[str] = None + indexed: bool = False + last_sync: Optional[str] = None + file_count: int = 0 + + +class ModuleConfig(BaseModel): + name: str + description: Optional[str] = None + program_patterns: List[str] = [] + keywords: List[str] = [] + rules: List[str] = [] + restrictions: List[str] = [] + + +class SystemConfig(BaseModel): + integrations: IntegrationConfig + repositories: List[RepositoryConfig] = [] + modules: List[ModuleConfig] = [] + + +@router.get("/integrations", response_model=IntegrationConfig) +async def get_integrations(): + """Get integration configuration (tokens masked).""" + # TODO: Load from database + return IntegrationConfig() + + +@router.put("/integrations") +async def update_integrations(config: IntegrationConfig): + """Update integration configuration.""" + logger.info("💾 Updating integration config") + # TODO: Save to database + return {"status": "updated"} + + +@router.post("/integrations/test/{service}") +async def test_integration(service: str): + """Test connection to a service (jira, bitbucket, llm, embeddings).""" + logger.info(f"🔌 Testing connection: {service}") + # TODO: Implement connection tests + return {"status": "ok", "service": service, "connected": True} + + +@router.get("/repositories", response_model=List[RepositoryConfig]) +async def list_repositories(): + """List configured repositories.""" + # TODO: Load from database + return [] + + +@router.post("/repositories") +async def add_repository(repo: RepositoryConfig): + """Add a new repository for indexing.""" + logger.info(f"📦 Adding repository: {repo.url}") + # TODO: Save and trigger indexing + return {"status": "added", "repository": repo.name} + + +@router.delete("/repositories/{repo_name}") +async def remove_repository(repo_name: str): + """Remove a repository.""" + logger.info(f"🗑️ Removing repository: {repo_name}") + # TODO: Remove from database and vector store + return {"status": "removed"} + + +@router.post("/repositories/{repo_name}/reindex") +async def reindex_repository(repo_name: str): + """Trigger re-indexing of a repository.""" + logger.info(f"🔄 Re-indexing repository: {repo_name}") + # TODO: Queue re-indexing job + return {"status": "queued"} + + +@router.get("/modules", response_model=List[ModuleConfig]) +async def list_modules(): + """List business rule modules.""" + # TODO: Load from database + return [] + + +@router.post("/modules") +async def add_module(module: ModuleConfig): + """Add a new business rule module.""" + logger.info(f"🧠 Adding module: {module.name}") + # TODO: Save to database + return {"status": "added", "module": module.name} + + +@router.put("/modules/{module_name}") +async def update_module(module_name: str, module: ModuleConfig): + """Update a business rule module.""" + logger.info(f"💾 Updating module: {module_name}") + # TODO: Update in database + return {"status": "updated"} + + +@router.delete("/modules/{module_name}") +async def delete_module(module_name: str): + """Delete a business rule module.""" + logger.info(f"🗑️ Deleting module: {module_name}") + # TODO: Remove from database + return {"status": "deleted"} diff --git a/api/routers/issues.py b/api/routers/issues.py new file mode 100644 index 0000000..018fb79 --- /dev/null +++ b/api/routers/issues.py @@ -0,0 +1,94 @@ +""" +Issue management API. +""" +from fastapi import APIRouter, HTTPException +from pydantic import BaseModel +from typing import Optional, List +from enum import Enum +from datetime import datetime +import logging + +logger = logging.getLogger(__name__) +router = APIRouter() + + +class IssueStatus(str, Enum): + PENDING = "pending" + ANALYZING = "analyzing" + ANALYZED = "analyzed" + FIX_GENERATED = "fix_generated" + PR_CREATED = "pr_created" + ACCEPTED = "accepted" + REJECTED = "rejected" + FAILED = "failed" + + +class AnalyzedIssue(BaseModel): + id: str + jira_key: str + title: str + status: IssueStatus + module: Optional[str] = None + confidence: Optional[float] = None + analysis_time_ms: Optional[int] = None + affected_files: List[str] = [] + root_cause: Optional[str] = None + proposed_fix: Optional[str] = None + pr_url: Optional[str] = None + created_at: datetime + updated_at: datetime + + +class IssueListResponse(BaseModel): + total: int + items: List[AnalyzedIssue] + + +@router.get("/", response_model=IssueListResponse) +async def list_issues( + status: Optional[IssueStatus] = None, + module: Optional[str] = None, + limit: int = 20, + offset: int = 0, +): + """ + List analyzed issues with optional filters. + """ + # TODO: Implement database query + return IssueListResponse(total=0, items=[]) + + +@router.get("/{issue_id}", response_model=AnalyzedIssue) +async def get_issue(issue_id: str): + """ + Get details of a specific analyzed issue. + """ + # TODO: Implement database query + raise HTTPException(status_code=404, detail="Issue not found") + + +@router.post("/{issue_id}/reanalyze") +async def reanalyze_issue(issue_id: str): + """ + Trigger re-analysis of an issue. + """ + logger.info(f"🔄 Re-analyzing issue: {issue_id}") + # TODO: Queue for re-analysis + return {"status": "queued", "issue_id": issue_id} + + +@router.get("/stats/summary") +async def get_stats(): + """ + Get summary statistics for dashboard. + """ + # TODO: Implement stats calculation + return { + "total_issues": 0, + "pending": 0, + "analyzed": 0, + "accepted": 0, + "rejected": 0, + "success_rate": 0.0, + "avg_analysis_time_ms": 0, + } diff --git a/api/routers/webhook.py b/api/routers/webhook.py new file mode 100644 index 0000000..10369d4 --- /dev/null +++ b/api/routers/webhook.py @@ -0,0 +1,79 @@ +""" +Webhook handlers for JIRA and Bitbucket events. +""" +from fastapi import APIRouter, Request, HTTPException, Header +from typing import Optional +import hmac +import hashlib +import logging + +logger = logging.getLogger(__name__) +router = APIRouter() + + +def verify_jira_signature(payload: bytes, signature: str, secret: str) -> bool: + """Verify JIRA webhook signature.""" + expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest() + return hmac.compare_digest(expected, signature) + + +@router.post("/jira") +async def jira_webhook( + request: Request, + x_atlassian_webhook_identifier: Optional[str] = Header(None), +): + """ + Handle JIRA webhook events. + + Events processed: + - jira:issue_created + - jira:issue_updated + """ + body = await request.body() + data = await request.json() + + event_type = data.get("webhookEvent", "unknown") + issue = data.get("issue", {}) + issue_key = issue.get("key", "unknown") + + logger.info(f"📥 JIRA webhook: {event_type} - {issue_key}") + + # Filter: only process Support Cases + issue_type = issue.get("fields", {}).get("issuetype", {}).get("name", "") + if issue_type != "Support Case": + logger.info(f"⏭️ Skipping non-Support Case issue: {issue_key} ({issue_type})") + return {"status": "skipped", "reason": "not a Support Case"} + + # Queue for analysis + # TODO: Implement queue system + logger.info(f"📋 Queuing Support Case for analysis: {issue_key}") + + return { + "status": "accepted", + "issue": issue_key, + "event": event_type, + } + + +@router.post("/bitbucket") +async def bitbucket_webhook(request: Request): + """ + Handle Bitbucket webhook events. + + Events processed: + - repo:refs_changed (push) + - pr:merged + """ + data = await request.json() + event_type = data.get("eventKey", "unknown") + + logger.info(f"📥 Bitbucket webhook: {event_type}") + + if event_type == "repo:refs_changed": + # Re-index affected files + changes = data.get("changes", []) + for change in changes: + ref = change.get("ref", {}).get("displayId", "") + logger.info(f"🔄 Branch updated: {ref}") + + return {"status": "accepted", "event": event_type} diff --git a/api/services/__init__.py b/api/services/__init__.py new file mode 100644 index 0000000..0057ede --- /dev/null +++ b/api/services/__init__.py @@ -0,0 +1,7 @@ +"""Services package.""" +from .jira import JiraClient +from .bitbucket import BitbucketClient +from .llm import LLMService +from .embeddings import EmbeddingsService + +__all__ = ["JiraClient", "BitbucketClient", "LLMService", "EmbeddingsService"] diff --git a/api/services/bitbucket.py b/api/services/bitbucket.py new file mode 100644 index 0000000..586103f --- /dev/null +++ b/api/services/bitbucket.py @@ -0,0 +1,188 @@ +""" +Bitbucket Service - Client for Bitbucket Server API. +""" +from typing import Optional, Dict, Any, List +import httpx +import logging + +logger = logging.getLogger(__name__) + + +class BitbucketClient: + """Bitbucket Server REST API client.""" + + def __init__(self, base_url: str, token: str): + self.base_url = base_url.rstrip("/") + self.headers = { + "Authorization": f"Bearer {token}", + "Content-Type": "application/json", + } + + async def get_file_content( + self, + project: str, + repo: str, + file_path: str, + ref: str = "main", + ) -> str: + """Get raw file content from a repository.""" + async with httpx.AsyncClient() as client: + response = await client.get( + f"{self.base_url}/rest/api/1.0/projects/{project}/repos/{repo}/raw/{file_path}", + headers=self.headers, + params={"at": ref}, + ) + response.raise_for_status() + return response.text + + async def list_files( + self, + project: str, + repo: str, + path: str = "", + ref: str = "main", + ) -> List[Dict[str, Any]]: + """List files in a directory.""" + async with httpx.AsyncClient() as client: + response = await client.get( + f"{self.base_url}/rest/api/1.0/projects/{project}/repos/{repo}/files/{path}", + headers=self.headers, + params={"at": ref}, + ) + response.raise_for_status() + return response.json().get("values", []) + + async def create_branch( + self, + project: str, + repo: str, + branch_name: str, + start_point: str = "main", + ) -> Dict[str, Any]: + """Create a new branch.""" + async with httpx.AsyncClient() as client: + response = await client.post( + f"{self.base_url}/rest/api/1.0/projects/{project}/repos/{repo}/branches", + headers=self.headers, + json={ + "name": branch_name, + "startPoint": f"refs/heads/{start_point}", + }, + ) + response.raise_for_status() + return response.json() + + async def commit_file( + self, + project: str, + repo: str, + branch: str, + file_path: str, + content: str, + message: str, + ) -> Dict[str, Any]: + """Commit a file change to a branch.""" + # Get current commit for the branch + async with httpx.AsyncClient() as client: + # First, get the latest commit on the branch + branch_response = await client.get( + f"{self.base_url}/rest/api/1.0/projects/{project}/repos/{repo}/branches", + headers=self.headers, + params={"filterText": branch}, + ) + branch_response.raise_for_status() + branches = branch_response.json().get("values", []) + + if not branches: + raise ValueError(f"Branch not found: {branch}") + + latest_commit = branches[0].get("latestCommit") + + # Use file edit API + response = await client.put( + f"{self.base_url}/rest/api/1.0/projects/{project}/repos/{repo}/browse/{file_path}", + headers=self.headers, + json={ + "content": content, + "message": message, + "branch": branch, + "sourceCommitId": latest_commit, + }, + ) + response.raise_for_status() + return response.json() + + async def create_pull_request( + self, + project: str, + repo: str, + title: str, + description: str, + source_branch: str, + target_branch: str = "main", + target_project: Optional[str] = None, + target_repo: Optional[str] = None, + ) -> Dict[str, Any]: + """Create a pull request.""" + target_project = target_project or project + target_repo = target_repo or repo + + async with httpx.AsyncClient() as client: + response = await client.post( + f"{self.base_url}/rest/api/1.0/projects/{project}/repos/{repo}/pull-requests", + headers=self.headers, + json={ + "title": title, + "description": description, + "fromRef": { + "id": f"refs/heads/{source_branch}", + "repository": { + "slug": repo, + "project": {"key": project}, + }, + }, + "toRef": { + "id": f"refs/heads/{target_branch}", + "repository": { + "slug": target_repo, + "project": {"key": target_project}, + }, + }, + }, + ) + response.raise_for_status() + return response.json() + + async def get_repositories(self, project: str) -> List[Dict[str, Any]]: + """List repositories in a project.""" + async with httpx.AsyncClient() as client: + response = await client.get( + f"{self.base_url}/rest/api/1.0/projects/{project}/repos", + headers=self.headers, + ) + response.raise_for_status() + return response.json().get("values", []) + + async def search_code( + self, + project: str, + repo: str, + query: str, + ref: str = "main", + ) -> List[Dict[str, Any]]: + """Search for code in a repository.""" + # Bitbucket Server code search API + async with httpx.AsyncClient() as client: + response = await client.get( + f"{self.base_url}/rest/search/1.0/search", + headers=self.headers, + params={ + "query": query, + "entities": "code", + "projectKey": project, + "repositorySlug": repo, + }, + ) + if response.status_code == 200: + return response.json().get("values", []) + return [] diff --git a/api/services/embeddings.py b/api/services/embeddings.py new file mode 100644 index 0000000..ddde074 --- /dev/null +++ b/api/services/embeddings.py @@ -0,0 +1,300 @@ +""" +Embeddings Service - Code indexing with vector embeddings. +""" +from typing import Optional, Dict, Any, List, Tuple +import httpx +import numpy as np +import logging +import re +from dataclasses import dataclass + +logger = logging.getLogger(__name__) + + +@dataclass +class CodeChunk: + """A chunk of indexed code.""" + file_path: str + content: str + start_line: int + end_line: int + chunk_type: str # program, section, paragraph, copybook + metadata: Dict[str, Any] + + +class EmbeddingsService: + """ + Service for generating and managing code embeddings. + + Supports: + - Local MiniLM-L6-v2 (development) + - Azure OpenAI embeddings (production) + """ + + def __init__( + self, + provider: str = "local", + azure_endpoint: Optional[str] = None, + azure_key: Optional[str] = None, + azure_model: str = "text-embedding-3-large", + qdrant_url: str = "http://localhost:6333", + ): + self.provider = provider + self.azure_endpoint = azure_endpoint + self.azure_key = azure_key + self.azure_model = azure_model + self.qdrant_url = qdrant_url + self._local_model = None + + async def embed_text(self, text: str) -> List[float]: + """Generate embedding for a text.""" + if self.provider == "azure": + return await self._embed_azure(text) + else: + return self._embed_local(text) + + async def _embed_azure(self, text: str) -> List[float]: + """Generate embedding using Azure OpenAI.""" + url = f"{self.azure_endpoint}/openai/deployments/{self.azure_model}/embeddings?api-version=2024-02-01" + + async with httpx.AsyncClient() as client: + response = await client.post( + url, + headers={ + "api-key": self.azure_key, + "Content-Type": "application/json", + }, + json={"input": text}, + timeout=60.0, + ) + response.raise_for_status() + data = response.json() + return data["data"][0]["embedding"] + + def _embed_local(self, text: str) -> List[float]: + """Generate embedding using local MiniLM model.""" + if self._local_model is None: + from sentence_transformers import SentenceTransformer + self._local_model = SentenceTransformer("all-MiniLM-L6-v2") + + embedding = self._local_model.encode(text) + return embedding.tolist() + + def parse_cobol_program(self, content: str, file_path: str) -> List[CodeChunk]: + """ + Parse a COBOL program into indexable chunks. + + Extracts: + - PROGRAM-ID + - COPY statements + - CALL statements + - SECTIONs and PARAGRAPHs + - FILE-CONTROL + - Working Storage variables + """ + chunks = [] + lines = content.split("\n") + + # Extract PROGRAM-ID + program_id = None + for i, line in enumerate(lines): + match = re.search(r"PROGRAM-ID\.\s+(\S+)", line, re.IGNORECASE) + if match: + program_id = match.group(1).rstrip(".") + break + + # Extract COPY statements + copies = [] + for i, line in enumerate(lines): + match = re.search(r"COPY\s+(\S+)", line, re.IGNORECASE) + if match: + copies.append(match.group(1).rstrip(".")) + + # Extract CALL statements + calls = [] + for i, line in enumerate(lines): + match = re.search(r"CALL\s+['\"](\S+)['\"]", line, re.IGNORECASE) + if match: + calls.append(match.group(1)) + + # Extract SECTIONs + current_section = None + section_start = 0 + section_content = [] + + for i, line in enumerate(lines): + # Check for SECTION definition + match = re.search(r"^\s{7}(\S+)\s+SECTION", line) + if match: + # Save previous section + if current_section: + chunks.append(CodeChunk( + file_path=file_path, + content="\n".join(section_content), + start_line=section_start, + end_line=i - 1, + chunk_type="section", + metadata={ + "program_id": program_id, + "section_name": current_section, + "copies": copies, + "calls": calls, + }, + )) + current_section = match.group(1) + section_start = i + section_content = [line] + elif current_section: + section_content.append(line) + + # Save last section + if current_section: + chunks.append(CodeChunk( + file_path=file_path, + content="\n".join(section_content), + start_line=section_start, + end_line=len(lines) - 1, + chunk_type="section", + metadata={ + "program_id": program_id, + "section_name": current_section, + "copies": copies, + "calls": calls, + }, + )) + + # If no sections found, chunk the whole program + if not chunks: + chunks.append(CodeChunk( + file_path=file_path, + content=content, + start_line=1, + end_line=len(lines), + chunk_type="program", + metadata={ + "program_id": program_id, + "copies": copies, + "calls": calls, + }, + )) + + return chunks + + async def index_chunks( + self, + chunks: List[CodeChunk], + collection: str, + product: str, + client: str, + ) -> int: + """Index code chunks into Qdrant.""" + indexed = 0 + + for chunk in chunks: + # Generate embedding + text_to_embed = f""" +File: {chunk.file_path} +Type: {chunk.chunk_type} +{chunk.metadata.get('section_name', '')} +{chunk.content[:1000]} +""" + embedding = await self.embed_text(text_to_embed) + + # Store in Qdrant + await self._store_vector( + collection=collection, + vector=embedding, + payload={ + "file_path": chunk.file_path, + "content": chunk.content, + "start_line": chunk.start_line, + "end_line": chunk.end_line, + "chunk_type": chunk.chunk_type, + "product": product, + "client": client, + **chunk.metadata, + }, + ) + indexed += 1 + + return indexed + + async def search_similar( + self, + query: str, + collection: str, + limit: int = 10, + filters: Optional[Dict[str, Any]] = None, + ) -> List[Dict[str, Any]]: + """Search for similar code chunks.""" + embedding = await self.embed_text(query) + + async with httpx.AsyncClient() as client: + body = { + "vector": embedding, + "limit": limit, + "with_payload": True, + } + if filters: + body["filter"] = filters + + response = await client.post( + f"{self.qdrant_url}/collections/{collection}/points/search", + json=body, + timeout=30.0, + ) + + if response.status_code == 200: + results = response.json().get("result", []) + return [ + { + "score": r["score"], + **r["payload"], + } + for r in results + ] + return [] + + async def _store_vector( + self, + collection: str, + vector: List[float], + payload: Dict[str, Any], + ) -> bool: + """Store a vector in Qdrant.""" + import uuid + + async with httpx.AsyncClient() as client: + response = await client.put( + f"{self.qdrant_url}/collections/{collection}/points", + json={ + "points": [ + { + "id": str(uuid.uuid4()), + "vector": vector, + "payload": payload, + } + ] + }, + timeout=30.0, + ) + return response.status_code == 200 + + async def create_collection( + self, + name: str, + vector_size: int = 384, # MiniLM default + ) -> bool: + """Create a Qdrant collection.""" + async with httpx.AsyncClient() as client: + response = await client.put( + f"{self.qdrant_url}/collections/{name}", + json={ + "vectors": { + "size": vector_size, + "distance": "Cosine", + } + }, + timeout=30.0, + ) + return response.status_code in [200, 201] diff --git a/api/services/jira.py b/api/services/jira.py new file mode 100644 index 0000000..95a2d6e --- /dev/null +++ b/api/services/jira.py @@ -0,0 +1,110 @@ +""" +JIRA Service - Client for JIRA Server API. +""" +from typing import Optional, Dict, Any, List +import httpx +import logging + +logger = logging.getLogger(__name__) + + +class JiraClient: + """JIRA Server REST API client.""" + + def __init__(self, base_url: str, token: str): + self.base_url = base_url.rstrip("/") + self.headers = { + "Authorization": f"Bearer {token}", + "Content-Type": "application/json", + } + + async def get_issue(self, issue_key: str) -> Dict[str, Any]: + """Fetch issue details.""" + async with httpx.AsyncClient() as client: + response = await client.get( + f"{self.base_url}/rest/api/2/issue/{issue_key}", + headers=self.headers, + ) + response.raise_for_status() + return response.json() + + async def add_comment(self, issue_key: str, body: str) -> Dict[str, Any]: + """Add a comment to an issue.""" + async with httpx.AsyncClient() as client: + response = await client.post( + f"{self.base_url}/rest/api/2/issue/{issue_key}/comment", + headers=self.headers, + json={"body": body}, + ) + response.raise_for_status() + return response.json() + + async def search_issues( + self, + jql: str, + start_at: int = 0, + max_results: int = 50, + fields: Optional[List[str]] = None, + ) -> Dict[str, Any]: + """Search issues using JQL.""" + params = { + "jql": jql, + "startAt": start_at, + "maxResults": max_results, + } + if fields: + params["fields"] = ",".join(fields) + + async with httpx.AsyncClient() as client: + response = await client.get( + f"{self.base_url}/rest/api/2/search", + headers=self.headers, + params=params, + ) + response.raise_for_status() + return response.json() + + async def get_projects(self) -> List[Dict[str, Any]]: + """List all accessible projects.""" + async with httpx.AsyncClient() as client: + response = await client.get( + f"{self.base_url}/rest/api/2/project", + headers=self.headers, + ) + response.raise_for_status() + return response.json() + + def format_analysis_comment( + self, + root_cause: str, + affected_files: List[str], + proposed_fix: str, + confidence: float, + pr_url: Optional[str] = None, + ) -> str: + """Format AI analysis as a JIRA comment.""" + files_list = "\n".join([f"* {f}" for f in affected_files]) + + comment = f""" +h2. 📋 Análise Automática + +h3. 🔍 Causa Raiz Identificada +{root_cause} + +h3. 📁 Arquivos Afetados +{files_list} + +h3. 💡 Correção Proposta +{{code:cobol}} +{proposed_fix} +{{code}} + +h3. 📊 Confiança: {confidence:.0%} +""" + + if pr_url: + comment += f"\nh3. 🔗 Pull Request\n[Ver PR|{pr_url}]" + + comment += "\n\n_Gerado automaticamente por ACI AI Fixer_" + + return comment diff --git a/api/services/llm.py b/api/services/llm.py new file mode 100644 index 0000000..3cb0875 --- /dev/null +++ b/api/services/llm.py @@ -0,0 +1,193 @@ +""" +LLM Service - Orchestration for AI models. +""" +from typing import Optional, Dict, Any, List +import httpx +import json +import logging +import os + +logger = logging.getLogger(__name__) + + +class LLMService: + """ + LLM orchestration service supporting multiple providers. + + Providers: + - Azure OpenAI (production, compliance) + - OpenRouter (development, free models) + """ + + def __init__( + self, + provider: str = "openrouter", + azure_endpoint: Optional[str] = None, + azure_key: Optional[str] = None, + azure_model: str = "gpt-4o", + openrouter_key: Optional[str] = None, + openrouter_model: str = "meta-llama/llama-3.3-70b-instruct:free", + ): + self.provider = provider + self.azure_endpoint = azure_endpoint + self.azure_key = azure_key + self.azure_model = azure_model + self.openrouter_key = openrouter_key + self.openrouter_model = openrouter_model + + async def analyze_issue( + self, + issue_description: str, + code_context: str, + business_rules: Optional[str] = None, + similar_fixes: Optional[List[Dict[str, Any]]] = None, + ) -> Dict[str, Any]: + """ + Analyze an issue and generate fix suggestions. + + Returns: + { + "root_cause": str, + "affected_files": List[str], + "proposed_fix": str, + "confidence": float, + "explanation": str, + } + """ + prompt = self._build_analysis_prompt( + issue_description, + code_context, + business_rules, + similar_fixes, + ) + + response = await self._call_llm(prompt) + return self._parse_analysis_response(response) + + def _build_analysis_prompt( + self, + issue_description: str, + code_context: str, + business_rules: Optional[str], + similar_fixes: Optional[List[Dict[str, Any]]], + ) -> str: + """Build the analysis prompt.""" + + prompt = f"""Você é um especialista em sistemas de pagamento mainframe, especificamente nos produtos ACI Acquirer (ACQ-MF) e Interchange (ICG-MF). + +## Contexto do Sistema +{business_rules or "Nenhuma regra de negócio específica fornecida."} + +## Issue Reportada +{issue_description} + +## Código Atual +{code_context} + +""" + + if similar_fixes: + prompt += "## Histórico de Fixes Similares\n" + for i, fix in enumerate(similar_fixes[:3], 1): + prompt += f""" +### Exemplo {i} +Problema: {fix.get('problem', 'N/A')} +Solução: {fix.get('solution', 'N/A')} +""" + + prompt += """ +## 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 alteração + +## Regras +- Mantenha compatibilidade COBOL-85 +- Preserve a estrutura de copybooks existente +- Não altere interfaces com outros sistemas sem menção explícita +- Documente todas as alterações propostas + +## Formato de Resposta +Responda em JSON válido: +{ + "root_cause": "Descrição da causa raiz identificada", + "affected_files": ["arquivo1.cbl", "arquivo2.cbl"], + "proposed_fix": "Código COBOL com a correção proposta", + "confidence": 0.85, + "explanation": "Explicação detalhada do impacto" +} +""" + return prompt + + async def _call_llm(self, prompt: str) -> str: + """Call the configured LLM provider.""" + if self.provider == "azure": + return await self._call_azure(prompt) + else: + return await self._call_openrouter(prompt) + + async def _call_azure(self, prompt: str) -> str: + """Call Azure OpenAI.""" + url = f"{self.azure_endpoint}/openai/deployments/{self.azure_model}/chat/completions?api-version=2024-02-01" + + async with httpx.AsyncClient() as client: + response = await client.post( + url, + headers={ + "api-key": self.azure_key, + "Content-Type": "application/json", + }, + json={ + "messages": [{"role": "user", "content": prompt}], + "temperature": 0.2, + "max_tokens": 4096, + }, + timeout=120.0, + ) + response.raise_for_status() + data = response.json() + return data["choices"][0]["message"]["content"] + + async def _call_openrouter(self, prompt: str) -> str: + """Call OpenRouter API.""" + async with httpx.AsyncClient() as client: + response = await client.post( + "https://openrouter.ai/api/v1/chat/completions", + headers={ + "Authorization": f"Bearer {self.openrouter_key}", + "Content-Type": "application/json", + }, + json={ + "model": self.openrouter_model, + "messages": [{"role": "user", "content": prompt}], + "temperature": 0.2, + "max_tokens": 4096, + }, + timeout=120.0, + ) + response.raise_for_status() + data = response.json() + return data["choices"][0]["message"]["content"] + + def _parse_analysis_response(self, response: str) -> Dict[str, Any]: + """Parse LLM response into structured format.""" + try: + # Try to extract JSON from response + start = response.find("{") + end = response.rfind("}") + 1 + if start >= 0 and end > start: + json_str = response[start:end] + return json.loads(json_str) + except json.JSONDecodeError: + logger.warning("Failed to parse LLM response as JSON") + + # Fallback: return raw response + return { + "root_cause": "Unable to parse structured response", + "affected_files": [], + "proposed_fix": response, + "confidence": 0.3, + "explanation": "Response could not be parsed automatically", + } diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..af9700b --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,63 @@ +version: "3.8" + +services: + api: + build: + context: ./api + dockerfile: Dockerfile + ports: + - "8000:8000" + environment: + - DATABASE_URL=postgresql://aci:aci@postgres:5432/aci_fixer + - REDIS_URL=redis://redis:6379 + - QDRANT_URL=http://qdrant:6333 + env_file: + - .env + depends_on: + - postgres + - redis + - qdrant + volumes: + - ./api:/app + command: uvicorn main:app --host 0.0.0.0 --port 8000 --reload + + portal: + build: + context: ./portal + dockerfile: Dockerfile + ports: + - "3000:3000" + volumes: + - ./portal:/app + - /app/node_modules + command: npm run dev + + postgres: + image: postgres:15-alpine + environment: + - POSTGRES_USER=aci + - POSTGRES_PASSWORD=aci + - POSTGRES_DB=aci_fixer + volumes: + - postgres_data:/var/lib/postgresql/data + ports: + - "5432:5432" + + redis: + image: redis:7-alpine + ports: + - "6379:6379" + volumes: + - redis_data:/data + + qdrant: + image: qdrant/qdrant:v1.7.4 + ports: + - "6333:6333" + volumes: + - qdrant_data:/qdrant/storage + +volumes: + postgres_data: + redis_data: + qdrant_data: diff --git a/docs/aci-jira-ai-fixer-executive-en.md b/docs/aci-jira-ai-fixer-executive-en.md new file mode 100644 index 0000000..833ef3f --- /dev/null +++ b/docs/aci-jira-ai-fixer-executive-en.md @@ -0,0 +1,346 @@ +# ACI JIRA AI Fixer +## Executive Proposal + +**Date:** February 18, 2026 +**Version:** 1.1 +**Update:** Azure OpenAI mandatory for compliance +**Classification:** Internal - Executive + +--- + +## Executive Summary + +### The Problem + +The support team faces growing challenges in resolving Support Cases: + +| Challenge | Impact | +|-----------|--------| +| **Response time** | Initial analysis consumes hours of senior developer time | +| **Growing backlog** | Issues accumulate while team focuses on urgent demands | +| **Variable quality** | Dependency on individual knowledge about the code | +| **Concentrated knowledge** | Few specialists know all modules | + +### The Solution + +An **Artificial Intelligence** system that: + +1. **Monitors** new Support Cases in JIRA automatically +2. **Analyzes** the problem and identifies affected source code +3. **Proposes** specific fixes in COBOL, SQL, and JCL +4. **Documents** the analysis directly in JIRA +5. **Creates** branches with fixes for human review + +### Expected Result + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ BEFORE vs AFTER │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ BEFORE AFTER │ +│ ────── ───── │ +│ Issue created Issue created │ +│ ↓ ↓ │ +│ Dev analyzes (2-4h) AI analyzes (5min) │ +│ ↓ ↓ │ +│ Search code (1-2h) Code identified │ +│ ↓ ↓ │ +│ Investigate cause (2-4h) Cause + suggested fix │ +│ ↓ ↓ │ +│ Develop fix (2-4h) Dev reviews and approves │ +│ ↓ ↓ │ +│ Review + deploy Review + deploy │ +│ │ +│ TOTAL: 8-14 hours TOTAL: 2-4 hours │ +│ │ +│ ✅ 60-70% reduction in resolution time │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Why Now? + +### 1. Mature Technology +Language models (GPT-4, Claude) have reached sufficient quality for code analysis and generation, including legacy languages like COBOL. + +### 2. Competitive Advantage +Leading companies are adopting AI to accelerate development. Those who don't adopt will fall behind in productivity. + +### 3. Manageable Volume +With 5-10 issues/month, the risk is low and the environment is ideal to validate the solution before scaling. + +### 4. Accessible Cost +Operational cost is minimal (~$500/month) due to low volume. + +--- + +## How It Works + +### Simplified Flow + +``` +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ Support │ │ AI │ │ Dev │ +│ Case │────▶│ Analyzes │────▶│ Reviews │ +│ (JIRA) │ │ + Suggests │ │ + Approves │ +└──────────────┘ └──────────────┘ └──────────────┘ + 5min 5min 30min-2h + + ┌─────────────────────┐ + │ JIRA Comment: │ + │ - Root cause │ + │ - Affected files │ + │ - Proposed fix │ + │ - Link to PR │ + └─────────────────────┘ +``` + +### Real Example + +**Issue:** "Transaction being declined with code 51 even with available balance" + +**AI Response (in 5 minutes):** + +``` +📋 AUTOMATIC ANALYSIS + +🔍 Identified Cause: +The ACQAUTH.CBL program is comparing the WS-AVAILABLE-BALANCE field +with format PIC 9(9)V99, but the value returned from HOST uses +PIC 9(11)V99, causing truncation. + +📁 Affected File: +- src/cobol/ACQAUTH.CBL (lines 1234-1256) + +💡 Proposed Fix: +Change WS-AVAILABLE-BALANCE declaration to PIC 9(11)V99 +and adjust the comparison in SECTION 3000-VALIDATE. + +📊 Confidence: 87% + +🔗 PR with fix: bitbucket.tsacorp.com/projects/ACQ/repos/... +``` + +### Security: AI Does Not Alter Production Code + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ SEPARATION OF RESPONSIBILITIES │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ CLIENT Repository (production) │ +│ ACQ-MF-safra-fork │ +│ ├── AI has access: READ ONLY │ +│ └── Changes: ONLY by developers │ +│ │ +│ AI Repository (isolated) │ +│ ACQ-MF-safra-ai │ +│ ├── AI has access: READ AND WRITE │ +│ └── Purpose: Branches with fix suggestions │ +│ │ +│ Approval Flow: │ +│ 1. AI creates branch in isolated repository │ +│ 2. AI opens Pull Request to client repository │ +│ 3. HUMAN developer reviews │ +│ 4. HUMAN developer approves or rejects │ +│ 5. Only then code goes to production │ +│ │ +│ ✅ 100% of changes go through human review │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Investment + +### Development (MVP) + +| Item | Investment | +|------|------------| +| Development (4.5 months) | $70,000 - $90,000 | +| Initial infrastructure | $3,000 | +| **Total MVP** | **$73,000 - $93,000** | + +*Estimate considers dedicated team of 4-5 professionals.* + +### Monthly Operational Cost + +| Item | Cost/Month | +|------|------------| +| Artificial Intelligence APIs | $30 | +| Infrastructure (servers) | $200 - $500 | +| Maintenance (10% team) | $700 | +| **Total Operational** | **~$1,000/month** | + +*Low cost due to volume of 5-10 issues/month.* + +--- + +## Return on Investment (ROI) + +### Time Savings + +| Metric | Value | +|--------|-------| +| Issues per month | 5-10 | +| Current average time per issue | 8-14 hours | +| Average time with AI | 2-4 hours | +| **Savings per issue** | **6-10 hours** | +| **Monthly savings** | **30-100 hours of senior dev** | + +### Financial Calculation + +``` +Senior developer hourly cost: ~$40 +Monthly savings: 50 hours (average) +Value saved: $2,000/month + +MVP Investment: $80,000 (average) +Operational cost: $1,000/month + +Payback: ~40-48 months + +However, considering: +- Scale to more clients/products +- Reduction of bugs in production +- Freeing devs for innovation +- Knowledge retention + +Real ROI: Hard to quantify, but HIGHLY POSITIVE +``` + +### Intangible Benefits + +| Benefit | Impact | +|---------|--------| +| **Standardization** | All issues analyzed with same rigor | +| **Documentation** | Complete analysis history in JIRA | +| **Knowledge** | AI learns patterns, doesn't depend on people | +| **Speed** | Initial response in minutes, not hours | +| **Team morale** | Devs focus on complex problems, not repetitive ones | + +--- + +## Risks and Mitigations + +| Risk | Probability | Mitigation | +|------|-------------|------------| +| **AI suggests incorrect fix** | Medium | Mandatory human review in 100% of cases | +| **Team resistance** | Low | Position as assistant, not replacement | +| **Code security** | ✅ Eliminated | Azure OpenAI - data stays in Azure tenant, not used for training | +| **LLM cost increases** | Low | Enterprise Azure contract with fixed prices | + +### Compliance and Security + +The solution **exclusively uses Azure OpenAI**, ensuring: +- ✅ Code data is not sent to public APIs +- ✅ Data is not used to train Microsoft models +- ✅ Processing in Brazil South region (low latency) +- ✅ Compatible with ACI corporate policies +- ✅ Uses existing Enterprise Agreement contract + +**Note:** The existing GitHub Copilot will continue to be used by developers in the IDE. They are complementary tools - Copilot for code autocomplete, AI Fixer for automating issue analysis. + +### Conservative Approach + +The system will be implemented in phases: + +``` +Phase 1 (MVP): Analysis and suggestion only + AI comments in JIRA, doesn't create code + +Phase 2: Code generation in isolated repository + Human decides whether to use or not + +Phase 3: Automatic Pull Requests + Human still approves + +Phase 4: Auto-merge (only for high-confidence fixes) + Only after months of validation +``` + +--- + +## Timeline + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ MVP ROADMAP │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Month 1-2 Month 2-3 Month 3-4 Month 4-5 │ +│ ──────── ──────── ──────── ──────── │ +│ Setup + Code Fix Tests + │ +│ Integrations Indexing Generation Refinement │ +│ │ +│ ✓ JIRA ✓ COBOL ✓ LLM ✓ Pilot │ +│ ✓ Bitbucket ✓ SQL ✓ Validation ✓ Adjustments │ +│ ✓ Infra ✓ JCL ✓ Output ✓ Docs │ +│ │ +│ │ │ +│ ▼ │ +│ GO-LIVE │ +│ ~4.5 months │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Solution Differentiators + +### Why not use ready-made tools (GitHub Copilot, etc)? + +| Aspect | Generic Tools | Our Solution | +|--------|---------------|--------------| +| **JIRA Integration** | ❌ Manual | ✅ Automatic | +| **ACI system knowledge** | ❌ Generic | ✅ Trained with ACI rules | +| **COBOL expertise** | ⚠️ Limited | ✅ Optimized for mainframe | +| **Support Case flow** | ❌ Doesn't exist | ✅ Native | +| **Security (on-premise)** | ❌ Cloud only | ✅ 100% internal | +| **Customization** | ❌ Generic | ✅ Configurable rules | + +--- + +## Recommendation + +### Requested Decision + +Approve the development of the **ACI JIRA AI Fixer MVP** with: + +- **Investment:** $73,000 - $93,000 +- **Timeline:** 4.5 months +- **Scope:** ACQ-MF and ICG-MF products +- **Objective:** Reduce Support Case analysis time by 60%+ + +### Next Steps (after approval) + +1. **Week 1:** Define team and start infrastructure setup +2. **Week 2:** Create AI repositories and configure integrations +3. **Month 1:** First demonstration with real issue +4. **Month 3:** Functional MVP for pilot +5. **Month 5:** Go-live in production + +--- + +## Conclusion + +The **ACI JIRA AI Fixer** represents an opportunity to: + +✅ **Increase productivity** of support team by 60%+ +✅ **Reduce response time** from hours to minutes +✅ **Standardize quality** of analyses +✅ **Retain knowledge** independent of people +✅ **Position ACI** at the forefront of AI automation + +The timing is ideal: mature technology, controlled volume for pilot, and urgent team demand. + +--- + +**Document prepared for Executive presentation.** + +*For questions, the technical team is available for demonstration.* diff --git a/docs/aci-jira-ai-fixer-executivo.md b/docs/aci-jira-ai-fixer-executivo.md new file mode 100644 index 0000000..8652159 --- /dev/null +++ b/docs/aci-jira-ai-fixer-executivo.md @@ -0,0 +1,346 @@ +# ACI JIRA AI Fixer +## Proposta Executiva + +**Data:** 18 de Fevereiro de 2026 +**Versão:** 1.1 +**Atualização:** Azure OpenAI obrigatório para compliance +**Classificação:** Interno - Diretoria + +--- + +## Sumário Executivo + +### O Problema + +A equipe de suporte enfrenta desafios crescentes na resolução de Support Cases: + +| Desafio | Impacto | +|---------|---------| +| **Tempo de resposta** | Análise inicial consome horas de desenvolvedor sênior | +| **Backlog crescente** | Issues acumulam enquanto equipe foca em demandas urgentes | +| **Qualidade variável** | Dependência de conhecimento individual sobre o código | +| **Conhecimento concentrado** | Poucos especialistas conhecem todos os módulos | + +### A Solução + +Um sistema de **Inteligência Artificial** que: + +1. **Monitora** automaticamente novos Support Cases no JIRA +2. **Analisa** o problema e identifica o código-fonte afetado +3. **Propõe** correções específicas em COBOL, SQL e JCL +4. **Documenta** a análise diretamente no JIRA +5. **Cria** branches com correções para revisão humana + +### Resultado Esperado + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ANTES vs DEPOIS │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ANTES DEPOIS │ +│ ────── ────── │ +│ Issue criada Issue criada │ +│ ↓ ↓ │ +│ Dev analisa (2-4h) IA analisa (5min) │ +│ ↓ ↓ │ +│ Busca código (1-2h) Código identificado │ +│ ↓ ↓ │ +│ Investiga causa (2-4h) Causa + fix sugerido │ +│ ↓ ↓ │ +│ Desenvolve fix (2-4h) Dev revisa e aprova │ +│ ↓ ↓ │ +│ Review + deploy Review + deploy │ +│ │ +│ TOTAL: 8-14 horas TOTAL: 2-4 horas │ +│ │ +│ ✅ Redução de 60-70% no tempo de resolução │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## Por Que Agora? + +### 1. Tecnologia Madura +Os modelos de linguagem (GPT-4, Claude) atingiram nível de qualidade suficiente para análise e geração de código, incluindo linguagens legadas como COBOL. + +### 2. Vantagem Competitiva +Empresas líderes estão adotando IA para acelerar desenvolvimento. Quem não adotar ficará para trás em produtividade. + +### 3. Volume Gerenciável +Com 5-10 issues/mês, o risco é baixo e o ambiente é ideal para validar a solução antes de escalar. + +### 4. Custo Acessível +O custo operacional é mínimo (~R$2.500/mês) devido ao baixo volume. + +--- + +## Como Funciona + +### Fluxo Simplificado + +``` +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ Support │ │ IA │ │ Dev │ +│ Case │────▶│ Analisa │────▶│ Revisa │ +│ (JIRA) │ │ + Sugere │ │ + Aprova │ +└──────────────┘ └──────────────┘ └──────────────┘ + 5min 5min 30min-2h + + ┌─────────────────────┐ + │ Comentário JIRA: │ + │ - Causa raiz │ + │ - Arquivos afetados│ + │ - Correção proposta│ + │ - Link para PR │ + └─────────────────────┘ +``` + +### Exemplo Real + +**Issue:** "Transação sendo declinada com código 51 mesmo com saldo disponível" + +**Resposta da IA (em 5 minutos):** + +``` +📋 ANÁLISE AUTOMÁTICA + +🔍 Causa Identificada: +O programa ACQAUTH.CBL está comparando o campo WS-AVAILABLE-BALANCE +com formato PIC 9(9)V99, mas o valor retornado do HOST usa +PIC 9(11)V99, causando truncamento. + +📁 Arquivo Afetado: +- src/cobol/ACQAUTH.CBL (linhas 1234-1256) + +💡 Correção Proposta: +Alterar declaração de WS-AVAILABLE-BALANCE para PIC 9(11)V99 +e ajustar a comparação na SECTION 3000-VALIDATE. + +📊 Confiança: 87% + +🔗 PR com correção: bitbucket.tsacorp.com/projects/ACQ/repos/... +``` + +### Segurança: IA Não Altera Código de Produção + +``` +┌─────────────────────────────────────────────────────────────┐ +│ SEPARAÇÃO DE RESPONSABILIDADES │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ Repositório CLIENTE (produção) │ +│ ACQ-MF-safra-fork │ +│ ├── IA tem acesso: SOMENTE LEITURA │ +│ └── Alterações: APENAS por desenvolvedores │ +│ │ +│ Repositório IA (isolado) │ +│ ACQ-MF-safra-ai │ +│ ├── IA tem acesso: LEITURA E ESCRITA │ +│ └── Propósito: Branches com sugestões de correção │ +│ │ +│ Fluxo de Aprovação: │ +│ 1. IA cria branch no repositório isolado │ +│ 2. IA abre Pull Request para repositório cliente │ +│ 3. Desenvolvedor HUMANO revisa │ +│ 4. Desenvolvedor HUMANO aprova ou rejeita │ +│ 5. Só então o código vai para produção │ +│ │ +│ ✅ 100% das alterações passam por revisão humana │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## Investimento + +### Desenvolvimento (MVP) + +| Item | Investimento | +|------|--------------| +| Desenvolvimento (4.5 meses) | R$ 350.000 - R$ 450.000 | +| Infraestrutura inicial | R$ 15.000 | +| **Total MVP** | **R$ 365.000 - R$ 465.000** | + +*Estimativa considera equipe dedicada de 4-5 profissionais.* + +### Custo Operacional Mensal + +| Item | Custo/Mês | +|------|-----------| +| APIs de Inteligência Artificial | R$ 150 | +| Infraestrutura (servidores) | R$ 1.000 - R$ 2.500 | +| Manutenção (10% equipe) | R$ 3.500 | +| **Total Operacional** | **~R$ 5.000/mês** | + +*Custo baixo devido ao volume de 5-10 issues/mês.* + +--- + +## Retorno do Investimento (ROI) + +### Economia de Tempo + +| Métrica | Valor | +|---------|-------| +| Issues por mês | 5-10 | +| Tempo médio atual por issue | 8-14 horas | +| Tempo médio com IA | 2-4 horas | +| **Economia por issue** | **6-10 horas** | +| **Economia mensal** | **30-100 horas de dev sênior** | + +### Cálculo Financeiro + +``` +Custo hora desenvolvedor sênior: ~R$ 200 +Economia mensal: 50 horas (média) +Valor economizado: R$ 10.000/mês + +Investimento MVP: R$ 400.000 (média) +Custo operacional: R$ 5.000/mês + +Payback: ~40-48 meses + +Porém, considerando: +- Escala para mais clientes/produtos +- Redução de bugs em produção +- Liberação de devs para inovação +- Retenção de conhecimento + +ROI real: Difícil quantificar, mas ALTAMENTE POSITIVO +``` + +### Benefícios Intangíveis + +| Benefício | Impacto | +|-----------|---------| +| **Padronização** | Todas as issues analisadas com mesmo rigor | +| **Documentação** | Histórico completo de análises no JIRA | +| **Conhecimento** | IA aprende padrões, independe de pessoas | +| **Velocidade** | Resposta inicial em minutos, não horas | +| **Moral da equipe** | Devs focam em problemas complexos, não repetitivos | + +--- + +## Riscos e Mitigações + +| Risco | Probabilidade | Mitigação | +|-------|---------------|-----------| +| **IA sugere fix incorreto** | Média | Revisão humana obrigatória em 100% dos casos | +| **Resistência da equipe** | Baixa | Posicionar como assistente, não substituto | +| **Segurança do código** | ✅ Eliminado | Azure OpenAI - dados ficam no tenant Azure, não são usados para treino | +| **Custo de LLM aumenta** | Baixa | Contrato Enterprise Azure com preços fixos | + +### Compliance e Segurança + +A solução utiliza **exclusivamente Azure OpenAI**, garantindo: +- ✅ Dados de código não são enviados para APIs públicas +- ✅ Dados não são usados para treinar modelos Microsoft +- ✅ Processamento na região Brazil South (baixa latência) +- ✅ Compatível com políticas corporativas ACI +- ✅ Utiliza contrato Enterprise Agreement existente + +**Nota:** O GitHub Copilot existente continuará sendo usado pelos desenvolvedores no IDE. São ferramentas complementares - Copilot para autocompletar código, AI Fixer para automatizar análise de issues. + +### Abordagem Conservadora + +O sistema será implementado em fases: + +``` +Fase 1 (MVP): Apenas análise e sugestão + IA comenta no JIRA, não cria código + +Fase 2: Geração de código em repositório isolado + Humano decide se usa ou não + +Fase 3: Pull Requests automáticos + Humano ainda aprova + +Fase 4: Auto-merge (apenas para fixes de alta confiança) + Somente após meses de validação +``` + +--- + +## Timeline + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ROADMAP MVP │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ Mês 1-2 Mês 2-3 Mês 3-4 Mês 4-5 │ +│ ─────── ─────── ─────── ─────── │ +│ Setup + Indexação Geração de Testes + │ +│ Integrações de Código Correções Refinamento │ +│ │ +│ ✓ JIRA ✓ COBOL ✓ LLM ✓ Piloto │ +│ ✓ Bitbucket ✓ SQL ✓ Validação ✓ Ajustes │ +│ ✓ Infra ✓ JCL ✓ Output ✓ Docs │ +│ │ +│ │ │ +│ ▼ │ +│ GO-LIVE │ +│ ~4.5 meses │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## Diferenciais da Solução + +### Por que não usar ferramentas prontas (GitHub Copilot, etc)? + +| Aspecto | Ferramentas Genéricas | Nossa Solução | +|---------|----------------------|---------------| +| **Integração JIRA** | ❌ Manual | ✅ Automática | +| **Conhecimento do sistema ACI** | ❌ Genérico | ✅ Treinado com regras ACI | +| **COBOL expertise** | ⚠️ Limitado | ✅ Otimizado para mainframe | +| **Fluxo Support Case** | ❌ Não existe | ✅ Nativo | +| **Segurança (on-premise)** | ❌ Cloud only | ✅ 100% interno | +| **Customização** | ❌ Genérico | ✅ Regras configuráveis | + +--- + +## Recomendação + +### Decisão Solicitada + +Aprovar o desenvolvimento do **MVP do ACI JIRA AI Fixer** com: + +- **Investimento:** R$ 400.000 - R$ 465.000 +- **Timeline:** 4.5 meses +- **Escopo:** Produtos ACQ-MF e ICG-MF +- **Objetivo:** Reduzir tempo de análise de Support Cases em 60%+ + +### Próximos Passos (após aprovação) + +1. **Semana 1:** Definir equipe e iniciar setup de infraestrutura +2. **Semana 2:** Criar repositórios AI e configurar integrações +3. **Mês 1:** Primeira demonstração com issue real +4. **Mês 3:** MVP funcional para piloto +5. **Mês 5:** Go-live em produção + +--- + +## Conclusão + +O **ACI JIRA AI Fixer** representa uma oportunidade de: + +✅ **Aumentar produtividade** da equipe de suporte em 60%+ +✅ **Reduzir tempo de resposta** de horas para minutos +✅ **Padronizar qualidade** das análises +✅ **Reter conhecimento** independente de pessoas +✅ **Posicionar a ACI** na vanguarda de automação com IA + +O momento é ideal: tecnologia madura, volume controlado para piloto, e demanda urgente da equipe. + +--- + +**Documento preparado para apresentação à Diretoria.** + +*Em caso de dúvidas, a equipe técnica está disponível para demonstração.* diff --git a/docs/aci-jira-ai-fixer-portal-en.md b/docs/aci-jira-ai-fixer-portal-en.md new file mode 100644 index 0000000..32847bc --- /dev/null +++ b/docs/aci-jira-ai-fixer-portal-en.md @@ -0,0 +1,558 @@ +# ACI JIRA AI Fixer - Admin Portal + +**Version:** 1.0 +**Date:** 2026-02-18 +**Classification:** Internal - Product Vision + +--- + +## 1. Overview + +The ACI JIRA AI Fixer Admin Portal is a modern, intuitive web interface that allows managing all system configurations without the need to modify code or configuration files manually. + +### 1.1 Objectives + +- **Zero code** for configuration +- **Intuitive interface** for medium/large enterprises +- **Multi-tenant** to support multiple teams +- **Complete auditing** of all actions +- **Integrated SSO** with corporate providers + +--- + +## 2. Portal Screens + +### 2.1 Main Dashboard + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 🤖 ACI AI Fixer admin@aci.com ⚙️ 🔔 │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │Dashboard│ │ Issues │ │ Code │ │ Config │ │ Logs │ │ +│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ 📊 DASHBOARD │ │ +│ │ │ │ +│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ +│ │ │ 12 │ │ 78% │ │ 2.3min │ │ │ +│ │ │ Issues/month │ │ Success Rate │ │ Avg Time │ │ │ +│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ +│ │ │ │ +│ │ 📈 Last 30 days │ │ +│ │ ████████████████████░░░░░░ 78% fixes accepted │ │ +│ │ │ │ +│ │ ┌─ Recent Activity ───────────────────────────────────────────┐ │ │ +│ │ │ ✅ SUPPORT-4521 - Fix accepted 2 hours ago │ │ │ +│ │ │ ⏳ SUPPORT-4519 - Awaiting review 5 hours ago │ │ │ +│ │ │ ❌ SUPPORT-4515 - Fix rejected 1 day ago │ │ │ +│ │ └─────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +**Displayed metrics:** +- Issues processed (day/week/month) +- Success rate (accepted vs rejected fixes) +- Average analysis time +- Trend chart +- Recent activity + +--- + +### 2.2 Settings - Integrations + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ ⚙️ SETTINGS > Integrations │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─ JIRA ────────────────────────────────────────────────────────────────┐ │ +│ │ ✅ Connected │ │ +│ │ │ │ +│ │ Server URL │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ https://gojira.tsacorp.com │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ API Token │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ •••••••••••••••••••••••••••••••• 👁️ │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ Webhook URL (copy and configure in JIRA) │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ https://ai-fixer.aci.com/api/webhook/jira 📋 │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ Monitored Projects │ │ +│ │ ☑️ ACQ - Acquirer ☑️ ICG - Interchange ☐ CORE - Core System │ │ +│ │ │ │ +│ │ [ 🔄 Test Connection ] │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Bitbucket ───────────────────────────────────────────────────────────┐ │ +│ │ ✅ Connected │ │ +│ │ │ │ +│ │ Server URL │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ https://bitbucket.tsacorp.com │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ Access Token │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ •••••••••••••••••••••••••••••••• 👁️ │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ [ 🔄 Test Connection ] │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ LLM Provider ────────────────────────────────────────────────────────┐ │ +│ │ ✅ Azure OpenAI │ │ +│ │ │ │ +│ │ Provider │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ Azure OpenAI ▼ │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ Options: Azure OpenAI | OpenAI | OpenRouter (Free) | Self-hosted │ │ +│ │ │ │ +│ │ Endpoint │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ https://aci-openai.openai.azure.com │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ API Key │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ •••••••••••••••••••••••••••••••• 👁️ │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ Model │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ gpt-4o ▼ │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ [ 🔄 Test Connection ] │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Embeddings ──────────────────────────────────────────────────────────┐ │ +│ │ ✅ Self-hosted │ │ +│ │ │ │ +│ │ Provider │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ Self-hosted (MiniLM-L6) ▼ │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ Options: Self-hosted | Azure OpenAI | OpenAI │ │ +│ │ │ │ +│ │ ℹ️ For production, we recommend Azure OpenAI for compliance. │ │ +│ │ │ │ +│ │ [ 🔄 Test Connection ] │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ [ 💾 Save All ] │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +### 2.3 Repository Management + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 📁 REPOSITORIES [ + Add New ] │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌───────────────────────────────────────────────────────────────────────┐ │ +│ │ 📦 ACQ-MF-safra-fork [ ⚙️ ] [ 🗑️ ]│ │ +│ │ │ │ +│ │ URL: bitbucket.tsacorp.com/projects/ACQ/repos/ACQ-MF-safra-fork │ │ +│ │ │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ Status │ ✅ Indexed │ │ │ +│ │ │ Files │ 2,847 files indexed │ │ │ +│ │ │ Last Sync │ 02/18/2026 11:30 │ │ │ +│ │ │ AI Fork │ ACQ-MF-safra-ai ✅ │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ Detected languages: │ │ +│ │ ████████████████████░░░░░░░░░░ COBOL 68% │ │ +│ │ ██████░░░░░░░░░░░░░░░░░░░░░░░░ SQL 22% │ │ +│ │ ███░░░░░░░░░░░░░░░░░░░░░░░░░░░ JCL 10% │ │ +│ │ │ │ +│ │ [ 🔄 Re-index Now ] [ 📊 View Details ] [ ⏰ Schedule Sync ] │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌───────────────────────────────────────────────────────────────────────┐ │ +│ │ 📦 ICG-MF-safra-fork [ ⚙️ ] [ 🗑️ ]│ │ +│ │ │ │ +│ │ URL: bitbucket.tsacorp.com/projects/ICG/repos/ICG-MF-safra-fork │ │ +│ │ │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ Status │ ✅ Indexed │ │ │ +│ │ │ Files │ 1,923 files indexed │ │ │ +│ │ │ Last Sync │ 02/18/2026 11:30 │ │ │ +│ │ │ AI Fork │ ICG-MF-safra-ai ✅ │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ [ 🔄 Re-index Now ] [ 📊 View Details ] [ ⏰ Schedule Sync ] │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +### 2.4 Business Rules Editor + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 🧠 BUSINESS RULES [ + New Module ] │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Configured modules: │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │ Author. │ │Clearing │ │HostComm │ │ Batch │ │ +│ │ ● │ │ │ │ │ │ │ │ +│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ +│ │ +│ ═══════════════════════════════════════════════════════════════════════ │ +│ │ +│ 📌 Module: Authorization │ +│ │ +│ ┌─ Description ─────────────────────────────────────────────────────────┐ │ +│ │ Card transaction authorization module. Responsible for validation, │ │ +│ │ HOST communication, and response generation. │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Related Programs ────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ +│ │ │ ACQAUTH* ✕ │ │ ACQVALD* ✕ │ │ ACQHOST* ✕ │ [ + Add ] │ │ +│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ +│ │ │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Detection Keywords ──────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ ┌──────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ +│ │ │authorization✕│ │ decline ✕ │ │ code 51 ✕ │ │ timeout ✕ │ [+] │ │ +│ │ └──────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │ +│ │ │ │ +│ │ ℹ️ When an issue contains these words, the system automatically │ │ +│ │ associates it with the Authorization module. │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Context Rules (instructions for AI) ─────────────────────────────────┐ │ +│ │ │ │ +│ │ 📋 Rule 1 [ ✏️ ] [ 🗑️ ]│ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ Transactions above $10,000 require additional validation in │ │ │ +│ │ │ program ACQVALD through SECTION 5000-VALIDATE-HIGH-VALUE │ │ │ +│ │ │ before sending to HOST. │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ 📋 Rule 2 [ ✏️ ] [ 🗑️ ]│ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ Response codes follow ISO 8583 standard: │ │ │ +│ │ │ - 00: Approved │ │ │ +│ │ │ - 51: Insufficient funds (check WS-AVAILABLE-BALANCE) │ │ │ +│ │ │ - 14: Invalid card │ │ │ +│ │ │ - 91: Issuer unavailable │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ 📋 Rule 3 [ ✏️ ] [ 🗑️ ]│ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ WS-AVAILABLE-BALANCE field must have PIC 9(11)V99 for │ │ │ +│ │ │ compatibility with HOST return. Check for truncation in │ │ │ +│ │ │ comparisons. │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ [ + Add New Rule ] │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Restrictions (files AI cannot modify) ───────────────────────────────┐ │ +│ │ │ │ +│ │ ┌────────────────┐ ┌──────────────────┐ │ │ +│ │ │ /interfaces/* ✕│ │ /copybooks/HOST* ✕│ [ + Add ] │ │ +│ │ └────────────────┘ └──────────────────┘ │ │ +│ │ │ │ +│ │ ⚠️ Files in these folders will only be analyzed, never modified. │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ [ Cancel ] [ 💾 Save Module ] │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +### 2.5 Issues View + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 📋 ANALYZED ISSUES │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ 🔍 Search... Status: [ All ▼ ] [ 📅 Period ] │ +│ │ +│ ┌───────────────────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ ┌─ SUPPORT-4521 ──────────────────────────────────────────────────┐ │ │ +│ │ │ │ │ │ +│ │ │ Transaction declined code 51 with available balance │ │ │ +│ │ │ │ │ │ +│ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ +│ │ │ │ ✅ Accepted│ │ 🎯 87% │ │ ⏱️ 2m 34s │ │ 📁 1 file │ │ │ │ +│ │ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │ │ +│ │ │ │ │ │ +│ │ │ Module: Authorization Created: 02/18/2026 09:15 │ │ │ +│ │ │ │ │ │ +│ │ │ [ 👁️ View Full Analysis ] [ 📝 View PR ] [ 🔗 Open JIRA ] │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ┌─ SUPPORT-4519 ──────────────────────────────────────────────────┐ │ │ +│ │ │ │ │ │ +│ │ │ Formatting error in clearing file │ │ │ +│ │ │ │ │ │ +│ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ +│ │ │ │ ⏳ Review │ │ 🎯 72% │ │ ⏱️ 3m 12s │ │ 📁 2 files │ │ │ │ +│ │ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │ │ +│ │ │ │ │ │ +│ │ │ Module: Clearing Created: 02/18/2026 06:45 │ │ │ +│ │ │ │ │ │ +│ │ │ [ 👁️ View Full Analysis ] [ 📝 View PR ] [ 🔗 Open JIRA ] │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ┌─ SUPPORT-4515 ──────────────────────────────────────────────────┐ │ │ +│ │ │ │ │ │ +│ │ │ JCL failing with return code 12 │ │ │ +│ │ │ │ │ │ +│ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ +│ │ │ │ ❌ Rejected│ │ 🎯 45% │ │ ⏱️ 4m 01s │ │ 📁 1 file │ │ │ │ +│ │ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │ │ +│ │ │ │ │ │ +│ │ │ Reason: "Incorrect dataset analysis PROD.CLEARING.INPUT" │ │ │ +│ │ │ │ │ │ +│ │ │ [ 👁️ View Analysis ] [ 🔄 Re-analyze ] [ 🔗 Open JIRA ] │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Showing 1-10 of 47 issues [ ← Previous ] [ Next → ] │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +### 2.6 Analysis Details + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 👁️ ANALYSIS: SUPPORT-4521 [ ← Back ]│ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─ Issue Information ───────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ Title: Transaction declined code 51 with available balance │ │ +│ │ Status: ✅ Fix Accepted │ │ +│ │ Confidence: 87% │ │ +│ │ Analysis time: 2 minutes 34 seconds │ │ +│ │ Analyzed at: 02/18/2026 09:17:34 │ │ +│ │ │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Original Description ────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ Safra client reports that transactions are being declined with │ │ +│ │ code 51 (insufficient funds) even when the customer has available │ │ +│ │ balance. Occurs on transactions above $100,000.00. │ │ +│ │ │ │ +│ │ Stack trace: │ │ +│ │ ACQAUTH - SECTION 3000-VALIDATE - EVALUATE WS-RESPONSE-CODE │ │ +│ │ │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ AI Analysis ─────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ 🔍 IDENTIFIED ROOT CAUSE │ │ +│ │ │ │ +│ │ The ACQAUTH.CBL program is comparing the WS-AVAILABLE-BALANCE │ │ +│ │ field with format PIC 9(9)V99 (maximum 9,999,999.99), but the │ │ +│ │ value returned from HOST uses PIC 9(11)V99 (max 999,999,999.99). │ │ +│ │ │ │ +│ │ This causes truncation on values above $100,000.00, │ │ +│ │ making the balance appear as insufficient. │ │ +│ │ │ │ +│ │ 📁 AFFECTED FILES │ │ +│ │ • src/cobol/ACQAUTH.CBL (lines 1234-1256) │ │ +│ │ │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Proposed Fix ────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ ```cobol │ │ +│ │ * BEFORE (line 1234) │ │ +│ │ 05 WS-AVAILABLE-BALANCE PIC 9(9)V99. │ │ +│ │ │ │ +│ │ * AFTER │ │ +│ │ 05 WS-AVAILABLE-BALANCE PIC 9(11)V99. │ │ +│ │ ``` │ │ +│ │ │ │ +│ │ Also adjust SECTION 3000-VALIDATE to use the new size. │ │ +│ │ │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Links ───────────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ 🔗 Issue in JIRA: gojira.tsacorp.com/browse/SUPPORT-4521 │ │ +│ │ 📝 Pull Request: bitbucket.tsacorp.com/.../pull-requests/142 │ │ +│ │ 💬 AI Comment: View in JIRA │ │ +│ │ │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ [ 🔄 Re-analyze ] [ 📥 Export PDF ] │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 3. Portal Technology Stack + +### 3.1 Frontend +```yaml +Framework: React 18 + TypeScript +Styling: Tailwind CSS + shadcn/ui +Components: + - Tables with sorting and filters + - Forms with validation + - Charts (Recharts) + - Code editor (Monaco Editor) + - Toast notifications +State Management: React Query + Zustand +Routing: React Router v6 +Build: Vite +``` + +### 3.2 Backend (API) +```yaml +Framework: FastAPI (Python 3.11+) +Documentation: Automatic OpenAPI/Swagger +Authentication: JWT + OAuth2/OIDC +Rate Limiting: slowapi +Validation: Pydantic v2 +``` + +### 3.3 Database +```yaml +Primary: PostgreSQL 15+ +Cache: Redis 7+ +Vector DB: Qdrant (embeddings) +Migrations: Alembic +``` + +### 3.4 Authentication +```yaml +Supported options: + - Azure AD (SAML/OIDC) + - Okta + - Google Workspace + - Email/Password with MFA (TOTP) + +Permissions (RBAC): + - Admin: Full access + - Editor: Configure rules, view everything + - Viewer: View only + - API: Programmatic access only +``` + +--- + +## 4. Configuration Simplicity + +| Action | Method | Time | +|--------|--------|------| +| Connect JIRA | Paste URL + Token | 2 minutes | +| Connect Bitbucket | Paste URL + Token | 2 minutes | +| Change LLM provider | Select from dropdown | 30 seconds | +| Add repository | Paste URL + Configure AI fork | 5 minutes | +| Create business rule | Visual editor | 5-10 minutes | +| Add restriction | Type path | 30 seconds | +| View logs | Click on tab | Immediate | +| Export report | "Export" button | Immediate | + +**Principle: Zero code for any configuration.** + +--- + +## 5. Multi-Tenant (Multiple Companies) + +The portal supports multiple isolated tenants: + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ MULTI-TENANT ARCHITECTURE │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Tenant: ACI Safra Tenant: ACI Itaú │ +│ ┌─────────────────────────┐ ┌─────────────────────────┐ │ +│ │ - Safra Repos │ │ - Itaú Repos │ │ +│ │ - Safra Rules │ │ - Itaú Rules │ │ +│ │ - Safra Users │ │ - Itaú Users │ │ +│ │ - Isolated Logs │ │ - Isolated Logs │ │ +│ └─────────────────────────┘ └─────────────────────────┘ │ +│ │ │ │ +│ └────────────────┬───────────────────┘ │ +│ │ │ +│ ┌──────────▼──────────┐ │ +│ │ Shared │ │ +│ │ Infrastructure │ │ +│ │ (LLM, Embeddings) │ │ +│ └─────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +**Guaranteed isolation:** +- Data from one tenant never visible to another +- Independent configurations +- Separate billing (if applicable) +- Audit logs per tenant + +--- + +## 6. Responsiveness + +The portal is responsive and works on: + +| Device | Support | +|--------|---------| +| Desktop (1920px+) | ✅ Optimized | +| Laptop (1366px) | ✅ Optimized | +| Tablet (768px) | ✅ Adapted | +| Mobile (375px) | ⚠️ View only | + +--- + +## 7. Accessibility + +- Full keyboard navigation +- Screen reader compatible (ARIA) +- Adequate contrast (WCAG 2.1 AA) +- Resizable text + +--- + +## 8. Roadmap + +1. **Phase 1:** Basic portal with Dashboard and Settings +2. **Phase 2:** Business rules editor +3. **Phase 3:** Multi-tenant and SSO +4. **Phase 4:** Advanced reports and export +5. **Phase 5:** Public API for integrations + +--- + +**Document prepared for product presentation.** diff --git a/docs/aci-jira-ai-fixer-portal.md b/docs/aci-jira-ai-fixer-portal.md new file mode 100644 index 0000000..76762d1 --- /dev/null +++ b/docs/aci-jira-ai-fixer-portal.md @@ -0,0 +1,558 @@ +# ACI JIRA AI Fixer - Portal Administrativo + +**Versão:** 1.0 +**Data:** 2026-02-18 +**Classificação:** Interno - Visão de Produto + +--- + +## 1. Visão Geral + +O Portal Administrativo do ACI JIRA AI Fixer é uma interface web moderna e intuitiva que permite gerenciar todas as configurações do sistema sem necessidade de alterar código ou arquivos de configuração manualmente. + +### 1.1 Objetivos + +- **Zero código** para configuração +- **Interface intuitiva** para empresas de médio/grande porte +- **Multi-tenant** para suportar múltiplas equipes +- **Auditoria completa** de todas as ações +- **SSO integrado** com provedores corporativos + +--- + +## 2. Telas do Portal + +### 2.1 Dashboard Principal + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 🤖 ACI AI Fixer admin@aci.com ⚙️ 🔔 │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │Dashboard│ │ Issues │ │ Código │ │ Config │ │ Logs │ │ +│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ 📊 DASHBOARD │ │ +│ │ │ │ +│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ +│ │ │ 12 │ │ 78% │ │ 2.3min │ │ │ +│ │ │ Issues/mês │ │ Taxa Acerto │ │ Tempo Médio │ │ │ +│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ +│ │ │ │ +│ │ 📈 Últimos 30 dias │ │ +│ │ ████████████████████░░░░░░ 78% fixes aceitos │ │ +│ │ │ │ +│ │ ┌─ Atividade Recente ─────────────────────────────────────────┐ │ │ +│ │ │ ✅ SUPPORT-4521 - Fix aceito há 2 horas │ │ │ +│ │ │ ⏳ SUPPORT-4519 - Aguardando review há 5 horas │ │ │ +│ │ │ ❌ SUPPORT-4515 - Fix rejeitado há 1 dia │ │ │ +│ │ └─────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +**Métricas exibidas:** +- Issues processadas (dia/semana/mês) +- Taxa de acerto (fixes aceitos vs rejeitados) +- Tempo médio de análise +- Gráfico de tendência +- Atividade recente + +--- + +### 2.2 Configurações - Integrações + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ ⚙️ CONFIGURAÇÕES > Integrações │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─ JIRA ────────────────────────────────────────────────────────────────┐ │ +│ │ ✅ Conectado │ │ +│ │ │ │ +│ │ URL do Servidor │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ https://gojira.tsacorp.com │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ API Token │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ •••••••••••••••••••••••••••••••• 👁️ │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ Webhook URL (copie e configure no JIRA) │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ https://ai-fixer.aci.com/api/webhook/jira 📋 │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ Projetos Monitorados │ │ +│ │ ☑️ ACQ - Acquirer ☑️ ICG - Interchange ☐ CORE - Core System │ │ +│ │ │ │ +│ │ [ 🔄 Testar Conexão ] │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Bitbucket ───────────────────────────────────────────────────────────┐ │ +│ │ ✅ Conectado │ │ +│ │ │ │ +│ │ URL do Servidor │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ https://bitbucket.tsacorp.com │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ Access Token │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ •••••••••••••••••••••••••••••••• 👁️ │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ [ 🔄 Testar Conexão ] │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ LLM Provider ────────────────────────────────────────────────────────┐ │ +│ │ ✅ Azure OpenAI │ │ +│ │ │ │ +│ │ Provedor │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ Azure OpenAI ▼ │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ Opções: Azure OpenAI | OpenAI | OpenRouter (Free) | Self-hosted │ │ +│ │ │ │ +│ │ Endpoint │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ https://aci-openai.openai.azure.com │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ API Key │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ •••••••••••••••••••••••••••••••• 👁️ │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ Modelo │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ gpt-4o ▼ │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ [ 🔄 Testar Conexão ] │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Embeddings ──────────────────────────────────────────────────────────┐ │ +│ │ ✅ Self-hosted │ │ +│ │ │ │ +│ │ Provedor │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ Self-hosted (MiniLM-L6) ▼ │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ Opções: Self-hosted | Azure OpenAI | OpenAI │ │ +│ │ │ │ +│ │ ℹ️ Para produção, recomendamos Azure OpenAI para compliance. │ │ +│ │ │ │ +│ │ [ 🔄 Testar Conexão ] │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ [ 💾 Salvar Tudo ] │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +### 2.3 Gerenciamento de Repositórios + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 📁 REPOSITÓRIOS [ + Adicionar ] │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌───────────────────────────────────────────────────────────────────────┐ │ +│ │ 📦 ACQ-MF-safra-fork [ ⚙️ ] [ 🗑️ ]│ │ +│ │ │ │ +│ │ URL: bitbucket.tsacorp.com/projects/ACQ/repos/ACQ-MF-safra-fork │ │ +│ │ │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ Status │ ✅ Indexado │ │ │ +│ │ │ Arquivos │ 2.847 arquivos indexados │ │ │ +│ │ │ Última Sync │ 18/02/2026 11:30 │ │ │ +│ │ │ Fork AI │ ACQ-MF-safra-ai ✅ │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ Linguagens detectadas: │ │ +│ │ ████████████████████░░░░░░░░░░ COBOL 68% │ │ +│ │ ██████░░░░░░░░░░░░░░░░░░░░░░░░ SQL 22% │ │ +│ │ ███░░░░░░░░░░░░░░░░░░░░░░░░░░░ JCL 10% │ │ +│ │ │ │ +│ │ [ 🔄 Re-indexar Agora ] [ 📊 Ver Detalhes ] [ ⏰ Agendar Sync ] │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌───────────────────────────────────────────────────────────────────────┐ │ +│ │ 📦 ICG-MF-safra-fork [ ⚙️ ] [ 🗑️ ]│ │ +│ │ │ │ +│ │ URL: bitbucket.tsacorp.com/projects/ICG/repos/ICG-MF-safra-fork │ │ +│ │ │ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ Status │ ✅ Indexado │ │ │ +│ │ │ Arquivos │ 1.923 arquivos indexados │ │ │ +│ │ │ Última Sync │ 18/02/2026 11:30 │ │ │ +│ │ │ Fork AI │ ICG-MF-safra-ai ✅ │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ [ 🔄 Re-indexar Agora ] [ 📊 Ver Detalhes ] [ ⏰ Agendar Sync ] │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +### 2.4 Editor de Regras de Negócio + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 🧠 REGRAS DE NEGÓCIO [ + Novo Módulo ] │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Módulos configurados: │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │Autoriz. │ │Clearing │ │HostComm │ │ Batch │ │ +│ │ ● │ │ │ │ │ │ │ │ +│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ +│ │ +│ ═══════════════════════════════════════════════════════════════════════ │ +│ │ +│ 📌 Módulo: Autorização │ +│ │ +│ ┌─ Descrição ───────────────────────────────────────────────────────────┐ │ +│ │ Módulo de autorização de transações de cartão. Responsável pela │ │ +│ │ validação, comunicação com HOST e geração de resposta. │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Programas Relacionados ──────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ +│ │ │ ACQAUTH* ✕ │ │ ACQVALD* ✕ │ │ ACQHOST* ✕ │ [ + Adicionar ]│ │ +│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ +│ │ │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Keywords de Detecção ────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ +│ │ │autorização✕│ │ decline ✕ │ │código 51 ✕ │ │ timeout ✕ │ [+Add] │ │ +│ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │ +│ │ │ │ +│ │ ℹ️ Quando uma issue contém essas palavras, o sistema associa │ │ +│ │ automaticamente ao módulo de Autorização. │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Regras de Contexto (instruções para a IA) ───────────────────────────┐ │ +│ │ │ │ +│ │ 📋 Regra 1 [ ✏️ ] [ 🗑️ ]│ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ Transações acima de R$ 10.000 requerem validação adicional no │ │ │ +│ │ │ programa ACQVALD através da SECTION 5000-VALIDATE-HIGH-VALUE │ │ │ +│ │ │ antes de enviar ao HOST. │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ 📋 Regra 2 [ ✏️ ] [ 🗑️ ]│ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ Códigos de resposta seguem padrão ISO 8583: │ │ │ +│ │ │ - 00: Aprovada │ │ │ +│ │ │ - 51: Saldo insuficiente (verificar WS-AVAILABLE-BALANCE) │ │ │ +│ │ │ - 14: Cartão inválido │ │ │ +│ │ │ - 91: Emissor indisponível │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ 📋 Regra 3 [ ✏️ ] [ 🗑️ ]│ │ +│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ O campo WS-AVAILABLE-BALANCE deve ter PIC 9(11)V99 para │ │ │ +│ │ │ compatibilidade com o retorno do HOST. Verificar se não há │ │ │ +│ │ │ truncamento em comparações. │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ [ + Adicionar Nova Regra ] │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Restrições (arquivos que a IA NÃO pode alterar) ─────────────────────┐ │ +│ │ │ │ +│ │ ┌────────────────┐ ┌────────────────┐ │ │ +│ │ │ /interfaces/* ✕│ │ /copybooks/HOST* ✕│ [ + Adicionar ]│ │ +│ │ └────────────────┘ └────────────────┘ │ │ +│ │ │ │ +│ │ ⚠️ Arquivos nestas pastas serão apenas analisados, nunca alterados. │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ [ Cancelar ] [ 💾 Salvar Módulo ] │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +### 2.5 Visualização de Issues + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 📋 ISSUES ANALISADAS │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ 🔍 Buscar... Status: [ Todos ▼ ] [ 📅 Período ] │ +│ │ +│ ┌───────────────────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ ┌─ SUPPORT-4521 ──────────────────────────────────────────────────┐ │ │ +│ │ │ │ │ │ +│ │ │ Transação declinada código 51 com saldo disponível │ │ │ +│ │ │ │ │ │ +│ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ +│ │ │ │ ✅ Aceito │ │ 🎯 87% │ │ ⏱️ 2m 34s │ │ 📁 1 arquivo│ │ │ │ +│ │ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │ │ +│ │ │ │ │ │ +│ │ │ Módulo: Autorização Criado: 18/02/2026 09:15 │ │ │ +│ │ │ │ │ │ +│ │ │ [ 👁️ Ver Análise Completa ] [ 📝 Ver PR ] [ 🔗 Abrir JIRA ] │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ┌─ SUPPORT-4519 ──────────────────────────────────────────────────┐ │ │ +│ │ │ │ │ │ +│ │ │ Erro de formatação no arquivo de clearing │ │ │ +│ │ │ │ │ │ +│ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ +│ │ │ │ ⏳ Review │ │ 🎯 72% │ │ ⏱️ 3m 12s │ │ 📁 2 arquivos│ │ │ │ +│ │ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │ │ +│ │ │ │ │ │ +│ │ │ Módulo: Clearing Criado: 18/02/2026 06:45 │ │ │ +│ │ │ │ │ │ +│ │ │ [ 👁️ Ver Análise Completa ] [ 📝 Ver PR ] [ 🔗 Abrir JIRA ] │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ┌─ SUPPORT-4515 ──────────────────────────────────────────────────┐ │ │ +│ │ │ │ │ │ +│ │ │ JCL falhando com código de retorno 12 │ │ │ +│ │ │ │ │ │ +│ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ +│ │ │ │ ❌ Rejeitado│ │ 🎯 45% │ │ ⏱️ 4m 01s │ │ 📁 1 arquivo│ │ │ │ +│ │ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │ │ +│ │ │ │ │ │ +│ │ │ Motivo: "Análise incorreta do dataset PROD.CLEARING.INPUT" │ │ │ +│ │ │ │ │ │ +│ │ │ [ 👁️ Ver Análise ] [ 🔄 Re-analisar ] [ 🔗 Abrir JIRA ] │ │ │ +│ │ └─────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Mostrando 1-10 de 47 issues [ ← Anterior ] [ Próximo → ] │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +### 2.6 Detalhes da Análise + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 👁️ ANÁLISE: SUPPORT-4521 [ ← Voltar]│ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─ Informações da Issue ────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ Título: Transação declinada código 51 com saldo disponível │ │ +│ │ Status: ✅ Fix Aceito │ │ +│ │ Confiança: 87% │ │ +│ │ Tempo de análise: 2 minutos 34 segundos │ │ +│ │ Analisado em: 18/02/2026 09:17:34 │ │ +│ │ │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Descrição Original ──────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ Cliente Safra reporta que transações estão sendo declinadas com │ │ +│ │ código 51 (saldo insuficiente) mesmo quando o cliente possui saldo │ │ +│ │ disponível. Ocorre em transações acima de R$ 100.000,00. │ │ +│ │ │ │ +│ │ Stack trace: │ │ +│ │ ACQAUTH - SECTION 3000-VALIDATE - EVALUATE WS-RESPONSE-CODE │ │ +│ │ │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Análise da IA ───────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ 🔍 CAUSA RAIZ IDENTIFICADA │ │ +│ │ │ │ +│ │ O programa ACQAUTH.CBL está comparando o campo WS-AVAILABLE-BALANCE │ │ +│ │ com formato PIC 9(9)V99 (máximo 9.999.999,99), mas o valor │ │ +│ │ retornado do HOST usa PIC 9(11)V99 (máximo 999.999.999,99). │ │ +│ │ │ │ +│ │ Isso causa truncamento em valores acima de R$ 100.000,00, │ │ +│ │ fazendo com que o saldo apareça como insuficiente. │ │ +│ │ │ │ +│ │ 📁 ARQUIVOS AFETADOS │ │ +│ │ • src/cobol/ACQAUTH.CBL (linhas 1234-1256) │ │ +│ │ │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Correção Proposta ───────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ ```cobol │ │ +│ │ * ANTES (linha 1234) │ │ +│ │ 05 WS-AVAILABLE-BALANCE PIC 9(9)V99. │ │ +│ │ │ │ +│ │ * DEPOIS │ │ +│ │ 05 WS-AVAILABLE-BALANCE PIC 9(11)V99. │ │ +│ │ ``` │ │ +│ │ │ │ +│ │ Também ajustar a SECTION 3000-VALIDATE para usar o novo tamanho. │ │ +│ │ │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ Links ───────────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ 🔗 Issue no JIRA: gojira.tsacorp.com/browse/SUPPORT-4521 │ │ +│ │ 📝 Pull Request: bitbucket.tsacorp.com/.../pull-requests/142 │ │ +│ │ 💬 Comentário IA: Ver no JIRA │ │ +│ │ │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ [ 🔄 Re-analisar ] [ 📥 Exportar PDF ] │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 3. Stack Tecnológico do Portal + +### 3.1 Frontend +```yaml +Framework: React 18 + TypeScript +Estilização: Tailwind CSS + shadcn/ui +Componentes: + - Tabelas com ordenação e filtros + - Formulários com validação + - Gráficos (Recharts) + - Editor de código (Monaco Editor) + - Notificações toast +State Management: React Query + Zustand +Roteamento: React Router v6 +Build: Vite +``` + +### 3.2 Backend (API) +```yaml +Framework: FastAPI (Python 3.11+) +Documentação: OpenAPI/Swagger automático +Autenticação: JWT + OAuth2/OIDC +Rate Limiting: slowapi +Validação: Pydantic v2 +``` + +### 3.3 Banco de Dados +```yaml +Principal: PostgreSQL 15+ +Cache: Redis 7+ +Vector DB: Qdrant (embeddings) +Migrations: Alembic +``` + +### 3.4 Autenticação +```yaml +Opções suportadas: + - Azure AD (SAML/OIDC) + - Okta + - Google Workspace + - Email/Senha com MFA (TOTP) + +Permissões (RBAC): + - Admin: Acesso total + - Editor: Configura regras, visualiza tudo + - Viewer: Apenas visualização + - API: Apenas acesso programático +``` + +--- + +## 4. Facilidade de Configuração + +| Ação | Método | Tempo | +|------|--------|-------| +| Conectar JIRA | Colar URL + Token | 2 minutos | +| Conectar Bitbucket | Colar URL + Token | 2 minutos | +| Trocar provedor LLM | Selecionar no dropdown | 30 segundos | +| Adicionar repositório | Colar URL + Configurar fork AI | 5 minutos | +| Criar regra de negócio | Editor visual | 5-10 minutos | +| Adicionar restrição | Digitar path | 30 segundos | +| Ver logs | Clicar na aba | Imediato | +| Exportar relatório | Botão "Exportar" | Imediato | + +**Princípio: Zero código para qualquer configuração.** + +--- + +## 5. Multi-Tenant (Múltiplas Empresas) + +O portal suporta múltiplos tenants isolados: + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ ARQUITETURA MULTI-TENANT │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Tenant: ACI Safra Tenant: ACI Itaú │ +│ ┌─────────────────────────┐ ┌─────────────────────────┐ │ +│ │ - Repos Safra │ │ - Repos Itaú │ │ +│ │ - Regras Safra │ │ - Regras Itaú │ │ +│ │ - Usuários Safra │ │ - Usuários Itaú │ │ +│ │ - Logs isolados │ │ - Logs isolados │ │ +│ └─────────────────────────┘ └─────────────────────────┘ │ +│ │ │ │ +│ └────────────────┬───────────────────┘ │ +│ │ │ +│ ┌──────────▼──────────┐ │ +│ │ Infraestrutura │ │ +│ │ Compartilhada │ │ +│ │ (LLM, Embeddings) │ │ +│ └─────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +**Isolamento garantido:** +- Dados de um tenant nunca visíveis para outro +- Configurações independentes +- Billing separado (se aplicável) +- Audit logs por tenant + +--- + +## 6. Responsividade + +O portal é responsivo e funciona em: + +| Dispositivo | Suporte | +|-------------|---------| +| Desktop (1920px+) | ✅ Otimizado | +| Laptop (1366px) | ✅ Otimizado | +| Tablet (768px) | ✅ Adaptado | +| Mobile (375px) | ⚠️ Visualização apenas | + +--- + +## 7. Acessibilidade + +- Navegação por teclado completa +- Compatível com leitores de tela (ARIA) +- Contraste adequado (WCAG 2.1 AA) +- Textos redimensionáveis + +--- + +## 8. Próximos Passos + +1. **Fase 1:** Portal básico com Dashboard e Configurações +2. **Fase 2:** Editor de regras de negócio +3. **Fase 3:** Multi-tenant e SSO +4. **Fase 4:** Relatórios avançados e exportação +5. **Fase 5:** API pública para integrações + +--- + +**Documento preparado para apresentação de produto.** diff --git a/docs/aci-jira-ai-fixer-technical-en.md b/docs/aci-jira-ai-fixer-technical-en.md new file mode 100644 index 0000000..00d5ea7 --- /dev/null +++ b/docs/aci-jira-ai-fixer-technical-en.md @@ -0,0 +1,611 @@ +# ACI JIRA AI Fixer - Technical Document + +**Version:** 1.1 +**Date:** 2026-02-18 +**Update:** Azure OpenAI mandatory for compliance +**Classification:** Internal - Technical Team + +--- + +## 1. Overview + +### 1.1 Objective +Develop an artificial intelligence system that integrates with JIRA and Bitbucket to automate Support Case analysis, identify affected modules in source code (COBOL/SQL/JCL), propose fixes, and automatically document solutions. + +### 1.2 Scope +- **Products:** ACQ-MF (Acquirer) and ICG-MF (Interchange) +- **Repositories:** Client-specific forks (e.g., ACQ-MF-safra-fork, ICG-MF-safra-fork) +- **Issues:** Support Cases in JIRA +- **Languages:** COBOL, SQL, JCL + +### 1.3 High-Level Architecture + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ ACI JIRA AI FIXER - ARCHITECTURE │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌───────────────┐ │ +│ │ JIRA │ │ +│ │ gojira.tsacorp│ │ +│ │ .com │ │ +│ └───────┬───────┘ │ +│ │ Webhook (issue_created, issue_updated) │ +│ ▼ │ +│ ┌───────────────────────────────────────────────────────────────────┐ │ +│ │ EVENT PROCESSOR │ │ +│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ +│ │ │ Queue │ │ Filter │ │ Issue Classifier │ │ │ +│ │ │ (Redis) │──▶ (Support │──▶ (Product, Module, │ │ │ +│ │ │ │ │ Cases) │ │ Severity) │ │ │ +│ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │ +│ └───────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌───────────────────────────────────────────────────────────────────┐ │ +│ │ CODE INTELLIGENCE ENGINE │ │ +│ │ │ │ +│ │ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │ │ +│ │ │ Bitbucket │ │ Code Index │ │ Context │ │ │ +│ │ │ Connector │ │ (Azure OpenAI │ │ Builder │ │ │ +│ │ │ │ │ Embeddings) │ │ │ │ │ +│ │ │ bitbucket. │ │ - COBOL procs │ │ - CALLs │ │ │ +│ │ │ tsacorp.com │ │ - SQL tables │ │ - COPYBOOKs │ │ │ +│ │ │ │ │ - JCL jobs │ │ - Includes │ │ │ +│ │ └─────────────────┘ └─────────────────┘ └──────────────┘ │ │ +│ │ │ │ +│ │ Repositories: │ │ +│ │ ├── ACQ-MF (base) │ │ +│ │ │ └── ACQ-MF-safra-fork (client) │ │ +│ │ │ └── ACQ-MF-safra-ai (AI) ← NEW │ │ +│ │ ├── ICG-MF (base) │ │ +│ │ │ └── ICG-MF-safra-fork (client) │ │ +│ │ │ └── ICG-MF-safra-ai (AI) ← NEW │ │ +│ └───────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌───────────────────────────────────────────────────────────────────┐ │ +│ │ FIX GENERATION ENGINE │ │ +│ │ │ │ +│ │ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │ │ +│ │ │ LLM Engine │ │ Fix Validator │ │ Output │ │ │ +│ │ │ (Azure OpenAI) │ │ │ │ Generator │ │ │ +│ │ │ - GPT-4o │ │ - Syntax check │ │ │ │ │ +│ │ │ - GPT-4 Turbo │ │ - COBOL rules │ │ - JIRA │ │ │ +│ │ │ │ │ - SQL lint │ │ comment │ │ │ +│ │ │ │ │ - JCL validate │ │ - PR/Branch │ │ │ +│ │ └─────────────────┘ └─────────────────┘ └──────────────┘ │ │ +│ └───────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌───────────────┴───────────────┐ │ +│ ▼ ▼ │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ JIRA │ │ Bitbucket │ │ +│ │ Comment │ │ Pull Request│ │ +│ │ (Analysis + │ │ (AI Fork) │ │ +│ │ Suggestion)│ │ │ │ +│ └──────────────┘ └──────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 2. Detailed Components + +### 2.1 Event Processor + +#### 2.1.1 JIRA Webhook Receiver +```yaml +Endpoint: POST /api/webhook/jira +Events: + - jira:issue_created + - jira:issue_updated +Filters: + - issueType: "Support Case" + - project: ["ACQ", "ICG"] +Authentication: Webhook Secret (HMAC-SHA256) +``` + +#### 2.1.2 Queue System +```yaml +Technology: Redis + Bull Queue +Queues: + - jira-events: Raw JIRA events + - analysis-jobs: Pending analysis jobs + - fix-generation: Fix generation tasks +Retry Policy: + - Max attempts: 3 + - Backoff: exponential (1min, 5min, 15min) +Dead Letter Queue: jira-events-dlq +``` + +#### 2.1.3 Issue Classifier +Responsible for extracting metadata from issues: + +```python +class IssueClassifier: + def classify(self, issue: JiraIssue) -> ClassifiedIssue: + return ClassifiedIssue( + product=self._detect_product(issue), # ACQ-MF or ICG-MF + module=self._detect_module(issue), # Authorization, Clearing, etc. + severity=self._detect_severity(issue), # P1, P2, P3 + keywords=self._extract_keywords(issue), # Technical terms + 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) +Authentication: Personal Access Token or OAuth + +Operations: + - Clone/Pull: Sparse checkout (relevant directories only) + - Read: Specific file contents + - Branches: Create/list branches in AI fork + - Pull Requests: Create PR from AI fork → client fork +``` + +**Access Structure per Repository:** + +| Repository | AI Permission | Usage | +|------------|---------------|-------| +| ACQ-MF (base) | READ | Reference, standards | +| ACQ-MF-safra-fork | READ | Current client code | +| ACQ-MF-safra-ai | WRITE | AI branches and commits | +| ICG-MF (base) | READ | Reference, standards | +| ICG-MF-safra-fork | READ | Current client code | +| ICG-MF-safra-ai | WRITE | AI branches and commits | + +#### 2.2.2 Code Index (Embeddings) + +**⚠️ IMPORTANT: Azure OpenAI Embeddings (Mandatory)** + +The client has compliance requirements that mandate source code data not be processed by public APIs. Therefore, we **mandatorily** use Azure OpenAI Embeddings: + +```yaml +Provider: Azure OpenAI (data remains in client's Azure tenant) +Model: text-embedding-ada-002 or text-embedding-3-large +Region: Brazil South (recommended) or East US +Compliance: Data not used for training Microsoft models +Contract: ACI's existing Enterprise Agreement +``` + +**Why not use GitHub Copilot for embeddings?** +- GitHub Copilot is an IDE tool, has no API for integration +- Does not offer indexing or semantic search functionality +- There is no way to use Copilot to search code programmatically + +**COBOL Code Indexing:** +```yaml +Granularity: By PROGRAM-ID / SECTION / PARAGRAPH +Extracted metadata: + - PROGRAM-ID + - COPY statements (dependencies) + - CALL statements (called programs) + - FILE-CONTROL (accessed files) + - SQL EXEC (tables/queries) + - Working Storage (main variables) + +Embedding Model: Azure OpenAI text-embedding-3-large +Vector DB: Qdrant (self-hosted on ACI infra) or Azure AI Search +Dimensions: 3072 +Index separated by: product + client +``` + +**SQL Indexing:** +```yaml +Granularity: By table/view/procedure +Extracted metadata: + - Object name + - Columns and types + - Foreign keys + - Referencing procedures +``` + +**JCL Indexing:** +```yaml +Granularity: By JOB / STEP +Extracted metadata: + - JOB name + - Executed PGMs + - DD statements (datasets) + - Passed PARMs + - Dependencies (JCL INCLUDEs) +``` + +#### 2.2.3 Context Builder + +Assembles relevant context for LLM analysis: + +```python +class ContextBuilder: + def build_context(self, issue: ClassifiedIssue) -> AnalysisContext: + # 1. Search programs mentioned in the issue + mentioned_programs = self._search_by_keywords(issue.keywords) + + # 2. Search similar programs from past issues + similar_issues = self._find_similar_issues(issue) + + # 3. Expand dependencies (COPYBOOKs, CALLs) + dependencies = self._expand_dependencies(mentioned_programs) + + # 4. Get configured business rules + business_rules = self._get_business_rules(issue.product) + + # 5. Build final context (respecting token limit) + return AnalysisContext( + primary_code=mentioned_programs[:5], # Max 5 main programs + dependencies=dependencies[:10], # Max 10 dependencies + similar_fixes=similar_issues[:3], # Max 3 examples + 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 (data does not leave Azure environment) +Fallback: Azure OpenAI GPT-4 Turbo +Gateway: LiteLLM (unified interface) + +Configuration: + temperature: 0.2 # Low for code + max_tokens: 4096 + top_p: 0.95 +``` + +**Note on GitHub Copilot:** The client has GitHub Copilot, however this tool is intended for use in the IDE by developers. Copilot **does not have a public API** for integration in automated systems and **does not offer embedding/indexing functionality**. Therefore, the solution uses Azure OpenAI for all AI operations. + +**COBOL Prompt Template:** +``` +You are an expert in mainframe payment systems, +specifically ACI Acquirer (ACQ-MF) and Interchange (ICG-MF) products. + +## System Context +{business_rules} + +## Reported Issue +{issue_description} + +## Current Code +{code_context} + +## Similar Fix History +{similar_fixes} + +## Task +Analyze the issue and: +1. Identify the probable root cause +2. Locate the affected program(s) +3. Propose a specific fix +4. Explain the impact of the change + +## Rules +- Maintain COBOL-85 compatibility +- Preserve existing copybook structure +- Do not change interfaces with other systems without explicit mention +- Document all proposed changes + +## Response Format +{response_format} +``` + +#### 2.3.2 Fix Validator + +**COBOL Validations:** +```yaml +Syntax: + - Compilation with GnuCOBOL (syntax check) + - Verification of referenced copybooks + +Semantics: + - CALLs to existing programs + - Variables declared before use + - Compatible PIC clauses + +Style: + - Standard indentation (Area A/B) + - ACI naming conventions + - Mandatory comments +``` + +**SQL Validations:** +```yaml +- Syntax check with SQL parser +- Verification of existing tables/columns +- Performance analysis (EXPLAIN) +``` + +**JCL Validations:** +```yaml +- JCL syntax check +- Referenced datasets exist +- Referenced PGMs exist +``` + +--- + +## 3. Repository Structure (AI Fork) + +### 3.1 AI Fork Creation + +```bash +# Proposed structure in Bitbucket +projects/ +├── ACQ/ +│ ├── ACQ-MF # Base product (existing) +│ ├── ACQ-MF-safra-fork # Client fork (existing) +│ └── ACQ-MF-safra-ai # AI fork (NEW) +│ +├── ICG/ +│ ├── ICG-MF # Base product (existing) +│ ├── ICG-MF-safra-fork # Client fork (existing) +│ └── ICG-MF-safra-ai # AI fork (NEW) +``` + +### 3.2 Branch Flow + +``` +ACQ-MF-safra-fork (client) + │ + │ fork + ▼ +ACQ-MF-safra-ai (AI) + │ + ├── main (sync with client) + │ + └── ai-fix/JIRA-1234-description + │ + │ Pull Request + ▼ + ACQ-MF-safra-fork (client) + │ + │ Review + Approve + ▼ + merge +``` + +### 3.3 Commit Convention + +``` +[AI-FIX] JIRA-1234: Short fix description + +Problem: +- Original problem description + +Solution: +- What was changed and why + +Modified files: +- src/cobol/ACQAUTH.CBL (lines 1234-1256) + +Confidence: 85% +Generated by: ACI JIRA AI Fixer v1.0 + +Co-authored-by: ai-fixer@aci.com +``` + +### 3.4 Recommended Permissions + +| User/Group | ACQ-MF (base) | Client Fork | AI Fork | +|------------|---------------|-------------|---------| +| ai-fixer-svc | READ | READ | WRITE | +| devs-aci | WRITE | WRITE | READ | +| tech-leads | ADMIN | ADMIN | ADMIN | + +--- + +## 4. Technology Stack + +### 4.1 Backend +```yaml +Runtime: Python 3.11+ +Framework: FastAPI +Async: asyncio + httpx +Queue: Redis 7+ with Bull Queue (via Python-RQ or Celery) +Database: PostgreSQL 15+ (metadata, configurations, logs) +Vector DB: Qdrant 1.7+ (self-hosted) +Cache: Redis +``` + +### 4.2 Frontend (Admin Panel) +```yaml +Framework: React 18+ or Vue 3+ +UI Kit: Tailwind CSS + shadcn/ui +State: React Query or Pinia +Build: Vite +``` + +### 4.3 Infrastructure +```yaml +Container: Docker + Docker Compose +Orchestration: Docker Swarm (initial) or Kubernetes (scale) +CI/CD: Bitbucket Pipelines +Reverse Proxy: Traefik or nginx +SSL: Let's Encrypt +Monitoring: Prometheus + Grafana +Logs: ELK Stack or Loki +``` + +### 4.4 External Integrations +```yaml +LLM (Azure OpenAI - MANDATORY): + Primary: Azure OpenAI GPT-4o + Fallback: Azure OpenAI GPT-4 Turbo + Region: Brazil South or East US + Gateway: LiteLLM (natively supports Azure OpenAI) + Compliance: Data not used for training, stays in Azure tenant + +Embeddings (Azure OpenAI - MANDATORY): + Model: Azure OpenAI text-embedding-3-large + Alternative: Azure OpenAI text-embedding-ada-002 + Vector DB: Qdrant (self-hosted) or Azure AI Search + +JIRA: + API: REST API v2 (Server) + Auth: Personal Access Token + +Bitbucket: + API: REST API 1.0 (Server) + Auth: Personal Access Token +``` + +**⚠️ Note on GitHub Copilot:** +The client has GitHub Copilot licenses, however this tool **is not applicable** for this solution because: +1. It's an IDE tool (code autocomplete), not an API +2. Has no public endpoint for programmatic integration +3. Does not offer embeddings or semantic search functionality +4. Does not allow indexing or querying code repositories + +GitHub Copilot will continue to be used by developers in their daily work, while the ACI AI Fixer solution uses Azure OpenAI for automation. + +--- + +## 5. Security + +### 5.1 Sensitive Data +```yaml +Source code: + - Processed in memory, not persisted to disk + - Embeddings stored in Qdrant (encrypted at-rest) + - Sanitized logs (no complete code) + +Credentials: + - Vault (HashiCorp) or AWS Secrets Manager + - Automatic token rotation + - Access audit log + +LLM and Embeddings: + - MANDATORY: Azure OpenAI (data does not leave Azure tenant) + - Data is not used to train Microsoft models + - Compliance with ACI corporate policies + - Brazil South region for lower latency +``` + +### 5.2 Network +```yaml +Deployment: + - Internal network (not exposed to internet) + - HTTPS/TLS 1.3 communication + - Firewall: only JIRA and Bitbucket can access webhooks + +Authentication: + - Admin Panel: SSO via SAML/OIDC (integrate with ACI AD) + - API: JWT tokens with short expiration + - Webhooks: HMAC-SHA256 signature verification +``` + +### 5.3 Compliance +```yaml +Requirements: + - [ ] Data segregation by client/fork + - [ ] Complete audit trail (who, when, what) + - [ ] Configurable log retention + - [ ] Option for 100% on-premise processing + - [ ] Data flow documentation +``` + +--- + +## 6. Estimates + +### 6.1 Development Timeline + +| Phase | Duration | Deliverables | +|-------|----------|--------------| +| **1. Initial Setup** | 2 weeks | Infra, repos, basic CI/CD | +| **2. Integrations** | 3 weeks | JIRA webhook, Bitbucket connector | +| **3. Code Intelligence** | 4 weeks | COBOL/SQL/JCL indexing, embeddings | +| **4. Fix Engine** | 3 weeks | LLM integration, prompt engineering | +| **5. Output & PR** | 2 weeks | JIRA comments, Bitbucket PRs | +| **6. Admin Panel** | 2 weeks | Dashboard, configurations | +| **7. Tests & Adjustments** | 2 weeks | Validation with real issues | +| **Total MVP** | **18 weeks** | ~4.5 months | + +### 6.2 Suggested Team + +| Role | Quantity | Dedication | +|------|----------|------------| +| Tech Lead | 1 | 100% | +| Backend Developer | 2 | 100% | +| Frontend Developer | 1 | 50% | +| DevOps | 1 | 25% | +| **Total** | **5** | | + +### 6.3 Monthly Operational Costs (Estimate) + +| Item | Cost/Month | +|------|------------| +| LLM APIs (10 issues × ~$3/issue) | ~$30 | +| Infra (VPS/On-premise) | $200-500 | +| Vector DB (Qdrant self-hosted) | $0 (infra) | +| **Total** | **~$230-530/month** | + +*Note: Low volume (5-10 issues/month) results in minimal operational cost.* + +--- + +## 7. Technical Risks and Mitigations + +| Risk | Probability | Impact | Mitigation | +|------|-------------|--------|------------| +| LLM generates incorrect fix | High | High | Mandatory human review, confidence score | +| Insufficient COBOL context | Medium | High | RAG with copybooks, fix examples | +| High latency | Low | Medium | Async queue, visual feedback | +| Bitbucket API rate limit | Low | Low | Aggressive cache, sparse checkout | +| Security (code exposure) | Medium | High | Azure OpenAI or self-hosted LLM | + +--- + +## 8. Success Metrics + +### 8.1 Technical KPIs + +| Metric | MVP Target | 6-Month Target | +|--------|------------|----------------| +| Successful analysis rate | 80% | 95% | +| Accepted fixes (no modification) | 30% | 50% | +| Accepted fixes (with adjustments) | 50% | 70% | +| Average analysis time | < 5 min | < 2 min | +| System uptime | 95% | 99% | + +### 8.2 Business KPIs + +| Metric | Target | +|--------|--------| +| Initial analysis time reduction | 50% | +| Issues with useful suggestion | 70% | +| Team satisfaction | > 4/5 | + +--- + +## 9. Next Steps + +1. **Week 1-2:** + - Provision development infrastructure + - Create AI forks in Bitbucket + - Configure JIRA webhooks (test environment) + +2. **Week 3-4:** + - Implement Bitbucket connector + - Index code from 1 repository (ACQ-MF-safra-fork) + - Test embeddings with 5 historical issues + +3. **Week 5-6:** + - Integrate LLM (Azure OpenAI GPT-4o) + - Develop COBOL-specific prompts + - Validate outputs with technical team + +--- + +**Document prepared for technical review.** + +*Contact: [Development Team]* diff --git a/docs/aci-jira-ai-fixer-tecnico.md b/docs/aci-jira-ai-fixer-tecnico.md new file mode 100644 index 0000000..ebd6eb1 --- /dev/null +++ b/docs/aci-jira-ai-fixer-tecnico.md @@ -0,0 +1,749 @@ +# 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]*