rework PR-comments

docu/Concepts/BusinessRequirements/UC_Contribution_Messaging.md

@@ -16,6 +16,7 @@ In diesem Dokument werden alle zu dem Thema besprochenen und angedachten Anforde
   * in Arbeit (inprogress): Die Contribution wurde von einem Moderator in Bearbeitung genommen, in dem er eine Rückfrage als Nachricht an den User erfasst hat und wartet auf Beantwortung vom User, dem die Contribution zugeordnet ist
   * bestätigt (confirmed): Die Contribution wurde von einem Moderator genehmigt und der Betrag ist dem User der Contribution schon gutgeschrieben. Dies ist eine Ende-Zustand auf den keine weitere Bearbeitung mehr folgt. **[AS-x]** Es kann selbst nach einer Bestätigung der Contribution noch eine neue Nachricht dazu erfasst werden.
   * abgelehnt (denied): die Contribution wurde vom Moderator abgelehnt und es hat keine Gutschrift des Betrages auf dem Konto des Users stattgefunden. Dies ist ein Ende-Zustand auf den keine weitere Bearbeitung mehr folgt. **[AS-x]** Es kann selbst nach einer Ablehnung der Contribution noch eine neue Nachricht dazu erfasst werden.
+  * gelöscht (deleted): die Contribution wurde von einem Moderator oder dem User gelöscht. Dies kann zu jeder Zeit aus dem Status pending oder inprogress nicht aber aus dem Status confirmed oder denied heraus initiiert werden und ist unabhängig, ob an der Contribution schon Messages anhängig sind. Das Löschen wird als Soft-Delete implementiert in dem die Attribute *deletedAt* und *deletedBy* gesetzt werden. Im Status deleted kommt die Contribution nicht mehr zur Anzeige, bleibt aber in der Datanbank erhalten.
 * **[AS-1]** Sobald ein Moderator eine Contribution zur Bearbeitung anzeigt, wird sofort die ModeratorId und/oder der neue Status in die Contribution gespeichert, um diese für andere Moderatoren zu sperren. Dies ist notwendig, um fälschlicherweise ein paralleles Bearbeiten einer Contribution durch mehrere Moderatoren zu verhindern.
 * **[AS-1]** Bei der Bestätigung einer Contribution wird neben der Status-Änderung auf *confirmed* eine neue Nachricht erzeugt. Diese Nachricht enthält einen Bestätigungstext, der im Frontend als Standard-Bestätigungstext vorbelegt ist und vom Moderator für eine individuelle Bestätigung überschrieben werden kann. Das Speichern der Contribution-Bestätigung erfolgt nach dem die zugehörige Schöpfung als Transaktion erfolgreich gespeichert ist. Falls es beim Speichern der Gutschrift und/oder der Contribution inkl. Message zu einem Fehler kommt, darf weder die Contribution noch die Transaktion gespeichert werden, sondern es muss eine Fehlermeldung ohne Änderungen der Datanbankdaten erfolgen.
 * **[AS-1]** Bei der Ablehnung einer Contribution wird neben der Status-Änderung auf *denied* eine neue Nachricht erzeugt. Diese Nachricht enthält einen Ablehnungtext, der im Frontend als Standard-Ablehnungstext vorbelegt ist und vom Moderator für eine individuelle Begründung überschrieben werden kann.
@@ -27,10 +28,11 @@ In diesem Dokument werden alle zu dem Thema besprochenen und angedachten Anforde
   * mindestens eine Nachricht existiert (blaue Sprechblase)
   * **[AS-x]** Gesamtsanzahl der existierenden Nachrichten (z.B. Zahl im bzw. neben Sprechbalsen-Icon)
   * **[AS-x]** Anzahl der ungelesenen Nachrichten (z.B. Zahl/Zahl im bzw. neben Sprechblasen-Icon)
