# Spec: toldo-poc

## Capability: Inventario

### Requirement: Registrar inventario inicial
The system SHALL allow registering initial inventory for products at the start of market day.

#### Scenario: Registro de inventario inicial
- **GIVEN** products exist for producers
- **WHEN** user registers initial inventory with quantities for each product
- **THEN** movements of type INGRESO_INICIAL are recorded
- **AND** initial inventory is stored for the day

### Requirement: Detectar diferencias de inventario
The system SHALL detect and record differences between expected inventory (from previous day) and actual inventory.

#### Scenario: Diferencia detectada
- **GIVEN** there is a previous day's final inventory
- **WHEN** current inventory count differs from expected
- **THEN** the difference is recorded and visible in reports
- **AND** the real inventory is used going forward

### Requirement: Registrar ingresos entre semana
The system SHALL allow registering product restocks during the week to warehouse/bodega.

#### Scenario: Ingreso en semana
- **GIVEN** a product needs restocking
- **WHEN** user registers ingreso with product, quantity, and person who received
- **THEN** movement of type INGRESO_SEMANA is recorded with receivedBy
- **AND** inventory is updated

## Capability: Ventas

### Requirement: Registrar ventas
The system SHALL allow registering sales with product lines, quantities, prices, and payment method.

#### Scenario: Venta en efectivo
- **GIVEN** products with stock available
- **WHEN** user creates a sale with product lines paying in EFECTIVO
- **THEN** venta and ventaLineas are recorded
- **AND** inventory is decremented
- **AND** sale is counted in cash total

#### Scenario: Venta con QR
- **GIVEN** products with stock available
- **WHEN** user creates a sale with product lines paying in QR
- **THEN** sale is recorded with formaPago QR
- **AND** sale is counted in QR total separately

### Requirement: Productos distintos por productor
The system SHALL treat products from different producers as different products even if same name.

#### Scenario: Mismo nombre diferente productor
- **GIVEN** "Café molido 250gr" exists for Productor A and Productor B
- **WHEN** selling
- **THEN** they are different productos with different IDs
- **AND** reported separately by producer

## Capability: Gastos

### Requirement: Registrar gastos
The system SHALL allow registering expenses during the day.

#### Scenario: Gasto registrado
- **GIVEN** an expense occurs
- **WHEN** user registers gasto with concepto and monto
- **THEN** gasto is recorded with fecha
- **AND** included in cash reconciliation

## Capability: Cuadre de Caja

### Requirement: Realizar cuadre de caja
The system SHALL allow end-of-day cash reconciliation.

#### Scenario: Cuadre completo
- **GIVEN** base inicial, ventas (cash/QR), gastos (cash/QR) recorded
- **WHEN** user performs cuadre
- **THEN** saldoEsperadoEfectivo is calculated (base + ventas efectivo - gastos efectivo)
- **AND** user can enter saldoRealEfectivo
- **AND** descuadreEfectivo is calculated
- **AND** QR totals compared (registrado vs banco)
- **AND** totalVentas = ventas efectivo + ventas QR

### Requirement: Detectar descuadres
The system SHALL track and report discrepancies.

#### Scenario: Descuadre en efectivo
- **GIVEN** saldoEsperadoEfectivo != saldoRealEfectivo
- **WHEN** cuadre is saved
- **THEN** descuadreEfectivo is recorded
- **AND** visible in cuadre report

## Capability: Ajustes

### Requirement: Ajustes requieren motivo
The system SHALL require a reason for any adjustment.

#### Scenario: Ajustar inventario con motivo
- **GIVEN** need to adjust inventory
- **WHEN** user creates ajuste with producto, cantidadNueva, and motivo
- **THEN** ajuste is saved with motivo (non-empty)
- **AND** marked as modified/changed
- **AND** motivo appears in final report

### Requirement: Ajustes trazables
The system SHALL track all adjustments with before/after values.

#### Scenario: Trazabilidad de ajuste
- **GIVEN** an adjustment is made
- **THEN** cantidadAnterior, cantidadNueva, diferencia recorded
- **AND** fecha and motivo recorded
- **AND** appears in reports marked as changed

## Capability: Reportes

### Requirement: Reporte por productor
The system SHALL generate reports by producer.

#### Scenario: Reporte por productor completo
- **GIVEN** sales and inventory data for the day
- **WHEN** generating report by producer
- **THEN** shows inventory differences vs previous day
- **AND** shows initial inventory (real)
- **AND** shows inventory movements from sales (salidas)
- **AND** shows sales value for producer's products
- **AND** shows total per producer

### Requirement: Reporte de cuadre de caja
The system SHALL generate cash reconciliation report.

#### Scenario: Reporte cuadre
- **GIVEN** cuadre data
- **WHEN** generating report
- **THEN** shows fecha/hora, concepto, ingreso, gastos, saldo
- **AND** separate sections for efectivo and QR
- **AND** shows descuadres if any
- **AND** shows totalVentas (efectivo + QR)

### Requirement: Reporte consolidado
The system SHALL generate consolidated reports by date range, week, or month.

#### Scenario: Consolidado por rango
- **GIVEN** multiple days of data
- **WHEN** generating consolidated report for date range
- **THEN** aggregates sales, expenses, adjustments
- **AND** shows totals by producer

## Capability: Persistencia y Exportar/Importar

### Requirement: Exportar datos
The system SHALL export all data in versioned JSON format.

#### Scenario: Exportar
- **GIVEN** data exists in the app
- **WHEN** user exports
- **THEN** JSON file is generated with schemaVersion, appVersion, exportedAt, data
- **AND** file can be saved/shared

### Requirement: Importar datos
The system SHALL import data with validation and migration support.

#### Scenario: Importar válido
- **GIVEN** a valid exported JSON file
- **WHEN** user imports
- **THEN** schemaVersion is validated
- **AND** data is migrated if needed or imported directly
- **AND** data is stored in local DB

#### Scenario: Importar incompatible
- **GIVEN** JSON with incompatible schemaVersion
- **WHEN** user imports
- **THEN** clear error message is shown
- **AND** import is rejected

## Capability: Offline y Empaquetado

### Requirement: Funcionar offline
The system SHALL work completely offline.

#### Scenario: Modo avión
- **GIVEN** app installed/running with no network
- **WHEN** performing all operations (inventory, sales, expenses, reports)
- **THEN** all operations work correctly
- **AND** data persists locally

### Requirement: Empaquetado APK
The system SHALL be buildable as Android APK via Capacitor.

#### Scenario: Generar APK
- **GIVEN** built web assets
- **WHEN** running cap sync android
- **THEN** Android project is updated
- **AND** APK can be built and installed on Android tablet