aiskillstore/marketplace

Requisitos para Saídas

Todos os arquivos Excel

Fonte profissional

• Use uma fonte consistente e profissional (ex.: Arial, Times New Roman) para todos os entregáveis, a menos que o usuário instrua o contrário

Zero erros de fórmula

• Todo modelo Excel DEVE ser entregue com ZERO erros de fórmula (#REF!, #DIV/0!, #VALOR!, #N/D, #NOME?)

Preservar modelos existentes (ao atualizar modelos)

• Estude e corresponda EXATAMENTE o formato, estilo e convenções existentes ao modificar arquivos
• Nunca imponha formatação padronizada em arquivos com padrões estabelecidos
• As convenções do modelo existente SEMPRE substituem estas diretrizes

Modelos financeiros

Padrões de codificação por cores

A menos que especificado pelo usuário ou pelo modelo existente

Convenções de cores padrão da indústria

• Texto azul (RGB: 0,0,255): Entradas fixas e números que o usuário alterará para cenários
• Texto preto (RGB: 0,0,0): TODAS as fórmulas e cálculos
• Texto verde (RGB: 0,128,0): Links para outras planilhas dentro do mesmo arquivo
• Texto vermelho (RGB: 255,0,0): Links externos para outros arquivos
• Fundo amarelo (RGB: 255,255,0): Premissas-chave que precisam de atenção ou células que precisam ser atualizadas

Padrões de formatação de números

Regras de formatação obrigatórias

• Anos: Formatar como strings de texto (ex.: "2024" não "2.024")
• Moeda: Usar formato $#.##0; SEMPRE especificar unidades nos cabeçalhos ("Receita ($mm)")
• Zeros: Usar formatação de número para exibir todos os zeros como "-", incluindo porcentagens (ex.: "$#.##0;($#.##0);-")
• Porcentagens: Padrão para formato 0,0% (uma casa decimal)
• Múltiplos: Formatar como 0,0x para múltiplos de valuation (EV/EBITDA, P/L)
• Números negativos: Usar parênteses (123) em vez de sinal de menos -123

Regras de construção de fórmulas

Posicionamento de premissas

• Coloque TODAS as premissas (taxas de crescimento, margens, múltiplos, etc.) em células de premissa separadas
• Use referências de células em vez de valores fixos nas fórmulas
• Exemplo: Use =B5*(1+$B$6) em vez de =B5*1,05

Prevenção de erros de fórmula

• Verifique se todas as referências de células estão corretas
• Verifique erros de deslocamento em intervalos
• Garanta fórmulas consistentes em todos os períodos de projeção
• Teste com casos extremos (valores zero, números negativos)
• Verifique se não há referências circulares não intencionais

Requisitos de documentação para valores fixos

• Comente ou coloque ao lado das células (se no final da tabela). Formato: "Fonte: [Sistema/Documento], [Data], [Referência Específica], [URL se aplicável]"
• Exemplos:
  • "Fonte: Formulário 10-K da Empresa, FY2024, Página 45, Nota de Receita, [URL EDGAR SEC]"
  • "Fonte: Formulário 10-Q da Empresa, 2º Trimestre 2025, Anexo 99.1, [URL EDGAR SEC]"
  • "Fonte: Terminal Bloomberg, 15/08/2025, AAPL US Equity"
  • "Fonte: FactSet, 20/08/2025, Tela de Estimativas Consensuais"

Criação, edição e análise de XLSX

Visão geral

Um usuário pode pedir para você criar, editar ou analisar o conteúdo de um arquivo .xlsx. Você tem diferentes ferramentas e fluxos de trabalho disponíveis para diferentes tarefas.

Requisitos importantes

LibreOffice Necessário para Recalcular Fórmulas: Você pode assumir que o LibreOffice está instalado para recalcular valores de fórmulas usando o script scripts/recalc.py. O script configura automaticamente o LibreOffice na primeira execução, inclusive em ambientes restritos onde sockets Unix são limitados (manipulado por scripts/office/soffice.py)

Leitura e análise de dados

Análise de dados com pandas

Para análise de dados, visualização e operações básicas, use pandas, que oferece poderosas capacidades de manipulação de dados:

import pandas as pd

# Ler Excel
df = pd.read_excel('arquivo.xlsx')  # Padrão: primeira planilha
todas_as_planilhas = pd.read_excel('arquivo.xlsx', sheet_name=None)  # Todas as planilhas como dicionário

# Analisar
df.head()      # Visualizar dados
df.info()      # Informações das colunas
df.describe()  # Estatísticas

# Escrever Excel
df.to_excel('saida.xlsx', index=False)

Fluxos de Trabalho com Arquivos Excel

CRÍTICO: Use Fórmulas, Não Valores Fixos

Sempre use fórmulas do Excel em vez de calcular valores em Python e fixá-los. Isso garante que a planilha permaneça dinâmica e atualizável.

❌ ERRADO - Fixar Valores Calculados

# Ruim: Calculando em Python e fixando o resultado
total = df['Vendas'].sum()
planilha['B10'] = total  # Fixa 5000

# Ruim: Calculando taxa de crescimento em Python
crescimento = (df.iloc[-1]['Receita'] - df.iloc[0]['Receita']) / df.iloc[0]['Receita']
planilha['C5'] = crescimento  # Fixa 0,15

# Ruim: Cálculo em Python para média
media = sum(valores) / len(valores)
planilha['D20'] = media  # Fixa 42,5

✅ CORRETO - Usando Fórmulas do Excel

# Bom: Deixe o Excel calcular a soma
planilha['B10'] = '=SOMA(B2:B9)'

# Bom: Taxa de crescimento como fórmula do Excel
planilha['C5'] = '=(C4-C2)/C2'

# Bom: Média usando função do Excel
planilha['D20'] = '=MÉDIA(D2:D19)'

Isso se aplica a TODOS os cálculos - totais, porcentagens, índices, diferenças, etc. A planilha deve ser capaz de recalcular quando os dados de origem mudarem.

Fluxo de Trabalho Comum

1. Escolher ferramenta: pandas para dados, openpyxl para fórmulas/formatação
2. Criar/Carregar: Criar nova pasta de trabalho ou carregar arquivo existente
3. Modificar: Adicionar/editar dados, fórmulas e formatação
4. Salvar: Escrever no arquivo
5. Recalcular fórmulas (OBRIGATÓRIO SE USAR FÓRMULAS): Use o script scripts/recalc.py

   python scripts/recalc.py saida.xlsx
   

6. Verificar e corrigir quaisquer erros:
   • O script retorna JSON com detalhes dos erros
   • Se status for erros_encontrados, verifique resumo_erros para tipos e locais específicos de erro
   • Corrija os erros identificados e recalcule novamente
   • Erros comuns a corrigir:
     • #REF!: Referências de célula inválidas
     • #DIV/0!: Divisão por zero
     • #VALOR!: Tipo de dado errado na fórmula
     • #NOME?: Nome de fórmula não reconhecido

Criando novos arquivos Excel

# Usando openpyxl para fórmulas e formatação
from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment

wb = Workbook()
planilha = wb.active

# Adicionar dados
planilha['A1'] = 'Olá'
planilha['B1'] = 'Mundo'
planilha.append(['Linha', 'de', 'dados'])

# Adicionar fórmula
planilha['B2'] = '=SOMA(A1:A10)'

# Formatação
planilha['A1'].font = Font(bold=True, color='FF0000')
planilha['A1'].fill = PatternFill('solid', start_color='FFFF00')
planilha['A1'].alignment = Alignment(horizontal='center')

# Largura da coluna
planilha.column_dimensions['A'].width = 20

wb.save('saida.xlsx')

Editando arquivos Excel existentes

# Usando openpyxl para preservar fórmulas e formatação
from openpyxl import load_workbook

# Carregar arquivo existente
wb = load_workbook('existente.xlsx')
planilha = wb.active  # ou wb['NomePlanilha'] para uma planilha específica

# Trabalhando com várias planilhas
for nome_planilha in wb.sheetnames:
    planilha = wb[nome_planilha]
    print(f"Planilha: {nome_planilha}")

# Modificar células
planilha['A1'] = 'Novo Valor'
planilha.insert_rows(2)  # Inserir linha na posição 2
planilha.delete_cols(3)  # Excluir coluna 3

# Adicionar nova planilha
nova_planilha = wb.create_sheet('NovaPlanilha')
nova_planilha['A1'] = 'Dados'

wb.save('modificado.xlsx')

Recalculando fórmulas

Arquivos Excel criados ou modificados pelo openpyxl contêm fórmulas como strings, mas não valores calculados. Use o script fornecido scripts/recalc.py para recalcular fórmulas:

python scripts/recalc.py <arquivo_excel> [segundos_timeout]

Exemplo:

python scripts/recalc.py saida.xlsx 30

O script:

• Configura automaticamente a macro do LibreOffice na primeira execução
• Recalcula todas as fórmulas em todas as planilhas
• Varre TODAS as células em busca de erros do Excel (#REF!, #DIV/0!, etc.)
• Retorna JSON com locais detalhados dos erros e contagens
• Funciona tanto em Linux quanto em macOS

Lista de Verificação de Fórmulas

Verificações rápidas para garantir que as fórmulas funcionem corretamente:

Verificação Essencial

• Testar 2-3 referências de amostra: Verifique se puxam os valores corretos antes de construir o modelo completo
• Mapeamento de colunas: Confirme se as colunas do Excel correspondem (ex.: coluna 64 = BL, não BK)
• Deslocamento de linhas: Lembre-se de que as linhas do Excel são indexadas a partir de 1 (linha 5 do DataFrame = linha 6 do Excel)

Armadilhas Comuns

• Tratamento de NaN: Verifique valores nulos com pd.notna()
• Colunas à direita: Dados de AF geralmente estão nas colunas 50+
• Múltiplas correspondências: Pesquise todas as ocorrências, não apenas a primeira
• Divisão por zero: Verifique denominadores antes de usar / nas fórmulas (#DIV/0!)
• Referências erradas: Verifique se todas as referências de célula apontam para as células pretendidas (#REF!)
• Referências entre planilhas: Use o formato correto (Planilha1!A1) para vincular planilhas

Estratégia de Teste de Fórmulas

• Comece pequeno: Teste fórmulas em 2-3 células antes de aplicar amplamente
• Verifique dependências: Verifique se todas as células referenciadas nas fórmulas existem
• Teste casos extremos: Inclua valores zero, negativos e muito grandes

Interpretando a Saída do scripts/recalc.py

O script retorna JSON com detalhes dos erros:

{
  "status": "sucesso",           // ou "erros_encontrados"
  "total_errors": 0,              // Contagem total de erros
  "total_formulas": 42,           // Número de fórmulas no arquivo
  "error_summary": {              // Presente apenas se erros forem encontrados
    "#REF!": {
      "count": 2,
      "locations": ["Planilha1!B5", "Planilha1!C10"]
    }
  }
}

Melhores Práticas

Seleção de Biblioteca

• pandas: Melhor para análise de dados, operações em massa e exportação simples de dados
• openpyxl: Melhor para formatação complexa, fórmulas e recursos específicos do Excel

Trabalhando com openpyxl

• Índices de célula são baseados em 1 (linha=1, coluna=1 refere-se à célula A1)
• Use data_only=True para ler valores calculados: load_workbook('arquivo.xlsx', data_only=True)
• Aviso: Se aberto com data_only=True e salvo, as fórmulas são substituídas por valores e perdidas permanentemente
• Para arquivos grandes: Use read_only=True para leitura ou write_only=True para escrita
• As fórmulas são preservadas, mas não avaliadas - use scripts/recalc.py para atualizar os valores

Trabalhando com pandas

• Especifique tipos de dados para evitar problemas de inferência: pd.read_excel('arquivo.xlsx', dtype={'id': str})
• Para arquivos grandes, leia colunas específicas: pd.read_excel('arquivo.xlsx', usecols=['A', 'C', 'E'])
• Manipule datas corretamente: pd.read_excel('arquivo.xlsx', parse_dates=['coluna_data'])

Diretrizes de Estilo de Código

IMPORTANTE: Ao gerar código Python para operações com Excel:

• Escreva código Python mínimo e conciso, sem comentários desnecessários
• Evite nomes de variáveis verbosos e operações redundantes
• Evite declarações print desnecessárias

Para os próprios arquivos Excel:

• Adicione comentários a células com fórmulas complexas ou premissas importantes
• Documente fontes de dados para valores fixos
• Inclua notas para cálculos-chave e seções do modelo