geoval

Bot de Mastodon que fa jugar als usuaris a endevinar comarques del País Valencià. Tot el codi i la comunicació amb els usuaris és en català.

Publica el mapa del País Valencià amb una comarca destacada i demana quina és. Cada encert encadena una comarca nova; el primer error acaba la partida i en desa la puntuació. Hi ha un rànquing dels millors jugadors i un panell personal amb les millors partides de cadascú.

Aquest projecte és un clon independent de geocat (el mateix joc amb les comarques catalanes): mateix codi, mateixa arquitectura, base de dades i compte de Mastodon totalment separats, només canvia el geojson de comarques.

Com jugar

Menciona el compte del bot amb una d'aquestes paraules:

Com funciona una partida:

• Cada encert suma un punt a la ratxa actual i, en el mateix toot, mostra en verd totes les comarques ja encertades (amb el nom escrit només a la darrera) i en vermell la comarca nova a endevinar.
• El primer error acaba la partida: es desa la ratxa final a la base de dades, es mostra el mapa amb l'historial verd i la comarca fallada en vermell, i es publica el rànquing actualitzat.
• Si s'encerten les 33 comarques sense cap error, la partida acaba en victòria.
• Demanar millors o panell en resposta a una partida oberta la dona per finalitzada (es desa la ratxa que portava) abans de respondre. Demanar ajuda, en canvi, no afecta cap partida activa.

Arquitectura

• Mastodon: client fet a mida amb aiohttp (app/libraries/mastodon_api.py) — no fa servir Mastodon.py. La seva API de streaming és síncrona i no es pot fer asíncrona sense un pont fil-bloquejant; com que aquí tot és aiohttp, el streaming (GET /api/v1/streaming/user, Server-Sent Events) és nadiament async.
• Base de dades: PostgreSQL via asyncpg, a través del pool propi de l'aplicació (app.services.postgres.dbpool) i les consultes a app/libraries/asyncdb.py (Database.crea_partida, Database.actualitza_partida, Database.obtenir_rankings, Database.obtenir_millors_partides). Totalment separada de la de geocat — cal el seu propi .env/DSN.
• Mapes: matplotlib, sense dependència de geopandas/GDAL (app/geo/mapa_comarques.py).
• Tot el bot és asyncio de cap a cap: no hi ha fils ni bridges bloquejants.

Estructura de fitxers

geoval.py # bot principal (streaming, lògica del joc)
app/
 geo/
 mapa_comarques.py # generació de tots els mapes
 comarques.geojson # 33 comarques del País Valencià
 libraries/
 mastodon_api.py # client Mastodon fet a mida (aiohttp)
 asyncdb.py # consultes SQL del joc (Database)
 setup.py # configuració de l'aplicació (Setup) — propi del projecte
 services/
 postgres.py # pool de connexió Postgres (dbpool) — propi del projecte
 db/
 schema.py # creació de taules (create_dbschema) — propi del projecte
 imatges/ # cache de mapes generats (es crea sola en executar-se)

Origen del geojson

Les 33 comarques provenen de fusionar (dissoldre) els municipis de la Comunitat Valenciana pel seu codi INE, agrupats segons la correspondència oficial municipi→comarca del Portal Estadístic de la Generalitat Valenciana (basada en l'article 228 de la Llei 8/2022). Les geometries dels municipis vénen del paquet npm es-atlas (topojson pre-generat a partir de l'IGN).

A diferència de les comarques catalanes, les comarques valencianes no són una divisió administrativa oficial amb límits legalment fixats: no hi ha cap llei que en reconegui l'existència administrativa ni en fixi els noms de manera oficial. La llista i agrupació que fem servir és la referència cartogràfica que utilitza de facto la Generalitat.

El còmput de 33 (i no 34, com diuen algunes fonts més antigues) es deu a la desaparició de l'Horta Oest com a comarca pròpia (fusionada amb l'Horta Sud) en el mapa comarcal vigent des de l'1 de gener de 2023; el seu codi (14) queda buit a la taula oficial.

