workPro Documentation
User Guides
USER_MANAGEMENT_GUIDE.md

📋 User Management System - Implementation Guide

Overview

A complete RBAC-enabled user management system with:

  • ✅ DataTable-based user list with search & pagination
  • ✅ Popup modals for View, Edit, Create, Delete & Change Password
  • ✅ Full RBAC (Role-Based Access Control) enforcement
  • ✅ Dark theme matching WorkPro design
  • ✅ Responsive design for all screen sizes

📁 Files Created

Frontend

  • public/users.php (Main management page)
    • DataTable integration
    • Modal popups
    • User interface with matching theme
    • JavaScript event handlers
    • Form validation

API Endpoints

  • public/api/users-list.php - Fetch all users
  • public/api/users-view.php - Get single user details
  • public/api/users-create.php - Create new user
  • public/api/users-edit.php - Update user info
  • public/api/users-password.php - Change user password
  • public/api/users-delete.php - Delete user

🔐 RBAC Permissions

Role Hierarchy

Role View Users Create User Edit User Change Password Delete User
Admin ✅ ✅ ✅ ✅ ✅
Staff ✅ ✅ ✅ ✅ ❌
Supervisor ❌ ❌ ❌ ❌ ❌
Field ❌ ❌ ❌ ❌ ❌

Security Features

✅ Session-based authentication required
✅ Role-based access control on all endpoints
✅ Parameterized queries (SQL injection prevention)
✅ Input validation on all forms
✅ Password hashing with bcrypt
✅ Prevents self-deletion
✅ User cannot see management page if not admin/staff

🚀 Features

1. User List (DataTable)

┌─────────────┬─────────────┬──────────────────┬────────────┬──────────┬─────────────┐
│ Login ID    │ Role        │ Email            │ Phone      │ Status   │ Actions     │
├─────────────┼─────────────┼──────────────────┼────────────┼──────────┼─────────────┤
│ john.doe    │ Admin       │ john@example.com │ +91 ...    │ Active   │ 👁️ ✏️ 🔐 🗑️ │
│ jane.smith  │ Staff       │ jane@example.com │ +91 ...    │ Active   │ 👁️ ✏️ 🔐 🗑️ │
└─────────────┴─────────────┴──────────────────┴────────────┴──────────┴─────────────┘

Features:

  • Search across all columns
  • Pagination (10 entries per page)
  • Sort by any column
  • Responsive table layout

2. Actions

👁️ View User

  • Read-only modal
  • Shows all user information
  • No editing capability

✏️ Edit User

  • Modal form with all fields
  • Cannot change Login ID (readonly)
  • Update: Role, Status, Email, Phone
  • Form validation

🔐 Change Password

  • Modal form for new password
  • Confirm password field
  • 8-character minimum requirement
  • Both admin and users can change password

🗑️ Delete User

  • Confirmation dialog
  • Warning message
  • Cannot delete yourself
  • Only admins can delete (staff cannot)

➕ Create New User

  • Modal form for new user
  • Login ID, Role, Status required
  • Email, Phone optional
  • Auto-generates default password: "password"
  • User must change it on first login

🎨 Theme Integration

Colors Used

--bg: #0b0f19                    /* Dark background */
--card: #121826                  /* Card background */
--text: #e5e7eb                  /* Main text */
--muted: #94a3b8                 /* Muted text */
--primary: #10b981               /* Green accent */
--warn: #f59e0b                  /* Orange warning */
--error: #ef4444                 /* Red error */
--border: #1f2937                /* Border color */

