SOLICITUD DE REQUERIMIENTO A DESARROLLO DE SISTEMAS · V1

SoloPropinas

Documento funcional, técnico y administrativo para construir una plataforma de propinas digitales centrada en personas, con QR personal permanente, integración con proveedores de pago y prevención de uso indebido.

Alcance: esta solicitud define el producto a construir; no reemplaza la validación legal, contable, impositiva, contractual ni de compliance que corresponda en cada jurisdicción y con cada PSP.

1. Objetivo

Permitir que una persona que brinda una buena atención reciba una propina digital de forma simple. El cliente agradece a una persona; el dinero se procesa mediante un PSP y llega al destino de cobro verificado de esa persona.

Resultado esperado

Alta simple y perfil humano.
QR permanente, personal y fácil de mostrar.
Propina con información clara de importe, tarifa y medio de pago.
Reputación separada entre atención personal y lugar.
Administración segura de cuenta, lugares y cobro.

2. Principios obligatorios

El QR representa a la persona, no a una cuenta bancaria ni a un local.
Identidad, perfil, reputación, lugar y destino de cobro son entidades distintas.
Una persona puede trabajar en varios lugares.
La interfaz usa lenguaje cotidiano, una decisión principal por pantalla y datos obligatorios explícitos.
La plataforma no se diseña como cobro genérico: el uso previsto es el agradecimiento voluntario por atención.
La Product Constitution es criterio de aceptación de todo diseño y desarrollo.

3. Roles y permisos

Rol	Puede hacer	No puede hacer
Cliente	Ver perfil/QR, elegir importe, pagar por PSP, valorar atención y optar por opinar del lugar.	Modificar perfil, cobro, lugares o métricas del trabajador.
Trabajador	Gestionar su perfil, lugares, cobro verificado, QR, historial y métricas privadas.	Alterar reseñas de Google ni estados del PSP.
Soporte	Asistir, consultar trazabilidad con permisos, abrir casos.	Cambiar cobro o liberar riesgo sin autorización reforzada.
Administración/riesgo	Revisar alertas, aplicar límites, solicitar evidencia, resolver casos.	Modificar datos sin auditoría ni ignorar el PSP.

4. Módulos funcionales

Módulo	Funciones mínimas	Reglas clave
Alta e identidad	Crear cuenta, validar teléfono, aceptar términos y verificar identidad según riesgo/PSP.	No activar cobro hasta completar las verificaciones requeridas.
Perfil	Nombre, foto, descripción asistida, fotos complementarias, visibilidad.	La foto humaniza la propina; no sustituye la verificación de identidad.
Cobro	Elegir PSP, vincular destino, verificar, activar, cambiar o desactivar.	Los cambios sensibles requieren segundo factor y auditoría. El QR no cambia.
QR personal	Generar, mostrar a pantalla completa, enviar, guardar, descargar e imprimir.	Es único, permanente y no contiene una cuenta de cobro fija.
Pago/propina	Perfil, importe, tarifa visible, selección de PSP, redirección/SDK, estado y comprobante.	Solo mostrar estados confirmados por el PSP. Factura/comprobante según reglas administrativas.
Reputación	Valoración de atención 1–5, promedio y distribución; opción de reseña del lugar en Google.	La atención es dato SoloPropinas. Google califica al lugar, no a la persona.
Mi cuenta	ABM de lugares, perfil, cobro, QR, seguridad, ayuda e historial.	Ningún formulario confirma campos obligatorios vacíos.

5. Pago, PSP y comprobantes

Integrar inicialmente Mercado Pago, Naranja X, Ualá y wallet disponible según viabilidad contractual/técnica. La elección final requiere validación de cada proveedor.
El PSP recibe datos sensibles, autentica al pagador, procesa y confirma el estado. SoloPropinas no guarda datos completos de tarjetas ni suplanta al PSP.
El cliente puede optar por cubrir la tarifa del servicio; el importe y porcentaje vigente deben mostrarse antes de pagar, sin promesas de plazos de acreditación.
Guardar: operación interna, referencia PSP, estado, importes, tarifa, fecha, trabajador, QR, lugar contextual, pagador pseudonimizado y versión de términos.
Emitir/poner a disposición el comprobante o factura que legalmente corresponda. Incluir acceso de descarga, estado de emisión y procedimiento para datos fiscales distintos a consumidor final.

6. ABM de lugares y Google Places

