panels-origin/docs/plan-pendientes-arctec.md

# Pendientes arctec-ar: análisis y plan de implementación

Fuente: observaciones de *Pendientes página* (facturas, nómina, IMSS/SUA).
Alcance de este documento: contrastar cada punto con el sistema actual y definir el orden de construcción. No implementa las pantallas ni las migraciones.

## Resumen

El sistema ya cubre captura manual de gastos, catálogo de proveedores, nómina semanal (jornal, destajo y administrativa), préstamos con descuento al pagar la semana, y datos básicos de IMSS en el padrón. No existe un módulo de facturas CFDI, ni descuentos varios estructurados, ni finiquitos, ni dispersión, ni historial de movimientos de personal, ni reportes de nómina por mes o año, ni jornal distinto para el IMSS.

La administración de proveedores **ya existe** y debe reutilizarse. No conviene un segundo catálogo. Las facturas y los gastos deben resolver el proveedor por `supplier_id` y por RFC.

## Qué hay hoy

| Área | Dónde vive | Qué hace |
| --- | --- | --- |
| Proveedores | `core.suppliers`, `fn_supplier_list/create/update`, `GET/POST/PATCH /v1/suppliers`, pestaña Proveedores en Configuración, `SupplierFormDialog` | Alta y edición de nombre, razón social, RFC único por tenant, contacto y domicilio. Estatus `activo` / `inactivo` en base, sin baja en la pantalla. |
| Uso del proveedor | Gastos (`expense_entries.supplier_id`) y materiales de almacén (`warehouse_material_suppliers`) | En Gastos se elige del catálogo. El RFC se copia al gasto. |
| Gastos | `expense_entries`, página Gastos | Captura uno a uno: empresa, obra, fecha, concepto de presupuesto, importes, IVA y PDF. Filtro de texto (descripción, proveedor, concepto) y “sin clasificar”. El listado de API filtra obra, empresa, fechas, concepto y origen. |
| Nómina | `payroll_weeks` (`draft` / `assembled` / `paid`), hojas `obra`, `destajo`, `admin` | Asistencia por día (presente o falta). Jornal = días × `workers.daily_wage`. Se arma desde el jueves. Al pagar se descuenta el préstamo y se sincroniza el gasto. Exportación: CSV de la semana. PDF solo de recibos de préstamo. |
| Préstamos | `loans`, `loan_payments`, ficha del trabajador | Alta, saldo en ficha y recuperación en el tablero. No hay edición del préstamo ya registrado. |
| Personal | `workers.status`, `imss_alta_at`, `imss_baja_at`, `last_rehire_at`, `assignments.start_date/end_date` | Una fecha de reingreso y una alta/baja IMSS. No hay bitácora de varios movimientos. |
| IMSS | Empresa: registro patronal y clase de riesgo. Persona: NSS, salario diario único, estatus y fechas de alta/baja, documentos `alta_imss` / `baja_imss` | No hay jornal IMSS separado, ni desglose de cuotas, ni archivo SUA. |

## Análisis por observación

### 1. Facturas y comprobantes

**Carga masiva de Excel (recibidas o emitidas) y concepto de material a la obra.**
No existe. Gastos se capturan de uno en uno y solo modelan egresos. Una factura emitida (ingreso) no cabe en `expense_entries` sin un tipo de movimiento. El concepto de presupuesto ya se puede ligar a un gasto manual (`budget_item_id`), pero no desde un Excel ni por línea de material.

**Filtros en facturas recibidas (proveedor, monto, RFC, UUID).**
No hay UUID, folio fiscal ni serie. La búsqueda de Gastos es un texto libre en el cliente. El API de gastos no filtra por proveedor, RFC ni rango de monto.

Decisión: las facturas son un registro propio, ligado al proveedor del catálogo. Una factura recibida clasificada puede generar o actualizar un gasto. Una emitida queda como ingreso y no entra al control de costos.

### 2. Nómina

**Bono.**
No hay concepto de percepción aparte del jornal, el destajo o el sueldo administrativo. `payroll_week_lines` tiene `gross`, `discounts` y `loan_discount`, sin tipo de percepción.

**Descuentos varios con observación.**
La columna `discounts` es un importe. El periodo legado acepta `extra_discounts` como número por trabajador, sin concepto, fecha, obra ni motivo. La pantalla de nómina no captura ese dato.

**Ajuste por horas trabajadas.**
La asistencia es sí/no por día (`attendance.present`). `days` es la cuenta de días presentes. No hay horas ni fracción de jornal por hora.

**Días festivos.**
No hay calendario ni regla (pagar el día, no descontarlo, o pagarlo doble). Un festivo hoy se trata como falta si no se marca presente.

**Consulta y descarga Excel y PDF.**
Hay CSV de la semana abierta (`fn_payroll_week_csv`). No hay libro Excel ni PDF de la nómina. El generador PDF actual solo arma recibos de préstamo (`api/pdf.ts`).

### Descuentos varios (sección propia)

No existe tabla ni pantalla. Cada descuento del pendiente pide concepto, importe, fecha, trabajador, obra y observación. Eso es un movimiento, no un campo suelto en la línea semanal. Al armar la semana, los descuentos vigentes de esa obra y persona se suman a `discounts`.

### Préstamos

Alta y lectura sí. `fn_loan_create` fija entregado, saldo, cuota, comisión y plan. No hay `fn_loan_update`. El saldo se ve en la ficha y el descuento de la semana en la línea (`loan_label`, `loan_discount`). No hay un estado de cuenta: saldo inicial, descuentos aplicados y saldo pendiente en un solo lugar. Editar un préstamo con pagos ya aplicados debe quedar restringido (solo nota, cuota futura o corrección si la semana sigue en borrador).

### Finiquitos y liquidaciones

No hay módulo. La baja de padrón cambia `status` / `pipeline_status` y no calcula proporcional, vacaciones, aguinaldo, prima ni finiquito. Hace falta un cálculo consultable (conceptos e importe final) y un pago que no se mezcle con el jornal semanal.

### Dispersión

No hay entidad de dispersión. Lo más cercano es el estado de la semana: borrador, armada y pagada. Después de pagada no se edita, y no se anexa el comprobante de la transferencia. El “corte semanal” hoy es la propia semana de nómina (se arma el jueves). Falta un corte explícito: congelar el neto a dispersar, permitir corrección mientras no sea definitivo, y adjuntar el comprobante al cerrarlo.

### Historial de movimientos del trabajador

Se guarda el estado actual y, como mucho, una fecha: `imss_alta_at`, `imss_baja_at`, `last_rehire_at`, inicio y fin de asignación. Un segundo reingreso pisa `last_rehire_at`. No se puede listar alta, baja y reingresos sucesivos.

### Reportes de nómina

No hay reporte mensual ni anual, ni filtro combinado por trabajador, obra y periodo, ni exportación Excel/PDF de ese corte. El CSV semanal no sustituye esos reportes.

### 3. IMSS / SUA

`workers.daily_wage` es el único jornal. No se distingue el jornal real del jornal diario para IMSS (salario base de cotización diario). La empresa tiene registro patronal y clase de riesgo; la persona tiene NSS y movimiento de alta/baja como fechas sueltas. No se calculan ni se consultan cuotas (enfermedad, invalidez, retiro, cesantía, infonavit, riesgo de trabajo) ni se arma el layout del SUA. El pendiente pide facilitar la revisión, no sustituir al SUA: guardar el jornal IMSS, los movimientos y el desglose usado en el cálculo, y poder exportarlo para cotejo.

## Proveedores: reutilizar el catálogo

La opción de administrar proveedores ya está hecha y es la base de facturas y almacén.

Se mantiene:

- Un solo catálogo por tenant (`core.suppliers`).
- RFC único cuando viene informado.
- Alta desde Configuración y, como atajo, desde Gastos y desde el catálogo de materiales.
- El gasto y la factura guardan `supplier_id` y una copia de nombre y RFC por si el catálogo cambia después.

Se completa, sin abrir otro módulo:

- Activar e inactivar desde la pestaña Proveedores (el campo `status` ya existe; la tabla no lo muestra ni lo edita).
- Búsqueda en servidor por nombre y RFC, alineada al filtro de facturas.
- Al importar Excel de facturas, emparejar por RFC. Si el RFC no existe, la fila queda en revisión para crear el proveedor o asignarlo; no se duplica el catálogo en silencio.
- Datos que el catálogo aún no tiene y la factura sí va a necesitar: régimen fiscal y código postal fiscal, opcionales, para cotejar el CFDI. Cuenta bancaria no entra en esta fase; la dispersión es de nómina, no de proveedores.

## Plan de implementación

Cada fase cierra con migración Liquibase en `db/core/changesets/`, funciones `core.fn_*`, rutas en la API y pantalla en `web-panel`. Los permisos siguen el patrón `modulo.view/create/update/delete`.

### Fase 1. Proveedores listos para facturas

Objetivo: el catálogo que ya existe queda usable como maestro de las facturas.

