ijuanes/inventschario
ijuanes/inventschario
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
inventschario/especificaciones.md
pikaos ee849eb9a8 feat: roadmap y diseño inicial — iteración 1 antes de feedback del usuario 
Inventario de dispositivos electrónicos no prestables para administración
pública. Esta primera iteración contiene el diseño y la planificación
antes de contactar con el usuario para su validación.

Contenido:
- especificaciones.md: requisitos detallados del programa
- docs/arquitectura.md: propuesta de arquitectura con alternativas
- docs/roadmap-iteracion-1.md: plan de desarrollo iteración 1
- docs/arquitectura-diagrama.html: diagrama visual de arquitectura
- sketches/: mockups de las 4 pantallas principales
  - 001-dashboard: vista resumen
  - 002-inventario: tabla de dispositivos
  - 003-formulario: alta/edición de dispositivos
  - 004-configuracion: ajustes generales

Stack propuesto: Python + Flask + SQLite + Alpine.js
Distribución: PyInstaller → un único .exe autocontenido
Entorno: Windows 11 Pro unida a dominio, sin privilegios de admin
2026-08-03 01:34:56 +01:00

836 lines
36 KiB
Markdown
Raw Blame History

# Inventschario — Especificaciones del Programa
**Versión:** 1.0.0-iteracion1
**Fecha:** 2026-08-03
**Estado:** Borrador para feedback del usuario
---
## 1. Resumen del Producto
**Inventschario** es una aplicación de inventario de dispositivos electrónicos no
prestables (ordenadores, monitores, periféricos, equipos de red, etc.) diseñada
para ejecutarse en una única máquina Windows 11 Pro unida a un dominio. La
aplicación se distribuye como un único paquete, se ejecuta en el navegador por
defecto del usuario y almacena sus datos en una base de datos SQLite local.
El usuario tiene privilegios de instalador pero NO de administrador. La
aplicación se instala únicamente en el directorio del usuario y aparece solo en
el Menú Inicio de dicho usuario.
---
## 2. Restricciones del Entorno
| Restricción | Detalle |
|------------------------------|-------------------------------------------------------------------------|
| SO | Windows 11 Pro |
| Dominio | Unida a dominio corporativo |
| Privilegios del usuario | Instalador (puede instalar software en su perfil), NO administrador |
| Distribución | Un único paquete autocontenido (sin dependencias externas en runtime) |
| Interfaz | Navegador por defecto del sistema (Edge), se abre al doble clic |
| Instalación | Solo en el directorio del usuario, Menú Inicio del usuario |
| Red | Mínima latencia (frontend y backend en la misma máquina) |
| Copias de seguridad | Automáticas diarias, recordatorio para limpieza de antiguas |
---
## 3. Funcionalidades Principales
### 3.1 Gestión de Dispositivos
#### 3.1.1 Campos de Identificación (Renombrables)
La aplicación debe soportar múltiples campos de registro para cada dispositivo.
El usuario puede renombrar la etiqueta visible de cada campo en la interfaz,
pero el nombre interno en la base de datos permanece constante.
| Campo BD (interno) | Etiqueta por defecto | Tipo | Obligatorio |
|------------------------|-------------------------------|------------|-------------|
| `serial_number` | Número de Serie | Texto | Sí |
| `service_tag` | Service Tag | Texto | No |
| `catalog_number` | Número de Catálogo Interno | Texto | Sí |
| `additional_registry` | Registro Adicional | Texto | No |
El sistema de renombrado se almacena en una tabla de configuración:
```sql
CREATE TABLE field_labels (
field_key TEXT PRIMARY KEY, -- e.g. 'serial_number'
label TEXT NOT NULL, -- e.g. 'Número de Serie'
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
#### 3.1.2 Campos Descriptivos del Dispositivo
| Campo BD | Etiqueta por defecto | Tipo | Obligatorio |
|-------------------------|----------------------------|------------|-------------|
| `device_name` | Nombre / Descripción | Texto | Sí |
| `device_type` | Tipo de Dispositivo | Enum | Sí |
| `brand` | Marca | Texto | No |
| `model` | Modelo | Texto | No |
| `serial_internal` | Número de Serie Interno | Texto | No |
| `purchase_date` | Fecha de Compra | Fecha | No |
| `warranty_expiry` | Fin de Garantía | Fecha | No |
| `purchase_price` | Precio de Compra (€) | Decimal | No |
| `assigned_location` | Ubicación Asignada | Texto | No |
| `assigned_user` | Usuario Asignado | Texto | No |
| `department` | Departamento | Texto | No |
| `status` | Estado | Enum | Sí |
| `condition` | Estado Físico | Enum | No |
| `notes` | Notas | Texto | No |
| `photo_path` | Ruta Foto | Texto | No |
#### 3.1.3 Tipos de Dispositivo (Enum)
- `computer` — Ordenador de sobremesa
- `laptop` — Portátil
- `monitor` — Monitor / Pantalla
- `printer` — Impresora
- `scanner` — Escáner
- `network_device` — Dispositivo de red (switch, router, AP)
- `peripheral` — Periférico (teclado, ratón, auriculares)
- `server` — Servidor
- `ups` — SAI / Regulador
- `storage` — Almacenamiento externo
- `other` — Otro
#### 3.1.4 Estados del Dispositivo (Enum)
| Estado | Descripción |
|-----------------|------------------------------------------------|
| `active` | En uso, asignado y operativo |
| `available` | Disponible, sin asignar |
| `maintenance` | En mantenimiento / reparación |
| `decommissioned`| Dado de baja |
| `disposed` | Enajenado / desechado |
| `lost` | Extraviado / no localizado |
| `reserved` | Reservado para asignación futura |
#### 3.1.5 Estado Físico (Enum)
- `excellent` — Excelente
- `good` — Bueno
- `fair` — Regular
- `poor` — Malo
- `damaged` — Dañado
### 3.2 Ciclo de Vida del Dispositivo (Administración Pública)
La aplicación debe gestionar el ciclo de vida completo de cada dispositivo,
incluyendo trámites de administración pública:
#### 3.2.1 Altas
- Registro manual de un nuevo dispositivo
- Importación masiva desde CSV
- Asignación automática de número de inventario interno
#### 3.2.2 Modificaciones
- Edición de cualquier campo del dispositivo
- Historial de cambios (quién, cuándo, qué cambió)
- Reasignación de ubicación / usuario / departamento
#### 3.2.3 Bajas
- Baja por obsolescencia
- Baja por avería irreversible
- Baja por robo / extravío
- Baja por fin de garantía sin renovación
- Registro del motivo de baja
- Fecha efectiva de baja
- Responsable que autoriza la baja
#### 3.2.4 Enajenación
- Enajenación por venta
- Enajenación por donación
- Enajenación por transferencia a otro organismo
- Registro del destinatario / adquirente
- Documento de enajenación (referencia)
- Importe de enajenación si aplica
- Fecha efectiva de enajenación
#### 3.2.5 Historial de Cambios
```sql
CREATE TABLE device_history (
id INTEGER PRIMARY KEY AUTOINCREMENT,
device_id INTEGER NOT NULL,
action TEXT NOT NULL, -- 'created', 'modified', 'decommissioned', 'disposed', ...
field_changed TEXT, -- NULL para acciones de ciclo completo
old_value TEXT,
new_value TEXT,
performed_by TEXT NOT NULL,
performed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
notes TEXT,
FOREIGN KEY (device_id) REFERENCES devices(id)
);
```
### 3.3 Copias de Seguridad
#### 3.3.1 Backup Automático Diario
- Se ejecuta una vez al día (configurable la hora)
- Copia completa de la base de datos SQLite
- Almacena en `%APPDATA%/inventschario/backups/`
- Formato de nombre: `inventschario_YYYYMMDD_HHMMSS.db`
- Comprimido en formato `.gz` para ahorrar espacio
#### 3.3.2 Gestión de Backups
- Al iniciar la aplicación, comprueba si hay backups con más de N días (configurable)
- Muestra un recordatorio al usuario indicando cuántos backups antiguos existen
- El usuario decide eliminar los antiguos o mantenerlos
- Opción para crear un backup manual en cualquier momento
- Opción para restaurar desde un backup específico
#### 3.3.3 Configuración de Backups
| Parámetro | Valor por defecto | Descripción |
|------------------------------|-------------------|---------------------------------------|
| `backup_enabled` | `true` | Habilitar backups automáticos |
| `backup_hour` | `02:00` | Hora diaria del backup |
| `backup_retention_days` | `30` | Días antes de sugerir eliminación |
| `backup_max_keep` | `90` | Máximo de backups a conservar |
| `backup_path` | `%APPDATA%/inventschario/backups/` | Ruta de almacenamiento |
### 3.4 Importación y Exportación
#### 3.4.1 Exportación a CSV
- Exporta todos los dispositivos o una selección filtrada
- Usa las etiquetas renombradas como cabeceras del CSV
- Separador configurable (coma, punto y coma, tabulador)
- Codificación UTF-8 con BOM para compatibilidad con Excel
- Opción de incluir solo columnas visibles
#### 3.4.2 Importación desde CSV
Sistema modular diseñado para ser extensible:
**Fase 1 (Implementación inicial):**
- Selección del archivo CSV
- Mapeo automático de columnas por posición o nombre
- Vista previa de los primeros 10 registros
- Detección de duplicados (por serial_number o catalog_number)
- Opciones ante duplicados: saltar, sobrescribir, crear como nuevo
- Registro de errores por fila
**Fase 2 (Extensibilidad futura):**
- Interfaz de mapeo visual de campos (drag & drop)
- Guardar perfiles de importación (plantillas)
- Transformaciones de datos durante la importación (regex, lookup)
- Importación desde Excel (.xlsx) directamente
#### 3.4.3 Arquitectura Modular de Importación/Exportación
```
import_export/
├── __init__.py
├── base.py # Clases abstractas ImporterBase, ExporterBase
├── csv_importer.py # Implementación CSV
├── csv_exporter.py # Implementación CSV
├── field_mapper.py # Motor de mapeo de campos
├── validator.py # Validación de datos importados
└── profiles/ # Perfiles de importación guardados
```
### 3.5 Interfaz de Usuario
#### 3.5.1 Requisitos de Usabilidad y Accesibilidad
- Navegación por teclado completa (Tab, Enter, Escape, atajos)
- Contraste de color WCAG 2.1 AA mínimo (4.5:1 texto, 3:1 elementos UI)
- Tamaño mínimo de objetivo de clic: 44x44 px
- Labels asociados a todos los inputs
- Mensajes de error claros y posicionados junto al campo
- Feedback visual en hover, focus, y active states
- Responsive (aunque el uso principal es escritorio)
- Modo de alto contraste soportado
- Texto alternativo en iconos decorativos
#### 3.5.2 Pantallas / Pestañas
1. **Dashboard** — Vista resumen con estadísticas clave
2. **Inventario** — Tabla de dispositivos con búsqueda, filtros, ordenación
3. **Agregar Dispositivo** — Formulario de alta
4. **Detalle / Edición** — Ficha completa del dispositivo con historial
5. **Baja / Enajenación** — Formulario de ciclo de vida
6. **Importar / Exportar** — Interfaz de importación y exportación CSV
7. **Configuración** — Parámetros generales, labels de campos, backups
8. **Configuración Inicial** — Wizard de primera ejecución
#### 3.5.3 Configuración Inicial (Primera Ejecución)
Al detectar que no existe base de datos, se muestra un wizard:
1. **Paso 1:** Bienvenida y nombre de la institución / organismo
2. **Paso 2:** Configuración de campos de registro (renombrar etiquetas)
3. **Paso 3:** Tipos de dispositivo a gestionar (seleccionar cuáles activar)
4. **Paso 4:** Configuración de copias de seguridad
5. **Paso 5:** Ubicaciones / Departamentos predefinidos (opcional)
6. **Paso 6:** Confirmación y creación de la base de datos
---
## 4. Modelo de Datos (SQLite)
### 4.1 Diagrama Entidad-Relación
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ devices │ │ device_history │ │ field_labels │
├─────────────────┤ ├──────────────────┤ ├─────────────────┤
│ id (PK) │◄────│ device_id (FK) │ │ field_key (PK) │
│ serial_number │ │ id (PK) │ │ label │
│ service_tag │ │ action │ │ updated_at │
│ catalog_number │ │ field_changed │ └─────────────────┘
│ additional_reg │ │ old_value │
│ device_name │ │ new_value │ ┌──────────────────┐
│ device_type │ │ performed_by │ │ app_config │
│ brand │ │ performed_at │ ├──────────────────┤
│ model │ │ notes │ │ key (PK) │
│ serial_internal │ └──────────────────┘ │ value │
│ purchase_date │ │ updated_at │
│ warranty_expiry │ ┌──────────────────┐ └──────────────────┘
│ purchase_price │ │ locations │
│ assigned_loc │ ├──────────────────┤ ┌──────────────────┐
│ assigned_user │ │ id (PK) │ │ departments │
│ department │ │ name │ ├──────────────────┤
│ status │ │ building │ │ id (PK) │
│ condition │ │ floor │ │ name │
│ notes │ │ room │ └──────────────────┘
│ photo_path │ └──────────────────┘
│ created_at │
│ updated_at │ ┌──────────────────┐
└─────────────────┘ │ backup_log │
├──────────────────┤
│ id (PK) │
│ filename │
│ size_bytes │
│ created_at │
│ is自動 │
└──────────────────┘
```
### 4.2 Script de Creación de la Base de Datos
```sql
-- Inventschario v1.0.0
-- Base de datos de inventario de dispositivos electrónicos
PRAGMA journal_mode=WAL;
PRAGMA foreign_keys=ON;
CREATE TABLE devices (
id INTEGER PRIMARY KEY AUTOINCREMENT,
serial_number TEXT NOT NULL,
service_tag TEXT,
catalog_number TEXT NOT NULL,
additional_registry TEXT,
device_name TEXT NOT NULL,
device_type TEXT NOT NULL DEFAULT 'other',
brand TEXT,
model TEXT,
serial_internal TEXT,
purchase_date DATE,
warranty_expiry DATE,
purchase_price DECIMAL(10,2),
assigned_location TEXT,
assigned_user TEXT,
department TEXT,
status TEXT NOT NULL DEFAULT 'active',
condition TEXT DEFAULT 'good',
notes TEXT,
photo_path TEXT,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE UNIQUE INDEX idx_devices_catalog ON devices(catalog_number);
CREATE INDEX idx_devices_serial ON devices(serial_number);
CREATE INDEX idx_devices_status ON devices(status);
CREATE INDEX idx_devices_type ON devices(device_type);
CREATE TABLE device_history (
id INTEGER PRIMARY KEY AUTOINCREMENT,
device_id INTEGER NOT NULL,
action TEXT NOT NULL,
field_changed TEXT,
old_value TEXT,
new_value TEXT,
performed_by TEXT NOT NULL,
performed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
notes TEXT,
FOREIGN KEY (device_id) REFERENCES devices(id) ON DELETE CASCADE
);
CREATE INDEX idx_history_device ON device_history(device_id);
CREATE INDEX idx_history_date ON device_history(performed_at);
CREATE TABLE field_labels (
field_key TEXT PRIMARY KEY,
label TEXT NOT NULL,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE app_config (
key TEXT PRIMARY KEY,
value TEXT NOT NULL,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE locations (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL UNIQUE,
building TEXT,
floor TEXT,
room TEXT
);
CREATE TABLE departments (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL UNIQUE
);
CREATE TABLE backup_log (
id INTEGER PRIMARY KEY AUTOINCREMENT,
filename TEXT NOT NULL,
size_bytes INTEGER,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
is_auto BOOLEAN DEFAULT 1
);
-- Valores por defecto para field_labels
INSERT INTO field_labels (field_key, label) VALUES
('serial_number', 'Número de Serie'),
('service_tag', 'Service Tag'),
('catalog_number', 'Número de Catálogo Interno'),
('additional_registry', 'Registro Adicional'),
('device_name', 'Nombre / Descripción'),
('device_type', 'Tipo de Dispositivo'),
('brand', 'Marca'),
('model', 'Modelo'),
('purchase_date', 'Fecha de Compra'),
('warranty_expiry', 'Fin de Garantía'),
('purchase_price', 'Precio de Compra (€)'),
('assigned_location', 'Ubicación Asignada'),
('assigned_user', 'Usuario Asignado'),
('department', 'Departamento'),
('status', 'Estado'),
('condition', 'Estado Físico');
-- Valores por defecto para app_config
INSERT INTO app_config (key, value) VALUES
('institution_name', ''),
('backup_enabled', 'true'),
('backup_hour', '02:00'),
('backup_retention_days', '30'),
('backup_max_keep', '90'),
('csv_separator', ';'),
('csv_encoding', 'utf-8-sig'),
('setup_complete', 'false');
```
---
## 5. Arquitectura del Sistema
### 5.1 Requisitos Arquitectónicos
- **Modularidad total:** Separación frontend / backend con pasarela (API)
- **Independencia de interfaz:** Cambiar el frontend no afecta al backend
- **Autocontenido:** Todas las dependencias empaquetadas en un solo ejecutable
- **Sin privilegios de admin:** Instalación y ejecución en perfil de usuario
- **Baja latencia:** Frontend y backend en la misma máquina
### 5.2 Capas
```
┌─────────────────────────────────────────────┐
│ NAVEGADOR (Edge) │
│ ┌───────────────────────────────────────┐ │
│ │ FRONTEND (HTML/CSS/JS) │ │
│ │ Framework ligero: Alpine.js o Vanilla│ │
│ └──────────────────┬────────────────────┘ │
│ │ HTTP/localhost │
├─────────────────────┼───────────────────────┤
│ SERVIDOR LOCAL │
│ ┌──────────────────┴────────────────────┐ │
│ │ API GATEWAY (REST/JSON) │ │
│ │ Endpoints: /api/devices, /api/... │ │
│ └──────────────────┬────────────────────┘ │
│ │ │
│ ┌──────────────────┴────────────────────┐ │
│ │ CAPA DE SERVICIOS │ │
│ │ DeviceService, BackupService, etc. │ │
│ └──────────────────┬────────────────────┘ │
│ │ │
│ ┌──────────────────┴────────────────────┐ │
│ │ CAPA DE DATOS (SQLite) │ │
│ │ Repository pattern, migraciones │ │
│ └───────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
```
### 5.3 API REST (Especificación)
Todas las rutas comienzan con `/api/v1/`.
#### Dispositivos
| Método | Ruta | Descripción |
|--------|------------------------------|-----------------------------------|
| GET | `/api/v1/devices` | Listar dispositivos (con filtros) |
| GET | `/api/v1/devices/:id` | Obtener dispositivo por ID |
| POST | `/api/v1/devices` | Crear dispositivo |
| PUT | `/api/v1/devices/:id` | Actualizar dispositivo |
| DELETE | `/api/v1/devices/:id` | Eliminar dispositivo (soft delete)|
| POST | `/api/v1/devices/:id/decommission` | Dar de baja |
| POST | `/api/v1/devices/:id/dispose` | Enajenar |
| GET | `/api/v1/devices/:id/history` | Historial de cambios |
#### Importación / Exportación
| Método | Ruta | Descripción |
|--------|------------------------------|-----------------------------------|
| GET | `/api/v1/export/csv` | Exportar a CSV |
| POST | `/api/v1/import/csv` | Importar desde CSV |
| GET | `/api/v1/import/preview` | Vista previa de importación |
#### Configuración
| Método | Ruta | Descripción |
|--------|------------------------------|-----------------------------------|
| GET | `/api/v1/config` | Obtener configuración |
| PUT | `/api/v1/config` | Actualizar configuración |
| GET | `/api/v1/config/labels` | Obtener etiquetas de campos |
| PUT | `/api/v1/config/labels` | Actualizar etiquetas de campos |
| POST | `/api/v1/config/initialize` | Ejecutar wizard de configuración |
#### Backups
| Método | Ruta | Descripción |
|--------|------------------------------|-----------------------------------|
| GET | `/api/v1/backups` | Listar backups |
| POST | `/api/v1/backups/create` | Crear backup manual |
| POST | `/api/v1/backups/:id/restore`| Restaurar desde backup |
| DELETE | `/api/v1/backups/:id` | Eliminar backup |
| GET | `/api/v1/backups/check-aging`| Verificar backups antiguos |
#### Ubicaciones y Departamentos
| Método | Ruta | Descripción |
|--------|------------------------------|-----------------------------------|
| GET | `/api/v1/locations` | Listar ubicaciones |
| POST | `/api/v1/locations` | Crear ubicación |
| GET | `/api/v1/departments` | Listar departamentos |
| POST | `/api/v1/departments` | Crear departamento |
---
## 6. Alternativas Tecnológicas
### Opción A: Python + Flask + SQLite (Recomendada)
| Aspecto | Detalle |
|------------------|-----------------------------------------------------------|
| Backend | Python 3.11+ con Flask |
| Base de datos | SQLite3 (incluido en Python stdlib) |
| Frontend | HTML/CSS/JS + Alpine.js (ligero, sin build step) |
| Empaquetado | PyInstaller → un único `.exe` |
| Tamaño aprox. | 25-40 MB |
| Ventajas | Ecosistema rico, fácil de desarrollar, SQLite nativo |
| Desventajas | PyInstaller a veces tiene problemas con antimalware |
| Dependencias | Flask, schedule (para backups) — todo empaquetado |
### Opción B: .NET 8 Self-Contained
| Aspecto | Detalle |
|------------------|-----------------------------------------------------------|
| Backend | ASP.NET Core minimal API |
| Base de datos | Microsoft.Data.Sqlite |
| Frontend | HTML/CSS/JS embebido en wwwroot |
| Empaquetado | `dotnet publish -r win-x64 --self-contained` |
| Tamaño aprox. | 60-80 MB |
| Ventajas | Nativo Windows, sin runtime externo, excelente rendimiento|
| Desventajas | Más verboso que Python, curva de aprendizaje mayor |
| Dependencias | Ninguna en runtime (self-contained) |
### Opción C: Go + SQLite
| Aspecto | Detalle |
|------------------|-----------------------------------------------------------|
| Backend | Go stdlib `net/http` + `mattn/go-sqlite3` |
| Base de datos | SQLite via CGO |
| Frontend | HTML/CSS/JS embebido via `embed` |
| Empaquetado | Binario compilado estático |
| Tamaño aprox. | 10-15 MB |
| Ventajas | Binario más pequeño, rendimiento excepcional |
| Desventajas | CGO complicationa el build cross-platform, menos ecosistema web |
| Dependencias | Ninguna en runtime |
### Opción D: Electron + SQLite
| Aspecto | Detalle |
|------------------|-----------------------------------------------------------|
| Backend | Node.js (embebido en Electron) |
| Base de datos | better-sqlite3 |
| Frontend | React/Vue/Svelte dentro de Electron |
| Empaquetado | electron-builder → instalador .exe |
| Tamaño aprox. | 150-200 MB |
| Ventajas | UI rica, familiar para devs frontend |
| Desventajas | Muy pesado para una app de inventario, innecesario |
| Dependencias | Chromium embebido |
### Comparativa Resumen
| Criterio | Python+Flask | .NET 8 | Go | Electron |
|------------------------|:------------:|:---------:|:---------:|:---------:|
| Tamaño del paquete | ★★★★ | ★★★ | ★★★★★ | ★★ |
| Facilidad de desarrollo| ★★★★★ | ★★★ | ★★★ | ★★★★ |
| Rendimiento | ★★★ | ★★★★★ | ★★★★★ | ★★★ |
| Sin dependencias RT | ★★★ (PyInst)| ★★★★★ | ★★★★★ | ★★★ |
| Ecosistema web | ★★★★★ | ★★★★ | ★★★ | ★★★★★ |
| Compatibilidad AV | ★★★ | ★★★★★ | ★★★★★ | ★★★★ |
| Modularidad frontend | ★★★★★ | ★★★★★ | ★★★★ | ★★★★★ |
**Recomendación:** Python + Flask (Opción A) para la iteración inicial. Si el
tamaño o la detección por antivirus se convierten en problemas, migrar a .NET 8.
---
## 7. Estructura de Directorios
```
inventschario/
├── especificaciones.md # Este documento
├── docs/
│ ├── arquitectura.md # Documento de arquitectura detallada
│ └── roadmap-iteracion-1.md # Roadmap de la primera iteración
├── sketches/ # Mockups de diseño de interfaz
│ ├── 001-dashboard/
│ ├── 002-inventario/
│ ├── 003-formulario/
│ └── 004-configuracion/
├── src/
│ ├── __init__.py
│ ├── main.py # Punto de entrada
│ ├── server.py # Servidor Flask
│ ├── config.py # Configuración de la aplicación
│ ├── database/
│ │ ├── __init__.py
│ │ ├── connection.py # Conexión SQLite
│ │ ├── models.py # Modelos de datos
│ │ ├── migrations.py # Migraciones de esquema
│ │ └── schema.sql # Esquema inicial
│ ├── services/
│ │ ├── __init__.py
│ │ ├── device_service.py # Lógica de dispositivos
│ │ ├── backup_service.py # Gestión de backups
│ │ ├── import_service.py # Importación CSV
│ │ ├── export_service.py # Exportación CSV
│ │ └── config_service.py # Configuración general
│ ├── api/
│ │ ├── __init__.py
│ │ ├── devices.py # Rutas API de dispositivos
│ │ ├── imports.py # Rutas API de importación
│ │ ├── exports.py # Rutas API de exportación
│ │ ├── backups.py # Rutas API de backups
│ │ └── config.py # Rutas API de configuración
│ ├── import_export/
│ │ ├── __init__.py
│ │ ├── base.py # Clases abstractas
│ │ ├── csv_importer.py # Importador CSV
│ │ ├── csv_exporter.py # Exportador CSV
│ │ ├── field_mapper.py # Motor de mapeo
│ │ └── validator.py # Validación de datos
│ └── utils/
│ ├── __init__.py
│ ├── scheduler.py # Programador de backups
│ └── paths.py # Rutas de archivos
├── frontend/
│ ├── index.html # Página principal (SPA)
│ ├── css/
│ │ └── styles.css # Estilos globales
│ ├── js/
│ │ ├── app.js # Router y estado global
│ │ ├── api.js # Cliente HTTP para la API
│ │ ├── components/ # Componentes reutilizables
│ │ │ ├── table.js
│ │ │ ├── form.js
│ │ │ ├── modal.js
│ │ │ ├── toast.js
│ │ │ └── sidebar.js
│ │ └── pages/ # Páginas / vistas
│ │ ├── dashboard.js
│ │ ├── inventory.js
│ │ ├── device-form.js
│ │ ├── device-detail.js
│ │ ├── lifecycle.js
│ │ ├── import-export.js
│ │ ├── settings.js
│ │ └── setup-wizard.js
│ └── assets/
│ └── icons/ # Iconos SVG
├── tests/
│ ├── test_devices.py
│ ├── test_import.py
│ ├── test_backup.py
│ └── test_config.py
├── pyproject.toml
├── requirements.txt
└── README.md
```
---
## 8. Requisitos No Funcionales
### 8.1 Rendimiento
- Tiempo de respuesta API: < 100ms (local)
- Carga de página inicial: < 2 segundos
- Búsqueda en inventario: < 500ms con 10,000 dispositivos
- Importación CSV: < 5 segundos para 1,000 registros
### 8.2 Seguridad
- El servidor solo escucha en `127.0.0.1` (localhost)
- No se exponen puertos a la red
- No se almacenan credenciales en texto plano
- Backups cifrados (futuro, iteración 2)
- Logs de auditoría para acciones críticas
### 8.3 Fiabilidad
- WAL mode en SQLite para concurrencia de lectura
- Backups automáticos diarios
- Integridad referencial con foreign keys
- Validación de datos tanto en backend como frontend
### 8.4 Mantenibilidad
- Código modular con separation of concerns
- API REST bien documentada
- Tests unitarios y de integración
- Migraciones de esquema versionadas
---
## 9. Flujo de Usuario — Escenarios Principales
### 9.1 Primera Ejecución
```
Doble clic en icono del Menú Inicio
→ Se abre Edge en http://localhost:PORT
→ Detector: no hay DB → Wizard de configuración
→ Paso 1: Nombre de institución
→ Paso 2: Etiquetas de campos de registro
→ Paso 3: Tipos de dispositivo a gestionar
→ Paso 4: Configuración de backups
→ Paso 5: Ubicaciones y departamentos (opcional)
→ Paso 6: Confirmación → Crear DB
→ Redirige al Dashboard
```
### 9.2 Alta de Dispositivo
```
Click "Agregar Dispositivo" (sidebar o botón)
→ Formulario con campos obligatorios marcados
→ Autocompletado de campos numéricos de registro
→ Validación en tiempo real
→ Submit → Guarda en BD → Historial "created"
→ Toast de confirmación → permanece en formulario para siguiente alta
```
### 9.3 Búsqueda y Edición
```
En pestaña Inventario:
→ Barra de búsqueda (búsqueda full-text)
→ Filtros: tipo, estado, departamento, ubicación
→ Click en fila → Detalle del dispositivo
→ Click "Editar" → Modo edición inline
→ Cambios guardados → Historial "modified"
```
### 9.4 Baja / Enajenación
```
En detalle del dispositivo:
→ Click "Dar de Baja" o "Enajenar"
→ Modal con:
- Tipo de baja/enajenación
- Fecha efectiva
- Motivo / observaciones
- Responsable autorizador
→ Confirmar → Estado cambia → Historial actualizado
→ Dispositivo aparece como "Baja" / "Enajenado" en el inventario
```
### 9.5 Backup Diario
```
Servidor inicia → Scheduler programado a las 02:00
→ BackupService.crear_backup():
- Copia el archivo .db
- Comprime con gzip
- Registra en backup_log
→ Al iniciar la app, BackupService.verificar_antiguos():
- Si hay backups > retention_days → Toast informativo
- "Hay X backups con más de N días. ¿Desea eliminarlos?"
- Botones: "Eliminar antiguos" / "Mantener"
```
---
## 10. Criterios de Aceptación — Iteración 1
- [ ] El usuario puede instalar la aplicación en su perfil de Windows
- [ ] El icono aparece en el Menú Inicio del usuario
- [ ] Al doble clic, se abre Edge con la aplicación
- [ ] El wizard de configuración initial crea la BD correctamente
- [ ] Se pueden crear, editar, y dar de baja dispositivos
- [ ] La tabla de inventario muestra búsqueda, filtros y ordenación
- [ ] Se pueden renombrar las etiquetas de los campos de registro
- [ ] Las copias de seguridad se ejecutan diariamente
- [ ] Se muestra recordatorio de backups antiguos al iniciar
- [ ] Se pueden exportar dispositivos a CSV
- [ ] Se pueden importar dispositivos desde CSV
- [ ] El historial de cambios se registra correctamente
- [ ] La interfaz es navegable por teclado
- [ ] Los colores cumplen WCAG 2.1 AA
---
## 11. Futuras Iteraciones (Roadmap)
### Iteración 2
- Cifrado de backups
- Autenticación de usuario (si se necesita multi-usuario)
- Informes y gráficos (distribución por tipo, estado, departamento)
- Impresión de etiquetas de inventario
### Iteración 3
- Escáner de códigos de barras / QR
- Sincronización con Active Directory
- API para integración con otros sistemas
- Importación desde Excel (.xlsx)
### Iteración 4
- Multi-idioma (i18n)
- Modo oscuro
- Notificaciones de garantía próxima a vencer
- Dashboard con métricas avanzadas
---
*Documento generado como parte de la primera iteración del proyecto Inventschario.
Sujeto a revisión y feedback del usuario.*
Reference in a new issue View git blame Copy permalink