Crear: el trabajador busca nombre o dirección; backend consulta Places Autocomplete (New) o Text Search (New) con credenciales restringidas; el usuario confirma nombre y dirección.
Guardar: worker_place_id, google_place_id, nombre canónico, dirección, coordenadas, estado, fecha de validación, enlace directo de reseña y auditoría.
Editar: volver a buscar y confirmar; no editar manualmente un Place ID.
Desactivar/eliminar: explicar impacto, conservar historial, evitar que aparezca en futuras opiniones, permitir reactivación administrativa cuando corresponda.
Enlace de reseña: https://search.google.com/local/writereview?placeid={google_place_id}. Cada lugar usa su propio ID; no scraping ni conversión de CIDs.

7. Reputación y experiencia Google

Antes de valorar, el cliente ve nombre, foto, promedio y cantidad de valoraciones de atención en SoloPropinas.
El trabajador ve además distribución 1–5 y porcentajes positivas (4–5), neutras (3) y negativas (1–2).
La reseña del lugar se abre en Google externo; SoloPropinas registra solo “formulario abierto”, no afirma que fue publicada.
Casos: sesión Google activa, sin sesión, reseña existente para editar, cancelación, error, Place ID inválido, restricción o CAPTCHA.
Después de abrir Google, SoloPropinas queda disponible para volver y agradecer. No incentivar reseñas ni condicionar beneficios a la calificación.

8. Circuitos y validación de datos

Todo botón lleva a: éxito confirmado, error comprensible, cancelación o revisión. Nunca a un callejón sin salida.
Datos obligatorios: informar etiqueta, motivo, validación en línea y conservar lo escrito si hay error.
Lugar: buscar → elegir coincidencia → confirmar → activo.
Cobro: proveedor → identificador obligatorio → validación PSP → segundo factor → activo/rechazado/revisión.
Perfil: campos requeridos → vista previa → confirmar publicación.
Bajas: explicación de impacto → confirmación → estado desactivado → posibilidad de reactivar según reglas.

9. Modelo de datos mínimo

Worker: identidad, estado, teléfono, perfil, riesgo, auditoría.
PaymentDestination: PSP, token/referencia, estado de verificación, fechas y auditoría.
PersonalQR: identificador inmutable, estado, versión visual, trabajador.
Workplace: relación trabajador–lugar y datos de Google Places.
TipIntent/Payment: operación, importes, tarifa, PSP, estados, referencias y comprobantes.
AttentionRating: operación, trabajador, lugar contextual, valor, fecha, controles anti-duplicado.
RiskCase/AuditLog: señales, decisión, responsable, evidencia, comunicaciones y apelación.

10. Seguridad y privacidad

Autenticación segura, protección de sesión, controles de acceso por rol, cifrado en tránsito y reposo.
Secretos y claves de proveedores solo en backend/gestor de secretos; nunca en HTML ni app cliente.
Minimización de datos, retención definida, registro de consentimiento y trazabilidad de acceso.
Segundo factor para cambios de acceso y destino de cobro.
Logs estructurados, alertas, backups, recuperación y plan de respuesta a incidentes.

11. Prevención de fraude y uso indebido

Objetivo: evitar que la plataforma se use para ventas, cobros no relacionados con propinas, autooperaciones, transferencias encubiertas o evasión de controles del PSP, sin bloquear injustificadamente una propina legítima.

Controles en tiempo real

QR vigente, perfil y PSP verificados.
Límites configurables por QR, pagador, dispositivo, medio, IP, importe acumulado y período.
Señales: autooperaciones, pagador–trabajador reiterado, múltiples cuentas/dispositivos, importes atípicos o redondos repetidos, ráfagas, reintentos, contracargos, cambios recientes de cobro/teléfono/dispositivo y lugares incongruentes.
Score de riesgo basado en múltiples señales; no revelar sus umbrales ni reglas al usuario.

Controles periódicos

Diario: conciliación PSP, reversos, reclamos, velocidad y anomalías.
Semanal: cola de revisión, patrones relacionados, revisión de reglas y falsos positivos.
Mensual: revalidación de identidad, cobro, lugares, límites y muestras de operaciones.
Por evento: cambio sensible o variación brusca activa revisión reforzada.

Bloqueos y respuesta administrativa

Riesgo bajo: aviso/límite temporal. Riesgo medio: retención preventiva y solicitud de información. Riesgo alto: suspensión de cobro, caso de riesgo y revisión.
Comunicar función limitada, documentación requerida, canal de apelación y plazo; no explicar señales internas que faciliten evasión.
Administración revisa evidencia, historial, contexto y datos disponibles del PSP. Decide liberar, mantener límite, cerrar, solicitar acción al PSP o reportar cuando la ley/contrato lo exija.
Toda decisión registra responsable, pruebas, motivo, comunicación, fecha de revisión y resultado de apelación.

12. Operación administrativa

