Scope monthly invoice split endpoint

Co-authored-by: Jeppe Bundgaard <jb@truckwash.dk>

services/nginx/app/classes/limited_backoffice_service.php

@@ -112,6 +112,134 @@ class limited_backoffice_service
         ],
     ];
 
+    /**
+     * @var array<string, array{group:string,capability:string}>
+     */
+    private const ROLE_PERMISSION_CAPABILITIES = [
+        'user' => [
+            'group' => 'account',
+            'capability' => 'sign_in',
+        ],
+        'permissions_list_own' => [
+            'group' => 'account',
+            'capability' => 'view_own_permissions',
+        ],
+        'list_orders' => [
+            'group' => 'orders',
+            'capability' => 'view_orders',
+        ],
+        'add_order' => [
+            'group' => 'orders',
+            'capability' => 'create_orders',
+        ],
+        'edit_order' => [
+            'group' => 'orders',
+            'capability' => 'edit_orders',
+        ],
+        'delete_order' => [
+            'group' => 'orders',
+            'capability' => 'delete_orders',
+        ],
+        'list_order_items' => [
+            'group' => 'orders',
+            'capability' => 'view_order_items',
+        ],
+        'add_order_items' => [
+            'group' => 'orders',
+            'capability' => 'create_order_items',
+        ],
+        'edit_order_items' => [
+            'group' => 'orders',
+            'capability' => 'update_order_lines',
+        ],
+        'delete_order_items' => [
+            'group' => 'orders',
+            'capability' => 'remove_order_lines',
+        ],
+        'charge_order' => [
+            'group' => 'orders',
+            'capability' => 'charge_orders',
+        ],
+        'list_bookings' => [
+            'group' => 'bookings',
+            'capability' => 'view_department_bookings',
+        ],
+        'list_own_bookings' => [
+            'group' => 'bookings',
+            'capability' => 'view_own_bookings',
+        ],
+        'edit_bookings' => [
+            'group' => 'bookings',
+            'capability' => 'update_bookings',
+        ],
+        'add_booking' => [
+            'group' => 'bookings',
+            'capability' => 'create_bookings',
+        ],
+        'complete_bookings' => [
+            'group' => 'bookings',
+            'capability' => 'mark_bookings_complete',
+        ],
+        'resend_booking_confirmations' => [
+            'group' => 'bookings',
+            'capability' => 'send_booking_confirmations',
+        ],
+        'department_timebookings_entries_get' => [
+            'group' => 'time_bookings',
+            'capability' => 'view_time_booking_entries',
+        ],
+        'department_timebookings_entries_post' => [
+            'group' => 'time_bookings',
+            'capability' => 'create_time_booking_entries',
+        ],
+        'department_timebookings_entries_put' => [
+            'group' => 'time_bookings',
+            'capability' => 'edit_time_booking_entries',
+        ],
+        'statistics_orders_new' => [
+            'group' => 'reports',
+            'capability' => 'view_order_statistics',
+        ],
+        'statistics_bookings_new' => [
+            'group' => 'reports',
+            'capability' => 'view_booking_statistics',
+        ],
+        self::PERMISSION_ACCESS => [
+            'group' => 'limited_backoffice',
+            'capability' => 'open_limited_backoffice',
+        ],
+        self::PERMISSION_MANAGE_PRICES => [
+            'group' => 'limited_backoffice',
+            'capability' => 'manage_department_prices',
+        ],
+        self::PERMISSION_MANAGE_EMPLOYEES => [
+            'group' => 'limited_backoffice',
+            'capability' => 'manage_employee_access',
+        ],
+    ];
+
+    /**
+     * @var array<int, string>
+     */
+    private const ROLE_PERMISSION_GROUP_ORDER = [
+        'account',
+        'orders',
+        'bookings',
+        'time_bookings',
+        'reports',
+        'limited_backoffice',
+    ];
+
+    /**
+     * @var array<int, true>
+     */
+    private const PHONE_COUNTRY_CODES = [
+        45 => true,
+        46 => true,
+        47 => true,
+        358 => true,
+    ];
+
     /**
      * @var array<string, bool>
      */
@@ -123,7 +251,7 @@ class limited_backoffice_service
     }
 
     /**
-     * @return array<int, array{key:string,label:string,description:string}>
+     * @return array<int, array{key:string,label:string,description:string,permission_groups:array<int,array{key:string,capabilities:array<int,string>}>}>
      */
     public function rolePresets(): array
     {
@@ -133,11 +261,45 @@ class limited_backoffice_service
                 'key' => $key,
                 'label' => $preset['label'],
                 'description' => $preset['description'],
+                'permission_groups' => $this->rolePermissionGroups($preset['permissions']),
             ];
         }
         return $roles;
     }
 
