app rearrangement

docs/agent/thoughts/user-profile.md

@@ -0,0 +1,629 @@
+# User Profile Management - Frontend Guide
+
+Quick reference for building user profile pages. All endpoints require authentication via Bearer token.
+
+---
+
+## Base URL
+```
+/api/v1
+```
+
+---
+
+## 1. Get Current User Profile
+
+**Get my complete profile**
+```http
+GET /profile/me
+```
+
+**Response:**
+```json
+{
+  "basic_info": {
+    "id": "uuid",
+    "name": "John Doe",
+    "email": "john@example.com",
+    "phone": "+254712345678",
+    "phone_alternate": "+254787654321",
+    "display_name": "Johnny",
+    "id_number": "12345678",
+    "emergency_contact_name": "Jane Doe",
+    "emergency_contact_phone": "+254700000000",
+    "role": "field_agent",
+    "status": "active",
+    "is_active": true,
+    "client_id": "uuid",
+    "contractor_id": null,
+    "created_at": "2025-01-01T00:00:00Z",
+    "updated_at": "2025-01-01T00:00:00Z"
+  },
+  "health_info": {
+    "blood_type": "O+",
+    "allergies": "Peanuts",
+    "chronic_conditions": "None",
+    "medications": "None",
+    "last_medical_check": "2024-12-01",
+    "medical_notes": "All good"
+  },
+  "ppe_sizes": {
+    "height": "180cm",
+    "weight": "75kg",
+    "waist": "32",
+    "shoe_size": "42",
+    "helmet_size": "M",
+    "shirt_size": "L",
+    "pants_size": "32",
+    "glove_size": "M",
+    "vest_size": "L"
+  },
+  "location": {
+    "current_location_name": "Nairobi Office",
+    "current_country": "Kenya",
+    "current_region": "Nairobi",
+    "current_city": "Nairobi",
+    "current_address_line1": "123 Main St",
+    "current_address_line2": "Apt 4B",
+    "current_maps_link": "https://maps.google.com/...",
+    "current_latitude": -1.286389,
+    "current_longitude": 36.817223,
+    "current_location_updated_at": "2025-01-01T00:00:00Z"
+  },
+  "completion_status": {
+    "basic_info": true,
+    "health_info": true,
+    "ppe_sizes": false,
+    "financial_accounts": true,
+    "documents": false,
+    "location": true,
+    "completion_percentage": 67
+  },
+  "financial_accounts_count": 2,
+  "documents_count": 3,
+  "asset_assignments_count": 1
+}
+```
+
+---
+
+## 2. Update Profile Sections
+
+### Basic Info
+```http
+PUT /profile/me/basic
+Content-Type: application/json
+
+{
+  "name": "John Doe",
+  "phone": "+254712345678",
+  "phone_alternate": "+254787654321",
+  "email": "john@example.com",
+  "display_name": "Johnny",
+  "emergency_contact_name": "Jane Doe",
+  "emergency_contact_phone": "+254700000000"
+}
+```
+All fields optional. Phone numbers must start with `+`.
+
+### Health Info
+```http
+PUT /profile/me/health
+Content-Type: application/json
+
+{
+  "blood_type": "O+",
+  "allergies": "Peanuts, Shellfish",
+  "chronic_conditions": "Asthma",
+  "medications": "Inhaler",
+  "last_medical_check": "2024-12-01",
+  "medical_notes": "Regular checkups"
+}
+```
+Blood type: `A+`, `A-`, `B+`, `B-`, `AB+`, `AB-`, `O+`, `O-`
+
+### PPE Sizes
+```http
+PUT /profile/me/ppe
+Content-Type: application/json
+
+{
+  "height": "180cm",
+  "weight": "75kg",
+  "waist": "32",
+  "shoe_size": "42",
+  "helmet_size": "M",
+  "shirt_size": "L",
+  "pants_size": "32",
+  "glove_size": "M",
+  "vest_size": "L"
+}
+```
+Sizes: `XS`, `S`, `M`, `L`, `XL`, `XXL`, `XXXL`
+
+### Location
+```http
+PUT /profile/me/location
+Content-Type: application/json
+
+{
+  "current_location_name": "Nairobi Office",
+  "current_country": "Kenya",
+  "current_region": "Nairobi",
+  "current_city": "Nairobi",
+  "current_address_line1": "123 Main St",
+  "current_address_line2": "Apt 4B",
+  "current_maps_link": "https://maps.google.com/...",
+  "current_latitude": -1.286389,
+  "current_longitude": 36.817223
+}
+```
+Latitude: -90 to 90, Longitude: -180 to 180
+
+### Bulk Update (Profile Setup Wizard)
+```http
+PUT /profile/me/bulk
+Content-Type: application/json
+
+{
+  "basic_info": { /* BasicProfileUpdate */ },
+  "health_info": { /* HealthInfoUpdate */ },
+  "ppe_sizes": { /* PPESizesUpdate */ },
+  "location": { /* LocationUpdate */ }
+}
+```
+Include only sections you want to update.
+
+---
+
+## 3. Profile Completion
+
+**Get completion status**
+```http
+GET /profile/me/completion
+```
+
+**Response:**
+```json
+{
+  "basic_info": true,
+  "health_info": true,
+  "ppe_sizes": false,
+  "financial_accounts": true,
+  "documents": false,
+  "location": true,
+  "completion_percentage": 67
+}
+```
+
+**Validate profile**
+```http
+GET /profile/me/validation
+```
+
+**Response:**
+```json
+{
+  "is_valid": false,
+  "missing_fields": ["ppe_sizes", "emergency_contact_phone"],
+  "invalid_fields": {
+    "phone": "Must start with country code"
+  },
+  "warnings": ["Medical check is overdue"]
+}
+```
+
+---
+
+## 4. Financial Accounts (Payout Details)
+
+**List my accounts**
+```http
+GET /financial-accounts/me
+```
+
+**Response:**
+```json
+[
+  {
+    "id": "uuid",
+    "user_id": "uuid",
+    "account_name": "M-Pesa Main",
+    "payout_method": "mobile_money",
+    "mobile_money_provider": "Safaricom",
+    "mobile_money_phone": "+254712345678",
+    "mobile_money_account_name": "John Doe",
+    "bank_name": null,
+    "bank_account_name": null,
+    "bank_account_number": null,
+    "bank_branch": null,
+    "bank_swift_code": null,
+    "payout_frequency": "weekly",
+    "is_primary": true,
+    "is_active": true,
+    "is_verified": true,
+    "verified_at": "2025-01-01T00:00:00Z",
+    "notes": null,
+    "created_at": "2025-01-01T00:00:00Z",
+    "updated_at": "2025-01-01T00:00:00Z"
+  }
+]
+```
+
+**Create account**
+```http
+POST /financial-accounts/me
+Content-Type: application/json
+
+{
+  "account_name": "M-Pesa Main",
+  "payout_method": "mobile_money",
+  "mobile_money_provider": "Safaricom",
+  "mobile_money_phone": "+254712345678",
+  "mobile_money_account_name": "John Doe",
+  "payout_frequency": "weekly",
+  "is_primary": true,
+  "notes": "Primary payment method"
+}
+```
+
+**Update account**
+```http
+PUT /financial-accounts/me/{account_id}
+Content-Type: application/json
+
+{
+  "account_name": "M-Pesa Updated",
+  "is_primary": false,
+  "is_active": true
+}
+```
+
+**Delete account**
+```http
+DELETE /financial-accounts/me/{account_id}
+```
+
+**Payout Methods:**
+- `mobile_money` - M-Pesa, Airtel Money, etc.
+- `bank_transfer` - Bank account details
+- `cash` - Cash pickup
+- `other` - Alternative methods
+
+---
+
+## 5. View Other Users (Manager Access)
+
+**Get user profile**
+```http
+GET /profile/{user_id}
+```
+Returns same structure as `/profile/me`. Requires permission.
+
+**Check edit permissions**
+```http
+GET /profile/{user_id}/permissions
+```
+
+**Response:**
+```json
+{
+  "can_edit_basic_info": true,
+  "can_edit_health_info": true,
+  "can_edit_ppe_sizes": true,
+  "can_edit_location": true,
+  "can_edit_financial_accounts": false,
+  "can_upload_documents": true,
+  "can_edit_role": false,
+  "can_edit_status": false,
+  "can_assign_assets": true,
+  "can_view_health_info": true,
+  "can_view_financial_accounts": false,
+  "can_view_documents": true
+}
+```
+Use this to show/hide edit buttons in UI.
+
+**Update user sections**
+```http
+PUT /profile/{user_id}/basic
+PUT /profile/{user_id}/health
+PUT /profile/{user_id}/ppe
+PUT /profile/{user_id}/location
+```
+Same request body as `/profile/me/*` endpoints. Permission checked.
+
+---
+
+## 6. User Management (Admin)
+
+**List users with filters**
+```http
+GET /users?skip=0&limit=50&role=field_agent&status=active&is_active=true
+```
+
+**Query params:**
+- `skip` (int, default 0) - Pagination offset
+- `limit` (int, default 50, max 100) - Page size
+- `email` (string) - Search by email
+- `phone` (string) - Search by phone
+- `role` (string) - Filter by role
+- `status` (string) - Filter by status
+- `is_active` (bool) - Filter by active
+- `client_id` (uuid) - Filter by client
+- `contractor_id` (uuid) - Filter by contractor
+- `sort_by` (string, default created_at) - Sort field
+- `sort_order` (string, default desc) - asc/desc
+
+**Response:**
+```json
+{
+  "users": [ /* array of UserResponse */ ],
+  "total": 150,
+  "page": 1,
+  "page_size": 50,
+  "total_pages": 3
+}
+```
+
+**Get user by ID**
+```http
+GET /users/{user_id}
+```
+
+**Update user**
+```http
+PUT /users/{user_id}
+Content-Type: application/json
+
+{
+  "name": "John Doe",
+  "email": "john@example.com",
+  "phone": "+254712345678",
+  "display_name": "Johnny",
+  "is_active": true
+}
+```
+
+**Change status**
+```http
+POST /users/{user_id}/status
+Content-Type: application/json
+
+{
+  "status": "active",
+  "reason": "Profile completed"
+}
+```
+Statuses: `invited`, `pending_setup`, `active`, `suspended`
+
+**Change role**
+```http
+POST /users/{user_id}/role
+Content-Type: application/json
+
+{
+  "role": "project_manager",
+  "reason": "Promotion"
+}
+```
+Roles: `platform_admin`, `client_admin`, `contractor_admin`, `sales_manager`, `project_manager`, `dispatcher`, `field_agent`, `sales_agent`
+
+**Deactivate user**
+```http
+POST /users/{user_id}/deactivate?reason=Left company
+```
+
+**Activate user**
+```http
+POST /users/{user_id}/activate
+```
+
+**Reset password (admin)**
+```http
+POST /users/{user_id}/reset-password
+Content-Type: application/json
+
+{
+  "new_password": "NewSecure123"
+}
+```
+
+---
+
+## 7. Bulk Operations
+
+**Bulk update users**
+```http
+POST /users/bulk/update
+Content-Type: application/json
+
+{
+  "user_ids": ["uuid1", "uuid2", "uuid3"],
+  "updates": {
+    "is_active": true,
+    "status": "active"
+  },
+  "reason": "Mass activation"
+}
+```
+
+**Bulk change status**
+```http
+POST /users/bulk/status
+Content-Type: application/json
+
+{
+  "user_ids": ["uuid1", "uuid2"],
+  "status": "suspended",
+  "reason": "Contract ended"
+}
+```
+
+**Bulk change role**
+```http
+POST /users/bulk/role
+Content-Type: application/json
+
+{
+  "user_ids": ["uuid1", "uuid2"],
+  "role": "field_agent",
+  "reason": "Restructuring"
+}
+```
+
+**Response:**
+```json
+{
+  "total": 3,
+  "successful": 2,
+  "failed": 1,
+  "errors": [
+    {
+      "user_id": "uuid3",
+      "error": "Permission denied"
+    }
+  ]
+}
+```
+
+---
+
+## 8. Asset Assignments
+
+**Get my assets**
+```http
+GET /asset-assignments/me
+```
+
+**Response:**
+```json
+[
+  {
+    "id": "uuid",
+    "user_id": "uuid",
+    "asset_type": "vehicle",
+    "asset_name": "Toyota Hilux KBX 123A",
+    "asset_description": "Field work truck",
+    "serial_number": "ABC123",
+    "registration_number": "KBX 123A",
+    "asset_value": 2500000.00,
+    "currency": "KES",
+    "assigned_at": "2025-01-01T00:00:00Z",
+    "assigned_by_user_id": "uuid",
+    "expected_return_at": null,
+    "returned_at": null,
+    "condition_on_assign": "good",
+    "condition_on_return": null,
+    "is_active": true,
+    "notes": "Handle with care",
+    "created_at": "2025-01-01T00:00:00Z",
+    "updated_at": "2025-01-01T00:00:00Z"
+  }
+]
+```
+
+**Get user's assets (manager)**
+```http
+GET /asset-assignments/user/{user_id}
+```
+
+**Assign asset (manager)**
+```http
+POST /asset-assignments/user/{user_id}
+Content-Type: application/json
+
+{
+  "asset_type": "laptop",
+  "asset_name": "Dell Latitude 5420",
+  "asset_description": "Work laptop",
+  "serial_number": "SN12345",
+  "asset_value": 65000.00,
+  "condition_on_assign": "new",
+  "notes": "Company property"
+}
+```
+
+**Return asset**
+```http
+POST /asset-assignments/{assignment_id}/return
+Content-Type: application/json
+
+{
+  "condition_on_return": "good",
+  "notes": "Returned in good condition"
+}
+```
+
+---
+
+## Permission Model
+
+### Platform Admin
+- Full access to all users
+- Can change roles, organizations
+- Can delete users
+
+### Client/Contractor Admin
+- Manage users in their organization
+- Cannot change to/from `platform_admin`
+- Cannot move users between organizations
+
+### Project/Sales Manager
+- View team profiles
+- Edit team profiles (permission checked per field)
+
+### Field/Sales Agent
+- View & edit own profile only
+- Manage own financial accounts
+
+---
+
+## Error Responses
+
+**401 Unauthorized**
+```json
+{
+  "detail": "Not authenticated"
+}
+```
+
+**403 Forbidden**
+```json
+{
+  "detail": "You don't have permission to view this user's profile"
+}
+```
+
+**404 Not Found**
+```json
+{
+  "detail": "User not found"
+}
+```
+
+**422 Validation Error**
+```json
+{
+  "detail": [
+    {
+      "loc": ["body", "phone"],
+      "msg": "Phone number must start with country code",
+      "type": "value_error"
+    }
+  ]
+}
+```
+
+---
+
+## Notes
+
+1. **All dates** use ISO 8601 format: `2025-01-01T00:00:00Z`
+2. **Phone numbers** must include country code: `+254712345678`
+3. **Passwords** must be 8+ chars, 1 uppercase, 1 digit
+4. **UUIDs** are strings in API requests/responses
+5. **Null values** mean field not set (valid state)
+6. **All PATCH/PUT** endpoints accept partial updates (only send changed fields)
+7. **Pagination** is 0-indexed for `skip` parameter
+8. **Soft deletes** - deleted records have `deleted_at` timestamp but data preserved

