# Admin User Creation, Search & Edit Update

## Summary
This update adds a complete admin user management flow including:
- A dedicated admin flow to create users directly from the admin panel with the full set of user profile fields
- A search-by-national-id interface to locate and edit any existing user's profile
- Quick-edit buttons on all user management views (pending approvals, approved users, officers)

## Scope
- Added user-creation route and action in the admin user controller
- Added dedicated create-user form in the admin interface
- Added search-by-national-id route and form
- Added user-profile edit route and form
- Added Edit buttons to pending users, approved users, and officers views
- Added four new controller methods: searchForm(), search(), editForm(), updateProfile()
- Added reference and guarantor database columns via migration
- Updated User model fillable array to support new fields

## Files touched
- `routes/web.php` (added 4 new routes for search and edit)
- `app/Http/Controllers/Admin/UserController.php` (added 4 new methods)
- `resources/views/admin/users/index.blade.php` (added Edit links to all user tables)
- `resources/views/admin/users/create.blade.php` (existing)
- `resources/views/admin/users/search.blade.php` (new)
- `resources/views/admin/users/edit-profile.blade.php` (new)
- `resources/views/admin/officers/index.blade.php` (existing)
- `app/Models/User.php` (updated fillable array)
- `database/migrations/2026_08_31_134307_add_reference_and_guarantor_to_users_table.php` (applied)

## User Creation Behavior
- Users can be created with fields such as:
  - name
  - email
  - password (with confirmation)
  - role (user, officer)
  - status (pending, approved, inactive)
  - accessible_tier_id
  - assigned_officer_id
  - mpesa_phone
  - national_id
  - admin_pin_hash
  - first_disbursement_completed
  - guarantee_deposit_balance
  - address
  - phone
  - age
  - reference
  - guarantor
- Regular users default to pending approval unless explicitly set otherwise
- Officer-role records are created as approved
- Existing approval and rejection logic remains unchanged

## User Search & Edit Behavior
- Admins can navigate to `/admin/users/search` to search for users by national_id
- Search results display the user's full profile including address, reference, guarantor, tier assignment, and officer assignment
- Admins can click "Edit Profile" from search results to access the edit form
- Alternatively, Edit buttons are available directly on the admin user lists:
  - Pending Approvals view: Edit link appears between Approve and Reject buttons
  - Approved Users view: Edit link appears next to View link
  - Officers view: Edit link appears next to View link
- The edit form allows updating all user profile fields:
  - name, email, phone, age, address, reference, guarantor
  - accessible_tier_id (tier assignment)
  - assigned_officer_id (officer assignment)
- All profile updates are validated server-side and logged via AuditService
- After saving changes, the admin is redirected to the search form with a success message
- Read-only fields (national_id, role, created_at) are displayed but not editable

## Database Changes
- Added optional `reference` varchar(255) column to users table
- Added optional `guarantor` varchar(255) column to users table
- Migration includes safe `Schema::hasColumn()` checks to prevent duplicate column errors
- User model fillable array updated to include reference and guarantor fields

## Routes Added
- `GET /admin/users/search` → `admin.users.search-form` - Display search form
- `POST /admin/users/search` → `admin.users.search` - Process national_id search
- `GET /admin/users/{user}/edit-profile` → `admin.users.edit-profile` - Display edit form
- `PUT /admin/users/{user}/edit-profile` → `admin.users.update-profile` - Save profile changes

## Notes
- This update extends the admin user management workflow without modifying existing approval, rejection, or officer assignment logic
- The search and edit features are accessible from multiple entry points for convenience
- All changes are audit-logged for compliance and tracking
- Form validation prevents invalid data entry and provides clear error messages
- Consistent Tailwind CSS styling matches existing admin interface patterns
