Nox (OpenClaw)
121 lines
4.9 KiB
Markdown
121 lines
4.9 KiB
Markdown
<!--
|
|
Sync Impact Report
|
|
- Version change: N/A → 1.0.0 (initial ratification)
|
|
- Added principles: I. API-First, II. Data Integrity, III. Test Coverage,
|
|
IV. Simplicity & Pragmatism, V. Docker-First Deployment
|
|
- Added sections: Technical Stack Constraints, Development Workflow, Governance
|
|
- Removed sections: none
|
|
- Templates requiring updates:
|
|
- .specify/templates/plan-template.md ✅ compatible (Constitution Check present)
|
|
- .specify/templates/spec-template.md ✅ compatible (priorities, acceptance scenarios)
|
|
- .specify/templates/tasks-template.md ✅ compatible (phased approach, test-optional)
|
|
- Follow-up TODOs: none
|
|
-->
|
|
|
|
# Budget Tracker Constitution
|
|
|
|
## Core Principles
|
|
|
|
### I. API-First Design
|
|
|
|
Le backend FastAPI expose une API REST documentee (OpenAPI/Swagger) qui
|
|
constitue le contrat unique entre frontend et backend.
|
|
|
|
- Chaque endpoint DOIT etre defini dans un schema OpenAPI avant implementation.
|
|
- Le frontend React consomme exclusivement l'API REST ; aucun acces direct
|
|
a la base de donnees depuis le frontend.
|
|
- Les reponses DOIVENT suivre un format JSON coherent avec codes HTTP
|
|
standards (200, 201, 400, 404, 422, 500).
|
|
- La validation des entrees DOIT utiliser les modeles Pydantic de FastAPI.
|
|
|
|
### II. Data Integrity
|
|
|
|
Les donnees financieres sont critiques et DOIVENT etre exactes et coherentes.
|
|
|
|
- Tous les montants DOIVENT etre stockes en centimes (entiers) pour eviter
|
|
les erreurs d'arrondi en virgule flottante.
|
|
- Les operations affectant le solde DOIVENT etre transactionnelles (ACID).
|
|
- Chaque transaction DOIT avoir une date, un montant, une categorie et un type
|
|
(revenu ou depense).
|
|
- Les suppressions DOIVENT etre des soft-deletes (champ deleted_at) pour
|
|
garantir la tracabilite de l'historique.
|
|
|
|
### III. Test Coverage
|
|
|
|
Les tests couvrent la logique metier critique sans imposer un TDD strict.
|
|
|
|
- Les calculs financiers (soldes, totaux, budgets) DOIVENT avoir des tests
|
|
unitaires.
|
|
- Les endpoints API DOIVENT avoir des tests d'integration avec une base de
|
|
donnees de test.
|
|
- Les tests DOIVENT etre executables via `pytest` en une seule commande.
|
|
- Le coverage minimum cible est 80% sur la logique metier (services/).
|
|
|
|
### IV. Simplicity & Pragmatism
|
|
|
|
Pas de sur-ingenierie. Chaque couche d'abstraction DOIT etre justifiee.
|
|
|
|
- YAGNI : ne pas implementer de fonctionnalite "au cas ou".
|
|
- Pas de pattern Repository si l'acces direct SQLAlchemy suffit.
|
|
- Pas de microservices : monolithe backend + SPA frontend.
|
|
- Les librairies tierces sont preferees a du code custom quand elles
|
|
resolvent exactement le probleme (ex: Chart.js pour les graphiques).
|
|
- Le code DOIT etre lisible par un developpeur junior sans documentation
|
|
supplementaire.
|
|
|
|
### V. Docker-First Deployment
|
|
|
|
L'application DOIT etre deployable via `docker compose up` sans
|
|
configuration manuelle.
|
|
|
|
- Un fichier `docker-compose.yml` a la racine DOIT orchestrer backend,
|
|
frontend et PostgreSQL.
|
|
- Les variables d'environnement DOIVENT etre centralisees dans un `.env`
|
|
(avec `.env.example` versionne).
|
|
- Les migrations de base de donnees DOIVENT s'executer automatiquement
|
|
au demarrage du conteneur backend.
|
|
- Le frontend DOIT etre servi en mode production via un build statique
|
|
(nginx ou equivalent).
|
|
|
|
## Technical Stack Constraints
|
|
|
|
- **Backend** : Python 3.12+, FastAPI, SQLAlchemy 2.0 (async), Alembic
|
|
- **Frontend** : React 18+, Tailwind CSS, Vite, Chart.js (ou Recharts)
|
|
- **Base de donnees** : PostgreSQL 16+
|
|
- **Tests** : pytest (backend), Vitest (frontend)
|
|
- **Conteneurisation** : Docker, Docker Compose v2
|
|
- **Langue du code** : anglais (variables, fonctions, fichiers)
|
|
- **Langue de la documentation** : francais
|
|
- Les dependances DOIVENT etre epinglees (versions exactes dans
|
|
requirements.txt / package.json)
|
|
|
|
## Development Workflow
|
|
|
|
- Le code DOIT etre formate automatiquement (Ruff pour Python, Prettier
|
|
pour JS/TS).
|
|
- Chaque commit DOIT passer le linting et les tests avant merge.
|
|
- Les branches suivent le pattern : `feature/xxx`, `fix/xxx`, `chore/xxx`.
|
|
- Les migrations Alembic DOIVENT etre auto-generees puis relues
|
|
manuellement avant commit.
|
|
- Le fichier `docker-compose.yml` DOIT inclure un service de
|
|
developpement avec hot-reload (backend + frontend).
|
|
|
|
## Governance
|
|
|
|
Cette constitution est le document de reference pour toutes les decisions
|
|
techniques et architecturales du projet Budget Tracker.
|
|
|
|
- Tout changement architectural DOIT etre valide contre les principes
|
|
ci-dessus avant implementation.
|
|
- Les amendements a cette constitution requierent : (1) une justification
|
|
ecrite, (2) une mise a jour du numero de version, (3) une propagation
|
|
aux artefacts dependants.
|
|
- Le versionnement suit le Semantic Versioning : MAJOR pour les
|
|
changements incompatibles, MINOR pour les ajouts, PATCH pour les
|
|
clarifications.
|
|
- En cas de conflit entre pragmatisme et rigueur, le principe IV
|
|
(Simplicity & Pragmatism) prevaut sauf pour les donnees financieres
|
|
(principe II).
|
|
|
|
**Version**: 1.0.0 | **Ratified**: 2026-03-15 | **Last Amended**: 2026-03-15
|