Manual d'usuari de Gestió Monedes

1. Presentació del projecte

Gestió de Monedes és una aplicació web per administrar una col·lecció de monedes de forma centralitzada. Permet registrar nous exemplars, consultar-los des d'un catàleg visual, editar-ne les dades, eliminar registres, pujar imatges i intercanviar informació amb fitxers XML i CSV.

El propòsit del projecte és oferir una eina clara, funcional i fàcil de desplegar en un entorn acadèmic o personal, utilitzant una arquitectura senzilla basada en PHP i MariaDB.

2. Accés i enllaços principals

Per treballar amb l'aplicació i la seva documentació tens disponibles aquests recursos:

Quan entres a l'aplicació trobaràs una navegació superior amb quatre accessos principals:

Col·lecció
Nova moneda
Import/Export
Documentació

3. Funcionament general

L'ús habitual de l'aplicació segueix aquest flux:

Crear una moneda nova.
Completar-ne les dades principals.
Afegir-hi una imatge si es vol documentar visualment.
Consultar la fitxa de detall per validar la informació.
Aplicar filtres i ordenacions quan el catàleg creix.
Exportar el conjunt de dades si es necessita una còpia de treball o un intercanvi d'informació.

4. Pantalles principals

4.1 Col·lecció

La pantalla principal mostra les monedes en forma de targetes. Cada targeta presenta, de manera resumida:

nom de la moneda
país o territori emissor
any d'emissió
valor
accessos ràpids a veure, editar o eliminar

Des d'aquesta pantalla també es mostren estadístiques generals i el panell de filtres.

4.2 Nova moneda

La pantalla de creació permet introduir un nou registre. És la via principal per ampliar el catàleg.

4.3 Import/Export

La pantalla d'importació i exportació serveix per treballar amb fitxers XML i CSV. Està pensada per facilitar la còpia de dades, la migració o la reutilització de contingut.

4.4 Documentació

La pantalla de documentació reuneix la descripció del projecte, la planificació, el manual d'usuari i les instruccions d'instal·lació.

5. Crear una moneda

Per donar d'alta una moneda nova:

Fes clic a Nova moneda.
Omple els camps obligatoris:
- Nom de la moneda
- País o territori emissor
- Valor facial o numismàtic
- Any d'emissió
Omple el camp de Descripció si vols afegir context històric o tècnic.
Puja una imatge si la vols associar al registre.
Prem Crear moneda.

Si tot és correcte, el sistema desa la informació i torna al llistat amb un missatge de confirmació.

6. Consultar i interpretar el detall d'una moneda

En fer clic sobre una targeta o sobre el botó de detall, s'obre la fitxa completa de la moneda. Aquesta vista mostra:

imatge principal
valor destacat
país o territori emissor
any d'emissió
nom complet
descripció
metadades del registre, com l'identificador i les dates de creació i actualització

La vista de detall serveix per revisar la informació abans d'editar-la o eliminar-la.

7. Editar una moneda

Per modificar un registre existent:

Accedeix a la vista de detall o fes clic a Editar des del llistat.
Modifica els camps necessaris.
Si no puges una nova imatge, la imatge actual es conserva.
Si cal, pots marcar l'opció per eliminar la imatge actual.
Prem Desar canvis.

L'aplicació actualitza el registre i mostra un missatge d'èxit si l'operació s'ha completat correctament.

8. Eliminar una moneda

Per eliminar una moneda:

Fes clic a Eliminar.
Revisa el nom de la moneda al quadre de confirmació.
Confirma l'acció.

Aquesta operació és permanent. Si la moneda tenia una imatge associada, el fitxer també s'elimina del servidor.

9. Cerca, filtres i ordenació

El panell de filtres permet localitzar registres concrets de manera ràpida. Els filtres disponibles són:

Nom
País
Any d'emissió
Valor mínim
Valor màxim

Els filtres es poden combinar. Això permet, per exemple:

trobar totes les monedes d'un país concret
localitzar monedes d'un any determinat
mostrar només monedes dins d'un rang de valor

També és possible ordenar els resultats per:

nom
any
valor

