🔍 Code Extractor

Completes a document review cycle by recording a decision and optional comments, then returns the operation status.

Purpose

This function serves as a controller action to finalize a review cycle in a document management system. It delegates to an underlying ReviewControllerBase instance to complete the cycle with the provided decision and comments, then returns a structured response indicating success or failure. The function is decorated with log_controller_action to track the operation for audit purposes.

Source Code

def complete_review(user: DocUser, review_uid: str, decision: str, comments: Optional[str] = None) -> Dict[str, Any]:
    """Complete a review cycle."""
    success = _controller.complete_cycle(
        cycle_uid=review_uid,
        decision=decision,
        comment=comments
    )
    return {"success": success, "message": "Review completed successfully" if success else "Failed to complete review"}

Parameters

Parameter Details

user: A DocUser object representing the authenticated user performing the review completion. This parameter is likely used by the decorator or for permission checking, though not directly used in the function body.

review_uid: A string containing the unique identifier (UID) of the review cycle to be completed. This is passed as 'cycle_uid' to the underlying controller.

decision: A string representing the review decision (e.g., 'approved', 'rejected', 'needs_revision'). The exact valid values depend on the ReviewControllerBase implementation and business rules.

comments: An optional string containing reviewer comments or feedback about the decision. Defaults to None if no comments are provided.

Return Value

Type: Dict[str, Any]

Returns a dictionary with two keys: 'success' (boolean indicating whether the review completion succeeded) and 'message' (string containing either 'Review completed successfully' if success is True, or 'Failed to complete review' if success is False). The return type is Dict[str, Any] to allow for potential future expansion of the response structure.

Dependencies

• CDocs

Required Imports

from typing import Dict, Any, Optional
from CDocs.models.user_extensions import DocUser
from CDocs.controllers import log_controller_action

Usage Example

from CDocs.models.user_extensions import DocUser
from typing import Dict, Any, Optional

# Assume _controller is already initialized as ReviewControllerBase instance
# and user is authenticated

user = DocUser.query.get(user_id)  # Get authenticated user
review_uid = "review-12345-abcde"  # UID of the review cycle
decision = "approved"  # Review decision
comments = "All requirements met, documentation is clear and complete."

# Complete the review
result = complete_review(
    user=user,
    review_uid=review_uid,
    decision=decision,
    comments=comments
)

if result["success"]:
    print(f"Success: {result['message']}")
else:
    print(f"Error: {result['message']}")

# Example without comments
result = complete_review(
    user=user,
    review_uid=review_uid,
    decision="rejected"
)

print(result)  # {'success': True/False, 'message': '...'}}

Best Practices

• Ensure the user has appropriate permissions to complete reviews before calling this function
• Validate that the review_uid exists and is in a state that allows completion
• Provide meaningful comments when rejecting or requesting revisions to help document authors
• Handle the returned dictionary appropriately, checking the 'success' key before proceeding
• The function relies on the log_controller_action decorator for audit logging, so ensure this decorator is properly configured
• The _controller instance must be properly initialized before this function is called
• Consider wrapping calls to this function in try-except blocks to handle potential exceptions like PermissionError, ResourceNotFoundError, ValidationError, or BusinessRuleError
• Ensure the decision parameter matches valid values expected by the underlying ReviewControllerBase.complete_cycle method
• This function is synchronous; if used in an async context, consider wrapping it appropriately

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function complete_approval_v2 84.4% similar

  Completes an approval cycle by recording a decision (approve/reject) and optional comments, then returns the operation status.

  From: /tf/active/vicechatdev/CDocs single class/controllers/approval_controller.py

• function complete_review 78.4% similar

  Completes a document review cycle by submitting a reviewer's decision (APPROVED/REJECTED), updating review status, managing sequential review workflows, and triggering notifications.

  From: /tf/active/vicechatdev/CDocs/controllers/review_controller.py

• function cancel_review_cycle_v1 76.6% similar

  Cancels an active review cycle for a controlled document by calling the underlying controller's cancel_cycle method and returns a success status with a message.

  From: /tf/active/vicechatdev/CDocs single class/controllers/review_controller.py

• function add_review_comment_v1 75.7% similar

  Adds a comment to a document review cycle, with options to mark it as requiring resolution and specify comment type.

  From: /tf/active/vicechatdev/CDocs single class/controllers/review_controller.py

• function close_review_cycle_v1 73.2% similar

  Closes an active review cycle by canceling it and optionally updating the associated document and document version status to a target status (default: DRAFT).

  From: /tf/active/vicechatdev/CDocs single class/controllers/review_controller.py