update doc

doc/auth.md

@@ -0,0 +1,106 @@
+# Authentification et frontend users
+
+L'extension [OtConnect](/ot_connect) se positionne en amont des services d'authentification Typo3 et utilise l'API Opentalent.
+En somme, un utilisateur connecté sur Opentalent.fr le sera aussi sur le ou les autres sous-domaines TYPO3
+(correspondant à ses structures et à ses droits)
+
+> **Important**: ce système d'authentification ne concerne pour l'instant que les front-end users
+
+## Fonctionnement de l'authentification TYPO3
+
+### Service d'authentification
+
+Pour authentifier un utilisateur, TYPO3 exécute des services par ordre de priorité, jusqu'à ce qu'un de ces services valident l'identité
+de l'utilisateur. Si aucun des services ne valident cette authentification, celle-ci est rejetée.
+
+### Création et enregistrement d'un service d'authentification
+
+Un service d'authentification doit hériter de la classe `TYPO3\CMS\Sv\AbstractAuthenticationService`, et implémenter au moins deux méthodes:
+
+* `getUser` vérifie qu'un utilisateur portant ce nom existe en base et retourne ses informations, ou retourne false en cas d'echec.
+* `authUser` vérifie que l'utilisateur est authentifié. La méthode retourne un code indiquant le résultat:
+    * 0 signifie que l'authentification a échoué et que le process d'authentif doit s'arrêter là
+    * 100 signifie que l'authentification a échoué, mais que les services suivants peuvent essayer à leur tour d'authentifier le user
+    * 200 signifie que l'authentification a réussi
+
+De plus, le service doit être enregistré dans `ext_localconf.php` via la méthode `\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addService`.
+A cette étape, on peut lui donner des rôles (authentification backend et/ou frontend, par exemple).
+
+> **IMPORTANT** : quelle que soit la méthode d'authentification, les users backend et frontend
+>doivent avoir leurs enregistrements dans la base TYPO3 (tables `fe_users` et `be_users`)
+
+### Requêtes d'authentification
+
+Typo3 reconnait une requête d'authentification de la manière suivante :
+
+* La requête a un paramètre `logintype` dont la valeur est `login`: c'est une requête d'authentification Frontend
+* La requête a un paramètre `login_status` dont la valeur est `login`: c'est une requête d'authentification Backend
+
+Voilà les formulaires minimaux pour poster une demande d'authentification :
+
+    <-- FrontEnd -->
+    <form action="" method="POST" enctype="multipart/form-data" >
+        <input type="hidden" name="logintype" value="login" />
+        <input type="text" placeholder="Nom d'utilisateur" name="user" required="1" />
+        <input type="password" name="pass" placeholder="Mot de passe" required="1" />
+        <input type="submit" value="Se connecter" />
+    </form>
+
+    <-- BackEnd -->
+    <form action="" method="POST" enctype="multipart/form-data" >
+        <input type="hidden" name="login_status" value="login" />
+        <input type="text" placeholder="Nom d'utilisateur" name="username" required="1" />
+        <input type="password" name="password" placeholder="Mot de passe" required="1" />
+        <input type="submit" value="Se connecter" />
+    </form>
+
+> Côté Frontend, Typo3 attend deux champs dont les attributs 'name' sont 'user' et 'pass'.
+
+### Base de données
+
+Les utilisateurs **Backend** doivent avoir une ligne correspondante dans la table `be_users` de la base TYPO3.
+Ils doivent avoir a minima les champs suivants renseignés :
+
+* `username`
+* `password`: si le mot de passe n'est pas utilisé pour authentifier l'utilisateur,
+  par exemple parce qu'une API l'a déjà authentifié en amont, mettre une random string
+* `usergroup`: le user doit appartenir à un groupe existant (cf. `be_groups`), sauf s'il est admin (champs `admin` = 1)
+
+Les utilisateurs **Frontend** doivent avoir une ligne correspondante dans la table `fe_users` de la base TYPO3.
+Ils doivent avoir a minima les champs suivants renseignés :
+
+* `username`
+* `password` : si le mot de passe n'est pas utilisé pour authentifier l'utilisateur,
+  par exemple parce qu'une API l'a déjà authentifié en amont, mettre une random string
+* `usergroup` : le user doit appartenir à un groupe existant (cf. `be_groups`)
+
+### Plus d'infos
+
+> [Voir la doc officielle](https://docs.typo3.org/m/typo3/reference-coreapi/master/en-us/ApiOverview/Authentication/Index.html)
+
+
+## Fonctionnement de l'extension OtConnect
+
+Un service `OtAuthenticationService` est créé et enregistré avec les caractéristiques suivantes :
+
+* `'subtype' => 'getUserFE,authUserFE,getUserBE,authUserBE'` : le service peut récupérer les infos des users
+  et les authentifier, à la fois pour le Frontend (FE) et pour le Backend (BE)
+* `'priority' => 80`: la priorité est fixée à 80, ce qui place le service en amont des services Typo3.
+
+Enfin, la variable de configuration `FE_fetchUserIfNoSession` force l'appel à la méthode getUser à chaque affichage d'une page frontEnd si une session n'existe pas déjà.
+(sans ça, l'utilisateur doit passer par la page de login même s'il a déjà une session opentalent.fr ouverte)
+
+Voilà les différents scénarios pour un utilisateur nommé Bob.
+
+> Les cas suivants sont donnés pour le Frontend, mais ils sont identiques pour le Backend à deux différences près :
+> * Le user doit saisir son login / mdp (pas d'auto-log)
+> * Seuls les utilisateurs ayant la propriété `admin_access` à true ont accès au Backend.
+
+| Num. | Cas | Comportement |
+| --- | --- | --- |
+| 1 | Bob a une session Typo3-FE existante dans son navigateur (cf. cookie `fe_typo_user`) | Le service n'est pas appelé, Bob est déjà connecté |
+| 2 | Bob n'a pas de session Typo3 ouverte, mais il a une session ouverte dans son navigateur sur Opentalent.fr (cf. cookies `BEARER` et `SFSESSID`) | Une requête GET `/isauthenticated` est envoyée à l'API Opentalent. En cas de succès, une nouvelle requête est envoyée à l'API pour obtenir les données à jour de l'utilisateur, puis la ligne de Bob est créee ou mise à jour dans la table `fe_users` de la base Typo3 (sauf si cette mise à jour a déjà été faite dans les dernières minutes, voir const USER_UPDATE_DELAY) |
+| 3 | Bob n'a ni session Typo3-FE ni session Opentalent.fr ouverte, mais il a envoyé une requête de login valide | Ses données d'authentif sont envoyées à l'API qui lui ouvre une session. La suite se déroule comme pour le cas n°2 |
+| 4 | Bob n'a ni session Typo3-FE ni session Opentalent.fr ouverte, mais il a envoyé une requête de login invalide | Ses données d'authentif sont envoyées à l'API qui essaie de lui ouvrir une session et retourne un code d'echec. Le service, constatant qu'il s'agit tout de même d'un compte Opentalent, s'interrompt et refuse l'accès à Bob (qui pleure) |
+| 5 | Bob se connecte en utilisant un compte créé dans Typo3 ou via un autre service d'authentification (ce compte n'existe donc pas dans la base Opentalent)  | Ses données d'authentif sont envoyées à l'API qui essaie de lui ouvrir une session et retourne un code d'echec. Le service passe la main aux services Typo3 suivants par ordre de priorité |
+

doc/ci.md

@@ -0,0 +1 @@
+# Intégration et déploiement continu

doc/db.md

@@ -0,0 +1,85 @@
+# Comprendre la DB Typo3
+
+Voici les principales tables sur lesquelles on est amené à intervenir. Toutes les autres tables sont soient
+rendues inutiles par le fonctionnement spécifiques de l'instance Opentalent (comme `sys_domain`), ou ne nécessitent
+quasiment jamais d'intervention manuelles.
+
+
+## Règles générales
+
+Toutes les tables ont pour clé primaire un champs `uid`.
+
+La majorité des tables définissent un champ `pid`, pour "parent id". C'est l'uid de l'objet parent, par exemple
+la page qui le contient pour contenu.
+
+La majorité des tables définissent un champ `deleted`. Par défaut, le QueryBuilder typo3 ignorera de lui-même 
+les champs dont ce champ est à 1.
+
+
+## La table `pages`
+
+La table `pages` contient un enregistrement pour chaque page d'un site.
+Un champs spécifique Opentalent (`ot_website_uid`) permet de faire le lien entre une page et son site.
+
+Chaque site est constitué d'une page racine (`is_siteroot=1`). Ensuite l'arborescence des pages du site est 
+définie par l'intermédiaire du champs pid, le pid d'une page étant l'uid de sa page parente.
+
+Le champs `dokType` définit le type d'une page (standard, raccourci, dossier...). Une page standard a pour dokType 1. 
+
+Le champs `slug` est responsable du routing à l'intérieur du site.
+
+
+## La table `ot_websites`
+
+> Voir [le chapitre dédié](ot_websites.md)
+
+## La table `tt_content`
+
+La table `tt_content` contient un enregistrement pour chaque contenu d'une page.
+
+Le champs `pid` correspond à l'uid de la page qui le contient.
+
+Le type de contenu est défini par le champs `CType`
+
+Le corps du contenu est défini par le champs `bodytext`
+
+
+## Les tables `fe_users` et `fe_groups`
+
+La table `fe_users` contient un enregistrement pour chaque frontend user.
+
+Ces enregistrements sont générés automatiquement via l'extension [OtConnect](/ot_connect).
+
+> Plus d'info [ici](auth.md)
+
+Chaque fe_user peut être affecté à un ou plusieurs fe_group par l'intermédiaire du champs `usergroup` (plusieurs valeurs
+possibles en séparant les uids avec une virgule)
+
+Les groupes sont lié à un site par l'intermédiaire du champs `pid`, qui contient l'uid de la page racine du site
+auquel le groupe est lié.
+
+## La table `be_users` et `be_groups`
+
+La table `be_users` contient un enregistrement pour chaque backend user.
+
+Chaque be_user peut être affecté à un ou plusieurs be_group par l'intermédiaire du champs `usergroup` (plusieurs valeurs
+possibles en séparant les uids avec une virgule)
+
+> Plus d'infos [ici](be_users.md)
+
+## Les tables `sys_file` et `sys_file_reference`
+
+
+Chaque fichier uploadé depuis le backend a un enregistrement correspondant dans la table `sys_file`.
+
+C'est ensuite la table `sys_file_reference` qui fait le lien entre cette table et la table étrangère qui référence ce 
+fichier (pages, tt_content...)
+
+La table ciblée et la clé étrangère sont indiquées par les champs `tablenames` et `uid_foreign` de la table `sys_file_reference`, 
+tandis que l'id du fichier dans `sys_file` est contenu dans le champs `uid_local`
+
+
+## Les tables `sys_log` et `ot_log`
+
+Les tables `sys_log` et `ot_log` contiennent les logs typo3 pour la première, et spécifiques aux extensions 
+Opentalent pour la seconde.

