Exemple de Memòria de Projecte

Què és aquest document

Aquesta pàgina recull un projecte fictici totalment desenvolupat, organitzat segons les 5 fases del M0379, per il·lustrar el nivell de detall, d'estructura i de justificació tècnica que s'espera en cadascun dels entregables del mòdul (vegeu Fase 1 a Fase 5).

No és un enunciat ni un model a copiar. El projecte triat aquí — un sistema de bitlletatge electrònic per a l'autobús urbà de Blanes — és només un exemple que compleix els criteris de selecció de projecte: té un caire social (millora un servei públic), està arrelat al territori (línia L2 de Blanes) i té relació amb el turisme de la Costa Brava.

Canvi respecte a promocions anteriors

Fins ara, el mòdul es treballava amb una sèrie de mini-projectes tancats, amb tecnologies concretes que l'alumnat no havia vist durant el curs, assignats pel professorat. A partir d'ara, és l'alumnat qui ha de pensar la seva pròpia idea, aplicant els criteris socials i de territori de la Fase 1, i triar les tecnologies que consideri més adients per resoldre-la — les que apareixen en aquest exemple, o d'altres més modernes — justificant sempre la tria a la Fase 2. Les tecnologies i versions concretes citades en aquest document eren les estables en el moment de redactar-lo; cal comprovar-ne sempre la vigència abans d'utilitzar-les en un projecte real.

Fase 1 — Document d'identificació de necessitats

Context i justificació

Blanes disposa d'una línia d'autobús urbà, la L2 Urbà Blanes, de traçat circular amb una quarantena de parades, operada per Moventis Costa Brava, amb origen i final a l'Estació d'Autobusos de Blanes. Es tracta d'un cas d'ús real i acotat (una sola línia, un nombre de parades conegut) sobre el qual es pot dissenyar un sistema complet sense haver de gestionar la complexitat d'una xarxa multimodal com la de Barcelona.

Necessitat identificada: l'operador no disposa d'un sistema de bitlletatge electrònic propi que permeti conèixer l'ús real del servei (nombre de viatges, franges horàries, fidelització) ni oferir tarifes bonificades gestionades digitalment.

Recomanació pràctica: abans de començar un projecte d'aquest tipus amb una entitat real, cal sol·licitar una reunió breu (real o simulada) amb la part interessada (en aquest cas, l'àrea de Mobilitat de l'Ajuntament de Blanes) per confirmar l'abast, el pressupost orientatiu i si ja existeix algun sistema amb el qual calgui integrar-se. Això converteix el projecte en un exercici d'enginyeria de requisits real, no només d'implementació tècnica.

Objectius didàctics

Dissenyar, construir, desplegar i documentar un sistema distribuït d'extrem a extrem, que integri electrònica/maquinari IoT, contenidors, orquestració i serveis de backend.
Construir físicament almenys un dispositiu real (no només simular-lo per programari).
Treballar en equip seguint una metodologia de gestió de projectes (Scrum o Kanban).
Aplicar criteris de seguretat, alta disponibilitat i monitorització propis del cicle ASIX.

Relació amb els mòduls del cicle

Mòdul professional	Contingut que aporta al projecte
Administració de sistemes operatius	Gestió de servidors Linux, usuaris, serveis systemd a les Raspberry Pi
Serveis de xarxa	DNS, DHCP, servidor web, proxy invers, VPN entre seus
Seguretat i alta disponibilitat	TLS, gestió de secrets, balanceig de càrrega, rèpliques, còpies de seguretat
Implantació de sistemes operatius	Provisionament automatitzat d'imatges (Ansible, cloud-init)

Fase 2 — Document de disseny

Visió general del sistema

El sistema té cinc grans blocs:

Màquina d'expedició i recàrrega de targetes (back-office físic): dispositiu fix on es donen d'alta targetes noves i es recarrega saldo.
Màquina validadora a bord de l'autobús (edge/IoT): llegeix la targeta quan el viatger hi puja i registra el viatge.
Transport de dades en temps real: comunicació entre dispositius i el backend mitjançant MQTT.
Backend, persistència i explotació: API, base de dades i lògica de negoci, en contenidors orquestrats.
Dashboard de seguiment: visualització de l'ús del servei per a l'ajuntament.