Si hi ha filtres actius, l'enllaç Mostra-les totes permet tornar al llistat complet.

10. Gestió d'imatges

La pujada d'imatges està integrada al formulari de creació i edició. El comportament previst és:

selecció manual del fitxer
arrossegar i deixar anar la imatge a la zona de pujada
previsualització abans de desar
validació del fitxer abans de l'emmagatzematge

Formats admesos:

JPG o JPEG
PNG
GIF
WebP

Recomanacions:

utilitza imatges clares i ben retallades
evita fitxers massa grans (màxim 5 MB)
comprova la previsualització abans de desar

11. Importació i exportació

11.1 Exportar el catàleg

Des de la pantalla Import/Export pots descarregar totes les monedes en dos formats:

XML
CSV

L'exportació es genera automàticament i el navegador descarrega el fitxer amb el nom monedes_YYYYMMDD_HHMMSS.xml o .csv.

11.2 Importar XML

Per importar dades en XML:

Ves a Import/Export.
Selecciona un fitxer XML amb l'estructura correcta.
Prem Importar des de XML.

Quan acaba el procés, el sistema informa del nombre de monedes inserides i dels errors detectats si el fitxer no és vàlid del tot.

11.3 Importar CSV

Per importar dades en CSV:

Prepara un fitxer amb la capçalera: nom;país;valor;any emissió;descripció
Selecciona'l des del formulari.
Prem Importar des de CSV.

El sistema valida el tipus de fitxer, la mida, la capçalera i el contingut mínim necessari abans de desar registres.

12. Bones pràctiques d'ús

Per mantenir el catàleg en bon estat:

escriu noms coherents i homogenis
revisa sempre el valor i l'any abans de desar
utilitza descripcions útils i no redundants
exporta les dades periòdicament si el catàleg és important
revisa els missatges de confirmació o error després de cada operació

13. Incidències habituals

Situacions freqüents i què revisar:

Si una imatge no puja, comprova que el format sigui admès (JPG, PNG, GIF, WebP) i que no superi 5 MB.
Si una importació falla, revisa l'estructura XML o la capçalera CSV.
Si no trobes un registre, esborra els filtres actius i revisa l'ordenació aplicada.
Si una dada es veu malament, entra al detall i corregeix el registre des d'edició.

14. Arquitectura i tecnologies del projecte

Gestió de Monedes (versió 1.1.0) és una aplicació web PHP pura, sense frameworks externs. S'executa sobre Apache o Nginx amb MariaDB i segueix el patró Model-Vista-Controlador (MVC):

Controladors — MonedaController.php i ImportExportController.php gestionen les peticions i coordinen model i vista.
Models — Moneda.php conté tota la lògica CRUD i de filtres; GestorImatge.php gestiona la pujada, validació i eliminació d'imatges.
Vistes — les plantilles PHP a views/ generen el HTML que rep el navegador.
Enrutador — index.php rep totes les peticions i les distribueix pel paràmetre ?accio=.

Esquema de la base de dades

La base de dades consta d'una taula monedes amb els camps:

id — clau primària autoincremental
nom — nom oficial de la moneda (VARCHAR 150)
pais — país o territori emissor (VARCHAR 100)
valor — valor facial o numismàtic (DECIMAL 15,4)
any_emissio — any d'emissió, negatiu per a.C. (SMALLINT)
descripcio — descripció lliure (TEXT, opcional)
imatge — nom del fitxer d'imatge (VARCHAR 255, opcional)
creat_el — data de creació automàtica (DATETIME)
actualitzat — data d'última modificació (DATETIME)

Integracions CMS opcionals

El projecte inclou tres integracions per a sistemes de gestió de continguts:

Plugin WordPress — shortcode [gestio_monedes_llistat] que mostra el catàleg al frontend; panell d'administració per inserir i gestionar monedes.
Extensió MediaWiki — pàgina especial Especial:GestioMonedes que permet consultar, filtrar i inserir monedes directament des de la wiki, amb capçalera informativa, panell resum, filtres visibles i targetes de resultat compactes.
Component Joomla — com_gestiomonedes amb frontend públic i backend d'administració integrats al CMS.

