refactor: fix 7 CRUD system inconsistencies for robustness and maintainability

- Add user-assignment dependency check to DepartmentService.deleteByUuid (409 when users assigned)
- Standardize POST detection to isMethod('POST') in 10 create/edit actions
- Align RoleService code uniqueness to warning pattern (matching departments)
- Normalize repository create() return types from mixed to int|false (3 repos + 3 interfaces)
- Add JSON response branches to 4 non-user delete actions
- Document delete authorization ordering pattern
- Decompose AdminSettingsService.updateFromAdmin into domain-scoped private methods

Workflow: .agents/runs/CRUD-CONSISTENCY-001/
Reviewed by: Code Reviewer (pass), Security Reviewer (pass), Acceptance Tester (pass)
Quality gates: QG-001 PHPUnit pass, QG-002 PHPStan pass, QG-003 Architecture pass

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

pages/admin/roles/create().php

@@ -26,6 +26,7 @@ if (!$decision->isAllowed()) {
 
 $errorBag = formErrors();
 $errors = [];
+$warnings = [];
 $form = [
     'description' => '',
     'code' => '',
@@ -42,7 +43,7 @@ if ($request->isMethod('POST') && !Session::checkCsrfToken()) {
     return;
 }
 
-if ($request->hasBody('description')) {
+if ($request->isMethod('POST')) {
     $dbSession = app(\MintyPHP\Repository\Support\DatabaseSessionRepository::class);
     $transactionStarted = false;
 
@@ -52,6 +53,7 @@ if ($request->hasBody('description')) {
 
         $result = app(\MintyPHP\Service\Access\RoleService::class)->createFromAdmin($request->bodyAll(), $currentUserId);
         $form = $result['form'] ?? $form;
+        $warnings = $result['warnings'] ?? [];
         $errorBag->merge($result['errors'] ?? []);
         $selectedPermissionIds = $request->body('permission_ids', $selectedPermissionIds);
         if (!is_array($selectedPermissionIds)) {
@@ -75,15 +77,24 @@ if ($request->hasBody('description')) {
 
             $action = (string) $request->body('action', 'create');
             if ($action === 'create_close') {
+                if ($warnings) {
+                    Flash::info(implode(' ', $warnings), $closeTarget, 'role_warning');
+                }
                 Flash::success('Role created', $closeTarget, 'role_created');
                 Router::redirect($closeTarget);
             } else {
                 $uuid = (string) ($result['uuid'] ?? '');
                 if ($uuid !== '') {
                     $target = requestPathWithReturnTarget("admin/roles/edit/{$uuid}", $returnTarget);
+                    if ($warnings) {
+                        Flash::info(implode(' ', $warnings), $target, 'role_warning');
+                    }
                     Flash::success('Role created', $target, 'role_created');
                     Router::redirect($target);
                 } else {
+                    if ($warnings) {
+                        Flash::info(implode(' ', $warnings), $closeTarget, 'role_warning');
+                    }
                     Flash::success('Role created', $closeTarget, 'role_created');
                     Router::redirect($closeTarget);
                 }

pages/admin/roles/create(default).phtml

@@ -42,6 +42,15 @@
     $validationSummaryErrors = $validationSummaryErrors ?? ($errors ?? []);
     require templatePath('partials/app-details-validation-summary.phtml');
     ?>
+    <?php if (!empty($warnings)): ?>
+      <div class="notice" data-variant="info">
+        <ul>
+          <?php foreach ($warnings as $warning): ?>
+            <li><?php e($warning); ?></li>
+          <?php endforeach; ?>
+        </ul>
+      </div>
+    <?php endif; ?>
     <?php
     $values = $form ?? [];
     $detailsOpenAll = true;

pages/admin/roles/delete($id).php

@@ -1,5 +1,6 @@
 <?php
 
+use MintyPHP\Http\Request;
 use MintyPHP\Http\SessionStoreInterface;
 use MintyPHP\Router;
 use MintyPHP\Service\Access\RoleAuthorizationPolicy;
@@ -11,10 +12,18 @@ Guard::requireLogin();
 
 $currentUserId = (int) ($session['user']['id'] ?? 0);
 $authorizationService = app(\MintyPHP\Service\Access\AuthorizationService::class);
+// Authorization is checked generically (can user delete ANY role?) before loading the entity.
+// Context-aware policies (departments, tenants, users) load the entity first to pass target_id.
+// Both patterns are valid; context-aware is preferred for new code.
 $decision = $authorizationService->authorize(RoleAuthorizationPolicy::ABILITY_ADMIN_ROLES_DELETE, [
     'actor_user_id' => $currentUserId,
 ]);
 if (!$decision->isAllowed()) {
+    if (Request::wantsJson()) {
+        http_response_code($decision->status());
+        Router::json(['error' => $decision->error()]);
+        return;
+    }
     Guard::deny();
 }
 
@@ -35,18 +44,31 @@ if ($role) {
 
 $result = app(\MintyPHP\Service\Access\RoleService::class)->deleteByUuid($uuid);
 if (!($result['ok'] ?? false)) {
-    $error = $result['error'] ?? 'unknown';
+    $error = $result['error'] ?? 'not_found';
+    $status = $result['status'] ?? 500;
+    if (Request::wantsJson()) {
+        http_response_code($status);
+        Router::json(['error' => $error]);
+        return;
+    }
     if ($error === 'admin_role_protected') {
         Flash::error('The Admin role cannot be deleted', 'admin/roles', 'admin_role_protected');
     } else {
         Flash::error('Role not found', 'admin/roles', 'role_not_found');
     }
     Router::redirect('admin/roles');
+    return;
 }
 
 if ($affectedUserIds) {
     app(\MintyPHP\Repository\User\UserWriteRepository::class)->bumpAuthzVersionByUserIds($affectedUserIds);
 }
 
+if (Request::wantsJson()) {
+    http_response_code(204);
+    Router::json([]);
+    return;
+}
+
 Flash::success('Role deleted', 'admin/roles', 'role_deleted');
 Router::redirect('admin/roles');

pages/admin/roles/edit($id).php

@@ -44,6 +44,7 @@ app(\MintyPHP\Service\Audit\AuditMetadataEnricher::class)->enrich($role);
 
 $errorBag = formErrors();
 $errors = [];
+$warnings = [];
 $form = $role;
 $permissions = $permissionRepository->listActive();
 $selectedPermissionIds = $rolePermissionRepository->listPermissionIdsByRoleId($roleId);
@@ -58,7 +59,7 @@ if ($request->isMethod('POST') && !Session::checkCsrfToken()) {
     return;
 }
 
-if ($request->hasBody('description')) {
+if ($request->isMethod('POST')) {
     $submitDecision = $authorizationService->authorize(RoleAuthorizationPolicy::ABILITY_ADMIN_ROLES_EDIT_SUBMIT, [
         'actor_user_id' => $currentUserId,
         'target_role_id' => $roleId,
@@ -68,6 +69,7 @@ if ($request->hasBody('description')) {
     }
     $result = app(\MintyPHP\Service\Access\RoleService::class)->updateFromAdmin($roleId, $request->bodyAll(), $currentUserId);
     $form = $result['form'] ?? $form;
+    $warnings = $result['warnings'] ?? [];
     $errorBag->merge($result['errors'] ?? []);
     $selectedPermissionIds = $request->body('permission_ids', $selectedPermissionIds);
     if (!is_array($selectedPermissionIds)) {
@@ -108,9 +110,15 @@ if ($request->hasBody('description')) {
         if ($syncSucceeded) {
             $action = (string) $request->body('action', 'save');
             if ($action === 'save_close') {
+                if ($warnings) {
+                    Flash::info(implode(' ', $warnings), $closeTarget, 'role_warning');
+                }
                 Flash::success('Role updated', $closeTarget, 'role_updated');
                 Router::redirect($closeTarget);
             } else {
+                if ($warnings) {
+                    Flash::info(implode(' ', $warnings), $editTarget, 'role_warning');
+                }
                 Flash::success('Role updated', $editTarget, 'role_updated');
                 Router::redirect($editTarget);
             }

pages/admin/roles/edit(default).phtml

@@ -53,6 +53,15 @@ $isReadOnly = !$canUpdateRole;
     $validationSummaryErrors = $validationSummaryErrors ?? ($errors ?? []);
     require templatePath('partials/app-details-validation-summary.phtml');
     ?>
+    <?php if (!empty($warnings)): ?>
+      <div class="notice" data-variant="info">
+        <ul>
+          <?php foreach ($warnings as $warning): ?>
+            <li><?php e($warning); ?></li>
+          <?php endforeach; ?>
+        </ul>
+      </div>
+    <?php endif; ?>
 
     <?php
     $detailsOpenAll = true;