small-business-payroll-prep

Preparación de Nómina para Pequeñas Empresas

Detecta los errores y omisiones antes del día de pago.

Esta habilidad convierte las reglas de pago del propietario y sus exportaciones de POS, control de tiempo, reservas y RRHH en una nómina verificada: un libro de revisión, un rastro de evidencia y archivos de carga para su sistema de nómina. Nunca envía la nómina. Una persona la revisa y envía.

Todo se ejecuta a través de una herramienta de línea de comandos en la carpeta de esta habilidad:

python3 scripts/payroll.py --help          # necesita Python 3.10+ y openpyxl (pip install openpyxl)

Ejecútela con la ruta absoluta de la carpeta de la habilidad cuando trabaje en otro lugar, por ejemplo python3 <ruta-habilidad>/scripts/payroll.py run <carpeta-periodo>.

Reglas básicas (léalas primero)

1. Solo payroll.py run decide TODO CLARO. Salida 0 más output/evidence.json con "status": "ALL CLEAR" es el único TODO CLARO. Nunca describa una ejecución como limpia, terminada o lista basándose en su propia lectura de números. Salida 2 es NO CLARO, salida 1 está BLOQUEADO.
2. Nunca invente una tarifa, umbral, ventana o nombre de tipo de pago. Si el propietario no se lo ha dicho, déjelo en blanco para que la ejecución se detenga y pregunte. Un número adivinado se convierte en un cheque de pago.
3. Las reglas firmadas del propietario son la ley de la ejecución. Los cambios de reglas van a payroll_config.json, luego el Libro de Reglas de Pago se vuelve a renderizar y a aprobar. Nunca edite manualmente un número en un libro o archivo de exportación; corrija la entrada o la regla y vuelva a ejecutar.
4. Una advertencia necesita una decisión. Cada ADVERTENCIA bloquea TODO CLARO hasta que la entrada se corrija o alguien registre un acuse de recibo en period.json (acknowledged_warnings, con quién decidió y por qué). No acuse en nombre del propietario; pregúntele.
5. No es asesoramiento legal o fiscal. Los preajustes estatales son puntos de partida. Dígale al propietario que confirme las reglas de horas extra, salario mínimo, pago por enfermedad, propinas y pago final con su proveedor de nómina o asesor laboral.
6. Mantenga los datos confidenciales fuera. El motor solo necesita nombres, IDs, tarifas y horas. Nunca solicite ni almacene números de Seguro Social, datos bancarios o fechas de nacimiento. Si una exportación los contiene, no copie esas columnas a ningún lado.

El espacio de trabajo

<espacio-trabajo>/
  payroll_config.json          reglas del propietario (de la admisión)
  PAY_RULES_BOOK.md / .html    las reglas en lenguaje sencillo, con la aprobación del propietario
  connectors/                  copias editadas opcionales de perfiles de HRIS/nómina
  history/weeks.json           horas y horas extra ya pagadas, por semana laboral (escrito por las ejecuciones)
  periods/<inicio>_<fin>/
    period.json                fechas, ventana mensual, ventanas, certificaciones, fuentes, acuses
    raw/                       exportaciones exactamente como se descargaron
    inputs/                    CSVs canónicos que lee el motor
    output/                    libro de revisión, archivos de carga, resumen de ejecución, evidence.json

Pruebe primero un ejemplo ficticio si el propietario quiere verlo funcionar: payroll.py sample ./demo (un spa) o payroll.py sample ./demo --kind retail (una cadena de tiendas), luego approve ./demo --by "<nombre>", hris-import y run para cada periodo en demo/periods/ (consulte references/getting-started.md). Elija el más cercano al negocio del propietario.

Lo que el propietario quiere decide el modo

1. Configuración (admisión)

El propietario aún no tiene payroll_config.json, o quiere cambiar cómo se paga a las personas.

