inventory/docs/PERMISSIONS.md

# Permission System Documentation

This document outlines the permission system implemented in the Inventory Manager application.

## Permission Structure

Permissions follow this naming convention:

- Page access: `access:{page_name}`
- Settings sections: `settings:{section_name}`
- Admin features: `admin:{feature}`

Examples:
- `access:products` - Can access the Products page
- `settings:user_management` - Can access User Management settings
- `admin:debug` - Can see debug information

## Permission Components

### PermissionGuard

The core component that conditionally renders content based on permissions.

```tsx
<PermissionGuard 
  permission="settings:user_management"
  fallback={<p>No permission</p>}
>
  <button>Manage Users</button>
</PermissionGuard>
```

Options:
- `permission`: Single permission code
- `anyPermissions`: Array of permissions (ANY match grants access)
- `allPermissions`: Array of permissions (ALL required)
- `adminOnly`: For admin-only sections
- `page`: Page name (checks `access:{page}` permission)
- `fallback`: Content to show if permission check fails

### PermissionProtectedRoute

Protects entire pages based on page access permissions.

```tsx
<Route path="/products" element={
  <PermissionProtectedRoute page="products">
    <Products />
  </PermissionProtectedRoute>
} />
```

### ProtectedSection

Protects sections within a page based on action permissions.

```tsx
<ProtectedSection page="products" action="create">
  <button>Add Product</button>
</ProtectedSection>
```

### PermissionButton

Button that automatically handles permissions.

```tsx
<PermissionButton 
  page="products" 
  action="create"
  onClick={handleCreateProduct}
>
  Add Product
</PermissionButton>
```

### SettingsSection

Specific component for settings with built-in permission checks.

```tsx
<SettingsSection
  title="System Settings"
  description="Configure global settings"
  permission="settings:global"
>
  {/* Settings content */}
</SettingsSection>
```

## Permission Hooks

### usePermissions

Core hook for checking any permission.

```tsx
const { hasPermission, hasPageAccess, isAdmin } = usePermissions();
if (hasPermission('settings:user_management')) {
  // Can access user management
}
```

### usePagePermission

Specialized hook for page-level permissions.

```tsx
const { canView, canCreate, canEdit, canDelete } = usePagePermission('products');
if (canView()) {
  // Can view products
}
```

## Database Schema

Permissions are stored in the database:
- `permissions` table: Stores all available permissions
- `user_permissions` junction table: Maps permissions to users

Admin users automatically have all permissions.

## Implemented Permission Codes

### Page Access Permissions
| Code | Description |
|------|-------------|
| `access:dashboard` | Access to Dashboard page |
| `access:overview` | Access to Overview page |
| `access:products` | Access to Products page |
| `access:categories` | Access to Categories page |
| `access:brands` | Access to Brands page |
| `access:vendors` | Access to Vendors page |
| `access:purchase_orders` | Access to Purchase Orders page |
| `access:analytics` | Access to Analytics page |
| `access:forecasting` | Access to Forecasting page |
| `access:import` | Access to Import page |
| `access:settings` | Access to Settings page |
| `access:chat` | Access to Chat Archive page |

### Settings Permissions
| Code | Description |
|------|-------------|
| `settings:global` | Access to Global Settings section |
| `settings:products` | Access to Product Settings section |
| `settings:vendors` | Access to Vendor Settings section |
| `settings:data_management` | Access to Data Management settings |
| `settings:calculation_settings` | Access to Calculation Settings |
| `settings:library_management` | Access to Image Library Management |
| `settings:performance_metrics` | Access to Performance Metrics |
| `settings:prompt_management` | Access to AI Prompt Management |
| `settings:stock_management` | Access to Stock Management |
| `settings:templates` | Access to Template Management |
| `settings:user_management` | Access to User Management |

### Admin Permissions
| Code | Description |
|------|-------------|
| `admin:debug` | Can see debug information and features |

## Implementation Examples

### Page Protection

In `App.tsx`:
```tsx
<Route path="/products" element={
  <PermissionProtectedRoute page="products">
    <Products />
  </PermissionProtectedRoute>
} />
```

### Component Level Protection

```tsx
const { hasPermission } = usePermissions();

function handleAction() {
  if (!hasPermission('settings:user_management')) {
    toast.error("You don't have permission");
    return;
  }
  // Action logic
}
```

### UI Element Protection

```tsx
<PermissionGuard permission="settings:user_management">
  <button onClick={handleManageUsers}>
    Manage Users
  </button>
</PermissionGuard>
```

## Notes

- **Page Access**: These permissions control which pages a user can navigate to
- **Settings Access**: These permissions control access to different sections within the Settings page
- **Admin Features**: Special permissions for administrative functions
- **CRUD Operations**: The application currently focuses on viewing and managing data rather than creating/editing/deleting individual records
- **User Management**: User CRUD operations are handled through the settings interface rather than dedicated user management pages