Μετάβαση στο περιεχόμενο

Ρύθμιση ανάπτυξης

Προαπαιτούμενα

  • Python 3.12+ (3.11 λειτουργεί επίσης για backend, αλλά τα plugins δοκιμάζονται με 3.12).
  • Node 24+ (απαιτείται από το Vite 8). Παλαιότερες εκδόσεις Node θα αποτυγχάνουν στο βήμα build με crypto.hash is not a function.
  • Poetry για διαχείριση εξαρτήσεων Python. Εγκατάσταση: curl -sSL https://install.python-poetry.org | python3 -.
  • npm (συνοδεύει το Node).
  • GNU Make για στόχους ενορχήστρωσης. Το Makefile είναι η πηγή αλήθειας — κάθε εντολή CI βρίσκεται εκεί.

Κλωνοποίηση + εγκατάσταση

git clone git@github.com:astrapi69/adaptive-learner.git
cd adaptive-learner
make install

Το make install εκτελεί:

  1. cd backend && poetry install — backend + path-deps plugin.
  2. cd frontend && npm ci — εξαρτήσεις frontend (Node 24).
  3. Εγκαθιστά κάθε plugin στο plugins/ ως path-dep στο venv του backend (develop = true ώστε οι επεξεργασίες να είναι live).

Αν το make install αποτύχει, το πιο συνηθισμένο αίτιο είναι το Poetry να επιλέγει λάθος Python. Εκτέλεσε poetry env use python3.12 στο backend/ (και σε κάθε plugin αν βαθαίνεις) και επανεγκατέστησε.

Ρύθμιση

Το backend διαβάζει τη ρύθμισή του από αλυσίδα τριών επιπέδων (υψηλότερη προτεραιότητα κερδίζει):

  1. Μεταβλητές περιβάλλοντος με πρόθεμα ADAPTIVE_LEARNER_*.
  2. Μυστικά χρήστη στο ~/.config/adaptive_learner/secrets.yaml — παράγεται αυτόματα ως σχολιασμένο πρότυπο κατά την πρώτη εκκίνηση (chmod 0600 σε POSIX)· ποτέ δεν commit στο git.
  3. Προεπιλογές στο backend/config/app.yaml.

Συν επίλυση κλειδιών ΤΝ ανά πάροχο πάνω από αυτά: env > secrets.yaml > κρυπτογραφημένη στήλη DB με Fernet (ορίζεται μέσω UI Ρυθμίσεων), εκτίθεται στο UI ως πεδίο key_source_* στο UserSettingsOut.

Το ένα υποχρεωτικό μυστικό είναι το ADAPTIVE_LEARNER_SECRET_KEY — χρησιμοποιείται για κρυπτογράφηση API keys χρηστών κατά ανάπαυση με Fernet. Παράγαγέ ένα με python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())". Τρία μέρη για να το τοποθετήσεις (υψηλότερη προτεραιότητα κερδίζει): μεταβλητή περιβάλλοντος ADAPTIVE_LEARNER_SECRET_KEY, secret_key: στο secrets.yaml, ή make dev-secret για εφάπαξ κλειδί ανάπτυξης. Η εφαρμογή αποτυγχάνει σκληρά κατά εκκίνηση αν το κλειδί δεν έχει οριστεί (χωρίς παγίδα σιωπηλά-δημιουργημένης-προεπιλογής — δες docs/configuration.md).

Εκτέλεση

make dev

Εκκινεί backend στη θύρα 18001 και frontend στη θύρα 15174, παράλληλα. Το backend έχει hot-reload μέσω --reload του uvicorn· το frontend είναι dev server του Vite. Πάτησε Ctrl-C μία φορά για να σταματήσουν και τα δύο.

Λειτουργία παρασκηνίου:

make dev-bg   # εκκίνηση backend + frontend στο παρασκήνιο
make dev-down # διακοπή τους

Δοκιμές

make test                 # backend + plugins + frontend Vitest
make test-backend         # μόνο backend pytest
make test-frontend        # μόνο frontend Vitest
make test-coverage        # προαιρετική εκτέλεση κάλυψης (αργή)

Δοκιμές E2E:

cd e2e && npx playwright test

16 αρχεία smoke spec στην v1.20.0: landing, onboarding + assessment, συνεδρία (SSE 3 κομματιών), πρόγραμμα σπουδών, ρυθμίσεις, mobile viewports, σύνδεση συγχρονισμού, roundtrip αντιγράφου, auto-loop πολλαπλών κύκλων, εισαγωγή + ανάλυση, εξαγωγή MD, φίλτρο θεμάτων/ ετικετών, σημειώσεις πλούσιου κειμένου, επιλογέας μοντέλου.

Lint + μορφοποίηση

cd backend && poetry run ruff check .       # Python lint
cd backend && poetry run ruff format .      # Python format
cd frontend && npx tsc --noEmit             # TypeScript check
cd frontend && npm run lint                 # ESLint
cd frontend && npm run format               # Prettier

Τα pre-commit hooks επιβάλλουν ελέγχους ruff + μορφοποιητή σε κάθε commit:

cd backend && poetry run pre-commit install

Έγγραφα

make docs-install   # εφάπαξ, εγκαθιστά venv MkDocs στο docs/
make docs-serve     # σέρβε έγγραφα στο localhost:8000 με hot-reload
make docs-build     # χτίζει στατικό site στο site/

Το venv docs είναι ξεχωριστό από αυτό του backend — το MkDocs έχει δικό του docs/pyproject.toml με mkdocs-material + mkdocs-static-i18n.

Συνηθισμένες παγίδες

  • Το make dev κρασάρει με "port already in use": μια άλλη εκτέλεση AdaptiveLearner εξακολουθεί να τρέχει. make dev-down ή pkill -f uvicorn.
  • Οι δοκιμές αποτυγχάνουν με "duplicate column name": μια μετεγκατάσταση Alembic άλλαξε το σχήμα. Διέγραψε backend/adaptive_learner.db και εκτέλεσε ξανά.
  • Το npm run build αποτυγχάνει στο Node 18: αναβάθμισε σε Node 24. Το Vite 8 το απαιτεί.