Validat comparant la superfície total resultant (23.233 km2) amb la xifra oficial de la Comunitat Valenciana (23.255 km2, ~0,1% de diferència) i la capsa delimitadora amb l'extensió geogràfica real.

Requisits

pip install aiohttp asyncpg matplotlib loguru python-dotenv

Base de dades

create_dbschema() crea, entre altres, la taula partides — una fila per cada partida jugada (no un total acumulat per usuari):

CREATETABLEIFNOTEXISTSpartides(idSERIALPRIMARYKEY,acctTEXTNOTNULL,encertsINTEGERNOTNULLDEFAULT0,creat_elTIMESTAMPTZNOTNULLDEFAULTnow());CREATEINDEXidx_partides_acctONpartides(acct);

El rànquing (millors) agrupa per acct i mostra la puntuació màxima de cadascú; el panell (panell) mostra les partides d'un usuari concret ordenades de major a menor puntuació.

Desat en temps real: en començar una partida es crea de seguida la fila corresponent a partides amb encerts=0, i es va actualitzant (no re-inserint) a cada encert. Això vol dir que, si el bot es reinicia enmig d'una partida, la ratxa que portava fins al darrer encert ja està desada. Com a efecte secundari, mentre algú està jugant, la seva partida en curs ja apareix a millors/panell amb el recompte parcial, no només un cop acabada.

Configuració

Al executar geoval.py per primer cop, es demanen els paràmetres de configuració (compte de Mastodon, connexió a Postgres) i es crea la base de dades.

Rendiment i cache

• Els mapes de pregunta i d'error es guarden a app/imatges/ la primera vegada que surt cada comarca, i es reutilitzen les següents.
• Els mapes que depenen de l'estat d'una partida concreta (el de progrés durant la partida, el de resultat final, i els de millors/panell) no es guarden a cache, perquè el seu contingut canvia cada vegada.
• Les geometries dels municipis d'es-atlas ja venen simplificades de fàbrica, així que cada mapa nou es genera en bé menys d'un segon sense necessitat de neteja addicional (a diferència del geojson de geocat, que sí que va requerir corregir una triplicació de geometria).
• Si mai canvieu com es dibuixen els mapes (colors, peu de pàgina, etc.), cal buidar app/imatges/*.png perquè els canvis es notin — la cache no es regenera sola.

Límits coneguts

• L'estat de les partides obertes (partides_actives, ratxes, demanades, encertades) viu només en memòria del procés; si el bot es reinicia enmig d'una partida, aquella partida concreta es perd (el rànquing i les partides ja completades, no: això viu a la base de dades).
• Si l'API de Mastodon respon amb un límit de peticions (429), el bot avisa l'usuari en català amb l'hora exacta a partir de la qual es podrà continuar, calculada a partir de la capçalera X-RateLimit-Reset que Mastodon envia de veritat (Mastodon no envia Retry-After; per defecte, POST /api/v1/media permet només 30 pujades cada 30 minuts, molt més estricte que el límit general de 300 peticions/5 min). Cap canvi d'estat (ratxa, comarques encertades, pregunta oberta) es dona per fet fins que la publicació a Mastodon no ha tingut èxit real, així que si es peta a mig torn, la pregunta original (i el mateix toot d'avís, registrat com a àlies) es manté oberta i n'hi ha prou de tornar-la a respondre un cop passi l'estona.
• Cada resposta a un encert o error inclou, al final del toot, l'últim estat conegut dels dos límits (Límit API: X/300 ... i Límit pujada d'imatges: X/30 ..., amb ⚠️ quan algun arriba a 0), llegit de les capçaleres X-RateLimit-* de la crida més recent.
• Es dona per fet un jugador amb una partida oberta alhora; dues partides simultànies del mateix usuari no estan cobertes.
• La validació de respostes normalitza accents, majúscules, puntuació final, variants d'apòstrof, i un article inicial opcional (el/la/els/les/l'), i compara per igualtat exacta (no per subcadena) per evitar falsos positius entre noms de comarca que es contenen l'un a l'altre.