Imported from WooferByte/SDD-Preparando-el-Entorno-para-Agentes (AGENTS.md). Install upstream with npx skills add WooferByte/SDD-Preparando-el-Entorno-para-Agentes. Copyright stays with the author.

AGENTS.md - StreetTune

Skills Reference

Skill	Descripción
python-fastapi	Patrones y convenciones FastAPI + Clean Architecture
react-native	Patrones React Native + TypeScript + Expo para mobile
mapas-geolocalizacion	Integración de mapas, geolocalización y gestión de estados en tiempo real
correccion-ia	No aplica directamente, pero sirve como referencia para flujos de validación
rubricas	No aplica
skill-sync	Sincroniza metadata de skills a AGENTS.md
skill-creator	Crea nuevos skills desde template

Auto-invoke Skills

Action	Skill
Creating FastAPI endpoints	python-fastapi
Creating React Native screens/components	react-native
Integrating maps and location	mapas-geolocalizacion
Creating new skills	skill-creator
Defining Pydantic schemas	python-fastapi
Managing reservation/check-in logic	react-native
Syncing AGENTS.md files	skill-sync
Writing geospatial queries	python-fastapi

Project Overview

StreetTune es una aplicación mobile que organiza el espacio público, conectando a músicos callejeros para encontrar y reservar su escenario, evitando así conflictos territoriales y reduciendo la incertidumbre laboral.

Módulos Principales

Módulo	Descripción
Autenticación	Registro/login con DNI y validación de identidad.
Mapa	Visualización de espacios (aptos/no aptos, disponibles/ocupados) en tiempo real.
Reservas	Creación, gestión y cancelación de reservas con hora de fin obligatoria.
Check-in	Validación de presencia con ventana de tolerancia de ±15 minutos.
Perfil	Gestión de datos personales, historial de reservas y registro de incumplimientos (No-show).
Sincronización Offline	Persistencia local de acciones (reservas, check-in) para conectividad variable.

Modelo de Datos

Usuario (DNI) ──┬── Reserva ──┬── Espacio
                │              └── HistorialReserva
                └── Incumplimiento (No-show)
                       └── Espacio (opcional)

Roles

Rol	Permisos
Artista Callejero	Visualizar mapa, reservar espacios, hacer check-in, ver su perfil e historial.
Preventor Municipal (MVP)	Consultar mapa y visualizar estado de espacios y reservas.

Critical Rules

ALWAYS

Offline-First: La app debe funcionar con la última sincronización disponible. Las acciones críticas (reserva, check-in) se persisten localmente y se sincronizan al recuperar conexión.
Experiencia de Calle: La interfaz debe ser de alta visibilidad (alto contraste para luz solar), legible, y permitir navegación con una sola mano.
Flujos Simples: Reducir al mínimo los pasos para acciones clave (ej. reserva en 3 taps o menos).
Validación de Reglas de Negocio: Verificar siempre la ventana de check-in (±15 minutos) y que la hora de fin sea posterior a la de inicio.
Seguridad de Datos: Encriptar información sensible como el DNI. No almacenar datos de identificación en texto plano en el dispositivo.
Máximo 500 LOC por archivo.
Logging de Acciones Críticas: Registrar reservas, check-ins e incumplimientos para auditoría.

NEVER

Lógica de negocio en componentes de UI.
Acceso directo a BD desde servicios de UI.
Asumir conectividad constante.
Exponer información sensible (como el DNI) en logs.
Commits sin mensaje descriptivo.
Push directo a main/master.

Decision Trees

¿Dónde colocar código nuevo?

Situación	Ubicación
Nuevo endpoint API	`backend/app/routers/`
Lógica de negocio (reservas, check-in)	`backend/app/services/`
Acceso a BD (geospatial queries)	`backend/app/repositories/`
Modelo SQLAlchemy (Espacio, Reserva)	`backend/app/models/`
Schema Pydantic	`backend/app/schemas/`
Pantalla (Screen) React Native	`frontend/src/screens/`
Componente UI reutilizable	`frontend/src/components/`
Lógica de mapa y geolocalización	`frontend/src/features/map/`
Servicio API	`frontend/src/services/`
Persistencia local (AsyncStorage)	`frontend/src/storage/`

¿Cómo manejar errores?

Tipo	Acción
Validación de entrada (ej. hora inválida)	HTTPException 400 + mensaje específico
No encontrado (ej. espacio no existe)	HTTPException 404
Sin permisos	HTTPException 403
Conflicto de reserva (espacio ocupado)	HTTPException 409 + "Espacio ya reservado en ese horario"
Error de conectividad (cliente)	Usar datos locales. Mostrar banner: "Modo offline. Los cambios se sincronizarán cuando recuperes la conexión."
Error interno	HTTPException 500 + log detallado

Commands

# Backend
cd backend
uvicorn app.main:app --reload          # Desarrollo
alembic revision --autogenerate -m ""  # Nueva migración
alembic upgrade head                   # Aplicar migraciones
pytest                                 # Tests

# Frontend (React Native + Expo)
cd frontend
npm start                              # Iniciar Metro bundler
npm run ios                            # Ejecutar en iOS simulator
npm run android                        # Ejecutar en Android emulator
npm run test                           # Tests
npm run lint                           # Linting

Commit Guidelines

Seguir Conventional Commits:

<type>(<scope>): <description>

[optional body]

Types

feat: Nueva funcionalidad
fix: Corrección de bug
refactor: Refactorización sin cambio funcional
docs: Documentación
test: Tests
chore: Tareas de mantenimiento

Scopes

auth: Autenticación (DNI, registro)
map: Mapa, geolocalización, visualización de espacios
reservations: Lógica de reservas (crear, cancelar)
checkin: Lógica de check-in y validación
profile: Perfil de usuario, historial
offline: Sincronización y persistencia local
api: Backend general
ui: Componentes de UI en frontend

QA Checklist

Antes de cada commit:

Tests pasan
Linting sin errores
Sin console.log/print de debug
Validación de reglas de negocio (check-in, reservas)
Comportamiento offline probado (sin conexión)
Interfaz probada en condiciones de "calle" (simular luz solar, uso con una mano)
Migraciones generadas si hay cambios en modelos
Sin secrets en código
Máximo 500 LOC por archivo

SDD-Preparando-el-Entorno-para-Agentes

About