user owner guidence added + status and steps fixed

src/claim-request-management/claim-request-management.v2.controller.ts

@@ -85,7 +85,7 @@ export class ClaimRequestManagementV2Controller {
   @ApiOperation({
     summary: "Get Claim Details (V2)",
     description:
-      "Get claim details for current actor. USER (claim owner) receives the same core claim payload including `owner` (userId, clientId, optional userClientKey). FIELD_EXPERT additionally receives unmasked money and userRating when present.",
+      "Returns the claim snapshot for **USER** (owner) or **FIELD_EXPERT** when permitted. Owners get `ownerGuidance`: `{ phaseKey, headline, nextActions[] (method + pathTemplate), objectionAllowed }` mapped from `status` / `claimStatus` / workflow so the client can show the correct screen without duplicating orchestration logic. FIELD_EXPERT does not receive `ownerGuidance`. Core payload includes documents, captures, evaluation replies, optional expert resend, and masked bank info.",
   })
   @ApiResponse({
     status: 200,
@@ -156,9 +156,11 @@ export class ClaimRequestManagementV2Controller {
   @ApiOperation({
     summary: "Submit user objection (V2)",
     description:
-      "After the damage expert submits a resend request (`damageExpertResend`), the owner may dispute priced parts " +
-      "and/or propose additional damaged parts. Stores a structured payload on `evaluation.objection`, merges " +
-      "`newParts` into `damage.selectedParts`, and moves the case back to `WAITING_FOR_DAMAGE_EXPERT` for re-review.",
+      "**Windows:** (1) **Insurer-review:** `WAITING_FOR_INSURER_APPROVAL` + `workflow.currentStep=INSURER_REVIEW` without a recorded **final** `evaluation.ownerInsurerApproval` signature — including **mixed** priced+factor gate (`NEEDS_REVISION` before factor upload signature) or **final** totals (`claimStatus=APPROVED`). Not allowed while `OWNER_UPLOAD_FACTOR_DOCUMENTS` or `EXPERT_COST_EVALUATION` (finish factor uploads / validation first).\n" +
+      "(2) **Legacy resend:** active expert resend (`WAITING_FOR_USER_RESEND` @ `USER_EXPERT_RESEND`).\n\n" +
+      "`objectionParts` may only reference **priced** repair lines (`factorNeeded=false`). Factor-only lines cannot be disputed until they have expert pricing.\n\n" +
+      "After **`damageExpertReplyFinal`** exists (final reply following a prior objection), **no second objection** — owner uses **owner-insurer-approval/sign** to accept/reject and close the case.\n\n" +
+      "Stores `evaluation.objection`, clears partial/final owner approval fields, merges `newParts` into `damage.selectedParts`, returns case to `WAITING_FOR_DAMAGE_EXPERT`.",
   })
   @ApiParam({
     name: "claimRequestId",
@@ -233,7 +235,7 @@ export class ClaimRequestManagementV2Controller {
   }
 
   /**
-   * V2: Owner signs acceptance of final expert pricing (WAITING_FOR_INSURER_APPROVAL @ INSURER_REVIEW).
+   * V2: Owner signature — priced-line gate (mixed factors) or final accept/reject.
    */
   @Put("request/:claimRequestId/owner-insurer-approval/sign")
   @ApiParam({
@@ -243,12 +245,12 @@ export class ClaimRequestManagementV2Controller {
   })
   @ApiConsumes("multipart/form-data")
   @ApiOperation({
-    summary: "Sign final claim pricing (owner)",
+    summary: "Sign priced lines or final claim pricing (owner)",
     description:
-      "Multipart: `sign` (signature image), `agree` (boolean), and `branchId` (Mongo ObjectId of the insurer branch the file is reviewed under). " +
-      "Allowed only when `status` is WAITING_FOR_INSURER_APPROVAL, " +
-      "`workflow.currentStep` is INSURER_REVIEW (not EXPERT_COST_EVALUATION), and `claimStatus` is APPROVED. " +
-      "If `agree` is true, the case moves to COMPLETED; if false, to REJECTED.",
+      "Multipart: `sign`, `agree`, `branchId`. Always requires `status=WAITING_FOR_INSURER_APPROVAL` and `workflow.currentStep=INSURER_REVIEW` (never during `EXPERT_COST_EVALUATION`).\n\n" +
+      "**Phase A — Mixed reply, priced lines only:** `claimStatus=NEEDS_REVISION`, no `evaluation.ownerPricedPartsApproval` yet. `agree=true` records that signature and moves to `OWNER_UPLOAD_FACTOR_DOCUMENTS` for factor uploads; `agree=false` rejects the whole case (`REJECTED`).\n\n" +
+      "**Phase B — Final:** `claimStatus=APPROVED`, no `evaluation.ownerInsurerApproval` yet. `agree=true` → `COMPLETED`; `agree=false` → `REJECTED`.\n\n" +
+      "Response may include `phase`: `PRICED_PARTS_FOR_FACTORS` or `FINAL_APPROVAL` for UI state.",
   })
   @ApiBody({
     description: "Signature file, agreement, and branch",
@@ -890,12 +892,12 @@ Returns status of each item (uploaded/captured or not).
   @Patch("request/reply/:claimRequestId/:partId/upload-factor")
   @ApiConsumes("multipart/form-data")
   @ApiOperation({
-    summary: "Upload factor file for a priced part (V2)",
+    summary: "Upload repair factor file for a factor-needed part (V2)",
     description:
-      "Use when the damage expert reply marks `factorNeeded: true` for this `partId`. " +
-      "Stores file in `claim-factors-image`, sets `factorLink` / `factorStatus` on the matching part in " +
-      "`evaluation.damageExpertReply` or `evaluation.damageExpertReplyFinal`. " +
-      "Requires claim `claimStatus` NEEDS_REVISION or UNDER_REVIEW.",
+      "Part must have `factorNeeded: true` on the active reply (`evaluation.damageExpertReply` or `evaluation.damageExpertReplyFinal`). One file per part.\n\n" +
+      "**Requires:** `status=WAITING_FOR_INSURER_APPROVAL`, `claimStatus=NEEDS_REVISION`, `workflow.currentStep=OWNER_UPLOAD_FACTOR_DOCUMENTS`.\n\n" +
+      "**Mixed priced+factor replies:** owner must complete **owner-insurer-approval/sign** (priced-line phase) first so `evaluation.ownerPricedPartsApproval` exists.\n\n" +
+      "When every `factorNeeded` line has `factorLink`, the case moves to `claimStatus=UNDER_REVIEW`, `workflow.currentStep=EXPERT_COST_EVALUATION` for damage expert validation.",
   })
   @ApiParam({ name: "claimRequestId", description: "Claim case ID" })
   @ApiParam({ name: "partId", description: "Part id from expert reply" })