API docs et Dockerfile for dev

docs/time-manager-api.md

@@ -0,0 +1,158 @@
+TimeManager — API publique (résumé d'usage)
+=========================================
+
+Ce document résume l'usage des endpoints exposés par l'app TimeManager (routes dans [appinfo/routes.php](https://github.com/te-online/timemanager/blob/main/appinfo/routes.php)). Les implémentations serveur se trouvent dans [lib/Controller/TApiController.php](https://github.com/te-online/timemanager/blob/main/lib/Controller/TApiController.php) et la logique de transformation/stockage dans [lib/Db/StorageHelper.php](https://github.com/te-online/timemanager/blob/main/lib/Db/StorageHelper.php).
+
+Authentification
+-----------------
+- L'API est une API Nextcloud : il faut une session authentifiée ou utiliser l'authentification HTTP Basic (utilisateur + mot de passe d'application). Dans les scripts automatisés, préférez un `app password`.
+- Pour les requêtes JSON, envoyez `Content-Type: application/json`.
+
+Résumé des endpoints
+--------------------
+
+- `GET  /api/items` — lecture / recherche d'items (clients / projets / tâches / temps). Usage UI/interop (paramètres de filtrage dépendants de l'implémentation). Le contrôleur `TApiController` ne contient pas de méthode `get` explicite dans la version actuelle du dépôt ; ce endpoint peut être géré par un héritage du framework ou un code serveur externe.
+- `POST /api/items` — création d'un item (implémentation: création d'un client via `post($name, $note)`). Exemple minimal : envoyer `{"name":"Mon client","note":"…"}`.
+- `POST /api/updateObjects` — endpoint principal de synchronisation bidirectionnelle. Accepta un objet JSON contenant `lastCommit` et `data` (structure détaillée ci‑dessous). Retourne les objets modifiés depuis le commit fourni plus un nouveau `commit` si des changements ont été appliqués.
+- `POST /api/sync-web` — alias/variante utilisée par le client web (`updateObjectsFromWeb`) ; se comporte comme `updateObjects`.
+- `GET  /api/hoursInPeriod` — statistique/aggrégation des heures sur une période. Paramètres détaillés ci‑dessous.
+
+Détail : `POST /api/updateObjects`
+---------------------------------
+
+Attendu : un JSON avec ces champs racine :
+
+ - `lastCommit` : string — le commit connu côté client (vide ou absent si première synchronisation).
+ - `data` : objet contenant 4 entités : `clients`, `projects`, `tasks`, `times`.
+
+Chaque entité doit être un objet contenant trois tableaux : `created`, `updated`, `deleted`.
+
+Exemple minimal :
+
+```
+{
+  "lastCommit": "",
+  "data": {
+    "clients": { "created": [ { "name": "Client A" } ], "updated": [], "deleted": [] },
+    "projects": { "created": [], "updated": [], "deleted": [] },
+    "tasks": { "created": [], "updated": [], "deleted": [] },
+    "times": { "created": [], "updated": [], "deleted": [] }
+  }
+}
+```
+
+Champs usuels par entité (voir `StorageHelper::convertToEntityObject` pour la liste complète)
+
+- clients: `name`, `note`, `email`, `phone`, `city`, `postcode`, `street`, `web`, `uuid`, `commit`, `created`, `changed`.
+- projects: `name`, `client_uuid`, `note`, `color`, `uuid`, `commit`, `created`, `changed`.
+- tasks: `name`, `project_uuid`, `uuid`, `commit`, `created`, `changed`.
+- times: `start`, `end`, `task_uuid`, `note`, `uuid`, `commit`, `created`, `changed`.
+
+Comportement serveur (synthèse)
+- Le serveur vérifie que chaque entité a bien les trois sous-tableaux `created`, `updated`, `deleted` et renverra une erreur HTTP 406 si la structure est invalide.
+- Pour les objets `created`, le serveur complète `uuid`, `created`, `changed` si besoin et insère l'objet. Pour `updated`/`deleted`, le serveur utilise les champs `commit` / `desiredCommit` pour résoudre les conflits selon la stratégie configurée.
+- Le serveur renvoie un objet JSON contenant `data` (les objets modifiés après le commit fourni) et `commit` (nouveau commit si des changements ont été appliqués, sinon le dernier commit connu côté serveur).
+
+Exemple de réponse (squelette) :
+
+```
+{
+  "data": {
+    "clients": [ /* liste d'objets client après commit demandé */ ],
+    "projects": [ /* ... */ ],
+    "tasks": [ /* ... */ ],
+    "times": [ /* ... */ ]
+  },
+  "commit": "<commit-uuid>"
+}
+```
+
+Notes pratiques
+- Le champ `commit` est central pour la synchronisation incrémentale : envoyez la valeur `commit` renvoyée par le serveur comme `lastCommit` lors du prochain appel pour ne recevoir que les changements suivants.
+- Si vous ne souhaitez pousser aucun changement mais uniquement récupérer les nouveautés, envoyez `data` vide (ou des tableaux vides) et `lastCommit` égal au dernier commit connu du client : le serveur renverra les objets après ce commit.
+
+`/api/sync-web`
+----------------
+Equivalent pratique de `updateObjects`, prévu pour les appels depuis le front‑end web. Même payload et même réponse.
+
+`GET /api/hoursInPeriod`
+------------------------
+
+Signature (d'après `TApiController::getHoursInPeriodStats`):
+
+- `start` (required) — date de début (format attendu par l'app, typiquement `YYYY-MM-DD` ou une date ISO)
+- `end` (required) — date de fin
+- `group_by` (optional) — `none` | `day` | `week` | `month` | `year` (par défaut `none`)
+- `clients`, `projects`, `tasks` (optional) — listes CSV d'UUIDs pour filtrer (`client_uuid1,client_uuid2`)
+- `status` (optional) — filtre d'état des temps (ex: `active`/`deleted` selon implémentation)
+- `shared` (optional) — booléen pour inclure les entrées partagées
+- `userFilter` (optional) — CSV d'IDs utilisateurs pour limiter aux auteurs
+- `timezone` (optional) — timezone utilisée pour l'agrégation (ex: `UTC`)
+
+Exemple curl :
+
+```bash
+curl -u "user:APP_PASSWORD" \
+  "https://<nextcloud>/apps/timemanager/api/hoursInPeriod?start=2026-01-01&end=2026-01-31&group_by=day"
+```
+
+Réponse (squelette) :
+
+```
+{
+  "total": 123.5,
+  "grouped": { "2026-01-01": 8.0, "2026-01-02": 7.5 },
+  "js_date_format": "yyyy-MM-dd"
+}
+```
+
+`GET /api/items` et `POST /api/items`
+------------------------------------
+
+- `POST /api/items` crée un client si on lui fournit `name` et `note` (méthode `post($name,$note)` dans `TApiController`). Exemple :
+
+```bash
+curl -u "user:APP_PASSWORD" -H "Content-Type: application/json" \
+  -d '{"name":"Nouveau client","note":"créé via API"}' \
+  -X POST "https://<nextcloud>/apps/timemanager/api/items"
+```
+
+- `GET /api/items` permet de lister / rechercher des éléments exposés par l'API (usage UI). Les filtres exacts sont implémentés dans la méthode `get` du contrôleur; si vous avez un usage précis je peux extraire la signature exacte et ajouter des exemples d'appel.
+
+Exemple Python de synchronisation `updateObjects`
+---------------------------------------------
+
+```python
+import requests
+import json
+from requests.auth import HTTPBasicAuth
+
+url = "https://<nextcloud>/apps/timemanager/api/updateObjects"
+username = "<user>"
+password = "<app_password>"
+
+payload = {
+    "lastCommit": "",
+    "data": {
+        "clients": {"created": [{"name": "Client API", "note": "Créé via API"}], "updated": [], "deleted": []},
+        "projects": {"created": [], "updated": [], "deleted": []},
+        "tasks": {"created": [], "updated": [], "deleted": []},
+        "times": {"created": [], "updated": [], "deleted": []}
+    }
+}
+
+resp = requests.post(url, json=payload, auth=HTTPBasicAuth(username, password))
+print(resp.status_code)
+print(resp.text)
+```
+
+Références et exploration
+-------------------------
+- Code source des routes : https://github.com/te-online/timemanager/blob/main/appinfo/routes.php
+- Contrôleur API : https://github.com/te-online/timemanager/blob/main/lib/Controller/TApiController.php
+- Conversion JSON → entités : https://github.com/te-online/timemanager/blob/main/lib/Db/StorageHelper.php
+
+Si vous voulez, je peux :
+- ajouter des exemples d'appels `curl` réels adaptés à votre instance Nextcloud (avec placeholders),
+- extraire la signature exacte de la méthode `get` pour `/api/items` et ajouter sa doc précise,
+- générer un petit script Python d'exemple qui synchronise un petit ensemble `clients/projects/tasks/times` contre votre instance.

support/docker-dev/.dockerignore

@@ -0,0 +1,8 @@
+env
+__pycache__
+.git
+.venv
+/*.pyc
+*.egg-info
+dist
+build

support/docker-dev/Dockerfile

@@ -0,0 +1,28 @@
+FROM python:3.9.2-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+# Install minimal build deps (kept small). Adjust if your requirements need additional system packages.
+RUN sed -i 's|http://deb.debian.org/debian|http://archive.debian.org/debian|g' /etc/apt/sources.list \
+    || true \
+    && sed -i 's|http://security.debian.org/debian-security|http://archive.debian.org/debian-security|g' /etc/apt/sources.list \
+    || true \
+    && echo 'Acquire::Check-Valid-Until "false";' > /etc/apt/apt.conf.d/99no-check-valid-until \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends gcc ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy only requirements first to leverage Docker cache
+COPY requirements.txt /app/requirements.txt
+
+RUN pip install --upgrade pip \
+    && pip install --no-cache-dir -r /app/requirements.txt
+
+# By default the container runs Python; pass a script name or `-m` args after the image name.
+ENTRYPOINT ["python3"]
+
+# Recommended working directory for runs
+CMD ["-V"]

support/docker-dev/README.md

@@ -0,0 +1,38 @@
+Image Docker de développement pour exécuter les scripts Python du projet
+
+This image provides a lightweight Python 3.9.2 environment with the project `requirements.txt` installed.
+
+Build
+-----
+
+From the repository root (where `requirements.txt` sits) run:
+
+```bash
+docker build -t cal-to-time-manager:dev -f support/docker-dev/Dockerfile .
+```
+
+Usage
+-----
+
+Run a script from the project root by mounting the repo into `/app`:
+
+```bash
+# run csv-to-timemanager.py
+docker run --rm -v "$(pwd)":/app -w /app cal-to-time-manager:dev csv-to-timemanager.py
+
+# run with arguments
+docker run --rm -v "$(pwd)":/app -w /app cal-to-time-manager:dev csv-to-timemanager.py arg1 arg2
+```
+
+Open an interactive shell (override the image entrypoint):
+
+```bash
+docker run --rm -it --entrypoint bash -v "$(pwd)":/app -w /app cal-to-time-manager:dev
+```
+
+Notes
+-----
+- The container uses Python 3.9.2 (slim). If your `requirements.txt` needs system packages, adapt the `Dockerfile` to install them.
+- The scripts expect `config.json` and CSV files to be present in the mounted workspace path.
+- If your scripts connect to services (MySQL, Nextcloud API), ensure the container can reach those hosts (network, VPN, or expose host ports).
+- To pass secret credentials, prefer using environment variables or Docker secrets rather than baking them in `config.json` inside the image.