Organização de Materiais de Reembolso Empresarial

Organiza um monte de materiais brutos de reembolso fornecidos pelo usuário em um conjunto de entregas com estrutura clara, nomenclatura padronizada e prontas para serem entregues ao financeiro: materiais arquivados em pastas + planilha de despesas preenchida + explicações adicionais para o financeiro + registro de processo rastreável.

Três Linhas Vermelhas Intransponíveis

Materiais originais e modelos originais nunca são modificados. Todas as alterações ocorrem em backups e cópias dos modelos.
Nunca invente informações. Itens ilegíveis, incompatíveis ou com elementos ausentes devem ser listados em uma lista de dúvidas para solicitar ao usuário. É melhor perguntar do que inventar.
Cada despesa é registrada em apenas uma linha na tabela, sem cobrança duplicada. A fatura e seu comprovante de pagamento são a mesma transação; antes e depois de uma reemissão são a mesma viagem; valores já pagos pela empresa não são reembolsados. Veja as seções 3.1–3.3 e a seção 6 de references/classificacao_normas_nomenclatura.md.

Use sempre python3 (muitos ambientes não têm o alias python); caminhos de script use relativos ao diretório desta skill: scripts/....

Entradas Necessárias Antes de Começar

Caminho da pasta de materiais brutos (podem ser jpg/png/pdf/ofd/excel/vários formatos misturados, pode conter subdiretórios).
Caminho do modelo de reembolso .xlsx.
Informações de identidade (nome, departamento, data de submissão, moeda, departamento padrão, código de projeto padrão, adiantamento em dinheiro).
- Verifique se process_files/identity.json já existe (salvo da execução anterior); se existir, leia e reutilize, e confirme com o usuário se deseja manter.
- Se não existir ou estiver incompleto, solicite ao usuário os campos faltantes e salve em process_files/identity.json para reutilização futura.

Os campos do modelo, significados das colunas e elementos obrigatórios do motivo estão em references/modelo_mapeamento_campos.md. Leia-o antes de começar.

Três Comportamentos Padrão Ajustáveis (o usuário pode alterar com uma frase)

Nível de autonomia (padrão: pergunte apenas se não tiver certeza). Itens com alta confiança são automaticamente classificados e arquivados; itens que não podem ser distinguidos (transporte intermunicipal vs. transporte urbano, valores ilegíveis, suspeita de despesa pessoal, motivo incompleto) são acumulados em uma lista de dúvidas e perguntados ao usuário de uma vez. O usuário pode solicitar totalmente automático ou confirmação item por item.
Informações de identidade (padrão: pergunte na primeira vez, salve e reutilize). Veja acima.
Moedas múltiplas (padrão: converta para RMB na tabela). Notas em moeda estrangeira (USD/KRW etc., como recibos de Uber no exterior) são convertidas usando a taxa de câmbio especificada pelo usuário. Se a taxa não for fornecida, não a invente — primeiro liste como dúvida para o usuário (ou use a cotação do Banco da China na data do documento e especifique a fonte); o valor original, moeda, taxa e resultado são escritos em explicacoes_adicionais/, e no registro de processo as colunas 'Valor/Moeda Original/Taxa' são preenchidas. Também pode ser alterado para preencher na moeda original, com a taxa de câmbio a cargo do usuário.

Fluxo de Trabalho

Passo 0: Montar Espaço de Trabalho + Backup (script)

python3 scripts/setup_workspace.py --source <pasta_de_materiais_brutos> [--out <diretório_raiz_workspace>] [--template <modelo_reembolso.xlsx>]

