my-module — un módulo de Convive

Plantilla mínima para crear un módulo de Convive.

Uso

1. Click en Use this template en GitHub para crear tu propio repo (recomendado: nombrarlo convive-module-<id>).
2. Edita module.json con tu id, name, version, description.
3. Ajusta las migraciones en migrations/ (recuerda IF NOT EXISTS).
4. Implementa tus rutas en routes/.
5. Crea un tag vX.Y.Z y pushea: el workflow de release generará el tarball y lo publicará automáticamente.

Instalación en Convive

Una vez publicado el primer release:

• Desde la UI: /settings/modules → pestaña Origen personalizado → introducir tu-usuario/convive-module-<id> → Instalar.
• Desde la CLI: docker compose exec server npm run module:install -- tu-usuario/convive-module-<id>.

Estructura

.
├── module.json           ← manifiesto (id, version, depends, convive)
├── index.js              ← entrypoint con register(ctx)
├── migrations/           ← .sql aplicados al cargar el módulo
└── routes/               ← Express routers, factories que reciben ctx

Plugin API

Tu register(ctx) recibe:

Campo	Uso
ctx.db, ctx.tx	acceso a SQLite del núcleo
ctx.router	Express router montado en /api/m/<id>
ctx.mountAsLegacy(['/api/foo'])	rutas adicionales para compatibilidad
ctx.registerMigrations(dir)	aplicar las .sql del módulo
ctx.registerCron(spec, fn)	tarea programada con node-cron
ctx.auth.authRequired, ctx.auth.householdScope, ctx.auth.requireRole(...)	middleware
ctx.utils.asyncHandler/validate/toCamel/errors	helpers
ctx.notify, ctx.notifyHousehold	notificaciones
ctx.exports, ctx.useModule(otherId)	compartir código entre módulos
ctx.logger	log con prefijo del módulo

Reglas

• Las migraciones deben ser idempotentes (CREATE TABLE IF NOT EXISTS, INSERT … WHERE NOT EXISTS). Si el usuario reinstala tu módulo, sus datos no deben perderse.
• No accedas a tablas de otros módulos a menos que declares depends.
• No subas archivos generados al repo: el workflow de release los crea.

Licencia

MIT — usa lo que quieras como base.