Implement three-layer permission system with URY roles and capabilities

[esafwan]

Summary

Introduces a comprehensive three-layer permission system for URY consisting of:

1. Capability Layer — Fine-grained capabilities (e.g., users.create, orders.view_all) checked throughout the application
2. URY Role Layer — Named roles (e.g., URY Admin, URY Manager, URY Cashier) that own sets of capabilities
3. Frappe Role Layer — Backing Frappe roles for DocType-level enforcement and desk access control

Key Changes

Backend (Python/Frappe)

• ury/ury/permissions.py — Core permission engine with:

  • Capability catalogue (50+ fine-grained capabilities)
  • URY role definitions with default capability sets
  • Role-to-Frappe role mapping for desk access control
  • has_capability() and get_user_capabilities() functions for runtime checks

• ury/ury/api/permissions_api.py — Whitelisted REST endpoints:

  • User management: get_users(), invite_user(), update_user_role(), set_user_enabled()
  • Role management: get_ury_roles(), create_ury_role(), update_ury_role()
  • All endpoints guarded with _require(capability) checks

• New DocTypes:

  • URY Role — Stores role definitions with capability assignments
  • URY User Role — Links users to URY roles with enable/disable toggle
  • URY Role Permission — Child table for capability assignments

• ury/install.py — Idempotent role seeding:

  • Creates Frappe backing roles for all URY roles
  • Seeds system URY roles with default capability sets
  • Assigns Administrator the URY Admin role
  • Migrates existing users to appropriate roles
  • Runs on both after_install and after_migrate hooks

Frontend (React/TypeScript)

• pos/src/lib/permissions-api.ts — TypeScript API client:

  • Type definitions for MeResponse, URYUser, URYRole, URYRoleCapability
  • Async functions wrapping backend endpoints with error handling

• pos/src/contexts/PermissionsContext.tsx — React context provider:

  • Exposes usePermissions() hook for capability checks
  • hasCapability(capability) method for conditional rendering/logic
  • Auto-refreshes on mount

• pos/src/pages/admin/UsersPage.tsx — User management UI:

  • List all users with search and status filtering
  • Invite new users with role assignment
  • Change user roles via dropdown
  • Enable/disable users with toggle
  • Role-based color coding for visual distinction
  • Permission-gated actions (only visible to users with users.manage or users.create)

Notable Implementation Details

• Capability-first design: All API endpoints check capabilities, not just Frappe roles
• Desk access control: Roles marked with desk_access=1 get Frappe desk access; others are frontend-only
• Idempotent seeding: Role creation is safe to run on every migrate without duplicates
• Frappe role sync: URYUserRole.on_update() automatically syncs Frappe roles when URY role changes
• Cache busting: Role changes invalidate user capability caches for immediate effect
• 15 system roles pre-configured with role-specific capability sets (Admin, Ops Admin, Manager, Director, Purchase Manager, Sales Manager, Accountant, Analyst, Captain, Servicer, Cashier, Chef, Store Manager, Store Admin, Store Accountant)

https://claude.ai/code/session_01TZ1yuzhjsj7276Qm3nZESS