# SIGED Module Summary - Quick Reference

## 17 Core Modules Overview

| # | Module | Purpose | Key Models | Main Routes |
|---|--------|---------|-----------|-------------|
| 1 | **Academic** | Student & classroom management | Student, Classroom, Subject | `/admin/academic/*` |
| 2 | **Grades** | Grade and report card management | Grade, Bulletin | `/admin/grades/*` |
| 3 | **Disciplinary** | Disciplinary records & penalties | DisciplinaryRecord, Penalty, Appeal | `/admin/disciplinary/*` |
| 4 | **Attendance** | Attendance tracking | Attendance | `/admin/attendance/*` |
| 5 | **Biometric** | Facial recognition system | FacialRecognition | `/admin/biometric/*` |
| 6 | **Uniforms** | Uniform request management | UniformRequest | `/admin/uniforms/*` |
| 7 | **Financial** | Invoices & payments | Account, Invoice, Payment | `/admin/financial/*` |
| 8 | **HR** | Employee management | Employee | `/admin/hr/*` |
| 9 | **Payroll** | Salary management | Payroll | `/admin/payroll/*` |
| 10 | **Refectory** | Cafeteria & menus | Menu | `/admin/refectory/*` |
| 11 | **Events** | Event scheduling | Event, EventParticipant | `/admin/events/*` |
| 12 | **Ceremonial** | Ceremonial activities | Ceremonial | `/admin/ceremonial/*` |
| 13 | **Sports** | Sports programs | Sport, Athlete, Match | `/admin/sports/*` |
| 14 | **Communication** | Internal messaging | Message | `/admin/communication/*` |
| 15 | **Analytics** | Data analysis & reports | Report | `/admin/analytics/*` |
| 16 | **Portal** | Multi-role portal access | PortalUser | `/admin/portal/*` |
| 17 | **System** | Config & maintenance | AuditLog, Configuration | `/admin/system/*` |

---

## Module Details

### 1. ACADEMIC MODULE
- **Models**: Student, Classroom, Subject
- **Key Features**: 
  - Enroll students in classrooms
  - Manage subjects and curriculum
  - Track enrollment history
  - Bulk import/export students
- **Tables**: `academic_students`, `academic_classrooms`, `academic_subjects`

### 2. GRADES MODULE
- **Models**: Grade, Bulletin
- **Key Features**:
  - Record grades by bimester
  - Calculate weighted averages
  - Generate report cards
  - Track grade history
- **Tables**: `grades`, `bulletins`

### 3. DISCIPLINARY MODULE
- **Models**: DisciplinaryRecord, Penalty, Appeal
- **Key Features**:
  - Record incidents with severity levels
  - Apply penalties with duration
  - Process appeals
  - Incident history tracking
- **Tables**: `disciplinary_records`, `penalties`, `appeals`

### 4. ATTENDANCE MODULE
- **Models**: Attendance
- **Key Features**:
  - Daily attendance recording
  - Multiple status types (Present, Absent, Late, etc.)
  - Bulk attendance entry
  - Attendance statistics
  - Monthly/yearly reports
- **Tables**: `attendance`

### 5. BIOMETRIC MODULE
- **Models**: FacialRecognition
- **Key Features**:
  - Facial recognition enrollment
  - Identity verification
  - Device integration capability
  - Enrollment tracking
- **Tables**: `facial_recognition`

### 6. UNIFORMS MODULE
- **Models**: UniformRequest
- **Key Features**:
  - Request uniform items
  - Track delivery status
  - Support multiple sizes/types
  - Inventory reports
- **Tables**: `uniform_requests`

### 7. FINANCIAL MODULE
- **Models**: Account, Invoice, Payment
- **Key Features**:
  - Student account management
  - Invoice generation
  - Payment processing
  - Overdue tracking
  - Debt reporting
  - Multiple payment methods
- **Tables**: `financial_accounts`, `invoices`, `payments`

### 8. HR MODULE
- **Models**: Employee
- **Key Features**:
  - Employee registration
  - Department management
  - Hire date tracking
  - Employment history
  - Status management
