CattleWiz Commons Library

Biblioteca de clases compartidas para las plataformas Web (Angular) y Móvil (Ionic/Angular) de CattleWiz.

📋 Descripción

Esta biblioteca contiene modelos de datos, utilidades y tipos TypeScript compartidos entre las aplicaciones web y móvil de CattleWiz, eliminando la duplicación de código y garantizando consistencia entre plataformas.

✅ Estado Actual

Fase 1: Modelos Base (Completada)

• ✅ Tipos de datos básicos (id.model.ts)

  • Tipo ID para identificadores únicos

• ✅ Soporte multiidioma (lang-string.model.ts)

  • Tipo LangString para cadenas traducibles
  • Funciones createLangString() y langStringToString()

• ✅ Datos geográficos (country.model.ts, state.model.ts)

  • Lista completa de países con códigos ISO
  • Estados de México y USA
  • Funciones de búsqueda y filtrado

• ✅ Modelos de negocio

  • ContactMessage - Mensajes de contacto
  • CreateTicket, TicketStatus - Sistema de tickets
  • Member, Membership, Account, Profile, Preferences - Datos de usuario

• ✅ Interfaces compartidas (interfaces.model.ts)

  • Interfaces para consultas de reportes
  • Parámetros del wizard
  • Posicionamiento y enlaces

Fase 2: Modelos del Wizard (Completada)

• ✅ Modelos de reportes analíticos (analytical-report-catalog.model.ts)

  • AnalyticalReportCatalog - Catálogo de reportes
  • AnalyticalReportTag - Tags jerárquicos del wizard
  • AnalyticalReportField - Campos de datos
  • AnalyticalReportFieldValueType - Tipos de valores

• ✅ Navegación del wizard (analytical-report-group.model.ts)

  • AnalyticalReportGroup - Gestión de navegación multinivel
  • Métodos para seleccionar/deseleccionar tags
  • Obtención de tags por nivel jerárquico

• ✅ Consultas de reportes (analytical-report-query.model.ts)

  • AnalyticalReportQuery - Consultas parametrizadas
  • AnalyticalReportQueryMetric - Métricas de consulta
  • AnalyticalReportQueryFilters - Filtros aplicables

• ✅ Utilidades del wizard (wizard-utilities.ts)

  • MENU_CONFIGURATION - Configuración de menú
  • Funciones de conversión entre pasos y parámetros
  • Utilidades de iconos y clases CSS

Fase 3: Servicios (Completada)

• ✅ Servicio de grupos de reportes (analytical-report-groups.service.ts)

  • getRootTag() - Obtiene el árbol completo de navegación
  • getTagsByParent() - Obtiene tags hijos
  • getTagByKey() - Busca un tag específico

• ✅ Servicio de reportes analíticos (analytical-reports.service.ts)

  • getMeasurements() - Obtiene mediciones disponibles
  • getMeasurement() - Obtiene detalles de una medición
  • getReportData() - Obtiene datos para visualización
  • getCatalogs() - Obtiene catálogos de reportes

• ✅ Servicio de navegación del wizard (wizard-navigation.service.ts)

  • Gestión de estado con RxJS
  • initialize() - Inicializa desde parámetros URL
  • selectTag() / unselectTag() - Navegación jerárquica
  • loadMeasurements() - Carga automática de mediciones
  • getQueryParams() - Obtiene parámetros actuales
  • Observable state$ para reactividad

Fase 4: Pipes (Completada)

• ✅ LangStringPipe (lang-string.pipe.ts)

  • Transforma LangString a texto según idioma
  • Soporte para LOCALE_ID de Angular
  • Pipe standalone reutilizable

• ✅ QueryStringPipe (query-string.pipe.ts)

  • Serializa objetos a query strings
  • Codificación automática de valores
  • Soporte para arrays

Fase 5: Tests Unitarios (Completada)

• ✅ 67 tests pasando con cobertura de:
  • AnalyticalReportGroup - 31 tests
  • wizard-utilities - 31 tests
  • Funciones LangString - 5 tests
  • Framework Jest configurado

📦 Instalación

npm install @gamariverib/mercados-pecuarios-libs-cattlewiz-commons

🚀 Uso

Importación en TypeScript

// Importar tipos y funciones específicas
import { ID, LangString, langStringToString } from '@gamariverib/mercados-pecuarios-libs-cattlewiz-commons';

// Importar modelos de países
import { Country, getCountry, getAllCountries } from '@gamariverib/mercados-pecuarios-libs-cattlewiz-commons';

// Importar modelos de usuario
import { Member, Membership } from '@gamariverib/mercados-pecuarios-libs-cattlewiz-commons';

Ejemplos de uso

Trabajar con países

import { getCountry, getAllCountries } from '@gamariverib/mercados-pecuarios-libs-cattlewiz-commons';

// Buscar un país por código ISO2
const mexico = getCountry('MX');
console.log(mexico.name); // "México"

// Buscar por código ISO3
const usa = getCountry('USA');

// Obtener todos los países
const allCountries = getAllCountries();

Trabajar con estados

import { getAllStatesByCountry, getStateByCountry } from '@gamariverib/mercados-pecuarios-libs-cattlewiz-commons';

// Obtener todos los estados de México
const mexicoStates = getAllStatesByCountry('mx');

// Buscar un estado específico
const jalisco = getStateByCountry('mx', 'JAL');
console.log(jalisco.name); // "Jalisco"

Soporte multiidioma

import { LangString, langStringToString, createLangString } from '@gamariverib/mercados-pecuarios-libs-cattlewiz-commons';

// Crear un texto multiidioma
const greeting: LangString = {
  en: 'Hello',
  es: 'Hola',
  mx: 'Hola'
};