Role Badges

  • Admin - Red (#dc2626)
  • Staff - Blue (#0284c7)
  • Supervisor - Purple (#7c3aed)
  • Field - Green (#16a34a)

Status Badges

  • Active - Green tint
  • Inactive - Red tint

Action Buttons

  • View - Cyan (#0891b2)
  • Edit - Blue (#2563eb)
  • Password - Orange (#f59e0b)
  • Delete - Red (#dc2626)

📊 Database Schema

CREATE TABLE user (
    id INT PRIMARY KEY AUTO_INCREMENT,
    loginId VARCHAR(50) UNIQUE NOT NULL,
    password_hash VARCHAR(255),
    role ENUM('admin', 'staff', 'supervisor', 'field'),
    status ENUM('Active', 'Inactive'),
    email VARCHAR(100),
    phone VARCHAR(20),
    vendor_id INT,
    project_id INT,
    dc_id INT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

🔌 API Endpoints Reference

1. users-list.php (GET)

Purpose: Fetch all users
RBAC: Admin, Staff
Response:

{
    "ok": true,
    "users": [
        {
            "id": 1,
            "loginId": "john.doe",
            "role": "admin",
            "email": "john@example.com",
            "phone": "+91 ...",
            "status": "Active"
        }
    ]
}

2. users-view.php (GET)

Purpose: Get single user details
RBAC: Admin, Staff
Params: id=<user_id>
Response:

{
    "ok": true,
    "user": {
        "id": 1,
        "loginId": "john.doe",
        "role": "admin",
        "email": "john@example.com",
        "phone": "+91 ...",
        "status": "Active"
    }
}

3. users-create.php (POST)

Purpose: Create new user
RBAC: Admin, Staff
Parameters:

  • loginId (required)
  • role (required) - admin, staff, supervisor, field
  • status (optional) - Active, Inactive
  • email (optional)
  • phone (optional)

Response:

{
    "ok": true,
    "message": "User created successfully. Default password is 'password'"
}

4. users-edit.php (POST)

Purpose: Update user information
RBAC: Admin, Staff
Params: id=<user_id>
Parameters:

  • role (required)
  • status (required)
  • email (optional)
  • phone (optional)

Response:

{
    "ok": true,
    "message": "User updated successfully"
}

5. users-password.php (POST)

Purpose: Change user password
RBAC: Admin, Staff
Params: id=<user_id>
Parameters:

  • password (required) - 8+ characters

Response:

{
    "ok": true,
    "message": "Password changed successfully"
}

6. users-delete.php (POST)

Purpose: Delete user
RBAC: Admin only
Params: id=<user_id>
Response:

{
    "ok": true,
    "message": "User deleted successfully"
}

📝 Usage Instructions

Access the Page

  1. Log in as Admin or Staff user
  2. Navigate to: /public/users.php
  3. Dashboard shows all users in DataTable format

Create New User

  1. Click "+ New User" button
  2. Fill in form:
    • Login ID (required)
    • Role (required)
    • Status (Active/Inactive)
    • Email (optional)
    • Phone (optional)
  3. Click "Save User"
  4. User created with default password: password
  5. User must change password on first login

Edit User

  1. Click ✏️ Edit button in Actions column
  2. Modal opens with user details
  3. Login ID is read-only
  4. Modify: Role, Status, Email, Phone
  5. Click "Save User"

View User

  1. Click 👁️ View button in Actions column
  2. Read-only modal shows all details
  3. Click "Close" to exit

Change Password

  1. Click 🔐 button in Actions column
  2. Enter new password (8+ characters)
  3. Confirm password
  4. Click "Change Password"
  5. Success message shown

Delete User

  1. Click 🗑️ Delete button in Actions column
  2. Confirmation dialog appears
  3. Review user name to delete
  4. Click "Delete User" to confirm
  5. User is permanently deleted

Search Users

  1. Use search box at top of table
  2. Search by: Login ID, Role, Email, Phone, Status
  3. Results filter in real-time

Pagination

  1. Use page navigation at bottom
  2. Select entries per page (10, 25, 50, etc.)
  3. Sort by clicking column headers

⚠️ Security Considerations

Best Practices

✅ Always use HTTPS in production
✅ Keep password hashing algorithm updated (bcrypt)
✅ Audit user modifications with timestamps
✅ Review deleted users in audit logs
✅ Regular security audits of user management

Protection Against

✅ SQL Injection - Parameterized queries
✅ XSS Attacks - htmlspecialchars() in output
✅ CSRF - Session-based authentication
✅ Privilege Escalation - Role-based API checks
✅ Unauthorized Access - Login requirement

🐛 Troubleshooting

"Access denied" message

  • ✅ Verify your user role is admin or staff
  • ✅ Check session is active
  • ✅ Log out and log back in

No users displayed in table

  • ✅ Check database connection
  • ✅ Verify user table exists and has data
  • ✅ Check browser console for JavaScript errors (F12)

Modal doesn't open

  • ✅ Check browser console (F12) for errors
  • ✅ Verify JavaScript libraries loaded correctly
  • ✅ Try hard refresh (Ctrl+Shift+R)

"User already exists" when creating

  • ✅ Login ID must be unique
  • ✅ Use different login ID
  • ✅ Or edit existing user instead

Password change failed

  • ✅ Ensure password is 8+ characters
  • ✅ Verify passwords match in confirm field
  • ✅ Check permissions (admin/staff only)

📱 Responsive Design

Desktop (> 768px)

  • Full DataTable with all columns
  • Side-by-side form fields
  • Optimal button spacing

Tablet (768px - 1024px)

  • Stacked layout adjusts
  • Modal width 90% with max-width 500px
  • Single column forms

Mobile (< 768px)

  • Full width forms
  • Single column for all inputs
  • Touch-friendly button sizes (44px minimum)
  • Horizontal scroll for tables

🎯 Future Enhancements

Potential features to add:

  • Bulk user import from CSV
  • User activity audit log
  • Two-factor authentication
  • User groups/teams
  • Departmental organization
  • Export users to PDF/Excel
  • Advanced filtering options
  • User inactivity notifications
  • Integration with LDAP/Active Directory
  • Role-based dashboard views

📞 Support

For issues or questions:

  1. Check browser console (F12) for errors
  2. Review error logs on server
  3. Verify database schema
  4. Confirm RBAC permissions
  5. Contact system administrator

Status: ✅ Production Ready
Last Updated: December 18, 2025
Version: 1.0

workPro Documentation | v1.3
Login to Dashboard