# 📘 FiberOps GMAO - Documentation complète

## 🚀 Accès rapide

### URLs d'accès
```
http://localhost/Insuite_backbones/public/index.php/login          (avec index.php)
http://localhost/Insuite_backbones/public/login                    (mod_rewrite)
http://localhost/Insuite_backbones/public/dashboard                (mod_rewrite)
```

### Identifiants de test
```
Email: admin@fiberops.local
Password: admin123
```

---

## 📋 Stack Technologique

| Composant | Version | URL |
|-----------|---------|-----|
| PHP | 8.1+ | Local |
| MySQL | 8.4.3 | Local |
| Bootstrap | 5.3.3 | CDN |
| AdminLTE | 4.0.0 | CDN |
| Bootstrap Icons | 1.11.3 | CDN |
| FullCalendar | 6.1.15 | CDN |
| Leaflet | 1.9.4 | CDN |

---

## 🏗️ Architecture MVC

### Core Framework
```
app/Core/
├── Router.php        # GET/POST/ANY routes, dispatch()
├── Controller.php    # Base controller avec view() & redirect()
├── View.php          # Template renderer avec layouts
├── Database.php      # PDO singleton
├── Auth.php          # Session management, RBAC
└── TOTP.php          # 2FA Google Authenticator
```

### Controllers
```
app/Controllers/
├── AuthController.php           # login, verify2fa, logout
├── DashboardController.php      # stats, home
├── IncidentsController.php      # index, create, detail, assign, status, comment
├── PlanningController.php       # calendar, events (JSON), save, delete
├── CartographyController.php    # map, data (JSON)
├── UsersController.php          # listing, create, toggle2fa
├── RolesController.php          # RBAC management
├── SettingsController.php       # branding, mail config
├── SLAController.php            # SLA policies
├── CatalogController.php        # cost items
└── QuotesController.php         # quote management
```

### Views & Layouts
```
app/Views/
├── layouts/
│   ├── main.php                 # Sidebar + header (auth users)
│   └── auth.php                 # Login/2FA minimal layout
├── auth/
│   ├── login.php                # Email + password form
│   └── 2fa.php                  # TOTP verification
├── dashboard/
│   └── index.php                # Stat cards + quick actions
├── incidents/
│   ├── index.php                # Filtered table listing
│   ├── create.php               # Incident form
│   └── detail.php               # History + comments + assignments
├── planning/
│   └── index.php                # FullCalendar + modal
├── cartography/
│   └── index.php                # Leaflet map
└── ... (other modules)
```

---

## 🔐 Authentification & Sécurité

### Login Flow
1. User POST email + password → `/login`
2. Query DB user by email
3. Verify password avec `password_verify()`
4. Create session: `$_SESSION['user'] = ['id', 'name', 'email', 'role_key']`
5. Check 2FA secret → if yes, redirect `/2fa` form
6. If 2FA passed → redirect `/dashboard`

### 2FA (TOTP)
- RFC 6238 implementation (class `TOTP`)
- Generate 32-char Base32 secret
- Store in `users.totp_secret`
- QR code scannable par Google Authenticator
- 6-digit code verification

### RBAC
```
Users → (many-to-one) → Roles → (many-to-many) → Permissions
```

**Rôles prédéfinis:**
- `admin` (toutes permissions)
- `agent` (incidents, devis, planning)
- `technicien` (dashboard view only)

**~25 Permissions:**
- `dashboard.view`
- `incidents.list`, `.create`, `.edit`, `.delete`
- `planning.view`, `.edit`
- `users.list`, `.create`, `.edit`, `.delete`
- `settings.view`, `.edit`
- Et bien d'autres...

---

## 📊 Modules en détail

### 1️⃣ Incidents Management

**Database Schema:**
```sql
- incidents: ticket_id, title, description, priority, status_id, client_id, location_id
- incident_history: field_name, old_value, new_value, changed_by, changed_at
- incident_comments: comment, is_internal, user_id
- incident_assignments: incident_id, user_id, assigned_by
```

