DEV Community: Enrique Lazo Bello

Matemáticas con Dados: cómo construí un juego para que mi niña aprenda a contar con dados y tapitas reales

Enrique Lazo Bello — Fri, 23 Oct 2026 12:31:40 +0000

Un juego web hecho con HTML, CSS y JavaScript, sin framework, pensado para los peques. En este tutorial lo construimos desde cero: la idea, la investigación detrás de cada decisión y el código, paso a paso.

Para quién es: programadores que están empezando y personas entusiastas de la programación con conocimiento básico de HTML y JavaScript. Si sabes qué es una función y un array, puedes seguirlo.

Qué vas a construir: una versión mínima pero completa del juego, con Contar y Sumar, voz en español, ayuda cuando el niño se equivoca y una pantalla de cierre.

Código completo: https://github.com/the-bunker-code/matematicas-con-dados

Vamos a jugar: https://the-bunker-code.github.io/matematicas-con-dados/

Índice

La idea
La investigación: qué necesita un niño para aprender a contar
Decisiones técnicas: por qué sin framework
Paso 0: carpetas y servidor local
Paso 1: el HTML de las tres pantallas
Paso 2: la configuración
Paso 3: las reglas del juego (lógica pura)
Paso 4: probar las reglas antes de tener pantalla
Paso 5: el estado y las acciones
Paso 6: dibujar la pantalla
Paso 7: conectar los clics
Paso 8: voz y sonidos sin archivos de audio
Paso 9: los estilos
Del prototipo al proyecto real
Publicarlo
Lo que aprendí
Glosario
Anexo: el CSS completo de la versión mínima

1. La idea

Todo empezó sobre una mesita para niños, con una caja blanca llena de tapitas de plástico y un teléfono apoyado al lado.

A sus casi 4 años, mi niña aprende con las manos: necesita palpar, mover, apilar y ordenar antes de que un símbolo abstracto tenga sentido. Las apps tradicionales de matemáticas hacían justo lo contrario: llenaban la pantalla de luces parpadeantes, ruidos estridentes al cometer un error y recompensas vacías que la absorbían en el cristal y la desconectaban de su entorno.

Decidí plantear la interacción al revés: la app no reemplaza a las tapitas, las acompaña.

El teléfono, apoyado en la mesa, propone el reto en silencio o con una voz tranquila. Ella mira los dos dados en la pantalla: un 4 y un 3. Mete la mano en la caja, saca cuatro tapitas rojas y tres verdes, las ordena en filas y las cuenta en voz alta, tocando cada una con el dedo. Solo después de haber sentido la cantidad en sus manos vuelve a la pantalla y marca el resultado. A su lado siempre hay un adulto que no la interrumpe; solo la acompaña a su ritmo.

Estas reglas nacieron de verla jugar en esa mesa, y el código las respeta al pie de la letra:

Sin castigos ni ruidos fuertes. Nunca hay un "no" cortante ni un sonido de error. Si se equivoca, la app cuenta junto a ella y le muestra el camino.
La pantalla es un tablero, no una distracción. El teléfono queda quieto sobre la mesa. Los gráficos son simples y estables, para que la atención esté en las tapitas.
Grupos que se pueden tocar. Cada dado tiene su color y cada color es un grupo de tapitas. Así, sumar es juntar dos grupos reales.
Sesiones cortas y predecibles. Ella elige 3, 5 u 8 rondas. Antes del final suena un aviso, para que el cierre no la tome por sorpresa.
El final se siente como final. El botón para volver a jugar tarda 4 segundos en aparecer. Esa pausa evita que siga tocando sin parar.
Respeta lo que hay en la mesa. El juego nunca pide más tapitas de las que caben en su caja.
Calma visual. Hay muy pocas animaciones (ninguna si el teléfono tiene activada la reducción de movimiento), cada operación tiene siempre el mismo color y las frases son cortas, en español neutro.

2. La investigación: qué necesita un niño para aprender a contar

Antes de escribir código, conviene entender qué estamos enseñando. No hace falta ser especialista; alcanza con unos pocos conceptos que la educación matemática temprana usa desde hace décadas.

Nota: esta sección resume conceptos generales para explicar las decisiones de diseño. No es una guía clínica. Si trabajas con un niño con necesidades específicas, la palabra de su terapeuta y de su familia está por encima de cualquier app.

Contar no es recitar

Un niño puede decir "uno, dos, tres, cuatro" de memoria y no saber contar. Los psicólogos Rochel Gelman y C. R. Gallistel describieron en 1978 los principios que hay detrás de contar de verdad. Tres de ellos guían este juego:

Principio	Qué significa	Cómo lo aplica el juego
Correspondencia uno a uno	Cada objeto se cuenta una sola vez.	Cada tapita tocada muestra su número y, si se toca de nuevo, repite el mismo número.
Orden estable	Los números se dicen siempre en el mismo orden.	La voz dice "uno, dos, tres…" con cada toque.
Cardinalidad	El último número dicho es cuántos hay.	Al terminar la ayuda, la voz dice "Hay cuatro." y la respuesta correcta empieza a latir.

De lo concreto a lo abstracto

Un enfoque muy usado para enseñar matemáticas es concreto → pictórico → abstracto: primero objetos reales, después dibujos de esos objetos, y recién al final los símbolos (2 + 1 = 3). El juego tiene los tres en la misma pantalla:

Concreto: las tapitas reales en la mesa (modo "Tapitas reales").
Pictórico: las tapitas dibujadas y los puntos de los dados.
Abstracto: la frase "2 más 1 es igual a…" y los números de las respuestas.

Ver cantidades sin contar

Los adultos vemos tres puntos y sabemos que son tres sin contarlos. Esa capacidad se llama subitización y funciona con cantidades chicas. Por eso:

Los dados se dibujan con sus puntos de siempre, no con números.
Debajo de cada respuesta hay tantos puntitos como vale.
Las tapitas se ordenan en filas de 5, como un cartón de huevos: es más fácil ver "una fila llena y dos más" que un montón desordenado.

Previsibilidad y transiciones

Para muchos niños, y en especial para muchos niños autistas, lo inesperado es difícil: el final abrupto de una actividad, un sonido fuerte, un cambio de colores. De ahí salen varias reglas:

Ancla visual: cada operación tiene su color fijo (Contar azul, Sumar naranja…) y la mascota es siempre la misma tapita roja.
Anticipar el final: dos rondas antes de terminar la voz dice "Dos más y guardamos", y en la última, "La última y guardamos".
Cierre: la pantalla final dice "Ahora guardamos las tapitas juntos" y los botones aparecen después de 4 segundos. Así el cierre no se convierte en "una más, una más".

Atención y error

Con TDAH, cada estímulo compite por la atención. Por eso el juego tiene pocas animaciones, sin premios que distraigan, y un error no se castiga: suena un tono grave y suave, la app cuenta en voz alta con el niño y la respuesta correcta late. El error se convierte en una oportunidad de contar juntos.

El adulto es parte del juego

El juego está pensado para jugar con un adulto al lado. En la pantalla hay una sección "Para el adulto" con consejos ("Cuenta tú primero, despacio…", "Si elige mal, no digas «no»…") y un modo en el que la pantalla solo muestra los dados y le dice al adulto qué sacar de la caja.

3. Decisiones técnicas: por qué sin framework

El juego tiene 3 pantallas y como mucho unas 60 tapitas en pantalla. Para eso no hace falta React, Vue ni un bundler. Usar HTML, CSS y JavaScript "a secas" tiene ventajas reales:

Lo que publicas son exactamente los archivos que escribiste. No hay paso de compilación que pueda fallar.
Cualquier persona que esté empezando puede leer el código de arriba a abajo.
Los navegadores modernos ya traen todo lo que necesitamos: módulos (import/export), voz (Web Speech API), sonido (Web Audio API) y almacenamiento (localStorage).

La arquitectura en una imagen

   clic del niño
        │
        ▼
   main.js ── busca el data-action del botón ──▶ game.js (acción)
                                                    │
                                     cambia `state` y llama a notify()
                                                    │
                                                    ▼
                                    render.js dibuja la pantalla

Cada archivo tiene una sola responsabilidad:

Archivo	Qué hace	Qué NO hace
`rules.js`	Recibe ajustes y devuelve una ronda.	No toca el DOM, no suena.
`game.js`	Guarda el estado y tiene las acciones.	No arma HTML.
`render.js`	Lee el estado y dibuja.	No cambia el estado.
`main.js`	Escucha los clics y llama a las acciones.	No tiene lógica del juego.

La regla más importante: la información fluye en una sola dirección. Si algo se ve mal, el problema está en render.js. Si el juego hace algo que no debería, está en game.js o en rules.js. Es la misma idea que usan React o Redux, pero sin la librería.

Paso 0: carpetas y servidor local

Crea esta estructura:

matematicas-con-dados/
├── index.html
├── css/
│   └── styles.css
├── js/
│   ├── audio.js      voz y sonidos
│   ├── config.js     datos fijos: colores, tiempos
│   ├── game.js       estado y acciones
│   ├── main.js       punto de entrada
│   ├── render.js     dibuja la pantalla
│   ├── rules.js      reglas: arma cada ronda
│   └── spanish.js    números en palabras
├── tests/
│   └── rules.test.js
└── package.json

En package.json solo necesitamos decirle a Node que usamos módulos:

{ "name": "matematicas-con-dados", "type": "module", "private": true }

Por qué no basta con abrir el archivo con doble clic

Vamos a usar módulos de JavaScript (<script type="module">). Por seguridad, los navegadores no cargan módulos desde file://. Necesitas un servidor local. Cualquiera de estos sirve:

python3 -m http.server 3000      # si tienes Python

o la extensión Live Server de VS Code. Luego abre http://localhost:3000.

En el proyecto real hay un pequeño servidor en Node (scripts/serve.js) que además aplica las mismas cabeceras de seguridad que el sitio publicado. Para este tutorial no hace falta.

Paso 1: el HTML de las tres pantallas

El juego tiene tres pantallas: inicio, juego y final. Las tres están en el mismo HTML y se muestran u ocultan con el atributo hidden. Las zonas que cambian (tarjetas, dados, mesa, respuestas) empiezan vacías: las llena JavaScript.

index.html:

<!doctype html>
<html lang="es">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Matemáticas con Dados</title>
    <link rel="stylesheet" href="css/styles.css" />
    <script type="module" src="js/main.js"></script>
  </head>
  <body>
    <main class="app">
      <!-- INICIO -->
      <section id="screen-home" class="screen">
        <h1>Matemáticas con Dados</h1>
        <div id="operation-tiles" class="tiles"></div>
      </section>

      <!-- JUEGO -->
      <section id="screen-game" class="screen" hidden>
        <button type="button" id="prompt" class="prompt" data-action="repeat-prompt"></button>
        <div id="dice-row" class="dice-row"></div>
        <div id="table" class="table"></div>
        <div id="answers" class="answers"></div>
      </section>

      <!-- FINAL -->
      <section id="screen-end" class="screen" hidden>
        <h2>Terminamos</h2>
        <p>Ahora guardamos las tapitas juntos.</p>
        <div id="end-buttons" class="end-buttons" hidden>
          <button type="button" data-action="go-home">Inicio</button>
          <button type="button" data-action="play-again">Otra vez</button>
        </div>
      </section>
    </main>
  </body>
</html>

Tres detalles:

lang="es" hace que los lectores de pantalla lean en español.
type="module" permite usar import/export y hace que el script se ejecute cuando el HTML ya cargó. No hace falta esperar a DOMContentLoaded.
Ningún botón tiene onclick. Llevan data-action="..." y, en el paso 7, un solo listener se encarga de todos.

Paso 2: la configuración

Todo lo que es "dato fijo" va en un solo archivo. Si mañana quieres cambiar un color o un tiempo, sabes dónde buscar.

js/config.js:

/**
 * CONFIGURACIÓN: todos los datos fijos del juego.
 * Si quieres cambiar un color o un tiempo, este es el archivo.
 */

/** Cada operación tiene SIEMPRE el mismo color: es el ancla visual del niño. */
export const OPERATIONS = {
  contar: { name: 'Contar', symbol: '', color: '#4f8ef7' },
  sumar: { name: 'Sumar', symbol: '+', color: '#ff7a4d' },
};

/** Colores de las tapitas, y el color fijo de cada dado (dado 1 azul, dado 2 verde...). */
export const CAP_COLORS = { blue: '#1d4ed8', green: '#15803d', red: '#b91c1c', orange: '#c2410c' };
export const DICE_COLORS = ['blue', 'green', 'red', 'orange'];

/** Tiempos, en milisegundos. */
export const TIMING = {
  nextRoundDelay: 2800, // después de acertar
  demoStepDelay: 700, // al contar una tapita en la ayuda
  endButtonsDelay: 4000, // los botones del final aparecen después
};

export function defaultSettings() {
  return {
    operation: 'sumar',
    dice: 2, // cuántos dados
    faces: 3, // caras del dado: 1 a 3
    rounds: 5, // rondas por sesión
  };
}

¿Por qué defaultSettings() es una función y no una constante? Porque cada vez que la llamas devuelve un objeto nuevo. Si fuera una constante compartida, cambiar los ajustes en un lugar los cambiaría en todos.

Y un ayudante para que la voz diga los números en palabras, js/spanish.js:

// prettier-ignore
const NUMBER_WORDS = [
  'cero', 'uno', 'dos', 'tres', 'cuatro', 'cinco', 'seis',
  'siete', 'ocho', 'nueve', 'diez', 'once', 'doce',
];

/** 3 → "tres". Desde el 13 usa la cifra, que los motores de voz leen bien. */
export function numberWord(n) {
  return n >= 0 && n < NUMBER_WORDS.length ? NUMBER_WORDS[n] : String(n);
}

Paso 3: las reglas del juego (lógica pura)

Este es el corazón del juego y el archivo más importante del tutorial. Su trabajo: recibir los ajustes y devolver una ronda. Una ronda es un objeto así:

{
  operation: 'sumar',
  values: [2, 1],                         // lo que salió en cada dado
  groups: [['blue', 'blue'], ['green']],  // las tapitas, agrupadas, con su color
  answer: 3,
  prompt: '2 más 1 es igual a…',          // lo que se lee en pantalla
  speech: 'dos más uno es igual a…',      // lo que dice la voz
  key: '2,1',                             // identifica la tirada, para no repetirla
}

Fíjate en que la ronda no sabe nada de botones ni de pantallas. Es solo datos. Eso es lo que llamamos "lógica pura": una función que recibe datos y devuelve datos, sin tocar el DOM, sin sonar y sin guardar nada.

js/rules.js:

/**
 * REGLAS DEL JUEGO: lógica pura.
 * Recibe ajustes, devuelve una ronda. No toca el DOM, no suena, no guarda.
 * Por eso se puede probar en Node, sin navegador.
 */

import { DICE_COLORS } from './config.js';
import { numberWord } from './spanish.js';

/** Entero al azar entre min y max, ambos incluidos. */
export function randomInt(min, max, random = Math.random) {
  return min + Math.floor(random() * (max - min + 1));
}

const sum = (numbers) => numbers.reduce((a, b) => a + b, 0);

/** "2 más 1 es igual a…": en pantalla con cifras (String), en la voz con palabras (numberWord). */
function operationPhrase(numbers, word, say) {
  return `${numbers.map(say).join(` ${word} `)} es igual a…`;
}

function rollDice(settings, random) {
  return Array.from({ length: settings.dice }, () => randomInt(1, settings.faces, random));
}

function buildContar(settings, random) {
  const values = rollDice(settings, random);
  const answer = sum(values);
  return {
    values,
    // Un solo montón, del color del primer dado: no hay grupos que juntar, solo contar.
    groups: [Array(answer).fill(DICE_COLORS[0])],
    answer,
    prompt: '¿Cuántas hay?',
    speech: '¿Cuántas hay?',
  };
}

function buildSumar(settings, random) {
  const values = rollDice(settings, random);
  return {
    values,
    // Un grupo por dado, del color de su dado.
    groups: values.map((value, i) => Array(value).fill(DICE_COLORS[i])),
    answer: sum(values),
    prompt: operationPhrase(values, 'más', String),
    speech: operationPhrase(values, 'más', numberWord),
  };
}

const BUILDERS = { contar: buildContar, sumar: buildSumar };

/**
 * Crea la siguiente ronda, sin repetir la tirada anterior.
 * @param {{ operation: string, dice: number, faces: number }} settings
 * @param {{ previousKey?: string, random?: () => number }} [options]
 */
export function createRound(settings, { previousKey = '', random = Math.random } = {}) {
  let round;
  for (let attempt = 0; attempt < 50; attempt++) {
    round = { operation: settings.operation, ...BUILDERS[settings.operation](settings, random) };
    round.key = round.values.join(',');
    if (round.key !== previousKey) break;
  }
  return round;
}

/** Tres respuestas distintas, de menor a mayor, con la correcta incluida. */
export function makeAnswerOptions(answer, random = Math.random) {
  const nearby = [answer - 2, answer - 1, answer + 1, answer + 2].filter((n) => n >= 0);
  // Mezcla de Fisher-Yates
  for (let i = nearby.length - 1; i > 0; i--) {
    const j = Math.floor(random() * (i + 1));
    [nearby[i], nearby[j]] = [nearby[j], nearby[i]];
  }
  return [answer, nearby[0], nearby[1]].sort((a, b) => a - b);
}

/** "Hay tres." */
export function resultPhrase(answer) {
  return answer === 1 ? 'Hay una.' : `Hay ${numberWord(answer)}.`;
}

Cuatro ideas para llevarte de este archivo:

Una función por operación y un objeto que las agrupa (BUILDERS). Para agregar Restar no hay que tocar createRound: escribes buildRestar y la sumas a BUILDERS.
El azar se puede reemplazar. Todas las funciones reciben random como parámetro, con Math.random por defecto. En las pruebas le pasamos un generador predecible y así una prueba que falla, falla siempre igual.
Respuestas cercanas. Las opciones incorrectas están a 1 o 2 de distancia de la correcta. Si una fuera 3 y la otra 50, el niño adivinaría sin contar.
No repetir la tirada anterior. Si sale dos veces seguidas "2 más 1", para el niño parece que no pasó nada. key identifica la tirada y createRound vuelve a tirar si se repite.

La frase "es igual a…". Al principio el juego decía “Juntamos. ¿Cuántas hay?”. Un día, viendo con mi hija Numberblocks, su programa favorito, me di cuenta de que convenía decir la operación como se dice ahí: “2 más 1 es igual a…”. Así escucha desde el principio el mismo lenguaje que ya conoce del programa y que va a usar en la escuela. Fíjate en que la voz dice “uno” y no “una”: hablamos de números, no de tapitas.

Paso 4: probar las reglas antes de tener pantalla

Como rules.js es lógica pura, la podemos probar en la terminal antes de dibujar un solo botón. Node trae su propio sistema de pruebas (node:test), así que no hay que instalar nada.

tests/rules.test.js:

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { createRound, makeAnswerOptions } from '../js/rules.js';

/** Números al azar repetibles: si una prueba falla, falla siempre igual. */
function seededRandom(seed = 42) {
  let value = seed;
  return () => {
    value = (value * 1664525 + 1013904223) % 4294967296;
    return value / 4294967296;
  };
}

for (const operation of ['contar', 'sumar']) {
  test(`${operation}: 500 rondas que cumplen las reglas`, () => {
    const settings = { operation, dice: 2, faces: 3 };
    const random = seededRandom();
    let previousKey = '';

    for (let i = 0; i < 500; i++) {
      const round = createRound(settings, { previousKey, random });
      const caps = round.groups.flat().length;

      assert.ok(
        round.values.every((v) => v >= 1 && v <= 3),
        'cada dado va de 1 a 3',
      );
      assert.equal(caps, round.answer, 'hay tantas tapitas como la respuesta');
      assert.notEqual(round.key, previousKey, 'no repite la tirada anterior');

      const options = makeAnswerOptions(round.answer, random);
      assert.equal(new Set(options).size, 3, 'tres respuestas distintas');
      assert.ok(options.includes(round.answer), 'incluye la correcta');
      assert.ok(
        options.every((n) => n >= 0),
        'ninguna negativa',
      );
      previousKey = round.key;
    }
  });
}

test('Sumar se dice como se lee', () => {
  const round = createRound({ operation: 'sumar', dice: 2, faces: 3 }, { random: () => 0.5 });
  assert.equal(round.prompt, '2 más 2 es igual a…');
  assert.equal(round.speech, 'dos más dos es igual a…');
});

Córrelas:

node --test

✔ contar: 500 rondas que cumplen las reglas
✔ sumar: 500 rondas que cumplen las reglas
✔ Sumar se dice como se lee
ℹ pass 3
ℹ fail 0

Fíjate en lo que prueban: no "que la función devuelva algo", sino las reglas que importan para el niño. Nunca una respuesta negativa, siempre tres opciones distintas, nunca la misma tirada dos veces. Y no una ronda: 500. El azar esconde errores que aparecen una vez cada cien rondas.

¿Cómo funciona seededRandom? Es un generador congruencial lineal: cada número sale del anterior con una multiplicación y una suma. Parece azar, pero con la misma semilla (42) da siempre la misma secuencia.

Paso 5: el estado y las acciones

Ahora necesitamos un lugar que recuerde qué está pasando: en qué pantalla estamos, qué ronda se juega, qué tapitas ya se contaron. Ese lugar es state, un objeto simple.

La regla de oro: nadie más que game.js cambia state. La interfaz llama a una acción (tapCap, chooseAnswer…), la acción cambia el estado y llama a notify(), y notify() avisa a quien esté escuchando (en el paso 7, la función que dibuja).

js/game.js, primera parte:

/**
 * ESTADO Y ACCIONES.
 * La interfaz nunca cambia `state` directamente: llama a una acción, la acción
 * cambia el estado y avisa con notify(), y la pantalla se vuelve a dibujar.
 *
 *     clic → acción → state → notify() → render()
 */

import { defaultSettings, TIMING } from './config.js';
import { createRound, makeAnswerOptions, resultPhrase } from './rules.js';
import { numberWord } from './spanish.js';
import { say, stopVoice, playCount, playSuccess, playMiss } from './audio.js';

export const state = {
  settings: defaultSettings(),
  screen: 'home', // 'home' | 'game' | 'end'
  phase: 'play', // 'play' | 'helping' | 'solved'
  roundNumber: 0, // rondas terminadas en esta sesión
  round: null,
  answerOptions: [],
  countedCaps: new Map(), // id de tapita → número que se le asignó
  highlightedCap: null, // la tapita que se agranda durante la ayuda
  pulsingAnswer: null, // la respuesta correcta que late después de la ayuda
  helpShown: false,
  endButtonsVisible: false,
};

// --- Avisar cambios ---------------------------------------------------------

const listeners = [];

export function onChange(listener) {
  listeners.push(listener);
}

function notify() {
  listeners.forEach((listener) => listener(state));
}

phase es importante: dice qué puede hacer el niño ahora.

`phase`	Qué significa	Qué acepta
`play`	el niño puede tocar	tapitas, respuestas
`helping`	la app está contando	nada
`solved`	acertó; en un momento sigue la ronda	nada

El problema de las tareas que esperan

Hay acciones que tardan: la ayuda cuenta una tapita cada 700 ms; después de acertar se espera 2,8 s antes de la ronda siguiente. ¿Qué pasa si el niño vuelve al inicio a mitad de la ayuda? La tarea sigue corriendo y la voz sigue contando en la pantalla de inicio.

La solución es sencilla: cada ronda tiene un número. Cada tarea anota el número con el que empezó y, después de cada espera, revisa si sigue siendo el mismo. Si no, se detiene.

Agrégalo en js/game.js, debajo de notify():

// --- Tareas con espera que se cancelan solas --------------------------------
// Cada ronda tiene un número. Una tarea guarda el número con el que empezó y,
// si cambió mientras esperaba (por ejemplo, el niño volvió al inicio), se detiene.

let roundId = 0;
const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const isStale = (id) => id !== roundId;

goHome() y cada ronda nueva suben roundId, y con eso todas las tareas viejas se cancelan solas.

Navegación y rondas

Sigue en js/game.js, debajo de lo anterior:

// --- Navegación ---------------------------------------------------------------

export function startOperation(operation) {
  state.settings.operation = operation;
  startSession();
}

export function startSession() {
  state.roundNumber = 0;
  state.screen = 'game';
  startRound();
}

export function goHome() {
  roundId++;
  stopVoice();
  state.screen = 'home';
  notify();
}

export function repeatPrompt() {
  if (state.round) say(state.round.speech);
}

// --- Rondas -------------------------------------------------------------------

function startRound() {
  roundId++;
  const round = createRound(state.settings, { previousKey: state.round?.key });
  Object.assign(state, {
    round,
    answerOptions: makeAnswerOptions(round.answer),
    phase: 'play',
    countedCaps: new Map(),
    highlightedCap: null,
    pulsingAnswer: null,
    helpShown: false,
  });
  notify();

  // Anticipar el final: el cierre no toma por sorpresa.
  const roundsLeft = state.settings.rounds - state.roundNumber;
  let intro = '';
  if (roundsLeft === 2) intro = 'Dos más y guardamos. ';
  else if (roundsLeft === 1) intro = 'La última y guardamos. ';
  say(intro + round.speech);
}

function finishSession() {
  roundId++;
  const id = roundId;
  state.screen = 'end';
  state.endButtonsVisible = false;
  notify();
  say('Terminamos. Guardamos las tapitas.');
  // Los botones aparecen después, para que el cierre se sienta como cierre.
  setTimeout(() => {
    if (isStale(id)) return;
    state.endButtonsVisible = true;
    notify();
  }, TIMING.endButtonsDelay);
}

Aquí están dos de las reglas de la investigación convertidas en código: el aviso "Dos más y guardamos" y los botones que aparecen a los 4 segundos.

Los toques del niño, y la ayuda sin "no"

Y al final de js/game.js:

// --- Toques del niño ----------------------------------------------------------

/** Tocar una tapita la cuenta: uno, dos, tres... */
export function tapCap(capId) {
  if (state.phase !== 'play') return;
  const counted = state.countedCaps.get(capId);
  if (counted !== undefined) {
    say(numberWord(counted)); // ya estaba contada: solo repite su número
    return;
  }
  const number = state.countedCaps.size + 1;
  state.countedCaps.set(capId, number);
  playCount(number);
  say(numberWord(number));
  notify();
}

export function chooseAnswer(value) {
  const { round } = state;
  if (!round || state.phase !== 'play') return;

  if (value === round.answer) {
    celebrate(round);
    return;
  }
  // Sin "no" y sin castigo: un tono suave y la app ayuda a contar.
  playMiss();
  if (!state.helpShown) {
    state.helpShown = true;
    showHelp();
  }
}

function celebrate(round) {
  const id = roundId;
  state.phase = 'solved';
  state.roundNumber++;
  playSuccess();
  notify();
  say(`Sí. ${resultPhrase(round.answer)}`);

  setTimeout(() => {
    if (isStale(id)) return;
    if (state.roundNumber >= state.settings.rounds) finishSession();
    else startRound();
  }, TIMING.nextRoundDelay);
}

/** La app cuenta en voz alta, tapita por tapita, y la respuesta correcta empieza a latir. */
async function showHelp() {
  const id = roundId;
  const { round } = state;
  state.phase = 'helping';
  state.countedCaps.clear();
  notify();

  const total = round.groups.flat().length;
  for (let i = 0; i < total; i++) {
    const capId = `cap-${i}`;
    state.countedCaps.set(capId, i + 1);
    state.highlightedCap = capId;
    notify();
    say(numberWord(i + 1));
    await wait(TIMING.demoStepDelay);
    if (isStale(id)) return;
  }

  state.highlightedCap = null;
  notify();
  await say(resultPhrase(round.answer));
  if (isStale(id)) return;
  state.pulsingAnswer = round.answer;
  state.phase = 'play';
  notify();
}

Mira tapCap: la Map countedCaps es la correspondencia uno a uno en código. Una tapita ya contada no suma otra vez: repite su número.

Y showHelp es la regla "nunca decir no": en vez de marcar el error, la app vuelve a contar desde cero, tapita por tapita, dice "Hay cuatro." (cardinalidad) y deja latiendo la respuesta correcta. El niño es quien la toca.

Paso 6: dibujar la pantalla

render.js recibe el estado y arma HTML con texto. Cada vez que algo cambia, se vuelve a dibujar la zona completa con innerHTML. Es el modelo más simple que existe y, para unas pocas decenas de elementos, es rápido de sobra.

El dado: una grilla de 3×3

Un dado es una grilla de 9 celdas; algunas tienen punto. Basta una tabla que diga qué celdas se pintan para cada número:

 0 │ 1 │ 2        5:   ● │   │ ●
───┼───┼───           ───┼───┼───
 3 │ 4 │ 5               │ ● │
───┼───┼───           ───┼───┼───
 6 │ 7 │ 8             ● │   │ ●     → [0, 2, 4, 6, 8]

js/render.js:

/**
 * DIBUJO: lee el estado y arma HTML. Nunca cambia el estado.
 */

import { OPERATIONS, CAP_COLORS, DICE_COLORS } from './config.js';

const $ = (id) => document.getElementById(id);

/** Posiciones de los puntos en la grilla 3×3 del dado (0 = arriba a la izquierda). */
const PIP_POSITIONS = {
  1: [4],
  2: [0, 8],
  3: [0, 4, 8],
  4: [0, 2, 6, 8],
  5: [0, 2, 4, 6, 8],
  6: [0, 2, 3, 5, 6, 8],
};

function dieHTML(value, colorId) {
  const cells = Array.from({ length: 9 }, (_, i) =>
    PIP_POSITIONS[value].includes(i) ? '<span class="die__pip"></span>' : '<span></span>',
  ).join('');
  return `<div class="die" style="--edge:${CAP_COLORS[colorId]}" role="img" aria-label="Dado: ${value}">${cells}</div>`;
}

function capHTML(id, colorId, state) {
  const number = state.countedCaps.get(id);
  const highlighted = state.highlightedCap === id ? 'cap--highlighted' : '';
  return `<button type="button" class="cap ${highlighted}" style="--cap-color:${CAP_COLORS[colorId]}"
    data-action="tap-cap" data-cap="${id}" aria-label="Tapita${number ? `, ${number}` : ''}">${number ?? ''}</button>`;
}

Cada tapita es un <button> de verdad: así funciona con el dedo, con el mouse y con el teclado. El dado lleva role="img" y aria-label="Dado: 5" para que un lector de pantalla diga el número.

El color va en una variable CSS (--cap-color) y no en una clase por color. Así el CSS tiene una sola regla .cap y el color sale de config.js.

Las pantallas

Al final de js/render.js, debajo de capHTML:

function renderHome() {
  $('operation-tiles').innerHTML = Object.entries(OPERATIONS)
    .map(
      ([id, operation]) => `
      <button type="button" class="tile" style="--tile-color:${operation.color}"
        data-action="start-operation" data-operation="${id}">${operation.name}</button>`,
    )
    .join('');
}

function renderGame(state) {
  const { round } = state;
  const operation = OPERATIONS[round.operation];

  $('prompt').textContent = `🔊 ${round.prompt}`;

  const result = state.phase === 'solved' ? round.answer : '?';
  $('dice-row').innerHTML =
    round.values.map((value, i) => dieHTML(value, DICE_COLORS[i])).join(`<span>${operation.symbol}</span>`) +
    `<span>=</span><span>${result}</span>`;

  // Cada tapita tiene un id único (cap-0, cap-1...) para saber cuál se contó.
  let capIndex = 0;
  $('table').innerHTML = round.groups
    .map((group) => {
      const caps = group.map((colorId) => capHTML(`cap-${capIndex++}`, colorId, state)).join('');
      return `<div class="cap-group" style="--columns:${Math.min(5, group.length)}">${caps}</div>`;
    })
    .join('');

  $('answers').innerHTML = state.answerOptions
    .map((value) => {
      const pulsing = state.pulsingAnswer === value ? 'is-pulsing' : '';
      return `<button type="button" class="answer ${pulsing}" data-action="choose-answer" data-value="${value}">${value}</button>`;
    })
    .join('');
}

