[PRMP-588] document review patch endpoint

.github/workflows/base-lambdas-reusable-deploy-all.yml

@@ -488,6 +488,20 @@ jobs:
     secrets:
       AWS_ASSUME_ROLE: ${{ secrets.AWS_ASSUME_ROLE }}
 
+  deploy_patch_document_review_lambda:
+    name: Deploy patch document review lambda
+    uses: ./.github/workflows/base-lambdas-reusable-deploy.yml
+    with:
+      environment: ${{ inputs.environment}}
+      python_version: ${{ inputs.python_version }}
+      build_branch: ${{ inputs.build_branch}}
+      sandbox: ${{ inputs.sandbox }}
+      lambda_handler_name: patch_document_review_handler
+      lambda_aws_name: PatchDocumentReview
+      lambda_layer_names: "core_lambda_layer"
+    secrets:
+      AWS_ASSUME_ROLE: ${{ secrets.AWS_ASSUME_ROLE }}
+
   deploy_get_document_review_lambda:
     name: Deploy get document review lambda
     uses: ./.github/workflows/base-lambdas-reusable-deploy.yml

lambdas/enums/document_review_accepted_querystring_parameters.py

@@ -6,4 +6,3 @@ class DocumentReviewQuerystringParameters(StrEnum):
     NEXT_PAGE_TOKEN = "nextPageToken"
     UPLOADER = "uploader"
     NHS_NUMBER = "nhsNumber"
-

lambdas/enums/document_review_status.py

@@ -4,4 +4,9 @@
 class DocumentReviewStatus(StrEnum):
     PENDING_REVIEW = "PENDING_REVIEW"
     APPROVED = "APPROVED"
+    APPROVED_PENDING_DOCUMENTS = "APPROVED_PENDING_DOCUMENTS"
     REJECTED = "REJECTED"
+    REJECTED_DUPLICATE = "REJECTED_DUPLICATE"
+    REASSIGNED = "REASSIGNED"
+    REASSIGNED_PATIENT_UNKNOWN = "REASSIGNED_PATIENT_UNKNOWN"
+    NEVER_REVIEWED = "NEVER_REVIEWED"

lambdas/enums/lambda_error.py

@@ -486,6 +486,33 @@ def create_error_body(self, params: Optional[dict] = None, **kwargs) -> str:
         "message": "User is unauthorised to view record",
         "fhir_coding": UKCoreSpineError.ACCESS_DENIED,
     }
+    """
+    Errors for document review lambda
+    """
+    DocumentReviewNotFound = {
+        "err_code": "DRV_4041",
+        "message": "Document review not found",
+        "fhir_coding": UKCoreSpineError.RESOURCE_NOT_FOUND,
+    }
+    DocumentReviewGeneralError = {
+        "err_code": "DRV_4002",
+        "message": "An error occurred while fetching the document review",
+        "fhir_coding": FhirIssueCoding.EXCEPTION,
+    }
+    UpdateDocStatusUnavailable = {
+        "err_code": "DRV_4003",
+        "message": "This Document is not available for review update",
+        "fhir_coding": FhirIssueCoding.FORBIDDEN,
+    }
+    DocumentReviewInvalidBody = {
+        "err_code": "DRV_4004",
+        "message": "Invalid request body",
+    }
+    DocumentReviewInvalidNhsNumber = {
+        "err_code": "DRV_4005",
+        "message": "The NHS number provided is invalid",
+    }
+
     """
        Errors for get ods report lambda 
     """

lambdas/enums/logging_app_interaction.py

@@ -20,3 +20,4 @@ class LoggingAppInteraction(Enum):
     UPLOAD_CONFIRMATION = "Upload confirmation"
     UPDATE_UPLOAD_STATE = "Update upload state"
     GET_REVIEW_DOCUMENTS = "Get review documents"
+    UPDATE_REVIEW = "Update review"

lambdas/handlers/get_document_review_handler.py

@@ -12,6 +12,7 @@
 from utils.decorators.set_audit_arg import set_request_context_for_logging
 from utils.decorators.validate_patient_id import validate_patient_id
 from utils.lambda_exceptions import GetDocumentReviewException
+from utils.lambda_handler_utils import validate_review_path_parameters
 from utils.lambda_response import ApiGatewayResponse
 from utils.request_context import request_context
 
@@ -35,15 +36,10 @@ def lambda_handler(event, context):
 
     logger.info("Get Document Review handler has been triggered")
     feature_flag_service = FeatureFlagService()
