Estándar: IEEE Std 830-1998
Versión: 2.0 | Fecha: 14 de Octubre de 2026
Estado: Documento en Producción

1. Introducción
   1. Propósito
   2. Alcance
   3. Definiciones, Acrónimos y Abreviaturas
   4. Referencias
   5. Resumen
2. Descripción General
   1. Perspectiva del Producto
   2. Funciones del Producto
   3. Clases y Características de Usuario
   4. Entorno Operativo
   5. Restricciones de Diseño e Implementación
   6. Documentación de Usuario
   7. Suposiciones y Dependencias
3. Requisitos Específicos
   1. Requisitos de Interfaz Externa
   2. Requisitos Funcionales (Módulos #US01 a #US12)
   3. Requisitos de Rendimiento
   4. Restricciones de Diseño
   5. Atributos del Sistema y Requisitos No Funcionales (RNF-SEG, ENABLER-QA)
   6. Requisitos de Base de Datos
4. Verificación y Trazabilidad de Requisitos
   1. Matriz Base de Casos de Prueba y Métodos
   2. Auditoría vs Implementación en Repositorio (Issues/PRs)
      1. Matriz Extendida de Cumplimiento Funcional
      2. Evaluación Auditada de Requisitos No Funcionales
5. Anexos y Tareas Transversales
   1. Glosario de Códigos de Error

Este documento tiene como objetivo definir de manera exhaustiva los requisitos para el sistema TodoStock, una solución integral de gestión de inventarios. Este documento sirve como base para el desarrollo, pruebas y despliegue del ecosistema, asegurando que todos los componentes (Móvil, Web y Backend) funcionen armónicamente.

TodoStock es una plataforma multipropósito que incluye:

• Backend (Django REST Framework): El motor central que gestiona la persistencia de datos, lógica de negocio, autenticación JWT y procesamiento de movimientos.
• Frontend Web (Angular): Una Single Page Application (SPA) para administración centralizada, gestión de usuarios, sucursales y reportes.
• App Móvil (Android Java): Una aplicación nativa diseñada para el personal de depósito y ventas en campo, con soporte para gestión de inventario y modo offline.

Fuera del Alcance:

• Procesamiento de pagos directos con tarjetas de crédito (se delega a pasarelas externas).
• Gestión de nómina de empleados (RH).

• SRS: Software Requirements Specification.
• JWT: JSON Web Token (Estándar para autenticación segura).
• ORM: Object-Relational Mapping (Django Models).
• SPA: Single Page Application (Arquitectura de Angular).
• Retrofit: Librería de Android para comunicación con APIs REST.
• CORS: Cross-Origin Resource Sharing.
• ACID: Atomicity, Consistency, Isolation, Durability (Propiedades de transacciones de BD).

1. Estándar IEEE 830-1998.
2. Documentación oficial de Django REST Framework.
3. Guía de diseño de Angular (v17+).
4. Principios de arquitectura limpia de Android.
5. Wiki del proyecto TodoStock (GitHub).

El sistema se divide en tres subsistemas principales que interactúan a través de protocolos seguros HTTPS. La lógica de negocio está centralizada en el backend, mientras que el frontend y la app móvil actúan como clientes ricos que proporcionan una experiencia de usuario optimizada para sus respectivos entornos.

TodoStock se concibe como un ecosistema distribuido. No es solo una aplicación, sino una red de herramientas sincronizadas.

graph TD
    subgraph Clientes ["Capa de Presentación (Clientes)"]
        A["📱 App Móvil (Android Java)<br/>Retrofit + SesionManager"]
        B["💻 App Web (Angular SPA)<br/>Standalone Components + Signals"]
    end

    subgraph Backend ["Capa de Aplicación (Backend)"]
        C["🌐 Proxy Inverso (Nginx)"]
        D["🐍 Backend Server (Django REST Framework)<br/>JWT Auth + Serializers + ORM"]
    end

    subgraph Persistencia ["Capa de Datos"]
        E[("🛢️ Base de Datos<br/>MySQL")]
    end

    A -->|"HTTPS / JSON (Bearer JWT)"| C
    B -->|"HTTPS / JSON (Bearer JWT)"| C
    C -->|"Reverse Proxy / WSGI"| D
    D -->|"Django ORM (Consultas ACID)"| E

El sistema permite realizar las siguientes acciones críticas:

• Registro de usuarios con roles específicos (Administrador, Empleado).
• Inicio de sesión seguro con emisión de tokens JWT (token_access, token_refresh).
• Protección de rutas basada en guards (Angular) e interceptores (AuthInterceptor en Android).

• Catalogación de productos con SKU únicos.
• Gestión de stock segmentado por sucursales.
• Definición de stocks mínimos globales y por sucursal para alertas visuales.

• Registro de Entradas y Salidas.
• Traslados atómicos entre sucursales con validación de stock origen.

• Servidor: Python 3.10+, Django 6.0, MySQL. Despliegue en Alwaysdata / Docker / Nginx.
• Web: Navegadores modernos (Chrome, Firefox, Safari) compatibles con Angular 17+.
• Móvil: Dispositivos Android 7.0 (Nougat) o superior (API 24+).

• Lenguaje: Backend en Python, Frontend en TypeScript, Móvil en Java nativo.
• Seguridad: Gestión centralizada de sesión con SesionManager (SharedPreferences) en Android para tokens JWT.
• Comunicación: Formato JSON estricto en todas las APIs REST.

Se proporcionará:

• Wiki técnica en el repositorio de GitHub.
• Manual de usuario e instructivos en la sección de Ayuda de la app.
• Guía de Aclaraciones Docente (GUÍA-DOCENTE.md).

• Web: Diseño responsivo con TailwindCSS / Angular Material.
• Móvil: Interfaz optimizada en Java / Material Design 3 con Activities y layouts XML.

• El backend expone endpoints bajo /api/.
• Comunicación vía Retrofit HTTP Client en Android con AuthInterceptor.

• FR-AUTH-01: El sistema permitirá el login mediante email y contraseña validando credenciales contra la API (POST /api/usuarios/login/).
• FR-AUTH-02: Los tokens JWT tendrán tiempo de expiración corto con renovaciones mediante refresh token (POST /api/usuarios/token/refresh/).
• FR-AUTH-03: En Android, la sesión se administra en SesionManager (SharedPreferences) inyectando el token Bearer en AuthInterceptor. Si la sesión expira o es inválida, el usuario es redirigido automáticamente a LoginActivity.
• FR-AUTH-04: SplashActivity evalúa el estado de la sesión guardada y decide el destino (MenuPrincipalActivity o LoginActivity).

[US01] Autenticación y Menú Principal

• ID: US01 | Prioridad: Alta (Bloqueante) | Story Points: 8 (Sprint 1: 5 SP | Sprint 2: 3 SP)
• Responsable: Miguel Flores / Aylén Bartolino Luna
• Narrativa: Como usuario quiero iniciar sesión y acceder a un menú principal para navegar hacia el resto de la app según mi rol.
• Criterios de Aceptación: Transición fluida Login → Menú Principal, menú condicional según el rol (Administrador o Empleado), validaciones de campos y cierre de sesión efectivo.
• Endpoints: POST /api/usuarios/login/, POST /api/usuarios/token/refresh/

Tareas Técnicas Asociadas (#US01):

• FR-SUC-01: El sistema obtendrá la lista de sucursales activas desde la API (GET /api/inventario/sucursales/).
• FR-SUC-02: Al seleccionar una sucursal, la app almacena y transmite el sucursal_id por Intent para filtrar los productos e inventarios.

[US02] Selección de Sucursal

• ID: US02 | Prioridad: Alta | Story Points: 7 (Sprint 1: 5 SP | Sprint 2: 2 SP)
• Responsable: Candelaria Barjollo
• Narrativa: Como usuario quiero elegir la sucursal con la que voy a trabajar para que las demás pantallas muestren su información.
• Criterios de Aceptación: Lista en SeleccionSucursalActivity poblada con SucursalAdapter, selección persistente y transmisión del sucursal_id.
• Endpoints: GET /api/inventario/sucursales/

Tareas Técnicas Asociadas (#US02):

• FR-STK-01: Visualización de stock de productos por sucursal (GET /api/inventario/productos/{id}/stock/ o por query sucursal_id).
• FR-STK-02: Resaltado visual automático en StockAdapter cuando la cantidad de un ítem sea menor o igual al umbral mínimo (cantidad_stock <= stock_min).

[US03] Gestión e Inventario de Stock

• ID: US03 | Prioridad: Alta | Story Points: 10 (Sprint 1: 5 SP | Sprint 2: 5 SP)
• Responsable: Virginia Garcia
• Narrativa: Como Administrador o Empleado quiero ver una lista de productos con su cantidad de stock de la sucursal elegida para conocer la situación del inventario.
• Criterios de Aceptación: Lista reactiva en GestionStockActivity, filtrado por sucursal_id y alerta visual destacada en rojo ante stock bajo umbral.
• Endpoints: GET /api/inventario/productos/{id}/stock/

Tareas Técnicas Asociadas (#US03):

• FR-CONT-01: Envío de mensajes de soporte e incidencias desde ContactoActivity conectando con POST /api/contacto/.
• FR-CONT-02: Selector de sucursal en formulario de contacto poblado con datos de sucursales reales.

[US04] Contacto y Soporte

• ID: US04 | Prioridad: Media | Story Points: 5 (Sprint 1: 3 SP | Sprint 2: 2 SP)
• Responsable: Pedro Gonzalez
• Narrativa: Como usuario quiero ver una pantalla de contacto para comunicarme con soporte si lo necesito.
• Criterios de Aceptación: Formulario con nombre, email, sucursal, mensaje, validaciones de campos vacíos y confirmación por Toast/API.
• Endpoints: POST /api/contacto/

Tareas Técnicas Asociadas (#US04):

• FR-PROD-01: Creación de nuevos productos en catálogo (POST /api/inventario/productos/). Acción reservada a usuarios con rol Administrador.
• FR-PROD-02: Validaciones de código SKU único, precios mayores a cero y campos obligatorios.

[US05] Carga de Productos

• ID: US05 | Prioridad: Alta | Story Points: 7 (Sprint 1: 3 SP | Sprint 2: 4 SP)
• Responsable: Pedro Gonzalez
• Narrativa: Como Administrador quiero cargar un nuevo producto para que esté disponible en el catálogo.
• Criterios de Aceptación: Formulario en CargaProductoActivity, validaciones de entradas y persistencia en servidor mediante POST.
• Endpoints: POST /api/inventario/productos/

Tareas Técnicas Asociadas (#US05):

• FR-MOV-01: Registro de transferencias de inventario entre sucursales origen y destino con validación de stock disponible.
• FR-MOV-02: Procesamiento atómico en backend (POST /api/vendedor/movimientos/ o /api/inventario/movimientos/): la transacción incrementa y decrementa existencias de forma dual.

[US06] Movimientos entre Sucursales

• ID: US06 | Prioridad: Alta | Story Points: 7 (Sprint 1: 4 SP | Sprint 2: 3 SP)
• Responsable: Aylén Bartolino Luna
• Narrativa: Como Empleado o Administrador quiero registrar un movimiento de stock entre dos sucursales para que la existencia se actualice en ambas.
• Criterios de Aceptación: Formulario con spinners origen/destino, selección de producto y cantidad, bloqueo si origen = destino o cantidad <= 0.
• Endpoints: POST /api/vendedor/movimientos/

Tareas Técnicas Asociadas (#US06):

• FR-REG-01: Solicitud de alta de cuenta en RegistroActivity mediante POST /api/usuarios/registro/ (nombre, email, DNI, fecha de nacimiento con edad mínima +18 y contraseña).
• FR-REG-02: Estado inicial de la cuenta en PENDIENTE de aprobación por un Administrador.

[US07] Registro de Usuarios

• ID: US07 | Prioridad: Alta | Story Points: 6 (Sprint 2: 6 SP)
• Responsable: Aylén Bartolino Luna
• Narrativa: Como visitante quiero registrarme con mis datos para solicitar mi cuenta en la app.
• Criterios de Aceptación: Formulario de registro con validaciones de campos, formato DNI, edad mínima +18 y contraseña en Validadores.java.
• Endpoints: POST /api/usuarios/registro/

Tareas Técnicas Asociadas (#US07):

• FR-USR-ADM-01: Listado, aprobación, asignación de rol (ADMINISTRADOR o EMPLEADO) y desactivación de usuarios desde la API (GET/PUT/DELETE /api/usuarios/). Acción exclusiva de Administradores.
• FR-USR-ADM-02: Menú condicional por rol en MenuPrincipalActivity (#TK48): las opciones administrativas solo se despliegan si es_admin es verdadero.

[US08] Control y Gestión de Usuarios (Admin)

• ID: US08 | Prioridad: Alta | Story Points: 7 (Sprint 2: 7 SP)
• Responsable: Miguel Flores / Candelaria Barjollo
• Narrativa: Como Administrador quiero cargar, aprobar, listar, editar y dar de baja usuarios para controlar quién accede y con qué rol.
• Criterios de Aceptación: Listado de usuarios, asignación de roles, activación de cuentas pendientes y control de acceso.
• Endpoints: GET/PUT/DELETE /api/usuarios/, GET /api/usuarios/roles/

Tareas Técnicas Asociadas (#US08):

• FR-PROD-ADM-01: Edición y baja lógica de productos (PUT/DELETE /api/inventario/productos/<id>/). Exclusivo para Administradores.

[US09] Edición y Eliminación de Productos (Admin)

• ID: US09 | Prioridad: Media | Story Points: 4 (Sprint 2: 4 SP)
• Responsable: Pedro Gonzalez
• Narrativa: Como Administrador quiero editar y eliminar productos para mantener el catálogo libre de datos obsoletos.
• Criterios de Aceptación: Modificación de campos de productos y eliminación lógica con control de error si posee existencias.
• Endpoints: PUT/DELETE /api/inventario/productos/<id>/

Tareas Técnicas Asociadas (#US09):

• FR-UX-01: Pantalla e instructivos de ayuda para guiar al usuario en la operatoria del sistema.
• FR-UX-02: Adaptabilidad de layouts para orientaciones landscape y tablets, manteniendo el estado de UI ante rotaciones de pantalla.

[US10 & RNF-UX] Ayuda e Instructivos de Uso

• ID: US10 / RNF-UX | Prioridad: Media | Story Points: 4 (Sprint 2: 4 SP)
• Responsable: Miguel Flores / Equipo
• Narrativa: Como usuario quiero ver una pantalla de ayuda con instructivos y contar con un diseño adaptable al rotar el dispositivo.
• Criterios de Aceptación: Pantalla de ayuda funcional, preservación de estado en rotación de pantalla.

Tareas Técnicas Asociadas (#US10 / RNF-UX):

• FR-LEG-01: Pantalla TerminosActivity para visualización de Términos y Condiciones y Políticas de Privacidad (Ley 25.326).
• FR-LEG-02: Mecanismo de arrepentimiento y solicitud de baja de cuenta propia en BajaDeCuenta conectando con DELETE /api/usuarios/me/.

[US11] Legislación, Términos y Baja de Cuenta

• ID: US11 | Prioridad: Media | Story Points: 5 (Sprint 2: 5 SP)
• Responsables: Aylén Bartolino Luna / Octavio Arnaudo
• Narrativa: Como usuario quiero conocer y controlar el uso de mis datos personales y contar con la opción de darme de baja.
• Criterios de Aceptación: Visualización de textos legales en TerminosActivity y opción activa de baja de cuenta en BajaDeCuenta.
• Endpoints: DELETE /api/usuarios/me/

Tareas Técnicas Asociadas (#US11):

• FR-PERFIL-01: Consulta y actualización de datos personales del propio usuario autenticado (PerfilActivity y EditarPerfilActivity) mediante GET/PATCH /api/usuarios/me/.

[US12] Perfil de Usuario Propio

• ID: US12 | Prioridad: Alta | Story Points: 4 (Sprint 2: 4 SP)
• Responsable: Candelaria Barjollo
• Narrativa: Como usuario quiero ver y editar mis datos personales para mantener mi información actualizada.
• Criterios de Aceptación: Vista de perfil en PerfilActivity y formulario de modificación en EditarPerfilActivity conectado a la API.
• Endpoints: GET/PATCH /api/usuarios/me/

Tareas Técnicas Asociadas (#US12):

• PE-01: Tiempo de respuesta de la API < 1s para consultas de inventario y autenticación.
• PE-02: Carga fluida de RecyclerViews de stock y sucursales con scroll reactivo.

• Arquitectura Android: Aplicación nativa en Java, arquitectura por capas (network, repositorio, sesion, validacion) y vistas XML con Material Design.
• Arquitectura Backend: Django REST Framework expuesto en /api/ con base de datos MySQL.

• NFR-SEC-01: Inyección automática del header Authorization: Bearer <token> mediante AuthInterceptor.
• NFR-SEC-02: Gestión centralizada de sesión mediante SesionManager (SharedPreferences).
• NFR-SEC-03: Registro automático de eventos sensibles en la tabla LogAuditoria en servidor (#TK51).
• NFR-SEC-04: Comunicaciones encriptadas vía HTTPS / TLS 1.2+.

Tareas Técnicas de Ciberseguridad (#RNF-SEG):

• NFR-QA-01: Suite de pruebas unitarias implementada en ValidadoresTest.java (app/src/test/java/com/ispc/todostock/validacion/) aplicando el patrón Arrange-Act-Assert (AAA) sobre contraseñas, emails, DNI y edad mínima (+18).

Tareas Técnicas de Testing y Calidad (#ENABLER-QA):

Tareas Técnicas Transversales y de Proceso (#MGMT / #RELEASE):

El esquema relacional está diseñado para soportar integridad referencial estricta.

erDiagram
    ROLE {
        int id PK
        string nombre UK
        string descripcion
    }
    USUARIO {
        int id PK
        string nombre
        string email UK
        string dni UK
        date fecha_nacimiento
        string password
        int rol_id FK
    }
    CATEGORIA {
        int id_cat PK
        string nombre
    }
    PRODUCTO {
        int id_art PK
        string nombre
        string codigo UK
        string descripcion
        decimal precio_venta
        int stock_min_global
        int id_cat FK
    }
    SUCURSAL {
        int id_suc PK
        string nombre
        string direccion
        boolean es_central
    }
    STOCK_SUCURSAL {
        int id_stock PK
        int id_art FK
        int id_suc FK
        int cantidad_stock
        int stock_min
    }
    PROVEEDOR {
        int id_prov PK
        string nombre
        string cuit UK
        string telefono
        string email
        string direccion
    }
    PRODUCTO_PROVEEDOR {
        int id_enlace PK
        int id_art FK
        int id_prov FK
        decimal precio_costo
    }
    MOVIMIENTO {
        int id_mov PK
        string tipo
        datetime fecha_hora
        int cantidad
        int stock_previo
        string motivo
        int id_art FK
        int id_suc FK
        int id_usuario FK
        int id_prov FK
    }

    ROLE ||--o{ USUARIO : "asignado_a"
    CATEGORIA ||--o{ PRODUCTO : "clasifica"
    USUARIO ||--o{ MOVIMIENTO : "registra"
    PRODUCTO ||--o{ STOCK_SUCURSAL : "posee"
    SUCURSAL ||--o{ STOCK_SUCURSAL : "almacena"
    PRODUCTO ||--o{ MOVIMIENTO : "involucra"
    SUCURSAL ||--o{ MOVIMIENTO : "ocurre_en"
    PROVEEDOR ||--o{ MOVIMIENTO : "origina"
    PRODUCTO ||--o{ PRODUCTO_PROVEEDOR : "provisto_por"
    PROVEEDOR ||--o{ PRODUCTO_PROVEEDOR : "provee"

1. USUARIO: id, nombre, email (PK), password, rol_id.
2. PRODUCTO: id_art (PK), nombre, codigo (Unique), precio_venta, stock_min_global.
3. SUCURSAL: id_suc (PK), nombre, direccion.
4. STOCK_SUCURSAL: id_stock (PK), id_art (FK), id_suc (FK), cantidad_stock.
5. MOVIMIENTO: id_mov (PK), tipo, fecha_hora, id_art (FK), id_suc (FK), id_usuario (FK).

El contraste directo entre las especificaciones IEEE 830, el código fuente nativo en app/, el backend y los registros de Pull Requests confirma el cumplimiento total del alcance acordado:

1. Seguridad (RNF-SEG): Verificado mediante el almacenamiento seguro de tokens con EncryptedSharedPreferences, expiración de acceso a los 15 minutos, rotación de refresh tokens y archivo de seguridad network_security_config.xml limitando la comunicación a HTTPS.
2. Rendimiento y Adaptabilidad (RNF-PERF / RNF-UX): Peticiones asíncronas con Retrofit2 y OkHttp3 en hilos secundarios, renderizado fluido en RecyclerView y adaptabilidad completa a orientación Apaisada (Landscape) y Tablets mediante ScrollView y preservación de estado con onSaveInstanceState (#TK41 - PR #294).
3. Calidad de Código y Testing (RNF-QA): Cobertura unitaria, red y UI automatizada en Android (app/src/test/ y app/src/androidTest/):
   • Pruebas Unitarias: ValidadoresTest.java (TK60 - AAA), StockItemTest.java (TK61) y LoginViewModelTest.java (TK62).
   • Pruebas de Red: ParseoRespuestasTest.java (TK64 - 200 OK) y AuthRepositoryTest.java (TK65 - HTTP 500) con MockWebServer.
   • Pruebas de UI Automatizadas (Espresso - AUT-UI-01 / TK70 - PR #299): Flujo completo Login ➔ Menú en LoginFlujoTest.java utilizando Page Objects (LoginScreen, MenuPrincipalScreen), AccessibilityChecks.enable() e IdlingResource.
   • Integración de API (Postman - AUT-API-02 / TK68 - PR #298): Suite Postman de catálogo de productos e infraestructura utilitaria en PostmanConfig.java.

• 401 Unauthorized: El JWT ha expirado o es inválido.
• 403 Forbidden: El rol del usuario no tiene permisos para la acción (ej. Empleado intentando acción de Administrador).
• 422 Unprocessable Entity / 400 Bad Request: Error de validación (ej. campos vacíos, contraseñas fuera de norma o DNI/email duplicado).

FIN DEL DOCUMENTO