export function render(state) {
  $('screen-home').hidden = state.screen !== 'home';
  $('screen-game').hidden = state.screen !== 'game';
  $('screen-end').hidden = state.screen !== 'end';

  // El fondo toma el color de la operación.
  const color = state.screen === 'home' ? '#ffa23a' : OPERATIONS[state.settings.operation].color;
  document.documentElement.style.setProperty('--theme', color);

  if (state.screen === 'home') renderHome();
  if (state.screen === 'game') renderGame(state);
  if (state.screen === 'end') $('end-buttons').hidden = !state.endButtonsVisible;
}

--columns: Math.min(5, group.length) es lo que ordena las tapitas en filas de 5, como un cartón de huevos.

Ojo con innerHTML. Aquí es seguro porque todo lo que se interpola viene de config.js o son números calculados: nunca texto que escribió una persona. Si alguna vez muestras texto de un usuario, escápalo primero (en el proyecto real hay una función escapeHTML para eso).

Paso 7: conectar los clics

Podríamos ponerle un addEventListener a cada botón, pero los botones se crean y se destruyen en cada render. En lugar de eso usamos delegación de eventos: un solo listener en todo el documento que, ante cada clic, busca el data-action más cercano.

js/main.js:

/**
 * PUNTO DE ENTRADA: conecta el estado con el dibujo y traduce cada clic en una acción.
 */

import * as game from './game.js';
import { render } from './render.js';
import { unlockAudio } from './audio.js';

/** Qué hace cada data-action. Para un botón nuevo: ponle data-action y suma una línea aquí. */
const ACTIONS = {
  'start-operation': (el) => {
    unlockAudio(); // primer toque: el navegador ya permite sonar
    game.startOperation(el.dataset.operation);
  },
  'repeat-prompt': () => game.repeatPrompt(),
  'tap-cap': (el) => game.tapCap(el.dataset.cap),
  'choose-answer': (el) => game.chooseAnswer(Number(el.dataset.value)),
  'go-home': () => game.goHome(),
  'play-again': () => game.startSession(),
};

// Un solo listener para toda la página (delegación de eventos).
// closest() encuentra el botón aunque se toque el número que tiene adentro,
// y funciona con botones que se crearon después de cargar la página.
document.addEventListener('click', (event) => {
  const element = event.target.closest('[data-action]');
  if (element) ACTIONS[element.dataset.action]?.(element);
});

game.onChange(render);
render(game.state);

game.onChange(render) es la pieza que cierra el círculo: cada vez que una acción llama a notify(), se ejecuta render(state).

Paso 8: voz y sonidos sin archivos de audio

El navegador trae dos APIs que nos ahorran grabar audios:

Web Speech API (speechSynthesis): convierte texto en voz.
Web Audio API (AudioContext): genera tonos con un oscilador.

js/audio.js:

/**
 * VOZ (Web Speech API) Y SONIDOS (Web Audio API). Sin archivos de audio.
 */

const hasSpeech = 'speechSynthesis' in window;
let spanishVoice = null;

/** Prefiere una voz en español que funcione en el propio dispositivo (privacidad). */
function pickSpanishVoice() {
  const voices = speechSynthesis.getVoices().filter((voice) => voice.lang.toLowerCase().startsWith('es'));
  spanishVoice = voices.find((voice) => voice.localService) ?? voices[0] ?? null;
}

if (hasSpeech) {
  pickSpanishVoice();
  // La lista de voces puede llegar vacía al principio y completarse después.
  speechSynthesis.addEventListener('voiceschanged', pickSpanishVoice);
}

/**
 * Dice una frase e interrumpe la anterior: si el niño toca rápido, se escucha
 * el último número y no una cola de números. Se resuelve al terminar de hablar.
 */
export function say(text) {
  return new Promise((resolve) => {
    if (!hasSpeech) return resolve();
    speechSynthesis.cancel();
    const utterance = new SpeechSynthesisUtterance(text);
    utterance.lang = spanishVoice?.lang ?? 'es-MX';
    if (spanishVoice) utterance.voice = spanishVoice;
    utterance.rate = 0.9; // un poco más lento que lo normal
    utterance.onend = resolve;
    utterance.onerror = resolve;
    speechSynthesis.speak(utterance);
    setTimeout(resolve, 5000); // por si el navegador nunca avisa que terminó
  });
}

export function stopVoice() {
  if (hasSpeech) speechSynthesis.cancel();
}

let audioContext = null;

/** Los navegadores no dejan sonar hasta que la persona toca la pantalla. */
export function unlockAudio() {
  audioContext ??= new AudioContext();
  if (audioContext.state === 'suspended') audioContext.resume().catch(() => {});
  if (hasSpeech) pickSpanishVoice();
}

/** Un tono corto que se apaga solo. */
export function playTone(frequency, duration = 0.1, volume = 0.12) {
  if (!audioContext) return;
  const now = audioContext.currentTime;
  const oscillator = audioContext.createOscillator();
  const gain = audioContext.createGain();
  oscillator.frequency.value = frequency;
  gain.gain.setValueAtTime(volume, now);
  gain.gain.exponentialRampToValueAtTime(0.001, now + duration);
  oscillator.connect(gain).connect(audioContext.destination);
  oscillator.start(now);
  oscillator.stop(now + duration);
}

/** Tres notas suaves al acertar (do, mi, sol). */
export function playSuccess() {
  [523, 659, 784].forEach((note, i) => setTimeout(() => playTone(note, 0.18), i * 110));
}

/** Un tono grave y corto al equivocarse. Suave: no es un castigo. */
export function playMiss() {
  playTone(240, 0.14, 0.08);
}

/** El tono sube con cada tapita: el niño "escucha" que el número crece. */
export function playCount(n) {
  playTone(330 + Math.min(n, 20) * 20, 0.08);
}

Tres detalles que costaron aprender:

El audio está bloqueado hasta el primer toque. Los navegadores, y sobre todo Safari en iPhone, no dejan sonar una página que el usuario no tocó. Por eso unlockAudio() se llama al elegir una operación.
say devuelve una promesa. Así la ayuda puede esperar a que termine una frase con await say(...). El setTimeout de 5 s es una red de seguridad: algunos navegadores a veces nunca avisan que terminaron.
Privacidad: algunas voces (por ejemplo, las "Google…" de Chrome) envían el texto a un servidor para convertirlo en audio. Las que tienen localService === true funcionan en el propio dispositivo. Por eso se prefieren.

Y un detalle de diseño: playCount sube el tono con cada tapita. Sin decir nada, el niño escucha que el número crece.

Paso 9: los estilos

El CSS completo está en el anexo, al final del artículo. Estas son las partes que vale la pena entender.

El dado, con CSS Grid:

/* El dado: una grilla de 3×3 donde algunas celdas tienen punto. */
.die {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 3px;
  width: 56px;
  height: 56px;
  padding: 6px;
  box-sizing: border-box;
  border: 3px solid var(--edge);
  border-radius: 12px;
  background: #fff;
}

.die__pip {
  border-radius: 50%;
  background: var(--edge);
}

Las tapitas en filas de 5, con la variable --columns que pone render.js:

/* Un grupo de tapitas en filas de hasta 5, como un cartón de huevos. */
.cap-group {
  display: grid;
  grid-template-columns: repeat(var(--columns), auto);
  gap: 8px;
}

.cap {
  width: var(--cap-size);
  height: var(--cap-size);
  border: 3px dashed rgb(255 255 255 / 45%);
  border-radius: 50%;
  background: var(--cap-color);
  color: #fff;
  font-size: 20px;
  font-weight: 700;
}

La respuesta que late, y la regla que la apaga si el sistema pide reducir el movimiento:

.answer.is-pulsing {
  animation: pulse 1s ease-in-out infinite;
}

@keyframes pulse {
  50% {
    transform: scale(1.12);
  }
}

/* Si el sistema pide "reducir movimiento", nada se mueve. */
@media (prefers-reduced-motion: reduce) {
  * {
    animation: none !important;
    transition: none !important;
  }
}

prefers-reduced-motion lee una opción de accesibilidad del sistema operativo (por ejemplo, "Reducir movimiento" en iPhone y Mac). Respetarla cuesta unas pocas líneas.

Punto de control

Levanta el servidor, abre http://localhost:3000 y juega. Deberías poder:

Elegir Contar o Sumar, y ver el fondo cambiar al color de la operación.
Escuchar "2 más 1 es igual a…".
Tocar las tapitas y oír "uno, dos, tres" con un tono que sube.
Elegir una respuesta equivocada y ver cómo la app cuenta sola y la correcta empieza a latir.
Escuchar "Dos más y guardamos" en la cuarta ronda de cinco.
Llegar al final y ver los botones recién a los 4 segundos.

Ejercicio: agrega Restar

Con lo que ya tienes, puedes agregar una operación sin tocar createRound:

En config.js, suma restar: { name: 'Restar', symbol: '−', color: '#ff5d8f' } a OPERATIONS.
En rules.js, escribe buildRestar(settings, random): el primer dado dice cuántas tapitas poner; el segundo, cuántas quitar. Cuida que el segundo no sea mayor que el primero (¡nada de respuestas negativas!). Para la frase, operationPhrase(values, 'menos', String).
Regístrala en BUILDERS y agrega 'restar' a la lista de operaciones de la prueba.

Corre node --test. Si la prueba de "ninguna negativa" falla, ya sabes dónde buscar.

Del prototipo al proyecto real

La versión mínima funciona, pero el proyecto real tuvo que resolver bastante más. Esta sección muestra esos problemas con extractos del código real y cuenta cómo se encontraron. Varios aparecieron recién en una auditoría, cuando el juego ya "funcionaba".

1. "Nunca pedir más tapitas de las que hay"

En el modo "Tapitas reales", la pantalla le dice al adulto qué sacar de la caja: "Saca 3 azules y 2 verdes". El adulto configura cuántas tapitas de cada color tiene. Regla: la app nunca puede pedir más de las que hay.

La primera versión probaba unas cuantas tiradas y, si ninguna cabía en la caja, aceptaba cualquiera. Con una caja con una sola tapita negra y el dado 1 de color negro, Restar pedía tapitas que no existían en 200 de 200 rondas. La solución: un orden de preferencia explícito, y una última opción que siempre cumple la regla.

for (let attempt = 0; attempt < 120; attempt++) {
  const round = tryBuild();
  if (round && round.key !== previousKey && fits(round)) return round;
}
// Caja chica o dado de un color con pocas tapitas: repetir la tirada
// anterior es mejor que pedir tapitas que no hay.
for (let attempt = 0; attempt < 200; attempt++) {
  const round = tryBuild();
  if (round && fits(round)) return round;
}
return countingFallback(settings, random);

Primero, una ronda nueva que quepa. Si no aparece, una que quepa aunque repita la anterior. Y si tampoco, countingFallback arma una ronda de Contar con el color que más tapitas tiene. La lección: cuando una regla es sagrada, el código tiene que garantizarla en todos los caminos, también en el último. Y la prueba tiene que usar cajas chicas a propósito.

2. No confiar en `localStorage`

Los ajustes se guardan en el navegador para que el adulto no configure la caja cada vez. Pero localStorage es texto que cualquiera puede editar desde las herramientas del navegador. La primera versión validaba la operación así:

raw.operation in OPERATIONS;

Y 'toString' in OPERATIONS es true: el operador in también mira lo que el objeto hereda. Un ajuste con "operation": "toString" rompía el juego. La versión real usa Object.hasOwn y valida cada campo contra una lista cerrada:

