M9 closure: fundamentos completos para empresas listadas na B3

A milestone M9 — Cias abertas (DFP/ITR/IPE) está fechada. O OBM passou de "ticker B3" para "empresa com fundamentos" em quatro fases entregues como branch única para a develop.

O que entrou

Fase 1 — Cadastro

• companies.slug introduzida (migration 0071); cadastro CVM já populado anteriormente via cad_cia_aberta.
• Endpoints /v1/assets/companies (listing + detail + sitemap).
• Páginas /empresas (listing com filtros) + /empresas/[slug] (detail com tickers vinculados).
• 3 termos de glossário: cia-aberta, cd-cvm, plano-de-contas-cvm.

Fase 2 — Demonstrações DFP/ITR

• Schema versionado (migration 0072): account_plans + account_plan_aliases + financial_statements + financial_statement_lines.
• Parsers cvm_dfp.py e CLI sync_dfp/sync_itr cobrindo os 6 demonstrativos × 2 escopos × N versões.
• Endpoint /v1/assets/companies/{slug}/statements + detail por statement_type.
• Página /empresas/[slug]/fundamentos com tabela hierárquica + período anterior + download CVM.
• 13 termos: DFP, ITR, BPA, BPP, DRE, DFC, DVA, DMPL, consolidado-vs-individual, EBITDA, lucro líquido, receita líquida, VPA.
• 2 posts: Cobertura DFP/ITR e Como ler um balanço com Petrobras.

Fase 3 — Eventos e comunicados (IPE)

• Schema material_events (migration 0073).
• Parser cvm_ipe.py + CLI sync_ipe + Procrastinate task daily.
• Endpoint /v1/assets/companies/{slug}/events + página /empresas/[slug]/eventos (timeline cronológica reversa).
• 3 termos: IPE, fato relevante, comunicado ao mercado.

Fase 4 — Valuation derivada + comparador

• Schema company_fundamentals (migration 0074).
• Serviço services/company_fundamentals.py computando margens, ROE, ROA, dívida líquida.
• Endpoint /v1/assets/companies/{slug}/kpis + cards na detail page.
• Página /empresas/comparar?slugs=... lado a lado (até 4 empresas).
• 10 termos de valuation: P/L, P/VP, ROE, ROA, margem bruta, margem líquida, margem EBITDA, dívida líquida, EV/EBITDA, dividend yield.
• 2 posts: P/L, P/VP, ROE explicados e Comparativo dos bancões 2026.

Números

• ~24 termos novos no glossário (Fase 1: 3, Fase 2: 13, Fase 3: 3, Fase 4: 10).
• 5 posts no blog (1 anchor, 1 deep-dive, 1 explainer, 1 comparativo, este closure).
• 4 migrations Alembic novas (0071, 0072, 0073, 0074).
• 5 endpoints /v1/assets/companies/* novos.
• 5 páginas /empresas/* novas.
• 4 Procrastinate tasks: sync-dfp, sync-itr, sync-ipe, compute-company-fundamentals.

O que ficou de fora explicitamente

• P/L, P/VP, EV/EBITDA, DY 12m dependem de market_cap (preço atual × ações em circulação). Ações em circulação vem do DMPL e demanda um upsert separado para chegar em company_fundamentals. Fica como follow-up curto.
• Comparador OG image dinâmica: o comparador já é shareable via URL, mas o OG image padrão é genérico. Trabalho de design + endpoint /api/og/empresas-comparar em iteração posterior.
• Full-text search nas notas explicativas: D4 do closure doc deferiu para pós-M9. Notas ficam acessíveis via download do zip CVM linkado em cada statement_type.
• Backfill histórico extenso: ingest atual cobre o ano corrente. Para back-fill profundo (10 anos de DFP), basta defer sync-dfp --year YYYY por ano. Mantemos como operação ad-hoc, não scheduled automation.

Para começar a usar

• Empresa que você quer estudar: /empresas/[slug] (ex.: /empresas/petrobras).
• Comparar lado a lado: /empresas/comparar?slugs=....
• Acompanhar fatos relevantes: /empresas/[slug]/eventos.
• Ler glossário para entender as siglas: /glossario/dfp, /glossario/pl-ratio etc.

Próxima milestone

Com M9 fechada, o backlog Coverage v∞ avança para M10 (letras estaduais/municipais — spike de pesquisa) ou para um follow-up adjacente (B3 BDI / arquivos de pregão históricos, já listados em docs/product/coverage-roadmap.md). A próxima milestone abre quando o doc-ponte aprovado for mergeado.