doc/dependencies.md

@@ -0,0 +1,17 @@
+# Extensions tierces et dépendances
+
+L'instance Typo3 installée dépend essentiellement des extensions et librairies suivantes:
+
+## Extensions Typo3
+
+### Fluid
+### VHS
+### Flux
+### News
+
+## Autres dépendances
+
+### SCSS
+### JQuery
+### Openstreetmap
+### Matomo

doc/hooks.md

@@ -0,0 +1 @@
+# Déclenchement des hooks de mise à jour depuis le logiciel

doc/maintenance.md

@@ -0,0 +1,2 @@
+# Opérations de maintenance et scheduler
+

doc/ot_websites.md

@@ -0,0 +1,14 @@
+# La table ot_website
+
+La table `ot_websites`, spécifique à l'instance Typo3 Opentalent, est ajoutée à la base de données par l'extension
+[ot_core](/ot_core).
+
+Cette table est centrale dans le fonctionnement des extensions Opentalent, car c'est elle qui recense les sites des 
+strucures, leurs paramètres, domaines, statuts...
+
+## La variable globale ot_website
+
+## Le rôle de la table dans le routing
+
+## La génération dynamique de la configuration du site
+

doc/readme.md

@@ -108,6 +108,6 @@ Plus d'infos [ici](dependencies.md).
 
 -------------------------
 