Consola con búsqueda por trabajador, QR, operación, PSP, lugar y caso de riesgo.
Colas: verificación, cambios de cobro, incidencias PSP, fraude, apelaciones y soporte.
Acciones con permisos: solicitar información, limitar, suspender, restituir, agregar nota, escalar y cerrar.
Tablero: operaciones, fallas PSP, conversión, alertas, falsos positivos, tiempos de resolución y quejas.

13. Integraciones y dependencias

PSP: contratos, onboarding, API/SDK, webhooks firmados, estados, devoluciones y comprobantes.
Google Maps Platform: proyecto, facturación, API key restringida, Places Autocomplete/Text Search/Details y atribución requerida.
Mensajería: WhatsApp para QR/onboarding y proveedor de SMS o equivalente para verificación cuando aplique.
Servicios internos: notificaciones, almacenamiento de imágenes, analítica, soporte y facturación.

14. Criterios de aceptación de entrega

El QR se mantiene personal al cambiar cobro o lugares.
Todos los campos obligatorios se validan y cada circuito tiene fin confirmado, error recuperable o estado de revisión.
Se pueden administrar varios lugares; cada uno se confirma con Google Places y usa su enlace correcto de reseña.
Los pagos solo muestran estados confirmados por el PSP y los comprobantes/facturas se ponen a disposición según configuración fiscal validada.
La métrica de atención se separa visiblemente de la reseña de Google.
Los eventos sensibles, pagos y decisiones de riesgo quedan auditados.
Existen pruebas funcionales, de integración, seguridad, permisos, abuso/fraude, accesibilidad y recuperación antes de producción.

15. Resumen de propinas y regla del último lugar

El panel principal debe permitir consultar hoy, esta semana y este mes. Para cada período mostrar total recibido, cantidad de propinas y propina promedio.
El filtro debe cambiar las tres métricas desde la misma fuente de datos, respetar zona horaria Argentina y permitir llegar al detalle de movimientos del período.
La relación trabajador–lugar debe mantener al menos un lugar activo mientras la cuenta esté habilitada para operar con contexto de lugar.
Si hay un único lugar activo, el botón “Quitar” debe transformarse en “Cambiar lugar”: buscar otro lugar, confirmar la coincidencia oficial y recién entonces reemplazar la relación anterior.
Si hay dos o más lugares activos, se puede desactivar uno tras confirmación; no se borra el historial ni se modifica el QR.

NUEVO · ALGORITMO DE MONTOS

16. Selección contextual de tres montos rápidos

El sistema mostrará siempre tres montos ordenados —bajo, recomendado y alto— más “Otro monto”. Debe funcionar sin identificar al cliente y personalizar progresivamente con una cookie anónima, sin unir dispositivos ni reconstruir identidades.

16.1 Objetivo y guardrails

Modo inicial: aprendizaje seguro, con tríos aprobados y sin afirmar optimización económica mientras costos e ingresos no estén configurados.
Modo económico futuro: maximizar margen de contribución esperado por impresión, protegiendo conversión, adopción, estabilidad, límites por moneda y separación absoluta entre propina y servicio SoloPropinas.
La opción central se destaca visualmente, sin llamarla “correcta” o “habitual”. “Otro monto” permanece siempre disponible.
Ninguna presión de demanda, clima o historial ajeno aumenta automáticamente la propina: son señales predictivas sujetas a muestra, pruebas y límites.

16.2 Contexto y cascada

Prioridad	Señal	Regla
1	Cliente anónimo	Solo con cookie, pagos aprobados, recencia y muestra suficiente; segmentar por moneda, ciudad y categoría.
2	Trabajador y comercio	Regularizar contra segmentos más amplios para evitar decisiones por pocas operaciones.
3	Categoría, día y franja	Distinguir restaurante, café y demás contextos; respetar zona horaria local.
4	Oferta, demanda y servicio	Usar trabajadores activos, oportunidades, rotación, duración real o proxy identificado y presión regularizada.
5	Clima, feriados y eventos	Temperatura, sensación, lluvia, tormenta, humedad y viento ajustan actividad esperada; nunca multiplican directamente los montos.
6	Mercado	Moneda ISO 4217 y ciudad normalizada son obligatorias; fallback ciudad → región/país → moneda → baseline global de esa moneda.

16.3 “Otro monto” y contexto compatible

Un monto manual puede reemplazar la opción más cercana cuando se repite en pagos aprobados, es reciente, está dentro de límites y coincide con moneda y contexto. El algoritmo aprende una distribución contextual, no “el monto del cliente”. Ejemplo: ARS 6.000 recurrentes en restaurantes de Córdoba y ARS 2.000 en cafés se conservan como perfiles separados; ninguno se convierte automáticamente a USD.

16.4 Modelo de datos requerido

