# 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}`
- Actions: `{action}:{resource}`

Examples:
- `access:products` - Can access the Products page
- `create:products` - Can create new products
- `edit:users` - Can edit user accounts

## Permission Components

### PermissionGuard

The core component that conditionally renders content based on permissions.

```tsx
<PermissionGuard 
  permission="create:products"
  fallback={<p>No permission</p>}
>
  <button>Create Product</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="edit:system_settings"
>
  {/* Settings content */}
</SettingsSection>
```

## Permission Hooks

### usePermissions

Core hook for checking any permission.

```tsx
const { hasPermission, hasPageAccess, isAdmin } = usePermissions();
if (hasPermission('delete:products')) {
  // Can delete products
}
```

### usePagePermission

Specialized hook for page-level permissions.

```tsx
const { canView, canCreate, canEdit, canDelete } = usePagePermission('products');
if (canEdit()) {
  // Can edit 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.

## Common Permission Codes

| Code | Description |
|------|-------------|
| `access:dashboard` | Access to Dashboard page |
| `access:products` | Access to Products page |
| `create:products` | Create new products |
| `edit:products` | Edit existing products |
| `delete:products` | Delete products |
| `view:users` | View user accounts |
| `edit:users` | Edit user accounts |
| `manage:permissions` | Assign permissions to users |

## Implementation Examples

### Page Protection

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

### Component Level Protection

```tsx
const { canEdit } = usePagePermission('products');

function handleEdit() {
  if (!canEdit()) {
    toast.error("You don't have permission");
    return;
  }
  // Edit logic
}
```

### UI Element Protection

```tsx
<PermissionButton 
  page="products" 
  action="delete"
  onClick={handleDelete}
>
  Delete
</PermissionButton>
```