export function normalizeSettings(raw) {
  const settings = defaultSettings();
  if (!isPlainObject(raw)) return settings;

  if (isOperationId(raw.operation)) settings.operation = raw.operation;
  if (Number.isInteger(raw.dice)) settings.dice = /** @type {number} */ (raw.dice);
  if (raw.preferredLevel === 2 || raw.preferredLevel === 3 || raw.preferredLevel === 4) {
    settings.preferredLevel = raw.preferredLevel;
  }
  if (raw.faces === 3 || raw.faces === 6) settings.faces = raw.faces;
  if (raw.rounds === 3 || raw.rounds === 5 || raw.rounds === 8) settings.rounds = raw.rounds;
  if (typeof raw.voice === 'boolean') settings.voice = raw.voice;
  if (typeof raw.sound === 'boolean') settings.sound = raw.sound;
  if (typeof raw.realCaps === 'boolean') settings.realCaps = raw.realCaps;

El patrón: empezar de los valores por defecto y copiar solo lo que pasa la validación. Nunca al revés.

3. El teclado perdía su lugar en cada toque

innerHTML borra los botones y crea otros nuevos. Si el foco del teclado estaba en uno, el navegador lo manda al <body> y quien navega con teclado tiene que empezar desde arriba después de cada toque. En la versión mínima pasa; pruébalo con Tab.

El proyecto real dibuja cada zona con updateZone(), que no toca una zona si quedó igual y, si el foco estaba adentro, lo devuelve al "mismo" botón:

export function updateZone(zone, html) {
  if (lastHTML.get(zone) === html) return;
  lastHTML.set(zone, html);

  const active = document.activeElement;
  const hadFocus = active instanceof HTMLElement && active !== zone && zone.contains(active);
  const selector = hadFocus ? identitySelector(active) : '';
  const action = hadFocus ? active.getAttribute('data-action') : null;

  zone.innerHTML = html;
  applyStyleVars(zone);
  if (!hadFocus) return;

  const target =
    (selector && zone.querySelector(selector)) ||
    (action && zone.querySelector(`[data-action="${CSS.escape(action)}"]`)) ||
    zone.querySelector('button, [tabindex="0"], input, select');
  if (target instanceof HTMLElement) target.focus();
}

"El mismo botón" se reconoce por sus atributos (data-action, data-cap, data-value…), porque el elemento en sí es nuevo. No es un DOM virtual: compara texto HTML y nada más. Pero resuelve el problema.

Otras mejoras de accesibilidad del proyecto real, todas pequeñas:

aria-disabled en vez de disabled en las respuestas mientras la app ayuda. disabled saca el botón del orden del teclado y el foco se pierde.
inert en los botones del final mientras están ocultos: tampoco se pueden alcanzar con Tab.
Una sola región aria-live que anuncia la pregunta y el resultado. Antes se anunciaba la mesa entera en cada toque.
Contraste: el texto sobre el color de cada operación es oscuro, con al menos 4,5:1 de contraste, sin cambiar los colores de las operaciones (que son el ancla del niño).
Al cambiar de pantalla, el foco va al título o a la pregunta.

4. Seguridad: una CSP estricta sin perder los colores

Una Content Security Policy (CSP) le dice al navegador qué puede cargar la página. La del proyecto real es muy estricta: solo archivos del propio sitio y ningún estilo escrito dentro del HTML. Eso incluye los style="--cap-color:..." que usamos en la versión mínima.

La solución: el HTML lleva los colores en un atributo de datos, y JavaScript los aplica con element.style.setProperty, que la CSP sí permite:

export function applyStyleVars(root) {
  for (const element of root.querySelectorAll('[data-vars]')) {
    if (!(element instanceof HTMLElement || element instanceof SVGElement)) continue;
    for (const declaration of (element.dataset.vars ?? '').split(';')) {
      const [name, value] = declaration.split(':').map((part) => part.trim());
      if (name?.startsWith('--') && value) element.style.setProperty(name, value);
    }
  }
}

En el HTML, style="--edge:#1d4ed8" pasa a ser data-vars="--edge:#1d4ed8". El CSS no cambia. Y la función solo acepta variables (nombres que empiezan con --), nunca otra propiedad.

5. Privacidad: nada sale del dispositivo

Es un juego para niños, así que la meta fue que no saliera ningún dato. Dos hallazgos:

La primera versión cargaba la letra Fredoka desde Google Fonts. Eso envía la dirección IP del dispositivo a un tercero en cada visita. Ahora la fuente se sirve desde el propio sitio: un solo archivo woff2 de unos 30 KB, con su licencia (OFL).
La elección de voz, como viste en el paso 8, prefiere voces locales.

Una prueba automática verifica que ninguna petición sale del propio sitio. Los ajustes guardados no tienen nada del niño: ni nombre, ni edad, ni aciertos.

6. Funcionar sin internet

Un service worker es un script que el navegador ejecuta aparte de la página y que puede responder las peticiones. El proyecto real usa la estrategia más fácil de razonar, "primero la red": con internet siempre se descarga la versión publicada (y se guarda una copia); sin internet se usa la copia.

// Cada pedido: primero la red; si falla, la copia guardada.
self.addEventListener('fetch', (event) => {
  const { request } = event;
  if (request.method !== 'GET' || new URL(request.url).origin !== self.location.origin) return;

  event.respondWith(
    fetch(request)
      .then((response) => {
        if (response.ok) {
          const copy = response.clone();
          caches.open(CACHE_NAME).then((cache) => cache.put(request, copy));
        }
        return response;
      })
      .catch(async () => (await caches.match(request)) ?? (await caches.match('index.html')) ?? Response.error()),
  );
});

Con un manifest.webmanifest y sus íconos, el juego además se puede instalar en la pantalla de inicio del celular o la tablet y abrirse a pantalla completa.

7. Herramientas que cuidan el código

Ninguna de estas herramientas se publica con el sitio. Son solo para desarrollo (devDependencies):

Herramienta	Para qué
JSDoc + `tsc --noEmit`	Tipos escritos en comentarios. TypeScript los revisa en modo estricto sin compilar nada.
ESLint	Detecta errores comunes, como variables que no se usan.
Prettier	Formato uniforme: nadie discute espacios ni comillas.
`node:test`	Pruebas unitarias de las reglas, el estado y el almacenamiento, sin navegador.
Playwright	Juega el juego de verdad en un navegador, en tamaño celular y en tamaño escritorio.

Una de las pruebas de Playwright que más me gusta comprueba la regla más importante del juego: ante una respuesta equivocada, ninguna frase de la voz contiene la palabra "no".

test('Respuesta equivocada: ayuda completa, sin "no", y la correcta late', async ({ page }) => {
  await page.goto('/');
  await startOperation(page, 'sumar', 2);
  const { answer } = await gameState(page);
  const wrong = page.locator(`[data-action="choose-answer"]:not([data-value="${answer}"])`).first();
  await wrong.click();

  await expect.poll(async () => (await gameState(page)).mood).toBe('think');
  await expect(page.locator('.answer[aria-disabled="true"]')).toHaveCount(3); // mientras ayuda
  await expect(page.locator(`.answer.is-pulsing[data-value="${answer}"]`)).toBeVisible({ timeout: 30_000 });
  await expect(page.locator('.cap--counted')).toHaveCount(Number(answer));

  for (const phrase of await spoken(page)) expect(phrase).not.toMatch(/\bno\b/i);
});

Las reglas del niño son requisitos, y los requisitos se prueban. Si alguien cambia una frase dentro de un año, la prueba le avisa.

Publicarlo

Es un sitio estático: se publica la carpeta tal como está, sin compilar.

Hosting	Cabeceras de seguridad	Qué hacer
Cloudflare Pages	Sí, desde el archivo `_headers`	Conectar el repositorio. Comando de build: ninguno. Carpeta de salida: `/`.
Netlify	Sí, desde el archivo `_headers`	Conectar el repositorio. Build command: vacío. Publish directory: `.`.
GitHub Pages	No permite cabeceras propias	Publicar desde la rama `main`. La CSP igual se aplica con una etiqueta `<meta>` en el HTML.

Una vez publicado, se abre desde cualquier navegador moderno y, después de la primera visita, funciona sin internet.

Lo que aprendí

El usuario define las reglas, el código las garantiza. "Nunca decir no" o "nunca pedir más tapitas de las que hay" no son detalles: son requisitos. Cada uno tiene su prueba.
Lo simple escala más de lo que parece. Tres pantallas, un objeto de estado y innerHTML alcanzaron para un juego completo, accesible y con pruebas.
La lógica pura se prueba sola. Separar rules.js del DOM permitió probar miles de rondas en milisegundos, antes de tener pantalla.
La accesibilidad son muchos detalles chicos. Ninguno fue difícil; todos se habrían perdido sin probar con el teclado y con un lector de pantalla.
Las observaciones de otros mejoran el juego. "Contar también necesita niveles" llegó de personas que lo usaron, y "2 más 1 es igual a…" salió de ver Numberblocks con mi hija.

Glosario

Término	Qué es
Módulo ES	Un archivo `.js` que usa `import` y `export`. Se carga con `<script type="module">`.
Lógica pura	Código que recibe datos y devuelve datos, sin efectos: no toca la pantalla, no suena, no guarda.
Estado (`state`)	El objeto que recuerda qué está pasando en el juego.
Delegación de eventos	Un solo listener en un elemento padre que atiende los clics de todos sus hijos.
*`data-`**	Atributos propios en el HTML (`data-action`, `data-cap`) que JavaScript lee con `element.dataset`.
Variable CSS	Un valor con nombre (`--cap-color`) que el CSS usa con `var(--cap-color)`.
CSP	Content Security Policy: reglas que le dicen al navegador qué puede cargar y ejecutar la página.
Service worker	Un script que el navegador ejecuta aparte de la página y que permite, por ejemplo, funcionar sin internet.
*`aria-`**	Atributos que describen la página para los lectores de pantalla.
Subitización	Reconocer cuántos objetos hay sin contarlos, en cantidades chicas.
Cardinalidad	Saber que el último número que se dice al contar es cuántos objetos hay.

Anexo: el CSS completo de la versión mínima

css/styles.css:

:root {
  --theme: #ffa23a; /* lo cambia render.js según la operación */
  --cap-size: 48px;
  font-family: system-ui, sans-serif;
}

body {
  margin: 0;
  min-height: 100vh;
  background: linear-gradient(var(--theme), #fff 60%);
}

.app {
  max-width: 600px;
  margin: 0 auto;
  padding: 16px;
  text-align: center;
}

button {
  font: inherit;
  cursor: pointer;
}

.tiles {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
  gap: 12px;
}

.tile {
  padding: 24px 12px;
  border: 0;
  border-radius: 20px;
  background: var(--tile-color);
  font-size: 24px;
  font-weight: 700;
}

.prompt {
  padding: 12px 20px;
  border: 0;
  border-radius: 999px;
  background: #fff;
  font-size: 22px;
}

.dice-row {
  display: flex;
  align-items: center;
  justify-content: center;
  gap: 10px;
  margin: 16px 0;
  font-size: 36px;
  font-weight: 700;
}

/* El dado: una grilla de 3×3 donde algunas celdas tienen punto. */
.die {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 3px;
  width: 56px;
  height: 56px;
  padding: 6px;
  box-sizing: border-box;
  border: 3px solid var(--edge);
  border-radius: 12px;
  background: #fff;
}

.die__pip {
  border-radius: 50%;
  background: var(--edge);
}

.table {
  display: flex;
  flex-wrap: wrap;
  justify-content: center;
  gap: 16px;
  padding: 16px;
  border-radius: 20px;
  background: #e8b77a;
}

/* Un grupo de tapitas en filas de hasta 5, como un cartón de huevos. */
.cap-group {
  display: grid;
  grid-template-columns: repeat(var(--columns), auto);
  gap: 8px;
}

.cap {
  width: var(--cap-size);
  height: var(--cap-size);
  border: 3px dashed rgb(255 255 255 / 45%);
  border-radius: 50%;
  background: var(--cap-color);
  color: #fff;
  font-size: 20px;
  font-weight: 700;
}

.cap--highlighted {
  transform: scale(1.2);
}

.answers {
  display: flex;
  justify-content: center;
  gap: 12px;
  margin-top: 16px;
}

.answer {
  width: 90px;
  height: 90px;
  border: 0;
  border-radius: 20px;
  background: #fff;
  font-size: 40px;
  font-weight: 700;
}

.answer.is-pulsing {
  animation: pulse 1s ease-in-out infinite;
}

@keyframes pulse {
  50% {
    transform: scale(1.12);
  }
}

/* Si el sistema pide "reducir movimiento", nada se mueve. */
@media (prefers-reduced-motion: reduce) {
  * {
    animation: none !important;
    transition: none !important;
  }
}

Si construyes tu propia versión, o la usas con un niño, me encantaría saber cómo te fue.

Matemáticas con Dados: how I built a game to help my little girl learn to count with dice and real bottle caps

Enrique Lazo Bello — Fri, 23 Oct 2026 12:21:49 +0000

A web game made with HTML, CSS and JavaScript, no framework, designed for little kids. In this tutorial we build it from scratch: the idea, the research behind every decision, and the code, step by step.

Who it's for: programmers who are just starting out and programming enthusiasts with basic HTML and JavaScript knowledge. If you know what a function and an array are, you can follow along.

What you'll build: a minimal but complete version of the game, with Count and Add, a Spanish voice, help when the child gets it wrong, and a closing screen.

Full code: https://github.com/the-bunker-code/matematicas-con-dados
Let's play: https://the-bunker-code.github.io/matematicas-con-dados/

A note on language. The game is in Spanish: it was made for a Spanish-speaking child, and the voice speaks Spanish. In the code below, the comments are translated to English, but identifiers and on-screen strings stay exactly as they are in the repository, so you can match them. A few words you'll see often: contar = count, sumar = add, tapita = bottle cap, "2 más 1 es igual a…" = "2 plus 1 equals…", "¿Cuántas hay?" = "How many are there?", "Hay cuatro." = "There are four.", "Dos más y guardamos" = "Two more and we put them away". Want it to speak English? Step 8 explains what to change.

The idea
The research: what a child needs to learn to count
Technical decisions: why no framework
Step 0: folders and a local server
Step 1: the HTML for the three screens
Step 2: configuration
Step 3: the game rules (pure logic)
Step 4: test the rules before there is a screen
Step 5: state and actions
Step 6: drawing the screen
Step 7: wiring up the clicks
Step 8: voice and sounds without audio files
Step 9: styles
From prototype to real project
Publishing it
What I learned
Glossary
Appendix: the full CSS of the minimal version

1. The idea

It all started on a small children's table, with a white box full of plastic bottle caps and a phone resting beside it.

At almost 4 years old, my little girl learns with her hands: she needs to feel, move, stack and sort before an abstract symbol makes sense. Traditional math apps did exactly the opposite: they filled the screen with flashing lights, harsh noises when she made a mistake, and empty rewards that pulled her into the glass and disconnected her from what was around her.

I decided to flip the interaction around: the app doesn't replace the bottle caps, it accompanies them.

The phone, resting on the table, poses the challenge silently or with a calm voice. She looks at the two dice on the screen: a 4 and a 3. She reaches into the box, takes out four red caps and three green ones, lines them up in rows and counts them out loud, touching each one with her finger. Only after she has felt the quantity in her hands does she go back to the screen and pick the result. Next to her there is always an adult who doesn't interrupt; they just go along at her pace.

These rules were born from watching her play at that table, and the code follows them to the letter:

No punishment and no loud noises. There is never a sharp "no" or an error sound. If she gets it wrong, the app counts along with her and shows her the way.
The screen is a board, not a distraction. The phone stays still on the table. The graphics are simple and stable, so attention stays on the caps.
Groups you can touch. Each die has its own color, and each color is a group of caps. That way, adding means joining two real groups.
Short, predictable sessions. She picks 3, 5 or 8 rounds. A warning plays before the end, so the ending doesn't catch her by surprise.
The end feels like the end. The button to play again takes 4 seconds to appear. That pause keeps her from tapping on and on.
It respects what's on the table. The game never asks for more caps than fit in her box.
Visual calm. There are very few animations (none if the phone has reduced motion turned on), each operation always has the same color, and the phrases are short, in neutral Spanish.

2. The research: what a child needs to learn to count

Before writing code, it pays to understand what we're teaching. You don't need to be a specialist; a few concepts that early math education has used for decades are enough.

Note: this section summarizes general concepts to explain the design decisions. It is not a clinical guide. If you work with a child with specific needs, the word of their therapist and their family comes before any app.

Counting is not reciting

A child can say "one, two, three, four" from memory and still not know how to count. In 1978, psychologists Rochel Gelman and C. R. Gallistel described the principles behind real counting. Three of them guide this game:

Principle	What it means	How the game applies it
One-to-one correspondence	Each object is counted exactly once.	Each tapped cap shows its number and, if tapped again, repeats the same number.
Stable order	Numbers are always said in the same order.	The voice says "uno, dos, tres…" with each tap.
Cardinality	The last number said is how many there are.	When the help ends, the voice says "Hay cuatro." ("There are four.") and the correct answer starts pulsing.

From concrete to abstract

A widely used approach to teaching math is concrete → pictorial → abstract: first real objects, then drawings of those objects, and only at the end the symbols (2 + 1 = 3). The game has all three on the same screen:

Concrete: the real caps on the table ("Tapitas reales", real caps mode).
Pictorial: the drawn caps and the pips on the dice.
Abstract: the phrase "2 más 1 es igual a…" and the numbers on the answers.

Seeing quantities without counting

Adults see three dots and know there are three without counting them. That ability is called subitizing, and it works with small quantities. That's why:

The dice are drawn with their usual pips, not with numbers.
Under each answer there are as many little dots as its value.
The caps are arranged in rows of 5, like an egg carton: "one full row and two more" is easier to see than a messy pile.

Predictability and transitions

For many children, and especially for many autistic children, the unexpected is hard: the abrupt end of an activity, a loud sound, a change of colors. Several rules come from that:

Visual anchor: each operation has its fixed color (Count blue, Add orange…) and the mascot is always the same red cap.
Announce the end: two rounds before finishing, the voice says "Dos más y guardamos" ("Two more and we put them away"), and on the last one, "La última y guardamos" ("The last one and we put them away").
Closing: the final screen says "Ahora guardamos las tapitas juntos" ("Now we put the caps away together") and the buttons appear after 4 seconds. That way the ending doesn't turn into "one more, one more".

Attention and mistakes

With ADHD, every stimulus competes for attention. That's why the game has few animations, no distracting prizes, and a mistake is not punished: a soft, low tone plays, the app counts out loud with the child, and the correct answer pulses. The mistake becomes a chance to count together.

The adult is part of the game

The game is designed to be played with an adult nearby. On screen there is a "Para el adulto" (For the adult) section with tips ("Count first, slowly…", "If they pick wrong, don't say «no»…") and a mode where the screen only shows the dice and tells the adult what to take out of the box.

3. Technical decisions: why no framework

The game has 3 screens and at most about 60 caps on screen. For that you don't need React, Vue or a bundler. Using "plain" HTML, CSS and JavaScript has real advantages:

What you publish is exactly the files you wrote. There is no build step that can break.
Anyone who is just starting out can read the code from top to bottom.
Modern browsers already ship everything we need: modules (import/export), voice (Web Speech API), sound (Web Audio API) and storage (localStorage).

The architecture in one picture

   child's click
        │
        ▼
   main.js ── finds the button's data-action ──▶ game.js (action)
                                                    │
                                     changes `state` and calls notify()
                                                    │
                                                    ▼
                                    render.js draws the screen

Each file has a single responsibility:

File	What it does	What it does NOT do
`rules.js`	Takes settings and returns a round.	Doesn't touch the DOM, no sound.
`game.js`	Holds the state and has the actions.	Doesn't build HTML.
`render.js`	Reads the state and draws.	Doesn't change the state.
`main.js`	Listens for clicks and calls the actions.	Has no game logic.

The most important rule: information flows in one direction only. If something looks wrong, the problem is in render.js. If the game does something it shouldn't, it's in game.js or rules.js. It's the same idea React or Redux use, but without the library.

Step 0: folders and a local server

Create this structure:

matematicas-con-dados/
├── index.html
├── css/
│   └── styles.css
├── js/
│   ├── audio.js      voice and sounds
│   ├── config.js     fixed data: colors, timings
│   ├── game.js       state and actions
│   ├── main.js       entry point
│   ├── render.js     draws the screen
│   ├── rules.js      rules: builds each round
│   └── spanish.js    numbers as words
├── tests/
│   └── rules.test.js
└── package.json

In package.json we only need to tell Node that we use modules:

{ "name": "matematicas-con-dados", "type": "module", "private": true }

Why double-clicking the file isn't enough

We're going to use JavaScript modules (<script type="module">). For security reasons, browsers don't load modules from file://. You need a local server. Any of these works:

python3 -m http.server 3000      # if you have Python

or the Live Server extension for VS Code. Then open http://localhost:3000.

The real project has a small Node server (scripts/serve.js) that also applies the same security headers as the published site. You don't need it for this tutorial.

Step 1: the HTML for the three screens

The game has three screens: home, game and end. All three live in the same HTML and are shown or hidden with the hidden attribute. The zones that change (tiles, dice, table, answers) start empty: JavaScript fills them in.

index.html:

<!doctype html>
<html lang="es">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Matemáticas con Dados</title>
    <link rel="stylesheet" href="css/styles.css" />
    <script type="module" src="js/main.js"></script>
  </head>
  <body>
    <main class="app">
      <!-- HOME -->
      <section id="screen-home" class="screen">
        <h1>Matemáticas con Dados</h1>
        <div id="operation-tiles" class="tiles"></div>
      </section>

      <!-- GAME -->
      <section id="screen-game" class="screen" hidden>
        <button type="button" id="prompt" class="prompt" data-action="repeat-prompt"></button>
        <div id="dice-row" class="dice-row"></div>
        <div id="table" class="table"></div>
        <div id="answers" class="answers"></div>
      </section>

      <!-- END -->
      <section id="screen-end" class="screen" hidden>
        <h2>Terminamos</h2>
        <p>Ahora guardamos las tapitas juntos.</p>
        <div id="end-buttons" class="end-buttons" hidden>
          <button type="button" data-action="go-home">Inicio</button>
          <button type="button" data-action="play-again">Otra vez</button>
        </div>
      </section>
    </main>
  </body>
</html>

Three details:

lang="es" makes screen readers read the page in Spanish.
type="module" lets us use import/export and runs the script once the HTML has loaded. No need to wait for DOMContentLoaded.
No button has an onclick. They carry data-action="..." and, in step 7, a single listener handles all of them.

Step 2: configuration

Everything that is "fixed data" goes in a single file. If tomorrow you want to change a color or a timing, you know where to look.

js/config.js:

/**
 * CONFIGURATION: all of the game's fixed data.
 * If you want to change a color or a timing, this is the file.
 */

/** Each operation ALWAYS has the same color: it is the child's visual anchor. */
export const OPERATIONS = {
  contar: { name: 'Contar', symbol: '', color: '#4f8ef7' },
  sumar: { name: 'Sumar', symbol: '+', color: '#ff7a4d' },
};

/** Cap colors, and each die's fixed color (die 1 blue, die 2 green...). */
export const CAP_COLORS = { blue: '#1d4ed8', green: '#15803d', red: '#b91c1c', orange: '#c2410c' };
export const DICE_COLORS = ['blue', 'green', 'red', 'orange'];

/** Timings, in milliseconds. */
export const TIMING = {
  nextRoundDelay: 2800, // after a correct answer
  demoStepDelay: 700, // per cap while the app helps
  endButtonsDelay: 4000, // the end buttons appear after this
};

export function defaultSettings() {
  return {
    operation: 'sumar',
    dice: 2, // how many dice
    faces: 3, // die faces: 1 to 3
    rounds: 5, // rounds per session
  };
}

Why is defaultSettings() a function and not a constant? Because every time you call it, it returns a new object. If it were a shared constant, changing the settings in one place would change them everywhere.

And a helper so the voice says numbers as words, js/spanish.js:

// prettier-ignore
const NUMBER_WORDS = [
  'cero', 'uno', 'dos', 'tres', 'cuatro', 'cinco', 'seis',
  'siete', 'ocho', 'nueve', 'diez', 'once', 'doce',
];

/** 3 → "tres". From 13 on it returns the digits, which speech engines read well. */
export function numberWord(n) {
  return n >= 0 && n < NUMBER_WORDS.length ? NUMBER_WORDS[n] : String(n);
}

Step 3: the game rules (pure logic)

This is the heart of the game and the most important file in the tutorial. Its job: take the settings and return a round. For example, if Add rolls a 2 and a 1, createRound() returns this object (you don't write it yourself; the code below builds it):

{
  operation: 'sumar',
  values: [2, 1],                         // what each die rolled
  groups: [['blue', 'blue'], ['green']],  // the caps, grouped, with their color
  answer: 3,
  prompt: '2 más 1 es igual a…',          // what is shown on screen
  speech: 'dos más uno es igual a…',      // what the voice says
  key: '2,1',                             // identifies the roll, so it isn't repeated
}

Notice that the round knows nothing about buttons or screens. It's just data. That's what we call "pure logic": a function that takes data and returns data, without touching the DOM, without making sound and without saving anything.

js/rules.js:

/**
 * GAME RULES: pure logic.
 * Takes settings, returns a round. Doesn't touch the DOM, doesn't make sound, doesn't save.
 * That's why it can be tested in Node, without a browser.
 */

import { DICE_COLORS } from './config.js';
import { numberWord } from './spanish.js';

/** Random integer between min and max, both included. */
export function randomInt(min, max, random = Math.random) {
  return min + Math.floor(random() * (max - min + 1));
}

const sum = (numbers) => numbers.reduce((a, b) => a + b, 0);

/** "2 más 1 es igual a…": digits on screen (String), words in the voice (numberWord). */
function operationPhrase(numbers, word, say) {
  return `${numbers.map(say).join(` ${word} `)} es igual a…`;
}

function rollDice(settings, random) {
  return Array.from({ length: settings.dice }, () => randomInt(1, settings.faces, random));
}

function buildContar(settings, random) {
  const values = rollDice(settings, random);
  const answer = sum(values);
  return {
    values,
    // A single pile, in the first die's color: no groups to join, just counting.
    groups: [Array(answer).fill(DICE_COLORS[0])],
    answer,
    prompt: '¿Cuántas hay?',
    speech: '¿Cuántas hay?',
  };
}

function buildSumar(settings, random) {
  const values = rollDice(settings, random);
  return {
    values,
    // One group per die, in that die's color.
    groups: values.map((value, i) => Array(value).fill(DICE_COLORS[i])),
    answer: sum(values),
    prompt: operationPhrase(values, 'más', String),
    speech: operationPhrase(values, 'más', numberWord),
  };
}

const BUILDERS = { contar: buildContar, sumar: buildSumar };

/**
 * Creates the next round, without repeating the previous roll.
 * @param {{ operation: string, dice: number, faces: number }} settings
 * @param {{ previousKey?: string, random?: () => number }} [options]
 */
export function createRound(settings, { previousKey = '', random = Math.random } = {}) {
  let round;
  for (let attempt = 0; attempt < 50; attempt++) {
    round = { operation: settings.operation, ...BUILDERS[settings.operation](settings, random) };
    round.key = round.values.join(',');
    if (round.key !== previousKey) break;
  }
  return round;
}

/** Three different answers, smallest to largest, including the correct one. */
export function makeAnswerOptions(answer, random = Math.random) {
  const nearby = [answer - 2, answer - 1, answer + 1, answer + 2].filter((n) => n >= 0);
  // Fisher-Yates shuffle
  for (let i = nearby.length - 1; i > 0; i--) {
    const j = Math.floor(random() * (i + 1));
    [nearby[i], nearby[j]] = [nearby[j], nearby[i]];
  }
  return [answer, nearby[0], nearby[1]].sort((a, b) => a - b);
}

/** "Hay tres." ("There are three.") */
export function resultPhrase(answer) {
  return answer === 1 ? 'Hay una.' : `Hay ${numberWord(answer)}.`;
}

Four ideas to take away from this file:

One function per operation, and an object that groups them (BUILDERS). To add Subtract you don't touch createRound: you write buildRestar and add it to BUILDERS.
Randomness can be swapped out. Every function takes random as a parameter, with Math.random as the default. In the tests we pass a predictable generator, so a test that fails always fails the same way.
Nearby answers. The wrong options are 1 or 2 away from the correct one. If one were 3 and another 50, the child would guess without counting.
Don't repeat the previous roll. If "2 plus 1" comes up twice in a row, it looks to the child like nothing happened. key identifies the roll and createRound rolls again if it repeats.

The phrase "es igual a…" ("equals…"). At first the game said "Juntamos. ¿Cuántas hay?" ("We join them. How many are there?"). One day, watching Numberblocks, her favorite show, with my daughter, I realized it was better to say the operation the way they say it there: "2 más 1 es igual a…" ("2 plus 1 equals…"). That way, from the very beginning, she hears the same language she already knows from the show and will use at school. Notice that the voice says "uno" and not "una" (the feminine form, as in "una tapita"): we're talking about numbers, not caps.

Step 4: test the rules before there is a screen

Since rules.js is pure logic, we can test it in the terminal before drawing a single button. Node ships with its own test runner (node:test), so there's nothing to install.

tests/rules.test.js:

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { createRound, makeAnswerOptions } from '../js/rules.js';

/** Repeatable random numbers: if a test fails, it always fails the same way. */
function seededRandom(seed = 42) {
  let value = seed;
  return () => {
    value = (value * 1664525 + 1013904223) % 4294967296;
    return value / 4294967296;
  };
}

for (const operation of ['contar', 'sumar']) {
  test(`${operation}: 500 rondas que cumplen las reglas`, () => {
    const settings = { operation, dice: 2, faces: 3 };
    const random = seededRandom();
    let previousKey = '';

    for (let i = 0; i < 500; i++) {
      const round = createRound(settings, { previousKey, random });
      const caps = round.groups.flat().length;

      assert.ok(
        round.values.every((v) => v >= 1 && v <= 3),
        'cada dado va de 1 a 3',
      );
      assert.equal(caps, round.answer, 'hay tantas tapitas como la respuesta');
      assert.notEqual(round.key, previousKey, 'no repite la tirada anterior');

      const options = makeAnswerOptions(round.answer, random);
      assert.equal(new Set(options).size, 3, 'tres respuestas distintas');
      assert.ok(options.includes(round.answer), 'incluye la correcta');
      assert.ok(
        options.every((n) => n >= 0),
        'ninguna negativa',
      );
      previousKey = round.key;
    }
  });
}

test('Sumar se dice como se lee', () => {
  const round = createRound({ operation: 'sumar', dice: 2, faces: 3 }, { random: () => 0.5 });
  assert.equal(round.prompt, '2 más 2 es igual a…');
  assert.equal(round.speech, 'dos más dos es igual a…');
});

The test names and messages are in Spanish, like the repository. In order: "500 rounds that follow the rules", "each die goes from 1 to 3", "as many caps as the answer", "doesn't repeat the previous roll", "three different answers", "includes the correct one", "none negative", and "Add is said the way it's read".

Run them:

node --test

✔ contar: 500 rondas que cumplen las reglas
✔ sumar: 500 rondas que cumplen las reglas
✔ Sumar se dice como se lee
ℹ pass 3
ℹ fail 0

Look at what they test: not "that the function returns something", but the rules that matter for the child. Never a negative answer, always three different options, never the same roll twice. And not one round: 500. Randomness hides bugs that show up once every hundred rounds.

How does seededRandom work? It's a linear congruential generator: each number comes from the previous one with a multiplication and an addition. It looks random, but with the same seed (42) it always produces the same sequence.

Step 5: state and actions

Now we need a place that remembers what is happening: which screen we're on, which round is being played, which caps have already been counted. That place is state, a plain object.

The golden rule: nobody but game.js changes state. The UI calls an action (tapCap, chooseAnswer…), the action changes the state and calls notify(), and notify() tells whoever is listening (in step 7, the drawing function).

js/game.js, first part:

/**
 * STATE AND ACTIONS.
 * The UI never changes `state` directly: it calls an action, the action
 * changes the state and announces it with notify(), and the screen is redrawn.
 *
 *     click → action → state → notify() → render()
 */

import { defaultSettings, TIMING } from './config.js';
import { createRound, makeAnswerOptions, resultPhrase } from './rules.js';
import { numberWord } from './spanish.js';
import { say, stopVoice, playCount, playSuccess, playMiss } from './audio.js';

export const state = {
  settings: defaultSettings(),
  screen: 'home', // 'home' | 'game' | 'end'
  phase: 'play', // 'play' | 'helping' | 'solved'
  roundNumber: 0, // rounds finished in this session
  round: null,
  answerOptions: [],
  countedCaps: new Map(), // cap id → number it was given
  highlightedCap: null, // the cap that grows during the help
  pulsingAnswer: null, // the correct answer that pulses after the help
  helpShown: false,
  endButtonsVisible: false,
};

// --- Announcing changes -----------------------------------------------------

const listeners = [];

export function onChange(listener) {
  listeners.push(listener);
}

function notify() {
  listeners.forEach((listener) => listener(state));
}

phase matters: it says what the child can do right now.

`phase`	What it means	What it accepts
`play`	the child can tap	caps, answers
`helping`	the app is counting	nothing
`solved`	correct; the next round follows in a moment	nothing

The problem with tasks that wait

Some actions take time: the help counts one cap every 700 ms; after a correct answer there's a 2.8 s wait before the next round. What happens if the child goes back home in the middle of the help? The task keeps running and the voice keeps counting on the home screen.

The solution is simple: each round has a number. Each task notes the number it started with and, after every wait, checks whether it's still the same. If it isn't, it stops.

Add it to js/game.js, below notify():

// --- Waiting tasks that cancel themselves -----------------------------------
// Each round has a number. A task stores the number it started with and,
// if it changed while waiting (for example, the child went back home), it stops.

let roundId = 0;
const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const isStale = (id) => id !== roundId;

goHome() and every new round increment roundId, and with that, all old tasks cancel themselves.

Navigation and rounds

Continue in js/game.js, below the previous block:

// --- Navigation ---------------------------------------------------------------

export function startOperation(operation) {
  state.settings.operation = operation;
  startSession();
}

export function startSession() {
  state.roundNumber = 0;
  state.screen = 'game';
  startRound();
}

export function goHome() {
  roundId++;
  stopVoice();
  state.screen = 'home';
  notify();
}

export function repeatPrompt() {
  if (state.round) say(state.round.speech);
}

// --- Rounds -------------------------------------------------------------------

function startRound() {
  roundId++;
  const round = createRound(state.settings, { previousKey: state.round?.key });
  Object.assign(state, {
    round,
    answerOptions: makeAnswerOptions(round.answer),
    phase: 'play',
    countedCaps: new Map(),
    highlightedCap: null,
    pulsingAnswer: null,
    helpShown: false,
  });
  notify();

  // Announce the end ahead of time: the closing never comes as a surprise.
  const roundsLeft = state.settings.rounds - state.roundNumber;
  let intro = '';
  if (roundsLeft === 2) intro = 'Dos más y guardamos. ';
  else if (roundsLeft === 1) intro = 'La última y guardamos. ';
  say(intro + round.speech);
}

function finishSession() {
  roundId++;
  const id = roundId;
  state.screen = 'end';
  state.endButtonsVisible = false;
  notify();
  say('Terminamos. Guardamos las tapitas.');
  // The buttons appear later, so the ending feels like an ending.
  setTimeout(() => {
    if (isStale(id)) return;
    state.endButtonsVisible = true;
    notify();
  }, TIMING.endButtonsDelay);
}

Here are two of the research rules turned into code: the "Dos más y guardamos" warning and the buttons that appear after 4 seconds.

The child's taps, and help without "no"

And at the end of js/game.js:

// --- The child's taps ---------------------------------------------------------

/** Tapping a cap counts it: one, two, three... */
export function tapCap(capId) {
  if (state.phase !== 'play') return;
  const counted = state.countedCaps.get(capId);
  if (counted !== undefined) {
    say(numberWord(counted)); // already counted: just repeat its number
    return;
  }
  const number = state.countedCaps.size + 1;
  state.countedCaps.set(capId, number);
  playCount(number);
  say(numberWord(number));
  notify();
}

export function chooseAnswer(value) {
  const { round } = state;
  if (!round || state.phase !== 'play') return;

  if (value === round.answer) {
    celebrate(round);
    return;
  }
  // No "no" and no punishment: a soft tone, and the app helps count.
  playMiss();
  if (!state.helpShown) {
    state.helpShown = true;
    showHelp();
  }
}

function celebrate(round) {
  const id = roundId;
  state.phase = 'solved';
  state.roundNumber++;
  playSuccess();
  notify();
  say(`Sí. ${resultPhrase(round.answer)}`);

  setTimeout(() => {
    if (isStale(id)) return;
    if (state.roundNumber >= state.settings.rounds) finishSession();
    else startRound();
  }, TIMING.nextRoundDelay);
}

/** The app counts out loud, cap by cap, and the correct answer starts pulsing. */
async function showHelp() {
  const id = roundId;
  const { round } = state;
  state.phase = 'helping';
  state.countedCaps.clear();
  notify();

  const total = round.groups.flat().length;
  for (let i = 0; i < total; i++) {
    const capId = `cap-${i}`;
    state.countedCaps.set(capId, i + 1);
    state.highlightedCap = capId;
    notify();
    say(numberWord(i + 1));
    await wait(TIMING.demoStepDelay);
    if (isStale(id)) return;
  }

  state.highlightedCap = null;
  notify();
  await say(resultPhrase(round.answer));
  if (isStale(id)) return;
  state.pulsingAnswer = round.answer;
  state.phase = 'play';
  notify();
}

Look at tapCap: the countedCaps Map is one-to-one correspondence in code. A cap that has already been counted doesn't add one more: it repeats its number.

And showHelp is the "never say no" rule: instead of marking the mistake, the app counts again from zero, cap by cap, says "Hay cuatro." (cardinality) and leaves the correct answer pulsing. The child is the one who taps it.

Step 6: drawing the screen

render.js takes the state and builds HTML as text. Every time something changes, the whole zone is redrawn with innerHTML. It's the simplest model there is and, for a few dozen elements, it's more than fast enough.

The die: a 3×3 grid

A die is a grid of 9 cells; some of them have a pip. All you need is a table that says which cells get painted for each number:

 0 │ 1 │ 2        5:   ● │   │ ●
───┼───┼───           ───┼───┼───
 3 │ 4 │ 5               │ ● │
───┼───┼───           ───┼───┼───
 6 │ 7 │ 8             ● │   │ ●     → [0, 2, 4, 6, 8]

js/render.js:

/**
 * DRAWING: reads the state and builds HTML. Never changes the state.
 */

import { OPERATIONS, CAP_COLORS, DICE_COLORS } from './config.js';

const $ = (id) => document.getElementById(id);

/** Pip positions on the die's 3×3 grid (0 = top left). */
const PIP_POSITIONS = {
  1: [4],
  2: [0, 8],
  3: [0, 4, 8],
  4: [0, 2, 6, 8],
  5: [0, 2, 4, 6, 8],
  6: [0, 2, 3, 5, 6, 8],
};

function dieHTML(value, colorId) {
  const cells = Array.from({ length: 9 }, (_, i) =>
    PIP_POSITIONS[value].includes(i) ? '<span class="die__pip"></span>' : '<span></span>',
  ).join('');
  return `<div class="die" style="--edge:${CAP_COLORS[colorId]}" role="img" aria-label="Dado: ${value}">${cells}</div>`;
}

function capHTML(id, colorId, state) {
  const number = state.countedCaps.get(id);
  const highlighted = state.highlightedCap === id ? 'cap--highlighted' : '';
  return `<button type="button" class="cap ${highlighted}" style="--cap-color:${CAP_COLORS[colorId]}"
    data-action="tap-cap" data-cap="${id}" aria-label="Tapita${number ? `, ${number}` : ''}">${number ?? ''}</button>`;
}

Each cap is a real <button>: that way it works with a finger, a mouse and a keyboard. The die has role="img" and aria-label="Dado: 5" ("Die: 5") so a screen reader announces the number.

The color goes in a CSS variable (--cap-color) and not in one class per color. That way the CSS has a single .cap rule and the color comes from config.js.

The screens

At the end of js/render.js, below capHTML:

function renderHome() {
  $('operation-tiles').innerHTML = Object.entries(OPERATIONS)
    .map(
      ([id, operation]) => `
      <button type="button" class="tile" style="--tile-color:${operation.color}"
        data-action="start-operation" data-operation="${id}">${operation.name}</button>`,
    )
    .join('');
}

function renderGame(state) {
  const { round } = state;
  const operation = OPERATIONS[round.operation];

  $('prompt').textContent = `🔊 ${round.prompt}`;

  const result = state.phase === 'solved' ? round.answer : '?';
  $('dice-row').innerHTML =
    round.values.map((value, i) => dieHTML(value, DICE_COLORS[i])).join(`<span>${operation.symbol}</span>`) +
    `<span>=</span><span>${result}</span>`;

  // Each cap has a unique id (cap-0, cap-1...) so we know which one was counted.
  let capIndex = 0;
  $('table').innerHTML = round.groups
    .map((group) => {
      const caps = group.map((colorId) => capHTML(`cap-${capIndex++}`, colorId, state)).join('');
      return `<div class="cap-group" style="--columns:${Math.min(5, group.length)}">${caps}</div>`;
    })
    .join('');

  $('answers').innerHTML = state.answerOptions
    .map((value) => {
      const pulsing = state.pulsingAnswer === value ? 'is-pulsing' : '';
      return `<button type="button" class="answer ${pulsing}" data-action="choose-answer" data-value="${value}">${value}</button>`;
    })
    .join('');
}

export function render(state) {
  $('screen-home').hidden = state.screen !== 'home';
  $('screen-game').hidden = state.screen !== 'game';
  $('screen-end').hidden = state.screen !== 'end';

  // The background takes the operation's color.
  const color = state.screen === 'home' ? '#ffa23a' : OPERATIONS[state.settings.operation].color;
  document.documentElement.style.setProperty('--theme', color);

  if (state.screen === 'home') renderHome();
  if (state.screen === 'game') renderGame(state);
  if (state.screen === 'end') $('end-buttons').hidden = !state.endButtonsVisible;
}

--columns: Math.min(5, group.length) is what arranges the caps in rows of 5, like an egg carton.

Careful with innerHTML. It's safe here because everything interpolated comes from config.js or is a computed number: never text a person typed. If you ever display user text, escape it first (the real project has an escapeHTML function for that).

Step 7: wiring up the clicks

We could add an addEventListener to each button, but the buttons are created and destroyed on every render. Instead we use event delegation: a single listener on the whole document that, on every click, looks for the nearest data-action.

js/main.js:

/**
 * ENTRY POINT: connects the state to the drawing and turns each click into an action.
 */

import * as game from './game.js';
import { render } from './render.js';
import { unlockAudio } from './audio.js';

/** What each data-action does. For a new button: give it a data-action and add a line here. */
const ACTIONS = {
  'start-operation': (el) => {
    unlockAudio(); // first tap: the browser now allows sound
    game.startOperation(el.dataset.operation);
  },
  'repeat-prompt': () => game.repeatPrompt(),
  'tap-cap': (el) => game.tapCap(el.dataset.cap),
  'choose-answer': (el) => game.chooseAnswer(Number(el.dataset.value)),
  'go-home': () => game.goHome(),
  'play-again': () => game.startSession(),
};

// A single listener for the whole page (event delegation).
// closest() finds the button even when the tap lands on the number inside it,
// and it works with buttons created after the page loaded.
document.addEventListener('click', (event) => {
  const element = event.target.closest('[data-action]');
  if (element) ACTIONS[element.dataset.action]?.(element);
});

game.onChange(render);
render(game.state);

game.onChange(render) is the piece that closes the loop: every time an action calls notify(), render(state) runs.

Step 8: voice and sounds without audio files

The browser ships two APIs that save us from recording audio:

Web Speech API (speechSynthesis): turns text into speech.
Web Audio API (AudioContext): generates tones with an oscillator.

js/audio.js:

/**
 * VOICE (Web Speech API) AND SOUNDS (Web Audio API). No audio files.
 */

const hasSpeech = 'speechSynthesis' in window;
let spanishVoice = null;

/** Prefers a Spanish voice that runs on the device itself (privacy). */
function pickSpanishVoice() {
  const voices = speechSynthesis.getVoices().filter((voice) => voice.lang.toLowerCase().startsWith('es'));
  spanishVoice = voices.find((voice) => voice.localService) ?? voices[0] ?? null;
}

if (hasSpeech) {
  pickSpanishVoice();
  // The voice list may arrive empty at first and fill in later.
  speechSynthesis.addEventListener('voiceschanged', pickSpanishVoice);
}

/**
 * Speaks a phrase and interrupts the previous one: if the child taps fast, they
 * hear the latest number, not a queue of numbers. Resolves when speech ends.
 */
export function say(text) {
  return new Promise((resolve) => {
    if (!hasSpeech) return resolve();
    speechSynthesis.cancel();
    const utterance = new SpeechSynthesisUtterance(text);
    utterance.lang = spanishVoice?.lang ?? 'es-MX';
    if (spanishVoice) utterance.voice = spanishVoice;
    utterance.rate = 0.9; // a bit slower than normal
    utterance.onend = resolve;
    utterance.onerror = resolve;
    speechSynthesis.speak(utterance);
    setTimeout(resolve, 5000); // in case the browser never reports that it finished
  });
}

export function stopVoice() {
  if (hasSpeech) speechSynthesis.cancel();
}

let audioContext = null;

/** Browsers don't allow sound until the person touches the screen. */
export function unlockAudio() {
  audioContext ??= new AudioContext();
  if (audioContext.state === 'suspended') audioContext.resume().catch(() => {});
  if (hasSpeech) pickSpanishVoice();
}

/** A short tone that fades out on its own. */
export function playTone(frequency, duration = 0.1, volume = 0.12) {
  if (!audioContext) return;
  const now = audioContext.currentTime;
  const oscillator = audioContext.createOscillator();
  const gain = audioContext.createGain();
  oscillator.frequency.value = frequency;
  gain.gain.setValueAtTime(volume, now);
  gain.gain.exponentialRampToValueAtTime(0.001, now + duration);
  oscillator.connect(gain).connect(audioContext.destination);
  oscillator.start(now);
  oscillator.stop(now + duration);
}

/** Three soft notes for a correct answer (C, E, G). */
export function playSuccess() {
  [523, 659, 784].forEach((note, i) => setTimeout(() => playTone(note, 0.18), i * 110));
}

/** A short, low tone for a wrong answer. Soft: it is not a punishment. */
export function playMiss() {
  playTone(240, 0.14, 0.08);
}

/** The pitch rises with each cap: the child "hears" the number grow. */
export function playCount(n) {
  playTone(330 + Math.min(n, 20) * 20, 0.08);
}

Three details that took a while to learn:

Audio is blocked until the first tap. Browsers, and Safari on iPhone above all, won't play sound on a page the user hasn't touched. That's why unlockAudio() is called when an operation is chosen.
say returns a promise. That way the help can wait for a phrase to finish with await say(...). The 5 s setTimeout is a safety net: some browsers occasionally never report that they finished.
Privacy: some voices (for example, Chrome's "Google…" voices) send the text to a server to turn it into audio. Voices with localService === true run on the device itself. That's why they're preferred.

And a design detail: playCount raises the pitch with each cap. Without a word, the child hears the number grow.

Want it to speak English?

The game was built in Spanish, but the language lives in very few places:

spanish.js: replace NUMBER_WORDS with 'zero', 'one', 'two'….
rules.js: operationPhrase builds es igual a…; change it to equals…, change 'más' to 'plus', and translate '¿Cuántas hay?' and resultPhrase.
game.js: the closing phrases ('Dos más y guardamos. ', 'Terminamos…') and the Sí. in celebrate.
audio.js: filter voices with startsWith('en') and use 'en-US' as the fallback.
index.html: lang="en" and the texts on the end screen.

The tests in step 4 will tell you if you missed one: Sumar se dice como se lee checks the exact phrase.

Step 9: styles

The full CSS is in the appendix, at the end of the article. These are the parts worth understanding.

The die, with CSS Grid:

/* The die: a 3×3 grid where some cells have a pip. */
.die {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 3px;
  width: 56px;
  height: 56px;
  padding: 6px;
  box-sizing: border-box;
  border: 3px solid var(--edge);
  border-radius: 12px;
  background: #fff;
}

.die__pip {
  border-radius: 50%;
  background: var(--edge);
}

The caps in rows of 5, using the --columns variable that render.js sets:

/* A group of caps in rows of up to 5, like an egg carton. */
.cap-group {
  display: grid;
  grid-template-columns: repeat(var(--columns), auto);
  gap: 8px;
}

.cap {
  width: var(--cap-size);
  height: var(--cap-size);
  border: 3px dashed rgb(255 255 255 / 45%);
  border-radius: 50%;
  background: var(--cap-color);
  color: #fff;
  font-size: 20px;
  font-weight: 700;
}

The pulsing answer, and the rule that turns it off when the system asks for reduced motion:

.answer.is-pulsing {
  animation: pulse 1s ease-in-out infinite;
}

@keyframes pulse {
  50% {
    transform: scale(1.12);
  }
}

/* If the system asks to "reduce motion", nothing moves. */
@media (prefers-reduced-motion: reduce) {
  * {
    animation: none !important;
    transition: none !important;
  }
}

prefers-reduced-motion reads an accessibility option from the operating system (for example, "Reduce Motion" on iPhone and Mac). Respecting it costs a few lines.

Checkpoint

Start the server, open http://localhost:3000 and play. You should be able to:

Choose Contar or Sumar, and see the background change to the operation's color.
Hear "2 más 1 es igual a…".
Tap the caps and hear "uno, dos, tres" with a rising tone.
Choose a wrong answer and watch the app count on its own while the correct answer starts pulsing.
Hear "Dos más y guardamos" in the fourth round of five.
Reach the end and see the buttons only after 4 seconds.

Exercise: add Subtract

With what you already have, you can add an operation without touching createRound:

In config.js, add restar: { name: 'Restar', symbol: '−', color: '#ff5d8f' } to OPERATIONS (restar = subtract).
In rules.js, write buildRestar(settings, random): the first die says how many caps to put down; the second, how many to take away. Make sure the second isn't larger than the first (no negative answers!). For the phrase, use operationPhrase(values, 'menos', String) (menos = minus).
Register it in BUILDERS and add 'restar' to the test's list of operations.

Run node --test. If the "ninguna negativa" (none negative) test fails, you know where to look.

From prototype to real project

The minimal version works, but the real project had to solve quite a bit more. This section shows those problems with excerpts from the real code and tells how they were found. Several only showed up in an audit, when the game already "worked".

1. "Never ask for more caps than there are"

In "Tapitas reales" (real caps) mode, the screen tells the adult what to take out of the box: "Saca 3 azules y 2 verdes" ("Take out 3 blue and 2 green"). The adult sets up how many caps of each color they have. The rule: the app can never ask for more than there are.

The first version tried a few rolls and, if none fit in the box, accepted any of them. With a box holding a single black cap and die 1 colored black, Subtract asked for caps that didn't exist in 200 out of 200 rounds. The fix: an explicit order of preference, and a last option that always follows the rule.

for (let attempt = 0; attempt < 120; attempt++) {
  const round = tryBuild();
  if (round && round.key !== previousKey && fits(round)) return round;
}
// Small box, or a die color with few caps: repeating the previous roll
// is better than asking for caps that aren't there.
for (let attempt = 0; attempt < 200; attempt++) {
  const round = tryBuild();
  if (round && fits(round)) return round;
}
return countingFallback(settings, random);

First, a new round that fits. If none shows up, one that fits even if it repeats the previous one. And if that fails too, countingFallback builds a Count round with the color that has the most caps. The lesson: when a rule is sacred, the code has to guarantee it on every path, including the last one. And the test has to use small boxes on purpose.

2. Don't trust `localStorage`

Settings are saved in the browser so the adult doesn't have to set up the box every time. But localStorage is text that anyone can edit from the browser's dev tools. The first version validated the operation like this:

raw.operation in OPERATIONS;

And 'toString' in OPERATIONS is true: the in operator also looks at what the object inherits. A setting with "operation": "toString" broke the game. The real version uses Object.hasOwn and validates each field against a closed list:

export function normalizeSettings(raw) {
  const settings = defaultSettings();
  if (!isPlainObject(raw)) return settings;

  if (isOperationId(raw.operation)) settings.operation = raw.operation;
  if (Number.isInteger(raw.dice)) settings.dice = /** @type {number} */ (raw.dice);
  if (raw.preferredLevel === 2 || raw.preferredLevel === 3 || raw.preferredLevel === 4) {
    settings.preferredLevel = raw.preferredLevel;
  }
  if (raw.faces === 3 || raw.faces === 6) settings.faces = raw.faces;
  if (raw.rounds === 3 || raw.rounds === 5 || raw.rounds === 8) settings.rounds = raw.rounds;
  if (typeof raw.voice === 'boolean') settings.voice = raw.voice;
  if (typeof raw.sound === 'boolean') settings.sound = raw.sound;
  if (typeof raw.realCaps === 'boolean') settings.realCaps = raw.realCaps;

The pattern: start from the defaults and copy only what passes validation. Never the other way around.

3. The keyboard lost its place on every tap

innerHTML deletes the buttons and creates new ones. If keyboard focus was on one of them, the browser sends it to <body>, and a keyboard user has to start from the top after every tap. It happens in the minimal version; try it with Tab.

The real project draws each zone with updateZone(), which leaves a zone alone if it hasn't changed and, if focus was inside, returns it to the "same" button:

export function updateZone(zone, html) {
  if (lastHTML.get(zone) === html) return;
  lastHTML.set(zone, html);

  const active = document.activeElement;
  const hadFocus = active instanceof HTMLElement && active !== zone && zone.contains(active);
  const selector = hadFocus ? identitySelector(active) : '';
  const action = hadFocus ? active.getAttribute('data-action') : null;

  zone.innerHTML = html;
  applyStyleVars(zone);
  if (!hadFocus) return;

  const target =
    (selector && zone.querySelector(selector)) ||
    (action && zone.querySelector(`[data-action="${CSS.escape(action)}"]`)) ||
    zone.querySelector('button, [tabindex="0"], input, select');
  if (target instanceof HTMLElement) target.focus();
}

"The same button" is recognized by its attributes (data-action, data-cap, data-value…), because the element itself is new. It's not a virtual DOM: it compares HTML text and nothing else. But it solves the problem.

Other accessibility improvements in the real project, all small:

aria-disabled instead of disabled on the answers while the app is helping. disabled removes the button from the keyboard order and focus gets lost.
inert on the end buttons while they're hidden: they can't be reached with Tab either.
A single aria-live region that announces the question and the result. Before, the whole table was announced on every tap.
Contrast: text on each operation's color is dark, with at least 4.5:1 contrast, without changing the operation colors (they are the child's anchor).
When the screen changes, focus moves to the title or the question.

4. Security: a strict CSP without losing the colors

A Content Security Policy (CSP) tells the browser what the page is allowed to load. The real project's is very strict: only files from the site itself and no styles written inside the HTML. That includes the style="--cap-color:..." attributes we used in the minimal version.

The fix: the HTML carries the colors in a data attribute, and JavaScript applies them with element.style.setProperty, which the CSP does allow:

export function applyStyleVars(root) {
  for (const element of root.querySelectorAll('[data-vars]')) {
    if (!(element instanceof HTMLElement || element instanceof SVGElement)) continue;
    for (const declaration of (element.dataset.vars ?? '').split(';')) {
      const [name, value] = declaration.split(':').map((part) => part.trim());
      if (name?.startsWith('--') && value) element.style.setProperty(name, value);
    }
  }
}

In the HTML, style="--edge:#1d4ed8" becomes data-vars="--edge:#1d4ed8". The CSS doesn't change. And the function only accepts variables (names that start with --), never any other property.

5. Privacy: nothing leaves the device

It's a game for children, so the goal was that no data leaves the device. Two findings:

The first version loaded the Fredoka font from Google Fonts. That sends the device's IP address to a third party on every visit. Now the font is served from the site itself: a single woff2 file of about 30 KB, with its license (OFL).
Voice selection, as you saw in step 8, prefers local voices.

An automated test checks that no request leaves the site itself. The saved settings contain nothing about the child: no name, no age, no scores.

6. Working offline

A service worker is a script the browser runs separately from the page that can answer its requests. The real project uses the easiest strategy to reason about, "network first": with internet it always downloads the published version (and saves a copy); without internet it uses the copy.

// Every request: network first; if it fails, the saved copy.
self.addEventListener('fetch', (event) => {
  const { request } = event;
  if (request.method !== 'GET' || new URL(request.url).origin !== self.location.origin) return;

  event.respondWith(
    fetch(request)
      .then((response) => {
        if (response.ok) {
          const copy = response.clone();
          caches.open(CACHE_NAME).then((cache) => cache.put(request, copy));
        }
        return response;
      })
      .catch(async () => (await caches.match(request)) ?? (await caches.match('index.html')) ?? Response.error()),
  );
});

With a manifest.webmanifest and its icons, the game can also be installed on the home screen of a phone or tablet and opened full screen.

7. Tools that look after the code

None of these tools ship with the site. They're for development only (devDependencies):

Tool	What for
JSDoc + `tsc --noEmit`	Types written in comments. TypeScript checks them in strict mode without compiling.
ESLint	Catches common mistakes, like unused variables.
Prettier	Uniform formatting: nobody argues about spaces or quotes.
`node:test`	Unit tests for the rules, the state and storage, without a browser.
Playwright	Plays the game for real in a browser, at phone size and at desktop size.

One of my favorite Playwright tests checks the game's most important rule: after a wrong answer, no phrase from the voice contains the word "no".

test('Respuesta equivocada: ayuda completa, sin "no", y la correcta late', async ({ page }) => {
  await page.goto('/');
  await startOperation(page, 'sumar', 2);
  const { answer } = await gameState(page);
  const wrong = page.locator(`[data-action="choose-answer"]:not([data-value="${answer}"])`).first();
  await wrong.click();

  await expect.poll(async () => (await gameState(page)).mood).toBe('think');
  await expect(page.locator('.answer[aria-disabled="true"]')).toHaveCount(3); // while helping
  await expect(page.locator(`.answer.is-pulsing[data-value="${answer}"]`)).toBeVisible({ timeout: 30_000 });
  await expect(page.locator('.cap--counted')).toHaveCount(Number(answer));

  for (const phrase of await spoken(page)) expect(phrase).not.toMatch(/\bno\b/i);
});

(The test name reads: "Wrong answer: full help, no 'no', and the correct one pulses".)

The child's rules are requirements, and requirements get tested. If someone changes a phrase a year from now, the test will tell them.

Publishing it

It's a static site: you publish the folder as it is, with no build.

Hosting	Security headers	What to do
Cloudflare Pages	Yes, from the `_headers` file	Connect the repository. Build command: none. Output directory: `/`.
Netlify	Yes, from the `_headers` file	Connect the repository. Build command: empty. Publish directory: `.`.
GitHub Pages	Doesn't allow custom headers	Publish from the `main` branch. The CSP still applies through a `<meta>` tag in the HTML.

Once published, it opens in any modern browser and, after the first visit, works offline.

What I learned

The user defines the rules; the code guarantees them. "Never say no" or "never ask for more caps than there are" aren't details: they're requirements. Each one has its test.
Simple scales further than it seems. Three screens, one state object and innerHTML were enough for a complete, accessible, tested game.
Pure logic tests itself. Separating rules.js from the DOM made it possible to test thousands of rounds in milliseconds, before there was a screen.
Accessibility is lots of small details. None was hard; all of them would have been missed without testing with a keyboard and a screen reader.
Other people's feedback makes the game better. "Count needs levels too" came from people who used it, and "2 más 1 es igual a…" came from watching Numberblocks with my daughter.

Glossary

Term	What it is
ES module	A `.js` file that uses `import` and `export`. Loaded with `<script type="module">`.
Pure logic	Code that takes data and returns data, with no side effects: doesn't touch the screen, no sound, no saving.
State (`state`)	The object that remembers what's happening in the game.
Event delegation	A single listener on a parent element that handles the clicks of all its children.
*`data-`**	Custom attributes in the HTML (`data-action`, `data-cap`) that JavaScript reads with `element.dataset`.
CSS variable	A named value (`--cap-color`) that CSS uses with `var(--cap-color)`.
CSP	Content Security Policy: rules that tell the browser what the page can load and run.
Service worker	A script the browser runs separately from the page that makes it possible, for example, to work offline.
*`aria-`**	Attributes that describe the page for screen readers.
Subitizing	Recognizing how many objects there are without counting them, for small quantities.
Cardinality	Knowing that the last number said while counting is how many objects there are.

Appendix: the full CSS of the minimal version

css/styles.css:

:root {
  --theme: #ffa23a; /* render.js changes it per operation */
  --cap-size: 48px;
  font-family: system-ui, sans-serif;
}

body {
  margin: 0;
  min-height: 100vh;
  background: linear-gradient(var(--theme), #fff 60%);
}

.app {
  max-width: 600px;
  margin: 0 auto;
  padding: 16px;
  text-align: center;
}

button {
  font: inherit;
  cursor: pointer;
}

.tiles {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
  gap: 12px;
}

.tile {
  padding: 24px 12px;
  border: 0;
  border-radius: 20px;
  background: var(--tile-color);
  font-size: 24px;
  font-weight: 700;
}

.prompt {
  padding: 12px 20px;
  border: 0;
  border-radius: 999px;
  background: #fff;
  font-size: 22px;
}

.dice-row {
  display: flex;
  align-items: center;
  justify-content: center;
  gap: 10px;
  margin: 16px 0;
  font-size: 36px;
  font-weight: 700;
}

/* The die: a 3×3 grid where some cells have a pip. */
.die {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 3px;
  width: 56px;
  height: 56px;
  padding: 6px;
  box-sizing: border-box;
  border: 3px solid var(--edge);
  border-radius: 12px;
  background: #fff;
}

.die__pip {
  border-radius: 50%;
  background: var(--edge);
}

.table {
  display: flex;
  flex-wrap: wrap;
  justify-content: center;
  gap: 16px;
  padding: 16px;
  border-radius: 20px;
  background: #e8b77a;
}

/* A group of caps in rows of up to 5, like an egg carton. */
.cap-group {
  display: grid;
  grid-template-columns: repeat(var(--columns), auto);
  gap: 8px;
}

.cap {
  width: var(--cap-size);
  height: var(--cap-size);
  border: 3px dashed rgb(255 255 255 / 45%);
  border-radius: 50%;
  background: var(--cap-color);
  color: #fff;
  font-size: 20px;
  font-weight: 700;
}

.cap--highlighted {
  transform: scale(1.2);
}

.answers {
  display: flex;
  justify-content: center;
  gap: 12px;
  margin-top: 16px;
}

.answer {
  width: 90px;
  height: 90px;
  border: 0;
  border-radius: 20px;
  background: #fff;
  font-size: 40px;
  font-weight: 700;
}

.answer.is-pulsing {
  animation: pulse 1s ease-in-out infinite;
}

@keyframes pulse {
  50% {
    transform: scale(1.12);
  }
}

/* If the system asks to "reduce motion", nothing moves. */
@media (prefers-reduced-motion: reduce) {
  * {
    animation: none !important;
    transition: none !important;
  }
}

If you build your own version, or use it with a child, I'd love to hear how it went.

# Cómo construí un asistente de recordatorios en Python (y por qué lo subí a GitLab en vez de GitHub)

Enrique Lazo Bello — Sat, 30 May 2026 15:40:06 +0000

Construí pyTask, un asistente de recordatorios y timers desde la terminal con Python, Click, y notificaciones nativas de Windows.
Código fuente aquí.

1. El porque

Una conversación con un amigo. Estábamos comparando plataformas.

GitLab venía pisando fuerte con su CI/CD nativo. Mientras tanto, GitHub acumulaba brechas de seguridad y el ecosistema de Actions, aunque potente, requería más piezas externas: Codecov para cobertura, SonarCloud para calidad, Dependabot para dependencias.

GitLab lo ofrece todo integrado desde el primer git push. Los pipelines, el registro de contenedores, el escaneo de secretos, la cobertura de código, la calidad del código, el registro de dependencias. Sin configurar 20 servicios
externos.

Para un proyecto pequeño como este, la diferencia es enorme.

2. La confirmación obligatoria

Empecé este proyecto porque me cansé de ignorar mis propios recordatorios.

Google Calendar suena, lo cierras, la reunión no existió. Las alarmas del celular: snooze, snooze, snooze. Los timers de cocina: suenan un rato y se apagan aunque nadie haya ido a la cocina.

El problema de fondo es que todos esos sistemas te dejan ignorarlos cómodamente. Necesitaba algo diferente: una alerta que no desaparezca hasta que confirmes que hiciste la tarea. Y que si no confirmas, te siga molestando cada N minutos.

Eso es pyTask. Un recordatorio pasivo-agresivo hecho en Python.

3. Estructura del proyecto

Arrancamos con un pyproject.toml moderno usando Hatchling como build backend.

[project]
name = "pytask"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = [
    "click>=8.0",
    "plyer>=2.0",
]

[project.scripts]
pytask = "pytask.cli:cli"

[project.optional-dependencies]
dev = ["ruff", "mypy", "pytest", "pytest-cov", "bandit", "pre-commit"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Tres cosas clave:

requires-python = ">=3.14" — usamos type hints con sintaxis str | None (PEP 604, disponible desde Python 3.10). 3.14 porque si ya hacemos esto, hagámoslo bien.
hatchling — build backend moderno, rápido, sin configuraciones mágicas que te exploten en producción.
[project.scripts] — define pytask como comando ejecutable directamente desde la terminal.

La estructura de carpetas:

├── pyproject.toml
├── LICENSE
├── .gitlab-ci.yml
├── .pre-commit-config.yaml
├── README.md
├── pytask/
│   ├── __init__.py
│   ├── __main__.py
│   ├── cli.py
│   ├── core.py
│   └── service.py
└── tests/
    ├── __init__.py
    ├── conftest.py
    ├── test_core.py
    ├── test_cli.py
    └── test_service.py

Cada archivo tiene una responsabilidad clara:

Archivo	Responsabilidad
`pytask/core.py`	Modelo `Task`, persistencia JSON, lógica de disparo
`pytask/cli.py`	Interfaz de comandos (Click)
`pytask/service.py`	Loop de servicio, notificaciones, re-alertas
`tests/`	Tests unitarios y de integración

4. CLI con Click: la interfaz de comandos

Usamos Click porque es la biblioteca estándar de facto para CLIs en Python. Mira qué limpio queda:

# pytask/cli.py — comandos principales
import re
from datetime import datetime
import click
from pytask.core import DAY_NAMES, Task, load_tasks, save_tasks, load_config, save_config


@click.group()
def cli():
    """pyTask - recordatorios y timers desde la terminal"""


def _validate_time_flags(time_str, in_minutes):
    """Valida que los flags de tiempo sean consistentes."""
    if in_minutes is not None and in_minutes < 1:
        return "Error: el timer debe ser al menos 1 minuto"
    if time_str and not re.match(r"^(?:[01]\d|2[0-3]):[0-5]\d$", time_str):
        return "Error: formato de hora invalido. Usa HH:MM (ej. 08:30, 14:00)"
    if time_str and in_minutes:
        return "Error: no puedes usar --at y --in juntos"
    if not time_str and not in_minutes:
        return "Error: usa --at HH:MM o --in Nmin"


def _validate_day_flags(days, weekdays, daily):
    """Valida que no haya flags de días contradictorios."""
    if days and weekdays:
        return "Error: no puedes usar --days y --weekdays juntos"
    if days and daily:
        return "Error: no puedes usar --days y --daily juntos"


def _validate_day_names(days):
    """Valida que los nombres de días sean correctos."""
    if not days:
        return
    DAY_NAMES = ["lun", "mar", "mie", "jue", "vie", "sab", "dom"]
    invalid = [d.strip() for d in days.split(",") if d.strip() not in DAY_NAMES]
    if invalid:
        return f"Error: dias invalidos: {', '.join(invalid)}. Usa: lun,mar,mie,jue,vie,sab,dom"


def _resolve_days(days, weekdays, daily):
    """Resuelve los flags de recurrencia a un string canónico."""
    if daily:
        return "daily"
    if weekdays:
        return "weekdays"
    return days


@cli.command()
@click.argument("text")
@click.option("--at", "time_str", help="Hora fija formato HH:MM")
@click.option("--days", help="Dias: lun,mar,mie,jue,vie,sab,dom")
@click.option("--weekdays", is_flag=True, help="Lunes a viernes")
@click.option("--daily", is_flag=True, help="Todos los dias")
@click.option("--in", "in_minutes", type=int, help="Minutos desde ahora (timer)")
def add(text, time_str, days, weekdays, daily, in_minutes):
    """Agregar un recordatorio o timer"""
    err = _validate_time_flags(time_str, in_minutes)
    if err:
        click.echo(err)
        return
    err = _validate_day_flags(days, weekdays, daily)
    if err:
        click.echo(err)
        return
    err = _validate_day_names(days)
    if err:
        click.echo(err)
        return

    task = Task(
        text=text,
        at=time_str,
        days=_resolve_days(days, weekdays, daily),
        in_minutes=in_minutes,
        created_at=datetime.now().isoformat(),
    )
    tasks = load_tasks()
    tasks.append(task)
    save_tasks(tasks)
    click.echo(f"Tarea creada: {task.id} - {text}")

Por qué separamos las validaciones: no es solo por legibilidad. Reduce la complejidad cognitiva del método add(). Cada función hace una cosa y la hace bien. La complejidad cognitiva mide lo difícil que es seguir el flujo de un método.

@cli.command(name="list")
def list_tasks():
    """Listar todas las tareas pendientes"""
    tasks = load_tasks()
    if not tasks:
        click.echo("No hay tareas pendientes")
        return
    for t in tasks:
        parts = []
        if t.at:
            parts.append(f"{t.at}")
        if t.days:
            label = {"daily": "todos los dias", "weekdays": "lun-vie"}.get(t.days, f"{t.days}")
            parts.append(label)
        if t.in_minutes:
            parts.append(f"timer {t.in_minutes}min")
        if t.done_today:
            parts.append("hecha hoy")
        click.echo(f"  {t.id}  {t.text}  ({', '.join(parts)})")

@cli.command()
@click.argument("task_id")
def done(task_id):
    """Marcar tarea como completada"""
    tasks = load_tasks()
    found = None
    for t in tasks:
        if t.id == task_id:
            found = t
            break
    if not found:
        click.echo(f"Tarea {task_id} no encontrada")
        return
    if found.days:
        found.done_today = True
        click.echo(f"{found.text} marcada como hecha (reaparece manana)")
    else:
        tasks.remove(found)
        click.echo(f"{found.text} completada y eliminada")
    save_tasks(tasks)

Aquí está la lógica de confirmación: si la tarea es recurrente, se marca como "hecha hoy" pero reaparece mañana. Si es de una sola vez, desaparece. Simple, pero es exactamente el comportamiento que quería.

5. El modelo Task: dataclasses, tipos, persistencia

El corazón del proyecto está en core.py. Un dataclass de Python para el modelo de datos:

# pytask/core.py
import json
import uuid
from dataclasses import asdict, dataclass, field
from datetime import datetime
from pathlib import Path


@dataclass
class Task:
    id: str = field(default_factory=lambda: uuid.uuid4().hex[:8])
    text: str = ""
    at: str | None = None        # "HH:MM" o None para timers
    days: str | None = None      # "daily", "weekdays", "lun,mar,..."
    in_minutes: int | None = None
    created_at: str = ""
    done_today: bool = False
    last_fired: str | None = None

str | None es la sintaxis moderna (PEP 604).
En Python < 3.10 escribías Optional[str]. Desde 3.10, | None es más legible y ya es el estándar.

La lógica de disparo es la función más importante del sistema:

    def should_fire(self, now: datetime) -> bool:
        if self.done_today:
            return False
        if self.in_minutes is not None:
            return self._check_timer(now)
        if self.at:
            return self._check_scheduled(now)
        return False

Extraída en sub-métodos para mantener la complejidad baja:

    def _check_timer(self, now: datetime) -> bool:
        if self.last_fired or not self.created_at:
            return False
        created = datetime.fromisoformat(self.created_at)
        return (now - created).total_seconds() / 60 >= self.in_minutes

    def _check_scheduled(self, now: datetime) -> bool:
        if now.strftime("%H:%M") != self.at:
            return False
        if self.days and not self.day_matches(now):
            return False
        if self.last_fired:
            try:
                last = datetime.fromisoformat(self.last_fired)
            except ValueError:
                return True
            if last.strftime("%Y-%m-%d %H:%M") == now.strftime("%Y-%m-%d %H:%M"):
                return False
        return True

La recurrencia con day_matches:

    def day_matches(self, now: datetime) -> bool:
        DAY_NAMES = ["lun", "mar", "mie", "jue", "vie", "sab", "dom"]
        if not self.days:
            return True
        if self.days == "daily":
            return True
        if self.days == "weekdays":
            return now.weekday() < 5
        today = DAY_NAMES[now.weekday()]
        return today in (d.strip() for d in self.days.split(","))

Ese .strip() resuelve un bug común: si alguien escribe --days "lun, mar" con espacio, split(",") produce ["lun", " mar"]. Sin el .strip(), " mar" no coincidiría con "mar" y la tarea nunca se dispararía los martes.

La persistencia es archivo JSON con escritura atómica:

TASKS_FILE = Path.home() / ".pytask" / "tasks.json"

def load_tasks() -> list[Task]:
    if not TASKS_FILE.exists():
        return []
    try:
        data = json.loads(TASKS_FILE.read_text(encoding="utf-8"))
        return [Task(**{k: v for k, v in t.items() if k in Task.__dataclass_fields__})
                for t in data]
    except (json.JSONDecodeError, TypeError):
        return []


def save_tasks(tasks: list[Task]) -> None:
    TASKS_FILE.parent.mkdir(parents=True, exist_ok=True)
    data = [asdict(t) for t in tasks]
    tmp = TASKS_FILE.with_suffix(".tmp")
    tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
    tmp.replace(TASKS_FILE)

Escritura atómica: primero escribimos a un .tmp, luego lo renombramos con replace(). Si el proceso muere a mitad, el .tmp queda basura pero tasks.json original está intacto. Sin esto, una escritura fallida a las 2am te borra todas las tareas del día. Pasó. Por eso está.

6. Servicio en segundo plano: el loop de notificaciones

El servicio corre en un while True durmiendo 30 segundos entre ciclos. Cada iteración:

Lee las tareas desde tasks.json
Resetea tareas recurrentes si cambió el día
Dispara tareas atrasadas (catch-up)
Dispara tareas que coinciden con la hora actual
Re-alerta tareas no confirmadas

# pytask/service.py
import time
from datetime import datetime
from plyer import notification
from pytask.core import load_config, load_tasks, save_tasks


def show_toast(title: str, message: str):
    try:
        notification.notify(
            title=title, message=message, app_name="pyTask", timeout=10
        )
    except Exception as e:
        print(f"Error al mostrar notificacion: {e}")

Plyer es una biblioteca cross-platform para notificaciones. En Windows usa el sistema nativo de toasts. En Linux usa notify-send. Una línea de código y funciona en ambos — sin if/else de plataforma.

La lógica del loop está en process_tasks(), extraída para poder testearla:

def process_tasks(tasks, cfg, now, prev_check_day):
    today_str = now.strftime("%Y-%m-%d")
    interval_min = cfg.get("interval", 5)

    tasks, reset_changed, prev_check_day = _reset_done_today(tasks, today_str, prev_check_day)
    catchup_changed = _catch_up_tasks(tasks, now)
    fire_changed = _fire_scheduled(tasks, now)
    ra_changed = _re_alert_tasks(tasks, now, interval_min)

    changed = reset_changed or catchup_changed or fire_changed or ra_changed
    return tasks, changed, prev_check_day

Cada sub-función independiente:

def _reset_done_today(tasks, today_str, prev_check_day):
    if today_str == prev_check_day:
        return tasks, False, prev_check_day
    changed = False
    for t in tasks:
        if t.days and t.done_today:
            last_done = t.last_fired[:10] if t.last_fired else None
            if last_done != today_str:
                t.done_today = False
                changed = True
    return tasks, changed, today_str


def _catch_up_tasks(tasks, now):
    changed = False
    for t in tasks:
        if not t.at or t.last_fired or t.done_today:
            continue
        task_h, task_m = map(int, t.at.split(":"))
        time_passed = now.hour * 60 + now.minute >= task_h * 60 + task_m
        if time_passed and (not t.days or t.day_matches(now)):
            show_toast("pyTask", t.text)
            t.last_fired = now.isoformat()
            changed = True
    return changed


def _re_alert_tasks(tasks, now, interval_min):
    changed = False
    for t in tasks:
        if t.last_fired and not t.done_today:
            last = datetime.fromisoformat(t.last_fired)
            if (now - last).total_seconds() / 60 >= interval_min:
                show_toast("pyTask", t.text)
                t.last_fired = now.isoformat()
                changed = True
    return changed

7. Tests: de 0 a 90% de cobertura

Sin tests, cualquier cambio rompe algo sin que te enteres hasta que ya estás en producción explicándole a alguien por qué su recordatorio de las 9am no sonó.

# tests/test_core.py — fragmento
from datetime import datetime
from pytask.core import Task


class TestShouldFire:
    def test_done_today_returns_false(self):
        t = Task(text="x", at="10:00", done_today=True)
        assert t.should_fire(datetime(2026, 5, 29, 10, 0, 0)) is False

    def test_timer_elapsed_returns_true(self):
        t = Task(text="x", in_minutes=5, created_at="2026-05-29T09:55:00")
        assert t.should_fire(datetime(2026, 5, 29, 10, 0, 0)) is True

    def test_scheduled_exact_time_returns_true(self):
        t = Task(text="x", at="10:00")
        assert t.should_fire(datetime(2026, 5, 29, 10, 0, 0)) is True

    def test_scheduled_wrong_time_returns_false(self):
        t = Task(text="x", at="10:00")
        assert t.should_fire(datetime(2026, 5, 29, 11, 0, 0)) is False

Para aislar los tests del sistema de archivos real, conftest.py con un fixture que redirige todo a directorios temporales:

# tests/conftest.py
import pytest
from pytask import core


@pytest.fixture(autouse=True)
def isolate_storage(tmp_path, monkeypatch):
    monkeypatch.setattr(core, "TASKS_FILE", tmp_path / "tasks.json")
    monkeypatch.setattr(core, "CONFIG_FILE", tmp_path / "config.json")

autouse=True corre esto en cada test automáticamente. tmp_path es un directorio temporal que pytest crea y destruye. Este fixture me ahorró muchos tests que fallaban por estado residual de otros tests — uno de esos bugs que te hacen perder una tarde.

Para notificaciones, mockeamos plyer:

# tests/test_service.py
from unittest.mock import patch
from pytask.service import show_toast


class TestShowToast:
    @patch("pytask.service.notification.notify")
    def test_show_toast_calls_notify(self, mock_notify):
        show_toast("pyTask", "test message")
        mock_notify.assert_called_once_with(
            title="pyTask", message="test message",
            app_name="pyTask", timeout=10
        )

Mockear significa reemplazar una función real por una simulación. Así no necesitas tener un sistema de notificaciones funcionando para testear que el código que llama a las notificaciones funciona.

Resultado final:

Name                 Stmts   Miss  Cover
pytask/core.py          79      1    99%
pytask/cli.py          112     10    91%
pytask/service.py       69     13    81%
─────────────────────────────────────────
TOTAL                  263     27    90%

8. CI/CD con GitLab: el pipeline completo

Aquí está la diferencia real con GitHub. Todo en un solo archivo, sin servicios externos.

# .gitlab-ci.yml
include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Security/Secret-Detection.gitlab-ci.yml

image: python:3-slim

variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.pip-cache"

cache:
  key: "$CI_JOB_NAME"
  paths:
    - .pip-cache/

stages:
  - lint
  - test
  - coverage

ruff:
  stage: lint
  before_script:
    - python -m venv .venv
    - . .venv/bin/activate
    - pip install -e ".[dev]"
  script:
    - . .venv/bin/activate
    - ruff check pytask tests
    - ruff format --check pytask tests

pytest:
  stage: test
  before_script:
    - python -m venv .venv
    - . .venv/bin/activate
    - pip install -e ".[dev]"
  script:
    - . .venv/bin/activate
    - pytest tests -v --junitxml=report.xml
  artifacts:
    when: always
    reports:
      junit: report.xml

coverage:
  stage: coverage
  before_script:
    - python -m venv .venv
    - . .venv/bin/activate
    - pip install -e ".[dev]"
  script:
    - . .venv/bin/activate
    - pip install codecov-cli
    - pytest --cov=pytask --cov-report=xml --cov-report=term-missing
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage.xml

Lo que hace cada etapa:

Stage	Herramienta	¿Qué verifica?
`lint`	Ruff	Formato del código, imports ordenados
`test`	pytest + JUnit	Tests pasan, reporte XML visible en GitLab

En GitHub Actions para lograr lo mismo habrías necesitado: actions/checkout@v4, actions/setup-python@v5, github/codeql-action@v3 para SAST, y Dependabot configurado por separado. En GitLab: include: - template: Security/SAST.gitlab-ci.yml. Una línea.

GitLab ofrece una plataforma unificada para SCM, CI/CD, container registry, escaneo de seguridad y dashboards de compliance, útil cuando quieres consolidar herramientas en vez de pegar juntos varios productos SaaS. Para proyectos grandes ese consolidado tiene valor real en mantenimiento y costos. Para un side project como este, el valor es diferente: que lo puedas montar en 30 minutos y que funcione.

9. Lo que aprendiste

Python moderno es genuinamente más legible. str | None, dataclasses, pathlib — cada uno de estos existe para que el código cuente su intención sin comentarios extra. Los aproveché todos.

El CI/CD integrado cambia el hábito. Cuando el pipeline corre solo, sin servicios externos que configurar, empiezas a usarlo en proyectos chicos también. Es el punto que marca si un side project tiene CI/CD o no.

Las pruebas de cobertura no mienten, pero tampoco lo dicen todo. Ver service.py en 81% me hizo identificar exactamente qué ramas no estaba cubriendo y por qué — y algunas de esas ramas eran precisamente los edge cases que me importaban. El número te da dirección, no garantía.

El .strip() es gratis. Úsalo.

El código completo está en GitLab:
https://gitlab.com/enlabe/pytask

PRs bienvenidos. Issues bienvenidos. Quejas sobre mi estilo de código, también — pero con argumento.

Construyendo un Web Scraper Profesional con Python y Playwright: Un Pipeline Completo de Tweets a Newsletter

Enrique Lazo Bello — Thu, 09 Apr 2026 05:13:11 +0000

Contexto y Arquitectura

En el ecosistema actual de la información, plataformas como X (anteriormente Twitter) son minas de oro para descubrir tendencias tecnológicas, lanzamientos de herramientas y tutoriales valiosos. Sin embargo, separar el ruido de la información útil requiere tiempo. ¿El problema? Curar contenido manualmente es tedioso y poco escalable.

Para resolver esto, construí XScrapper (cuyo código completo puedes encontrar en el repositorio oficial: https://github.com/enlabedev/xscraper/), un pipeline automatizado que extrae tweets basados en grupos de hashtags, filtra el contenido utilizando Inteligencia Artificial y envía un newsletter curado por correo electrónico.

Desde una perspectiva técnica, este proyecto es un desafío excelente porque combina:

Web Scraping moderno y asíncrono lidiando con sitios web dinámicos (SPAs).
Integración de APIs de Inteligencia Artificial para procesamiento de lenguaje natural.
Orquestación de procesos con programación de tareas (scheduling).

Arquitectura de Alto Nivel

El sistema está construido en Python 3.11+ y se divide en módulos con responsabilidades únicas:

Scraper (src/scraper.py): Utiliza Playwright para la automatización del navegador, permitiendo navegar por X.com, realizar scroll infinito y extraer elementos del DOM.
AI Processor (src/ai_processor.py): Conecta con modelos LLM a través de OpenRouter y LangChain para resumir y filtrar los tweets con mayor relevancia técnica.
Email Sender (src/email_sender.py): Genera el HTML del newsletter y lo distribuye utilizando la API de Resend.
Scheduler (src/scheduler.py): Automatiza las ejecuciones diarias mediante APScheduler.

El Scraper - El Core del Proyecto

¿Por qué Playwright?

A diferencia de herramientas tradicionales como BeautifulSoup (que no ejecuta JavaScript) o Selenium (que suele ser más lento y síncrono por defecto), Playwright ofrece una API asíncrona nativa, manejo impecable de SPAs (Single Page Applications) y una excelente evasión de detección de bots mediante plugins como playwright-stealth.

Inicialización del Navegador

Para navegar en X.com sin ser bloqueados de inmediato, no podemos usar una configuración por defecto. XScrapper inicializa el contexto del navegador inyectando un USER_AGENT realista, configurando el viewport a 1920x1080, estableciendo la localización (es-ES) y añadiendo argumentos específicos (--disable-blink-features=AutomationControlled) para enmascarar que somos un script automatizado. Además, aplicamos stealth_async a la página para ocultar las variables de entorno típicas de navegadores headless.

Manejo de Sesiones con Cookies

El manejo de autenticación puede parecer magia oscura. En lugar de automatizar un "login" escribiendo usuario y contraseña (lo cual suele disparar captchas y bloqueos), exportamos las cookies de una sesión legítima en formato JSON (cookies.json). El scraper carga este archivo y lo inyecta en el contexto del navegador usando await self.context.add_cookies(saved_cookies).

Configuración de las Cookies:
Para raspar X.com de forma exitosa, necesitas exportar las cookies de tu navegador:

Inicia sesión en X.com en tu navegador (Chrome o Firefox).
Instala una extensión para gestionar cookies (por ejemplo, "Get cookies.txt" o "Cookie-Editor").
Exporta las cookies para el dominio x.com en formato Netscape o JSON.
Guarda el archivo como cookies.json en el directorio raíz del proyecto.

Ejemplo del formato esperado en cookies.json:

[
  {
    "domain": ".x.com",
    "name": "auth_token",
    "value": "your_token_here",
    "path": "/",
    "secure": true,
    "sameSite": "Lax"
  }
]

El Patrón de Infinite Scroll

X.com carga los tweets de forma dinámica mientras bajas por la página. Para extraer datos, simulamos el comportamiento humano mediante un bucle de scroll:

await page.evaluate("window.scrollTo(0, document.body.scrollHeight)")
await asyncio.sleep(SCROLL_DELAY)

El script verifica la cantidad de tweets cargados en el DOM tras cada scroll, cuenta los "nuevos" mediante un seguimiento de URLs únicas (seen_urls), y se detiene si alcanza el límite objetivo o si detecta que no hay progreso tras múltiples intentos.

Extracción del DOM y Lógica de Negocio

Una vez cargados los elementos, buscamos los artículos con el selector article[data-testid="tweet"]. Extrae el texto, la fecha, y lo más importante: las métricas (likes, retweets, views).

Nuestra lógica de negocio exige que los tweets tengan un mínimo de interacciones (por defecto 10, configurable en hashtags.yaml). Implementa una función _parse_interactions que suma estas métricas, lidiando inteligentemente con sufijos como "K" (miles) o "M" (millones) para convertirlos a enteros comparables.

Lo que ningún tutorial enseña

La mayoría de los tutoriales asumen que la web es un entorno estático y amigable. En producción, la historia es muy distinta.

Por qué las "sessions" importan: Intentar hacer scraping masivo de X sin autenticación redirige inmediatamente a un muro de login. El uso de un archivo cookies.json persistente y la inyección silenciosa de cookies es la única forma confiable de mantener acceso a la API interna de búsqueda.
El problema de la detección de bots: X utiliza huellas digitales del navegador para detectar scrapers. Por eso usamos flags como --disable-dev-shm-usage y --no-sandbox, junto al paquete playwright-stealth. Esto elimina las banderas rojas que gritan "¡Soy un robot!".
Estrategias de Rate Limiting: Para evitar ser baneados por hacer demasiadas peticiones, no saltamos de un grupo de hashtags a otro de forma inmediata. Implementamos un wait_between_requests_ms (por defecto 7000ms o 7 segundos) entre cada grupo, lo que simula una pausa humana.

Testing y Calidad

Probar scrapers es notoriamente difícil porque dependen de interfaces web volátiles de terceros. En XScrapper, abordamos esto aplicando un fuerte enfoque en pruebas unitarias mediante Mocks.

Usamos la librería pytest y pytest-asyncio. En lugar de levantar un navegador real que ralentizaría nuestra suite y causaría flaky tests (pruebas inestables), utilizamos AsyncMock y MagicMock. Simulamos el DOM inyectando objetos falsos que imitan los retornos de los selectores de Playwright.

Establecimos un umbral mínimo de cobertura del 80% (actualmente por encima de este objetivo). Este estándar nos permite refactorizar la lógica de cálculo de métricas o el formato del HTML del email sabiendo que no rompe la lógica central del negocio.

DevOps y Automatización

El código profesional no solo debe funcionar en la máquina local; debe mantener su calidad en el tiempo. Para ello, integramos automatización desde el primer git commit.

Pre-commit Hooks: Configuramos .pre-commit-config.yaml para ejecutar validaciones automáticamente antes de cada commit. Esto incluye limpieza de espacios en blanco, chequeo de archivos YAML, linting hiper-rápido con ruff (y ruff-format), escaneo de vulnerabilidades de seguridad con bandit, y un script personalizado (pre_commit_coverage.py) que detiene el commit si la cobertura de tests cae por debajo del 80%.
Integración Continua (CI): Utilizamos GitHub Actions (.github/workflows/ci.yml). Ante cualquier Push o Pull Request a las ramas principales, el servidor levanta contenedores de Ubuntu, instala las dependencias de Python 3.11, ejecuta ruff, valida tipado estático con mypy, corre los tests con pytest y finalmente sube el reporte de cobertura a Codecov.
Makefile: Para agilizar el trabajo diario del desarrollador, incluimos comandos como make lint, make format y make test.

Prueba y error

Construir un proyecto de inicio a fin como XScrapper expone varias lecciones valiosas:

Asincronía en Python: Comprender async/await, el event loop de asyncio y cómo lidiar con peticiones de red simultáneas te separa inmediatamente de los desarrolladores junior promedio.
Reintentar ante todo: Aprenderás que en el scraping, el fallo es la norma. Los selectores cambiarán, la red fallará y los muros de login aparecerán. El uso sistemático de bloques try/except y timeouts lógicos es crucial.
La Arquitectura Limpia Paga: Separar el scraper de la IA (AIProcessor) y del módulo de envío de emails (EmailSender) hace que el código sea testeable y mantenible. Si mañana X.com cierra y decidimos extraer datos de Reddit, la IA y los correos seguirán funcionando intactos.
DevOps Temprano: Acostúmbrate a configurar ruff, mypy y pytest el día 1. Tratar de añadir tipado o linting a un proyecto monolítico heredado es una pesadilla; hacerlo incrementalmente es fácil.

En resumen, los errores y bloqueos son parte del proceso. Crear un web scraper real te saca del "tutorial habitual" y te obliga a lidiar con redes reales, esquemas cambiantes y la suciedad inherente de la web moderna. Al dominar estas herramientas, demuestras que puedes crear valor end-to-end en el mundo real.

🚀 Notificaciones en Tiempo Real con SSE, FastAPI y Celery

Enrique Lazo Bello — Mon, 16 Mar 2026 15:44:48 +0000

¿Alguna vez has hecho clic en un botón, la página se queda "pensando" y no sabes si algo está pasando? Para evitar esto en procesos largos —generar un reporte, procesar imágenes, ejecutar un análisis— necesitas comunicación en tiempo real. Pero más importante: necesitas elegir la herramienta correcta.

¿Cuándo usar SSE y cuándo no?

Antes de escribir una línea de código, la decisión de arquitectura más importante es elegir el protocolo correcto.

Criterio	Polling	WebSockets	SSE
Dirección	Client → Server	Bidireccional	Server → Client
Complejidad	Baja	Alta	Baja/Media
Reconexión automática	Manual	Manual	Nativa
Soporte HTTP/2	Sí	No	Sí
Ideal para	Datos muy esporádicos	Chat, juegos	Progreso, notificaciones

Regla práctica: Si el cliente nunca necesita enviar datos por el mismo canal abierto, SSE gana. Es HTTP estándar, tiene reconexión automática incorporada en el navegador, y es significativamente más simple de escalar que WebSockets.

La Arquitectura: Por qué 4 piezas y no 2

La tentación inicial es hacer todo en un solo proceso FastAPI. El problema: FastAPI (ASGI) está optimizado para I/O, no para cómputo pesado. Si pones una tarea de 30 segundos directamente en un endpoint, bloqueas el event loop y degradas toda la API.

✅ Arquitectura correcta:
Browser → FastAPI → Redis (cola) → Celery Worker → Redis (estado)
                 ↑                                      |
                 └──────── SSE stream ←─────────────────┘

Cada pieza tiene una responsabilidad única:

FastAPI: Recibe peticiones HTTP y mantiene las conexiones SSE abiertas.
Celery Worker: Ejecuta las tareas pesadas en un proceso separado.
Redis: Actúa como Broker (cola) y como State Store (donde vive el progreso).
React: Consume el stream SSE y actualiza la UI.

Paso 1: El Backend (FastAPI)

El endpoint de encolar

Usamos celery_app.send_task para enviar la tarea al worker sin esperar a que termine.

@app.post("/task")
async def create_task():
    task_id = str(uuid.uuid4())
    # Encolar la tarea y guardar estado inicial
    celery_app.send_task("tasks.run_simulation", args=[task_id], task_id=task_id)
    redis_client.set(f"task:{task_id}", json.dumps({"status": "pending", "progress": 0}))
    return {"task_id": task_id}

El stream SSE: Máxima estabilidad con `StreamingResponse`

Para evitar errores de encoding y asegurar compatibilidad total, usamos StreamingResponse formateando manualmente el protocolo SSE (data: <json>\n\n).

from fastapi.responses import StreamingResponse

@app.get("/task/{task_id}/stream")
async def task_stream(task_id: str, request: Request):
    async def event_generator():
        while True:
            # 1. Detectar si el usuario cerró la pestaña
            if await request.is_disconnected():
                break

            # 2. Leer progreso de Redis
            raw = redis_client.get(f"task:{task_id}")
            if raw:
                data = json.loads(raw)
                data["id"] = task_id
                # 3. Formato obligatorio SSE: "data: ...\n\n"
                yield f"data: {json.dumps(data)}\n\n"

                if data.get("status") == "done":
                    break

            await asyncio.sleep(0.5)

    return StreamingResponse(
        event_generator(), 
        media_type="text/event-stream",
        headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"}
    )

Paso 2: El Worker (Celery)

El worker es el encargado de actualizar Redis en cada fase de la simulación.

@celery_app.task(name="tasks.run_simulation", bind=True)
def run_simulation(self, task_id):
    # Fase 1: Simulación de inicio
    time.sleep(2)
    redis_client.set(f"task:{task_id}", json.dumps({"status": "processing", "progress": 33}))

    # Fase 2: Trabajo pesado
    time.sleep(random.uniform(3, 6))
    redis_client.set(f"task:{task_id}", json.dumps({"status": "processing", "progress": 66}))

    # Fase 3: Finalización
    result = {
        "status": "done", 
        "progress": 100, 
        "result": {"metric": random.uniform(0, 100), "processed_at": "..."}
    }
    redis_client.set(f"task:{task_id}", json.dumps(result))
    return result

Paso 3: El Frontend (React)

Usamos la API nativa EventSource. Un detalle clave: cerramos la conexión manualmente cuando el estado es done para liberar recursos del servidor.

function TaskCard({ task, onUpdate }: TaskCardProps) {
  useEffect(() => {
    if (task.status === "done") return;

    const eventSource = new EventSource(`http://localhost:8000/task/${task.id}/stream`);

    eventSource.onmessage = (event) => {
      const updated = JSON.parse(event.data);
      onUpdate(updated);
      if (updated.status === "done") eventSource.close();
    };

    return () => eventSource.close(); // Cleanup
  }, [task.id, task.status]);

  // ... Render barrita de progreso y badges
}

Paso 4: Dockerización

Orquestamos los 4 servicios para que la red interna permita la comunicación entre ellos usando sus nombres de servicio (redis, api, etc.).

services:
  redis:
    image: redis:7-alpine
  api:
    build: ./api
    environment:
      - REDIS_URL=redis://redis:6379/0
    ports:
      - "8000:8000"
  worker:
    build: ./worker
    environment:
      - REDIS_URL=redis://redis:6379/0
  frontend:
    build: ./frontend
    ports:
      - "5173:5173"

Casos de Producción: Lo que no te dicen

Nginx Buffering: Si usas Nginx como proxy, debes desactivar el buffering (proxy_buffering off), de lo contrario, los eventos SSE se acumularán y llegarán todos de golpe al final.
Límite de conexiones: Los navegadores limitan a 6 las conexiones SSE por dominio en HTTP/1.1. Si tu app escala, considera usar HTTP/2.
Manejo de desconexiones: El check request.is_disconnected() en FastAPI es vital para no dejar bucles infinitos en el backend.

Conclusión

Este stack (FastAPI + Celery + Redis + SSE) es una solución de grado industrial. Es robusta, fácil de debuguear y escala mucho mejor que intentar manejar sockets bidireccionales cuando solo necesitas enviar progreso al usuario.

¿Has implementado sistemas en tiempo real antes? ¿Qué retos encontraste con los streams de datos? ¡Te leo en los comentarios! 👇

¿Cómo diseño APIs REST limpias y fáciles de mantener (Python/Laravel)?

Enrique Lazo Bello — Sat, 06 Dec 2025 12:37:57 +0000

Durante los últimos años trabajando como arquitecto backend, he visto equipos completos bloqueados por APIs mal diseñadas. El problema nunca es la complejidad técnica del negocio, sino decisiones estructurales que tomamos al inicio y que terminan convirtiéndose en deuda técnica imposible de pagar. Una API bien diseñada no es aquella que funciona hoy, es aquella que otro desarrollador puede extender mañana sin necesidad de llamarte a las 3 AM.

En proyectos con multiples API o microservicios, he aplicado un conjunto de principios que transforman APIs caóticas en sistemas predecibles. No se trata de arquitecturas complejas ni patrones rebuscados. Se trata de decisiones pequeñas y consistentes que facilitan el mantenimiento, reducen bugs en producción y permiten que el equipo escale sin inconvenientes.

Este artículo desglosa mi enfoque práctico para estructurar APIs REST profesionales, con ejemplos reales de decisiones que marcan la diferencia entre un sistema mantenible y uno que nadie quiere tocar.

Estructurando nuestro proyecto

La primera regla de una API mantenible es que cualquier desarrollador pueda predecir dónde está cada cosa sin necesidad de buscar. He trabajado en sistemas donde cada endpoint tenía su propia lógica de organización: algunos mezclaban validación con lógica de negocio, otros tenían consultas SQL directamente en los controladores. El resultado era predecible: cada cambio requería horas de análisis y el riesgo de romper algo no relacionado era altísimo.

La arquitectura que aplico divide el flujo en tres capas con responsabilidades claras:

Controlador (Capa de Transporte): Recibe el HTTP Request, orquesta la llamada al servicio y devuelve el HTTP Response. No contiene reglas de negocio. Su única responsabilidad es traducir entre el protocolo HTTP y tu dominio de aplicación.

Servicio (Lógica de Negocio): Aquí reside la inteligencia del sistema. Es agnóstico al framework HTTP, no sabe si la petición vino de una API REST, una tarea programada o un comando de consola. Esta independencia permite reutilizar la lógica en múltiples contextos sin duplicación.

Repositorio (Capa de Persistencia): Abstrae las consultas a la base de datos o servicios externos. Si mañana cambias de MySQL a PostgreSQL o consumes una API externa, el servicio no debería enterarse.

Mi estructura estándar en FastAPI:

app/
├── api/
│   └── v1/
│       ├── endpoints/
│       │   ├── users.py
│       │   └── orders.py
│       └── __init__.py
├── schemas/
│   ├── user.py
│   └── order.py
├── services/
│   ├── user_service.py
│   └── order_service.py
└── repositories/
    ├── user_repository.py
    └── order_repository.py

En Laravel, mantengo el mismo principio con la estructura nativa del framework:

app/
├── Http/
│   ├── Controllers/
│   │   └── Api/
│   │       └── V1/
│   │           ├── UserController.php
│   │           └── OrderController.php
│   └── Requests/
│       └── V1/
│           ├── CreateUserRequest.php
│           └── CreateOrderRequest.php
├── Services/
│   ├── UserService.php
│   └── OrderService.php
└── Repositories/
    ├── UserRepository.php
    └── OrderRepository.php

Esta separación tiene un propósito claro: cada capa tiene una única razón para cambiar. Cuando necesitas modificar cómo se valida un campo, sabes exactamente que vas a schemas o Requests. Cuando cambias la lógica de cálculo de descuentos, vas directo al servicio correspondiente. Cuando optimizas una consulta SQL, modificas solo el repositorio sin tocar la lógica de negocio.

En un proyecto de e-commerce que heredé, refactoricé una API donde todo estaba en los controladores. El resultado: reducimos el tiempo promedio de implementación de nuevas features de 3 días a 1 día, y los bugs en producción cayeron un 60% en el primer trimestre. La razón fue simple: al separar responsabilidades, cada cambio afectaba solo a una capa, eliminando efectos secundarios inesperados.

Validar todo desde el lado del cliente

Uno de los errores más costosos que veo en APIs es validar datos dentro de la lógica de negocio. Cuando la validación está dispersa, terminas con código defensivo por todas partes, verificando el mismo campo en múltiples lugares y generando inconsistencias. La validación debe ocurrir en la puerta de entrada. Si el dato no es válido, recházalo inmediatamente con HTTP 422 antes de consumir recursos del servidor.

En FastAPI, Pydantic es tu mejor aliado:

from pydantic import BaseModel, EmailStr, validator, Field
from typing import Optional
from datetime import datetime

class CreateUserRequest(BaseModel):
    email: EmailStr
    full_name: str = Field(..., min_length=3, max_length=100)
    phone: Optional[str] = None
    birth_date: datetime

    @validator('full_name')
    def validate_full_name(cls, v):
        if len(v.strip()) < 3:
            raise ValueError('El nombre debe tener al menos 3 caracteres')
        return v.strip()

    @validator('phone')
    def validate_phone(cls, v):
        if v and not v.isdigit():
            raise ValueError('El teléfono solo puede contener dígitos')
        return v

    @validator('birth_date')
    def validate_age(cls, v):
        age = (datetime.now() - v).days / 365
        if age < 18:
            raise ValueError('El usuario debe ser mayor de edad')
        return v

@router.post("/users", status_code=201)
async def create_user(
    user_data: CreateUserRequest,
    service: UserService = Depends(get_user_service)
):
    user = await service.create_user(user_data)
    return {"user_id": user.id, "email": user.email}

El servicio recibe datos ya validados y transformados. No necesita verificar si el email es válido o si el nombre cumple las reglas de negocio. Esto permite que las pruebas unitarias del servicio se concentren en la lógica real, no en casos extremos de validación.

En Laravel, los FormRequests cumplen el mismo rol y extraen la validación a una clase dedicada que limpia el controlador:

class CreateUserRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true;
    }

    public function rules(): array
    {
        return [
            'email' => 'required|email|unique:users,email|max:255',
            'full_name' => 'required|min:3|max:100',
            'phone' => 'nullable|digits:9',
            'birth_date' => 'required|date|before:18 years ago',
        ];
    }

    public function messages(): array
    {
        return [
            'birth_date.before' => 'El usuario debe ser mayor de edad',
            'phone.digits' => 'El teléfono debe tener 9 dígitos',
            'email.unique' => 'Este email ya está registrado',
        ];
    }

    protected function prepareForValidation()
    {
        $this->merge([
            'full_name' => trim($this->full_name),
        ]);
    }
}

Esta centralización tiene un beneficio enorme cuando tu API crece: si cambias las reglas de validación de usuarios, modificas un único archivo. No tienes que rastrear validaciones dispersas por 15 controladores diferentes. Además, la documentación automática en FastAPI (Swagger) y las respuestas de validación en Laravel son consistentes y predecibles para los consumidores de tu API.

Versionado simple

El versionado de APIs genera debates interminables sobre la estrategia perfecta. Después de implementar sistemas con versionado en headers, query params y URLs, mi recomendación es usar versionado en la URL con prefijo /v1, /v2. Es explícito, fácil de documentar, y no requiere que los clientes de tu API configuren headers especiales. Cuando un cliente consume api.tuapp.com/v1/users, sabe exactamente qué versión está usando.

Mi regla práctica para crear una nueva versión:

Cambios backward-compatible (agregar campos opcionales, nuevos endpoints): mantener misma versión.

Cambios breaking (eliminar campos, cambiar tipos de datos, modificar comportamiento esperado): nueva versión.

El error común es versionar desde el día 1 sin justificación. Prefiero versionar cuando toca, no antes. Si tu API aún no está en producción o solo la consumes internamente, no necesitas versiones múltiples. La complejidad que agrega el versionado prematuro no vale la pena.

En FastAPI:

from fastapi import APIRouter

router_v1 = APIRouter(prefix="/api/v1", tags=["v1"])
router_v2 = APIRouter(prefix="/api/v2", tags=["v2"])

# v1: retorna user_id como string y estructura simple
@router_v1.get("/users/{user_id}")
async def get_user_v1(user_id: str):
    return {
        "user_id": user_id,
        "name": "John Doe",
        "email": "john@example.com"
    }

# v2: retorna user_id como int, agrega metadata y estructura más rica
@router_v2.get("/users/{user_id}")
async def get_user_v2(user_id: int):
    return {
        "user_id": user_id,
        "name": "John Doe",
        "email": "john@example.com",
        "metadata": {
            "created_at": "2024-01-01T00:00:00Z",
            "last_login": "2024-12-01T10:30:00Z"
        },
        "preferences": {
            "language": "es",
            "timezone": "America/Lima"
        }
    }

# Registro en la app
app.include_router(router_v1)
app.include_router(router_v2)

En Laravel:

// routes/api.php
Route::prefix('v1')->group(function () {
    Route::get('/users/{id}', [UserController::class, 'show']);
    Route::post('/users', [UserController::class, 'store']);
});

Route::prefix('v2')->group(function () {
    Route::get('/users/{id}', [UserControllerV2::class, 'show']);
    Route::post('/users', [UserControllerV2::class, 'store']);
});

Una estrategia que aplico en producción: cuando lanzamos v2, v1 permanece activa con un header X-API-Deprecation-Date que informa la fecha de cierre del API. Esto permite a los clientes migrar sin prisa, y a nosotros deprecar versiones antiguas de manera controlada. Típicamente mantengo una versión antigua activa entre 6 y 12 meses después de lanzar la nueva, dependiendo de la criticidad de la API y el número de integraciones activas.

Manejo explícito de errores: hablar el idioma correcto

Un error HTTP 500 con el mensaje "Error" no ayuda a nadie. He depurado sistemas donde cada problema se devolvía como 200 OK con un campo status: "error" en el JSON. Esto rompe el contrato HTTP y obliga a los clientes a implementar lógica adicional para interpretar respuestas. El protocolo HTTP ya tiene códigos de estado bien definidos, úsalos correctamente.

Mi estructura estándar de errores en FastAPI:

from fastapi import HTTPException, Request
from fastapi.responses import JSONResponse
from datetime import datetime

class APIException(Exception):
    def __init__(self, status_code: int, message: str, code: str = None, details: dict = None):
        self.status_code = status_code
        self.message = message
        self.code = code or "INTERNAL_ERROR"
        self.details = details or {}

@app.exception_handler(APIException)
async def api_exception_handler(request: Request, exc: APIException):
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "error": {
                "code": exc.code,
                "message": exc.message,
                "details": exc.details,
                "path": str(request.url),
                "timestamp": datetime.now().isoformat(),
                "request_id": request.state.request_id
            }
        }
    )

# Uso en el servicio
class UserService:
    async def get_user(self, user_id: int):
        user = await self.repository.find(user_id)
        if not user:
            raise APIException(
                status_code=404,
                code="USER_NOT_FOUND",
                message="Usuario no encontrado",
                details={"user_id": user_id}
            )
        return user

    async def create_user(self, user_data: CreateUserRequest):
        try:
            return await self.repository.create(user_data)
        except IntegrityError:
            raise APIException(
                status_code=409,
                code="EMAIL_ALREADY_EXISTS",
                message="El email ya está registrado",
                details={"email": user_data.email}
            )

En Laravel, los Custom Exceptions permiten un patrón similar:

class UserNotFoundException extends Exception
{
    public function render($request)
    {
        return response()->json([
            'error' => [
                'code' => 'USER_NOT_FOUND',
                'message' => 'Usuario no encontrado',
                'details' => ['user_id' => $request->route('id')],
                'path' => $request->path(),
                'timestamp' => now()->toIso8601String(),
                'request_id' => request()->header('X-Request-ID')
            ]
        ], 404);
    }
}

class EmailAlreadyExistsException extends Exception
{
    protected $email;

    public function __construct($email)
    {
        parent::__construct();
        $this->email = $email;
    }

    public function render($request)
    {
        return response()->json([
            'error' => [
                'code' => 'EMAIL_ALREADY_EXISTS',
                'message' => 'El email ya está registrado',
                'details' => ['email' => $this->email],
                'path' => $request->path(),
                'timestamp' => now()->toIso8601String(),
                'request_id' => request()->header('X-Request-ID')
            ]
        ], 409);
    }
}

Esta consistencia permite que los equipos frontend construyan manejadores de errores genéricos. Si todas las respuestas de error siguen la misma estructura, el cliente puede implementar un interceptor único que procese cualquier error de la API. Además, el campo code permite al frontend reaccionar programáticamente a errores específicos sin tener que parsear mensajes de texto que pueden cambiar.

Logging y trazabilidad: debugging sin adivinar

Cuando un endpoint falla en producción a las 2 AM, necesitas responder una pregunta: qué pasó exactamente. Sin logging estructurado, estás adivinando. No hablo de logs masivos, hablo de logs útiles que permitan reconstruir el flujo completo de una request en minutos.

Mi configuración base en FastAPI con middleware de logging:

import structlog
from uuid import uuid4
from fastapi import Request
import time

logger = structlog.get_logger()

@app.middleware("http")
async def logging_middleware(request: Request, call_next):
    request_id = str(uuid4())
    request.state.request_id = request_id

    structlog.contextvars.clear_contextvars()
    structlog.contextvars.bind_contextvars(
        request_id=request_id,
        path=request.url.path,
        method=request.method,
        client_ip=request.client.host
    )

    start_time = time.time()

    logger.info("request_started")

    try:
        response = await call_next(request)
        duration = time.time() - start_time

        logger.info(
            "request_completed",
            status_code=response.status_code,
            duration_ms=round(duration * 1000, 2)
        )

        response.headers["X-Request-ID"] = request_id
        return response
    except Exception as e:
        duration = time.time() - start_time
        logger.error(
            "request_failed",
            error=str(e),
            duration_ms=round(duration * 1000, 2),
            exc_info=True
        )
        raise

# En tu servicio
class UserService:
    async def create_user(self, user_data: CreateUserRequest):
        logger.info("creating_user", email=user_data.email)

        try:
            user = await self.repository.create(user_data)
            logger.info("user_created", user_id=user.id)
            return user
        except IntegrityError as e:
            logger.error("user_creation_failed", error=str(e), email=user_data.email)
            raise APIException(409, "EMAIL_ALREADY_EXISTS", "El email ya existe")

En Laravel:

// app/Http/Middleware/LogRequests.php
class LogRequests
{
    public function handle(Request $request, Closure $next)
    {
        $requestId = Str::uuid()->toString();
        $request->headers->set('X-Request-ID', $requestId);

        $startTime = microtime(true);

        Log::channel('api')->info('request_started', [
            'request_id' => $requestId,
            'method' => $request->method(),
            'url' => $request->fullUrl(),
            'ip' => $request->ip(),
            'user_id' => optional($request->user())->id,
        ]);

        try {
            $response = $next($request);

            $duration = microtime(true) - $startTime;

            Log::channel('api')->info('request_completed', [
                'request_id' => $requestId,
                'duration_ms' => round($duration * 1000, 2),
                'status_code' => $response->getStatusCode(),
            ]);

            return $response->header('X-Request-ID', $requestId);
        } catch (Exception $e) {
            $duration = microtime(true) - $startTime;

            Log::channel('api')->error('request_failed', [
                'request_id' => $requestId,
                'duration_ms' => round($duration * 1000, 2),
                'error' => $e->getMessage(),
                'trace' => $e->getTraceAsString(),
            ]);

            throw $e;
        }
    }
}

// app/Services/UserService.php
class UserService
{
    public function createUser(CreateUserRequest $request)
    {
        $requestId = request()->header('X-Request-ID');

        Log::withContext(['request_id' => $requestId]);
        Log::info('creating_user', ['email' => $request->email]);

        try {
            $user = $this->repository->create($request->validated());
            Log::info('user_created', ['user_id' => $user->id]);
            return $user;
        } catch (QueryException $e) {
            Log::error('user_creation_failed', [
                'error' => $e->getMessage(),
                'email' => $request->email
            ]);
            throw new EmailAlreadyExistsException($request->email);
        }
    }
}

Este request_id es oro puro en debugging. Cuando un cliente reporta un error, me da el X-Request-ID, y yo puedo rastrear cada log relacionado a esa petición específica. En un sistema con 10,000 requests por minuto, esto reduce el tiempo de diagnóstico de horas a minutos. Además, incluir duración en milisegundos permite detectar endpoints lentos y optimizarlos proactivamente.

Evitar sobrecargar los endpoints: una responsabilidad por endpoint

Uno de los antipatrones más comunes es el endpoint Frankenstein: hace validación, lógica de negocio, envío de emails, actualización de caché y notificaciones push. Todo en un solo lugar. Si un endpoint hace demasiado, mezcla casos de uso o devuelve sets de datos gigantes, lo divido sin excepción.

Ejemplo de lo que no debes hacer:

@router.post("/orders")
async def create_order_bad(order_data: dict):
    # Validación manual mezclada
    if not order_data.get('items'):
        raise HTTPException(400, "Items requeridos")

    # Lógica de negocio directa
    total = sum(item['price'] * item['qty'] for item in order_data['items'])
    if total > 10000:
        order_data['requires_approval'] = True

    # Guardado directo sin abstracción
    order = db.orders.insert(order_data)

    # Efectos secundarios sincrónicos
    send_email(order_data['email'], "Orden creada")
    cache.set(f"order:{order.id}", order)
    push_service.notify(order_data['user_id'], "Tu orden está en proceso")

    return order

Esto es una bomba de tiempo. Cada responsabilidad agregada aumenta la complejidad de testing y la probabilidad de efectos secundarios. Si el envío de email falla, toda la creación de la orden falla. Si necesitas agregar una nueva acción cuando se crea una orden, tienes que modificar este endpoint y arriesgarte a romper algo.

La versión correcta:

@router.post("/orders", status_code=201)
async def create_order(
    order_data: CreateOrderRequest,
    service: OrderService = Depends(get_order_service)
):
    """
    Crea una nueva orden de compra.

    La orden se crea de forma síncrona.
    Las notificaciones y procesos secundarios se ejecutan de forma asíncrona.
    """
    order = await service.create_order(order_data)
    return {"order_id": order.id, "status": order.status}

# En el servicio
class OrderService:
    async def create_order(self, order_data: CreateOrderRequest):
        # La validación ya ocurrió en CreateOrderRequest
        logger.info("creating_order", user_id=order_data.user_id)

        order = await self.repository.create(order_data)

        # Las operaciones asíncronas se delegan a workers
        await self.event_bus.publish(
            OrderCreatedEvent(order_id=order.id, user_id=order_data.user_id)
        )

        logger.info("order_created", order_id=order.id)
        return order

El endpoint solo coordina. La lógica de envío de emails, actualización de caché y notificaciones vive en event handlers separados que procesan el evento OrderCreatedEvent. Si el envío de email falla, no afecta la creación de la orden. Si necesitas agregar una nueva acción cuando se crea una orden, creas un nuevo handler sin tocar el endpoint.

Ejemplo práctico: estructura completa de un endpoint real

Veamos cómo todos estos principios se integran en un endpoint de producción. Este ejemplo muestra la creación de una orden de compra con validación completa, cálculo de totales y manejo de stock.

Estructura completa en FastAPI:

# schemas/order.py
from pydantic import BaseModel, validator, Field
from typing import List
from decimal import Decimal

class OrderItem(BaseModel):
    product_id: int = Field(..., gt=0)
    quantity: int = Field(..., gt=0)

    @validator('quantity')
    def validate_quantity(cls, v):
        if v < 1:
            raise ValueError('La cantidad debe ser mayor a 0')
        if v > 100:
            raise ValueError('La cantidad máxima por producto es 100')
        return v

class CreateOrderRequest(BaseModel):
    user_id: int = Field(..., gt=0)
    items: List[OrderItem] = Field(..., min_items=1)
    shipping_address: str = Field(..., min_length=10, max_length=500)

    @validator('items')
    def validate_items(cls, v):
        if not v:
            raise ValueError('La orden debe tener al menos un producto')
        if len(v) > 50:
            raise ValueError('Máximo 50 productos por orden')
        return v

# repositories/order_repository.py
class OrderRepository:
    def __init__(self, db):
        self.db = db

    async def create(self, order_data: dict):
        query = """
            INSERT INTO orders (user_id, total, status, shipping_address, created_at)
            VALUES (:user_id, :total, :status, :shipping_address, NOW())
            RETURNING id, user_id, total, status, shipping_address, created_at
        """
        result = await self.db.execute(query, order_data)
        return result

    async def create_items(self, order_id: int, items: List[dict]):
        query = """
            INSERT INTO order_items (order_id, product_id, quantity, price)
            VALUES (:order_id, :product_id, :quantity, :price)
        """
        await self.db.execute_many(query, items)

# services/order_service.py
class OrderService:
    def __init__(
        self,
        repository: OrderRepository,
        product_service: ProductService,
        event_bus: EventBus
    ):
        self.repository = repository
        self.product_service = product_service
        self.event_bus = event_bus

    async def create_order(self, order_data: CreateOrderRequest):
        logger.info("creating_order", user_id=order_data.user_id, items_count=len(order_data.items))

        # Validar disponibilidad y calcular total
        total = Decimal(0)
        validated_items = []

        for item in order_data.items:
            product = await self.product_service.get_product(item.product_id)

            if product.stock < item.quantity:
                raise APIException(
                    400,
                    "INSUFFICIENT_STOCK",
                    "Stock insuficiente",
                    {
                        "product_id": item.product_id,
                        "requested": item.quantity,
                        "available": product.stock
                    }
                )

            item_total = product.price * item.quantity
            total += item_total

            validated_items.append({
                "product_id": item.product_id,
                "quantity": item.quantity,
                "price": product.price
            })

        # Crear orden
        order = await self.repository.create({
            "user_id": order_data.user_id,
            "total": total,
            "status": "pending",
            "shipping_address": order_data.shipping_address
        })

        # Crear items de la orden
        items_with_order_id = [
            {**item, "order_id": order.id}
            for item in validated_items
        ]
        await self.repository.create_items(order.id, items_with_order_id)

        # Publicar evento para procesos asíncronos
        await self.event_bus.publish(
            OrderCreatedEvent(
                order_id=order.id,
                user_id=order_data.user_id,
                total=float(total)
            )
        )

        logger.info("order_created", order_id=order.id, total=float(total))
        return order

# endpoints/orders.py
@router.post("/orders", status_code=201, response_model=OrderResponse)
async def create_order(
    order_data: CreateOrderRequest,
    service: OrderService = Depends(get_order_service),
    current_user: User = Depends(get_current_user)
):
    """
    Crea una nueva orden de compra.

    Valida stock disponible, calcula el total y genera la orden.
    Las notificaciones y emails se procesan de forma asíncrona.

    Requiere autenticación.
    """
    if order_data.user_id != current_user.id:
        raise APIException(
            403,
            "FORBIDDEN",
            "No tienes permiso para crear órdenes de otros usuarios"
        )

    order = await service.create_order(order_data)

    return {
        "order_id": order.id,
        "total": float(order.total),
        "status": order.status,
        "created_at": order.created_at.isoformat()
    }

Implementación equivalente en Laravel:

// app/Http/Requests/CreateOrderRequest.php
class CreateOrderRequest extends FormRequest
{
    public function authorize(): bool
    {
        return $this->user()->id === $this->input('user_id');
    }

    public function rules(): array
    {
        return [
            'user_id' => 'required|integer|exists:users,id',
            'items' => 'required|array|min:1|max:50',
            'items.*.product_id' => 'required|integer|exists:products,id',
            'items.*.quantity' => 'required|integer|min:1|max:100',
            'shipping_address' => 'required|string|min:10|max:500',
        ];
    }
}

// app/Repositories/OrderRepository.php
class OrderRepository
{
    public function create(array $data): Order
    {
        return DB::transaction(function () use ($data) {
            $order = Order::create([
                'user_id' => $data['user_id'],
                'total' => $data['total'],
                'status' => $data['status'],
                'shipping_address' => $data['shipping_address'],
            ]);

            foreach ($data['items'] as $item) {
                $order->items()->create($item);
            }

            return $order->fresh('items');
        });
    }
}

// app/Services/OrderService.php
class OrderService
{
    public function __construct(
        private OrderRepository $repository,
        private ProductService $productService
    ) {}

    public function createOrder(array $data): Order
    {
        $requestId = request()->header('X-Request-ID');
        Log::withContext(['request_id' => $requestId]);

        Log::info('creating_order', [
            'user_id' => $data['user_id'],
            'items_count' => count($data['items'])
        ]);

        $total = 0;
        $validatedItems = [];

        foreach ($data['items'] as $item) {
            $product = $this->productService->getProduct($item['product_id']);

            if ($product->stock < $item['quantity']) {
                throw new InsufficientStockException(
                    $item['product_id'],
                    $item['quantity'],
                    $product->stock
                );
            }

            $itemTotal = $product->price * $item['quantity'];
            $total += $itemTotal;

            $validatedItems[] = [
                'product_id' => $item['product_id'],
                'quantity' => $item['quantity'],
                'price' => $product->price,
            ];
        }

        $order = $this->repository->create([
            'user_id' => $data['user_id'],
            'total' => $total,
            'status' => 'pending',
            'shipping_address' => $data['shipping_address'],
            'items' => $validatedItems,
        ]);

        event(new OrderCreated($order));

        Log::info('order_created', [
            'order_id' => $order->id,
            'total' => $total
        ]);

        return $order;
    }
}

// app/Http/Controllers/Api/V1/OrderController.php
class OrderController extends Controller
{
    public function __construct(private OrderService $service) {}

    public function store(CreateOrderRequest $request): JsonResponse
    {
        $order = $this->service->createOrder($request->validated());

        return response()->json([
            'order_id' => $order->id,
            'total' => $order->total,
            'status' => $order->status,
            'created_at' => $order->created_at->toIso8601String(),
        ], 201);
    }
}

Este endpoint cumple con todos los principios discutidos: estructura predecible con cada componente en su lugar, validación temprana antes de llegar al servicio, manejo explícito de errores con códigos y mensajes claros, logging estructurado con request_id para trazabilidad completa, y responsabilidad única donde el endpoint solo coordina mientras el servicio contiene toda la lógica.

Conclusión

Diseñar APIs mantenibles no requiere arquitecturas complejas ni frameworks exóticos. Requiere disciplina y consistencia en decisiones pequeñas que tomamos cada día. La estructura predecible reduce la carga cognitiva del equipo. La validación temprana elimina bugs antes de que lleguen a producción. El versionado explícito protege a tus clientes de cambios inesperados. El manejo de errores claro acelera el debugging. El logging estructurado convierte el diagnóstico en ciencia, no en arte adivinatorio.

Cada una de estas prácticas tiene un costo inicial: requiere planificación, coordinación con el equipo y establecer estándares claros. Pero ese costo se paga una sola vez. El beneficio se multiplica con cada nueva feature, cada bug que se evita y cada desarrollador que se incorpora al equipo sin necesidad de semanas de onboarding. La mantenibilidad de una API no depende del framework, sino de la disciplina arquitectónica.

¿Cuál ha sido tu mayor desafío al mantener APIs en producción?
¿Qué prácticas te han funcionado mejor en tu equipo?
Déjamelo en los comentarios.

Contabilidad para Django Developers: Implementando Reportería Regulatoria SBS

Enrique Lazo Bello — Sat, 09 Nov 2024 01:08:14 +0000

Introducción

Como desarrollador Django, ¿alguna vez te has enfrentado al desafío de implementar un sistema contable regulatorio? Si la palabra "contabilidad" te genera la misma ansiedad que un deployment fallido en producción, este tutorial es para ti.

Aprenderás a implementar un sistema de reportería regulatoria básica para la SBS (Superintendencia de Banca y Seguros) utilizando Django, traduciendo conceptos contables a términos de programación que ya conoces. Al final, podrás:

Crear modelos Django para manejar estados financieros
Implementar validaciones automáticas de cuadre contable
Gestionar operaciones en múltiples monedas
Todo esto usando únicamente el admin de Django

Prerrequisitos

Django>=5.0
python-decimal>=3.12

Conocimientos necesarios:

Experiencia básica con Django y su ORM
Familiaridad con modelos Django y el admin
Conocimientos básicos de Python 3

Conceptos Clave para Developers

La Contabilidad como Sistema de Base de Datos

Piensa en la contabilidad como un sistema de base de datos con estas características:

ACID compliant (como PostgreSQL)
Double-entry (cada transacción afecta dos o más registros)
Event sourcing (cada movimiento queda registrado)

# Analogía entre conceptos
class ContabilidadConceptos:
    """
    Conceptos contables traducidos a términos de programación:

    Cuenta Contable    -> Tabla
    Asiento           -> Transacción
    Debe/Haber        -> Crédito/Débito (como git add/remove)
    Balance           -> Checkpoint/Snapshot
    """
    pass

Implementación Práctica

1. Modelos Base

from decimal import Decimal
from django.db import models
from django.core.exceptions import ValidationError
from django.utils.translation import gettext_lazy as _

class Currency(models.Model):
    code = models.CharField(max_length=3, unique=True)
    name = models.CharField(max_length=50)
    exchange_rate = models.DecimalField(
        max_digits=10, 
        decimal_places=4,
        help_text="Tipo de cambio respecto a moneda local"
    )

    class Meta:
        verbose_name_plural = "Currencies"

    def __str__(self):
        return self.code

class Account(models.Model):
    """Cuenta contable según plan contable SBS"""
    ACCOUNT_TYPES = [
        ('A', 'Activo'),
        ('P', 'Pasivo'),
        ('R', 'Resultado'),
    ]

    code = models.CharField(max_length=6, unique=True)
    name = models.CharField(max_length=100)
    type = models.CharField(max_length=1, choices=ACCOUNT_TYPES)
    currency = models.ForeignKey(Currency, on_delete=models.PROTECT)
    is_analytic = models.BooleanField(
        default=False,
        help_text="Indica si la cuenta acepta movimientos"
    )

    def __str__(self):
        return f"{self.code} - {self.name}"

    def get_balance(self, date=None):
        """Obtiene el saldo de la cuenta a una fecha"""
        query = self.movements.all()
        if date:
            query = query.filter(accounting_date__lte=date)

        debit = query.aggregate(
            total=models.Sum('debit_amount', default=Decimal('0.00'))
        )['total']
        credit = query.aggregate(
            total=models.Sum('credit_amount', default=Decimal('0.00'))
        )['total']

        if self.type in ['A', 'R']:
            return debit - credit
        return credit - debit

    class Meta:
        ordering = ['code']

class AccountingEntry(models.Model):
    """Asiento contable"""
    date = models.DateField()
    number = models.CharField(max_length=10, unique=True)
    description = models.TextField()
    is_adjusted = models.BooleanField(
        default=False,
        help_text="Indica si es un asiento de ajuste"
    )
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    def clean(self):
        """Validación de cuadre contable"""
        if self.pk:  # Solo validamos entradas existentes
            debit_sum = self.movements.aggregate(
                total=models.Sum('debit_amount', default=Decimal('0.00'))
            )['total']
            credit_sum = self.movements.aggregate(
                total=models.Sum('credit_amount', default=Decimal('0.00'))
            )['total']

            if debit_sum != credit_sum:
                raise ValidationError(
                    _('El asiento no cuadra. Débito: %(debit)s, Crédito: %(credit)s'),
                    params={'debit': debit_sum, 'credit': credit_sum},
                )

    class Meta:
        verbose_name_plural = "Accounting Entries"

class AccountingMove(models.Model):
    """Movimiento contable individual"""
    entry = models.ForeignKey(
        AccountingEntry,
        on_delete=models.PROTECT,
        related_name='movements'
    )
    account = models.ForeignKey(
        Account,
        on_delete=models.PROTECT,
        related_name='movements'
    )
    debit_amount = models.DecimalField(
        max_digits=15,
        decimal_places=2,
        default=Decimal('0.00')
    )
    credit_amount = models.DecimalField(
        max_digits=15,
        decimal_places=2,
        default=Decimal('0.00')
    )
    exchange_rate = models.DecimalField(
        max_digits=10,
        decimal_places=4,
        help_text="Tipo de cambio usado en la operación"
    )
    accounting_date = models.DateField()

    def clean(self):
        """Validaciones de movimiento"""
        if self.debit_amount and self.credit_amount:
            raise ValidationError(
                _('Un movimiento no puede tener débito y crédito simultáneamente')
            )

        if not self.debit_amount and not self.credit_amount:
            raise ValidationError(
                _('El movimiento debe tener al menos un monto')
            )

        if not self.account.is_analytic:
            raise ValidationError(
                _('La cuenta seleccionada no acepta movimientos')
            )

    def save(self, *args, **kwargs):
        if not self.exchange_rate:
            self.exchange_rate = self.account.currency.exchange_rate
        super().save(*args, **kwargs)

    class Meta:
        ordering = ['accounting_date', 'id']

2. Admin personalizado

from django.contrib import admin
from django.db.models import Sum, Value
from django.db.models.functions import Coalesce

@admin.register(Currency)
class CurrencyAdmin(admin.ModelAdmin):
    list_display = ['code', 'name', 'exchange_rate']
    search_fields = ['code', 'name']

@admin.register(Account)
class AccountAdmin(admin.ModelAdmin):
    list_display = ['code', 'name', 'type', 'currency', 'current_balance']
    list_filter = ['type', 'currency', 'is_analytic']
    search_fields = ['code', 'name']

    def current_balance(self, obj):
        return obj.get_balance()
    current_balance.short_description = 'Saldo Actual'

class AccountingMoveInline(admin.TabularInline):
    model = AccountingMove
    extra = 2
    fields = ['account', 'debit_amount', 'credit_amount', 'exchange_rate', 'accounting_date']

@admin.register(AccountingEntry)
class AccountingEntryAdmin(admin.ModelAdmin):
    list_display = ['number', 'date', 'description', 'is_adjusted', 'total_amount']
    list_filter = ['date', 'is_adjusted']
    search_fields = ['number', 'description']
    inlines = [AccountingMoveInline]

    def total_amount(self, obj):
        return obj.movements.aggregate(
            total=Coalesce(Sum('debit_amount'), Value(0))
        )['total']
    total_amount.short_description = 'Monto Total'

3. Tests Unitarios

import pytest
from decimal import Decimal
from django.core.exceptions import ValidationError
from django.utils import timezone
from .models import Currency, Account, AccountingEntry, AccountingMove

@pytest.mark.django_db
class TestAccountingSystem:
    def setup_method(self):
        # Configuración inicial
        self.pen = Currency.objects.create(
            code='PEN',
            name='Soles',
            exchange_rate=Decimal('1.0000')
        )
        self.usd = Currency.objects.create(
            code='USD',
            name='Dólares',
            exchange_rate=Decimal('3.7500')
        )

        # Cuentas de prueba
        self.cash_pen = Account.objects.create(
            code='101101',
            name='Caja MN',
            type='A',
            currency=self.pen,
            is_analytic=True
        )
        self.cash_usd = Account.objects.create(
            code='101102',
            name='Caja ME',
            type='A',
            currency=self.usd,
            is_analytic=True
        )
        self.income = Account.objects.create(
            code='701101',
            name='Ingresos Financieros',
            type='R',
            currency=self.pen,
            is_analytic=True
        )

    def test_account_balance(self):
        # Crear asiento contable
        entry = AccountingEntry.objects.create(
            date=timezone.now().date(),
            number='AS0001',
            description='Test Entry'
        )

        # Movimientos
        AccountingMove.objects.create(
            entry=entry,
            account=self.cash_pen,
            debit_amount=Decimal('1000.00'),
            accounting_date=entry.date
        )
        AccountingMove.objects.create(
            entry=entry,
            account=self.income,
            credit_amount=Decimal('1000.00'),
            accounting_date=entry.date
        )

        assert self.cash_pen.get_balance() == Decimal('1000.00')
        assert self.income.get_balance() == Decimal('-1000.00')

    def test_unbalanced_entry(self):
        entry = AccountingEntry.objects.create(
            date=timezone.now().date(),
            number='AS0002',
            description='Unbalanced Entry'
        )

        AccountingMove.objects.create(
            entry=entry,
            account=self.cash_pen,
            debit_amount=Decimal('1000.00'),
            accounting_date=entry.date
        )

        with pytest.raises(ValidationError):
            entry.clean()

    def test_foreign_currency_movement(self):
        entry = AccountingEntry.objects.create(
            date=timezone.now().date(),
            number='AS0003',
            description='USD Transaction'
        )

        # Movimiento en USD
        AccountingMove.objects.create(
            entry=entry,
            account=self.cash_usd,
            debit_amount=Decimal('100.00'),
            exchange_rate=Decimal('3.7500'),
            accounting_date=entry.date
        )

        # Contrapartida en PEN
        AccountingMove.objects.create(
            entry=entry,
            account=self.income,
            credit_amount=Decimal('375.00'),
            exchange_rate=Decimal('1.0000'),
            accounting_date=entry.date
        )

        assert self.cash_usd.get_balance() == Decimal('100.00')
        assert self.income.get_balance() == Decimal('-375.00')

Ejemplo Real: Sistema de Transferencias

def transfer_between_accounts(
    from_account: Account,
    to_account: Account,
    amount: Decimal,
    date: date,
    description: str
) -> AccountingEntry:
    """
    Realiza una transferencia entre cuentas, manejando diferentes monedas
    """
    # Validaciones previas
    if not from_account.is_analytic or not to_account.is_analytic:
        raise ValidationError('Las cuentas deben ser analíticas')

    if amount <= 0:
        raise ValidationError('El monto debe ser positivo')

    # Crear asiento
    entry = AccountingEntry.objects.create(
        date=date,
        number=f'TR{timezone.now().strftime("%Y%m%d%H%M%S")}',
        description=description
    )

    # Si las monedas son diferentes, calculamos la conversión
    if from_account.currency != to_account.currency:
        to_amount = amount * (
            to_account.currency.exchange_rate / from_account.currency.exchange_rate
        )
    else:
        to_amount = amount

    # Crear movimientos
    AccountingMove.objects.create(
        entry=entry,
        account=from_account,
        credit_amount=amount,
        exchange_rate=from_account.currency.exchange_rate,
        accounting_date=date
    )

    AccountingMove.objects.create(
        entry=entry,
        account=to_account,
        debit_amount=to_amount,
        exchange_rate=to_account.currency.exchange_rate,
        accounting_date=date
    )

    return entry

Mejores Prácticas

Validaciones de Seguridad
- Usar decimal.Decimal para todos los cálculos monetarios
- Implementar permisos granulares en el admin
- Validar cuadre contable antes de guardar
Manejo de Errores
- Usar transacciones para asegurar atomicidad
- Validar tipos de cambio antes de operaciones
- Implementar logging detallado
Patrones de Diseño
- Repository pattern para consultas complejas
- Factory pattern para creación de asientos
- Observer pattern para auditoría

Conclusión

Este tutorial te ha proporcionado una base sólida para implementar reportería regulatoria en Django. Los conceptos clave aprendidos son:

Modelado de datos contables en Django
Validaciones automáticas de cuadre
Manejo de múltiples monedas
Testing de operaciones contables

Contabilidad para Django Developers: Implementando Libros Contables

Enrique Lazo Bello — Sat, 09 Nov 2024 00:54:35 +0000

Introducción

Como desarrollador de Django, ¿alguna vez te has enfrentado al desafío de implementar un sistema contable y te has sentido abrumado por la terminología financiera? No estás solo. La contabilidad puede parecer un mundo completamente diferente a la programación, pero en realidad, comparten muchos conceptos fundamentales.

En este tutorial, aprenderemos a implementar los libros contables principales (Diario, Mayor y Balance de Comprobación) utilizando Django Admin, relacionando conceptos contables con paradigmas de programación que ya conoces. Por ejemplo, un asiento contable es similar a una transacción en base de datos: ambos deben mantener la integridad y ser atómicos.

Al final de este tutorial, serás capaz de implementar un sistema contable robusto utilizando únicamente Django Admin, con validaciones automáticas y pruebas unitarias que garanticen la integridad de los datos.

Prerrequisitos

Python 3.12+
Django 5.0+

Conceptos Clave

La Contabilidad desde una Perspectiva de Desarrollador

Libro Diario → Piense en ello como su historial de confirmaciones de Git
- Cada asiento es como un commit que registra un cambio en el estado financiero
- Debe ser inmutable (como un commit)
- Tiene timestamp y metadata (autor, descripción)
Libro Mayor → Similar a un agregador de logs por categoría
- Agrupa transacciones por "cuenta" (como agrupar logs por servicio)
- Mantiene saldos actualizados (como un contador en Redis)
Balance de Comprobación → Equivalente a revision de cambios
- Verifica que el sistema esté en un estado consistente
- Debe cumplir reglas matemáticas específicas (como assertions en tests)

Implementación Práctica

Modelos Django

from django.db import models
from django.core.exceptions import ValidationError
from django.db.models import Sum
from decimal import Decimal
import uuid

class Account(models.Model):
    """
    Representa una cuenta contable.
    Similar a una tabla en base de datos donde se agregan o restan valores.
    """
    ACCOUNT_TYPES = [
        ('ASSET', 'Activo'),
        ('LIABILITY', 'Pasivo'),
        ('EQUITY', 'Patrimonio'),
        ('INCOME', 'Ingreso'),
        ('EXPENSE', 'Gasto'),
    ]

    code = models.CharField(max_length=20, unique=True)
    name = models.CharField(max_length=100)
    type = models.CharField(max_length=10, choices=ACCOUNT_TYPES)
    is_active = models.BooleanField(default=True)
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return f"{self.code} - {self.name}"

    def get_balance(self, end_date=None):
        """
        Calcula el saldo de la cuenta hasta una fecha específica.
        Similar a un query con filtro temporal.
        """
        entries = JournalEntryLine.objects.filter(account=self)
        if end_date:
            entries = entries.filter(entry__date__lte=end_date)

        debit_sum = entries.aggregate(Sum('debit'))['debit__sum'] or Decimal('0')
        credit_sum = entries.aggregate(Sum('credit'))['credit__sum'] or Decimal('0')

        if self.type in ['ASSET', 'EXPENSE']:
            return debit_sum - credit_sum
        return credit_sum - debit_sum

    class Meta:
        ordering = ['code']

class JournalEntry(models.Model):
    """
    Representa un asiento contable.
    Similar a una transacción en base de datos.
    """
    reference = models.UUIDField(default=uuid.uuid4, editable=False)
    date = models.DateField()
    description = models.TextField()
    is_posted = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)
    created_by = models.ForeignKey('auth.User', on_delete=models.PROTECT)

    def clean(self):
        """
        Validaciones a nivel de asiento.
        Similar a validaciones de integridad en DB.
        """
        if self.is_posted:
            raise ValidationError("No se puede modificar un asiento contabilizado")

        # Verificar balance entre débito y crédito
        total_debit = sum(line.debit for line in self.lines.all())
        total_credit = sum(line.credit for line in self.lines.all())

        if total_debit != total_credit:
            raise ValidationError("El asiento no está balanceado")

    def post(self):
        """
        Contabiliza el asiento.
        Similar a un commit en una transacción.
        """
        self.clean()
        self.is_posted = True
        self.save()

    class Meta:
        verbose_name_plural = "Journal Entries"
        ordering = ['-date', '-created_at']

class JournalEntryLine(models.Model):
    """
    Representa una línea de asiento contable.
    Similar a un detalle de transacción.
    """
    entry = models.ForeignKey(
        JournalEntry, 
        related_name='lines', 
        on_delete=models.CASCADE
    )
    account = models.ForeignKey(
        Account, 
        on_delete=models.PROTECT
    )
    description = models.CharField(max_length=200)
    debit = models.DecimalField(
        max_digits=15, 
        decimal_places=2, 
        default=0
    )
    credit = models.DecimalField(
        max_digits=15, 
        decimal_places=2, 
        default=0
    )

    def clean(self):
        """
        Validaciones a nivel de línea.
        Similar a check constraints en DB.
        """
        if self.debit < 0 or self.credit < 0:
            raise ValidationError("Los montos no pueden ser negativos")

        if self.debit > 0 and self.credit > 0:
            raise ValidationError("Una línea no puede tener débito y crédito")

        if self.debit == 0 and self.credit == 0:
            raise ValidationError("El monto debe ser mayor que cero")

    class Meta:
        ordering = ['id']

class TrialBalance(models.Model):
    """
    Balance de Comprobación.
    Similar a un reporte de health check del sistema.
    """
    date = models.DateField(unique=True)
    is_closed = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)
    created_by = models.ForeignKey('auth.User', on_delete=models.PROTECT)

    def generate(self):
        """
        Genera el balance de comprobación.
        Similar a generar un reporte de estado del sistema.
        """
        if self.is_closed:
            raise ValidationError("Este balance ya está cerrado")

        # Eliminar líneas existentes
        self.lines.all().delete()

        # Generar nuevas líneas
        for account in Account.objects.filter(is_active=True):
            balance = account.get_balance(self.date)
            if balance != 0:
                TrialBalanceLine.objects.create(
                    trial_balance=self,
                    account=account,
                    debit=max(balance, 0),
                    credit=max(-balance, 0)
                )

    def validate(self):
        """
        Valida el balance de comprobación.
        Similar a ejecutar test suite.
        """
        total_debit = self.lines.aggregate(Sum('debit'))['debit__sum'] or 0
        total_credit = self.lines.aggregate(Sum('credit'))['credit__sum'] or 0

        if total_debit != total_credit:
            raise ValidationError(
                f"El balance no cuadra: Débito={total_debit}, Crédito={total_credit}"
            )

    class Meta:
        ordering = ['-date']

class TrialBalanceLine(models.Model):
    """
    Línea de Balance de Comprobación.
    Similar a un resultado individual de test.
    """
    trial_balance = models.ForeignKey(
        TrialBalance,
        related_name='lines',
        on_delete=models.CASCADE
    )
    account = models.ForeignKey(Account, on_delete=models.PROTECT)
    debit = models.DecimalField(max_digits=15, decimal_places=2, default=0)
    credit = models.DecimalField(max_digits=15, decimal_places=2, default=0)

    class Meta:
        ordering = ['account__code']

Configuración del Admin

from django.contrib import admin
from django.urls import reverse
from django.utils.html import format_html
from .models import Account, JournalEntry, JournalEntryLine, TrialBalance, TrialBalanceLine

@admin.register(Account)
class AccountAdmin(admin.ModelAdmin):
    list_display = ['code', 'name', 'type', 'get_balance_display', 'is_active']
    list_filter = ['type', 'is_active']
    search_fields = ['code', 'name']

    def get_balance_display(self, obj):
        balance = obj.get_balance()
        return f"{balance:,.2f}"
    get_balance_display.short_description = 'Balance'

class JournalEntryLineInline(admin.TabularInline):
    model = JournalEntryLine
    extra = 2

    def get_readonly_fields(self, request, obj=None):
        if obj and obj.is_posted:
            return ['account', 'description', 'debit', 'credit']
        return []

@admin.register(JournalEntry)
class JournalEntryAdmin(admin.ModelAdmin):
    list_display = ['reference', 'date', 'description', 'is_posted', 'created_by']
    list_filter = ['is_posted', 'date']
    search_fields = ['reference', 'description']
    readonly_fields = ['reference', 'created_by']
    inlines = [JournalEntryLineInline]

    def save_model(self, request, obj, form, change):
        if not obj.pk:
            obj.created_by = request.user
        super().save_model(request, obj, form, change)

    def get_readonly_fields(self, request, obj=None):
        if obj and obj.is_posted:
            return ['reference', 'date', 'description', 'is_posted', 'created_by']
        return ['reference', 'created_by']

class TrialBalanceLineInline(admin.TabularInline):
    model = TrialBalanceLine
    extra = 0
    readonly_fields = ['account', 'debit', 'credit']
    can_delete = False

    def has_add_permission(self, request, obj=None):
        return False

@admin.register(TrialBalance)
class TrialBalanceAdmin(admin.ModelAdmin):
    list_display = ['date', 'is_closed', 'created_by', 'created_at']
    readonly_fields = ['created_by', 'created_at']
    inlines = [TrialBalanceLineInline]

    def save_model(self, request, obj, form, change):
        if not obj.pk:
            obj.created_by = request.user
        super().save_model(request, obj, form, change)

    def response_add(self, request, obj):
        obj.generate()
        obj.validate()
        return super().response_add(request, obj)

Tests Unitarios

from django.test import TestCase
from django.contrib.auth.models import User
from django.core.exceptions import ValidationError
from decimal import Decimal
from .models import Account, JournalEntry, JournalEntryLine, TrialBalance
from datetime import date

class AccountingTestCase(TestCase):
    def setUp(self):
        self.user = User.objects.create_user(
            username='testuser',
            password='testpass'
        )

        # Crear cuentas de prueba
        self.cash = Account.objects.create(
            code='1000',
            name='Cash',
            type='ASSET'
        )
        self.bank = Account.objects.create(
            code='1001',
            name='Bank',
            type='ASSET'
        )
        self.revenue = Account.objects.create(
            code='4000',
            name='Revenue',
            type='INCOME'
        )

    def test_journal_entry_balance(self):
        """Verifica que los asientos contables estén balanceados"""
        entry = JournalEntry.objects.create(
            date=date.today(),
            description='Test Entry',
            created_by=self.user
        )

        # Crear líneas desbalanceadas
        JournalEntryLine.objects.create(
            entry=entry,
            account=self.cash,
            description='Debit line',
            debit=Decimal('100.00')
        )

        JournalEntryLine.objects.create(
            entry=entry,
            account=self.revenue,
            description='Credit line',
            credit=Decimal('90.00')
        )

        # Intentar contabilizar debería fallar
        with self.assertRaises(ValidationError):
            entry.post()

    def test_trial_balance(self):
        """Verifica la generación del balance de comprobación"""
        # Crear y contabilizar un asiento
        entry = JournalEntry.objects.create(
            date=date.today(),
            description='Test Entry',
            created_by=self.user
        )

        JournalEntryLine.objects.create(
            entry=entry,
            account=self.cash,
            description='Debit line',
            debit=Decimal('100.00')
        )

        JournalEntryLine.objects.create(
            entry=entry,
            account=self.revenue,
            description='Credit line',
            credit=Decimal('100.00')
        )

        entry.post()

        # Generar balance de comprobación
        trial_balance = TrialBalance.objects.create(
            date=date.today(),
            created_by=self.user
        )

        trial_balance.generate()

        # Verificar saldos
        self.assertEqual(
            trial_balance.lines.aggregate(Sum('debit'))['debit__sum'],
            trial_balance.lines.aggregate(Sum('credit'))['credit__sum']
        )

Ejemplo Real: Sistema de Transferencias entre Cuentas

Crear una Transferencia Bancaria

def create_bank_transfer(
    date,
    amount,
    from_account,
    to_account,
    description,
    user
):
    """
    Crea un asiento contable para una transferencia bancaria.
    """
    entry = JournalEntry.objects.create(
        date=date,
        description=description,
        created_by=user
    )

    # Crear línea de débito (cuenta destino)
    JournalEntryLine.objects.create(
        entry=entry,
        account=to_account,
        description=f"Transferencia recibida de {from_account.name}",
        debit=amount
    )

    # Crear línea de crédito (cuenta origen)
    JournalEntryLine.objects.create(
        entry=entry,
        account=from_account,
        description=f"Transferencia enviada a {to_account.name}",
        credit=amount
    )

    # Contabilizar el asiento
    entry.post()

    return entry

# Ejemplo de uso:
from decimal import Decimal
from datetime import date

transfer = create_bank_transfer(
    date=date.today(),
    amount=Decimal('1000.00'),
    from_account=Account.objects.get(code='1001'),  # Cuenta Banco
    to_account=Account.objects.get(code='1000'),    # Cuenta Caja
    description="Transferencia para gastos operativos",
    user=request.user
)

Mejores Prácticas

1. Validaciones de Seguridad

from django.contrib.admin import ModelAdmin
from django.core.exceptions import PermissionDenied

class JournalEntryAdmin(ModelAdmin):
    def has_delete_permission(self, request, obj=None):
        # Prevenir eliminación de asientos contabilizados
        if obj and obj.is_posted:
            return False
        return super().has_delete_permission(request, obj)

    def save_model(self, request, obj, form, change):
        # Verificar permisos especiales para contabilizar
        if 'is_posted' in form.changed_data:
            if not request.user.has_perm('accounting.post_journal_entry'):
                raise PermissionDenied("No tienes permiso para contabilizar asientos")
        super().save_model(request, obj, form, change)

2. Manejo de Errores

class AccountingError(Exception):
    """Base exception for accounting errors"""
    pass

class UnbalancedEntryError(AccountingError):
    """Raised when a journal entry is not balanced"""
    pass

class PostedEntryError(AccountingError):
    """Raised when trying to modify a posted entry"""
    pass

class JournalEntry(models.Model):
    # ... otros campos ...

    def post(self):
        try:
            # Validar balance
            total_debit = self.lines.aggregate(Sum('debit'))['debit__sum'] or 0
            total_credit = self.lines.aggregate(Sum('credit'))['credit__sum'] or 0

            if total_debit != total_credit:
                raise UnbalancedEntryError(
                    f"Débito ({total_debit}) != Crédito ({total_credit})"
                )

            # Validar que no esté contabilizado
            if self.is_posted:
                raise PostedEntryError("El asiento ya está contabilizado")

            # Contabilizar
            self.is_posted = True
            self.save()

        except AccountingError as e:
            # Log del error
            logger.error(f"Error al contabilizar asiento {self.reference}: {str(e)}")
            raise

3. Patrones de Diseño Recomendados

Command Pattern para Operaciones Contables

from abc import ABC, abstractmethod
from decimal import Decimal
from typing import List

class AccountingCommand(ABC):
    @abstractmethod
    def execute(self) -> JournalEntry:
        pass

class TransferCommand(AccountingCommand):
    def __init__(
        self,
        date: date,
        amount: Decimal,
        from_account: Account,
        to_account: Account,
        description: str,
        user: User
    ):
        self.date = date
        self.amount = amount
        self.from_account = from_account
        self.to_account = to_account
        self.description = description
        self.user = user

    def execute(self) -> JournalEntry:
        return create_bank_transfer(
            self.date,
            self.amount,
            self.from_account,
            self.to_account,
            self.description,
            self.user
        )

# Uso del Command Pattern
transfer_cmd = TransferCommand(
    date=date.today(),
    amount=Decimal('1000.00'),
    from_account=bank_account,
    to_account=cash_account,
    description="Transferencia operativa",
    user=current_user
)

journal_entry = transfer_cmd.execute()

Queries Útiles

1. Balance por Tipo de Cuenta

from django.db.models import Sum, Case, When, F

def get_account_type_balances(end_date=None):
    """
    Obtiene los saldos agrupados por tipo de cuenta
    """
    query = Account.objects.all()

    if end_date:
        lines = JournalEntryLine.objects.filter(
            entry__date__lte=end_date,
            entry__is_posted=True
        )
    else:
        lines = JournalEntryLine.objects.filter(entry__is_posted=True)

    balances = query.annotate(
        total_debit=Sum(
            Case(
                When(
                    journalentryline__in=lines,
                    then='journalentryline__debit'
                ),
                default=0
            )
        ),
        total_credit=Sum(
            Case(
                When(
                    journalentryline__in=lines,
                    then='journalentryline__credit'
                ),
                default=0
            )
        ),
        balance=Case(
            When(
                type__in=['ASSET', 'EXPENSE'],
                then=F('total_debit') - F('total_credit')
            ),
            default=F('total_credit') - F('total_debit')
        )
    ).values('type').annotate(
        total_balance=Sum('balance')
    )

    return balances

2. Libro Mayor

def get_ledger(account, start_date=None, end_date=None):
    """
    Obtiene el libro mayor para una cuenta específica
    """
    lines = JournalEntryLine.objects.filter(
        account=account,
        entry__is_posted=True
    ).select_related('entry')

    if start_date:
        lines = lines.filter(entry__date__gte=start_date)
    if end_date:
        lines = lines.filter(entry__date__lte=end_date)

    return lines.order_by('entry__date', 'entry__id')

Conclusión

En este tutorial, hemos construido un sistema contable robusto utilizando Django Admin, aplicando principios de programación familiares para entender conceptos contables. Los puntos clave son:

La contabilidad es similar a un sistema de logging transaccional
Las validaciones son cruciales para mantener la integridad de los datos
El patrón Command nos ayuda a encapsular operaciones contables complejas

Contabilidad para Django Developers: Implementando Reglas de Negocio Contables

Enrique Lazo Bello — Sat, 09 Nov 2024 00:47:03 +0000

Introducción

¿Alguna vez te has preguntado por qué los contadores insisten tanto en que "el debe igual al haber"? Como desarrollador de Django, probablemente estés más familiarizado con transacciones ACID que con asientos contables. Pero aquí está la sorpresa: los principios contables son muy similares a los conceptos de programación que ya conoces.

En este tutorial, transformaremos conceptos contables en código Django limpio y mantenible. Aprenderás a implementar las reglas de negocio básicas de contabilidad utilizando solo el admin de Django, sin necesidad de crear vistas personalizadas.

Al final de este tutorial, serás capaz de:

Implementar validaciones contables robustas
Garantizar la integridad de los datos financieros
Crear un sistema contable básico pero profesional

Prerrequisitos

# Crear un nuevo ambiente virtual
python -m venv env
source env/bin/activate  # En Windows: env\Scripts\activate

# Instalar dependencias
pip install django==5.0
pip install python-dateutil

Conceptos Clave

1. Asientos Contables = Transacciones Atómicas

Así como una transacción en base de datos debe ser atómica, un asiento contable debe cuadrar (debe = haber). No existe un estado intermedio válido.

2. Período Contable = Ventana de Tiempo Válida

Similar a un rate limiter o una ventana de caché, un período contable define cuándo se pueden realizar operaciones.

3. Plan de Cuentas = Enum Jerárquico

Las cuentas contables son como un enum jerárquico con estados (activa/inactiva) y metadatos.

Implementación Práctica

Primero, definamos nuestros modelos:

# accounting/models.py
from django.db import models
from django.core.exceptions import ValidationError
from django.utils import timezone
from dateutil.relativedelta import relativedelta
import decimal

class AccountingPeriod(models.Model):
    name = models.CharField(max_length=100)
    start_date = models.DateField()
    end_date = models.DateField()
    is_closed = models.BooleanField(default=False)

    class Meta:
        ordering = ['-start_date']

    def __str__(self):
        return f"{self.name} ({self.start_date} - {self.end_date})"

    def clean(self):
        if self.start_date > self.end_date:
            raise ValidationError("La fecha de inicio debe ser anterior a la fecha final")

        # Verificar solapamiento de períodos
        overlapping = AccountingPeriod.objects.filter(
            start_date__lte=self.end_date,
            end_date__gte=self.start_date
        ).exclude(pk=self.pk)

        if overlapping.exists():
            raise ValidationError("El período se solapa con otros existentes")

    def is_date_valid(self, date):
        return self.start_date <= date <= self.end_date and not self.is_closed

class Currency(models.Model):
    code = models.CharField(max_length=3, unique=True)
    name = models.CharField(max_length=100)
    symbol = models.CharField(max_length=5)
    is_active = models.BooleanField(default=True)

    def __str__(self):
        return f"{self.code} - {self.name}"

    class Meta:
        verbose_name_plural = "Currencies"

class ExchangeRate(models.Model):
    currency = models.ForeignKey(Currency, on_delete=models.PROTECT)
    date = models.DateField()
    rate = models.DecimalField(max_digits=10, decimal_places=4)

    class Meta:
        unique_together = ['currency', 'date']

    def __str__(self):
        return f"{self.currency.code} - {self.date} - {self.rate}"

    def clean(self):
        if self.rate <= 0:
            raise ValidationError("El tipo de cambio debe ser mayor a 0")

class Account(models.Model):
    ACCOUNT_TYPES = [
        ('A', 'Asset'),
        ('L', 'Liability'),
        ('E', 'Equity'),
        ('I', 'Income'),
        ('X', 'Expense'),
    ]

    code = models.CharField(max_length=20, unique=True)
    name = models.CharField(max_length=200)
    type = models.CharField(max_length=1, choices=ACCOUNT_TYPES)
    is_active = models.BooleanField(default=True)
    allow_movements = models.BooleanField(default=True)
    parent = models.ForeignKey(
        'self',
        null=True,
        blank=True,
        on_delete=models.PROTECT,
        related_name='children'
    )

    def __str__(self):
        return f"{self.code} - {self.name}"

    def clean(self):
        if self.parent:
            if self.parent.type != self.type:
                raise ValidationError("La cuenta padre debe ser del mismo tipo")
            if not self.code.startswith(self.parent.code):
                raise ValidationError("El código debe empezar con el código de la cuenta padre")

class JournalEntry(models.Model):
    date = models.DateField()
    number = models.CharField(max_length=20, unique=True)
    description = models.TextField()
    currency = models.ForeignKey(Currency, on_delete=models.PROTECT)
    is_posted = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return f"{self.number} - {self.date}"

    def clean(self):
        if not self.pk:  # Solo para nuevos registros
            # Generar número automático
            last_entry = JournalEntry.objects.order_by('-number').first()
            if last_entry:
                last_num = int(last_entry.number)
                self.number = str(last_num + 1).zfill(8)
            else:
                self.number = "00000001"

        # Verificar período contable
        period = AccountingPeriod.objects.filter(
            start_date__lte=self.date,
            end_date__gte=self.date,
            is_closed=False
        ).first()

        if not period:
            raise ValidationError("La fecha no corresponde a un período contable válido y abierto")

        # Verificar tipo de cambio
        if not ExchangeRate.objects.filter(
            currency=self.currency,
            date=self.date
        ).exists():
            raise ValidationError(
                f"No existe tipo de cambio para {self.currency.code} en la fecha {self.date}"
            )

    def save(self, *args, **kwargs):
        if not self.is_posted:
            self.verify_balance()
        super().save(*args, **kwargs)

    def verify_balance(self):
        """Verifica que el asiento cuadre (debe = haber)"""
        if self.pk:  # Solo para entradas existentes
            debit_sum = self.lines.aggregate(
                total=models.Sum('debit_amount')
            )['total'] or 0
            credit_sum = self.lines.aggregate(
                total=models.Sum('credit_amount')
            )['total'] or 0

            if debit_sum != credit_sum:
                raise ValidationError(
                    f"El asiento no cuadra. Debe: {debit_sum}, Haber: {credit_sum}"
                )

class JournalEntryLine(models.Model):
    entry = models.ForeignKey(
        JournalEntry,
        on_delete=models.CASCADE,
        related_name='lines'
    )
    account = models.ForeignKey(Account, on_delete=models.PROTECT)
    description = models.CharField(max_length=200)
    debit_amount = models.DecimalField(
        max_digits=15,
        decimal_places=2,
        default=0
    )
    credit_amount = models.DecimalField(
        max_digits=15,
        decimal_places=2,
        default=0
    )

    def clean(self):
        if not self.account.is_active:
            raise ValidationError("La cuenta no está activa")

        if not self.account.allow_movements:
            raise ValidationError("La cuenta no permite movimientos")

        if self.debit_amount < 0 or self.credit_amount < 0:
            raise ValidationError("Los montos no pueden ser negativos")

        if (self.debit_amount > 0 and self.credit_amount > 0):
            raise ValidationError("Una línea no puede tener debe y haber")

        if (self.debit_amount == 0 and self.credit_amount == 0):
            raise ValidationError("El monto debe ser mayor a 0")

Ahora, configuremos el admin de Django para manejar estos modelos:

# accounting/admin.py
from django.contrib import admin
from django.db.models import Sum
from .models import (
    AccountingPeriod,
    Currency,
    ExchangeRate,
    Account,
    JournalEntry,
    JournalEntryLine
)

@admin.register(AccountingPeriod)
class AccountingPeriodAdmin(admin.ModelAdmin):
    list_display = ['name', 'start_date', 'end_date', 'is_closed']
    search_fields = ['name']
    list_filter = ['is_closed']

@admin.register(Currency)
class CurrencyAdmin(admin.ModelAdmin):
    list_display = ['code', 'name', 'symbol', 'is_active']
    search_fields = ['code', 'name']
    list_filter = ['is_active']

@admin.register(ExchangeRate)
class ExchangeRateAdmin(admin.ModelAdmin):
    list_display = ['currency', 'date', 'rate']
    search_fields = ['currency__code']
    list_filter = ['currency', 'date']

@admin.register(Account)
class AccountAdmin(admin.ModelAdmin):
    list_display = [
        'code',
        'name',
        'type',
        'is_active',
        'allow_movements',
        'parent'
    ]
    search_fields = ['code', 'name']
    list_filter = ['type', 'is_active', 'allow_movements']
    ordering = ['code']

class JournalEntryLineInline(admin.TabularInline):
    model = JournalEntryLine
    extra = 2

    def get_readonly_fields(self, request, obj=None):
        if obj and obj.is_posted:
            return ['account', 'description', 'debit_amount', 'credit_amount']
        return []

@admin.register(JournalEntry)
class JournalEntryAdmin(admin.ModelAdmin):
    list_display = [
        'number',
        'date',
        'description',
        'currency',
        'is_posted',
        'total_amount'
    ]
    search_fields = ['number', 'description']
    list_filter = ['date', 'currency', 'is_posted']
    inlines = [JournalEntryLineInline]
    readonly_fields = ['number']

    def get_readonly_fields(self, request, obj=None):
        if obj and obj.is_posted:
            return ['date', 'number', 'description', 'currency', 'is_posted']
        return ['number']

    def total_amount(self, obj):
        if obj.pk:
            return obj.lines.aggregate(
                total=Sum('debit_amount')
            )['total'] or 0
        return 0

    def save_model(self, request, obj, form, change):
        if not change:  # Nuevo registro
            obj.save()
        else:
            if 'is_posted' in form.changed_data and obj.is_posted:
                # Verificar balance antes de marcar como contabilizado
                obj.verify_balance()
            obj.save()

Ejemplo Real: Sistema de Transferencias entre Cuentas

Veamos cómo implementar una transferencia entre cuentas bancarias:

# accounting/tests.py
from django.test import TestCase
from django.core.exceptions import ValidationError
from decimal import Decimal
from datetime import date
from .models import (
    AccountingPeriod,
    Currency,
    ExchangeRate,
    Account,
    JournalEntry,
    JournalEntryLine
)

class AccountingTests(TestCase):
    def setUp(self):
        # Crear período contable
        self.period = AccountingPeriod.objects.create(
            name="2024-01",
            start_date=date(2024, 1, 1),
            end_date=date(2024, 1, 31)
        )

        # Crear moneda y tipo de cambio
        self.currency = Currency.objects.create(
            code="USD",
            name="US Dollar",
            symbol="$"
        )

        self.exchange_rate = ExchangeRate.objects.create(
            currency=self.currency,
            date=date(2024, 1, 15),
            rate=Decimal('1.0')
        )

        # Crear cuentas bancarias
        self.bank_parent = Account.objects.create(
            code="1001",
            name="Bancos",
            type='A'
        )

        self.bank_account_1 = Account.objects.create(
            code="1001001",
            name="Banco 1",
            type='A',
            parent=self.bank_parent
        )

        self.bank_account_2 = Account.objects.create(
            code="1001002",
            name="Banco 2",
            type='A',
            parent=self.bank_parent
        )

    def test_bank_transfer(self):
        # Crear asiento de transferencia
        entry = JournalEntry.objects.create(
            date=date(2024, 1, 15),
            description="Transferencia entre bancos",
            currency=self.currency
        )

        # Débito al banco 2
        JournalEntryLine.objects.create(
            entry=entry,
            account=self.bank_account_2,
            description="Transferencia recibida",
            debit_amount=Decimal('1000.00')
        )

        # Crédito al banco 1
        JournalEntryLine.objects.create(
            entry=entry,
            account=self.bank_account_1,
            description="Transferencia enviada",
            credit_amount=Decimal('1000.00')
        )

        # Verificar balance
        entry.verify_balance()

        # Marcar como contabilizado
        entry.is_posted = True
        entry.save()


    def test_invalid_transfer(self):
        # Probar transferencia con montos desbalanceados
        entry = JournalEntry.objects.create(
            date=date(2024, 1, 15),
            description="Transferencia inválida",
            currency=self.currency
        )

        JournalEntryLine.objects.create(
            entry=entry,
            account=self.bank_account_2,
            description="Transferencia recibida",
            debit_amount=Decimal('1000.00')
        )

        JournalEntryLine.objects.create(
            entry=entry,
            account=self.bank_account_1,
            description="Transferencia enviada",
            credit_amount=Decimal('900.00')  # Monto diferente
        )

        # Debería levantar una excepción al verificar el balance
        with self.assertRaises(ValidationError):
            entry.verify_balance()

    def test_closed_period(self):
        # Cerrar el período
        self.period.is_closed = True
        self.period.save()

        # Intentar crear un asiento en período cerrado
        with self.assertRaises(ValidationError):
            JournalEntry.objects.create(
                date=date(2024, 1, 15),
                description="Asiento en período cerrado",
                currency=self.currency
            )

    def test_inactive_account(self):
        # Desactivar cuenta
        self.bank_account_1.is_active = False
        self.bank_account_1.save()

        entry = JournalEntry.objects.create(
            date=date(2024, 1, 15),
            description="Transferencia con cuenta inactiva",
            currency=self.currency
        )

        # Intentar crear línea con cuenta inactiva
        with self.assertRaises(ValidationError):
            JournalEntryLine.objects.create(
                entry=entry,
                account=self.bank_account_1,
                description="Débito a cuenta inactiva",
                debit_amount=Decimal('1000.00')
            )

Mejores Prácticas

1. Validaciones de Seguridad

Para garantizar la integridad de los datos contables, hemos implementado múltiples niveles de validación:

# accounting/models.py

class JournalEntry(models.Model):
    # ... (código anterior) ...

    def save(self, *args, **kwargs):
        if self.is_posted:
            raise ValidationError(
                "No se pueden modificar asientos contabilizados"
            )
        super().save(*args, **kwargs)

class JournalEntryLine(models.Model):
    # ... (código anterior) ...

    def save(self, *args, **kwargs):
        if self.entry.is_posted:
            raise ValidationError(
                "No se pueden modificar líneas de asientos contabilizados"
            )
        super().save(*args, **kwargs)

2. Manejo de Errores

Implementamos un middleware personalizado para manejar errores contables de manera amigable:

# accounting/middleware.py
from django.core.exceptions import ValidationError
from django.contrib import messages
from django.shortcuts import redirect

class AccountingErrorMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        response = self.get_response(request)
        return response

    def process_exception(self, request, exception):
        if isinstance(exception, ValidationError):
            messages.error(
                request,
                f"Error de validación contable: {str(exception)}"
            )
            return redirect('admin:index')
        return None

3. Patrones de Diseño Recomendados

Unit of Work: Implementado a través de las transacciones de Django
Repository Pattern: Usando el ORM de Django
Value Objects: Para manejo de montos y tipos de cambio

# accounting/utils.py
from decimal import Decimal
from dataclasses import dataclass
from typing import Optional

@dataclass
class Money:
    amount: Decimal
    currency: str

    def __post_init__(self):
        self.amount = Decimal(str(self.amount))

    def __add__(self, other):
        if not isinstance(other, Money):
            raise TypeError("Solo se pueden sumar objetos Money")
        if self.currency != other.currency:
            raise ValueError("No se pueden sumar montos en diferentes monedas")
        return Money(self.amount + other.amount, self.currency)

    def __sub__(self, other):
        if not isinstance(other, Money):
            raise TypeError("Solo se pueden restar objetos Money")
        if self.currency != other.currency:
            raise ValueError("No se pueden restar montos en diferentes monedas")
        return Money(self.amount - other.amount, self.currency)

@dataclass
class ExchangeRateValue:
    from_currency: str
    to_currency: str
    rate: Decimal
    date: date

    def convert(self, money: Money) -> Money:
        if money.currency != self.from_currency:
            raise ValueError("Moneda incompatible")
        return Money(
            money.amount * self.rate,
            self.to_currency
        )

Consultas Útiles

Aquí hay algunos ejemplos de consultas comunes:

# Obtener balance por cuenta
from django.db.models import Sum, F, Value
from django.db.models.functions import Coalesce

def get_account_balance(account_code, date_from, date_to):
    return JournalEntryLine.objects.filter(
        account__code__startswith=account_code,
        entry__date__range=[date_from, date_to],
        entry__is_posted=True
    ).aggregate(
        balance=Coalesce(
            Sum(F('debit_amount') - F('credit_amount')),
            Value(0)
        )
    )['balance']

# Libro mayor
def get_ledger(account_code, date_from, date_to):
    return JournalEntryLine.objects.filter(
        account__code__startswith=account_code,
        entry__date__range=[date_from, date_to],
        entry__is_posted=True
    ).select_related(
        'entry', 'account'
    ).order_by('entry__date', 'entry__number')

# Balance de comprobación
def get_trial_balance(date_from, date_to):
    return Account.objects.filter(
        lines__entry__date__range=[date_from, date_to],
        lines__entry__is_posted=True
    ).annotate(
        debit_sum=Coalesce(
            Sum('lines__debit_amount'),
            Value(0)
        ),
        credit_sum=Coalesce(
            Sum('lines__credit_amount'),
            Value(0)
        ),
        balance=F('debit_sum') - F('credit_sum')
    ).filter(balance__ne=0)

Conclusión

Hemos construido un sistema contable básico pero robusto utilizando Django. Los puntos clave a recordar son:

Las reglas contables se implementan como validaciones en los modelos
El admin de Django proporciona una interfaz lista para usar
Los tests son cruciales para garantizar la integridad contable

Contabilidad para Django Developers: Control de Cambios y Tipo de Cambio

Enrique Lazo Bello — Sat, 09 Nov 2024 00:36:22 +0000

Introducción

Como desarrollador Django, ¿alguna vez te has preguntado cómo manejar correctamente las operaciones en diferentes monedas en tus aplicaciones? Si estás construyendo sistemas empresariales o financieros, entender el control de cambios no es solo una necesidad contable - es un requisito técnico crucial.

En este tutorial, transformaremos conceptos contables complejos en modelos Django intuitivos, usando el admin de Django como nuestra interfaz principal. Aprenderás a manejar tipos de cambio, calcular diferencias cambiarias y mantener una posición de cambio precisa, todo sin escribir una sola vista personalizada.

Al finalizar, tendrás un sistema robusto de control de cambios que cualquier contador podrá usar desde el admin de Django, con validaciones automáticas y tests que aseguran su correcto funcionamiento.

Prerrequisitos

Python 3.12+
Django 5.0+
Conocimientos básicos de modelos Django y el admin
SQLite o PostgreSQL
Git para control de versiones

Conceptos Clave

El Tipo de Cambio como un State Pattern

Piensa en el tipo de cambio como un state pattern en programación: representa el estado de una moneda en relación a otra en un momento específico. Así como guardamos timestamps para auditoría, necesitamos mantener un historial de tipos de cambio para operaciones financieras.

# Analogía en código
class Currency(str, Enum):
    PEN = "PEN"  # Soles
    USD = "USD"  # Dólares
    EUR = "EUR"  # Euros

# El tipo de cambio es como un estado inmutable
@dataclass(frozen=True)
class ExchangeRate:
    currency_from: Currency
    currency_to: Currency
    rate: Decimal
    timestamp: datetime

Diferencia de Cambio como Debugging

La diferencia de cambio es similar a encontrar un bug entre el comportamiento esperado y el actual. Cuando tienes una cuenta por pagar de $1000 registrada cuando el dólar estaba a S/3.80, pero la pagas cuando está a S/3.85, esa diferencia necesita ser registrada - como cuando haces un diff entre versiones de código.

Implementación Práctica

Modelos Base

from django.db import models
from django.core.validators import MinValueValidator
from decimal import Decimal
from django.core.exceptions import ValidationError
from django.utils import timezone

class Currency(models.Model):
    code = models.CharField(max_length=3, unique=True)
    name = models.CharField(max_length=50)
    is_base = models.BooleanField(default=False)

    def save(self, *args, **kwargs):
        if self.is_base:
            # Solo puede haber una moneda base
            Currency.objects.filter(is_base=True).update(is_base=False)
        super().save(*args, **kwargs)

    def __str__(self):
        return f"{self.code} - {self.name}"

    class Meta:
        verbose_name_plural = "Currencies"

class ExchangeRate(models.Model):
    currency_from = models.ForeignKey(
        Currency, 
        on_delete=models.PROTECT,
        related_name='rates_from'
    )
    currency_to = models.ForeignKey(
        Currency,
        on_delete=models.PROTECT,
        related_name='rates_to'
    )
    rate = models.DecimalField(
        max_digits=10,
        decimal_places=4,
        validators=[MinValueValidator(Decimal('0.0001'))]
    )
    date = models.DateField(default=timezone.now)
    is_sbs = models.BooleanField(
        default=False,
        verbose_name="Is SBS Rate",
        help_text="Indica si es tipo de cambio oficial SBS"
    )

    class Meta:
        unique_together = [['currency_from', 'currency_to', 'date']]

    def clean(self):
        if self.currency_from == self.currency_to:
            raise ValidationError(
                "La moneda origen y destino no pueden ser iguales"
            )
        if self.is_sbs and ExchangeRate.objects.filter(
            date=self.date,
            is_sbs=True,
            currency_from=self.currency_from,
            currency_to=self.currency_to
        ).exclude(id=self.id).exists():
            raise ValidationError(
                "Ya existe un tipo de cambio SBS para esta fecha"
            )

    def save(self, *args, **kwargs):
        self.full_clean()
        super().save(*args, **kwargs)

        # Crear tipo de cambio inverso automáticamente
        if not ExchangeRate.objects.filter(
            currency_from=self.currency_to,
            currency_to=self.currency_from,
            date=self.date
        ).exists():
            ExchangeRate.objects.create(
                currency_from=self.currency_to,
                currency_to=self.currency_from,
                rate=Decimal('1.0') / self.rate,
                date=self.date,
                is_sbs=self.is_sbs
            )

class ForexAccount(models.Model):
    currency = models.ForeignKey(Currency, on_delete=models.PROTECT)
    code = models.CharField(max_length=10, unique=True)
    name = models.CharField(max_length=100)
    balance = models.DecimalField(
        max_digits=15,
        decimal_places=2,
        default=Decimal('0.00')
    )

    def __str__(self):
        return f"{self.code} - {self.name} ({self.currency.code})"

    def get_balance_base_currency(self, date=None):
        if not date:
            date = timezone.now().date()

        base_currency = Currency.objects.get(is_base=True)
        if self.currency == base_currency:
            return self.balance

        try:
            rate = ExchangeRate.objects.get(
                currency_from=self.currency,
                currency_to=base_currency,
                date=date
            )
            return self.balance * rate.rate
        except ExchangeRate.DoesNotExist:
            raise ValidationError(
                f"No existe tipo de cambio para {date}"
            )

class ForexTransaction(models.Model):
    TRANSACTION_TYPES = [
        ('IN', 'Ingreso'),
        ('OUT', 'Egreso'),
    ]

    account = models.ForeignKey(
        ForexAccount,
        on_delete=models.PROTECT,
        related_name='transactions'
    )
    type = models.CharField(max_length=3, choices=TRANSACTION_TYPES)
    amount = models.DecimalField(max_digits=15, decimal_places=2)
    exchange_rate = models.ForeignKey(
        ExchangeRate,
        on_delete=models.PROTECT,
        null=True,
        blank=True
    )
    date = models.DateField(default=timezone.now)
    description = models.TextField()

    def clean(self):
        if self.exchange_rate and (
            self.exchange_rate.currency_from != self.account.currency
        ):
            raise ValidationError(
                "El tipo de cambio debe corresponder a la moneda de la cuenta"
            )

    def save(self, *args, **kwargs):
        self.full_clean()
        if not self.exchange_rate:
            base_currency = Currency.objects.get(is_base=True)
            self.exchange_rate = ExchangeRate.objects.get(
                currency_from=self.account.currency,
                currency_to=base_currency,
                date=self.date
            )

        # Actualizar saldo de la cuenta
        multiplier = Decimal('1.0') if self.type == 'IN' else Decimal('-1.0')
        self.account.balance += (self.amount * multiplier)
        self.account.save()

        super().save(*args, **kwargs)

Configuración del Admin

from django.contrib import admin
from django.utils.html import format_html

@admin.register(Currency)
class CurrencyAdmin(admin.ModelAdmin):
    list_display = ['code', 'name', 'is_base']
    search_fields = ['code', 'name']
    list_filter = ['is_base']

@admin.register(ExchangeRate)
class ExchangeRateAdmin(admin.ModelAdmin):
    list_display = [
        'date',
        'currency_from',
        'currency_to',
        'rate',
        'is_sbs'
    ]
    list_filter = ['date', 'currency_from', 'currency_to', 'is_sbs']
    search_fields = ['currency_from__code', 'currency_to__code']
    date_hierarchy = 'date'

@admin.register(ForexAccount)
class ForexAccountAdmin(admin.ModelAdmin):
    list_display = [
        'code',
        'name',
        'currency',
        'balance',
        'base_currency_balance'
    ]
    search_fields = ['code', 'name']
    list_filter = ['currency']

    def base_currency_balance(self, obj):
        try:
            base_balance = obj.get_balance_base_currency()
            base_currency = Currency.objects.get(is_base=True)
            return f"{base_currency.code} {base_balance:.2f}"
        except Exception as e:
            return format_html(
                '<span style="color: red;">{}</span>',
                str(e)
            )

    base_currency_balance.short_description = "Balance en Moneda Base"

@admin.register(ForexTransaction)
class ForexTransactionAdmin(admin.ModelAdmin):
    list_display = [
        'date',
        'account',
        'type',
        'amount',
        'exchange_rate',
        'amount_base_currency'
    ]
    list_filter = ['date', 'type', 'account__currency']
    search_fields = ['description', 'account__name']
    date_hierarchy = 'date'

    def amount_base_currency(self, obj):
        base_amount = obj.amount * obj.exchange_rate.rate
        base_currency = Currency.objects.get(is_base=True)
        return f"{base_currency.code} {base_amount:.2f}"

    amount_base_currency.short_description = "Monto en Moneda Base"

Tests Unitarios

from django.test import TestCase
from django.core.exceptions import ValidationError
from decimal import Decimal
from django.utils import timezone
from .models import Currency, ExchangeRate, ForexAccount, ForexTransaction

class ForexTests(TestCase):
    def setUp(self):
        # Crear monedas base
        self.pen = Currency.objects.create(
            code='PEN',
            name='Soles',
            is_base=True
        )
        self.usd = Currency.objects.create(
            code='USD',
            name='Dólares'
        )

        # Crear tipo de cambio
        self.exchange_rate = ExchangeRate.objects.create(
            currency_from=self.usd,
            currency_to=self.pen,
            rate=Decimal('3.85'),
            date=timezone.now().date(),
            is_sbs=True
        )

        # Crear cuenta
        self.account = ForexAccount.objects.create(
            currency=self.usd,
            code='1041',
            name='Cuenta Corriente USD'
        )

    def test_exchange_rate_inverse(self):
        """Verifica que se cree automáticamente el tipo de cambio inverso"""
        inverse_rate = ExchangeRate.objects.get(
            currency_from=self.pen,
            currency_to=self.usd,
            date=self.exchange_rate.date
        )
        self.assertAlmostEqual(
            float(inverse_rate.rate),
            float(Decimal('1.0') / self.exchange_rate.rate),
            places=4
        )

    def test_account_balance_update(self):
        """Verifica la actualización correcta del saldo"""
        initial_balance = self.account.balance

        # Crear transacción de ingreso
        transaction = ForexTransaction.objects.create(
            account=self.account,
            type='IN',
            amount=Decimal('1000.00'),
            exchange_rate=self.exchange_rate,
            description='Test transaction'
        )

        self.account.refresh_from_db()
        self.assertEqual(
            self.account.balance,
            initial_balance + Decimal('1000.00')
        )

        # Verificar balance en moneda base
        base_balance = self.account.get_balance_base_currency()
        self.assertEqual(
            base_balance,
            Decimal('1000.00') * Decimal('3.85')
        )

    def test_invalid_exchange_rate(self):
        """Verifica que no se pueden crear tipos de cambio inválidos"""
        with self.assertRaises(ValidationError):
            ExchangeRate.objects.create(
                currency_from=self.usd,
                currency_to=self.usd,
                rate=Decimal('1.00'),
                date=timezone.now().date()
            )

Ejemplo Real: Sistema de Transferencias

Caso de Uso: Transferencia entre Cuentas

from django.db import transaction
from decimal import Decimal

def transfer_between_accounts(
    from_account: ForexAccount,
    to_account: ForexAccount,
    amount: Decimal,
    date=None
) -> tuple[ForexTransaction, ForexTransaction]:
    """
    Realiza una transferencia entre cuentas, manejando la conversión
    de monedas si es necesario.
    """
    if not date:
        date = timezone.now().date()

    with transaction.atomic():
        # Obtener tipo de cambio si las monedas son diferentes
        exchange_rate = None
        if from_account.currency != to_account.currency:
            exchange_rate = ExchangeRate.objects.get(
                currency_from=from_account.currency,
                currency_to=to_account.currency,
                date=date
            )

        # Crear transacción de salida
        outgoing = ForexTransaction.objects.create(
            account=from_account,
            type='OUT',
            amount=amount,
            date=date,
            description=f'Transferencia a {to_account.code}'
        )

        # Calcular monto en moneda destino si es necesario
        incoming_amount = amount
        if exchange_rate:
            incoming_amount = amount * exchange_rate.rate

        # Crear transacción de ingreso
        incoming = ForexTransaction.objects.create(
            account=to_account,
            type='IN',
            amount=incoming_amount,
            date=date,
            description=f'Transferencia desde {from_account.code}'
        )

        return outgoing, incoming

Mejores Prácticas

Validaciones de Seguridad
- Usar decimal.Decimal para todos los cálculos monetarios

Mejores Prácticas (continuación)

Validaciones de Seguridad
- Usar decimal.Decimal para todos los cálculos monetarios
- Implementar validaciones a nivel de modelo
- Utilizar transacciones atómicas para operaciones críticas
- Mantener un registro de auditoría

# models.py
class AuditMixin(models.Model):
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)
    created_by = models.ForeignKey(
        'auth.User',
        on_delete=models.PROTECT,
        related_name='%(class)s_created',
        null=True
    )
    updated_by = models.ForeignKey(
        'auth.User',
        on_delete=models.PROTECT,
        related_name='%(class)s_updated',
        null=True
    )

    class Meta:
        abstract = True