+    /**
+     * @param array<int, string> $permissions
+     * @return array<int, array{key:string,capabilities:array<int,string>}>
+     */
+    private function rolePermissionGroups(array $permissions): array
+    {
+        $groups = [];
+        foreach ($permissions as $permission) {
+            $capability = self::ROLE_PERMISSION_CAPABILITIES[$permission] ?? null;
+            if ($capability === null) {
+                throw new \RuntimeException('Missing limited backoffice role capability for permission: ' . $permission);
+            }
+
+            $group = $capability['group'];
+            $groups[$group] ??= [];
+            $groups[$group][] = $capability['capability'];
+        }
+
+        $payload = [];
+        foreach (self::ROLE_PERMISSION_GROUP_ORDER as $group) {
+            if (!isset($groups[$group])) {
+                continue;
+            }
+
+            $payload[] = [
+                'key' => $group,
+                'capabilities' => array_values(array_unique($groups[$group])),
+            ];
+        }
+
+        return $payload;
+    }
+
     /**
      * @return array<int, int>
      */
@@ -382,7 +544,8 @@ class limited_backoffice_service
         $roleKey = $this->normalizeRoleKey($payload['role_key'] ?? null);
         $displayName = $this->normalizeRequiredString($payload['display_name'] ?? null, 'Display name is required.');
         $password = $this->normalizePassword($payload['password'] ?? null, true);
-        $email = $this->normalizeOptionalString($payload['email'] ?? null);
+        $email = $this->normalizeEmail($payload['email'] ?? null, true);
+        $phone = $this->normalizeOptionalPhonePair($payload);
 
         $mysqli = $this->mysqli();
         $mysqli->begin_transaction();
@@ -393,13 +556,23 @@ class limited_backoffice_service
             $passwordHash = password_hash($password, PASSWORD_DEFAULT);
 
             $statement = $mysqli->prepare(
-                'INSERT INTO `users` (`customer_number`, `display_name`, `email`, `password`, `group_id`)
-                 VALUES (?, ?, ?, ?, ?)'
+                'INSERT INTO `users`
+                    (`customer_number`, `display_name`, `email`, `password`, `group_id`, `phone_country_code`, `phone`)
+                 VALUES (?, ?, ?, ?, ?, ?, ?)'
             );
             if ($statement === false) {
                 throw new \RuntimeException('Unable to prepare employee insert.');
             }
-            $statement->bind_param('isssi', $customerNumber, $displayName, $email, $passwordHash, $groupId);
+            $statement->bind_param(
+                'isssiii',
+                $customerNumber,
+                $displayName,
+                $email,
+                $passwordHash,
+                $groupId,
+                $phone['phone_country_code'],
+                $phone['phone']
+            );
             $statement->execute();
             $employeeId = (int)$mysqli->insert_id;
             $statement->close();
@@ -477,11 +650,12 @@ class limited_backoffice_service
             ? $this->normalizeRequiredString($payload['display_name'], 'Display name is required.')
             : null;
         $email = array_key_exists('email', $payload)
-            ? $this->normalizeOptionalString($payload['email'])
+            ? $this->normalizeEmail($payload['email'], true)
             : null;
         $password = array_key_exists('password', $payload)
             ? $this->normalizePassword($payload['password'], false)
             : null;
+        $phone = $this->normalizeOptionalPhonePair($payload, false);
         $active = array_key_exists('active', $payload)
             ? (bool)$payload['active']
             : $this->isEmployeeRowActive($employee);
@@ -511,6 +685,10 @@ class limited_backoffice_service
             if ($password !== null) {
                 $userUpdates['password'] = password_hash($password, PASSWORD_DEFAULT);
             }
+            if ($phone !== null) {
+                $userUpdates['phone_country_code'] = $phone['phone_country_code'];
+                $userUpdates['phone'] = $phone['phone'];
+            }
             $usersHaveDeletedAt = $this->tableHasColumn('users', 'deleted_at');
             if ($active) {
                 $userUpdates['group_id'] = $managedGroupId;
@@ -909,6 +1087,89 @@ class limited_backoffice_service
         return $value === '' ? null : $value;
     }
 
