forked from yvv/decision
v2 : nettoyage des orphelins v1 + documentation livrable
- 43 fichiers v1 supprimés (composants documents/protocols/sanctuary/toolbox, stores auth/documents/groups/mandates/organizations/protocols/votes, composables api/notifications/formula/websocket, utils doublons du moteur) - nuxt.config épuré (polkadot retiré, KaTeX et apiBase gardés), meta v2 - README.md, CONTRIBUTING.md, CLAUDE.md réécrits pour la v2 - Build zéro erreur, 342/342 tests verts Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Yvv
@@ -1,75 +1,73 @@
|
||||
# libreDecision
|
||||
|
||||
Boîte à outils de gouvernance collective pour la communauté Duniter/G1.
|
||||
Documents modulaires sous vote permanent + protocoles de vote + mandats.
|
||||
Architecture marque blanche — vocation à être intégré dans sweethomeCloud et librodrome.
|
||||
Boîte à outils de la première démocratie — décider ensemble, du trio à la population.
|
||||
v2 local-first : 6 routes de décision, 5 modalités, documents sous vote permanent, mandats,
|
||||
observatoire. Marque blanche par construction (seeds Ğ1 + Atelier du Canal).
|
||||
**Référence produit : `docs/dev/BLUEPRINT-V2.md`** — toute décision de comportement s'y adosse.
|
||||
|
||||
## Protocole de début de session
|
||||
|
||||
1. `git pull --rebase origin main`
|
||||
2. Si des migrations DB sont attendues : `cd backend && alembic upgrade head`
|
||||
3. Si l'objectif de la session n'est pas précisé, le demander
|
||||
2. Si l'objectif de la session n'est pas précisé, le demander
|
||||
|
||||
## Stack
|
||||
|
||||
- **Frontend** : Nuxt 4 (Vue 3, TypeScript) + Nuxt UI v3 + Pinia + UnoCSS ; package manager : npm
|
||||
- **Backend** : Python FastAPI + SQLAlchemy 2.0 async + PostgreSQL asyncpg ; migrations Alembic
|
||||
- **Auth** : Duniter V2 Ed25519 challenge-response (substrate-interface — stub en dev)
|
||||
- **Sanctuaire** : IPFS kubo + hash on-chain (system.remark) — TODO sprint 2
|
||||
- Déploiement : Docker multi-stage + Traefik (postgres + backend + frontend + ipfs) ; CI Woodpecker
|
||||
- **Frontend** : Nuxt 4 (Vue 3, TypeScript, SPA — SSR off) + Nuxt UI v3 + Pinia + UnoCSS ;
|
||||
package manager : npm ; port **3002** strict
|
||||
- **Local-first** : IndexedDB (idb-keyval) via `app/data/persistence.ts` — une clé
|
||||
`ld2:<collectiveId>` par collectif, export/import de bundles JSON, seeds par le même chemin
|
||||
- **Backend v1** (FastAPI + SQLAlchemy async, port 8002) : conservé pour la **future synchro**
|
||||
— non requis pour le dev frontend ; `runtimeConfig.public.apiBase` gardé dans nuxt.config
|
||||
en prévision
|
||||
- Déploiement : Docker multi-stage + Traefik ; CI Woodpecker
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
frontend/
|
||||
app/
|
||||
components/ # composants Vue
|
||||
layouts/ # layouts Nuxt
|
||||
pages/ # routing file-based (9 pages sprint 1)
|
||||
composables/ # (1 composable sprint 1)
|
||||
stores/ # 5 Pinia stores (auth, ...)
|
||||
assets/css/
|
||||
moods.css # système de palettes (.mood-* sur <html>)
|
||||
utils/ # (2 utils sprint 1)
|
||||
nuxt.config.ts # port 3002, host 0.0.0.0, apiBase via NUXT_PUBLIC_API_BASE
|
||||
backend/
|
||||
app/
|
||||
routers/ # 8 routers : auth, communes, documents, protocols, votes, ...
|
||||
services/ # 6 services
|
||||
engine/ # 5 modules : formule inertie, critères Smith/TechComm, médiane
|
||||
models/ # 14 tables SQLAlchemy
|
||||
alembic/versions/ # migrations
|
||||
tests/ # 186 tests (63 intégration TDD sprint 1)
|
||||
seed.py # Engagement Certification (33 items) + Forgeron (51 items) + Runtime Upgrade
|
||||
docker/
|
||||
docker-compose.yml # postgres + backend + frontend + ipfs
|
||||
backend.Dockerfile
|
||||
frontend.Dockerfile
|
||||
docs/content/ # 7 docs dev + 8 docs user
|
||||
public/
|
||||
hexagram-tsing.svg # sceau 井 (embossed)
|
||||
hexagram-tsing-flat.svg
|
||||
engine/ # moteurs PURS (zéro dépendance Nuxt) : threshold (+electionResult),
|
||||
# nuanced, modeParams, parametric (+crystallize), settings, state (canTransition),
|
||||
# triage, impact — import UNIQUEMENT via le barrel ~/engine
|
||||
data/
|
||||
persistence.ts # IndexedDB local-first
|
||||
templates.ts # 7 gabarits de collectif (invariant : protocole Consentement partout)
|
||||
seeds/ # duniter-g1.bundle.json (324 Ko) + atelier-du-canal.bundle.json
|
||||
stores/
|
||||
collective.ts # le tenant : collectif actif, état complet, cycle de vie des bundles
|
||||
decisions.ts # façade d'actions sans état propre (LWW updatedAt, persist debounced)
|
||||
composables/ # useMood (useLibreMood), useFeed (le Fil = sélecteur pur), useSearch
|
||||
components/ # par domaine : chemin/ decisions/ votes/ texts/ mandates/ feed/
|
||||
# onboarding/ common/ (primitives Ld*)
|
||||
pages/ # 14 routes : / · decider · decisions (+[id], vote, observatoire) ·
|
||||
# textes (+[slug], formules) · mandats (+[id], nouveau) ·
|
||||
# creer (layout bare) · donnees
|
||||
lexicon.ts # SOURCE UNIQUE des libellés FR + FORBIDDEN_UI_TERMS
|
||||
types/domain.ts # le noyau du modèle
|
||||
tests/ # 342 tests vitest : engine/, stores/, seeds/ (non-perte), lexicon.spec.ts
|
||||
backend/ # v1 FastAPI conservé pour la synchro future — ne pas développer dessus
|
||||
scripts/export_seed_bundle.py # extrait seed.py → duniter-g1.bundle.json (source vivante = bundle)
|
||||
docker/ # compose + Dockerfiles
|
||||
docs/dev/BLUEPRINT-V2.md # la référence produit v2
|
||||
public/hexagram-tsing*.svg # sceau 井 (#48 Tsing)
|
||||
```
|
||||
|
||||
## Données runtime
|
||||
|
||||
- **postgres-data** : volume Docker PostgreSQL — jamais écrasé par les builds
|
||||
- **ipfs-data** : volume Docker IPFS kubo
|
||||
- `.env` à la racine : `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, `SECRET_KEY`, `DOMAIN`, `DUNITER_RPC_URL`
|
||||
- **postgres-data** / **ipfs-data** : volumes Docker du backend v1 — jamais écrasés
|
||||
- `.env` racine : secrets backend — jamais commité
|
||||
|
||||
## Commandes
|
||||
|
||||
```bash
|
||||
# Backend
|
||||
cd backend && . venv/bin/activate
|
||||
uvicorn app.main:app --port 8002 --host 0.0.0.0 --reload
|
||||
pytest tests/ -v
|
||||
alembic upgrade head
|
||||
python seed.py # reseed Engagement Certification + Forgeron + Runtime Upgrade
|
||||
|
||||
# Frontend
|
||||
# Frontend (tout le dev v2)
|
||||
cd frontend && npm run dev # :3002
|
||||
npm run build
|
||||
npm test # vitest — 342 tests, référence à maintenir
|
||||
npm run build # zéro erreur exigé avant commit
|
||||
|
||||
# Seeds : le bundle est la source vivante ; seed.py (backend) est remplacé par
|
||||
cd backend && .venv/bin/python scripts/export_seed_bundle.py # régénère duniter-g1.bundle.json
|
||||
# → test de non-perte bloquant : tests/seeds/duniter-g1.spec.ts
|
||||
|
||||
# Docker
|
||||
docker compose -f docker/docker-compose.yml up
|
||||
@@ -78,11 +76,25 @@ docker compose -f docker/docker-compose.yml up
|
||||
## Conventions / pièges
|
||||
|
||||
- **UI français, code anglais** (variables, commentaires, docstrings)
|
||||
- **API** : préfixe `/api/v1/`, Pydantic v2 pour tous les schémas, async partout (SQLAlchemy + FastAPI)
|
||||
- **Auth** : `get_current_admin` (24h), `get_current_citizen` (4h), `require_super_admin`
|
||||
- **Formule inertie** : `Result = C + B^W + (M + (1-M) × (1 - (T/W)^G)) × max(0, T-C)` — voir `backend/app/engine/`
|
||||
- **Mood system** : `useMood.ts` synchronise `colorMode.preference` avec la palette — **jamais** de `:global()` dans `<style scoped>` pour les styles mood-dépendants (causa le bug dark mode veil)
|
||||
- **Sceau** `井` (#48 Tsing) : `.app-seal` dans `app.vue`, right-aligned ; SVGs dans `public/`
|
||||
- **CSS drop-shadow()** safe pour effets emboss ; `<filter>` SVG inline cause des artefacts de rendu
|
||||
- **lexicon.ts d'abord** : aucun libellé UI en dur si le lexicon peut le porter ; ton = tutoyer
|
||||
la personne, sujet grammatical = la personne ou le collectif, jamais la formule ni le système
|
||||
- **Anti-lexique** (`tests/lexicon.spec.ts`) : `FORBIDDEN_UI_TERMS` scanné sur lexicon +
|
||||
templates `.vue` (insensible casse/accents) — « triage », « verdict », « déléguer »… restent
|
||||
des identifiants de code, jamais des textes affichés
|
||||
- **Invariants doctrinaux** : jamais de score sur une personne (attributs jamais affichés à
|
||||
autrui, re-votes visibles du seul auteur) ; jamais de contenu adopté sans geste humain
|
||||
(cristallisation, clôture de dossier, départage = gestes datés) ; repli universel → consent ;
|
||||
dérogation asymétrique (alourdir libre, alléger motivé)
|
||||
- **Budget 400 lignes max par page** (`app/pages/`)
|
||||
- **Moteurs purs** : engine/ sans Nuxt/Pinia/DOM, import via `~/engine` seulement ; stores en
|
||||
imports explicites (testables sous vitest nu) ; toute mutation d'état passe par
|
||||
`canTransition(decision, to, ctx)`
|
||||
- **Formule inertie** : `R = C + B^W + (M + (1−M)(1−(T/W)^G))·max(0, T−C)` —
|
||||
`frontend/app/engine/threshold.ts` ; l'Atelier (`/textes/formules`) est la seule maison des
|
||||
lettres W/T/M/B/G/C et de KaTeX
|
||||
- **Mood system** : `useLibreMood()` (`composables/useMood.ts`) — **jamais** de `:global()`
|
||||
dans `<style scoped>` pour les styles mood-dépendants (causa le bug dark mode veil)
|
||||
- **Sceau** `井` (#48 Tsing) : `LdSeal` dans les layouts ; SVGs dans `public/`
|
||||
- **CSS `drop-shadow()`** safe pour l'emboss ; `<filter>` SVG inline cause des artefacts
|
||||
- **Composants** : `pathPrefix: false` — noms de fichiers uniques, auto-import
|
||||
- **Domaine** : decision.librodrome.org (Woodpecker CI ; ancien dossier : Glibredecision)
|
||||
- **Ed25519 verification** : stub en dev (substrate-interface), autoritaire en prod — ne pas bypasser sans test
|
||||
|
||||
Reference in New Issue
Block a user