feat: crowd lists audit, enum, factory, service and tests

Audit and complete the Crowd Lists module:
- Add CrowdListType enum (internal/external) with proper casts
- Create CrowdListService for business logic (add/remove person,
  max_persons enforcement, auto_approve, activity logging)
- Create CrowdListFactory with Dutch names and states
- Create AddPersonToCrowdListRequest form request
- Fix FormRequests to use Rule::enum instead of hardcoded strings
- Fix CrowdListResource to use enum->value and add is_full field
- Refactor controller to be thin (delegates to service)
- Add eager loading for crowdType and recipientCompany
- Write 18 comprehensive tests (CRUD, auth, edge cases)
- Update API.md with request/response documentation

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

api/app/Http/Controllers/Api/V1/CrowdListController.php

@@ -5,24 +5,32 @@ declare(strict_types=1);
 namespace App\Http\Controllers\Api\V1;
 
 use App\Http\Controllers\Controller;
+use App\Http\Requests\Api\V1\AddPersonToCrowdListRequest;
 use App\Http\Requests\Api\V1\StoreCrowdListRequest;
 use App\Http\Requests\Api\V1\UpdateCrowdListRequest;
 use App\Http\Resources\Api\V1\CrowdListResource;
 use App\Models\CrowdList;
 use App\Models\Event;
 use App\Models\Person;
+use App\Services\CrowdListService;
 use Illuminate\Http\JsonResponse;
-use Illuminate\Http\Request;
 use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
 use Illuminate\Support\Facades\Gate;
 
 final class CrowdListController extends Controller
 {
+    public function __construct(
+        private readonly CrowdListService $crowdListService,
+    ) {}
+
     public function index(Event $event): AnonymousResourceCollection
     {
         Gate::authorize('viewAny', [CrowdList::class, $event]);
 
-        $crowdLists = $event->crowdLists()->withCount('persons')->get();
+        $crowdLists = $event->crowdLists()
+            ->with(['crowdType', 'recipientCompany'])
+            ->withCount('persons')
+            ->get();
 
         return CrowdListResource::collection($crowdLists);
     }
@@ -31,43 +39,36 @@ final class CrowdListController extends Controller
     {
         Gate::authorize('create', [CrowdList::class, $event]);
 
-        $crowdList = $event->crowdLists()->create($request->validated());
+        $crowdList = $this->crowdListService->create($event, $request->validated(), $request->user());
 
-        return $this->created(new CrowdListResource($crowdList));
+        return $this->created(new CrowdListResource($crowdList->loadCount('persons')));
     }
 
     public function update(UpdateCrowdListRequest $request, Event $event, CrowdList $crowdList): JsonResponse
     {
         Gate::authorize('update', [$crowdList, $event]);
 
-        $crowdList->update($request->validated());
+        $crowdList = $this->crowdListService->update($crowdList, $request->validated(), $request->user());
 
-        return $this->success(new CrowdListResource($crowdList->fresh()));
+        return $this->success(new CrowdListResource($crowdList->loadCount('persons')));
     }
 
     public function destroy(Event $event, CrowdList $crowdList): JsonResponse
     {
         Gate::authorize('delete', [$crowdList, $event]);
 
-        $crowdList->delete();
+        $this->crowdListService->delete($crowdList, request()->user());
 
         return response()->json(null, 204);
     }
 
-    public function addPerson(Request $request, Event $event, CrowdList $crowdList): JsonResponse
+    public function addPerson(AddPersonToCrowdListRequest $request, Event $event, CrowdList $crowdList): JsonResponse
     {
         Gate::authorize('managePerson', [$crowdList, $event]);
 
-        $validated = $request->validate([
-            'person_id' => ['required', 'ulid', 'exists:persons,id'],
-        ]);
+        $person = Person::findOrFail($request->validated('person_id'));
 
-        $crowdList->persons()->syncWithoutDetaching([
-            $validated['person_id'] => [
-                'added_at' => now(),
-                'added_by_user_id' => $request->user()->id,
-            ],
-        ]);
+        $this->crowdListService->addPerson($crowdList, $person, $request->user());
 
         return $this->success(new CrowdListResource($crowdList->fresh()->loadCount('persons')));
     }
@@ -76,7 +77,7 @@ final class CrowdListController extends Controller
     {
         Gate::authorize('managePerson', [$crowdList, $event]);
 
-        $crowdList->persons()->detach($person->id);
+        $this->crowdListService->removePerson($crowdList, $person, request()->user());
 
         return response()->json(null, 204);
     }

api/app/Http/Requests/Api/V1/AddPersonToCrowdListRequest.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests\Api\V1;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+final class AddPersonToCrowdListRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /** @return array<string, mixed> */
+    public function rules(): array
+    {
+        return [
+            'person_id' => ['required', 'ulid', 'exists:persons,id'],
+        ];
+    }
+}

api/app/Http/Requests/Api/V1/StoreCrowdListRequest.php

@@ -4,7 +4,9 @@ declare(strict_types=1);
 
 namespace App\Http\Requests\Api\V1;
 
+use App\Enums\CrowdListType;
 use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
 
 final class StoreCrowdListRequest extends FormRequest
 {
@@ -19,7 +21,7 @@ final class StoreCrowdListRequest extends FormRequest
         return [
             'crowd_type_id' => ['required', 'ulid', 'exists:crowd_types,id'],
             'name' => ['required', 'string', 'max:255'],
-            'type' => ['required', 'in:internal,external'],
+            'type' => ['required', Rule::enum(CrowdListType::class)],
             'recipient_company_id' => ['nullable', 'ulid', 'exists:companies,id'],
             'auto_approve' => ['sometimes', 'boolean'],
             'max_persons' => ['nullable', 'integer', 'min:1'],

api/app/Http/Requests/Api/V1/UpdateCrowdListRequest.php

@@ -4,7 +4,9 @@ declare(strict_types=1);
 
 namespace App\Http\Requests\Api\V1;
 
+use App\Enums\CrowdListType;
 use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
 
 final class UpdateCrowdListRequest extends FormRequest
 {
@@ -19,7 +21,7 @@ final class UpdateCrowdListRequest extends FormRequest
         return [
             'crowd_type_id' => ['sometimes', 'ulid', 'exists:crowd_types,id'],
             'name' => ['sometimes', 'string', 'max:255'],
-            'type' => ['sometimes', 'in:internal,external'],
+            'type' => ['sometimes', Rule::enum(CrowdListType::class)],
             'recipient_company_id' => ['nullable', 'ulid', 'exists:companies,id'],
             'auto_approve' => ['sometimes', 'boolean'],
             'max_persons' => ['nullable', 'integer', 'min:1'],

api/app/Http/Resources/Api/V1/CrowdListResource.php

@@ -11,17 +11,22 @@ final class CrowdListResource extends JsonResource
 {
     public function toArray(Request $request): array
     {
+        $personsCount = $this->whenCounted('persons');
+
         return [
             'id' => $this->id,
             'event_id' => $this->event_id,
             'crowd_type_id' => $this->crowd_type_id,
             'name' => $this->name,
-            'type' => $this->type,
+            'type' => $this->type->value,
             'recipient_company_id' => $this->recipient_company_id,
             'auto_approve' => $this->auto_approve,
             'max_persons' => $this->max_persons,
+            'is_full' => $this->max_persons !== null && isset($this->persons_count)
+                ? $this->persons_count >= $this->max_persons
+                : false,
             'created_at' => $this->created_at->toIso8601String(),
-            'persons_count' => $this->whenCounted('persons'),
+            'persons_count' => $personsCount,
         ];
     }
 }