class ForexTransaction(AuditMixin, models.Model):
    # ... (código anterior del modelo) ...

    def save(self, *args, **kwargs):
        if not self.pk:  # Solo en creación
            if not hasattr(self, 'created_by') and hasattr(self, '_current_user'):
                self.created_by = self._current_user
        if hasattr(self, '_current_user'):
            self.updated_by = self._current_user
        super().save(*args, **kwargs)

Manejo de Errores
- Implementar excepciones personalizadas
- Logging detallado
- Mensajes de error amigables en el admin

# exceptions.py
class ForexError(Exception):
    """Base exception for forex operations"""
    pass

class ExchangeRateError(ForexError):
    """Raised when there's an issue with exchange rates"""
    pass

class InsufficientFundsError(ForexError):
    """Raised when an account has insufficient funds"""
    pass

# models.py
from django.core.exceptions import ValidationError
import logging

logger = logging.getLogger(__name__)

class ForexAccount(AuditMixin, models.Model):
    def withdraw(self, amount: Decimal) -> None:
        if self.balance < amount:
            logger.error(
                f"Insufficient funds in account {self.code}: "
                f"balance={self.balance}, amount={amount}"
            )
            raise InsufficientFundsError(
                f"Saldo insuficiente. Disponible: {self.balance}"
            )
        self.balance -= amount
        self.save()