-* **[AS-1]** Das Bearbeiten einer Contribution ist im Status *eingereicht* möglich. Solange noch keine Nachrichten anhängig sind, wird nach dem Bearbeiten keine weitere Aktion notwendig, es erfolgt noch keine Historisierung. Sobald aber schon mindestens eine Nachricht anhängig ist, muss eine Historisierung der Contribution-Bearbeitung erfolgen. Das bedeutet, dass beim Starten der Bearbeitung der original Contributiontext und -Betrag als Nachricht mit besonderer Kennzeichnung als Historisierungsnachricht (*Messages.createdAt = Contribution.createdAt*) erzeugt und angehängt wird. Der geänderte bzw. neue Inhalt der Contribution wird in der Contribution selbst gespeichert und das updatedAt und updatedBy der Contribution wird aktualisiert. Die Reihenfolge der Historisierung ergibt sich aus dem Zeitstempel an dem die Historisierungs-Nachricht erzeugt wurde.
-* [AS-1] Folgende Status-Übergänge sind für eine Contribution möglich:
+* **[AS-1]** Das Bearbeiten einer Contribution ist im Status *eingereicht* möglich. Solange noch keine Nachrichten anhängig sind, wird nach dem Bearbeiten keine weitere Aktion notwendig, es erfolgt noch keine Historisierung. Sobald aber schon mindestens eine Nachricht anhängig ist, muss eine Historisierung der Contribution-Bearbeitung erfolgen. Das Ziel der Historisierung ist die jeweilige Version einer Contribution vor der Bearbeitung als Message in die Nachrichtenliste einzutragen und dabei diese HISTORY-Message so zeitlich einzusortieren, dass diese mit den DIALOG-Messages inhaltlich korrespondiert. Das bedeutet, dass beim Starten der Bearbeitung der original Contributiontext und -Betrag als Nachricht mit besonderer Kennzeichnung (*type* = HISTORY) und mit Zeitstempel für Contribution-Version 1: *Message.createdAt* = Contribution.createdAt bzw. für Contribution-Version >1: *Message.createdAt* = Contribution.updatedAt erzeugt und angehängt wird. Der geänderte bzw. neue Inhalt der Contribution wird in der Contribution selbst gespeichert und das *updatedAt* und *updatedBy* der Contribution wird aktualisiert. 
+* **[AS-1]** Folgende Status-Übergänge sind für eine Contribution möglich:
 
   ![img](./image/ContributionStates.png)
+* **[AS-x]** Für das Bearbeiten der Contributions im AdminInterface bedarf es einer Möglichkeit der Synchronisierung zwischen den Moderatoren. Dazu kann in die Contribution eine *workerId* eingetragen werden, die jedem Moderator zeigt, wer aktuell diese Contribution in Bearbeitung hat. Diese Information ist lediglich informativ, denn jeder Moderator kann sich selbst als workerId eintragen, um beispielsweise die Bearbeitung, bei längerer Abwesenheit des aktuell bearbeitenden Moderators, selbst zu übernehmen. Das AdminInterface bietet dazu für jede Contribution neben der Anzeige des aktuell bearbeitenden Moderators (Name aus User-Daten über *workerId* ermittelt) eine Möglichkeit die eigene ModeratorId als *workerId* in die Contribution einzutragen. Ein Wechsel der *workerId* hat keine Auswirkungen auf den aktuellen Status der Contribution.
 
 ### Nachrichten
 
@@ -43,10 +45,11 @@ In diesem Dokument werden alle zu dem Thema besprochenen und angedachten Anforde
 * **[AS-1]** Analog zur Detailansicht einer Contribution in der Wallet wird auch eine Detailansicht der Contributions im Admin-Bereich eingebaut.
 * **[AS-1]** Die Länge einer Nachricht wird auf maximal 2000 Zeichen begrenzt
 * **[AS-1]** Die Nachrichten werden als einfach verkettete Liste an die Contribution angehängt. Es wird keine Untertützung von Nachrichten an Nachrichten geben
