Etapa 0: capa de persistencia de ediciones de mapa

[leocagli]

Parte de #2 (modo construcción). Esta issue desbloquea todas las demás.

Problema

Los mapas son archivos estáticos en disco. api/src/lib/mapNpcStorage.ts sólo expone lectura:

listAvailableMapIds()      // fs.readdir
loadMapNpcPlacements()     // fs.readFile
loadAllMapNpcPlacements()

No hay ninguna ruta de escritura de mapas en todo el repo. Sin una capa de persistencia, cualquier editor visual no tiene dónde guardar.

Enfoque propuesto

No inventar un mecanismo nuevo. Extender el que ya funciona para el resto del game data:

• Tabla game_data_revisions con columnas kind, entity_id, action, checksum
• Repositorios en api/src/repositories/ (ver gameObjects.ts, gameNpcs.ts como referencia)
• El server hidrata desde la DB al arrancar y reporta versión aplicada

Los mapas serían un kind más dentro de ese esquema.

Alcance

1. Tablas nuevas para mapas editados. Sugerencia de punto de partida:
   • game_maps (metadata por mapa: id, nombre, terreno, zona, pk, etc.)
   • game_map_tiles (grilla: mapa, x, y, entrada de paleta, bloqueado)
   • game_map_palette (paleta por mapa: clave, capas de gráficos, bloqueado)
2. Importador que cargue los 294 mapas de api/src/mapas_source/ a la DB, idempotente (se puede correr de nuevo sin duplicar).
3. Lectura con precedencia: si el mapa existe en DB se usa esa versión, si no se cae al archivo. Así nada se rompe mientras la migración es parcial.
4. Registrar cada edición en game_data_revisions.

Criterios de aceptación

• Los 294 mapas se importan a la DB y el juego sigue funcionando igual que antes
• Correr el importador dos veces no duplica ni corrompe datos
• Un mapa editado en DB se sirve desde DB; uno no editado se sigue sirviendo desde archivo
• Cada edición deja registro en game_data_revisions con su checksum
• Tests de integración en api/src/tests/ (ya hay 11 ahí como referencia de estilo)

Archivos relevantes

• api/src/lib/mapNpcStorage.ts (hoy sólo lectura)
• api/src/mapas_source/mapa_<n>/ (294 mapas: meta.json, terrain.json, npcs.json, specials.json)
• api/src/repositories/gameObjects.ts, gameNpcs.ts (patrón a seguir)
• api/schema.sql

Notas

Vale la pena decidir temprano si la grilla se guarda fila por fila o como documento JSON por mapa. Son 100x100 = 10.000 tiles por mapa y 294 mapas: 2,9 millones de filas si se hace tile por tile. Medir antes de comprometerse.

[leafwithered]

Revisé el main actual (c2765df) antes de postularme. El PR #33 ya agregó game_map_tile_overrides para cambios puntuales, pero #3 sigue teniendo un alcance distinto y necesario: todavía no existe una representación canónica de los 294 mapas en DB, un importador idempotente del directorio mapas_source, precedencia DB→archivo ni revisiones de tipo mapa en game_data_revisions.

Mi propuesta es evitar 2,9 millones de filas por tile y guardar una unidad canónica por mapa en JSONB (metadata + terrain/palette + NPCs + specials), con checksum estable y campos de versión/autoría. Haría el import por lotes dentro de transacciones, usando upsert sólo cuando cambie el checksum, de modo que una segunda ejecución sea realmente idempotente. La lectura consultaría primero DB y conservaría el fallback actual a archivos para migración parcial.

Los tests de integración cubrirían: importación de los 294 mapas, segunda ejecución sin duplicados ni revisiones espurias, precedencia de un mapa editado en DB, fallback de un mapa aún no importado y registro del checksum/revisión tras una edición. También mediría el tamaño y tiempo de importación para documentar por qué se eligió JSONB por mapa frente a una fila por tile.

Puedo entregar un PR enfocado dentro de 4 días desde la asignación. No empezaré una implementación paralela antes de la asignación formal, para evitar trabajo duplicado.

Evidence used:

• Current source inspected locally at c2765df.
• Existing game_data_revisions pattern reviewed in gameObjects.ts and gameNpcs.ts.
• Existing sparse override schema reviewed in api/schema.sql.
• Existing file fallback path reviewed in api/src/lib/mapNpcStorage.ts.

