================================================================================
  Holerite TEMPORÁRIO para testar no app (RegistroPro — Meus holerites)
================================================================================

O app NÃO lista PDFs só porque existem no disco. É obrigatório ter uma LINHA
na tabela MySQL employee_holerites apontando para o arquivo certo.

--------------------------------------------------------------------------------
ONDE O PDF FICA ARMAZENADO (servidor)
--------------------------------------------------------------------------------

Pasta base (relativa ao projeto ponto-saas):

  desktop\storage\holerites\{tenant_id}\{employee_id}\{nome_do_arquivo}.pdf

Exemplos:
  desktop\storage\holerites\1\2\a1b2c3d4e5f6....pdf   (nome aleatório pelo script)
  desktop\storage\holerites\1\2\holerite_demo_seeded.pdf (se usar SQL manual)

{tenant_id}  = coluna id da tabela tenants (não é o slug).
{employee_id} = coluna id da tabela employees — deve ser o MESMO ID do colaborador
                que aparece no app (ex.: dica "seu ID neste app: 2").

O upload feito pelo RH pela tela/API também grava nesta mesma estrutura.

--------------------------------------------------------------------------------
FORMA MAIS RÁPIDA — script PHP (recomendado)
--------------------------------------------------------------------------------

1) Abra o Prompt/PowerShell na pasta do backend:

     cd c:\xampp\htdocs\projetos\apps\ponto-saas\desktop

2) Rode (troque 2 pelo employee_id do seu login no app):

     c:\xampp\php\php.exe tools\seed_demo_holerite.php 2

   Opcional — forçar um tenant pelo slug:

     c:\xampp\php\php.exe tools\seed_demo_holerite.php 2 nome-do-tenant-slug

3) O script:
   - copia o PDF de demonstração (de desktop\public\samples\holerite_demo.pdf
     ou desta pasta: fixtures\holerite_demo.pdf);
   - cria a pasta storage se precisar;
   - insere o registro em employee_holerites.

4) No app: abra "Meus holerites" logado com esse colaborador.

Pré-requisitos:
   - Tabela employee_holerites criada (arquivo desktop\database\06_employee_holerites.sql).
   - Colaborador com esse id deve existir no banco.

Se faltar o PDF demo, na pasta desktop rode:

     c:\xampp\php\php.exe tools\generate_demo_holerite_pdf.php

--------------------------------------------------------------------------------
FORMA MANUAL — SQL + cópia do arquivo
--------------------------------------------------------------------------------

1) Ajuste tenant_id e employee_id no arquivo:

     desktop\database\07_seed_holerite_demo_manual.sql

   (use as queries de ajuda no final do .sql para descobrir os IDs.)

2) Execute o script no phpMyAdmin (banco do projeto).

3) Copie o arquivo manualmente:

   DE:   desktop\public\samples\holerite_demo.pdf
   PARA: desktop\storage\holerites\{tenant_id}\{employee_id}\holerite_demo_seeded.pdf

   Crie as pastas {tenant_id} e {employee_id} se não existirem.
   O nome holerite_demo_seeded.pdf deve bater com stored_filename no INSERT.

--------------------------------------------------------------------------------
FORMA pelo RH (ambiente real)
--------------------------------------------------------------------------------

Tela de upload (exemplo no projeto): desktop\public\rh_holerite_upload.html
API: manager/holerites_upload.php (login de usuário gestor/RH, não colaborador).

O employee_id informado no upload deve ser o mesmo do cadastro do colaborador
no app.

--------------------------------------------------------------------------------
Conferência rápida
--------------------------------------------------------------------------------

No MySQL:

  SELECT id, tenant_id, employee_id, title, stored_filename
  FROM employee_holerites
  ORDER BY id DESC
  LIMIT 10;

No disco, confira se existe:

  desktop\storage\holerites\<tenant_id>\<employee_id>\<stored_filename>

--------------------------------------------------------------------------------
"Tenho holerite_demo.pdf mas não abre / não exibe no app"
--------------------------------------------------------------------------------

No banco existem DOIS nomes diferentes:

  • original_filename  → só o nome bonito na lista (ex.: holerite_demo.pdf)
  • stored_filename    → nome REAL do ficheiro na pasta (ex.: a1b2c3d4....pdf)

O servidor SÓ abre o ficheiro cujo nome é stored_filename.

Se você copiou manualmente "holerite_demo.pdf" mas no INSERT o stored_filename
for outro hash, dá erro "Arquivo não encontrado no servidor".

Corrija UMA das opções:

  A) Renomeie o PDF no disco para bater com stored_filename, OU
  B) UPDATE employee_holerites SET stored_filename = 'holerite_demo.pdf' WHERE id = ?;
     (e garanta que o ficheiro holerite_demo.pdf está na pasta certa)

Na pasta desktop (CLI):

  php tools/check_holerite_file.php <id_do_registro>

Mostra o caminho exato esperado e se o ficheiro existe.

================================================================================
