Edición de «Manual d'usuari de Gestió Monedes»

__TOC__
= 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:

* [https://fmehmood.cat/gestio_monedes/ Aplicació Gestió de Monedes]
* [https://fmehmood.cat/gestio_monedes/documentacio.php Documentació tècnica del projecte]
* [https://fmehmood.cat/mediawiki/index.php/Manual_d%27usuari_de_Gesti%C3%B3_Monedes Manual d'usuari a MediaWiki]
* [https://fmehmood.cat/mediawiki/index.php/Especial:GestioMonedes Extensió MediaWiki GestioMonedes]
* [https://fmehmood.cat/gestio_monedes/docs/manual_usuari_gestio_monedes.pdf Manual d'usuari en PDF]
* [https://fmehmood.cat/gestio_monedes/docs/manual_usuari_gestio_monedes.docx Manual d'usuari en DOCX]
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 <code>monedes_YYYYMMDD_HHMMSS.xml</code> o <code>.csv</code>.

=== 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: <code>nom;país;valor;any emissió;descripció</code>
# 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.2) é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''' — <code>MonedaController.php</code> i <code>ImportExportController.php</code> gestionen les peticions i coordinen model i vista.
* '''Models''' — <code>Moneda.php</code> conté tota la lògica CRUD i de filtres; <code>GestorImatge.php</code> gestiona la pujada, validació i eliminació d'imatges.
* '''Vistes''' — les plantilles PHP a <code>views/</code> generen el HTML que rep el navegador.
* '''Enrutador''' — <code>index.php</code> rep totes les peticions i les distribueix pel paràmetre <code>?accio=</code>.
=== Esquema de la base de dades ===

La base de dades consta d'una taula <code>monedes</code> amb els camps:

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

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

* '''Plugin WordPress''' — shortcode <code>[gestio_monedes_llistat]</code> que mostra el catàleg al frontend amb diagnòstic de fonts, selector de font, ordenació, límit visible i filtre específic d'imatges; panell d'administració per inserir i gestionar monedes.
* '''Extensió MediaWiki''' — pàgina especial <code>Especial:GestioMonedes</code> que permet consultar, filtrar i inserir monedes directament des de la wiki, amb diagnòstic de fonts, ordenació, límit visible, filtre específic d'imatges i targetes de resultat compactes.
* '''Component Joomla''' — <code>com_gestiomonedes</code> 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, a continuació apareix un diagnòstic visual de MariaDB, CSV i XML, 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, descripció i darrera actualització.

== 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 [https://fmehmood.cat/gestio_monedes/documentacio.php#instalacio documentació tècnica del projecte].

=== Requisits mínims ===

* PHP 8.0 o superior
* Extensions PHP: <code>pdo_mysql</code>, <code>mbstring</code>, <code>xml</code>, <code>fileinfo</code>
* 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 ===

<pre>
sudo apt update &amp;&amp; sudo apt install -y apache2 php php-mysql php-mbstring php-xml php-fileinfo mariadb-server
sudo systemctl enable --now apache2 mariadb
</pre>

=== Pas 2 — Copiar el projecte i preparar els permisos ===

<pre>
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/
</pre>

=== Pas 3 — Configurar les credencials ===

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

=== Pas 4 — Primera execució ===

Obre el navegador a l'URL de l'aplicació. Si les credencials són correctes, la base de dades <code>gestio_monedes</code> i la taula <code>monedes</code> 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.

* <code>apache2</code> o <code>nginx</code> — servidor web
* <code>php</code> + <code>libapache2-mod-php</code> — motor d'aplicació (8.0+)
* <code>php-mysql</code> — extensió PDO per a MariaDB
* <code>php-mbstring</code> — codificació de caràcters multibyte
* <code>php-xml</code> — processament XML per a importació i exportació
* <code>php-fileinfo</code> — validació del tipus MIME d'imatges
* <code>mariadb-server</code> — sistema de gestió de base de dades
Per verificar que totes les extensions estan actives:

<pre>
php -m | grep -E &quot;pdo_mysql|mbstring|simplexml|fileinfo&quot;
</pre>

=== Resolució de problemes habituals ===

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

<pre>
sudo systemctl status mariadb
</pre>

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

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

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

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

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

<pre>
upload_max_filesize = 10M
post_max_size = 12M
</pre>

I reinicia el servidor web:

<pre>
sudo systemctl restart apache2
</pre>

== 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 [https://fmehmood.cat/gestio_monedes/documentacio.php documentació tècnica completa].

Recursos finals:

* [https://fmehmood.cat/gestio_monedes/ Aplicació Gestió de Monedes]
* [https://fmehmood.cat/gestio_monedes/documentacio.php Documentació tècnica del projecte]
* [https://fmehmood.cat/mediawiki/index.php/Manual_d%27usuari_de_Gesti%C3%B3_Monedes Manual d'usuari a MediaWiki]
* [https://fmehmood.cat/gestio_monedes/docs/manual_usuari_gestio_monedes.pdf Manual d'usuari en PDF]
* [https://fmehmood.cat/gestio_monedes/docs/manual_usuari_gestio_monedes.docx Manual d'usuari en DOCX]