Les tres integracions llegeixen i escriuen des de MariaDB, CSV i XML, compartint la mateixa configuració privada del servidor.

En el cas de MediaWiki, la pàgina especial s'ha pensat com una entrada ràpida al catàleg: a la part superior es mostra la font activa i un resum del conjunt de dades, al centre hi ha el formulari de consulta i d'inserció, i a la part inferior es mostren les monedes en forma de targetes llegibles amb imatge, valor, país, any i descripció.

15. Instal·lació i configuració ràpida

Aquesta secció resumeix els passos per desplegar l'aplicació en un servidor Ubuntu/Debian. Per a la guia completa amb totes les opcions de configuració, consulta la documentació tècnica del projecte.

Requisits mínims

PHP 8.0 o superior
Extensions PHP: pdo_mysql, mbstring, xml, fileinfo
MariaDB 10.5 o superior
Apache 2.4+ o Nginx 1.18+
Sistema operatiu: Ubuntu 22.04 LTS (recomanat), Debian, macOS o Windows amb XAMPP

Pas 1 — Instal·lar dependències

sudo apt update && sudo apt install -y apache2 php php-mysql php-mbstring php-xml php-fileinfo mariadb-server
sudo systemctl enable --now apache2 mariadb

Pas 2 — Copiar el projecte i preparar els permisos

cp -r gestio_monedes/ /var/www/html/
chmod 755 /var/www/html/gestio_monedes/uploads/
chown www-data:www-data /var/www/html/gestio_monedes/uploads/

Pas 3 — Configurar les credencials

Opció recomanada: crear el fitxer /etc/gestio_monedes/config.local.php fora del directori web amb les credencials de MariaDB. Alternatives: variables d'entorn GESTIO_MONEDES_DB_HOST, GESTIO_MONEDES_DB_NAME, GESTIO_MONEDES_DB_USER i GESTIO_MONEDES_DB_PASS, o editar directament config.php.

Pas 4 — Primera execució

Obre el navegador a l'URL de l'aplicació. Si les credencials són correctes, la base de dades gestio_monedes i la taula monedes es creen automàticament en el primer accés. No cal executar cap script SQL manualment.

16. Dependències i resolució de problemes

Dependències principals

Totes les dependències es gestionen amb el gestor de paquets del sistema operatiu. No hi ha cap biblioteca externa de PHP ni cap gestor de paquets addicional.

apache2 o nginx — servidor web
php + libapache2-mod-php — motor d'aplicació (8.0+)
php-mysql — extensió PDO per a MariaDB
php-mbstring — codificació de caràcters multibyte
php-xml — processament XML per a importació i exportació
php-fileinfo — validació del tipus MIME d'imatges
mariadb-server — sistema de gestió de base de dades

Per verificar que totes les extensions estan actives:

php -m | grep -E "pdo_mysql|mbstring|simplexml|fileinfo"

Resolució de problemes habituals

Si hi ha un error de connexió a la base de dades, comprova les credencials i l'estat del servei:

sudo systemctl status mariadb

Si una imatge no es pot desar, revisa els permisos del directori d'uploads:

chmod 755 /var/www/html/gestio_monedes/uploads/
chown www-data:www-data /var/www/html/gestio_monedes/uploads/

Si la pàgina apareix en blanc, activa temporalment el mode de depuració i revisa els registres:

export GESTIO_MONEDES_APP_DEBUG=1
tail -f /var/log/apache2/error.log

Si les imatges pujades pesen massa i donen error 413, augmenta els límits a php.ini:

upload_max_filesize = 10M
post_max_size = 12M

I reinicia el servidor web:

sudo systemctl restart apache2

17. Resum final

Gestió de Monedes és una eina per fer un seguiment complet d'una col·lecció numismàtica amb una interfície simple, funcional i preparada per treballar amb dades reals. Consta de l'aplicació principal en PHP i MariaDB, tres integracions opcionals per a WordPress, MediaWiki i Joomla, i una documentació completa en format web, wiki, PDF i DOCX.

Per a qualsevol consulta tècnica sobre instal·lació, arquitectura o configuració avançada, consulta la documentació tècnica completa.

Recursos finals: