SimCo Restaurant Stats API

Una API RESTful construida con NestJS para analizar estadísticas de restaurantes y oficinas de ventas corporativas del juego SimCompanies. Esta aplicación permite sincronizar tus datos desde la API oficial de SimCompanies y realizar análisis detallados de mercado y rendimiento.

📋 Descripción

SimCo Restaurant Stats API es una aplicación backend diseñada para jugadores de SimCompanies que desean analizar el rendimiento de sus restaurantes y el comportamiento del mercado de órdenes de venta.

🎯 Principales funcionalidades:

Sincronización de datos: Obtiene automáticamente datos de restaurantes y órdenes de venta desde la API oficial de SimCompanies
Análisis de restaurantes: Rastrea métricas como rating, ocupancy, revenue, costs y reviews de restaurantes
Análisis de mercado: Monitorea precios, demanda y tendencias de recursos en el mercado
Gestión de edificios: Administra información de oficinas de ventas y restaurantes
APIs de análisis: Proporciona endpoints especializados para obtener estadísticas y tendencias

🏢 Casos de uso:

Optimización de restaurantes: Analiza el rendimiento histórico para mejorar la rentabilidad
Investigación de mercado: Estudia tendencias de precios y demanda de recursos
Toma de decisiones: Obtén insights basados en datos para estrategias comerciales
Monitoreo automatizado: Seguimiento continuo del rendimiento de múltiples edificios

🛠️ Tecnologías

Backend Framework

NestJS - Framework de Node.js progresivo para aplicaciones escalables
TypeScript - Superset tipado de JavaScript
Node.js v18+ - Runtime de JavaScript

Base de datos

PostgreSQL - Base de datos relacional robusta
TypeORM - ORM para TypeScript y JavaScript

Gestión de dependencias

pnpm - Gestor de paquetes eficiente y rápido

Librerías principales

@nestjs/axios - Cliente HTTP para integraciones con APIs externas
@nestjs/config - Gestión de configuración y variables de entorno
joi - Validación de esquemas de datos
rxjs - Programación reactiva con observables

Desarrollo y calidad de código

ESLint - Linter para identificar y arreglar problemas en el código
Prettier - Formateador de código automático
Jest - Framework de testing

🏗️ Arquitectura del proyecto

src/
├── auth/                    # Módulo de autenticación
│   ├── controllers/         # Controladores de auth
│   ├── entities/           # Entidades de tokens
│   └── services/           # Servicios de autenticación
├── database/               # Configuración de base de datos
│   ├── migrations/         # Migraciones de TypeORM
│   └── typeorm.config.ts   # Configuración de TypeORM
├── health/                 # Health checks de la API
├── restaurant-stats/       # Módulo de estadísticas de restaurantes
│   ├── controllers/        # Endpoints de restaurantes
│   ├── entities/          # Entidades de restaurantes y edificios
│   └── services/          # Lógica de negocio de restaurantes
├── sales-orders-stats/     # Módulo de órdenes de venta
│   ├── controllers/        # Endpoints de órdenes de venta
│   ├── entities/          # Entidades de órdenes de venta
│   ├── interfaces/        # Interfaces de análisis
│   └── services/          # Lógica de negocio de órdenes
├── app.module.ts          # Módulo principal
├── config.ts              # Configuraciones globales
├── enviroments.ts         # Configuración de entornos
└── main.ts               # Punto de entrada de la aplicación

🚀 Configuración del proyecto

Prerrequisitos

Node.js v18 o superior
PostgreSQL 15 o superior
pnpm (recomendado) o npm
Cuenta activa en SimCompanies

Variables de entorno

Crea un archivo .env en la raíz del proyecto:

# Base de datos
DATABASE_URL=postgresql://usuario:contraseña@localhost:5432/simco_restaurant_stats

# Credenciales de SimCompanies
GAME_EMAIL=tu_email@ejemplo.com
GAME_PASSWORD=tu_contraseña

# Configuración opcional
TIMEZONE_OFFSET=0
NODE_ENV=dev

Instalación

# Clonar el repositorio
$ git clone <url-del-repositorio>
$ cd simco-stats-api

# Instalar dependencias
$ pnpm install

# Ejecutar migraciones de base de datos
$ pnpm run migration:run

Compilar y ejecutar el proyecto

