Pre-computed merge for change #6

Contexto general en formato HU (roles y capacidades de negocio)
para copiar al MD de sistema, sin detalle de arquitectura.

Co-authored-by: alberto.martinez <alberto.martinez@mrdev.mx>

docs/historias-usuario.md

@@ -0,0 +1,144 @@
+# PANELS — Historias de usuario (estado actual)
+
+Contexto de producto para pegar en reglas / sistema. Describe **qué puede hacer el usuario hoy**, no arquitectura ni roadmap.
+
+PANELS es un escritorio de obra para constructoras en México. Cada cliente (tenant) opera su propia empresa, personal, obras, costos y nómina. Los operadores de PANELS administran tenants desde una consola aparte.
+
+## Roles
+
+| Rol | Quién es |
+|-----|----------|
+| Operador de plataforma | Personal de PANELS. Crea y da acceso a constructoras. |
+| Administrador del tenant | Usuario de la constructora con control total (empresas, usuarios, config). |
+| Usuario operativo | Personal de la constructora con acceso a módulos según permisos (padrón, gastos, almacén, etc.). |
+
+Formato: **Como** rol, **quiero** capacidad, **para** beneficio.
+
+---
+
+## Acceso y cuenta
+
+- Como usuario, quiero iniciar sesión con usuario y contraseña, para entrar a mi escritorio o a la consola según mi tipo de cuenta.
+- Como usuario, quiero cerrar sesión, para que nadie use mi sesión en el mismo equipo.
+- Como usuario nuevo o con clave temporal, quiero cambiar mi contraseña al primer acceso, para no trabajar con una clave compartida.
+- Como administrador del tenant, quiero que un operador de plataforma no entre al escritorio de obra, para separar la consola de PANELS del día a día de la constructora.
+- Como usuario, quiero tema claro u oscuro, para trabajar con la interfaz que me resulte más cómoda.
+
+---
+
+## Operación SaaS (consola)
+
+- Como operador de plataforma, quiero ver y crear tenants, para dar de alta constructoras en PANELS.
+- Como operador de plataforma, quiero suspender o actualizar un tenant, para controlar vigencia y estado del servicio.
+- Como operador de plataforma, quiero enviar el acceso al administrador de un tenant por correo, para que la constructora entre sin intercambio informal de claves.
+- Como operador de plataforma, quiero configurar y probar el SMTP, para que los correos de acceso salgan de forma fiable.
+
+---
+
+## Empresas y obras
+
+- Como administrador, quiero registrar la empresa principal y subempresas (fiscales / patronales), para operar varias razones sociales en un mismo tenant.
+- Como usuario, quiero dar de alta una obra con datos de contrato, fechas, residente, SIROC y empresa dueña, para tener el expediente de proyecto en un solo lugar.
+- Como usuario, quiero pausar, concluir o cancelar una obra, para que el padrón y las asignaciones respeten solo obras activas cuando corresponde.
+- Como usuario, quiero adjuntar documentos de empresa y de obra, para conservar el expediente (contratos, altas, etc.) junto al registro.
+- Como usuario, quiero ver el detalle de una obra desde el escritorio (árbol / ficha), para consultar presupuesto y documentos sin salir del flujo.
+
+---
+
+## Padrón de personal
+
+- Como usuario de RH / obra, quiero dar de alta a una persona con datos México (CURP, RFC, NSS, puesto, riesgo, jornal o destajo), para tener un registro maestro único.
+- Como usuario, quiero editar los datos de una persona sin borrarla, para conservar historial; la baja es un estado, no un delete.
+- Como usuario, quiero validar CURP, RFC y NSS (formato y unicidad), para no duplicar gente ni cargar identificadores inválidos.
+- Como usuario, quiero importar personal desde Excel y bajar una plantilla, para altas masivas.
+- Como usuario, quiero asignar a una persona a una obra activa, reactivar una asignación previa o darla de baja conservando la fecha de fin, para saber quién está en qué frente.
+- Como usuario, quiero cargar el expediente (foto, INE, CURP, NSS/IMSS, RFC y opcionales) con vigencia cuando aplique, para saber qué falta y qué está vencido o desactualizado.
+- Como usuario, quiero ver el estado de pipeline de cada persona (expediente, IMSS, gafete) calculado por el sistema, para no editar a mano un semáforo que se desactualiza.
+- Como usuario, quiero filtrar el padrón (con/sin IMSS, incompletos, listos para gafete, sin asignar, frescura de docs), para priorizar trámites.
+- Como usuario, quiero ver la ficha de una persona (datos, documentos, asignaciones, préstamos) en un panel lateral, para operar sin perder el listado.
+- Como usuario, quiero un tablero tipo kanban del pipeline de personal, para ver de un vistazo quién está atorado y en qué etapa.
+
+---
+
+## Gafetes
+
+- Como usuario, quiero generar trabajos de impresión de gafetes por obra, para sacar identificaciones del personal que ya está listo.
+- Como usuario, quiero un PDF de gafetes con foto, datos, color de riesgo y QR/vCard, para cumplir el control de acceso en campo.
+- Como usuario, quiero marcar o consultar quién ya se imprimió en un job, para no reimprimir a ciegas.
+
+---
+
+## Presupuesto
+
+- Como usuario de costos, quiero cargar el presupuesto de una obra por capítulos y partidas (alta manual o Excel), para tener la base contractual en el sistema.
+- Como usuario, quiero previsualizar un Excel antes de importar, para corregir errores sin romper el presupuesto.
+- Como usuario, quiero exportar el presupuesto, para compartirlo o archivarlo.
+- Como usuario, quiero editar o eliminar capítulos y partidas, para ajustar el alcance mientras la obra vive.
+
+---
+
+## Programa de obra
+
+- Como usuario, quiero armar el programa de una obra (fechas, semanas, importación o asistente), para calendarizar erogaciones y avance.
+- Como usuario, quiero distribuir montos por concepto y por partida en cada periodo, para ver qué se gasta o ejecuta cada semana.
+- Como usuario, quiero registrar avance por periodo, para comparar lo programado contra lo real.
+- Como usuario, quiero contrastar el programa contra el control de costos, para detectar desvíos de calendario vs dinero.
+- Como usuario, quiero exportar el programa a Excel, para llevarlo a junta o a campo.
+
+---
+
+## Gastos y control de costos
+
+- Como usuario, quiero capturar gastos de obra (con adjuntos) y consultarlos, para registrar lo erogado día a día.
+- Como usuario, quiero ver un resumen de IVA por periodo, para apoyar la contabilidad.
+- Como administrador, quiero configurar umbrales de alerta presupuestal, para que el tablero avise cuando un rubro se desvía.
+- Como usuario, quiero ver control de costos por obra (resumen, partidas, capítulos y desviaciones vs presupuesto), para saber si la obra se come el contrato.
+- Como usuario, quiero que la nómina alimente el control de costos, para no capturar dos veces la mano de obra.
+
+---
+
+## Almacén
+
+- Como usuario, quiero un almacén central y almacenes por obra, para separar existencias de patio vs frente.
+- Como usuario, quiero catálogo de materiales y ligarlos al presupuesto, para que las salidas impacten el control de obra.
+- Como usuario, quiero entradas, salidas y transferencias, para mover material con historial.
+- Como usuario, quiero consultar stock global y por almacén, para saber qué hay y dónde.
+- Como usuario, quiero abrir o cerrar el almacén de una obra, para congelar movimientos cuando el frente termina.
+
+---
+
+## Nómina
+
+- Como usuario de nómina, quiero registrar asistencia por semana, para pagar jornales con base en asistencia.
+- Como usuario, quiero armar y pagar la semana (jornal, destajo, líneas administrativas), para cerrar la nómina del periodo.
+- Como usuario, quiero gestionar destajo (unidades, trabajos, cortes), para pagar por avance y no solo por día.
+- Como usuario, quiero otorgar préstamos y registrar abonos, con recibo PDF, para descontar en nómina con soporte.
+- Como usuario, quiero exportar la nómina a CSV, para banco o contabilidad.
+- Como usuario, quiero consultar periodos de nómina históricos, para auditorías y aclaraciones.
+
+---
+
+## Usuarios y permisos (dentro del tenant)
+
+- Como administrador del tenant, quiero dar de alta usuarios operativos, para que RH, costos o almacén entren sin compartir mi cuenta.
+- Como administrador, quiero ver el catálogo de permisos y ajustar lo que puede un rol operativo, para no dar de más (el administrador del tenant no se recorta a sí mismo).
+- Como usuario, quiero que el sistema respete lo que puedo ver o capturar (gastos, almacén, padrón, etc.), para no operar módulos que no me tocan.
+
+---
+
+## Configuración del tenant
+
+- Como administrador, quiero configurar datos del tenant (zona horaria y parámetros de operación), para que fechas y reglas coincidan con cómo trabaja la constructora.
+
+---
+
+## Criterios transversales (aceptación general)
+
+- Los datos de una constructora no se mezclan con los de otra.
+- Una persona del padrón no se elimina: queda en baja con historial.
+- El semáforo de expediente / gafete / IMSS lo calcula el sistema; no se edita a mano salvo la baja.
+- Los documentos de expediente se guardan cifrados; el usuario los sube y descarga, no ve archivos en claro en disco.
+- Solo se asigna o importa personal a obras activas.
+- CURP, RFC y NSS no se duplican.
+- Mensajes de error y de éxito son específicos y en español.
+- El escritorio de obra y la consola SaaS son productos distintos: misma cuenta de API, pantallas y roles separados.