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