Cursor rule

1---
2description: Role-based access control (RBAC) patterns and implementations for POS System
3globs: **/components/**,**/api/**,**/routes/**
4---
5 
6# Role-Based Access Control (RBAC) Patterns
7 
8## Role Definitions
9 
10### Available Roles
11```typescript
12type UserRole = 'admin' | 'manager' | 'server' | 'counter' | 'kitchen'
13```
14 
15### Role Capabilities
16- **admin**: Full system access, can switch to any interface
17- **manager**: Business operations, reports, staff oversight
18- **server**: Dine-in order creation only
19- **counter**: All order types + payment processing
20- **kitchen**: Order preparation and status updates
21 
22## Frontend Role Routing
23 
24### Main Router Pattern
25```typescript
26// RoleBasedLayout.tsx
27export function RoleBasedLayout({ user }: { user: User }) {
28  // Admin gets AdminLayout with all interfaces
29  if (user.role === 'admin') {
30    return <AdminLayout user={user} />
31  }
32  
33  // Other roles get specific interfaces
34  switch (user.role) {
35    case 'server': return <ServerInterface />
36    case 'counter': return <CounterInterface />
37    case 'kitchen': return <KitchenLayout user={user} />
38    default: return <POSLayout user={user} />
39  }
40}
41```
42 
43### Navigation Access Control
44```typescript
45// AdminLayout.tsx - Admin can access all interfaces
46const adminSections = [
47  { id: 'dashboard', label: 'Dashboard' },
48  { id: 'pos', label: 'General POS' },        // Full POS access
49  { id: 'server', label: 'Server Interface' }, // Server view
50  { id: 'counter', label: 'Counter/Checkout' }, // Counter view
51  { id: 'kitchen', label: 'Kitchen Display' }   // Kitchen view
52  // + admin-only sections
53]
54```
55 
56## Backend API Role Restrictions
57 
58### Route Groups by Role
59```go
60// routes.go pattern
61func setupRoutes(router *gin.Engine) {
62    api := router.Group("/api/v1")
63    
64    // Public routes
65    api.POST("/auth/login", handlers.Login)
66    
67    // Protected routes
68    protected := api.Group("", middleware.RequireAuth)
69    
70    // Admin only
71    admin := protected.Group("/admin", middleware.RequireRole("admin"))
72    admin.GET("/users", handlers.GetUsers)
73    admin.POST("/users", handlers.CreateUser)
74    
75    // Server only
76    server := protected.Group("/server", middleware.RequireRole("server"))
77    server.POST("/orders", handlers.CreateDineInOrder) // Restricted to dine_in
78    
79    // Counter access
80    counter := protected.Group("/counter", middleware.RequireRoles("counter", "admin"))
81    counter.POST("/orders", handlers.CreateCounterOrder) // All order types
82    counter.POST("/orders/:id/payments", handlers.ProcessPayment)
83}
84```
85 
86### Role-Specific Endpoints
87```typescript
88// API Client role-specific methods
89class APIClient {
90  // Admin-only endpoints
91  async getUsers(): Promise<APIResponse<User[]>> {
92    return this.request({ method: 'GET', url: '/admin/users' });
93  }
94  
95  // Server-specific (dine-in only)
96  async createServerOrder(order: CreateOrderRequest): Promise<APIResponse<Order>> {
97    return this.request({ method: 'POST', url: '/server/orders', data: order });
98  }
99  
100  // Counter-specific (all order types + payments)
101  async createCounterOrder(order: CreateOrderRequest): Promise<APIResponse<Order>> {
102    return this.request({ method: 'POST', url: '/counter/orders', data: order });
103  }
104  
105  async processCounterPayment(orderId: string, payment: ProcessPaymentRequest): Promise<APIResponse<Payment>> {
106    return this.request({ method: 'POST', url: `/counter/orders/${orderId}/payments`, data: payment });
107  }
108}
109```
110 
111## Component-Level Access Control
112 
113### Conditional Rendering by Role
114```typescript
115// Show admin-only features
116{user.role === 'admin' && (
117  <Button onClick={() => navigate('/admin')}>
118    Admin Dashboard
119  </Button>
120)}
121 
122// Show based on multiple roles
123{['admin', 'manager'].includes(user.role) && (
124  <ReportsSection />
125)}
126```
127 
128### Form Restrictions
129```typescript
130// ServerInterface.tsx - Only dine-in orders
131const ServerInterface = () => {
132  const createOrderMutation = useMutation({
133    mutationFn: (order: CreateOrderRequest) => {
134      // Force dine_in type for servers
135      return apiClient.createServerOrder({
136        ...order,
137        order_type: 'dine_in'
138      })
139    }
140  })
141  
142  // Hide takeout/delivery options in UI
143  const availableOrderTypes = ['dine_in'] // Only option for servers
144}
145```
146 
147## Database Role Validation
148 
149### User Schema
150```sql
151-- users table with role enum
152CREATE TYPE user_role AS ENUM ('admin', 'manager', 'server', 'counter', 'kitchen');
153 
154ALTER TABLE users ADD COLUMN role user_role NOT NULL DEFAULT 'server';
155```
156 
157### Sample Role Data
158```sql
159-- Seed data with all roles
160INSERT INTO users (username, email, password_hash, first_name, last_name, role) VALUES
161('admin', 'admin@pos.com', '$2b$10$...', 'Admin', 'User', 'admin'),
162('server1', 'server1@pos.com', '$2b$10$...', 'Sarah', 'Smith', 'server'),
163('counter1', 'counter1@pos.com', '$2b$10$...', 'Lisa', 'Davis', 'counter'),
164('kitchen1', 'kitchen@pos.com', '$2b$10$...', 'Chef', 'Williams', 'kitchen');
165```
166 
167## Authentication Flow
168 
169### Login Process
170```typescript
171// login.tsx
172const loginMutation = useMutation({
173  mutationFn: async (credentials: LoginRequest) => {
174    const response = await apiClient.login(credentials)
175    return response
176  },
177  onSuccess: (data) => {
178    if (data.success && data.data) {
179      // Store user info with role
180      apiClient.setAuthToken(data.data.token)
181      localStorage.setItem('pos_user', JSON.stringify(data.data.user))
182      router.navigate({ to: '/' })
183    }
184  }
185})
186```
187 
188### Route Protection
189```typescript
190// index.tsx
191function HomePage() {
192  const [user, setUser] = useState<User | null>(null)
193  
194  useEffect(() => {
195    const storedUser = localStorage.getItem('pos_user')
196    if (storedUser) {
197      setUser(JSON.parse(storedUser))
198    }
199  }, [])
200  
201  // Redirect if not authenticated
202  if (!apiClient.isAuthenticated() || !user) {
203    return <Navigate to="/login" />
204  }
205  
206  // Role-based routing
207  return <RoleBasedLayout user={user} />
208}
209```
210 
211## Security Best Practices
212 
213### Frontend Security
214- Never trust frontend role checks alone
215- Always validate roles on backend
216- Store minimal user data in localStorage
217- Clear auth on logout
218 
219### Backend Security
220- Use middleware for role validation
221- Check roles on every protected endpoint
222- Log access attempts for audit
223- Implement proper session management
224 
225### Error Handling
226```typescript
227// Handle role access errors gracefully
228onError: (error: any) => {
229  if (error.status === 403) {
230    alert('Access denied: Insufficient permissions')
231  } else {
232    alert(`Error: ${error.message}`)
233  }
234}
235```