la-chariotte/README.md

# La Chariotte

<img src="la_chariotte/static/img/logos/logo_la_chariotte.png" title="Logo de la Chariotte" height="150"/>

La Chariotte est une application de gestion de commandes groupées.

Elle est publiée sous licence libre Affero GPL, développée et maintenue par [Hashbang](https://hashbang.fr/).

## Contribuer

Si vous souhaitez contribuer au projet de la Chariotte, merci beaucoup !

La permière étape est de cloner le projet et d'obtenir le statut de développeur. Une fois que c'est fait, vous pouvez :

- choisir une tâche dans le board que vous voulez réaliser, et vous l'assigner - si vous ne savez pas quelle tâche faire, n'hésitez pas à écrire à laetitia@chariotte.fr
- créer une nouvelle branche **à partir de develop** dont le nom dira ce que vous voulez faire
- réaliser la tâche, sans oublier d'écrire et de lancer les tests (voir plus bas)
- créer une Merge Request, contenant le plus de détails possible sur ce que vous avez fait

Ensuite, un mainteneur de la Chariotte pourra relire votre code et proposer des améliorations/poser des questions si nécessaire. Seuls les mainteneurs peuvent merger dans develop et main.

Encore merci, et bon code !

## Versions - semantic versionning

Les fonctionnalités développées dans les différentes versions sont listées dans le fichier [CHANGELOG.md](https://gitlab.com/hashbangfr/la_chariotte/-/blob/main/CHANGELOG.md). 

Étant donné un numéro de version MAJEUR.MINEUR.CORRECTIF, il faut incrémenter :

le numéro de version MAJEUR quand il y a des changements non rétrocompatibles,
le numéro de version MINEUR quand il y a des ajouts de fonctionnalités rétrocompatibles,
le numéro de version de CORRECTIF quand il y a des corrections d’anomalies rétrocompatibles.

La version est à mettre à jour dans `la_chariotte.__init__.py` lors des releases.

## Développement

Cloner le projet :
```bash
git clone git@gitlab.com:hashbangfr/la_chariotte.git
```

### Environnement virtuel.

Pour éviter que les bibliothèques nécessaires au projet ne rentrent en conflit avec celles de votre système, il peut être utile d'installer un environnement virtuel :

```bash
python3 -m venv .venv
```

Une fois l'environnement virtuel installé, vous pouvez l'activer :

```bash
source .venv/bin/activate
```

### Dépendances

Installer les dépendances :
```bash
pip install -r requirements.txt
pip install -r dev-requirements.txt
```

### Base de données

La Chariotte nécessite une base de données, et est actuellement compatible avec PostgreSQL ([instructions d'installation ici](https://www.digitalocean.com/community/tutorials/how-to-install-postgresql-on-ubuntu-20-04-quickstart)).

Pour le développement, nous vous conseillons de créer une base de données nommée ```chariotte``` accessible par l'utilisateur et le mot de passe du même nom.

Dans une invite postgresql, entrez ceci :

```SQL
CREATE ROLE chariotte WITH
	LOGIN
	NOSUPERUSER
	CREATEDB
	NOCREATEROLE
	INHERIT
	NOREPLICATION
	CONNECTION LIMIT -1
	PASSWORD 'xxxxxx';
```
```SQL
CREATE DATABASE chariotte
    WITH
    OWNER = chariotte
    ENCODING = 'UTF8'
    CONNECTION LIMIT = -1
    IS_TEMPLATE = False;
```

### Fichier de configuration

Créez un fichier de configuration dans lequel vous pourrez spécifier la configuration qui est utile pour vous. Nous allons le nommer ici ```local_settings.py```.

```python
from la_chariotte.settings import *

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": "chariotte",
        "USER": "chariotte",
        "PASSWORD": "chariotte",
        "HOST": "localhost",
    }
}
```

### Lancement du serveur

Tout devrait être maintenant prêt pour pouvoir lancer le serveur :

```shell
python manage.py runserver --settings=local_settings
```

Pour créer un superutilisateur, qui aura accès à l'interface admin (/admin) :
```shell
python manage.py createsuperuser
```

### Travailler sur le frontend

Nous utilisons bulma comme framework CSS. Vous pouvez l'installer en utilisant la commande suivante :

```bash
npm install bulma
```

Vérifiez que vous utilisez la bonne version de sass :

```bash
sass --version
# used for developement: 1.59.3 compiled with dart2js 2.19.4
```

Recompiler dès que des changements sont detectés dans les fichiers scss.

```bash
sass --watch --no-source-map ./la_chariotte/static/sass/style.sass:./la_chariotte/static/css/app.css
```

Ou bien préférez compiler vers CSS au coup à coup :
```bash
sass --no-source-map ./la_chariotte/static/sass/style.sass:./la_chariotte/static/css/app.css
```

### Lancer les tests

Lancer les tests avec pytest :
```bash
pytest
```

Si il y a des erreurs [isort](https://pycqa.github.io/isort/), on peut lancer isort pour trier les fichiers :

```bash
isort .
```

Si il y a des erreurs [black](https://black.readthedocs.io/en/stable/), on peut lancer black pour linter le code :

```bash
black .
```

### Tests de l'envoi de mails

Pour tester l'apparence des mails, on peut utiliser [Sendria](https://github.com/msztolcman/sendria) : 
```bash
pip install sendria
sendria --db mails.sqlite
$NAVIGATOR http://127.0.0.1:1080
```

## Architecture de l'application

Les différentes applications Django créées sont :

- ``order``, pour gérer tout ce qui tourne autour des commandes
- ``accounts``, pour gérer la création de comptes. Pour la connexion, la déconnexion et le changement de mot de passe, on utilise l'application auth intégrée à Django.
- ``mail``, pour l'envoi des mails.

A l'état actuel, le diagramme de classes est le suivant :

```mermaid
classDiagram
    GroupedOrder "item_set" <-- Item
    GroupedOrder "order_set" <-- Order
    Order "ordered_items" <-- OrderedItem 
    Item "orders" <-- OrderedItem 
    OrderAuthor "author" <-- Order
    CustomUser "grouped_orders" <-- GroupedOrder

    class GroupedOrder{
      name
      deadline : DateTime
      delivery_date : Date
      place
      description
      orga : CustomUser
      total_price
    }
    class Item{
      name
      grouped_order : GroupedOrder
      ordered_nb
      total_price
      max_limit
    }
    class Order{
        grouped_order : GroupedOrder
        author : OrderAuthor
        price
        created_date
        note
    }
    class OrderedItem{
        order : Order
        nb 
        item : Item
    }
    class OrderAuthor {
        first_name
        last_name
        phone
        email
    }
    class CustomUser{
        first_name
        last_name
        email
    }
```