-    upload_lambda_enabled_flag_object = feature_flag_service.get_feature_flags_by_flag(
+    feature_flag_service.validate_feature_flag(
         FeatureFlags.UPLOAD_DOCUMENT_ITERATION_3_ENABLED
     )
 
-    if not upload_lambda_enabled_flag_object[FeatureFlags.UPLOAD_DOCUMENT_ITERATION_3_ENABLED]:
-        logger.info("Feature flag not enabled, event will not be processed")
-        raise GetDocumentReviewException(404, LambdaError.FeatureFlagDisabled)
-
-    # Extract patient_id from query string parameters
     query_params = event.get("queryStringParameters", {})
     patient_id = query_params.get("patientId", "")
 
@@ -53,26 +49,19 @@ def lambda_handler(event, context):
             400, LambdaError.DocumentReferenceMissingParameters
         )
 
-    # Extract id from path parameters
-    path_params = event.get("pathParameters", {})
-    document_id = path_params.get("id")
-
-    if not document_id:
-        logger.error("Missing id in path parameters")
-        raise GetDocumentReviewException(
-            400, LambdaError.DocumentReferenceMissingParameters
-        )
+    document_id, document_version = validate_review_path_parameters(event)
 
     request_context.patient_nhs_no = patient_id
 
     logger.info(
         f"Retrieving document review for patient_id: {patient_id}, document_id: {document_id}"
     )
 
-    # Get document review service
     document_review_service = GetDocumentReviewService()
     document_review = document_review_service.get_document_review(
-        patient_id=patient_id, document_id=document_id
+        patient_id=patient_id,
+        document_id=document_id,
+        document_version=document_version,
     )
 
     if document_review:

lambdas/handlers/patch_document_review_handler.py

@@ -0,0 +1,79 @@
+from enums.feature_flags import FeatureFlags
+from enums.lambda_error import LambdaError
+from enums.logging_app_interaction import LoggingAppInteraction
+from models.document_review import PatchDocumentReviewRequest
+from pydantic import ValidationError
+from services.feature_flags_service import FeatureFlagService
+from services.update_document_review_service import UpdateDocumentReviewService
+from utils.audit_logging_setup import LoggingService
+from utils.decorators.ensure_env_var import ensure_environment_variables
+from utils.decorators.handle_lambda_exceptions import handle_lambda_exceptions
+from utils.decorators.override_error_check import override_error_check
+from utils.decorators.set_audit_arg import set_request_context_for_logging
+from utils.decorators.validate_patient_id import validate_patient_id
+from utils.lambda_exceptions import UpdateDocumentReviewException
+from utils.lambda_handler_utils import validate_review_path_parameters
+from utils.lambda_response import ApiGatewayResponse
+from utils.request_context import request_context
+
+logger = LoggingService(__name__)
+
+
+@set_request_context_for_logging
+@validate_patient_id
+@ensure_environment_variables(
+    names=[
+        "DOCUMENT_REVIEW_DYNAMODB_NAME",
+    ]
+)
+@override_error_check
+@handle_lambda_exceptions
+def lambda_handler(event, context):
+    request_context.app_interaction = LoggingAppInteraction.UPDATE_REVIEW.value
+
+    logger.info("Patch Document Review handler has been triggered")
+    feature_flag_service = FeatureFlagService()
+    feature_flag_service.validate_feature_flag(
+        FeatureFlags.UPLOAD_DOCUMENT_ITERATION_3_ENABLED
+    )
+
+    query_params = event.get("queryStringParameters", {})
+    patient_id = query_params.get("patientId")
+
+    if not patient_id:
+        logger.error("Missing patient_id in query string parameters")
+        raise UpdateDocumentReviewException(400, LambdaError.PatientIdNoKey)
+
+    document_id, document_version = validate_review_path_parameters(event)
+
+    reviewer_ods_code = request_context.authorization.get(
+        "selected_organisation", {}
+    ).get("org_ods_code")
+
+    if not reviewer_ods_code:
+        logger.error("Missing ODS code in authorization token")
+        raise UpdateDocumentReviewException(
+            401, LambdaError.DocumentReferenceUnauthorised
+        )
+
+    body = event.get("body")
+    try:
+        review_request = PatchDocumentReviewRequest.model_validate_json(body)
+    except ValidationError as e:
+        logger.error(f"Invalid request body: {str(e)}")
+        raise UpdateDocumentReviewException(400, LambdaError.DocumentReviewInvalidBody)
+
+    document_review_service = UpdateDocumentReviewService()
+    document_review_service.update_document_review(
+        patient_id=patient_id,
+        document_id=document_id,
+        document_version=document_version,
+        update_data=review_request,
+        reviewer_ods_code=reviewer_ods_code,
+    )
+
+    logger.info(
+        "Document review updated successfully",
+        {"Result": "Successful document review update"},
+    )
+    return ApiGatewayResponse(200, "", "PATCH").create_api_gateway_response()

