rckrdmrd/michangarrito
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
8a540b4e94
michangarrito/docs/00-vision-general/REQUERIMIENTOS-FUNCIONALES.md
rckrdmrd 97f407c661 [MIGRATION-V2] feat: Migrar michangarrito a estructura v2 
- Prefijo v2: MCH
- TRACEABILITY-MASTER.yml creado
- Listo para integracion como submodulo

Workspace: v2.0.0 | SIMCO: v4.0.0
2026-01-10 11:28:54 -06:00

712 lines
19 KiB
Markdown
Raw Blame History

---
id: RF-MCH-001
title: Requerimientos Funcionales MiChangarrito
type: Requirement
status: Approved
priority: P0
module: core
version: 1.1.0
created_date: 2026-01-04
updated_date: 2026-01-10
total_requirements: 20
implemented: 15
pending: 5
owner: Product Team
tags:
- requerimientos
- funcional
- saas
---
# MiChangarrito - Requerimientos Funcionales
| Campo | Valor |
|-------|-------|
| **ID** | RF-MCH-001 |
| **Tipo** | Requirement Specification |
| **Estado** | Approved |
| **Total Requisitos** | 20 |
| **Implementados** | 15 (75%) |
| **Pendientes** | 5 |
| **Version** | 1.1.0 |
## Indice de Requerimientos
| ID | Nombre | Prioridad | Estado | Epica |
|----|--------|-----------|--------|-------|
| RF-001 | Punto de Venta (POS) | P0 | Implementado | [MCH-004](../01-epicas/MCH-004-punto-venta.md) |
| RF-002 | Catalogo de Productos | P0 | Implementado | [MCH-003](../01-epicas/MCH-003-catalogo-productos.md) |
| RF-003 | Inventario | P0 | Implementado | [MCH-009](../01-epicas/MCH-009-prediccion-inventario.md) |
| RF-004 | Sistema de Fiados | P1 | Implementado | [MCH-008](../01-epicas/MCH-008-sistema-fiados.md) |
| RF-005 | Clientes | P1 | Implementado | [MCH-014](../01-epicas/MCH-014-gestion-clientes.md) |
| RF-006 | Pedidos de Clientes | P1 | Implementado | [MCH-015](../01-epicas/MCH-015-pedidos-whatsapp.md) |
| RF-007 | Asistente IA (LLM) | P0 | Implementado | [MCH-010](../01-epicas/MCH-010-mcp-server.md) |
| RF-008 | WhatsApp Business | P0 | Implementado | [MCH-011](../01-epicas/MCH-011-whatsapp-service.md) |
| RF-009 | Pagos y Suscripciones | P0 | Implementado | [MCH-005](../01-epicas/MCH-005-integraciones-pago.md) |
| RF-010 | Reportes y Analytics | P1 | Implementado | [MCH-021](../01-epicas/MCH-021-dashboard-web.md) |
| RF-011 | Notificaciones | P1 | Implementado | [MCH-017](../01-epicas/MCH-017-notificaciones.md) |
| RF-012 | Modo Offline | P1 | Implementado | [MCH-022](../01-epicas/MCH-022-modo-offline.md) |
| RF-013 | Integraciones Terminal | P0 | Implementado | [MCH-005](../01-epicas/MCH-005-integraciones-pago.md) |
| RF-014 | Onboarding | P1 | Implementado | [MCH-006](../01-epicas/MCH-006-onboarding-inteligente.md) |
| RF-015 | Seguridad y Acceso | P0 | Implementado | [MCH-002](../01-epicas/MCH-002-autenticacion.md) |
| RF-016 | Programa de Referidos | P2 | Pendiente | [MCH-023](../01-epicas/MCH-023-programa-referidos.md) |
| RF-017 | Soporte | P2 | Parcial | - |
| RF-018 | Audit Logs | P1 | Pendiente | - |
| RF-019 | Feature Flags | P1 | Pendiente | - |
| RF-020 | Rate Limiting | P1 | Pendiente | - |
---
## RF-001: Punto de Venta (POS)
| Campo | Valor |
|-------|-------|
| **ID** | RF-001 |
| **Prioridad** | P0 |
| **Estado** | Implementado |
| **Epica** | [MCH-004](../01-epicas/MCH-004-punto-venta.md) |
### RF-001.1: Registro de Ventas
- Agregar productos manualmente o por búsqueda
- Escanear código de barras (cámara del celular)
- Ajustar cantidad de productos
- Aplicar descuentos (porcentaje o monto fijo)
- Calcular total automáticamente
- Mostrar desglose de productos
### RF-001.2: Métodos de Cobro
- **Efectivo**: Ingresar monto recibido, calcular cambio
- **Tarjeta Mercado Pago**: Conexión Bluetooth con terminal
- **Tarjeta Clip**: Conexión Bluetooth con terminal
- **CoDi**: Generar QR de cobro, esperar confirmación
- **Transferencia SPEI**: Mostrar CLABE virtual, confirmar manual
- **Fiado/Crédito**: Registrar deuda a cliente
### RF-001.3: Tickets y Comprobantes
- Generar ticket digital (imagen/PDF)
- Enviar por WhatsApp al cliente
- Imprimir en impresora térmica Bluetooth (opcional)
- Historial de tickets
### RF-001.4: Corte de Caja
- Corte parcial (sin cerrar día)
- Corte de día completo
- Resumen por método de pago
- Diferencia efectivo esperado vs real
- Enviar resumen por WhatsApp
### Criterios de Aceptacion
```gherkin
Feature: RF-001 - Punto de Venta (POS)
Scenario: Registrar venta con efectivo
Given el usuario esta autenticado como dueno
And tiene productos en el carrito por $150 MXN
When selecciona "Efectivo" como metodo de pago
And ingresa $200 como monto recibido
Then el sistema calcula cambio de $50 MXN
And genera ticket de venta
And actualiza inventario
Scenario: Corte de caja
Given hay ventas registradas en el dia
When el usuario solicita "Corte de caja"
Then muestra resumen por metodo de pago
And calcula diferencia esperado vs real
And envia resumen por WhatsApp
```
---
## RF-002: Catalogo de Productos
### RF-002.1: Gestión de Productos
- Crear producto (nombre, precio, código de barras)
- Editar producto
- Eliminar/desactivar producto
- Categorizar productos
- Foto del producto (opcional)
- Precio de compra (para calcular margen)
### RF-002.2: Importación de Productos
- Desde foto (OCR de lista de precios)
- Desde archivo Excel/CSV
- Desde templates predefinidos (Bimbo, Coca-Cola, etc.)
- Desde audio (transcripción y procesamiento IA)
- Copia de otro negocio similar (con permiso)
### RF-002.3: Templates de Proveedores
- Bimbo: Pan, galletas, pastelitos
- Coca-Cola/FEMSA: Refrescos, jugos, agua
- PepsiCo: Sabritas, Gamesa, bebidas
- Modelo/Corona: Cervezas (donde aplique)
- Ricolino: Dulces, chocolates
- Genéricos: Productos básicos de abarrotes
- Giros específicos: Taquería, fonda, nevería
### RF-002.4: Variantes y Presentaciones
- Mismo producto, diferentes tamaños
- Precios por presentación
- Código de barras por variante
## RF-003: Inventario
### RF-003.1: Control de Stock
- Stock actual por producto
- Stock mínimo configurable
- Alertas de stock bajo (WhatsApp y push)
- Historial de movimientos
### RF-003.2: Entradas de Inventario
- Registro de compras a proveedor
- Entrada desde foto de nota/factura (OCR)
- Ajustes manuales (merma, robo, etc.)
### RF-003.3: Predicción de Resurtido
- Análisis de ventas históricas
- Sugerencia de cuánto comprar
- Alertas proactivas: "En 3 días se te acaba la Coca"
## RF-004: Sistema de Fiados/Crédito
### RF-004.1: Registro de Fiados
- Fiar a cliente identificado
- Monto máximo de crédito por cliente
- Fecha límite de pago (opcional)
- Notas del fiado
### RF-004.2: Gestión de Cobros
- Lista de fiados pendientes por cliente
- Total de fiados del negocio
- Marcar como pagado (parcial o total)
- Recordatorios automáticos por WhatsApp al cliente
### RF-004.3: Historial
- Historial de fiados por cliente
- Clientes morosos
- Reporte de fiados
## RF-005: Clientes
### RF-005.1: Registro de Clientes
- Nombre, teléfono (WhatsApp)
- Dirección (para entregas)
- Notas
- Registro automático desde WhatsApp
### RF-005.2: Historial de Cliente
- Compras realizadas
- Fiados pendientes y pagados
- Productos frecuentes
- Total gastado
### RF-005.3: Comunicación
- Enviar mensaje por WhatsApp
- Notificaciones de promociones
- Recordatorios de fiado
## RF-006: Pedidos de Clientes
### RF-006.1: Recepción de Pedidos
- Cliente envía pedido por WhatsApp
- LLM interpreta y estructura el pedido
- Notificación push al dueño
- Vista de pedidos pendientes
### RF-006.2: Procesamiento
- Aceptar/rechazar pedido
- Modificar pedido
- Confirmar disponibilidad de productos
- Calcular total
### RF-006.3: Cobro de Pedido
- Link de pago (Stripe)
- Pago presencial con terminal
- Pago en efectivo al entregar
- CoDi
### RF-006.4: Entregas a Domicilio
- Marcar pedido como "para entrega"
- Dirección del cliente
- Costo de envío configurable
- Estado: preparando, en camino, entregado
## RF-007: Asistente IA (LLM)
| Campo | Valor |
|-------|-------|
| **ID** | RF-007 |
| **Prioridad** | P0 |
| **Estado** | Implementado |
| **Epica** | [MCH-010](../01-epicas/MCH-010-mcp-server.md) |
### RF-007.1: Canales de Comunicacion
- WhatsApp (principal)
- Chat in-app
- Comandos de voz (futuro)
### RF-007.2: Capacidades para Dueño del Negocio
- Consultar ventas: "¿Cuánto vendí hoy/esta semana/este mes?"
- Consultar ganancias: "¿Cuál es mi utilidad de hoy?"
- Consultar inventario: "¿Cuántas Coca-Colas tengo?"
- Alertas: "¿Qué me falta por resurtir?"
- Predicciones: "¿Cuándo debo comprar más pan?"
- Registrar venta por chat: "Vendí 2 refrescos y una torta"
- Agregar producto: "Agrega un producto nuevo: Doritos a $18"
- Generar reportes: "Mándame el reporte de la semana"
- Configurar: "Cambia el precio de la Coca a $22"
### RF-007.3: Capacidades para Clientes
- Identificación: Detectar que es cliente (no dueño)
- Consultar productos: "¿Tienen refrescos?"
- Hacer pedido: "Quiero 3 tacos y una Coca"
- Preguntar precios: "¿A cómo el kilo de tortilla?"
- Estado de pedido: "¿Ya está mi pedido?"
- Horarios: "¿A qué hora abren?"
### RF-007.4: MCP Server - Herramientas
```
TOOLS DISPONIBLES:
# Ventas
- registrar_venta(productos, metodo_pago, cliente?)
- obtener_ventas(periodo, filtros?)
- generar_corte_caja()
- calcular_ganancias(periodo)
# Productos
- buscar_producto(query)
- crear_producto(datos)
- actualizar_producto(id, datos)
- obtener_precio(producto)
# Inventario
- consultar_stock(producto?)
- registrar_entrada(productos)
- obtener_alertas_stock()
- predecir_resurtido(producto?)
# Clientes
- buscar_cliente(telefono)
- crear_cliente(datos)
- historial_cliente(cliente_id)
- enviar_mensaje_cliente(cliente_id, mensaje)
# Fiados
- registrar_fiado(cliente_id, monto, descripcion)
- obtener_fiados(cliente_id?)
- marcar_fiado_pagado(fiado_id, monto?)
# Pedidos
- crear_pedido(cliente_id, productos)
- obtener_pedidos(estado?)
- actualizar_pedido(pedido_id, estado)
- enviar_link_pago(pedido_id)
# Reportes
- generar_reporte(tipo, periodo, formato)
- enviar_reporte_whatsapp(reporte, destino)
- exportar_excel(datos)
# Configuracion
- obtener_configuracion(clave?)
- actualizar_configuracion(clave, valor)
- obtener_horarios()
- actualizar_horarios(horarios)
```
### Criterios de Aceptacion
```gherkin
Feature: RF-007 - Asistente IA (LLM)
Scenario: Dueno consulta ventas por WhatsApp
Given el usuario es el dueno del negocio
And el negocio tiene saldo de tokens > 0
When envia mensaje "Cuanto vendi hoy?"
Then el LLM detecta intencion de consulta de ventas
And ejecuta tool obtener_ventas(periodo="hoy")
And responde con total de ventas del dia
And descuenta tokens utilizados
Scenario: Cliente hace pedido por WhatsApp
Given el usuario es un cliente (no dueno)
When envia mensaje "Quiero 3 tacos y una coca"
Then el LLM detecta que es cliente
And detecta intencion de pedido
And estructura el pedido con productos
And notifica al dueno del negocio
And responde al cliente con confirmacion
Scenario: Sin saldo de tokens
Given el negocio tiene saldo de tokens = 0
When el dueno envia mensaje por WhatsApp
Then el sistema responde con mensaje de saldo agotado
And ofrece opciones de recarga
```
---
## RF-008: WhatsApp Business
| Campo | Valor |
|-------|-------|
| **ID** | RF-008 |
| **Prioridad** | P0 |
| **Estado** | Implementado |
| **Epica** | [MCH-011](../01-epicas/MCH-011-whatsapp-service.md) |
### RF-008.1: Configuracion de Numero
- **Opción A**: WhatsApp Business propio del negocio
- Conexión vía Meta Business API
- Verificación del número
- **Opción B**: Número compartido de la plataforma
- Un número para múltiples negocios
- Detección de negocio por contexto
- "Hola, busco [Nombre Negocio]"
### RF-008.2: Detección de Rol
- Identificar si es dueño o cliente
- Dueño: Acceso completo a gestión
- Cliente: Solo consultas y pedidos
### RF-008.3: Mensajes Automatizados
- Bienvenida
- Fuera de horario
- Confirmación de pedido
- Recordatorio de fiado
- Alertas de inventario
### RF-008.4: Multimedia
- Recibir y procesar fotos (OCR)
- Recibir y transcribir audios
- Enviar tickets/reportes como imagen
- Enviar documentos PDF
## RF-009: Pagos y Suscripciones
### RF-009.1: Suscripción del Negocio
- Plan Changarrito ($99/mes)
- Plan Tiendita ($199/mes)
- Cambio de plan
- Cancelación
### RF-009.2: Métodos de Pago de Suscripción
- Tarjeta (Stripe) - Recurrente
- OXXO (Stripe) - Referencia única
- Play Store In-App Purchase
- App Store In-App Purchase
### RF-009.3: Paquetes de Tokens IA
- Compra de paquetes
- Visualización de saldo
- Historial de consumo
- Alertas de saldo bajo
### RF-009.4: Facturación (Opcional)
- Solicitar factura
- Datos fiscales del negocio
- Descarga de facturas
## RF-010: Reportes y Analytics
### RF-010.1: Dashboard Web
- Ventas del día/semana/mes
- Gráficas de tendencia
- Productos más vendidos
- Comparativas de periodos
### RF-010.2: Reportes Generables
- Ventas por periodo
- Inventario actual
- Productos por agotarse
- Fiados pendientes
- Ganancias y márgenes
- Cortes de caja históricos
### RF-010.3: Formatos de Exportación
- PDF
- Excel
- Imagen (para WhatsApp)
## RF-011: Notificaciones
### RF-011.1: Push Notifications
- Nuevo pedido de cliente
- Fiado por vencer
- Stock bajo
- Pago recibido
### RF-011.2: WhatsApp
- Resumen diario de ventas
- Alertas de inventario
- Recordatorios configurables
### RF-011.3: Configuración
- Activar/desactivar por tipo
- Horarios de no molestar
- Frecuencia
## RF-012: Modo Offline
### RF-012.1: Funcionalidad Sin Internet
- Registrar ventas
- Consultar productos y precios
- Agregar productos al carrito
- Ver historial local
### RF-012.2: Sincronización
- Automática al recuperar conexión
- Manual forzada
- Resolución de conflictos
- Indicador de datos pendientes
## RF-013: Integraciones de Terminal
### RF-013.1: Mercado Pago
- Pareado Bluetooth con terminal
- Envío de monto a cobrar
- Recepción de confirmación
- Manejo de errores/rechazos
### RF-013.2: Clip
- Pareado Bluetooth con terminal
- Envío de monto a cobrar
- Recepción de confirmación
- Manejo de errores/rechazos
### RF-013.3: CoDi
- Generación de QR
- Polling de confirmación
- Timeout y reintentos
## RF-014: Onboarding
### RF-014.1: Registro de Negocio
- Nombre del negocio
- Giro (abarrotes, comida, etc.)
- Ubicación (colonia, ciudad)
- Teléfono del dueño
### RF-014.2: Configuración Inicial Guiada
- Vía WhatsApp con LLM
- Paso a paso en app
- Cargar productos iniciales
- Seleccionar templates
### RF-014.3: Tutorial
- Primeros pasos interactivo
- Videos cortos
- Tips por WhatsApp los primeros días
## RF-015: Seguridad y Acceso
### RF-015.1: Autenticación
- Login con teléfono + OTP (SMS/WhatsApp)
- PIN de acceso rápido
- Biométrico (huella/face)
### RF-015.2: Roles (Futuro)
- Dueño: Acceso total
- Empleado: Solo ventas
- Contador: Solo reportes
### RF-015.3: Datos
- Encriptación en tránsito (HTTPS)
- Encriptación en reposo
- Backups automáticos
## RF-016: Programa de Referidos
### RF-016.1: Mecánica
- Código/link único por negocio
- Beneficio por referido: 1 mes gratis (ambos)
- Tracking de referidos
### RF-016.2: Comunicación
- Compartir por WhatsApp
- Ver referidos activos
- Historial de beneficios
## RF-017: Soporte
### RF-017.1: Autoservicio
- FAQ en app
- Videos tutoriales
- Asistente IA para dudas
### RF-017.2: Humano (Escalación)
- Chat con soporte (cuando IA no resuelve)
- Teléfono de emergencia
- Horario de atención
---
## RF-018: Sistema de Audit Logs
| Campo | Valor |
|-------|-------|
| **ID** | RF-018 |
| **Prioridad** | P1 |
| **Estado** | Pendiente |
| **Epica** | Pendiente de asignar |
| **Referencia SaaS** | SAAS-008 (template-saas) |
### RF-018.1: Registro de Eventos
- Log de acciones de usuario (login, logout, cambios)
- Log de operaciones de negocio (ventas, cambios de precio)
- Log de eventos de sistema (errores, integraciones)
- Metadata: timestamp, user_id, tenant_id, ip, action, details
### RF-018.2: Consulta de Logs
- Filtros por fecha, usuario, tipo de accion
- Busqueda full-text en detalles
- Exportacion CSV/JSON
- Retencion configurable (90 dias default)
### Criterios de Aceptacion
```gherkin
Feature: RF-018 - Audit Logs
Scenario: Registrar accion de venta
Given un usuario realiza una venta
When la transaccion se completa
Then se registra log con action="sale_created"
And incluye tenant_id, user_id, timestamp
And incluye detalles de la venta
Scenario: Consultar logs por fecha
Given existen logs de los ultimos 30 dias
When el admin filtra por fecha "2026-01-10"
Then muestra solo logs de esa fecha
And permite exportar a CSV
```
---
## RF-019: Feature Flags por Plan
| Campo | Valor |
|-------|-------|
| **ID** | RF-019 |
| **Prioridad** | P1 |
| **Estado** | Pendiente |
| **Epica** | Pendiente de asignar |
| **Referencia SaaS** | SAAS-009 (template-saas) |
### RF-019.1: Configuracion de Flags
- Flags globales (on/off para todos)
- Flags por plan (Changarrito vs Tiendita)
- Flags por tenant (override individual)
- UI de administracion para superadmin
### RF-019.2: Evaluacion de Flags
- SDK para evaluar flag en backend
- Hook para evaluar flag en frontend
- Cache de evaluaciones
- Default values seguros
### Criterios de Aceptacion
```gherkin
Feature: RF-019 - Feature Flags
Scenario: Feature habilitada por plan
Given el tenant tiene plan "Tiendita"
And feature "advanced_reports" esta habilitada para plan Tiendita
When el frontend evalua el flag
Then devuelve enabled=true
And muestra la funcionalidad
Scenario: Feature deshabilitada por plan
Given el tenant tiene plan "Changarrito"
And feature "advanced_reports" NO esta habilitada para plan Changarrito
When el frontend evalua el flag
Then devuelve enabled=false
And oculta la funcionalidad
And muestra mensaje de upgrade
```
---
## RF-020: Rate Limiting por Plan
| Campo | Valor |
|-------|-------|
| **ID** | RF-020 |
| **Prioridad** | P1 |
| **Estado** | Pendiente |
| **Epica** | Pendiente de asignar |
| **Referencia SaaS** | SAAS-005 (template-saas) |
### RF-020.1: Limites por Plan
| Limite | Changarrito | Tiendita |
|--------|-------------|----------|
| Transacciones/dia | 200 | Ilimitadas |
| Productos | 500 | 5,000 |
| Tokens IA/mes | 500 base | 2,000 base |
| Storage (MB) | 100 | 500 |
| Usuarios | 1 | 3 |
### RF-020.2: Enforcement
- Middleware de validacion en cada request
- Contadores en Redis
- Reset diario/mensual segun tipo
- Mensajes claros al alcanzar limite
- Upgrade path (link a subir plan)
### Criterios de Aceptacion
```gherkin
Feature: RF-020 - Rate Limiting
Scenario: Tenant alcanza limite de transacciones
Given el tenant tiene plan "Changarrito"
And ha registrado 200 transacciones hoy
When intenta registrar transaccion 201
Then recibe error "Limite diario alcanzado"
And muestra opcion de upgrade a plan Tiendita
Scenario: Reset de limite diario
Given el tenant alcanzo limite ayer
When inicia nuevo dia (00:00 UTC)
Then el contador de transacciones se resetea a 0
And puede registrar nuevas transacciones
```
---
## Referencias
### Documentos Relacionados
| Documento | Relacion |
|-----------|----------|
| [VISION-PROYECTO.md](./VISION-PROYECTO.md) | Contexto de negocio |
| [ARQUITECTURA-TECNICA.md](./ARQUITECTURA-TECNICA.md) | Implementacion tecnica |
| [Epicas](../01-epicas/_MAP.md) | Implementacion por epica |
### Inventarios
| Inventario | Contenido |
|------------|-----------|
| [MASTER_INVENTORY](../../orchestration/inventarios/MASTER_INVENTORY.yml) | Estado consolidado |
| [BACKEND_INVENTORY](../../orchestration/inventarios/BACKEND_INVENTORY.yml) | Modulos y endpoints |
### Patrones de Referencia (template-saas)
| Patron | Modulo |
|--------|--------|
| SAAS-008 | Audit Logs (RF-018) |
| SAAS-009 | Feature Flags (RF-019) |
| SAAS-005 | Plans/Limits (RF-020) |
---
**Sistema**: SIMCO v3.7.0
**Documento**: RF-MCH-001 v1.1.0
Reference in New Issue View Git Blame Copy Permalink