Ir al contenido

Diferencia entre revisiones de «Manual d'usuari de Gestió Monedes»

De Wiki Local
← Edición anteriorEdición siguiente →
Contenido eliminado Contenido añadido
VisualWikitexto
Ampliació del manual: arquitectura MVC, instal·lació, dependències i integracions CMS
Sincronitzat el manual d'usuari des de la font Markdown del projecte
Línea 2: Línea 2:
= Manual d'usuari de Gestió Monedes =
= Manual d'usuari de Gestió Monedes =


== 1. Presentació del projecte ==
'''Versió PDF del manual:''' [https://fmehmood.cat/gestio_monedes/docs/manual_usuari_gestio_monedes.pdf Manual d'usuari de Gestió Monedes (PDF)]


'''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.
'''Aplicació web:''' [https://fmehmood.cat/gestio_monedes/ Gestió de Monedes]


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


== 1. Presentació del projecte ==
== 2. Accés i enllaços principals ==


Per treballar amb l'aplicació i la seva documentació tens disponibles aquests recursos:
'''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.


* [https://fmehmood.cat/gestio_monedes/ Aplicació Gestió de Monedes]
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.
* [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]
Quan entres a l'aplicació trobaràs una navegació superior amb quatre accessos principals:


* '''Col·lecció'''
{| class="wikitable"
* '''Nova moneda'''
! Recurs
* '''Import/Export'''
! Enllaç
* '''Documentació'''
! Finalitat
== 3. Funcionament general ==
|-
| Aplicació web
| [https://fmehmood.cat/gestio_monedes/ Gestió de Monedes]
| Ús diari de l'aplicació
|-
| Manual PDF
| [https://fmehmood.cat/gestio_monedes/docs/manual_usuari_gestio_monedes.pdf Manual d'usuari en PDF]
| Consulta i impressió
|-
| Documentació tècnica
| [https://fmehmood.cat/gestio_monedes/documentacio.php Documentació del projecte]
| Instal·lació, arquitectura i dependències
|-
| Extensió MediaWiki
| [https://fmehmood.cat/mediawiki/index.php/Special:GestioMonedes Special:GestioMonedes]
| Catàleg integrat a la wiki
|}


L'ús habitual de l'aplicació segueix aquest flux:
== 2. Arquitectura i tecnologies ==


# Crear una moneda nova.
L'aplicació segueix el patró '''Model-Vista-Controlador (MVC)''' i s'executa sobre PHP pur sense frameworks:
# 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ó ===
{| class="wikitable"
! Capa
! Fitxers principals
! Responsabilitat
|-
| Presentació
| <code>views/header.php</code>, <code>llistat.php</code>, <code>formulari.php</code>, <code>detall.php</code>
| Genera el HTML que rep el navegador
|-
| Control
| <code>index.php</code>, <code>MonedaController.php</code>, <code>ImportExportController.php</code>
| Rep peticions, coordina model i vista
|-
| Model
| <code>models/Moneda.php</code>, <code>models/GestorImatge.php</code>
| Lògica de negoci, CRUD i gestió d'imatges
|-
| Base de dades
| MariaDB · taula <code>monedes</code>
| Emmagatzematge relacional via PDO
|}


La pantalla principal mostra les monedes en forma de targetes. Cada targeta presenta, de manera resumida:
=== Esquema de la base de dades ===


* nom de la moneda
{| class="wikitable"
* país o territori emissor
! Camp
* any d'emissió
! Tipus
* valor
! Nul·lable
* accessos ràpids a veure, editar o eliminar
! Descripció
Des d'aquesta pantalla també es mostren estadístiques generals i el panell de filtres.
|-
| <code>id</code>
| INT UNSIGNED PK AI
| No
| Identificador únic autoincremental
|-
| <code>nom</code>
| VARCHAR(150)
| No
| Nom oficial de la moneda
|-
| <code>pais</code>
| VARCHAR(100)
| No
| País o territori emissor
|-
| <code>valor</code>
| DECIMAL(15,4)
| No
| Valor facial o numismàtic
|-
| <code>any_emissio</code>
| SMALLINT
| No
| Any d'emissió (negatiu = a.C.)
|-
| <code>descripcio</code>
| TEXT
| Sí
| Descripció lliure
|-
| <code>imatge</code>
| VARCHAR(255)
| Sí
| Nom del fitxer d'imatge
|-
| <code>creat_el</code>
| DATETIME
| No
| Data de creació automàtica
|-
| <code>actualitzat</code>
| DATETIME
| No
| Data d'última modificació
|}


=== Tecnologies principals ===
=== 4.2 Nova moneda ===


La pantalla de creació permet introduir un nou registre. És la via principal per ampliar el catàleg.
* '''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 ==
=== 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.
La barra superior de l'aplicació inclou aquests accessos:


=== 4.4 Documentació ===
* '''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ó


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


# Crear una moneda nova.
== 5. Crear una moneda ==
# 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:
Per donar d'alta una moneda nova:


# Fes clic a '''Nova moneda'''.
# Fes clic a '''Nova moneda'''.
# Omple els camps obligatoris:
# Omple els camps obligatoris:
#* '''Nom de la moneda'''
#* '''Nom''' — nom oficial o popular (ex: «Euro», «Pesseta», «Denari»)
#* '''País''' — territori emissor (ex: «Espanya», «Unió Europea»)
#* '''País o territori emissor'''
#* '''Valor''' — valor facial en format numèric (ex: 1.00, 0.50)
#* '''Valor facial o numismàtic'''
#* '''Any d'emissió''' — per anys a.C., usa valors negatius (ex: -264)
#* '''Any d'emissió'''
# Omple la '''Descripció''' si vols afegir informació contextual.
# Omple el camp de '''Descripció''' si vols afegir context històric o tècnic.
# Puja una imatge si la vols associar al registre.
# Puja una imatge si la vols associar al registre.
# Prem '''Crear moneda'''.
# 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 ==
Quan el formulari és correcte, el sistema desa la moneda, torna al llistat i mostra un missatge de confirmació.


En fer clic sobre una targeta o sobre el botó de detall, s'obre la fitxa completa de la moneda. Aquesta vista mostra:
== 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
* imatge principal
Línea 173: Línea 83:
* nom complet
* nom complet
* descripció
* descripció
* metadades del registre (identificador, dates de creació i modificació)
* 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.


== 6. Editar i eliminar ==
== 7. Editar una moneda ==


Per modificar un registre existent:
=== 6.1 Editar ===


# Accedeix a la vista de detall o fes clic a '''Editar''' des del llistat.
Per editar una moneda:

# Entra a la fitxa o fes clic a '''Editar''' des del llistat.
# Modifica els camps necessaris.
# Modifica els camps necessaris.
# Si no afegeixes una nova imatge, la imatge actual es conserva.
# Si no puges una nova imatge, la imatge actual es conserva.
# Si vols esborrar la imatge actual, marca l'opció corresponent.
# Si cal, pots marcar l'opció per eliminar la imatge actual.
# Prem '''Desar canvis'''.
# Prem '''Desar canvis'''.
L'aplicació actualitza el registre i mostra un missatge d'èxit si l'operació s'ha completat correctament.


=== 6.2 Eliminar ===
== 8. Eliminar una moneda ==


Per eliminar una moneda:
Per eliminar una moneda:


# Fes clic a '''Eliminar''' (botó vermell).
# Fes clic a '''Eliminar'''.
# Revisa el nom al quadre de confirmació.
# Revisa el nom de la moneda al quadre de confirmació.
# Confirma l'acció.
# Fes clic a '''Eliminar''' per confirmar, o '''Cancel·lar''' per abortar.
Aquesta operació és permanent. Si la moneda tenia una imatge associada, el fitxer també s'elimina del servidor.


== 9. Cerca, filtres i ordenació ==
'''Atenció:''' l'eliminació és permanent i també suprimeix la imatge associada si existeix.


El panell de filtres permet localitzar registres concrets de manera ràpida. Els filtres disponibles són:
== 7. Cerca, filtres i ordenació ==


* '''Nom'''
El panell de filtres permet cercar per:
* '''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
{| class="wikitable"
* localitzar monedes d'un any determinat
! Filtre
* mostrar només monedes dins d'un rang de valor
! Descripció
També és possible ordenar els resultats per:
! Exemple
|-
| Nom
| Cerca per coincidència parcial
| <code>Euro</code> → troba «Euro», «Euronova»…
|-
| País
| Cerca per coincidència parcial
| <code>Esp</code> → troba «Espanya», «Esparta»…
|-
| Any d'emissió
| Any exacte
| <code>1999</code> o <code>-264</code>
|-
| Valor mínim
| Valor ≥ al valor indicat
| <code>0.50</code>
|-
| Valor màxim
| Valor ≤ al valor indicat
| <code>100</code>
|}


* nom
Els filtres es poden combinar lliurement. L'enllaç '''Mostra-les totes''' o el botó '''×''' permet tornar a l'estat general del catàleg.
* any
* valor
Si hi ha filtres actius, l'enllaç '''Mostra-les totes''' permet tornar al llistat complet.


== 8. Gestió d'imatges ==
== 10. Gestió d'imatges ==


La pujada d'imatges admet:
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
* JPG o JPEG
Línea 237: Línea 141:
* GIF
* GIF
* WebP
* WebP
Recomanacions:


* utilitza imatges clares i ben retallades
Característiques principals:
* evita fitxers massa grans (màxim 5 MB)

* comprova la previsualització abans de desar
* selecció manual de fitxer o arrossegar i deixar anar (drag & drop)
== 11. Importació i exportació ==
* 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ó ==


=== 11.1 Exportar el catàleg ===
Des de la pantalla '''Import/Export''' pots:


* exportar totes les monedes a XML
Des de la pantalla '''Import/Export''' pots descarregar totes les monedes en dos formats:
* exportar totes les monedes a CSV
* importar monedes des d'un XML vàlid
* importar monedes des d'un CSV amb capçalera correcta


* XML
=== 9.1 Exportar ===
* 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 ===
L'exportació genera un fitxer descarregable directament des del navegador amb el nom <code>monedes_YYYYMMDD_HHMMSS.xml</code> o <code>.csv</code>.


Per importar dades en XML:
=== 9.2 Importar XML ===


# Ves a '''Import/Export'''.
# Ves a '''Import/Export'''.
# Selecciona un fitxer XML amb l'estructura esperada.
# Selecciona un fitxer XML amb l'estructura correcta.
# Prem '''Importar des de XML'''.
# 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 ===
L'aplicació informa del nombre de monedes importades i dels errors detectats.


Per importar dades en CSV:
=== 9.3 Importar CSV ===


# Prepara el fitxer amb la capçalera: <code>nom;país;valor;any emissió;descripció</code>
# Prepara un fitxer amb la capçalera: <code>nom;país;valor;any emissió;descripció</code>
# Selecciona'l al formulari.
# Selecciona'l des del formulari.
# Prem '''Importar des de CSV'''.
# 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 ==
El sistema detecta automàticament el separador (punt i coma o coma) i valida la capçalera i el contingut mínim.


Per mantenir el catàleg en bon estat:
== 10. Bones pràctiques ==


* escriu noms coherents i homogenis
Per treballar millor amb l'aplicació:
* 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:
* 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ó


* Si una imatge no puja, comprova que el format sigui admès (JPG, PNG, GIF, WebP) i que no superi 5 MB.
== 11. Incidències habituals ==
* 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):
{| class="wikitable"
! 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
|}


* '''Controladors''' — <code>MonedaController.php</code> i <code>ImportExportController.php</code> gestionen les peticions i coordinen model i vista.
== 12. Instal·lació i configuració ==
* '''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:
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 [https://fmehmood.cat/gestio_monedes/documentacio.php#instalacio documentació tècnica del projecte].


* <code>id</code> — clau primària autoincremental
=== 12.1 Requisits del sistema ===
* <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:
{| class="wikitable"
! 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
|}


* '''Plugin WordPress''' — shortcode <code>[gestio_monedes_llistat]</code> que mostra el catàleg al frontend; panell d'administració per inserir i gestionar monedes.
=== 12.2 Passos d'instal·lació ===
* '''Extensió MediaWiki''' — pàgina especial <code>Special:GestioMonedes</code> que permet consultar, filtrar i inserir monedes directament des de la wiki.
* '''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.


== 15. Instal·lació i configuració ràpida ==
'''Pas 1 — Instal·lar dependències:'''

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


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


<pre>
<pre>
Línea 359: Línea 247:
</pre>
</pre>


'''Pas 3 — Configurar les credencials:'''
=== Pas 3 — Configurar les credencials ===


Opció recomanada: crear el fitxer <code>/etc/gestio_monedes/config.local.php</code> fora del directori web. Alternatives: variables d'entorn <code>GESTIO_MONEDES_DB_*</code> o editar directament <code>config.php</code>.
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ó:'''
=== 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.
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.


== 13. Dependències i resolució de problemes ==
== 16. Dependències i resolució de problemes ==


=== 13.1 Dependències ===
=== 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.
{| class="wikitable"
! Dependència
! Paquet
! Verificació
! Si falta
|-
| Servidor web
| <code>apache2</code> o <code>nginx</code>
| <code>systemctl status apache2</code>
| <code>sudo apt install apache2 -y</code>
|-
| Motor PHP
| <code>php</code> + <code>libapache2-mod-php</code>
| <code>php -v</code>
| <code>sudo apt install php libapache2-mod-php -y</code>
|-
| PDO MySQL
| <code>php-mysql</code>
| <code>php -m | grep pdo_mysql</code>
| <code>sudo apt install php-mysql -y</code>
|-
| Multibyte strings
| <code>php-mbstring</code>
| <code>php -m | grep mbstring</code>
| <code>sudo apt install php-mbstring -y</code>
|-
| XML
| <code>php-xml</code>
| <code>php -m | grep simplexml</code>
| <code>sudo apt install php-xml -y</code>
|-
| Fileinfo
| <code>php-fileinfo</code>
| <code>php -m | grep fileinfo</code>
| <code>sudo apt install php-fileinfo -y</code>
|-
| MariaDB
| <code>mariadb-server</code>
| <code>systemctl status mariadb</code>
| <code>sudo apt install mariadb-server -y</code>
|}


* <code>apache2</code> o <code>nginx</code> — servidor web
=== 13.2 Resolució de problemes habituals ===
* <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>
{| class="wikitable"
php -m | grep -E &quot;pdo_mysql|mbstring|simplexml|fileinfo&quot;
! Error
</pre>
! Causa probable
! Solució
|-
| Error de connexió a la BD
| Credencials incorrectes o MariaDB aturat
| Verifica <code>config.php</code> i executa <code>sudo systemctl status mariadb</code>
|-
| No s'ha pogut desar la imatge
| Permisos incorrectes a <code>uploads/</code>
| <code>chmod 755 uploads/ && chown www-data uploads/</code>
|-
| Pàgina en blanc
| Error de PHP ocult
| Activa <code>GESTIO_MONEDES_APP_DEBUG=1</code> o revisa <code>/var/log/apache2/error.log</code>
|-
| Error 413 (fitxer massa gran)
| Límit de pujada del servidor
| Augmenta <code>upload_max_filesize</code> a <code>php.ini</code> i reinicia Apache
|-
| Caràcters incorrectes
| Charset de la BD no és utf8mb4
| <code>ALTER DATABASE gestio_monedes CHARACTER SET utf8mb4</code>
|-
| Falta una extensió PHP
| No estan carregats pdo_mysql, mbstring, xml o fileinfo
| Instal·la el paquet corresponent amb <code>apt</code> i reinicia Apache
|}


=== Resolució de problemes habituals ===
== 14. Integracions CMS ==


Si hi ha un error de connexió a la base de dades, comprova les credencials i l'estat del servei:
El projecte inclou tres integracions opcionals per a sistemes de gestió de continguts. Totes llegeixen i escriuen des de MariaDB, CSV i XML.


<pre>
=== 14.1 Plugin WordPress ===
sudo systemctl status mariadb
</pre>


Si una imatge no es pot desar, revisa els permisos del directori d'uploads:
* '''Nom:''' Gestio Monedes WP
* '''Shortcode:''' <code>[gestio_monedes_llistat]</code>
* '''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


<pre>
=== 14.2 Extensió MediaWiki ===
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 ==
* '''Nom:''' GestioMonedes
* '''Pàgina especial:''' [https://fmehmood.cat/mediawiki/index.php/Special:GestioMonedes Special:GestioMonedes]
* '''Funcions:''' consulta, filtres, inserció de monedes i visualització d'imatges directament des de la wiki.
* '''Fonts de dades:''' MariaDB, CSV, XML


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.
=== 14.3 Component Joomla ===


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].
* '''Nom:''' com_gestiomonedes
* '''Frontend:''' [https://fmehmood.cat/joomla/index.php/gestio-monedes-joomla 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


Recursos finals:
== 15. Enllaços útils ==


* [https://fmehmood.cat/gestio_monedes/ Aplicació Gestió de Monedes]
* [https://fmehmood.cat/gestio_monedes/ Aplicació Gestió de Monedes]
* [https://fmehmood.cat/gestio_monedes/documentacio.php Documentació tècnica del projecte]
* [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.pdf Manual d'usuari en PDF]
* [https://fmehmood.cat/mediawiki/index.php/Special:GestioMonedes Extensió MediaWiki — Special:GestioMonedes]
* [https://fmehmood.cat/gestio_monedes/docs/manual_usuari_gestio_monedes.docx Manual d'usuari en DOCX]
* [https://fmehmood.cat/joomla/index.php/gestio-monedes-joomla Component Joomla — Frontend]

Revisión del 00:56 16 abr 2026

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:

  1. Crear una moneda nova.
  2. Completar-ne les dades principals.
  3. Afegir-hi una imatge si es vol documentar visualment.
  4. Consultar la fitxa de detall per validar la informació.
  5. Aplicar filtres i ordenacions quan el catàleg creix.
  6. 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:

  1. Fes clic a Nova moneda.
  2. Omple els camps obligatoris:
    • Nom de la moneda
    • País o territori emissor
    • Valor facial o numismàtic
    • Any d'emissió
  3. Omple el camp de Descripció si vols afegir context històric o tècnic.
  4. Puja una imatge si la vols associar al registre.
  5. 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:

  1. Accedeix a la vista de detall o fes clic a Editar des del llistat.
  2. Modifica els camps necessaris.
  3. Si no puges una nova imatge, la imatge actual es conserva.
  4. Si cal, pots marcar l'opció per eliminar la imatge actual.
  5. 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:

  1. Fes clic a Eliminar.
  2. Revisa el nom de la moneda al quadre de confirmació.
  3. 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:

  1. Ves a Import/Export.
  2. Selecciona un fitxer XML amb l'estructura correcta.
  3. 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:

  1. Prepara un fitxer amb la capçalera: nom;país;valor;any emissió;descripció
  2. Selecciona'l des del formulari.
  3. 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 Special:GestioMonedes que permet consultar, filtrar i inserir monedes directament des de la wiki.
  • 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.

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:

Obtenido de «https://fmehmood.cat/mediawiki/index.php?title=Manual_d%27usuari_de_Gestió_Monedes&oldid=29»