# Employee Management Audit

## Audit Session - 2026-05-29 11:38:13 +03:00

## Current Employee/User Model

Employees are stored in `users`. Current relevant fields:

- `name`
- `email`
- `password`
- `whatsapp_phone_id`
- `team_id`
- `is_active`
- `last_assigned_at`

Roles are assigned through Spatie Permission. Team membership is via `users.team_id`. Supervisor ownership is modeled on `teams.supervisor_id`, not directly on the employee row.

## Feature Audit

| Feature | Exists? | Working? | File/Route/API | Problems Found | Recommendation |
|---|---|---|---|---|---|
| Team or Users screen | Yes | Partly | `/admin/users`, `/admin/teams`; `UserResource`, `TeamResource` | Sidebar says Team, but employee management is Users. Permissions and Settings also route to Users. | Rename/restructure to Team / Employees and separate Permissions/Settings. |
| Create new employee | Yes | Loads | `/admin/users/create` | Form exists but not presented as guided employee setup. | Keep form but add clear role/team/permission guidance. |
| Edit employee | Yes | Loads | `/admin/users/{id}/edit` | No employee profile context such as assigned conversations or activity. | Add employee profile/details page or panels. |
| Disable employee | Yes | Likely | `is_active` toggle in UserResource | No workflow guidance for what happens to assigned conversations. | On disable, require transfer/close plan for active conversations. |
| Delete employee | Yes | Partly | UserResource delete action | Delete blocked if assigned conversations exist; good safety, but message is not clearly documented in UI. | Prefer deactivate over delete; add transfer warning. |
| Assign role | Yes | Loads | UserResource role multi-select | Uses raw role names; permissions table empty; multi-role may confuse business roles. | Use single business role unless multi-role is required; show descriptions. |
| Assign employee under supervisor | Indirect | Partly | TeamResource supervisor + UserResource team | No direct "supervisor" field on employee; employee belongs to team. | Make supervisor/team relationship visible in employee form. |
| Assign WhatsApp number to employee | Yes | Partly | `whatsapp_phone_id` on user | Field accepts raw WABA phone number ID; no validation/lookup. | Add configured WhatsApp number selector/validation. |
| Assign conversations to employee | Yes | Partly | Conversation transfer action and API | Transfer UI is split across dashboard and Filament; some options use all active users. | Centralize assignment/transfer workflow and filter targets by role/team. |
| Dedicated agent for contact | Yes | Incomplete | ContactResource `dedicated_agent_id` | `ConversationRouter` currently ignores dedicated agent and assigns new conversations to manager/admin. | Use dedicated agent in routing or remove until implemented. |
| Clear employee profile | No | No | N/A | Only list/create/edit forms. | Add employee profile with role, team, status, assigned conversations, stats, activity. |
| Password/login setup | Yes | Partly | UserResource password field | Password is manually entered; no invite/reset workflow. | Add invite/reset-password flow later. |
| Active/inactive status | Yes | Partly | `is_active` | Router uses active manager/admin; transfer options use active users; existing assigned conversations not automatically handled. | Define inactive behavior. |
| Employee connected to WhatsApp conversations | Yes | Partly | `conversations.assigned_to`, `assignments.employee_id` | No single employee view showing assigned conversations. | Add assigned conversations panel on employee profile. |

## Current Employee Creation Form

Browser audit of `/admin/users/create` showed:

- Name
- Email
- Password
- Role multi-select
- WhatsApp phone ID (WABA)
- Team select
- Active toggle

This is enough for raw creation, but not enough for a clear business workflow because the user must understand raw roles and WABA IDs.

## Current Employee List

Browser audit of `/admin/users` showed:

- Name
- Email
- Role
- Team
- Active
- Last assignment
- Edit/Delete actions

Before the test DB reset, users found were:

| ID | Name | Email | Roles | Team | Active | WhatsApp Phone ID |
|---:|---|---|---|---|---|---|
| 1 | Admin User | admin@example.com | admin | none | true | none |
| 2 | Supervisor User | supervisor@example.com | supervisor | Support Team A | true | none |
| 3 | Agent A | agent.a@example.com | agent | Support Team A | true | 901126826426967 |
| 4 | Agent B | agent.b@example.com | agent | Support Team A | true | 901126826426967 |
| 5 | Agent C | agent.c@example.com | agent | Support Team A | true | 901126826426967 |
| 6 | Unassigned Queue | unassigned@system.local | none | none | false | none |

## Employee Management Problems

| Problem | Impact | Recommended Fix |
|---|---|---|
| No clear Team / Employees screen separation | User does not know where to create employees versus manage teams. | Combine user-facing sidebar item as "Team / Employees" or split into "Employees" and "Teams". |
| Permissions item routes to Users | User thinks permissions are managed there, but only roles are assigned. | Create real Permissions page. |
| Settings item routes to Users | Misleading navigation. | Create real Settings page or remove until ready. |
| Role names are technical | Admin/Supervisor/Agent are visible as raw names. | Add localized labels and role descriptions. |
| Roles are multi-select | Could create conflicting role combinations. | Use single role field unless multi-role is intentional. |
| No employee profile | Cannot quickly see employee workload, assigned conversations, or supervisor relationship. | Add profile/detail page. |
| Dedicated contact agent not used in routing | Admin can configure something that workflow ignores. | Wire it into `ConversationRouter` or hide it until implemented. |
| Test suite reset local data | Employee seed/live data was lost during audit test run. | Isolate tests, then restore data from backup/seed with user approval. |

## Phase 2 Update - 2026-05-29 12:09:31 +03:00

| Feature | Exists? | Working? | File/Route/API | Problems Found | Recommendation |
|---|---|---|---|---|---|
| Team / Employees sidebar | Yes | Yes | `/admin/users`, `UserResource.php` | Previously named only Employees and custom sidebar linked Team to `/admin/teams`. | Keep `/admin/users` as the main employee management screen. |
| Employee creation | Yes | Yes in route tests | `/admin/users/create` | Roles were raw/multi-select. | Phase 2 limits to one business role and adds role helper text. |
| Business role labels | Yes | Yes | `UserResource::roleLabel()` | Technical role names were confusing. | Continue using backend values `admin/supervisor/agent` and friendly labels in UI. |
| Team assignment | Yes | Partially | `team_id` on users | Supervisor relationship is via team, but full profile context is missing. | Add employee profile/detail panels in Phase 3. |
| WhatsApp phone ID | Yes | Partially | `whatsapp_phone_id` field | Field exists but routing use is limited. | Decide routing behavior before making it prominent. |
| Active/inactive status | Yes | Yes | `is_active` field | Transfer target filtering now respects active employees. | Add filters and status badges if needed. |
| Assignment history | Yes | Partial | `/admin/assignments` | Employee cannot access; supervisor/admin can. | Link from employee profile in Phase 3. |

## Phase 3B Update - 2026-05-29 12:45:48 +03:00

| Feature | Exists? | Working? | File/Route/API | Problems Found | Recommendation |
|---|---|---|---|---|---|
| Employee profile/details | Yes | Yes | `/admin/users/{record}`, `ViewUser.php` | No self-service My Profile route for employees. | Add My Profile later only if business wants employee self-view. |
| Basic employee information | Yes | Yes | `view-user.blade.php` | None found. | Keep role labels business-friendly. |
| Team/supervisor information | Yes | Yes | `ViewUser.php` | Supervisor member count depends on `teams.supervisor_id`. | Keep team setup clean when creating supervisors. |
| WhatsApp information | Yes | Yes | `whatsapp_phone_id` on profile | Assigned WhatsApp number is limited to stored phone ID. | Add friendly number label later if settings table stores phone metadata. |
| Workload summary | Yes | Yes | `Conversation::system()` scoped to employee | None found. | Add deeper performance metrics in Reports phase, not profile. |
| Assignment history | Yes | Yes | Recent `assignments` rows | `assigned_from` is inferred; not a dedicated DB field. | Add explicit transfer-from field only if audit requirements demand it. |
| Conversation list | Yes | Yes | Latest employee conversations with open links | No inline filters in profile. | Keep detailed filtering in Conversations screen. |
| Inactive warning | Yes | Yes | User edit form placeholder | Warning only; it does not block deactivation. | Add transfer/deactivation workflow later if needed. |