# Cahier des charges front end

Réalisation d'une webapp pour la plateforme Wannup.

Organisation en 3 phases de développement, à chiffrer séparément.
- Développement des composants génériques.
- Développement du socle de la webapp.
- Développement des écrans.

La partie "en option" est à mettre en option dans le devis, car moins prioritaire et ne doit pas repousser la deadline.

Deadline finale (prenant en compte la phase de recette et modifications): au plus tard le 15 Novembre 2021.

En annexe de ce cahier des charges:
- Les wireframes
- Les maquettes des écrans
- Les spécifications des modules

## Présentation du projet

Wannup est une plateforme de création de jeu Urban gaming permettant à un professionnel de créer un jeu sous forme visuelle (nodale).
Ces jeux se présentent sous forme de web app. Le joueur effectue un parcours dans un lieu tout en complétant des challenges lui permettant d'avancer dans l'histoire. Ces challenges sont des mini-jeux de plusieurs types (quiz, trouver une image, un lieu, ...), lui donnant l'impression de faire partie de l'histoire.

Le projet se repose sur 3 briques techniques principales :
- Un éditeur : Outil pour de la création / édition de jeu
- Une runtime : moteur d'execution du jeu
- Une application web : interface entre le joueur et le jeu (runtime)

## Web app

La webapp est une application react "mobile first" ("only" pour le moment) permettant au joueur d'interagir avec le jeu. Le fonctionnement du jeu se repose entièrement sur la runtime, la webapp étant uniquement l'interface. L'application web communique seulement avec la runtime (par le biais de la runtime-api) et adaptera les écrans sur base des réponses de celle-ci.

Celle-ci doit fonctionner sur tous les navigateurs mobiles.

### Quelques concepts

- **noeud**: un noeud correspond à la partie "game" d'un module. Il est le pendant de la partie "front" qui est l'objet de cette prestation.
- **module**: Un module est un ensemble de fonctionnalités qui tire parti de la modularité de la plate-forme. Par exemple, il n'est pas nécessaire de modifier le code source de la plateforme pour ajouter des modules permettant à un joueur de voir un quizz. Un module doit fonctionner indépendamment des autres. Il est composé de 3 parties différentes :
- **La partie "front"**: Les écrans et les éléments de l'interface utilisateur affichés par l'application web.
- **La partie "node"**: Une brique de conception de jeu ou "nœud", utilisée pour concevoir le jeu (édition et logique de jeu).
- **La partie "content"**: Un contenu configurable qui est traduisible et peut contenir des médias.
- **écran**: la partie "front" d'un module peut contenir (généralement) un ou (rarement) plusieurs écrans qui vont être la partie visible du module.
- **gamestate**: état du jeu pour un joueur. Le gamestate est géré par la runtime. A chaque réponse de la runtime-api, le contenu du module sera renvoyé avec son *module-state*, c'est à dire le morceau de gamestate qui lui correspond, permettant d'afficher l'état actuel du jeu.
- **runtime-api**: c'est une REST api (composée de 2 routes) qui permet de communiquer avec la runtime. C'est l'unique point de communication de la webapp.

### Structure du projet

La plateforme est gérée sous la forme d'un monorepo, avec lerna et yarn workspaces.

Chaque module est implémenté sous forme de package, chaque package doit déclarer des scripts de *start* et *build*.

La structure des dossiers se présente sous la forme :

- **WebApp** : code de la web app
- **PreviewApp** : Application de prévisualisation de jeu (hors scope de la prestation)
- **Components** : Composants génériques et composants dits "de base".
- **Modules** : Modules de jeu, organisés en package npm.
├── VideoModule
├── ContentModule
└── ...

La documentation interne du projet sera fournie.

### CSS, theming et configuration des composants