--out pode ser omitido: por padrão, cria um novo workspace com nome significativo <nome_da_pasta_original>_organizacao_reembolso_<YYYYMMDD> ao lado da pasta de materiais brutos (seu diretório pai = localização padrão); também pode usar --out para especificar um diretório desejado.
--template pode ser omitido: diferentes usuários podem ter modelos diferentes ou nenhum. Sem modelo, siga o ramo "sem modelo" (veja Passo 6) e use make_default_table.py para gerar uma planilha de despesas genérica. Ele criará: dez subpastas (com_fatura/sem_fatura/materiais_auxiliares/aguardando_verificacao/faturas_substitutas/explicacoes_adicionais/process_files/backup/materiais_complementares/irrelevantes), fará backup completo dos materiais brutos em backup/ (o modelo em si e arquivos *.skill não são considerados materiais e são ignorados automaticamente), quando houver modelo, salvará o original em backup/_modelo_original/ e gerará uma cópia editável <nome_original>_preenchido.xlsx, gerará process_files/manifest.json. O workspace é criado fora da pasta de materiais brutos. O stdout retorna os caminhos chave (workspace/writable_template, sem modelo writable_template é null). Todos os scripts são puramente python3, multiplataforma (mac/linux/windows), sem dependência de comandos específicos do sistema.

Passo 1: Ler e Entender Materiais Individualmente

Leia cada material na ordem do manifest.json, escolha o método de leitura conforme o tipo:

Imagens (jpg/png/webp etc.): Use visão diretamente (o modelo pode ler imagens), não precisa de OCR primeiro. Leia: data da despesa, comerciante/item, valor, se é fatura oficial, locais de partida/destino, número de pessoas, etc.
PDFs: Primeiro use extract-text ou skill de leitura de PDF para extrair texto; para scans/formatos com layout, se não conseguir extrair texto, converta para imagem e use visão (consulte método de rasterização da skill de leitura de PDF).
OFD (fatura eletrônica nacional):
```
python3 scripts/extract_ofd.py <arquivo.ofd> --json
```
Se não conseguir extrair texto (OFD apenas com camada gráfica), fallback: converter para imagem e usar reconhecimento visual.
- Passagem ferroviária eletrônica: leia o 'preço do bilhete' (valor a ser reembolsado para viagem normal) ou 'taxa de cancelamento/reembolso com diferença' (cancelamento, valor muito pequeno), preste atenção ao marcador 'reemissão de partida'.
- Fatura de IVA: O valor a ser inserido na tabela é o total com impostos (incluindo IVA), não o valor sem impostos (veja references/modelo_mapeamento_campos.md).
Excel/CSV: Use extract-text file.xlsx ou pandas para ler, comum em contas de telefone, extratos, resumos.
Outros formatos desconhecidos: Primeiro use file <caminho> para identificar o tipo, depois escolha a leitura adequada; se realmente não conseguir ler, adicione à lista de dúvidas.

Cada material deve ter os elementos extraídos escritos em process_files/extracted/<nome_original>.json.

Passo 2: Classificar em Pastas + Categorizar + Associar Eventos

Conforme references/classificacao_normas_nomenclatura.md:

Decida se entra em com_fatura / sem_fatura / materiais_auxiliares (critério na seção 1 do arquivo de referência). Importante: despesa real com apenas captura de tela, sem fatura oficial, vai para 'sem_fatura' (é a evidência principal), não para 'materiais_auxiliares' (seção 1.1); materiais auxiliares devem ter uma evidência principal ao lado. Uma vez que apareça um item sem fatura, lembre-se de notificar o cliente para colocar faturas substitutas em faturas_substitutas/ (veja 'Diretórios Especiais · faturas_substitutas/').
Decida a qual das 12 categorias de despesa pertence → coluna correspondente no modelo (mapeamento de colunas em references/modelo_mapeamento_campos.md). Observe a distinção entre J transporte intermunicipal vs Q transporte urbano.
Atribua o mesmo número de evento a múltiplos materiais da mesma despesa (fatura + comprovante de pagamento + itinerário + comprovante de reembolso devem ser vinculados ao mesmo evento). Antes e depois de reemissão, pagamento pela empresa/pagamento pessoal também vinculado ao mesmo evento (seções 3.1–3.3).
Suspeita de uso pessoal/não relacionado à viagem (assinaturas pessoais, vistos de países não relacionados, documentos de alto valor sem fatura, etc.) vá para a lista de dúvidas, por padrão não incluído (seção 5); após confirmação do usuário de que não é relevante/não será reembolsado/pertence a outro período, mova para irrelevantes/ (não incluído neste período).
Itens incertos não force: materiais cuja pasta/categoria/possibilidade de reembolso não pode ser determinada, coloque primeiro em aguardando_verificacao/, não coloque diretamente em com_fatura/ ou sem_fatura/; acumule em lista de dúvidas e pergunte ao usuário, e só então mova de aguardando_verificacao/ para a pasta correta.

