ToldoConjunto/openspec/specs/toldo-poc/spec.md

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