- Mostrar estatus y permitir pasarlo a `inactivo` (no se borra si tiene gastos o facturas).
- Campos opcionales `regimen_fiscal` y `codigo_postal`.
- Listado filtrable por nombre, RFC y estatus.
- Prueba de API: alta, RFC duplicado, inactivar, y que Gastos solo ofrezca activos.

No cambia el flujo de captura de un gasto.

### Fase 2. Facturas recibidas y emitidas

Objetivo: registrar comprobantes en lote y clasificar la recibida a la obra.

Tablas nuevas:

- `invoices`: tenant, dirección `recibida` | `emitida`, `supplier_id`, nombre y RFC copiados, UUID, serie, folio, fecha, subtotal, IVA, total, moneda, estatus `borrador` | `registrada` | `clasificada` | `anulada`.
- `invoice_lines`: factura, descripción, cantidad, unidad, importe, `project_id`, `budget_item_id`.
- UUID único por tenant cuando viene informado.

Excel de carga (una fila por partida, se agrupa por UUID o, si no hay UUID, por RFC + folio + fecha):

- Dirección, RFC, nombre proveedor, UUID, serie, folio, fecha, descripción, cantidad, unidad, importe, IVA, total, clave de obra, clave de concepto.

Reglas:

- RFC conocido asigna `supplier_id`. RFC nuevo no crea proveedor hasta que alguien lo confirme en la revisión.
- Concepto y obra vacíos dejan la factura recibida como `registrada` (equivalente al gasto sin clasificar). Al asignar concepto se puede generar el gasto con `source = 'invoice'` y `source_ref_id` = id de factura, reusando la unicidad que ya tiene `expense_entries`.
- La emitida no genera gasto.
- Filtros del listado de recibidas: proveedor (id o nombre), RFC, UUID, folio, rango de monto, rango de fechas, obra, con o sin concepto.
- Edición de concepto y obra mientras la factura no esté anulada. Si ya generó gasto confirmado, la reclasificación pasa por la misma regla que `fn_expense_update`.

Pantalla: apartado Facturas, pestañas Recibidas y Emitidas, acción Importar Excel y diálogo de clasificación. Gastos sigue siendo la captura manual y el reflejo de nómina; no se le pide que sea el CFDI.

### Fase 3. Conceptos de nómina de la semana

Objetivo: bono, descuento con motivo, horas y festivo dentro del cálculo semanal que ya arma y paga.

- Percepciones de la línea: jornal, bono (importe y nota). El bruto pasa a ser jornal + bono + destajo o sueldo admin, según la hoja.
- `payroll_adjustments`: tipo `descuento` | `bono` | `horas`, trabajador, obra opcional, semana o fecha, concepto, importe o horas, observación. Un descuento sin observación no se guarda.
- Horas: además del día presente/ausente, un ajuste de horas × (jornal / jornada, por defecto 8). Puede sumar o restar del jornal de esa semana. No reemplaza la asistencia por día.
- `holidays`: fecha, nombre, tenant. Si el día cae en la semana y la persona está asignada, cuenta como día pagado aunque no haya marca de asistencia, y se identifica en la línea. No se paga doble en esta fase; si más adelante se pide festivo trabajado, será otro tipo de ajuste.
- El armado de la semana (`fn_payroll_week_assemble`) suma estos conceptos antes de congelar `payable_net`. En semana `paid` no se editan.
- Pantalla Nómina: captura de bono y de descuento (concepto, importe, obra, observación) sobre la persona de la semana, y marcas de festivo en el calendario de la semana.

La sección “Descuentos varios” del pendiente es esta misma captura, también consultable fuera de la semana: listado por trabajador, obra y fechas. No es un módulo aparte del cálculo.

### Fase 4. Préstamos editables y estado de cuenta

- `fn_loan_update` mientras no haya `loan_payments`, o solo nota y cuota si ya hay pagos. El saldo no se teclea: se recalcula como entregado − suma de pagos.
- Ficha y diálogo de préstamo: entregado, comisión, cuota, saldo pendiente y tabla de descuentos aplicados (semana, importe, etiqueta).
- Corregir un préstamo no reabre una semana ya pagada.

### Fase 5. Finiquitos y liquidaciones

- `settlements`: trabajador, tipo `finiquito` | `liquidacion`, fecha de baja, obra, estatus `borrador` | `pagado`.
- `settlement_lines`: concepto (sueldo pendiente, vacaciones, prima vacacional, aguinaldo, otro), días o base, importe, observación.
- El importe final es la suma de líneas menos descuentos y saldo de préstamo vigentes, mostrados en el detalle antes de pagar.
- Pagar el finiquito no lo mete en la semana de jornal. Puede generar un gasto de nómina distinto, con referencia al finiquito, para que el control de costos lo vea.

