UrNetwork-Stats-Dashboard-r.../readme.md

275 lines
11 KiB
Markdown
Raw Normal View History

2025-07-05 20:32:55 +02:00
# UrNetwork Stats Dashboard - Refactored
Hits - [demo](http://38.242.156.120:90) | [![Hits](https://hits.sh/38.242.156.120:90.svg)](https://hits.sh/38.242.156.120:90/)
Hits - [repo](https://forgejo.plainrock127.xyz/mxnticek/UrNetwork-Stats-Dashboard-remade) | [![Hits](https://hits.sh/forgejo.plainrock127.xyz/mxnticek/UrNetwork-Stats-Dashboard-remade.svg)](https://hits.sh/forgejo.plainrock127.xyz/mxnticek/UrNetwork-Stats-Dashboard-remade/)
-----
## 🇬🇧 English
### About The Project
This project is a significantly enhanced and refactored version of the original [UrNetwork Stats Dashboard](https://github.com/techroy23/UrNetwork-Stats-Dashboard). The application is designed to track, store, and visualize statistics about data transfers (both paid and unpaid) and earnings from your UrNetwork account.
The entire application is packaged into a single `main_app.py` file for simplicity, yet it contains robust features including a web-based installer, authentication, public/private views, interactive charts, a provider map, and support for webhook notifications.
> **A Note from the Author**
>
> I know I might get some hate for using AI to build and refactor this, but since I have access to it for free, I want to make the most of it. Plus, no offense to my friends who can code, but Gemini often explains concepts more clearly! (no hate)
> (this readme is made by ai too.... please just dont hate me, im a stupid bitch-ass idiot that's almost braindead and im not even kidding.)
-----
### ✨ Features
* **🐍 All-in-One Python Script:** The entire application logic, including the frontend, is contained within a single `main_app.py` file.
* **🚀 Web-Based Installer:** A simple setup wizard guides you through configuring your UrNetwork API credentials on the first run.
* **🔐 Dual Views (Public/Private):**
* **Public Dashboard:** Displays summary stats, total data over time, and a world map of provider locations. Perfect for a quick overview.
* **Private Dashboard:** After logging in, you get access to detailed charts, a complete history of data points, webhook management, and other administrative functions.
* **📊 Interactive Charts:** Utilizes `Chart.js` for data visualization, including:
* Total data provided over time.
* Paid vs. Unpaid data comparison.
* A bar chart showing data change between intervals.
* **🗺️ Provider Map:** Displays the number of active providers by country on a world map using `Leaflet.js`.
* **⚙️ Automated Data Collection:** A scheduler (`APScheduler`) automatically fetches and saves new data from the API every 15 minutes.
* **🔔 Webhook Notifications:** Add your own webhook URLs (e.g., for Discord) to receive notifications with each new data sync.
* **🎨 Modern UI:**
* Styled with **Tailwind CSS**.
* **Light/Dark/System theme** support.
* Fully responsive design.
* **💾 Persistent Storage:** Uses `SQLAlchemy` and a `SQLite` database to store historical data.
-----
### 🚀 Getting Started
#### Prerequisites
* Python 3.x
* Pip (Python package manager)
#### Installation
1. **Clone the repository:**
```bash
git clone <YOUR_REPOSITORY_URL>
cd <FOLDER_NAME>
```
2. **Create and activate a virtual environment (recommended):**
```bash
python -m venv venv
# On Windows
.venvScriptsactivate
# On macOS / Linux
source venv/bin/activate
```
3. **Install requirements:**
Create a `requirements.txt` file with the following content:
```txt
Flask
Flask-SQLAlchemy
Flask-APScheduler
requests
python-dateutil
gunicorn
```
Then, install them:
```bash
pip install -r requirements.txt
```
4. **Run the application:**
```bash
python main_app.py
```
*Note: For a production environment, it's better to use a WSGI server like `gunicorn`.*
```bash
gunicorn --bind 0.0.0.0:90 main_app:app
```
5. **Web-based Configuration:**
* Open `http://localhost:90` (or your server's IP address) in your browser.
* You will be redirected to the setup page. Enter your UrNetwork **username** and **password**.
* Upon successful verification, a `.env` file will be created with your credentials and a secret key will be generated for the session. The application is now installed.
-----
### 🕹️ Usage
After installation, the application is ready to use.
* **Public Dashboard (`/`):** The main page, accessible to anyone. It shows summary stats and the provider map. The data on this page updates automatically every minute without a page refresh.
* **Private Dashboard (`/dashboard`):**
* Click on "Owner Dashboard" to access it.
* Log in using the same credentials you entered during setup.
* Here you will find detailed charts, the full history of all measurements, and you can manage your webhooks.
* **Fetch Now:** Manually triggers a data fetch from the API.
* **Clear All Data:** Deletes all historical data from the database.
* **Webhook Management:** Add or remove URLs for notifications.
-----
### 🛠️ Tech Stack
* **Backend:** [Flask](https://flask.palletsprojects.com/)
* **Database:** [Flask-SQLAlchemy](https://flask-sqlalchemy.palletsprojects.com/) (with SQLite)
* **Job Scheduler:** [Flask-APScheduler](https://github.com/viniciuschiele/flask-apscheduler)
* **Frontend:** [Tailwind CSS](https://tailwindcss.com/), [Chart.js](https://www.chartjs.org/), [Leaflet.js](https://leafletjs.com/)
* **HTTP Requests:** [Requests](https://requests.readthedocs.io/en/latest/)
-----
### 🙏 Acknowledgements
* Original concept and project by **[techroy23](https://github.com/techroy23/UrNetwork-Stats-Dashboard)**.
* This version was completely refactored and extended with the help of AI.
<br>
<hr>
<br>
## 🇨🇿 Česky
### O Projektu
Tento projekt je výrazně vylepšená a refaktorovaná verze původního [UrNetwork Stats Dashboard](https://github.com/techroy23/UrNetwork-Stats-Dashboard). Aplikace slouží ke sledování, ukládání a vizualizaci statistik o přenesených datech (placených i neplacených) a výdělcích z vašeho účtu v síti UrNetwork.
Celá aplikace je zabalena do jediného souboru `main_app.py` pro jednoduchost, ale obsahuje robustní funkce, včetně webového instalátoru, autentizace, veřejného a soukromého pohledu, interaktivních grafů, mapy poskytovatelů a podpory pro webhooky.
> **Poznámka od Autora**
>
> Vím, že asi dostanu hejt za to, že jsem na stavbu a refaktoring použil AI, ale když k tomu mám přístup zadarmo, chci toho co nejvíc využít. Navíc, nic proti mým kamarádům, co umí programovat, ale Gemini mi to často vysvětlí srozumitelněji! (no hate)
> (Tento soubor readme je také vytvořen umělou inteligencí... Prosím, nenávidějte mě, jsem debilní idiot, který je skoro mrtvýmozkově, a to ani nepřeháním.)
-----
### ✨ Klíčové Vlastnosti
* **🐍 All-in-One Python Skript:** Celá logika aplikace, včetně frontendu, je obsažena v jediném souboru `main_app.py`.
* **🚀 Webový Instalátor:** Při prvním spuštění vás provede jednoduchým nastavením přihlašovacích údajů k UrNetwork API.
* **🔐 Dva Pohledy (Public/Private):**
* **Veřejný Dashboard:** Zobrazuje souhrnné statistiky, celkový objem dat v čase a mapu poskytovatelů po celém světě. Ideální pro rychlý přehled.
* **Soukromý Dashboard:** Po přihlášení získáte přístup k detailním grafům, kompletní historii měření, správě webhooků a dalším administrátorským funkcím.
* **📊 Interaktivní Grafy:** Využívá `Chart.js` pro vizualizaci dat, včetně:
* Celkový objem dat v čase.
* Porovnání placených vs. neplacených dat.
* Graf přírůstků dat mezi jednotlivými měřeními.
* **🗺️ Mapa Poskytovatelů:** Zobrazuje na mapě světa (pomocí `Leaflet.js`) počet aktivních poskytovatelů v jednotlivých zemích.
* **⚙️ Automatický Sběr Dat:** Plánovač (`APScheduler`) automaticky stahuje a ukládá data z API každých 15 minut.
* **🔔 Notifikace přes Webhooky:** Možnost přidat si vlastní webhooky (např. pro Discord) a dostávat notifikace při každé nové synchronizaci dat.
* **🎨 Moderní UI:**
* Stylováno pomocí **Tailwind CSS**.
* Podpora **Světlého/Tmavého režimu** s možností synchronizace s nastavením systému.
* Plně responzivní design.
* **💾 Perzistentní Úložiště:** Využívá `SQLAlchemy` a `SQLite` databázi pro ukládání historických dat.
-----
### 🚀 Jak začít
#### Požadavky
* Python 3.x
* Pip (správce balíčků pro Python)
#### Instalace
1. **Klonujte repozitář:**
```bash
git clone <URL_VAŠEHO_REPOZITÁŘE>
cd <NÁZEV_SLOŽKY>
```
2. **Vytvořte a aktivujte virtuální prostředí (doporučeno):**
```bash
python -m venv venv
# Windows
.venvScriptsactivate
# macOS / Linux
source venv/bin/activate
```
3. **Nainstalujte potřebné balíčky:**
Vytvořte soubor `requirements.txt` s následujícím obsahem:
```txt
Flask
Flask-SQLAlchemy
Flask-APScheduler
requests
python-dateutil
gunicorn
```
A poté je nainstalujte:
```bash
pip install -r requirements.txt
```
4. **Spusťte aplikaci:**
```bash
python main_app.py
```
*Poznámka: Pro produkční nasazení je lepší použít WSGI server jako `gunicorn`.*
```bash
gunicorn --bind 0.0.0.0:90 main_app:app
```
5. **Webová konfigurace:**
* Otevřete v prohlížeči adresu `http://localhost:90` (nebo IP adresu vašeho serveru).
* Budete přesměrováni na instalační stránku. Zde zadejte své **uživatelské jméno** a **heslo** k účtu UrNetwork.
* Po úspěšném ověření se automaticky vytvoří soubor `.env` s vašimi údaji a vygeneruje se tajný klíč pro session. Aplikace se tímto nainstaluje.
-----
### 🕹️ Použití
Po instalaci je aplikace připravena k použití.
* **Veřejný Dashboard (`/`):** Hlavní stránka dostupná komukoliv. Zobrazuje souhrnné statistiky a mapu. Data na této stránce se automaticky aktualizují každou minutu bez nutnosti obnovení stránky.
* **Soukromý Dashboard (`/dashboard`):**
* Pro přístup klikněte na "Owner Dashboard".
* Přihlaste se pomocí stejných údajů, které jste zadali při instalaci.
* Zde naleznete detailní grafy, historii všech měření a můžete spravovat webhooky.
* **Fetch Now:** Manuálně spustí sběr dat z API.
* **Clear All Data:** Smaže veškerá historická data z databáze.
* **Webhook Management:** Přidávejte nebo odebírejte URL pro notifikace.
-----
### 🛠️ Použité Technologie
* **Backend:** [Flask](https://flask.palletsprojects.com/)
* **Databáze:** [Flask-SQLAlchemy](https://flask-sqlalchemy.palletsprojects.com/) (s SQLite)
* **Plánovač úloh:** [Flask-APScheduler](https://github.com/viniciuschiele/flask-apscheduler)
* **Frontend:** [Tailwind CSS](https://tailwindcss.com/), [Chart.js](https://www.chartjs.org/), [Leaflet.js](https://leafletjs.com/)
* **HTTP Požadavky:** [Requests](https://requests.readthedocs.io/en/latest/)
-----
### 🙏 Poděkování
* Původní koncept a projekt vytvořil **[techroy23](https://github.com/techroy23/UrNetwork-Stats-Dashboard)**.
* Tato verze byla kompletně refaktorována a rozšířena pomocí AI.