-* **[AS-1]** Eine Nachricht unterscheidet sich im Typ, ob es eine vom User/Moderator manuell erstellte oder ob es eine vom System automatisierte Nachricht -z.B. Contribution-Versionierung, Nachricht über Confirmation, etc. - ist
+* **[AS-1]** Eine Nachricht unterscheidet sich im Typ, ob es eine vom User/Moderator erstellte DIALOG-Message oder ob es eine vom System automatisierte HISTORY-Message ist. Nachrichten, die während einer Bestätigung bzw. Ablehnung einer Contribution mit vordefinierten Texten vom System erstellt werden sind dennoch vom Typ DIALOG, denn der vordefinierte Text kann vom Moderator auch manuell überschrieben bzw. angepasst werden.
 * **[AS-1]** Ist die letzte, sprich jüngste Nachricht eine manuell erstellte Nachricht, kann diese vom Ersteller der Nachricht - `Messages.userId` - nachträglich bearbeitet werden. Neben dem geänderten Nachrichtentext wird der Zeitpunkt der Änderung im Feld `updatedAt `erfasst. Die Einsortierung in der Nachrichtenliste bleibt auch bei einer nachträglichen Änderung auf dem Feld `createdAt`.
 * **[AS-x]** Eine existente Nachricht kann nur von einem Moderator gelöscht werden - Unterbindung von unliebsamen Troll-Inhalten. Dabei wird ein SoftDelete ausgeführt und das Attribut *deleted_at* und *deleted_by* mit dem Zeitpunkt des Löschens und mit der UserId des Moderators gesetzt.
 * **[AS-x]** Ist die jüngste Nachricht der Liste eine DIALOG-Nachricht, dann kann diese vom User, der sie erstellt hat, nachträglich bearbeiten werden. In der Nachrichtenanzeige wird dazu ein Stift-Icon sichtbar, das die Anzeige der Nachricht in einen Bearbeitungsmodus versetzt, der den vorhandenen Text plus einen Abbruch- und einen Speichern-Button anzeigt. Mit Beenden des Bearbeitungsmodus per Speichern-Button wird der geänderte Text und der aktuelle Zeitpunkt in das *updated_at* gespeichert.
+* **[AS-x]** Die Verwaltung ob eine Nachricht neu ist und ob diese schon vom User/Moderator angezeigt sprich gelesen wurde, muss für eine spätere Ausbaustufe noch im Detail spezifiziert werden. Die einfache Variante mit einem Attribut *presentedAt* würde nur für den User funktionieren, nicht aber für zusätzlich mehrere Moderatoren und ggf. später für andere User.
 
 ## Contribution Ansichten
 
@@ -58,7 +61,9 @@ Die Contributions werden in den User-Ansichten "Meine Beiträge" und "Gemeinscha
 
 Die Liste der Contributions enthält vier Contributions, je eine in den vier verschiedenen Darstellungsarten "eingereicht", "in Bearbeitung", "bestätigt" und "abgelehnt". Die ersten beiden Contributions im Status "eingereicht" und "in Bearbeitung" können nachträglich noch bearbeitet oder gar gelöscht werden - zu erkennen an den Icons "Stift" und "Mülleimer". Diese Möglichkeit besteht bei den beiden anderen Contributions nicht mehr, da diese schon vom Support entsprechend bestätigt oder gar abgelehnt wurden.
 
