diff --git a/docu/Concepts/BusinessRequirements/UC_Send_Contribution.md b/docu/Concepts/BusinessRequirements/UC_Send_Contribution.md index ab04efc7f..ac982fa53 100644 --- a/docu/Concepts/BusinessRequirements/UC_Send_Contribution.md +++ b/docu/Concepts/BusinessRequirements/UC_Send_Contribution.md @@ -2,6 +2,18 @@ Die Idee besteht darin, dass ein Administrator eine Contribution mit all seinen Attributen und Regeln im System erfasst. Dabei kann er unter anderem festlegen, ob für diese ein Link oder ein QR-Code generiert und über andere Medien wie Email oder Messenger versendet werden kann. Der Empfänger kann diesen Link bzw QR-Code dann über die Gradido-Anwendung einlösen und bekommt dann den Betrag der Contribution als Schöpfung auf seinem Konto gutgeschrieben. +## Ausbaustufen + +Die beschriebenen Anforderungen werden in mehrere Ausbaustufen eingeteilt. Damit können nach und nach die Dialoge und Businesslogik schrittweise in verschiedene Releases gegossen und ausgeliefert werden. + +### Ausbaustufe 1 + +Diese Ausbaustufe wird gezielt für die "Dokumenta" im Juni 2022 zusammengestellt. Details siehe weiter unten im speziellen Kapitel "Ausbaustufe 1". + +### Ausbaustufe 2 + +Diese Ausbaustufe wird gezielt für die Anforderungen für das Medidationsportal von "Abraham" zusammegestellt. Details siehe weiter unten im speziellen Kapitel "Ausbaustufe 2". + ## Logischer Ablauf Der logische Ablauf für das Szenario "Activity-Confirmation and booking of Creations " wird in der nachfolgenden Grafik dargestellt. Dabei wird links das Szenario der "interactive Confirmation and booking of Creations" und rechts "automatic Confirmation and booking of Creations" dargestellt. Ziel dieser Grafik ist neben der logischen Ablaufsübersicht auch die Gemeinsamkeiten und Unterschiede der beiden Szenarien herauszuarbeiten. @@ -28,11 +40,11 @@ Der Gültigkeitsstart wird als Default mit dem aktuellen Erfassungszeitpunkt vor Wie häufig ein User für diese Contribution eine Schöpfung gutgeschrieben bekommen kann, wird über die Auswahl eines Zyklus - stündlich, 2-stündlich, 4-stündlich, etc. - und innerhalb dieses Zyklus eine Anzahl an Wiederholungen definiert. Voreinstellung sind 1x täglich. -![Zyklus](./image/UC_Send_Contribution_Admin-new ContributionZyklus.png) +![img](./image/UC_Send_Contribution_Admin-new_ContributionZyklus.png) Ob die Contribution über einen versendeten Link bzw. QR-Code geschöpft werden kann, wird mittels der Auswahl "Versenden möglich als" bestimmt. -![send](./image/UC_Send_Contribution_Admin-new ContributionSend.png) +![img](./image/UC_Send_Contribution_Admin-new_ContributionSend.png) Für die Schöpfung der Contribution können weitere Regeln definiert werden: @@ -44,11 +56,11 @@ Für die Schöpfung der Contribution können weitere Regeln definiert werden: ![new](./image/UC_Send_Contribution_Admin-newContribution.png) -### Ausbaustufe-1: +## Ausbaustufe-1: -Die Ausbaustufe-1 wird gezielt auf die Anforderungen der "Dokumenta" im Juni 2022 abgestimmt. +Die Ausbaustufe-1 wird gezielt auf die Anforderungen der "Dokumenta" im Juni 2022 abgestimmt. -#### Contribution-Erfassungsdialog (Adminbereich) +### Contribution-Erfassungsdialog (Adminbereich) Es werden folgende Anforderungen an den Erfassungsdialog einer Contribution gestellt: @@ -64,14 +76,12 @@ Es werden folgende Anforderungen an den Erfassungsdialog einer Contribution gest | VersendenMöglich | - hier wird "als Link / QR-Code" voreingestellt | | alle weiteren Attribute | - entfallen für diese Ausbaustufe
- die GUI-Komponenten können optional schon im Dialog eingebaut und angezeigt werden
- diese GUI-Komponenten müssen wenn sichtbar disabled sein und dürfen damit keine Eingaben entgegen nehmen | - -#### Ablauflogik +### Ablauflogik Für die Ausbaustufe-1 wird gemäß der Beschreibung aus dem Kapitel "Logischer Ablauf" nur die "automatic Confirmation and booking of Creations" umgesetzt. Die interaktive Variante - sprich Ablösung des EloPage Prozesses - mit "interactive Confirmation and booking of Creations" bleibt für eine spätere Ausbaustufe aussen vor. Das Regelwerk in der Businesslogik wird gemäß der reduzierten Contribution-Attribute aus dem Erfassungsdialog, den vordefinierten Initialwerten und der daraus resultierenden Variantenvielfalt vereinfacht. - #### Kriterien "Dokumenta" * Es soll eine "Dokumenta"-Contribution im Admin-Bereich erfassbar sein und in der Datenbank als ContributionLink gespeichert werden. @@ -91,6 +101,66 @@ Das Regelwerk in der Businesslogik wird gemäß der reduzierten Contribution-Att * es erfolgt eine übliche Schöpfungstransaktion nach der Bestätigung der Contribution * die Schöpfungstransaktion schreibt den Betrag der Contribution dem Kontostand des Users gut +## Ausbaustufe-2 + +Die Ausbaustufe-2 wird gezielt auf die Anforderungen zur Anbindung des Meditationsportals von Abraham im Oktober 2022 abgestimmt. + +### Contribution-Erfassungsdialog (Adminbereich) + +Es werden folgende Anforderungen an den Erfassungsdialog einer Contribution gestellt: + +| Attribut | Beschreibung | +| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GültigBis | - das Datum, wie lange die Contribution gültig und damit einlösbar ist
- für diese Ausbaustufe soll ein offenes Ende möglich sein, daher bleibt dieses Attribut leer | +| Zyklus | - Angabe wie häufig eine Contribution gutgeschrieben werden kann
- als Auswahlliste (Combobox) geplant, aber für diese Ausbaustufe nur mit dem Wert "täglich" vorbelegt | +| Wiederholungen | - Anzahl an Wiederholungen pro Zyklus
- für diese Ausbaustufe wird der Wert "1" vorbelegt -> somit gilt: ein User kann diese Contribution nur 1x täglich einlösen | +| alle weiteren noch nicht vorhandenen Attribute | - entfallen für diese Ausbaustufe
- die GUI-Komponenten können optional schon im Dialog eingebaut und angezeigt werden
- diese GUI-Komponenten müssen wenn sichtbar disabled sein und dürfen damit keine Eingaben entgegen nehmen | + +### Ablauflogik + +Für die Ausbaustufe-2 und der inzwischen umgesetzten Ablösung des "EloPage Contribution Erfassungsprozesses" wird gemäß der Beschreibung aus dem Kapitel "Logischer Ablauf" die "automatic Confirmation and booking of Creations" sowie die interaktive Variante "interactive Confirmation and booking of Creations" mit berücksichtigt. + +Das Regelwerk in der Businesslogik wird gemäß der noch nicht vollumfänglich geplanten Contribution-Attribute aus dem Erfassungsdialog, den vordefinierten Initialwerten und der daraus resultierenden Variantenvielfalt vereinfacht. + +#### Kriterien "Meditationsportal (Abraham)" + +* Es soll eine "GlobalMeditation"-Contribution nur im Admin-Bereich erfassbar sein und in der Datenbank als ContributionLink gespeichert werden. +* Es wird ein offenes Ende als Gesamtlaufzeit dieser Contribution benötigt, was durch ein leeres GültigBis-Datum ausgedrückt bzw. erfasst werden soll. +* Die "Meditationsportal"-Contribution kann von einem User maximal 1x täglich aktiviert werden. Dies wird über die Erfassung des Attributes "Zyklus" = täglich und des Attributes "Wiederholungen" = 1 ermöglicht. +* Ein User kann mit diesem Link nur die Menge an GDDs schöpfen, die in der Contribution als "Betrag" festgelegt ist +* Die "GlobalMeditation"-Contribution kann als Link / QR-Code erzeugt, angezeigt und in die Zwischenablage kopiert werden +* Jeder beliebige User kann den Link / QR-Code aktivieren +* der Link führt auf eine Gradido-Seite, wo der User sich anmelden oder registrieren kann +* mit erfolgreichem Login bzw. Registrierung wird der automatische Bestätigungs- und Schöpfungsprozess getriggert +* es erfolgt eine Überprüfung der definierten Contribution-Regeln für den angemeldeten User: + * Gültigkeit: liegt die Aktivierung im Gültigkeitszeitraum der Contribution + * Zyklus und WIederholungen: bei einem Zyklus-Wert = "täglich" und einem Wiederholungswert = 1 darf der User den Betrag dieser Contribution nur einmal am Tag schöpfen. Es gibt keine Überprüfung eines zeitlichen Mindestabstandes zwischen zwei Schöpfungen an zwei aufeinanderfolgenden Tagen. + * max. schöpfbarer Gradido-Betrag pro Monat: wenn der Betrag der Contribution plus der Betrag, den der User in diesem Monat schon geschöpft hat, den maximal schöpfbaren Betrag pro Monat von 1000 GDD übersteigt, dann wird die Schöpfung dieser Contribution abgelehnt +* mit erfolgreich durchlaufenen Regelprüfungen wird ein "besätigter" aber "noch nicht gebuchten" Eintrag in der "Contributions"-Tabelle erzeugt +* ein "bestätigter" aber "noch nicht gebuchter" "Contributions"-Eintrag stößt eine Schöpfungstransaktion für den User an +* es erfolgt eine übliche Schöpfungstransaktion mit automatischer Bestätigung der Contribution +* die Schöpfungstransaktion schreibt den Betrag der Contribution dem Kontostand des Users gut + +## Ausbaustufe-3 + +### Änderungen im Registrierungsprozess + +Aktuell treten Probleme mit der Aktivierung des ContributionLinks während des Registrierungsprozesses auf. Sobald der User bei der Registrierung sein Konto zwar angelegt, aber die erhaltene Email-Confirmation nicht abgeschlossen und damit sein Konto noch nicht aktiviert hat, kann derzeit der Redeem-Link nicht als Transaktion durchgeführt werden. Die Gültigkeitsdauer des Redeemlink reicht meist nicht bis der User sein Konto aktiviert. Daher wird nun die Idee verfolgt die Einlösung des Redeemlinks schon während der Anlage des inaktiven Kontos als "pendingRedeem Contribution" anzulegen. Sobald dann der User sein Konto per Email-Confirmation aktiviert, soll die "pendingRedeem Contribution" automatisch zu einer Tranaktion überführt und der Betrag des Redeemlinks auf das Konto des Users gebucht werden. + +Folgende Schritte und Änderungen sind dabei vorgesehen (siehe in der Grafik rechts im orange markierten Bereich im Vergleich zur Grafik im Kapitel "Logischer Ablauf"): + +![img](./image/Ablauf_manuelle_auto_Creations_2.png) + +* Der User landet mit Aktivierung eines Redeem-Links wie bisher auf der Login/Registrierungsseite, wobei wie bisher schon der Redeemlink als Parameter in den Registrierungsprozess übergeben wird. +* Mit der Anlage des neuen aber noch inaktiven User-Kontos und einer Übergabe eines Redeemlinks wird der Redeemlink zu einer "pendingRedeem Contribution" für den neuen User angelegt, aber noch nicht als Transaktion gebucht + * nach Anlage des inaktiven User-Kontos und bevor die Confirmation-Email abgeschickt wird, erfolgt das Schreiben eines neuen Contribution-Eintrages mit den Daten des Redeem-Links. + * Die neu angelegte Contribution wird im Status "pendingRedeem" gespeichert. Dieser neue Status ist notwendig, um im AdminInterface die normalen "pending Contributions" von den "pendingRedeem Contributions" zu unterscheiden. Denn der Admin soll zum Einen diese "pendingRedeem Contributions" weder bestätigen noch ablehnen können und zum Anderen sollen die "pendingRedeem Contributions" automatisiert bestätigt und gebucht werden können. Daher wird eine Unterscheidung zwischen den interaktiv angelegten Contributions im Status pending und den per Redeem-Link angelegten Contributions im Status pending benötigt. + * Damit endet erst einmal die weitere Verarbeitung der Redeem-Link-Aktivierung +* Mit Aktivierung des Links in der Email-Confirmation und damit der Aktivierung des User-Kontos erfolgt automatisch die Buchung der "pendingRedeem Contribution" und führt damit zur eigentlichen Buchung des Redeem-Betrages auf das User Konto. + * mit Erhalt der Email-Confirmation Aktivierung wird das User-Konto aktiviert + * Nach der Aktivierung des User-Kontos erfolgt eine Prüfung auf schon vorhandene "pendingRedeem Contributions" aus vorherigen Redeem-Link-Aktivierungen + * Jede vorhandene "pendingRedeem Contribution" wird jetzt automatisch bestätigt und zu einer Transaktion überführt + * Mit der bestätigten Contribution und daraus überführten Transaktion erhält der User eine Bestätigungsemail mit den Contribution spezifischen Daten. ## Datenbank-Modell @@ -100,34 +170,36 @@ Das nachfolgende Bild zeigt das Datenmodell vor der Einführung und Migration au ![Datenbankmodell](./image/DB-Diagramm_20220518.png) -### Datenbank-Änderungen +### Ausbaustufe-1 + +#### Datenbank-Änderungen Die Datenbank wird in ihrer vollständigen Ausprägung trotz Ausbaustufe-1 wie folgt beschrieben umgesetzt. -#### neue Tabellen +##### neue Tabellen -##### contribution_links - Tabelle +###### contribution_links - Tabelle | Name | Typ | Nullable | Default | Kommentar | | ------------------------------- | ------------ | :------: | :------------: | -------------------------------------------------------------------------------------------------------------------------------------- | | id | INT UNSIGNED | NOT NULL | auto increment | PrimaryKey | -| name | varchar(100) | NOT NULL | | unique Name | -| description | varchar(255) | | | | +| name | varchar(100) | NOT NULL | | unique Name | +| description | varchar(255) | | | | | valid_from | DATETIME | NOT NULL | NOW | | -| valid_to | DATETIME | | NULL | | -| amount | DECIMAL | NOT NULL | | | +| valid_to | DATETIME | | NULL | | +| amount | DECIMAL | NOT NULL | | | | cycle | ENUM | NOT NULL | ONCE | ONCE, HOUR, 2HOUR, 4HOUR, 8HOUR, HALFDAY, DAY, 2DAYS, 3DAYS, 4DAYS, 5DAYS, 6DAYS, WEEK, 2WEEKS, MONTH, 2MONTH, QUARTER, HALFYEAR, YEAR | | max_per_cycle | INT UNSIGNED | NOT NULL | 1 | | -| max_amount_per_month | DECIMAL | | NULL | | -| total_max_count_of_contribution | INT UNSIGNED | | NULL | | -| max_account_balance | DECIMAL | | NULL | | -| min_gap_hours | INT UNSIGNED | | NULL | | -| created_at | DATETIME | | NOW | | -| deleted_at | DATETIMEBOOL | | NULL | | -| code | varchar(24) | | NULL | | -| link_enabled | BOOL | | NULL | | +| max_amount_per_month | DECIMAL | | NULL | | +| total_max_count_of_contribution | INT UNSIGNED | | NULL | | +| max_account_balance | DECIMAL | | NULL | | +| min_gap_hours | INT UNSIGNED | | NULL | | +| created_at | DATETIME | | NOW | | +| deleted_at | DATETIMEBOOL | | NULL | | +| code | varchar(24) | | NULL | | +| link_enabled | BOOL | | NULL | | -##### contributions -Tabelle +###### contributions -Tabelle | Name | Typ | Nullable | Default | Kommentar | | --------------------- | ------------ | -------- | -------------- | -------------------------------------------------------------------------------- | @@ -145,9 +217,9 @@ Die Datenbank wird in ihrer vollständigen Ausprägung trotz Ausbaustufe-1 wie f | booked_at | DATETIME | | NULL | date, when the system has booked the amount of the activity on the users account | | deleted_at | DATETIME | | NULL | soft delete | -#### zu migrierende Tabellen +##### zu migrierende Tabellen -##### Tabelle admin_pending_creations +###### Tabelle admin_pending_creations Diese Tabelle wird im Rahmen dieses UseCase migriert in die neue Tabelle contributions... @@ -168,6 +240,18 @@ Diese Tabelle wird im Rahmen dieses UseCase migriert in die neue Tabelle contrib ...und kann nach Übernahme der Daten in die neue Tabelle gelöscht werden oder es erfolgen die Änderungen sofort auf der Ursprungstabelle. -### Zielmodell +#### Zielmodell ![Contributions-DB](./image/DB-Diagramm_Contributions.png) + +### Ausbaustufe-2 + +Für die Ausbaustufe-2 sind keine Datenbank-Änderungen notwendig. Gemäß dem Zielmodell sind alle notwendigen Tabellen und Attribute schon vorhanden. + +#### Zielmodell + +![img](./image/DB-Diagramm_Contributions_Stufe_2.png) + +### Ausbaustufe-3 + +Für die Ausbaustufe-3 dürften im Grunde ebenfalls keine zusätzlichen Datenbankänderungen notwendig sein. Denn für eine "pending Contribution" und deren Confirmation mit Tranaktionsüberführng sind ebenfalls schon alle Attribute vorhanden. diff --git a/docu/Concepts/BusinessRequirements/graphics/Ablauf_manuelle_auto_Creations.drawio b/docu/Concepts/BusinessRequirements/graphics/Ablauf_manuelle_auto_Creations.drawio index b4f1f45ea..3c2ae0559 100644 --- a/docu/Concepts/BusinessRequirements/graphics/Ablauf_manuelle_auto_Creations.drawio +++ b/docu/Concepts/BusinessRequirements/graphics/Ablauf_manuelle_auto_Creations.drawio @@ -1,6 +1,6 @@ - + @@ -183,31 +183,31 @@ - + - + - + - + - + - + @@ -317,15 +317,15 @@ - + - + - + @@ -334,10 +334,10 @@ - + - + @@ -351,7 +351,7 @@ - + @@ -359,8 +359,76 @@ - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docu/Concepts/BusinessRequirements/image/Ablauf_manuelle_auto_Creations_2.png b/docu/Concepts/BusinessRequirements/image/Ablauf_manuelle_auto_Creations_2.png new file mode 100644 index 000000000..4211f65cf Binary files /dev/null and b/docu/Concepts/BusinessRequirements/image/Ablauf_manuelle_auto_Creations_2.png differ diff --git a/docu/Concepts/BusinessRequirements/image/DB-Diagramm_Contributions_Stufe_2.png b/docu/Concepts/BusinessRequirements/image/DB-Diagramm_Contributions_Stufe_2.png new file mode 100644 index 000000000..eee7fa23f Binary files /dev/null and b/docu/Concepts/BusinessRequirements/image/DB-Diagramm_Contributions_Stufe_2.png differ diff --git a/docu/Concepts/BusinessRequirements/image/UC_Send_Contribution_Admin-new ContributionSend.png b/docu/Concepts/BusinessRequirements/image/UC_Send_Contribution_Admin-new_ContributionSend.png similarity index 100% rename from docu/Concepts/BusinessRequirements/image/UC_Send_Contribution_Admin-new ContributionSend.png rename to docu/Concepts/BusinessRequirements/image/UC_Send_Contribution_Admin-new_ContributionSend.png diff --git a/docu/Concepts/BusinessRequirements/image/UC_Send_Contribution_Admin-new ContributionZyklus.png b/docu/Concepts/BusinessRequirements/image/UC_Send_Contribution_Admin-new_ContributionZyklus.png similarity index 100% rename from docu/Concepts/BusinessRequirements/image/UC_Send_Contribution_Admin-new ContributionZyklus.png rename to docu/Concepts/BusinessRequirements/image/UC_Send_Contribution_Admin-new_ContributionZyklus.png diff --git a/docu/Concepts/TechnicalRequirements/UC_Introduction_of_Gradido-ID.md b/docu/Concepts/TechnicalRequirements/UC_Introduction_of_Gradido-ID.md index 9d607ba97..a6ca83bfc 100644 --- a/docu/Concepts/TechnicalRequirements/UC_Introduction_of_Gradido-ID.md +++ b/docu/Concepts/TechnicalRequirements/UC_Introduction_of_Gradido-ID.md @@ -10,30 +10,27 @@ Additionally the Gradido-ID allows to administrade any user account data like ch The formalized definition of the Gradido-ID can be found in the document [BenutzerVerwaltung#Gradido-ID](../BusinessRequirements/BenutzerVerwaltung#Gradido-ID). -## Steps of Introduction +## 1st Stage -To Introduce the Gradido-ID there are several steps necessary. The first step is to define a proper database schema with additional columns and tables followed by data migration steps to add or initialize the new columns and tables by keeping valid data at all. +The 1st stage of introducing the Gradido-ID contains several steps. The first step is to define a proper database schema with additional columns and tables followed by data migration steps to add or initialize the new columns and tables by keeping valid data at all. -The second step is to decribe all concerning business logic processes, which have to be adapted by introducing the Gradido-ID. +The second step is to decribe all concerning business logic processes, which have to be adapted by introducing the Gradido-ID and handling the attributes of the new user_contacts table. ### Database-Schema #### Users-Table -The entity users has to be changed by adding the following columns. +The entity users has to be changed by adding the following columns. The column State gives a hint about the working state including the ticket number. -| Column | Type | Description | -| ------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------- | -| gradidoID | String | technical unique key of the user as UUID (version 4) | -| alias | String | a business unique key of the user | -| passphraseEncryptionType | int | defines the type of encrypting the passphrase: 1 = email (default), 2 = gradidoID, ... | -| emailID | int | technical foreign key to the entry with type Email and contactChannel=maincontact of the new entity UserContacts | +| State | Column | Type | Description | +| -------------- | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| *done #2125* | gradidoID | String | technical unique key of the user as UUID (version 4) | +| *done #2125* | alias | String | a business unique key of the user | +| *done #2165* | emailID | int | technical foreign key to the UserContacts-Table with the entry of type Email, which will be interpreted as the maincontact from the Users table point of view | ##### Email vs emailID -The existing column `email`, will now be changed to the primary email contact, which will be stored as a contact entry in the new `UserContacts` table. It is necessary to decide if the content of the `email `will be changed to the foreign key `emailID `to the contact entry with the email address or if the email itself will be kept as a denormalized and duplicate value in the `users `table. - -The preferred and proper solution will be to add a new column `Users.emailId `as foreign key to the `UsersContact `entry and delete the `Users.email` column after the migration of the email address in the `UsersContact `table. +The existing column `email`, will now be changed to the primary email contact, which will be stored as a contact entry in the new `UserContacts` table. #### new UserContacts-Table @@ -55,17 +52,21 @@ A new entity `UserContacts `is introduced to store several contacts of different | phone | String | defines the address of a contact entry of type Phone | | contactChannels | String | define the contact channel as comma separated list for which this entry is confirmed by the user e.g. main contact (default), infomail, contracting, advertisings, ... | +##### ToDo: + +The UserContacts, expecially the email contacts, will for future be categorized to communication channels for example to allow the user to define which information he will get on which email-contact (aspects of administration, contract, advertising, etc.) + ### Database-Migration After the adaption of the database schema and to keep valid consistent data, there must be several steps of data migration to initialize the new and changed columns and tables. -#### Initialize GradidoID +#### Initialize GradidoID (done #2125) In a one-time migration create for each entry of the `Users `tabel an unique UUID (version4). -#### Primary Email Contact +#### Primary Email Contact (done #1798) -In a one-time migration read for each entry of the `Users `table the `Users.id` and `Users.email`, select from the table `login_email_opt_in` the entry with the `login_email_opt_in.user_id` = `Users.id` and create a new entry in the `UsersContact `table, by initializing the contact-values with: +In a one-time migration read for each entry of the `Users `table the `Users.id` and `Users.email` and create for it a new entry in the `UserContacts `table, by initializing the contact-values with: * id = new technical key * type = Enum-Email @@ -88,72 +89,130 @@ After this one-time migration and a verification, which ensures that all data ar The following logic or business processes has to be adapted for introducing the Gradido-ID -#### Read-Write Access of Users-Table especially Email +#### Capturing of alias + +To avoid using the email as primary identifier it is necessary to introduce a capturing of the alias. It is not a good solution to create for existing users an individual alias by a migration. So each user should capture his own alias during registration- and/or login-process. + +These requirements are described in the concept document [../BusinessRequirements/UC_Set_UserAlias.md]() **(done #2144)** and the implementation of these requirements will be the prerequisite for changing the login-process from single email-identifier to the future identifiers alias / gradidoID / email. + +#### Read-Write Access of Users-Table especially Email (done #1798) The ORM mapping has to be adapted to the changed and new database schema. -#### Registration Process +#### Create and Update User Processes -The logic of the registration process has to be adapted by +The logic of the create and update user process has to be adapted by -* initializing the `Users.userID` with a unique UUID -* creating a new `UsersContact `entry with the given email address and *maincontact* as `usedChannel ` -* set `emailID `in the `Users `table as foreign key to the new `UsersContact `entry -* set `Users.passphraseEncrpytionType = 2` and encrypt the passphrase with the `Users.userID` instead of the `UsersContact.email` +* creating a new User including with a unique UUID-V4 **(done #2125)** +* creating a new `UserContacts `entry with the given email address **(#2165)** +* set `emailID `in the `Users `table as foreign key to the new `UserContacts `entry **(#2165)** +* handling the new emailXXX attributes in the `user_contacts `table previously in the `email_opt_in `table **(#2165)** -#### Login Process +#### Search User Processes (#2165) -The logic of the login process has to be adapted by +The logic of all processes where the user is searched has to be adapted by -* search the users data by reading the `Users `and the `UsersContact` table with the email (or alias as soon as the user can maintain his profil with an alias) as input -* depending on the `Users.passphraseEncryptionType` decrypt the stored password - * = 1 : with the email - * = 2 : with the userID +* always search a *user* with its relation "emailContact" to load the associated userContact with his email +* a search user by *email* has to be implemented by searching a `userContact `for the given *email* and its relation "user" to load the associated user to this email + +#### Password Processes (#2165) + +The logic of all password processes has to be adapted by + +* read the *emailXXX* attributes out of the `user_contacts `table instead of previoulsy from the `email_opt_in `table +* writing or updating the *emailXXX* attributes now in the `user_contact `table instead of previously in the `email_opt_in `table +* the logic how to de/encrypt the password will not part of this 1st stage of introduction of the gradidoID. This will be part of the 2nd stage + +## 2nd Stage + +In the 2nd stage of this topic the password handling during registration and login process will be changed. These change must keep the current active password handling where the email is part of the encryption as long as all users are shifted to the new logic of password handling where the gradidoID will part of the encryption. This means there must be a kind of versioning which type of password encryption is used. Because some users will not login for a long time, which causes to use the old password encryption at their login process or in the future there could be the requirement to change the password handling to newer and safer algorithms. + +### Database-Schema + +#### Users-Table + +The entity *users* has to be changed by + +| Action | Column | Type | Description | +| :----: | ---------------------- | ---------- | ----------------------------------------------------------------------------------- | +| add | passwordEncryptionType | int | defines the type of encrypting the password: default 1 = email, 2 = gradidoID, ... | +| delete | public_key | binary(32) | before deletion verify and ensure that realy not in use even for encryption type 1 | +| delete | privkey | binary(80) | before deletion verify and ensure that realy not in use even for encryption type 1 | +| delete | email_hash | binary(32) | before deletion verify and ensure that realy not in use even for encryption type 1 | +| delete | passphrase | text | before deletion verify and ensure that realy not in use even for encryption type 1 | + +### Adaption of BusinessLogic #### Password En/Decryption -The logic of the password en/decryption has to be adapted by encapsulate the logic to be controlled with an input parameter. The input parameter can be the email or the userID. +The logic of the existing password en/decryption has to be shifted out of the ***UserResolver.js*** file in separated file(s). This separated file will be placed in the package-directory `backend/src/password` and named ***emailEncryptor.js***. As the name express the password encryption uses the `email `attribute. + +For the new password encryption logic a new file named ***gradidoIDEncryptor.js*** has to be created in the package-directory `backend/src/password`, which uses the *gradidoID* instead of the *email* for the password encryption. As soon as a user is changed to this encryption type with the *gradidoID*, it will be possible for him to change his *email* in his gradido-profile without any effect on his password encryption. + +For possible future requirements of newer and safer encryption logic additional files can be placed in the same directory with an expressiv file name for the new encryption type. + +All these `xxxEncryptor `files has to implement the following API, but with possibly different parameter types, depending on the encryption requirements: + +| API | emailEncryptor | gradidoIDEncryptor | return | description | +| ------------------------- | ---------------- | ------------------ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| **encryptPassword** | dbUser, password | dbUser, password | encrypted password | process the encryption with
the encryptor specific attributs
out of the dbUser and the original 
password entered by the user | +| **verifyPassword** | dbUser, password | dbUser, password | boolean | process the decryption with
the encryptor specific attributs
out of the dbUser and the original
password entrered by the user | +| **isPassword** | password | password | boolean | verifiy the formal rules of the original
password entered by the user | + +Which of the *xxxEncryptor* implementations will be used, depends on the value of the attribute `user.passwordEncryptionType`, which has to be interpreted before. To encapsulate this logic from the general business logic the ***Encryptor.js*** will be created with the same API as the specific *encryptor* classes, but it will interpret the attribute `dbUser.passwordEncryptionType` to select and invoke the correct *encryptor* implementation and to decide if an upgrade to a newer *encryptor* class should be done. + +The new Enum `PasswordEncryptionType `with the increasing values: + +* 1 = emailEncryptor +* 2 = gradidoIDEncryptor +* ... = ? + +will be used to define the order, which encryptor implementation is the oldest and the newest. That means if a user is still not using the newest *encryptor* for his password encryption the logic will implicit start a change to the newest *encryptor*. In all business processes, where the user enters his password the invokation of the ***Encryptor.js*** has to be introduced, because without the original entered password from the user no *encryptor* upgrade can be done. + +#### Registration Process + +The backend logic of the registration process has to be adapted + +* the ***UserResolver.createUser*** logic has to be changed by setting for a new user the attribut `Users.passwordEncrpytionType = 2` +* As soon as the user activates the email-confirmation link `https://gradido.net/checkEmail/` the application frontend invokes + + * at first the ***UserResolver.queryOptIn*** method, which will not be necessary, because the same checks about the given *emailOptIn*-code will be done a 2nd time in the invocation of *UserResolver.setPassword* + * at second the ***UserResolver.setPassword*** method, which has to be changed + * to use the new ***Encryptor.isPassword*** to validate the formal rules of the given password + * to remove all cryptographic logic like passphrase and key pair generation and password hashing to the new ***emailEncryptor.js*** + * to introduce the invocation of the new ***Encryptor.encryptPassword*** in the existing logic flow + +#### Login Process + +The logic of the login process has to be adapted in frontend and backend + +* Frontend + * The login dialog has to be changed at the email input component + * the new label contains "Email / Alias / GradidoID" + * the validation of the input field has to be changed to accept the input of one of these three possible values + * in case of failed validation an expressiv error message for the specific given input has to be shown (for more details about the rules for alias and gradidoID see the concepts [UC_SetUserAlias.md](../BusinessRequirements/UC_SetUserAlias.md) and [BenutzerVerwaltung#Gradido-ID](../BusinessRequirements/BenutzerVerwaltung#Gradido-ID)). + * The signature of the backend invocation ***UserResolver.login*** has to be changed to accept all three variants of identifiers + * depending on the implemented backend solution the frontend has to detect and initialize the correct parameter settings +* Backend + * The signature of the backend invocation ***UserResolver.login*** has to be changed to accept all three variants of identifiers + * solution-A: the first parameter *email* is renamed to *identifier* and the backend has to detect which type of identifier is given + * solution-B: two additional parameters *alias* and *gradidoID* are inserted in the type ***UnsecureLoginArgs*** and the frontend has to decide, which type of identifier is given and initialize the correct parameter + * **TODO**: solution-A is preferred? + * The logic of ***UserResolver.login*** has to be changed by + * in case of solution-A for the signature, the given identifier has to be detected for the correct user searching + * the user to be searched by the given identifier (email / alias / gradidoID) + * if a user could be found all the existing checks will be done as is, except the public and private key check, which will be removed + * for the password check the new ***Encryptor.isPassword*** and ***Encryptor.verifyPassword*** has to be invoked; all existing cryptographic logic has to be deleted #### Change Password Process -The logic of change password has to be adapted by +There are two ways to change a user password. -* if the `Users.passphraseEncryptionType` = 1, then +The first one is the *Forget-Password process*, which will use the same backend invocation with activating the email link like the *Registration Process* to set the password; for details see description above. - * read the users email address from the `UsersContact `table - * give the email address as input for the password decryption of the existing password - * use the `Users.userID` as input for the password encryption for the new password - * change the `Users.passphraseEnrycptionType` to the new value =2 -* if the `Users.passphraseEncryptionType` = 2, then +The second one is the *Update-Userinfo process*, which invokes the ***UserResolver.updateUserInfos***. This method has to be changed in the *password check block* by - * give the `Users.userID` as input for the password decryption of the existing password - * use the `Users.userID` as input for the password encryption fo the new password - -#### Search- and Access Logic - -A new logic has to be introduced to search the user identity per different input values. That means searching the user data must be possible by - -* searching per email (only with maincontact as contactchannel) -* searching per userID -* searching per alias - -#### Identity-Mapping - -A new mapping logic will be necessary to allow using unmigrated APIs like GDT-servers api. So it must be possible to give this identity-mapping logic the following input to get the respective output: - -* email -> userID -* email -> gradidoID -* email -> alias -* userID -> gradidoID -* userID -> email -* userID -> alias -* alias -> gradidoID -* alias -> email -* alias -> userID -* gradidoID -> email -* gradidoID -> userID -* gradidoID -> alias - -#### GDT-Access - -To use the GDT-servers api the used identifier for GDT has to be switch from email to userID. +* removing all the cryptographic logic and +* invoke the new ***Encryptor.isPassword*** for the given *newPassword* and if valid then +* invoke the new ***Encryptor.verifyPassword*** for the given *oldPassword* and if valid then +* invoke the new ***Encryptor.encryptPassword*** for the given *newPassword*