El comandament de control de l'e-commerce de Castañer
El Dashboard Castañer és el lloc on totes les dades de la botiga online —vendes, comandes, stocks, tràfic, devolucions, fulfillment— conflueixen en una sola veritat, viva les 24 hores del dia.
No és un informe que es mira un cop al mes. És el pols diari del negoci: el primer que s'obre al matí i el que respon, en segons, la pregunta que importa en cada moment. Una sola font de veritat, sempre actualitzada, en la qual es pot confiar cegament. Aquesta confiança és tot el projecte; tota la resta —l'arquitectura, els automatismes, els agents— existeix per protegir-la.
El projecte en 30 segons
Què és. Un dashboard intern 24/7 de KPIs operatius per a castaner.com, la botiga online de Castañer (marca catalana de calçat, fundada el 1927).
Per a qui. L'equip d'e-commerce de Castañer. Va néixer com a eina d'un sol usuari i avui és multi-usuari amb rols: gestió, agència, direcció, operacions, marketing i l'equip de botiga UK, cadascun amb la seva vista.
Quin problema resol. Castañer ven per molts canals i mercats; les dades viuen escampades entre Shopify, Klaviyo, GA4 i REVENI, sovint amb criteris que no quadren entre ells. El dashboard les unifica, les fa consistents i les serveix consolidades, sense que ningú hagi d'exportar Excels ni recalcular res.
Fets clau
| Fet | Detall |
|---|---|
| Mercats | ES · FR · IT · UK · US · GR · EU_REST (la resta de la UE/món) |
| Canals | Web (Shopify) · Marketplaces · Botigues físiques (POS, 10+ punts) |
| 2 botigues Shopify | Botiga principal (EUR) + botiga internacional (UK, GBP) |
| Integracions | Shopify · Klaviyo · GA4 · REVENI · GLS/carriers |
| Idiomes | Trilingüe complet CA / EN / ES (~1.295 claus per idioma) |
| Automatismes | ~20 processos automàtics: snapshots, sync, còpies de seguretat, 2 emails automàtics, auditoria diària |
| Agents IA | 4 subagents de Claude Code: redactor de mails, 2 traductors, auditor de dades |
Principis i regles d'or
Principis no negociables. Cadascun ha nascut d'un error real; seguir-los és el que manté el dashboard fiable i mantenible.
Les dades no s'inventen mai
Tot el que s'afirma surt d'una xifra real. Quan una vista, un email o el xat necessiten un número, llegeixen el camp ja publicat al snapshot de dades; no tornen a recalcular-lo pel seu compte.
Tot text passa per i18n (CA/EN/ES)
Cap text es codifica directament ("hardcoded"). Tot va a través d'un diccionari únic amb una clau per a cada frase i la seva traducció als tres idiomes (català, anglès i castellà).
Els informes són autocontinguts
Cada informe monogràfic porta les seves dades incrustades dins el propi document. Es desa sempre la versió AMB dades, mai una plantilla buida pendent d'omplir.
Un únic procés de desplegament controlat
Els canvis arriben a producció sempre pel mateix camí reproduïble i versionat. Mai es modifiquen fitxers directament al servidor saltant-se aquest procés.
Col·lisions de funcions JS
El codi del frontend viu repartit en diversos mòduls que comparteixen un únic espai de noms global. Si dos mòduls defineixen una funció amb el mateix nom, una sobreescriu l'altra silenciosament.
Consistència visual via CSS global
Tots els blocs amb el patró títol → descripció → filtres tenen el mateix espaiat vertical, governat per shared.css. Amplada uniforme (width:90%; max-width:1900px).
margin-top inline als banners o filtres. Un bloc nou amb aquesta estructura no cal estilar-lo: el CSS global ja el fa quadrar.Colors només via variables CSS
Hi ha dark mode (per defecte) i light mode (monocrom estricte: negre/blanc/grisos, només verd i vermell per a positius/negatius). Mai hardcodejar colors: sempre var(--xxx).
var() al canvas → dins configs de gràfics s'usen grisos neutres literals que funcionen als dos temes.Les API keys read-only no es roten
Per a keys de tercers (Klaviyo, Shopify) amb scope només lectura, si s'exposen accidentalment no es roten: el risc és limitat (es poden llegir dades, no modificar res).
UK és un món a part
UK té la seva pròpia botiga, magatzem, Klaviyo i moneda (GBP→EUR). Es veu a Realtime, Negoci, Producte i "Operacions UK".
El sistema d'un cop d'ull
El dashboard és un pipeline de 4 capes. La clau de tot és la capa de snapshots: cap pantalla ni email toca mai la base de dades en viu.
Les 4 capes · flux de dades
El patró snapshot · per què existeix
El frontend, l'email diari i el xat Manuel no consulten mai la base de dades en viu: llegeixen els mateixos snapshots de dades que es regeneren periòdicament en segon pla.
- Una sola font de veritat. És impossible que el dashboard, l'email i el Manuel mostrin xifres diferents: tots llegeixen el mateix camp del mateix snapshot.
- Velocitat. Llegir un snapshot ja preparat és gairebé instantani; tornar a calcular-ho tot contra la base de dades seria molt més lent.
- No carrega la base de dades, que ja està ocupada capturant dades noves contínuament.
- Consistència temporal. Tots veuen la mateixa foto del mateix instant.
Les pàgines, en clau de negoci
Cada pestanya respon una pregunta de negoci. "Qui la veu" indica els rols amb accés (l'admin ho veu tot).
Els ritmes automàtics
Tot funciona sol gràcies a una vintena de processos automàtics. Aquesta és la jornada d'un dia normal (hora local).
El calendari de comunicació
Els emails d'insights tenen en compte el calendari de comunicació (campanyes, Early Access i Rebaixes per mercat). Serveix per contextualitzar les comparatives vs l'any passat: sovint una caiguda vs LY no és una alarma sinó un desplaçament de calendari.
Manteniment manual: quan arriba un calendari de comunicació nou, s'afegeix l'entrada del mes corresponent. Detall de marca: Castañer NO fa Black Friday (posicionament "NO Black Friday").
Decisions clau i el perquè
Registre de decisions d'arquitectura. Format: Decisió → Context → Per què.
Els agents de Claude Code
Quatre subagents especialitzats de Claude Code, cadascun amb una funció concreta.
Glossari i convencions
Canals
| Terme | Definició |
|---|---|
| WEB | Vendes de la botiga online (web + app). Tots els mercats, inclòs UK. |
| MARKETPLACES | Vendes a marketplaces. Imports petits; el senyal real és que la majoria no arrenquen (només El Corte Inglés factura de manera consistent). |
| BOTIGUES / POS | Vendes de botiga física, per botiga. Fora dels KPIs online. |
Mercats
Els mercats principals i els del seguiment mensual inclouen UK.
Mètriques
| Terme | Significat |
|---|---|
| Vendes netes (pre-IVA) | Suma de les línies de comanda (preu menys descomptes), sense IVA ni enviament. Mètrica de referència. |
| Brut vs Net | El KPI gran "Vendes avui" + cards de mercat = BRUT (no resta devolucions). Les taules de detall + Objectius/Mensual = NET (sí resten). L'email diari usa BRUT. |
| LY (Last Year) | Mateix dia de l'any anterior, llegit del snapshot (no de la base de dades en viu). |
| MTD | Month to date — mes en curs acumulat. |
| FY (Fiscal Year) | Any fiscal de Castañer: agost → juliol. |
| Same-store | Creixement de botigues obertes els 2 anys (exclou les noves i les tancades). El % brut de botigues l'inflen les noves. |
| Visitants vs Sessions | Visitants = usuaris únics (lleugerament per sota de les sessions). Sessions = comptabilitzades amb el mercat correcte. Per UK, els visitants es deriven de les sessions. |
| Conversió (realtime) | comandes ÷ visitants × 100 (mai la conversió que reporta directament la font externa). |
Altres termes
- Funnel: Sessions → Cistella → Checkout → Compra (font Shopify; la "fitxa de producte" prové de GA4).
- BIS / Back-in-Stock: sol·licituds de "avisa'm quan torni" (Klaviyo). "Diners perduts" = sol·licituds no convertides × preu mig (sense IVA).
- RMA: procés de devolució (estat, mètode, transportista, dates). La talla és el principal motiu de devolució.
- PUDO / pickup point: paquet deixat en un punt de recollida; detectat a posteriori (estat virtual "Pendent recollida").
- PUDO ≠ checkout: Castañer no ofereix pickup points de tercers al checkout.