README

PUC (Plan Único de Cuentas) y CIIU (Clasificación Industrial Uniforme) colombianos para MoonShine 4.x.

Campos de búsqueda con autocompletado AJAX, árboles navegables jerárquicos y filtros para Resources de MoonShine. Datos oficiales del Decreto 2649/93 (PUC) y el DANE (CIIU).

Contenido

Requisitos
Instalación
Campos de búsqueda
- CuentaPucField
- ActividadCiiuField
Componentes árbol
- PucTreeComponent
- CiiuTreeComponent
Filtros para Resources
Modelos Eloquent
PUC Comercial vs ESAL
Información de los datos
Pruebas
Licencia

Requisitos

Dependencia	Versión mínima
PHP	8.3+
Laravel	11, 12 ó 13
MoonShine	4.x

Instalación

composer require jamesmosq/moonshine-colombia-puc-ciiu

Ejecutar migraciones y seeders:

php artisan migrate

# PUC oficial — 2.596 cuentas (Decreto 2649/93)
php artisan db:seed --class="MoonshineColumbia\PucCiiu\Database\Seeders\PucComercialSeeder"

# CIIU Colombia — 865 registros generados (DANE Rev. 4)
php artisan db:seed --class="MoonshineColumbia\PucCiiu\Database\Seeders\CiiuSeeder"

Los seeders son idempotentes: se pueden ejecutar varias veces sin duplicar datos.

Campos de búsqueda

CuentaPucField

Campo AJAX para seleccionar una cuenta del PUC. Muestra [código] nombre en el campo y guarda el código como string.

use MoonshineColumbia\PucCiiu\Fields\CuentaPucField;

// Uso básico — solo cuentas contabilizables (nivel ≥ 3, sin hijos)
CuentaPucField::make('Cuenta PUC', 'cuenta_puc')

// Permitir cualquier nivel (grupos, clases, subcuentas)
CuentaPucField::make('Cuenta', 'cuenta')->permitirTodosLosNiveles()

// Solo gastos e ingresos (clases 4 y 5)
CuentaPucField::make('Cuenta', 'cuenta')->filtroPorClase([4, 5])

// Plan ESAL (entidades sin ánimo de lucro)
CuentaPucField::make('Cuenta', 'cuenta')->filtroPorTipo('esal')

Muestra: [1105] Caja
Guarda: "1105" (string)
Evento Alpine al seleccionar: puc-selected → { value, label, node }

ActividadCiiuField

Campo AJAX para seleccionar una actividad económica CIIU. Por defecto solo permite seleccionar clases (4 dígitos).

use MoonshineColumbia\PucCiiu\Fields\ActividadCiiuField;

// Uso básico — solo clases de 4 dígitos
ActividadCiiuField::make('Actividad económica', 'actividad_ciiu')

// Permitir secciones, divisiones y grupos también
ActividadCiiuField::make('Actividad', 'actividad')->permitirTodosLosNiveles()

// Restringir a una sección (ej: C = Industrias manufactureras)
ActividadCiiuField::make('Actividad', 'actividad')->filtroPorSeccion('C')

Muestra: [0111] Cultivo de cereales
Evento Alpine: ciiu-selected → { value, label, node }

Componentes árbol

Los árboles cargan cada nivel de forma lazy al expandir, lo que los hace eficientes incluso con el PUC completo.

PucTreeComponent

use MoonshineColumbia\PucCiiu\Components\PucTreeComponent;

// En un IndexPage o CustomPage de MoonShine
protected function components(): array
{
    return [
        // Árbol completo PUC comercial
        PucTreeComponent::make(),

        // Plan ESAL con título personalizado
        PucTreeComponent::make(
            tipo: 'esal',
            titulo: 'Plan de Cuentas ESAL'
        ),

        // Conectado a un campo — el botón "Seleccionar" rellena el campo
        PucTreeComponent::make(targetField: 'cuenta_puc'),
    ];
}

Características:

Íconos D (débito) y C (crédito) en cada nodo
Filtro rápido sobre nodos ya expandidos
Botón "Seleccionar" al pasar el mouse, solo en cuentas hoja
Emite evento Alpine puc-selected (o puc-selected:{targetField})
Soporte dark mode

CiiuTreeComponent

use MoonshineColumbia\PucCiiu\Components\CiiuTreeComponent;

protected function components(): array
{
    return [
        // Árbol CIIU completo (22 secciones)
        CiiuTreeComponent::make(),

        // Solo la sección C — Industrias manufactureras
        CiiuTreeComponent::make(seccion: 'C'),

        // Conectado a un campo
        CiiuTreeComponent::make(targetField: 'actividad_ciiu'),
    ];
}

Jerarquía CIIU:

Sección A — Agricultura, ganadería…
  └─ División 01
       └─ Grupo 011
            ├─ Clase 0111 — Cultivo de cereales    [Seleccionar]
            └─ Clase 0112 — Cultivo de arroz        [Seleccionar]

Filtros para Resources

Usar en el método filters() de cualquier Resource de MoonShine.

use MoonshineColumbia\PucCiiu\Filters\ClasePucFilter;
use MoonshineColumbia\PucCiiu\Filters\NaturalezaFilter;
use MoonshineColumbia\PucCiiu\Filters\SeccionCiiuFilter;

// Resource de movimientos contables
class MovimientoResource extends ModelResource
{
    protected function filters(): array
    {
        return [
            ClasePucFilter::make('Clase de cuenta'),
            NaturalezaFilter::make('Naturaleza'),
        ];
    }
}