- **Tables**: `employees`

### 9. PAYROLL MODULE
- **Models**: Payroll
- **Key Features**:
  - Salary calculations
  - Allowances & deductions
  - Period-based generation
  - Payroll receipts
  - Reports
- **Tables**: `payroll`

### 10. REFECTORY MODULE
- **Models**: Menu
- **Key Features**:
  - Daily menu planning
  - Meal tracking
  - Nutritional info
  - Bulk creation
- **Tables**: `refectory_menus`

### 11. EVENTS MODULE
- **Models**: Event, EventParticipant
- **Key Features**:
  - Event scheduling
  - Participant registration
  - Capacity management
  - Event types (Graduation, Presentation, etc.)
- **Tables**: `events`, `event_participants`

### 12. CEREMONIAL MODULE
- **Models**: Ceremonial
- **Key Features**:
  - Flag ceremonies
  - Ceremonial squad management
  - Band coordination
  - Protocol tracking
- **Tables**: `ceremonials`

### 13. SPORTS MODULE
- **Models**: Sport, Athlete, Match
- **Key Features**:
  - Sport/modality management
  - Athlete enrollment
  - Match scheduling
  - Coach assignment
  - Training schedules
- **Tables**: `sports`, `athletes`, `matches`

### 14. COMMUNICATION MODULE
- **Models**: Message
- **Key Features**:
  - Direct messaging
  - Broadcast messages
  - WhatsApp integration ready
  - Message read tracking
  - Multiple channels
- **Tables**: `messages`

### 15. ANALYTICS MODULE
- **Models**: Report
- **Key Features**:
  - Custom report generation
  - Data filtering
  - Export functionality
  - Historical storage
  - AI-ready architecture
- **Tables**: `analytics_reports`

### 16. PORTAL MODULE
- **Models**: PortalUser
- **Key Features**:
  - Role-based access (Student, Teacher, Parent, Admin)
  - Last login tracking
  - Access logs
  - Password management
  - Permission control
- **Tables**: `portal_users`

### 17. SYSTEM MODULE
- **Models**: AuditLog, Configuration
- **Key Features**:
  - Audit log management
  - System configuration
  - Backup & restore
  - System monitoring
  - Change tracking
- **Tables**: `audit_logs`, `configurations`

---

## Shared Components

### Enums (app/Enums/)
- **UserRole**: Admin, Director, Teacher, Student, Parent, Staff, etc.
- **AttendanceStatus**: Present, Absent, Late, Excused, Justified
- **DisciplinaryStatus**: Open, Investigating, Resolved, Appealed, Closed
- **PaymentStatus**: Pending, Approved, Processing, Completed, Failed, Cancelled, Refunded

### Traits (app/Traits/)
- **HasTenancy**: Multi-tenancy filtering, automatic tenant_id assignment
- **HasAudit**: Automatic change logging, audit trail tracking

---

## Standard Endpoints Pattern

All modules follow RESTful conventions:

```
GET    /admin/module/resource              List
GET    /admin/module/resource/create       Create form
POST   /admin/module/resource              Store
GET    /admin/module/resource/{id}         Show
GET    /admin/module/resource/{id}/edit    Edit form
PUT    /admin/module/resource/{id}         Update
DELETE /admin/module/resource/{id}         Delete
POST   /admin/module/resource/{id}/action  Custom action
```

---

## API Endpoints

All modules also provide API access at `/api/v1/`:

```
GET    /api/v1/students
POST   /api/v1/students
GET    /api/v1/students/{id}
PUT    /api/v1/students/{id}
DELETE /api/v1/students/{id}
```

---

## File Structure Per Module

Each module includes:
- **Model** (`app/Models/ModuleName/Model.php`)
- **Controller** (`app/Http/Controllers/ModuleName/Controller.php`)
- **Service** (`app/Services/ModuleName/Service.php`)
- **Requests** (`app/Http/Requests/ModuleName/StoreRequest.php`, `UpdateRequest.php`)

---

## Database Tables Summary

