SW-7695 Add endpoint to edit observation details (#3647)

`PATCH /api/v1/tracking/observations/{observationId}/plots/{plotId}` updates
information about completed observations of monitoring plots. It will eventually
replace the existing `PUT` endpoint.

Initially, it only supports updating the description and soil assessment
properties of biomass observations, but it's structured to support editing
additional kinds of details in future changes.

The request payload uses `PATCH` semantics, where omitting a property means
leaving the current value in place.

Author: sgrimm

src/main/kotlin/com/terraformation/backend/tracking/api/ObservationUpdateOperationPayload.kt

@@ -0,0 +1,23 @@
+package com.terraformation.backend.tracking.api
+
+import com.fasterxml.jackson.annotation.JsonTypeInfo
+import com.fasterxml.jackson.annotation.JsonTypeName
+import com.terraformation.backend.tracking.model.EditableBiomassDetailsModel
+import com.terraformation.backend.util.patchNullable
+import java.util.Optional
+
+@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "type")
+sealed interface ObservationUpdateOperationPayload
+
+@JsonTypeName("Biomass")
+data class BiomassUpdateOperationPayload(
+    val description: Optional<String?>?,
+    val soilAssessment: String?,
+) : ObservationUpdateOperationPayload {
+  fun applyTo(model: EditableBiomassDetailsModel): EditableBiomassDetailsModel {
+    return model.copy(
+        description = description.patchNullable(model.description),
+        soilAssessment = soilAssessment ?: model.soilAssessment,
+    )
+  }
+}

src/main/kotlin/com/terraformation/backend/tracking/api/ObservationsController.kt

@@ -79,6 +79,7 @@ import org.springframework.http.MediaType
 import org.springframework.http.ResponseEntity
 import org.springframework.web.bind.annotation.DeleteMapping
 import org.springframework.web.bind.annotation.GetMapping
+import org.springframework.web.bind.annotation.PatchMapping
 import org.springframework.web.bind.annotation.PathVariable
 import org.springframework.web.bind.annotation.PostMapping
 import org.springframework.web.bind.annotation.PutMapping
@@ -322,6 +323,30 @@ class ObservationsController(
     return GetOneAssignedPlotResponsePayload(AssignedPlotPayload(details))
   }
 
+  @ApiResponse404(
+      "The plot or observation can't be found, or the plot isn't part of the observation."
+  )
+  @ApiResponse409("The plot's observation has not been completed yet.")
+  @ApiResponseSimpleSuccess
+  @Operation(summary = "Updates information about a completed plot in an observation.")
+  @PatchMapping("/{observationId}/plots/{plotId}")
+  fun updateCompletedObservationPlot(
+      @PathVariable observationId: ObservationId,
+      @PathVariable plotId: MonitoringPlotId,
+      @RequestBody payload: UpdateObservationRequestPayload,
+  ): SimpleSuccessResponsePayload {
+    observationService.updateCompletedPlot(observationId, plotId) {
+      payload.updates.forEach { element ->
+        when (element) {
+          is BiomassUpdateOperationPayload ->
+              observationStore.updateBiomassDetails(observationId, plotId, element::applyTo)
+        }
+      }
+    }
+
+    return SimpleSuccessResponsePayload()
+  }
+
   @Operation(summary = "Updates information about the observation of a plot.")
   @PutMapping("/{observationId}/plots/{plotId}")
   fun updatePlotObservation(
@@ -1035,6 +1060,18 @@ data class UpdatePlotObservationRequestPayload(
     val coordinates: List<ObservationMonitoringPlotCoordinatesPayload>,
 )
 
+data class UpdateObservationRequestPayload(
+    @ArraySchema(
+        arraySchema =
+            Schema(
+                description =
+                    "List of changes to make to different parts of the observation. " +
+                        "Changes are all-or-nothing; if any of them fails, none of them is applied."
+            )
+    )
+    val updates: List<ObservationUpdateOperationPayload>,
+)
+
 data class UpdatePlotPhotoRequestPayload(
     val caption: String?,
 ) {