flowchart TB
    U[Viatger amb targeta NFC] -->|alta / recarrega| MX[Maquina d'expedicio\nRaspberry Pi + pantalla + lector NFC]
    U -->|validacio en pujar| MV[Maquina validadora al bus\nRaspberry Pi + Arduino + NFC]
    MX -->|MQTT sobre TLS| BR[Broker MQTT\nEclipse Mosquitto a k3s]
    MV -->|MQTT sobre TLS| BR
    BR --> ING[Servei d'ingesta\nsubscriptor MQTT]
    ING --> BD[(Base de dades\nPostgreSQL)]
    BD --> API[API REST]
    API --> DASH[Dashboard de seguiment\nGrafana]
    API --> MX

Tot el bloc de backend (broker, ingesta, base de dades, API, dashboard) es desplega com a contenidors orquestrats amb Kubernetes (k3s). Els dos dispositius físics són clients d'aquest sistema central i s'hi comuniquen mitjançant MQTT.

Maquinari (BOM orientatiu)

Component	Model recomanat	Funció
Ordinador de control	Raspberry Pi 5 (4 GB)	Executa el sistema operatiu i el client que parla amb el backend
Lector/escriptor NFC	Mòdul PN532 (13,56 MHz, SPI/I2C)	Llegeix l'UID de la targeta
Pantalla (màquina d'expedició)	Pantalla tàctil oficial de 7"	Interfície d'usuari
Microcontrolador de feedback (validadora)	Arduino Uno/Nano	Controla el LED RGB i el brunzidor de feedback immediat
Connectivitat (validadora)	Mòdul 4G LTE amb GNSS integrat	Connexió mentre el bus circula, amb posicionament
Alimentació (validadora)	Convertidor DC-DC 12-24V a 5V/5A	Alimentació estable des de la bateria del vehicle

Els preus i la disponibilitat del maquinari IoT (Raspberry Pi, mòduls electrònics) evolucionen ràpidament; cal comprovar-los sempre en el moment de comprar-los, i pressupostar amb el model més econòmic que compleixi els requisits.

Model de dades (esquema relacional)

CREATE TABLE targetes (
  uid              VARCHAR(32) PRIMARY KEY,
  tipus            VARCHAR(20) NOT NULL,  -- 'ocasional','abonament','bonificada','control'
  saldo            NUMERIC(8,2) DEFAULT 0,
  viatges_restants INTEGER DEFAULT 0,
  data_alta        TIMESTAMP NOT NULL DEFAULT now(),
  actiu            BOOLEAN DEFAULT TRUE
);

CREATE TABLE validacions (
  id          BIGSERIAL PRIMARY KEY,
  uid_targeta VARCHAR(32) REFERENCES targetes(uid),
  bus_id      VARCHAR(20) NOT NULL,
  linia       VARCHAR(10) NOT NULL,
  ts          TIMESTAMP NOT NULL,
  resultat    VARCHAR(20) NOT NULL,
  latitud     NUMERIC(9,6),
  longitud    NUMERIC(9,6)
);

Missatgeria: esquema de topics MQTT

Topic	Ús
`blanes/l2/{bus_id}/validacions`	Cada validació feta a bord d'un bus concret
`blanes/l2/{bus_id}/estat`	Missatges periòdics d'estat del dispositiu (bateria, connexió, GPS)
`blanes/expedicio/{maquina_id}/operacions`	Altes i recàrregues fetes a cada màquina d'expedició
`blanes/config/{dispositiu_id}`	Topic en sentit invers: el backend envia configuració o ordres

MQTT s'ha triat per damunt d'HTTP perquè manté (quan pot) una connexió persistent i lleugera amb el broker, i inclou mecanismes de QoS i sessió persistent que faciliten no perdre missatges durant talls breus de connexió — exactament la situació d'un autobús en moviment.

Seguretat (checklist transversal)

Capa	Mesures a aplicar
Dispositius (expedició i validadora)	TLS en totes les comunicacions; accés SSH només amb clau pública
Broker MQTT	Autenticació per usuari/dispositiu; llistes de control d'accés (ACL) per topic; certificat TLS vàlid
Backend / API	Autenticació per token (JWT); validació estricta de totes les dades d'entrada
Base de dades	Usuari amb permisos mínims (mai l'usuari administrador per a l'aplicació); còpies de seguretat xifrades i periòdiques
Dades personals	Ús exclusiu de dades fictícies generades pels alumnes; cap vinculació real de targetes a noms o DNI reals

Aquesta taula es pot fer servir directament com a llista de verificació abans de la presentació final del projecte, i és el tipus de contingut que es demana també al pla de seguiment i control de la Fase 4.

Fase 3 — Pla d'execució

Repartiment en equips de treball

Equip	Responsabilitat
A — Màquina d'expedició	Munta el maquinari, en programa la interfície gràfica i la lògica d'alta/recàrrega, documenta el manual d'ús
B — Màquina validadora	Munta el maquinari, programa la màquina d'estats de validació i la cua local, prova la connectivitat intermitent
C — Missatgeria i orquestració	Desplega el broker MQTT, primer amb Docker i després amb k3s; en configura la seguretat
D — Backend i base de dades	Dissenya el model de dades, implementa el servei d'ingesta i l'API REST
E — Explotació i dashboard	Construeix el dashboard, valida la checklist de seguretat, prepara la documentació i presentació final

Cronograma orientatiu (un trimestre, 12 setmanes)

Setmanes	Fita
1-2	Anàlisi de requisits, disseny de l'arquitectura, repartiment d'equips
3-4	Primers prototips aïllats de cada component, incloent el primer muntatge físic
5-6	Primera integració física: la validadora llegeix una targeta real i dona feedback; l'expedició crea una targeta nova
7-8	Connexió de totes dues màquines amb el broker MQTT; primer missatge real de cap a cap fins a la base de dades
9-10	Dashboard funcional; seguretat aplicada; proves de talls de connexió
11	Proves d'acceptació conjuntes, correcció d'errors, documentació final
12	Presentació final

Fase 4 — Pla de seguiment i control

Criteris d'avaluació orientatius (KPIs del projecte)

Criteri	Pes orientatiu
Funcionament físic real de la màquina d'expedició	15%
Funcionament físic real de la màquina validadora (incloent la cua local en cas de tall de connexió)	20%
Funcionament end-to-end del sistema complet	15%
Qualitat del desplegament amb contenidors/k3s	15%
Seguretat aplicada (TLS, gestió de secrets, control d'accés)	15%
Documentació tècnica (arquitectura, manual d'instal·lació i d'usuari)	10%
Treball en equip i seguiment de la metodologia	5%
Presentació final	5%

Aquests criteris es concreten per a cada projecte real dins la rúbrica de cada fase i la rúbrica global del mòdul.

Riscos i recomanacions

Maquinari i pressupost: el mercat de components IoT (Raspberry Pi, mòduls electrònics) pot patir tensions de preu i subministrament; cal pressupostar amb marge i confirmar disponibilitat amb antelació. Si no hi ha prou unitats físiques per a tots els equips, els blocs que no en depenguin directament poden treballar contra un simulador en programari sense perdre valor didàctic.
Abast i expectatives: cal deixar clar que es tracta d'una prova de concepte educativa, no d'un sistema que substituirà un servei real sense un procés molt més llarg de validació amb l'operador.
Protecció de dades: si en algun moment es vincula un dispositiu a dades reals d'una persona, cal tractar-ho amb cura (RGPD); es recomana treballar només amb dades fictícies generades pel mateix alumnat.

Fase 5 — Informe d'execució

Abast de la implantació real

Donat el temps disponible, no cal implementar el sistema complet: cada equip ha d'implantar i verificar una part real i funcional del seu bloc (per exemple, l'Equip B pot limitar-se a demostrar la lectura NFC amb feedback lluminós i l'enviament d'un missatge MQTT real, sense necessitat del mòdul 4G complet).

Verificació i proves

Prova de lectura NFC en menys d'un segon, amb feedback visual/sonor immediat.
Prova de funcionament sense connexió: la cua local (per exemple, amb SQLite) ha de reenviar les dades pendents quan es recupera la connexió.
Prova end-to-end: una validació feta al dispositiu físic ha d'aparèixer al dashboard en temps (quasi) real.

Documentació a lliurar

Documentació d'administrador: com desplegar de nou el sistema, com fer i restaurar una còpia de seguretat, com consultar registres.
Guia d'usuari: dirigida al personal de l'oficina d'expedició, sense llenguatge tècnic.

Per anar més enllà (ampliació opcional)

Els equips que acabin amb marge poden treballar un exercici de prospectiva: com caldria redissenyar el sistema si, en lloc d'una línia i un o dos vehicles, calgués donar servei a tota una xarxa de transport de ciutat (desenes de línies i centenars de vehicles). No es tracta de construir-ho físicament, sinó de raonar i justificar els canvis d'arquitectura necessaris:

Component	A escala petita (aquest exemple)	A escala de ciutat
Broker de missatgeria	Un sol node (Mosquitto)	Broker amb clustering natiu (per exemple EMQX), en diversos nodes
Orquestració	k3s en una sola Raspberry Pi	Clúster Kubernetes multi-node amb autoescalat
Base de dades	PostgreSQL en una sola instància	PostgreSQL distribuït (per exemple amb l'extensió Citus) i rèpliques de lectura
Gestió de dispositius	Configuració manual	Aprovisionament automàtic i infraestructura de certificats (PKI) pròpia

Aquest exercici connecta directament amb els continguts de Seguretat i Alta Disponibilitat i és una bona manera de demostrar que un disseny "funciona en una maqueta" és una cosa diferent de "funcionaria en producció a gran escala".