# Desarrollo
$ pnpm run start

# Modo watch (recompilación automática)
$ pnpm run start:dev

# Modo producción
$ pnpm run start:prod

Migraciones de base de datos

# Generar nueva migración
$ pnpm run migration:gen --name=nombre-de-la-migracion

# Ejecutar migraciones pendientes
$ pnpm run migration:run

# Revertir última migración
$ pnpm run migration:revert

# Mostrar estado de migraciones
$ pnpm run migration:show

📊 API Endpoints

Autenticación

POST /auth/login - Iniciar sesión en SimCompanies

Health Check

GET /health - Estado de la aplicación

Restaurantes

GET /restaurant-stats - Últimas estadísticas agrupadas por restaurante
GET /restaurant-stats/:id - Estadísticas de un restaurante específico
POST /restaurant-stats/sync/:buildingId - Sincronizar un restaurante
POST /restaurant-stats/sync-all - Sincronizar todos los restaurantes

Edificios

GET /buildings - Lista de todos los edificios
GET /buildings/:id - Información de un edificio específico
POST /buildings/sync - Sincronizar edificios desde SimCompanies

Órdenes de venta

GET /sale-orders - Lista de órdenes de venta
GET /sale-orders/:id - Orden específica por ID
GET /sale-orders/status/resolved - Órdenes resueltas
GET /sale-orders/status/pending - Órdenes pendientes
GET /sale-orders/building/:buildingId - Órdenes por edificio
POST /sale-orders/sync/:buildingId - Sincronizar órdenes de un edificio
POST /sale-orders/sync-all - Sincronizar todas las órdenes

Análisis de mercado

GET /sale-orders/analytics/prices/:date - Precios promedio por fecha
GET /sale-orders/analytics/demand/:date - Demanda total por fecha
GET /sale-orders/analytics/market-summary/:date - Resumen completo del mercado
GET /sale-orders/analytics/market-data/:startDate/:endDate - Datos históricos
GET /sale-orders/analytics/top-demand/:date - Recursos más demandados
GET /sale-orders/analytics/stats - Estadísticas generales

📈 Ejemplos de uso

Obtener precios promedio del día

curl http://localhost:3000/sale-orders/analytics/prices/2025-06-17

Respuesta:

{
  "date": "2025-06-17",
  "total_sale_orders_analyzed": 45,
  "resources": [
    {
      "resource_kind": 91,
      "average_price": "125000.00",
      "average_quality_bonus": "2.2816",
      "total_orders": 15,
      "total_amount": 45,
      "min_price": "120000",
      "max_price": "130000"
    }
  ]
}

Sincronizar datos de restaurante

curl -X POST http://localhost:3000/restaurant-stats/sync/12345678

Obtener demanda de recursos

curl http://localhost:3000/sale-orders/analytics/demand/2025-06-17

🧪 Tests

# Tests unitarios
$ pnpm run test

# Tests e2e
$ pnpm run test:e2e

# Cobertura de tests
$ pnpm run test:cov

📝 Desarrollo

Linting y formateo

# Ejecutar linter
$ pnpm run lint

# Formatear código
$ pnpm run format

Estructura de commits

Se recomienda usar commits descriptivos siguiendo el formato:

tipo(scope): descripción

feat(auth): añadir autenticación con SimCompanies
fix(database): corregir migración de sale_orders
docs(readme): actualizar documentación de API

🤝 Contribución

Fork el proyecto
Crea tu feature branch (git checkout -b feature/AmazingFeature)
Commit tus cambios (git commit -m 'Add some AmazingFeature')
Push al branch (git push origin feature/AmazingFeature)
Abre un Pull Request

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo LICENSE para más detalles.

📞 Soporte

Para preguntas, problemas o sugerencias:

Abre un issue en GitHub
Contacta al equipo de desarrollo

🔄 Changelog

v1.0.0

✨ Sincronización inicial de datos de restaurantes
✨ Análisis de órdenes de venta
✨ APIs de análisis de mercado
✨ Gestión de edificios y oficinas de ventas
✨ Sistema de autenticación con SimCompanies

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.prettierrc		.prettierrc
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
entrypoint.sh		entrypoint.sh
eslint.config.mjs		eslint.config.mjs
nest-cli.json		nest-cli.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation