npm package: @gamariverib/mercados-pecuarios-libs-cattlewiz-commons
Description: Biblioteca de clases comunes para la plataforma CattleWiz de Mercados Pecuarios.
Author: José Gamaliel Rivera Ibarra
Latest version: 0.3.14

# 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

```bash
npm install @gamariverib/mercados-pecuarios-libs-cattlewiz-commons
```

## 🚀 Uso

### Importación en TypeScript

```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

```typescript
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

```typescript
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

```typescript
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)

```typescript
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

```typescript
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

```typescript
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
``` Ejecutar tests

```bash
npm test
```

### Linting

```bash
npm run lint
```

### Formatear código

```bash
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 <gama.rivera@gmail.com>