From cc926d466826e4125c684a4bdf57cfd06e23a765 Mon Sep 17 00:00:00 2001
From: SepehrYahyaee <7heycallmegray@gmail.com>
Date: Sun, 10 May 2026 14:29:32 +0330
Subject: [PATCH] deprecated some old APIs + added examples for login

---
 .../actor/actor.auth.controller.ts            | 58 ++++++++++++++++++-
 1 file changed, 57 insertions(+), 1 deletion(-)

diff --git a/src/auth/auth-controllers/actor/actor.auth.controller.ts b/src/auth/auth-controllers/actor/actor.auth.controller.ts
index 04d020c..dd83ea8 100644
--- a/src/auth/auth-controllers/actor/actor.auth.controller.ts
+++ b/src/auth/auth-controllers/actor/actor.auth.controller.ts
@@ -11,6 +11,7 @@ import {
 import {
   ApiBody,
   ApiAcceptedResponse,
+  ApiOperation,
   ApiResponse,
   ApiTags,
   ApiBearerAuth,
@@ -39,13 +40,33 @@ import { CurrentUser } from "src/decorators/user.decorator";
 export class ActorAuthController {
   constructor(private readonly actorAuthService: ActorAuthService) {}
 
+  /**
+   * @deprecated Use the unified actor onboarding flow instead. This endpoint
+   * will be removed in a future release.
+   */
   @Post("register/genuine")
+  @ApiOperation({
+    deprecated: true,
+    summary: "[DEPRECATED] Genuine actor registration",
+    description:
+      "Deprecated — kept only for legacy clients. Use the unified actor onboarding flow instead. Will be removed.",
+  })
   @ApiBody({ type: GenuineRegisterDto })
   async registerGenuine(@Body() body: GenuineRegisterDto) {
     return await this.actorAuthService.genuineRegister(body);
   }
 
+  /**
+   * @deprecated Use the unified actor onboarding flow instead. This endpoint
+   * will be removed in a future release.
+   */
   @Post("register/legal")
+  @ApiOperation({
+    deprecated: true,
+    summary: "[DEPRECATED] Legal actor registration",
+    description:
+      "Deprecated — kept only for legacy clients. Use the unified actor onboarding flow instead. Will be removed.",
+  })
   @ApiBody({ type: LegalRegisterDto })
   async registerLegal(@Body() body: LegalRegisterDto) {
     return await this.actorAuthService.legalRegister(body);
@@ -76,9 +97,44 @@ export class ActorAuthController {
   @UseGuards(LocalActorAuthGuard)
   @Post("login")
   @Roles()
+  @ApiOperation({
+    summary: "Actor login (returns access + refresh tokens)",
+    description:
+      "Authenticate any non-end-user actor (insurer/company, blame expert, damage expert, registrar, field expert, admin). Submit `role` as an array — e.g. `[\"damage_expert\"]` — together with the actor's email/`username` and password. On success the response contains the JWT pair and the resolved profile.",
+  })
   @ApiBody({
     type: LoginActorDto,
-    description: "user verify otp -- call this api and get a tokens",
+    description:
+      "Login payload. Pick one of the swagger examples below to see the exact body shape per role.",
+    examples: {
+      company: {
+        summary: "Insurer / company portal",
+        description: "Sample tenant credentials for the insurer (company) panel.",
+        value: {
+          role: "company",
+          username: "saman_insurer@gmail.com",
+          password: "123321",
+        },
+      },
+      expert: {
+        summary: "Blame expert panel",
+        description: "Sample credentials for a blame (`expert`) account.",
+        value: {
+          role: "expert",
+          username: "blame@gmail.com",
+          password: "123321",
+        },
+      },
+      damage_expert: {
+        summary: "Damage expert (claim) panel",
+        description: "Sample credentials for a damage-expert account.",
+        value: {
+          role: "damage_expert",
+          username: "claim@gmail.com",
+          password: "123321",
+        },
+      },
+    },
   })
   @ApiAcceptedResponse()
   async login(@Body() body, @Req() req, @ClientKey() client) {