+    private function normalizeEmail(mixed $value, bool $required): ?string
+    {
+        $email = $this->normalizeOptionalString($value);
+        if ($email === null) {
+            if ($required) {
+                throw new limited_backoffice_exception('Email is required.', 400);
+            }
+            return null;
+        }
+
+        if (filter_var($email, FILTER_VALIDATE_EMAIL) === false) {
+            throw new limited_backoffice_exception('Email must be a valid email address.', 400);
+        }
+
+        return $email;
+    }
+
+    /**
+     * @param array<string, mixed> $payload
+     * @return array{phone_country_code:int|null,phone:int|null}|null
+     */
+    private function normalizeOptionalPhonePair(array $payload, bool $defaultWhenMissing = true): ?array
+    {
+        $hasCountryCode = array_key_exists('phone_country_code', $payload);
+        $hasPhone = array_key_exists('phone', $payload);
+        if (!$hasCountryCode && !$hasPhone) {
+            return $defaultWhenMissing
+                ? ['phone_country_code' => null, 'phone' => null]
+                : null;
+        }
+
+        if (!$hasCountryCode || !$hasPhone) {
+            throw new limited_backoffice_exception('Phone country code and phone number must be provided together.', 400);
+        }
+
+        $countryCode = $this->normalizeOptionalDigits($payload['phone_country_code']);
+        $phone = $this->normalizeOptionalDigits($payload['phone']);
+        if ($countryCode === null && $phone === null) {
+            return ['phone_country_code' => null, 'phone' => null];
+        }
+
+        if ($countryCode === null || $phone === null) {
+            throw new limited_backoffice_exception('Phone country code and phone number must be provided together.', 400);
+        }
+
+        if (!isset(self::PHONE_COUNTRY_CODES[$countryCode])) {
+            throw new limited_backoffice_exception('Phone country code is not supported.', 400);
+        }
+
+        $phoneText = (string)$phone;
+        if (!preg_match('/^\d{4,15}$/', $phoneText)) {
+            throw new limited_backoffice_exception('Phone number must be 4-15 digits.', 400);
+        }
+
+        return [
+            'phone_country_code' => $countryCode,
+            'phone' => $phone,
+        ];
+    }
+
+    private function normalizeOptionalDigits(mixed $value): ?int
+    {
+        if ($value === null) {
+            return null;
+        }
+
+        if (is_int($value)) {
+            return $value > 0 ? $value : null;
+        }
+
+        if (is_string($value)) {
+            $value = trim($value);
+            if ($value === '') {
+                return null;
+            }
+            if (ctype_digit($value)) {
+                return (int)$value;
+            }
+        }
+
+        throw new limited_backoffice_exception('Phone values must contain digits only.', 400);
+    }
+
     private function normalizePassword(mixed $value, bool $required): ?string
     {
         if ($value === null || $value === '') {
@@ -1084,6 +1345,8 @@ class limited_backoffice_service
             'customer_number' => (int)$row['customer_number'],
             'display_name' => (string)($row['display_name'] ?? ''),
             'email' => $row['email'] === null ? null : (string)$row['email'],
+            'phone_country_code' => $row['phone_country_code'] === null ? null : (int)$row['phone_country_code'],
+            'phone' => $row['phone'] === null ? null : (int)$row['phone'],
             'active' => $active,
             'role' => $this->rolePayload((string)$row['role_key']),
             'departments' => $this->departmentSummaries($departmentIds),
@@ -1204,7 +1467,7 @@ class limited_backoffice_service
         $types = '';
         $values = [];
         foreach ($fields as $field => $value) {
-            if (!in_array($field, ['display_name', 'email', 'password', 'group_id', 'deleted_at'], true)) {
+            if (!in_array($field, ['display_name', 'email', 'password', 'group_id', 'deleted_at', 'phone_country_code', 'phone'], true)) {
                 continue;
             }
             if ($value === null) {

services/nginx/app/routes/orderInvoicesRoute.php

@@ -612,21 +612,46 @@ class orderInvoicesRoute
                     $preview ? 'User previewed splitting collected order invoices by month' : 'User split collected order invoices by order month'
                 );
 
-                $date_from = $db->escape_string($date_range['dateFrom']);
-                $date_to = $db->escape_string($date_range['dateTo']);
-                $sql = "SELECT DISTINCT invoice_collection_id
-                        FROM orders
-                        WHERE created_at BETWEEN '$date_from' AND '$date_to'
-                        AND invoice_collection_id IS NOT NULL
-                        AND invoice_collection_id > 0
-                        AND deleted_at IS NULL";
-                $query_result = $db->query($sql);
                 $invoice_collection_ids = [];
-                while ($row = $query_result->fetch_assoc()) {
-                    $invoice_collection_id = (int)($row['invoice_collection_id'] ?? 0);
-                    if ($invoice_collection_id > 0) {
+                if (self::isParametersSet(['invoice_collection_ids'])) {
+                    $invoice_collection_ids_raw = self::getParameter('invoice_collection_ids');
+                    if (!is_array($invoice_collection_ids_raw)) {
+                        $response->error('invoice_collection_ids must be an array', 400);
+                    }
+
+                    foreach ($invoice_collection_ids_raw as $invoice_collection_id_raw) {
+                        if (is_array($invoice_collection_id_raw) || is_object($invoice_collection_id_raw) || !is_numeric($invoice_collection_id_raw)) {
+                            $response->error('invoice_collection_ids must contain only positive integer ids', 400);
+                        }
+
+                        $invoice_collection_id = (int)$invoice_collection_id_raw;
+                        if ($invoice_collection_id < 1 || $invoice_collection_id > 999999999) {
+                            $response->error('invoice_collection_ids must contain only positive integer ids', 400);
+                        }
+
                         $invoice_collection_ids[] = $invoice_collection_id;
                     }
+
+                    $invoice_collection_ids = array_values(array_unique($invoice_collection_ids));
+                    if (empty($invoice_collection_ids)) {
+                        $response->error('invoice_collection_ids must contain at least one id', 400);
+                    }
+                } else {
+                    $date_from = $db->escape_string($date_range['dateFrom']);
+                    $date_to = $db->escape_string($date_range['dateTo']);
+                    $sql = "SELECT DISTINCT invoice_collection_id
+                            FROM orders
+                            WHERE created_at BETWEEN '$date_from' AND '$date_to'
+                            AND invoice_collection_id IS NOT NULL
+                            AND invoice_collection_id > 0
+                            AND deleted_at IS NULL";
+                    $query_result = $db->query($sql);
+                    while ($row = $query_result->fetch_assoc()) {
+                        $invoice_collection_id = (int)($row['invoice_collection_id'] ?? 0);
+                        if ($invoice_collection_id > 0) {
+                            $invoice_collection_ids[] = $invoice_collection_id;
+                        }
+                    }
                 }
 
                 $items = [];

services/nginx/app/tests/Api/CollectedInvoiceMonthlySplitApiTest.php

@@ -85,6 +85,65 @@ it('previews monthly split changes without moving orders or creating collections
         ->and(monthly_split_order_collection_id((int)$aprilOrder['id']))->toBe((int)$invoiceCollection['id']);
 });
 
+it('previews only explicit monthly split invoice collection ids', function (): void {
+    api_test_covers('POST /collected-invoices/split-by-month', 'preview-scope');
+
+    $customer = api_fixtures()->createUser(['display_name' => 'Scoped Preview Monthly Split Customer']);
+    $department = api_fixtures()->createDepartment();
+    $targetCollection = api_fixtures()->createInvoiceCollection([
+        'customer_number' => $customer['customer_number'],
+    ]);
+    $ignoredCollection = api_fixtures()->createInvoiceCollection([
+        'customer_number' => $customer['customer_number'],
+    ]);
+    $targetMarchOrder = api_fixtures()->createOrder([
+        'customer_id' => $customer['customer_number'],
+        'department_id' => $department['id'],
+        'invoice_collection_id' => $targetCollection['id'],
+        'created_at' => '2096-03-15 10:00:00',
+    ]);
+    $targetAprilOrder = api_fixtures()->createOrder([
+        'customer_id' => $customer['customer_number'],
+        'department_id' => $department['id'],
+        'invoice_collection_id' => $targetCollection['id'],
+        'created_at' => '2096-04-02 10:00:00',
+    ]);
+    $ignoredMarchOrder = api_fixtures()->createOrder([
+        'customer_id' => $customer['customer_number'],
+        'department_id' => $department['id'],
+        'invoice_collection_id' => $ignoredCollection['id'],
+        'created_at' => '2096-03-16 10:00:00',
+    ]);
+    $ignoredAprilOrder = api_fixtures()->createOrder([
+        'customer_id' => $customer['customer_number'],
+        'department_id' => $department['id'],
+        'invoice_collection_id' => $ignoredCollection['id'],
+        'created_at' => '2096-04-03 10:00:00',
+    ]);
+    $session = api_fixtures()->createUserSession(['split_collected_invoice']);
+
+    $response = api_client()->post('/collected-invoices/split-by-month', [
+        'dateFrom' => '2096-03-01',
+        'dateTo' => '2096-04-30',
+        'invoice_collection_ids' => [$targetCollection['id']],
+        'preview' => true,
+    ], $session['headers']);
+
+    $response
+        ->assertStatus(200)
+        ->assertEnvelope()
+        ->assertSuccess();
+
+    $payload = $response->data();
+    expect($payload['processed_count'] ?? null)->toBe(1)
+        ->and($payload['changed_count'] ?? null)->toBe(1)
+        ->and($payload['changed'][0]['invoice_collection_id'] ?? null)->toBe((int)$targetCollection['id'])
+        ->and(monthly_split_order_collection_id((int)$targetMarchOrder['id']))->toBe((int)$targetCollection['id'])
+        ->and(monthly_split_order_collection_id((int)$targetAprilOrder['id']))->toBe((int)$targetCollection['id'])
+        ->and(monthly_split_order_collection_id((int)$ignoredMarchOrder['id']))->toBe((int)$ignoredCollection['id'])
+        ->and(monthly_split_order_collection_id((int)$ignoredAprilOrder['id']))->toBe((int)$ignoredCollection['id']);
+});
+
 it('splits a selected March and April collected invoice into monthly collections', function (): void {
     api_test_covers('POST /collected-invoices/split-by-month', 'happy');
 
@@ -139,6 +198,74 @@ it('splits a selected March and April collected invoice into monthly collections
     }
 });
 
+it('splits only explicit monthly split invoice collection ids', function (): void {
+    api_test_covers('POST /collected-invoices/split-by-month', 'scope');
+
+    $customer = api_fixtures()->createUser(['display_name' => 'Scoped Monthly Split Customer']);
+    $department = api_fixtures()->createDepartment();
+    $targetCollection = api_fixtures()->createInvoiceCollection([
+        'customer_number' => $customer['customer_number'],
+        'created_at' => '2096-03-01 00:00:01',
+    ]);
+    $ignoredCollection = api_fixtures()->createInvoiceCollection([
+        'customer_number' => $customer['customer_number'],
+        'created_at' => '2096-03-01 00:00:01',
+    ]);
+    $targetMarchOrder = api_fixtures()->createOrder([
+        'customer_id' => $customer['customer_number'],
+        'department_id' => $department['id'],
+        'invoice_collection_id' => $targetCollection['id'],
+        'created_at' => '2096-03-15 10:00:00',
+    ]);
+    $targetAprilOrder = api_fixtures()->createOrder([
+        'customer_id' => $customer['customer_number'],
+        'department_id' => $department['id'],
+        'invoice_collection_id' => $targetCollection['id'],
+        'created_at' => '2096-04-02 10:00:00',
+    ]);
+    $ignoredMarchOrder = api_fixtures()->createOrder([
+        'customer_id' => $customer['customer_number'],
+        'department_id' => $department['id'],
+        'invoice_collection_id' => $ignoredCollection['id'],
+        'created_at' => '2096-03-16 10:00:00',
+    ]);
+    $ignoredAprilOrder = api_fixtures()->createOrder([
+        'customer_id' => $customer['customer_number'],
+        'department_id' => $department['id'],
+        'invoice_collection_id' => $ignoredCollection['id'],
+        'created_at' => '2096-04-03 10:00:00',
+    ]);
+    $session = api_fixtures()->createUserSession(['split_collected_invoice']);
+    $createdCollectionIds = [];
+
+    try {
+        $response = api_client()->post('/collected-invoices/split-by-month', [
+            'dateFrom' => '2096-03-01',
+            'dateTo' => '2096-04-30',
+            'invoice_collection_ids' => [$targetCollection['id']],
+        ], $session['headers']);
+
+        $response
+            ->assertStatus(200)
+            ->assertEnvelope()
+            ->assertSuccess();
+
+        $payload = $response->data();
+        $createdCollectionIds = (array)($payload['changed'][0]['created_invoice_collection_ids'] ?? []);
+        $aprilCollectionId = (int)($createdCollectionIds[0] ?? 0);
+
+        expect($payload['processed_count'] ?? null)->toBe(1)
+            ->and($payload['changed_count'] ?? null)->toBe(1)
+            ->and($aprilCollectionId)->toBeGreaterThan(0)
+            ->and(monthly_split_order_collection_id((int)$targetMarchOrder['id']))->toBe((int)$targetCollection['id'])
+            ->and(monthly_split_order_collection_id((int)$targetAprilOrder['id']))->toBe($aprilCollectionId)
+            ->and(monthly_split_order_collection_id((int)$ignoredMarchOrder['id']))->toBe((int)$ignoredCollection['id'])
+            ->and(monthly_split_order_collection_id((int)$ignoredAprilOrder['id']))->toBe((int)$ignoredCollection['id']);
+    } finally {
+        monthly_split_cleanup_collections($createdCollectionIds);
+    }
+});
+
 it('sets closed_at to month end when split month has ended', function (): void {
     api_test_covers('POST /collected-invoices/split-by-month', 'closed-at');
 
@@ -345,3 +472,27 @@ it('rejects invalid monthly split date ranges', function (): void {
         ->assertEnvelope()
         ->assertSuccess(false);
 });
+
+it('rejects invalid explicit monthly split invoice collection ids', function (): void {
+    api_test_covers('POST /collected-invoices/split-by-month', 'invalid-scope');
+
+    $session = api_fixtures()->createUserSession(['split_collected_invoice']);
+
+    api_client()->post('/collected-invoices/split-by-month', [
+        'dateFrom' => '2096-03-01',
+        'dateTo' => '2096-04-30',
+        'invoice_collection_ids' => ['not-a-number'],
+    ], $session['headers'])
+        ->assertStatus(400)
+        ->assertEnvelope()
+        ->assertSuccess(false);
+
+    api_client()->post('/collected-invoices/split-by-month', [
+        'dateFrom' => '2096-03-01',
+        'dateTo' => '2096-04-30',
+        'invoice_collection_ids' => [],
+    ], $session['headers'])
+        ->assertStatus(400)
+        ->assertEnvelope()
+        ->assertSuccess(false);
+});

services/nginx/app/tests/Api/LimitedBackofficeApiTest.php

@@ -348,11 +348,60 @@ it('creates updates lists and deactivates scoped employees without exposing raw
         ->assertSuccess();
 
     expect(array_column($roles->data(), 'key'))->toBe(['viewer', 'cashier', 'booking_coordinator', 'operations_lead', 'department_admin']);
+    $rolesByKey = array_column($roles->data(), null, 'key');
+    expect($rolesByKey['viewer']['permission_groups'] ?? null)->toBe([
+        [
+            'key' => 'account',
+            'capabilities' => ['sign_in', 'view_own_permissions'],
+        ],
+    ]);
+    $departmentAdminGroups = array_column($rolesByKey['department_admin']['permission_groups'] ?? [], 'capabilities', 'key');
+    expect($departmentAdminGroups['limited_backoffice'] ?? null)->toBe([
+        'open_limited_backoffice',
+        'manage_department_prices',
+        'manage_employee_access',
+    ]);
     expect($roles->body)->not->toContain('department_access_');
+    $rolePayload = $roles->data();
+    $rolePayloadStrings = [];
+    array_walk_recursive($rolePayload, static function ($value) use (&$rolePayloadStrings): void {
+        if (is_string($value)) {
+            $rolePayloadStrings[] = $value;
+        }
+    });
+    foreach ([
+        'list_orders',
+        'add_order',
+        'edit_order',
+        'delete_order',
+        'list_order_items',
+        'add_order_items',
+        'edit_order_items',
+        'delete_order_items',
+        'charge_order',
+        'list_bookings',
+        'list_own_bookings',
+        'edit_bookings',
+        'add_booking',
+        'complete_bookings',
+        'resend_booking_confirmations',
+        'department_timebookings_entries_get',
+        'department_timebookings_entries_post',
+        'department_timebookings_entries_put',
+        'statistics_orders_new',
+        'statistics_bookings_new',
+        'limited_backoffice_access',
+        'limited_backoffice_prices_manage',
+        'limited_backoffice_employees_manage',
+    ] as $rawPermission) {
+        expect($rolePayloadStrings)->not->toContain($rawPermission);
+    }
 
     $created = api_client()->post('/limited-backoffice/employees', [
         'display_name' => 'Limited Cashier',
         'email' => 'limited-cashier@example.test',
+        'phone_country_code' => 45,
+        'phone' => 12345678,
         'password' => 'Secret123!',
         'role_key' => 'cashier',
         'department_ids' => [(int)$department['id']],
@@ -366,6 +415,9 @@ it('creates updates lists and deactivates scoped employees without exposing raw
     $employeeId = (int)($created->data()['id'] ?? 0);
     expect($employeeId)->toBeGreaterThan(0);
     limited_backoffice_cleanup_created_employee($employeeId);
+    expect($created->data()['email'] ?? null)->toBe('limited-cashier@example.test');
+    expect($created->data()['phone_country_code'] ?? null)->toBe(45);
+    expect($created->data()['phone'] ?? null)->toBe(12345678);
     expect($created->body)->not->toContain('department_access_');
     expect($created->body)->not->toContain('permissions');
 
@@ -384,6 +436,9 @@ it('creates updates lists and deactivates scoped employees without exposing raw
 
     $updated = api_client()->put('/limited-backoffice/employees/' . $employeeId, [
         'display_name' => 'Limited Lead',
+        'email' => 'limited-lead@example.test',
+        'phone_country_code' => 358,
+        'phone' => 87654321,
         'role_key' => 'operations_lead',
         'department_ids' => [(int)$department['id']],
     ], $session['headers']);
@@ -393,11 +448,25 @@ it('creates updates lists and deactivates scoped employees without exposing raw
         ->assertSuccess();
 
     expect($updated->data()['display_name'] ?? null)->toBe('Limited Lead');
+    expect($updated->data()['email'] ?? null)->toBe('limited-lead@example.test');
+    expect($updated->data()['phone_country_code'] ?? null)->toBe(358);
+    expect($updated->data()['phone'] ?? null)->toBe(87654321);
     expect($updated->data()['role']['key'] ?? null)->toBe('operations_lead');
 
     $list = api_client()->get('/limited-backoffice/employees', $session['headers']);
     $ids = array_column($list->data(), 'id');
     expect($ids)->toContain($employeeId);
+    $listedEmployee = null;
+    foreach ($list->data() as $employee) {
+        if ((int)($employee['id'] ?? 0) === $employeeId) {
+            $listedEmployee = $employee;
+            break;
+        }
+    }
+    expect($listedEmployee)->not->toBeNull();
+    expect($listedEmployee['email'] ?? null)->toBe('limited-lead@example.test');
+    expect($listedEmployee['phone_country_code'] ?? null)->toBe(358);
+    expect($listedEmployee['phone'] ?? null)->toBe(87654321);
     expect($list->body)->not->toContain('department_access_');
 
     $deactivated = api_client()->delete('/limited-backoffice/employees/' . $employeeId, null, $session['headers']);
@@ -419,6 +488,34 @@ it('creates updates lists and deactivates scoped employees without exposing raw
     });
 });
 
+it('accepts employees without optional phone details', function (): void {
+    api_test_covers('POST /limited-backoffice/employees', 'happy');
+
+    $department = api_fixtures()->createDepartment(['name' => 'Limited Employee No Phone']);
+    $session = limited_backoffice_manager_session([(int)$department['id']]);
+
+    $created = api_client()->post('/limited-backoffice/employees', [
+        'display_name' => 'Limited No Phone',
+        'email' => 'limited-no-phone@example.test',
+        'password' => 'Secret123!',
+        'role_key' => 'viewer',
+        'department_ids' => [(int)$department['id']],
+    ], $session['headers']);
+
+    $created
+        ->assertStatus(200)
+        ->assertEnvelope()
+        ->assertSuccess();
+
+    $employeeId = (int)($created->data()['id'] ?? 0);
+    expect($employeeId)->toBeGreaterThan(0);
+    limited_backoffice_cleanup_created_employee($employeeId);
+    expect(array_key_exists('phone_country_code', $created->data()))->toBeTrue();
+    expect(array_key_exists('phone', $created->data()))->toBeTrue();
+    expect($created->data()['phone_country_code'])->toBeNull();
+    expect($created->data()['phone'])->toBeNull();
+});
+
 it('rejects employee scopes roles raw permissions self edits superusers and shared groups', function (): void {
     api_test_covers('POST /limited-backoffice/employees', 'validation');
     api_test_covers('PUT /limited-backoffice/employees/{employeeId}', 'validation');
@@ -429,6 +526,7 @@ it('rejects employee scopes roles raw permissions self edits superusers and shar
 
     api_client()->post('/limited-backoffice/employees', [
         'display_name' => 'Outside Employee',
+        'email' => 'outside@example.test',
         'password' => 'Secret123!',
         'role_key' => 'cashier',
         'department_ids' => [(int)$otherDepartment['id']],
@@ -440,6 +538,7 @@ it('rejects employee scopes roles raw permissions self edits superusers and shar
 
     api_client()->post('/limited-backoffice/employees', [
         'display_name' => 'Raw Employee',
+        'email' => 'raw@example.test',
         'password' => 'Secret123!',
         'role_key' => 'cashier',
         'department_ids' => [(int)$department['id']],
@@ -452,6 +551,7 @@ it('rejects employee scopes roles raw permissions self edits superusers and shar
 
     api_client()->post('/limited-backoffice/employees', [
         'display_name' => 'Unknown Role Employee',
+        'email' => 'unknown-role@example.test',
         'password' => 'Secret123!',
         'role_key' => 'superuser',
         'department_ids' => [(int)$department['id']],
@@ -504,3 +604,88 @@ it('rejects employee scopes roles raw permissions self edits superusers and shar
         ->assertSuccess(false)
         ->assertMessage('Cannot manage shared groups.');
 });
+
+it('rejects invalid limited backoffice employee contact details', function (): void {
+    api_test_covers('POST /limited-backoffice/employees', 'validation');
+    api_test_covers('PUT /limited-backoffice/employees/{employeeId}', 'validation');
+
+    $department = api_fixtures()->createDepartment(['name' => 'Limited Employee Contact Validation']);
+    $session = limited_backoffice_manager_session([(int)$department['id']]);
+    $basePayload = [
+        'display_name' => 'Contact Employee',
+        'email' => 'contact@example.test',
+        'password' => 'Secret123!',
+        'role_key' => 'viewer',
+        'department_ids' => [(int)$department['id']],
+    ];
+
+    api_client()->post('/limited-backoffice/employees', array_diff_key($basePayload, ['email' => true]), $session['headers'])
+        ->assertStatus(400)
+        ->assertEnvelope()
+        ->assertSuccess(false)
+        ->assertMessage('Email is required.');
+
+    api_client()->post('/limited-backoffice/employees', [
+        ...$basePayload,
+        'email' => 'not-an-email',
+    ], $session['headers'])
+        ->assertStatus(400)
+        ->assertEnvelope()
+        ->assertSuccess(false)
+        ->assertMessage('Email must be a valid email address.');
+
+    api_client()->post('/limited-backoffice/employees', [
+        ...$basePayload,
+        'phone_country_code' => 45,
+    ], $session['headers'])
+        ->assertStatus(400)
+        ->assertEnvelope()
+        ->assertSuccess(false)
+        ->assertMessage('Phone country code and phone number must be provided together.');
+
+    api_client()->post('/limited-backoffice/employees', [
+        ...$basePayload,
+        'phone_country_code' => 1,
+        'phone' => 12345678,
+    ], $session['headers'])
+        ->assertStatus(400)
+        ->assertEnvelope()
+        ->assertSuccess(false)
+        ->assertMessage('Phone country code is not supported.');
+
+    api_client()->post('/limited-backoffice/employees', [
+        ...$basePayload,
+        'phone_country_code' => 45,
+        'phone' => '12ab',
+    ], $session['headers'])
+        ->assertStatus(400)
+        ->assertEnvelope()
+        ->assertSuccess(false)
+        ->assertMessage('Phone values must contain digits only.');
+
+    $created = api_client()->post('/limited-backoffice/employees', $basePayload, $session['headers'])
+        ->assertStatus(200)
+        ->assertEnvelope()
+        ->assertSuccess();
+
+    $employeeId = (int)($created->data()['id'] ?? 0);
+    expect($employeeId)->toBeGreaterThan(0);
+    limited_backoffice_cleanup_created_employee($employeeId);
+
+    api_client()->put('/limited-backoffice/employees/' . $employeeId, [
+        'email' => '',
+    ], $session['headers'])
+        ->assertStatus(400)
+        ->assertEnvelope()
+        ->assertSuccess(false)
+        ->assertMessage('Email is required.');
+
+    api_client()->put('/limited-backoffice/employees/' . $employeeId, [
+        'phone_country_code' => 45,
+        'phone' => '123',
+    ], $session['headers'])
+        ->assertStatus(400)
+        ->assertEnvelope()
+        ->assertSuccess(false)
+        ->assertMessage('Phone number must be 4-15 digits.');
+});