-Das Icon Sprechblase in der Farbe grau deutet darauf hin, dass es zu dieser Contribution noch keine gespeicherten Nachrichten gibt. Ist das Sprechblasen-Icon blau, dann existieren zu der Contribution schon gespeicherte Nachrichten. Ist zu der Farbe blau auch noch eine Zahl, wie bei der zweiten Contribution sichtbar, dann ist in der Nachrichtenliste dieser Contribution eine neue Nachricht enthalten, die noch nicht vom User zur Anzeige gebracht wurde. Ein Klick auf das Sprechblasen-Icon öffnet die Nachrichten-Ansicht der entsprechenden Contribution, wodurch ein Update aller neuen noch ungelesenen Nachrichten erfolgt, in dem der Zeitpunkt der Anzeige in das Attribut *presented_at* eingetragen wird. Gleichzeit wird auch dadurch die Zahl unterhalb des blauen Sprechblasen-Icons gelöscht analog der dritten und vierten Contribution.
+Das Icon Sprechblase in der Farbe grau deutet darauf hin, dass es zu dieser Contribution noch keine gespeicherten Nachrichten gibt. Ist das Sprechblasen-Icon blau, dann existieren zu der Contribution schon gespeicherte Nachrichten. Ein Klick auf das Sprechblasen-Icon öffnet die Nachrichten-Ansicht der entsprechenden Contribution
+
+**[AS-x]** Ist zu der Farbe blau auch noch eine Zahl, wie bei der zweiten Contribution sichtbar, dann ist in der Nachrichtenliste dieser Contribution eine neue Nachricht enthalten, die noch nicht vom User zur Anzeige gebracht wurde. Ein Klick auf das Sprechblasen-Icon öffnet die Nachrichten-Ansicht der entsprechenden Contribution, wodurch ein Update aller neuen noch ungelesenen Nachrichten erfolgt, in dem der Zeitpunkt der Anzeige in das Attribut *presented_at* eingetragen wird. Gleichzeit wird auch dadurch die Zahl unterhalb des blauen Sprechblasen-Icons gelöscht analog der dritten und vierten Contribution.
 
 ## Contribution-Liste "Gemeinschaft" Ansicht
 
@@ -104,7 +109,7 @@ Mit Klicken auf das Sprechblasen-Icon kann die Nachrichten-Ansicht der Contribut
 
 ![img](./image/ContributionMyListDeniedMessages.png)
 
-Bei geöffneter Nachrichten-Ansicht wird unterhalb der Contribution eine Kopfzeile "Nachrichten" und darunter die Liste der Nachrichten chronologisch absteigend nach ihrem `createdAt`-Datum sortiert angezeigt. Pro Nachricht ist der Absender, der Zeitstempel der Nachrichtenerstellung und der Nachrichtentext zu sehen. 
+Bei geöffneter Nachrichten-Ansicht wird unterhalb der Contribution eine Kopfzeile "Nachrichten" und darunter die Liste der Nachrichten chronologisch absteigend nach ihrem `createdAt`-Datum sortiert angezeigt. Pro Nachricht ist der Absender, der Zeitstempel der Nachrichtenerstellung und der Nachrichtentext zu sehen.
 
 Eine einmal erstellte Nachricht kann vom User selbst zwar nicht mehr gelöscht, aber sie kann als jüngste Nachricht in der Nachrichtenliste vom Ersteller noch einmal bearbeitet werden, wie an dem sichtbaren Stift-Icon in der Nachricht zu erkennen ist. Mit Klick auf das Stift-Icon wechselt die Anzeige der Nachricht in den Bearbeitungsmodus (analog dem Erfassen einer neuen Nachricht wie im nächsten Kapitel), in dem der Text nun verändert werden kann und zwei angezeigte Buttons zum Speichern bzw zum Verwerfen der Änderungen. Sobald eine Nachricht nachträglich bearbeitet wurde, wird der Zeitpunkt der Bearbeitung zusätzlich mit dem Label "bearbeitet am: < Zeitpunkt >" hinter dem Creation-Zeitpunkt angezeigt.
 
@@ -122,19 +127,19 @@ Es wird mit Klicken auf das Sprechblasen-Icon mit den drei Punkten ein neues Nac
 
 ### searchContributions of User
 
-Mit diesem Service werden alle Contributions aber keine Messages, die dem einen User zugeordnet sind gelesen und nach ihrem CreatedAt-Datum zeitlich absteigend sortiert. Es werden weitere evtl. transiente Informationen pro Contribution mit geliefert, um die entsprechenden Ausprägungen im Frontend ansteuern zu können:
+Mit diesem Service werden alle Contributions aber ohne Messages, die dem einen User zugeordnet sind gelesen und nach ihrem CreatedAt-Datum zeitlich absteigend sortiert. Ein mögliches Paged-Reading über eine größere Menge an Contributions muss dabei möglich sein. Es werden weitere evtl. transiente Informationen pro Contribution mit geliefert, um die entsprechenden Ausprägungen im Frontend ansteuern zu können:
 
 * Status: eingereicht / in Bearbeitung / bestätigt / abgelehnt
 * Messages vorhanden: ja / nein
