make the booking in many steps

2026-06-29 08:54:41 -04:00
parent ae10f5272f
commit 3d6607e6c8
20 changed files with 3894 additions and 836 deletions
@@ -0,0 +1,775 @@
+# RentalDriveGo Dashboard Menu and Subscription Entitlements Plan
+
+## Document status
+
+- **Purpose:** Implementation plan only
+- **Source code changes:** None
+- **Target applications:** Dashboard, Admin, API, Database, Shared i18n package
+- **Primary objective:** Make the initial dashboard sidebar match the approved seven-item menu while allowing platform administrators to control advanced modules by subscription plan.
+- **Localization objective:** Provide one consistent terminology system for English (`en`), French (`fr`), and Arabic (`ar`), including true RTL behavior for Arabic.
+
+---
+
+## 1. Approved baseline sidebar
+
+The default owner sidebar must contain exactly these items, in this order:
+
+| Order | Menu item | System key | Route |
+|---:|---|---|---|
+| 10 | Dashboard | `dashboard` | `/` |
+| 20 | Reservations | `reservations` | `/reservations` |
+| 30 | Fleet | `fleet` | `/fleet` |
+| 40 | Customers | `customers` | `/customers` |
+| 50 | Reports | `reports` | `/reports` |
+| 60 | Billing | `billing` | `/billing` |
+| 70 | Settings | `settings` | `/settings` |
+
+The existing sidebar styling, layout, branding, theme controls, language controls, responsive behavior, and RTL behavior must remain unchanged.
+
+---
+
+## 2. Advanced subscription modules
+
+The following existing modules will remain available as configurable advanced features:
+
+- Online Reservations
+- Offers
+- Team
+- Contracts
+- Notifications
+- Reviews
+- Complaints
+
+Initial entitlement proposal:
+
+| Module | STARTER | GROWTH | PRO |
+|---|:---:|:---:|:---:|
+| Dashboard | Yes | Yes | Yes |
+| Reservations | Yes | Yes | Yes |
+| Fleet | Yes | Yes | Yes |
+| Customers | Yes | Yes | Yes |
+| Reports | Yes | Yes | Yes |
+| Billing | Yes | Yes | Yes |
+| Settings | Yes | Yes | Yes |
+| Online Reservations | No | Yes | Yes |
+| Offers | No | Yes | Yes |
+| Team | No | Yes | Yes |
+| Contracts | No | Yes | Yes |
+| Notifications | No | Yes | Yes |
+| Reviews | No | No | Yes |
+| Complaints | No | No | Yes |
+
+The platform administrator may later change the advanced-module assignments. Core baseline modules remain protected.
+
+---
+
+## 3. Multilingual terminology and translation contract
+
+All menu items must use immutable system keys and shared translation keys. Application logic must never depend on translated labels.
+
+### 3.1 Approved menu terminology
+
+| System key | Translation key | English (`en`) | French (`fr`) | Arabic (`ar`) |
+|---|---|---|---|---|
+| `dashboard` | `navigation.dashboard` | Dashboard | Tableau de bord | لوحة التحكم |
+| `reservations` | `navigation.reservations` | Reservations | Réservations | الحجوزات |
+| `fleet` | `navigation.fleet` | Fleet | Flotte | الأسطول |
+| `customers` | `navigation.customers` | Customers | Clients | العملاء |
+| `reports` | `navigation.reports` | Reports | Rapports | التقارير |
+| `billing` | `navigation.billing` | Billing | Facturation | الفوترة |
+| `settings` | `navigation.settings` | Settings | Paramètres | الإعدادات |
+| `online-reservations` | `navigation.onlineReservations` | Online Reservations | Réservations en ligne | الحجوزات عبر الإنترنت |
+| `offers` | `navigation.offers` | Offers | Offres | العروض |
+| `team` | `navigation.team` | Team | Équipe | الفريق |
+| `contracts` | `navigation.contracts` | Contracts | Contrats | العقود |
+| `notifications` | `navigation.notifications` | Notifications | Notifications | الإشعارات |
+| `reviews` | `navigation.reviews` | Reviews | Avis | التقييمات |
+| `complaints` | `navigation.complaints` | Complaints | Réclamations | الشكاوى |
+
+These translations are the approved product glossary. Core labels are protected and must not be edited casually from the Admin application.
+
+### 3.2 Shared localization architecture
+
+Recommended structure:
+
+```text
+packages/i18n/
+├── locales/
+│   ├── en.json
+│   ├── fr.json
+│   └── ar.json
+├── glossary.ts
+├── validation.ts
+└── index.ts
+```
+
+Dashboard, Admin, and any future storefront or mobile application must consume the same translation package. Independent translation copies are prohibited because they create terminology drift.
+
+Example menu definition:
+
+```ts
+{
+  systemKey: "reservations",
+  labelKey: "navigation.reservations",
+  route: "/reservations"
+}
+```
+
+The database and API may store `systemKey` and `labelKey`. They must not use translated text as an identifier.
+
+### 3.3 Translation publishing rules
+
+- Core menu translations are locked.
+- Custom modules require English, French, and Arabic labels before publishing.
+- A label override must provide all three languages.
+- Empty translations are rejected.
+- Unknown or obsolete translation keys are rejected.
+- Translation variables must match across all languages.
+- Administrators may configure plan access, roles, order, status, and icons without modifying protected terminology.
+- Only `SUPER_ADMIN` may approve changes to the shared product glossary.
+
+### 3.4 Fallback behavior
+
+The application fallback order is:
+
+```text
+Requested locale
+→ English fallback in local development only
+→ Validation or build failure before production deployment
+```
+
+Production must not silently display English labels inside French or Arabic interfaces.
+
+### 3.5 Arabic RTL requirements
+
+When Arabic is selected:
+
+```html
+<html lang="ar" dir="rtl">
+```
+
+When English or French is selected:
+
+```html
+<html lang="en" dir="ltr">
+<html lang="fr" dir="ltr">
+```
+
+Arabic verification must include:
+
+- Sidebar alignment
+- Menu indentation
+- Chevron direction
+- Breadcrumb order
+- Form and modal layout
+- Text alignment
+- Number formatting
+- Date formatting
+- Currency formatting
+- Mobile navigation behavior
+
+Only directional icons should be mirrored. Neutral icons such as Settings, Billing, Fleet, and Reports must keep their original orientation.
+
+### 3.6 Locale-aware formatting
+
+Dates, numbers, percentages, and currencies must use locale-aware formatting rather than translated strings.
+
+```ts
+new Intl.DateTimeFormat(locale).format(date);
+
+new Intl.NumberFormat(locale, {
+  style: "currency",
+  currency: "MAD",
+}).format(amount);
+```
+
+Stored values remain locale-independent.
+
+---
+
+## 4. Authorization rule
+
+A module is available only when all required conditions are true:
+
+```text
+Module is globally enabled
+AND module is included in the company's subscription plan
+AND the company has not disabled the module
+AND the employee role is allowed to use the module
+AND the subscription status permits access
+```
+
+Company-level settings may disable or reorder entitled modules. They must not unlock a module outside the active subscription plan.
+
+Sidebar visibility alone is not authorization. The API and direct routes must enforce the same entitlement rules.
+
+---
+
+## 5. Role behavior
+
+Subscription access and employee-role access remain separate.
+
+Recommended baseline policy:
+
+| Module | OWNER | MANAGER | AGENT |
+|---|:---:|:---:|:---:|
+| Dashboard | Yes | Yes | Yes |
+| Reservations | Yes | Yes | Yes |
+| Fleet | Yes | Yes | Yes |
+| Customers | Yes | Yes | Yes |
+| Reports | Yes | Yes | Optional |
+| Billing | Yes | Optional | No |
+| Settings | Yes | Optional | No |
+
+The final role matrix must be approved before implementation. The screenshot represents the owner-level default menu, not automatic access for every employee.
+
+---
+
+## 6. Subscription-status behavior
+
+| Subscription status | Menu behavior |
+|---|---|
+| `ACTIVE` | Full entitled menu |
+| `TRIALING` | Full entitled menu |
+| `PAST_DUE` | Configurable restricted or read-only behavior |
+| `SUSPENDED` | Recovery menu only |
+| `EXPIRED` | Recovery menu only |
+| `CANCELLED` | Recovery menu only |
+| Missing subscription | Onboarding or recovery menu only |
+
+Recommended recovery menu:
+
+- Dashboard
+- Billing
+- Settings
+
+This keeps account recovery possible without exposing paid operational modules.
+
+---
+
+## 7. Data model
+
+### 7.1 Menu module catalog
+
+Each module should define:
+
+```text
+id
+systemKey
+defaultLabel
+localizedLabels
+routeOrUrl
+icon
+defaultOrder
+parentId
+minimumRole or allowedRoles
+isRequired
+isGloballyEnabled
+createdAt
+updatedAt
+```
+
+### 7.2 Subscription-plan entitlement
+
+```text
+plan
+menuItemId
+enabled
+displayOrder
+```
+
+### 7.3 Company override
+
+```text
+companyId
+menuItemId
+enabled
+displayOrder
+optionalLabelOverride
+optionalIconOverride
+```
+
+### 7.4 Audit record
+
+```text
+actorId
+action
+targetType
+targetId
+before
+after
+reason
+createdAt
+```
+
+---
+
+## 8. Implementation phases
+
+## Phase 1: Confirm the menu contract
+
+### Work
+
+- Approve the seven baseline items.
+- Approve the initial advanced-module plan matrix.
+- Approve the employee-role matrix.
+- Define protected system fields.
+- Define subscription-status behavior.
+- Confirm whether companies may customize labels and icons.
+- Approve the English, French, and Arabic terminology glossary.
+- Confirm which translation fields are protected.
+
+### Deliverable
+
+A frozen entitlement matrix and protected-module contract.
+
+### Exit criteria
+
+- No unresolved module ownership questions.
+- No unresolved role-access questions.
+- No unresolved downgrade behavior.
+- No unresolved translation or RTL terminology decisions.
+
+---
+
+## Phase 2: Database migration and seed
+
+### Work
+
+- Create or update the menu catalog.
+- Seed the seven baseline modules.
+- Assign the baseline modules explicitly to `STARTER`, `GROWTH`, and `PRO`.
+- Seed the advanced-module plan assignments.
+- Normalize menu order.
+- Create company-override records only where required.
+- Add unique constraints for `systemKey`.
+- Add audit support if missing.
+- Detect and report existing assignments that exceed subscription access.
+- Make the migration idempotent.
+
+### Deliverable
+
+Database migration, seed, and rollback procedure.
+
+### Exit criteria
+
+- Re-running the migration causes no duplicates.
+- No navigable module relies on implicit plan access.
+- Existing companies receive deterministic menus.
+
+---
+
+## Phase 3: Central entitlement resolver in the API
+
+### Work
+
+Create one canonical entitlement service used by both menu generation and API authorization.
+
+Suggested responsibility:
+
+```ts
+resolveModuleAccess({
+  companyId,
+  employeeId,
+  systemKey,
+})
+```
+
+The resolver must evaluate:
+
+- Global module state
+- Active subscription plan
+- Subscription status
+- Explicit plan entitlement
+- Company override
+- Employee role
+- Required recovery access
+
+### Deliverable
+
+A reusable entitlement service with unit tests.
+
+### Exit criteria
+
+- Menu generation and API guards use the same decision logic.
+- Company overrides cannot grant higher-plan access.
+- Missing plan assignments mean unavailable.
+
+---
+
+## Phase 4: Harden menu-management API
+
+### Work
+
+- Protect required modules.
+- Prevent ordinary administrators from changing:
+  - `systemKey`
+  - Core routes
+  - Required status
+  - Core plan assignments
+  - Core role assignments
+  - Parent relationships
+- Validate unique system keys.
+- Prevent circular parent relationships.
+- Require explicit plan selection for new navigable modules.
+- Record all changes in the audit log.
+- Require a reason and expiration for exceptional plan overrides.
+- Add clear validation errors.
+
+### Deliverable
+
+Secure admin menu endpoints and boundary tests.
+
+### Exit criteria
+
+- Required modules cannot be weakened through general update endpoints.
+- Invalid menu trees are rejected.
+- All entitlement-changing actions are auditable.
+
+---
+
+## Phase 5: Enforce advanced-module API access
+
+### Work
+
+Apply reusable entitlement middleware to advanced modules:
+
+```ts
+requireModuleEntitlement("online-reservations")
+requireModuleEntitlement("offers")
+requireModuleEntitlement("team")
+requireModuleEntitlement("contracts")
+requireModuleEntitlement("notifications")
+requireModuleEntitlement("reviews")
+requireModuleEntitlement("complaints")
+```
+
+Also enforce baseline role restrictions where applicable.
+
+### Deliverable
+
+Server-side module protection across all relevant routes.
+
+### Exit criteria
+
+- Entering a hidden route manually does not bypass access.
+- Calling an advanced API directly does not bypass the subscription.
+- Unauthorized responses are consistent and testable.
+
+---
+
+## Phase 6: Refine the Admin menu-management interface
+
+### Work
+
+Create a clear plan matrix as the primary management view:
+
+```text
+Module | STARTER | GROWTH | PRO | Roles | Enabled | Order
+```
+
+Add:
+
+- Plan tabs or columns
+- Required-item locks
+- Role controls
+- Ordering controls
+- Company and role preview
+- Subscription-status preview
+- Audit history
+- Warning before removing a module used by active companies
+- Supported icon selector instead of unrestricted icon text
+- Advanced configuration restricted to `SUPER_ADMIN`
+
+### Deliverable
+
+A safer, plan-oriented administration interface.
+
+### Exit criteria
+
+- An administrator can configure advanced subscriptions without editing routes or system keys.
+- The preview matches the actual dashboard menu.
+- Protected items are visibly locked.
+
+---
+
+## Phase 7: Update the Dashboard sidebar
+
+### Work
+
+- Replace the large hardcoded fallback with the seven approved baseline items.
+- Preserve the exact approved order.
+- Keep the API-generated menu as the source of truth.
+- Distinguish:
+  - Loading state
+  - API failure
+  - Successful empty response
+  - Successful populated response
+- Treat a successful empty response as intentional.
+- Never restore advanced modules after an empty response.
+- Use a role-aware safe fallback only when the API genuinely fails.
+- Remove the separate Subscription item from the initial menu.
+- Keep subscription access available through Billing or Settings.
+- Preserve visual design and unrelated behavior.
+
+### Deliverable
+
+A deterministic sidebar matching the approved design.
+
+### Exit criteria
+
+- A `STARTER` owner sees exactly seven items.
+- No menu flicker exposes restricted modules.
+- RTL, mobile, theme, and localization behavior remain intact.
+
+---
+
+## Phase 8: Route guards in Dashboard and Admin
+
+### Work
+
+- Align frontend route guards with API entitlements.
+- Show a clear access-denied or upgrade-required screen.
+- Do not silently redirect users to unrelated pages.
+- Prevent stale cached menus after plan or role changes.
+- Invalidate menu data after admin updates.
+
+### Deliverable
+
+Consistent frontend route protection.
+
+### Exit criteria
+
+- Hidden modules cannot be opened by entering their URL.
+- Downgrades remove route access without requiring a new login.
+- Upgrade messaging is explicit and accurate.
+
+---
+
+## Phase 9: Implement shared localization validation
+
+### Work
+
+- Create or update the shared `packages/i18n` package.
+- Add the approved `en`, `fr`, and `ar` navigation keys.
+- Replace hardcoded menu labels in Dashboard and Admin with translation keys.
+- Validate that all locale files contain the same required keys.
+- Validate that interpolation variables match across languages.
+- Reject empty, unknown, and obsolete keys.
+- Add CI checks for translation completeness.
+- Add development logging for missing keys.
+- Ensure Arabic applies `lang="ar"` and `dir="rtl"` at the document root.
+- Verify locale-aware dates, numbers, and MAD currency formatting.
+- Prevent translated labels from being used in permissions, routes, plan assignments, or database lookups.
+
+### Deliverable
+
+Shared translation package, approved glossary, validation script, and CI enforcement.
+
+### Exit criteria
+
+- Every required English key exists in French and Arabic.
+- No navigation label is hardcoded in Dashboard or Admin.
+- Core glossary terms are protected.
+- Arabic uses true RTL layout.
+- Missing translations fail CI before deployment.
+
+---
+
+## Phase 10: Testing
+
+### API tests
+
+- Explicit plan assignment is required.
+- Company override cannot upgrade a plan.
+- Required items cannot be disabled by ordinary admins.
+- Suspended subscriptions receive only recovery access.
+- Role restrictions remain active.
+- Advanced APIs reject unauthorized requests.
+- Audit entries are created.
+
+### Localization tests
+
+- Every navigation key exists in English, French, and Arabic.
+- Core terminology matches the approved glossary exactly.
+- Missing or empty translations fail CI.
+- Interpolation variables match across locales.
+- Switching language does not change routes, permissions, subscription access, or system keys.
+- French labels do not overflow.
+- Arabic labels do not truncate.
+- Arabic sets `lang="ar"` and `dir="rtl"`.
+- Directional icons mirror correctly and neutral icons do not.
+- Dates, numbers, and MAD currency values format correctly by locale.
+
+### Dashboard tests
+
+- `STARTER` owner sees exactly seven items.
+- Approved order is preserved.
+- Empty successful response remains empty.
+- API failure uses only the safe fallback.
+- Advanced modules appear only when entitled.
+- Direct routes are blocked.
+- Mobile and desktop menus behave consistently.
+- EN, FR, and AR labels render correctly.
+- Arabic remains true RTL.
+
+### Admin tests
+
+- Plan toggles save correctly.
+- Locked modules cannot be modified.
+- Preview matches the generated employee menu.
+- Invalid parent relationships are rejected.
+- Removing a widely used entitlement produces a warning.
+- Audit history displays the change.
+
+### Deliverable
+
+Unit, integration, boundary, and end-to-end test coverage.
+
+---
+
+## Phase 11: Deployment and rollback
+
+### Deployment order
+
+1. Database migration and seed
+2. API entitlement resolver
+3. API route enforcement
+4. Admin management interface
+5. Dashboard sidebar and route guards
+6. End-to-end verification
+
+### Rollback requirements
+
+- Database rollback or compensating migration
+- Feature flag for new entitlement enforcement
+- Ability to restore previous menu assignments
+- Audit record of rollback actions
+- No destructive deletion of historical menu configuration
+
+### Exit criteria
+
+- Production smoke tests pass.
+- Existing companies retain expected access.
+- No restricted module is exposed.
+- Recovery access remains available.
+
+---
+
+## 9. File-level work areas
+
+Expected targets, subject to repository verification:
+
+### Dashboard
+
+```text
+src/components/layout/Sidebar.tsx
+src/components/layout/DashboardAccessGuard.tsx
+src/components/layout/Sidebar.boundary.test.ts
+src/components/layout/DashboardAccessGuard.boundary.test.ts
+```
+
+### Admin
+
+```text
+src/app/dashboard/menu-management/page.tsx
+related menu-management components
+related API client modules
+related tests
+```
+
+### API
+
+```text
+src/modules/menu/menu.service.ts
+src/modules/menu/menu.entitlement.ts
+src/middleware/requireModuleEntitlement.ts
+menu administration routes
+advanced-module routes
+related unit, boundary, and E2E tests
+```
+
+### Database
+
+```text
+Prisma schema
+menu seed
+subscription entitlement seed
+migration
+rollback or repair script
+```
+
+### Shared i18n package
+
+```text
+packages/i18n/locales/en.json
+packages/i18n/locales/fr.json
+packages/i18n/locales/ar.json
+packages/i18n/glossary.ts
+packages/i18n/validation.ts
+packages/i18n/index.ts
+related localization tests
+```
+
+No file should be changed until the repository structure is verified against these expected paths.
+
+---
+
+## 10. Non-goals
+
+This milestone will not:
+
+- Redesign the sidebar visually.
+- Change dashboard branding.
+- Change the theme system.
+- Change localization architecture.
+- Replace existing pages.
+- Introduce machine translation at runtime.
+- Allow translated labels to control routes, permissions, or entitlements.
+- Add unrelated subscription billing features.
+- Grant tenant administrators permission to alter platform routes.
+- Treat hidden navigation as sufficient security.
+
+---
+
+## 11. Definition of done
+
+The implementation is complete only when:
+
+- The initial owner sidebar contains exactly the seven approved items.
+- The order matches the approved design.
+- Advanced items are explicitly assigned by subscription plan.
+- Company overrides cannot bypass subscription entitlements.
+- Employee roles remain enforced.
+- Subscription status affects access.
+- Direct frontend routes are protected.
+- Direct API calls are protected.
+- Required system items cannot be weakened by ordinary administrators.
+- Admin previews match actual dashboard results.
+- All changes are audited.
+- Existing visual behavior remains unchanged.
+- English, French, and Arabic use the approved shared terminology.
+- Arabic uses true RTL behavior.
+- Missing or inconsistent translations fail CI.
+- Routes, permissions, subscriptions, and API logic use immutable system keys rather than translated labels.
+- Tests pass across Dashboard, Admin, API, and Database.
+- Deployment and rollback procedures are documented.
+
+---
+
+## 12. Execution gate
+
+Implementation must not begin until these items are approved:
+
+1. Baseline seven-item menu
+2. Advanced-module plan matrix
+3. Employee-role matrix
+4. Subscription-status policy
+5. Company customization limits
+6. Required-item protection rules
+7. Database migration strategy
+8. Approved EN/FR/AR glossary
+9. Translation fallback and CI policy
+10. Arabic RTL acceptance criteria
+
+This prevents the usual ritual of coding first and discovering the business rules afterward.