diff --git a/docs/UI-IMPROVEMENTS-PLAN.md b/docs/UI-IMPROVEMENTS-PLAN.md new file mode 100644 index 0000000..97bc9d3 --- /dev/null +++ b/docs/UI-IMPROVEMENTS-PLAN.md @@ -0,0 +1,734 @@ +# Castle UI Improvements Plan + +**Date**: November 10, 2025 +**Status**: 📋 **Planning Document** +**Related**: ACCOUNT-SYNC-AND-PERMISSION-IMPROVEMENTS.md, PERMISSIONS-SYSTEM.md + +--- + +## Overview + +Enhance the Castle permissions UI to showcase new bulk permission management and account sync features, making admin tasks faster and more intuitive. + +--- + +## Current UI Assessment + +**What's Good:** +- ✅ Clean Quasar/Vue.js structure +- ✅ Three views: By User, By Account, Equity +- ✅ Basic grant/revoke functionality +- ✅ Good visual design with icons and colors +- ✅ Admin-only protection + +**What's Missing:** +- ❌ No bulk operations +- ❌ No permission analytics dashboard +- ❌ No permission templates/copying +- ❌ No account sync UI +- ❌ No user offboarding workflow +- ❌ No expiring permissions alerts + +--- + +## Proposed Enhancements + +### 1. Add "Analytics" Tab + +**Purpose**: Give admins visibility into permission usage + +**Features:** +- Total permissions count (by type) +- Permissions expiring soon (7 days) +- Most-permissioned accounts (top 10) +- Users with/without permissions +- Permission grant timeline chart + +**UI Mockup:** +``` +┌─────────────────────────────────────────────┐ +│ 📊 Permission Analytics │ +├─────────────────────────────────────────────┤ +│ │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ Total │ │ Expiring │ │ +│ │ 150 │ │ 5 (7 days) │ │ +│ │ Permissions │ │ │ │ +│ └──────────────┘ └──────────────┘ │ +│ │ +│ Permission Distribution │ +│ ┌────────────────────────────────────┐ │ +│ │ READ ██████ 50 (33%) │ │ +│ │ SUBMIT_EXPENSE ████████ 80 (53%) │ │ +│ │ MANAGE ████ 20 (13%) │ │ +│ └────────────────────────────────────┘ │ +│ │ +│ ⚠ī¸ Expiring Soon │ +│ ┌────────────────────────────────────┐ │ +│ │ alice on Expenses:Food (3 days) │ │ +│ │ bob on Income:Services (5 days) │ │ +│ └────────────────────────────────────┘ │ +│ │ +│ Top Accounts by Permissions │ +│ ┌────────────────────────────────────┐ │ +│ │ 1. Expenses:Food (25 permissions) │ │ +│ │ 2. Expenses:Accommodation (18) │ │ +│ │ 3. Income:Services (12) │ │ +│ └────────────────────────────────────┘ │ +└─────────────────────────────────────────────┘ +``` + +**Implementation:** +- New API endpoint: `GET /api/v1/admin/permissions/analytics` +- Client-side stats display with Quasar charts +- Auto-refresh every 30 seconds + +--- + +### 2. Bulk Permission Operations Menu + +**Purpose**: Enable admins to perform bulk operations efficiently + +**Features:** +- Bulk Grant (multiple users) +- Copy Permissions (template from user) +- Offboard User (revoke all) +- Close Account (revoke all on account) + +**UI Mockup:** +``` +┌─────────────────────────────────────────────┐ +│ 🔐 Permission Management │ +│ │ +│ [Grant Permission â–ŧ] [Bulk Operations â–ŧ] │ +│ │ +│ ┌──────────────────────────────────┐ │ +│ │ â€ĸ Bulk Grant to Multiple Users │ │ +│ │ â€ĸ Copy Permissions from User │ │ +│ │ â€ĸ Offboard User (Revoke All) │ │ +│ │ â€ĸ Close Account (Revoke All) │ │ +│ │ â€ĸ Sync Accounts from Beancount │ │ +│ └──────────────────────────────────┘ │ +└─────────────────────────────────────────────┘ +``` + +--- + +### 3. Bulk Grant Dialog + +**UI Mockup:** +``` +┌───────────────────────────────────────────┐ +│ đŸ‘Ĩ Bulk Grant Permission │ +├───────────────────────────────────────────┤ +│ │ +│ Select Users * │ +│ ┌────────────────────────────────────┐ │ +│ │ 🔍 Search users... │ │ +│ └────────────────────────────────────┘ │ +│ │ +│ Selected: alice, bob, charlie (3 users) │ +│ │ +│ Select Account * │ +│ ┌────────────────────────────────────┐ │ +│ │ Expenses:Food │ │ +│ └────────────────────────────────────┘ │ +│ │ +│ Permission Type * │ +│ ┌────────────────────────────────────┐ │ +│ │ Submit Expense │ │ +│ └────────────────────────────────────┘ │ +│ │ +│ Expires (Optional) │ +│ [2025-12-31 23:59:59] │ +│ │ +│ Notes (Optional) │ +│ [Q4 2025 food team members] │ +│ │ +│ ℹī¸ This will grant SUBMIT_EXPENSE │ +│ permission to 3 users on │ +│ Expenses:Food │ +│ │ +│ [Cancel] [Grant to 3 Users] │ +└───────────────────────────────────────────┘ +``` + +**Features:** +- Multi-select user dropdown +- Preview of operation before confirm +- Shows estimated time savings + +--- + +### 4. Copy Permissions Dialog + +**UI Mockup:** +``` +┌───────────────────────────────────────────┐ +│ 📋 Copy Permissions │ +├───────────────────────────────────────────┤ +│ │ +│ Copy From (Template User) * │ +│ ┌────────────────────────────────────┐ │ +│ │ alice (Experienced Coordinator) │ │ +│ └────────────────────────────────────┘ │ +│ │ +│ 📊 alice has 5 permissions: │ +│ â€ĸ Expenses:Food (Submit Expense) │ +│ â€ĸ Expenses:Food:Groceries (Submit) │ +│ â€ĸ Income:Services (Read) │ +│ â€ĸ Assets:Cash (Read) │ +│ â€ĸ Expenses:Utilities (Submit) │ +│ │ +│ Copy To (New User) * │ +│ ┌────────────────────────────────────┐ │ +│ │ bob (New Hire) │ │ +│ └────────────────────────────────────┘ │ +│ │ +│ Filter by Permission Type (Optional) │ +│ ☑ Submit Expense ☐ Read ☐ Manage │ +│ │ +│ Notes │ +│ [Copied from Alice - new coordinator] │ +│ │ +│ ℹī¸ This will copy 3 SUBMIT_EXPENSE │ +│ permissions from alice to bob │ +│ │ +│ [Cancel] [Copy Permissions] │ +└───────────────────────────────────────────┘ +``` + +**Features:** +- Shows source user's permissions +- Filter by permission type +- Preview before copying + +--- + +### 5. Offboard User Dialog + +**UI Mockup:** +``` +┌───────────────────────────────────────────┐ +│ đŸšĒ Offboard User │ +├───────────────────────────────────────────┤ +│ │ +│ Select User to Offboard * │ +│ ┌────────────────────────────────────┐ │ +│ │ charlie (Departed Employee) │ │ +│ └────────────────────────────────────┘ │ +│ │ +│ ⚠ī¸ Current Permissions (8 total): │ +│ ┌────────────────────────────────────┐ │ +│ │ â€ĸ Expenses:Food (Submit Expense) │ │ +│ │ â€ĸ Expenses:Utilities (Submit) │ │ +│ │ â€ĸ Income:Services (Read) │ │ +│ │ â€ĸ Assets:Cash (Read) │ │ +│ │ â€ĸ Expenses:Accommodation (Submit) │ │ +│ │ â€ĸ ... 3 more │ │ +│ └────────────────────────────────────┘ │ +│ │ +│ ⚠ī¸ Warning: This will revoke ALL │ +│ permissions for this user. They will │ +│ immediately lose access to Castle. │ +│ │ +│ Reason for Offboarding │ +│ [Employee departure - last day] │ +│ │ +│ [Cancel] [Revoke All (8)] │ +└───────────────────────────────────────────┘ +``` + +**Features:** +- Shows all current permissions +- Requires confirmation +- Logs reason for audit + +--- + +### 6. Account Sync UI + +**Location**: Admin Settings or Bulk Operations menu + +**UI Mockup:** +``` +┌───────────────────────────────────────────┐ +│ 🔄 Sync Accounts from Beancount │ +├───────────────────────────────────────────┤ +│ │ +│ Sync accounts from your Beancount ledger │ +│ to Castle database for permission mgmt. │ +│ │ +│ Last Sync: 2 hours ago │ +│ Status: ✅ Up to date │ +│ │ +│ Accounts in Beancount: 150 │ +│ Accounts in Castle DB: 150 │ +│ │ +│ Options: │ +│ ☐ Force full sync (re-check all) │ +│ │ +│ [Sync Now] │ +│ │ +│ Recent Sync History: │ +│ ┌────────────────────────────────────┐ │ +│ │ Nov 10, 2:00 PM - Added 2 accounts │ │ +│ │ Nov 10, 12:00 PM - Up to date │ │ +│ │ Nov 10, 10:00 AM - Added 1 account │ │ +│ └────────────────────────────────────┘ │ +└───────────────────────────────────────────┘ +``` + +**Features:** +- Shows sync status +- Last sync timestamp +- Account counts +- Sync history + +--- + +### 7. Expiring Permissions Alert + +**Location**: Top of permissions page (if any expiring soon) + +**UI Mockup:** +``` +┌─────────────────────────────────────────────┐ +│ ⚠ī¸ 5 Permissions Expiring Soon (Next 7 Days)│ +├─────────────────────────────────────────────┤ +│ â€ĸ alice on Expenses:Food (3 days) │ +│ â€ĸ bob on Income:Services (5 days) │ +│ â€ĸ charlie on Assets:Cash (7 days) │ +│ │ +│ [View All] [Extend Expiration] [Dismiss] │ +└─────────────────────────────────────────────┘ +``` + +**Features:** +- Prominent alert banner +- Shows expiring in next 7 days +- Quick actions to extend + +--- + +### 8. Permission Templates (Future) + +**Concept**: Pre-defined permission sets for common roles + +**UI Mockup:** +``` +┌───────────────────────────────────────────┐ +│ 📝 Apply Permission Template │ +├───────────────────────────────────────────┤ +│ │ +│ Select User * │ +│ [bob] │ +│ │ +│ Select Template * │ +│ ┌────────────────────────────────────┐ │ +│ │ Food Coordinator (5 permissions) │ │ +│ │ â€ĸ Expenses:Food (Submit) │ │ +│ │ â€ĸ Expenses:Food:* (Submit) │ │ +│ │ â€ĸ Income:Services (Read) │ │ +│ │ │ │ +│ │ Accommodation Manager (8 perms) │ │ +│ │ Finance Admin (15 perms) │ │ +│ │ Read-Only Auditor (25 perms) │ │ +│ └────────────────────────────────────┘ │ +│ │ +│ [Cancel] [Apply Template] │ +└───────────────────────────────────────────┘ +``` + +--- + +## Implementation Priority + +### Phase 1: Quick Wins (This Week) +**Effort**: 2-3 days + +1. **Analytics Tab** (1 day) + - Add new tab to permissions.html + - Call analytics API endpoint + - Display stats with Quasar components + +2. **Bulk Grant Dialog** (1 day) + - Add multi-select user dropdown + - Call bulk grant API + - Show success/failure results + +3. **Account Sync Button** (0.5 days) + - Add sync button to admin area + - Call sync API + - Show progress and results + +**Impact**: Immediate productivity boost for admins + +--- + +### Phase 2: Bulk Operations (Next Week) +**Effort**: 2-3 days + +4. **Copy Permissions Dialog** (1 day) + - Template selection UI + - Preview permissions + - Copy operation + +5. **Offboard User Dialog** (1 day) + - User selection with permission preview + - Confirmation with reason logging + - Bulk revoke operation + +6. **Expiring Permissions Alert** (0.5 days) + - Alert banner component + - Query expiring permissions + - Quick actions + +**Impact**: Major time savings for common workflows + +--- + +### Phase 3: Polish (Later) +**Effort**: 2-3 days + +7. **Permission Templates** (2 days) + - Template management UI + - Template CRUD operations + - Apply template workflow + +8. **Advanced Analytics** (1 day) + - Charts and graphs + - Permission history timeline + - Usage patterns + +**Impact**: Long-term ease of use + +--- + +## Technical Implementation + +### New API Endpoints Needed + +```javascript +// Analytics +GET /api/v1/admin/permissions/analytics + +// Bulk Operations +POST /api/v1/admin/permissions/bulk-grant +{ + user_ids: ["alice", "bob", "charlie"], + account_id: "acc123", + permission_type: "submit_expense", + expires_at: "2025-12-31T23:59:59", + notes: "Q4 team" +} + +POST /api/v1/admin/permissions/copy +{ + from_user_id: "alice", + to_user_id: "bob", + permission_types: ["submit_expense"], + notes: "New coordinator" +} + +DELETE /api/v1/admin/permissions/user/{user_id} + +DELETE /api/v1/admin/permissions/account/{account_id} + +// Account Sync +POST /api/v1/admin/sync-accounts +{ + force_full_sync: false +} + +GET /api/v1/admin/sync-accounts/status +``` + +### Vue.js Component Structure + +``` +permissions.html +├── Analytics Tab (new) +│ ├── Stats Cards +│ ├── Distribution Chart +│ ├── Expiring Soon List +│ └── Top Accounts List +│ +├── By User Tab (existing) +│ └── Enhanced with bulk operations +│ +├── By Account Tab (existing) +│ └── Enhanced with bulk operations +│ +├── Equity Tab (existing) +│ +└── Dialogs + ├── Bulk Grant Dialog (new) + ├── Copy Permissions Dialog (new) + ├── Offboard User Dialog (new) + ├── Account Sync Dialog (new) + ├── Grant Permission Dialog (existing) + └── Revoke Confirmation Dialog (existing) +``` + +### State Management + +```javascript +// Add to Vue app data +{ + // Analytics + analytics: { + total: 0, + byType: {}, + expiringSoon: [], + topAccounts: [] + }, + + // Bulk Operations + bulkGrantForm: { + user_ids: [], + account_id: null, + permission_type: null, + expires_at: null, + notes: '' + }, + + copyPermissionsForm: { + from_user_id: null, + to_user_id: null, + permission_types: [], + notes: '' + }, + + offboardForm: { + user_id: null, + reason: '' + }, + + // Account Sync + syncStatus: { + lastSync: null, + beancountAccounts: 0, + castleAccounts: 0, + status: 'idle' + } +} +``` + +--- + +## User Experience Flow + +### Onboarding New Team Member (Before vs After) + +**Before** (10 minutes): +1. Open permissions page +2. Click "Grant Permission" 5 times +3. Fill form each time (user, account, type) +4. Click grant, repeat +5. Hope you didn't forget any + +**After** (1 minute): +1. Click "Bulk Operations" → "Copy Permissions" +2. Select template user → Select new user +3. Click "Copy" +4. Done! ✨ + +**Time Saved**: 90% + +--- + +### Quarterly Access Review (Before vs After) + +**Before** (2 hours): +1. Export permissions to spreadsheet +2. Manually review each one +3. Delete expired individually +4. Update expiration dates one by one + +**After** (5 minutes): +1. Click "Analytics" tab +2. See "5 Expiring Soon" alert +3. Review list, click "Extend" on relevant ones +4. Done! ✨ + +**Time Saved**: 96% + +--- + +## Testing Plan + +### UI Testing + +```javascript +// Test bulk grant +async function testBulkGrant() { + // 1. Open bulk grant dialog + // 2. Select 3 users + // 3. Select account + // 4. Select permission type + // 5. Click grant + // 6. Verify success message + // 7. Verify permissions appear in UI +} + +// Test copy permissions +async function testCopyPermissions() { + // 1. Open copy dialog + // 2. Select source user with 5 permissions + // 3. Select target user + // 4. Filter to SUBMIT_EXPENSE only + // 5. Verify preview shows 3 permissions + // 6. Click copy + // 7. Verify target user has 3 new permissions +} + +// Test analytics +async function testAnalytics() { + // 1. Switch to analytics tab + // 2. Verify stats load + // 3. Verify charts display + // 4. Verify expiring permissions show + // 5. Click on expiring permission + // 6. Verify details dialog opens +} +``` + +### Integration Testing + +```python +# Test full workflow +async def test_onboarding_workflow(): + # 1. Admin syncs accounts + sync_result = await api.post("/admin/sync-accounts") + assert sync_result["accounts_added"] >= 0 + + # 2. Admin copies permissions from template user + copy_result = await api.post("/admin/permissions/copy", { + "from_user_id": "template", + "to_user_id": "new_user" + }) + assert copy_result["copied"] > 0 + + # 3. Verify new user has permissions in UI + perms = await api.get(f"/admin/permissions?user_id=new_user") + assert len(perms) > 0 + + # 4. Check analytics reflect new permissions + analytics = await api.get("/admin/permissions/analytics") + assert analytics["total_permissions"] increased +``` + +--- + +## Accessibility + +- ✅ Keyboard navigation support +- ✅ Screen reader friendly labels +- ✅ Color contrast compliance (WCAG AA) +- ✅ Focus indicators +- ✅ ARIA labels on interactive elements + +--- + +## Mobile Responsiveness + +- ✅ Analytics cards stack vertically on mobile +- ✅ Dialogs are full-screen on small devices +- ✅ Touch-friendly button sizes +- ✅ Swipe gestures for tabs + +--- + +## Error Handling + +**Bulk Grant Fails:** +``` +⚠ī¸ Bulk Grant Results +✅ Granted to 3 users +❌ Failed for 2 users: + â€ĸ bob: Already has permission + â€ĸ charlie: Account not found + +[View Details] [Retry Failed] [Dismiss] +``` + +**Account Sync Fails:** +``` +❌ Account Sync Failed +Could not connect to Beancount service. + +Error: Connection timeout after 10s + +[Retry] [Check Settings] [Dismiss] +``` + +--- + +## Performance Considerations + +- **Pagination**: Load permissions in batches of 50 +- **Lazy Loading**: Load analytics only when tab is viewed +- **Debouncing**: Debounce search inputs (300ms) +- **Caching**: Cache analytics for 30 seconds +- **Optimistic UI**: Show loading state immediately + +--- + +## Security Considerations + +- ✅ All bulk operations require admin key +- ✅ Confirmation dialogs for destructive actions +- ✅ Audit log all bulk operations +- ✅ Rate limiting on API endpoints +- ✅ CSRF protection on forms + +--- + +## Documentation + +**User Guide** (to create): +1. How to bulk grant permissions +2. How to copy permissions (templating) +3. How to offboard a user +4. How to sync accounts +5. How to use analytics dashboard + +**Admin Guide** (to create): +1. When to use bulk operations +2. Best practices for permission templates +3. How to monitor permission usage +4. Troubleshooting sync issues + +--- + +## Success Metrics + +**Measure after deployment:** +- Time to onboard new user: 10min → 1min +- Time for access review: 2hr → 5min +- Admin satisfaction score: 6/10 → 9/10 +- Support tickets for permissions: -70% +- Permissions granted per month: +40% + +--- + +## Summary + +This UI improvement plan focuses on: + +1. **Quick Wins**: Analytics and bulk grant (2-3 days) +2. **Bulk Operations**: Copy, offboard, sync (2-3 days) +3. **Polish**: Templates and advanced features (later) + +**Total Time**: ~5-6 days for Phase 1 & 2 +**Impact**: 50-70% reduction in admin time +**ROI**: Immediate productivity boost + +The enhancements leverage the new backend features we built (account sync, bulk permission management) and make them accessible through an intuitive UI, significantly improving the admin experience. + +--- + +**Document Version**: 1.0 +**Last Updated**: November 10, 2025 +**Status**: Ready for Implementation