Further comments on database-model

Fixes #319

RoleDescriptions.txt

@@ -26,6 +26,7 @@ Corrector for a sheet
 - may download their assigned anonymous homework submissions (submissions are identify through crypto-ids, no user-names)
 - may upload corrected and marked homework submissions for their assignments
 - may always download solution and sheet description files for their sheet, ignoring deadline constraints
+- may create homework submissions in the name of students (which identify themselves to the corrector by pseudonym; no association with real identity needed) for homework assignments which have their submission-mode set to "Submission external with pseudonym" by a lecturer
 
 
 Tutor for a tutorial of a course
@@ -35,7 +36,7 @@ Tutor for a tutorial of a course
 User (logged-in)
 - all logged-in users may use this role
 - no special school restrictions
-- may enrol in courses from any school
+- may enroll in courses from any school; enrollment is associated with a field of study the user had at the time
 - may submit homework for marking in enrolled courses
 - all rights that not logged-in users have
 
@@ -44,8 +45,9 @@ User (not logged-in)
 - can view course descriptions
 - can download course materials from courses that allow this for all un-enrolled users
 - can requests help from administrators
+- can log in with their campus-id creating a new user record in the process and elevating rights to "logged-in"
 
 
 
 Terminology:
- - participants: a logged-in users that is enrolled in a specific course
+ - participants: a logged-in users that is enrolled in a specific course

models/config

@@ -1,4 +1,6 @@
+-- Configuration settings shared among all uni2work-instances for interoperability (Users can seamlessly switch between uni2work-instances (load-balancing need not attach users to an instance persistently))
+-- Mostly cryptographic keys
 ClusterConfig
-    setting             ClusterSettingsKey
+    setting             ClusterSettingsKey -- I.e. Symmetric key for encrypting database-ids for use in URLs, Symmetric key for encrypting user-sessions so they can be saved directly as a browser-cookie, Symmetric key for encrypting error messages which might contain secret information, ...
-    value               Value
+    value               Value              -- JSON-encoded value
     Primary setting

models/jobs

@@ -1,13 +1,17 @@
--- Routine tasks to be executed later
+-- Jobs to be executed as soon as possible in the background (so not to delay HTTP-responses, or triggered by cron-system without associated HTTP-Request)
 QueuedJob
-    content             Value
+    content             Value              -- JSON-encoded description of the work to be done (send an email to "test@example.org", find all recipients for a certain notifications and queue one new job each, distribute all submissions for a sheet to correctors, ...)
-    creationInstance    InstanceId         -- multiple uni2work instances access the same database, but each job must be only executed once
+    creationInstance    InstanceId         -- multiple uni2work-instances access the same database, record which instance created this job for debugging purposes
     creationTime        UTCTime
     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
+
+-- Jobs are deleted from @QueuedJob@ after they are executed successfully and recorded in @CronLastExec@
+-- There is a Cron-system that, at set intervals, queries the database for work to be done in the background (i.e. if a lecturer has set a sheet's submissions to be automatically distributed and the submission deadline passed since the last check, then queue a new job to actually do the distribution)
+-- For the cron-system to determine whether a job needs to be done it needs to know if and when it was last (or ever) executed (i.e. a sheet's submissions should not be distributed twice)
 CronLastExec
-    job                 Value
+    job                 Value -- JSON-encoded description of work done
-    time                UTCTime
+    time                UTCTime -- When was the job executed
-    instance            InstanceId
+    instance            InstanceId -- Which uni2work-instance did the work
     UniqueCronLastExec job

models/sheets

@@ -19,9 +19,13 @@ SheetEdit                     -- who edited when a row in table "Course", kept i
     user            UserId
     time            UTCTime
     sheet           SheetId
-SheetPseudonym                -- for anonoymous external submissions (ie paper submission tracked in uni2work)
+
+-- For anonoymous external submissions (i.e. paper submission tracked in uni2work)
+-- Map pseudonyms to users injectively in the context of a single sheet; for the next sheet all-new pseudonyms need to be created
+-- Chosen uniformly at random when the submitting user presses a button on the view of a sheet
+SheetPseudonym
     sheet           SheetId
-    pseudonym       Pseudonym -- should be attached to submission
+    pseudonym       Pseudonym -- 24-bit number that should be attached to external submission (i.e. written on the submitted paper); encoded as two english words akin to PGP-Wordlist
     user            UserId
     UniqueSheetPseudonym sheet pseudonym
     UniqueSheetPseudonymUser sheet user

models/system-messages

@@ -1,12 +1,14 @@
+-- Messages shown to all users as soon as they visit the site/log in (i.e.: "System is going down for maintenance next sunday")
+-- Only administrators (of any school) should be able to create these via a web-interface
 SystemMessage
-    from                UTCTime Maybe
+    from                UTCTime Maybe -- Message is not shown before this date has passed (never shown, if null)
-    to                  UTCTime Maybe
+    to                  UTCTime Maybe -- Message is shown until this date has passed (shown forever, if null)
-    authenticatedOnly   Bool
+    authenticatedOnly   Bool -- Show message to all users upon visiting the site or only upon login?
-    severity            MessageStatus
+    severity            MessageStatus -- Success, Warning, Error, Info, ...
-    defaultLanguage     Lang
+    defaultLanguage     Lang -- Language of @content@ and @summary@
-    content             Html
+    content             Html -- Detailed message shown when clicking on the @summary@-popup or when no @summary@ is specified
     summary             Html Maybe
-SystemMessageTranslation
+SystemMessageTranslation -- Translation of a @SystemMessage@ into another language; which language to choose is determined by user-sent HTTP-headers
     message             SystemMessageId
     language            Lang
     content             Html