Les composants doivent être découpés de façon à être testable facilement, il doivent être configurés et documentés pour être testés depuis [Storybook](https://storybook.js.org/).

Il doivent être conçus dans une version visuelle minimaliste d'abord (hors thème), puis être à la suite customisé à partir du thème des maquettes fournies (thème "européen").

## Architecture de l'application

### La couche de base

#### Mise en place de l'application et outils dépendants

- React
- Storybook
- Api Matomo
- Map : [leaflet](https://react-leaflet.js.org/) *à valider*
- *Autres à définir*

#### Controller d'application

Mise en place des éléments de base de l'application incluant :

- Client-Api permettant à l'application d'interagir avec la runtime-api en se basant sur les interfaces de celle-ci (interface typescript partagé)
- App controller permettant l'initialisation de la session de jeu et la synchronisation de l'état visuel de l'app avec la runtime [TODO: add doc link]
- Mise en place de la navigation se reposant sur le système de routage en phase avec l'app controller.

#### Socle graphique

Développement des composants et hooks clés permettant le fonctionnement de l'application et de l'intégration des écrans:

- Système d'écran
- Système de transition
- Système de theming

#### API de tracking

Intégration de l'API de tracking matomo pour suivre les actions utilisateurs dans l'application.

### Composants génériques

Implémentation des composants génériques de l'application, hors de leur cadre d'utilisation dans les modules.
*(Un seul package pour l'ensemble des composants génériques.)*

#### Composants de navigation d'input et d'information

- Bouton
- Bar de navigation
- Set d'icones
- Notification
- Text input

#### Composants de contenu

- Rich text content : **!! Attention, le contenu peut également contenir des images**
- Player vimeo
- Image
- Titre / Bannière

#### Composant map

Integration d'un composant map se reposant sur une librairie ou composant existant permettant :
- l'affichage de markeur, tracé, infobulle
- l'utilisation de la geolocalisation (+ gestion des permissions browser)
- assurant une compatibilité avec le schéma de donnée POI utilisé par l'application

### Ecrans de modules

Intégration des écrans de modules et implémentation des composants spécifiques à ces modules.

Chaque écran et composant doit fonctionner avec un thème par défaut (se rapprochant de celui de bootstrap et des wireframes fournies).
Ils doivent pouvoir être themeable, c'est à dire stylisés par des thèms séparés.
Un thème (le thème "européen") visible dans les maquettes est à faire dans la prestation.

#### Ecrans des modules applicatifs

**Ecran d'intro**
Ecran d'intro de l'application

**Choix de langue**
Ecran permettant de choisir la langue (selection de la langue donnée par la runtime ou celle du navigateur par défaut).

**Ecrans de choix des cookies**
Ecrans d'options permettant de valider l'utilisation de cookies, découpé en 2 écrans:
- Ecran de texte 'privacy policy' + choix du mode cookie.
- Ecran optionnel d'activation de cookies spécifiques.

**Permissions du navigateur**
Ecran d'options permettant l'activation de la gélocalisation et de la caméra du navigateur.

**Ecran de sauvegarde**
Ecran spécifique lié à la sauvegarde de la progression, permettant à l'utilisateur d'entrer son adresse email afin qu'il puisse recevoir un email avec un lien spécial.

**Ecran de partage**
Ecran permettant de partager sur les réseaux sociaux un texte générique concernant le jeu en cours, via les liens de partage direct de chaque réseaux sociaux (pas d'intégration inapp)

**Insription à la newsletter**
Ecran d'inscription à une newsletter permettant de s'y inscrire et / ou de passer à l'étape suivante

#### Ecrans des modules de jeu

Les modules reposent sur la même base que les modules applicatifs.

Ils intègrent en plus la notion de *sub theme*, permettant de créer des variantes d'affichage d'un thème pour le module en question(ex section-screen).

Ce subtheme sera sous la forme d'une classe css spécifique injectée dans le container de l'écran.

Afin de faciliter la lisibilité du code et la refactorisation de certains composants, il est important de garder une séparation claire entre les écrans et les composants.
Un écran est un contenant, ne faisant que le lien entre la runtime-api et les composants de l'application.
Il faudra utiliser au maximum les composants génériques développés plus haut. De plus, les composants ne doivent être ni trop gros, ni trop petits (granularité moyenne).

**Ecran de contenu**
Ecran permettant l'affichage de contenu (Rich Text) sous 3 formes, en fonction des données reçues:

- contenu
- contenu + titre
- titre

**Fullscreen image**

Ecran de contenu permettant l'affichage d'image sous 2 formes en fonction du contenu recu:

- image + titre
- image plein écran

**Fullscreen video**

Integration d'un lecteur vimeo en plein écran :

- supportant l'orientation portait et paysage
- liant la langue de l'utilisateur avec les sous titres

**Choix**

Module permettant à l'utilisateur de faire un choix (boutons ou images).

**Quiz**

Module de quiz à décliner sous 2 formes:

- quiz images (texte en option)
- quiz textes (boutons)

**Gps**

Module permettant d'emmener l'utilisateur à un point précis de la carte

## Partie en option

**Composant prise d'image**

Implémentation d'un composant de prise d'image se reposant sur la caméra native du téléphone (filebrowser type photo) permettant :
- la prise de bouton sous forme de bouton
- la gestion de la permission (si besoin)
- un retour de l'image prise dans un format standard

**Ecran d'alerte**
Ecran d'alerte bloquant la navigation du jeu et informant le joueur d'un problème rendant le jeu inaccessible. Cette alerte sera envoyée par la runtime-api en réponse à une action utilisateur.

**Geolocation quiz**

Module de quiz demandant au joueur d'aller à un lieu caché (cf specs)

**QR Code**

Module de quiz demandant au joueur d'aller photographier un QRCode. Basé sur le composant prise d'image plus haut.

**Image recognition**

Module de quiz demandant au joueur d'aller photographier un objet / image. Basé sur le composant prise d'image plus haut.