analysis/04-functional-spec/providers-and-companies-module.md
Tourism Companies
Providers & Companies Module – Functional Specification
1. Purpose
The Providers & Companies Module defines how MASARUK manages tourism companies (B2B Providers) who create and manage trips, buses, hotels, and rest stops.
This includes:
- Provider account creation & onboarding
- Managing provider company data
- Associating provider staff users
- Controlling resources (trips, buses, hotels, rest stops)
- Linking financial records & ad campaigns to providers
- Activation/deactivation logic
- Role-based access (Provider Admin vs Provider Staff)
4. Provider Entity Fields
| Field | Type | Notes |
|---|---|---|
| id | PK | — |
| company_name | String | Company name |
| cr_number | String | Commercial register (if available) |
| license_number | String | Tourism license |
| phone | String | Phone number |
| String | Email address | |
| address | String | Address |
| logo_url | String | Company logo |
| status | Enum | ACTIVE / INACTIVE / PENDING_APPROVAL / REJECTED |
| country | String | Country (Saudi Arabia, Egypt, UAE, Jordan) |
| total_trips | Integer | Number of trips |
| total_sales | Decimal | Total sales |
| created_at | timestamp | — |
| updated_at | timestamp | — |
5. Provider Statuses
| Label | Enum | Color | Meaning |
|---|---|---|---|
| Active | ACTIVE | Green | Provider can operate normally |
| Rejected | REJECTED | Pink | Application rejected by admin |
| Pending Approval | PENDING_APPROVAL | Orange | Awaiting admin review |
Admin Actions
| Action | Modal Title | Confirmation Button |
|---|---|---|
| Approve | Accept! | Yes, Continue |
| Reject | — | — |
| Pause | Deactivate! | Yes, Continue |
| Reactivate | Reactivate! | Yes, Continue |
6. Provider Staff Fields (ProviderUser)
| Field | Type | Notes |
|---|---|---|
| id | PK | — |
| provider_id | FK | Staff's company |
| name | String | — |
| String | — | |
| phone | String | — |
| role | Enum | provider_admin / staff |
| status | Enum | active / disabled |
| created_at | timestamp | — |
| updated_at | timestamp | — |
7. Business Rules
BR-1. Provider must be activated to publish trips
If provider.status != active then: Cannot create trips, Cannot run ad campaigns, Cannot access financial reports.
BR-2. Provider Admin vs Provider Staff
- Provider Admin: full CRUD on all provider resources
- Staff: limited access depending on RBAC matrix
BR-3. Provider owns all created resources
Every trip, bus, hotel, rest stop is linked using provider_id
BR-4. Provider financial participation
- Provider receives net payout after platform commission
- Payout only if trip successfully completed
- Payout never issued on refunded bookings
BR-5. Provider cannot modify system-level entities
VAT, Commission settings, Global notifications, System-wide settings — these are Admin-only.
BR-6. Provider account removal is soft-delete only
Because trips, buses, hotels, rest-stops, and bookings reference provider.
BR-7. Campaign payments must always be linked to provider
AdCampaign → PaymentTransaction → Provider — ensures correct financial attribution.
8. Actions & Behaviors
A-1. Provider Creation (Admin Only)
- Create provider
- Upload logo
- Set status
- Assign initial provider admin user
A-2. Provider Self-Management
- Update profile data
- Change logo
- Update address
- Add/edit/remove staff users
A-3. Provider Resource Management
- Add/Edit/Delete Trips
- Add/Edit/Delete Buses
- Add/Edit/Delete Hotels
- Add/Edit/Delete RestStops
- Create AdCampaigns
A-4. Provider Financial Reports
- Transactions related to their trips
- Net revenues
- Payout status
- Export feature (CSV)
9. Validation Rules
VR-1. Unique Company Email
email must be unique across all providers.
VR-2. Unique Phone
phone must be unique.
VR-3. Provider License Validation
Admin must supply license_number; system stores it without interpretation.
VR-4. Provider User Role Validation
ProviderUser.role ∈ { provider_admin, staff }
VR-5. Provider cannot delete resources with active dependencies
Cannot delete hotel linked to future trips or bus assigned to active bookings.
10. Error Cases
| Case | Message |
|---|---|
| Provider inactive | Company account is not activated |
| Staff tries admin action | You do not have permission to perform this action |
| Duplicate email or phone | Entered data is already in use |
| Resource deletion blocked | Cannot delete this resource as it is linked to active trips |
| Ad campaign payment unsuccessful | Campaign creation aborted |