feat(api): add AI text-to-deck generation, wallet deposit structure, and profile/notification endpoints

Fills the gaps between the admin panel screens and the backend: a full
free-text + slide-count + language -> AI-generated presentation flow with
new slide-cloning logic in TemplateFillService, a "my presentations" list
endpoint, a swappable payment-gateway structure for wallet top-ups (fake
driver for now), and avatar upload / public-profile toggle / account
deletion / password change / notification preference endpoints.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

app/Http/Controllers/Api/TemplateGenerationController.php

@@ -2,9 +2,11 @@
 
 namespace App\Http\Controllers\Api;
 
+use App\Enums\TemplateGenerationSource;
 use App\Enums\TemplateGenerationStatus;
 use App\Enums\TemplateKeyType;
 use App\Http\Controllers\Controller;
+use App\Http\Requests\Api\GenerateAiPresentationRequest;
 use App\Http\Requests\Api\GenerateTemplateRequest;
 use App\Http\Resources\TemplateGenerationResource;
 use App\Jobs\GenerateTemplateJob;
@@ -12,6 +14,7 @@ use App\Models\Template;
 use App\Models\TemplateGeneration;
 use App\Traits\ApiResponse;
 use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
 use Illuminate\Http\Response;
 use Illuminate\Support\Facades\Storage;
 use Illuminate\Support\Str;
@@ -89,6 +92,117 @@ class TemplateGenerationController extends Controller
         ], 202);
     }
 
+    #[OA\Post(
+        path: '/templates/{slug}/generate-from-text',
+        description: 'Start generating a presentation from free-form text using AI',
+        summary: 'Generate presentation from text (AI)',
+        security: [['sanctum' => []]],
+        tags: ['Templates'],
+        parameters: [
+            new OA\Parameter(name: 'slug', description: 'Template slug', in: 'path', required: true, schema: new OA\Schema(type: 'string')),
+        ],
+        requestBody: new OA\RequestBody(
+            required: true,
+            content: new OA\JsonContent(
+                required: ['title', 'language', 'slide_count', 'text'],
+                properties: [
+                    new OA\Property(property: 'title', type: 'string', example: 'گزارش فروش سال ۱۴۰۴'),
+                    new OA\Property(property: 'language', type: 'string', example: 'fa'),
+                    new OA\Property(property: 'slide_count', type: 'integer', example: 10),
+                    new OA\Property(property: 'text', type: 'string', example: 'متن، عناوین، بولت‌ها و قوانین موردنظر...'),
+                ]
+            )
+        ),
+        responses: [
+            new OA\Response(
+                response: 202,
+                description: 'Generation started',
+                content: new OA\JsonContent(
+                    properties: [
+                        new OA\Property(property: 'message', type: 'string', example: 'درخواست تولید پاورپوینت ثبت شد.'),
+                        new OA\Property(
+                            property: 'data',
+                            properties: [
+                                new OA\Property(property: 'generation', ref: '#/components/schemas/TemplateGeneration'),
+                            ],
+                            type: 'object'
+                        ),
+                    ]
+                )
+            ),
+            new OA\Response(response: 401, description: 'Unauthenticated'),
+            new OA\Response(response: 422, description: 'Validation error'),
+        ]
+    )]
+    public function storeFromText(GenerateAiPresentationRequest $request, Template $template): JsonResponse
+    {
+        $generation = TemplateGeneration::query()->create([
+            'template_id' => $template->id,
+            'uuid' => (string) Str::uuid(),
+            'source' => TemplateGenerationSource::AiText,
+            'title' => $request->validated('title'),
+            'language' => $request->validated('language'),
+            'slide_count' => $request->validated('slide_count'),
+            'source_text' => $request->validated('text'),
+            'status' => TemplateGenerationStatus::Pending,
+            'requested_by' => $request->user()->id,
+        ]);
+
+        GenerateTemplateJob::dispatch($generation);
+
+        return $this->success('درخواست تولید پاورپوینت ثبت شد.', [
+            'generation' => new TemplateGenerationResource($generation),
+        ], 202);
+    }
+
+    #[OA\Get(
+        path: '/generations',
+        description: 'List the authenticated user presentation generations (both template-based and AI-generated)',
+        summary: 'List my presentations',
+        security: [['sanctum' => []]],
+        tags: ['Templates'],
+        parameters: [
+            new OA\Parameter(name: 'per_page', description: 'Items per page', in: 'query', schema: new OA\Schema(type: 'integer', example: 15)),
+        ],
+        responses: [
+            new OA\Response(
+                response: 200,
+                description: 'Generations fetched successfully',
+                content: new OA\JsonContent(
+                    properties: [
+                        new OA\Property(property: 'message', type: 'string', example: 'پاورپوینت‌های شما با موفقیت دریافت شد.'),
+                        new OA\Property(
+                            property: 'data',
+                            properties: [
+                                new OA\Property(
+                                    property: 'generations',
+                                    type: 'array',
+                                    items: new OA\Items(ref: '#/components/schemas/TemplateGeneration')
+                                ),
+                            ],
+                            type: 'object'
+                        ),
+                    ]
+                )
+            ),
+            new OA\Response(response: 401, description: 'Unauthenticated'),
+        ]
+    )]
+    public function index(Request $request): JsonResponse
+    {
+        $perPage = min(max((int) $request->integer('per_page', 15), 1), 100);
+
+        $generations = TemplateGeneration::query()
+            ->with('template')
+            ->where('requested_by', $request->user()->id)
+            ->latest()
+            ->paginate($perPage);
+
+        return $this->success('پاورپوینت‌های شما با موفقیت دریافت شد.', [
+            'generations' => TemplateGenerationResource::collection($generations)->response()->getData(true),
+        ]);
+    }
+
     #[OA\Get(
         path: '/generations/{uuid}',
         description: 'Get the status of a presentation generation request',