lambdas/models/document_review.py

@@ -3,8 +3,10 @@
 from enums.document_review_status import DocumentReviewStatus
 from enums.metadata_field_names import DocumentReferenceMetadataFields
 from enums.snomed_codes import SnomedCodes
-from pydantic import BaseModel, ConfigDict, Field
-from pydantic.alias_generators import to_pascal, to_camel
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic.alias_generators import to_camel, to_pascal
+from utils.exceptions import InvalidNhsNumberException
+from utils.utilities import validate_nhs_number
 
 
 class DocumentReviewFileDetails(BaseModel):
@@ -41,10 +43,8 @@ class DocumentUploadReviewReference(BaseModel):
     upload_date: int
     files: list[DocumentReviewFileDetails] = Field(min_length=1)
     nhs_number: str
-    ttl: int | None = Field(
-        alias=str(DocumentReferenceMetadataFields.TTL.value), default=None
-    )
-    document_reference_id: str | None = Field(default=None)
+    version: int = Field(default=1)
+    document_reference_id: str = Field(default=None)
     document_snomed_code_type: str = Field(default=SnomedCodes.LLOYD_GEORGE.value.code)
 
     def model_dump_camel_case(self, *args, **kwargs):
@@ -66,4 +66,63 @@ def camelize(self, model: dict) -> dict:
                 value = result
             camel_case_dict[to_camel(key)] = value
 
-        return camel_case_dict
+        return camel_case_dict
+
+class PatchDocumentReviewRequest(BaseModel):
+    model_config = ConfigDict(
+        validate_by_alias=True,
+        populate_by_name=True,
+        alias_generator=to_camel,
+        use_enum_values=True,
+    )
+
+    review_status: DocumentReviewStatus = Field(..., description="Review outcome")
+    document_reference_id: str | None = Field(
+        default=None,
+        description="Document reference ID (required when status is APPROVED)",
+    )
+    nhs_number: str | None = Field(
+        default=None,
+        description="New NHS number (required when status is REASSIGNED)",
+    )
+
+    @model_validator(mode="after")
+    def validate_document_reference_id(self):
+        """Ensure document_reference_id is provided when review_status is APPROVED."""
+        if (
+            self.review_status == DocumentReviewStatus.APPROVED
+            and not self.document_reference_id
+        ):
+            raise ValueError(
+                "document_reference_id is required when review_status is APPROVED"
+            )
+        elif (
+            self.review_status != DocumentReviewStatus.APPROVED
+            and self.document_reference_id
+        ):
+            raise ValueError(
+                "document_reference_id is not required when review_status is not APPROVED"
+            )
+        return self
+
+    @model_validator(mode="after")
+    def validate_reassign_nhs_number(self):
+        """
+        Validate the reassignment of the NHS number after the input data model has been populated.
+
+        Checks whether the `reassigned_nhs_number` field has been provided and is valid when the
+        `review_status` reflects a reassigned state. Raises an error if validation fails.
+        """
+        if (
+            self.review_status == DocumentReviewStatus.REASSIGNED
+            and not self.nhs_number
+        ):
+            raise ValueError(
+                "reassigned_nhs_number is required when review_status is REASSIGNED or REASSIGNED_PATIENT_UNKNOWN"
+            )
+        elif self.review_status == DocumentReviewStatus.REASSIGNED and self.nhs_number:
+            try:
+                validate_nhs_number(self.nhs_number)
+            except InvalidNhsNumberException:
+                raise ValueError("Invalid NHS number")
+        return self

lambdas/services/authoriser_service.py

@@ -97,7 +97,9 @@ def deny_access_policy(self, path, user_role, nhs_number: str = None):
 
             case doc_ref if re.match(doc_ref_pattern, doc_ref):
                 deny_resource = True
-                if (is_user_gp_admin or is_user_gp_clinical) and patient_access_is_allowed:
+                if (
+                    is_user_gp_admin or is_user_gp_clinical
+                ) and patient_access_is_allowed:
                     deny_resource = False
                 if patient_access_is_allowed and access_to_deceased_patient:
                     deny_resource = True
@@ -125,9 +127,7 @@ def deny_access_policy(self, path, user_role, nhs_number: str = None):
                     not patient_access_is_allowed or is_user_gp_clinical or is_user_pcse
                 )
             case path if path.startswith("/DocumentReview/"):
-                deny_resource = (
-                    not patient_access_is_allowed
-                )
+                deny_resource = not patient_access_is_allowed
 
             case "/UploadState":
                 deny_resource = (