uecko-control-tiempos/docs/Ficha del proyecto UECKO.md

# Ficha del proyecto

## 1. Identificación

**Nombre del proyecto:**  
Aplicación de Control de Tiempos y Gestión UECKO

**Objetivo principal:**  
Desarrollar una aplicación para la gestión de tiempos, tareas, actividad, incidencias y procesos de Oficina Técnica y Oficina Comercial para Uecko. La aplicación debe centralizar la operativa de ambos módulos, conservar la trazabilidad y el histórico de la información y permitir la evolución funcional mediante nuevas versiones sin pérdida ni reconstrucción manual de datos.

**Estado actual:**  
En pruebas con datos demo

## 2. Repositorio

**Repositorio principal:**  
N/A

**Estructura general:**  
N/A

## 3. Stack tecnológico

**Backend:**  
N/A

**Frontend:**  
N/A

**Base de datos:**  
N/A

**Testing:**  
N/A

**Infraestructura / despliegue:**  
N/A

## 4. Arquitectura

**Estilo arquitectónico:**  
N/A

**Organización principal:**  
La aplicación se divide inicialmente en dos módulos funcionales:

* Oficina Comercial.
* Oficina Técnica.

Existe además una base común transversal que contiene las reglas compartidas de arquitectura, personas, perfiles, permisos, tareas, contextos, imputación de tiempos, trazabilidad, actualización y continuidad de datos.

Cada módulo mantiene su responsabilidad funcional y es propietario de los datos que genera. Los flujos, campos y permisos específicos deben definirse en el documento funcional correspondiente a cada módulo.

La aplicación y la base de datos deben mantenerse separadas conceptualmente:

* la aplicación contiene interfaz, lógica de negocio, pantallas, navegación y funcionalidades;
* la base de datos contiene usuarios, perfiles, permisos, presupuestos, expedientes, OF, estados, tareas, tiempos, errores, comentarios, trazabilidad e históricos.

**Límites arquitectónicos y de continuidad:**

* El programa y los datos deben permanecer separados.
* Una actualización de la aplicación no puede sobrescribir ni eliminar información operativa o histórica.
* Los datos deben sobrevivir a cualquier cambio de versión.
* Los cambios de estructura de datos deben realizarse mediante actualizaciones controladas.
* Antes de modificar la estructura de datos debe existir una copia de seguridad recuperable.
* Las nuevas versiones no pueden exigir reintroducir manualmente datos históricos.
* Las ampliaciones futuras deben integrarse sobre la base existente sin reconstruir usuarios, históricos ni datos comunes.
* Las migraciones de datos y actualizaciones deben quedar registradas.
* Los módulos pueden consultar información del otro módulo cuando sea necesario, pero no modificar datos ajenos salvo permiso expreso.
* Los cambios relevantes deben poder probarse en un entorno Beta antes de aplicarse a Producción.
* El desarrollador no debe operar directamente sobre datos de Producción fuera de los mecanismos previstos por la aplicación.

Las reglas técnicas que materializan estos límites se definen en los documentos de [arquitectura](arquitectura/), especialmente [visión general](arquitectura/vision-general.md), [backend](arquitectura/backend.md) y [datos y persistencia](arquitectura/datos-persistencia.md).

## 5. Convenciones relevantes

* Los perfiles se definen por puesto o función y se reutilizan entre las personas que desempeñen ese puesto.
* Una misma persona puede disponer de varios perfiles.
* El Máster asigna perfiles y permisos; el usuario no puede modificarlos por sí mismo.
* Tarea y contexto son conceptos diferentes:
  * la tarea indica qué trabajo se realiza;
  * el contexto indica para qué se realiza.
* Los contextos principales de la primera fase son:
  * Presupuesto;
  * OF;
  * Actividad general.
* Los grupos funcionales de tareas contemplados inicialmente son, como mínimo:
  * OT;
  * OC · Presupuestos;
  * OC · Back Office;
  * OC · Pedidos;
  * Comunes.
* Una tarea puede pertenecer a uno o varios grupos.
* Las tareas o grupos con histórico no se eliminan físicamente; se desactivan para nuevos usos.
* Solo puede existir una actividad activa a la vez.
* Debe permitirse tanto la imputación de tiempo en tiempo real como la imputación diferida.
* La imputación debe disponer de controles de solape y mantener trazabilidad.
* Back Office puede iniciar tareas sin número de presupuesto ni OF mediante un identificador interno y vincularlas posteriormente sin reescribir el tiempo registrado.
* Presupuestos imputa normalmente contra número de presupuesto, con posibilidad excepcional de hacerlo contra OF.
* Pedidos imputa contra OF.
* Oficina Técnica trabaja fundamentalmente contra OF.
* Cuando un expediente cambia de fase, los datos consolidados de la fase anterior quedan bloqueados para la edición ordinaria.
* Las correcciones posteriores a un cambio de fase deben realizarse mediante un procedimiento formal y quedar registradas.
* Un expediente puede existir incompleto, pero no puede avanzar de fase mientras falten datos obligatorios para dicha transición.
* Las fechas y horas de cambios de estado, el usuario que ejecuta las acciones y los registros automáticos del sistema no son editables por usuarios ordinarios.
* Las correcciones excepcionales realizadas por el Máster deben conservar:
  * valor anterior;
  * valor nuevo;
  * fecha;
  * hora;
  * usuario.