Passo 3: Criar Registro de Processo (arquivo de processo)

Em process_files/registro_materiais.csv (UTF-8-SIG), uma linha por material original, estrutura de colunas conforme seção 4 de references/classificacao_normas_nomenclatura.md. O registro de processo é a única fonte de dados para preenchimento posterior e relatório de auditoria — primeiro acerte o registro.

Passo 4: Copiar + Renomear + Arquivar em Pastas

Seguindo a norma de nomenclatura data_tipo_despesa_info_chave_valor, copie materiais de backup/ para a pasta correspondente e renomeie. Mesmo evento em pastas diferentes com mesmo nome, mesma pasta com sufixo semântico (regras no arquivo de referência). Preencha o novo nome de arquivo de volta no registro.

Passo 5: Escrever Explicações Adicionais (conforme necessário)

Sempre que houver consolidação, reembolso parcial, conversão de moeda, divisão/rateio, ou valor do material ≠ valor na tabela, escreva um txt em explicacoes_adicionais/ conforme references/formato_explicacoes_adicionais.md, e aponte para ele na coluna 'Observações' do registro.

Passo 6: Registro → Conciliação de Duplicidade → Gerar Ledger → Preencher Cópia do Modelo (script)

Primeiro faça a conciliação de duplicidade (seção 6 de references/classificacao_normas_nomenclatura.md): Agrupe o registro por número de evento em "uma linha por evento" — faturas/evidências principais sem fatura geram valor, materiais auxiliares e comprovantes de reembolso não geram linhas separadas; cancelamento conta apenas a taxa de cancelamento; pagamento pela empresa conta apenas o valor pago pelo indivíduo; moeda estrangeira convertida para RMB. Anote Σ(valor do ledger) como base de conciliação.

Ordene cronologicamente: O cabeçalho do modelo exige "preencher em ordem cronológica". Os itens no ledger devem ser ordenados pela data de ocorrência da despesa em ordem crescente (múltiplos no mesmo dia podem ser ordenados como "primeiro faturas normais, depois cancelamentos/reembolsos com diferença"). Por padrão, fill_template.py também ordena por mês/dia de forma estável como fallback (se quiser manter sua ordem, use --no-sort).

Em seguida, organize em process_files/ledger.json (estrutura no topo de scripts/fill_template.py: identity + items, cada item com 'coluna' ou 'categoria' + valor + motivo + partida/destino/departamento/código de projeto). O motivo deve preencher os elementos exigidos para a anotação financeira conforme references/modelo_mapeamento_campos.md. Depois:

python3 scripts/fill_template.py --xlsx <modelo_editavel> --ledger process_files/ledger.json

fill_template.py lida automaticamente com inserção de linhas além de 31 e expansão de SUM, e no computed de saída já fornece os valores esperados de subtotais/totais de cada coluna — primeiro confira se coincidem com sua base de conciliação.

Depois recalcule as fórmulas (escolha uma):

# Opção 1: skill xlsx (requer LibreOffice)
python3 /mnt/skills/public/xlsx/scripts/recalc.py <modelo_editavel>
# Opção 2: Sem LibreOffice / caminho não disponível, use fallback nativo desta skill (--write grava valores, entrega mostra números diretamente):
python3 scripts/recalc_fallback.py <modelo_editavel> --write

É obrigatório confirmar que total_errors é 0, e que o resultado do recálculo é consistente com o computed do fill_template e com a soma do registro — todos os três devem coincidir.

Ramo sem modelo: Se o usuário não tiver modelo, pule fill_template.py/recalc e use o script para gerar uma planilha de despesas genérica (com valores e totais já escritos, e uma prévia em .md):

python3 scripts/make_default_table.py --ledger process_files/ledger.json --out <workspace>/<nome_significativo>.xlsx