Entidad / tabla	Campos mínimos
`AmountImpression`	`id`, timestamp, cookie pseudónima, worker, workplace, category, city, country, timezone, currency, trío, opción destacada, variante, modo, configuración/modelo y contexto de señales.
`AmountSelection`	Impresión, opción elegida, monto, indicador manual, timestamp y orden de selección.
`TipPayment`	Intento, pago aprobado/rechazado/abandonado, monto de propina, monto de servicio, total, currency, PSP, referencias, timestamps y reverso.
`ClientContextPreference`	Cookie hash, currency, city/region, category/workplace, mediana/moda redondeada, frecuencia, recencia, dispersión, confianza y expiración.
`MarketAmountConfig`	Currency, país/ciudad/categoría, trío baseline, mínimo/máximo, redondeo, separación mínima, candidatos, vigencia, versión y aprobador.
`OperationalWindow`	Workplace, ventana, oportunidades, pagos, trabajadores activos, oferta, demanda, rotación, participación, duración, saturación, cobertura y calidad/proxy.
`WeatherSnapshot`	Proveedor, geohash/coordenada aproximada del comercio, observación/pronóstico, temperatura, sensación, precipitación, tormenta, humedad, viento, calidad, fetched_at y expires_at.
`AlgorithmDecisionLog`	Impresión, candidatos evaluados, features versionadas, fallback usado, scores, restricciones aplicadas, trío final, motivo y versión del algoritmo.
`ExperimentAssignment`	Experimento, unidad estable, variante, fecha, elegibilidad y exclusiones.

16.5 Parámetros configurables

Muestras mínimas por cliente, trabajador, comercio, categoría y ciudad; ventanas, TTL y decaimiento por recencia.
Tríos candidatos, mínimo, máximo, redondeo, separación y cambio máximo por moneda/mercado.
Recurrencia y confianza necesarias para insertar un monto manual; dispersión máxima y vencimiento.
Ventanas operativas, definición de trabajador activo, oportunidad, servicio, duración y calidad mínima de proxies.
Proveedor meteorológico, timeout, caché, antigüedad máxima y fallback sin clima.
Exploración, asignación experimental, pérdida máxima de conversión, histéresis y frecuencia de actualización.
Costos PSP fijos/porcentuales, impuestos variables, precio del servicio y reglas de redondeo, inicialmente desactivados hasta validación.

16.6 Cálculos

presión = demanda_observada / oferta_observable, regularizada contra el patrón histórico comparable. La actividad esperada combina historia, oferta/demanda, rotación, duración, clima, calendario y eventos. Cuando la configuración económica esté completa:

MCPI(T,c) = P(pago aprobado | T,c) × E[ingreso del servicio − costos variables | pago,T,c]

La propina del trabajador no es ingreso de SoloPropinas ni se descuenta para calcular este margen. El trío ganador debe superar guardrails de conversión, estabilidad, confianza y límites del mercado.

16.7 Casos de aceptación

Sin cookie o con comercio nuevo: usar categoría/franja o baseline de moneda.
Cookie borrada: tratar como visita nueva; no reconstruir identidad.
Pagos simultáneos de otros mozos: actualizar actividad agregada, nunca copiar sus montos.
Alta demanda y alta oferta en igual proporción: no inferir saturación por volumen bruto.
Duración inferida sin POS: marcar proxy y reducir peso.
API meteorológica caída: usar dato válido dentro del TTL o modelo sin clima; nunca bloquear el pago.
Nueva ciudad: fallback regional dentro de la misma moneda; no convertir baseline por tipo de cambio.
Montos manuales dispersos o abandonados: no personalizar.
Restaurante versus café: mantener preferencias independientes.

16.8 Privacidad, auditoría y monitoreo

Cookie pseudónima con finalidad informada, consentimiento cuando corresponda, vencimiento, revocación y derecho de supresión conforme Ley 25.326.
No guardar respuesta meteorológica cruda indefinidamente ni ubicación precisa del cliente; usar la ubicación validada del comercio.
Registrar versión de features, configuración, algoritmo y motivo de fallback para reproducir cada decisión.
Monitorear conversión, abandono, “Otro monto”, distribución de opciones, margen por impresión, error de pronóstico, cobertura de proxies y deriva por mercado.
Los cambios de baseline y parámetros sensibles requieren permisos, aprobación y auditoría.

16.9 Criterio de terminado

Se considera implementado cuando existe baseline por moneda, decisión reproducible, fallback completo, eventos sin duplicados, separación contable propina/servicio, pruebas de contextos y monedas, tablero de guardrails, rollback de configuración y documentación operativa. La hipótesis ARS 2.000 / 4.000 / 6.000 permanece como configuración inicial validable, no como constante de código.