Los factores (días de aguinaldo, porcentaje de prima) salen de configuración del tenant, con valores editables. El primer corte usa los días capturados en cada línea para no bloquear el módulo por una tabla fiscal incompleta.

### Fase 6. Dispersión y corte semanal

- `payroll_dispersions`: semana, estatus `abierta` | `corte` | `definitiva`, neto, nota.
- Mientras está `abierta` o en `corte`, se puede corregir el neto por persona (ajuste que también queda en la línea de la semana si la semana no está pagada).
- `definitiva` bloquea la edición y exige, o al menos permite, el comprobante (mismo almacenamiento cifrado que los PDF de gastos).
- El corte semanal es la acción que pasa la dispersión a `corte` con el `payable_net` de esa semana. No crea otra periodicidad: la semana de nómina sigue siendo el periodo.

### Fase 7. Historial de movimientos

- `worker_movements`: trabajador, tipo `alta` | `baja` | `reingreso`, fecha, motivo, usuario.
- Alta de persona, baja de padrón y reactivación escriben un renglón. Las fechas actuales (`last_rehire_at`, alta y baja IMSS) se siguen actualizando para no romper el expediente.
- La ficha muestra la lista en orden de fecha. No se edita el pasado desde la ficha; una corrección es otro movimiento o una nota.

### Fase 8. Reportes de nómina

- Consulta por periodo (semana, mes o año), trabajador y obra, leyendo líneas de semanas, ajustes, préstamos y finiquitos pagados en el rango.
- Exportación Excel (libro con el mismo detalle que la pantalla) y PDF (resumen por persona y totales). El CSV semanal se conserva.
- Mes y año agrupan por `week_start` / fecha del movimiento, en la zona horaria del tenant.

### Fase 9. Jornal IMSS y apoyo a SUA

- `workers.imss_daily_wage`: jornal diario para cotización. Si está vacío, el cálculo usa `daily_wage` y lo indica en pantalla.
- Movimientos IMSS que alimentan el historial de la fase 7 con tipo `alta_imss`, `baja_imss`, `modificacion_salario`, más registro patronal de la empresa.
- Consulta por persona y periodo: jornal real, jornal IMSS, días, salario base de cotización del periodo y cuotas calculadas con las tasas vigentes guardadas en configuración (no hardcodeadas en la pantalla).
- Exportación de esa consulta a Excel para cotejar contra el SUA. No se genera el archivo propietario del SUA en esta fase: faltan tablas de ausentismo, incapacidades y el layout oficial completo. Eso queda como fase posterior si el cotejo en Excel no basta.

## Orden y dependencias

1. Proveedores (fase 1) antes que facturas, porque el Excel casa por RFC.
2. Facturas (fase 2) no bloquea nómina. Puede ir en paralelo con la fase 3 después de la 1.
3. Ajustes de nómina (fase 3) antes que reportes (fase 8) y antes que dispersión (fase 6), para que el neto a dispersar ya incluya bono, horas, festivo y descuentos.
4. Préstamos (fase 4) antes que finiquitos (fase 5), porque el finiquito resta el saldo.
5. Historial (fase 7) puede avanzar en paralelo con nómina; la fase 9 lo reutiliza para movimientos IMSS.
6. IMSS/SUA (fase 9) al final: depende del jornal y de los movimientos, y no cambia el pago semanal.

## Fuera de este plan

- Timbrado CFDI o descarga automática del SAT.
- Archivo de pago bancario (layout de dispersión del banco).
- Archivo SUA de carga directa.
- Sustituir la asistencia por día con un reloj checador.

## Verificación por fase

- Fase 1: crear, editar, RFC repetido, inactivar, y que un gasto nuevo no liste al inactivo.
- Fase 2: Excel con proveedor existente, RFC desconocido, UUID repetido, clasificación a concepto y gasto generado una sola vez.
- Fase 3: semana con bono, descuento con motivo, horas y un festivo; el neto armado cuadra con la suma; semana pagada rechaza cambios.
- Fase 4: editar préstamo sin pagos; con pagos, el saldo es entregado menos pagos.
- Fase 5: detalle de conceptos igual al importe a pagar.
- Fase 6: corrección antes de definitiva; comprobante adjunto; definitiva no editable.
- Fase 7: alta, baja y reingreso aparecen en orden y no se pierden al repetir el ciclo.
- Fase 8: el mes suma las semanas del mes; Excel y PDF coinciden con la pantalla.
- Fase 9: jornal IMSS distinto del real se ve en la consulta de cuotas y en el Excel.