-* falls Messages vorhanden, wieviele davon sind ungelesen
+* **[AS-x]** falls Messages vorhanden, wieviele davon sind ungelesen
 
 ### searchContributions for all
 
-Mit diesem Service werden alle Contributions aber keine Messages, aller User gelesen und nach ihrem CreatedAt-Datum zeitlich absteigend sortiert. Es werden weitere evtl. transiente Informationen pro Contribution mit geliefert, um die entsprechenden Ausprägungen im Frontend ansteuern zu können:
+Mit diesem Service werden alle Contributions aber ohne Messages, aller User gelesen und nach ihrem CreatedAt-Datum zeitlich absteigend sortiert. Ein mögliches Paged-Reading über eine größere Menge an Contributions muss dabei möglich sein. Es werden weitere evtl. transiente Informationen pro Contribution mit geliefert, um die entsprechenden Ausprägungen im Frontend ansteuern zu können:
 
 * Status: eingereicht / in Bearbeitung / bestätigt / abgelehnt
 * Messages vorhanden: ja / nein
-* falls Messages vorhanden, wieviele davon sind ungelesen
+* **[AS-x]** falls Messages vorhanden, wieviele davon sind ungelesen
 * User-Info: Vorname, Nachname oder sofern vorhanden dann der Alias
 
 ### updateContribution
@@ -155,7 +160,7 @@ Mit diesem Service kann eine Contribution im Status "*eingereicht*" bzw. "*in Be
 
 ### searchContributionMessages
 
-Dieser Service liefert zu einer bestimmten Contribution alle gespeicherten Nachrichten chronologisch nach dem `CreatedAt`-Datum absteigend sortiert. Neben dem Nachrichtentext und dem CreatedAt-Datum wird auch der User, der die Nachricht erstellt hat, geliefert. Als User-Daten wird entweder der Vorname und Nachname oder falls vorhanden der Alias geliefert.
+Dieser Service liefert zu einer bestimmten Contribution alle gespeicherten Nachrichten chronologisch nach dem `CreatedAt`-Datum absteigend sortiert. Neben dem Nachrichtentext und dem CreatedAt-Datum wird auch der User, der die Nachricht erstellt hat, geliefert. Als User-Daten wird entweder der Vorname und Nachname oder falls vorhanden der Alias geliefert. Ein mögliches Paged-Reading über eine größere Menge an Messages muss dabei möglich sein.
 
 ### createMessageForContribution
 
@@ -163,7 +168,9 @@ Dieser Service liefert zu einer bestimmten Contribution alle gespeicherten Nachr
 
 ### UpdatePresentedMessagesOfContribution
 
-Mit diesem Service werden alle Nachrichten einer Contribution mit *presented_at* = null aktualisiert, in dem der aktuelle Zeitpunkt in das Attribut *presented_at* eingetragen wird.
+**[AS-x]** Die Verwaltung wer hat wann welche Nachricht angezeigt bzw. welche Nachricht ist für ein User bzw ein Moderator noch neu und ungelesen bedarf einer komplexeren Verwaltung, die auf eine zukünftige Ausbaustufe verschoben wird. Es wird dabei eine Many-To-Many Beziehung zwischen einer Message und einem User benötigt. 
+
+Ein einfacher Ansatz, der aber nur für den User funktionieren könnte, wäre mit dem Attribut *presented_at* in der Message.  Mit diesem Service werden alle Nachrichten einer Contribution mit *presented_at* = null aktualisiert, in dem der aktuelle Zeitpunkt in das Attribut *presented_at* eingetragen wird.
 
 ## Datenbank Anpassungen