Saltar a contenido

Sprint 01 — Onboarding + Catálogo de Productos

Instancia de sprint. Tracker activo del Sprint 1.

1. Datos del sprint

Campo Valor
Número 01
Objetivo Que un nuevo tenant pueda completar el wizard de onboarding, ver su suscripción y gestionar su catálogo de productos con stock por sucursal
Estado CERRADO
Tag git sprint-01

2. Tareas planificadas

Antes de pasar una tarea a EN_PROGRESO: completar su instancia en prompts/AGENT_TASK_TEMPLATE.md con contexto, alcance y criterios de aceptación. Sin eso, el agente improvisa.

# Tarea Agente Rama git Depende de Estado
1 app_suscripciones — modelo Suscripcion + FeatureFlag + validación en core_api Backend feat/suscripciones-feature-flags — CERRADA
2 app_empresas — wizard onboarding backend + CRUD Sucursal Backend feat/onboarding-sucursales T1 CERRADA
3 app_inventario — modelos Categoria, PlantillaRubro, AtributoConfig, Producto (JSONB), StockSucursal + APIs CRUD Backend feat/inventario-base T1 CERRADA
4 Frontend — wizard de onboarding (pantallas de configuración inicial del tenant) Frontend feat/frontend-onboarding T2 CERRADA
5 Frontend — catálogo de productos (listar, crear, editar, ver stock por sucursal) Frontend feat/frontend-catalogo T3 CERRADA

3. Agentes involucrados

  • Backend — T1, T2, T3
  • Frontend — T4, T5

4. Definition of Done — proceso

El sprint está completo cuando:

  • [ ] Todas las ramas mergeadas a main.
  • [ ] Todos los PRs aprobados con PR_CHECKLIST.md.
  • [ ] Tests ejecutados y sin regresiones.
  • [ ] Documentación actualizada: ARCHITECTURE.md, FOLDER_STRUCTURE.md, WORKFLOW.md según aplique.
  • [ ] Tag sprint-01 creado en main.
  • [ ] docs/PROJECT_STATUS.md actualizado.
  • [ ] docs/NEXT_ACTION.md actualizado.
  • [ ] Esta instancia marcada como CERRADO en SPRINT_INDEX.md.

5. Definition of Done — técnico

  • [ ] GET /api/suscripciones/mi-plan/ retorna el plan activo del tenant con JWT válido.
  • [ ] Un endpoint con feature flag bloqueado retorna 403 si el plan no lo habilita.
  • [ ] POST /api/empresas/onboarding/ completa el wizard y transiciona Empresa a WIZARD_COMPLETADO.
  • [ ] GET /api/empresas/sucursales/ lista solo las sucursales del tenant activo (aislamiento multi-tenant verificado).
  • [ ] POST /api/inventario/productos/ crea un producto con especificaciones JSONB validado contra PlantillaRubro.
  • [ ] GET /api/inventario/productos/ retorna productos con stock de la sucursal activa.
  • [ ] GET /api/inventario/stock/?sucursal=X filtra por sucursal y respeta el scope del rol.
  • [ ] Usuario de otro tenant no puede ver productos ni stock de este tenant (403 o 404).
  • [ ] Tests de permisos: sin login 401, rol insuficiente 403, tenant ajeno 403/404.
  • [ ] Frontend onboarding: el wizard completa el flujo sin errores y redirige al dashboard.
  • [ ] Frontend catálogo: se pueden listar, crear y editar productos desde la UI.

6. Resumen de cierre

Fecha de cierre: 2026-06-27

Completado

  • T1 — app_suscripciones: modelo Suscripcion + FeatureFlag + validación en core_api (PR #16)
  • T2 — app_empresas: wizard onboarding backend + CRUD Sucursal (PR #18)
  • T3 — app_inventario: Categoria, PlantillaRubro, AtributoConfig, Producto JSONB, StockSucursal + APIs CRUD (PR #19)
  • T4 — Frontend wizard onboarding: 3 pasos, guards de ruta, estadoOnboarding en store, 40 tests (PR #20)
  • T5 — Frontend catálogo de productos: ProductosPage, ProductoFormPage, StockPage, permisos por rol, JSONB dinámico, 83 tests (PR #23)
  • Protocolo profesional de 6 fases con QA y Security como subagentes en cada tarea (PR #22)
  • CI GitHub Actions verde en todo el sprint — 68 tests backend + 83 tests frontend

Pendiente / movido al backlog

  • Auditoría de ajustes de stock (MovimientoStock) — backlog #6. Decisión: cajero puede ver stock de cualquier sucursal del tenant; los ajustes deben ser auditables con registro de usuario, sucursal, cantidad, motivo y timestamp
  • Rate limiting en POST /api/auth/token/ — backlog #7. Sin throttle actual
  • Tests 401 faltantes en categorías y stock, idempotencia de seed, import de permiso en clase — backlog #14
  • Test de regresión test_me_retorna_campo_rol en backend — deuda técnica menor

Decisiones tomadas

  • GET /api/auth/me/ incluye campo rol (primer acceso activo del usuario en el tenant, order_by('id') determinístico). Decisión pragmática para MVP — ADR pendiente para escenario multi-rol real (sesión 9)
  • Cajero puede leer stock de cualquier sucursal del tenant — comportamiento intencional por diseño de negocio (confirmado sesión 9)
  • @hookform/resolvers agregado como dependencia de frontend (necesario para integración RHF + Zod)
  • usePlantillas() auto-selecciona la plantilla si el tenant tiene una sola — patrón para MVP (la mayoría de tenants tienen una plantilla de rubro)

Estado de salida

SPRINT_01_STATUS: CERRADO