MSM VAT Calculator

Profesjonalny kalkulator VAT dla WordPress z nowoczesnym, responsywnym interfejsem. Plugin pozwala osadzić formularz kalkulatora na dowolnej stronie za pomocą shortcode i zapisuje wszystkie obliczenia do bazy danych.

---

✨ Funkcje

Formularz kalkulatora

• Nazwa produktu - pole tekstowe
• Kwota netto - pole numeryczne z walidacją
• Waluta - pole zablokowane, wartość konfigurowana w ustawieniach (domyślnie PLN)
• Stawka VAT - lista rozwijana z konfigurowalnymi stawkami

Obsługiwane stawki VAT

Domyślnie plugin zawiera wszystkie polskie stawki VAT:

• 23%, 22%, 8%, 7%, 5%, 3%, 0%
• zw. (zwolniony)
• np. (nie podlega)
• o.o. (odwrotne obciążenie)

Zapisywane dane

Każde obliczenie zapisywane jest do bazy danych wraz z:

• Nazwą produktu
• Kwotą netto
• Stawką VAT
• Kwotą podatku
• Kwotą brutto
• Walutą
• Adresem IP użytkownika
• Datą i godziną wypełnienia formularza

Panel administracyjny

• Konfiguracja waluty
• Zarządzanie stawkami VAT (dodawanie, edycja, usuwanie)
• Historia wszystkich obliczeń z paginacją
• Możliwość usuwania wpisów

Design

• W pełni responsywny (mobile-first)
• Animacje i efekty hover
• CSS z metodologią BEM

---

📦 Wymagania

• WordPress 5.0 lub nowszy
• PHP 7.4 lub nowszy
• MySQL 5.6 lub nowszy

---

🚀 Instalacja

Metoda 1: Przez panel WordPress

1. Pobierz plik msm-vat-calculator.zip
2. Przejdź do Wtyczki → Dodaj nową → Wyślij wtyczkę
3. Wybierz pobrany plik ZIP i kliknij Zainstaluj teraz
4. Aktywuj plugin

Metoda 2: Przez FTP

1. Rozpakuj archiwum msm-vat-calculator.zip
2. Wgraj folder msm-vat-calculator do katalogu /wp-content/plugins/
3. Aktywuj plugin w panelu WordPress

---

📖 Użycie

Podstawowe użycie

Wstaw shortcode na dowolnej stronie, wpisie lub widgecie:

[msm_vat_calculator]

Przykład w edytorze blokowym (Gutenberg)

1. Dodaj blok Shortcode
2. Wpisz [msm_vat_calculator]
3. Zapisz stronę

Przykład w szablonie PHP

<?php echo do_shortcode('[msm_vat_calculator]'); ?>

---

⚙️ Panel administracyjny

Po aktywacji pluginu w menu pojawi się nowa pozycja Kalkulator VAT z podstronami:

Strona główna

• Shortcode do skopiowania
• Statystyki (liczba obliczeń)
• Szybkie linki do ustawień i historii

Ustawienia

Waluta:

• Zmień symbol waluty wyświetlany w formularzu (np. PLN, EUR, USD)

Stawki VAT:

• Dodawaj nowe stawki (klucz + etykieta)
• Edytuj istniejące stawki
• Usuwaj niepotrzebne stawki

Uwaga: Klucz to wartość liczbowa (np. 23) lub kod specjalny (np. zw). Etykieta to tekst wyświetlany użytkownikowi (np. 23% lub zw.).

Historia obliczeń

• Tabela ze wszystkimi zapisanymi obliczeniami
• Sortowanie od najnowszych
• Paginacja (20 wpisów na stronę)
• Możliwość usuwania pojedynczych wpisów

---

🏷️ Shortcode

Podstawowy shortcode

[msm_vat_calculator]

Shortcode nie wymaga żadnych atrybutów - wszystkie ustawienia pobierane są z panelu administracyjnego.

---

📁 Struktura plików

msm-vat-calculator/
├── msm-vat-calculator.php    # Główny plik pluginu
├── uninstall.php             # Obsługa odinstalowania
├── readme.txt                # Dokumentacja WordPress.org
├── README.md                 # Dokumentacja GitHub
├── index.php                 # Ochrona katalogu
│
├── assets/
│   ├── css/
│   │   ├── frontend.css      # Style formularza
│   │   ├── admin.css         # Style panelu admina
│   │   └── index.php
│   │
│   ├── js/
│   │   ├── frontend.js       # Obsługa AJAX formularza
│   │   ├── admin.js          # Funkcje panelu admina
│   │   └── index.php
│   │
│   └── index.php

---

🛠️ Technologie

Backend

• PHP 7.4+ - programowanie obiektowe
• WordPress API - Custom Post Types, Settings API, AJAX
• Bezpieczeństwo - nonce verification, sanitization, escaping

Frontend

• HTML5 - semantyczny markup
• CSS3 - Custom Properties, Flexbox, animacje
• JavaScript (ES6) - moduły, async/await

Metodologie

• BEM (Block Element Modifier) dla CSS z prefixem msm-
• AJAX do asynchronicznego przetwarzania formularza
• Responsive Design - mobile-first approach

---

❓ FAQ

Jak zmienić walutę?

Przejdź do Kalkulator VAT → Ustawienia i zmień wartość w polu "Symbol waluty".

Jak dodać własną stawkę VAT?

W ustawieniach kliknij Dodaj stawkę, wprowadź klucz (np. 15) i etykietę (np. 15%).

Gdzie są przechowywane dane?

Wszystkie obliczenia zapisywane są jako Custom Post Type (msm_vat_entry) w standardowych tabelach WordPress.

Czy plugin jest zgodny z RODO?

Plugin zapisuje adresy IP użytkowników. Upewnij się, że informujesz o tym w swojej polityce prywatności.

Co się stanie po odinstalowaniu pluginu?

Plik uninstall.php automatycznie usunie wszystkie dane pluginu (obliczenia i ustawienia) z bazy danych.

Czy mogę użyć kilku kalkulatorów na jednej stronie?

Tak, możesz wstawić shortcode wielokrotnie, ale każdy formularz będzie działał niezależnie.

---

📝 Changelog

1.0.0 (2024)

• 🎉 Pierwsza wersja pluginu
• ✅ Formularz kalkulatora VAT z shortcode
• ✅ Obsługa wszystkich polskich stawek VAT
• ✅ Panel administracyjny z ustawieniami
• ✅ Historia obliczeń z paginacją
• ✅ Zapisywanie IP i daty
• ✅ Responsywny design
• ✅ Obsługa AJAX

---

📄 Licencja

Ten plugin jest udostępniany na licencji GPL v2 lub późniejszej.

MSM VAT Calculator is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
any later version.

MSM VAT Calculator is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

---

🤝 Wsparcie

Jeśli masz pytania lub znalazłeś błąd, utwórz Issue na GitHubie.

---

Made with ❤️ for WordPress