agent foundation

lib/Service/Org/DepartmentService.php

@@ -26,6 +26,7 @@ class DepartmentService
 
     public function listPaged(array $options): array
     {
+        // Global-scope users see all departments — remove tenant filter so the query isn't restricted.
         if (!empty($options['tenantUserId'])) {
             $tenantUserId = (int) $options['tenantUserId'];
             if ($tenantUserId > 0 && $this->scopeGateway->hasGlobalAccess($tenantUserId)) {
@@ -78,6 +79,8 @@ class DepartmentService
         return $this->departmentRepository->listByIds($departmentIds);
     }
 
+    // Merges the tenant-scoped list with any already-selected departments outside the filter —
+    // ensures a user keeps visibility of departments they're already assigned to.
     public function listForUserAssignments(array $tenantIds, array $selectedDepartmentIds): array
     {
         $departments = $tenantIds ? $this->listByTenantIds($tenantIds) : $this->list();
@@ -192,6 +195,8 @@ class DepartmentService
         return ['ok' => true, 'form' => $form, 'warnings' => $warnings];
     }
 
+    // After moving a department to a different tenant, users who aren't in the new tenant
+    // are no longer valid members — remove their assignments immediately.
     public function syncTenant(int $departmentId, int $tenantId): int
     {
         $updated = $this->departmentRepository->setTenant($departmentId, $tenantId);
@@ -201,6 +206,7 @@ class DepartmentService
         return $this->cleanupUserAssignments($departmentId);
     }
 
+    // Departments belong to exactly one tenant — only the first ID in the array is used.
     public function syncTenants(int $departmentId, array $tenantIds): int
     {
         $tenantId = (int) ($tenantIds[0] ?? 0);
@@ -266,6 +272,8 @@ class DepartmentService
         return $errors;
     }
 
+    // Duplicate codes are a warning, not a hard error — codes are optional identifiers,
+    // not unique keys, so duplicates are allowed but surfaced to the user.
     private function warningsForCode(array $form, int $excludeId): array
     {
         $warnings = [];