playbooks

home / skills / jpropato / ssg-santalucia / project-overview

project-overview skill

/.agent/skills/project-overview

This skill helps outline Santa Lucía delivery system architecture and business rules for tracking miles, ranking, and payments.

npx playbooks add skill jpropato/ssg-santalucia --skill project-overview

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.5 KB
---
name: santalucia-overview
description: Información general del proyecto Santa Lucía - Sistema de Delivery
---

# Santa Lucía - Sistema de Delivery

## Descripción del Proyecto

Sistema de gestión de delivery para pizzería con las siguientes características:
- Registro de viajes realizados por motoqueros
- Cálculo automático de kilómetros usando Google Maps
- Sistema de ranking mensual con multiplicadores
- Liquidación de pagos por km recorrido
- Reportes y auditoría completa

## Stack Tecnológico

### Frontend
- **React 19** + TypeScript
- **Vite** como build tool
- **Mantine v7** + TailwindCSS para UI
- **TanStack Query** para data fetching
- **Zustand** para estado global
- **React Hook Form** + Zod para formularios

### Backend
- **Fastify** + TypeScript
- **Prisma** ORM
- **PostgreSQL 16**
- **Better-Auth** para autenticación
- **Zod** para validación

### APIs Externas
- **Google Maps Distance Matrix API** para cálculo de km

## Documentación Principal

- `docs/especificacion-funcional.md` - Reglas de negocio y flujos
- `docs/arquitectura-tecnica.md` - Stack y estructura del código

## Reglas de Negocio Clave

1. **Solo ida**: Los km se calculan desde el local hasta la dirección más lejana (no ida y vuelta)
2. **Turnos**: Día y Noche, liquidan por separado
3. **Ranking**: Los motoqueros se rankean por km totales del período
4. **Multiplicadores**: Según posición (1°: x5, 2°: x3, 3°: x2, resto: x1)
5. **Bono**: El que más pedidos entrega recibe bono = x20 × precio nafta

Overview

This skill provides a concise technical and functional overview of the Santa Lucía delivery management system for a pizzeria. It summarizes core features: trip recording, automatic distance calculation, monthly ranking with multipliers, payment liquidation by km, and full reporting and audit. The description highlights the tech stack and key business rules to help engineers, product managers, or auditors quickly understand the system.

How this skill works

The skill inspects the system design that records motoquero trips and computes distances using the Google Maps Distance Matrix API, counting only one-way kilometers from the store to the farthest delivery address. It explains how back-end logic aggregates km per shift (day/night), applies ranking and position-based multipliers, and calculates liquidations and bonuses. It also covers reporting and audit capabilities for verifying trips, payments, and historical data.

When to use it

  • Onboarding engineers or stakeholders to the delivery system architecture and rules
  • Auditing trip records, payments, and ranking outcomes
  • Designing or extending payroll/liquidation logic based on km and multipliers
  • Integrating or validating Google Maps distance calculations
  • Preparing reporting, CSV exports, or financial reconciliations

Best practices

  • Treat distance calculations as one-way from the store to the farthest address; do not double for return trips
  • Keep API keys secure and throttle Distance Matrix requests; cache responses for repeated addresses
  • Separate day and night shifts in data models and liquidations to avoid mixing periods
  • Use migrations and strong schema validation (Zod + Prisma) to keep trip and payment data consistent
  • Implement audit trails for trip edits and payment adjustments to support reconciliation and disputes

Example use cases

  • Compute monthly payroll: aggregate km per motoquero by shift, apply multipliers and produce payment batches
  • Generate ranking report: list top motoqueros by total km and apply position multipliers automatically
  • Audit a suspect trip: verify recorded route, distance calculation, and any manual edits with full history
  • Simulate payout scenarios: adjust multipliers or fuel price to estimate bonus and liquidation impact
  • Integrate a new front-end view to display real-time rankings and per-trip details for managers

FAQ

Are distances calculated round-trip or one-way?

Distances are calculated one-way from the store to the farthest delivery address; return trips are not included.

How are multipliers applied to rankings?

Monthly rankings apply predefined multipliers by position (1st x5, 2nd x3, 3rd x2, others x1) to the total km for liquidation.