Admin View Locations List

1. What does this feature do? (High-Level Overview)

The Admin View Locations List gives administrators a centralized list of assigned locations and lets them update each location status for operational control. It is mainly used to keep location availability aligned with current business operations.

2. Who is this for? (Roles & Permissions)

• Users in Admin View: Can access the Locations List screen. The page is blocked outside Admin View.
• Users with manage_locations_access: See the Locations entry in the admin sidebar and can open this list through navigation.
• Users with update_locations: Can change a location status (Active, Paused, Inactive) from the row action menu.

3. Business Rules & Enforcements

• Admin View is required for this page. If a user tries to open the list while working in a regular location context, the app redirects to the dashboard home.
• The list is scoped to authorized locations. The UI requests the list with authorized_only=true, so users only see locations they are allowed to access.
• Inactive locations are included in this specific admin list. The UI also sends all=true, which keeps inactive records visible for management and reactivation workflows.
• Filtering and sorting are server-side. Name, city, and state filters, plus sort field/direction, are sent as query params and reapplied on each reload.
• Status changes are limited to valid values. The API accepts only active, stop (shown as Paused), or inactive.
• Status updates require explicit permission. The status endpoint is protected by update_locations permission checks.
• Status affects availability outside this screen.
  • active: selectable for login and location switching.
  • stop (Paused): visible in selection lists but not selectable.
  • inactive: removed from login/location-switch options.

4. UI Placement

1. Admin View > Main > Locations (/location/list) — Opens the Locations List.
2. Top filter bar — Search by name, city, and state.
3. Locations table — Name, email, city, state, status, and actions.
4. Status dropdown (Actions column) — Activate, Pause, or Deactivate.
5. Help icon in table header — Opens Location Status Guide modal.

5. How-To Guide (Step-by-Step)

Scenario A: Review current locations in admin mode

1. Switch to Admin View.
2. Open Locations from the sidebar.
3. Use the Search, City, and State filters to narrow results.
4. Review each row status badge (Active, Paused, or Inactive).
5. Use sorting and pagination controls to review larger lists.

Scenario B: Change a location status for operational control

1. In Admin View > Locations, find the target location.
2. Click the Status dropdown in that row.
3. Select Activate, Pause, or Deactivate.
4. Confirm the warning dialog.
5. Wait for the success message and verify the updated status badge in the table.

6. What happens if…? (Edge Cases / FAQ)

• Q: Why am I redirected when opening /location/list?

  • A: This screen is restricted to Admin View context. In location-scoped mode, the route guard redirects to dashboard home.

• Q: Why can a Paused location still appear in lists but cannot be selected at login?

  • A: Paused (stop) locations remain visible for management, but selection is blocked by login/location-switch behavior.

• Q: Why does status update fail for some admins?

  • A: The update endpoint requires update_locations. If the current role does not include that permission, the request is rejected.