• Mahmoud Aglan's avatar
    fix(auth): resolve route/menu/role permission drift causing phantom 403s · d39d9293
    Mahmoud Aglan authored
    Users saw sidebar links that returned 403. Root cause was drift between four
    independently-authored declaration sets that nothing reconciles: the permission
    catalogue (bootstrap.php), the route gate (Routes.php), the menu gate
    (MenuRegistry) and the role grants (seeds).
    
    Route shadowing (Router::dispatch is first-match-wins over a sorted module glob):
    - GET /reports was declared by both Members and Reports; Members won and enforced
      member.reports while the sidebar gated on report.view_membership. Members'
      report routes moved to /members/reports/*.
    - GET /sports-dashboard[/export] was declared by three modules, so the dashboard
      index and its drill-downs were served by different modules. Disciplines ->
      /disciplines/dashboard, PlaygroundAdmin -> /playgrounds/dashboard[/export];
      /sports-dashboard is now wholly owned by SportsDashboard.
    - Members/Routes.php used unconstrained {id} in 15 routes, so /members/<anything>
      was swallowed by MemberController@show. Constrained to {id:\d+}, matching every
      other module. All 25 affected links updated.
    
    Gate alignment:
    - Six menu entries gated on a different permission than the route they link to
      (/members/search, /sports, /carnets, /rentals/entities,
      /notifications/templates, /reports).
    
    Authorization bypasses:
    - RetroactiveWizardController hardcoded a role_code = 'super_admin' query,
      throwing "هذه الأداة متاحة فقط لمدير النظام". Replaced with a registered
      member.retroactive permission enforced by the route and grantable via the
      Roles UI.
    - report_definitions.required_permission was stored and displayed but never
      checked, so report.view_membership was enough to open ANY report by code,
      including financial ones. Now enforced on view/export/print; the listing
      filters to what the viewer can actually run.
    
    Role grants (Phase_105_001, idempotent):
    - Closes the reported gaps for report_viewer, general_manager, receptionist,
      sports_officer, academy_manager and membership_director; grants the sports
      report keys to board_member/auditor so enforcing the per-report permission
      does not silently remove reports; revokes member.view/member.search from
      facilities_manager, who keeps bookings and reservations.
    
    Data correctness:
    - SaFinanceReportService read base_price from sa_pricing_rules, a facility
      booking table with neither that column nor activity_type, and derived revenue
      as headcount x a rate-card price. Now sums actual sa_registrations
      .registration_fee, matching how subscription and booking revenue are computed.
    
    Regression guard:
    - php cli.php permissions:audit reconciles all four declaration sets, reproduces
      the router's load order, and exits non-zero on drift. Run it after touching any
      Routes.php, menu block or role seed.
    
    Docs: new docs/architecture-maps/Authorization.md; cross-module authorization
    section added to DEPENDENCY-GRAPH.md.
    
    Note: the live DB was unreachable from the dev environment, so role grants were
    verified by replaying the seeds and schema came from migrations, not the live DB.
    PHPUnit is not installed locally; all changed files lint clean.
    Co-Authored-By: 's avatarClaude Opus 5 <noreply@anthropic.com>
    d39d9293