Patrones de Diseño Recomendados
- Repository Pattern para acceso a datos
- Service Layer para lógica de negocio
- Command Pattern para operaciones complejas

# services.py
class ForexService:
    @staticmethod
    def calculate_exchange_difference(
        account: ForexAccount,
        date_from: date,
        date_to: date
    ) -> Decimal:
        """
        Calcula la diferencia de cambio para una cuenta en un período
        """
        initial_rate = ExchangeRate.objects.get(
            currency_from=account.currency,
            currency_to=Currency.objects.get(is_base=True),
            date=date_from
        )

        final_rate = ExchangeRate.objects.get(
            currency_from=account.currency,
            currency_to=Currency.objects.get(is_base=True),
            date=date_to
        )

        balance = account.balance
        initial_value = balance * initial_rate.rate
        final_value = balance * final_rate.rate

        return final_value - initial_value

class ForexReportService:
    @staticmethod
    def get_position_report(date: date) -> dict:
        """
        Genera reporte de posición de cambio
        """
        base_currency = Currency.objects.get(is_base=True)
        accounts = ForexAccount.objects.all()

        position = {
            'date': date,
            'positions': [],
            'total_base_currency': Decimal('0.00')
        }

        for account in accounts:
            if account.currency != base_currency:
                balance_base = account.get_balance_base_currency(date)
                position['positions'].append({
                    'account': account.code,
                    'currency': account.currency.code,
                    'balance': account.balance,
                    'balance_base': balance_base
                })
                position['total_base_currency'] += balance_base

        return position

