more model descriptions added

RoleDescriptions.txt

@@ -28,6 +28,10 @@ Corrector for a sheet
 - may always download solution and sheet description files for their sheet, ignoring deadline constraints
 
 
+Tutor for a tutorial of a course
+- yet unimplemented, likely similar to corrector; ie. can access sheets and solutions earlier than participants
+
+
 User (logged-in)
 - all logged-in users may use this role
 - no special school restrictions

models/exams

@@ -1,4 +1,4 @@
--- EXAMS ARE TODO:
+-- EXAMS ARE TODO; THIS IS JUST AN UNUSED STUB
 Exam
     course              CourseId
     name                Text
@@ -8,8 +8,8 @@ Exam
     registrationBegin   UTCTime
     registrationEnd     UTCTime
     deregistrationEnd   UTCTime
-    ratingVisible       Bool
-    statisticsVisible   Bool
+    ratingVisible       Bool     -- may participants see their own rating yet
+    statisticsVisible   Bool     -- may participants view statistics over all participants (should not be allowed for 'small' courses)
 --ExamEdit
 --    user                UserId
 --    time                UTCTime

models/files

@@ -1,3 +1,6 @@
+-- Table storing all kinds of larges files as 8bit-byte vectors (regardless of encoding)
+-- PostgreSQL is intelligent enough to handle this in a sensible manner;
+-- helps to ensure consistency of database snapshots, no data is stored outside database
 File
     title           FilePath
     content         ByteString Maybe -- Nothing iff this is a directory

models/jobs

@@ -1,9 +1,10 @@
+-- Routine tasks to be executed later
 QueuedJob
     content             Value
-    creationInstance    InstanceId
+    creationInstance    InstanceId         -- multiple uni2work instances access the same database, but each job must be only executed once
     creationTime        UTCTime
-    lockInstance        InstanceId Maybe
-    lockTime            UTCTime Maybe
+    lockInstance        InstanceId Maybe   -- instance that has started to execute this job
+    lockTime            UTCTime Maybe      -- time when execution had begun
     deriving Eq Read Show Generic Typeable
 CronLastExec
     job                 Value

models/rooms

@@ -1,3 +1,8 @@
+-- ROOMS ARE TODO; THIS IS JUST AN UNUSED STUB
+-- Idea is to create a selection of rooms that may be
+-- associated with exercise classes and exams
+-- offering links to the LMU Roomfinder
+-- and allow the creation of neat timetables for users
 Booking
     term        TermId
     begin       UTCTime
@@ -13,7 +18,8 @@ BookingEdit
 Room
     name        Text
     capacity    Int Maybe
-    building    Text Maybe
+    building    Text Maybe -- name of building
+    roomfinder  Text Maybe -- external url for LMU Roomfinder
 -- BookingRoom
 --    subject     RoomForId
 --    room        RoomId

models/schools

@@ -1,3 +1,5 @@
+-- Description of all primary schools managed by uni2work
+-- Each school must have a unique human-readable shorthand which is used as database row key
 School json
     name          (CI Text)
     shorthand     (CI Text)  -- SchoolKey :: SchoolShorthand -> SchoolId

models/sheets

@@ -1,4 +1,4 @@
-Sheet
+Sheet   -- exercise sheet for a given course
     course          CourseId
     name            (CI Text)
     description     Html Maybe

models/terms

@@ -1,10 +1,13 @@
+-- Describes each term time.
+-- TermIdentifier is either W for Winterterm or S for Summerterm,
+-- followed by a two-digit year
 Term json
     name          TermIdentifier -- unTermKey :: TermId -> TermIdentifier
     start         Day            -- TermKey   :: TermIdentifier -> TermId
-    end           Day
-    holidays      [Day]
-    lectureStart  Day
-    lectureEnd    Day
-    active        Bool
+    end           Dayl
+    holidays      [Day]          -- LMU holidays, for display in timetables
+    lectureStart  Day            -- lectures usually start/end  later/earlier than the actual term,
+    lectureEnd    Day            -- used to generate warnings for lecturers creating unusual courses
+    active        Bool           -- may lecturers add courses to this term?
     Primary name       -- newtype Key Term = TermKey { unTermKey :: TermIdentifier }
     deriving Show Eq Generic -- type TermId = Key Term

models/tutorials

@@ -1,7 +1,10 @@
+-- TUTORIALS ARE TODO; THIS IS JUST AN UNUSED STUB
+-- Idea: management of exercise classes, offering sub-enrolement to distribute all students among all exercise classs
 Tutorial json
     name        Text
     tutor       UserId
     course      CourseId
+    capacity    Int64 Maybe -- limit for enrolement in this tutorial
 TutorialUser
     user        UserId
     tutorial    TutorialId