# Users & Roles Module

## Purpose
Manage all user accounts, roles, permissions, authentication, and profile management across the system.

## User Roles (RBAC)
Uses **Spatie Permission** package with 7 defined roles:

| Role | Panel | Access Level |
|------|-------|-------------|
| **super-admin** | Admin | System-wide access, all programs |
| **super-manager** | Admin | System-wide management (non-admin tasks) |
| **portal-admin** | Program | Full program management (settings, users, content) |
| **portal-manager** | Program | Program management (non-admin tasks) |
| **portal-teacher** | Program | Educational content creation, student management |
| **portal-teacher-assistant** | Program | Assists teacher with limited permissions |
| **portal-student** | Program | Access to assessments, self-training, results |

## Key Models

### User (`app/Models/User.php`)
- Extends `Authenticatable`, implements `FilamentUser` and `MustVerify`
- Uses traits: `HasRoles`, `HasFactory`, `Notifiable`, `HasPlanSubscriptions`, `InteractsWithLanguages`, `HasFeatureAccess`
- Supports dual verification: email OR phone (at least one required)
- Has `is_default` flag for the system default super-admin user
- Has `is_active` flag controlled by program admin approval
- Can belong to a Program (via `program_id`) and/or a Teacher (via `teacher_id`)

### Key Relationships
- `program()` → BelongsTo Program
- `teacher()` → BelongsTo User (parent teacher)
- `students()` → HasMany User (if teacher)
- `teams()` → BelongsToMany Team (via TeamUser pivot)
- `courses()`, `lessons()` → HasMany if teacher
- `teacherSubscriptions()`, `studentSubscriptions()` → HasMany

### Custom DatabaseNotification (`app/Models/DatabaseNotification.php`)
- Overrides standard `notifications()` relationship to use translatable data
- Applies `__()` to title/body at display time for multi-language support

## Authentication

### Dual Authentication Methods
- **Email-based:** Login, Register, Verify, Password Reset
- **Phone-based:** Login, Register, Verify, Password Reset

### Auth Pages (Filament Custom Pages)
Located in `app/Filament/Pages/Auth/`:
- `LoginEmail`, `LoginPhone` — Email/phone login
- `RegisterProgramEmail`, `RegisterProgramPhone` — Program registration
- `RegisterTeacherEmail`, `RegisterTeacherPhone` — Teacher registration
- `RegisterStudentEmail`, `RegisterStudentPhone` — Student registration
- `VerifyEmail`, `VerifyPhone` — Verification
- `RequestPasswordResetEmail`, `RequestPasswordResetPhone`
- `ResetPasswordEmail`, `ResetPasswordPhone`

### Verification Flow
- Users must verify email OR phone before accessing the panel
- Unverified users see a verification prompt with sidebar hidden
- Verification changes dispatch `user.email.verified` / `user.phone.verified` events

### Auto-Subscription on Registration
- Students auto-subscribed to initial `StudentPlan`
- Teachers/Admins auto-subscribed to initial `TeacherPlan`
- Programs auto-subscribed to initial `ProgramPlan`

## Authorization
- Panel access controlled via `canAccessPanel()` method
- Admin panel restricted by `EnsureUserIsSuper` middleware
- Program panel restricted by `EnsureUserBelongsToProgram` middleware
- Verification checked via `EnsureUserIsVerified` middleware
- Feature-based authorization via FeatureGate middleware `feature:feature_key`

## Events & Notifications
The User model dispatches these notification events via booted `created`/`deleted`/`saved` hooks:
- `user.account.created` — New user registered
- `user.account.deleted` — User deleted
- `user.email.verified` — Email verified
- `user.phone.verified` — Phone verified
- `user.account.approved` — Account activated
- `user.account.suspended` — Account deactivated
- `user.password.changed` — Password changed
- `user.profile.updated` — Profile fields changed
- `user.teacher.assigned` — Teacher reassigned
- `user.program.assigned` — Program reassigned
- `user.login.detected` — On login (dispatched via event listener)

## Related Workflows
- **[Teacher Registration Workflow](../WORKFLOWS.md#2-teacher-registration-workflow)** — End-to-end teacher account creation and approval
- **[Student Registration Workflow](../WORKFLOWS.md#3-student-registration-workflow)** — End-to-end student account creation and approval
- **[User Login & Session Workflow](../WORKFLOWS.md#10-user-login--session-workflow)** — Authentication, session tracking, and login history