Neste caso, ledger.json usa a estrutura "versão sem modelo" (veja topo de make_default_table.py: identity pode conter título/requerente/departamento etc., cada item com data/categoria/motivo/comerciante/moeda/valor original/taxa/valor (RMB)/observações). O total do xlsx gerado deve corresponder à soma do registro.

Passo 7: Relatório de Auditoria + Entrega

Escreva relatorio_auditoria.md na raiz do workspace:

Resumo por categoria de despesa: valor total reembolsável;
Conciliação: soma do registro = total do modelo = soma dos valores dos materiais em cada pasta (listar item por item, destacar inconsistências em vermelho);
Lista de dúvidas: itens que precisam de complemento do usuário (número de convidados, dias de viagem, taxa de câmbio, valores ilegíveis, suspeita de despesa pessoal, etc.);
Contagem de arquivos por pasta, lista de explicações adicionais. Coloque <modelo_editavel> primeiro (use ferramentas de apresentação como present_files se disponível, senão apenas forneça o caminho do workspace e a lista de arquivos), apresente junto com o relatório de auditoria ao usuário e esclareça a lista de dúvidas pessoalmente.

Diretórios Especiais (processados conforme necessário, todos não afetam o fluxo principal de conciliação)

Além do fluxo principal dos passos 0–7, existem quatro diretórios que podem ser ativados conforme necessário; cada um é independente e não afeta o registro e conciliação de com_fatura/sem_fatura/materiais_auxiliares.

aguardando_verificacao/ — Itens incertos, armazene aqui primeiro

Materiais cuja classificação (pasta, categoria, possibilidade de reembolso) não pode ser determinada, coloque primeiro em aguardando_verificacao/, nunca coloque diretamente em com_fatura/ ou sem_fatura/. Acumule em lista de dúvidas e pergunte ao usuário de uma vez; após a decisão do usuário, mova de aguardando_verificacao/ para a pasta correta e registre. Na entrega, aguardando_verificacao/ deve idealmente estar vazio; se ainda houver itens pendentes, mencione-os no relatório de auditoria.

irrelevantes/ — Não relacionado a esta viagem / não reembolsável neste período / de outro período

Materiais confirmados pelo usuário como não relacionados a este reembolso, não reembolsáveis neste período ou pertencentes ao próximo período (passagens de voos de outro período, vistos não relacionados a esta viagem, etc.), copie uma cópia de backup/ para irrelevantes/ para armazenamento separado, não inclua no registro e modelo deste período; no relatório de auditoria, liste como "movido para irrelevantes". Não contamina a conciliação nem perde materiais.

faturas_substitutas/ — Pool opcional de faturas substitutas (não viram com_fatura, não contam valor)

Alguns itens "sem_fatura" são despesas reais sem fatura oficial (aluguel de empresa, contas de água/luz, pagamentos pessoais esporádicos, etc.). O cliente pode opcionalmente fornecer faturas oficiais de outras despesas do dia a dia para colocar em faturas_substitutas/, de modo a aproximar o valor total desses itens sem fatura e anexar ao financeiro — ou não fornecer. O mais importante: faturas substitutas NÃO são faturas reais correspondentes um a um aos itens sem fatura, são apenas valores aproximados. Portanto:

Faturas substitutas nunca são movidas para com_fatura/, e itens sem fatura nunca são reclassificados como 'com_fatura' — itens sem fatura permanecem gerenciados como sem fatura (são o registro dessa despesa real).
Faturas substitutas ficam em faturas_substitutas/ anexadas separadamente ao financeiro, não entram nas linhas de despesa do registro, não contam para o valor do reembolso (caso contrário, duplicaria o valor com os itens sem fatura).
Apenas em process_files/pool_faturas_substitutas.csv registre a lista de faturas substitutas e o total do pool, fazendo uma comparação aproximada de cobertura com o total sem fatura; não faça mapeamento 1:1, não mude pastas, não mude ledger.
Sempre que aparecer um item sem fatura, lembre o cliente que ele pode opcionalmente fornecer faturas substitutas (liste os itens sem fatura e o valor total, explicando que "pode ou não fornecer"). Não force o cliente, não suponha que ele vai complementar.