[YospGeng]

Me postulo para #3. Revisé api/src/lib/mapNpcStorage.ts, api/src/repositories/gameObjects.ts y server/src/mapNpcStorage.ts. Además del modelo de almacenamiento, hay dos casos que protegería explícitamente: una importación parcial y un mapa válido de DB cuya lista de NPCs esté vacía. Este último no debe volver a cargar los NPCs del archivo por tratar [] como “mapa ausente”.

Propuesta concreta:

• Añadir un repositorio api/src/repositories/gameMaps.ts y la migración correspondiente en api/schema.sql, con una fila JSONB canónica por mapa y checksum/versionado; conservar game_map_tile_overrides y su separación draft/published, sin materializar millones de filas por tile.
• Añadir un importador por ID de mapa. No copiaría el atajo global COUNT(*) > 0 de ensureSeededInternal(): dejaría incompleta una migración parcial. La importación inicial insertaría los IDs ausentes y no sobrescribiría mapas ya editados en DB. Una repetición no generaría revisiones adicionales.
• Resolver DB→archivo por existencia del registro, no por si contiene NPCs/tiles; revisar tanto el lector del API como el del servidor para que no diverjan.
• Ampliar el CHECK actual de game_data_revisions.kind para admitir maps, y escribir contenido, checksum y revisión dentro de la misma transacción, siguiendo insertRevision().

Verificación propuesta con PostgreSQL de pruebas: los 294 mapas y equivalencia de sus datos; segunda importación sin duplicados ni revisiones nuevas; completar una importación parcial conservando una edición previa; mapa DB con NPCs vacíos; fallback sólo para un ID ausente; rollback atómico ante un fallo de escritura. Mediría tamaño y tiempo de importación antes de cerrar la elección de JSONB.

Es una revisión de código y un plan asistidos por Codex, no una implementación ni pruebas ya ejecutadas. Solicito asignación antes de abrir un PR, conforme a CONTRIBUTING.md. ¿Pueden indicar también la entrada vigente de GrantFox y los requisitos de inscripción/aceptación para la etiqueta reward-100-usd? Entiendo que la etiqueta no garantiza un premio y que el pago se gestiona exclusivamente en la plataforma.

[AydinGuney428]

Me gustaría postularme para esta bounty. Revisé el main actual antes de proponer una implementación, incluyendo api/src/lib/mapNpcStorage.ts, server/src/mapNpcStorage.ts, api/src/repositories/gameObjects.ts y el cambio introducido por PR #33.

Veo un punto importante que conviene resolver sin duplicar modelos: #33 ya introdujo game_map_tile_overrides y documenta explícitamente que los mapas base siguen en disco y que la DB guarda sólo diferencias por tile. Por eso no propondría crear 2,9M+ filas de tiles ni una segunda representación incompatible de esas ediciones.

Mi propuesta concreta sería:

• añadir una representación canónica por mapa para los datos que sí necesitan precedencia DB→archivo, usando una fila JSONB/checksum/version por map_num o, si se prefiere mantener el modelo sparse de feat(modo-construccion): subir PNG y pintarlos en el mapa, con borrador y revertir #33, limitar esa fila a metadata + NPC/specials/terrain/palette no cubiertos por overrides;
• importar por ID de mapa, no con un COUNT(*) > 0 global como hace hoy ensureSeededInternal() en gameObjects.ts, porque ese patrón deja una migración parcial permanentemente incompleta;
• hacer el import idempotente por checksum: insertar sólo IDs ausentes y no generar revisiones nuevas en una segunda ejecución si el contenido no cambió;
• resolver existencia del mapa en DB por presencia del registro, no por array.length ni por contenido truthy. Un mapa DB válido con npcs: [] debe seguir siendo autoritativo y no caer al archivo accidentalmente;
• mantener coherencia entre el lector del API y server/src/mapNpcStorage.ts. Hoy ambos leen archivos por separado y el servidor además tiene escritura directa a mapas_source; dejar sólo uno con precedencia DB produciría comportamiento distinto entre API y runtime;
• registrar la revisión y el checksum dentro de la misma transacción que actualiza el mapa, siguiendo el patrón de insertRevision() de gameObjects.ts, y extender game_data_revisions.kind para mapas sin crear un segundo sistema de versionado;
• conservar game_map_tile_overrides de feat(modo-construccion): subir PNG y pintarlos en el mapa, con borrador y revertir #33 y su separación draft/published, en lugar de reemplazarla.

