Punto de Venta (pv_app)

Aplicación Flutter para registrar ventas en negocios pequeños y medianos de forma rápida, con escaneo de productos, carrito, descuentos, confirmación de venta e historial según rol.

Producto

Objetivo

Reducir fricción en el flujo de venta diario:

• escanear productos por QR o código de barras
• construir un carrito
• aplicar descuentos y precios por volumen
• confirmar la venta
• compartir el resumen por WhatsApp

Alcance actual

• Login con autenticación contra backend existente
• Escaneo y agregado de productos al carrito
• Precios por volumen
• Descuentos por línea y por carrito
• Selección de método de pago
• Confirmación y anulación de venta
• Historial y detalle de ventas
• Restricción de visibilidad por rol (seller y admin)

Más contexto funcional en docs/project.md.

Stack

• Flutter
• Dart
• flutter_bloc / Cubit
• Dio
• get_it
• go_router
• flutter_secure_storage
• mobile_scanner

Arquitectura

El proyecto usa Clean Architecture con organización por features y separación entre presentation, domain y data.

lib/
  app/
    di/
    router/
    theme/
  core/
  features/
    auth/
    products/
    sales/

Reglas base:

• La UI no accede directo a red ni a implementaciones de data.
• Los flujos relevantes pasan por Cubit.
• domain no depende de Flutter.
• El backend trabaja montos en centavos enteros; la UI formatea a soles solo en presentación.

Más detalle en docs/architecture.md.

Theme y Figma

La app ya tiene una base de tokens para conectar exports de Figma con Flutter:

• el generador está en tool/generate_figma_theme.dart
• el snapshot generado queda en lib/app/theme/tokens/figma_token_source.g.dart
• la app consume esos valores mediante AppTheme, AppColorTokens, AppTextStyles y extensiones de BuildContext

Guía corta de uso:

• docs/figma-theme-generator.md

Desarrollo local

Requisitos

• Flutter SDK instalado
• Dart SDK compatible con el sdk definido en pubspec.yaml
• Backend disponible y credenciales válidas para login

Comandos básicos

flutter pub get
flutter run

Análisis estático:

flutter analyze

Tests:

flutter test

Forma de trabajo del proyecto

El repo se viene trabajando por vertical slices. El orden general ha sido:

1. definir slice
2. documentar contrato backend
3. implementar
4. auditar
5. corregir hallazgos bloqueantes
6. registrar deuda técnica si aplica

Estado actual del roadmap:

• vertical slices core completados
• fase de Quality & Hardening en progreso
• UI Alignment with Figma pendiente

Referencia:

• docs/roadmap.md

Documentación útil

• docs/project.md
• docs/architecture.md
• docs/roadmap.md
• docs/tech-debt.md
• docs/figma-theme-generator.md