materiais_complementares/ — Materiais fornecidos posteriormente pelo cliente (processar depois limpar)

Materiais fornecidos posteriormente pelo cliente (faturas faltantes anteriormente, recibos perdidos) coloque em materiais_complementares/. Na próxima execução, processe conforme abaixo, após processar, materiais_complementares/ deve ser esvaziado:

Backup: Copie cada um para backup/_complementar_<data>/ (originais não se perdem).
Ler + Associar eventos: Use o método de leitura do Passo 1 para identificar, vincule a eventos existentes ou crie novos eventos.
Ação de complemento de fatura: Se uma transação era "sem_fatura (aguardando fatura)" e agora chega uma fatura oficial — a fatura vai para com_fatura/, a captura de tela original vai para materiais_auxiliares/, a pasta/confiança/valor (usar total com IVA) do evento no registro é atualizado, e a dúvida correspondente é removida.
Refazer conciliação + preenchimento: Recalcule conforme Passo 6, confirme que o total foi atualizado e ainda é consistente entre os três.
Esvazie materiais_complementares/: Após processamento, remova os arquivos (backups e cópias nas pastas já existem), mantenha vazio para facilitar a próxima execução.

Como deve ficar a Estrutura do Diretório Após Conclusão

<workspace>/
├── <nome_original>_preenchido.xlsx       ← Planilha de despesas preenchida (entrega)
├── relatorio_auditoria.md
├── com_fatura/         Faturas oficiais, evidências independentes (somente após confirmação)
├── sem_fatura/         Evidências principais de despesas reais sem fatura oficial (somente após confirmação)
├── materiais_auxiliares/   Evidências secundárias (capturas de tela de pedido/pagamento/itinerário)
├── aguardando_verificacao/  Itens incertos (pasta/categoria/possibilidade de reembolso); não coloque direto em com_fatura/sem_fatura; mova após verificação
├── faturas_substitutas/    Pool opcional de faturas substitutas: aproximadamente cobre o valor sem fatura para o financeiro, não vira com_fatura, não conta valor (veja 'Diretórios Especiais')
├── explicacoes_adicionais/ Arquivos txt para o financeiro (consolidação/reembolso/moeda estrangeira/divisão)
├── process_files/      identity.json, manifest.json, extracted/, registro_materiais.csv, ledger.json, (pool_faturas_substitutas.csv)
├── backup/             Backup 1:1 dos materiais originais + _modelo_original/ (modelo e *.skill não entram no backup de materiais)
├── materiais_complementares/  Materiais enviados posteriormente pelo cliente; serão limpos após processamento (veja 'Diretórios Especiais')
└── irrelevantes/       Materiais confirmados como não relacionados/não reembolsáveis neste período/de outro período, armazenados separadamente, não incluídos neste período

Verificação Final

Materiais originais e modelo original não foram modificados (apenas backups/cópias foram alterados)
Cada material está em algum diretório e tem uma linha no registro
Sem duplicidade: cada número de evento tem apenas uma linha no ledger; fatura + comprovante de pagamento, antes e depois de reemissão, reembolso com dedução não foram contados como múltiplas transações
Fatura de IVA inserida com total com impostos (incluindo IVA); cancelamento conta apenas a taxa; pagamento pela empresa conta apenas o valor pago pelo indivíduo
Moeda estrangeira já convertida com taxa com origem (ou listada como dúvida)
Modelo preenchido em ordem cronológica; recálculo sem erros de fórmula, e total do modelo = soma do ledger = computed do fill_template
Motivos atendem aos requisitos da anotação correspondente (número de pessoas/data/partida-destino/dias etc.)
aguardando_verificacao/ já vazio (tudo resolvido), materiais_complementares/ já vazio; faturas_substitutas/ (se existir) não conta valor
Itens suspeitos de uso pessoal/irrelevantes e outras dúvidas já foram totalmente esclarecidos com o usuário pessoalmente

Auromix/expense-reimbursement-skill

O que é expense-reimbursement-skill?

Perguntar na sua IA favorita

Documentação