* Los números de presupuesto y OF son identificadores maestros externos procedentes de Factuges.
* La aplicación no debe generar, sustituir ni reutilizar números de presupuesto u OF.
* El presupuesto debe conservar su identidad de origen y las OF deben mantener su vínculo con el presupuesto del que proceden.

## 6. Comandos habituales

**Instalación:**

```bash
N/A
```

**Desarrollo:**

```bash
N/A
```

**Tests:**

```bash
N/A
```

**Typecheck:**

```bash
N/A
```

**Lint:**

```bash
N/A
```

## 7. Documentación de referencia

Principales documentos que deben consultarse antes de tomar decisiones:

* [Visión general de arquitectura](arquitectura/vision-general.md).
* [Arquitectura backend](arquitectura/backend.md).
* [Arquitectura de datos y persistencia](arquitectura/datos-persistencia.md).
* [Arquitectura frontend](arquitectura/frontend.md).
* [Convenciones del proyecto](arquitectura/convenciones.md).
* [Estrategia de testing](arquitectura/testing.md).

El respaldo técnico y los documentos funcionales de Oficina Comercial y Oficina Técnica citados anteriormente no están disponibles en este repositorio. Cuando se incorporen, deberán declararse aquí como referencias normativas con su ruta real.

## 8. Restricciones importantes

* No debe perderse información existente como consecuencia de una actualización.
* No deben sobrescribirse ni eliminarse usuarios, expedientes, OF, tareas, imputaciones de tiempo, errores, históricos, registros de actividad ni configuraciones funcionales durante una actualización.
* Debe mantenerse compatibilidad con los datos existentes entre versiones.
* Ninguna evolución futura debe requerir la reintroducción manual de datos históricos.
* Antes de cualquier cambio estructural de base de datos debe existir una copia de seguridad recuperable.
* Toda actualización debe realizar una copia automática de seguridad cuando corresponda.
* Debe existir un mecanismo de restauración o rollback que no dependa de conocimientos técnicos del usuario Máster.
* La aplicación debe impedir la instalación de paquetes de actualización no válidos o incompatibles.
* En la primera etapa, las actualizaciones se distribuyen como paquetes completos de versión, no como conjuntos de archivos sueltos.
* Las modificaciones relevantes deben poder validarse en Beta antes de pasar a Producción.
* El perfil Informática / Soporte no debe modificar por defecto reglas funcionales del negocio.
* El perfil Desarrollador no debe modificar directamente datos de Producción fuera de los mecanismos previstos.
* Los módulos no deben modificar datos propiedad de otros módulos salvo permiso expreso.
* No deben eliminarse físicamente tareas o grupos que tengan histórico.
* Los datos consolidados de una fase no deben modificarse mediante edición ordinaria después del avance de fase.
* Los registros automáticos, fechas de cambio de estado y usuarios asociados a acciones no deben ser editables por usuarios ordinarios.
* Los identificadores de presupuesto y OF procedentes de Factuges no pueden ser inventados, sustituidos ni reutilizados por la aplicación.
* Las nuevas decisiones funcionales deben incorporarse previamente al documento marco correspondiente antes de pasar a Producción.
* La aplicación debe limitarse a registrar, conservar, relacionar, mostrar, filtrar y exportar información. No debe emitir automáticamente juicios de rendimiento ni conclusiones de gestión.

## 9. Observaciones

La responsabilidad transversal de la primera fase corresponde a Dirección Técnica. Cada módulo conserva además su propia responsabilidad funcional mediante el Responsable de Oficina Comercial y el Responsable de Oficina Técnica.

Existe un perfil Máster con responsabilidad sobre permisos y decisiones funcionales, diferenciado de los perfiles Informática / Soporte y Desarrollador.

La aplicación contempla un nivel de experiencia UECKO calculado automáticamente a partir de la fecha de incorporación:

* Nivel 1: hasta 3 meses.
* Nivel 2: más de 3 y hasta 6 meses.
* Nivel 3: más de 6 y hasta 9 meses.
* Nivel 4: más de 9 y hasta 12 meses.
* Nivel 5: más de 12 meses.

Este nivel representa antigüedad y adaptación al entorno UECKO, no una calificación profesional. Cuando sea relevante para análisis posteriores, debe conservarse el nivel existente en el momento de asignación del trabajo.

Las actualizaciones deben generar un registro técnico independiente del histórico funcional, incluyendo fecha y hora, usuario, versión anterior, versión nueva, resultado y, cuando proceda, restauración posterior.

Mientras no exista integración automática con Factuges, los números de presupuesto y OF pueden incorporarse manualmente o mediante importación, manteniendo siempre Factuges como sistema de origen de dichos identificadores.