Manual d'usuari de Gestió Monedes

Versió PDF del manual: Manual d'usuari de Gestió Monedes (PDF)

Documentació tècnica: Documentació del projecte

1. Presentació del projecte

Gestió de Monedes (v1.1.0) és una aplicació web per administrar una col·lecció de monedes des del navegador. Permet crear registres nous, consultar-los, editar-los, eliminar-los, gestionar imatges i importar/exportar dades en format XML i CSV.

L'objectiu del projecte és oferir una eina clara, funcional i fàcil de desplegar per a entorns acadèmics o personals, sense dependre de cap framework extern.

Recurs	Enllaç	Finalitat
Aplicació web	Gestió de Monedes	Ús diari de l'aplicació
Manual PDF	Manual d'usuari en PDF	Consulta i impressió
Documentació tècnica	Documentació del projecte	Instal·lació, arquitectura i dependències
Extensió MediaWiki	Special:GestioMonedes	Catàleg integrat a la wiki

2. Arquitectura i tecnologies

L'aplicació segueix el patró Model-Vista-Controlador (MVC) i s'executa sobre PHP pur sense frameworks:

Capa	Fitxers principals	Responsabilitat
Presentació	`views/header.php`, `llistat.php`, `formulari.php`, `detall.php`	Genera el HTML que rep el navegador
Control	`index.php`, `MonedaController.php`, `ImportExportController.php`	Rep peticions, coordina model i vista
Model	`models/Moneda.php`, `models/GestorImatge.php`	Lògica de negoci, CRUD i gestió d'imatges
Base de dades	MariaDB · taula `monedes`	Emmagatzematge relacional via PDO

Esquema de la base de dades

Camp	Tipus	Nul·lable	Descripció
`id`	INT UNSIGNED PK AI	No	Identificador únic autoincremental
`nom`	VARCHAR(150)	No	Nom oficial de la moneda
`pais`	VARCHAR(100)	No	País o territori emissor
`valor`	DECIMAL(15,4)	No	Valor facial o numismàtic
`any_emissio`	SMALLINT	No	Any d'emissió (negatiu = a.C.)
`descripcio`	TEXT	Sí	Descripció lliure
`imatge`	VARCHAR(255)	Sí	Nom del fitxer d'imatge
`creat_el`	DATETIME	No	Data de creació automàtica
`actualitzat`	DATETIME	No	Data d'última modificació

Tecnologies principals

PHP 8.0+ (sense frameworks) — motor d'aplicació
MariaDB 10.5+ — base de dades relacional via PDO
Apache 2.4+ / Nginx 1.18+ — servidor web
HTML5, CSS3 i JavaScript vanilla — interfície d'usuari

3. Navegació principal

La barra superior de l'aplicació inclou aquests accessos:

Col·lecció — llistat de totes les monedes
Nova moneda — formulari per crear un registre nou
Import/Export — importació i exportació en XML i CSV
Documentació — descripció, arquitectura, manual i instal·lació

Flux d'ús recomanat:

Crear una moneda nova.
Afegir-hi dades i, si cal, una imatge.
Revisar la fitxa de detall.
Aplicar filtres o ordenació quan el catàleg creix.
Exportar les dades si es necessita una còpia de treball.

4. Crear una moneda

Per donar d'alta una moneda:

Fes clic a Nova moneda.
Omple els camps obligatoris:
- Nom — nom oficial o popular (ex: «Euro», «Pesseta», «Denari»)
- País — territori emissor (ex: «Espanya», «Unió Europea»)
- Valor — valor facial en format numèric (ex: 1.00, 0.50)
- Any d'emissió — per anys a.C., usa valors negatius (ex: -264)
Omple la Descripció si vols afegir informació contextual.
Puja una imatge si la vols associar al registre.
Prem Crear moneda.

Quan el formulari és correcte, el sistema desa la moneda, torna al llistat i mostra un missatge de confirmació.

5. Consultar el llistat i el detall

Des del llistat principal pots:

veure totes les monedes en forma de targetes
ordenar per nom, any o valor fent clic a les capçaleres
obrir la vista de detall fent clic sobre una targeta
editar o eliminar registres directament des de la targeta

La vista de detall mostra:

imatge principal
valor destacat
país o territori emissor
any d'emissió
nom complet
descripció
metadades del registre (identificador, dates de creació i modificació)

6. Editar i eliminar

6.1 Editar

Per editar una moneda:

Entra a la fitxa o fes clic a Editar des del llistat.
Modifica els camps necessaris.
Si no afegeixes una nova imatge, la imatge actual es conserva.
Si vols esborrar la imatge actual, marca l'opció corresponent.
Prem Desar canvis.

6.2 Eliminar

Per eliminar una moneda:

Fes clic a Eliminar (botó vermell).
Revisa el nom al quadre de confirmació.
Fes clic a Eliminar per confirmar, o Cancel·lar per abortar.

Atenció: l'eliminació és permanent i també suprimeix la imatge associada si existeix.

7. Cerca, filtres i ordenació

El panell de filtres permet cercar per:

Filtre	Descripció	Exemple
Nom	Cerca per coincidència parcial	`Euro` → troba «Euro», «Euronova»…
País	Cerca per coincidència parcial	`Esp` → troba «Espanya», «Esparta»…
Any d'emissió	Any exacte	`1999` o `-264`
Valor mínim	Valor ≥ al valor indicat	`0.50`
Valor màxim	Valor ≤ al valor indicat	`100`

Els filtres es poden combinar lliurement. L'enllaç Mostra-les totes o el botó × permet tornar a l'estat general del catàleg.

8. Gestió d'imatges