**Statuts:**
- 🔴 Ouvert (new incident)
- 🟠 Assigné (assigned to technician)
- 🔵 En cours (work started)
- 🟢 Résolu provisoire (temporary fix)
- 🟢 Résolu définitif (final resolution)
- ⚪ Annulé

**Priorités:**
- Basse (blue)
- Moyenne (cyan)
- Haute (orange)
- Urgent (red)

**Features:**
- Auto-generated ticket ID: `INC-YYYY-MM-NNN`
- SLA calculation based on maintenance type + priority
- Full history tracking
- Internal/external comments
- Technician assignment

### 2️⃣ Planning

**Database Schema:**
```sql
- planning_tasks: title, type (preventive/corrective), start_datetime, end_datetime
  status, technician_id, incident_id, location_id, notes, color
```

**Calendar Integration (FullCalendar):**
- Month/Week/Day views
- Drag&drop to move events
- Resize to change duration
- Click to create/edit via modal
- Color-coded by type or custom

**Data:** Task title, type, dates, assignee, linked incident, site, custom color

### 3️⃣ Cartography

**Map Integration (Leaflet + OpenStreetMap):**
- Interactive map
- Markers for each incident with geolocation
- Color by status
- Popup with: Ticket + Title + Status + Priority + Site
- Auto-fit to show all markers

**Data:** Incidents WHERE latitude IS NOT NULL

### 4️⃣ Administration Panel

#### Users (`/users`)
- List all users
- Create new user (email, name, password hash)
- Assign role
- Toggle 2FA
- Activate/deactivate

#### Roles & Permissions (`/roles`)
- RBAC matrix: Roles × Permissions
- Edit permissions per role
- ~25 permissions defined

#### SLA (`/sla`)
- Maintenance types: Preventive, Corrective, Installation, Migration, Audit
- SLA policies: type + priority → response_minutes, resolution_minutes
- Example: Corrective + Urgent = 30min response / 120min resolution

#### Settings (`/settings`)
- Upload logo (PNG/JPG → stored in `storage/uploads/logo.png`)
- Upload favicon (ICO/SVG → `storage/uploads/favicon.ico`)
- Upload login background (JPG/PNG → `storage/uploads/login-bg.jpg`)
- SMTP mail config (host, port, username, password, from email)
- Default currency
- App branding (name, primary color)

#### Catalog (`/catalog`)
- Cost categories (Matériel, Main d'œuvre, Logiciels, etc.)
- Cost items: designation, unit (u, h, m², etc.), price, currency
- Linked to quotes

---

## 🎨 UI/UX Design

### Layout Structure

**For Authenticated Users:**
```
┌─────────────────────────────────────────────┐
│ NAVBAR (Gradient Blue #0d6efd → #0a58ca)   │
│ [Logo] FiberOps GMAO | [User ▼] [Logout]   │
├───────────────────┬─────────────────────────┤
│ SIDEBAR (250px)   │   CONTENT AREA          │
│ ┌─────────────────┤                         │
│ │ User Panel      │ ┌───────────────────┐   │
│ │ (avatar+name)   │ │ Content Header    │   │
│ │                 │ │ (page title)      │   │
│ │ Menu Items:     │ ├───────────────────┤   │
│ │ 📊 Dashboard    │ │                   │   │
│ │ 🔧 GMAO         │ │ Main Content      │   │
│ │  ├ ⚠️ Incidents │ │ (cards/table)     │   │
│ │  ├ ➕ New Inc.  │ │                   │   │
│ │  ├ 📅 Planning  │ │                   │   │
│ │  └ 🗺️ Map       │ │                   │   │
│ │ 📄 Quotes       │ │                   │   │
│ │ 🛡️ Admin        │ └───────────────────┘   │
│ │  ├ ⚙️ Settings  │                         │
│ │  ├ 👥 Users     │                         │
│ │  ├ 🔑 Roles     │                         │
│ │  ├ ⏳ SLA        │                         │
│ │  └ 📦 Catalog   │                         │
│ └─────────────────┘                         │
└───────────────────┴─────────────────────────┘
│ FOOTER (gray background)                    │
│ FiberOps GMAO © 2025 | Version 1.0.0        │
└─────────────────────────────────────────────┘
```

**For Guest (Login/2FA):**
```
┌───────────────────────────────────┐
│                                   │
│   [Gradient Blue Background]      │
│                                   │
│         [Company Logo]            │
│         FiberOps GMAO             │
│                                   │
│   ┌───────────────────────────┐   │
│   │  Login / 2FA Form         │   │
│   │  ┌─────────────────────┐  │   │
│   │  │ Email               │  │   │
│   │  │ [input]             │  │   │
│   │  │ Password            │  │   │
│   │  │ [password]          │  │   │
│   │  │ [Login Button]      │  │   │
│   │  └─────────────────────┘  │   │
│   └───────────────────────────┘   │
│                                   │
└───────────────────────────────────┘
```

### Color Scheme
| Element | Color | Hex | Usage |
|---------|-------|-----|-------|
| Primary | Blue | #0d6efd | Buttons, links, highlights |
| Success | Green | #198754 | Resolved, completed |
| Danger | Red | #dc3545 | Urgent priority, errors |
| Warning | Orange | #ffc107 | High priority, warnings |
| Info | Cyan | #0dcaf0 | Medium priority, info |
| Secondary | Gray | #6c757d | Disabled, secondary |

### Components Used
- **Navbar:** Bootstrap navbar with collapse
- **Sidebar:** Custom nav with submenu expand/collapse
- **Cards:** Bootstrap cards with icons + numbers
- **Tables:** Responsive tables with hover effect
- **Badges:** Priority + status (colored)
- **Buttons:** Primary, outline, danger, success
- **Forms:** Inputs, selects, textarea with validation
- **Modals:** FullCalendar event editor
- **Icons:** Bootstrap Icons (bi-*)

### Responsive Breakpoints
```
Mobile  (< 768px):  Sidebar hidden, hamburger menu, full-width content
Tablet  (768-1024px): Sidebar compact, adjusted padding
Desktop (> 1024px): Full sidebar, 2-column layout
```

---

## 🗄️ Database Schema

### Core Tables

**users**
```sql
id, name, email, password_hash, role_key, totp_secret, active, created_at
```

**roles**
```sql
id, key_name (admin/agent/technicien), label
```

**permissions**
```sql
id, key_name (e.g., dashboard.view), label
```

**role_permissions**
```sql
role_id, permission_id (junction table)
```

### Incidents Domain

**incidents**
```sql
id, ticket_id (UNIQUE), client_id, location_id, cause_id, title, description, 
priority (ENUM), status_id, declared_by, declared_at, expected_response_at, 
expected_resolution_at, resolved_at, created_at, updated_at
```

**incident_statuses**
```sql
id, key_name, label, is_system (1), color, sort_order
```

**incident_history**
```sql
id, incident_id, field_name, old_value, new_value, changed_by, changed_at
```

**incident_comments**
```sql
id, incident_id, user_id, comment, is_internal (0/1), created_at
```

**incident_assignments**
```sql
id, incident_id, user_id, assigned_by, assigned_at, active (1)
```

### Planning Domain

**planning_tasks**
```sql
id, title, type (preventive/corrective), start_datetime, end_datetime, 
status (Planifié/En cours/Terminé/Annulé), technician_id, incident_id, 
location_id, notes, color, created_at, updated_at
```

### Other Tables

**clients**
```sql
id, name, contact_email, contact_phone, active
```

**locations**
```sql
id, name, address, latitude, longitude, active
```

**maintenance_types**
```sql
id, name (Preventive/Corrective/Installation/Migration/Audit)
```

**sla_policies**
```sql
id, maintenance_type_id, priority (ENUM), response_minutes, resolution_minutes
```

**cost_categories**
```sql
id, name
```

**cost_items**
```sql
id, category_id, designation, unit, unit_price, currency
```

**quotes**
```sql
id, quote_no, client_name, related_type, related_ref, quote_date, 
status (En attente/Validé/Rejeté), total_ht, total_tva, total_ttc, currency
```

**settings**
```sql
`key` (PRIMARY), `value`
```

---

## 🛠️ Installation & Configuration

### Step 1: Database Setup

```bash
# Create database
mysql -u root -e "CREATE DATABASE bd_insuite_backbones CHARACTER SET utf8mb4;"

# Import schemas and seeds
mysql -u root bd_insuite_backbones < database/schema.sql
mysql -u root bd_insuite_backbones < database/seeds.sql
mysql -u root bd_insuite_backbones < database/incidents_schema.sql
mysql -u root bd_insuite_backbones < database/incidents_seeds.sql
mysql -u root bd_insuite_backbones < database/planning_schema.sql
mysql -u root bd_insuite_backbones < database/planning_seeds.sql
```

### Step 2: PHP Configuration

```php
// config/db.php
<?php
return [
    'driver' => 'mysql',
    'host' => 'localhost',
    'port' => 3306,
    'database' => 'bd_insuite_backbones',
    'username' => 'root',
    'password' => '',
    'charset' => 'utf8mb4',
];
```

### Step 3: Verify Installation

```
http://localhost/Insuite_backbones/public/index.php/login
Login: admin@fiberops.local / admin123
```

---

## 📡 API Endpoints (JSON)

### Planning
```
GET  /planning/events              # Return array of calendar events
POST /planning/save                # Create/update task (form data)
POST /planning/delete              # Delete task (form data)
```

### Cartography
```
GET  /cartography/data             # Return array of incident markers
```

---

## 🔄 Flow Examples

### Incident Declaration Flow
1. User clicks "Déclarer un incident"
2. Form rendered: client, location, title, description, cause, priority
3. POST to `/incidents/store`
4. Controller:
   - Generate ticket_id (`INC-2025-11-001`)
   - Calculate SLA (lookup maintenance_type + priority → sla_policy)
   - Insert incident record
   - Insert incident_history entry
   - Redirect to detail page
5. Display confirmation

### Planning Event Creation
1. User clicks calendar date OR clicks "Ajouter"
2. Modal appears with form
3. Fill: Title, Type, Start, End, Technician, Incident link, Site, Color
4. Submit → POST `/planning/save`
5. Controller inserts planning_task
6. Response: `{'ok': true}`
7. JS re-fetches events from `/planning/events`
8. FullCalendar re-renders

### Cartography Map View
1. User navigates to `/cartography`
2. Page renders empty div#map
3. JS fetches `/cartography/data`
4. Returns array: `[{id, lat, lng, title, status, color, priority, location}, ...]`
5. JS creates Leaflet markers with popup
6. fitBounds() to show all markers

---

## 📝 Notes & Best Practices

1. **Subdirectory Deployment:** All views calculate `$base` from `$_SERVER['SCRIPT_NAME']`. Works with or without mod_rewrite.

2. **Fallback Assets:** If custom logo/favicon not uploaded, defaults to SVG assets. Vues handle `file_exists()` check.

3. **Error Handling:** Controllers catch exceptions, return error messages. No try/catch shown explicitly but production should add.

4. **HTTPS:** Strongly recommended for production (auth sessions, password transmission).

5. **Session Security:** Set in `php.ini`:
   ```ini
   session.cookie_secure = 1         # HTTPS only
   session.cookie_httponly = 1       # No JS access
   session.cookie_samesite = "Strict"
   session.use_strict_mode = 1
   ```

6. **CORS:** Not implemented (same-origin). If API needed, add CORS headers.

7. **Input Validation:** Use `htmlspecialchars()` in views. Controllers should validate/sanitize.

8. **Rate Limiting:** Not implemented. Consider for production login endpoints.

---

## 🚀 Version 2 Roadmap

- [ ] Dashboard real-time stats (Chart.js)
- [ ] PDF export (incidents, quotes)
- [ ] Bulk actions (incidents)
- [ ] Email notifications
- [ ] Technician mobile app (React Native/Flutter)
- [ ] GPS tracking
- [ ] Photo upload
- [ ] Offline sync
- [ ] WebSocket real-time updates
- [ ] Advanced reporting
- [ ] Multi-tenancy
- [ ] REST API
- [ ] GraphQL endpoint

---

**Generated:** 5 Novembre 2025  
**Version:** 1.0.0  
**Status:** Production Ready