### Academic
- `academic_students` - Student records
- `academic_classrooms` - Classroom/turma records
- `academic_subjects` - Subject records
- `academic_classroom_subject` - Pivot table

### Grades
- `grades` - Grade records
- `bulletins` - Report cards

### Disciplinary
- `disciplinary_records` - Incident records
- `penalties` - Penalty records
- `appeals` - Appeal records

### Attendance
- `attendance` - Daily attendance records

### Biometric
- `facial_recognition` - Facial data

### Uniforms
- `uniform_requests` - Uniform requests

### Financial
- `financial_accounts` - Student accounts
- `invoices` - School invoices
- `payments` - Payment records

### HR
- `employees` - Employee records

### Payroll
- `payroll` - Payroll records

### Refectory
- `refectory_menus` - Menu records

### Events
- `events` - Event records
- `event_participants` - Participant records

### Ceremonial
- `ceremonials` - Ceremonial records

### Sports
- `sports` - Sport/modality records
- `athletes` - Athlete records
- `matches` - Match records

### Communication
- `messages` - Message records

### Analytics
- `analytics_reports` - Report records

### Portal
- `portal_users` - Portal access records

### System
- `audit_logs` - Audit log records
- `configurations` - System configuration

---

## Key Features Across All Modules

✅ **Multi-Tenancy** - Data isolated by tenant
✅ **Audit Logging** - All changes tracked
✅ **Soft Deletes** - Safe data deletion
✅ **Relationship Mapping** - Proper foreign keys
✅ **Scopes** - Reusable query filters
✅ **Validation** - Form request validation with Portuguese messages
✅ **RESTful API** - API endpoints for all resources
✅ **Role-Based Access** - Permission system built-in
✅ **Export/Import** - CSV and bulk operations
✅ **Status Tracking** - Status enums for consistency

---

## Getting Started

### 1. Set Up Routes
```bash
# Include in routes/web.php
require base_path('routes/modules.php');
```

### 2. Run Migrations
```bash
php artisan migrate
```

### 3. Use in Controller
```php
use App\Services\Academic\AcademicService;

class YourController {
    public function __construct(private AcademicService $service) {}
    
    public function index() {
        $students = $this->service->listStudents();
    }
}
```

### 4. Call API
```bash
curl -X GET "http://localhost/api/v1/students" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

## Common Operations

### Create Record
```php
$student = Student::create([
    'registration_number' => '2024001',
    'first_name' => 'João',
    'last_name' => 'Silva',
    'class_id' => 1,
]);
```

### Update Record
```php
$student->update(['status' => 'inactive']);
```

### Filter Records
```php
$students = Student::active()
    ->byClassroom(1)
    ->where('gender', 'M')
    ->paginate(20);
```

### Soft Delete
```php
$student->delete(); // Soft delete
$student->restore(); // Restore
$student->forceDelete(); // Permanent delete
```

### Audit Trail
```php
$auditLogs = $student->auditLogs()->get();
```

---

## Authentication & Authorization

All routes require:
1. Authenticated user (`auth` middleware)
2. Valid tenant (`tenant` middleware)
3. Appropriate permissions (role-based)

---

## Performance Tips

1. **Use Eager Loading**: Load relationships with `with()`
2. **Paginate Results**: Use `paginate()` for large datasets
3. **Cache Common Queries**: Use Laravel's cache
4. **Add Indexes**: Index `tenant_id`, `student_id`, etc.
5. **Use Scopes**: Leverage query scopes for filtering

---

## Error Handling

All requests return:
- **200**: Success
- **201**: Created
- **400**: Bad Request (validation error)
- **401**: Unauthorized
- **403**: Forbidden
- **404**: Not Found
- **500**: Server Error

---

## Support Resources

- **Documentation**: See `MODULES_STRUCTURE.md`
- **Routes**: See `routes/modules.php`
- **Models**: Browse `app/Models/*/`
- **Controllers**: Browse `app/Http/Controllers/*/`
- **Services**: Browse `app/Services/*/`

---

**Version**: 1.0
**Laravel**: 11.x
**PHP**: 8.3+
**Last Updated**: June 2026