src/app/config/apps.py

@@ -420,9 +420,9 @@ ROLE_APP_ACCESS: Dict[str, List[str]] = {
         # Field agents (casual workers) need to see their earnings and daily work
         # Include payroll to track earnings from daily errands
         # To Add later: "incidents", "documents",
-        "notifications", "dashboard", "tickets", "inventory", "timesheets", "tasks", 
+        "notifications", "dashboard", "tickets", "inventory", "timesheets", # "tasks", 
         "payroll",  # Track their daily earnings
-        "expenses", "customers", "sales_orders", "maps",  # Customer info for field visits
+        "expenses", # "customers", "sales_orders", "maps",  # Customer info for field visits
         "profile", "help"
     ],
     
@@ -446,11 +446,11 @@ DEFAULT_FAVORITE_APPS: Dict[str, List[str]] = {
     "platform_admin": ["dashboard", "organizations", "users", "invitations", "activity"],
     "client_admin": ["dashboard", "projects", "team", "invitations", "activity"],
     "contractor_admin": ["dashboard", "projects", "team", "invitations", "activity"],
-    "sales_manager": ["dashboard", "sales_orders", "customers", "team", "maps"],
-    "project_manager": ["dashboard", "projects", "tickets", "team", "maps"],
-    "dispatcher": ["dashboard", "tickets", "sales_orders", "maps", "tasks"],
-    "field_agent": ["dashboard", "tickets", "maps", "expenses", "customers"],
-    "sales_agent": ["dashboard", "sales_orders", "customers", "maps"]
+    "sales_manager": ["dashboard", "sales_orders", "customers", "notifications", "team"],
+    "project_manager": ["dashboard", "tickets", "sales_orders", "notifications", "team"],
+    "dispatcher": ["dashboard", "tickets", "sales_orders", "team"],
+    "field_agent": ["dashboard", "tickets", "notifications", "expenses"],
+    "sales_agent": ["dashboard", "sales_orders", "customers", "notifications"]
 }
 
 
@@ -461,11 +461,11 @@ DEFAULT_FAVORITE_APPS: Dict[str, List[str]] = {
 
 META_APPS_BY_ROLE: Dict[str, List[str]] = {
     # Project-based roles: Only show context-independent apps outside project
-    "project_manager": ["overview", "projects", "users", "finance", "notifications", "settings", "help"],
-    "sales_manager": ["overview", "projects", "users", "finance", "notifications", "settings", "help"],
-    "dispatcher": ["overview", "projects", "users", "finance", "notifications", "settings", "help"],
-    "field_agent": ["overview", "notifications", "projects", "payroll"],
-    "sales_agent": ["overview", "notifications", "projects", "payroll"],
+    "project_manager": ["overview", "projects", "users", "finance", "notifications", "settings", "profile", "help"],
+    "sales_manager": ["overview", "projects", "users", "finance", "notifications", "settings", "profile", "help"],
+    "dispatcher": ["overview", "projects", "users", "finance", "notifications", "settings", "profile", "help"],
+    "field_agent": ["overview", "notifications", "projects", "payroll", "profile"],
+    "sales_agent": ["overview", "notifications", "projects", "payroll", "profile"],
     
     # Admin roles: No context switching - empty list means show all apps always
     "platform_admin": [],