Tests Adicionales

# tests.py
class ForexServiceTests(TestCase):
    def setUp(self):
        # ... (setup anterior) ...

    def test_exchange_difference_calculation(self):
        """
        Verifica el cálculo correcto de la diferencia de cambio
        """
        # Crear tipos de cambio para diferentes fechas
        date1 = timezone.now().date()
        date2 = date1 + timedelta(days=1)

        ExchangeRate.objects.create(
            currency_from=self.usd,
            currency_to=self.pen,
            rate=Decimal('3.85'),
            date=date1
        )

        ExchangeRate.objects.create(
            currency_from=self.usd,
            currency_to=self.pen,
            rate=Decimal('3.90'),
            date=date2
        )

        # Establecer saldo en la cuenta
        self.account.balance = Decimal('1000.00')
        self.account.save()

        # Calcular diferencia de cambio
        difference = ForexService.calculate_exchange_difference(
            self.account,
            date1,
            date2
        )

        # La diferencia debería ser (3.90 - 3.85) * 1000 = 50
        self.assertEqual(difference, Decimal('50.00'))

    def test_position_report(self):
        """
        Verifica la generación correcta del reporte de posición
        """
        date = timezone.now().date()

        # Crear algunas cuentas con saldos
        ForexAccount.objects.create(
            currency=self.usd,
            code='1042',
            name='Otra cuenta USD',
            balance=Decimal('2000.00')
        )

        position = ForexReportService.get_position_report(date)

        self.assertEqual(len(position['positions']), 2)
        self.assertGreater(position['total_base_currency'], Decimal('0'))

