==================
MEG Academy Models
==================

Course Folder and Online Course Organization
--------------------------------------------

The :class:`~academy.models.CourseFolder` and :class:`~academy.models.OnlineCourse` models are structured to provide organized access to courses based on the institution and possibly other grouping metrics such as institution or subject.

1. **Course Folder Visibility**:

   - Every :class:`~academy.models.CourseFolder` is linked to an :class:`~academy.models.Institution` through a ForeignKey relationship.
   - Users can only see :class:`~academy.models.CourseFolder` objects that are associated with their institution unless explicitly granted broader access.
   - Each folder has a ``level`` field to control whether it is globally accessible or institution-specific.

2. **Online Course Accessibility**:

   - Each :class:`~academy.models.OnlineCourse` is associated with a :class:`~academy.models.CourseFolder`.
   - Users must be part of the institution to access the courses unless the course is placed in a global folder, which is available to all users.

Course Stages and Acknowledgment
--------------------------------

Each :class:`~academy.models.OnlineCourse` can contain multiple :class:`~academy.models.CourseStage`, each representing a segment or module of the course.

1. **Course Stage Accessibility**:

   - Users can access course stages if they have access to the :class:`~academy.models.OnlineCourse`.
   - Course stages may contain files that are only accessible based on user permissions or course completion status.

2. **Course Stage Acknowledgment**:

   - The :class:`~academy.models.CourseStageAcknowledgment` model tracks when a user acknowledges completing a course stage.
   - Acknowledgment can be used to track progress but is no longer explicitly required for every stage.

Security and Progress Tracking
------------------------------

The system incorporates several methods to ensure security and provide progress tracking for users in courses.

1. **Progress Calculation**:

   - The progress within a course is calculated based on the number of stages completed by the user.
   - Only stages that have been acknowledged by the user are counted towards course completion, but acknowledgment requirements are now decoupled from the stages themselves.

2. **Assessment Visibility**:

   - Assessments in courses can only be viewed by users who have completed all the required stages of the course, ensuring readiness for assessment.

3. **Document Security**:

   - Files associated with course stages are stored securely and are only accessible through the course stage interface.

These rules ensure that the system manages courses, stages, and user progression securely and efficiently, maintaining strict access controls based on institutional boundaries.