jira-ai-fixer/docs/portal-en.md

538 lines
46 KiB
Markdown
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# JIRA AI Fixer - Admin Portal
**Version:** 1.0
**Date:** February 2026
**Classification:** Product Documentation
---
## 1. Overview
The 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
- **SSO integration** with corporate providers
---
## 2. Portal Screens
### 2.1 Main Dashboard
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 🤖 JIRA AI Fixer admin@company.com ⚙️ 🔔 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │Dashboard│ │ Issues │ │ Repos │ │ Modules │ │Settings │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 📊 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://jira.yourcompany.com │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ API Token │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ •••••••••••••••••••••••••••••••• 👁️ │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Webhook URL (copy and configure in JIRA) │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ https://jira-fixer.yourcompany.com/api/webhook/jira 📋 │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Monitored Projects │ │
│ │ ☑️ PROJECT-A ☑️ PROJECT-B ☐ PROJECT-C │ │
│ │ │ │
│ │ [ 🔄 Test Connection ] │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Bitbucket ───────────────────────────────────────────────────────────┐ │
│ │ ✅ Connected │ │
│ │ │ │
│ │ Server URL │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ https://bitbucket.yourcompany.com │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Access Token │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ •••••••••••••••••••••••••••••••• 👁️ │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ [ 🔄 Test Connection ] │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ LLM Provider ────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Provider │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Azure OpenAI ▼ │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ Options: Azure OpenAI | OpenAI | OpenRouter | Self-hosted (Ollama) │ │
│ │ │ │
│ │ Endpoint (for Azure/Self-hosted) │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ https://your-resource.openai.azure.com │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ API Key │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ •••••••••••••••••••••••••••••••• 👁️ │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Model │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ gpt-4o ▼ │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ [ 🔄 Test Connection ] │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Embeddings ──────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Provider │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Self-hosted (MiniLM-L6) ▼ │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ Options: Self-hosted | Azure OpenAI | OpenAI │ │
│ │ │ │
│ │ Self-hosted embeddings are free and keep data on your servers. │ │
│ │ │ │
│ │ [ 🔄 Test Connection ] │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ [ 💾 Save All ] │
└─────────────────────────────────────────────────────────────────────────────┘
```
---
### 2.3 Repository Management
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 📁 REPOSITORIES [ + Add New ] │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ 📦 Product-Client-Fork [ ⚙️ ] [ 🗑️ ]│ │
│ │ │ │
│ │ URL: bitbucket.company.com/projects/PROD/repos/Product-Client-Fork │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Status │ ✅ Indexed │ │ │
│ │ │ Files │ 2,847 files indexed │ │ │
│ │ │ Last Sync │ 02/18/2026 11:30 │ │ │
│ │ │ AI Fork │ Product-Client-AI ✅ │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Detected languages: │ │
│ │ ████████████████████░░░░░░░░░░ COBOL 68% │ │
│ │ ██████░░░░░░░░░░░░░░░░░░░░░░░░ SQL 22% │ │
│ │ ███░░░░░░░░░░░░░░░░░░░░░░░░░░░ JCL 10% │ │
│ │ │ │
│ │ [ 🔄 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 ────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ AUTH* ✕ │ │ VALID* ✕ │ │ HOST* ✕ │ [ + 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 VALIDATE 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 │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ [ + 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 ] │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ 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 ────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 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: │ │
│ │ AUTH - SECTION 3000-VALIDATE - EVALUATE WS-RESPONSE-CODE │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ AI Analysis ─────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 🔍 IDENTIFIED ROOT CAUSE │ │
│ │ │ │
│ │ The AUTH.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/AUTH.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: jira.company.com/browse/SUPPORT-4521 │ │
│ │ 📝 Pull Request: bitbucket.company.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 Teams/Products)
The portal supports multiple isolated tenants:
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ MULTI-TENANT ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Tenant: Team Alpha Tenant: Team Beta │
│ ┌─────────────────────────┐ ┌─────────────────────────┐ │
│ │ - Alpha Repos │ │ - Beta Repos │ │
│ │ - Alpha Rules │ │ - Beta Rules │ │
│ │ - Alpha Users │ │ - Beta 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
### Version 1.0 (MVP)
- ✅ Dashboard with metrics
- ✅ JIRA/Bitbucket integration
- ✅ LLM configuration
- ✅ Repository management
- ✅ Business rules editor
- ✅ Issue list view
### Version 1.1
- [ ] Email notifications
- [ ] Slack/Teams integration
- [ ] Scheduled reports
- [ ] API rate limiting dashboard
### Version 2.0
- [ ] Custom AI prompts editor
- [ ] A/B testing for prompts
- [ ] Advanced analytics
- [ ] Workflow automation
---
**JIRA AI Fixer - Intelligent Support Case Resolution**
*For questions, contact: support@yourcompany.com*