Conclusión

Has aprendido a implementar un sistema robusto de control de cambios en Django que:

Maneja tipos de cambio y diferencias cambiarias
Implementa validaciones y seguridad
Proporciona reportes de posición de cambio
Es fácilmente extensible

Contabilidad para Django Developers: Implementando Asientos Contables

Enrique Lazo Bello — Sat, 09 Nov 2024 00:23:12 +0000

Introducción

Como desarrollador de Django, ¿alguna vez te has enfrentado al desafío de implementar un sistema contable y te has sentido abrumado por la terminología y los conceptos? No estás solo. La contabilidad puede parecer un mundo completamente diferente, pero en realidad tiene muchas similitudes con la programación.

Este tutorial te guiará paso a paso en la implementación de un sistema de asientos contables en Django, utilizando analogías familiares para desarrolladores. Aprenderás a manejar diferentes tipos de asientos contables (apertura, operativos, ajustes y cierre) de una manera que tenga sentido para tu mente de programador.

Al final de este tutorial, serás capaz de implementar un sistema contable robusto utilizando solo el admin de Django, con validaciones sólidas y pruebas automatizadas.

Prerrequisitos

Python 3.12
Django 5.0+
Conocimientos básicos de modelos en Django
Familiaridad con el admin de Django

Conceptos Clave