La pujada d'imatges admet:

JPG o JPEG
PNG
GIF
WebP

Característiques principals:

selecció manual de fitxer o arrossegar i deixar anar (drag & drop)
previsualització en temps real abans de desar
mida màxima: 5 MB
validació del tipus MIME real del fitxer
eliminació automàtica del fitxer quan s'esborra el registre

9. Importació i exportació

Des de la pantalla Import/Export pots:

exportar totes les monedes a XML
exportar totes les monedes a CSV
importar monedes des d'un XML vàlid
importar monedes des d'un CSV amb capçalera correcta

9.1 Exportar

L'exportació genera un fitxer descarregable directament des del navegador amb el nom monedes_YYYYMMDD_HHMMSS.xml o .csv.

9.2 Importar XML

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

L'aplicació informa del nombre de monedes importades i dels errors detectats.

9.3 Importar CSV

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

El sistema detecta automàticament el separador (punt i coma o coma) i valida la capçalera i el contingut mínim.

10. Bones pràctiques

Per treballar millor amb l'aplicació:

escriu noms i països de forma coherent i homogènia
revisa els valors numèrics i l'any abans de desar
usa la descripció per afegir context útil, no redundant
fes exportacions periòdiques si el catàleg és important
revisa els missatges d'èxit o error després de cada acció

11. Incidències habituals

Problema	Causa probable	Solució
Imatge no es puja	Format no admès o fitxer massa gran	Comprova que sigui JPG, PNG, GIF o WebP i que no superi 5 MB
Importació falla	Estructura XML o capçalera CSV incorrecta	Revisa el format del fitxer importat
No es troba un registre	Hi ha filtres actius	Fes clic a «Mostra-les totes» per eliminar els filtres
Dada incorrecta	Error en la creació o edició	Entra a editar el registre i corregeix el camp

12. Instal·lació i configuració

Aquesta secció descriu com desplegar l'aplicació en un servidor Ubuntu/Debian. La guia completa amb totes les opcions de configuració avançada es troba a la documentació tècnica del projecte.

12.1 Requisits del sistema

Component	Versió mínima	Recomanada
PHP	8.0	8.2 o superior
MariaDB	10.5	10.11 o superior
Servidor web	Apache 2.4 / Nginx 1.18	Apache 2.4+
Extensions PHP	pdo_mysql, mbstring, xml, fileinfo	—
Sistema operatiu	Linux, macOS, Windows (XAMPP)	Ubuntu 22.04 LTS

12.2 Passos d'instal·lació

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. Alternatives: variables d'entorn GESTIO_MONEDES_DB_* o editar directament config.php.

Pas 4 — Primera execució:

Obre el navegador a l'URL de l'aplicació. La base de dades i la taula es creen automàticament si les credencials són correctes. No cal executar cap script SQL manualment.

13. Dependències i resolució de problemes

13.1 Dependències

Dependència	Paquet	Verificació	Si falta
Servidor web	`apache2` o `nginx`	`systemctl status apache2`	`sudo apt install apache2 -y`
Motor PHP	`php` + `libapache2-mod-php`	`php -v`	`sudo apt install php libapache2-mod-php -y`
PDO MySQL	`php-mysql`	grep pdo_mysql	`sudo apt install php-mysql -y`
Multibyte strings	`php-mbstring`	grep mbstring	`sudo apt install php-mbstring -y`
XML	`php-xml`	grep simplexml	`sudo apt install php-xml -y`
Fileinfo	`php-fileinfo`	grep fileinfo	`sudo apt install php-fileinfo -y`
MariaDB	`mariadb-server`	`systemctl status mariadb`	`sudo apt install mariadb-server -y`

13.2 Resolució de problemes habituals

Error	Causa probable	Solució
Error de connexió a la BD	Credencials incorrectes o MariaDB aturat	Verifica `config.php` i executa `sudo systemctl status mariadb`
No s'ha pogut desar la imatge	Permisos incorrectes a `uploads/`	`chmod 755 uploads/ && chown www-data uploads/`
Pàgina en blanc	Error de PHP ocult	Activa `GESTIO_MONEDES_APP_DEBUG=1` o revisa `/var/log/apache2/error.log`
Error 413 (fitxer massa gran)	Límit de pujada del servidor	Augmenta `upload_max_filesize` a `php.ini` i reinicia Apache
Caràcters incorrectes	Charset de la BD no és utf8mb4	`ALTER DATABASE gestio_monedes CHARACTER SET utf8mb4`
Falta una extensió PHP	No estan carregats pdo_mysql, mbstring, xml o fileinfo	Instal·la el paquet corresponent amb `apt` i reinicia Apache

14. Integracions CMS

El projecte inclou tres integracions opcionals per a sistemes de gestió de continguts. Totes llegeixen i escriuen des de MariaDB, CSV i XML.

14.1 Plugin WordPress

Nom: Gestio Monedes WP
Shortcode: [gestio_monedes_llistat]
Funcions: mostra el catàleg al frontend; permet inserir monedes des del panell d'administració; admet filtres per nom, país, any i valor.
Fonts de dades: MariaDB, CSV, XML

14.2 Extensió MediaWiki

Nom: GestioMonedes
Pàgina especial: Special:GestioMonedes
Funcions: consulta, filtres, inserció de monedes i visualització d'imatges directament des de la wiki.
Fonts de dades: MariaDB, CSV, XML

14.3 Component Joomla

Nom: com_gestiomonedes
Frontend: Gestió Monedes Joomla
Funcions: frontend públic amb catàleg i filtres; backend d'administració per configurar la font de dades i inserir monedes.
Fonts de dades: MariaDB, CSV, XML