fix: added the readme md file
parent
2e179c0c4b
commit
cfd5a6d9ef
|
|
@ -0,0 +1,272 @@
|
||||||
|
Swap Station Real-Time Monitoring & Analytics Dashboard
|
||||||
|
|
||||||
|
A full-stack web application designed for the real-time monitoring, control, and historical analysis of battery swap stations. This dashboard provides a comprehensive interface for administrators and operators to track station health, manage operations, and derive insights from performance data.
|
||||||
|
► Key Features
|
||||||
|
|
||||||
|
Real-Time Dashboard: Live monitoring of station status, slot occupancy, battery vitals (Voltage, SoC, Temperature), and ongoing swap processes via WebSocket communication.
|
||||||
|
|
||||||
|
Remote Control: Send commands directly to stations to open/close slots, enable/disable chargers, initiate swaps, and perform system reboots.
|
||||||
|
|
||||||
|
Advanced Analytics: An interactive analytics page with customizable date ranges to visualize historical data, including swap activity, hourly distribution, abort reasons, and slot utilization heatmaps.
|
||||||
|
|
||||||
|
Data Export: Export detailed periodic and event logs as CSV files for offline analysis and record-keeping.
|
||||||
|
|
||||||
|
Station & User Management: Securely add, remove, and manage swap stations and user accounts.
|
||||||
|
|
||||||
|
Dockerized for Deployment: The entire application is containerized using Docker, Nginx, and Gunicorn, ensuring consistent and reliable deployment to any cloud environment.
|
||||||
|
|
||||||
|
► Tech Stack
|
||||||
|
|
||||||
|
Component
|
||||||
|
|
||||||
|
|
||||||
|
Technology
|
||||||
|
|
||||||
|
Backend
|
||||||
|
|
||||||
|
|
||||||
|
Python 3, Flask, Flask-SocketIO, SQLAlchemy, PostgreSQL
|
||||||
|
|
||||||
|
Frontend
|
||||||
|
|
||||||
|
|
||||||
|
HTML5, CSS3, JavaScript (ES6+), Tailwind CSS, Chart.js, Flatpickr.js
|
||||||
|
|
||||||
|
Real-Time Engine
|
||||||
|
|
||||||
|
|
||||||
|
MQTT (for station communication), WebSockets (for client communication)
|
||||||
|
|
||||||
|
Deployment
|
||||||
|
|
||||||
|
|
||||||
|
Docker, Docker Compose, Nginx (Reverse Proxy), Gunicorn (WSGI Server)
|
||||||
|
► Local Installation & Setup Guide
|
||||||
|
|
||||||
|
These instructions will guide a developer in setting up the project on their local machine for development and testing.
|
||||||
|
Prerequisites
|
||||||
|
|
||||||
|
Ensure you have the following software installed on your system:
|
||||||
|
|
||||||
|
Python (version 3.9+) & Pip
|
||||||
|
|
||||||
|
Node.js (version 16+) & Npm
|
||||||
|
|
||||||
|
PostgreSQL (a running local instance)
|
||||||
|
|
||||||
|
Git
|
||||||
|
|
||||||
|
1. Clone the Repository
|
||||||
|
|
||||||
|
git clone <your-repository-url>
|
||||||
|
cd SWAPSTATION_WEBAPP
|
||||||
|
|
||||||
|
2. Backend Setup
|
||||||
|
|
||||||
|
Navigate to the backend directory:
|
||||||
|
|
||||||
|
cd backend
|
||||||
|
|
||||||
|
Create and activate a Python virtual environment:
|
||||||
|
|
||||||
|
# For macOS/Linux
|
||||||
|
python3 -m venv venv
|
||||||
|
source venv/bin/activate
|
||||||
|
|
||||||
|
# For Windows
|
||||||
|
python -m venv venv
|
||||||
|
.\venv\Scripts\activate
|
||||||
|
|
||||||
|
Install Python dependencies:
|
||||||
|
|
||||||
|
pip install -r requirements.txt
|
||||||
|
|
||||||
|
Set up the PostgreSQL Database:
|
||||||
|
|
||||||
|
Start your local PostgreSQL service.
|
||||||
|
|
||||||
|
Create a new user and a new database for the application. For example, using psql:
|
||||||
|
|
||||||
|
CREATE DATABASE swap_station_db;
|
||||||
|
CREATE USER swap_app_user WITH PASSWORD 'your_secure_password';
|
||||||
|
ALTER DATABASE swap_station_db OWNER TO swap_app_user;
|
||||||
|
|
||||||
|
Configure Environment Variables:
|
||||||
|
|
||||||
|
Create a .env file inside the backend/ directory.
|
||||||
|
|
||||||
|
Copy the contents of .env.example (if it exists) or use the template below, filling in your local database details.
|
||||||
|
|
||||||
|
# backend/.env
|
||||||
|
SECRET_KEY="a_random_secret_key_for_flask"
|
||||||
|
DATABASE_URL="postgresql://swap_app_user:your_secure_password@localhost:5432/swap_station_db"
|
||||||
|
CORS_ALLOWED_ORIGIN="[http://127.0.0.1:5500](http://127.0.0.1:5500)" # For VS Code Live Server
|
||||||
|
|
||||||
|
3. Frontend Setup
|
||||||
|
|
||||||
|
Navigate to the frontend directory:
|
||||||
|
|
||||||
|
# From the project root
|
||||||
|
cd frontend
|
||||||
|
|
||||||
|
Install Node.js dependencies:
|
||||||
|
|
||||||
|
npm install
|
||||||
|
|
||||||
|
► Running the Application Locally
|
||||||
|
|
||||||
|
Start the Backend Server:
|
||||||
|
|
||||||
|
Make sure you are in the backend/ directory with your virtual environment activated.
|
||||||
|
|
||||||
|
Run the Flask application. The first time you run this, it will create the necessary database tables.
|
||||||
|
|
||||||
|
flask run --host=0.0.0.0 --port=5000
|
||||||
|
|
||||||
|
The backend API and WebSocket server is now running on http://localhost:5000.
|
||||||
|
|
||||||
|
Serve the Frontend:
|
||||||
|
|
||||||
|
The simplest way to serve the frontend for local development is using the Live Server extension in Visual Studio Code.
|
||||||
|
|
||||||
|
Right-click on the frontend/index.html file and select "Open with Live Server".
|
||||||
|
|
||||||
|
This will open the application in your browser, typically at http://127.0.0.1:5500.
|
||||||
|
|
||||||
|
► API Endpoints Overview
|
||||||
|
|
||||||
|
The backend provides the following main RESTful API endpoints. All are prefixed with /api.
|
||||||
|
|
||||||
|
Endpoint
|
||||||
|
|
||||||
|
|
||||||
|
Method
|
||||||
|
|
||||||
|
|
||||||
|
Description
|
||||||
|
|
||||||
|
/login
|
||||||
|
|
||||||
|
|
||||||
|
POST
|
||||||
|
|
||||||
|
|
||||||
|
Authenticates a user.
|
||||||
|
|
||||||
|
/users
|
||||||
|
|
||||||
|
|
||||||
|
POST
|
||||||
|
|
||||||
|
|
||||||
|
Adds a new user account.
|
||||||
|
|
||||||
|
/stations
|
||||||
|
|
||||||
|
|
||||||
|
GET
|
||||||
|
|
||||||
|
|
||||||
|
Retrieves a list of all stations.
|
||||||
|
|
||||||
|
/stations
|
||||||
|
|
||||||
|
|
||||||
|
POST
|
||||||
|
|
||||||
|
|
||||||
|
Adds a new station to the system.
|
||||||
|
|
||||||
|
/stations/<id>
|
||||||
|
|
||||||
|
|
||||||
|
DELETE
|
||||||
|
|
||||||
|
|
||||||
|
Removes a station from the system.
|
||||||
|
|
||||||
|
/stations/daily-stats
|
||||||
|
|
||||||
|
|
||||||
|
GET
|
||||||
|
|
||||||
|
|
||||||
|
Gets swap statistics for all stations (last 24h).
|
||||||
|
|
||||||
|
/analytics
|
||||||
|
|
||||||
|
|
||||||
|
GET
|
||||||
|
|
||||||
|
|
||||||
|
Fetches detailed historical analytics data.
|
||||||
|
|
||||||
|
/logs/recent/<id>
|
||||||
|
|
||||||
|
|
||||||
|
GET
|
||||||
|
|
||||||
|
|
||||||
|
Retrieves recent logs for a specific station.
|
||||||
|
|
||||||
|
/logs/export
|
||||||
|
|
||||||
|
|
||||||
|
GET
|
||||||
|
|
||||||
|
|
||||||
|
Exports logs as a CSV file.
|
||||||
|
|
||||||
|
/uptime/<id>
|
||||||
|
|
||||||
|
|
||||||
|
GET
|
||||||
|
|
||||||
|
|
||||||
|
Gets the live uptime percentage for a station.
|
||||||
|
► Deployment
|
||||||
|
|
||||||
|
This application is designed for production deployment using Docker. For detailed, step-by-step instructions on how to deploy the application to an AWS server, please refer to the official guide:
|
||||||
|
|
||||||
|
➡️ DEPLOYMENT.md
|
||||||
|
► Contributing
|
||||||
|
|
||||||
|
Contributions are welcome! If you'd like to contribute to the project, please follow these steps:
|
||||||
|
|
||||||
|
Fork the repository on GitHub.
|
||||||
|
|
||||||
|
Create a new branch for your feature or bug fix (git checkout -b feature/your-feature-name).
|
||||||
|
|
||||||
|
Make your changes and commit them with a clear, descriptive message.
|
||||||
|
|
||||||
|
Push your branch to your fork (git push origin feature/your-feature-name).
|
||||||
|
|
||||||
|
Create a Pull Request back to the main repository.
|
||||||
|
|
||||||
|
Please report any bugs or suggest features using the GitHub Issues tab.
|
||||||
|
► License
|
||||||
|
|
||||||
|
This project is licensed under the MIT License. See the LICENSE file for details.
|
||||||
|
► Project Structure
|
||||||
|
|
||||||
|
/SWAPSTATION_WEBAPP
|
||||||
|
|-- backend/ # Contains all Python/Flask backend source code
|
||||||
|
| |-- core/
|
||||||
|
| |-- models/
|
||||||
|
| |-- proto/
|
||||||
|
| |-- main.py # Main Flask application entry point
|
||||||
|
| |-- requirements.txt
|
||||||
|
|
|
||||||
|
|-- frontend/ # Contains all frontend assets
|
||||||
|
| |-- js/ # JavaScript files
|
||||||
|
| |-- css/ # CSS files
|
||||||
|
| |-- assets/ # Images and other static assets
|
||||||
|
| |-- *.html # HTML pages
|
||||||
|
|
|
||||||
|
|-- .gitignore # Specifies files to be ignored by Git
|
||||||
|
|-- Dockerfile # Instructions to build the production Docker image
|
||||||
|
|-- docker-compose.yml # Defines services for Docker Compose
|
||||||
|
|-- nginx.conf # Nginx configuration for the reverse proxy
|
||||||
|
|-- DEPLOYMENT.md # Detailed deployment guide
|
||||||
|
|-- README.md # This file
|
||||||
|
|
||||||
Loading…
Reference in New Issue