444 lines
11 KiB
Markdown
Executable File
444 lines
11 KiB
Markdown
Executable File
# 🛠️ INSTALLAZIONE E CONFIGURAZIONE - SISTEMA CONTROLLO QUALITÀ
|
|
|
|
**Versione**: 1.0.0
|
|
**Piattaforma**: Laravel 10+ con NetGescon
|
|
**Requisiti**: PHP 8.1+, MySQL 5.7+
|
|
|
|
---
|
|
|
|
## ⚡ INSTALLAZIONE RAPIDA
|
|
|
|
### **Status Attuale**
|
|
✅ **SISTEMA GIÀ INSTALLATO E OPERATIVO!**
|
|
|
|
Il sistema è stato implementato il 23 Luglio 2025 e include:
|
|
- ✅ Controller completo
|
|
- ✅ Views responsive
|
|
- ✅ Routes configurate
|
|
- ✅ Navigazione integrata
|
|
- ✅ Documentazione completa
|
|
|
|
### **Verifica Installazione**
|
|
```bash
|
|
# 1. Verifica file esistenti
|
|
ls -la app/Http/Controllers/Admin/CodeQualityController.php
|
|
ls -la resources/views/admin/code-quality/index.blade.php
|
|
|
|
# 2. Test access URL
|
|
curl -I https://yourdomain.com/admin/code-quality
|
|
|
|
# 3. Check routes
|
|
php artisan route:list | grep code-quality
|
|
```
|
|
|
|
---
|
|
|
|
## 📁 STRUTTURA FILE INSTALLATI
|
|
|
|
### **Controller**
|
|
```
|
|
📂 app/Http/Controllers/Admin/
|
|
└── 📄 CodeQualityController.php (8.2KB)
|
|
├── index() - Dashboard principale
|
|
├── scan() - Engine scansione AJAX
|
|
├── autofix() - Fix automatici
|
|
├── scanCodeQuality() - Core logic
|
|
├── analyzeFile() - Analisi singolo file
|
|
├── getFilesToScan() - File discovery
|
|
├── shouldApplyRule() - Rule filtering
|
|
├── getLineContext() - Context viewer
|
|
├── filterBySeverity() - Severity filter
|
|
├── generateSummary() - Statistics
|
|
└── applyAutoFix() - Automated fixes
|
|
```
|
|
|
|
### **Views**
|
|
```
|
|
📂 resources/views/admin/code-quality/
|
|
└── 📄 index.blade.php (12.5KB)
|
|
├── NetGescon layout integration
|
|
├── Configuration form
|
|
├── Real-time scanning
|
|
├── Results dashboard
|
|
├── Statistics cards
|
|
├── Interactive fix buttons
|
|
└── JavaScript automation
|
|
```
|
|
|
|
### **Routes**
|
|
```
|
|
📂 routes/
|
|
└── 📄 web.php (modified)
|
|
├── Route::prefix('code-quality')
|
|
├── GET /admin/code-quality (index)
|
|
├── POST /admin/code-quality/scan
|
|
└── POST /admin/code-quality/autofix
|
|
```
|
|
|
|
### **Documentazione**
|
|
```
|
|
📂 docs/sistema-controllo-qualita/
|
|
├── 📄 README.md (Sistema overview)
|
|
├── 📄 REGOLE-CONTROLLO.md (8 regole dettagliate)
|
|
├── 📄 GUIDA-PRATICA.md (Workflow operativi)
|
|
└── 📄 INSTALLAZIONE.md (Questo file)
|
|
```
|
|
|
|
---
|
|
|
|
## ⚙️ CONFIGURAZIONE POST-INSTALLAZIONE
|
|
|
|
### **1. Permissions Setup**
|
|
```bash
|
|
# Assicura permessi corretti per fix automatici
|
|
chmod 755 app/Http/Controllers/
|
|
chmod 644 app/Http/Controllers/Admin/CodeQualityController.php
|
|
chmod 755 resources/views/admin/code-quality/
|
|
chmod 644 resources/views/admin/code-quality/index.blade.php
|
|
|
|
# Permessi scrittura per fix automatici
|
|
chmod 775 app/
|
|
chmod 775 resources/views/
|
|
find app/ -type f -name "*.php" -exec chmod 664 {} \;
|
|
find resources/views/ -type f -name "*.blade.php" -exec chmod 664 {} \;
|
|
```
|
|
|
|
### **2. Environment Configuration**
|
|
```bash
|
|
# .env additions (opzionale)
|
|
CODE_QUALITY_ENABLED=true
|
|
CODE_QUALITY_MAX_FILE_SIZE=1048576 # 1MB
|
|
CODE_QUALITY_TIMEOUT=30 # 30 secondi
|
|
CODE_QUALITY_MEMORY_LIMIT=512M
|
|
```
|
|
|
|
### **3. Cache Optimization**
|
|
```bash
|
|
# Clear cache per nuove routes
|
|
php artisan route:clear
|
|
php artisan cache:clear
|
|
php artisan config:clear
|
|
|
|
# Optimize for production
|
|
php artisan route:cache
|
|
php artisan config:cache
|
|
```
|
|
|
|
---
|
|
|
|
## 🔧 PERSONALIZZAZIONE AVANZATA
|
|
|
|
### **Aggiungere Regole Custom**
|
|
```php
|
|
// In CodeQualityController.php - $qualityRules array
|
|
|
|
'custom_netgescon_rule' => [
|
|
'name' => 'NetGescon Custom Check',
|
|
'description' => 'Verifica standard specifici NetGescon',
|
|
'pattern' => '/your-custom-regex-pattern/m',
|
|
'required' => 'Soluzione richiesta',
|
|
'severity' => 'warning|error|critical|info'
|
|
],
|
|
```
|
|
|
|
### **Configurare Esclusioni**
|
|
```php
|
|
// In getFilesToScan() method
|
|
$excludePatterns = [
|
|
'vendor/*',
|
|
'node_modules/*',
|
|
'storage/logs/*',
|
|
'_BACKUP_*',
|
|
'*.min.js',
|
|
'*.min.css',
|
|
// Aggiungi pattern custom
|
|
'legacy/*',
|
|
'external/*',
|
|
'temp/*'
|
|
];
|
|
```
|
|
|
|
### **Personalizzare Fix Automatici**
|
|
```php
|
|
// In applyAutoFix() method
|
|
switch ($ruleKey) {
|
|
case 'your_custom_rule':
|
|
$content = preg_replace(
|
|
'/old-pattern/',
|
|
'new-pattern',
|
|
$content
|
|
);
|
|
break;
|
|
|
|
// Aggiungi altri fix custom
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🔌 INTEGRAZIONE CI/CD
|
|
|
|
### **GitHub Actions**
|
|
```yaml
|
|
# .github/workflows/code-quality.yml
|
|
name: NetGescon Code Quality
|
|
|
|
on: [push, pull_request]
|
|
|
|
jobs:
|
|
quality-check:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v3
|
|
|
|
- name: Setup PHP
|
|
uses: shivammathur/setup-php@v2
|
|
with:
|
|
php-version: '8.1'
|
|
|
|
- name: Install Dependencies
|
|
run: composer install --no-dev --optimize-autoloader
|
|
|
|
- name: Run Code Quality Check
|
|
run: |
|
|
php artisan code:quality:scan --format=json --output=quality-report.json
|
|
|
|
- name: Upload Quality Report
|
|
uses: actions/upload-artifact@v3
|
|
with:
|
|
name: quality-report
|
|
path: quality-report.json
|
|
```
|
|
|
|
### **Webhook Integration**
|
|
```php
|
|
// routes/api.php - per integrazione esterna
|
|
Route::post('/webhook/code-quality', function (Request $request) {
|
|
// Trigger scansione automatica su push
|
|
$controller = new CodeQualityController();
|
|
$results = $controller->scan($request);
|
|
|
|
// Invia notifica su Slack/Teams se critical > 0
|
|
if ($results['summary']['by_severity']['critical'] > 0) {
|
|
// Send alert notification
|
|
}
|
|
|
|
return response()->json($results);
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 MONITORING E ALERTING
|
|
|
|
### **Database Logging** (Opzionale)
|
|
```php
|
|
// Migration per logging risultati
|
|
Schema::create('code_quality_scans', function (Blueprint $table) {
|
|
$table->id();
|
|
$table->timestamp('scan_date');
|
|
$table->integer('total_files');
|
|
$table->integer('critical_issues');
|
|
$table->integer('error_issues');
|
|
$table->integer('warning_issues');
|
|
$table->integer('info_issues');
|
|
$table->decimal('quality_score', 5, 2);
|
|
$table->json('detailed_results');
|
|
$table->timestamps();
|
|
});
|
|
```
|
|
|
|
### **Slack Notifications**
|
|
```php
|
|
// In controller, after scan completion
|
|
if ($summary['by_severity']['critical'] > 0) {
|
|
Notification::route('slack', config('services.slack.webhook'))
|
|
->notify(new CriticalQualityIssuesNotification($summary));
|
|
}
|
|
```
|
|
|
|
### **Email Reports**
|
|
```php
|
|
// Scheduled command for weekly reports
|
|
// app/Console/Commands/WeeklyQualityReport.php
|
|
class WeeklyQualityReport extends Command
|
|
{
|
|
public function handle()
|
|
{
|
|
$controller = new CodeQualityController();
|
|
$results = $controller->scanCodeQuality('app,resources/views', 'all');
|
|
|
|
Mail::to(config('app.admin_email'))
|
|
->send(new QualityReportMail($results));
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🔍 DEBUGGING E TROUBLESHOOTING
|
|
|
|
### **Enable Debug Mode**
|
|
```php
|
|
// In CodeQualityController.php
|
|
private $debug = true; // Enable for troubleshooting
|
|
|
|
private function debugLog($message, $data = null) {
|
|
if ($this->debug) {
|
|
\Log::debug("CodeQuality: $message", $data ? ['data' => $data] : []);
|
|
}
|
|
}
|
|
```
|
|
|
|
### **Performance Profiling**
|
|
```php
|
|
// Add timing to scan methods
|
|
$startTime = microtime(true);
|
|
$results = $this->scanCodeQuality($scanPath, $severityFilter);
|
|
$executionTime = microtime(true) - $startTime;
|
|
|
|
\Log::info("Code Quality Scan completed", [
|
|
'execution_time' => round($executionTime, 2) . 's',
|
|
'files_scanned' => count($results),
|
|
'memory_used' => memory_get_peak_usage(true) / 1024 / 1024 . 'MB'
|
|
]);
|
|
```
|
|
|
|
### **Error Handling**
|
|
```php
|
|
// Wrap scan operations in try-catch
|
|
try {
|
|
$results = $this->scanCodeQuality($scanPath, $severityFilter);
|
|
} catch (\Exception $e) {
|
|
\Log::error("Code Quality scan failed", [
|
|
'error' => $e->getMessage(),
|
|
'trace' => $e->getTraceAsString()
|
|
]);
|
|
|
|
return response()->json([
|
|
'success' => false,
|
|
'message' => 'Scansione fallita: ' . $e->getMessage()
|
|
], 500);
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🔐 SECURITY CONSIDERATIONS
|
|
|
|
### **File Access Control**
|
|
```php
|
|
// Verify file access permissions
|
|
private function canAccessFile($filePath) {
|
|
// Prevent access to sensitive files
|
|
$forbiddenPaths = [
|
|
'.env',
|
|
'storage/logs/',
|
|
'bootstrap/cache/',
|
|
'.git/'
|
|
];
|
|
|
|
foreach ($forbiddenPaths as $forbidden) {
|
|
if (Str::contains($filePath, $forbidden)) {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
return is_readable($filePath);
|
|
}
|
|
```
|
|
|
|
### **Input Validation**
|
|
```php
|
|
// Validate scan parameters
|
|
$request->validate([
|
|
'path' => 'required|string|max:500|regex:/^[a-zA-Z0-9\/_,.-]+$/',
|
|
'severity' => 'required|in:all,critical,error,warning,info'
|
|
]);
|
|
```
|
|
|
|
### **Rate Limiting**
|
|
```php
|
|
// In routes/web.php
|
|
Route::prefix('code-quality')->middleware(['throttle:10,1'])->group(function () {
|
|
// Limit to 10 scans per minute per user
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## 📋 POST-INSTALL CHECKLIST
|
|
|
|
### **Verifica Funzionalità**
|
|
```bash
|
|
✅ Dashboard accessibile (/admin/code-quality)
|
|
✅ Scansione funzionante (test su file piccolo)
|
|
✅ Fix automatici operativi
|
|
✅ Navigazione integrata (header/sidebar)
|
|
✅ Permissions corretti per file modification
|
|
✅ Performance accettabile (< 30s per scansione media)
|
|
✅ Error handling robusto
|
|
✅ Logging configurato
|
|
```
|
|
|
|
### **Team Onboarding**
|
|
```bash
|
|
✅ Documentazione condivisa con team
|
|
✅ Training session programmata
|
|
✅ Best practices comunicate
|
|
✅ Quality gates definiti
|
|
✅ Workflow integrato nel processo
|
|
```
|
|
|
|
### **Production Readiness**
|
|
```bash
|
|
✅ Environment variables configurate
|
|
✅ Caching abilitato
|
|
✅ Monitoring setup
|
|
✅ Backup strategy
|
|
✅ Rollback plan
|
|
✅ Performance baseline
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 NEXT STEPS
|
|
|
|
### **Immediate (Settimana 1)**
|
|
1. 🎯 Team training su utilizzo base
|
|
2. 📊 Prima scansione completa progetto
|
|
3. 🔧 Personalizzazione regole per NetGescon
|
|
4. 📋 Definizione quality gates
|
|
|
|
### **Short Term (Mese 1)**
|
|
1. 🔄 Integrazione workflow quotidiano
|
|
2. 📈 Monitoring metriche qualità
|
|
3. 🎯 Fix automatici per problemi comuni
|
|
4. 👥 Feedback raccolta da team
|
|
|
|
### **Long Term (Trimestre 1)**
|
|
1. 🤖 CI/CD integration completa
|
|
2. 📊 Advanced reporting dashboard
|
|
3. 🧠 Machine learning per pattern detection
|
|
4. 🌐 Multi-project support
|
|
|
|
---
|
|
|
|
## 📞 SUPPORT
|
|
|
|
### **Documentazione**
|
|
- 📖 **README**: Overview completo sistema
|
|
- 🛡️ **REGOLE**: Dettaglio 8 regole controllo
|
|
- 🎯 **GUIDA**: Workflow pratici operativi
|
|
- 🛠️ **INSTALL**: Questa guida
|
|
|
|
### **Contatti**
|
|
- 🤖 **Sviluppato da**: GitHub Copilot per NetGescon
|
|
- 📧 **Support**: Utilizzare sistema ticket NetGescon
|
|
- 🔄 **Updates**: Monitorare docs/ per nuove versioni
|
|
- 🐛 **Bug Reports**: Via issue tracking interno
|
|
|
|
---
|
|
|
|
**🎉 Il Sistema Controllo Qualità NetGescon è ora completamente installato e pronto per elevare la qualità del vostro codice! 🚀**
|