-Et si vous avez lu jusqu'ici, vous avez bien mérité un cookie:
+Et si vous avez lu jusqu'ici, vous avez mérité un cookie:
 
 ![cookie](images/cookie.png)

doc/routing.md

@@ -22,7 +22,7 @@ Lors des accès suivants, ces configurations sont en cache, ce qui réduit l'imp
 
 Cependant, le router instancie tous les sites avant de faire finalement correspondre le domaine utilisé dans la requête à l'uid de la page racine d'un site.
 
-[blackfire_1](images/routing_blackfire_1.png)
+![blackfire_1](images/routing_blackfire_1.png)
 
 
 ### La résolution du chemin
@@ -87,7 +87,7 @@ En mode développement (sur preprod ou en local), les urls ne sont pas construit
 
 | Prod | Dev |
 | --- | --- |
-| <subdomain>.opentalent.fr | host.opentalent.fr/<subdomain> |
+| `<subdomain>.opentalent.fr` | `host.opentalent.fr/<subdomain> |
 
  
 

doc/social_networks.md

@@ -0,0 +1 @@
+# Intégration des réseaux sociaux

doc/stats.md

@@ -0,0 +1,2 @@
+# Fonctionnement du suivi des stats d'utilisation des sites
+

doc/templating.md

@@ -0,0 +1,2 @@
+# Fonctionnement du multi-templating
+

doc/tests.md

@@ -0,0 +1 @@
+# Tests automatisés

ot_connect/Readme.md

@@ -10,105 +10,5 @@ Extension d'authentification typo3.
 
 Le rôle de cette extension est de fournir une authentification et une session unique pour les utilisateurs Opentalent, 
 qu'ils se rendent sur l'application Opentalent ou sur le frontend du site de leur(s) structure(s).
-**L'authentification backend n'est pour l'instant pas concernée.**
-OtConnect se positionne en amont des services d'authentification Typo3 et utilise l'API Opentalent.
-En somme, un utilisateur connecté sur Opentalent.fr le sera aussi sur le ou les autres sous-domaines TYPO3 
-(correspondant à ses structures et à ses droits)
 
-## Fonctionnement de l'authentification TYPO3
-
-### Service d'authentification
-
-Pour authentifier un utilisateur, TYPO3 exécute des services par ordre de priorité, jusqu'à ce qu'un de ces services valident l'identité
-de l'utilisateur. Si aucun des services ne valident cette authentification, celle-ci est rejetée.
-
-### Création et enregistrement d'un service d'authentification
-
-Un service d'authentification doit hériter de la classe `TYPO3\CMS\Sv\AbstractAuthenticationService`, et implémenter au moins deux méthodes:
-
-* `getUser` vérifie qu'un utilisateur portant ce nom existe en base et retourne ses informations, ou retourne false en cas d'echec.
-* `authUser` vérifie que l'utilisateur est authentifié. La méthode retourne un code indiquant le résultat: 
-  * 0 signifie que l'authentification a échoué et que le process d'authentif doit s'arrêter là
-  * 100 signifie que l'authentification a échoué, mais que les services suivants peuvent essayer à leur tour d'authentifier le user
-  * 200 signifie que l'authentification a réussi
-
-De plus, le service doit être enregistré dans `ext_localconf.php` via la méthode `\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addService`.
-A cette étape, on peut lui donner des rôles (authentification backend et/ou frontend, par exemple).
-
-> **IMPORTANT** : quelle que soit la méthode d'authentification, les users backend et frontend 
->doivent avoir leurs enregistrements dans la base TYPO3 (tables `fe_users` et `be_users`)
-
-### Requêtes d'authentification
-
-Typo3 reconnait une requête d'authentification de la manière suivante :
-
-* La requête a un paramètre `logintype` dont la valeur est `login`: c'est une requête d'authentification Frontend
-* La requête a un paramètre `login_status` dont la valeur est `login`: c'est une requête d'authentification Backend
-
-Voilà les formulaires minimaux pour poster une demande d'authentification :
-
-    <-- FrontEnd -->
-    <form action="" method="POST" enctype="multipart/form-data" >
-        <input type="hidden" name="logintype" value="login" />
-        <input type="text" placeholder="Nom d'utilisateur" name="user" required="1" />
-        <input type="password" name="pass" placeholder="Mot de passe" required="1" />
-        <input type="submit" value="Se connecter" />
-    </form>
-
-    <-- BackEnd -->
-    <form action="" method="POST" enctype="multipart/form-data" >
-        <input type="hidden" name="login_status" value="login" />
-        <input type="text" placeholder="Nom d'utilisateur" name="username" required="1" />
-        <input type="password" name="password" placeholder="Mot de passe" required="1" />
-        <input type="submit" value="Se connecter" />
-    </form>
-
-> Côté Frontend, Typo3 attend deux champs dont les attributs 'name' sont 'user' et 'pass'. 
-
-### Base de données
-
-Les utilisateurs **Backend** doivent avoir une ligne correspondante dans la table `be_users` de la base TYPO3.
-Ils doivent avoir a minima les champs suivants renseignés : 
-
-* `username`
-* `password`: si le mot de passe n'est pas utilisé pour authentifier l'utilisateur, 
-par exemple parce qu'une API l'a déjà authentifié en amont, mettre une random string
-* `usergroup`: le user doit appartenir à un groupe existant (cf. `be_groups`), sauf s'il est admin (champs `admin` = 1)
-
-Les utilisateurs **Frontend** doivent avoir une ligne correspondante dans la table `fe_users` de la base TYPO3.
-Ils doivent avoir a minima les champs suivants renseignés : 
-
-* `username`
-* `password` : si le mot de passe n'est pas utilisé pour authentifier l'utilisateur, 
-par exemple parce qu'une API l'a déjà authentifié en amont, mettre une random string
-* `usergroup` : le user doit appartenir à un groupe existant (cf. `be_groups`)
-
-### Plus d'infos
-
-> [Voir la doc officielle](https://docs.typo3.org/m/typo3/reference-coreapi/master/en-us/ApiOverview/Authentication/Index.html)
-
-
-## Fonctionnement de l'extension OtConnect
-
-Un service `OtAuthenticationService` est créé et enregistré avec les caractéristiques suivantes :
- 
-* `'subtype' => 'getUserFE,authUserFE,getUserBE,authUserBE'` : le service peut récupérer les infos des users 
-et les authentifier, à la fois pour le Frontend (FE) et pour le Backend (BE)
-* `'priority' => 80`: la priorité est fixée à 80, ce qui place le service en amont des services Typo3.
-
-Enfin, la variable de configuration `FE_fetchUserIfNoSession` force l'appel à la méthode getUser à chaque affichage d'une page frontEnd si une session n'existe pas déjà.
-(sans ça, l'utilisateur doit passer par la page de login même s'il a déjà une session opentalent.fr ouverte)
-
-Voilà les différents scénarios pour un utilisateur nommé Bob. 
-
-> Les cas suivants sont donnés pour le Frontend, mais ils sont identiques pour le Backend à deux différences près :
-> * Le user doit saisir son login / mdp (pas d'auto-log)
-> * Seuls les utilisateurs ayant la propriété `admin_access` à true ont accès au Backend.
-
-| Num. | Cas | Comportement |
-| --- | --- | --- |
-| 1 | Bob a une session Typo3-FE existante dans son navigateur (cf. cookie `fe_typo_user`) | Le service n'est pas appelé, Bob est déjà connecté |
-| 2 | Bob n'a pas de session Typo3 ouverte, mais il a une session ouverte dans son navigateur sur Opentalent.fr (cf. cookies `BEARER` et `SFSESSID`) | Une requête GET `/isauthenticated` est envoyée à l'API Opentalent. En cas de succès, une nouvelle requête est envoyée à l'API pour obtenir les données à jour de l'utilisateur, puis la ligne de Bob est créee ou mise à jour dans la table `fe_users` de la base Typo3 (sauf si cette mise à jour a déjà été faite dans les dernières minutes, voir const USER_UPDATE_DELAY) |
-| 3 | Bob n'a ni session Typo3-FE ni session Opentalent.fr ouverte, mais il a envoyé une requête de login valide | Ses données d'authentif sont envoyées à l'API qui lui ouvre une session. La suite se déroule comme pour le cas n°2 |
-| 4 | Bob n'a ni session Typo3-FE ni session Opentalent.fr ouverte, mais il a envoyé une requête de login invalide | Ses données d'authentif sont envoyées à l'API qui essaie de lui ouvrir une session et retourne un code d'echec. Le service, constatant qu'il s'agit tout de même d'un compte Opentalent, s'interrompt et refuse l'accès à Bob (qui pleure) |
-| 5 | Bob se connecte en utilisant un compte créé dans Typo3 ou via un autre service d'authentification (ce compte n'existe donc pas dans la base Opentalent)  | Ses données d'authentif sont envoyées à l'API qui essaie de lui ouvrir une session et retourne un code d'echec. Le service passe la main aux services Typo3 suivants par ordre de priorité |
+> Plus d'infos dans la [documentation](/doc/auth.md)