Tests de integración que entregaría:

1. importación completa de los 294 mapas;
2. segunda importación sin duplicados ni revisiones espurias;
3. importación parcial que completa sólo IDs faltantes;
4. una edición previa en DB que no es sobrescrita por el seed/import;
5. mapa existente en DB con npcs: [] que NO hace fallback al archivo;
6. mapa ausente en DB que sí cae al archivo;
7. revisión/checksum creados atómicamente al editar;
8. equivalencia de lectura API/runtime para el mismo mapa.

También mediría tamaño y tiempo del import para dejar documentada la decisión JSONB/canónico-vs-sparse en vez de asumirla.

Puedo preparar un PR enfocado una vez asignada la issue, para evitar trabajo duplicado con los otros postulantes.

[AydinGuney428]

Me gustaría postularme para esta bounty. Revisé el main actual antes de proponer una implementación, incluyendo api/src/lib/mapNpcStorage.ts, server/src/mapNpcStorage.ts, api/src/repositories/gameObjects.ts y el cambio introducido por PR #33.

Veo un punto importante que conviene resolver sin duplicar modelos: #33 ya introdujo game_map_tile_overrides y documenta explícitamente que los mapas base siguen en disco y que la DB guarda sólo diferencias por tile. Por eso no propondría crear 2,9M+ filas de tiles ni una segunda representación incompatible de esas ediciones.

Mi propuesta concreta sería:

• añadir una representación canónica por mapa para los datos que sí necesitan precedencia DB→archivo, usando una fila JSONB/checksum/version por map_num o, si se prefiere mantener el modelo sparse de feat(modo-construccion): subir PNG y pintarlos en el mapa, con borrador y revertir #33, limitar esa fila a metadata + NPC/specials/terrain/palette no cubiertos por overrides;
• importar por ID de mapa, no con un COUNT(*) > 0 global como hace hoy ensureSeededInternal() en gameObjects.ts, porque ese patrón deja una migración parcial permanentemente incompleta;
• hacer el import idempotente por checksum: insertar sólo IDs ausentes y no generar revisiones nuevas en una segunda ejecución si el contenido no cambió;
• resolver existencia del mapa en DB por presencia del registro, no por array.length ni por contenido truthy. Un mapa DB válido con npcs: [] debe seguir siendo autoritativo y no caer al archivo accidentalmente;
• mantener coherencia entre el lector del API y server/src/mapNpcStorage.ts. Hoy ambos leen archivos por separado y el servidor además tiene escritura directa a mapas_source; dejar sólo uno con precedencia DB produciría comportamiento distinto entre API y runtime;
• registrar la revisión y el checksum dentro de la misma transacción que actualiza el mapa, siguiendo el patrón de insertRevision() de gameObjects.ts, y extender game_data_revisions.kind para mapas sin crear un segundo sistema de versionado;
• conservar game_map_tile_overrides de feat(modo-construccion): subir PNG y pintarlos en el mapa, con borrador y revertir #33 y su separación draft/published, en lugar de reemplazarla.

Tests de integración que entregaría:

1. importación completa de los 294 mapas;
2. segunda importación sin duplicados ni revisiones espurias;
3. importación parcial que completa sólo IDs faltantes;
4. una edición previa en DB que no es sobrescrita por el seed/import;
5. mapa existente en DB con npcs: [] que NO hace fallback al archivo;
6. mapa ausente en DB que sí cae al archivo;
7. revisión/checksum creados atómicamente al editar;
8. equivalencia de lectura API/runtime para el mismo mapa.

También mediría tamaño y tiempo del import para dejar documentada la decisión JSONB/canónico-vs-sparse en vez de asumirla.

Puedo preparar un PR enfocado una vez asignada la issue, para evitar trabajo duplicado con los otros postulantes.

[ranjeet150]

Hi there,

I would like to resolve this issue. Here is my proposed execution plan:

• Implementation: Provide a structured solution for Etapa 0: capa de persistencia de ediciones de mapa addressing all stated requirements.
• Testing: Ensure the change passes all existing lint, format, and CI verification pipelines.

Excited to work on this—please assign to me and I will submit a clean PR shortly!

[suixincc]

/opire try