1. Pregunte en qué industria están y cómo se paga a las personas (start.1 y start.2 en references/questionnaire.md). Infórmeles con anticipación sobre cualquier cosa que su industria necesite y que esta herramienta no haga (la columna "Aún no manejado" allí).
2. Pregunte cómo quieren responder el resto: una entrevista con usted, o el libro de admisión para completar de su industria (payroll.py intake-workbook intake.xlsx --industry <id>, luego compile-intake intake.xlsx payroll_config.json).
3. Para la entrevista, siga references/questionnaire.md: una pregunta a la vez, solo las secciones principales que coincidan con cómo pagan a las personas y los paquetes para su industria, leyendo cada sección como reglas antes de escribir nada.
4. Escriba la configuración siguiendo references/config-reference.md. Comience con payroll.py init <workspace>. Cargue los preajustes estatales desde assets/states/ y haga que el propietario los confirme (references/state-rules.md).
5. payroll.py validate <workspace> hasta que diga VÁLIDO.
6. payroll.py rulebook <workspace>, guíe al propietario a través de cada ID de regla, corrija, vuelva a renderizar.
7. Cuando el propietario esté de acuerdo, payroll.py approve <workspace> --by "<nombre del propietario>".

2. Iniciar un período de pago

payroll.py new-period <workspace> --start YYYY-MM-DD --end YYYY-MM-DD --pay-date YYYY-MM-DD (agregue --monthly en la ejecución que paga incentivos mensuales; la ventana predeterminada es el mes calendario de la fecha de fin, o establezca --month-start y --month-end). Ejecute los períodos en orden de fecha: una semana laboral que abarca dos períodos necesita las horas del período anterior. Para el primer período, consulte "history" en references/config-reference.md. Imprime las semanas laborales que toca el período, las advertencias de semana límite y la lista de verificación de exportación de systems.pos_reports. Entregue esa lista al propietario.

3. Convertir exportaciones en entradas

• Plantilla de RRHH, tarifas de pago y tiempo libre: payroll.py hris-import <period> --roster <file> --time-off <file> usando el perfil en systems.hris (references/hris-connectors.md). Lea output/hris_import_report.md; corrija los FALLOS con --map field=Header o editando una copia del perfil en <workspace>/connectors/.
• Informes de POS: asigne cada uno a los CSVs canónicos (references/input-formats.md, references/pos-mapping.md). Asigne por texto de encabezado, nunca por posición de columna. Registre cada informe en las sources de period.json con sus propios totales impresos, para que la ejecución pueda demostrar que no se perdió ni duplicó nada.
• Si una entrada genuinamente no tiene nada este período (nadie tomó tiempo libre en una ubicación), registre una certificación en period.json en lugar de un archivo vacío.

Luego payroll.py check <period>: LISTO PARA EJECUTAR, o los FALLOS exactos a corregir.

4. Ejecutar

payroll.py run <period>. Ejecuta las compuertas, calcula, reconcilia cada total de entrada con lo pagado, recalcula todo de forma independiente (auditoría), compara con el último período, escribe los archivos de nómina e imprime TODO CLARO, NO CLARO o BLOQUEADO.

• BLOQUEADO: no se calculó nada. Corrija las líneas de FALLO (generalmente un problema de entrada) y vuelva a ejecutar.
• NO CLARO: lea las razones. Corrija entradas o reglas; para una advertencia que el propietario acepte, agregue su acuse a period.json. Vuelva a ejecutar. Los archivos de carga de una ejecución NO CLARA se nombran DO_NOT_UPLOAD_...; cada ejecución limpia primero las salidas de la ejecución anterior.
• TODO CLARO: envíe al propietario output/payroll_review_<date>.xlsx, run_summary.html y los archivos de carga. Señale cualquier cosa en Hallazgos y Notas de Incentivos que deba saber. El propietario revisa y carga; usted no.

Para ejecuciones de alto riesgo (primera ejecución en vivo, una nueva ubicación, un cambio de reglas), haga que un agente separado revise las salidas con references/auditor.md antes de entregarlas.

5. Cambiar una regla

Edite payroll_config.json, validate, vuelva a renderizar el libro de reglas, obtenga la aprobación del propietario nuevamente (approve), luego vuelva a ejecutar el período. La huella digital en el libro de reglas cambia con cada cambio de regla, por lo que las aprobaciones obsoletas se detectan automáticamente.

Dónde buscar

Necesidad	Archivo
Preguntas de entrevista por industria, por qué importan y brechas conocidas	references/questionnaire.md
Cada campo de configuración	references/config-reference.md
Las entradas CSV canónicas	references/input-formats.md
Asignación de informes POS (y trampas conocidas de informes)	references/pos-mapping.md
Puertas de entrada a sistemas de RRHH y nómina	references/hris-connectors.md
Preajustes estatales y qué confirmar	references/state-rules.md
Por qué existe cada compuerta y verificación	references/lessons.md
Resumen de revisión independiente	references/auditor.md
Tutorial para primera vez con los ejemplos de spa y retail	references/getting-started.md