SPB Git forge
spboucher.ai ↗

spb/api-ka

Public

API-KA — plateforme centrale : collecte quotidienne des 8 services KA, historisation append-only et API publique sur www.api-ka.com

fastapipostgresqlagregationka
48commits 1branches 0releases
5.9 MBsize
maindefault branch
19 days agolast push
Python 60.9% HTML 21% TypeScript 7.3% JavaScript 5.2% CSS 4.8% Shell 0.8%

Page /stats : tableau de bord analytique de la plateforme + rapport PDF Groupe-KA

- Journalisation légère des requêtes API : table api_requests (ts, méthode,
  endpoint normalisé, statut, durée) alimentée par le middleware de logging
  via un tampon mémoire non bloquant + tâche de fond (flush 5 s, purge 90 j).
- Backfill : scripts/backfill_api_requests.py réimporte l historique réel des
  logs JSON (811 requêtes depuis le 2026-08-16), idempotent.
- GET /api/stats/dashboard : contrat commun Groupe KA (SPEC.md) — KPI avec
  deltas, séries jour/heure (appels, latence, enregistrements collectés),
  top endpoints, anneau par service, heatmap, tableaux, records ; cache 5 min.
- GET /api/stats/report : PDF Groupe-KA (moteur kapdf/fpdf2, wordmark API·Ka,
  accent #3b5bdb), modes complet et synthèse ; correctif kit : pied de page
  qui fuyait sur la couverture.
- Page /stats (vanilla JS + SVG, langage visuel du kit kacharts) : chips de
  période + plage personnalisée, KPI, courbes avec infobulle et légende
  cliquable, barres, anneau, heatmap, tableaux triables (recherche +
  pagination), records, boutons PDF, états vides propres, mobile 360-1440.
- Lien « Stats » dans la nav de index.html et contact.html ; fpdf2 ajouté aux
  requirements ; tests /api/stats (32 tests verts).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Simon-Pierre Boucher committed 1 mo ago (Aug 18, 2026) parent 9672813

15 changed files +3,229 −4

modified requirements.txt +1 −0
@@ -15,6 +15,7 @@ alembic>=1.13
15 15 apscheduler>=3.10
16 16 httpx>=0.27
17 17 python-dotenv>=1.0
18 +fpdf2>=2.8
18 19
19 20 # Développement / tests
20 21 pytest>=8.0
added scripts/backfill_api_requests.py +93 −0
@@ -0,0 +1,93 @@
1 +# ============================================
2 +# Projet : API-KA
3 +# Fichier : scripts/backfill_api_requests.py
4 +# Node : m3u96b
5 +# Author : Simon-Pierre Boucher
6 +# Contact : contact@spboucher.ai
7 +# Date : 2026-08-17
8 +# ============================================
9 +"""Rattrapage : importe l'historique des requêtes HTTP déjà journalisées dans
10 +``logs/apika.log*`` (lignes JSON ``http_request`` du middleware) vers la table
11 +``api_requests`` qui alimente la page /stats.
12 +
13 +Idempotent : seules les lignes STRICTEMENT antérieures au plus ancien
14 +enregistrement déjà présent dans ``api_requests`` sont insérées (à la première
15 +exécution, tout l'historique des logs est repris ; aux suivantes, rien).
16 +
17 +Usage : venv/bin/python -m scripts.backfill_api_requests
18 +"""
19 +
20 +from __future__ import annotations
21 +
22 +import datetime
23 +import json
24 +
25 +from sqlalchemy import func, select
26 +
27 +from src.api.reqstats import normalize_endpoint
28 +from src.config import get_settings
29 +from src.database.db import init_db, session_scope
30 +from src.database.models import ApiRequest
31 +from src.utils.logger import get_logger
32 +
33 +
34 +def main() -> None:
35 + logger = get_logger("apika.backfill_requests")
36 + init_db()
37 + settings = get_settings()
38 +
39 + with session_scope() as session:
40 + cutoff = session.execute(select(func.min(ApiRequest.ts))).scalar()
41 + if cutoff is not None and cutoff.tzinfo is None:
42 + cutoff = cutoff.replace(tzinfo=datetime.UTC)
43 + if cutoff is None:
44 + cutoff = datetime.datetime.now(tz=datetime.UTC)
45 +
46 + entries: list[dict] = []
47 + parsed = skipped = 0
48 + for log_file in sorted(settings.logs_dir.glob("apika.log*")):
49 + with open(log_file, encoding="utf-8") as fh:
50 + for line in fh:
51 + line = line.strip()
52 + if not line or '"http_request"' not in line:
53 + continue
54 + try:
55 + rec = json.loads(line)
56 + except json.JSONDecodeError:
57 + continue
58 + if rec.get("message") != "http_request":
59 + continue
60 + parsed += 1
61 + try:
62 + ts = datetime.datetime.fromisoformat(rec["timestamp"])
63 + except (KeyError, ValueError):
64 + skipped += 1
65 + continue
66 + if ts.tzinfo is None:
67 + ts = ts.replace(tzinfo=datetime.UTC)
68 + if ts >= cutoff:
69 + skipped += 1
70 + continue
71 + entries.append(
72 + {
73 + "ts": ts,
74 + "method": rec.get("method", "GET"),
75 + "endpoint": normalize_endpoint(rec.get("path", "(autre)")),
76 + "status": int(rec.get("status_code", 0)),
77 + "duration_ms": round(float(rec.get("duration_ms", 0.0)), 2),
78 + }
79 + )
80 +
81 + if entries:
82 + with session_scope() as session:
83 + session.bulk_insert_mappings(ApiRequest.__mapper__, entries)
84 +
85 + logger.info(
86 + "Backfill api_requests terminé",
87 + extra={"inserted": len(entries), "parsed": parsed, "skipped": skipped},
88 + )
89 + print(f"Backfill : {len(entries)} requêtes insérées ({parsed} lues, {skipped} ignorées)")
90 +
91 +
92 +if __name__ == "__main__":
93 + main()
added src/api/kapdf.py +568 −0
@@ -0,0 +1,568 @@
1 +# ============================================
2 +# Projet : API-KA
3 +# Fichier : src/api/kapdf.py
4 +# Node : m3u96b
5 +# Author : Simon-Pierre Boucher
6 +# Contact : contact@spboucher.ai
7 +# Date : 2026-08-17
8 +# ============================================
9 +# Auteur : Simon-Pierre Boucher — contact@spboucher.ai
10 +# ka-ui/stats/kapdf.py — moteur PDF commun Groupe KA (fpdf2).
11 +# Consomme le JSON du contrat /api/stats/dashboard (voir SPEC.md) et produit
12 +# le rapport estampillé Groupe-KA : couverture, sommaire, KPI, graphiques
13 +# VECTORIELS (courbes/barres/anneaux), tableaux paginés, records, page de fin.
14 +# Usage :
15 +# from kapdf import GroupeKAReport
16 +# pdf_bytes = GroupeKAReport(site={"wordmark":"Lou·Ka","accent":"#ff6a00",
17 +# "domain":"www.lou-ka.com","tagline":"…"}, dashboard=dash_json,
18 +# mode="complet").build()
19 +# Dépendance : pip install fpdf2 (aucune autre)
20 +from __future__ import annotations
21 +
22 +import math
23 +from datetime import datetime
24 +from zoneinfo import ZoneInfo
25 +
26 +from fpdf import FPDF
27 +
28 +INK = (20, 24, 20)
29 +INK2 = (77, 85, 81)
30 +INK3 = (139, 146, 140)
31 +PAPER = (245, 243, 238)
32 +SURFACE2 = (250, 249, 245)
33 +GREEN = (28, 92, 65)
34 +DANGER = (179, 66, 58)
35 +WHITE = (255, 255, 255)
36 +
37 +EMAILS = [
38 + ("contact@groupe-ka.com", "Projets, partenariats & données"),
39 + ("info@groupe-ka.com", "Médias & questions générales"),
40 + ("admin@groupe-ka.com", "Légal, vie privée & Loi 25"),
41 +]
42 +DISCLAIMER = (
43 + "Groupe KA est un agrégateur de contenu : nous ne vendons rien, ne louons "
44 + "rien et ne sommes partie à aucune transaction. Données lues à la source, "
45 + "rien d'inventé, tout est traçable."
46 +)
47 +
48 +
49 +def _hex(c: str) -> tuple[int, int, int]:
50 + c = c.lstrip("#")
51 + return tuple(int(c[i : i + 2], 16) for i in (0, 2, 4)) # type: ignore
52 +
53 +
54 +def _fr(n) -> str:
55 + if isinstance(n, float) and not n.is_integer():
56 + return f"{n:,.2f}".replace(",", " ").replace(".", ",")
57 + return f"{int(n):,}".replace(",", " ")
58 +
59 +
60 +_SUBST = {
61 + "—": "-", "–": "-", "→": "->", "▲": "+", "▼": "-",
62 + "…": "...", "’": "'", "‘": "'", "“": '"', "”": '"',
63 + "œ": "oe", "Œ": "OE", "−": "-", " ": " ", " ": " ",
64 +}
65 +
66 +
67 +def _latin1(s: str) -> str:
68 + for k, v in _SUBST.items():
69 + s = s.replace(k, v)
70 + return s.encode("latin-1", "replace").decode("latin-1")
71 +
72 +
73 +class _PDF(FPDF):
74 + """FPDF avec en-tête/pied Groupe-KA sur chaque page (sauf couverture).
75 + Les polices core sont latin-1 : normalize_text sanitise en amont."""
76 +
77 + def normalize_text(self, text):
78 + return super().normalize_text(_latin1(text))
79 +
80 + def __init__(self, brand: str, accent: tuple, period_label: str):
81 + super().__init__(orientation="P", unit="mm", format="A4")
82 + self.brand = brand
83 + self.accent = accent
84 + self.period_label = period_label
85 + self.cover_mode = False
86 + self.set_margins(18, 20, 18)
87 + self.set_auto_page_break(True, margin=22)
88 +
89 + def header(self):
90 + if self.cover_mode:
91 + return
92 + self.set_font("helvetica", "B", 8.5)
93 + self.set_text_color(*INK)
94 + self.set_xy(18, 9)
95 + self.cell(0, 5, f"Groupe KA · {self.brand}")
96 + self.set_font("helvetica", "", 8)
97 + self.set_text_color(*INK3)
98 + self.set_xy(18, 9)
99 + self.cell(0, 5, "Rapport statistique", align="R")
100 + self.set_draw_color(*INK)
101 + self.set_line_width(0.5)
102 + self.line(18, 15.5, 192, 15.5)
103 + self.set_y(20)
104 +
105 + def footer(self):
106 + # La page 1 est toujours la couverture : fpdf dessine son pied de page
107 + # au add_page() suivant, quand cover_mode est deja retombe a False.
108 + if self.cover_mode or self.page_no() == 1:
109 + return
110 + self.set_y(-15)
111 + self.set_draw_color(*INK3)
112 + self.set_line_width(0.2)
113 + self.line(18, self.get_y() - 1.5, 192, self.get_y() - 1.5)
114 + self.set_font("helvetica", "", 7.5)
115 + self.set_text_color(*INK3)
116 + year = datetime.now(ZoneInfo("America/Toronto")).year
117 + self.cell(130, 5, f"© Groupe-KA — {year} — groupe-ka.com · {self.period_label}")
118 + self.cell(0, 5, f"p. {self.page_no()}/{{nb}}", align="R")
119 +
120 +
121 +class GroupeKAReport:
122 + def __init__(self, site: dict, dashboard: dict, mode: str = "complet"):
123 + self.site = site
124 + self.d = dashboard
125 + self.mode = mode
126 + self.accent = _hex(site.get("accent", "#d9f26b"))
127 + period = dashboard.get("period", {}) or {}
128 + self.period_label = period.get("label") or "toute la période"
129 + self.pdf = _PDF(site.get("wordmark", ""), self.accent, self.period_label)
130 + self.toc: list[tuple[str, int]] = []
131 +
132 + # ---------- primitives ----------
133 + def _card(self, x, y, w, h, fill=WHITE):
134 + p = self.pdf
135 + p.set_draw_color(*INK)
136 + p.set_line_width(0.45)
137 + p.set_fill_color(*fill)
138 + p.rect(x, y, w, h, style="DF", round_corners=True, corner_radius=2.2)
139 +
140 + def _kicker(self, text):
141 + p = self.pdf
142 + p.set_font("helvetica", "B", 8)
143 + p.set_text_color(*GREEN)
144 + p.set_draw_color(*GREEN)
145 + p.set_line_width(0.6)
146 + y = p.get_y() + 2
147 + p.line(p.l_margin, y, p.l_margin + 7, y)
148 + p.set_xy(p.l_margin + 9, y - 2.5)
149 + p.cell(0, 5, text.upper())
150 + p.ln(8)
151 +
152 + def _section_title(self, title):
153 + if self.pdf.get_y() > 240:
154 + self.pdf.add_page()
155 + self._kicker("Groupe KA · " + self.site.get("wordmark", ""))
156 + self.pdf.set_font("helvetica", "B", 15)
157 + self.pdf.set_text_color(*INK)
158 + self.pdf.set_x(self.pdf.l_margin)
159 + self.pdf.cell(0, 8, title)
160 + self.toc.append((title, self.pdf.page_no()))
161 + self.pdf.ln(11)
162 +
163 + # ---------- pages ----------
164 + def _cover(self):
165 + p = self.pdf
166 + p.cover_mode = True
167 + p.set_auto_page_break(False)
168 + p.add_page()
169 + p.set_fill_color(*PAPER)
170 + p.rect(0, 0, 210, 297, style="F")
171 + p.set_draw_color(*INK)
172 + p.set_line_width(1.0)
173 + p.rect(10, 10, 190, 277)
174 + # kicker
175 + p.set_font("helvetica", "B", 10)
176 + p.set_text_color(*GREEN)
177 + p.set_xy(24, 34)
178 + p.cell(0, 6, "GROUPE KA · RAPPORT STATISTIQUE")
179 + # wordmark : partie gauche + boîte encre/accent
180 + wm = self.site.get("wordmark", "")
181 + left, boxed = (wm.split("·") + [None])[:2] if "·" in wm else (wm, None)
182 + p.set_xy(24, 70)
183 + p.set_font("helvetica", "B", 40)
184 + p.set_text_color(*INK)
185 + p.cell(p.get_string_width(left) + 2, 20, left)
186 + if boxed:
187 + bw = p.get_string_width(boxed) + 12
188 + x = p.get_x() + 2
189 + p.set_fill_color(*INK)
190 + p.rect(x, 68, bw, 22, style="F", round_corners=True, corner_radius=3)
191 + p.set_text_color(*self.accent)
192 + p.set_xy(x + 6, 70)
193 + p.cell(bw - 12, 18, boxed)
194 + p.set_xy(24, 100)
195 + p.set_font("helvetica", "", 13)
196 + p.set_text_color(*INK2)
197 + p.multi_cell(150, 7, f"Rapport statistique — {wm}")
198 + now = datetime.now(ZoneInfo("America/Toronto"))
199 + per = self.d.get("period", {}) or {}
200 + p.set_xy(24, 125)
201 + p.set_font("helvetica", "", 10.5)
202 + rows = [
203 + ("Période couverte", self.period_label + (f" ({per.get('from')} → {per.get('to')})" if per.get("from") else "")),
204 + ("Généré le", now.strftime("%Y-%m-%d à %H:%M") + " (heure de l'Est)"),
205 + ("Plateforme", "https://" + self.site.get("domain", "")),
206 + ("Mode", "Rapport complet" if self.mode == "complet" else "Synthèse"),
207 + ]
208 + y = 128
209 + for k, v in rows:
210 + p.set_xy(24, y)
211 + p.set_text_color(*INK3)
212 + p.cell(40, 6, k)
213 + p.set_text_color(*INK)
214 + p.set_font("helvetica", "B", 10.5)
215 + p.cell(0, 6, str(v))
216 + p.set_font("helvetica", "", 10.5)
217 + y += 8
218 + # bande encre au pied
219 + p.set_fill_color(*INK)
220 + p.rect(10, 262, 190, 25, style="F")
221 + p.set_xy(24, 270)
222 + p.set_font("helvetica", "B", 12)
223 + p.set_text_color(*WHITE)
224 + p.cell(60, 8, "par Groupe ")
225 + p.set_text_color(*self.accent)
226 + p.set_xy(24 + p.get_string_width("par Groupe ") + 1, 270)
227 + p.cell(20, 8, "KA")
228 + p.set_font("helvetica", "B", 10)
229 + p.set_xy(24, 270)
230 + p.set_text_color(*self.accent)
231 + p.cell(162, 8, "groupe-ka.com", align="R")
232 + p.set_auto_page_break(True, margin=22)
233 + p.cover_mode = False
234 +
235 + def _kpis(self):
236 + kpis = self.d.get("kpis") or []
237 + if not kpis:
238 + return
239 + self._section_title("Synthèse des indicateurs")
240 + p = self.pdf
241 + cols, gw, gh, gap = 3, 56, 26, 3
242 + x0, y = p.l_margin, p.get_y()
243 + for i, k in enumerate(kpis[:9]):
244 + x = x0 + (i % cols) * (gw + gap)
245 + if i and i % cols == 0:
246 + y += gh + gap
247 + if y > 250:
248 + p.add_page(); y = p.get_y()
249 + self._card(x, y, gw, gh)
250 + p.set_xy(x + 4, y + 4)
251 + p.set_font("helvetica", "B", 14)
252 + p.set_text_color(*INK)
253 + val = k.get("value")
254 + p.cell(gw - 8, 7, (_fr(val) if isinstance(val, (int, float)) else str(val)) + (" " + k["unit"] if k.get("unit") else ""))
255 + p.set_xy(x + 4, y + 12)
256 + p.set_font("helvetica", "", 7.6)
257 + p.set_text_color(*INK2)
258 + p.multi_cell(gw - 8, 3.6, str(k.get("label", ""))[:70])
259 + if k.get("delta_pct") is not None:
260 + up = (k.get("direction") or ("up" if k["delta_pct"] >= 0 else "down")) == "up"
261 + p.set_xy(x + 4, y + gh - 6.5)
262 + p.set_font("helvetica", "B", 8)
263 + p.set_text_color(*(GREEN if up else DANGER))
264 + arrow = "+" if k["delta_pct"] >= 0 else ""
265 + p.cell(gw - 8, 4, f"{'▲' if up else '▼'} {arrow}{str(k['delta_pct']).replace('.', ',')} % vs période préc.")
266 + p.set_y(y + gh + 8)
267 +
268 + def _line_chart(self, s):
269 + p = self.pdf
270 + pts = s.get("points") or []
271 + if len(pts) < 2:
272 + return
273 + if p.get_y() > 200:
274 + p.add_page()
275 + p.set_font("helvetica", "B", 10)
276 + p.set_text_color(*INK)
277 + p.cell(0, 6, s.get("title", ""))
278 + p.ln(7)
279 + x0, y0, w, h = p.l_margin, p.get_y(), 174, 52
280 + self._card(x0, y0, w, h, fill=WHITE)
281 + cx, cy, cw, ch = x0 + 12, y0 + 6, w - 20, h - 16
282 + vals = [pt["v"] for pt in pts] + [c["v"] for c in (s.get("compare") or [])]
283 + vmax = max(vals) or 1
284 + vmin = min(0, min(vals))
285 + rng = (vmax - vmin) or 1
286 + # grille + graduations
287 + p.set_font("helvetica", "", 6.3)
288 + p.set_text_color(*INK3)
289 + p.set_draw_color(200, 200, 195)
290 + p.set_line_width(0.15)
291 + for g in range(5):
292 + gy = cy + ch - ch * g / 4
293 + p.line(cx, gy, cx + cw, gy)
294 + p.set_xy(x0 + 1, gy - 1.6)
295 + p.cell(10, 3, _fr(vmin + rng * g / 4), align="R")
296 +
297 + def draw(series, color, width, dash=None):
298 + n = len(series)
299 + p.set_draw_color(*color)
300 + p.set_line_width(width)
301 + if dash:
302 + p.set_dash_pattern(dash=1.2, gap=1.2)
303 + last = None
304 + for i, pt in enumerate(series):
305 + px = cx + cw * (i / (n - 1))
306 + py = cy + ch - ch * ((pt["v"] - vmin) / rng)
307 + if last:
308 + p.line(last[0], last[1], px, py)
309 + last = (px, py)
310 + p.set_dash_pattern()
311 +
312 + if s.get("compare"):
313 + draw(s["compare"], INK3, 0.35, dash=True)
314 + draw(pts, self.accent, 0.7)
315 + # libellés d'axe X (premier / milieu / dernier)
316 + p.set_text_color(*INK3)
317 + for frac, idx in ((0, 0), (0.5, len(pts) // 2), (1, -1)):
318 + p.set_xy(cx + cw * frac - 9, cy + ch + 1.5)
319 + p.cell(18, 3, str(pts[idx].get("t", ""))[:10], align="C")
320 + p.set_y(y0 + h + 4)
321 + if s.get("compare"):
322 + p.set_font("helvetica", "", 6.8)
323 + p.set_text_color(*INK3)
324 + p.cell(0, 4, "— période courante (accent) · ---- période comparée")
325 + p.ln(6)
326 + else:
327 + p.ln(2)
328 +
329 + def _bars(self, title, items, unit=""):
330 + p = self.pdf
331 + items = [it for it in (items or []) if isinstance(it.get("value"), (int, float))][:12]
332 + if not items:
333 + return
334 + need = 10 + len(items) * 7
335 + if p.get_y() + need > 265:
336 + p.add_page()
337 + p.set_font("helvetica", "B", 10)
338 + p.set_text_color(*INK)
339 + p.cell(0, 6, title)
340 + p.ln(8)
341 + vmax = max(it["value"] for it in items) or 1
342 + for it in items:
343 + y = p.get_y()
344 + p.set_font("helvetica", "", 7.6)
345 + p.set_text_color(*INK)
346 + p.set_x(p.l_margin)
347 + p.cell(46, 5, str(it["label"])[:34])
348 + bw = 96 * (it["value"] / vmax)
349 + p.set_fill_color(*self.accent)
350 + p.set_draw_color(*INK)
351 + p.set_line_width(0.25)
352 + p.rect(p.l_margin + 48, y + 0.7, max(bw, 0.8), 3.6, style="DF")
353 + p.set_xy(p.l_margin + 148, y)
354 + p.set_font("helvetica", "B", 7.6)
355 + p.cell(26, 5, _fr(it["value"]) + (" " + unit if unit else ""), align="R")
356 + p.ln(6.4)
357 + p.ln(3)
358 +
359 + def _donut(self, b):
360 + # anneau vectoriel simple (arcs) + légende
361 + p = self.pdf
362 + items = [it for it in (b.get("items") or []) if it.get("value")][:8]
363 + total = sum(it["value"] for it in items)
364 + if not items or not total:
365 + return
366 + if p.get_y() > 210:
367 + p.add_page()
368 + p.set_font("helvetica", "B", 10)
369 + p.set_text_color(*INK)
370 + p.cell(0, 6, b.get("title", ""))
371 + p.ln(8)
372 + cx, cy, r = p.l_margin + 26, p.get_y() + 24, 20
373 + shades = [1.0, 0.78, 0.58, 0.42, 0.30, 0.22, 0.15, 0.10]
374 + start = -90.0
375 + for i, it in enumerate(items):
376 + frac = it["value"] / total
377 + f = shades[i % len(shades)]
378 + col = tuple(int(PAPER[j] + (self.accent[j] - PAPER[j]) * f) for j in range(3))
379 + steps = max(2, int(72 * frac))
380 + p.set_fill_color(*col)
381 + p.set_draw_color(*col)
382 + for st in range(steps):
383 + a0 = math.radians(start + 360 * frac * st / steps)
384 + a1 = math.radians(start + 360 * frac * (st + 1) / steps)
385 + p.polygon(
386 + [(cx, cy),
387 + (cx + r * math.cos(a0), cy + r * math.sin(a0)),
388 + (cx + r * math.cos(a1), cy + r * math.sin(a1))],
389 + style="DF",
390 + )
391 + start += 360 * frac
392 + p.set_fill_color(*WHITE)
393 + p.set_draw_color(*INK)
394 + p.set_line_width(0.4)
395 + p.ellipse(cx - 11, cy - 11, 22, 22, style="DF")
396 + p.ellipse(cx - r, cy - r, 2 * r, 2 * r, style="D")
397 + # légende
398 + ly = cy - 22
399 + for i, it in enumerate(items):
400 + f = shades[i % len(shades)]
401 + col = tuple(int(PAPER[j] + (self.accent[j] - PAPER[j]) * f) for j in range(3))
402 + p.set_fill_color(*col)
403 + p.set_draw_color(*INK)
404 + p.rect(p.l_margin + 60, ly + 0.8, 4, 4, style="DF")
405 + p.set_xy(p.l_margin + 66, ly)
406 + p.set_font("helvetica", "", 7.6)
407 + p.set_text_color(*INK)
408 + pct = 100 * it["value"] / total
409 + p.cell(0, 5.6, f"{str(it['label'])[:40]} — {_fr(it['value'])} ({pct:.1f} %)".replace(".", ","))
410 + ly += 5.6
411 + p.set_y(max(cy + r, ly) + 6)
412 +
413 + def _table(self, t):
414 + p = self.pdf
415 + cols = t.get("columns") or []
416 + rows = t.get("rows") or []
417 + if not cols or not rows:
418 + return
419 + self._section_title(t.get("title", "Tableau"))
420 + w = 174 / len(cols)
421 + def head():
422 + p.set_font("helvetica", "B", 7.6)
423 + p.set_fill_color(*INK)
424 + p.set_text_color(*WHITE)
425 + for c in cols:
426 + p.cell(w, 6, " " + str(c)[:30], fill=True)
427 + p.ln(6)
428 + head()
429 + p.set_text_color(*INK)
430 + for i, row in enumerate(rows[:200]):
431 + if p.get_y() > 262:
432 + p.add_page()
433 + head()
434 + p.set_text_color(*INK)
435 + p.set_font("helvetica", "", 7.4)
436 + p.set_fill_color(*(SURFACE2 if i % 2 else WHITE))
437 + for cell in row:
438 + txt = _fr(cell) if isinstance(cell, (int, float)) else str(cell)
439 + p.cell(w, 5.4, " " + txt[:34], fill=True)
440 + p.ln(5.4)
441 + if len(rows) > 200:
442 + p.set_font("helvetica", "", 7)
443 + p.set_text_color(*INK3)
444 + p.cell(0, 5, f"… {len(rows) - 200} lignes supplémentaires non imprimées")
445 + p.ln(6)
446 +
447 + def _records(self):
448 + recs = self.d.get("records") or []
449 + if not recs:
450 + return
451 + self._section_title("Records & faits marquants")
452 + p = self.pdf
453 + for r in recs[:10]:
454 + if p.get_y() > 258:
455 + p.add_page()
456 + y = p.get_y()
457 + self._card(p.l_margin, y, 174, 11, fill=SURFACE2)
458 + p.set_xy(p.l_margin + 4, y + 2)
459 + p.set_font("helvetica", "", 8.6)
460 + p.set_text_color(*INK2)
461 + p.cell(96, 7, str(r.get("label", ""))[:70])
462 + p.set_font("helvetica", "B", 9)
463 + p.set_text_color(*INK)
464 + p.cell(52, 7, str(r.get("value", ""))[:36], align="R")
465 + p.set_font("helvetica", "", 7.6)
466 + p.set_text_color(*INK3)
467 + p.cell(20, 7, str(r.get("date", "") or ""), align="R")
468 + p.set_y(y + 13.5)
469 + p.ln(4)
470 +
471 + def _final_page(self):
472 + p = self.pdf
473 + p.add_page()
474 + self._kicker("Groupe KA · contact")
475 + p.set_font("helvetica", "B", 15)
476 + p.set_text_color(*INK)
477 + p.cell(0, 8, "Coordonnées du Groupe KA")
478 + p.ln(12)
479 + for email, role in EMAILS:
480 + p.set_font("helvetica", "B", 10.5)
481 + p.set_text_color(*INK)
482 + p.cell(0, 6, email)
483 + p.ln(5.5)
484 + p.set_font("helvetica", "", 8.6)
485 + p.set_text_color(*INK3)
486 + p.cell(0, 5, role)
487 + p.ln(8)
488 + p.ln(2)
489 + p.set_font("helvetica", "B", 10)
490 + p.set_text_color(*GREEN)
491 + p.cell(0, 6, "groupe-ka.com — le portail de l'écosystème ·Ka")
492 + p.ln(10)
493 + p.set_draw_color(*self.accent)
494 + p.set_line_width(0.8)
495 + p.line(p.l_margin, p.get_y(), p.l_margin + 30, p.get_y())
496 + p.ln(4)
497 + p.set_font("helvetica", "", 8.6)
498 + p.set_text_color(*INK2)
499 + p.multi_cell(160, 4.6, DISCLAIMER)
500 + p.ln(4)
501 + p.set_font("helvetica", "", 7.6)
502 + p.set_text_color(*INK3)
503 + p.multi_cell(
504 + 160, 4.2,
505 + "Mentions : rapport généré automatiquement à partir des données réelles de la "
506 + "plateforme au moment indiqué en couverture. Conditions d'utilisation, politique "
507 + "de confidentialité et protection des renseignements personnels (Loi 25) : "
508 + "groupe-ka.com/conditions · /confidentialite · /loi-25.",
509 + )
510 +
511 + def _toc_page(self):
512 + # insérée après coup ? fpdf ne réordonne pas : on écrit le sommaire en
513 + # page 2 en réservant la page lors du build (voir build()).
514 + pass
515 +
516 + def build(self) -> bytes:
517 + p = self.pdf
518 + p.alias_nb_pages()
519 + self._cover()
520 + if self.mode == "synthese":
521 + p.add_page()
522 + self._kpis()
523 + self._records()
524 + self._final_page()
525 + else:
526 + p.add_page()
527 + toc_page_no = p.page_no()
528 + p.add_page()
529 + self._kpis()
530 + for s in self.d.get("series") or []:
531 + if s.get("kind") == "bar":
532 + self._bars(s.get("title", ""), [{"label": pt.get("t"), "value": pt.get("v")} for pt in (s.get("points") or [])], s.get("unit", ""))
533 + else:
534 + self._line_chart(s)
535 + for b in self.d.get("breakdowns") or []:
536 + if b.get("kind") == "donut":
537 + self._donut(b)
538 + else:
539 + self._bars(b.get("title", ""), b.get("items"))
540 + geo = self.d.get("geo")
541 + if geo:
542 + self._bars(geo.get("title", "Répartition géographique"), geo.get("items"))
543 + for t in self.d.get("tables") or []:
544 + self._table(t)
545 + self._records()
546 + self._final_page()
547 + # sommaire écrit sur la page réservée (page 2)
548 + last_page = p.page
549 + p.page = toc_page_no
550 + p.set_y(22)
551 + p.set_font("helvetica", "B", 15)
552 + p.set_text_color(*INK)
553 + p.cell(0, 8, "Sommaire")
554 + p.ln(12)
555 + p.set_font("helvetica", "", 9.5)
556 + for title, page_no in self.toc:
557 + p.set_text_color(*INK)
558 + p.cell(140, 6.5, title[:80])
559 + p.set_text_color(*INK3)
560 + p.cell(0, 6.5, str(page_no), align="R")
561 + p.ln(6.5)
562 + p.page = last_page
563 + return bytes(p.output())
564 +
565 +
566 +def filename(platform_id: str, period: str) -> str:
567 + today = datetime.now(ZoneInfo("America/Toronto")).strftime("%Y-%m-%d")
568 + return f"groupe-ka_{platform_id}_stats_{period}_{today}.pdf"
modified src/api/main.py +25 −4
@@ -11,9 +11,10 @@ exposée publiquement uniquement via le tunnel ngrok www.api-ka.com."""
11 11
12 12 from __future__ import annotations
13 13
14 +import asyncio
14 15 import json
15 16 from collections.abc import AsyncIterator
16 −from contextlib import asynccontextmanager
17 +from contextlib import asynccontextmanager, suppress
17 18 from pathlib import Path
18 19 from typing import Any
19 20
@@ -21,9 +22,10 @@ from fastapi import FastAPI, Request
21 22 from fastapi.responses import FileResponse
22 23 from fastapi.staticfiles import StaticFiles
23 24
25 +from src.api import reqstats
24 26 from src.api.middleware.logging import RequestLoggingMiddleware
25 27 from src.api.middleware.ratelimit import RateLimitMiddleware
26 −from src.api.routes import auth, envelope, health, runs, services
28 +from src.api.routes import auth, envelope, health, runs, services, stats
27 29 from src.config import SERVICES, get_settings, verify_node
28 30 from src.database.db import init_db
29 31 from src.utils.logger import get_logger
@@ -33,14 +35,21 @@ VERSION = "1.0.0"
33 35
34 36 @asynccontextmanager
35 37 async def lifespan(app: FastAPI) -> AsyncIterator[None]:
36 − """Au démarrage : vérifie le node m3u96b et initialise le schéma DB."""
38 + """Au démarrage : vérifie le node m3u96b, initialise le schéma DB et lance
39 + la tâche de fond qui persiste le journal léger des requêtes (/stats)."""
37 40 verify_node()
38 41 init_db()
39 42 get_logger("apika.api").info(
40 43 "API-KA démarrée",
41 44 extra={"version": VERSION, "node": get_settings().node_name},
42 45 )
43 − yield
46 + flusher = asyncio.create_task(reqstats.flusher_task())
47 + try:
48 + yield
49 + finally:
50 + flusher.cancel()
51 + with suppress(asyncio.CancelledError):
52 + await flusher
44 53
45 54
46 55 app = FastAPI(
@@ -63,12 +72,14 @@ app.add_middleware(RequestLoggingMiddleware)
63 72 app.include_router(health.router)
64 73 app.include_router(auth.router)
65 74 app.include_router(runs.router)
75 +app.include_router(stats.router)
66 76 app.include_router(services.router)
67 77
68 78
69 79 WEB_DIR = Path(__file__).resolve().parent / "web"
70 80 WEB_INDEX = WEB_DIR / "index.html"
71 81 WEB_CONTACT = WEB_DIR / "contact.html"
82 +WEB_STATS = WEB_DIR / "stats.html"
72 83 KA_DIR = WEB_DIR / "ka"
73 84
74 85 # Package ka-ui vendorisé (tokens.css, ecosystem.json, ka-shell.js) — servi
@@ -119,6 +130,16 @@ def contact(request: Request) -> Any:
119 130 )
120 131
121 132
133 +@app.get("/stats", tags=["root"], include_in_schema=False)
134 +def stats_page() -> FileResponse:
135 + """Page /stats — tableau de bord analytique de la plateforme (HTML statique).
136 +
137 + Les données proviennent de GET /api/stats/dashboard ; l'export PDF de
138 + GET /api/stats/report (gabarit Groupe-KA).
139 + """
140 + return FileResponse(WEB_STATS, media_type="text/html")
141 +
142 +
122 143 # Assets de marque Groupe KA servis à la racine du domaine (voir src/api/web/) :
123 144 # favicon SVG, icône iOS et image Open Graph 1200x630 referencée par les meta og:image.
124 145 @app.get("/favicon.svg", include_in_schema=False)
modified src/api/middleware/logging.py +14 −0
@@ -10,12 +10,14 @@
10 10
11 11 from __future__ import annotations
12 12
13 +import datetime
13 14 import time
14 15
15 16 from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
16 17 from starlette.requests import Request
17 18 from starlette.responses import Response
18 19
20 +from src.api import reqstats
19 21 from src.utils.logger import get_logger
20 22
21 23
@@ -28,6 +30,18 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
28 30 start = time.perf_counter()
29 31 response = await call_next(request)
30 32 duration_ms = round((time.perf_counter() - start) * 1000, 2)
33 + # Journalisation légère pour /stats : simple append en mémoire (O(1),
34 + # aucune I/O ici) — la persistance se fait en lot par la tâche de fond.
35 + try:
36 + reqstats.record(
37 + ts=datetime.datetime.now(tz=datetime.UTC),
38 + method=request.method,
39 + path=request.url.path,
40 + status=response.status_code,
41 + duration_ms=duration_ms,
42 + )
43 + except Exception: # pragma: no cover — jamais bloquant pour l'API
44 + pass
31 45 get_logger("apika.api").info(
32 46 "http_request",
33 47 extra={
added src/api/reqstats.py +164 −0
@@ -0,0 +1,164 @@
1 +# ============================================
2 +# Projet : API-KA
3 +# Fichier : src/api/reqstats.py
4 +# Node : m3u96b
5 +# Author : Simon-Pierre Boucher
6 +# Contact : contact@spboucher.ai
7 +# Date : 2026-08-17
8 +# ============================================
9 +"""Journalisation légère des requêtes API vers la table ``api_requests``.
10 +
11 +Conçu pour ne JAMAIS ralentir le chemin de requête : le middleware appelle
12 +``record()`` (un simple ``deque.append``, O(1), sans I/O) et une tâche de
13 +fond (démarrée dans le lifespan de l'app) vide le tampon en lot toutes les
14 +``FLUSH_INTERVAL`` secondes via un thread, hors boucle d'événements.
15 +
16 +Rétention : ``RETENTION_DAYS`` jours — une purge s'exécute au plus une fois
17 +par jour lors d'un flush. Alimente exclusivement la page /stats.
18 +"""
19 +
20 +from __future__ import annotations
21 +
22 +import asyncio
23 +import datetime
24 +import threading
25 +from collections import deque
26 +
27 +from src.config import SERVICES
28 +from src.utils.logger import get_logger
29 +
30 +FLUSH_INTERVAL = 5.0 # secondes entre deux vidages du tampon
31 +MAX_BUFFER = 10_000 # garde-fou mémoire : au-delà, les plus anciens sont perdus
32 +RETENTION_DAYS = 90
33 +
34 +_buffer: deque[dict] = deque(maxlen=MAX_BUFFER)
35 +_lock = threading.Lock()
36 +_last_purge: datetime.date | None = None
37 +
38 +# Chemins statiques connus, conservés tels quels dans la colonne ``endpoint``.
39 +_KNOWN_PATHS = frozenset(
40 + {
41 + "/",
42 + "/health",
43 + "/contact",
44 + "/stats",
45 + "/docs",
46 + "/redoc",
47 + "/openapi.json",
48 + "/favicon.svg",
49 + "/apple-touch-icon.png",
50 + "/og.png",
51 + "/api/v1/runs",
52 + "/api/stats/dashboard",
53 + "/api/stats/report",
54 + }
55 +)
56 +_SERVICE_SUBROUTES = frozenset({"latest", "stats"})
57 +
58 +
59 +def normalize_endpoint(path: str) -> str:
60 + """Replie un chemin de requête vers un endpoint à cardinalité bornée.
61 +
62 + Les paramètres de route (dates) sont remplacés par des gabarits, les
63 + assets statiques /ka/* sont agrégés et les chemins inconnus (scans de
64 + bots, 404) sont regroupés sous « (autre) ».
65 + """
66 + path = path.rstrip("/") or "/"
67 + if path in _KNOWN_PATHS:
68 + return path
69 + if path.startswith("/ka/"):
70 + return "/ka/*"
71 + if path.startswith("/api/v1/"):
72 + parts = path.split("/") # ['', 'api', 'v1', service, ...]
73 + service = parts[3] if len(parts) > 3 else ""
74 + if service in SERVICES:
75 + if len(parts) == 4:
76 + return f"/api/v1/{service}"
77 + sub = parts[4]
78 + if sub == "date":
79 + return f"/api/v1/{service}/date/{{date}}"
80 + if sub in _SERVICE_SUBROUTES and len(parts) == 5:
81 + return f"/api/v1/{service}/{sub}"
82 + return "/api/v1/(autre)"
83 + return "(autre)"
84 +
85 +
86 +def record(
87 + ts: datetime.datetime, method: str, path: str, status: int, duration_ms: float
88 +) -> None:
89 + """Empile une requête dans le tampon mémoire (non bloquant, jamais d'I/O)."""
90 + entry = {
91 + "ts": ts,
92 + "method": method,
93 + "endpoint": normalize_endpoint(path),
94 + "status": int(status),
95 + "duration_ms": round(float(duration_ms), 2),
96 + }
97 + with _lock:
98 + _buffer.append(entry)
99 +
100 +
101 +def _drain() -> list[dict]:
102 + """Vide le tampon et retourne son contenu."""
103 + with _lock:
104 + entries = list(_buffer)
105 + _buffer.clear()
106 + return entries
107 +
108 +
109 +def flush() -> int:
110 + """Insère en lot le contenu du tampon dans ``api_requests`` (synchrone).
111 +
112 + Appelée depuis un thread par la tâche de fond ; purge les lignes plus
113 + vieilles que ``RETENTION_DAYS`` jours au plus une fois par jour.
114 + """
115 + global _last_purge
116 + entries = _drain()
117 + if not entries:
118 + _maybe_purge()
119 + return 0
120 + try:
121 + from src.database.db import session_scope
122 + from src.database.models import ApiRequest
123 +
124 + with session_scope() as session:
125 + session.bulk_insert_mappings(ApiRequest.__mapper__, entries)
126 + except Exception: # pragma: no cover — la stat ne doit jamais casser l'API
127 + get_logger("apika.reqstats").exception("Échec du flush api_requests")
128 + return 0
129 + _maybe_purge()
130 + return len(entries)
131 +
132 +
133 +def _maybe_purge() -> None:
134 + """Purge les requêtes plus vieilles que RETENTION_DAYS (1 fois/jour max)."""
135 + global _last_purge
136 + today = datetime.datetime.now(tz=datetime.UTC).date()
137 + if _last_purge == today:
138 + return
139 + _last_purge = today
140 + try:
141 + from sqlalchemy import delete
142 +
143 + from src.database.db import session_scope
144 + from src.database.models import ApiRequest
145 +
146 + cutoff = datetime.datetime.now(tz=datetime.UTC) - datetime.timedelta(
147 + days=RETENTION_DAYS
148 + )
149 + with session_scope() as session:
150 + session.execute(delete(ApiRequest).where(ApiRequest.ts < cutoff))
151 + except Exception: # pragma: no cover
152 + get_logger("apika.reqstats").exception("Échec de la purge api_requests")
153 +
154 +
155 +async def flusher_task() -> None:
156 + """Tâche de fond : flush périodique du tampon, hors event loop (thread)."""
157 + try:
158 + while True:
159 + await asyncio.sleep(FLUSH_INTERVAL)
160 + await asyncio.to_thread(flush)
161 + except asyncio.CancelledError:
162 + # Dernier flush au shutdown pour ne rien perdre.
163 + await asyncio.to_thread(flush)
164 + raise
added src/api/routes/stats.py +580 −0
@@ -0,0 +1,580 @@
1 +# ============================================
2 +# Projet : API-KA
3 +# Fichier : src/api/routes/stats.py
4 +# Node : m3u96b
5 +# Author : Simon-Pierre Boucher
6 +# Contact : contact@spboucher.ai
7 +# Date : 2026-08-17
8 +# ============================================
9 +"""Routes /api/stats : tableau de bord analytique de la plateforme + rapport PDF.
10 +
11 +Contrat commun Groupe KA (src/api/web/ka/stats/SPEC.md) :
12 +- ``GET /api/stats/dashboard?period=…`` → JSON (KPI, séries, répartitions,
13 + heatmap, tableaux, records) calculé depuis les données réelles :
14 + table ``api_requests`` (journal du middleware) et ``collection_runs``.
15 +- ``GET /api/stats/report?period=…&mode=complet|synthese`` → PDF Groupe-KA.
16 +
17 +Cache serveur : 5 minutes par période. Aucune stat inventée : une section
18 +sans données est simplement absente (le front affiche « Pas encore mesuré »).
19 +"""
20 +
21 +from __future__ import annotations
22 +
23 +import datetime
24 +import threading
25 +import time
26 +from typing import Any
27 +from zoneinfo import ZoneInfo
28 +
29 +from fastapi import APIRouter, Depends, HTTPException, Query, Response
30 +from sqlalchemy import func, select
31 +from sqlalchemy.orm import Session
32 +
33 +from src.api import kapdf
34 +from src.api.routes import envelope
35 +from src.database.db import get_db
36 +from src.database.models import ApiRequest, CollectionRun
37 +
38 +router = APIRouter(prefix="/api/stats", tags=["stats"])
39 +
40 +TZ = ZoneInfo("America/Toronto")
41 +CACHE_TTL = 300.0 # ≥ 5 min (SPEC)
42 +PLATFORM_ID = "api-ka"
43 +
44 +SITE = {
45 + "wordmark": "API·Ka",
46 + "accent": "#3b5bdb",
47 + "domain": "www.api-ka.com",
48 + "tagline": "Plateforme centrale de l'écosystème Groupe KA",
49 +}
50 +
51 +SERVICE_NAMES = {
52 + "louka": "Lou·Ka",
53 + "immoka": "Immo·Ka",
54 + "foodka": "Food·Ka",
55 + "autoka": "Auto·Ka",
56 + "fabrika": "Fabri·Ka",
57 + "restoka": "Resto·Ka",
58 + "sortika": "Sorti·Ka",
59 + "creaka": "Créa·Ka",
60 +}
61 +
62 +PERIOD_LABELS = {
63 + "auj": "aujourd'hui",
64 + "7j": "7 jours",
65 + "30j": "30 jours",
66 + "3m": "3 mois",
67 + "6m": "6 mois",
68 + "12m": "12 mois",
69 + "annee": "année en cours",
70 + "tout": "toute la période",
71 +}
72 +PERIOD_DAYS = {"7j": 7, "30j": 30, "3m": 91, "6m": 182, "12m": 365}
73 +
74 +_cache: dict[tuple, tuple[float, dict]] = {}
75 +_cache_lock = threading.Lock()
76 +
77 +
78 +# ---------------------------------------------------------------- périodes
79 +def _resolve_period(
80 + period: str,
81 + date_from: datetime.date | None,
82 + date_to: datetime.date | None,
83 + db: Session,
84 +) -> tuple[datetime.date, datetime.date, str]:
85 + """Résout (from, to, label) en dates locales America/Toronto."""
86 + today = datetime.datetime.now(tz=TZ).date()
87 + if date_from and date_to:
88 + if date_from > date_to:
89 + raise HTTPException(status_code=422, detail="from doit précéder to")
90 + return date_from, date_to, f"du {date_from} au {date_to}"
91 + if period == "auj":
92 + return today, today, PERIOD_LABELS["auj"]
93 + if period == "annee":
94 + return datetime.date(today.year, 1, 1), today, PERIOD_LABELS["annee"]
95 + if period == "tout":
96 + firsts = [
97 + db.execute(select(func.min(ApiRequest.ts))).scalar(),
98 + db.execute(select(func.min(CollectionRun.started_at))).scalar(),
99 + ]
100 + dates = []
101 + for f in firsts:
102 + if f is not None:
103 + if f.tzinfo is None:
104 + f = f.replace(tzinfo=datetime.UTC)
105 + dates.append(f.astimezone(TZ).date())
106 + return (min(dates) if dates else today), today, PERIOD_LABELS["tout"]
107 + if period in PERIOD_DAYS:
108 + return (
109 + today - datetime.timedelta(days=PERIOD_DAYS[period] - 1),
110 + today,
111 + PERIOD_LABELS[period],
112 + )
113 + raise HTTPException(
114 + status_code=422,
115 + detail=f"Période invalide : {period}. Valides : {', '.join(PERIOD_LABELS)}",
116 + )
117 +
118 +
119 +def _utc_bounds(
120 + d_from: datetime.date, d_to: datetime.date
121 +) -> tuple[datetime.datetime, datetime.datetime]:
122 + """Bornes UTC [00:00 from, 24:00 to] exprimées depuis les dates locales."""
123 + start = datetime.datetime.combine(d_from, datetime.time.min, tzinfo=TZ)
124 + end = datetime.datetime.combine(
125 + d_to + datetime.timedelta(days=1), datetime.time.min, tzinfo=TZ
126 + )
127 + return start.astimezone(datetime.UTC), end.astimezone(datetime.UTC)
128 +
129 +
130 +# ---------------------------------------------------------------- agrégats
131 +def _fetch_requests(
132 + db: Session, d_from: datetime.date, d_to: datetime.date
133 +) -> list[tuple[datetime.datetime, str, int, float]]:
134 + """Requêtes API de la fenêtre : (ts local, endpoint, status, duration_ms)."""
135 + lo, hi = _utc_bounds(d_from, d_to)
136 + rows = db.execute(
137 + select(
138 + ApiRequest.ts, ApiRequest.endpoint, ApiRequest.status, ApiRequest.duration_ms
139 + ).where(ApiRequest.ts >= lo, ApiRequest.ts < hi)
140 + ).all()
141 + out = []
142 + for ts, endpoint, status, duration in rows:
143 + if ts.tzinfo is None:
144 + ts = ts.replace(tzinfo=datetime.UTC)
145 + out.append((ts.astimezone(TZ), endpoint, status, duration or 0.0))
146 + return out
147 +
148 +
149 +def _fetch_runs(
150 + db: Session, d_from: datetime.date, d_to: datetime.date
151 +) -> list[CollectionRun]:
152 + """Runs de collecte de la fenêtre (par date logique ``date_key``)."""
153 + return (
154 + db.execute(
155 + select(CollectionRun)
156 + .where(CollectionRun.date_key >= d_from, CollectionRun.date_key <= d_to)
157 + .order_by(CollectionRun.started_at.desc())
158 + )
159 + .scalars()
160 + .all()
161 + )
162 +
163 +
164 +def _p95(values: list[float]) -> float:
165 + if not values:
166 + return 0.0
167 + vs = sorted(values)
168 + idx = max(0, int(round(0.95 * (len(vs) - 1))))
169 + return vs[idx]
170 +
171 +
172 +def _delta(cur: float, prev: float | None) -> float | None:
173 + if prev is None or prev == 0:
174 + return None
175 + return round((cur - prev) / prev * 100, 1)
176 +
177 +
178 +def _daterange(d_from: datetime.date, d_to: datetime.date) -> list[datetime.date]:
179 + n = (d_to - d_from).days + 1
180 + return [d_from + datetime.timedelta(days=i) for i in range(n)]
181 +
182 +
183 +def _fr_int(n: float) -> str:
184 + return f"{int(n):,}".replace(",", " ")
185 +
186 +
187 +# ---------------------------------------------------------------- dashboard
188 +def _build_dashboard(db: Session, period: str, d_from, d_to, label) -> dict[str, Any]:
189 + """Calcule le JSON complet du contrat SPEC depuis les données réelles."""
190 + hourly = period == "auj" or d_from == d_to
191 + span = (d_to - d_from).days + 1
192 + prev_to = d_from - datetime.timedelta(days=1)
193 + prev_from = prev_to - datetime.timedelta(days=span - 1)
194 +
195 + reqs = _fetch_requests(db, d_from, d_to)
196 + prev_reqs = _fetch_requests(db, prev_from, prev_to)
197 + runs = _fetch_runs(db, d_from, d_to)
198 + prev_runs = _fetch_runs(db, prev_from, prev_to)
199 +
200 + # -------- agrégats requêtes API (période courante)
201 + total_calls = len(reqs)
202 + durations = [r[3] for r in reqs]
203 + avg_ms = round(sum(durations) / total_calls, 2) if total_calls else 0.0
204 + p95_ms = round(_p95(durations), 2)
205 + errors = sum(1 for r in reqs if r[2] >= 400)
206 + err_rate = round(errors / total_calls * 100, 2) if total_calls else 0.0
207 + active_endpoints = len({r[1] for r in reqs})
208 +
209 + # -------- agrégats requêtes API (période précédente, pour les deltas)
210 + prev_calls = len(prev_reqs)
211 + prev_durs = [r[3] for r in prev_reqs]
212 + prev_avg = (sum(prev_durs) / prev_calls) if prev_calls else None
213 + prev_err = (
214 + sum(1 for r in prev_reqs if r[2] >= 400) / prev_calls * 100
215 + if prev_calls
216 + else None
217 + )
218 +
219 + # -------- agrégats runs de collecte
220 + ok_runs = [r for r in runs if r.status in ("success", "retried")]
221 + failed_runs = [r for r in runs if r.status == "failed"]
222 + records_total = sum(r.records_count for r in ok_runs)
223 + prev_ok = [r for r in prev_runs if r.status in ("success", "retried")]
224 + prev_records = sum(r.records_count for r in prev_ok)
225 +
226 + # -------- KPI (uniquement des mesures réelles)
227 + kpis: list[dict[str, Any]] = []
228 +
229 + def kpi(id_, label_, value, unit="", delta=None, invert=False):
230 + d: dict[str, Any] = {"id": id_, "label": label_, "value": value, "unit": unit}
231 + if delta is not None:
232 + d["delta_pct"] = delta
233 + good = (delta <= 0) if invert else (delta >= 0)
234 + d["direction"] = "up" if good else "down"
235 + if invert:
236 + d["invert"] = True
237 + kpis.append(d)
238 +
239 + kpi("calls", "Appels API", total_calls, "", _delta(total_calls, prev_calls))
240 + kpi(
241 + "latency",
242 + "Latence moyenne",
243 + avg_ms,
244 + "ms",
245 + _delta(avg_ms, round(prev_avg, 2) if prev_avg else None),
246 + invert=True,
247 + )
248 + kpi("p95", "Latence p95", p95_ms, "ms")
249 + kpi(
250 + "errors",
251 + "Taux d'erreur (HTTP ≥ 400)",
252 + err_rate,
253 + "%",
254 + _delta(err_rate, round(prev_err, 2) if prev_err else None),
255 + invert=True,
256 + )
257 + kpi("endpoints", "Endpoints actifs", active_endpoints)
258 + kpi(
259 + "runs_ok",
260 + "Collectes réussies",
261 + len(ok_runs),
262 + "",
263 + _delta(len(ok_runs), len(prev_ok) or None),
264 + )
265 + kpi("runs_failed", "Collectes échouées", len(failed_runs), "", invert=True)
266 + kpi(
267 + "records",
268 + "Enregistrements collectés",
269 + records_total,
270 + "",
271 + _delta(records_total, prev_records or None),
272 + )
273 +
274 + # -------- séries temporelles
275 + series: list[dict[str, Any]] = []
276 + days = _daterange(d_from, d_to)
277 +
278 + if hourly:
279 + buckets = [f"{h:02d}h" for h in range(24)]
280 + calls_by = {b: 0 for b in buckets}
281 + lat_by: dict[str, list[float]] = {b: [] for b in buckets}
282 + for ts, _, _, dur in reqs:
283 + b = f"{ts.hour:02d}h"
284 + calls_by[b] += 1
285 + lat_by[b].append(dur)
286 + calls_pts = [{"t": b, "v": calls_by[b]} for b in buckets]
287 + lat_pts = [
288 + {
289 + "t": b,
290 + "v": round(sum(lat_by[b]) / len(lat_by[b]), 1) if lat_by[b] else 0,
291 + }
292 + for b in buckets
293 + ]
294 + calls_title = "Appels API par heure"
295 + lat_title = "Latence moyenne par heure (ms)"
296 + else:
297 + calls_by = {d: 0 for d in days}
298 + lat_by = {d: [] for d in days}
299 + for ts, _, _, dur in reqs:
300 + d = ts.date()
301 + if d in calls_by:
302 + calls_by[d] += 1
303 + lat_by[d].append(dur)
304 + calls_pts = [{"t": d.isoformat(), "v": calls_by[d]} for d in days]
305 + lat_pts = [
306 + {
307 + "t": d.isoformat(),
308 + "v": round(sum(lat_by[d]) / len(lat_by[d]), 1) if lat_by[d] else 0,
309 + }
310 + for d in days
311 + ]
312 + calls_title = "Appels API par jour"
313 + lat_title = "Latence moyenne par jour (ms)"
314 +
315 + calls_serie: dict[str, Any] = {
316 + "id": "calls",
317 + "title": calls_title,
318 + "unit": "appels",
319 + "kind": "line",
320 + "points": calls_pts,
321 + }
322 + if prev_reqs and not hourly:
323 + prev_days = _daterange(prev_from, prev_to)
324 + prev_by = {d: 0 for d in prev_days}
325 + for ts, _, _, _ in prev_reqs:
326 + d = ts.date()
327 + if d in prev_by:
328 + prev_by[d] += 1
329 + calls_serie["compare"] = [
330 + {"t": d.isoformat(), "v": prev_by[d]} for d in prev_days
331 + ]
332 + if reqs:
333 + series.append(calls_serie)
334 + series.append(
335 + {
336 + "id": "latency",
337 + "title": lat_title,
338 + "unit": "ms",
339 + "kind": "line",
340 + "points": lat_pts,
341 + }
342 + )
343 +
344 + if runs and not hourly:
345 + rec_by = {d: 0 for d in days}
346 + for r in ok_runs:
347 + if r.date_key in rec_by:
348 + rec_by[r.date_key] += r.records_count
349 + series.append(
350 + {
351 + "id": "records",
352 + "title": "Enregistrements collectés par jour",
353 + "unit": "enregistrements",
354 + "kind": "line",
355 + "points": [{"t": d.isoformat(), "v": rec_by[d]} for d in days],
356 + }
357 + )
358 +
359 + # -------- répartitions
360 + breakdowns: list[dict[str, Any]] = []
361 + ep_stats: dict[str, dict[str, Any]] = {}
362 + for _, endpoint, status, dur in reqs:
363 + s = ep_stats.setdefault(endpoint, {"calls": 0, "durs": [], "errors": 0})
364 + s["calls"] += 1
365 + s["durs"].append(dur)
366 + if status >= 400:
367 + s["errors"] += 1
368 + top_eps = sorted(ep_stats.items(), key=lambda kv: kv[1]["calls"], reverse=True)
369 + if top_eps:
370 + breakdowns.append(
371 + {
372 + "id": "top_endpoints",
373 + "title": "Top endpoints (appels)",
374 + "kind": "bars",
375 + "items": [
376 + {"label": ep, "value": s["calls"]} for ep, s in top_eps[:12]
377 + ],
378 + }
379 + )
380 + svc_records: dict[str, int] = {}
381 + for r in ok_runs:
382 + svc_records[r.service] = svc_records.get(r.service, 0) + r.records_count
383 + if svc_records:
384 + breakdowns.append(
385 + {
386 + "id": "services",
387 + "title": "Enregistrements collectés par service",
388 + "kind": "donut",
389 + "items": sorted(
390 + (
391 + {"label": SERVICE_NAMES.get(s, s), "value": v}
392 + for s, v in svc_records.items()
393 + ),
394 + key=lambda it: it["value"],
395 + reverse=True,
396 + ),
397 + }
398 + )
399 +
400 + # -------- heatmap : appels API par jour
401 + heatmap = None
402 + if reqs and not hourly:
403 + cells = [
404 + {"date": d.isoformat(), "value": calls_by[d]}
405 + for d in days
406 + if calls_by[d] > 0
407 + ]
408 + if cells:
409 + heatmap = {"title": "Appels API par jour", "cells": cells}
410 +
411 + # -------- tableaux
412 + tables: list[dict[str, Any]] = []
413 + if top_eps:
414 + tables.append(
415 + {
416 + "id": "endpoints",
417 + "title": "Endpoints — appels, latence et erreurs",
418 + "columns": [
419 + "Endpoint",
420 + "Appels",
421 + "Latence moy. (ms)",
422 + "p95 (ms)",
423 + "Erreurs",
424 + "Taux d'erreur",
425 + ],
426 + "rows": [
427 + [
428 + ep,
429 + s["calls"],
430 + round(sum(s["durs"]) / len(s["durs"]), 1),
431 + round(_p95(s["durs"]), 1),
432 + s["errors"],
433 + f"{s['errors'] / s['calls'] * 100:.1f} %".replace(".", ","),
434 + ]
435 + for ep, s in top_eps
436 + ],
437 + }
438 + )
439 + if runs:
440 + tables.append(
441 + {
442 + "id": "runs",
443 + "title": "Derniers runs de collecte",
444 + "columns": ["Service", "Date", "Statut", "Enregistrements", "Durée (s)"],
445 + "rows": [
446 + [
447 + SERVICE_NAMES.get(r.service, r.service),
448 + r.date_key.isoformat(),
449 + {"success": "succès", "failed": "échec", "retried": "relancé"}.get(
450 + r.status, r.status
451 + ),
452 + r.records_count,
453 + round(r.duration_seconds, 1),
454 + ]
455 + for r in runs[:80]
456 + ],
457 + }
458 + )
459 +
460 + # -------- records & faits marquants
461 + records: list[dict[str, Any]] = []
462 + if reqs and not hourly:
463 + best_day = max(calls_by.items(), key=lambda kv: kv[1])
464 + if best_day[1] > 0:
465 + records.append(
466 + {
467 + "label": "Jour record d'appels API",
468 + "value": f"{_fr_int(best_day[1])} appels",
469 + "date": best_day[0].isoformat(),
470 + }
471 + )
472 + if top_eps:
473 + records.append(
474 + {
475 + "label": "Endpoint le plus sollicité",
476 + "value": f"{top_eps[0][0]} — {_fr_int(top_eps[0][1]['calls'])} appels",
477 + }
478 + )
479 + if ok_runs:
480 + biggest = max(ok_runs, key=lambda r: r.records_count)
481 + records.append(
482 + {
483 + "label": "Run de collecte le plus volumineux",
484 + "value": (
485 + f"{_fr_int(biggest.records_count)} enregistrements "
486 + f"({SERVICE_NAMES.get(biggest.service, biggest.service)})"
487 + ),
488 + "date": biggest.date_key.isoformat(),
489 + }
490 + )
491 + fastest = min(ok_runs, key=lambda r: r.duration_seconds)
492 + records.append(
493 + {
494 + "label": "Collecte la plus rapide",
495 + "value": (
496 + f"{fastest.duration_seconds:.1f} s "
497 + f"({SERVICE_NAMES.get(fastest.service, fastest.service)})"
498 + ).replace(".", ","),
499 + "date": fastest.date_key.isoformat(),
500 + }
501 + )
502 +
503 + # -------- couverture de mesure (depuis quand les appels sont journalisés)
504 + first_req = db.execute(select(func.min(ApiRequest.ts))).scalar()
505 + if first_req is not None and first_req.tzinfo is None:
506 + first_req = first_req.replace(tzinfo=datetime.UTC)
507 +
508 + dash: dict[str, Any] = {
509 + "updated": datetime.datetime.now(tz=TZ).isoformat(timespec="seconds"),
510 + "period": {"from": d_from.isoformat(), "to": d_to.isoformat(), "label": label},
511 + "kpis": kpis,
512 + "series": series,
513 + "breakdowns": breakdowns,
514 + "tables": tables,
515 + "records": records,
516 + "coverage": {
517 + "api_requests_since": (
518 + first_req.astimezone(TZ).isoformat(timespec="seconds")
519 + if first_req
520 + else None
521 + )
522 + },
523 + }
524 + if heatmap:
525 + dash["heatmap"] = heatmap
526 + return dash
527 +
528 +
529 +def _dashboard_cached(
530 + db: Session,
531 + period: str,
532 + date_from: datetime.date | None,
533 + date_to: datetime.date | None,
534 +) -> dict[str, Any]:
535 + d_from, d_to, label = _resolve_period(period, date_from, date_to, db)
536 + key = (period, d_from.isoformat(), d_to.isoformat())
537 + now = time.monotonic()
538 + with _cache_lock:
539 + hit = _cache.get(key)
540 + if hit and now - hit[0] < CACHE_TTL:
541 + return hit[1]
542 + dash = _build_dashboard(db, period, d_from, d_to, label)
543 + with _cache_lock:
544 + if len(_cache) > 64:
545 + _cache.clear()
546 + _cache[key] = (now, dash)
547 + return dash
548 +
549 +
550 +# ---------------------------------------------------------------- routes
551 +@router.get("/dashboard")
552 +def stats_dashboard(
553 + period: str = Query("30j", description="auj, 7j, 30j, 3m, 6m, 12m, annee, tout"),
554 + date_from: datetime.date | None = Query(None, alias="from"),
555 + date_to: datetime.date | None = Query(None, alias="to"),
556 + db: Session = Depends(get_db),
557 +) -> dict[str, Any]:
558 + """Tableau de bord analytique de la plateforme (contrat commun Groupe KA)."""
559 + return envelope(_dashboard_cached(db, period, date_from, date_to))
560 +
561 +
562 +@router.get("/report")
563 +def stats_report(
564 + period: str = Query("30j", description="auj, 7j, 30j, 3m, 6m, 12m, annee, tout"),
565 + date_from: datetime.date | None = Query(None, alias="from"),
566 + date_to: datetime.date | None = Query(None, alias="to"),
567 + mode: str = Query("complet", description="complet ou synthese"),
568 + db: Session = Depends(get_db),
569 +) -> Response:
570 + """Rapport statistique PDF estampillé Groupe-KA (complet ou synthèse)."""
571 + if mode not in ("complet", "synthese"):
572 + raise HTTPException(status_code=422, detail="mode : complet ou synthese")
573 + dash = _dashboard_cached(db, period, date_from, date_to)
574 + pdf_bytes = kapdf.GroupeKAReport(site=SITE, dashboard=dash, mode=mode).build()
575 + fname = kapdf.filename(PLATFORM_ID, period)
576 + return Response(
577 + content=pdf_bytes,
578 + media_type="application/pdf",
579 + headers={"Content-Disposition": f'attachment; filename="{fname}"'},
580 + )
modified src/api/web/contact.html +1 −0
@@ -78,6 +78,7 @@ section{padding:64px 0}
78 78 <li><a href="/#services">Services</a></li>
79 79 <li><a href="/#endpoints">Endpoints</a></li>
80 80 <li><a href="/#playground">Playground</a></li>
81 + <li><a href="/stats">Stats</a></li>
81 82 <li><a href="/docs">Swagger</a></li>
82 83 <li><a href="/contact">Contact</a></li>
83 84 </ul>
modified src/api/web/index.html +1 −0
@@ -175,6 +175,7 @@ pre{margin:0;background:var(--ink);color:var(--paper);padding:16px 18px;overflow
175 175 <li><a href="#endpoints">Endpoints</a></li>
176 176 <li><a href="#playground">Playground</a></li>
177 177 <li><a href="#conventions">Conventions</a></li>
178 + <li><a href="/stats">Stats</a></li>
178 179 <li><a href="/docs">Swagger</a></li>
179 180 <li><a href="/contact">Contact</a></li>
180 181 </ul>
added src/api/web/ka/stats/SPEC.md +123 −0
@@ -0,0 +1,123 @@
1 +# ka-stats — module Stats commun Groupe KA (spec v1)
2 +
3 +Contrat partagé par les 12 plateformes pour leurs pages **/stats** (tableau de
4 +bord analytique) et l'**export PDF** estampillé Groupe-KA. Le visuel suit le
5 +design system ka-ui (tokens.css) avec l'accent de la marque.
6 +
7 +## 1. Page /stats — structure obligatoire (dans cet ordre)
8 +
9 +1. **Bandeau KPI** : 4–6 grandes cartes (`KpiCard`) — valeur, libellé,
10 + variation vs période précédente (▲/▼ + %, vert `--green` / rouge `--danger`).
11 +2. **Sélecteur de période global** (`PeriodSelector`) : `aujourd'hui · 7 j ·
12 + 30 j · 3 m · 6 m · 12 m · année en cours · tout` + plage personnalisée
13 + (2 champs date). Toute la page se recalcule (state → refetch dashboard).
14 +3. **Graphiques** : courbes d'évolution (`LineChart`, survol = infobulle,
15 + légende cliquable pour masquer une série, comparaison N vs N-1 en
16 + pointillé), barres (`BarChart`), anneaux (`Donut`), calendrier de chaleur
17 + (`CalendarHeatmap`) quand pertinent.
18 +4. **Répartition géographique** (par ville/région) quand pertinent — barres
19 + horizontales triées (pas besoin de vraie carte).
20 +5. **Tableaux détaillés** (`DataTable`) : tri par colonne, recherche interne,
21 + pagination (25/pg), débordement horizontal propre sur mobile (.tbl-wrap).
22 +6. **Records & faits marquants** : générés depuis les données (jour record,
23 + plus forte croissance, meilleure entrée…) — cartes compactes.
24 +7. **Fraîcheur** : « Mis à jour le {date heure} » + bouton Rafraîchir.
25 +8. **Bouton PDF** bien visible en haut : « Télécharger le rapport PDF » avec
26 + deux choix (Rapport complet / Synthèse 2 pages). Indicateur de progression
27 + si > 2 s.
28 +
29 +Responsive : KPI empilés < 768 px, graphiques pleine largeur redimensionnés
30 +(SVG viewBox), tableaux en défilement horizontal contenu, tactile ≥ 44 px.
31 +AUCUNE donnée inventée : une stat indisponible = bloc « Pas encore mesuré »
32 +(carte grise propre), jamais un faux chiffre.
33 +
34 +## 2. API — contrat commun
35 +
36 +`GET /api/stats/dashboard?period=7j|30j|3m|6m|12m|annee|tout|auj&from=YYYY-MM-DD&to=YYYY-MM-DD`
37 +
38 +```jsonc
39 +{
40 + "updated": "2026-08-17T21:04:00-04:00",
41 + "period": { "from": "2026-07-18", "to": "2026-08-17", "label": "30 jours" },
42 + "kpis": [ { "id": "total", "label": "Annonces actives", "value": 33744,
43 + "unit": "", "delta_pct": 4.2, "direction": "up" } ],
44 + "series": [ { "id": "vol", "title": "Annonces actives par jour", "unit": "annonces",
45 + "kind": "line", "points": [{ "t": "2026-07-18", "v": 31200 }],
46 + "compare": [{ "t": "2025-07-18", "v": 24100 }] } ],
47 + "breakdowns": [ { "id": "types", "title": "Par type", "kind": "donut",
48 + "items": [{ "label": "4½", "value": 9120 }] } ],
49 + "geo": { "title": "Par région", "items": [{ "label": "Montréal", "value": 15680 }] },
50 + "heatmap": { "title": "Activité", "cells": [{ "date": "2026-08-01", "value": 210 }] },
51 + "tables": [ { "id": "top", "title": "Top villes", "columns": ["Ville", "Annonces", "Δ 30 j"],
52 + "rows": [["Montréal", 15680, "+3,1 %"]] } ],
53 + "records": [ { "label": "Jour record d'ajouts", "value": "412 annonces", "date": "2026-08-09" } ]
54 +}
55 +```
56 +
57 +Champs absents = section masquée. Cache serveur recommandé (≥ 5 min par
58 +période). Les valeurs proviennent des données réelles (DB de la plateforme,
59 +journaux de sync des connecteurs, /api/v1/runs d'API-KA…).
60 +
61 +`GET /api/stats/report?period=…&from=&to=&mode=complet|synthese`
62 +→ `application/pdf`, en-tête `Content-Disposition: attachment; filename=
63 +groupe-ka_<plateforme>_stats_<periode>_<YYYY-MM-DD>.pdf`.
64 +
65 +## 3. PDF — gabarit Groupe-KA (implémentations : `kapdf.py` fpdf2 pour les
66 +apps Python ; les apps Next portent le même gabarit en pdfkit)
67 +
68 +- **Couverture** : cadre encre, kicker « GROUPE KA · RAPPORT STATISTIQUE »,
69 + wordmark de la plateforme (boîte encre + accent), sous-titre, période
70 + couverte, date/heure de génération, bande encre au pied avec
71 + « par Groupe KA — groupe-ka.com ».
72 +- **Sommaire** avec numéros de pages (mode complet).
73 +- **KPI** : grille de cartes (bordure encre, valeur en gros, delta coloré).
74 +- **Graphiques VECTORIELS** (dessinés en primitives, jamais de capture) :
75 + courbes, barres, anneaux — accent de la plateforme, axes/graduations encre.
76 +- **Tableaux** paginés proprement (lignes zébrées `--surface-2`, jamais
77 + coupés en deux à cheval sur une ligne).
78 +- **Records** puis **page de fin** : coordonnées Groupe KA (3 courriels +
79 + rôles d'ecosystem.json, groupe-ka.com), avertissement d'agrégateur,
80 + mentions légales courtes.
81 +- **Chaque page** : en-tête discret (« Groupe KA · {Plateforme} », filet
82 + encre) + pied (« © Groupe-KA — {année} — groupe-ka.com · {période} · p. X/Y »).
83 +- A4 portrait, marges 18 mm, typo : Helvetica (fallback sûr) ou fonts TTF du
84 + DS si présentes. Mode « synthese » = couverture + 1 page KPI/records.
85 +
86 +## 4. Spécifique par plateforme (sections métier attendues)
87 +
88 +- **groupe-ka** : tableau de bord maître — consolidation des 12 (volume total,
89 + croissance), classement des plateformes, bloc résumé par plateforme + lien
90 + vers sa page /stats ; « Rapport écosystème complet » = PDF consolidé.
91 +- **lou-ka** : annonces actives/nouvelles/retirées, loyers moyens/médians par
92 + ville & taille, évolution, répartition par type, top villes.
93 +- **immo-ka** : annonces actives/nouvelles/vendues-retirées, prix moyen/médian
94 + par ville/région/type, délai de présence, top villes, tension du marché.
95 +- **vrai-prix** : couverture du rôle (unités, valeur totale), estimations
96 + servies si journalisées, répartitions par municipalité/type, indices marché.
97 +- **auto-ka** : volume par marque/modèle/année/carburant/boîte, prix moyens et
98 + km moyens par segment, top marques/modèles.
99 +- **fabri-ka** : produits par catégorie/région/boutique, fourchettes de prix,
100 + nouveautés par période, top catégories.
101 +- **food-ka** : produits suivis, relevés de prix, soldes détectés (baisses/
102 + hausses, amplitude), top produits en solde, prix moyens par catégorie.
103 +- **resto-ka** : restos par cuisine/ville/gamme, menus & plats, nouveautés/
104 + fermetures détectées, top établissements.
105 +- **sorti-ka** : événements à venir/passés par catégorie/ville, gratuits vs
106 + payants, heatmap calendrier, top lieux.
107 +- **crea-ka** : créateurs par plateforme/niche/tier, comptes reliés, top
108 + créateurs, croissance du répertoire.
109 +- **trouve-ka** : pages indexées, domaines, rythme de crawl (indexées/h),
110 + erreurs, file frontier, tendances si les requêtes sont journalisées.
111 +- **api-ka** : appels par endpoint/jour/heure, latences moyennes + p95, taux
112 + d'erreur, top endpoints, uptime (données des middlewares de logging + runs).
113 +- **Transverse (tous)** : volume total agrégé + croissance, connecteurs actifs
114 + et éléments ajoutés/mis à jour par période (journaux de sync), complétude/
115 + fraîcheur moyenne des fiches quand mesurable. Trafic web : seulement si des
116 + journaux d'accès existent — sinon état vide propre.
117 +
118 +## 5. Ajouter une métrique / un graphique / une plateforme
119 +
120 +1 métrique = 1 entrée `kpis[]` ou `series[]` côté API (requête SQL agrégée +
121 +cache) — le front la rend automatiquement. 1 plateforme = implémenter les 2
122 +endpoints du contrat + une page /stats montée sur les composants du kit +
123 +`kapdf.py` (ou gabarit pdfkit) branché sur le même JSON de dashboard.
added src/api/web/ka/stats/kacharts.tsx +389 −0
@@ -0,0 +1,389 @@
1 +// Auteur : Simon-Pierre Boucher — contact@spboucher.ai
2 +// ka-ui/stats/kacharts.tsx — kit de graphiques SVG du module Stats commun
3 +// Groupe KA (zéro dépendance, React 18+). Style : design system ka-ui
4 +// (bordures encre, accent de la plateforme via var(--accent)).
5 +// Composants : KpiCard, PeriodSelector, LineChart (infobulle + légende
6 +// cliquable + comparaison N-1), BarChart, Donut, CalendarHeatmap, DataTable
7 +// (tri/recherche/pagination), RecordCard, PdfButton, EmptyBlock, Fraicheur.
8 +import { useMemo, useState } from "react";
9 +
10 +/* ---------- types (contrat SPEC.md) ---------- */
11 +export type Kpi = {
12 + id: string; label: string; value: number | string; unit?: string;
13 + delta_pct?: number | null; direction?: "up" | "down";
14 +};
15 +export type Point = { t: string; v: number };
16 +export type Serie = {
17 + id: string; title: string; unit?: string; kind?: "line" | "bar";
18 + points: Point[]; compare?: Point[];
19 +};
20 +export type BreakItem = { label: string; value: number };
21 +export type TableSpec = { id: string; title: string; columns: string[]; rows: (string | number)[][] };
22 +export type RecordFact = { label: string; value: string; date?: string };
23 +
24 +export const PERIODS: { id: string; label: string }[] = [
25 + { id: "auj", label: "Aujourd'hui" },
26 + { id: "7j", label: "7 jours" },
27 + { id: "30j", label: "30 jours" },
28 + { id: "3m", label: "3 mois" },
29 + { id: "6m", label: "6 mois" },
30 + { id: "12m", label: "12 mois" },
31 + { id: "annee", label: "Année en cours" },
32 + { id: "tout", label: "Tout" },
33 +];
34 +
35 +export const fmtInt = (n: number) => n.toLocaleString("fr-CA");
36 +export const fmtNum = (n: number) =>
37 + Number.isInteger(n) ? fmtInt(n) : n.toLocaleString("fr-CA", { maximumFractionDigits: 2 });
38 +
39 +/* ---------- KPI ---------- */
40 +export function KpiCard({ k }: { k: Kpi }) {
41 + const up = (k.direction ?? ((k.delta_pct ?? 0) >= 0 ? "up" : "down")) === "up";
42 + return (
43 + <article className="card" style={{ padding: "14px 16px", minWidth: 0 }}>
44 + <p style={{ margin: 0, fontFamily: "var(--font-display)", fontWeight: 700, fontSize: "clamp(22px,2.4vw,30px)", letterSpacing: "-0.02em" }}>
45 + {typeof k.value === "number" ? fmtNum(k.value) : k.value}
46 + {k.unit ? <span style={{ fontSize: "0.6em", color: "var(--ink-2)" }}> {k.unit}</span> : null}
47 + </p>
48 + <p className="klabel" style={{ margin: "6px 0 0" }}>{k.label}</p>
49 + {k.delta_pct !== undefined && k.delta_pct !== null && (
50 + <p style={{ margin: "8px 0 0", fontFamily: "var(--font-mono)", fontSize: 11, fontWeight: 700, color: up ? "var(--green)" : "var(--danger)" }}>
51 + {up ? "▲" : "▼"} {k.delta_pct >= 0 ? "+" : ""}{fmtNum(k.delta_pct)} % <span style={{ color: "var(--ink-3)", fontWeight: 500 }}>vs période préc.</span>
52 + </p>
53 + )}
54 + </article>
55 + );
56 +}
57 +
58 +/* ---------- Sélecteur de période ---------- */
59 +export function PeriodSelector({
60 + value, onChange, custom, onCustom,
61 +}: {
62 + value: string; onChange: (p: string) => void;
63 + custom?: { from: string; to: string }; onCustom?: (from: string, to: string) => void;
64 +}) {
65 + return (
66 + <div style={{ display: "flex", flexWrap: "wrap", gap: 8, alignItems: "center" }}>
67 + {PERIODS.map((p) => (
68 + <button key={p.id} type="button" onClick={() => onChange(p.id)}
69 + className="chip" aria-pressed={value === p.id}
70 + style={{ cursor: "pointer", minHeight: 44, background: value === p.id ? "var(--accent)" : "var(--surface)", color: value === p.id ? "var(--on-accent)" : "var(--ink)" }}>
71 + {p.label}
72 + </button>
73 + ))}
74 + {onCustom && (
75 + <span style={{ display: "inline-flex", gap: 6, alignItems: "center" }}>
76 + <input className="input" type="date" style={{ width: 150 }} value={custom?.from ?? ""} aria-label="Du"
77 + onChange={(e) => onCustom(e.target.value, custom?.to ?? "")} />
78 + <span className="klabel">au</span>
79 + <input className="input" type="date" style={{ width: 150 }} value={custom?.to ?? ""} aria-label="Au"
80 + onChange={(e) => onCustom(custom?.from ?? "", e.target.value)} />
81 + </span>
82 + )}
83 + </div>
84 + );
85 +}
86 +
87 +/* ---------- Courbe ---------- */
88 +export function LineChart({ serie, height = 240 }: { serie: Serie; height?: number }) {
89 + const [hide, setHide] = useState<{ cur: boolean; cmp: boolean }>({ cur: false, cmp: false });
90 + const [hover, setHover] = useState<number | null>(null);
91 + const W = 720, H = height, PL = 54, PR = 10, PT = 14, PB = 26;
92 + const pts = serie.points ?? [];
93 + if (pts.length < 2) return <EmptyBlock title={serie.title} />;
94 + const all = [...(hide.cur ? [] : pts), ...(!hide.cmp && serie.compare ? serie.compare : [])];
95 + const vmax = Math.max(...all.map((p) => p.v), 1);
96 + const vmin = Math.min(0, ...all.map((p) => p.v));
97 + const X = (i: number, n: number) => PL + ((W - PL - PR) * i) / (n - 1);
98 + const Y = (v: number) => PT + (H - PT - PB) * (1 - (v - vmin) / (vmax - vmin || 1));
99 + const path = (s: Point[]) => s.map((p, i) => `${i ? "L" : "M"}${X(i, s.length)},${Y(p.v)}`).join("");
100 + const hi = hover !== null ? Math.min(pts.length - 1, Math.max(0, hover)) : null;
101 + return (
102 + <figure className="card" style={{ margin: 0, padding: 16 }}>
103 + <figcaption style={{ display: "flex", justifyContent: "space-between", flexWrap: "wrap", gap: 8 }}>
104 + <b style={{ fontFamily: "var(--font-display)", fontSize: 15 }}>{serie.title}</b>
105 + <span style={{ display: "flex", gap: 10 }}>
106 + <LegendChip label="Période courante" color="var(--accent)" off={hide.cur} onClick={() => setHide((h) => ({ ...h, cur: !h.cur }))} />
107 + {serie.compare && <LegendChip label="Période comparée" color="var(--ink-3)" dashed off={hide.cmp} onClick={() => setHide((h) => ({ ...h, cmp: !h.cmp }))} />}
108 + </span>
109 + </figcaption>
110 + <svg viewBox={`0 0 ${W} ${H}`} style={{ width: "100%", height: "auto", marginTop: 10, touchAction: "pan-y" }} role="img" aria-label={serie.title}
111 + onMouseMove={(e) => {
112 + const r = (e.currentTarget as SVGSVGElement).getBoundingClientRect();
113 + const fx = ((e.clientX - r.left) / r.width) * W;
114 + setHover(Math.round(((fx - PL) / (W - PL - PR)) * (pts.length - 1)));
115 + }}
116 + onMouseLeave={() => setHover(null)}>
117 + {[0, 1, 2, 3, 4].map((g) => {
118 + const y = PT + ((H - PT - PB) * g) / 4;
119 + const v = vmax - ((vmax - vmin) * g) / 4;
120 + return (
121 + <g key={g}>
122 + <line x1={PL} x2={W - PR} y1={y} y2={y} stroke="var(--line)" strokeWidth={1} />
123 + <text x={PL - 6} y={y + 3} textAnchor="end" fontSize={10} fill="var(--ink-3)" fontFamily="var(--font-mono)">{fmtInt(Math.round(v))}</text>
124 + </g>
125 + );
126 + })}
127 + {[0, Math.floor(pts.length / 2), pts.length - 1].map((i) => (
128 + <text key={i} x={X(i, pts.length)} y={H - 8} textAnchor="middle" fontSize={10} fill="var(--ink-3)" fontFamily="var(--font-mono)">{pts[i].t}</text>
129 + ))}
130 + {!hide.cmp && serie.compare && serie.compare.length > 1 && (
131 + <path d={path(serie.compare)} fill="none" stroke="var(--ink-3)" strokeWidth={1.4} strokeDasharray="4 4" />
132 + )}
133 + {!hide.cur && <path d={path(pts)} fill="none" stroke="var(--accent)" strokeWidth={2.4} />}
134 + {hi !== null && (
135 + <g>
136 + <line x1={X(hi, pts.length)} x2={X(hi, pts.length)} y1={PT} y2={H - PB} stroke="var(--ink)" strokeWidth={1} strokeDasharray="2 3" />
137 + <circle cx={X(hi, pts.length)} cy={Y(pts[hi].v)} r={4} fill="var(--accent)" stroke="var(--ink)" strokeWidth={1.5} />
138 + </g>
139 + )}
140 + </svg>
141 + {hi !== null && (
142 + <p className="chip" style={{ marginTop: 8 }}>
143 + {pts[hi].t} — <b>{fmtNum(pts[hi].v)}{serie.unit ? ` ${serie.unit}` : ""}</b>
144 + {serie.compare?.[hi] && !hide.cmp ? <span style={{ color: "var(--ink-3)" }}> · N-1 : {fmtNum(serie.compare[hi].v)}</span> : null}
145 + </p>
146 + )}
147 + </figure>
148 + );
149 +}
150 +
151 +function LegendChip({ label, color, off, dashed, onClick }: { label: string; color: string; off: boolean; dashed?: boolean; onClick: () => void }) {
152 + return (
153 + <button type="button" onClick={onClick} aria-pressed={!off}
154 + style={{ display: "inline-flex", alignItems: "center", gap: 6, border: 0, background: "none", cursor: "pointer", opacity: off ? 0.4 : 1, fontFamily: "var(--font-mono)", fontSize: 10.5, fontWeight: 700, textTransform: "uppercase", letterSpacing: "0.06em", minHeight: 44 }}>
155 + <span style={{ width: 18, height: 0, borderTop: `3px ${dashed ? "dashed" : "solid"} ${color}` }} />
156 + {label}
157 + </button>
158 + );
159 +}
160 +
161 +/* ---------- Barres horizontales (répartitions, géo) ---------- */
162 +export function BarChart({ title, items, unit }: { title: string; items: BreakItem[]; unit?: string }) {
163 + const rows = (items ?? []).slice(0, 14);
164 + if (!rows.length) return <EmptyBlock title={title} />;
165 + const max = Math.max(...rows.map((r) => r.value), 1);
166 + return (
167 + <figure className="card" style={{ margin: 0, padding: 16 }}>
168 + <figcaption><b style={{ fontFamily: "var(--font-display)", fontSize: 15 }}>{title}</b></figcaption>
169 + <div style={{ marginTop: 12, display: "grid", gap: 9 }}>
170 + {rows.map((r) => (
171 + <div key={r.label} title={`${r.label} — ${fmtNum(r.value)}${unit ? ` ${unit}` : ""}`}>
172 + <div style={{ display: "flex", justifyContent: "space-between", fontSize: 12.5 }}>
173 + <span style={{ overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>{r.label}</span>
174 + <b style={{ fontFamily: "var(--font-mono)", fontSize: 11.5 }}>{fmtNum(r.value)}{unit ? ` ${unit}` : ""}</b>
175 + </div>
176 + <div style={{ marginTop: 3, height: 12, background: "rgba(20,24,20,0.06)", borderRadius: "0 3px 3px 0" }}>
177 + <div style={{ height: "100%", width: `${Math.max((r.value / max) * 100, 1)}%`, background: "var(--accent)", border: "1px solid var(--ink)", borderRadius: "0 3px 3px 0", boxSizing: "border-box" }} />
178 + </div>
179 + </div>
180 + ))}
181 + </div>
182 + </figure>
183 + );
184 +}
185 +
186 +/* ---------- Anneau ---------- */
187 +export function Donut({ title, items }: { title: string; items: BreakItem[] }) {
188 + const rows = (items ?? []).filter((i) => i.value > 0).slice(0, 8);
189 + const total = rows.reduce((s, r) => s + r.value, 0);
190 + if (!total) return <EmptyBlock title={title} />;
191 + const R = 74, C = 2 * Math.PI * R;
192 + let acc = 0;
193 + const shades = [1, 0.78, 0.58, 0.42, 0.3, 0.22, 0.15, 0.1];
194 + return (
195 + <figure className="card" style={{ margin: 0, padding: 16 }}>
196 + <figcaption><b style={{ fontFamily: "var(--font-display)", fontSize: 15 }}>{title}</b></figcaption>
197 + <div style={{ display: "flex", flexWrap: "wrap", gap: 18, alignItems: "center", marginTop: 12 }}>
198 + <svg viewBox="0 0 200 200" style={{ width: 180, maxWidth: "100%" }} role="img" aria-label={title}>
199 + {rows.map((r, i) => {
200 + const frac = r.value / total;
201 + const off = acc; acc += frac;
202 + return (
203 + <circle key={r.label} cx={100} cy={100} r={R} fill="none"
204 + stroke="var(--accent)" strokeOpacity={shades[i % shades.length]}
205 + strokeWidth={30} strokeDasharray={`${frac * C} ${C}`} strokeDashoffset={-off * C}
206 + transform="rotate(-90 100 100)">
207 + <title>{`${r.label} — ${fmtNum(r.value)} (${((100 * r.value) / total).toFixed(1)} %)`}</title>
208 + </circle>
209 + );
210 + })}
211 + <circle cx={100} cy={100} r={R} fill="none" stroke="var(--ink)" strokeWidth={1} opacity={0.5} />
212 + </svg>
213 + <ul style={{ listStyle: "none", margin: 0, padding: 0, display: "grid", gap: 6, minWidth: 200, flex: 1 }}>
214 + {rows.map((r, i) => (
215 + <li key={r.label} style={{ display: "flex", alignItems: "center", gap: 8, fontSize: 12.5 }}>
216 + <span style={{ width: 11, height: 11, borderRadius: 3, border: "1px solid var(--ink)", background: "var(--accent)", opacity: shades[i % shades.length] }} />
217 + <span style={{ flex: 1, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>{r.label}</span>
218 + <b style={{ fontFamily: "var(--font-mono)", fontSize: 11 }}>{((100 * r.value) / total).toFixed(1)} %</b>
219 + </li>
220 + ))}
221 + </ul>
222 + </div>
223 + </figure>
224 + );
225 +}
226 +
227 +/* ---------- Calendrier de chaleur ---------- */
228 +export function CalendarHeatmap({ title, cells }: { title: string; cells: { date: string; value: number }[] }) {
229 + if (!cells?.length) return <EmptyBlock title={title} />;
230 + const byDate = new Map(cells.map((c) => [c.date, c.value]));
231 + const dates = cells.map((c) => c.date).sort();
232 + const end = new Date(dates[dates.length - 1] + "T12:00:00");
233 + const max = Math.max(...cells.map((c) => c.value), 1);
234 + const weeks = 26, cols: { date: string; v: number }[][] = [];
235 + const cur = new Date(end);
236 + cur.setDate(cur.getDate() - (weeks * 7 - 1));
237 + for (let w = 0; w < weeks; w++) {
238 + const col: { date: string; v: number }[] = [];
239 + for (let d = 0; d < 7; d++) {
240 + const iso = cur.toISOString().slice(0, 10);
241 + col.push({ date: iso, v: byDate.get(iso) ?? 0 });
242 + cur.setDate(cur.getDate() + 1);
243 + }
244 + cols.push(col);
245 + }
246 + return (
247 + <figure className="card" style={{ margin: 0, padding: 16 }}>
248 + <figcaption><b style={{ fontFamily: "var(--font-display)", fontSize: 15 }}>{title}</b> <span className="klabel">26 dernières semaines</span></figcaption>
249 + <div className="tbl-wrap" style={{ marginTop: 12 }}>
250 + <svg viewBox={`0 0 ${weeks * 14} ${7 * 14}`} style={{ minWidth: 480, width: "100%", height: "auto" }} role="img" aria-label={title}>
251 + {cols.map((col, w) => col.map((c, d) => (
252 + <rect key={c.date} x={w * 14} y={d * 14} width={12} height={12} rx={2.5}
253 + fill={c.v ? "var(--accent)" : "rgba(20,24,20,0.07)"} fillOpacity={c.v ? 0.25 + 0.75 * (c.v / max) : 1}
254 + stroke="rgba(20,24,20,0.15)" strokeWidth={0.5}>
255 + <title>{`${c.date} — ${fmtNum(c.v)}`}</title>
256 + </rect>
257 + )))}
258 + </svg>
259 + </div>
260 + </figure>
261 + );
262 +}
263 +
264 +/* ---------- Tableau : tri, recherche, pagination ---------- */
265 +export function DataTable({ spec, pageSize = 25 }: { spec: TableSpec; pageSize?: number }) {
266 + const [q, setQ] = useState("");
267 + const [sort, setSort] = useState<{ col: number; dir: 1 | -1 } | null>(null);
268 + const [page, setPage] = useState(0);
269 + const rows = useMemo(() => {
270 + let r = spec.rows ?? [];
271 + if (q) r = r.filter((row) => row.some((c) => String(c).toLowerCase().includes(q.toLowerCase())));
272 + if (sort) r = [...r].sort((a, b) => {
273 + const x = a[sort.col], y = b[sort.col];
274 + const nx = typeof x === "number" ? x : parseFloat(String(x).replace(/[^\d.,-]/g, "").replace(",", "."));
275 + const ny = typeof y === "number" ? y : parseFloat(String(y).replace(/[^\d.,-]/g, "").replace(",", "."));
276 + if (!Number.isNaN(nx) && !Number.isNaN(ny)) return (nx - ny) * sort.dir;
277 + return String(x).localeCompare(String(y), "fr") * sort.dir;
278 + });
279 + return r;
280 + }, [spec.rows, q, sort]);
281 + const pages = Math.max(1, Math.ceil(rows.length / pageSize));
282 + const cur = Math.min(page, pages - 1);
283 + return (
284 + <section className="card" style={{ padding: 16 }}>
285 + <div style={{ display: "flex", flexWrap: "wrap", gap: 10, justifyContent: "space-between", alignItems: "center" }}>
286 + <b style={{ fontFamily: "var(--font-display)", fontSize: 15 }}>{spec.title}</b>
287 + <input className="input" style={{ maxWidth: 240 }} placeholder="Rechercher…" value={q}
288 + onChange={(e) => { setQ(e.target.value); setPage(0); }} aria-label={`Rechercher dans ${spec.title}`} />
289 + </div>
290 + <div className="tbl-wrap" style={{ marginTop: 10 }}>
291 + <table style={{ width: "100%", borderCollapse: "collapse", fontSize: 13 }}>
292 + <thead>
293 + <tr>
294 + {spec.columns.map((c, i) => (
295 + <th key={c} onClick={() => setSort((s) => ({ col: i, dir: s?.col === i && s.dir === 1 ? -1 : 1 }))}
296 + style={{ cursor: "pointer", textAlign: "left", padding: "8px 10px", background: "var(--ink)", color: "var(--paper)", fontFamily: "var(--font-mono)", fontSize: 10.5, textTransform: "uppercase", letterSpacing: "0.06em", whiteSpace: "nowrap", userSelect: "none" }}
297 + aria-sort={sort?.col === i ? (sort.dir === 1 ? "ascending" : "descending") : "none"}>
298 + {c} {sort?.col === i ? (sort.dir === 1 ? "▲" : "▼") : "↕"}
299 + </th>
300 + ))}
301 + </tr>
302 + </thead>
303 + <tbody>
304 + {rows.slice(cur * pageSize, (cur + 1) * pageSize).map((row, ri) => (
305 + <tr key={ri} style={{ background: ri % 2 ? "var(--surface-2)" : "var(--surface)" }}>
306 + {row.map((c, ci) => (
307 + <td key={ci} style={{ padding: "7px 10px", borderBottom: "1px solid var(--line)", whiteSpace: "nowrap" }}>
308 + {typeof c === "number" ? fmtNum(c) : c}
309 + </td>
310 + ))}
311 + </tr>
312 + ))}
313 + </tbody>
314 + </table>
315 + </div>
316 + <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center", marginTop: 10, flexWrap: "wrap", gap: 8 }}>
317 + <span className="klabel">{fmtInt(rows.length)} lignes</span>
318 + <span style={{ display: "flex", gap: 6 }}>
319 + <button type="button" className="btn btn-ghost" disabled={cur === 0} onClick={() => setPage(cur - 1)}>←</button>
320 + <span className="chip">{cur + 1} / {pages}</span>
321 + <button type="button" className="btn btn-ghost" disabled={cur >= pages - 1} onClick={() => setPage(cur + 1)}>→</button>
322 + </span>
323 + </div>
324 + </section>
325 + );
326 +}
327 +
328 +/* ---------- Records / faits marquants ---------- */
329 +export function RecordCard({ r }: { r: RecordFact }) {
330 + return (
331 + <article className="card" style={{ padding: "12px 16px", display: "flex", justifyContent: "space-between", gap: 12, alignItems: "baseline", background: "var(--surface-2)" }}>
332 + <span style={{ fontSize: 13, color: "var(--ink-2)" }}>{r.label}</span>
333 + <span style={{ textAlign: "right" }}>
334 + <b style={{ fontFamily: "var(--font-display)", fontSize: 15 }}>{r.value}</b>
335 + {r.date && <span className="klabel" style={{ display: "block" }}>{r.date}</span>}
336 + </span>
337 + </article>
338 + );
339 +}
340 +
341 +/* ---------- Bouton PDF ---------- */
342 +export function PdfButton({ period, from, to, endpoint = "/api/stats/report" }: { period: string; from?: string; to?: string; endpoint?: string }) {
343 + const [busy, setBusy] = useState(false);
344 + const url = (mode: string) => {
345 + const p = new URLSearchParams({ period, mode });
346 + if (from) p.set("from", from);
347 + if (to) p.set("to", to);
348 + return `${endpoint}?${p}`;
349 + };
350 + const dl = (mode: string) => {
351 + setBusy(true);
352 + const a = document.createElement("a");
353 + a.href = url(mode);
354 + a.download = "";
355 + document.body.appendChild(a);
356 + a.click();
357 + a.remove();
358 + setTimeout(() => setBusy(false), 2500);
359 + };
360 + return (
361 + <span style={{ display: "inline-flex", gap: 8, flexWrap: "wrap" }}>
362 + <button type="button" className="btn btn-primary" onClick={() => dl("complet")} disabled={busy}>
363 + {busy ? "Génération…" : "⬇ Télécharger le rapport PDF"}
364 + </button>
365 + <button type="button" className="btn btn-ghost" onClick={() => dl("synthese")} disabled={busy}>
366 + Synthèse (2 p.)
367 + </button>
368 + </span>
369 + );
370 +}
371 +
372 +/* ---------- États ---------- */
373 +export function EmptyBlock({ title }: { title: string }) {
374 + return (
375 + <div className="card" style={{ padding: 20, background: "var(--surface-2)", borderStyle: "dashed" }}>
376 + <b style={{ fontFamily: "var(--font-display)", fontSize: 14 }}>{title}</b>
377 + <p className="klabel" style={{ margin: "6px 0 0" }}>Pas encore mesuré — aucune donnée disponible pour cette période.</p>
378 + </div>
379 + );
380 +}
381 +
382 +export function Fraicheur({ updated, onRefresh }: { updated: string; onRefresh: () => void }) {
383 + return (
384 + <p style={{ display: "flex", gap: 10, alignItems: "center", flexWrap: "wrap", margin: 0 }}>
385 + <span className="klabel">Mis à jour le {new Date(updated).toLocaleString("fr-CA", { dateStyle: "medium", timeStyle: "short" })}</span>
386 + <button type="button" className="btn btn-ghost" onClick={onRefresh}>↻ Rafraîchir</button>
387 + </p>
388 + );
389 +}
added src/api/web/ka/stats/kapdf.py +560 −0
@@ -0,0 +1,560 @@
1 +# Auteur : Simon-Pierre Boucher — contact@spboucher.ai
2 +# ka-ui/stats/kapdf.py — moteur PDF commun Groupe KA (fpdf2).
3 +# Consomme le JSON du contrat /api/stats/dashboard (voir SPEC.md) et produit
4 +# le rapport estampillé Groupe-KA : couverture, sommaire, KPI, graphiques
5 +# VECTORIELS (courbes/barres/anneaux), tableaux paginés, records, page de fin.
6 +# Usage :
7 +# from kapdf import GroupeKAReport
8 +# pdf_bytes = GroupeKAReport(site={"wordmark":"Lou·Ka","accent":"#ff6a00",
9 +# "domain":"www.lou-ka.com","tagline":"…"}, dashboard=dash_json,
10 +# mode="complet").build()
11 +# Dépendance : pip install fpdf2 (aucune autre)
12 +from __future__ import annotations
13 +
14 +import math
15 +from datetime import datetime
16 +from zoneinfo import ZoneInfo
17 +
18 +from fpdf import FPDF
19 +
20 +INK = (20, 24, 20)
21 +INK2 = (77, 85, 81)
22 +INK3 = (139, 146, 140)
23 +PAPER = (245, 243, 238)
24 +SURFACE2 = (250, 249, 245)
25 +GREEN = (28, 92, 65)
26 +DANGER = (179, 66, 58)
27 +WHITE = (255, 255, 255)
28 +
29 +EMAILS = [
30 + ("contact@groupe-ka.com", "Projets, partenariats & données"),
31 + ("info@groupe-ka.com", "Médias & questions générales"),
32 + ("admin@groupe-ka.com", "Légal, vie privée & Loi 25"),
33 +]
34 +DISCLAIMER = (
35 + "Groupe KA est un agrégateur de contenu : nous ne vendons rien, ne louons "
36 + "rien et ne sommes partie à aucune transaction. Données lues à la source, "
37 + "rien d'inventé, tout est traçable."
38 +)
39 +
40 +
41 +def _hex(c: str) -> tuple[int, int, int]:
42 + c = c.lstrip("#")
43 + return tuple(int(c[i : i + 2], 16) for i in (0, 2, 4)) # type: ignore
44 +
45 +
46 +def _fr(n) -> str:
47 + if isinstance(n, float) and not n.is_integer():
48 + return f"{n:,.2f}".replace(",", " ").replace(".", ",")
49 + return f"{int(n):,}".replace(",", " ")
50 +
51 +
52 +_SUBST = {
53 + "—": "-", "–": "-", "→": "->", "▲": "+", "▼": "-",
54 + "…": "...", "’": "'", "‘": "'", "“": '"', "”": '"',
55 + "œ": "oe", "Œ": "OE", "−": "-", " ": " ", " ": " ",
56 +}
57 +
58 +
59 +def _latin1(s: str) -> str:
60 + for k, v in _SUBST.items():
61 + s = s.replace(k, v)
62 + return s.encode("latin-1", "replace").decode("latin-1")
63 +
64 +
65 +class _PDF(FPDF):
66 + """FPDF avec en-tête/pied Groupe-KA sur chaque page (sauf couverture).
67 + Les polices core sont latin-1 : normalize_text sanitise en amont."""
68 +
69 + def normalize_text(self, text):
70 + return super().normalize_text(_latin1(text))
71 +
72 + def __init__(self, brand: str, accent: tuple, period_label: str):
73 + super().__init__(orientation="P", unit="mm", format="A4")
74 + self.brand = brand
75 + self.accent = accent
76 + self.period_label = period_label
77 + self.cover_mode = False
78 + self.set_margins(18, 20, 18)
79 + self.set_auto_page_break(True, margin=22)
80 +
81 + def header(self):
82 + if self.cover_mode:
83 + return
84 + self.set_font("helvetica", "B", 8.5)
85 + self.set_text_color(*INK)
86 + self.set_xy(18, 9)
87 + self.cell(0, 5, f"Groupe KA · {self.brand}")
88 + self.set_font("helvetica", "", 8)
89 + self.set_text_color(*INK3)
90 + self.set_xy(18, 9)
91 + self.cell(0, 5, "Rapport statistique", align="R")
92 + self.set_draw_color(*INK)
93 + self.set_line_width(0.5)
94 + self.line(18, 15.5, 192, 15.5)
95 + self.set_y(20)
96 +
97 + def footer(self):
98 + # La page 1 est toujours la couverture : fpdf dessine son pied de page
99 + # au add_page() suivant, quand cover_mode est deja retombe a False.
100 + if self.cover_mode or self.page_no() == 1:
101 + return
102 + self.set_y(-15)
103 + self.set_draw_color(*INK3)
104 + self.set_line_width(0.2)
105 + self.line(18, self.get_y() - 1.5, 192, self.get_y() - 1.5)
106 + self.set_font("helvetica", "", 7.5)
107 + self.set_text_color(*INK3)
108 + year = datetime.now(ZoneInfo("America/Toronto")).year
109 + self.cell(130, 5, f"© Groupe-KA — {year} — groupe-ka.com · {self.period_label}")
110 + self.cell(0, 5, f"p. {self.page_no()}/{{nb}}", align="R")
111 +
112 +
113 +class GroupeKAReport:
114 + def __init__(self, site: dict, dashboard: dict, mode: str = "complet"):
115 + self.site = site
116 + self.d = dashboard
117 + self.mode = mode
118 + self.accent = _hex(site.get("accent", "#d9f26b"))
119 + period = dashboard.get("period", {}) or {}
120 + self.period_label = period.get("label") or "toute la période"
121 + self.pdf = _PDF(site.get("wordmark", ""), self.accent, self.period_label)
122 + self.toc: list[tuple[str, int]] = []
123 +
124 + # ---------- primitives ----------
125 + def _card(self, x, y, w, h, fill=WHITE):
126 + p = self.pdf
127 + p.set_draw_color(*INK)
128 + p.set_line_width(0.45)
129 + p.set_fill_color(*fill)
130 + p.rect(x, y, w, h, style="DF", round_corners=True, corner_radius=2.2)
131 +
132 + def _kicker(self, text):
133 + p = self.pdf
134 + p.set_font("helvetica", "B", 8)
135 + p.set_text_color(*GREEN)
136 + p.set_draw_color(*GREEN)
137 + p.set_line_width(0.6)
138 + y = p.get_y() + 2
139 + p.line(p.l_margin, y, p.l_margin + 7, y)
140 + p.set_xy(p.l_margin + 9, y - 2.5)
141 + p.cell(0, 5, text.upper())
142 + p.ln(8)
143 +
144 + def _section_title(self, title):
145 + if self.pdf.get_y() > 240:
146 + self.pdf.add_page()
147 + self._kicker("Groupe KA · " + self.site.get("wordmark", ""))
148 + self.pdf.set_font("helvetica", "B", 15)
149 + self.pdf.set_text_color(*INK)
150 + self.pdf.set_x(self.pdf.l_margin)
151 + self.pdf.cell(0, 8, title)
152 + self.toc.append((title, self.pdf.page_no()))
153 + self.pdf.ln(11)
154 +
155 + # ---------- pages ----------
156 + def _cover(self):
157 + p = self.pdf
158 + p.cover_mode = True
159 + p.set_auto_page_break(False)
160 + p.add_page()
161 + p.set_fill_color(*PAPER)
162 + p.rect(0, 0, 210, 297, style="F")
163 + p.set_draw_color(*INK)
164 + p.set_line_width(1.0)
165 + p.rect(10, 10, 190, 277)
166 + # kicker
167 + p.set_font("helvetica", "B", 10)
168 + p.set_text_color(*GREEN)
169 + p.set_xy(24, 34)
170 + p.cell(0, 6, "GROUPE KA · RAPPORT STATISTIQUE")
171 + # wordmark : partie gauche + boîte encre/accent
172 + wm = self.site.get("wordmark", "")
173 + left, boxed = (wm.split("·") + [None])[:2] if "·" in wm else (wm, None)
174 + p.set_xy(24, 70)
175 + p.set_font("helvetica", "B", 40)
176 + p.set_text_color(*INK)
177 + p.cell(p.get_string_width(left) + 2, 20, left)
178 + if boxed:
179 + bw = p.get_string_width(boxed) + 12
180 + x = p.get_x() + 2
181 + p.set_fill_color(*INK)
182 + p.rect(x, 68, bw, 22, style="F", round_corners=True, corner_radius=3)
183 + p.set_text_color(*self.accent)
184 + p.set_xy(x + 6, 70)
185 + p.cell(bw - 12, 18, boxed)
186 + p.set_xy(24, 100)
187 + p.set_font("helvetica", "", 13)
188 + p.set_text_color(*INK2)
189 + p.multi_cell(150, 7, f"Rapport statistique — {wm}")
190 + now = datetime.now(ZoneInfo("America/Toronto"))
191 + per = self.d.get("period", {}) or {}
192 + p.set_xy(24, 125)
193 + p.set_font("helvetica", "", 10.5)
194 + rows = [
195 + ("Période couverte", self.period_label + (f" ({per.get('from')} → {per.get('to')})" if per.get("from") else "")),
196 + ("Généré le", now.strftime("%Y-%m-%d à %H:%M") + " (heure de l'Est)"),
197 + ("Plateforme", "https://" + self.site.get("domain", "")),
198 + ("Mode", "Rapport complet" if self.mode == "complet" else "Synthèse"),
199 + ]
200 + y = 128
201 + for k, v in rows:
202 + p.set_xy(24, y)
203 + p.set_text_color(*INK3)
204 + p.cell(40, 6, k)
205 + p.set_text_color(*INK)
206 + p.set_font("helvetica", "B", 10.5)
207 + p.cell(0, 6, str(v))
208 + p.set_font("helvetica", "", 10.5)
209 + y += 8
210 + # bande encre au pied
211 + p.set_fill_color(*INK)
212 + p.rect(10, 262, 190, 25, style="F")
213 + p.set_xy(24, 270)
214 + p.set_font("helvetica", "B", 12)
215 + p.set_text_color(*WHITE)
216 + p.cell(60, 8, "par Groupe ")
217 + p.set_text_color(*self.accent)
218 + p.set_xy(24 + p.get_string_width("par Groupe ") + 1, 270)
219 + p.cell(20, 8, "KA")
220 + p.set_font("helvetica", "B", 10)
221 + p.set_xy(24, 270)
222 + p.set_text_color(*self.accent)
223 + p.cell(162, 8, "groupe-ka.com", align="R")
224 + p.set_auto_page_break(True, margin=22)
225 + p.cover_mode = False
226 +
227 + def _kpis(self):
228 + kpis = self.d.get("kpis") or []
229 + if not kpis:
230 + return
231 + self._section_title("Synthèse des indicateurs")
232 + p = self.pdf
233 + cols, gw, gh, gap = 3, 56, 26, 3
234 + x0, y = p.l_margin, p.get_y()
235 + for i, k in enumerate(kpis[:9]):
236 + x = x0 + (i % cols) * (gw + gap)
237 + if i and i % cols == 0:
238 + y += gh + gap
239 + if y > 250:
240 + p.add_page(); y = p.get_y()
241 + self._card(x, y, gw, gh)
242 + p.set_xy(x + 4, y + 4)
243 + p.set_font("helvetica", "B", 14)
244 + p.set_text_color(*INK)
245 + val = k.get("value")
246 + p.cell(gw - 8, 7, (_fr(val) if isinstance(val, (int, float)) else str(val)) + (" " + k["unit"] if k.get("unit") else ""))
247 + p.set_xy(x + 4, y + 12)
248 + p.set_font("helvetica", "", 7.6)
249 + p.set_text_color(*INK2)
250 + p.multi_cell(gw - 8, 3.6, str(k.get("label", ""))[:70])
251 + if k.get("delta_pct") is not None:
252 + up = (k.get("direction") or ("up" if k["delta_pct"] >= 0 else "down")) == "up"
253 + p.set_xy(x + 4, y + gh - 6.5)
254 + p.set_font("helvetica", "B", 8)
255 + p.set_text_color(*(GREEN if up else DANGER))
256 + arrow = "+" if k["delta_pct"] >= 0 else ""
257 + p.cell(gw - 8, 4, f"{'▲' if up else '▼'} {arrow}{str(k['delta_pct']).replace('.', ',')} % vs période préc.")
258 + p.set_y(y + gh + 8)
259 +
260 + def _line_chart(self, s):
261 + p = self.pdf
262 + pts = s.get("points") or []
263 + if len(pts) < 2:
264 + return
265 + if p.get_y() > 200:
266 + p.add_page()
267 + p.set_font("helvetica", "B", 10)
268 + p.set_text_color(*INK)
269 + p.cell(0, 6, s.get("title", ""))
270 + p.ln(7)
271 + x0, y0, w, h = p.l_margin, p.get_y(), 174, 52
272 + self._card(x0, y0, w, h, fill=WHITE)
273 + cx, cy, cw, ch = x0 + 12, y0 + 6, w - 20, h - 16
274 + vals = [pt["v"] for pt in pts] + [c["v"] for c in (s.get("compare") or [])]
275 + vmax = max(vals) or 1
276 + vmin = min(0, min(vals))
277 + rng = (vmax - vmin) or 1
278 + # grille + graduations
279 + p.set_font("helvetica", "", 6.3)
280 + p.set_text_color(*INK3)
281 + p.set_draw_color(200, 200, 195)
282 + p.set_line_width(0.15)
283 + for g in range(5):
284 + gy = cy + ch - ch * g / 4
285 + p.line(cx, gy, cx + cw, gy)
286 + p.set_xy(x0 + 1, gy - 1.6)
287 + p.cell(10, 3, _fr(vmin + rng * g / 4), align="R")
288 +
289 + def draw(series, color, width, dash=None):
290 + n = len(series)
291 + p.set_draw_color(*color)
292 + p.set_line_width(width)
293 + if dash:
294 + p.set_dash_pattern(dash=1.2, gap=1.2)
295 + last = None
296 + for i, pt in enumerate(series):
297 + px = cx + cw * (i / (n - 1))
298 + py = cy + ch - ch * ((pt["v"] - vmin) / rng)
299 + if last:
300 + p.line(last[0], last[1], px, py)
301 + last = (px, py)
302 + p.set_dash_pattern()
303 +
304 + if s.get("compare"):
305 + draw(s["compare"], INK3, 0.35, dash=True)
306 + draw(pts, self.accent, 0.7)
307 + # libellés d'axe X (premier / milieu / dernier)
308 + p.set_text_color(*INK3)
309 + for frac, idx in ((0, 0), (0.5, len(pts) // 2), (1, -1)):
310 + p.set_xy(cx + cw * frac - 9, cy + ch + 1.5)
311 + p.cell(18, 3, str(pts[idx].get("t", ""))[:10], align="C")
312 + p.set_y(y0 + h + 4)
313 + if s.get("compare"):
314 + p.set_font("helvetica", "", 6.8)
315 + p.set_text_color(*INK3)
316 + p.cell(0, 4, "— période courante (accent) · ---- période comparée")
317 + p.ln(6)
318 + else:
319 + p.ln(2)
320 +
321 + def _bars(self, title, items, unit=""):
322 + p = self.pdf
323 + items = [it for it in (items or []) if isinstance(it.get("value"), (int, float))][:12]
324 + if not items:
325 + return
326 + need = 10 + len(items) * 7
327 + if p.get_y() + need > 265:
328 + p.add_page()
329 + p.set_font("helvetica", "B", 10)
330 + p.set_text_color(*INK)
331 + p.cell(0, 6, title)
332 + p.ln(8)
333 + vmax = max(it["value"] for it in items) or 1
334 + for it in items:
335 + y = p.get_y()
336 + p.set_font("helvetica", "", 7.6)
337 + p.set_text_color(*INK)
338 + p.set_x(p.l_margin)
339 + p.cell(46, 5, str(it["label"])[:34])
340 + bw = 96 * (it["value"] / vmax)
341 + p.set_fill_color(*self.accent)
342 + p.set_draw_color(*INK)
343 + p.set_line_width(0.25)
344 + p.rect(p.l_margin + 48, y + 0.7, max(bw, 0.8), 3.6, style="DF")
345 + p.set_xy(p.l_margin + 148, y)
346 + p.set_font("helvetica", "B", 7.6)
347 + p.cell(26, 5, _fr(it["value"]) + (" " + unit if unit else ""), align="R")
348 + p.ln(6.4)
349 + p.ln(3)
350 +
351 + def _donut(self, b):
352 + # anneau vectoriel simple (arcs) + légende
353 + p = self.pdf
354 + items = [it for it in (b.get("items") or []) if it.get("value")][:8]
355 + total = sum(it["value"] for it in items)
356 + if not items or not total:
357 + return
358 + if p.get_y() > 210:
359 + p.add_page()
360 + p.set_font("helvetica", "B", 10)
361 + p.set_text_color(*INK)
362 + p.cell(0, 6, b.get("title", ""))
363 + p.ln(8)
364 + cx, cy, r = p.l_margin + 26, p.get_y() + 24, 20
365 + shades = [1.0, 0.78, 0.58, 0.42, 0.30, 0.22, 0.15, 0.10]
366 + start = -90.0
367 + for i, it in enumerate(items):
368 + frac = it["value"] / total
369 + f = shades[i % len(shades)]
370 + col = tuple(int(PAPER[j] + (self.accent[j] - PAPER[j]) * f) for j in range(3))
371 + steps = max(2, int(72 * frac))
372 + p.set_fill_color(*col)
373 + p.set_draw_color(*col)
374 + for st in range(steps):
375 + a0 = math.radians(start + 360 * frac * st / steps)
376 + a1 = math.radians(start + 360 * frac * (st + 1) / steps)
377 + p.polygon(
378 + [(cx, cy),
379 + (cx + r * math.cos(a0), cy + r * math.sin(a0)),
380 + (cx + r * math.cos(a1), cy + r * math.sin(a1))],
381 + style="DF",
382 + )
383 + start += 360 * frac
384 + p.set_fill_color(*WHITE)
385 + p.set_draw_color(*INK)
386 + p.set_line_width(0.4)
387 + p.ellipse(cx - 11, cy - 11, 22, 22, style="DF")
388 + p.ellipse(cx - r, cy - r, 2 * r, 2 * r, style="D")
389 + # légende
390 + ly = cy - 22
391 + for i, it in enumerate(items):
392 + f = shades[i % len(shades)]
393 + col = tuple(int(PAPER[j] + (self.accent[j] - PAPER[j]) * f) for j in range(3))
394 + p.set_fill_color(*col)
395 + p.set_draw_color(*INK)
396 + p.rect(p.l_margin + 60, ly + 0.8, 4, 4, style="DF")
397 + p.set_xy(p.l_margin + 66, ly)
398 + p.set_font("helvetica", "", 7.6)
399 + p.set_text_color(*INK)
400 + pct = 100 * it["value"] / total
401 + p.cell(0, 5.6, f"{str(it['label'])[:40]} — {_fr(it['value'])} ({pct:.1f} %)".replace(".", ","))
402 + ly += 5.6
403 + p.set_y(max(cy + r, ly) + 6)
404 +
405 + def _table(self, t):
406 + p = self.pdf
407 + cols = t.get("columns") or []
408 + rows = t.get("rows") or []
409 + if not cols or not rows:
410 + return
411 + self._section_title(t.get("title", "Tableau"))
412 + w = 174 / len(cols)
413 + def head():
414 + p.set_font("helvetica", "B", 7.6)
415 + p.set_fill_color(*INK)
416 + p.set_text_color(*WHITE)
417 + for c in cols:
418 + p.cell(w, 6, " " + str(c)[:30], fill=True)
419 + p.ln(6)
420 + head()
421 + p.set_text_color(*INK)
422 + for i, row in enumerate(rows[:200]):
423 + if p.get_y() > 262:
424 + p.add_page()
425 + head()
426 + p.set_text_color(*INK)
427 + p.set_font("helvetica", "", 7.4)
428 + p.set_fill_color(*(SURFACE2 if i % 2 else WHITE))
429 + for cell in row:
430 + txt = _fr(cell) if isinstance(cell, (int, float)) else str(cell)
431 + p.cell(w, 5.4, " " + txt[:34], fill=True)
432 + p.ln(5.4)
433 + if len(rows) > 200:
434 + p.set_font("helvetica", "", 7)
435 + p.set_text_color(*INK3)
436 + p.cell(0, 5, f"… {len(rows) - 200} lignes supplémentaires non imprimées")
437 + p.ln(6)
438 +
439 + def _records(self):
440 + recs = self.d.get("records") or []
441 + if not recs:
442 + return
443 + self._section_title("Records & faits marquants")
444 + p = self.pdf
445 + for r in recs[:10]:
446 + if p.get_y() > 258:
447 + p.add_page()
448 + y = p.get_y()
449 + self._card(p.l_margin, y, 174, 11, fill=SURFACE2)
450 + p.set_xy(p.l_margin + 4, y + 2)
451 + p.set_font("helvetica", "", 8.6)
452 + p.set_text_color(*INK2)
453 + p.cell(96, 7, str(r.get("label", ""))[:70])
454 + p.set_font("helvetica", "B", 9)
455 + p.set_text_color(*INK)
456 + p.cell(52, 7, str(r.get("value", ""))[:36], align="R")
457 + p.set_font("helvetica", "", 7.6)
458 + p.set_text_color(*INK3)
459 + p.cell(20, 7, str(r.get("date", "") or ""), align="R")
460 + p.set_y(y + 13.5)
461 + p.ln(4)
462 +
463 + def _final_page(self):
464 + p = self.pdf
465 + p.add_page()
466 + self._kicker("Groupe KA · contact")
467 + p.set_font("helvetica", "B", 15)
468 + p.set_text_color(*INK)
469 + p.cell(0, 8, "Coordonnées du Groupe KA")
470 + p.ln(12)
471 + for email, role in EMAILS:
472 + p.set_font("helvetica", "B", 10.5)
473 + p.set_text_color(*INK)
474 + p.cell(0, 6, email)
475 + p.ln(5.5)
476 + p.set_font("helvetica", "", 8.6)
477 + p.set_text_color(*INK3)
478 + p.cell(0, 5, role)
479 + p.ln(8)
480 + p.ln(2)
481 + p.set_font("helvetica", "B", 10)
482 + p.set_text_color(*GREEN)
483 + p.cell(0, 6, "groupe-ka.com — le portail de l'écosystème ·Ka")
484 + p.ln(10)
485 + p.set_draw_color(*self.accent)
486 + p.set_line_width(0.8)
487 + p.line(p.l_margin, p.get_y(), p.l_margin + 30, p.get_y())
488 + p.ln(4)
489 + p.set_font("helvetica", "", 8.6)
490 + p.set_text_color(*INK2)
491 + p.multi_cell(160, 4.6, DISCLAIMER)
492 + p.ln(4)
493 + p.set_font("helvetica", "", 7.6)
494 + p.set_text_color(*INK3)
495 + p.multi_cell(
496 + 160, 4.2,
497 + "Mentions : rapport généré automatiquement à partir des données réelles de la "
498 + "plateforme au moment indiqué en couverture. Conditions d'utilisation, politique "
499 + "de confidentialité et protection des renseignements personnels (Loi 25) : "
500 + "groupe-ka.com/conditions · /confidentialite · /loi-25.",
501 + )
502 +
503 + def _toc_page(self):
504 + # insérée après coup ? fpdf ne réordonne pas : on écrit le sommaire en
505 + # page 2 en réservant la page lors du build (voir build()).
506 + pass
507 +
508 + def build(self) -> bytes:
509 + p = self.pdf
510 + p.alias_nb_pages()
511 + self._cover()
512 + if self.mode == "synthese":
513 + p.add_page()
514 + self._kpis()
515 + self._records()
516 + self._final_page()
517 + else:
518 + p.add_page()
519 + toc_page_no = p.page_no()
520 + p.add_page()
521 + self._kpis()
522 + for s in self.d.get("series") or []:
523 + if s.get("kind") == "bar":
524 + self._bars(s.get("title", ""), [{"label": pt.get("t"), "value": pt.get("v")} for pt in (s.get("points") or [])], s.get("unit", ""))
525 + else:
526 + self._line_chart(s)
527 + for b in self.d.get("breakdowns") or []:
528 + if b.get("kind") == "donut":
529 + self._donut(b)
530 + else:
531 + self._bars(b.get("title", ""), b.get("items"))
532 + geo = self.d.get("geo")
533 + if geo:
534 + self._bars(geo.get("title", "Répartition géographique"), geo.get("items"))
535 + for t in self.d.get("tables") or []:
536 + self._table(t)
537 + self._records()
538 + self._final_page()
539 + # sommaire écrit sur la page réservée (page 2)
540 + last_page = p.page
541 + p.page = toc_page_no
542 + p.set_y(22)
543 + p.set_font("helvetica", "B", 15)
544 + p.set_text_color(*INK)
545 + p.cell(0, 8, "Sommaire")
546 + p.ln(12)
547 + p.set_font("helvetica", "", 9.5)
548 + for title, page_no in self.toc:
549 + p.set_text_color(*INK)
550 + p.cell(140, 6.5, title[:80])
551 + p.set_text_color(*INK3)
552 + p.cell(0, 6.5, str(page_no), align="R")
553 + p.ln(6.5)
554 + p.page = last_page
555 + return bytes(p.output())
556 +
557 +
558 +def filename(platform_id: str, period: str) -> str:
559 + today = datetime.now(ZoneInfo("America/Toronto")).strftime("%Y-%m-%d")
560 + return f"groupe-ka_{platform_id}_stats_{period}_{today}.pdf"
added src/api/web/stats.html +572 −0
@@ -0,0 +1,572 @@
1 +<!DOCTYPE html>
2 +<!--
3 +============================================
4 +Projet : API-KA
5 +Fichier : src/api/web/stats.html
6 +Node : m3u96b
7 +Author : Simon-Pierre Boucher
8 +Contact : contact@spboucher.ai
9 +Date : 2026-08-17
10 +============================================
11 +Page /stats — tableau de bord analytique de la plateforme (module Stats commun
12 +Groupe KA, SPEC.md). Vanilla JS + SVG : reproduit le langage visuel du kit
13 +ka-ui/stats/kacharts.tsx (KPI + delta, chips de période, courbe avec infobulle
14 +et légende cliquable, barres, anneau, heatmap calendrier, tableaux triables,
15 +records, bouton PDF). Données : GET /api/stats/dashboard — rien d'inventé.
16 +-->
17 +<html lang="fr">
18 +<head>
19 +<meta charset="utf-8">
20 +<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
21 +<title>Statistiques — API-Ka — Un service Groupe KA</title>
22 +<meta name="description" content="Tableau de bord analytique d'API-Ka : appels API par endpoint, latences moyennes et p95, taux d'erreur, runs de collecte quotidiens des 8 services KA et export PDF Groupe-KA.">
23 +<meta name="theme-color" content="#f5f3ee">
24 +<link rel="icon" type="image/svg+xml" href="/favicon.svg">
25 +<link rel="apple-touch-icon" href="/apple-touch-icon.png">
26 +<meta property="og:title" content="Statistiques — API-Ka — Un service Groupe KA">
27 +<meta property="og:description" content="Tableau de bord analytique d'API-Ka : appels API, latences, taux d'erreur, collectes quotidiennes des 8 services KA et export PDF Groupe-KA.">
28 +<meta property="og:url" content="https://www.api-ka.com/stats">
29 +<meta property="og:type" content="website">
30 +<meta property="og:image" content="https://www.api-ka.com/og.png">
31 +<meta property="og:image:width" content="1200">
32 +<meta property="og:image:height" content="630">
33 +<meta name="twitter:card" content="summary_large_image">
34 +<meta name="twitter:image" content="https://www.api-ka.com/og.png">
35 +<link rel="preconnect" href="https://fonts.googleapis.com">
36 +<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
37 +<link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@500;600;700&family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet">
38 +<link rel="stylesheet" href="/ka/tokens.css">
39 +<style>
40 +/* ---- Accent API-Ka : INDIGO (identique à l'accueil) ---- */
41 +:root{
42 + --accent:#3b5bdb; --accent-soft:#e4eafb; --accent-deep:#2b44a8; --on-accent:#ffffff;
43 +}
44 +
45 +/* ---- topbar (identique à l'accueil) ---- */
46 +.topbar{position:sticky;top:0;z-index:60;background:rgba(245,243,238,.94);backdrop-filter:blur(10px);-webkit-backdrop-filter:blur(10px);border-bottom:1.5px solid var(--ink)}
47 +.topbar-in{display:flex;align-items:center;gap:14px;min-height:68px;flex-wrap:wrap;padding-top:8px;padding-bottom:8px}
48 +.brand{font-family:var(--font-display);font-weight:700;font-size:24px;letter-spacing:-.03em;color:var(--ink);text-decoration:none;display:inline-flex;align-items:center;min-height:var(--touch);white-space:nowrap}
49 +.brand .ka{display:inline-block;background:var(--ink);color:var(--accent);border-radius:6px;padding:0 7px 2px;margin-left:5px;transform:rotate(-2deg);transition:transform .15s}
50 +.brand:hover .ka{transform:rotate(0)}
51 +.topnav{display:flex;gap:2px;list-style:none;margin:0 0 0 auto;padding:0;overflow-x:auto;-webkit-overflow-scrolling:touch;max-width:100%}
52 +.topnav a{display:inline-flex;align-items:center;min-height:var(--touch);text-decoration:none;font-family:var(--font-mono);font-size:11.5px;font-weight:700;letter-spacing:.06em;text-transform:uppercase;color:var(--ink-2);padding:0 12px;border-radius:var(--r-ctl);white-space:nowrap;transition:background .13s,color .13s}
53 +.topnav a:hover,.topnav a[aria-current]{background:var(--accent-soft);color:var(--accent-deep)}
54 +#ka-auth{display:flex;align-items:center;gap:8px}
55 +#ka-auth .btn{font-size:12.5px;padding:8px 14px}
56 +.ka-user{display:inline-flex;align-items:center;gap:8px;font-family:var(--font-mono);font-size:11px;font-weight:700;text-transform:uppercase;letter-spacing:.06em;color:var(--ink-2)}
57 +.ka-user b{font-family:var(--font-display);font-size:13px;text-transform:none;letter-spacing:-.01em;color:var(--ink)}
58 +.ka-avatar{width:28px;height:28px;border-radius:50%;border:1.5px solid var(--ink);object-fit:cover}
59 +@media(max-width:1023px){.topnav{order:5;flex-basis:100%;margin-left:0}}
60 +
61 +/* ---- entête de page ---- */
62 +.hero-s{padding:52px 0 40px;border-bottom:1.5px solid var(--ink);background:linear-gradient(rgba(59,91,219,.05),transparent 60%),var(--paper)}
63 +.hero-s h1{max-width:640px;margin-top:16px}
64 +.lede{margin-top:14px;max-width:62ch;color:var(--ink-2);font-size:16px}
65 +.hero-tools{display:flex;flex-wrap:wrap;gap:12px;margin-top:24px;align-items:center}
66 +.fresh{display:flex;gap:10px;align-items:center;flex-wrap:wrap;margin:0}
67 +
68 +/* ---- page ---- */
69 +section{padding:44px 0}
70 +.stats-head{display:flex;flex-wrap:wrap;gap:14px;align-items:center;justify-content:space-between;margin-bottom:22px}
71 +.periods{display:flex;flex-wrap:wrap;gap:8px;align-items:center}
72 +.periods .chip{cursor:pointer;min-height:44px;display:inline-flex;align-items:center;border:1.5px solid var(--ink);background:var(--surface);transition:background .12s,color .12s}
73 +.periods .chip[aria-pressed="true"]{background:var(--accent);color:var(--on-accent)}
74 +.custom-range{display:inline-flex;gap:6px;align-items:center}
75 +.custom-range input{min-height:44px;width:148px}
76 +
77 +.kpi-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(175px,1fr));gap:14px;margin-bottom:26px}
78 +.kpi{padding:14px 16px;min-width:0}
79 +.kpi .v{margin:0;font-family:var(--font-display);font-weight:700;font-size:clamp(22px,2.4vw,30px);letter-spacing:-.02em;color:var(--ink);font-variant-numeric:tabular-nums}
80 +.kpi .v small{font-size:.55em;color:var(--ink-2);font-weight:600}
81 +.kpi .klabel{margin:6px 0 0;display:block}
82 +.kpi .delta{margin:8px 0 0;font-family:var(--font-mono);font-size:11px;font-weight:700}
83 +.kpi .delta span{color:var(--ink-3);font-weight:500}
84 +.d-good{color:var(--green)}.d-bad{color:var(--danger)}
85 +
86 +.charts-grid{display:grid;grid-template-columns:1fr 1fr;gap:16px}
87 +.charts-grid .full{grid-column:1/-1}
88 +@media(max-width:1023px){.charts-grid{grid-template-columns:1fr}}
89 +figure.chart{margin:0;padding:16px}
90 +figure.chart figcaption{display:flex;justify-content:space-between;flex-wrap:wrap;gap:8px;align-items:baseline}
91 +figure.chart figcaption b{font-family:var(--font-display);font-size:15px}
92 +.legend{display:flex;gap:10px;flex-wrap:wrap}
93 +.legend button{display:inline-flex;align-items:center;gap:6px;border:0;background:none;cursor:pointer;font-family:var(--font-mono);font-size:10.5px;font-weight:700;text-transform:uppercase;letter-spacing:.06em;min-height:44px;color:var(--ink-2)}
94 +.legend button[aria-pressed="false"]{opacity:.4}
95 +.legend .sw{width:18px;height:0;border-top:3px solid var(--accent)}
96 +.legend .sw.cmp{border-top-style:dashed;border-top-color:var(--ink-3)}
97 +.chart svg{width:100%;height:auto;margin-top:10px;touch-action:pan-y;display:block}
98 +.tip{margin-top:8px;min-height:30px}
99 +.tip .chip{font-size:11.5px}
100 +.tip .n1{color:var(--ink-3)}
101 +
102 +.bars-rows{margin-top:12px;display:grid;gap:9px}
103 +.bar-row .bl{display:flex;justify-content:space-between;font-size:12.5px;gap:10px}
104 +.bar-row .bl span{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
105 +.bar-row .bl b{font-family:var(--font-mono);font-size:11.5px;font-variant-numeric:tabular-nums}
106 +.bar-row .track{margin-top:3px;height:12px;background:rgba(20,24,20,.06);border-radius:0 3px 3px 0}
107 +.bar-row .fill{height:100%;background:var(--accent);border:1px solid var(--ink);border-radius:0 3px 3px 0;box-sizing:border-box;min-width:2px}
108 +
109 +.donut-wrap{display:flex;flex-wrap:wrap;gap:18px;align-items:center;margin-top:12px}
110 +.donut-wrap svg{width:180px;max-width:100%;margin:0}
111 +.donut-legend{list-style:none;margin:0;padding:0;display:grid;gap:6px;min-width:200px;flex:1}
112 +.donut-legend li{display:flex;align-items:center;gap:8px;font-size:12.5px}
113 +.donut-legend .sq{width:11px;height:11px;border-radius:3px;border:1px solid var(--ink);background:var(--accent);flex:none}
114 +.donut-legend span.lbl{flex:1;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
115 +.donut-legend b{font-family:var(--font-mono);font-size:11px}
116 +
117 +.tbl-card{padding:16px;margin-top:16px}
118 +.tbl-top{display:flex;flex-wrap:wrap;gap:10px;justify-content:space-between;align-items:center}
119 +.tbl-top b{font-family:var(--font-display);font-size:15px}
120 +.tbl-top .input{max-width:240px}
121 +table.dt{width:100%;border-collapse:collapse;font-size:13px;margin-top:10px}
122 +table.dt th{cursor:pointer;text-align:left;padding:8px 10px;background:var(--ink);color:var(--paper);font-family:var(--font-mono);font-size:10.5px;text-transform:uppercase;letter-spacing:.06em;white-space:nowrap;user-select:none}
123 +table.dt td{padding:7px 10px;border-bottom:1px solid var(--line);white-space:nowrap}
124 +table.dt tbody tr:nth-child(even){background:var(--surface-2)}
125 +.tbl-foot{display:flex;justify-content:space-between;align-items:center;margin-top:10px;flex-wrap:wrap;gap:8px}
126 +.tbl-foot .pg{display:flex;gap:6px;align-items:center}
127 +
128 +.records-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(260px,1fr));gap:12px}
129 +.record{padding:12px 16px;display:flex;justify-content:space-between;gap:12px;align-items:baseline;background:var(--surface-2)}
130 +.record .rl{font-size:13px;color:var(--ink-2)}
131 +.record .rv{text-align:right}
132 +.record .rv b{font-family:var(--font-display);font-size:15px}
133 +.record .rv .klabel{display:block}
134 +
135 +.empty{padding:20px;background:var(--surface-2);border-style:dashed}
136 +.empty b{font-family:var(--font-display);font-size:14px}
137 +.empty p{margin:6px 0 0}
138 +
139 +.pdf-note{font-family:var(--font-mono);font-size:10.5px;color:var(--ink-3);text-transform:uppercase;letter-spacing:.05em}
140 +#pdf-busy:not(:empty){font-family:var(--font-mono);font-size:11px;color:var(--accent-deep);font-weight:700}
141 +.sec-gap{margin-top:30px}
142 +@media(max-width:767px){section{padding:32px 0}.hero-s{padding:40px 0 32px}}
143 +@media(prefers-reduced-motion:reduce){*{transition:none!important}}
144 +</style>
145 +</head>
146 +<body>
147 +
148 +<div class="topbar"><div class="container topbar-in">
149 + <a class="brand" href="/" aria-label="API-Ka — accueil">API<span class="ka">·Ka</span></a>
150 + <a class="gk-badge" href="https://www.groupe-ka.com" target="_blank" rel="noopener noreferrer"
151 + aria-label="Un service Groupe KA — visiter le portail de l'écosystème">Un service <b>Groupe<span class="ka">KA</span></b></a>
152 + <ul class="topnav">
153 + <li><a href="/#services">Services</a></li>
154 + <li><a href="/#endpoints">Endpoints</a></li>
155 + <li><a href="/#playground">Playground</a></li>
156 + <li><a href="/stats" aria-current="page">Stats</a></li>
157 + <li><a href="/docs">Swagger</a></li>
158 + <li><a href="/contact">Contact</a></li>
159 + </ul>
160 + <div id="ka-auth"></div>
161 +</div></div>
162 +
163 +<header class="hero-s"><div class="container">
164 + <span class="kicker">Statistiques · Plateforme</span>
165 + <h1>Les <span class="hl">stats</span> de la plateforme</h1>
166 + <p class="lede">Appels API par endpoint, latences moyennes et p95, taux d'erreur et
167 + runs de collecte quotidiens des huit services KA — mesurés en continu par la
168 + plateforme, rien d'inventé.</p>
169 + <div class="hero-tools">
170 + <button type="button" class="btn btn-primary" id="pdf-complet">⬇ Télécharger le rapport PDF</button>
171 + <button type="button" class="btn btn-ghost" id="pdf-synthese">Synthèse (2 p.)</button>
172 + <span id="pdf-busy" role="status"></span>
173 + </div>
174 + <p class="fresh" style="margin-top:18px">
175 + <span class="klabel" id="updated">Chargement…</span>
176 + <button type="button" class="btn btn-ghost" id="refresh">↻ Rafraîchir</button>
177 + <span class="pdf-note" id="coverage"></span>
178 + </p>
179 +</div></header>
180 +
181 +<section><div class="container">
182 + <div class="stats-head">
183 + <div class="periods" id="periods" role="group" aria-label="Période"></div>
184 + <span class="custom-range">
185 + <input class="input" type="date" id="d-from" aria-label="Du">
186 + <span class="klabel">au</span>
187 + <input class="input" type="date" id="d-to" aria-label="Au">
188 + </span>
189 + </div>
190 +
191 + <div class="kpi-grid" id="kpis"></div>
192 +
193 + <div class="charts-grid" id="charts"></div>
194 +
195 + <div id="heatmap" class="sec-gap"></div>
196 +
197 + <div id="tables"></div>
198 +
199 + <div class="sec-gap">
200 + <span class="kicker">Records &amp; faits marquants</span>
201 + <div class="records-grid" id="records" style="margin-top:14px"></div>
202 + </div>
203 +</div></section>
204 +
205 +<footer class="ka-footer"><div class="container" id="ka-footer-root"></div></footer>
206 +
207 +<script src="/ka/ka-shell.js" defer></script>
208 +<script>
209 +"use strict";
210 +/* Reproduction vanilla JS + SVG du kit ka-ui/stats/kacharts.tsx. */
211 +const NF = new Intl.NumberFormat("fr-CA");
212 +const fmt = n => Number.isInteger(n) ? NF.format(n) : new Intl.NumberFormat("fr-CA",{maximumFractionDigits:2}).format(n);
213 +const esc = s => String(s).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/"/g,"&quot;");
214 +
215 +const PERIODS = [
216 + {id:"auj", label:"Aujourd'hui"},
217 + {id:"7j", label:"7 jours"},
218 + {id:"30j", label:"30 jours"},
219 + {id:"3m", label:"3 mois"},
220 + {id:"6m", label:"6 mois"},
221 + {id:"12m", label:"12 mois"},
222 + {id:"annee", label:"Année en cours"},
223 + {id:"tout", label:"Tout"},
224 +];
225 +const state = {period:"30j", from:"", to:""};
226 +
227 +/* ---------- sélecteur de période ---------- */
228 +const periodsEl = document.getElementById("periods");
229 +PERIODS.forEach(p => {
230 + const b = document.createElement("button");
231 + b.type = "button"; b.className = "chip"; b.textContent = p.label;
232 + b.setAttribute("aria-pressed", String(p.id === state.period));
233 + b.addEventListener("click", () => {
234 + state.period = p.id; state.from = ""; state.to = "";
235 + document.getElementById("d-from").value = "";
236 + document.getElementById("d-to").value = "";
237 + syncChips(); load();
238 + });
239 + b.dataset.p = p.id;
240 + periodsEl.appendChild(b);
241 +});
242 +function syncChips(){
243 + periodsEl.querySelectorAll(".chip").forEach(c =>
244 + c.setAttribute("aria-pressed", String(!state.from && c.dataset.p === state.period)));
245 +}
246 +["d-from","d-to"].forEach(id => document.getElementById(id).addEventListener("change", () => {
247 + const f = document.getElementById("d-from").value, t = document.getElementById("d-to").value;
248 + if (f && t) { state.from = f; state.to = t; syncChips(); load(); }
249 +}));
250 +document.getElementById("refresh").addEventListener("click", load);
251 +
252 +/* ---------- bouton PDF ---------- */
253 +function pdfUrl(mode){
254 + const p = new URLSearchParams({period: state.period, mode});
255 + if (state.from && state.to) { p.set("from", state.from); p.set("to", state.to); }
256 + return "/api/stats/report?" + p;
257 +}
258 +function dlPdf(mode){
259 + const busy = document.getElementById("pdf-busy");
260 + busy.textContent = "Génération du PDF…";
261 + const a = document.createElement("a");
262 + a.href = pdfUrl(mode); a.download = "";
263 + document.body.appendChild(a); a.click(); a.remove();
264 + setTimeout(() => { busy.textContent = ""; }, 2600);
265 +}
266 +document.getElementById("pdf-complet").addEventListener("click", () => dlPdf("complet"));
267 +document.getElementById("pdf-synthese").addEventListener("click", () => dlPdf("synthese"));
268 +
269 +/* ---------- blocs vides (jamais de faux chiffres) ---------- */
270 +function emptyBlock(title){
271 + const d = document.createElement("div");
272 + d.className = "card empty";
273 + d.innerHTML = `<b>${esc(title)}</b><p class="klabel">Pas encore mesuré — aucune donnée disponible pour cette période.</p>`;
274 + return d;
275 +}
276 +
277 +/* ---------- KPI ---------- */
278 +function renderKpis(kpis){
279 + const grid = document.getElementById("kpis");
280 + grid.innerHTML = "";
281 + if (!kpis || !kpis.length) { grid.appendChild(emptyBlock("Indicateurs")); return; }
282 + kpis.forEach(k => {
283 + const card = document.createElement("article");
284 + card.className = "card kpi";
285 + let delta = "";
286 + if (k.delta_pct !== undefined && k.delta_pct !== null) {
287 + const arrowUp = k.delta_pct >= 0;
288 + const good = (k.direction ?? (arrowUp ? "up" : "down")) === "up";
289 + delta = `<p class="delta ${good ? "d-good" : "d-bad"}">${arrowUp ? "▲" : "▼"} ${arrowUp ? "+" : ""}${fmt(k.delta_pct)} % <span>vs période préc.</span></p>`;
290 + }
291 + card.innerHTML = `
292 + <p class="v">${typeof k.value === "number" ? fmt(k.value) : esc(k.value)}${k.unit ? `<small> ${esc(k.unit)}</small>` : ""}</p>
293 + <span class="klabel">${esc(k.label)}</span>${delta}`;
294 + grid.appendChild(card);
295 + });
296 +}
297 +
298 +/* ---------- courbe (infobulle + légende cliquable + N-1 pointillé) ---------- */
299 +function lineChart(serie){
300 + const pts = serie.points || [];
301 + if (pts.length < 2) return emptyBlock(serie.title);
302 + const W = 720, H = 240, PL = 54, PR = 10, PT = 14, PB = 26;
303 + const fig = document.createElement("figure");
304 + fig.className = "card chart";
305 + const hasCmp = Array.isArray(serie.compare) && serie.compare.length > 1;
306 + fig.innerHTML = `
307 + <figcaption><b>${esc(serie.title)}</b>
308 + <span class="legend">
309 + <button type="button" data-s="cur" aria-pressed="true"><span class="sw"></span>Période courante</button>
310 + ${hasCmp ? '<button type="button" data-s="cmp" aria-pressed="true"><span class="sw cmp"></span>Période comparée</button>' : ""}
311 + </span>
312 + </figcaption>
313 + <svg viewBox="0 0 ${W} ${H}" role="img" aria-label="${esc(serie.title)}"></svg>
314 + <p class="tip" aria-live="polite"></p>`;
315 + const svg = fig.querySelector("svg");
316 + const tip = fig.querySelector(".tip");
317 + const hide = {cur:false, cmp:false};
318 + let hover = null;
319 +
320 + function draw(){
321 + const all = [...(hide.cur ? [] : pts), ...((!hide.cmp && hasCmp) ? serie.compare : [])];
322 + const vmax = Math.max(...all.map(p => p.v), 1);
323 + const vmin = Math.min(0, ...all.map(p => p.v));
324 + const X = (i, n) => PL + (W - PL - PR) * i / (n - 1);
325 + const Y = v => PT + (H - PT - PB) * (1 - (v - vmin) / ((vmax - vmin) || 1));
326 + const path = s => s.map((p, i) => `${i ? "L" : "M"}${X(i, s.length)},${Y(p.v)}`).join("");
327 + let g = "";
328 + for (let k = 0; k < 5; k++) {
329 + const y = PT + (H - PT - PB) * k / 4;
330 + const v = vmax - (vmax - vmin) * k / 4;
331 + g += `<line x1="${PL}" x2="${W-PR}" y1="${y}" y2="${y}" stroke="var(--line)" stroke-width="1"/>
332 + <text x="${PL-6}" y="${y+3}" text-anchor="end" font-size="10" fill="var(--ink-3)" font-family="var(--font-mono)">${NF.format(Math.round(v))}</text>`;
333 + }
334 + [0, Math.floor(pts.length/2), pts.length-1].forEach((i, k) => {
335 + const anchor = k === 0 ? "start" : k === 2 ? "end" : "middle";
336 + g += `<text x="${X(i, pts.length)}" y="${H-8}" text-anchor="${anchor}" font-size="10" fill="var(--ink-3)" font-family="var(--font-mono)">${esc(pts[i].t)}</text>`;
337 + });
338 + if (hasCmp && !hide.cmp) g += `<path d="${path(serie.compare)}" fill="none" stroke="var(--ink-3)" stroke-width="1.4" stroke-dasharray="4 4"/>`;
339 + if (!hide.cur) g += `<path d="${path(pts)}" fill="none" stroke="var(--accent)" stroke-width="2.4"/>`;
340 + if (hover !== null) {
341 + const x = X(hover, pts.length);
342 + g += `<line x1="${x}" x2="${x}" y1="${PT}" y2="${H-PB}" stroke="var(--ink)" stroke-width="1" stroke-dasharray="2 3"/>`;
343 + if (!hide.cur) g += `<circle cx="${x}" cy="${Y(pts[hover].v)}" r="4" fill="var(--accent)" stroke="var(--ink)" stroke-width="1.5"/>`;
344 + }
345 + svg.innerHTML = g;
346 + if (hover !== null) {
347 + const cmpTxt = (hasCmp && !hide.cmp && serie.compare[hover])
348 + ? ` <span class="n1">· N-1 : ${fmt(serie.compare[hover].v)}</span>` : "";
349 + tip.innerHTML = `<span class="chip">${esc(pts[hover].t)} — <b>&nbsp;${fmt(pts[hover].v)}${serie.unit ? " " + esc(serie.unit) : ""}</b>${cmpTxt}</span>`;
350 + } else tip.innerHTML = "";
351 + }
352 + function setHover(clientX){
353 + const r = svg.getBoundingClientRect();
354 + const fx = (clientX - r.left) / r.width * W;
355 + hover = Math.max(0, Math.min(pts.length - 1, Math.round((fx - PL) / (W - PL - PR) * (pts.length - 1))));
356 + draw();
357 + }
358 + svg.addEventListener("mousemove", e => setHover(e.clientX));
359 + svg.addEventListener("touchstart", e => setHover(e.touches[0].clientX), {passive:true});
360 + svg.addEventListener("touchmove", e => setHover(e.touches[0].clientX), {passive:true});
361 + svg.addEventListener("mouseleave", () => { hover = null; draw(); });
362 + fig.querySelectorAll(".legend button").forEach(b => b.addEventListener("click", () => {
363 + hide[b.dataset.s] = !hide[b.dataset.s];
364 + b.setAttribute("aria-pressed", String(!hide[b.dataset.s]));
365 + draw();
366 + }));
367 + draw();
368 + return fig;
369 +}
370 +
371 +/* ---------- barres horizontales ---------- */
372 +function barChart(title, items, unit){
373 + const rows = (items || []).slice(0, 14);
374 + if (!rows.length) return emptyBlock(title);
375 + const max = Math.max(...rows.map(r => r.value), 1);
376 + const fig = document.createElement("figure");
377 + fig.className = "card chart";
378 + fig.innerHTML = `<figcaption><b>${esc(title)}</b></figcaption><div class="bars-rows"></div>`;
379 + const zone = fig.querySelector(".bars-rows");
380 + rows.forEach(r => {
381 + const d = document.createElement("div");
382 + d.className = "bar-row";
383 + d.title = `${r.label} — ${fmt(r.value)}${unit ? " " + unit : ""}`;
384 + d.innerHTML = `
385 + <div class="bl"><span>${esc(r.label)}</span><b>${fmt(r.value)}${unit ? " " + esc(unit) : ""}</b></div>
386 + <div class="track"><div class="fill" style="width:${Math.max(r.value / max * 100, 1)}%"></div></div>`;
387 + zone.appendChild(d);
388 + });
389 + return fig;
390 +}
391 +
392 +/* ---------- anneau ---------- */
393 +function donut(title, items){
394 + const rows = (items || []).filter(i => i.value > 0).slice(0, 8);
395 + const total = rows.reduce((s, r) => s + r.value, 0);
396 + if (!total) return emptyBlock(title);
397 + const R = 74, C = 2 * Math.PI * R;
398 + const shades = [1, .78, .58, .42, .3, .22, .15, .1];
399 + let acc = 0, segs = "";
400 + rows.forEach((r, i) => {
401 + const frac = r.value / total, off = acc; acc += frac;
402 + segs += `<circle cx="100" cy="100" r="${R}" fill="none" stroke="var(--accent)" stroke-opacity="${shades[i % 8]}"
403 + stroke-width="30" stroke-dasharray="${frac * C} ${C}" stroke-dashoffset="${-off * C}" transform="rotate(-90 100 100)">
404 + <title>${esc(r.label)} — ${fmt(r.value)} (${(100 * r.value / total).toFixed(1)} %)</title></circle>`;
405 + });
406 + const fig = document.createElement("figure");
407 + fig.className = "card chart";
408 + fig.innerHTML = `
409 + <figcaption><b>${esc(title)}</b></figcaption>
410 + <div class="donut-wrap">
411 + <svg viewBox="0 0 200 200" role="img" aria-label="${esc(title)}">${segs}
412 + <circle cx="100" cy="100" r="${R}" fill="none" stroke="var(--ink)" stroke-width="1" opacity=".5"/></svg>
413 + <ul class="donut-legend">
414 + ${rows.map((r, i) => `<li><span class="sq" style="opacity:${shades[i % 8]}"></span>
415 + <span class="lbl">${esc(r.label)}</span><b>${(100 * r.value / total).toFixed(1).replace(".", ",")} %</b></li>`).join("")}
416 + </ul>
417 + </div>`;
418 + return fig;
419 +}
420 +
421 +/* ---------- calendrier de chaleur ---------- */
422 +function heatmap(title, cells){
423 + if (!cells || !cells.length) return null;
424 + const byDate = new Map(cells.map(c => [c.date, c.value]));
425 + const dates = cells.map(c => c.date).sort();
426 + const end = new Date(dates[dates.length - 1] + "T12:00:00");
427 + const max = Math.max(...cells.map(c => c.value), 1);
428 + const weeks = 26;
429 + const cur = new Date(end);
430 + cur.setDate(cur.getDate() - (weeks * 7 - 1));
431 + let rects = "";
432 + for (let w = 0; w < weeks; w++) for (let d = 0; d < 7; d++) {
433 + const iso = cur.toISOString().slice(0, 10);
434 + const v = byDate.get(iso) ?? 0;
435 + rects += `<rect x="${w * 14}" y="${d * 14}" width="12" height="12" rx="2.5"
436 + fill="${v ? "var(--accent)" : "rgba(20,24,20,0.07)"}" fill-opacity="${v ? (0.25 + 0.75 * v / max).toFixed(3) : 1}"
437 + stroke="rgba(20,24,20,0.15)" stroke-width="0.5"><title>${iso} — ${fmt(v)}</title></rect>`;
438 + cur.setDate(cur.getDate() + 1);
439 + }
440 + const fig = document.createElement("figure");
441 + fig.className = "card chart";
442 + fig.innerHTML = `
443 + <figcaption><b>${esc(title)}</b> <span class="klabel">26 dernières semaines</span></figcaption>
444 + <div class="tbl-wrap" style="margin-top:12px">
445 + <svg viewBox="0 0 ${weeks * 14} ${7 * 14}" style="min-width:480px" role="img" aria-label="${esc(title)}">${rects}</svg>
446 + </div>`;
447 + return fig;
448 +}
449 +
450 +/* ---------- tableau : tri, recherche, pagination 25/pg ---------- */
451 +function dataTable(spec, pageSize = 25){
452 + if (!spec.rows || !spec.rows.length) return emptyBlock(spec.title);
453 + const sec = document.createElement("section");
454 + sec.className = "card tbl-card";
455 + sec.innerHTML = `
456 + <div class="tbl-top"><b>${esc(spec.title)}</b>
457 + <input class="input" placeholder="Rechercher…" aria-label="Rechercher dans ${esc(spec.title)}"></div>
458 + <div class="tbl-wrap"><table class="dt"><thead><tr>
459 + ${spec.columns.map((c, i) => `<th data-i="${i}" aria-sort="none">${esc(c)} <span class="si">↕</span></th>`).join("")}
460 + </tr></thead><tbody></tbody></table></div>
461 + <div class="tbl-foot"><span class="klabel"></span>
462 + <span class="pg">
463 + <button type="button" class="btn btn-ghost" data-d="-1" aria-label="Page précédente">←</button>
464 + <span class="chip"></span>
465 + <button type="button" class="btn btn-ghost" data-d="1" aria-label="Page suivante">→</button>
466 + </span></div>`;
467 + const st = {q:"", sort:null, page:0};
468 + const num = x => typeof x === "number" ? x : parseFloat(String(x).replace(/[^\d.,-]/g, "").replace(",", "."));
469 + function rowsFiltered(){
470 + let r = spec.rows;
471 + if (st.q) r = r.filter(row => row.some(c => String(c).toLowerCase().includes(st.q.toLowerCase())));
472 + if (st.sort) r = [...r].sort((a, b) => {
473 + const nx = num(a[st.sort.col]), ny = num(b[st.sort.col]);
474 + if (!Number.isNaN(nx) && !Number.isNaN(ny)) return (nx - ny) * st.sort.dir;
475 + return String(a[st.sort.col]).localeCompare(String(b[st.sort.col]), "fr") * st.sort.dir;
476 + });
477 + return r;
478 + }
479 + function render(){
480 + const rows = rowsFiltered();
481 + const pages = Math.max(1, Math.ceil(rows.length / pageSize));
482 + st.page = Math.min(st.page, pages - 1);
483 + sec.querySelector("tbody").innerHTML = rows.slice(st.page * pageSize, (st.page + 1) * pageSize)
484 + .map(row => `<tr>${row.map(c => `<td>${typeof c === "number" ? fmt(c) : esc(c)}</td>`).join("")}</tr>`).join("");
485 + sec.querySelector(".tbl-foot .klabel").textContent = NF.format(rows.length) + " lignes";
486 + sec.querySelector(".pg .chip").textContent = `${st.page + 1} / ${pages}`;
487 + sec.querySelector('[data-d="-1"]').disabled = st.page === 0;
488 + sec.querySelector('[data-d="1"]').disabled = st.page >= pages - 1;
489 + sec.querySelectorAll("th").forEach(th => {
490 + const i = +th.dataset.i;
491 + const on = st.sort && st.sort.col === i;
492 + th.setAttribute("aria-sort", on ? (st.sort.dir === 1 ? "ascending" : "descending") : "none");
493 + th.querySelector(".si").textContent = on ? (st.sort.dir === 1 ? "▲" : "▼") : "↕";
494 + });
495 + }
496 + sec.querySelector(".tbl-top .input").addEventListener("input", e => { st.q = e.target.value; st.page = 0; render(); });
497 + sec.querySelectorAll("th").forEach(th => th.addEventListener("click", () => {
498 + const i = +th.dataset.i;
499 + st.sort = { col:i, dir: st.sort && st.sort.col === i && st.sort.dir === 1 ? -1 : 1 };
500 + render();
501 + }));
502 + sec.querySelectorAll(".pg button").forEach(b => b.addEventListener("click", () => { st.page += +b.dataset.d; render(); }));
503 + render();
504 + return sec;
505 +}
506 +
507 +/* ---------- records ---------- */
508 +function renderRecords(records){
509 + const grid = document.getElementById("records");
510 + grid.innerHTML = "";
511 + if (!records || !records.length) { grid.appendChild(emptyBlock("Records")); return; }
512 + records.forEach(r => {
513 + const a = document.createElement("article");
514 + a.className = "card record";
515 + a.innerHTML = `<span class="rl">${esc(r.label)}</span>
516 + <span class="rv"><b>${esc(r.value)}</b>${r.date ? `<span class="klabel">${esc(r.date)}</span>` : ""}</span>`;
517 + grid.appendChild(a);
518 + });
519 +}
520 +
521 +/* ---------- chargement & rendu ---------- */
522 +async function load(){
523 + const upd = document.getElementById("updated");
524 + upd.textContent = "Chargement…";
525 + const p = new URLSearchParams({period: state.period});
526 + if (state.from && state.to) { p.set("from", state.from); p.set("to", state.to); }
527 + let dash;
528 + try {
529 + const r = await fetch("/api/stats/dashboard?" + p, {headers:{Accept:"application/json"}});
530 + dash = (await r.json()).data;
531 + } catch {
532 + upd.textContent = "Impossible de charger les statistiques.";
533 + return;
534 + }
535 + upd.textContent = "Mis à jour le " + new Date(dash.updated).toLocaleString("fr-CA", {dateStyle:"medium", timeStyle:"short"})
536 + + (dash.period ? ` · ${dash.period.label} (${dash.period.from} → ${dash.period.to})` : "");
537 + const cov = document.getElementById("coverage");
538 + cov.textContent = dash.coverage && dash.coverage.api_requests_since
539 + ? "Appels API journalisés depuis le " + new Date(dash.coverage.api_requests_since).toLocaleDateString("fr-CA")
540 + : "";
541 +
542 + renderKpis(dash.kpis);
543 +
544 + const charts = document.getElementById("charts");
545 + charts.innerHTML = "";
546 + const series = dash.series || [];
547 + if (!series.length) charts.appendChild(Object.assign(emptyBlock("Séries temporelles"), {className:"card empty full"}));
548 + series.forEach((s, i) => {
549 + const el = lineChart(s);
550 + if (i === 0) el.classList.add("full");
551 + charts.appendChild(el);
552 + });
553 + (dash.breakdowns || []).forEach(b => {
554 + charts.appendChild(b.kind === "donut" ? donut(b.title, b.items) : barChart(b.title, b.items));
555 + });
556 + if (dash.geo && dash.geo.items) charts.appendChild(barChart(dash.geo.title || "Répartition géographique", dash.geo.items));
557 +
558 + const hm = document.getElementById("heatmap");
559 + hm.innerHTML = "";
560 + const hmEl = dash.heatmap ? heatmap(dash.heatmap.title, dash.heatmap.cells) : null;
561 + if (hmEl) hm.appendChild(hmEl);
562 +
563 + const tbls = document.getElementById("tables");
564 + tbls.innerHTML = "";
565 + (dash.tables || []).forEach(t => tbls.appendChild(dataTable(t)));
566 +
567 + renderRecords(dash.records);
568 +}
569 +load();
570 +</script>
571 +</body>
572 +</html>
modified src/database/models.py +25 −0
@@ -156,3 +156,28 @@ class CollectionRun(Base):
156 156 finished_at: Mapped[datetime.datetime] = mapped_column(
157 157 DateTime(timezone=True), nullable=False
158 158 )
159 +
160 +
161 +class ApiRequest(Base):
162 + """Journal léger des requêtes HTTP servies par l'API (alimenté par le
163 + middleware de logging, purge automatique > 90 jours).
164 +
165 + Sert exclusivement la page /stats : appels par endpoint/jour, latences
166 + moyennes et p95, taux d'erreur. Le chemin est normalisé (paramètres de
167 + route repliés) pour garder une cardinalité bornée.
168 + """
169 +
170 + __tablename__ = "api_requests"
171 + __table_args__ = (
172 + Index("ix_api_requests_ts", "ts"),
173 + Index("ix_api_requests_endpoint_ts", "endpoint", "ts"),
174 + )
175 +
176 + id: Mapped[int] = mapped_column(BigIntPK, primary_key=True, autoincrement=True)
177 + ts: Mapped[datetime.datetime] = mapped_column(
178 + DateTime(timezone=True), nullable=False
179 + )
180 + method: Mapped[str] = mapped_column(Text, nullable=False, default="GET")
181 + endpoint: Mapped[str] = mapped_column(Text, nullable=False)
182 + status: Mapped[int] = mapped_column(Integer, nullable=False)
183 + duration_ms: Mapped[float] = mapped_column(Float, nullable=False, default=0.0)
added tests/test_stats.py +113 −0
@@ -0,0 +1,113 @@
1 +# ============================================
2 +# Projet : API-KA
3 +# Fichier : tests/test_stats.py
4 +# Node : m3u96b
5 +# Author : Simon-Pierre Boucher
6 +# Contact : contact@spboucher.ai
7 +# Date : 2026-08-17
8 +# ============================================
9 +"""Tests des routes /api/stats : dashboard (contrat SPEC), rapport PDF, page /stats."""
10 +
11 +from __future__ import annotations
12 +
13 +import datetime
14 +
15 +import pytest
16 +from fastapi.testclient import TestClient
17 +
18 +from src.api import reqstats
19 +from src.api.main import app
20 +from src.api.routes import stats as stats_module
21 +from src.database.db import session_scope
22 +from src.database.models import ApiRequest, CollectionRun
23 +
24 +
25 +@pytest.fixture(autouse=True)
26 +def _clear_stats_cache():
27 + """Le cache 5 min du dashboard ne doit pas fuiter entre les tests."""
28 + stats_module._cache.clear()
29 + yield
30 + stats_module._cache.clear()
31 +
32 +
33 +def _seed_requests_and_run() -> None:
34 + now = datetime.datetime.now(tz=datetime.UTC)
35 + today = datetime.datetime.now(tz=stats_module.TZ).date()
36 + with session_scope() as session:
37 + if session.query(ApiRequest).count() == 0:
38 + for i in range(5):
39 + session.add(
40 + ApiRequest(
41 + ts=now - datetime.timedelta(hours=i + 1),
42 + method="GET",
43 + endpoint="/api/v1/louka",
44 + status=200 if i else 404,
45 + duration_ms=10.0 + i,
46 + )
47 + )
48 + session.add(
49 + CollectionRun(
50 + service="louka",
51 + date_key=today,
52 + status="success",
53 + records_count=42,
54 + duration_seconds=2.0,
55 + error_message=None,
56 + node="m3u96b",
57 + started_at=now,
58 + finished_at=now,
59 + )
60 + )
61 +
62 +
63 +def test_dashboard_contract() -> None:
64 + _seed_requests_and_run()
65 + with TestClient(app) as client:
66 + response = client.get("/api/stats/dashboard?period=7j")
67 + assert response.status_code == 200
68 + body = response.json()
69 + assert body["success"] is True
70 + dash = body["data"]
71 + assert set(dash) >= {"updated", "period", "kpis", "series", "tables", "records"}
72 + kpis = {k["id"]: k for k in dash["kpis"]}
73 + assert kpis["calls"]["value"] >= 5
74 + assert kpis["records"]["value"] >= 42
75 + assert any(s["id"] == "calls" for s in dash["series"])
76 +
77 +
78 +def test_dashboard_invalid_period() -> None:
79 + with TestClient(app) as client:
80 + assert client.get("/api/stats/dashboard?period=xx").status_code == 422
81 +
82 +
83 +def test_report_pdf() -> None:
84 + _seed_requests_and_run()
85 + with TestClient(app) as client:
86 + response = client.get("/api/stats/report?period=7j&mode=synthese")
87 + assert response.status_code == 200
88 + assert response.headers["content-type"] == "application/pdf"
89 + assert "groupe-ka_api-ka_stats_7j_" in response.headers["content-disposition"]
90 + assert response.content.startswith(b"%PDF")
91 +
92 +
93 +def test_stats_page_and_middleware_recording() -> None:
94 + with TestClient(app) as client:
95 + response = client.get("/stats")
96 + assert response.status_code == 200
97 + assert "tableau de bord" in response.text.lower() or "stats" in response.text.lower()
98 + # Le middleware a empilé la requête ; flush() la persiste en base.
99 + reqstats.flush()
100 + with session_scope() as session:
101 + assert (
102 + session.query(ApiRequest).filter(ApiRequest.endpoint == "/stats").count()
103 + >= 1
104 + )
105 +
106 +
107 +def test_normalize_endpoint() -> None:
108 + assert reqstats.normalize_endpoint("/api/v1/louka/date/2026-08-16") == (
109 + "/api/v1/louka/date/{date}"
110 + )
111 + assert reqstats.normalize_endpoint("/api/v1/louka/latest") == "/api/v1/louka/latest"
112 + assert reqstats.normalize_endpoint("/ka/tokens.css") == "/ka/*"
113 + assert reqstats.normalize_endpoint("/wp-admin/setup.php") == "(autre)"
114