-- =============================================================================
-- Migración:    0003_create_permissions_table
-- Sprint:       1.1 — auth + RBAC + audit
-- Tabla:        permissions
-- Aplica en:    BD de cada tenant (innovium_<slug>)
-- Dependencias: ninguna.
--
-- Descripción:
--   Permisos granulares del sistema (verbos sobre módulos).
--   Convención de slug: "<modulo>.<accion>", ej: "contratos.crear",
--   "cobranzas.exportar". Se chequean con Auth::can('contratos.crear').
--
--   En Sprint 1.1 se siembran ~25 permisos iniciales. Más adelante
--   cada sprint agregará los suyos en migraciones futuras (no acá).
--
-- Notas:
--   - categoria: agrupa permisos por módulo en pantallas de admin
--     (ej: "contratos", "cobranzas", "usuarios", "reportes", "tenant").
--   - actualizado_en presente por consistencia con la convención global
--     de CLAUDE.md: TODAS las tablas tienen creado_en y actualizado_en.
-- =============================================================================

CREATE TABLE permissions (
    id             BIGINT UNSIGNED NOT NULL AUTO_INCREMENT
                   COMMENT 'PK auto-incremental del permiso.',
    slug           VARCHAR(100)    NOT NULL
                   COMMENT 'Slug único usado en Auth::can() (ej: "contratos.crear").',
    nombre         VARCHAR(150)    NOT NULL
                   COMMENT 'Nombre legible para UI de admin (ej: "Crear contrato").',
    categoria      VARCHAR(50)     NOT NULL
                   COMMENT 'Módulo al que pertenece. Agrupa en UI (ej: "contratos").',
    descripcion    TEXT                NULL
                   COMMENT 'Texto explicativo del permiso, opcional.',
    creado_en      DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP
                   COMMENT 'UTC de creación. Inmutable.',
    actualizado_en DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP
                                            ON UPDATE CURRENT_TIMESTAMP
                   COMMENT 'UTC de la última edición. Auto-actualizado por MySQL.',
    PRIMARY KEY (id),
    UNIQUE KEY uq_permissions_slug (slug),
    KEY idx_permissions_categoria (categoria)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
  COMMENT='Permisos granulares del sistema (verbos sobre módulos), chequeados por Auth::can().';