SoftEng 25-03 Project - Voltes

Αυτό το repository περιέχει την εργασία για το μάθημα Τεχνολογία Λογισμικού (SoftEng) για το ακαδημαϊκό έτος 2025-2026. Αποτελείται από ένα πλήρες σύστημα διαχείρισης φορτιστών ηλεκτρικών οχημάτων, το οποίο περιλαμβάνει Backend API, Frontend Web Application, Command Line Interface (CLI) και Βάση Δεδομένων.

Μέλη Ομάδας:

• Κωνσταντόπουλος Γεώργιος (03122104)
• Πολυμέρη Βασιλική - Σπυριδούλα (03122641)
• Πουλόπουλος Ηλίας (03122160)
• Φραγκονικολάκη Κυριακή (03121215)

Components & Dev Stack

1. Backend API

Το Backend είναι υλοποιημένο σε Node.js χρησιμοποιώντας το Express.js framework.

• Γλώσσα: JavaScript (Node.js)
• Framework: Express.js
• Database: MySQL
• Libraries:
  • cors: Για διαχείριση Cross-Origin Resource Sharing.
  • multer: Για διαχείριση upload αρχείων (CSV).
  • csv-parser: Για ανάγνωση αρχείων CSV.
  • axios: Για επικοινωνία με εξωτερικά API.
• Security: HTTPS με self-signed certificates (OpenSSL).

2. Frontend Application

Το Frontend είναι μια Web εφαρμογή υλοποιημένη με React.

• Framework: React.js
• Styling: CSS / React Scripts
• Maps: @react-google-maps/api για χάρτες.
• HTTP Client: axios για επικοινωνία με το Backend.

3. Command Line Interface (CLI)

Ένα εργαλείο γραμμής εντολών για διαχειριστικές λειτουργίες και αλληλεπίδραση με το σύστημα.

• Γλώσσα: Node.js
• Entry Point: se2503.js
• Λειτουργικότητα: Διαχείριση σταθμών, συνεδριών, φορτιστών, συντήρησης και εκτύπωσης στοιχείων από διαχειριστές ή third parties.

4. Database

Η βάση δεδομένων είναι σχεσιακή, υλοποιημένη σε MySQL.

• Σύστημα: MySQL Server
• Όνομα Βάσης: voltes_db
• Διαχείριση: Μέσω SQL scripts και API endpoints.

---

Οδηγίες Εγκατάστασης (Installation Guide)

1. Clone Repository

Επειδή το repository είναι private, χρειάστηκε η εγκατάσταση του Github Desktop και να συνδεθούμε με τους λογαριασμούς μας στο github για να δουλέψει το clone.

Διαφορετικά σε ένα terminal σε έναν κενό φάκελο θα μπορούσαμε να:

git clone https://github.com/ntua/softeng25-03.git

2. Ρύθμιση Βάσης Δεδομένων (Database Setup)

1. Βεβαιωθείτε ότι έχετε εγκαταστήσει και τρέχετε τον MySQL Server.
2. Συνδεθείτε στην MySQL και εκτελέστε το script back-end/database/db.sql. Αυτό θα δημιουργήσει τη βάση voltes_db και όλους τους απαραίτητους πίνακες.

mysql -u <user> -p < back-end/database/db.sql

3. Εναλλακτικά, αν το API τρέχει, μπορείτε να κάνετε reset τη βάση μέσω του CLI ή του endpoint admin/resetpoints.

se2503 resetpoints

Στοιχεία Σύνδεσης (Default):

• Host: localhost
• User: ilias
• Password: 1234
• Database: voltes_db

Σημείωση: Αν έχετε διαφορετικά credentials, ενημερώστε το αρχείο back-end/api/server.js.

3. Δημιουργία Certificates (OpenSSL)

Το Backend χρησιμοποιεί HTTPS. Πρέπει να δημιουργήσετε self-signed certificates μέσα στον φάκελο back-end/api.

Ανοίξτε ένα terminal στο back-end/api και τρέξτε (αν έχετε openssl):

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

Αυτό θα δημιουργήσει τα αρχεία key.pem και cert.pem που απαιτούνται από το server.js. Μπορεί να ζητηθούν στοιχεία όπως κωδικό χώρας, κ.α. αλλά δεν είναι απαραίτητα.

4. Εκκίνηση Backend (API)

1. Πλοηγηθείτε στον φάκελο του API:

   cd back-end/api

2. Εγκαταστήστε τα dependencies:

   npm install

3. Ξεκινήστε τον server:

   npm start

Ο server θα τρέχει στο https://localhost:9876.

5. Εκκίνηση Frontend

1. Πλοηγηθείτε στον φάκελο του Frontend:

   cd front-end

2. Εγκαταστήστε τα dependencies:

   npm install

3. Ξεκινήστε την εφαρμογή:

   npm start

Η εφαρμογή θα ανοίξει στον browser (συνήθως http://localhost:3000).

---

Οδηγίες Χρήσης CLI

Το CLI εργαλείο βρίσκεται στον φάκελο cli-client.

Εγκατάσταση / Προετοιμασία

1. cd cli-client

2. npm install

3. Για να χρησιμοποιείτε την εντολή se2503 από παντού (χωρίς το node μπροστά), μέσα στον φάκελο cli-client τρέξτε:

   npm link

Διαθέσιμες Εντολές

Η γενική μορφή είναι se2503 [scope] --param1 value1 ....

• healthcheck: Έλεγχος καλής λειτουργίας του API.

  se2503 healthcheck

• resetpoints: Επαναφορά της βάσης δεδομένων στην αρχική κατάσταση (default data).

  se2503 resetpoints

• addpoints: Εισαγωγή σημείων φόρτισης από αρχείο CSV.

  se2503 addpoints --source <filepath>

• points: Εμφάνιση λίστας σημείων φόρτισης.

  se2503 points --status [available|charging|reserved|offline] --format [json|csv]

• point: Εμφάνιση λεπτομερειών για συγκεκριμένο σημείο.

  se2503 point --id <charger_id>

• reserve: Δέσμευση θέσης φόρτισης.

  se2503 reserve --id <charger_id> --minutes <duration_in_minutes>

• pointstatus: Ιστορικό κατάστασης σημείου φόρτισης.

  se2503 pointstatus --id <charger_id> --from YYYYMMDD --to YYYYMMDD

• newsession: Έναρξη νέας συνεδρίας φόρτισης (upload session).

  se2503 newsession --id <charger_id> --starttime "YYYY-MM-DD HH:mm:ss" --endtime "..." --startsoc <%> --endsoc <%> --totalkwh <kwh> --kwhprice <price> --amount <cost>

• sessions: Αναζήτηση ολοκληρωμένων συνεδριών φόρτισης.

  se2503 sessions --id <charger_id> --from YYYYMMDD --to YYYYMMDD

• updpoint: Ενημέρωση στοιχείων σημείου (status/price).

  se2503 updpoint --id <charger_id> --status <new_status> --price <new_price>

Testing

API Testing (Postman)

Στον φάκελο test παρέχονται αρχεία συλλογών για το Postman, τα οποία μπορούν να χρησιμοποιηθούν για τον έλεγχο των API endpoints.

• Voltes script.json: Σενάριο ελέγχου ροής.
• Voltes testin.json: Συλλογή για functional testing των endpoints.

CLI Testing

Στον φάκελο test παρέχονται scripts για τον έλεγχο της λειτουργικότητας του CLI.

• cli_test.sh: Ένα αναλυτικό script που εκτελεί functional testing. Ελέγχει:

  • Την ορθή εκτέλεση των εντολών.
  • Τη διαχείριση σφαλμάτων (π.χ. λάθος ορίσματα, μη έγκυρα IDs, λάθος μορφή ημερομηνιών).
  • Edge cases (π.χ. αρνητικές τιμές, ημερομηνίες στο μέλλον, start time > end time).
  • Όλες τις υποστηριζόμενες εντολές (healthcheck, resetpoints, addpoints, points, point, reserve, updpoint, newsession, sessions, pointstatus).

• cli_script.sh: Ένα σενάριο ροής (demo script) που εκτελεί μια σειρά από ενέργειες για να επιδείξει τη λειτουργικότητα του συστήματος σε μια τυπική χρήση.

• test_points.csv: Αρχείο δεδομένων που χρησιμοποιείται από τα scripts για την εισαγωγή σημείων φόρτισης.

Για να τρέξετε τα tests (σε περιβάλλον Linux/Bash ή Git Bash στα Windows):

bash test/cli_test.sh
# ή
bash test/cli_script.sh

AI Logs

Ο φάκελος ai-log είναι κενός καθώς τα logs είναι αυτόματα αποθηκευμένα στο https://ailog.softlab.ntua.gr/.

Documentation

Στον φάκελο documentation περιλαμβάνονται όλα τα απαραίτητα έγγραφα και διαγράμματα για το έργο:

1. Έγγραφο SRS (Software Requirements Specification)

   • Αρχείο: srs-softeng25-03.docx
   • Περιγραφή: Αναλυτική καταγραφή των απαιτήσεων του λογισμικού.

2. UML Diagrams (Visual Paradigm)

   • Αρχείο: softeng25-03.vpp
   • Περιεχόμενα:
     • Data design diagrams (ER / UML class)
     • UML Activity / State diagrams
     • UML class & API diagrams
     • UML component & deployment diagrams

3. API Specification

   • Αρχείο: openapi.yaml
   • Περιγραφή: Προδιαγραφές του API σε μορφή OpenAPI (Swagger).

Screenshots

Home Page

Available Charger	Offline Charger	Reservation

Location Permission	Filter by Price	Search