Asientos Contables = Transacciones en Base de Datos

Piensa en los asientos contables como transacciones en una base de datos:

Asiento de Apertura: Es como el initial migration de tus modelos
Asientos Operativos: Similar a los CRUD operations diarios
Asientos de Ajuste: Como un database cleanup script
Asientos de Cierre: Equivalente a un end-of-period backup

Implementación de Modelos

from django.db import models
from django.core.exceptions import ValidationError
from django.db.models import Sum
from decimal import Decimal
from enum import Enum
import datetime

class AsientoTipo(models.TextChoices):
    APERTURA = 'AP', 'Apertura'
    OPERATIVO = 'OP', 'Operativo'
    AJUSTE = 'AJ', 'Ajuste'
    CIERRE = 'CI', 'Cierre'

class Cuenta(models.Model):
    codigo = models.CharField(max_length=20, unique=True)
    nombre = models.CharField(max_length=100)
    es_deudora = models.BooleanField(
        help_text="True para cuentas que aumentan con débito"
    )

    def __str__(self):
        return f"{self.codigo} - {self.nombre}"

    class Meta:
        ordering = ['codigo']

class LibroContable(models.Model):
    año = models.PositiveIntegerField()
    esta_cerrado = models.BooleanField(default=False)

    class Meta:
        unique_together = ['año']

    def clean(self):
        if self.esta_cerrado:
            if Asiento.objects.filter(
                libro=self, 
                tipo=AsientoTipo.CIERRE
            ).count() == 0:
                raise ValidationError(
                    "No se puede cerrar un libro sin asiento de cierre"
                )

    def __str__(self):
        return f"Libro Contable {self.año}"

class Asiento(models.Model):
    libro = models.ForeignKey(LibroContable, on_delete=models.PROTECT)
    fecha = models.DateField()
    tipo = models.CharField(
        max_length=2,
        choices=AsientoTipo.choices,
        default=AsientoTipo.OPERATIVO
    )
    descripcion = models.TextField()

    def clean(self):
        self._validar_fecha()
        self._validar_tipo_asiento()
        self._validar_balance()

    def _validar_fecha(self):
        if self.fecha.year != self.libro.año:
            raise ValidationError(
                "La fecha debe corresponder al año del libro contable"
            )

    def _validar_tipo_asiento(self):
        if self.tipo == AsientoTipo.APERTURA:
            self._validar_apertura()
        elif self.tipo == AsientoTipo.CIERRE:
            self._validar_cierre()

    def _validar_apertura(self):
        if Asiento.objects.filter(
            libro=self.libro,
            tipo=AsientoTipo.APERTURA
        ).exclude(pk=self.pk).exists():
            raise ValidationError(
                "Ya existe un asiento de apertura para este libro"
            )

    def _validar_cierre(self):
        if Asiento.objects.filter(
            libro=self.libro,
            tipo=AsientoTipo.CIERRE
        ).exclude(pk=self.pk).exists():
            raise ValidationError(
                "Ya existe un asiento de cierre para este libro"
            )

    def _validar_balance(self):
        if hasattr(self, 'pk'):
            total_debe = Decimal('0')
            total_haber = Decimal('0')
            for detalle in self.detalles.all():
                total_debe += detalle.debe
                total_haber += detalle.haber
            if total_debe != total_haber:
                raise ValidationError(
                    "El asiento debe estar balanceado (debe = haber)"
                )

    def __str__(self):
        return f"{self.fecha} - {self.get_tipo_display()} - {self.descripcion[:50]}"

class DetalleAsiento(models.Model):
    asiento = models.ForeignKey(
        Asiento,
        related_name='detalles',
        on_delete=models.CASCADE
    )
    cuenta = models.ForeignKey(Cuenta, on_delete=models.PROTECT)
    debe = models.DecimalField(
        max_digits=15,
        decimal_places=2,
        default=0
    )
    haber = models.DecimalField(
        max_digits=15,
        decimal_places=2,
        default=0
    )

    def clean(self):
        if self.debe > 0 and self.haber > 0:
            raise ValidationError(
                "Un movimiento no puede tener debe y haber simultáneamente"
            )
        if self.debe == 0 and self.haber == 0:
            raise ValidationError(
                "El movimiento debe tener un valor en debe o haber"
            )

    class Meta:
        ordering = ['id']

Configuración del Admin

from django.contrib import admin
from django.db import models
from django.forms import ModelForm
from .models import LibroContable, Cuenta, Asiento, DetalleAsiento

class DetalleAsientoInline(admin.TabularInline):
    model = DetalleAsiento
    extra = 2
    min_num = 2

@admin.register(Asiento)
class AsientoAdmin(admin.ModelAdmin):
    list_display = ['fecha', 'tipo', 'descripcion', 'total_debe', 'total_haber']
    list_filter = ['tipo', 'libro']
    search_fields = ['descripcion']
    inlines = [DetalleAsientoInline]

    def total_debe(self, obj):
        return obj.detalles.aggregate(
            total=models.Sum('debe')
        )['total'] or 0

    def total_haber(self, obj):
        return obj.detalles.aggregate(
            total=models.Sum('haber')
        )['total'] or 0

@admin.register(Cuenta)
class CuentaAdmin(admin.ModelAdmin):
    list_display = ['codigo', 'nombre', 'es_deudora']
    search_fields = ['codigo', 'nombre']

@admin.register(LibroContable)
class LibroContableAdmin(admin.ModelAdmin):
    list_display = ['año', 'esta_cerrado']
    list_filter = ['esta_cerrado']

Tests Automatizados

from django.test import TestCase
from django.core.exceptions import ValidationError
from decimal import Decimal
from .models import LibroContable, Cuenta, Asiento, DetalleAsiento

class AsientoTests(TestCase):
    def setUp(self):
        self.libro = LibroContable.objects.create(año=2024)
        self.cuenta_caja = Cuenta.objects.create(
            codigo='1.1.1',
            nombre='Caja',
            es_deudora=True
        )
        self.cuenta_capital = Cuenta.objects.create(
            codigo='3.1.1',
            nombre='Capital',
            es_deudora=False
        )

    def test_asiento_apertura(self):
        asiento = Asiento.objects.create(
            libro=self.libro,
            fecha='2024-01-01',
            tipo=AsientoTipo.APERTURA,
            descripcion='Asiento de apertura'
        )

        DetalleAsiento.objects.create(
            asiento=asiento,
            cuenta=self.cuenta_caja,
            debe=Decimal('1000')
        )

        DetalleAsiento.objects.create(
            asiento=asiento,
            cuenta=self.cuenta_capital,
            haber=Decimal('1000')
        )

        asiento.full_clean()  # Debería validar sin errores

        # Intentar crear otro asiento de apertura
        with self.assertRaises(ValidationError):
            Asiento.objects.create(
                libro=self.libro,
                fecha='2024-01-01',
                tipo=AsientoTipo.APERTURA,
                descripcion='Segundo asiento de apertura'
            ).full_clean()

Ejemplo Real: Sistema de Transferencias

def realizar_transferencia(
    libro_id: int,
    fecha: str,
    cuenta_origen_id: int,
    cuenta_destino_id: int,
    monto: Decimal,
    descripcion: str
) -> Asiento:
    """
    Crea un asiento contable para una transferencia entre cuentas.
    """
    libro = LibroContable.objects.get(pk=libro_id)

    asiento = Asiento.objects.create(
        libro=libro,
        fecha=fecha,
        tipo=AsientoTipo.OPERATIVO,
        descripcion=descripcion
    )

    # Movimiento de salida
    DetalleAsiento.objects.create(
        asiento=asiento,
        cuenta_id=cuenta_origen_id,
        haber=monto
    )

    # Movimiento de entrada
    DetalleAsiento.objects.create(
        asiento=asiento,
        cuenta_id=cuenta_destino_id,
        debe=monto
    )

    asiento.full_clean()
    return asiento

Mejores Prácticas

Validaciones de Seguridad
- Implementar permisos por tipo de asiento
- Validar fechas y períodos contables
- Prevenir modificaciones en libros cerrados
Manejo de Errores
- Usar transacciones para operaciones atómicas
- Implementar rollback en caso de error
- Registrar auditoría de cambios
Patrones de Diseño
- Usar Factory Method para diferentes tipos de asientos
- Implementar Observer para notificaciones
- Aplicar Strategy para diferentes reglas contables

Conclusión

Has aprendido a implementar un sistema contable básico pero robusto en Django, utilizando solo el admin. Los conceptos clave que debes recordar son:

Los asientos contables son como transacciones en una base de datos
Las validaciones son cruciales para mantener la integridad de los datos
El admin de Django es suficiente para muchas operaciones contables

Contabilidad para Django Developers: Implementando Estados Financieros

Enrique Lazo Bello — Fri, 08 Nov 2024 23:49:12 +0000

Introducción

Como desarrollador Django, ¿alguna vez te has enfrentado al desafío de implementar un sistema contable y te has sentido abrumado por la terminología financiera? No estás solo. La contabilidad puede parecer un mundo completamente diferente a la programación, pero en realidad, comparte muchos conceptos similares a los que ya conoces.

En este tutorial, aprenderás a implementar un sistema de estados financieros utilizando Django y su potente admin interface, traduciendo conceptos contables a términos de programación que ya conoces. Por ejemplo, verás cómo un asiento contable es similar a una transacción en una base de datos, y cómo el principio de partida doble es comparable a mantener la integridad referencial.

Al final de este tutorial, serás capaz de implementar un sistema contable básico pero robusto, con validaciones automáticas y tests unitarios, todo desde el Django Admin.

Prerrequisitos

Python 3.12
Django 5.0
Conocimientos básicos de modelos Django y Django Admin
SQLite o PostgreSQL para la base de datos

Conceptos Clave

La Contabilidad desde una Perspectiva de Programador

Antes de sumergirnos en el código, vamos a establecer algunas analogías:

Balance General = Estado de la Aplicación
- Similar a cómo guardamos el estado de una aplicación
- Activo = Recursos (como RAM o espacio en disco)
- Pasivo = Recursos comprometidos (como procesos en background)
- Patrimonio = Recursos netos disponibles
Estado de Resultados = Logs de Operaciones
- Como un log de transacciones
- Ingresos = Datos entrantes
- Gastos = Recursos consumidos
- Utilidad = Resultado final del proceso

Implementación

Modelos Base

from django.db import models
from django.core.exceptions import ValidationError
from django.db.models import Sum
from decimal import Decimal
import uuid

class AccountType(models.TextChoices):
    ASSET = 'ASSET', 'Activo'
    LIABILITY = 'LIABILITY', 'Pasivo'
    EQUITY = 'EQUITY', 'Patrimonio'
    INCOME = 'INCOME', 'Ingreso'
    EXPENSE = 'EXPENSE', 'Gasto'

class Account(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    code = models.CharField(max_length=20, unique=True)
    name = models.CharField(max_length=100)
    type = models.CharField(max_length=10, choices=AccountType.choices)
    balance = models.DecimalField(max_digits=15, decimal_places=2, default=0)
    parent = models.ForeignKey(
        'self', 
        null=True, 
        blank=True, 
        on_delete=models.PROTECT,
        related_name='children'
    )
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        ordering = ['code']
        indexes = [
            models.Index(fields=['code']),
            models.Index(fields=['type']),
        ]

    def __str__(self):
        return f"{self.code} - {self.name}"

    def clean(self):
        if self.parent and self.parent.type != self.type:
            raise ValidationError('La cuenta padre debe ser del mismo tipo.')

    def save(self, *args, **kwargs):
        self.full_clean()
        super().save(*args, **kwargs)

    @property
    def calculated_balance(self):
        """Calcula el balance incluyendo subcuentas"""
        balance = self.balance
        for child in self.children.all():
            balance += child.calculated_balance
        return balance

class JournalEntry(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    date = models.DateField()
    description = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        verbose_name = 'Asiento Contable'
        verbose_name_plural = 'Asientos Contables'
        ordering = ['-date', '-created_at']

    def __str__(self):
        return f"Asiento #{self.id} - {self.date}"

    def clean(self):
        if hasattr(self, 'entries'):
            debits = sum(entry.debit for entry in self.entries.all())
            credits = sum(entry.credit for entry in self.entries.all())
            if debits != credits:
                raise ValidationError(
                    'Los débitos y créditos deben ser iguales.'
                )

    def save(self, *args, **kwargs):
        self.full_clean()
        super().save(*args, **kwargs)

class JournalEntryLine(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    entry = models.ForeignKey(
        JournalEntry,
        on_delete=models.CASCADE,
        related_name='entries'
    )
    account = models.ForeignKey(
        Account,
        on_delete=models.PROTECT,
        related_name='entries'
    )
    debit = models.DecimalField(max_digits=15, decimal_places=2, default=0)
    credit = models.DecimalField(max_digits=15, decimal_places=2, default=0)
    description = models.CharField(max_length=200, blank=True)

    class Meta:
        verbose_name = 'Línea de Asiento'
        verbose_name_plural = 'Líneas de Asiento'

    def clean(self):
        if self.debit < 0 or self.credit < 0:
            raise ValidationError(
                'Los valores no pueden ser negativos.'
            )
        if self.debit > 0 and self.credit > 0:
            raise ValidationError(
                'Una línea no puede tener débito y crédito simultáneamente.'
            )
        if self.debit == 0 and self.credit == 0:
            raise ValidationError(
                'Debe especificar un débito o un crédito.'
            )

    def save(self, *args, **kwargs):
        self.full_clean()

        # Actualizar balance de la cuenta
        if self._state.adding:  # Solo para nuevos registros
            if self.debit > 0:
                self.account.balance += self.debit
            else:
                self.account.balance -= self.credit
            self.account.save()

        super().save(*args, **kwargs)

Configuración del Admin

from django.contrib import admin
from django.db import models
from .models import Account, JournalEntry, JournalEntryLine

class AccountAdmin(admin.ModelAdmin):
    list_display = ['code', 'name', 'type', 'balance', 'parent']
    list_filter = ['type']
    search_fields = ['code', 'name']
    readonly_fields = ['balance']

class JournalEntryLineInline(admin.TabularInline):
    model = JournalEntryLine
    extra = 2
    fields = ['account', 'debit', 'credit', 'description']

class JournalEntryAdmin(admin.ModelAdmin):
    list_display = ['id', 'date', 'description', 'total_debit', 'total_credit']
    inlines = [JournalEntryLineInline]

    def total_debit(self, obj):
        return sum(line.debit for line in obj.entries.all())

    def total_credit(self, obj):
        return sum(line.credit for line in obj.entries.all())

admin.site.register(Account, AccountAdmin)
admin.site.register(JournalEntry, JournalEntryAdmin)

Tests Unitarios

from django.test import TestCase
from django.core.exceptions import ValidationError
from decimal import Decimal
from .models import Account, JournalEntry, JournalEntryLine

class AccountingTests(TestCase):
    def setUp(self):
        # Crear cuentas de prueba
        self.cash = Account.objects.create(
            code='1000',
            name='Caja',
            type='ASSET'
        )
        self.bank = Account.objects.create(
            code='1001',
            name='Banco',
            type='ASSET'
        )
        self.capital = Account.objects.create(
            code='3000',
            name='Capital',
            type='EQUITY'
        )

    def test_double_entry_principle(self):
        """Prueba el principio de partida doble"""
        entry = JournalEntry.objects.create(
            date='2024-01-01',
            description='Aporte inicial'
        )

        # Crear líneas de asiento
        JournalEntryLine.objects.create(
            entry=entry,
            account=self.cash,
            debit=Decimal('1000.00')
        )
        JournalEntryLine.objects.create(
            entry=entry,
            account=self.capital,
            credit=Decimal('1000.00')
        )

        # Verificar balances
        self.cash.refresh_from_db()
        self.capital.refresh_from_db()

        self.assertEqual(self.cash.balance, Decimal('1000.00'))
        self.assertEqual(self.capital.balance, Decimal('-1000.00'))

    def test_invalid_entry(self):
        """Prueba validaciones de asientos inválidos"""
        entry = JournalEntry.objects.create(
            date='2024-01-01',
            description='Asiento inválido'
        )

        with self.assertRaises(ValidationError):
            JournalEntryLine.objects.create(
                entry=entry,
                account=self.cash,
                debit=Decimal('-1000.00')  # Valor negativo
            )

Ejemplo Práctico: Sistema de Transferencias

1. Crear las Cuentas Base

Desde el admin de Django, crea las siguientes cuentas:

Activos
- Caja (1000)
- Banco (1001)
Pasivos
- Cuentas por Pagar (2000)
Patrimonio
- Capital (3000)
Ingresos
- Ventas (4000)
Gastos
- Gastos Operativos (5000)

2. Registrar una Transacción

Para registrar una venta en efectivo:

Crear nuevo JournalEntry
Fecha: La fecha de la transacción
Descripción: "Venta al contado"
Agregar líneas:
- Débito a Caja (1000) por $100
- Crédito a Ventas (4000) por $100

3. Verificar Balances

# Desde el shell de Django
from accounting.models import Account

# Verificar balance de caja
caja = Account.objects.get(code='1000')
print(f"Balance de caja: ${caja.balance}")

# Verificar balance de ventas
ventas = Account.objects.get(code='4000')
print(f"Balance de ventas: ${ventas.balance}")

Mejores Prácticas

Validaciones de Seguridad
- Usar transacciones de base de datos
- Implementar permisos granulares en el admin
- Mantener log de cambios
Manejo de Errores
- Validar balances negativos según tipo de cuenta
- Verificar referencias circulares en cuentas
- Implementar rollback en caso de error
Patrones de Diseño
- Usar Factory Method para crear asientos predefinidos
- Implementar Observer para actualizar balances
- Aplicar Command para operaciones complejas

Conclusión

Has aprendido a implementar un sistema contable básico usando Django y su admin interface. Los conceptos clave que debes recordar son:

La contabilidad es similar a mantener estado en tu aplicación
El principio de partida doble garantiza la integridad de los datos
Las validaciones automáticas previenen errores comunes

DEV Community: Enrique Lazo Bello

Matemáticas con Dados: cómo construí un juego para que mi niña aprenda a contar con dados y tapitas reales

Índice

1. La idea

2. La investigación: qué necesita un niño para aprender a contar

Contar no es recitar

De lo concreto a lo abstracto

Ver cantidades sin contar

Previsibilidad y transiciones

Atención y error

El adulto es parte del juego

3. Decisiones técnicas: por qué sin framework

La arquitectura en una imagen

Paso 0: carpetas y servidor local

Por qué no basta con abrir el archivo con doble clic

Paso 1: el HTML de las tres pantallas

Paso 2: la configuración

Paso 3: las reglas del juego (lógica pura)

Paso 4: probar las reglas antes de tener pantalla

Paso 5: el estado y las acciones

El problema de las tareas que esperan

Navegación y rondas

Los toques del niño, y la ayuda sin "no"

Paso 6: dibujar la pantalla

El dado: una grilla de 3×3

Las pantallas

Paso 7: conectar los clics

Paso 8: voz y sonidos sin archivos de audio

Paso 9: los estilos

Punto de control

Ejercicio: agrega Restar

Del prototipo al proyecto real

1. "Nunca pedir más tapitas de las que hay"

2. No confiar en localStorage

3. El teclado perdía su lugar en cada toque

4. Seguridad: una CSP estricta sin perder los colores

5. Privacidad: nada sale del dispositivo

6. Funcionar sin internet

7. Herramientas que cuidan el código

Publicarlo

Lo que aprendí

Glosario

Anexo: el CSS completo de la versión mínima

Matemáticas con Dados: how I built a game to help my little girl learn to count with dice and real bottle caps

Table of contents

1. The idea

2. The research: what a child needs to learn to count

Counting is not reciting

From concrete to abstract

Seeing quantities without counting

Predictability and transitions

Attention and mistakes

The adult is part of the game

3. Technical decisions: why no framework

The architecture in one picture

Step 0: folders and a local server

Why double-clicking the file isn't enough

Step 1: the HTML for the three screens

Step 2: configuration

Step 3: the game rules (pure logic)

Step 4: test the rules before there is a screen

Step 5: state and actions

The problem with tasks that wait

Navigation and rounds

The child's taps, and help without "no"

Step 6: drawing the screen

The die: a 3×3 grid

The screens

Step 7: wiring up the clicks

Step 8: voice and sounds without audio files

Want it to speak English?

Step 9: styles

Checkpoint

Exercise: add Subtract

From prototype to real project

1. "Never ask for more caps than there are"

2. Don't trust localStorage

3. The keyboard lost its place on every tap

4. Security: a strict CSP without losing the colors

5. Privacy: nothing leaves the device

2. No confiar en `localStorage`

2. Don't trust `localStorage`

El stream SSE: Máxima estabilidad con `StreamingResponse`