// Resource de empresas
class EmpresaResource extends ModelResource
{
    protected function filters(): array
    {
        return [
            // Opciones fijas (21 secciones A–U, sin consulta a BD)
            SeccionCiiuFilter::make('Sección CIIU'),

            // Opciones dinámicas desde la tabla actividades_ciiu
            SeccionCiiuFilter::make('Sección CIIU')->fromDb(),
        ];
    }
}

Filtro	Columna por defecto	Opciones
`ClasePucFilter`	`clase`	1–9 con nombre de cada clase
`NaturalezaFilter`	`naturaleza`	`debito` / `credito`
`SeccionCiiuFilter`	`seccion`	A–U (21 secciones CIIU)

Todos los filtros son nullable (incluyen opción "Todos") y aceptan columna personalizada:

ClasePucFilter::make('Clase', 'cuenta_clase')
NaturalezaFilter::make('Naturaleza', 'cuenta_naturaleza')

Modelos Eloquent

CuentaPuc

use MoonshineColumbia\PucCiiu\Models\CuentaPuc;

// Scopes disponibles
CuentaPuc::comercial()          // tipo = 'comercial'
CuentaPuc::esal()               // tipo = 'esal'
CuentaPuc::byClase(5)           // clase = 5 (Gastos)
CuentaPuc::byClase([4, 5])      // clase IN (4, 5)
CuentaPuc::byNivel(3)           // nivel = 3 (Cuentas)
CuentaPuc::hojas()              // sin hijos, nivel >= 3
CuentaPuc::activas()            // activa = true

// Relaciones
$cuenta->padre               // CuentaPuc padre
$cuenta->hijos               // Collection de cuentas hijas

// Atributo calculado
$cuenta->path                // "Activo > Disponible > Caja"

Jerarquía PUC:

Nivel	Nombre	Dígitos	Ejemplo
1	Clase	1	`1` — Activos
2	Grupo	2	`11` — Disponible
3	Cuenta	4	`1105` — Caja
4	Subcuenta	6	`110505` — Caja General
5	Auxiliar	8+	`11050501`

Naturaleza: clases 1, 5, 6, 7 → débito · clases 2, 3, 4, 8, 9 → crédito

ActividadCiiu

use MoonshineColumbia\PucCiiu\Models\ActividadCiiu;

// Scopes disponibles
ActividadCiiu::bySeccion('A')       // sección A — Agricultura
ActividadCiiu::byNivel('clase')     // nivel = 'clase' (4 dígitos)
ActividadCiiu::hojas()              // solo clases (nivel = 'clase')
ActividadCiiu::activas()            // activa = true

// Relaciones
$actividad->padre            // ActividadCiiu padre
$actividad->hijos            // Collection de hijos

// Atributo calculado
$actividad->path             // "Agricultura… > División 01 > Grupo 011 > Cultivo de cereales"

PUC Comercial vs ESAL

PUC Comercial (Decreto 2649 de 1993)

Plan estándar para empresas con ánimo de lucro. Cargado por defecto con PucComercialSeeder. Cubre 9 clases, 52 grupos, 356 cuentas y 2.179 subcuentas.

PUC ESAL (Decreto 4400 de 2004)

Plan para Entidades Sin Ánimo de Lucro: fundaciones, asociaciones, corporaciones y cooperativas. Adapta el PUC comercial para:

Fondos sociales y patrimoniales (clase 3 ampliada)
Ingresos no constitutivos de renta
Cuentas de excedentes y déficit del ejercicio
Vigencias fiscales especiales

Para activar el PUC ESAL:

Crea el archivo puc_esal.json con el mismo formato que puc_colombia.json
Cópialo a packages/moonshine-colombia-puc/database/seeders/data/puc_esal.json
Ejecuta el seeder:

php artisan db:seed --class="MoonshineColumbia\PucCiiu\Database\Seeders\PucEsalSeeder"

Usa el campo con el tipo ESAL:

CuentaPucField::make('Cuenta ESAL', 'cuenta')->filtroPorTipo('esal')

Información de los datos

PUC Colombia

Campo	Detalle
Base legal	Decreto 2649 de 1993 y sus modificaciones
Registros incluidos	2.596 (niveles 1 a 4)
Actualización	Manual — conforme al decreto vigente
Licencia de los datos	Dominio público (norma oficial colombiana)

CIIU Colombia

Campo	Detalle
Fuente	DANE — Clasificación Industrial Uniforme Rev. 4
Registros generados	~865 (22 secciones + 89 divisiones + 250 grupos + 504 clases)
Licencia de los datos	Dominio público (estadística oficial del DANE)

Pruebas

php artisan test

La suite incluye 91 tests / 150 assertions sobre SQLite en memoria:

Grupo	Tests	Qué cubre
PUC Feature	23	Seeder, modelo, scopes, relaciones, endpoints
CIIU Feature	19	Seeder, modelo, scopes, relaciones, endpoints
Componentes árbol	11	Instanciación, `make()`, propiedades
Filtros y Campos	22	Instanciación MoonShine, columnas, nullable
Opciones estáticas (Unit)	15	Arrays de filtros sin depender de MoonShine
Base Laravel	2	Ejemplo incluido por defecto

Licencia

MIT — ver LICENSE.

Los datos del PUC y el CIIU son de dominio público por ser normas y estadísticas oficiales de la República de Colombia.

jamesmosq / moonshine-colombia-puc-ciiu

Maintainers

Package info

Statistics

Security