// Obtener el texto en un idioma específico
const spanishGreeting = langStringToString(greeting, 'es'); // "Hola"

// Si el idioma no existe, retorna el primero disponible
const fallback = langStringToString(greeting, 'fr'); // "Hello"

Trabajar con reportes analíticos (Wizard)

import { 
  AnalyticalReportGroup,
  AnalyticalReportTag,
  getStepsFromParams,
  getParamsFromSteps
} from '@gamariverib/mercados-pecuarios-libs-cattlewiz-commons';

// Crear un grupo de reportes desde parámetros de URL
const rootTag: AnalyticalReportTag = {
  key: 'root',
  name: { en: 'Reports' },
  orderIndex: 0,
  restrictedValues: false,
  allowedValues: [/* ... */]
};

const steps = getStepsFromParams({
  reference: 'value-chain',
  scope: 'national',
  link: 'livestock'
});

const group = AnalyticalReportGroup.loadFromParams(rootTag, steps);

// Navegar por niveles
const referenceTag = group.getReferenceTag();
const countryTag = group.getCountryOrScopeTag();
const commodityTag = group.getLinkOrCommodityTag();

// Obtener la ruta de navegación
console.log(group.getPath()); // "root > value-chain > national > livestock"

// Verificar si es el último nivel
if (group.isLastLevel) {
  console.log('Listo para mostrar el reporte');
}

// Convertir de vuelta a parámetros
const params = getParamsFromSteps(group.items);

Utilidades del wizard

import { 
  MENU_CONFIGURATION,
  getReferenceCardClass,
  getReferenceIcon,
  getQueryFromParams
} from '@gamariverib/mercados-pecuarios-libs-cattlewiz-commons';

// Obtener la clase CSS de una referencia
const cardClass = getReferenceCardClass('value-chain'); // "bg-reference-value-chain"

// Obtener el ícono configurado
const icon = getReferenceIcon('futures');
if (icon.type === 'image') {
  console.log(icon.value); // "../assets/icons/color/futures.png"
}

// Convertir parámetros a query string
const queryString = getQueryFromParams({
  reference: 'weather',
  scope: 'national'
}); // "reference=weather&scope=national"

Usar servicios

import { 
  AnalyticalReportGroupsService,
  AnalyticalReportsService,
  AnalyticalReportGroup
} from '@gamariverib/mercados-pecuarios-libs-cattlewiz-commons';

@Component({
  selector: 'app-wizard',
  // ...
})
export class WizardComponent implements OnInit {
  constructor(
    private groupsService: AnalyticalReportGroupsService,
    private reportsService: AnalyticalReportsService
  ) {}

  async ngOnInit() {
    // Obtener el árbol de navegación
    const rootTag = await this.groupsService.getRootTag();
    
    // Crear grupo desde parámetros
    const group = AnalyticalReportGroup.loadFromParams(rootTag, ['value-chain', 'scope:mex']);
    
## 📁 Estructura del Proyecto

src/ ├── models/ # Modelos de datos │ ├── id.model.ts # Tipos de identificadores │ ├── lang-string.model.ts # Soporte multiidioma │ ├── country.model.ts # Datos de países │ ├── state.model.ts # Datos de estados │ ├── contact-message.model.ts # Mensajes de contacto │ ├── ticket.model.ts # Sistema de tickets │ ├── me.model.ts # Datos de usuario │ ├── interfaces.model.ts # Interfaces compartidas │ ├── analytical-report-catalog.model.ts # Catálogos de reportes │ ├── analytical-report-group.model.ts # Navegación del wizard │ └── analytical-report-query.model.ts # Consultas de reportes ├── services/ # Servicios Angular │ ├── analytical-report-groups.service.ts # Servicio de navegación │ └── analytical-reports.service.ts # Servicio de reportes ├── utils/ # Utilidades │ └── wizard-utilities.ts # Funciones del wizard └── index.ts # Punto de entrada principal

```bash
npm test

Linting

npm run lint

Formatear código

npm run format

📁 Estructura del Proyecto

src/
├── models/                                    # Modelos de datos
│   ├── id.model.ts                           # Tipos de identificadores
│   ├── lang-string.model.ts                  # Soporte multiidioma
│   ├── country.model.ts                      # Datos de países
│   ├── state.model.ts                        # Datos de estados
│   ├── contact-message.model.ts              # Mensajes de contacto
│   ├── ticket.model.ts                       # Sistema de tickets
│   ├── me.model.ts                           # Datos de usuario
│   ├── interfaces.model.ts                   # Interfaces compartidas
│   ├── analytical-report-catalog.model.ts    # Catálogos de reportes
│   ├── analytical-report-group.model.ts      # Navegación del wizard
│   └── analytical-report-query.model.ts      # Consultas de reportes
├── utils/                                     # Utilidades
│   └── wizard-utilities.ts                   # Funciones del wizard
└── index.ts                                   # Punto de entrada principal

🤝 Contribuir

Esta es una biblioteca interna del proyecto CattleWiz. Para contribuir:

1. Asegúrate de que todo el código sea agnóstico a la UI
2. No incluyas dependencias de Angular, Bootstrap, o Ionic
3. Documenta todas las funciones y clases con JSDoc
4. Ejecuta los tests antes de hacer commit
5. Sigue las convenciones de nomenclatura:
   • Archivos: nombre-descriptivo.model.ts
   • Clases: PascalCase
   • Funciones: camelCase
   • Constantes: UPPER_SNAKE_CASE

📄 Licencia

Apache-2.0

👥 Autor

José Gamaliel Rivera Ibarra [email protected]