# Documentation de développement de betaportic

## Architecture

### Installation des npm

npm install material-design-icons
npm install vue-material --save

### Version des logiciels

Les imports à mettre dans package.json

- Un serveur web apache2 pour faire tourner le site
- PostgreSQL 9.6 pour la base de données
- Python3 pour récupérer les informations de la base de données (API)
- Vue.JS 2.5.2 pour le site web (Front)
- OpenLayers 5.3.2 pour la carte permettant de visualiser les trajets
- WebPack service 3.6.0 pour compiler OpenLayer/Vue.JS

### Serveur Web

## Les variables d'état applicatives

- le niveau spatial de cartographie + liste des objets spatiaux sélectionnés (un triplet (id, niveau, nature)) avec
- id = identifiant de l'objet
- niveau = port, amirauté, ferme, province, etat, colonie, etc.
- nature : in, out, home
- le niveau temporel + la liste des périodes temporelles sélectionnées : (date_debut, date_fin, niveau, periodic)
- date_debut : yyyy-mm-dd
- date_fin : yyyy-mm-dd
- niveau : year, season, month, week, day
- periodic : booléen qui vaut vrai si on doit répéter l'analyse sur la même période de façon cyclique (pour l'instant, garder le choix à faux par défaut).
- les variables à croiser : 2 parmi
- ship class - catégorielle (type de navire)
- ship flag - catégorielle (pavillon)
- cargo class - catégorielle (type de cargaison)
- out class - catégorielle (type de sortie)
- source class - catégorielle - type de source : G5 (congés) ou Marseille (Santé) ou les congés d'une amirauté en particulier (congé-Bordeaux).
- ship tonnage - quantitative & qualitative (tonnage) : on découpe en catégories de tonnage pour certaines analyses (qualitatif), ou on compte la somme des tonneaux (quantitatif)
- nb ship - quantitative (nombre de bateaux) - sortis, entrés, rattachés au port (en fonction de IN/OUT/HOME)
- les catégories actives pour chaque variable.
- Pour les classes de navires : (brick, brigantin, schooner)
- Pour les drapeaux : (fr, es) si navires de pavillon français et espagnols uniquement
- Pour les cargaisons : (fish, human) si choisis.
- Pour les sorties : pêche, cabotage, long-cours, ... [pêche découpée en *grande pêche*, *pêche fraîche* (sortie à la journée, vente en direct) et *pêches "industrielles"* (hareng, sardine, maquereau). Les sources distinguent à coup sûr grande et petites pêches mais quid des pêches industrielles ? Le hareng c'est la Manche orientale, le maquereau la Manche occidentale, la sardine la Bretagne sud, le Bas Poitou et le Pays Basque...]
- Pour les tonnages : (cat1, cat3) avec une lecture pour l'instant dans un fichier de config que cat1 = [0, 5], et cat3 = [50, 100]
- Pour les sources : (santé, congé-Bordeaux) si marseille et congés de Bordeaux à analyser conjointement

## Déploiement

1. URLs dans les composants Vue pour interrroger l'API
**api** à remplacer par **python/serverPython.py**

2. compiler le projet avec la commande **npm run build**

3. copier le _dist/static_ + _dist/index.html_ dans le repertoire root servi par apache.

4. Faire attention au fichier server*.py :
- rajouter **#!/usr/bin/env python3** dans l'entête du fichier serverPython.py
- dos2unix : `for fic in $(find . -type f -name "*.py"); do sudo dos2unix $fic; done`
- droits +x et www-data : attention à log.txt **après** une première exécution de serverPython.py
- `sudo chown -R :www-data ../navigoviz`
- `sudo chmod -R g+x ../navigoviz`
- `python3 serverPython.py`
- `sudo chown :www-data log.txt`

5. Bien executer les requetes qui se trouvent dans `python/detail.sql` et `navigoviz.pointcall_agregate.sql` afin de créer les tables

6. Executer le fichier createTravel.py pour créer la table navigoviz.travel
7. Executer les requêtes du fichier travel.sql afin de créer les segments des ports et supprimer les congés en dehors du G5/marseille

8. Accorder les droits en lecture à navigo sur toutes les tables du schema navigoviz

GRANT SELECT ON ALL TABLES IN SCHEMA navigoviz TO  navigo;

9. Vérifier les logs d'Apache
`sudo vi /var/log/apache2/error.log`

# API

## Les Tables
Certaines tables sont créers à partir des fichiers python/detail.sql, navigoviz.pointcall_agregate.sql

### navigoviz.ship
Contient la liste de tous les bateaux regrouper par **ship_local_id** de la table **navigocheck.check_pointcall**

Attributs (voir occurences pour le detail des json):
- _Local_id (text)_ : l'id du bateau
- _occurences_names(json)_ : La liste des noms possible pour un même id présent dans la table navigocheck.check_pointcall avec leurs nombres d'occurences
- _occurences_homeports(json)_ : La liste des homeports possible pour un même id présent dans la table navigocheck.check_pointcall avec leurs nombres d'occurences
- _occurences_flags(json)_ : La liste des flags possible pour un même id présent dans la table navigocheck.check_pointcall avec leurs nombres d'occurences
- _occurences_class(json)_ : La liste des class possible pour un même id présent dans la table navigocheck.check_pointcall avec leurs nombres d'occurences
- _occurences_captain(json)_ : La liste des noms des capitaines ayant piloté le bateau avec leurs nombres d'occurences

### navigoviz.captain
Contient la liste de tous les capitaines regrouper par **captain_local_id** de la table **navigocheck.check_pointcall**

Attributs (voir occurences pour le detail des json):
- _Local_id (text)_ : l'id du capitaine
- occurences_last_names(json)_ : La liste des last_names possible pour un même id présent dans la table navigocheck.check_pointcall avec leurs nombres d'occurences. Il est calculé grâce à une expression régulière qui récupére la première partie avant la virgule de captain_name dans la table **navigocheck.check_pointcall**. Il peut donc il y a avoir des erreurs dans le cas ou c'est marqué **prénom,nom** au lieu de **nom,prénom**.
- _occurences_names(json)_ : La liste des names (first name + last_name) possible pour un même id présent dans la table navigocheck.check_pointcall avec leurs nombres d'occurences
- _occurences_birthplaces(json)_ : La liste des birthplaces possible pour un même id présent dans la table navigocheck.check_pointcall avec leurs nombres d'occurences
- _occurences_citizenships(json)_ : La liste des citizenships possible pour un même id présent dans la table navigocheck.check_pointcall avec leurs nombres d'occurences
- _occurences_ship(json)_ : La liste des noms des bateaux qu'a piloté ce capitaine avec leurs nombres d'occurences

### navigoviz.travel
Contient la liste de tous les trajets de tous les bateaux/capitaines de la table navigocheck.check_pointcall

- _documentary_unit_id(String)_ : l'id du troncon
- _rank(Int)_ : le rank du troncon
- _from_port(String)_ : le nom (le plus fréquent) port d'ou part le bateau
- _to_port(String)_ le nom (le plus fréquent) port ou vas le bateau
- _ship_id(String)_ : l'id du bateau
- _captain_id(String)_: l'id du capitaine
- _in_date(String)_ : la date ou le bateau part de _from_port_
- _out_date(String)_ : la date ou le bateau arrive à _to_port_
- _from_port_id_(String) : l'id du port d'ou part le bateau (créer a partir de navigoviz.check_pointcall pointcall_uhgs_id)
- _to_port_id_(String) : l'id du port ou arrive le bateau (créer a partir de navigoviz.check_pointcall pointcall_uhgs_id)
- _guns_(String) : Le nombre de guns que transporté le bateau pendant le voyage
- _ship_tonnage_(String) : Le tonnage du bateau identifié
- _ship_tonnage_u_(String) : L'unité du tonnage
- _captain_name_(String) : Le nom et prénom du capitaine
- _ship_name_(String) : Le nom du bateau
- _captain_age_(String) : L'âge du capitaine au moment du voyage
- captain_status_(String) : Status du capitaine au moment du voyage
- _sailling_around_ (Boolean) : **true** si le port d'arrivé = port de départ
- _segment_(Geometry) LineString entre les deux points correspondant aux deux ports du voyages. Le segment es tcréer grâce au fichier travel.sql

### Schema des tables travel, ship et captain

### navigoviz.pointcall_agregate
Contient les données utilisées pour la visualisation agrégée des données, caractéristiques des bateaux, ports, amirautés...

- _pkid(Int)_ : clé primaire, référence le pkid de la table navigocheck.check_pointcall
- _record_id(String)_ : référence l'attribut record_id de la table navigocheck.check_pointcall
- _documentary_unit_id(String)_ : l'id du troncon
- _ship_local_id(String)_ : identifiant unique du navire
- _ship_class(String)_ : class du type de navire sans correction, issu de navigocheck.check_pointcall
- _ship_class_sort(String)_ : class du type de navire avec correction
- _ship_flag(String)_ : pavillon du navire, issu de navigocheck.check_pointcall
- _ship_homeport(String) : port d'attache du navire sans correction, issu de navigocheck.check_pointcall
- _ship_homeport_sort(String)_ : port d'attache du navire avec correction
- _ship_homeport_id(String)_ : identifiant du port d'attache du navire, référence _uhgs_id_ de la table navigoviz.port_points
- _ship_homeamiraute(String)_ : amirauté du port d'attache du navire, récupérée dans navigoviz.port_points
- _ship_tonnage(String)_ : tonnage du navire sans correction, issu de navigocheck.check_pointcall
- _ship_tonnage_sort(String) : tonnage du navire avec correction
- _ship_tonnage_int(Int) : tonnage du navire converti en entier et ramené à unité "tonneaux"
- _ship_tonnage_u(String)_ : unité de type de tonnage du navire
- _guns(String)_ : nombre de cannon(s) à bord du navire, issu de navigocheck.check_pointcall
- _pointcall_action(String)_ : motif de l'enregistrement du navire, In/Out/In-Out/Sailing, issu de navigocheck.check_pointcall
- _pointcall_function(String)_ : critères d'enregistrement de la données, issu de navigocheck.check_pointcall
- _pointcall_name(String)_ : nom du port de l'enregistrement, issu de navigocheck.check_pointcall
- _pointcall_rank(String)_ : rang du troncon sur l'itinéraire du navire, issu de navigocheck.check_pointcall
- _pointcall_status(String)_ : issu de navigocheck.check_pointcall
- _pointcall_uhgs_id(String)_ : identifiant d'un port, référence _uhgs_id_ de la table navigoviz.port_points
- _ship_increw(String)_ : nombre d'hommes embarqués, issu de navigocheck.check_pointcall
- _ship_outcrew(String)_ : nombre d'hommes débarqués, issu de navigocheck.check_pointcall
- _source(String)_ : identifiant précis du Congé/Registre, issu de navigocheck.check_pointcall
- _component_description__component_short_title(String)_ : Nom français du Congé/Registre, issu de navigocheck.check_pointcall
- _component_description__component_source(String)_ : identifiant raccourci Congé/Registre, issu de navigocheck.check_pointcall
- _component_description__suite_id(String)_ : identifiant du type de Congé/Registre
- _conge_name(String)_ : nom du port de l'enregistrement de la donnée avec correction
- _stage_id(String)_ : identifiant du troncon, issu de navigocheck.check_pointcall
- _stage_id_link_reversed(String)_ : permet de des navires qui se baladent dans les deux sens entre les 2 points, issu de navigocheck.check_pointcall
- _pointcall_date(String)_ : date sans correction, issu de navigocheck.check_pointcall
- _pointcall_date_string(String)_ : date avec correction
- _pointcall_date_date(Date)_ : date convertie en type SQL `Date`
- _year(String)_ : année de l'enregistrement de la donnée
- _month(String)_ : mois de l'enregistrement de la donnée
- _day(String)_ : jour de l'enregistrement de la donnée
- _flag_date(Int)_ : status de la date,
> 1 Date stated in the source
> 2 Evaluated date posterior to the known date stated in the source
> 3 Evaluated date preceding the known date stated in the source
> -1 Data format is invalid
> 4 When various points referred to the same ship have a same date
> 21 When day posterior to the known date stated ex 1794=10>18
> 31 When day preceding to the known date stated ex 1796=07<24
> null Date format is invalid (ex 1787-01-00, 1787-05-99, 1788-02-30)
- _conge_id(Int)_ : référence conge_id de la table navigoviz.conge
- _country(String)_ : pays
- _amiraute(String)_ : amiraute
- _province(String)_ : province
- _cargo_class(String)_ : Class principale de la cargaison
- _cargo_subclass(String)_ : Class secondaire de la cargaison
- _out_class(String)_ : Type de sortie effectué par un navire
- _latitude(numeric)_ : latitude du point,
- _longitude(numeric)_ : longitude du point,
- _travel_distance(numeric)_ : distance parcourue pour atteindre le point actuel, issue de la table navigoviz.distance_pointcall

>##### Classification Cargo
>###### Classification sur commodity_permanent_coding
>* Humains : `IY-`
>* Betails : `ID-M`
>* Food : `ID-AA`
- Céréales : `ID-B`
- Fruits : `ID-FFE` `ID-FFD` `ID-FFC` `ID-FC` `ID-FB` `ID-FA`
- Vegetables : `IF-` `ID-EE` `ID-EF` `ID-EB` `ID-EA`
- Sel : `IC-CA`
- Produits laitier : `ID-OA`
- Viande : `ID-NC` `ID-NB`
- Huiles : `ID-GOC Oil`
- Sucre : `ID-GBA`
- Poisson : `IA-F`
- Autres : `IA-AA`
>* Alcool tabac epices
- Alcool : `IF-FA`
- Epices : `ID-V`
- Chocolat : `ID-GDB`
- Thé Café : `ID-GCD`
- Vin : `ID-FFB`
- Biere : `ID-GCB`
- Tabac : `ID-GVA`
>* Charbon : `IC-AA` `IB-B`
>* Bois : `IB-C` `IB-A`
>* Bien : `IZ-AC`
>* Textile : (vegetale) `ID-GT` (animale) `ID-OW` `ID-OS` `ID-OL`
>* Peche : `FD-` `FC-` `FB-`
>* Sans cargo : `TM-` `NT-` `MN-`
>###### Nom des class et sous-class (navigoviz.pointcall_agregate.cargo_class et navigoviz.pointcall_agregate.cargo_subclass)
>* Humans
>* Cattle
>* Foods
- Cereals
- Fruits
- Vegetables
- Salt
- Dairy Products
- Meat
- Oils
- Sugars
- Fishes
- Others
>* Liquor Tobacco Spice
- Tobacco
- Liquors
- Spices
- Chocolates
- Tea Coffee
- Wine
- Beer
>* Coal
>* Woods
>* Goods Sundries
>* Textiles
>* Fishery
>* Ballast

### navigoviz.conge
Table servant à compléter la table navigoviz.pointcall_agregate. Peut être supprimé.

### navigoviz.pointcall_date
Table servant à compléter la table navigoviz.pointcall_agregate. Peut être supprimé.

### navigoviz.distance_pointcall
Table servant à compléter l'attribut travel_distance de la table navigoviz.pointcall_agregate. Peut être supprimé.

## Occurences

Toutes les data comportant **occurences** dans leurs noms renvoie un array d'object avec comme attributs :
- f1 : L'occurences (ca peut etre un nom, une class ...)
- f2 : la fréquence de l'occurence
## Les Requêtes
Tous les liens indiqué sont en mode dev
les _fonctions_ indiqué dans les **data** correspondent au noms des fonctions sous l'API python il est important de les préciser lors d'une requêtes ajax. Elles sont toutes de types "POST"

### export_object_name
Recherche tous les noms d'un bateau ou d'un capitaine comportant une certaine chaîne de caractères

- **type** : "POST"
- **url** : /api
- **data** :
- _fonction_ = "object_name"
- _startName(String)_ : La chaine de caractère a rechercher
- _object(String)_ : ship || captain pour savoir si c'est le nom d'un bateau ou d'un câpitaine qu'on recherche

- **dataType** : "json"
- **return** : _name[String]_ Une liste de tous les noms de _object_

### export_captain_with_name
Recherche tous les captaines qui ont le même noms que celui renseigné dans les **data**

- **type** : "POST"
- **url** : /api
- **data** :
- fonction : "captain_with_name"
- _last_name(String)_ le noms que l'on doit rechercher

- **dataType** : "json"

- **return** : Renvoie une liste de captaine[{Object}] avec comme attributs
- _local_id(String)_ l'id du capitaine
- _name(String)_ le nom correspondant à la recherche
- _citizenship(String)_ sa nationalité la plus fréquente
- _birthplace(String)_ son lieu de naissance le plus fréquent
- _current_name(String)_ Le nom du capitaine le plus enregistré
- _ship(String)_ Le nom du bateau le plus utilisé

### export_ship_with_name
Recherche tous les bateaux qui ont le même noms que celui renseigné dans les **data**

- **type** : "POST"
- **url** : /api
- **data** :
- fonction : "captain_ship_name"
- _ship_name(String)_ le noms que l'on doit rechercher

- **dataType** : "json"

- **return** : Renvoie une liste de bateaux[{Object}] avec comme attributs
- _local_id(String)_ l'id du bateau
- _name(String)_ le nom correspondant à la recherche
- _current_name(String)_ Le nom du bateau le plus enregistré
- _flag(String)_ Sous quelle flag le bateau navigue le plus fréquament
- _homeport(String)_ Le nom de son port de rattachement qui apparait le plus
- _class(String)_ Le type de bateau qui est le plus indiqué dans les sources
- captain(String)_ Le nom du capitaine ayant le plus navigué avec le bateau concerné

### export_detail_ship
Donne les détail d'un bateau pour un id donné

- **type** : "POST"
- **url** : /api
- **data** :
- fonction : "ship_detail"
- _object_id(String)_ : l'id du bateau qu'on doit rechercher

- **dataType** : "json"

- **return** : Renvoie un _bateau{Object}_ (voir occurences pour le détail des objects)
- _local_id(String)_ l'id du bateau
- _occurences_name[{Object}]_ Le/Les noms du bateau
- _occurences_flags[{Object}]_ Le/Les flags du bateau
- _occurences_homeports[{Object}]_ Le/Les homeports du bateau
- _occruences_class[{Object}]_ Le/Les type de bateau

### export_detail_captain
Donne le détail d'un captaine pour un id donné

- **type** : "POST"
- **url** : /api
- **data** :
- fonction : "captain_detail"
- _object_id(String)_ l'id du captaine qu'on doit rechercher

- **dataType** : "json"

- **return** : Renvoie un captaine{Object} (voir occurences pour le détail des objects)
- _local_id(String)_ l'id du capitaine
- _occurences_name(String)_ Le/Les nom du captaine
- _citizenship(String)_ La/Les nationalité
- _birthplace(String)_ Le/Les lieux de naissances

### export_travel
Donne la liste des voyages pour un id de captaine ou de bateau donné
<aside class = "alert-danger">
La table navigoviz.travel doit être créer au préalable grâce au fichier python/createTravel.py
</aside>
</div>
</div>

- **type** : "POST"
- **url** : /api
- **data** :
- fonction : "travel_detail"
- _field(String)_ :
- **captain_id** si on renseigne l'id d'un captaine
- **ship_id** si on rensigne l'id d'un bateau
- _id(String)_ l'id du _field_ qu'on doit rechercher

- **dataType** : "json"

- **return** : Renvoie une liste de voyage[{Object}]
- _id_(Int) : identifiant du voyage
- _features(GEOJSON)_ renvoie la features du segment du trajets
- _documentary_unit_id(String)_ : l'id du troncon
- _rank(Int)_ : le rank du troncon
- _from_port(String)_ : le nom (le plus fréquent) port d'ou part le bateau
- _to_port(String)_ le nom (le plus fréquent) port ou vas le bateau
- _ship_id(String)_ : l'id du bateau
- _captain_id(String)_: l'id du capitaine
- _in_date(String)_ : quand le bateau part de _from_port_
- _out_date(String)_ quand le bateau arrive à _to_port_
- _from_port_id(String)_ id du port de départ
- _to_port_id(String)_ id du port d'arrivé
- _segment_(Geometry)_ Ligne du port d'arrivé au port de départ
- _captain_name_(String) : Nom du capitaine
- _ship_name(String)_ : Nom du bateau
- _sailling_arround(Boolean)_ : renvoie true si port arrivé=port de départ

### export_country_by_captain
Recherche les pays associé au birthplace d'un ou plusieurs capitaine

- **type** : "POST"
- **url** : /api
- **data** :
- _fonction_ = country_by_captain
- _name(String)_ : Le nom du capitaine

- **dataType** : "json"
- **return** :
- _birthplace(String)_ : le lieu de naissance du capitaine
- _local_id(String)_ : l'id du capitaine
- _captain_name(String)_ : le nom du capitaine
- _country(String)_ : le pays du capitaine

<style>
.alert-danger {
color: rgb(169,68,66) !important;
}
</style