From 0f0b308806f06d95204351beba7090269ce0c978 Mon Sep 17 00:00:00 2001
From: Carsten Rose <carsten.rose@math.uzh.ch>
Date: Thu, 4 Jan 2024 15:58:52 +0100
Subject: [PATCH] Refactore
---
Documentation-develop/CHAT.md | 330 +++++++++++++++++++---------------
1 file changed, 186 insertions(+), 144 deletions(-)
diff --git a/Documentation-develop/CHAT.md b/Documentation-develop/CHAT.md
index 36cb7be3a..05cc3dbcc 100644
--- a/Documentation-develop/CHAT.md
+++ b/Documentation-develop/CHAT.md
@@ -18,27 +18,15 @@
## Features
-Zu diskutieren.
-
### V1.0
-* Chat-Rooms:
-
- * a) *General Topic* : z.B. Support Anfrage
- * b) *Topic per Request* : Pro User (oder pro Antrag) und Topic (Rueckfrage an Antragsteller, Rueckfrage bei
- Stv.Dean, ...)
- * Columns:
-
- * grIdChatType (kann sowohl 'General Topic' als auch 'Topic per Request' sein). Bsp: 'Support', 'Rueckfrage an
- Antragsteller', 'Rueckfrage bei Stv.Dean', ...
- * xIdRequest (Bei 'Topic per Request' zeigt diese Column auf den User oder den Request).
-
+* Chat-Rooms
* User kann eingeloggt sein oder nicht (Anonymous)
- * Hintergrund 'Anonym': wenig Mehraufwand, es kann direkt auf einem Tool ein Chatfenster angezeigt werden um Kontakt
- aufzunehmen.
- * Ziel: Support Channel (I-MATH) in RC aufloesen und ein Chat Fenster auf MY anbieten. Gleiches fuer diverse andere
- QFQ Tools.
+ * Hintergrund 'Anonym': wenig Mehraufwand, es kann direkt auf einem Tool ein Chatfenster angezeigt werden um Kontakt
+ aufzunehmen.
+ * Ziel: Support Channel (I-MATH) in RC aufloesen und ein Chat Fenster auf MY anbieten. Gleiches fuer diverse andere
+ QFQ Tools.
* Anzeige Nachrichten:
@@ -48,44 +36,49 @@ Zu diskutieren.
### V1.1
* Thread pro Chat-Room.
-* Anzeige Nachrichten:
-
- * Lazy Loading.
- * Edit / Delete bestehender Messages.
+* Anzeige Nachrichten: Lazy Loading.
### V1.2
-* Flag 'Done' pro Chat Room / Thread.
-* Dashboard:
- * Anzahl offener Anfragen.
- * Anzahl offener Anfragen aelter als 8 Arbeitsstunden (critical).
- * Anzahl neu eingetroffener Anfragen seit dem die eigene Seite (typischerweise stellt die eine Seite Fragen und die
- andere Seite antwortet) das letzte mal im Chat geschrieben hat.
+* Flag 'Done' pro Chat-Room / Thread.
+* Dashboard Ideen (ist vermutlich keine PHP Implementierung sondern nur Best Practice SQL Queries):
+ * Anzahl offener Anfragen.
+ * Anzahl offener Anfragen aelter als 8 Arbeitsstunden (critical).
+ * Anzahl neu eingetroffener Anfragen seit dem die eigene Seite (typischerweise stellt die eine Seite Fragen und die
+ andere Seite antwortet) das letzte mal im Chat geschrieben hat.
### V1.3
-* Flag 'Read'
-* Reminder
* Chat: Public/Private
-* Permission:
+* *Edit Message* : Kann der Creator einer Message / Admin diese nachtraeglich veraendern?
+* *Delete Message* : Kann der Creator einer Message / Admin diese nachtraeglich veraendern?
+* *Make Semi-Private* : Nur interessant bei 'Public' Chats. By default ist ein Chat Verlauf in einem Public Chat fuer
+ alle
+ lesbar. Mit einem Click koennen alle Nachrichten eines Thread auf 'private' gestellt werden. Damit kann nur noch
+ der Creator und die 'andere' Seite die Chat's lesen. Das wird benoetigt fuer Anfragen via IT Support Chat, wenn
+ z.B. ein Prof eine allgmeine Frage hat und ploetzlich einen Studentennamen nennt.
- * *Read* : Nur interessant bei 'Public' Chats. By default ist ein Chat Verlauf in einem Public Chat fuer alle
- lesbar. Mit einem Click koennen alle Nachrichten eines Thread auf 'private' gestellt werden. Damit kann nur noch
- der Creator und die 'andere' Seite die Chat's lesen. Das wird benoetigt fuer Anfragen via IT Support Chat, wenn
- z.B. ein Prof eine allgmeine Frage hat und ploetzlich einen Studentennamen nennt.
- * *Edit* : Kann der Creator einer Message / Admin diese nachtraeglich veraendern?
- * *Delete* : Kann der Creator einer Message / Admin diese nachtraeglich veraendern?
+### V1.4
-* Tags pro Messages vergeben.
* Link zu einem Video Call anbieten (Jitsi, Teams, Zoom).
-* Thread: Teilnehmer (Admin oder Creator) kann einen bestehenden Thread teilen. Bsp: Die Diskussion beginnt ein weiteres
- Topic (oder User stellt mehrere Fragen) die einzeln behandelt werden sollen.
+
+### V1.5
+
+* Status 'Read'
+* Reminder
+
+### V1.6
+
* Screenshots / Attachments
* Emoticons
-### V1.4
+### V1.7
+* Split Thread: Teilnehmer (Admin oder Creator) kann einen bestehenden Thread teilen. Bsp: Die Diskussion beginnt ein
+ weiteres
+ Topic (oder User stellt mehrere Fragen) die einzeln behandelt werden sollen.
* Option: optionDoneResetOnNewMessage
+* Tags pro Messages vergeben.
## Konzept
@@ -106,47 +99,106 @@ Zu diskutieren.
* Records mit einer 'reference' werden gesynct.
- * Im aktuellen Konzept haben nur type='Topic' Records eine Reference. Damit sind Chat-Raume implizit
- Applikationslogik und werden bei einem Sync angelegt (falls die noch nicht existieren).
+ * Im aktuellen Konzept haben nur Chat.type='Topic' Records eine Reference.
+ * Damit werden Chat-Rooms implizit Applikationslogik, denn diese werden bei einem Sync angelegt (falls die noch
+ nicht existieren).
+ * Werden neue Chat-Rooms auf 'prod' angelegt, bleiben sie bei einem Sync unberuehrt (ok).
+
+### FormElement.parameter
+
+<pre>
+# Thread Support
+thread=0|1
+
+# Chat-Room: cIcTopic + xId bilden jeweils einen Chat-Room.
+cIdTopic=
+xId=
+
+# Person die die Message erstellt hat. Sonderfall: Bei Teams wird hier eine Fake Person eingetragen (z.B. Person.name='Team A')
+pIdCreator={{pIdFeUser}}
+
+# Mapping das FE.Chat auch mit anderen Tabellen, Spaltennamen arbeiten kann.
+columnMap=[apId:xId,pId:pIdCreator,grIdStatus:xGrIdStatus,...]
+tableName=history[, note]
+
+# Displayname des aktuellen Users. Bei Teams koennte das z.B. die reale Person sein, pIdCreator zeigt aber auf das Team.
+username = {{SELECT p.firstname, ' ', p.lastname FROM Person WHERE p.account='{{feUser:UT}}' }}
+
+# TBD: wo genau brauchen wir den noch?
+xGrIdStatus (optional)
+
+# Optional kann ein Teilnehmer pro Chat / Thread ein Flag 'done' setzen.
+# `off` - Es kann kein Flag 'done' gesetzt werden.
+# `all` - Jeder Teilnehmer kann ein Flag 'done' setzen/loeschen. Im Chat wird angezeigt welche Personen ein Flag 'done' gesetzt haben.
+# 'my' - Jeder Teilnehmer kann ein Flag 'done' setzen/loeschen. Im Chat wird nur angezeigt wenn man selbst ein Flag 'done' gesetzt hat.
+optionDone=*off|all|my
+
+# 0: Done Flag wird vollstaendig manuell kontrolliert.
+# 1: Ist das done Flag gesetzt und wird eine neue Message gesendet, wird das done Flag automatisch geloescht.
+optionDoneResetOnNewMessage=0|1
+
+# Pro Teilnehmer kann auf einem Chat / Thread ein Reminder gesetzt werden.
+optionReminder=0|1
+</pre>
+
+Beispiel `FE.type=chat`:
+
+<pre>
+fillStoreVar={{!SELECT CONCAT(p.firstname, ' ', p.lastname) AS username, p.id AS pId FROM Person WHERE p.account='{{feUser:UT}}' }}
+cIdTopic={{SELECT c.id FROM Chat AS c WHERE c.reference='RueckfrageAntragsteller'}}
+username={{username:V}}
+pIdCreator={{pId:V}}
+xId={{id:R}}
+thread=0|1
+optionDone=all
+</pre>
+
+### Chat-Room
+
+Es gibt zwei Sorten von Chat-Rooms:
+
+* General Topic : z.B. Support Anfrage.
+* Topic per Request : Pro User (oder pro Antrag) und Topic (Rueckfrage an Antragsteller, Rueckfrage bei Stv.Dean, ...)
+
+Bei einen `General Topic` kann `per Request` einfach leer gelassen werden (=0).
+
+Die Chat-Rooms (name, id) werden in der Tabelle `Chat` gespeichert mit `Chat.type='topic'`.
### Thread
-Motivation: In einem Support Chat Room beginnt jeder User Request einen neuen Thread. Damit ist es moeglich eine
-Übersicht über die offenen Anfragen zu behalten.
+Motivation: In einem Chat-Room, in dem viele Personen Anfragen stellen koennen, geht schnell die Ãœbersicht verloren wer
+mit wem was diskutiert. _Threads_ innerhalb eines Chats helfen die Uebersicht zu behalten.
-Pro FE.type='Chat' kann konfiguriert werden ob @FE.parameter.threads=0|1@ unterstuetzt werden.
+Pro FE.type='Chat' kann konfiguriert werden ob @FE.parameter.threads=0|1@ moeglich sind.
Umsetzung:
-* Column: chat.cIdThread
-* Vorschlag: Bei dem ersten Record eines Threads ist cIdThreadId=0 (das ist implizit das Flag das bei diesem Record ein
- Thread startet).
+* Column: Chat.cIdThread
+* Bei dem ersten Message-Record eines Threads ist `Chat.cIdThreadId=0` - das ist implizit das Flag das bei diesem Record
+ ein
+ Thread startet.
+* Alle weiteren Message-Records des Threads zeigen mit `Chat.cIdThreadId=...` auf den ersten Thread Message-Record.
UI:
-* By default sind alle Threads zusammen geklappt, nur der neueste ist offen (vergleichbar RC).
-* Durch anklicken auf einen anderen Thread wird dieser aktiv und aufgeklappt. Die anderen Threads sind dann gemuted.
-* Die Message Eingabe Textbox (sticky unten) sendet immer in den zuletzt aktivierten Thread.
-* Message:
-
- * Message zu einem Thread: die threadId in der SIP.
- * Message zu einem neuem Thread: keine threadId in der SIP (also 0).
-
+* By default ist der neueste Thread ausgeklappt und _aktiv_, alle anderen Threads sind zusammen geklappt (vergleichbar
+ RC).
+* Durch anklicken eines anderen Thread wird dieser aktiv und aufgeklappt. Die anderen Threads sind inaktiv/gemuted.
+* Die Message Eingabe Textbox (sticky, unten) sendet immer in den zuletzt aktivierten Thread (in RC ist das anders
+ geloest).
+* New Message:
+ * zu einem _bestehenden_ Thread: die threadId in der SIP.
+ * zu einem _neuem_ Thread: keine threadId in der SIP (also 0).
+* Beispiel ('+' bedeutet eingeklappt):
<pre>
+Dekanat: cxxxxdgsdg
+Dekanat: cxxxxdgsdg
+Dekanat: cxxxxdgsdg
Dekanat: cxxxxdgsdg
-
skdafhsdkafhsdakf: Antragsteller
-
skdafhsdkafhsdakf: Antragsteller
-
Dekanat: cxxxxdgsdg
-
skdafhsdkafhsdakf: Antragsteller
-
-
+Dekanat: cxxxxdgsdg
------------------------------------------
@@ -156,45 +208,44 @@ Dekanat: cxxxxdgsdg
### Flag 'done'
-* Ein 'Done' Flag kann gesetzt werden pro Chat Teilnehmer und Chat/Thread.
-* Darstellung (zur Diskussion):
-
- * thread=no: Oben rechts 'done: Olga ..., Patrick ...'
- * thread=yes: Im Thread Rahmen oben rechts 'done: Olga ..., Patrick ...'
-
-* Ein Chat.type=done Record symbolisiert der Chat/Thread ist als 'done' markiert. Soll das 'done' Flag wieder geloescht
- werden, wird der Record geloescht.
- * Hintergrund: nur wenige User werden den done-Mechanismus nutzen, damit haben wir dann nur die wirklich noetigen
- Records.
-* Change: Es wird ein 'Refresh' an den Websocket gesendet damit alle Clients informiert werden und die Messages, inkl.
- Done Status neu laden.
-* Hinweis Teams: Es wird in pIdCreator nicht der aktuelle FeUser eingetragen, sondern eine
- Fake Person 'Dekanat MEF'. Welche Person eingetragen wird kontrolliert die Konfiguration des FE.Chat Elements. Die
- eine Seite des Chats (Antragsteller) kann eine andere Konfiguration haben als die andere Seite (Dekanat).
-
- * Nachteil: Normalerweise ist der Autor einer Chat Nachricht auf der rechten Seite im Chat. Bei dieser Variante
- werden
- alle Chatnachrichten des Teams (egal welche Teamsmitglied ) rechts dargestellt. Wir haben ueber eine Spalte '
- pIdTeam'
- nachgedacht, das ist aber nicht ausgearbeitet.
+* Optional kann ein Flag 'Done' gesetzt werden pro Chat Teilnehmer und Chat/Thread.
+* Ziel:
+ * Die Ãœbersicht behalten in Chat-Rooms mit vielen Anfragen welche Punkte noch zu tun sind.
+ * Auf einem Dashboard anzeigen, in welchen Chat-Rooms noch etwas zu tun ist (typischerweise gab es bei einem Antrag
+ eine Rückfrage).
+* Darstellung:
+ * FE.thread=0: Oben rechts 'done: John, Jane'
+ * FE.thread=1: Im Thread Rahmen oben rechts 'done: John, Jane'
+* Ein `Chat.type=done` Record symbolisiert 'done' fuer den Chat/Thread und den User `Chat.pIdCreator`.
+* Soll das Flag 'done' wieder geloescht werden, wird der Record geloescht.
+ * Hintergrund: nur wenige User werden den done-Mechanismus nutzen, damit werden dann nur die wirklich noetigen
+ Records angelegt.
+ * Mit dem loeschen muss nicht zusaetzlich ein value on/off gemanaged werden.
+* Pro Chat/Thread koennen beliebig viele `Chat.type=done` Records angelegt werden. D.h. jeder User kann fuer sich
+ markieren ob dieser Chat/Thread fuer ihn 'done' ist.
+* Change: User klickt auf das 'done' Icon.
+ * API Aufruf save.php
+ * Der Done Status wird gesetzt oder geloescht, je nachdem was vorher war.
+ * Es wird ein 'Refresh' an den Websocket gesendet, um alle registrierten Clients zu informier die Messages, inkl.
+ Done Status, neu zu laden.
* Mode 'Set Status Done'
- * FE.type=Chat wird geladen
- * Value: 0|1
- * Check ob es bereits ein Record 'done' zu dem aktuellen Chat/Thread gibt.
- * Nein & value==1: es wird ein Record angelegt.
- * Ja & value==0: der Record wird geloescht.
+ * FE.type=Chat wird geladen
+ * Value: 0|1
+ * Check ob es bereits ein Record 'done' zu dem aktuellen Chat/Thread gibt.
+ * Nein & value==1: es wird ein Record angelegt.
+ * Ja & value==0: der Record wird geloescht.
* Tabelle Chat:
- * type='done'
- * cIdTopic, xId: pro Chat Room
- * cIdThread: pro Thread moeglich
+ * type='done'
+ * cIdTopic, xId: pro Chat-Room
+ * cIdThread: pro Thread moeglich
* pIdCreator: Person fuer die dieser Chat/Thread als 'done' markiert ist.
-### Flag 'read'
+### Status 'read'
-* Pro User und Chat-Room gibt es einen Pointer der auf die letzte gelesene Nachricht zeigt: Chat.cIdLastRead
+* Pro User und Chat-Room gibt es einen Pointer der auf die letzte gelesene Nachricht zeigt: `Chat.cIdLastRead`
* Alle Chat.id die groesser sind als dieser Wert, werden als 'ungelesen' dargestellt: Strich 'unread' hinter der letzten
gelesenen Nachricht.
* Update Chat.cIdLastRead:
@@ -206,9 +257,9 @@ Dekanat: cxxxxdgsdg
sobald
der User das erste mal den Chat aufmacht.
* Tabelle Chat:
- * type='read'
- * cIdTopic, xId: pro Chat Room
- * cIdLastRead: Pointer auf die zuletzt gelesene Message des pIdCreator.
+ * type='read'
+ * cIdTopic, xId: pro Chat-Room
+ * cIdLastRead: Pointer auf die zuletzt gelesene Message des pIdCreator.
* pIdCreator: Chat Teilnehmer
### Reminder
@@ -230,18 +281,43 @@ Dekanat: cxxxxdgsdg
* Koennen gemuted werden (.z.B. 24h)
* Tabelle Chat:
- * type='reminder'
- * cIdTopic, xId: pro Chat Room
- * cIdThread: pro Thread moeglich
- * reminder: timestamp wann der Reminder aufpoppen soll
- * message: Eigene Custom Nachricht die man angeben kann wenn man den Remider setzt.
- * pIdCreator: Person die den Reminder angelegt hat.
+ * type='reminder'
+ * cIdTopic, xId: pro Chat-Room
+ * cIdThread: pro Thread moeglich
+ * reminder: timestamp wann der Reminder aufpoppen soll
+ * message: Eigene Custom Nachricht die man angeben kann wenn man den Remider setzt.
+ * pIdCreator: Person die den Reminder angelegt hat.
+
+### Attachments
+
+TBD
### Emoticons
* Pro Message
* Chat.emoticons = 'thumbsup:enured,crose;smiley:crose,jhaller,bbaer'
+### Team
+
+* Gerade bei Support Chats kommt es haeufig vor, dass Anfragen von einem Team von Personen bearbeitet werden.
+* Um die Ãœbersicht zu behalten welche Anfragen offen/in progress/done sind, koennte z.B. als pIdCreator nicht eine
+ reale Person eingetragen werden, sondern eine Fake Person die ein Team representiert.
+* Mit dieser Variante koennte mit wenig Aufwand eine 'Team'-Applikationslogik implementiert werden.
+* Die eine Seite des Chats (Antragsteller) kann eine andere Konfiguration haben als die andere Seite (Dekanat).
+ Welche Person eingetragen wird kontrolliert das FE.Chat Element. Damit ist es einfach moeglich auf der einen Seite
+ ein _Team_ als Creator einzutragen.
+
+ * Hinweis: Damit der Autor einer Chat Nachricht immer auf der rechten Seite im Chat erscheint sollte fuer die
+ fuer die Seitenerkennung nicht `pIdCreator` sondern `pIdCreator+username` verwendet werden.
+
+Frage: brauchen wir wirklich diese Art von Teams?
+
+* Koennte das gleiche nicht implizit erreicht werden? Ein 'Team' kennt alle 'seine'
+ Chat-Rooms, das reicht aus um die offenen Anfrage fuer die man zustaendig ist anzuzeigen.
+* Auch die Existenz eines 'done' Flags muesste ausreichen um zu erkennen das eine Anfrage 'done' ist, egal wer als
+ 'Creator' eingetragen ist.
+* Die Diskussion ist aber eigentlich egal, denn wenn FE.pidCreator={{pIdFeUser:Y}} ist, werden keine Teams verwendet.
+
## API
### Load Messages
@@ -266,45 +342,7 @@ TBD: was liefert der AJAX Call load.php zurueck wenn die 10 neuesten Messages, i
* FormElement.id (zeigt direkt auf das FE.type=Chat Element)
* Mode: 'Set Status Done'
-## Beschreibung Parameter
-
-### FE.parameter
-
-<pre>
-thread=0|1
-cIdTopic=
-xId=
-pIdCreator={{pIdFeUser}}
-pIdTeam=123 (=Dekanat BEF)
-columnMap=[apId:xId,pId:pIdCreator,grIdStatus:xGrIdStatus,...]
-tableName=history[, note]
-username = {{SELECT p.firstname, ' ', p.lastname FROM Person WHERE p.account='{{feUser:UT}}' }}
-xGrIdStatus (optional)
-
-# a) Wer kann einen Status 'done' pro Chat/Thread setzen
-# b) bei 'my' wird nur das eigene Done Flag angezeigt,
-# bei 'all' kann auch nur das eigene Done Flag gesetzt werden, aber man sieht zusaetzlich noch die anderen
-optionDone=*off|all|my
-
-# 0: Done Flag wird vollstaendig manuell kontrolliert
-# 1: Ist das done Flag gesetzt und wird eine neue Message gesendet, wird das done Flag automatisch geloescht.
-optionDoneResetOnNewMessage=0|1
-
-optionReminder=0|1
-</pre>
-
-Beispiel FE.type=chat:
-
-<pre>
-fillStoreVar={{!SELECT CONCAT(p.firstname, ' ', p.lastname) AS username, p.id AS pId FROM Person WHERE p.account='{{feUser:UT}}' }}
-cIdTopic={{SELECT c.id FROM Chat AS c WHERE c.reference='RueckfrageAntragsteller'}}
-username={{username:V}}
-pIdCreator={{pId:V}}
-pIdTeam=123 (=Dekanat BEF)
-xId={{id:R}}
-thread=0|1 (s.u.)
-optionDone=all
-</pre>
+## Umsetzung
QFQ interne Query fuer alle Messages (FE.thread=0):
<pre>
@@ -348,14 +386,14 @@ Pseudo Person (=Dekanat BEF).
### threadId
-Innerhalb eines Chat Rooms (Beispiel: Antrag 123 & 'Frage von Antragsteller an Dekanat') soll es moeglich sein mehrere
+Innerhalb eines Chat-Rooms (Beispiel: Antrag 123 & 'Frage von Antragsteller an Dekanat') soll es moeglich sein mehrere
Threads zu fuehren.
* Die `threadId` gruppiert Records eines Threads.
* Bsp: Antrag 123 hat a) eine Rueckfrage an den Antragsteller und b) eine Rueckfrage zum Vize-Dean. Die threadId waere
in dem Fall eine unterschiedliche Nummer.
* Die threadId koennte z.B. die ID des ersten Chat-Records in einem Thread sein.
-* BTW: Eine grIdChatType (='Chat Room' ... aber ich finde der Begriff 'room' passt hier nicht so gut) waere z.B. 'Frage
+* BTW: Eine grIdChatType (='Chat-Room' ... aber ich finde der Begriff 'room' passt hier nicht so gut) waere z.B. 'Frage
von Antragsteller', 'Frage an Antragsteller' oder 'Frage an Vize Dean', ... - also eine uebergeordnete
Kategorisierung.
* Pro Antragsteller und grIdChatType koennen theoretisch mehrere Threads existieren - z.B. wenn der Antragsteller am
@@ -446,4 +484,8 @@ A
### Flag done
-* Falls ein thread='done', ist das Textmessage Eingabe Feld muted und der 'Send' Button zeigt 'Reopen' an.
\ No newline at end of file
+* Falls ein thread='done', ist das Textmessage Eingabe Feld muted und der 'Send' Button zeigt 'Reopen' an.
+
+### FormElement.parameter
+
+pIdTeam=123 (=Dekanat BEF)
--
GitLab