Add training certificate endpoint with completion validation

[marceloarocha]

Summary

Adds a new GET /training/<id>/certificate endpoint that allows users to retrieve certificate data for completed training modules. The endpoint validates that all active lessons are finished before issuing a certificate and includes fallback logic for legacy completion records.

Key Changes

• New Repository Functions:

  • get_training(): Retrieves active training records by ID
  • get_lesson_completion_stats(): Returns total lessons, completed lessons, and last completion timestamp for a user
  • get_training_user(): Retrieves the training completion record for a user
  • Refactored is_training_finished() to use the new get_lesson_completion_stats() function

• New Service Function:

  • get_training_certificate(): Validates training completion and returns certificate data including user name, training title, total lessons, and completion date
  • Includes permission check for READ_BASIC_FEATURES
  • Validates that training exists and is active
  • Validates that all active lessons are completed
  • Falls back to last lesson completion date for legacy records without treinamento_usuario entries

• New API Endpoint:

  • GET /training/<id>/certificate: Returns certificate data for completed trainings
  • Requires READ_BASIC_FEATURES permission
  • Returns 400 if training doesn't exist, is inactive, or has pending lessons
  • Returns 401 if user lacks required permissions

• Comprehensive Test Coverage:

  • Tests successful certificate retrieval after module completion
  • Tests rejection while lessons are pending
  • Tests handling of unknown/inactive modules
  • Tests fallback to last lesson completion date for legacy records
  • Tests permission enforcement

Implementation Details

The certificate endpoint enforces strict validation: it refuses to issue certificates while any active lesson remains unfinished. This ensures certificates are only issued for truly completed modules. The implementation also handles backward compatibility by falling back to the last lesson completion timestamp for records created before the treinamento_usuario table was introduced.

https://claude.ai/code/session_011woQiKv9LnkUj5E6JeahY8

[amazon-q-developer]

Review Summary

This PR adds a certificate endpoint with comprehensive test coverage and clean refactoring. However, one critical issue must be fixed before merge:

Critical Issue:

• Missing null check on user query (line 174) can cause AttributeError crashes

Approved Changes:

• Repository refactoring extracts get_lesson_completion_stats for reuse
• New get_training and get_training_user functions provide clear abstractions
• Certificate validation properly enforces completion requirements
• Comprehensive test coverage (5 test cases) covering success, validation, permissions, and legacy compatibility
• Clean separation of concerns between route, service, and repository layers

Once the null check is added, this PR is ready to merge.

---

You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.

[amazon-q-developer]

🛑 Crash Risk: Query returns None when user doesn't exist, causing AttributeError on line 184 when accessing user.name.

Suggested change

	user = db.session.query(User).filter(User.id == user_context.id).first()
	user = db.session.query(User).filter(User.id == user_context.id).first()
	if user is None:
	raise ValidationError(
	"Usuário não encontrado",
	"errors.invalidUser",
	status.HTTP_400_BAD_REQUEST,
	)