clqms-be/openspec/changes/archive/2026-03-08-backend-specs/user-api.md

# User Management API

## Overview
Create a complete User CRUD API for the user management page.

## Required Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | /api/users | List all users (with pagination) |
| GET | /api/users/(:num) | Get single user by ID |
| POST | /api/users | Create new user |
| PATCH | /api/users | Update existing user |
| DELETE | /api/users/(:num) | Delete user |

## Database Schema

The User model should use the existing `users` table (or create if doesn't exist):

```sql
-- If table doesn't exist, create it:
CREATE TABLE IF NOT EXISTS users (
    UserID INT AUTO_INCREMENT PRIMARY KEY,
    Username VARCHAR(50) NOT NULL UNIQUE,
    Email VARCHAR(100) NOT NULL,
    Name VARCHAR(100),
    Role VARCHAR(50),
    Department VARCHAR(100),
    IsActive BOOLEAN DEFAULT TRUE,
    CreatedAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UpdatedAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    DelDate TIMESTAMP NULL,
    INDEX idx_username (Username),
    INDEX idx_email (Email)
);
```

## User Fields

### Required Fields
- `Username` - Unique login username
- `Email` - User email address

### Optional Fields
- `Name` - Full name
- `Role` - User role (admin, technician, doctor, etc.)
- `Department` - Department name
- `IsActive` - Whether user is active

## API Specifications

### 1. List Users

**Request:**
```http
GET /api/users?page=1&per_page=20&search=john HTTP/1.1
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `per_page` - Items per page (default: 20)
- `search` - Search term for username/email/name (optional)

**Success Response (200):**
```json
{
  "status": "success",
  "message": "Users retrieved successfully",
  "data": {
    "users": [
      {
        "UserID": 1,
        "Username": "john.doe",
        "Email": "john@hospital.com",
        "Name": "John Doe",
        "Role": "technician",
        "Department": "Laboratory",
        "IsActive": true,
        "CreatedAt": "2024-01-15 10:30:00"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 150,
      "total_pages": 8
    }
  }
}
```

### 2. Get Single User

**Request:**
```http
GET /api/users/1 HTTP/1.1
```

**Success Response (200):**
```json
{
  "status": "success",
  "message": "User retrieved successfully",
  "data": {
    "UserID": 1,
    "Username": "john.doe",
    "Email": "john@hospital.com",
    "Name": "John Doe",
    "Role": "technician",
    "Department": "Laboratory",
    "IsActive": true,
    "CreatedAt": "2024-01-15 10:30:00",
    "UpdatedAt": "2024-01-15 10:30:00"
  }
}
```

**Not Found Response (404):**
```json
{
  "status": "failed",
  "message": "User not found",
  "data": null
}
```

### 3. Create User

**Request:**
```http
POST /api/users HTTP/1.1
Content-Type: application/json

```

**Success Response (201):**
```json
{
  "status": "success",
  "message": "User created successfully",
  "data": {
    "UserID": 2,
    "Username": "jane.smith",
    "Email": "jane@hospital.com"
  }
}
```

**Validation Error Response (400):**
```json
{
  "status": "failed",
  "message": "Validation failed",
  "data": {
    "Username": "Username is required",
    "Email": "Email is required"
  }
}
```

### 4. Update User

**Request:**
```http
PATCH /api/users HTTP/1.1
Content-Type: application/json

```

**Success Response (200):**
```json
{
  "status": "success",
  "message": "User updated successfully",
  "data": {
    "UserID": 1,
    "Name": "John Doe Updated",
    "Role": "senior_technician"
  }
}
```

### 5. Delete User

**Request:**
```http
DELETE /api/users/1 HTTP/1.1
```

**Success Response (200):**
```json
{
  "status": "success",
  "message": "User deleted successfully",
  "data": {
    "UserID": 1
  }
}
```

## Implementation Files

See `code-templates/` folder for ready-to-use code:
- `UserController.php` - Complete controller implementation
- `UserModel.php` - Database model
- `Routes-additions.php` - Routes to add to Routes.php

## Testing

After implementation, test with:

```bash
# List users
curl http://localhost:8000/api/users

# Get single user
curl http://localhost:8000/api/users/1

# Create user
curl -X POST http://localhost:8000/api/users \
  -H "Content-Type: application/json" \
  -d '{"Username":"test","Email":"test@test.com","Name":"Test User"}'

# Update user
curl -X PATCH http://localhost:8000/api/users \
  -H "Content-Type: application/json" \
  -d '{"UserID":1,"Name":"Updated Name"}'

# Delete user
curl -X DELETE http://localhost:8000/api/users/1
```