Publica gerador evolutivo e carrega modelos do repositório MESA

Atualiza importação e narrativa das avaliações, tabelas e notas. No Space, consulta o dataset da MESA com cache por revisão e acesso autenticado somente no backend. Validado com 99 testes Python, 6 testes do frontend e build Vite.

.dockerignore

@@ -8,3 +8,6 @@ node_modules
 frontend/node_modules
 output/laudos_gerados
 output/tmp_uploads
+models/files
+models/backups
+tmp

Dockerfile

@@ -11,6 +11,9 @@ FROM python:3.11-slim AS runtime
 ENV PYTHONDONTWRITEBYTECODE=1
 ENV PYTHONUNBUFFERED=1
 ENV PORT=7860
+ENV MODELOS_REPOSITORIO_PROVIDER=hf_dataset
+ENV MODELOS_REPOSITORIO_HF_REPO_ID=gui-sparim/repositorio_mesa
+ENV MODELOS_REPOSITORIO_HF_SUBDIR=modelos_dai
 WORKDIR /app
 
 COPY requirements.txt ./

README.md

@@ -19,6 +19,19 @@ Aplicação para geração de laudos de avaliação imobiliária com backend em
 
 ## Rodando em desenvolvimento local
 
+Para iniciar backend e frontend juntos:
+
+```bash
+./run_dev.sh
+```
+
+O script procura as próximas portas livres a partir de `8000` para o backend e
+`5173` para o frontend, configura a conexão com a API e as origens CORS, e exibe
+os endereços escolhidos. Para mudar as portas iniciais, use, por exemplo,
+`PORT=8100 FRONTEND_PORT=5200 ./run_dev.sh`. `Ctrl+C` encerra os dois servidores.
+
+Também é possível iniciar cada serviço separadamente:
+
 ### 1) Backend
 
 ```bash
@@ -69,9 +82,76 @@ Este repositório inclui `Dockerfile` para Spaces com Docker SDK.
 
 - Builda o frontend em estágio Node
 - Sobe API FastAPI na porta `7860` (ou `PORT` informado pelo ambiente)
+- Consulta os modelos no dataset da MESA, `gui-sparim/repositorio_mesa`, pasta `modelos_dai`.
+  Os arquivos `.dai` locais e seus backups não entram na imagem Docker.
+
+Cadastre nos **Settings → Secrets** do Space o `HF_TOKEN` com acesso de leitura
+ao dataset da MESA, caso ele seja privado. O token permanece no backend.
+Em Spaces, a fonte é sempre o dataset; falhas de acesso são informadas e não
+substituídas pelos modelos locais.
+
+Configuração opcional em **Settings → Variables** (mesmos nomes da MESA):
+
+- `MODELOS_REPOSITORIO_HF_REPO_ID`: padrão `gui-sparim/repositorio_mesa`
+- `MODELOS_REPOSITORIO_HF_REVISION`: padrão `main`
+- `MODELOS_REPOSITORIO_HF_SUBDIR`: padrão `modelos_dai`
+- `MODELOS_REPOSITORIO_HF_CACHE_TTL_SECONDS`: padrão `300` segundos
+
+O catálogo é consultado novamente após esse intervalo. Cada modelo é baixado
+somente quando utilizado e a versão fica vinculada ao commit do dataset.
+Uma nova revisão invalida os modelos carregados em memória, incluindo modelos
+alterados ou excluídos. O cache de downloads do Hub evita transferências repetidas.
+
+No desenvolvimento fora do Docker/Spaces, o padrão continua sendo `models/files`.
+Para testar a mesma fonte de produção localmente, defina
+`MODELOS_REPOSITORIO_PROVIDER=hf_dataset` e configure `HF_TOKEN` no ambiente.
 
 Comando de execução no container:
 
 ```bash
 uvicorn backend.app.main:app --host 0.0.0.0 --port ${PORT:-7860}
 ```
+
+## Importação de avaliações do MESA
+
+A aplicação abre na etapa **Início · Importar avaliação**. A importação sugere os
+motivos desvalorizantes e preenche método, modelos, referências e valores na
+seção **5. Avaliação**. Os dados continuam editáveis; revisar anos ou trocar o
+arquivo atualiza os campos automáticos e preserva as alterações manuais. Os
+valores adotados são reiniciados ao trocar de arquivo para não reutilizar valores
+de outra avaliação.
+
+As condições registradas na MESA são sugeridas como confirmadas, sem presumir
+que tenham sido alegadas pelo contribuinte. Revise essas marcações na seção de
+motivos. O catálogo de condições tem origem e versão da MESA; para sincronizá-lo,
+execute `python scripts/sync_mesa_redutores.py /caminho/mesa-frame`.
+
+Um valor de mercado editado é usado no cabeçalho e na conclusão; a memória do
+laudo conserva também o valor registrado na avaliação de origem. Método, nome do
+modelo e referências revisados são textos documentais; a identificação original
+do modelo permanece disponível para a metodologia e os anexos.
+
+A importação preenche modelo e valores de mercado a partir de um arquivo JSON
+exportado pelo MESA:
+
+- **`.ame` (versão 1):** uma ou várias avaliações por modelo; mantém entradas, valores adotados, intervalos, KNN, ajustes e fundamentação, sem incorporar a base do modelo.
+- **`.evo` (versões 1 e 2):** composições evolutivas salvas com resultado válido. Importa separadamente terreno, construção e total adotado. Redutores e fator de comercialização podem fazer o total diferir da soma dos componentes.
+
+A prévia identifica o ano pelos parâmetros anuais 0/1, títulos e referências temporais. Cenários com todos os anos em zero usam o ano-base indicado no título exportado; se o título for apenas “Ano Base”, o ano deve ser informado pelo usuário. Referências ausentes ou conflitantes também devem ser confirmadas. O usuário escolhe se os anos representam a data-base da avaliação ou o exercício do IPTU; o documento registra ambos. Anos duplicados são apresentados como avaliações separadas, sem somar valores. Para avaliações por modelo, o objeto avaliado pode ser identificado na prévia.
+
+O arquivo é lido novamente no backend ao gerar o documento; os valores da prévia não substituem os resultados originais. Valores unitários sem total não são tratados como totais. Arquivos inválidos, versões desconhecidas e composições sem resultado são recusados. Limite de upload: 50 MB.
+
+O laudo evolutivo apresenta no corpo as seções **3.3 Terreno**, **3.4 Construções** e **3.5 Composição do imóvel**, com parâmetros por exercício, variáveis e equação, áreas de modelo e aplicação, CUB histórico simples ou composto, adequação, BDI, Ross-Heidecke, residual, Kd, redutores e Fc. A seção 4 discrimina fundamentação dos componentes e global, com a precisão restrita ao terreno. A conclusão mostra o valor adotado e seu extenso; a composição conserva o resultado calculado.
+
+Em **5. Avaliação**, a revisão recupera as justificativas públicas salvas e permite complementar VU, área, BDI por sequência, Fc, ajustes não aplicados e critério de adoção. É possível reutilizar deliberadamente as justificativas nos demais exercícios. Critérios de fundamentação não preenchidos continuam pendentes; observações internas não são publicadas. Conferências com os dados salvos apontam divergências sem corrigir os resultados.
+
+Os anexos estatísticos EVO usam o modelo do catálogo (dataset da MESA no Hugging Face ou pasta local no desenvolvimento) somente quando coeficientes, covariância, transformações e amostra correspondem ao contexto preservado. Caso contrário, o documento registra a falta de correspondência e utiliza o contexto importado na narrativa. Resultados não são reestimados. As avaliações AME e o preenchimento manual mantêm seus fluxos próprios.
+
+As explicações técnicas são extraídas das fontes da MESA por `node scripts/sync_mesa_documentacao.mjs`. O catálogo versionado é gravado em `config/mesa_documentacao.json` e em `mesa-frame/frontend/src/evolutivo/documentacaoTecnica.json`; as novas exportações EVO incorporam o mesmo pacote e conservam os pacotes já existentes. Arquivos antigos continuam importáveis, com indicação explícita do uso do catálogo sincronizado quando falta um pacote histórico. Para atualizar o catálogo de redutores, use `python scripts/sync_mesa_redutores.py`.
+
+Endpoints adicionais:
+
+- `POST /api/avaliacoes/importar`: multipart com `arquivo`; retorna a prévia.
+- `POST /api/laudos/generate`: inclui `arquivo_avaliacoes` e as opções `importacao_avaliacoes` no JSON de `payload` (`anos`, `referencia_anos`, `objeto_modelo`, `valores_adotados`, `complementos`, `campos_editados`).
+
+Validação: `python -m unittest discover -s tests -v` e `npm run build --prefix frontend`.

backend/app/avaliacoes_import.py

@@ -0,0 +1,247 @@
+"""Read MESA JSON exports without loading executable models or recalculating results."""
+from __future__ import annotations
+
+import json
+import re
+from copy import deepcopy
+from decimal import Decimal, InvalidOperation, ROUND_HALF_UP
+from pathlib import Path
+
+from .import_defaults import motivos_da_avaliacao, sugestoes_documentais
+from .evo_documentation import saved_complements, apply_complements, review_for
+from document.mesa_content import current_content
+
+MAX_FILE_BYTES = 50 * 1024 * 1024
+YEAR = re.compile(r"(?<!\d)(?:19|20|21)\d{2}(?!\d)")
+
+
+def record(value):
+    return value if isinstance(value, dict) else {}
+
+
+def money(value):
+    if value is None or value == "" or isinstance(value, bool):
+        return None
+    try:
+        number = Decimal(str(value))
+        if not number.is_finite() or number < 0:
+            return None
+        return format(number.quantize(Decimal('.01'), rounding=ROUND_HALF_UP), '.2f')
+    except (InvalidOperation, ValueError):
+        return None
+
+
+def first_money(*values):
+    return next((parsed for value in values if (parsed := money(value)) is not None), None)
+
+
+def year_in(text):
+    years = set(YEAR.findall(str(text or '')))
+    return next(iter(years)) if len(years) == 1 else None
+
+
+def parameter_year(values):
+    years = {str(key).strip(): str(value) for key, value in record(values).items()
+             if re.fullmatch(r'(?:19|20|21)\d{2}', str(key).strip())}
+    if not years:
+        return None, False, []
+    try:
+        nums = {key: Decimal(value) for key, value in years.items()}
+    except InvalidOperation:
+        return None, False, ['Há parâmetros anuais inválidos; informe o ano de referência.']
+    active = [key for key, value in nums.items() if value == 1]
+    if all(value == 0 for value in nums.values()):
+        return None, True, []
+    if len(active) == 1 and all(value in (0, 1) for value in nums.values()):
+        return active[0], False, []
+    return None, False, ['Os parâmetros anuais não identificam um único ano; confira a referência.']
+
+
+def compact_evaluation(value):
+    source = record(value)
+    if source.get('valores_x') is not None and not isinstance(source['valores_x'], dict):
+        raise ValueError('Os parâmetros da avaliação devem ser um objeto JSON.')
+    names = ('valores_x', 'tipo_y', 'coluna_area', 'valor_area', 'estimado',
+             'estimado_unitario', 'estimado_total', 'ca_inf', 'ca_sup', 'ic_inf',
+             'ic_sup', 'perc_inf', 'perc_sup', 'amplitude', 'precisao', 'fundamentacao',
+             'knn_estimado', 'knn_estimado_unitario', 'knn_estimado_total', 'extrapolacoes')
+    return {name: source[name] for name in names if name in source}
+
+
+def ame_rows(data):
+    cards = data.get('avaliacoes')
+    # Accept the initial single-card AME layout as well as the current list.
+    if cards is None and isinstance(data.get('card'), dict):
+        cards = [{**data['card'], 'titulo': data.get('titulo'), 'nomeModelo': data.get('nomeModelo')}]
+    if not isinstance(cards, list) or not cards:
+        raise ValueError('O arquivo AME não contém avaliações.')
+    for index, item in enumerate(cards):
+        if not isinstance(item, dict):
+            raise ValueError('Avaliação inválida no arquivo AME.')
+        evaluation = record(item.get('avaliacao'))
+        title = str(item.get('titulo') or f'Avaliação {index + 1}')
+        adjusted = record(record(evaluation.get('ajuste_territorial')).get('resultado'))
+        total = first_money(adjusted.get('valor_total_imovel'), adjusted.get('valor_total_territorial'),
+                            evaluation.get('estimado_total'),
+                            evaluation.get('estimado') if evaluation.get('tipo_y') == 'total' else None)
+        if total is None:
+            raise ValueError(f'{title}: falta o valor total. Configure o tipo de valor e a área no MESA e exporte novamente; valor unitário não será tratado como total.')
+        year, base, warnings = parameter_year(evaluation.get('valores_x'))
+        label_year = year_in(title)
+        if year and label_year and year != label_year:
+            year = None
+            warnings.append('O título e o parâmetro anual divergem; informe o ano correto.')
+        elif not year and not warnings and (not base or YEAR.fullmatch(title.strip())):
+            year = label_year
+        yield {
+            'id': f'ame-{index + 1}', 'titulo': title,
+            'modelo': str(item.get('nomeModelo') or item.get('modelo') or evaluation.get('modelo_nome') or ''),
+            'ano_sugerido': year, 'cenario_base': base, 'avisos': warnings,
+            'valor_total': total,
+            'valor_unitario': first_money(adjusted.get('valor_unitario_adotado'), evaluation.get('estimado_unitario')),
+            'valor_terreno': None, 'valor_construcao': None,
+            'area': evaluation.get('valor_area'),
+            'avaliacao': compact_evaluation(evaluation),
+            'fundamentacao': record(item.get('fundamentacaoCalculada')),
+            'ajustes': record(evaluation.get('ajuste_territorial')),
+            'motivos_desvalorizantes': motivos_da_avaliacao(item, evaluation),
+        }
+
+
+def evo_rows(data):
+    years = data.get('anos')
+    if not isinstance(years, list) or not years:
+        raise ValueError('O arquivo EVO não contém avaliações.')
+    for index, item in enumerate(years):
+        if not isinstance(item, dict):
+            raise ValueError('Composição inválida no arquivo EVO.')
+        terrain, construction = record(item.get('terreno')), record(item.get('construcao'))
+        for container, keys in [(item,('catalogoAjustes','fundamentacaoGlobal','documentacaoTecnica','complementosDocumentais')),
+                                (terrain,('contextoModelo','parametrosAplicados','parametrosOriginais','fundamentacaoModelo','avaliacao')),
+                                (construction,('avaliacao','fundamentacaoMqc'))]:
+            if any(container.get(key) is not None and not isinstance(container[key],dict) for key in keys):
+                raise ValueError('Os dados documentais da avaliação evolutiva devem ser objetos JSON.')
+        result = record(item.get('resultadoComposicao'))
+        title = str(item.get('identificacao') or f'Avaliação evolutiva {index + 1}')
+        if not terrain or not construction or not result or result.get('erros') or not isinstance(construction.get('construcoes', []), list):
+            raise ValueError(f'{title}: composição incompleta ou sem resultado válido. Recalcule no MESA antes de exportar.')
+        total = first_money(result.get('valorTotal'))
+        terrain_total = first_money(result.get('valorTerrenoPgv'), terrain.get('valorTotal'))
+        construction_total = first_money(result.get('valorConstrucao'), construction.get('valorTotal'))
+        if any(value is None for value in (total, terrain_total, construction_total)):
+            raise ValueError(f'{title}: faltam valores de terreno, construção ou total adotado.')
+        evaluation = record(terrain.get('avaliacao'))
+        year, base, warnings = parameter_year(terrain.get('parametrosAplicados') or evaluation.get('valores_x'))
+        reference = year_in(item.get('referencia') or item.get('ano'))
+        construction_year = year_in(construction.get('anoReferencia'))
+        inferred = {value for value in (year, reference, construction_year) if value}
+        if len(inferred) > 1:
+            year = None
+            warnings.append('As referências do terreno, construção ou composição divergem; confirme o ano adotado.')
+        else:
+            year = next(iter(inferred), None)
+        if base and not reference:
+            year = None
+            warnings.append('O terreno está no cenário com todos os anos em zero. Informe o ano-base dessa composição; o ano do CUB não define sozinho o ano-base do terreno.')
+        if not item.get('concluida'):
+
+            warnings.append('A composição foi salva sem a marca de conclusão no MESA.')
+        yield {
+            'id': f'evo-{index + 1}', 'titulo': title, 'modelo': str(terrain.get('modelo') or ''),
+            'ano_sugerido': year, 'cenario_base': base and not reference,
+            'avisos': warnings, 'valor_total': total, 'valor_terreno': terrain_total,
+            'valor_construcao': construction_total, 'valor_unitario': first_money(result.get('valorUnitarioTerreno'), terrain.get('valorUnitario')),
+            'id_origem': item.get('id'),
+            'evolutivo': deepcopy(item),
+            'complementos': saved_complements(item),
+            'revisao_documental': review_for(item, saved_complements(item)),
+            'area': terrain.get('areaAplicacao') if terrain.get('areaAplicacao') is not None else terrain.get('area'),
+            'area_construida': construction.get('area'), 'avaliacao': compact_evaluation(evaluation),
+            'construcoes': deepcopy([row for row in construction.get('construcoes', []) if isinstance(row, dict)]),
+            'fator_comercializacao': result.get('fatorFcAplicado', item.get('fatorComercializacao')),
+            'valor_antes_redutores_imovel': result.get('valorAposConstrucao'),
+            'valor_apos_redutores_imovel': result.get('valorAposRedutoresImovel'),
+            'observacoes': str(item.get('observacoes') or ''),
+            'motivos_desvalorizantes': motivos_da_avaliacao(item, evaluation, item.get('catalogoAjustes')),
+        }
+
+
+def parse_export(content: bytes, filename: str):
+    extension = Path(filename).suffix.lower()
+    if extension not in ('.ame', '.evo'):
+        raise ValueError('Envie um arquivo .ame ou .evo.')
+    if len(content) > MAX_FILE_BYTES:
+        raise ValueError('O arquivo excede o limite de 50 MB.')
+    try:
+        data = json.loads(content.decode('utf-8-sig'), parse_constant=lambda value: (_ for _ in ()).throw(ValueError(value)))
+    except (UnicodeError, ValueError, RecursionError) as exc:
+        raise ValueError('O arquivo não contém JSON válido.') from exc
+    if not isinstance(data, dict):
+        raise ValueError('Estrutura de arquivo inválida.')
+    if extension == '.ame':
+        if data.get('formato') != 'ame' or data.get('versao') != 1:
+            raise ValueError('Formato ou versão AME não suportado.')
+        rows, kind = list(ame_rows(data)), 'modelo'
+    else:
+        if data.get('format') != 'mesa-evolutivo' or data.get('version') not in (1, 2):
+            raise ValueError('Formato ou versão EVO não suportado.')
+        rows, kind = list(evo_rows(data)), 'evolutivo'
+    return {'arquivo': Path(filename).name, 'tipo': kind, 'avaliacoes': rows,
+            'conteudo_tecnico': {'identificador': current_content()['identificador'], 'versao': current_content()['versao']},
+            'sugestoes': sugestoes_documentais(rows, kind)}
+
+
+def resolve_import(parsed, choices):
+    if choices.referencia_anos not in ('ano_base', 'exercicio_iptu'):
+        raise ValueError('Selecione a interpretação dos anos.')
+    known_ids = {source['id'] for source in parsed['avaliacoes']}
+    if set(choices.valores_adotados) - known_ids:
+        raise ValueError('Há valores adotados para avaliações que não pertencem ao arquivo.')
+    if set(choices.complementos) - known_ids:
+        raise ValueError('Há complementos para avaliações que não pertencem ao arquivo.')
+    rows = []
+    for source in parsed['avaliacoes']:
+        selected = choices.anos[source['id']] if source['id'] in choices.anos else source['ano_sugerido']
+        year = str(selected or '').strip()
+        if not re.fullmatch(r'(?:19|20|21)\d{2}', year):
+            raise ValueError(f"Informe o ano de referência para {source['titulo']}.")
+        base = int(year) if choices.referencia_anos == 'ano_base' else int(year) - 1
+        warnings = [warning for warning in source['avisos']
+                    if not any(word in warning.lower() for word in ('informe', 'confira', 'confirme'))]
+        if not source['ano_sugerido']:
+            warnings.append('Referência temporal definida pelo usuário durante a importação.')
+        original_title = source['titulo']
+        title = f'Exercício {base + 1}'
+        if source['cenario_base']:
+            title += ' — Cenário base'
+        elif not re.fullmatch(r'(?:19|20|21)\d{2}', original_title.strip()):
+            title += f' — {original_title}'
+        rows.append({**source, 'titulo_origem': original_title, 'titulo': title,
+                     'avisos': warnings, 'ano_base': str(base), 'ano': str(base + 1),
+                     'objeto': 'Terreno e construção' if parsed['tipo'] == 'evolutivo' else choices.objeto_modelo.strip() or 'Objeto avaliado por modelo'})
+        if parsed['tipo'] == 'evolutivo':
+            complements = deepcopy(source['complementos'])
+            if source['id'] in choices.complementos:
+                override = choices.complementos[source['id']]
+                changes = override.model_dump(exclude_unset=True)
+                for key, value in changes.items():
+                    if key in ('bdi', 'requisitos_grau_iii'):
+                        complements[key] = {**complements.get(key, {}), **value}
+                    else:
+                        complements[key] = value
+            rows[-1]['complementos'] = complements
+            rows[-1]['evolutivo'] = apply_complements(source['evolutivo'], complements)
+            rows[-1]['revisao_documental'] = review_for(rows[-1]['evolutivo'], complements)
+        if source['id'] in choices.valores_adotados:
+            adopted = money(choices.valores_adotados[source['id']])
+            if adopted is None:
+                raise ValueError(f"Informe um valor adotado válido para {source['titulo']}.")
+            if adopted != source['valor_total']:
+                rows[-1]['valor_total_origem'] = source['valor_total']
+                rows[-1]['valor_total'] = adopted
+    rows.sort(key=lambda item: (int(item['ano_base']), item['titulo']))
+    from collections import Counter
+    occurrences = Counter(item['ano_base'] for item in rows)
+    for row in rows:
+        row['referencia_duplicada'] = occurrences[row['ano_base']] > 1
+    return {**parsed, 'avaliacoes': rows}

backend/app/evo_documentation.py

@@ -0,0 +1,123 @@
+"""Saved case-specific reasons and missing documentary evidence for EVO review."""
+from copy import deepcopy
+from document.mesa_content import content_for
+from document.fundamentacao import global_foundation, POINTS, number
+from decimal import Decimal, ROUND_HALF_UP
+from models.construction_identity import construction_identity
+
+
+def construction_key(row, index):
+    return str(row.get('id') or row.get('seq') or index+1)
+
+
+def public_reason(obj, *keys):
+    for key in keys:
+        if obj.get(key + 'Interna') or obj.get(key + '_interna'):
+            continue
+        value = obj.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return ''
+
+
+def saved_complements(source):
+    terrain = source.get('terreno') or {}
+    evaluation = terrain.get('avaliacao') or {}
+    ca = (evaluation.get('ajuste_territorial') or {}).get('configuracao', {}).get('campo_arbitrio') or {}
+    manual = terrain.get('fundamentacaoModelo') or {}
+    construction = source.get('construcao') or {}
+    global_state = source.get('fundamentacaoGlobal') or {}
+    result = {
+        'justificativa_vu': public_reason(ca, 'justificativa') or public_reason(terrain, 'justificativaVu', 'justificativaValorUnitario'),
+        'justificativa_area': public_reason(terrain, 'justificativaArea', 'areaAplicacaoJustificativa'),
+        'justificativa_fc': public_reason(global_state, 'justificativa', 'justificativaFc') or public_reason(source, 'justificativaFc', 'fatorComercializacaoJustificativa'),
+        'ajustes_nao_aplicados': public_reason(source, 'ajustesNaoAplicados'),
+        'criterio_adocao': public_reason(source, 'criterioAdocao'),
+        'fc_criterio': global_state.get('fatorComercializacao') or '',
+        'bdi': {construction_key(row, i): public_reason(row, 'bdiJustificativa', 'justificativaBdi') for i, row in enumerate(construction.get('construcoes') or [])},
+        'caracterizacao_grau': (manual.get('caracterizacao') or {}).get('grau',''),
+        'caracterizacao_justificativa': public_reason(manual.get('caracterizacao') or {}, 'justificativa'),
+        'identificacao_grau': (manual.get('identificacaoDados') or {}).get('grau',''),
+        'identificacao_justificativa': public_reason(manual.get('identificacaoDados') or {}, 'justificativa'),
+        'requisitos_grau_iii': manual.get('requisitosGrauIII') or {},
+    }
+    # Future EVO files may preserve these exact documentary fields as a package.
+    saved = source.get('complementosDocumentais') or {}
+    for key in result:
+        if saved.get(key): result[key] = saved[key]
+    return result
+
+
+def apply_complements(source, values):
+    source = deepcopy(source)
+    terrain = source.setdefault('terreno', {})
+    state = terrain.setdefault('fundamentacaoModelo', {})
+    for prefix, key in [('caracterizacao','caracterizacao'),('identificacao','identificacaoDados')]:
+        selected = values.get(prefix+'_grau', '')
+        if selected and selected not in POINTS:
+            raise ValueError('Grau de fundamentação inválido.')
+        state[key] = {'grau':selected,'justificativa':values.get(prefix+'_justificativa','')}
+    allowed = {item['value'] for item in content_for(source)['criterios_fc']}
+    if values.get('fc_criterio') and values['fc_criterio'] not in allowed:
+        raise ValueError('Critério do fator de comercialização inválido.')
+    reqs = values.get('requisitos_grau_iii') or {}
+    allowed_reqs = {item['key'] for item in content_for(source)['requisitos_modelo']}
+    if set(reqs) - allowed_reqs or any(v not in ('','sim','nao',True,False) for v in reqs.values()):
+        raise ValueError('Requisitos do Grau III inválidos.')
+    state['requisitosGrauIII'] = reqs
+    source.setdefault('fundamentacaoGlobal', {})['fatorComercializacao'] = values.get('fc_criterio','')
+    source['complementosDocumentais'] = deepcopy(values)
+    return source
+
+
+def review_for(source, complements):
+    terrain = source.get('terreno') or {}
+    area_model = terrain.get('areaModelo', (terrain.get('avaliacao') or {}).get('valor_area'))
+    area_apply = terrain.get('areaAplicacao', terrain.get('area'))
+    pending = []
+    for key, label, required in [
+        ('justificativa_vu','Escolha do valor unitário / campo de arbítrio',True),
+        ('justificativa_area','Diferença entre área do modelo e área de aplicação',number(area_model) != number(area_apply)),
+        ('justificativa_fc','Escolha do fator de comercialização',True),
+    ]:
+        if required and not complements.get(key): pending.append(label)
+    constructions = []
+    construction = source.get('construcao') or {}
+    for index, row in enumerate(construction.get('construcoes') or []):
+        key = construction_key(row,index)
+        name = row.get('nome') or f"Construção {row.get('seq') or index+1} — {row.get('tipoConstrucao') or 'tipo não informado'}"
+        constructions.append({'id':key,'nome':name,'bdi':row.get('bdi'),'grupo':construction_identity(source,row,index)})
+        if not complements.get('bdi',{}).get(key): pending.append(f'BDI: {name}')
+    foundation = global_foundation(source)
+    for label, item in [('Terreno',foundation['terrain']),('Construções',foundation['construction']),('Global',foundation)]:
+        if item['grade'] == 'Pendente': pending.append(f'Fundamentação {label.lower()}: há critérios não informados')
+    return {'pendencias':pending,'construcoes':constructions,'area_modelo':area_model,'area_aplicacao':area_apply,
+            'conferencias': check_saved_results(source),
+            'fundamentacao': {k:foundation[k]['grade'] for k in ['terrain','construction']} | {'global':foundation['grade']},
+            'criterios_fc':content_for(source)['criterios_fc'],'requisitos_modelo':content_for(source)['requisitos_modelo']}
+
+
+def check_saved_results(source):
+    """Report inconsistencies using saved precision; never repair source values."""
+    warnings = []
+    result = source.get('resultadoComposicao') or {}
+    def check(label, expected, actual):
+        actual = number(actual)
+        if expected is not None and actual is not None:
+            expected = expected.quantize(Decimal('.01'),rounding=ROUND_HALF_UP)
+            if abs(expected-actual) > Decimal('.02'):
+                warnings.append(f'{label}: os dados salvos não reproduzem o resultado registrado (conferência {expected}; registro {actual}). O resultado de origem foi preservado.')
+    terrain = source.get('terreno') or {}
+    vu = number(result.get('valorUnitarioTerreno',result.get('valorCa',terrain.get('valorUnitario'))))
+    area = number(terrain.get('areaAplicacao',terrain.get('area')))
+    check('Valor territorial',vu*area if vu is not None and area is not None else None,result.get('valorTerrenoPgv'))
+    construction_values = []
+    for i, item in enumerate((source.get('construcao') or {}).get('construcoes') or []):
+        a,c,bdi,kd = [number(item.get(key)) for key in ['areaCalculada','custoUnitario','bdi','kd']]
+        check(f"Construção {item.get('seq') or i+1}",a*c*(1+bdi/100)*kd if all(v is not None for v in (a,c,bdi,kd)) else None,item.get('vcalcConstSeq'))
+        construction_values.append(number(item.get('vcalcConstSeq')))
+    if construction_values and all(v is not None for v in construction_values):
+        check('Total das construções',sum(construction_values),result.get('valorConstrucao'))
+    base,fc = number(result.get('valorAposRedutoresImovel')),number(result.get('fatorFcAplicado'))
+    check('Aplicação final do Fc',base*fc if base is not None and fc is not None else None,result.get('valorTotalCalculado'))
+    return warnings

backend/app/import_defaults.py

@@ -0,0 +1,90 @@
+"""Sugestões documentais a partir das condições registradas nas avaliações."""
+from functools import lru_cache
+import json
+from pathlib import Path
+from config.constants import METODO_COMPARATIVO, METODO_EVOLUTIVO
+
+
+def record(value):
+    return value if isinstance(value, dict) else {}
+
+
+@lru_cache(maxsize=1)
+def catalogo_mesa():
+    path = Path(__file__).resolve().parents[2] / "config/mesa_redutores.json"
+    return json.loads(path.read_text(encoding="utf-8"))["catalogo"]
+
+
+def positivo(value):
+    try:
+        return float(value) > 0
+    except (TypeError, ValueError):
+        return False
+
+
+def motivos_da_avaliacao(item, evaluation, catalog=None):
+    catalog = record(catalog) or catalogo_mesa()
+    ajuste = record(record(evaluation).get("ajuste_territorial"))
+    config = record(ajuste.get("configuracao")) or ajuste
+    redutores = record(ajuste.get("redutores"))
+    reasons = {}
+
+    def add(description, alleged=False, confirmed=True):
+        description = str(description or "").strip()
+        if not description:
+            return
+        key = description.casefold()
+        previous = reasons.get(key, {})
+        reasons[key] = {"descricao": description,
+                        "alegado": bool(alleged or previous.get("alegado")),
+                        "confirmado": bool(confirmed or previous.get("confirmado"))}
+
+    for reason in item.get("motivos_desvalorizantes", []) if isinstance(item.get("motivos_desvalorizantes"), list) else []:
+        if isinstance(reason, dict):
+            add(reason.get("descricao"), reason.get("alegado", False), reason.get("confirmado", False))
+
+    def selected(group, codes, subkey="condicoes"):
+        if not isinstance(codes, (list, tuple, set)):
+            return
+        for condition in record(catalog.get(group)).get(subkey, []):
+            if condition.get("codigo") in codes:
+                add(condition.get("rotulo"))
+
+    conditions = record(record(config.get("art_88_i")).get("condicoes"))
+    details = record(record(redutores.get("art_88")).get("condicoes_inciso_i"))
+    for condition in record(catalog.get("art_88_i")).get("condicoes", []):
+        code = condition["codigo"]
+        values = record(conditions.get(code))
+        detail = record(details.get(code))
+        if any(positivo(value) for value in [values.get("percentual_area"),
+                values.get("percentual_area_considerada"), values.get("percentual_area_bruta"),
+                detail.get("percentual_area_informado")]):
+            add(condition.get("rotulo"))
+    selected("art_88_ii", record(config.get("art_88_ii")).get("selecionados",
+             record(redutores.get("art_88")).get("selecionados_inciso_ii_informados", [])))
+    selected("art_60_61", record(config.get("art_60_61")).get("selecionados",
+             record(redutores.get("art_60_61")).get("selecionados", [])))
+    topography = record(config.get("topografia")) or record(redutores.get("topografia"))
+    for key in ("relevo", "nivel_rua"):
+        selected("topografia", [topography.get(key)], key)
+    water = record(config.get("agua")) or record(redutores.get("agua"))
+    selected("agua", [water.get("situacao")])
+    apan = record(config.get("apan")) or record(redutores.get("apan"))
+    if positivo(apan.get("percentual_area")):
+        add("APAN")
+    return list(reasons.values())
+
+
+def sugestoes_documentais(rows, kind):
+    reasons = {}
+    for row in rows:
+        for reason in row.get("motivos_desvalorizantes", []):
+            key = reason["descricao"].casefold()
+            previous = reasons.get(key, {})
+            reasons[key] = {**reason, "alegado": reason["alegado"] or previous.get("alegado", False),
+                           "confirmado": reason["confirmado"] or previous.get("confirmado", False)}
+    return {
+        "motivos_desvalorizantes": list(reasons.values()),
+        "metodo_avaliacao": METODO_EVOLUTIVO if kind == "evolutivo" else METODO_COMPARATIVO,
+        "modelo_avaliacao": ", ".join(dict.fromkeys(row["modelo"] for row in rows if row["modelo"])),
+    }

backend/app/main.py

@@ -10,6 +10,9 @@ from fastapi.staticfiles import StaticFiles
 from pydantic import ValidationError
 
 from config.settings import OUTPUT_DIR
+from models.hf_repository import ModelRepositoryError
+
+from .avaliacoes_import import MAX_FILE_BYTES, parse_export
 
 from .runtime import CORS_ORIGINS, FRONTEND_DIST_DIR, HOST, PORT
 from .schemas import (
@@ -44,6 +47,11 @@ if CORS_ORIGINS:
     )
 
 
+@app.exception_handler(ModelRepositoryError)
+async def model_repository_error(request, exc):
+    return JSONResponse(status_code=503, content={'detail': str(exc)})
+
+
 @app.get("/api/health")
 def health() -> dict:
     return {"status": "ok"}
@@ -64,6 +72,8 @@ def models() -> dict:
 def model_columns(modelo_nome: str) -> dict:
     try:
         return get_model_columns_payload(modelo_nome)
+    except ModelRepositoryError:
+        raise
     except ValueError as exc:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
     except Exception as exc:
@@ -93,10 +103,19 @@ def market_values_generate(payload: MarketValuesRangeRequest) -> dict:
         raise HTTPException(status_code=400, detail=f"Intervalo de anos inválido: {exc}") from exc
 
 
+@app.post("/api/avaliacoes/importar")
+async def avaliacoes_importar(arquivo: UploadFile = File(...)) -> dict:
+    try:
+        return parse_export(await arquivo.read(MAX_FILE_BYTES + 1), arquivo.filename or "")
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
 @app.post("/api/laudos/generate", response_model=LaudoGenerateResponse)
 async def laudos_generate(
     payload: str = Form(...),
     registro_fotografico: UploadFile | None = File(default=None),
+    arquivo_avaliacoes: UploadFile | None = File(default=None),
 ) -> dict:
     try:
         payload_obj = LaudoFormInput.model_validate_json(payload)
@@ -111,7 +130,9 @@ async def laudos_generate(
             )
 
     try:
-        output_path = generate_laudo_document(payload_obj, registro_fotografico)
+        output_path = generate_laudo_document(payload_obj, registro_fotografico, arquivo_avaliacoes)
+    except ModelRepositoryError:
+        raise
     except ValueError as exc:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
     except Exception as exc:

backend/app/schemas.py

@@ -17,7 +17,33 @@ class ValorMercadoInput(BaseModel):
     valor: str = ""
 
 
+class ComplementosAvaliacaoInput(BaseModel):
+    justificativa_vu: str = ""
+    justificativa_area: str = ""
+    justificativa_fc: str = ""
+    ajustes_nao_aplicados: str = ""
+    criterio_adocao: str = ""
+    bdi: dict[str, str] = Field(default_factory=dict)
+    caracterizacao_grau: str = ""
+    caracterizacao_justificativa: str = ""
+    identificacao_grau: str = ""
+    identificacao_justificativa: str = ""
+    requisitos_grau_iii: dict[str, str | bool] = Field(default_factory=dict)
+    fc_criterio: str = ""
+
+
+class ImportacaoAvaliacoesInput(BaseModel):
+    referencia_anos: str = "ano_base"
+    anos: dict[str, str] = Field(default_factory=dict)
+    objeto_modelo: str = "Objeto avaliado por modelo"
+    valores_adotados: dict[str, str] = Field(default_factory=dict)
+    campos_editados: List[str] = Field(default_factory=list)
+    complementos: dict[str, ComplementosAvaliacaoInput] = Field(default_factory=dict)
+
+
 class LaudoFormInput(BaseModel):
+    importacao_avaliacoes: Optional[ImportacaoAvaliacoesInput] = None
+
     numero_laudo: str = ""
     numero_processo: str = ""
     data_laudo: str = ""

backend/app/services.py

@@ -1,6 +1,7 @@
 """Serviços de negócio do backend."""
 from __future__ import annotations
 
+from collections import Counter
 from datetime import datetime
 from pathlib import Path
 from tempfile import NamedTemporaryFile
@@ -14,6 +15,8 @@ from config.constants import (
     MAX_MOTIVOS_DESVALORIZANTES,
     MAX_VALORES_MERCADO,
     METODOS_AVALIACAO,
+    METODO_COMPARATIVO,
+    METODO_EVOLUTIVO,
     TECNICOS_RESPONSAVEIS,
     TIPOS_REQUERIMENTO,
     UNIDADES_DEMANDANTES,
@@ -29,6 +32,7 @@ from utils.formatters import (
     formatar_valores_mercado_para_documento,
 )
 
+from .avaliacoes_import import MAX_FILE_BYTES, parse_export, resolve_import
 from .runtime import DEFAULT_FILL_DUMMY, ENABLE_DUMMY_DATA
 from .schemas import LaudoFormInput
 
@@ -236,6 +240,7 @@ def _normalizar_lista_strings(values: List[str]) -> List[str]:
 def _build_generator_payload(
     payload: LaudoFormInput,
     registro_fotografico_path: str | None,
+    importacao: dict | None = None,
 ) -> Tuple[Dict[str, Any], Dict[str, Any]]:
     valor_formatado, valor_extenso = formatar_valor_monetario(payload.valor_proposto)
     valor_proposto_completo = (
@@ -271,7 +276,7 @@ def _build_generator_payload(
 
     colunas_banco_dados = (
         _validar_colunas_banco_dados(payload.modelo_avaliacao, payload.banco_dados_colunas)
-        if payload.banco_dados_colunas is not None
+        if payload.banco_dados_colunas is not None and importacao is None
         else []
     )
 
@@ -322,12 +327,36 @@ def _build_generator_payload(
         "registro_fotografico_path": registro_fotografico_path,
     }
 
+    if importacao:
+        rows = importacao['avaliacoes']
+        models = list(dict.fromkeys(row['modelo'] for row in rows if row['modelo']))
+        dados['avaliacoes_importadas'] = importacao
+        dados['modelo_avaliacao'] = ', '.join(models)
+        dados['metodo_avaliacao'] = METODO_EVOLUTIVO if importacao['tipo'] == 'evolutivo' else METODO_COMPARATIVO
+        dados['datas_referencia'] = ', '.join(dict.fromkeys(
+            f"Dezembro/{row['ano_base']}" for row in rows))
+        dados['valores_mercado_lista'] = []
+        exercicios = Counter(row['ano'] for row in rows)
+        anos = [row['ano'] if exercicios[row['ano']] == 1
+                else f"{row['ano']} ({row['titulo_origem']})" for row in rows]
+        valores = [formatar_valor_monetario(row['valor_total'].replace('.', ','))[0]
+                   for row in rows]
+        dados['valores_mercado'] = formatar_valores_mercado_para_documento(anos, valores)
+        # Apenas as alterações explícitas da revisão substituem os metadados
+        # documentais. O modelo e os resultados de origem continuam no arquivo.
+        for campo in ('metodo_avaliacao', 'modelo_avaliacao', 'datas_referencia'):
+            if payload.importacao_avaliacoes and campo in payload.importacao_avaliacoes.campos_editados:
+                revisado = _resolver_dropdown(payload.metodo_avaliacao, payload.metodo_avaliacao_custom) if campo == 'metodo_avaliacao' else getattr(payload, campo)
+                if campo != 'metodo_avaliacao' or revisado not in ('Método evolutivo', 'Método comparativo direto de dados de mercado por modelo estatístico'):
+                    dados[campo] = revisado
+
     return dados, motivos_formatados
 
 
 def generate_laudo_document(
     payload: LaudoFormInput,
     registro_fotografico: UploadFile | None,
+    arquivo_avaliacoes: UploadFile | None = None,
 ) -> Path:
     temp_registro_path: str | None = None
     try:
@@ -338,7 +367,16 @@ def generate_laudo_document(
                 temp_file.write(registro_fotografico.file.read())
                 temp_registro_path = temp_file.name
 
-        dados, motivos_formatados = _build_generator_payload(payload, temp_registro_path)
+        importacao = None
+        if arquivo_avaliacoes and arquivo_avaliacoes.filename:
+            if payload.importacao_avaliacoes is None:
+                raise ValueError('Informe a correspondência dos anos da avaliação importada.')
+            arquivo_avaliacoes.file.seek(0)
+            parsed = parse_export(arquivo_avaliacoes.file.read(MAX_FILE_BYTES + 1), arquivo_avaliacoes.filename)
+            importacao = resolve_import(parsed, payload.importacao_avaliacoes)
+        elif payload.importacao_avaliacoes is not None:
+            raise ValueError('Envie o arquivo .ame ou .evo da avaliação.')
+        dados, motivos_formatados = _build_generator_payload(payload, temp_registro_path, importacao)
         output_path = LaudoGenerator().gerar(dados, motivos_formatados)
 
         if output_path is None:

config/constants.py

@@ -50,6 +50,9 @@ METODOS_AVALIACAO = [
 
 # --- Textos padrão ---
 
+METODO_COMPARATIVO = "Método Comparativo Dados de Mercado - ABNT NBR 14.653-2"
+METODO_EVOLUTIVO = METODO_COMPARATIVO + " e Método de Quantificação de Custo"
+
 TEXTO_OBSERVACOES_COMPLEMENTARES = """- Pressupõe-se que todas as informações fornecidas por terceiros merecem credibilidade;
 
 - Considerou-se que os documentos e/ou títulos de propriedade do avaliando espelham a realidade;

config/mesa_documentacao.json

@@ -0,0 +1,818 @@
+{
+  "versao": 1,
+  "fontes": {
+    "frontend/src/mqc/data/referenceData.js": "b57ca605c1505d28d895142704b81893d369ee67fca702d7a042e9aa74310616",
+    "frontend/src/mqc/wordExportOptions.js": "66210e6d0d8f99b776551050890f4e7159f37eb2fa916341f6d21bff93f09e71",
+    "frontend/src/components/NormativeReference.jsx": "8fe15de448046093efa83ea3c1f8fc7a0f4147c8d3f95eaef52af0882338b4f5",
+    "frontend/src/components/RedutoresAvaliacaoModal.jsx": "40f2a918ccdf5282f13e7e25e4141e6153e2d60eb670dda8733b1572d790454c",
+    "frontend/src/mqc/calculations.js": "ab4cabf7243e4cf52ace67e2280545b399b465d9ed7104ed989d31ad08839e4e",
+    "frontend/src/modelFoundation.js": "69e8893a8506c6c7c33277a5183c8f22369318cd10e512799ee3ac2bef1c187a",
+    "frontend/src/globalFoundation.js": "24b630bce2a805e8506b714d627d7cdddd7aa4c3b0d34978496e3b3d52fb6972",
+    "frontend/src/mqc/exporters.js": "467251f8372625f54980f8424184eb250ec65c724936cad9f9567f925658cfbf"
+  },
+  "notas": {
+    "sequence": "Const.: número da sequência construtiva.",
+    "year": "Ano (base): ano de construção.",
+    "cubGroup": "CUB (R$ / m²): grupo dos dados relacionados ao custo unitário básico por metro quadrado.",
+    "cubType": "CUB: tipo ou composição de CUB adotada.",
+    "cubValue": "CUB (R$): valor do CUB por metro quadrado na DataCUB; quando houver ponderação, uma anotação específica apresenta sua composição.",
+    "cubPercent": "% do CUB: percentual aplicado ao valor do CUB.",
+    "unitCost": "CUNIT: custo unitário após a aplicação do percentual do CUB.",
+    "bdi": "BDI (%): percentual de benefícios e despesas indiretas.",
+    "conservation": "Est. Cons.: estado de conservação adotado, identificado pelo respectivo código.",
+    "depreciation": "Depr. (K): coeficiente de depreciação calculado pelo método de Ross-Heidecke.",
+    "residual": "R (%): valor residual percentual.",
+    "kd": "kd: fator de depreciação com consideração do valor residual.",
+    "constructionValue": "Valor Construção (R$): valor final depreciado da sequência construtiva."
+  },
+  "notas_area": [
+    "Área eq. (m²): área utilizada no cálculo após ponderação das áreas reais pelos respectivos coeficientes de equivalência. Os coeficientes representam quanto cada tipo de área contribui, em custo, em relação à área padrão da construção.",
+    "Área (m²): área da construção considerada diretamente no cálculo da sequência construtiva."
+  ],
+  "referencias": {
+    "bdiAdicionais": [
+      {
+        "item": "a)",
+        "descricao": "projetos detalhados e especificacoes (5% a 10%)",
+        "perc1": 0.05,
+        "perc2": 0.05,
+        "perc3": 0.05,
+        "escolha": 0.05
+      },
+      {
+        "item": "b)",
+        "descricao": "copias, licenca da obra, agua, luz e forca (1,5% a 3%)",
+        "perc1": 0.03,
+        "perc2": 0.015,
+        "perc3": 0.03,
+        "escolha": 0.03
+      },
+      {
+        "item": "c)",
+        "descricao": "adm. local - mestre, apontador geral e engenheiro de obras (3% a 7%)",
+        "perc1": 0.05,
+        "perc2": 0.03,
+        "perc3": 0.05,
+        "escolha": 0.05
+      },
+      {
+        "item": "d)",
+        "descricao": "escritorio - pessoal, material, despesas de locacao ou amortizacao (4% a 8%)",
+        "perc1": 0.04,
+        "perc2": 0.04,
+        "perc3": 0.04,
+        "escolha": 0.04
+      },
+      {
+        "item": "e)",
+        "descricao": "eventuais, para atender omissoes de orcamento e elevacoes de precos nao previstos (minimo)",
+        "perc1": 0.05,
+        "perc2": 0.05,
+        "perc3": 0.05,
+        "escolha": 0.05
+      },
+      {
+        "item": "f)",
+        "descricao": "administracao central, lucro da firma construtora e custos financeiros, oscilando entre 10% e 25% conforme condicoes de servico da mesma e de mercado",
+        "perc1": null,
+        "perc2": 0.1,
+        "perc3": 0.1,
+        "escolha": 0.1
+      }
+    ],
+    "bdiTiposConstrucao": [
+      {
+        "tipo": "TELHEIRO SIMPLES (SEM BDI)",
+        "bdi": "0%"
+      },
+      {
+        "tipo": "TELHEIRO MEDIO (5%)",
+        "bdi": "5%"
+      },
+      {
+        "tipo": "TELHEIRO ALUMINIO (12%)",
+        "bdi": "12%"
+      },
+      {
+        "tipo": "MADEIRA SIMPLES (SEM BDI)",
+        "bdi": "0%"
+      },
+      {
+        "tipo": "MADEIRA MEDIA (5%)",
+        "bdi": "5%"
+      },
+      {
+        "tipo": "MADEIRA SUPERIOR (10%)",
+        "bdi": "10%"
+      },
+      {
+        "tipo": "MISTA SIMPLES (SEM BDI)",
+        "bdi": "0%"
+      },
+      {
+        "tipo": "MISTA MEDIA (5%)",
+        "bdi": "5%"
+      },
+      {
+        "tipo": "MISTA SUPERIOR (10%)",
+        "bdi": "10%"
+      },
+      {
+        "tipo": "ALVENARIA PRECARIA (SEM BDI)",
+        "bdi": "0%"
+      },
+      {
+        "tipo": "ALVENARIA POPULAR (8%)",
+        "bdi": "8 - 10%"
+      },
+      {
+        "tipo": "ALVENARIA POPULAR (10%)",
+        "bdi": "8 - 10%"
+      },
+      {
+        "tipo": "ALVENARIA MEDIA",
+        "bdi": "12 - 25%"
+      },
+      {
+        "tipo": "ALVENARIA FINA",
+        "bdi": "25 - 32%"
+      },
+      {
+        "tipo": "ALVENARIA LUXO",
+        "bdi": "32 - 35%"
+      },
+      {
+        "tipo": "PAVILHAO ALVENARIA POPULAR",
+        "bdi": "5%"
+      },
+      {
+        "tipo": "PAVILHAO ALVENARIA MEDIA",
+        "bdi": "10 - 12%"
+      }
+    ],
+    "estadosConservacao": [
+      {
+        "estado": "A - novo",
+        "coeficiente": 0,
+        "descricao": "Com ate seis meses de uso e sem danos. Nao sofreu nem necessita de reparos. Edificacao nova ou com reforma geral e substancial, com menos de 02 anos, que apresente apenas sinais de desgaste natural da pintura externa."
+      },
+      {
+        "estado": "B - entre novo e regular",
+        "coeficiente": 0.0032,
+        "descricao": "Apesar de ja submetido ao uso, apresenta-se nas condicoes de novo ou bem proximo disso. Nao recebeu e nem necessita de reparos. Edificacao nova ou com reforma geral e substancial, com menos de 02 anos, que apresente necessidade apenas de uma demao leve de pintura para recompor a sua aparencia."
+      },
+      {
+        "estado": "C - regular",
+        "coeficiente": 0.0252,
+        "descricao": "Requer ou recebeu reparos pequenos. Quando o objeto do servico de recuperacao ou de restauracao recente deixou o imovel em condicoes proximas ao de novo. Quando da existencia de atividade de manutencao permanente e eficiente que mantem a aparencia e/ou uso em condicoes de novo; requer apenas limpeza sem utilizacao de mao de obra especializada para manter em boas condicoes de uso/aparencia. Edificacao semi-nova ou com reforma geral e substancial entre 02 e 05 anos, cujo estado geral possa ser recuperado apenas com reparos de eventuais fissuras superficiais localizadas e/ou pintura externa e interna."
+      },
+      {
+        "estado": "D - entre regular e reparos simples",
+        "coeficiente": 0.0809,
+        "descricao": "Atividade de manutencao eventual ou periodica que mantem uma boa aparencia e condicoes normais de uso, mas sem o aspecto de novo ou recuperacao recente. Requer intervencoes superficiais em pontos localizados para recuperacao de desgastes naturais. Pode requerer mao de obra especializada com uso de instrumentos especiais. Edificacao semi-nova ou com reforma geral e substancial entre 02 e 05 anos, cujo estado geral possa ser recuperado com reparo de fissuras localizadas e superficiais e pintura externa e interna."
+      },
+      {
+        "estado": "E - reparos simples",
+        "coeficiente": 0.181,
+        "descricao": "Requer reparacoes simples como intervencoes em pontos localizados ou em partes/componentes definidos para restauracao de aspectos e/ou funcionalidades originais. Necessitam de servicos generalizados de manutencao e limpeza. Implicam a realizacao de servicos superficiais ou reparos de partes ou componentes definidos/localizados com mao de obra especializada. Nao comprometem a operacao e a funcionalidade. Edificacao cujo estado geral possa ser recuperado com pintura interna e externa, apos reparos de fissuras superficiais generalizadas, sem recuperacao do sistema estrutural. Eventualmente, revisao do sistema hidraulico e eletrico."
+      },
+      {
+        "estado": "F - entre reparos simples e importantes",
+        "coeficiente": 0.332,
+        "descricao": "Requer intervencoes generalizadas na maior parte, ou com profundidade, em pecas ou componentes especificos sob pena de comprometimento iminente de operacao e seguranca. Implica restauracao ou recuperacao com remocao/substituicao/adicao de elementos ou pecas com mao de obra especializada. Edificacao cujo estado geral possa ser recuperado com pintura interna e externa, apos reparos de fissuras, e com estabilizacao e/ou recuperacao localizada do sistema estrutural. As instalacoes hidraulicas e eletricas possam ser restauradas mediante a revisao e com substituicao eventual de algumas pecas desgastadas naturalmente. Eventualmente possa ser necessaria a substituicao dos revestimentos de pisos e paredes, de um, ou de outro compartimento. Revisao da impermeabilizacao ou substituicao de telhas da cobertura."
+      },
+      {
+        "estado": "G - reparos importantes",
+        "coeficiente": 0.526,
+        "descricao": "Requer intervencoes generalizadas e com profundidade em partes ou pecas criticas sob o aspecto de estetica, salubridade, seguranca e funcionalidade. Implica restauracao ou recuperacao com remocao/substituicao/adicao de elementos ou pecas com mao de obra especializada. Edificacao cujo estado geral possa ser recuperado com pintura interna e externa, com substituicao de parametros de regularizacao da alvenaria, reparos de fissuras, com estabilizacao e/ou recuperacao de grande parte do sistema estrutural. As instalacoes hidraulicas e eletricas possam ser restauradas mediante a substituicao das pecas aparentes. A substituicao dos revestimentos de pisos e paredes, da maioria dos compartimentos. Substituicao ou reparacoes importantes na impermeabilizacao ou no telhado."
+      },
+      {
+        "estado": "H - entre reparos importantes e sem valor",
+        "coeficiente": 0.752,
+        "descricao": "Restauracao total de elementos ou pecas importantes. Degradacao generalizada e com alto grau de exposicao. Alto nivel de comprometimento da funcionalidade, seguranca e operacao. Edificacao cujo estado geral possa ser recuperado com estabilizacao e/ou recuperacao do sistema estrutural, substituicao da regularizacao da alvenaria, reparos de fissuras. Substituicao das instalacoes hidraulicas e eletricas. Substituicao dos revestimentos de pisos e paredes. Substituicao da impermeabilizacao ou do telhado."
+      },
+      {
+        "estado": "I - sem valor",
+        "coeficiente": 1
+      }
+    ],
+    "vidaUtilTipos": [
+      {
+        "tipo": "APARTAMENTOS",
+        "vidaUtil": 60
+      },
+      {
+        "tipo": "BANCOS",
+        "vidaUtil": 70
+      },
+      {
+        "tipo": "CASAS DE ALVENARIA",
+        "vidaUtil": 65
+      },
+      {
+        "tipo": "CASAS DE MADEIRA",
+        "vidaUtil": 45
+      },
+      {
+        "tipo": "HOTEIS",
+        "vidaUtil": 50
+      },
+      {
+        "tipo": "LOJAS",
+        "vidaUtil": 70
+      },
+      {
+        "tipo": "TEATROS",
+        "vidaUtil": 50
+      },
+      {
+        "tipo": "ARMAZENS",
+        "vidaUtil": 75
+      },
+      {
+        "tipo": "FABRICAS",
+        "vidaUtil": 50
+      },
+      {
+        "tipo": "CONST. RURAIS",
+        "vidaUtil": 60
+      },
+      {
+        "tipo": "GARAGENS",
+        "vidaUtil": 60
+      },
+      {
+        "tipo": "EDIFICIOS DE ESCRITORIOS",
+        "vidaUtil": 70
+      },
+      {
+        "tipo": "GALPOES (DEPOSITOS)",
+        "vidaUtil": 70
+      },
+      {
+        "tipo": "SILOS",
+        "vidaUtil": 75
+      }
+    ],
+    "valorResidualReferencias": [
+      {
+        "classe": "Residencial",
+        "tipo": "Barraco",
+        "padrao": "Rústico",
+        "vidaReferencialIr": 5,
+        "valorResidual": 0
+      },
+      {
+        "classe": "Residencial",
+        "tipo": "Barraco",
+        "padrao": "Simples",
+        "vidaReferencialIr": 10,
+        "valorResidual": 0
+      },
+      {
+        "classe": "Residencial",
+        "tipo": "Casa",
+        "padrao": "Rústico",
+        "vidaReferencialIr": 60,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Residencial",
+        "tipo": "Casa",
+        "padrao": "Proletário",
+        "vidaReferencialIr": 60,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Residencial",
+        "tipo": "Casa",
+        "padrao": "Econômico",
+        "vidaReferencialIr": 70,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Residencial",
+        "tipo": "Casa",
+        "padrao": "Simples",
+        "vidaReferencialIr": 70,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Residencial",
+        "tipo": "Casa",
+        "padrao": "Médio",
+        "vidaReferencialIr": 70,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Residencial",
+        "tipo": "Casa",
+        "padrao": "Superior",
+        "vidaReferencialIr": 70,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Residencial",
+        "tipo": "Casa",
+        "padrao": "Fino",
+        "vidaReferencialIr": 60,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Residencial",
+        "tipo": "Casa",
+        "padrao": "Luxo",
+        "vidaReferencialIr": 60,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Residencial",
+        "tipo": "Apartamento",
+        "padrao": "Econômico",
+        "vidaReferencialIr": 60,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Residencial",
+        "tipo": "Apartamento",
+        "padrao": "Simples",
+        "vidaReferencialIr": 60,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Residencial",
+        "tipo": "Apartamento",
+        "padrao": "Médio",
+        "vidaReferencialIr": 60,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Residencial",
+        "tipo": "Apartamento",
+        "padrao": "Superior",
+        "vidaReferencialIr": 60,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Residencial",
+        "tipo": "Apartamento",
+        "padrao": "Fino",
+        "vidaReferencialIr": 50,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Residencial",
+        "tipo": "Apartamento",
+        "padrao": "Luxo",
+        "vidaReferencialIr": 50,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Comercial",
+        "tipo": "Escritório",
+        "padrao": "Econômico",
+        "vidaReferencialIr": 70,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Comercial",
+        "tipo": "Escritório",
+        "padrao": "Simples",
+        "vidaReferencialIr": 70,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Comercial",
+        "tipo": "Escritório",
+        "padrao": "Médio",
+        "vidaReferencialIr": 60,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Comercial",
+        "tipo": "Escritório",
+        "padrao": "Superior",
+        "vidaReferencialIr": 60,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Comercial",
+        "tipo": "Escritório",
+        "padrao": "Fino",
+        "vidaReferencialIr": 50,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Comercial",
+        "tipo": "Escritório",
+        "padrao": "Luxo",
+        "vidaReferencialIr": 50,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Comercial",
+        "tipo": "Galpões",
+        "padrao": "Rústico",
+        "vidaReferencialIr": 60,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Comercial",
+        "tipo": "Galpões",
+        "padrao": "Simples",
+        "vidaReferencialIr": 60,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Comercial",
+        "tipo": "Galpões",
+        "padrao": "Médio",
+        "vidaReferencialIr": 80,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Comercial",
+        "tipo": "Galpões",
+        "padrao": "Superior",
+        "vidaReferencialIr": 80,
+        "valorResidual": 20
+      },
+      {
+        "classe": "Comercial",
+        "tipo": "Coberturas",
+        "padrao": "Rústico",
+        "vidaReferencialIr": 20,
+        "valorResidual": 10
+      },
+      {
+        "classe": "Comercial",
+        "tipo": "Coberturas",
+        "padrao": "Simples",
+        "vidaReferencialIr": 20,
+        "valorResidual": 10
+      },
+      {
+        "classe": "Comercial",
+        "tipo": "Coberturas",
+        "padrao": "Superior",
+        "vidaReferencialIr": 30,
+        "valorResidual": 10
+      }
+    ],
+    "areaEquivalenteCoeficientes": [
+      {
+        "item": "a",
+        "descricao": "garagem (subsolo)",
+        "coeficiente": "0,50 a 0,75"
+      },
+      {
+        "item": "b",
+        "descricao": "área privativa (unidade autônoma padrão)",
+        "coeficiente": "1,00"
+      },
+      {
+        "item": "c",
+        "descricao": "área privativa (salas com acabamento)",
+        "coeficiente": "1,00"
+      },
+      {
+        "item": "d",
+        "descricao": "área privativa (salas sem acabamento)",
+        "coeficiente": "0,75 a 0,90"
+      },
+      {
+        "item": "e",
+        "descricao": "área de loja sem acabamento",
+        "coeficiente": "0,40 a 0,60"
+      },
+      {
+        "item": "f",
+        "descricao": "varandas",
+        "coeficiente": "0,75 a 1,00"
+      },
+      {
+        "item": "g",
+        "descricao": "terraços ou áreas descobertas sobre lajes",
+        "coeficiente": "0,30 a 0,60"
+      },
+      {
+        "item": "h",
+        "descricao": "estacionamento sobre terreno",
+        "coeficiente": "0,05 a 0,10"
+      },
+      {
+        "item": "i",
+        "descricao": "área de projeção do terreno sem benfeitoria",
+        "coeficiente": "0,00"
+      },
+      {
+        "item": "j",
+        "descricao": "área de serviço - residência unifamiliar padrão baixo",
+        "coeficiente": "0,5"
+      },
+      {
+        "item": "k",
+        "descricao": "barrilete",
+        "coeficiente": "0,50 a 0,75"
+      },
+      {
+        "item": "l",
+        "descricao": "caixa d'água",
+        "coeficiente": "0,50 a 0,75"
+      },
+      {
+        "item": "m",
+        "descricao": "casa de máquinas",
+        "coeficiente": "0,50 a 0,75"
+      },
+      {
+        "item": "n",
+        "descricao": "piscinas",
+        "coeficiente": "0,50 a 0,75"
+      },
+      {
+        "item": "o",
+        "descricao": "quintais, calçadas, jardins, etc.",
+        "coeficiente": "0,10 a 0,30"
+      }
+    ],
+    "siglasCub": [
+      {
+        "sigla": "R1-B",
+        "descricao": "Residencia unifamiliar padrao baixo",
+        "dormitorios": 2,
+        "areaReal": 58.64,
+        "areaEquivalente": 51.94
+      },
+      {
+        "sigla": "R1-N",
+        "descricao": "Residencia unifamiliar padrao normal",
+        "dormitorios": 3,
+        "areaReal": 106.44,
+        "areaEquivalente": 99.47
+      },
+      {
+        "sigla": "R1-A",
+        "descricao": "Residencia unifamiliar padrao alto",
+        "dormitorios": 4,
+        "areaReal": 224.82,
+        "areaEquivalente": 210.44
+      },
+      {
+        "sigla": "RP1Q",
+        "descricao": "Residencia unifamiliar popular",
+        "dormitorios": 1,
+        "areaReal": 39.56,
+        "areaEquivalente": 39.56
+      },
+      {
+        "sigla": "PIS",
+        "descricao": "Residencia multifamiliar - projeto de interesse social",
+        "dormitorios": 2,
+        "areaReal": 991.45,
+        "areaEquivalente": 978.09
+      },
+      {
+        "sigla": "PP4-B",
+        "descricao": "Predio popular padrao baixo",
+        "dormitorios": 2,
+        "areaReal": 1415.07,
+        "areaEquivalente": 927.08
+      },
+      {
+        "sigla": "PP4-N",
+        "descricao": "Predio popular padrao normal",
+        "dormitorios": 3,
+        "areaReal": 2521.96,
+        "areaEquivalente": 1991.05
+      },
+      {
+        "sigla": "R8-N",
+        "descricao": "Residencia multifamiliar padrao normal",
+        "dormitorios": 3,
+        "areaReal": 5998.73,
+        "areaEquivalente": 5137.54
+      },
+      {
+        "sigla": "CAL8-N",
+        "descricao": "Comercial andares livres padrao normal",
+        "dormitorios": "-",
+        "areaReal": 5917.79,
+        "areaEquivalente": 5093.82
+      },
+      {
+        "sigla": "GI",
+        "descricao": "Galpao industrial",
+        "dormitorios": "-",
+        "areaReal": 1000,
+        "areaEquivalente": 1000
+      }
+    ]
+  },
+  "normas": {
+    "terreno": {
+      "title": "Fundamentação da avaliação do terreno",
+      "source": "ABNT NBR 14653-2:2011 - itens 9.2.1 e 9.2.1.6; Tabelas 1 e 2.",
+      "intro": "Aplicável ao modelo de regressão linear usado na estimativa do terreno. A seção 9 calcula os seis itens e usa a soma e as exigências mínimas da Tabela 2.",
+      "columns": [
+        "Critério",
+        "Grau III",
+        "Grau II",
+        "Grau I"
+      ],
+      "rows": [
+        [
+          "Caracterização",
+          "Completa para todas as variáveis analisadas",
+          "Completa para as variáveis do modelo",
+          "Situação paradigma"
+        ],
+        [
+          "Dados de mercado",
+          "Ao menos 6 × (k + 1)",
+          "Ao menos 4 × (k + 1)",
+          "Ao menos 3 × (k + 1)"
+        ],
+        [
+          "Identificação",
+          "Todos os dados e variáveis, com registros de campo",
+          "Todos os dados e variáveis analisados",
+          "Dados e variáveis efetivamente usados"
+        ],
+        [
+          "Extrapolação",
+          "Não admitida",
+          "Uma variável, dentro dos limites e impacto de até 15%",
+          "Dentro dos limites e impacto de até 20%"
+        ],
+        [
+          "Regressores",
+          "p-valor máximo de 10%",
+          "p-valor máximo de 20%",
+          "p-valor máximo de 30%"
+        ],
+        [
+          "Teste F",
+          "p-valor máximo de 1%",
+          "p-valor máximo de 2%",
+          "p-valor máximo de 5%"
+        ]
+      ],
+      "framing": "Enquadramento global do modelo: Grau III exige 16 pontos; Grau II, 10; Grau I, 6. Há também requisitos mínimos específicos por item. Para Grau III, a norma requer laudo completo, análise do modelo, endereços e fontes identificados e estimativa de tendência central."
+    },
+    "construcoes": {
+      "title": "Fundamentação da avaliação das construções",
+      "source": "ABNT NBR 14653-2:2011 - item 9.3; Tabelas 6 e 7.",
+      "intro": "Aplicável à estimativa dos custos de reedição pelo método da quantificação do custo. A seção 10 usa os três itens da Tabela 6.",
+      "columns": [
+        "Critério",
+        "Grau III",
+        "Grau II",
+        "Grau I"
+      ],
+      "rows": [
+        [
+          "Custo direto",
+          "Orçamento ao menos sintético",
+          "CUB de projeto semelhante ao padrão",
+          "CUB de projeto diferente, com ajustes"
+        ],
+        [
+          "BDI",
+          "Calculado",
+          "Justificado",
+          "Arbitrado"
+        ],
+        [
+          "Depreciação física",
+          "Levantamento do custo de recuperação ou bem novo/hipotético",
+          "Métodos técnicos, com idade, vida útil e conservação",
+          "Arbitrada"
+        ]
+      ],
+      "framing": "Enquadramento global do método: Grau III exige 7 pontos e custo direto no Grau III, com os demais no mínimo no Grau II; Grau II exige 5 pontos e os itens 1 e 2 no mínimo no Grau II; Grau I exige 3 pontos e todos no mínimo no Grau I. Grau III exige laudo na modalidade completa."
+    },
+    "global": {
+      "title": "Fundamentação global pelo método evolutivo",
+      "source": "ABNT NBR 14653-2:2011 - item 9.5; Tabelas 10 e 11.",
+      "intro": "A seção 11 reúne automaticamente os graus das avaliações de terreno e de construções e permite definir o critério do fator de comercialização.",
+      "columns": [
+        "Item",
+        "Grau III",
+        "Grau II",
+        "Grau I"
+      ],
+      "rows": [
+        [
+          "Valor do terreno",
+          "Grau III no método comparativo ou involutivo",
+          "Grau II no método comparativo ou involutivo",
+          "Grau I no método comparativo ou involutivo"
+        ],
+        [
+          "Custos de reedição",
+          "Grau III no método da quantificação do custo",
+          "Grau II no método da quantificação do custo",
+          "Grau I no método da quantificação do custo"
+        ],
+        [
+          "Fator de comercialização",
+          "Inferido em mercado semelhante",
+          "Justificado",
+          "Arbitrado"
+        ]
+      ],
+      "framing": "Enquadramento global: Grau III exige 8 pontos, itens 1 e 2 no Grau III e item 3 no mínimo no Grau II; Grau II exige 5 pontos e itens 1 e 2 no mínimo no Grau II; Grau I exige 3 pontos e todos no mínimo no Grau I. Quando o terreno ou as benfeitorias representam menos de 15% do valor total do imóvel, a norma admite dois pontos para o respectivo item. Grau III exige laudo na modalidade completa."
+    }
+  },
+  "redutores_termos": {
+    "VU central": "valor unitário estimado pelo modelo territorial antes de qualquer redutor ou campo de arbítrio",
+    "Área territorial": "área multiplicada pelo valor unitário para obter o valor territorial",
+    "Art. 88, inciso I — total": "soma das parcelas ponderadas válidas do inciso I; o fator é 1 menos essa redução",
+    "Art. 60 e 61 — aplicado": "maior redutor entre as condições selecionadas; o fator é 1 menos essa redução",
+    "Topografia — total": "soma dos redutores de relevo e desnível; o fator é 1 menos essa soma",
+    "Inundação — aplicado": "percentual da situação selecionada; o fator é 1 menos essa redução",
+    "Área atingida por APAN": "parcela territorial informada como APAN",
+    "APAN considerada no CA": "redução correspondente à faixa de APAN, que deve ser considerada pelo avaliador ao definir o fator final do campo de arbítrio",
+    "VU após redutores territoriais": "valor unitário que chega ao campo de arbítrio",
+    "Fator CA final escolhido": "fator definido pelo avaliador após considerar APAN, quando existente, e os demais fundamentos técnicos",
+    "VU após o CA": "valor unitário territorial adotado",
+    "Valor territorial": "resultado do VU após o CA multiplicado pela área",
+    "Valor das construções": "resultado trazido da avaliação MQC selecionada",
+    "Imóvel composto": "soma do terreno e das construções antes dos redutores de imóvel",
+    "Valor de referência do Art. 88": "valor do terreno com o CA somado às construções, antes dos incisos I e II",
+    "Redução do inciso I": "redutor territorial ponderado pelas áreas atingidas",
+    "Inciso II selecionado": "soma bruta das condições do inciso II antes da verificação do limite",
+    "Piso legal": "15% do valor de referência; o resultado combinado dos incisos não pode ficar abaixo deste valor",
+    "Resultado bruto dos incisos": "resultado que seria obtido antes de aplicar o limite de 85%",
+    "Redução total do imóvel": "percentual efetivamente aplicado do inciso II após a verificação do limite do Art. 88",
+    "Fator dos redutores do imóvel": "multiplicador equivalente a 1 menos a redução total do imóvel",
+    "Valor após redutores do imóvel": "base que seguirá para a aplicação final do FC",
+    "Base antes do FC": "valor do imóvel depois dos redutores de imóvel",
+    "FC": "fator de comercialização aplicado como última operação",
+    "Valor final": "resultado final da avaliação após todas as etapas"
+  },
+  "funcoes_mqc": {
+    "calcularDepreciacao": "function calcularDepreciacao(percentualVidaUtil, coefHeidecke) {\n  const q = toNumber(percentualVidaUtil) / 100\n  const curvaRoss = round(q / 2 + q ** 2 / 2, 6)\n  return round(1 - (1 - curvaRoss) * (1 - toNumber(coefHeidecke)), 4)\n}",
+    "calcularKd": "function calcularKd(valorResidual, depreciacao) {\n  const residual = toNumber(valorResidual)\n  return round(residual + (1 - toNumber(depreciacao)) * (1 - residual), 3)\n}",
+    "calcularEnquadramento": "function calcularEnquadramento(definitions = {}) {\n  const cust1 = definitions.formaCub === 'Elaboracao de orcamento, no minimo sintetico' ? 3 : definitions.formaCub === 'Utilizacao CUB para projeto semelhante ao projeto padrao' ? 2 : definitions.formaCub ? 1 : null\n  const cust2 = definitions.tipoBdi === 'Calculado' ? 3 : definitions.tipoBdi === 'Justificado' ? 2 : definitions.tipoBdi ? 1 : null\n  const cust3 = definitions.depreciacao === 'Por levantamento do custo de recuperacao do bem, para deixa-lo no estado de novo ou caso de bens novos ou projetos hipoteticos' ? 3 : definitions.depreciacao === 'Por metodos tecnicos consagrados, considerando-se idade, vida util e estado de conservacao' ? 2 : definitions.depreciacao ? 1 : null\n  const complete = [cust1, cust2, cust3].every((value) => value !== null)\n  const somaCusto = complete ? cust1 + cust2 + cust3 : 0\n  let enquadramento = complete ? 'Fora dos critérios' : 'Pendente'\n  if (complete && somaCusto >= 7 && cust1 === 3 && cust2 >= 2 && cust3 >= 2) enquadramento = 'Grau III'\n  else if (complete && somaCusto >= 5 && cust1 >= 2 && cust2 >= 2) enquadramento = 'Grau II'\n  else if (complete && somaCusto >= 3) enquadramento = 'Grau I'\n  return { cust1, cust2, cust3, somaCusto, enquadramento }\n}"
+  },
+  "anotacoes_mqc": {
+    "wordCubTypeExplanation": "function wordCubTypeExplanation(value) {\n  const text = String(value || '').trim()\n  const match = text.match(/^(.+?)\\s*\\((.+)\\)$/)\n  return match ? `CUB ${match[1].trim()}: ${match[2].trim()}.` : `CUB ${text || '-'}: tipo de CUB adotado.`\n}",
+    "wordMixExplanation": "function wordMixExplanation(item, composition) {\n  const components = composition.map((row) => (\n    `${wordNumber(row.peso, 2, 2)}% do CUB ${wordCubShortName(row.cubTipo)}, no valor de R$ ${wordNumber(row.valorCub, 2, 2)}/m²`\n  ))\n  return `CUB ponderado da Const. ${item.seq}: composição formada por ${wordNaturalList(components)}. Considerados esses pesos, a média ponderada adotada é de R$ ${wordNumber(item.valorCub, 2, 2)}/m².`\n}",
+    "wordLifeAdjustmentExplanation": "function wordLifeAdjustmentExplanation(item) {\n  const justification = String(item.percentualVidaUtilJustificativa || '').replace(/\\s+/g, ' ').trim()\n  const punctuation = /[.!?]$/.test(justification) ? '' : '.'\n  return `Coeficiente de depreciação da construção nº ${item.seq}: calculado considerando ${wordNumber(item.percentualVidaUtil, 0, 2)}% da vida útil transcorrida, em vez dos ${wordNumber(item.percentualVidaUtilPadrao, 0, 2)}% transcorridos que seriam obtidos automaticamente pela relação entre a idade e a vida útil da construção. O ajuste foi adotado pela seguinte razão: ${justification}${punctuation}`\n}"
+  },
+  "criterios_fc": [
+    {
+      "value": "mercado_semelhante",
+      "label": "Grau III - Inferido em mercado semelhante",
+      "grade": "Grau III",
+      "points": 3
+    },
+    {
+      "value": "justificado",
+      "label": "Grau II - Justificado",
+      "grade": "Grau II",
+      "points": 2
+    },
+    {
+      "value": "arbitrado",
+      "label": "Grau I - Arbitrado",
+      "grade": "Grau I",
+      "points": 1
+    }
+  ],
+  "descricoes_modelo": {
+    "caracterizacao": {
+      "Grau III": "Caracterização completa quanto a todas as variáveis analisadas.",
+      "Grau II": "Caracterização completa quanto às variáveis utilizadas no modelo.",
+      "Grau I": "Adoção de situação paradigma.",
+      "Sem enquadramento": "O critério não foi atendido."
+    },
+    "identificacaoDados": {
+      "Grau III": "Informações de todos os dados e variáveis analisados, com fotos e características observadas no local pelo autor do laudo.",
+      "Grau II": "Informações de todos os dados e variáveis analisados na modelagem.",
+      "Grau I": "Informações dos dados e variáveis efetivamente utilizados no modelo.",
+      "Sem enquadramento": "O critério não foi atendido."
+    }
+  },
+  "requisitos_modelo": [
+    {
+      "key": "laudoCompleto",
+      "label": "Apresentação do laudo na modalidade completa"
+    },
+    {
+      "key": "analiseModelo",
+      "label": "Análise do modelo no laudo, com coerência do comportamento das variáveis e suas elasticidades no ponto de estimação"
+    },
+    {
+      "key": "enderecosCompletos",
+      "label": "Identificação completa dos endereços dos dados de mercado e das fontes de informação"
+    },
+    {
+      "key": "estimativaCentral",
+      "label": "Adoção da estimativa central"
+    }
+  ],
+  "identificador": "0d96271df5c3c68e"
+}

config/mesa_redutores.json

@@ -0,0 +1,192 @@
+{
+  "origem": "mesa-frame/backend/app/core/redutores_territoriais.py",
+  "catalogo": {
+    "versao": "redutores_padrao_v5",
+    "campo_arbitrio": {
+      "minimo": 0.85,
+      "maximo": 1.15,
+      "padrao": 1.0
+    },
+    "limite_reducao_art_88": 0.85,
+    "art_88_i": {
+      "tipo": "terreno",
+      "limite_minimo_area": 0.1,
+      "condicoes": [
+        {
+          "codigo": "app",
+          "rotulo": "Área de Preservação Permanente",
+          "redutor": 0.7
+        },
+        {
+          "codigo": "diretriz_logradouro",
+          "rotulo": "Diretriz para implantação de logradouro público",
+          "redutor": 0.35
+        },
+        {
+          "codigo": "faixa_redes",
+          "rotulo": "Faixa não edificável para passagens de redes",
+          "redutor": 0.35
+        },
+        {
+          "codigo": "alta_tensao",
+          "rotulo": "Redes de alta tensão",
+          "redutor": 0.85
+        },
+        {
+          "codigo": "ocupacoes_irregulares",
+          "rotulo": "Ocupações irregulares",
+          "redutor": 0.6
+        }
+      ]
+    },
+    "art_88_ii": {
+      "tipo": "imovel",
+      "redutor_por_item": 0.15,
+      "limite_combinado_art_88": 0.85,
+      "condicoes": [
+        {
+          "codigo": "sem_agua",
+          "rotulo": "Sem disponibilidade do serviço público de água",
+          "redutor": 0.15
+        },
+        {
+          "codigo": "sem_luz",
+          "rotulo": "Sem disponibilidade do serviço público de luz",
+          "redutor": 0.15
+        },
+        {
+          "codigo": "sem_esgoto",
+          "rotulo": "Sem disponibilidade do serviço público de esgoto",
+          "redutor": 0.15
+        },
+        {
+          "codigo": "sem_pavimentacao",
+          "rotulo": "Logradouro público sem pavimentação",
+          "redutor": 0.15
+        }
+      ]
+    },
+    "art_60_61": {
+      "tipo": "terreno",
+      "condicoes": [
+        {
+          "codigo": "vila",
+          "rotulo": "Imóvel em vila",
+          "redutor": 0.3
+        },
+        {
+          "codigo": "encravado",
+          "rotulo": "Terreno encravado",
+          "redutor": 0.6
+        },
+        {
+          "codigo": "triangular_ate_1000",
+          "rotulo": "Terreno interno triangular de até 1.000 m²",
+          "redutor": 0.3
+        }
+      ]
+    },
+    "apan": {
+      "tipo": "terreno",
+      "faixas": [
+        {
+          "minimo": 0.0,
+          "maximo_exclusivo": 0.1,
+          "redutor": 0.0
+        },
+        {
+          "minimo": 0.1,
+          "maximo_exclusivo": 0.37,
+          "redutor": 0.05
+        },
+        {
+          "minimo": 0.37,
+          "maximo_exclusivo": 0.67,
+          "redutor": 0.1
+        },
+        {
+          "minimo": 0.67,
+          "maximo_exclusivo": null,
+          "redutor": 0.15
+        }
+      ]
+    },
+    "topografia": {
+      "tipo": "terreno",
+      "relevo": [
+        {
+          "codigo": "declive_ate_5",
+          "rotulo": "Declive até 5%",
+          "redutor": 0.05
+        },
+        {
+          "codigo": "declive_5_10",
+          "rotulo": "Declive de 5% até 10%",
+          "redutor": 0.1
+        },
+        {
+          "codigo": "declive_10_20",
+          "rotulo": "Declive de 10% até 20%",
+          "redutor": 0.2
+        },
+        {
+          "codigo": "declive_acima_20",
+          "rotulo": "Declive acima de 20%",
+          "redutor": 0.3
+        },
+        {
+          "codigo": "aclive_ate_10",
+          "rotulo": "Aclive até 10%",
+          "redutor": 0.05
+        },
+        {
+          "codigo": "aclive_ate_20",
+          "rotulo": "Aclive até 20%",
+          "redutor": 0.1
+        },
+        {
+          "codigo": "aclive_acima_20",
+          "rotulo": "Aclive acima de 20%",
+          "redutor": 0.15
+        }
+      ],
+      "nivel_rua": [
+        {
+          "codigo": "abaixo_1_2_5",
+          "rotulo": "Abaixo do nível da rua de 1,00 m até 2,50 m",
+          "redutor": 0.1
+        },
+        {
+          "codigo": "abaixo_2_5_4",
+          "rotulo": "Abaixo do nível da rua de 2,50 m até 4,00 m",
+          "redutor": 0.2
+        },
+        {
+          "codigo": "acima_2_4",
+          "rotulo": "Acima do nível da rua de 2,00 m até 4,00 m",
+          "redutor": 0.1
+        }
+      ]
+    },
+    "agua": {
+      "tipo": "terreno",
+      "condicoes": [
+        {
+          "codigo": "acesso_inundavel",
+          "rotulo": "Região inundável dificulta o acesso, sem atingir o terreno",
+          "redutor": 0.1
+        },
+        {
+          "codigo": "inundacao_periodica",
+          "rotulo": "Terreno atingido ou afetado periodicamente por inundação",
+          "redutor": 0.3
+        },
+        {
+          "codigo": "alagado_permanente",
+          "rotulo": "Terreno permanentemente alagado",
+          "redutor": 0.4
+        }
+      ]
+    }
+  }
+}

docs/plano-metodo-evolutivo.md

@@ -0,0 +1,221 @@
+# Plano da geração textual pelo método evolutivo
+
+Data: 20 de outubro de 2026.
+
+Estado: implementado em 20/10/2026. O corpo EVO, a preservação dos dados, o catálogo técnico compartilhado e incorporado nas novas exportações, a revisão de complementos, os enquadramentos, a conclusão e os anexos foram integrados. Validação inclui testes de equivalência com os algoritmos da MESA, importação e geração completa com arquivo real de quatro exercícios e três construções, navegação da revisão e inspeção do Word renderizado. Os itens abaixo registram o escopo e os critérios da implementação.
+
+Referência examinada: [LA 107/2025 — Belém Velho, Casa 17](/Users/guilhermesilberfarbcosta/Downloads/LA_107_2025_BELEM_VELHO_4139_CASA_17.pdf), com 60 páginas. Foram examinados o cabeçalho, a demonstração da avaliação nas páginas 9–17 e o Anexo IV nas páginas 44–45.
+
+## Objetivo e princípio de organização
+
+Organizar o corpo do laudo em metodologia geral, avaliação do terreno, avaliação das construções e composição do valor do imóvel. A demonstração técnica precisa aparecer no corpo do texto; os anexos conservam os dados, os resultados estatísticos e a memória detalhada que sustentam essa demonstração.
+
+Os exercícios devem ser apresentados em tabelas comparativas dentro de cada etapa, como no exemplo, evitando repetir toda a metodologia para cada ano. Havendo modelos, imóveis ou construções diferentes, agrupar por identidade efetiva e identificar as diferenças. Avaliações do mesmo exercício permanecem distintas.
+
+O gerador documentará os resultados salvos no MESA. Não recalculará o modelo estatístico, não substituirá o CUB histórico por uma série atual e não inventará justificativas técnicas.
+
+## Reaproveitamento obrigatório das explicações técnicas da MESA
+
+Requisito confirmado pelo usuário: as explicações de redutores, BDI, CUB, áreas equivalentes, depreciação, campo de arbítrio, Fc e fundamentação deverão aproveitar os conteúdos técnicos da própria MESA. O PDF orienta a organização do documento; os textos, termos, fórmulas, tabelas de referência e explicações de cálculo da MESA orientam seu conteúdo técnico.
+
+Esse reaproveitamento inclui a explicação do significado e da forma de aplicação de cada fator, além dos números finais. A adaptação para prosa de laudo poderá retirar instruções de interface e ajustar remissões, preservando o sentido técnico, as condições de aplicação, as unidades, as fontes e a sequência das operações.
+
+Fontes já identificadas no projeto `mesa-frame`, em `/Users/guilhermesilberfarbcosta/Downloads/mesa-frame`:
+
+| Tema | Fonte na MESA | Conteúdo a reaproveitar |
+| --- | --- | --- |
+| Redutores e campo de arbítrio | `frontend/src/components/RedutoresAvaliacaoModal.jsx` e `backend/app/core/redutores_territoriais.py` | Explicações das etapas, termos e fórmulas de `memoriaMatematica` e `memoriaCompleta`; catálogo e versão das regras; condições selecionadas, áreas atingidas, ponderações, limites, bases de incidência, ordem dos ajustes e justificativa do campo de arbítrio. |
+| BDI | `frontend/src/mqc/data/referenceData.js`, `frontend/src/mqc/wordExportOptions.js` e `frontend/src/mqc/exporters.js` | Definição do BDI, componentes de adicionais, referências por tipo construtivo, significado de percentual e multiplicador e notas documentais existentes. Usar a composição efetivamente registrada quando disponível, sem presumir que uma tabela de referência foi a composição adotada. |
+| CUB e CUB composto | `frontend/src/mqc/data/referenceData.js`, `frontend/src/mqc/wordExportOptions.js`, `frontend/src/mqc/exporters.js` e `frontend/src/mqc/calculations.js` | Descrição dos projetos padrão, DataCUB, percentual de adequação, CUNIT e explicações automáticas dos tipos e da média ponderada dos CUBs com seus pesos e valores. |
+| Áreas equivalentes | `frontend/src/mqc/data/referenceData.js`, `frontend/src/mqc/wordExportOptions.js` e `frontend/src/components/MqcEvaluationEditor.jsx` | Significado da área equivalente, tipos e coeficientes de equivalência e memória da composição da área efetivamente calculada. |
+| Depreciação e conservação | `frontend/src/mqc/data/referenceData.js`, `frontend/src/mqc/calculations.js`, `frontend/src/mqc/wordExportOptions.js` e `frontend/src/mqc/exporters.js` | Descrição dos estados de conservação, vida útil, Ross-Heidecke, K, residual e Kd; explicação dos ajustes manuais de percentual de vida e respectivas justificativas públicas. |
+| Fundamentação e Fc | `frontend/src/components/NormativeReference.jsx`, `frontend/src/modelFoundation.js`, `frontend/src/globalFoundation.js` e `frontend/src/evolutivo/exportPdf.js` | Textos de critérios, fontes normativas, descrições dos enquadramentos e explicações dos resultados por componente e do método evolutivo. |
+
+Na implementação, extrair os conteúdos hoje embutidos em componentes e exportadores para módulos ou catálogos serializáveis, compartilhados com a interface e com as exportações da MESA. O gerador consumirá esse conteúdo por um pacote documental versionado, preferencialmente preservado no `.evo`, ou por catálogo sincronizado com identificação de versão. Não manter cópias manuais independentes dos mesmos textos em JavaScript e Python.
+
+Priorizar os fundamentos e referências preservados com a avaliação. Quando um arquivo antigo não trouxer os textos, usar o catálogo compatível com a versão identificável e sinalizar a ausência dessa identificação quando necessário. A atualização de um texto ou regra da MESA não deverá alterar silenciosamente a explicação de um resultado histórico.
+
+Textos explicativos gerais não substituem a justificativa específica do avaliador para escolher um fator, um percentual de BDI ou um VU. Recuperar a justificativa já salva; solicitar complemento somente para a decisão particular que continuar sem fundamento. Respeitar as marcações de observação interna existentes na MESA, incluindo `percentualVidaUtilJustificativaInterna`: elas não autorizam publicar o texto no laudo.
+
+## O que o laudo de referência demonstra
+
+| Parte | Páginas | Estrutura e conteúdo observados |
+| --- | --- | --- |
+| Metodologia geral | 9 | Apresenta o método evolutivo e explica os métodos empregados para terreno e construções, com consideração final do fator de comercialização. |
+| Avaliação do terreno | 9–13 | Pesquisa e amostra, variáveis, equação e interpretação estatística; parâmetros do avaliando, campo de arbítrio, valor unitário adotado e justificativa; aplicação do valor unitário à área da unidade. |
+| Avaliação das construções | 14–15 | Método da quantificação de custo, CUB e sua referência temporal; equação e significado dos termos; características construtivas, BDI e sua justificativa, depreciação e tabela de cálculo por exercício. |
+| Composição do imóvel | 15–16 | Soma dos componentes, aplicação do Fc, tabela de resultados e justificativa do fator; explicação de uma redução não aplicada por já estar representada no modelo. |
+| Especificação | 16 | Métodos, graus de fundamentação por componente, precisão do terreno e explicações para os enquadramentos. |
+| Conclusão | 16–17 | Tratamento dos motivos desvalorizantes e valores finais adotados por exercício, com representação por extenso. |
+| Anexo de cálculo | 44–45 | Parâmetros e limites amostrais, intervalos de confiança, campo de arbítrio e valores territoriais. |
+
+Há duas distinções essenciais no exemplo:
+
+- A área usada para estimar o valor unitário é a da gleba; a área de aplicação do valor unitário é a da unidade autônoma, de 4.126,73 m². O gerador precisa documentar ambas e a razão de serem diferentes.
+- A tabela de composição apresenta valores calculados com centavos, enquanto a conclusão adota valores arredondados. Por exemplo, em 2022 aparecem R$ 741.299,90 na composição e R$ 740.000,00 na conclusão. São campos diferentes; o gerador não deve aplicar uma regra de arredondamento presumida.
+
+## Estrutura proposta para o corpo do laudo
+
+```text
+3 ANÁLISE DO VALOR DE MERCADO
+  3.1 Diagnóstico de mercado
+  3.2 Metodologia de avaliação
+      Definição do método evolutivo e dos métodos dos componentes
+  3.3 Avaliação do terreno
+      3.3.1 Aplicação do método comparativo
+          3.3.1.1 Variáveis
+          3.3.1.2 Equação e análise do modelo estatístico
+      3.3.2 Cálculo do valor do terreno
+          3.3.2.1 Parâmetros e valor estimado pelo modelo
+          3.3.2.2 Ajustes aplicados e valor territorial adotado
+          Condições de incidência e justificativas do VU e da área
+  3.4 Avaliação das construções
+      3.4.1 Aplicação do método da quantificação de custo
+          3.4.1.1 Características das construções e áreas
+          3.4.1.2 CUB, referência temporal e adequações
+          3.4.1.3 BDI e justificativa
+          3.4.1.4 Depreciação
+          3.4.1.5 Cálculo por construção e exercício
+  3.5 Avaliação do imóvel objeto
+      Composição dos componentes, ajustes e Fc
+      Tabela por exercício e justificativas
+4 ESPECIFICAÇÃO DA AVALIAÇÃO
+  Terreno, construções e enquadramento global
+5 CONCLUSÃO TÉCNICA
+  Motivos desvalorizantes
+  Valores adotados por exercício e por extenso
+  Observações e referências temporais
+```
+
+A separação do CUB em item próprio é uma proposta para tornar explícitos os dados existentes no MESA. A numeração será automática, inclusive no quarto nível, e as remissões usarão os números efetivamente gerados.
+
+## Conteúdo e tabelas de cada etapa
+
+### Terreno
+
+Reaproveitar os textos e o cadastro de variáveis já existentes, incluindo o tratamento do ano de referência das dicotômicas. Identificar o modelo, a amostra, o período dos dados, as variáveis, a equação e os diagnósticos disponíveis. Afirmações sobre aderência estatística devem decorrer dos resultados, sem frases fixas que assegurem normalidade, ausência de autocorrelação ou atendimento de critérios independentemente dos testes.
+
+Gerar um quadro comparativo com parâmetros, estimativas e intervalos por exercício e outro com os ajustes efetivamente aplicados, campo de arbítrio, VU adotado, áreas e valor territorial. As justificativas acompanham o quadro e são agrupadas quando iguais, mantendo a abrangência das diferenças entre referências.
+
+Preservar a diferença entre a referência anual da avaliação e o ano-base omitido na codificação das dicotômicas. Também distinguir estimativa central do modelo, limites de confiança, campo de arbítrio e valor adotado: não são resultados intercambiáveis.
+
+### Construções
+
+Explicar o custo de reedição e a equação, com unidades e convenção de percentuais coerentes com os dados salvos:
+
+```text
+CUNIT = CUB × percentual de adequação em forma decimal
+VC = área de cálculo × CUNIT × (1 + BDI em forma decimal) × Kd
+Kd = R + (1 − K) × (1 − R)
+```
+
+O BDI de 25% no cadastro corresponde ao multiplicador 1,25; a apresentação deve distinguir percentual e multiplicador. A notação de K, R e Kd deve permanecer consistente.
+
+Documentar, por construção, área real e equivalente quando aplicável, ano da construção, idade ou percentual de vida, vida útil, tipo construtivo, conservação, CUB, adequações e depreciação. Preservar as ponderações quando houver CUB composto e os ajustes manuais de vida útil com suas justificativas.
+
+Apresentar uma tabela de cálculo por construção com linhas por exercício e, havendo várias construções, um quadro de totais. Se a tabela ficar larga, separar características e memória de cálculo em tabelas legíveis. Não repetir automaticamente os 25% de BDI, o padrão R1-N ou o residual de 20% do exemplo.
+
+Usar o mês do CUB efetivamente registrado em `cubData`. O texto sobre CUB de novembro publicado em dezembro é próprio do exemplo e só deve ser reproduzido quando essa correspondência estiver demonstrada nos dados do trabalho.
+
+### Composição do imóvel
+
+Sem outros ajustes, apresentar a expressão do exemplo, `VI = (VT + VC) × Fc`. Quando houver ajustes, a expressão e as tabelas devem refletir a sequência salva em `resultadoComposicao.memoria`, incluindo ajustes unitários, territoriais, do imóvel e a aplicação final do Fc. Não resumir uma composição com redutores em uma fórmula que omita etapas.
+
+O quadro deve permitir acompanhar os componentes, os ajustes aplicados, a base antes do Fc, o fator e o resultado calculado. A justificativa do Fc precisa acompanhar o fator, por exercício ou em texto comum quando for a mesma. Identificar também os ajustes expressamente não aplicados e sua justificativa, quando informados pelo avaliador, para evitar dupla consideração do mesmo aspecto.
+
+### Especificação e conclusão
+
+Exibir os enquadramentos de terreno e construções, a precisão da avaliação territorial e o enquadramento global quando houver elementos para documentá-lo. Não atribuir a precisão da regressão ao imóvel inteiro. Preservar os critérios e justificativas, sem adotar os graus II/III do exemplo como padrão.
+
+Mostrar na conclusão o valor final adotado, com eventual diferença em relação ao calculado claramente identificada. Cabeçalho e conclusão devem usar o mesmo registro de valor adotado e a mesma referência temporal. A composição conservará o valor calculado.
+
+## Lacunas verificadas no código atual
+
+| Componente | Situação atual | Mudança planejada |
+| --- | --- | --- |
+| `backend/app/avaliacoes_import.py` | O importador EVO conserva totais e parte das informações, mas reduz o conjunto de dados de terreno, construções e composição. | Preservar os dados documentais necessários, de forma estruturada e validada, mantendo a origem de cada resultado. |
+| `document/generator.py` | A seção 3.2 recebe a metodologia do modelo e um parágrafo geral sobre o evolutivo. A seção 4 ainda contém um campo para preenchimento. | Encaminhar o caso evolutivo a um gerador próprio para as seções 3.2–3.5 e para a especificação. |
+| `document/anexos/metodologia.py` | A metodologia comparativa produz títulos no terceiro nível e pressupõe valor unitário no texto de abertura das variáveis. | Permitir reaproveitamento no bloco territorial, com quarto nível de títulos e descrição compatível com a natureza real do Y. |
+| `document/avaliacoes_importadas.py` | A conclusão EVO apresenta uma tabela de componentes e o Anexo IV concentra a demonstração por avaliação. | Separar quadro de composição e conclusão, trazendo a demonstração essencial para o corpo do laudo. |
+| `frontend/src/ImportacaoAvaliacoes.jsx` e schemas | A prévia permite corrigir anos, mas não possui campos próprios para os fundamentos documentais da avaliação evolutiva. | Acrescentar revisão dos dados e complementos técnicos vinculados ao ID de cada avaliação. |
+
+O `.evo` do MESA já conserva dados úteis em `terreno`, `construcao`, `resultadoComposicao` e `fundamentacaoGlobal`. A implementação deve primeiro preservar esses registros antes de acrescentar campos ao exportador.
+
+## Dados a preservar na importação
+
+| Bloco | Dados necessários |
+| --- | --- |
+| Identificação | ID estável, imóvel/unidade, exercício IPTU, ano e data de referência, modelo e identificação da versão disponível. |
+| Terreno | `areaModelo`, `areaAplicacao`, `parametrosAplicados`, parâmetros originais quando necessários para explicar mudanças, `valorUnitario`, resultados e intervalos da avaliação, configuração e justificativa do campo de arbítrio, contexto e fundamentação do modelo. |
+| Construções | `cubData`, `anoReferencia`, referências de cálculo, `fundamentacaoMqc`, sequências com área e suas equivalências, CUB simples/composto, `percentualCub`, `custoUnitario`, `bdi`, ano de construção, conservação, vida útil, percentuais de vida e ajustes manuais, `coefHeidecke`, `depreciacao`, `valorResidual`, `kd` e `vcalcConstSeq`. |
+| Composição | Memória ordenada e resultados intermediários, redutores e seus componentes, Fc aplicado, resultado final salvo e fundamentação global. |
+| Complementos | Justificativas de área, escolha do VU, BDI, Fc e ajustes não aplicados; eventual valor final adotado distinto do calculado e critério dessa adoção. |
+
+Para tabelas de parâmetros aplicados, não usar automaticamente `avaliacao.valores_x` quando houver `terreno.parametrosAplicados` mais recente. A área usada na estimação não deve ser sobrescrita pela área de aplicação.
+
+Os anexos estatísticos dependem do modelo correspondente. O nome de um arquivo local, sozinho, não comprova que ele é a mesma versão usada na avaliação salva; usar a identificação e o contexto disponíveis e tornar explícita eventual falta de correspondência. Resultados importados não serão substituídos por uma nova estimação do arquivo local.
+
+## Complementos no gerador
+
+Primeiro, utilizar os fundamentos já presentes no arquivo e as explicações técnicas compartilhadas da MESA. Campos de complemento devem tratar apenas das decisões específicas ainda não justificadas, associados ao ID da avaliação e, para BDI ou características específicas, à construção. Não pedir ao usuário que redigite definições, referências ou explicações gerais já existentes na MESA. Permitir reutilização deliberada de uma justificativa em vários exercícios.
+
+O valor adotado será inicialmente o resultado final salvo. Caso seja necessário registrar adoção diferente, como os arredondamentos do exemplo, deverá existir campo explícito para esse valor e seu critério. Preservar ambos os números; não arredondar silenciosamente e não alterar o resultado de origem.
+
+Arquivos antigos continuarão importáveis dentro das validações já existentes. Uma informação documental ausente deverá aparecer na revisão como pendente, sem ser convertida em zero ou em justificativa padrão. Dados essenciais de resultado inválidos continuarão impedindo a geração de resultados sem suporte.
+
+## Sequência de implementação
+
+1. **Conteúdo técnico compartilhado:** inventariar os textos da MESA e separar conteúdos gerais, explicações parametrizadas e justificativas particulares. Preparar o catálogo/pacote documental versionado, reaproveitando os mesmos conteúdos da interface e das exportações existentes.
+2. **Contrato de dados:** ampliar e testar a normalização EVO, os campos de origem e a preservação do conteúdo técnico. Preparar um exemplo com quatro exercícios, áreas de modelo e aplicação distintas e memória completa.
+3. **Demonstração no corpo:** criar `document/evolutivo.py` com geradores de metodologia geral, terreno, construções e composição, consumindo as explicações compartilhadas da MESA; adaptar o reaproveitamento da metodologia comparativa e a numeração.
+4. **Revisão e fundamentos:** ampliar os schemas e a interface de importação para mostrar as pendências e permitir os complementos necessários, com valores calculados e adotados separados.
+5. **Especificação e conclusão:** gerar os quadros e explicações a partir dos dados preservados; integrar o valor adotado ao cabeçalho já recuperado.
+6. **Anexos e remissões:** manter os anexos estatísticos, organizar o Anexo IV como memória detalhada e gerar referências coerentes com os títulos e números efetivos.
+7. **Validação:** executar testes de dados, equivalência do conteúdo técnico e geração; produzir DOCX representativos, renderizar e conferir todas as páginas afetadas. Verificar também o fluxo AME e o preenchimento manual existentes.
+
+## Critérios de aceitação
+
+- O corpo contém a demonstração territorial, construtiva e de composição por exercício, com os fundamentos técnicos correspondentes.
+- As explicações de redutores, BDI, CUB, depreciação e demais fatores provêm das fontes compartilhadas da MESA, com origem e versão identificáveis. Testes conferem que a adaptação documental preserva fórmulas, termos, unidades, condições, referências e a memória efetivamente aplicada.
+- Explicações técnicas já disponíveis são preenchidas automaticamente. Complementos do avaliador são restritos às decisões específicas ainda sem justificativa; observações marcadas como internas não são publicadas.
+- Um caso com área da gleba e área da unidade distintas mostra ambas corretamente e conserva os parâmetros realmente aplicados.
+- Não se repetem textos de metodologia para cada ano quando o método e o modelo são os mesmos.
+- Há suporte a várias construções, áreas equivalentes, CUB composto, alterações por exercício e justificativas diferentes.
+- BDI em percentual e multiplicador, K, R e Kd têm identificação inequívoca.
+- Reduções e Fc aparecem na ordem e com os valores intermediários do resultado salvo; diferenças de conferência não são corrigidas silenciosamente.
+- Campos monetários são tratados com precisão decimal e formatação consistente; a conferência não recompõe resultados usando coeficientes de exibição com precisão reduzida.
+- Precisão territorial, fundamentação dos componentes e global não são confundidas nem presumidas.
+- Cabeçalho, conclusão e referências temporais permanecem consistentes. Valores calculados e adotados podem diferir, mas a diferença está registrada.
+- Avaliações distintas do mesmo exercício não são somadas ou fundidas automaticamente.
+- A ausência de justificativa, modelo local ou dados históricos é visível e não produz texto técnico inventado.
+- Tabelas largas e quebras de página são verificadas no documento renderizado; títulos e remissões são automáticos.
+
+## Inconsistências do exemplo a evitar
+
+O PDF servirá como referência de estrutura, não como base numérica sem conferência. Foram observadas diferenças internas:
+
+- No cabeçalho, o valor numérico de 2023 aparece como R$ 780.000.000,00, enquanto o extenso e a conclusão indicam R$ 780.000,00.
+- A área do modelo aparece como 70.478 na tabela do corpo e 74.478 no Anexo IV.
+- Há referências anuais e parâmetros diferentes entre a tabela da página 12 e o Anexo IV; para 2025, a tabela do corpo marca duas dicotômicas anuais, enquanto o anexo marca somente AP2024.
+- As observações finais citam dezembro de 2022 a 2024, enquanto o cabeçalho inclui dezembro de 2021 a 2024.
+- Existem remissões de itens e anexos que não correspondem à numeração apresentada.
+
+Esses pontos motivam dados compartilhados entre corpo, cabeçalho e anexos, além de referências geradas automaticamente. Os valores e justificativas próprios deste imóvel não serão adotados como padrões para outros trabalhos.
+
+## Revisão crítica da apresentação
+
+A comparação com o PDF evidenciou excesso de tabelas pequenas e textos genéricos sobre ajustes sem efeito. A revisão reúne parâmetros e estimativas do modelo; reúne ajustes efetivos, campo de arbítrio, áreas e valor territorial; consolida características e mantém um único quadro comparativo de cálculo por construção e grupo de até quatro avaliações. CUB, adequação, CUNIT, BDI, vida consumida, K, Kd e VC passam a aparecer juntos. Mudanças de características, composição do CUB e justificativas entre exercícios permanecem identificadas. Tabelas de áreas equivalentes com uma única área e coeficiente 1 são dispensadas quando repetem exatamente os valores já informados.
+
+As explicações de redutores dependem do efeito salvo, com precedência do fator efetivamente executado sobre a seleção ou taxa de referência. Reduções zeradas não aparecem como aplicadas. Na demonstração das condições do inciso I, somente parcelas acima do limiar histórico participam; nos arts. 60 e 61, somente a condição correspondente ao maior percentual efetivo é apresentada. O limite do art. 88 é explicado com seus valores de verificação somente quando efetivamente acionado. APAN permanece vinculada à decisão no campo de arbítrio, sem desconto autônomo. Ajustes expressamente não aplicados continuam documentados quando o avaliador forneceu justificativa. Ausência de dados não é tratada como percentual zero.
+
+O Anexo IV mantém a ordem salva das operações, omitindo etapas de redutores com efeito explicitamente neutro. Conversões, adição das construções e Fc continuam disponíveis para conferência. Os resultados e a origem importada não são alterados nem recalculados. Explicações comuns de CUB, BDI, vida útil e conservação são agrupadas por conteúdo e abrangência; composições efetivamente adotadas permanecem distintas de referências gerais.
+
+## Narrativa dos ajustes e remissões à caracterização
+
+Revisão de 21/10/2026: o item 3.3.2.2 passa a conter títulos de quinto nível, um para cada condição de restrição efetivamente aplicada, seguido da escolha no campo de arbítrio, quando cabível, e da síntese territorial. A numeração dos filhos se reinicia em cada item de quarto nível. O quadro comparativo de valores permanece único.
+
+As remissões à caracterização usam os números efetivamente gerados nos itens 2.2.X, e não a posição presumida do motivo na entrada. A ligação compara a descrição da condição e designações conhecidas, como APP e APAN, respeitando palavras completas. A ausência de correspondência é indicada, sem criar um número de item inexistente nem afirmar que uma condição foi confirmada quando o capítulo apenas a examina.
+
+A narrativa encadeia a condição tratada no capítulo 2.2, seu fundamento legal, a regra de incidência e o percentual registrado para as referências às quais se aplica. Para as restrições ponderadas, distingue área atingida, taxa de referência, contribuição ponderada e redução efetiva do conjunto. Divergências entre contribuições e percentual salvo são explicitadas sem substituir resultados. APAN continua na decisão técnica do campo de arbítrio.
+
+A identificação dos fundamentos gerais foi conferida no [texto municipal do Decreto nº 16.500/2009](https://legislacao.portoalegre.rs.gov.br/media/sapl/public/normajuridica/sirel/Norma_16500_20091110_1.html): art. 88 para desvalorização particular; arts. 60 e 61, com os incisos correspondentes à condição, para a configuração do terreno; art. 56, parágrafo único, para a equivalência da correção no preço do metro quadrado. Os percentuais apresentados continuam provenientes do catálogo e dos efeitos históricos salvos na avaliação. O fundamento geral não transforma essas taxas em percentuais prescritos pelo caput legal, nem cria enquadramento específico para memórias sem hipótese identificável.

document/anexos/metodologia.py

@@ -3,7 +3,6 @@ Gerador da seção de Metodologia de Avaliação.
 Gera as sub-seções de Aplicação, Variáveis e Equação a partir dos dados do modelo (.dai).
 """
 import json
-import re
 from datetime import date, datetime
 from typing import Optional, List, Tuple, Dict
 
@@ -14,13 +13,16 @@ from docx.oxml import OxmlElement
 from docx.oxml.ns import qn
 
 from models.model_data import ModelData
+from models.anos import periodo_variavel_ano
 from document.numbering import NumeradorSecoes
 from document.formatters import (
     add_body_text,
     add_placeholder_text,
     add_subsubsection_title,
+    add_subsubsubsection_title,
     add_bullet_text,
     criar_paragrafo_formatado,
+    add_simple_table,
 )
 from config.settings import BASE_DIR
 
@@ -76,10 +78,7 @@ _TEXTO_VARIAVEIS_INTRO = (
     "dos imóveis e valorização imobiliária da zona onde se localizam os mesmos."
 )
 
-_TEXTO_VARIAVEIS_LISTA = (
-    "As variáveis independentes que se mostraram mais significativas, a nível "
-    "estatístico, para a formação do valor do imóvel em análise foram:"
-)
+_TEXTO_VARIAVEIS_LISTA = "As variáveis independentes utilizadas no modelo são:"
 
 
 # ---------------------------------------------------------------------------
@@ -153,41 +152,27 @@ def _obter_periodo_amostra(modelo: ModelData) -> Tuple[str, str]:
     return inicio or "data inicial não informada", fim or "data final não informada"
 
 
-def _extrair_anos_variaveis(variaveis: List[str]) -> Tuple[List[int], Optional[int], List[str]]:
-    """
-    Separa variáveis de ano das demais.
-
-    Returns:
-        (anos, ap_ano, outras) onde:
-        - anos: lista ordenada de anos (de variáveis aYYYY)
-        - ap_ano: ano de variável APYYYY (ou None)
-        - outras: variáveis que não são de ano
-    """
+def _extrair_anos_variaveis(variaveis: List[str]) -> Tuple[List[str], List[str]]:
+    """Separa dicotômicas de ano, preservando os nomes usados no modelo."""
     anos = []
-    ap_ano = None
     outras = []
-
     for v in variaveis:
-        if re.fullmatch(r"a(20\d{2}|2100)", v):
-            anos.append(int(v[1:]))
-        elif re.fullmatch(r"AP(20\d{2}|2100)", v):
-            ap_ano = int(v[2:])
+        if periodo_variavel_ano(str(v)) is not None:
+            anos.append(str(v))
         else:
             outras.append(v)
+    return sorted(anos, key=lambda nome: periodo_variavel_ano(nome)[0]), outras
 
-    return sorted(anos), ap_ano, outras
 
-
-def _gerar_bloco_ano(doc: Document, anos: List[int], ap_ano: Optional[int]) -> None:
+def _gerar_bloco_ano(doc: Document, anos: List[str], ano_base: Optional[int]) -> None:
     """
     Gera o bloco especial da variável ANO com título bold e bullets por ano.
     """
     colchetes = [f"[{ano}]" for ano in anos]
-    if ap_ano:
-        colchetes.append(f"[AP{ap_ano}]")
+    lista = " e ".join([", ".join(colchetes[:-1]), colchetes[-1]]) if len(colchetes) > 1 else colchetes[0]
 
     # Título + descrição no mesmo parágrafo (bold + non-bold)
-    titulo = f"Ano {', '.join(colchetes[:-1])} e {colchetes[-1]}:"
+    titulo = f"Ano {lista}:"
     descricao = (
         " variáveis do tipo dicotômicas que identificam o ano em que cada "
         "elemento foi pesquisado, ou seja, corresponde à época em que foi "
@@ -196,18 +181,21 @@ def _gerar_bloco_ano(doc: Document, anos: List[int], ap_ano: Optional[int]) -> N
     _adicionar_paragrafo_variavel(doc, titulo, descricao)
 
     # Bullets individuais por ano
-    for ano in anos:
-        add_bullet_text(doc, f"[{ano}] = 1, se o dado é de {ano};")
-
-    if ap_ano:
-        add_bullet_text(doc, f"[AP{ap_ano}] = 1, se o dado é a partir de {ap_ano};")
+    for nome in anos:
+        periodo, a_partir = periodo_variavel_ano(nome)
+        if a_partir:
+            condicao = f"a partir de {periodo[0]}"
+        elif len(periodo) > 1:
+            condicao = "de " + " ou ".join(str(ano) for ano in periodo)
+        else:
+            condicao = f"de {periodo[0]}"
+        add_bullet_text(doc, f"[{nome}] = 1, se o dado é {condicao}; e 0, caso contrário;")
 
     # Linha final com ano base
-    ano_base = min(anos) - 1
-    add_bullet_text(
-        doc,
-        f"{', '.join(colchetes[:-1])} e {colchetes[-1]} = 0, se o dado é de {ano_base}."
-    )
+    if ano_base is not None:
+        add_bullet_text(doc, f"{lista} = 0, se o dado é de {ano_base} (ano-base do modelo).")
+    else:
+        add_placeholder_text(doc, "[Ano-base não identificado no modelo - conferir a variável de ano dos dados]")
 
 
 def _adicionar_paragrafo_variavel(doc: Document, titulo: str, descricao: str) -> None:
@@ -233,34 +221,44 @@ def _adicionar_paragrafo_variavel(doc: Document, titulo: str, descricao: str) ->
         run_desc.font.color.rgb = RGBColor(255, 0, 0)
 
 
-def _adicionar_equacao_destacada(doc: Document, equacao: str) -> None:
-    """Apresenta a equação como um bloco centralizado e visualmente destacado."""
-    p = doc.add_paragraph()
-    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
-    p.paragraph_format.space_before = Pt(8)
-    p.paragraph_format.space_after = Pt(10)
-    p.paragraph_format.left_indent = Cm(0)
-    p.paragraph_format.right_indent = Cm(0)
-
-    p_pr = p._p.get_or_add_pPr()
-    shading = OxmlElement("w:shd")
-    shading.set(qn("w:fill"), "F2F5F7")
-    p_pr.append(shading)
-
-    bordas = OxmlElement("w:pBdr")
-    for lado in ("top", "left", "bottom", "right"):
-        borda = OxmlElement(f"w:{lado}")
-        borda.set(qn("w:val"), "single")
-        borda.set(qn("w:sz"), "6")
-        borda.set(qn("w:space"), "6")
-        borda.set(qn("w:color"), "7F8C8D")
-        bordas.append(borda)
-    p_pr.append(bordas)
-
-    run = p.add_run(equacao)
-    run.bold = True
-    run.font.name = "Arial"
-    run.font.size = Pt(11)
+def _adicionar_tabela_equacao(doc: Document, modelo: ModelData):
+    """Tabela de identificação e equação no padrão do laudo LA_107."""
+    section = doc.sections[-1]
+    table = add_simple_table(
+        doc, [['Modelo', 'Nº de dados', 'Equação'],
+              [modelo.nome, str(modelo.n_amostras), modelo.equacao or 'Equação não informada']],
+        largura_colunas=[23, 14, 63],
+        largura_total=int(section.page_width-section.left_margin-section.right_margin),
+    )
+    borders = OxmlElement('w:tblBorders')
+    for side in ('top', 'left', 'bottom', 'right', 'insideH', 'insideV'):
+        border = OxmlElement('w:'+side)
+        for key, value in [('val', 'single'), ('sz', '4'), ('color', '000000')]:
+            border.set(qn('w:'+key), value)
+        borders.append(border)
+    table._tbl.tblPr.append(borders)
+    for index, row in enumerate(table.rows):
+        row._tr.get_or_add_trPr().append(OxmlElement('w:cantSplit'))
+        for column, cell in enumerate(row.cells):
+            props = cell._tc.get_or_add_tcPr()
+            for node in list(props.findall(qn('w:shd'))) + list(props.findall(qn('w:noWrap'))):
+                props.remove(node)
+            shading = OxmlElement('w:shd')
+            shading.set(qn('w:fill'), 'FFFFFF' if index == 0 else 'F2F2F2')
+            props.append(shading)
+            margins = OxmlElement('w:tcMar')
+            for side, value in [('top', '100'), ('bottom', '100'), ('left', '80'), ('right', '80')]:
+                margin = OxmlElement('w:'+side)
+                margin.set(qn('w:w'), value)
+                margin.set(qn('w:type'), 'dxa')
+                margins.append(margin)
+            props.append(margins)
+            for paragraph in cell.paragraphs:
+                paragraph.paragraph_format.line_spacing = 1
+                paragraph.paragraph_format.keep_with_next = index == 0
+                for run in paragraph.runs:
+                    run.font.size = Pt(9 if index == 1 and column == 0 else 10)
+    return table
 
 
 # ---------------------------------------------------------------------------
@@ -272,6 +270,13 @@ def _gerar_aplicacao(doc: Document, modelo: ModelData, num: Optional[NumeradorSe
     numero = num.subsubsecao() if num else ""
     add_subsubsection_title(doc, numero, "Aplicação Método Comparativo")
 
+    _adicionar_pesquisa(doc, modelo)
+    _adicionar_fundamentos_comparativos(doc)
+
+
+def _adicionar_pesquisa(doc: Document, modelo: ModelData) -> None:
+    """Reutiliza o texto padrão com a quantidade e o período da amostra."""
+
     data_inicial, data_final = _obter_periodo_amostra(modelo)
     texto = _TEXTO_APLICACAO_P1.format(
         n_amostras=modelo.n_amostras,
@@ -288,24 +293,27 @@ def _gerar_aplicacao(doc: Document, modelo: ModelData, num: Optional[NumeradorSe
         recuo_primeira_linha=1.25,
     )
 
+
+def _adicionar_fundamentos_comparativos(doc: Document) -> None:
     add_body_text(doc, _TEXTO_APLICACAO_P2)
     add_body_text(doc, _TEXTO_APLICACAO_P3)
 
 
-def _gerar_variaveis(doc: Document, modelo: ModelData, num: Optional[NumeradorSecoes]) -> None:
+def _gerar_variaveis(doc: Document, modelo: ModelData, num: Optional[NumeradorSecoes], nivel=3, tipo_y='unitario') -> None:
     """Gera sub-seção 3.2.2 - Variáveis."""
-    numero = num.subsubsecao() if num else ""
-    add_subsubsection_title(doc, numero, "Variáveis")
+    numero = (num.subsubsubsecao() if nivel == 4 else num.subsubsecao()) if num else ""
+    (add_subsubsubsection_title if nivel == 4 else add_subsubsection_title)(doc, numero, "Variáveis")
 
-    add_body_text(doc, _TEXTO_VARIAVEIS_INTRO)
+    add_body_text(doc, _TEXTO_VARIAVEIS_INTRO if tipo_y == 'unitario' else
+                  "A variável dependente representa o valor total do imóvel, em reais (R$). As variáveis independentes representam as características dos elementos de mercado utilizadas no modelo.")
     add_body_text(doc, _TEXTO_VARIAVEIS_LISTA)
 
     descricoes = _carregar_descricoes_variaveis()
-    anos, ap_ano, outras_variaveis = _extrair_anos_variaveis(modelo.variaveis)
+    anos, outras_variaveis = _extrair_anos_variaveis(modelo.variaveis)
 
     # Bloco ANO (se houver variáveis de ano)
-    if anos or ap_ano:
-        _gerar_bloco_ano(doc, anos, ap_ano)
+    if anos:
+        _gerar_bloco_ano(doc, anos, modelo.ano_base)
 
     # Demais variáveis
     for var in outras_variaveis:
@@ -322,9 +330,9 @@ def _gerar_equacao(doc: Document, modelo: ModelData, num: Optional[NumeradorSeco
     add_subsubsection_title(doc, numero, "Equação Modelo Estatístico")
 
     add_body_text(doc, "O modelo de regressão que melhor se ajustou aos dados da amostra é transcrito a seguir:")
+    doc.paragraphs[-1].paragraph_format.keep_with_next = True
 
-    if modelo.equacao:
-        _adicionar_equacao_destacada(doc, modelo.equacao)
+    _adicionar_tabela_equacao(doc, modelo)
 
     add_body_text(doc, "Os resultados estatísticos e a planilha de cálculo são exibidos no Anexo II.")
 

document/avaliacoes_importadas.py

@@ -0,0 +1,104 @@
+"""Document sections based on the adopted results saved in AME/EVO."""
+from .formatters import add_body_text, add_simple_table, add_subsection_title
+from .formatters.table import set_table_font_size
+from decimal import Decimal, InvalidOperation, ROUND_HALF_UP
+
+
+def currency(value):
+    if value is None or value == '':
+        return '—'
+    try:
+        number = Decimal(str(value)).quantize(Decimal('.01'),rounding=ROUND_HALF_UP)
+        if not number.is_finite(): return '—'
+        return 'R$ ' + f'{number:,.2f}'.replace(',','#').replace('.',',').replace('#','.')
+    except (InvalidOperation,ValueError):
+        return '—'
+
+
+def conclusion_table(doc, imported):
+    evo = imported['tipo'] == 'evolutivo'
+    header = ['IPTU', 'Objeto / Avaliação', 'Valor adotado']
+    rows = [header]
+    for item in imported['avaliacoes']:
+        reference = f"IPTU {item['ano']}"
+        rows.append([reference, f"{item['objeto']} — {item['titulo']} [{item['id']}]", currency(item['valor_total'])])
+    if evo:
+        from .evolutivo import table
+        table(doc,rows,[1.3,3.4,1.6],keep_together=len(rows)<=9,font_size=7)
+    else:
+        set_table_font_size(add_simple_table(doc, rows, header_row=True, largura_colunas=[1.4, 3.6, 2.5]),7)
+    from utils.formatters import numero_para_extenso
+    for item in imported['avaliacoes']:
+        extenso = numero_para_extenso(Decimal(item['valor_total']))
+        paragraph = add_body_text(doc,f"{item['titulo']} [{item['id']}] — valor adotado por extenso: {extenso}.")
+        paragraph.paragraph_format.keep_together = True
+        calculated = (item.get('evolutivo') or {}).get('resultadoComposicao',{}).get('valorTotalCalculado')
+        different_calculated = calculated is not None and Decimal(str(calculated)).quantize(Decimal('.01')) != Decimal(item['valor_total'])
+        if item.get('valor_total_origem') is not None or different_calculated:
+            paragraph.paragraph_format.keep_with_next = True
+            origin = item.get('valor_total_origem',calculated)
+            add_body_text(doc,f"Valor registrado na composição de origem: {currency(origin)}; valor adotado no laudo: {currency(item['valor_total'])}. Critério da adoção: {(item.get('complementos') or {}).get('criterio_adocao') or 'não informado; complemento técnico pendente.'}").paragraph_format.keep_together = True
+
+def calculation_sections(doc, imported):
+    for item in imported['avaliacoes']:
+        add_subsection_title(doc, '', f"{item['titulo']} — Ano-base {item['ano_base']}")
+        add_body_text(doc, f"Modelo: {item['modelo'] or 'Não identificado no arquivo'}. Objeto: {item['objeto']}.")
+        evaluation = item['avaliacao']
+        if evaluation.get('precisao'):
+            add_body_text(doc, f"Precisão da estimativa do modelo: {evaluation['precisao']}.")
+        foundation = item.get('fundamentacao') or {}
+        if foundation.get('grade'):
+            add_body_text(doc, f"Fundamentação do modelo: {foundation['grade']}.")
+        for warning in item.get('avisos', []):
+            add_body_text(doc, f"Observação da avaliação: {warning}")
+        parameters = (item.get('evolutivo') or {}).get('terreno',{}).get('parametrosAplicados') or evaluation.get('valores_x') or {}
+        if parameters:
+            add_simple_table(doc, [['Parâmetro', 'Valor informado']] + [[str(key), str(value)] for key, value in parameters.items()], header_row=True, largura_colunas=[3.5, 4])
+        values = [['Resultado', 'Valor']]
+        if item.get('area') is not None:
+            values.append(['Área de aplicação (m²)', str(item['area'])])
+        for key, label in [('estimado_unitario', 'Estimativa unitária do modelo'), ('estimado_total', 'Estimativa total do modelo'), ('ca_inf', 'Campo de arbítrio inferior'), ('ca_sup', 'Campo de arbítrio superior'), ('ic_inf', 'Limite inferior do intervalo de confiança'), ('ic_sup', 'Limite superior do intervalo de confiança'), ('knn_estimado_unitario', 'KNN unitário'), ('knn_estimado_total', 'KNN total')]:
+            if evaluation.get(key) is not None:
+                values.append([label, currency(evaluation[key])])
+        if imported['tipo'] == 'evolutivo':
+            from .evo_adjustments import applied_reducers
+            values.extend([['Valor do terreno', currency(item['valor_terreno'])], ['Valor das construções', currency(item['valor_construcao'])], ['Fator de comercialização', str(item.get('fator_comercializacao', '—'))]])
+            if applied_reducers(item,False):
+                values.append(['Valor após redutores do imóvel', currency(item.get('valor_apos_redutores_imovel'))])
+        if item.get('valor_total_origem') is not None:
+            values.append(['Valor total registrado na avaliação de origem', currency(item['valor_total_origem'])])
+        values.append(['Valor total adotado', currency(item['valor_total'])])
+        add_simple_table(doc, values, header_row=True, largura_colunas=[4.5, 3])
+        if imported['tipo'] == 'evolutivo' and item.get('construcoes'):
+            add_body_text(doc, 'Construções incorporadas à composição')
+            constructions = [['Construção / Tipo', 'Área (m²)', 'CUB / Ano construção', 'Valor calculado']]
+            for index, construction in enumerate(item['construcoes']):
+                constructions.append([
+                    str(construction.get('nome') or construction.get('tipoConstrucao') or f'Construção {index + 1}'),
+                    str(construction.get('areaCalculada', construction.get('areaTotal', '—'))),
+                    f"{construction.get('cubTipo', '—')} / {construction.get('anoConstrucao', '—')}",
+                    currency(construction.get('vcalcConstSeq')),
+                ])
+            add_simple_table(doc, constructions, header_row=True, largura_colunas=[2.5, 1.2, 2.3, 1.5])
+        if imported['tipo'] == 'evolutivo':
+            from .evolutivo import table, fmt, source
+            from .evo_adjustments import visible_memory
+            memory = visible_memory(item)
+            if memory:
+                add_body_text(doc,'Memória das etapas efetivas na ordem de origem')
+                table(doc,[['Etapa','Fator','Resultado','Unidade']]+[[str(step.get('rotulo',step.get('codigo',''))),fmt(step.get('fator'),6),currency(step.get('resultado')),str(step.get('unidade') or 'Não informada')] for step in memory if isinstance(step,dict)],[3,1,1.5,.8],compact=True)
+        if item.get('observacoes'):
+            add_body_text(doc, item['observacoes'])
+        adjustment = item.get('ajustes') or {}
+        memory = adjustment.get('memoria_calculo')
+        if memory:
+            add_body_text(doc, 'Memória dos ajustes adotados')
+            # Preserve saved adjustment evidence in readable paragraphs instead of a raw JSON dump.
+            entries = memory if isinstance(memory, list) else [memory]
+            for entry in entries:
+                if isinstance(entry, dict):
+                    text = '; '.join(f'{key}: {value}' for key, value in entry.items() if not isinstance(value, (list, dict)))
+                    if text:
+                        add_body_text(doc, text)
+                else:
+                    add_body_text(doc, str(entry))

document/evo_adjustments.py

@@ -0,0 +1,69 @@
+"""Select adjustments from saved effects, never from a checkbox alone."""
+from .fundamentacao import number
+
+REDUCERS = {
+    'redutor88I': ('Art. 88, inciso I', 'Art. 88, inciso I — total'),
+    'redutor6061': ('Art. 60 e 61', 'Art. 60 e 61 — aplicado'),
+    'redutorTopografia': ('Topografia', 'Topografia — total'),
+    'redutorAgua': ('Inundação e ação da água', 'Inundação — aplicado'),
+    'redutor88II': ('Art. 88, inciso II', 'Redução total do imóvel'),
+}
+
+
+def saved_result(row):
+    return (row.get('evolutivo') or {}).get('resultadoComposicao') or {}
+
+
+def saved_step(row, code):
+    return next((s for s in saved_result(row).get('memoria') or []
+                 if isinstance(s, dict) and s.get('codigo') == code), {})
+
+
+def step_has_effect(step):
+    # The applied factor takes precedence over a selected/reference percentage.
+    factor = number(step.get('fator'))
+    if factor is not None:
+        return factor != 1
+    rate = number(step.get('percentualReducao'))
+    return rate != 0 if rate is not None else True  # Unknown is not zero.
+
+
+def visible_memory(row):
+    return [s for s in saved_result(row).get('memoria') or [] if isinstance(s, dict)
+            and (s.get('codigo') not in ('redutores_terreno', 'redutores_imovel') or step_has_effect(s))]
+
+
+def reducer_rate(row, key):
+    values = saved_result(row)
+    if key in values:
+        return number(values[key])
+    if key == 'redutor88II' and 'redutorImovel' in values:
+        return number(values['redutorImovel'])
+    code = 'redutores_imovel' if key == 'redutor88II' else 'redutores_terreno'
+    for component in saved_step(row, code).get('componentes') or []:
+        if isinstance(component,dict) and component.get('rotulo') == REDUCERS[key][0]:
+            return number(component.get('reducao'))
+    return None
+
+
+def applied_reducers(row, territorial):
+    code = 'redutores_terreno' if territorial else 'redutores_imovel'
+    step = saved_step(row, code)
+    # Explicitly neutral execution wins over selected components, including caps.
+    if step and not step_has_effect(step):
+        return []
+    keys = list(REDUCERS)[:4] if territorial else ['redutor88II']
+    items = [(key, REDUCERS[key][0], reducer_rate(row, key)) for key in keys
+             if reducer_rate(row, key) is not None and reducer_rate(row, key) > 0]
+    if items:
+        return items
+    aggregate_key = 'redutorTerreno' if territorial else 'redutorImovel'
+    rate = number(saved_result(row).get(aggregate_key))
+    if rate is None and step:
+        factor = number(step.get('fator'))
+        rate = 1-factor if factor is not None else number(step.get('percentualReducao'))
+    if rate is not None and rate <= 0:
+        return []
+    if (rate is not None and rate > 0) or (step and step_has_effect(step)):
+        return [(aggregate_key, 'Redução territorial registrada' if territorial else 'Redução do imóvel registrada', rate)]
+    return []

document/evolutivo.py

@@ -0,0 +1,545 @@
+"""EVO narrative: explain saved evidence in the body, with annexes as support."""
+from collections import OrderedDict
+from decimal import Decimal, ROUND_HALF_UP
+import json
+
+from docx.enum.text import WD_ALIGN_PARAGRAPH
+from docx.oxml import OxmlElement
+from docx.oxml.ns import qn
+
+from .formatters import (add_body_text, add_simple_table, add_subsection_title,
+                         add_subsubsection_title, add_subsubsubsection_title, add_subsubsubsubsection_title)
+from .avaliacoes_importadas import currency
+from .mesa_content import content_for
+from .evo_adjustments import REDUCERS, applied_reducers
+from .fundamentacao import number, global_foundation
+from .footnotes import add_footnote
+from .formatters.table import set_table_font_size
+from .anexos.metodologia import (_gerar_variaveis, _adicionar_pesquisa,
+                                _adicionar_fundamentos_comparativos, _adicionar_tabela_equacao)
+from models.imported_context import context_key, snapshot_model, matching_local
+from models.construction_identity import construction_identity
+
+
+def fmt(value, digits=2):
+    value = number(value)
+    if value is None:
+        return 'Não informado'
+    text = f'{value.quantize(Decimal(1).scaleb(-digits), rounding=ROUND_HALF_UP):,.{digits}f}'
+    return text.replace(',', '#').replace('.', ',').replace('#', '.')
+
+
+def pct(value, fraction=False):
+    value = number(value)
+    return 'Não informado' if value is None else fmt(value * (100 if fraction else 1)) + '%'
+
+
+def ref(row, show_base=True):
+    value = f"IPTU {row['ano']}"
+    if show_base:
+        value += f" / base {row['ano_base']}"
+    return value + (f" — {row['titulo_origem']} [{row['id']}]" if row.get('referencia_duplicada') else '')
+
+
+def source(row):
+    return row.get('evolutivo') or {}
+
+
+def terrain(row):
+    return source(row).get('terreno') or {}
+
+
+def result(row):
+    return source(row).get('resultadoComposicao') or {}
+
+
+def complement(row, key, fallback='Não informado no arquivo; complemento técnico pendente.'):
+    return (row.get('complementos') or {}).get(key) or fallback
+
+
+def table(doc, rows, widths=None, compact=False, keep_together=False, font_size=None):
+    section = doc.sections[-1]
+    if doc.paragraphs:
+        previous = doc.paragraphs[-1]
+        if previous.text.startswith(('Construção ', 'Composição das áreas', 'IPTU ', 'Memória integral', 'Memória das etapas')):
+            previous.paragraph_format.keep_with_next = True
+    obj = add_simple_table(doc, rows, largura_colunas=widths,
+                           largura_total=int(section.page_width-section.left_margin-section.right_margin))
+    for row_index,row in enumerate(obj.rows):
+        row._tr.get_or_add_trPr().append(OxmlElement('w:cantSplit'))
+        for index, cell in enumerate(row.cells):
+            props = cell._tc.get_or_add_tcPr()
+            for no_wrap in list(props.findall(qn('w:noWrap'))): props.remove(no_wrap)
+            margins = OxmlElement('w:tcMar')
+            padding = 25 if compact else 65
+            for side, size in [('top',padding),('bottom',padding),('left',80),('right',80)]:
+                node = OxmlElement('w:'+side); node.set(qn('w:w'), str(size)); node.set(qn('w:type'),'dxa'); margins.append(node)
+            props.append(margins)
+            for para in cell.paragraphs:
+                para.paragraph_format.line_spacing = 1.05
+                para.paragraph_format.keep_with_next = keep_together and row_index<len(obj.rows)-1
+                para.alignment = WD_ALIGN_PARAGRAPH.LEFT if index == 0 else WD_ALIGN_PARAGRAPH.CENTER
+    borders = OxmlElement('w:tblBorders')
+    for side in ['top','left','bottom','right','insideH','insideV']:
+        node = OxmlElement('w:'+side); node.set(qn('w:val'),'single'); node.set(qn('w:sz'),'4'); node.set(qn('w:color'),'D9D9D9'); borders.append(node)
+    obj._tbl.tblPr.append(borders)
+    if font_size is not None:
+        set_table_font_size(obj, font_size)
+    return obj
+
+
+def heading(doc, num, label, level):
+    counter = {2:num.subsecao,3:num.subsubsecao,4:num.subsubsubsecao,5:num.subsubsubsubsecao}[level]
+    builder = {2:add_subsection_title,3:add_subsubsection_title,4:add_subsubsubsection_title,5:add_subsubsubsubsection_title}[level]
+    value = counter()
+    paragraph = builder(doc,value,label)
+    paragraph.paragraph_format.keep_with_next = True
+    return value
+
+
+def equation(doc, text):
+    # Cost/depreciation formulas remain separate from the statistical model table.
+    para = add_body_text(doc,text)
+    if para is not None:
+        para.alignment = WD_ALIGN_PARAGRAPH.CENTER
+        para.paragraph_format.keep_together = True
+
+
+def compared(doc, rows, metrics, notes=None, batch_size=4, show_base=False):
+    """Keep references distinct, with a wider batch for short result labels."""
+    for offset in range(0,len(rows),batch_size):
+        batch = rows[offset:offset+batch_size]
+        labels = [ref(row, show_base=show_base) for row in batch]
+        duplicates = len(set(labels)) != len(labels)
+        if duplicates: labels = [f"{label}\n{row['titulo_origem']} [{row['id']}]" for label,row in zip(labels,batch)]
+        # Short comparative tables stay with their captions; longer ones may
+        # continue with the repeated header.
+        obj = table(doc, [['Parâmetro / resultado']+labels] + [[label]+[getter(row) for row in batch] for label,getter in metrics], [2.4]+[1.45]*len(batch), keep_together=len(metrics)<=12)
+        for index, (label, _) in enumerate(metrics, 1):
+            if notes and label in notes:
+                add_footnote(doc, obj.rows[index].cells[0].paragraphs[0], notes[label])
+        set_table_font_size(obj, 7)
+
+
+def model_analysis(doc, model, tipo_y):
+    """Resumo estatístico no padrão do laudo, sem inferir diagnósticos ausentes."""
+    r2 = number(model.r2) if model else None
+    text = ''
+    if r2 is not None and 0 <= r2 <= 1:
+        value = 'valor total em reais' if tipo_y == 'total' else 'valor unitário em reais por metro quadrado'
+        correlation = r2.sqrt()
+        interpretation = (', indicando a existência de um alto grau de correlação entre as variáveis consideradas.'
+                          if correlation >= Decimal('.9') else '.')
+        text = (f'O coeficiente de correlação linear do modelo é de {fmt(correlation,4)}{interpretation} '
+                f'O modelo de regressão obtido explica aproximadamente {fmt(r2*100,0)}% da variabilidade do {value}, '
+                'sendo o restante da variabilidade atribuída a outras variáveis não consideradas ou a oscilações de caráter aleatório. ')
+    text += ('As especificações e os resultados detalhados encontram-se no Anexo I - Banco de Dados, '
+             'no Anexo II - Planilha de Cálculo e Resultados Estatísticos e no Anexo III - Gráficos.')
+    add_body_text(doc, text)
+
+
+
+def grouped_notes(doc, rows, getter, prefix, always_refs=False):
+    groups = OrderedDict()
+    for row in rows:
+        text = getter(row)
+        if text: groups.setdefault(str(text), []).append(ref(row))
+    for text, references in groups.items():
+        scope = f" ({'; '.join(references)})" if always_refs or len(references)!=len(rows) else ""
+        add_body_text(doc, f"{prefix}{scope}: {text}")
+
+
+def definitions_for(doc, rows, keys):
+    """Different historical packages retain their own wording and applicability."""
+    for key in keys:
+        variants = OrderedDict()
+        for row in rows:
+            text = content_for(source(row)).get('notas',{}).get(key)
+            if text: variants.setdefault(text,[]).append(ref(row))
+        for text,references in variants.items():
+            add_body_text(doc,text + (f" Aplicável a {'; '.join(references)}." if len(variants)>1 else ''))
+
+
+def gerar_corpo_evolutivo(doc, imported, num, caracteristicas_refs=None):
+    rows = imported['avaliacoes']
+    add_body_text(doc, 'O valor do imóvel é obtido pelo método evolutivo, mediante a composição do valor do terreno, estimado pelo método comparativo de dados de mercado, com o custo de reedição das construções, pelo método da quantificação de custo. A composição considera os ajustes registrados e, ao final, o fator de comercialização (Fc).')
+    add_body_text(doc, 'A demonstração a seguir transcreve os parâmetros e resultados salvos na avaliação, mantendo suas referências temporais. O Anexo IV reúne a memória detalhada. O valor calculado permanece distinto de eventual valor final adotado pelo avaliador.')
+    refs = {}
+    refs['terreno'] = heading(doc,num,'AVALIAÇÃO DO TERRENO',2)
+    heading(doc,num,'Aplicação Método Comparativo',3)
+    models = OrderedDict()
+    for row in rows: models.setdefault(context_key(row),[]).append(row)
+    groups = [(snapshot_model(group[0]), group) for group in models.values()]
+    for model, group in groups:
+        if model:
+            if len(groups) > 1:
+                add_body_text(doc, f"Pesquisa utilizada nas avaliações: {'; '.join(ref(row) for row in group)}.")
+            _adicionar_pesquisa(doc, model)
+    if any(model for model, _ in groups):
+        _adicionar_fundamentos_comparativos(doc)
+    for model, group in groups:
+        if model:
+            if len(groups) > 1:
+                add_body_text(doc, f"As variáveis e a equação a seguir se aplicam às avaliações: {'; '.join(ref(row) for row in group)}.")
+            _gerar_variaveis(doc, model, num, nivel=4, tipo_y=(terrain(group[0]).get('avaliacao') or {}).get('tipo_y','unitario'))
+            heading(doc,num,'Equação Modelo Estatístico',4)
+            add_body_text(doc, 'O modelo de regressão que melhor se ajustou aos dados da amostra é transcrito a seguir:')
+            doc.paragraphs[-1].paragraph_format.keep_with_next = True
+            _adicionar_tabela_equacao(doc, model)
+            local, _ = matching_local(group[0])
+            model_analysis(doc, local or model, (terrain(group[0]).get('avaliacao') or {}).get('tipo_y'))
+        else:
+            add_body_text(doc,'O arquivo não preserva o contexto estatístico necessário para transcrever a equação, a amostra e o cadastro de variáveis com segurança. Permanecem documentados os parâmetros e resultados importados; a versão correspondente do modelo deve ser complementada.')
+    heading(doc,num,'Cálculo do valor do terreno',3)
+    heading(doc,num,'Parâmetros e valor estimado pelo modelo',4)
+    keys = list(dict.fromkeys(key for row in rows for key in (terrain(row).get('parametrosAplicados') or row['avaliacao'].get('valores_x') or {})))
+    metrics = [(str(key),lambda row,k=key: str((terrain(row).get('parametrosAplicados') or row['avaliacao'].get('valores_x') or {}).get(k,'Não informado'))) for key in keys]
+    compared(doc,rows,metrics + [
+        ('Estimado Unitário', lambda row: currency(row['avaliacao'].get('estimado_unitario'))),
+        ('CA −15%', lambda row: currency(row['avaliacao'].get('ca_inf'))),
+        ('CA +15%', lambda row: currency(row['avaliacao'].get('ca_sup'))),
+        ('IC 80% Inf.', lambda row: currency(row['avaliacao'].get('ic_inf'))),
+        ('IC 80% Sup.', lambda row: currency(row['avaliacao'].get('ic_sup'))),
+    ], notes={
+        'Estimado Unitário': 'Estimativa do valor do terreno por metro quadrado (R$/m²), antes dos ajustes. Quando o modelo estima o valor total, corresponde à conversão desse valor pela área utilizada no modelo.',
+        'CA −15%': 'CA: campo de arbítrio. CA −15% e CA +15% são os limites inferior e superior, correspondentes a 85% e 115% da estimativa central. Não representam descontos automaticamente aplicados. Os limites são expressos na unidade da variável dependente do modelo: R$/m² no modelo unitário e R$ no modelo total.',
+        'IC 80% Inf.': 'IC 80%: intervalo de confiança de 80% da estimativa do modelo. Inf. e Sup. indicam seus limites inferior e superior. Expressam a incerteza estatística e não se confundem com o campo de arbítrio. Os limites são expressos em R$/m² no modelo unitário e R$ no modelo total.',
+    }, batch_size=5)
+    add_body_text(doc,'A referência anual das avaliações é distinta do ano-base omitido na codificação das variáveis dicotômicas do modelo.')
+    heading(doc,num,'Ajustes aplicados e valor territorial adotado',4)
+    # Load after shared formatters are available to the narrative helper.
+    from .territorial_narrative import gerar_ajustes_territoriais, justificar_area
+    gerar_ajustes_territoriais(doc,rows,num,caracteristicas_refs or [])
+    heading(doc,num,'Síntese do valor territorial adotado',5)
+    add_body_text(doc,'Concluída a análise dos ajustes, o quadro a seguir reúne a formação do valor territorial em cada referência: parte-se do valor unitário do modelo, consideram-se os fatores aplicados e a escolha no campo de arbítrio e multiplica-se o valor unitário adotado pela área de aplicação.').paragraph_format.keep_with_next = True
+    metrics = [('VU antes dos ajustes (R$/m²)',lambda row:currency(terrain(row).get('valorUnitarioOriginal',row['avaliacao'].get('estimado_unitario'))))]
+    metrics += reducer_metrics(rows,True)
+    if any(applied_reducers(row,True) for row in rows):
+        metrics.append(('VU após redutores territoriais (R$/m²)',lambda row:currency(result(row).get('valorUnitarioAposRedutoresTerritoriais'))))
+    metrics += [
+        ('Fator do campo de arbítrio',lambda row:fmt(result(row).get('fatorCaFinal'),4)),
+        ('VU territorial adotado (R$/m²)',lambda row:currency(row.get('valor_unitario'))),
+        ('Área utilizada no modelo (m²)',lambda row:fmt(terrain(row).get('areaModelo',row['avaliacao'].get('valor_area')))),
+        ('Área de aplicação do VU (m²)',lambda row:fmt(row.get('area'))),
+        ('Valor do terreno (R$)',lambda row:currency(row.get('valor_terreno'))),
+    ]
+    compared(doc,rows,metrics,show_base=False)
+    justificar_area(doc,rows)
+    refs['construcoes'] = heading(doc,num,'AVALIAÇÃO DAS CONSTRUÇÕES',2)
+    heading(doc,num,'Aplicação do método da quantificação de custo',3)
+    add_body_text(doc,'O custo de reedição é documentado a partir da área de cálculo, do custo unitário básico (CUB) histórico, das adequações adotadas, do BDI e da depreciação física com valor residual. Os valores e coeficientes são os registrados para cada sequência construtiva.')
+    equation(doc,'CUNIT = CUB × (% CUB / 100)')
+    equation(doc,'VC = área de cálculo × CUNIT × (1 + BDI / 100) × Kd')
+    content = content_for(source(rows[0]))
+    definitions_for(doc,rows,['constructionValue','unitCost'])
+    heading(doc,num,'Características das construções e áreas',4)
+    for note in content.get('notas_area',[]): add_body_text(doc,note)
+    groups = construction_groups(rows)
+    if not groups: add_body_text(doc,'Não há sequências construtivas detalhadas preservadas; o total importado permanece identificado na composição.')
+    construction_characteristics(doc,groups)
+    heading(doc,num,'CUB histórico, referência temporal e adequações',4)
+    definitions_for(doc,rows,['cubGroup','cubType','cubValue','cubPercent'])
+    construction_cub_notes(doc,groups)
+    heading(doc,num,'BDI e justificativa',4)
+    definitions_for(doc,rows,['bdi'])
+    add_body_text(doc,'O BDI informado em percentual é convertido no multiplicador 1 + BDI/100. As referências gerais da MESA orientam a análise; não constituem, por si, uma composição de BDI efetivamente adotada.')
+    construction_bdi_notes(doc,groups)
+    heading(doc,num,'Depreciação e conservação',4)
+    definitions_for(doc,rows,['depreciation','residual','kd','conservation'])
+    add_body_text(doc,'Na expressão de Ross-Heidecke, q é a fração de vida útil consumida e H é o coeficiente de conservação. K representa a depreciação; R é o residual em forma decimal; Kd é o fator remanescente aplicado ao custo.')
+    equation(doc,'q = percentual de vida útil / 100; Ross = q/2 + q²/2')
+    equation(doc,'K = 1 − (1 − Ross) × (1 − H); Kd = R + (1 − K) × (1 − R)')
+    add_body_text(doc,'A MESA registra a curva de Ross com seis casas decimais, K com quatro e Kd com três. Os resultados abaixo são transcritos dos registros salvos, sem recompor os valores a partir de coeficientes arredondados para exibição.')
+    construction_depreciation_notes(doc,groups)
+    heading(doc,num,'Cálculo por construção e exercício',4)
+    for entries in groups.values():
+        add_body_text(doc,construction_name(entries[0][1],entries[0][2]))
+        by_id = {row['id']: c for row,c,i in entries}
+        # One comparative calculation table per effective construction, with all
+        # annual inputs together; characteristics above are grouped by changes.
+        compared(doc,[row for row,c,i in entries],[
+            ('Data do CUB',lambda row:cub_date(row)),
+            ('Projeto / composição CUB',lambda row:'CUB composto' if by_id[row['id']].get('cubCompostoAtivo') else str(by_id[row['id']].get('cubTipo') or 'Não informado')),
+            ('CUB histórico (R$/m²)',lambda row:currency(by_id[row['id']].get('valorCub'))),
+            ('Adequação do CUB (%)',lambda row:pct(by_id[row['id']].get('percentualCubCalculado',by_id[row['id']].get('percentualCub')))),
+            ('CUNIT (R$/m²)',lambda row:currency(by_id[row['id']].get('custoUnitario'))),
+            ('BDI (%)',lambda row:pct(by_id[row['id']].get('bdi'))),
+            ('Multiplicador 1 + BDI/100',lambda row:fmt(1+number(by_id[row['id']]['bdi'])/100,4) if number(by_id[row['id']].get('bdi')) is not None else 'Não informado'),
+            ('Vida útil consumida (%)',lambda row:pct(by_id[row['id']].get('percentualVidaUtil'))),
+            ('Depreciação K',lambda row:fmt(by_id[row['id']].get('depreciacao'),4)),
+            ('Fator remanescente Kd',lambda row:fmt(by_id[row['id']].get('kd'),3)),
+            ('Valor da construção - VC (R$)',lambda row:currency(by_id[row['id']].get('vcalcConstSeq'))),
+        ])
+    refs['composicao'] = heading(doc,num,'AVALIAÇÃO DO IMÓVEL OBJETO',2)
+    add_body_text(doc,'Na ausência de outros ajustes, a composição corresponde a VI = (VT + VC) × Fc, em que VT é o valor territorial e VC é o custo de reedição das construções. Havendo ajustes, a sequência efetivamente salva, apresentada abaixo, prevalece sobre essa expressão simplificada.').paragraph_format.keep_with_next = True
+    gerar_ajustes(doc,rows,territorial=False)
+    metrics = [
+        ('Valor do terreno',lambda row:currency(row['valor_terreno'])),
+        ('Valor das construções',lambda row:currency(row['valor_construcao'])),
+    ]
+    if any(applied_reducers(row,False) for row in rows):
+        metrics += [('Base antes dos redutores do imóvel',lambda row:currency(result(row).get('valorAposConstrucao')))]
+        metrics += reducer_metrics(rows,False)
+        metrics += [('Base após redutores / antes do Fc',lambda row:currency(result(row).get('valorAposRedutoresImovel')))]
+    metrics += [
+        ('Fc aplicado',lambda row:fmt(row.get('fator_comercializacao'),4)),
+        ('Valor total calculado',lambda row:currency(result(row).get('valorTotalCalculado',result(row).get('valorTotal')))),
+    ]
+    compared(doc,rows,metrics)
+    grouped_notes(doc,rows,lambda row:complement(row,'justificativa_fc'),'Justificativa do fator de comercialização')
+    grouped_notes(doc,rows,lambda row:complement(row,'ajustes_nao_aplicados',''),'Ajustes expressamente não aplicados e justificativa')
+    for row in rows:
+        for warning in row.get('revisao_documental',{}).get('conferencias',[]):
+            add_body_text(doc,f"Conferência — {ref(row)}: {warning}")
+    return refs
+
+
+def construction_groups(rows):
+    groups = OrderedDict()
+    for row in rows:
+        for index,c in enumerate(row.get('construcoes') or []):
+            key = construction_identity(source(row),c,index)
+            groups.setdefault(key,[]).append((row,c,index))
+    return groups
+
+
+def construction_name(c,index):
+    return f"Construção {c.get('seq') or index+1}" + (f" — {c['nome']}" if c.get('nome') else '')
+
+
+def cub_date(row):
+    construction = source(row).get('construcao') or {}
+    value = (construction.get('avaliacao') or {}).get('cubData') or construction.get('cubData')
+    if not value: return 'Não informada'
+    text = str(value)
+    return f'{text[5:7]}/{text[:4]}' if len(text) >= 7 and text[4] == '-' else text
+
+
+def entry_scope(entries, groups, show_base=True):
+    """Compact applicability while keeping changes and duplicate years explicit."""
+    selected = {(row['id'],i) for row,c,i in entries}
+    labels = []
+    for full in groups.values():
+        subset = [(row,c,i) for row,c,i in full if (row['id'],i) in selected]
+        if not subset: continue
+        label = construction_name(full[0][1],full[0][2])
+        if len(subset) != len(full): label += ' (' + '; '.join(ref(row, show_base=show_base) for row,c,i in subset) + ')'
+        labels.append(label)
+    return '; '.join(labels)
+
+
+def construction_notes(doc, notes, groups):
+    for text,entries in notes.items():
+        add_body_text(doc,f"{text} Aplicável a {entry_scope(entries,groups)}.")
+
+
+def construction_characteristics(doc, groups):
+    records = [['Construção / referência','Tipo / ano','Área real / de cálculo (m²)','Vida útil / residual R','Conservação / H']]
+    for entries in groups.values():
+        variants = OrderedDict()
+        for row,c,i in entries:
+            values = (f"{c.get('tipoConstrucao') or 'Não informado'} / {c.get('anoConstrucao') or 'Não informado'}",
+                      f"{fmt(c.get('areaTotal'))} / {fmt(c.get('areaCalculada'))}",
+                      f"{fmt(c.get('vidaUtil'),0)} anos / {pct(c.get('valorResidual'),True)}",
+                      f"{c.get('estadoConservacao') or 'Não informado'} / {fmt(c.get('coefHeidecke'),4)}")
+            variants.setdefault(values,[]).append((row,c,i))
+        for values,subset in variants.items():
+            records.append([entry_scope(subset,groups,show_base=False)]+list(values))
+    if len(records)>1: table(doc,records,[1.6,1.6,1.2,1.1,1.5],font_size=7)
+    areas = OrderedDict()
+    for entries in groups.values():
+        for row,c,i in entries:
+            details = [{key:a.get(key) for key in ('descricao','area','coeficiente')} for a in c.get('areasEquivalentes') or []]
+            # A single area at coefficient 1 contributes no additional explanation.
+            if not details or (len(details)==1 and number(details[0].get('coeficiente'))==1
+                               and number(c.get('areaTotal'))==number(c.get('areaCalculada'))==number(details[0].get('area'))): continue
+            areas.setdefault(json.dumps(details,sort_keys=True,ensure_ascii=False),[]).append((row,c,i))
+    for identity,entries in areas.items():
+        add_body_text(doc,'Composição das áreas — '+entry_scope(entries,groups)+'.')
+        table(doc,[['Tipo de área','Área real (m²)','Coeficiente','Parcela equivalente (m²)']]+[
+            [a.get('descricao') or 'Não informado',fmt(a.get('area')),fmt(a.get('coeficiente'),4),
+             fmt(number(a['area'])*number(a['coeficiente'])) if number(a.get('area')) is not None and number(a.get('coeficiente')) is not None else 'Não informado'] for a in json.loads(identity)],[3,1,1,1.4])
+
+
+def construction_cub_notes(doc, groups):
+    notes,compositions = OrderedDict(),OrderedDict()
+    for entries in groups.values():
+        for row,c,i in entries:
+            catalog = content_for(source(row))['referencias'].get('siglasCub',[])
+            short = str(c.get('cubTipo') or '').split(' (',1)[0]
+            found = next((item for item in catalog if item.get('sigla')==short),{})
+            if found: notes.setdefault(f"{short}: {found['descricao']}.",[]).append((row,c,i))
+            if not c.get('cubCompostoAtivo'): continue
+            composition = c.get('cubComposicaoCalculada') or c.get('cubComposicao') or [
+                {'cubTipo':c.get('cubTipo'),'peso':c.get('cubPesoPrincipalCalculado'),'valorCub':c.get('valorCubPrincipal')},
+                {'cubTipo':c.get('cubTipoSecundario'),'peso':c.get('cubPesoSecundarioCalculado'),'valorCub':c.get('valorCubSecundario')}]
+            details = [{key:item.get(key) for key in ('cubTipo','peso','valorCub')} for item in composition]
+            # Historical values/weights distinguish compositions, incidental IDs do not.
+            compositions.setdefault(json.dumps(details,sort_keys=True,ensure_ascii=False),[]).append((row,c,i))
+    construction_notes(doc,notes,groups)
+    if compositions:
+        add_body_text(doc,'O CUB composto corresponde à média ponderada dos projetos: CUB = Σ(CUBᵢ × pesoᵢ) / Σ(pesoᵢ). Os valores compostos salvos constam no quadro de cálculo.')
+        records = [['Construção / referência','Projeto padrão','Peso','CUB histórico (R$/m²)']]
+        for identity,entries in compositions.items():
+            for item in json.loads(identity):
+                records.append([entry_scope(entries,groups,show_base=False),str(item.get('cubTipo') or 'Não informado'),fmt(item.get('peso'),4),currency(item.get('valorCub'))])
+        table(doc,records,[2.5,1.8,.8,1.4],font_size=7)
+
+
+def construction_bdi_notes(doc, groups):
+    notes,compositions = OrderedDict(),OrderedDict()
+    for entries in groups.values():
+        for row,c,i in entries:
+            key = str(c.get('id') or c.get('seq') or i+1)
+            note = (row.get('complementos') or {}).get('bdi',{}).get(key) or 'não preservada no arquivo; complemento técnico pendente.'
+            notes.setdefault('Justificativa do BDI: '+note,[]).append((row,c,i))
+            reference = next((item for item in content_for(source(row))['referencias'].get('bdiTiposConstrucao',[]) if item.get('tipo')==c.get('tipoConstrucao')),None)
+            if reference:
+                notes.setdefault(f"Referência da MESA para {reference['tipo']}: BDI {reference['bdi']}. O percentual adotado consta no quadro de cálculo.",[]).append((row,c,i))
+            composition = c.get('bdiComposicaoAdotada')
+            if isinstance(composition,list) and composition:
+                details = [{key:item.get(key) for key in ('descricao','percentual')} for item in composition]
+                compositions.setdefault(json.dumps(details,sort_keys=True,ensure_ascii=False),[]).append((row,c,i))
+    construction_notes(doc,notes,groups)
+    if compositions:
+        records = [['Construção / referência','Componente de BDI adotado','Percentual']]
+        for identity,entries in compositions.items():
+            records.extend([[entry_scope(entries,groups,show_base=False),str(item.get('descricao') or ''),pct(item.get('percentual'))] for item in json.loads(identity)])
+        table(doc,records,[2.3,3.2,1],font_size=7)
+
+
+def construction_depreciation_notes(doc,groups):
+    from backend.app.evo_documentation import public_reason
+    notes = OrderedDict()
+    for entries in groups.values():
+        for row,c,i in entries:
+            saved = ((source(row).get('construcao') or {}).get('avaliacao') or {}).get('referenciasCalculo') or content_for(source(row))['referencias']
+            life = next((item for item in saved.get('vidaUtilTipos',[]) if item.get('tipo')==c.get('tipoConstrucao')),None)
+            if life:
+                notes.setdefault(f"Referência de vida útil para {life['tipo']}: {life.get('vidaUtil','não informada')} anos. A vida consumida considera a idade no ano de referência, limitada a 100%, ou o ajuste manual registrado.",[]).append((row,c,i))
+            state = next((item for item in saved.get('estadosConservacao',[]) if item.get('estado')==c.get('estadoConservacao')),None)
+            if state and state.get('descricao'): notes.setdefault(f"{c['estadoConservacao']}: {state['descricao']}",[]).append((row,c,i))
+            if c.get('percentualVidaUtilManualAtivo') or c.get('percentualVidaUtilAjusteManual'):
+                reason = public_reason(c,'percentualVidaUtilJustificativa')
+                text = f"Ajuste manual de vida consumida: padrão {pct(c.get('percentualVidaUtilPadrao'))}; adotado {pct(c.get('percentualVidaUtil'))}. " + (reason or 'A justificativa pública não está disponível no arquivo.')
+                notes.setdefault(text,[]).append((row,c,i))
+    construction_notes(doc,notes,groups)
+
+
+def reducer_metrics(rows,territorial):
+    keys = OrderedDict((key,label) for row in rows for key,label,rate in applied_reducers(row,territorial))
+    def display(row,key):
+        active = {k:rate for k,label,rate in applied_reducers(row,territorial)}
+        return pct(active[key],True) if key in active else '—'
+    return [(label+' — redução efetiva',lambda row,k=key:display(row,k)) for key,label in keys.items()]
+
+
+def condition_description(row,territorial):
+    active = {key:rate for key,label,rate in applied_reducers(row,territorial)}
+    if not active: return ''
+    config = ((terrain(row).get('avaliacao') or {}).get('ajuste_territorial') or {}).get('configuracao') or {}
+    saved = source(row).get('catalogoAjustes') or {}
+    lines = []
+    if 'redutor88I' in active:
+        catalog = saved.get('art_88_i') or {}
+        minimum = number(catalog.get('limite_minimo_area'))
+        if minimum is not None:
+            lines.append(f"Inciso I: participam as condições com área atingida superior a {pct(minimum,True)}; cada contribuição corresponde à área relativa multiplicada pela redução de referência.")
+            for item in catalog.get('condicoes') or []:
+                area = number(((config.get('art_88_i') or {}).get('condicoes',{}).get(item.get('codigo')) or {}).get('percentual_area'))
+                rate = number(item.get('redutor',item.get('percentual_reducao')))
+                if area is not None and area>minimum and rate is not None and rate>0:
+                    lines.append(f"{item.get('rotulo') or item['codigo']}: área {pct(area,True)} × redução de referência {pct(rate,True)} = contribuição {pct(area*rate,True)}.")
+    for key,group in [('redutor6061','art_60_61'),('redutor88II','art_88_ii')]:
+        if key not in active: continue
+        selected = (config.get(group) or {}).get('selecionados') or []
+        choices = [item for item in (saved.get(group) or {}).get('condicoes',[]) if item.get('codigo') in selected]
+        if key=='redutor6061':
+            choices = [item for item in choices if number(item.get('redutor'))==active[key]]
+            lines.append('Arts. 60 e 61: aplica-se somente a maior redução selecionada.')
+        if choices:
+            from .territorial_narrative import legal_reference, ARTICLE_88_DECREE
+            if key == 'redutor88II':
+                lines.append('Condições de incidência: '+ '; '.join(
+                    f"{item.get('rotulo') or item['codigo']} ({legal_reference(key, [item['codigo']])})" for item in choices)+'.')
+                lines.append(f'Os dispositivos referidos integram o {ARTICLE_88_DECREE}.')
+            else:
+                lines.append('Condição de incidência: '+ '; '.join(item.get('rotulo') or item['codigo'] for item in choices)+'.')
+    if 'redutorTopografia' in active:
+        for part,rate_key in [('relevo','redutorRelevo'),('nivel_rua','redutorNivel')]:
+            code = (config.get('topografia') or {}).get(part)
+            item = next((item for item in (saved.get('topografia') or {}).get(part,[]) if item.get('codigo')==code),{})
+            rate = number(result(row).get(rate_key)) if rate_key in result(row) else number(item.get('redutor'))
+            if item and rate is not None and rate>0: lines.append(f"{item.get('rotulo') or code}: {pct(rate,True)}.")
+    if 'redutorAgua' in active:
+        code = (config.get('agua') or {}).get('situacao')
+        item = next((item for item in (saved.get('agua') or {}).get('condicoes',[]) if item.get('codigo')==code),{})
+        if item: lines.append((item.get('rotulo') or code)+'.')
+    if not saved: lines.append('Catálogo histórico de ajustes ausente; a redução efetiva foi transcrita do resultado salvo, sem atribuir condições presumidas.')
+    return ' '.join(lines)
+
+
+def gerar_ajustes(doc,rows,territorial):
+    active_rows = [row for row in rows if applied_reducers(row,territorial)]
+    descriptions = OrderedDict()
+    for row in active_rows:
+        terms = content_for(source(row)).get('redutores_termos',{})
+        for key,label,rate in applied_reducers(row,territorial):
+            desc = terms.get(REDUCERS.get(key,('',''))[1])
+            if desc: descriptions.setdefault(label+': '+desc+'.',[]).append(row)
+    for text,applicable in descriptions.items():
+        add_body_text(doc,text + (f" Aplicável a {'; '.join(ref(row) for row in applicable)}." if len(applicable)!=len(rows) else ''))
+    if territorial and active_rows:
+        add_body_text(doc,'Os fatores dos redutores territoriais efetivamente aplicados incidem de forma multiplicativa, antes da escolha no campo de arbítrio. O quadro apresenta os percentuais de redução e os resultados salvos.')
+    grouped_notes(doc,rows,lambda row:condition_description(row,territorial),'Condições dos redutores aplicados')
+    if territorial:
+        apan_rows = [row for row in rows if (number(result(row).get('redutorApan')) or 0)>0
+                     and number(result(row).get('fatorCaFinal')) not in (None,1)]
+        if apan_rows:
+            add_body_text(doc,'A referência de APAN participa da decisão no campo de arbítrio; não constitui desconto territorial autônomo e não é aplicada novamente.')
+            grouped_notes(doc,apan_rows,lambda row:f"Área atingida: {pct(((terrain(row).get('avaliacao') or {}).get('ajuste_territorial') or {}).get('configuracao',{}).get('apan',{}).get('percentual_area'),True)}; referência de APAN: {pct(result(row).get('redutorApan'),True)}; fator final adotado: {fmt(result(row).get('fatorCaFinal'),4)}.",'APAN considerada no campo de arbítrio',always_refs=True)
+    else:
+        limited = [row for row in rows if result(row).get('limiteArt88Aplicado')]
+        if limited:
+            add_body_text(doc,'O limite conjunto dos incisos I e II do art. 88, previsto em seu § 3º, foi efetivamente acionado nas referências abaixo. O percentual do inciso II exibido na composição já considera o limite; os valores de verificação são transcritos da avaliação.')
+            def cap_note(row):
+                catalog = source(row).get('catalogoAjustes') or {}
+                limit = number(catalog.get('limite_reducao_art_88',(catalog.get('art_88_ii') or {}).get('limite_combinado_art_88')))
+                if limit is None or not 0 <= limit <= 1:
+                    return 'Percentual do limite não preservado no catálogo histórico; mantidos os valores de verificação salvos.'
+                return f'Limite conjunto de redução: {pct(limit,True)}; piso correspondente: {pct(1-limit,True)} do valor de referência.'
+            grouped_notes(doc,limited,cap_note,'Limite do art. 88',always_refs=True)
+            compared(doc,limited,[
+                ('Referência do art. 88',lambda row:currency(result(row).get('valorReferenciaArt88'))),
+                ('Resultado após inciso I',lambda row:currency(result(row).get('valorAposIncisoIArt88'))),
+                ('Resultado bruto dos incisos',lambda row:currency(result(row).get('valorAposArt88Bruto'))),
+                ('Resultado após limite do art. 88',lambda row:currency(result(row).get('valorAposArt88Aplicado'))),
+            ])
+
+
+def gerar_especificacao_evolutivo(doc,imported,refs):
+    rows = imported['avaliacoes']
+    foundations = {row['id']:global_foundation(source(row)) for row in rows}
+    if doc.paragraphs: doc.paragraphs[-1].paragraph_format.keep_with_next = True
+    table(doc,[['IPTU','Terreno','Construções','Global','Precisão / amplitude do terreno']]+[
+        [ref(row,show_base=False),foundations[row['id']]['terrain']['grade'],foundations[row['id']]['construction']['grade'],foundations[row['id']]['grade'],str(row['avaliacao'].get('precisao') or 'Indisponível') + (' / ' + pct(row['avaliacao']['amplitude']) if row['avaliacao'].get('amplitude') is not None else '')] for row in rows],[1.4,1,1,1,1.4],font_size=7)
+    add_body_text(doc,f"A fundamentação do terreno corresponde à demonstração do item {refs['terreno']}; a das construções, ao item {refs['construcoes']}; e a composição global, ao item {refs['composicao']}. A precisão e a amplitude relativa do intervalo de confiança dizem respeito à estimativa territorial por regressão.")
+    content = content_for(source(rows[0]))
+    for section,key in [('terreno','terrain'),('construcoes','construction'),('global',None)]:
+        norm = content['normas'][section]
+        add_subsubsection_title(doc,'',norm['title']).paragraph_format.keep_with_next = True
+        add_body_text(doc,norm['source'] + ' ' + norm['framing']).paragraph_format.keep_with_next = True
+        first = foundations[rows[0]['id']][key] if key else foundations[rows[0]['id']]
+        compared(doc,rows,[(item['label'],lambda row,i=index,k=key: (foundations[row['id']][k] if k else foundations[row['id']])['items'][i]['grade'] + ' / ' + str((foundations[row['id']][k] if k else foundations[row['id']])['items'][i]['points'] if (foundations[row['id']][k] if k else foundations[row['id']])['items'][i]['points'] is not None else '—') + ' ponto(s)') for index,item in enumerate(first['items'])])
+        grouped_notes(doc,rows,lambda row,k=key: ' '.join(f"{item['label']}: {item['detail']}" for item in (foundations[row['id']][k] if k else foundations[row['id']])['items']),'Evidências e critérios')
+    content_versions = OrderedDict()
+    for row in rows:
+        f = foundations[row['id']]['terrain']
+        if f.get('missingRequirements'): add_body_text(doc,f"{ref(row)} — o Grau III do terreno depende da declaração dos requisitos adicionais; enquadramento pendente.")
+        catalog = content_for(source(row))
+        saved = source(row).get('documentacaoTecnica')
+        note = f"Conteúdo técnico MESA, versão documental {catalog['versao']}, identificação {catalog['identificador']}. " + ('Pacote identificado na exportação; dados e referências históricas do cálculo preservados.' if saved and saved.get('origem') == 'catalogo_exportacao' else 'Pacote preservado na avaliação.' if saved else 'Arquivo sem pacote documental histórico identificado; utilizadas as explicações gerais do catálogo sincronizado, preservando os dados e as referências de cálculo salvos.')
+        content_versions.setdefault(note,[]).append(ref(row))
+    for note,references in content_versions.items():
+        paragraph = add_body_text(doc,note + (f" Aplicável a {', '.join(references)}." if len(content_versions)>1 else ''))
+        paragraph.paragraph_format.keep_together = True

document/footnotes.py

@@ -0,0 +1,49 @@
+"""Notas de rodapé nativas, inclusive quando o documento já contém notas."""
+from lxml import etree
+from docx.oxml import OxmlElement, parse_xml
+from docx.oxml.ns import qn
+from docx.opc.constants import CONTENT_TYPE as CT, RELATIONSHIP_TYPE as RT
+from docx.opc.packuri import PackURI
+from docx.opc.part import Part, XmlPart
+from docx.shared import Pt
+
+
+def add_footnote(doc, paragraph, text):
+    try:
+        part = doc.part.part_related_by(RT.FOOTNOTES)
+        root = parse_xml(part.blob)
+    except KeyError:
+        root = OxmlElement('w:footnotes')
+        for identifier, kind in [(-1, 'separator'), (0, 'continuationSeparator')]:
+            note = OxmlElement('w:footnote')
+            note.set(qn('w:id'), str(identifier)); note.set(qn('w:type'), kind)
+            p = OxmlElement('w:p'); r = OxmlElement('w:r')
+            r.append(OxmlElement('w:'+kind)); p.append(r); note.append(p); root.append(note)
+        part = Part(PackURI('/word/footnotes.xml'), CT.WML_FOOTNOTES, b'', doc.part.package)
+        doc.part.relate_to(part, RT.FOOTNOTES)
+    identifier = max([0] + [int(n.get(qn('w:id'))) for n in root]) + 1
+    note = OxmlElement('w:footnote'); note.set(qn('w:id'), str(identifier))
+    p = OxmlElement('w:p'); props = OxmlElement('w:pPr')
+    spacing = OxmlElement('w:spacing'); spacing.set(qn('w:after'), '60')
+    props.append(spacing); p.append(props)
+    for marker, value in [('footnoteRef', None), ('t', ' '+text)]:
+        r = OxmlElement('w:r'); rp = OxmlElement('w:rPr')
+        font = OxmlElement('w:rFonts')
+        font.set(qn('w:ascii'), 'Arial'); font.set(qn('w:hAnsi'), 'Arial'); rp.append(font)
+        size = OxmlElement('w:sz'); size.set(qn('w:val'), '14'); rp.append(size)
+        if value is None:
+            vertical = OxmlElement('w:vertAlign'); vertical.set(qn('w:val'), 'superscript'); rp.append(vertical)
+        r.append(rp); element = OxmlElement('w:'+marker)
+        if value is not None:
+            element.text = value; element.set(qn('xml:space'), 'preserve')
+        r.append(element); p.append(r)
+    note.append(p); root.append(note)
+    if isinstance(part, XmlPart):
+        part._element = root
+    else:
+        part._blob = etree.tostring(root, xml_declaration=True, encoding='UTF-8', standalone=True)
+    run = paragraph.add_run(); run.font.superscript = True
+    run.font.size = Pt(7)
+    reference = OxmlElement('w:footnoteReference'); reference.set(qn('w:id'), str(identifier))
+    run._r.append(reference)
+    return identifier

document/formatters/__init__.py

@@ -14,6 +14,7 @@ from .heading import (
     add_subsection_title,
     add_subsubsection_title,
     add_subsubsubsection_title,
+    add_subsubsubsubsection_title,
 )
 from .table import (
     set_cell_shading,
@@ -45,6 +46,7 @@ __all__ = [
     'add_subsection_title',
     'add_subsubsection_title',
     'add_subsubsubsection_title',
+    'add_subsubsubsubsection_title',
     # Tabelas
     'set_cell_shading',
     'formatar_celula_tabela',

document/formatters/heading.py

@@ -7,6 +7,12 @@ from docx.enum.text import WD_ALIGN_PARAGRAPH
 from .paragraph import criar_paragrafo_formatado
 
 
+def _heading_paragraph(*args, **kwargs):
+    paragraph = criar_paragrafo_formatado(*args, **kwargs)
+    paragraph.paragraph_format.keep_with_next = True
+    return paragraph
+
+
 def add_heading_custom(doc: Document, text: str, level: int = 1):
     """Adiciona título customizado."""
     configs = {
@@ -15,7 +21,7 @@ def add_heading_custom(doc: Document, text: str, level: int = 1):
     }
     cfg = configs.get(level, {'tamanho': 11, 'antes': 6, 'depois': 6})
 
-    return criar_paragrafo_formatado(
+    return _heading_paragraph(
         doc, text, negrito=True, sublinhado=True, tamanho=cfg['tamanho'],
         espaco_antes=cfg['antes'], espaco_depois=cfg['depois'],
         alinhamento=WD_ALIGN_PARAGRAPH.LEFT
@@ -24,7 +30,7 @@ def add_heading_custom(doc: Document, text: str, level: int = 1):
 
 def add_section_title(doc: Document, number: str, text: str):
     """Adiciona título de seção principal (ex: 1. SOLICITAÇÃO)."""
-    return criar_paragrafo_formatado(
+    return _heading_paragraph(
         doc, f"{number}. {text}", negrito=True, tamanho=12,
         espaco_antes=18, espaco_depois=12, alinhamento=WD_ALIGN_PARAGRAPH.LEFT
     )
@@ -32,7 +38,7 @@ def add_section_title(doc: Document, number: str, text: str):
 
 def add_subsection_title(doc: Document, number: str, text: str):
     """Adiciona título de subseção (ex: 1.1 Considerações)."""
-    return criar_paragrafo_formatado(
+    return _heading_paragraph(
         doc, f"{number} {text}", negrito=True, tamanho=11,
         espaco_antes=12, espaco_depois=6, recuo_esq=0.3,
         alinhamento=WD_ALIGN_PARAGRAPH.LEFT
@@ -41,7 +47,7 @@ def add_subsection_title(doc: Document, number: str, text: str):
 
 def add_subsubsection_title(doc: Document, number: str, text: str):
     """Adiciona título de sub-subseção (ex: 3.2.1)."""
-    return criar_paragrafo_formatado(
+    return _heading_paragraph(
         doc, f"{number} {text}", negrito=True, tamanho=11,
         espaco_antes=10, espaco_depois=4, recuo_esq=0.5,
         alinhamento=WD_ALIGN_PARAGRAPH.LEFT
@@ -50,7 +56,16 @@ def add_subsubsection_title(doc: Document, number: str, text: str):
 
 def add_subsubsubsection_title(doc: Document, number: str, text: str):
     """Adiciona título de sub-sub-subseção (ex: 3.2.1.1)."""
-    return criar_paragrafo_formatado(
+    return _heading_paragraph(
+        doc, f"{number} {text}", negrito=True, tamanho=10,
+        espaco_antes=8, espaco_depois=4, recuo_esq=0.7,
+        alinhamento=WD_ALIGN_PARAGRAPH.LEFT
+    )
+
+
+def add_subsubsubsubsection_title(doc: Document, number: str, text: str):
+    """Título de quinto nível sem reduzir a legibilidade do texto."""
+    return _heading_paragraph(
         doc, f"{number} {text}", negrito=True, tamanho=10,
         espaco_antes=8, espaco_depois=4, recuo_esq=0.7,
         alinhamento=WD_ALIGN_PARAGRAPH.LEFT

document/formatters/table.py

@@ -15,6 +15,15 @@ from .paragraph import aplicar_cor_run
 WD_ALIGN_VERTICAL = WD_CELL_VERTICAL_ALIGNMENT
 
 
+def set_table_font_size(table, size):
+    """Apply a uniform size to every run, including headers and note markers."""
+    for row in table.rows:
+        for cell in row.cells:
+            for paragraph in cell.paragraphs:
+                for run in paragraph.runs:
+                    run.font.size = Pt(size)
+
+
 def set_cell_shading(cell, color: str) -> None:
     """
     Define a cor de fundo de uma célula.

document/fundamentacao.py

@@ -0,0 +1,136 @@
+"""Documentary framing equivalent to MESA modelFoundation/globalFoundation.
+
+No valuation is recalculated. Missing evidence remains pending. Equivalence is
+checked against MESA's JavaScript, including the per-item minima.
+"""
+from decimal import Decimal, InvalidOperation
+from .mesa_content import content_for
+
+POINTS = {'Grau III': 3, 'Grau II': 2, 'Grau I': 1, 'Sem enquadramento': 0}
+
+
+def number(value):
+    try:
+        if value is None or value == '' or isinstance(value, bool):
+            return None
+        text = str(value)
+        if ',' in text:
+            text = text.replace('.', '').replace(',', '.')
+        result = Decimal(text)
+        return result if result.is_finite() else None
+    except (InvalidOperation, ValueError):
+        return None
+
+
+def grade(points):
+    return {3: 'Grau III', 2: 'Grau II', 1: 'Grau I', 0: 'Sem enquadramento'}.get(points, 'Pendente')
+
+
+def threshold(value, limits):
+    value = number(value)
+    if value is None:
+        return None
+    return next((3-i for i, limit in enumerate(limits) if value <= Decimal(str(limit))), 0)
+
+
+def model_foundation(source):
+    terrain = source.get('terreno') or {}
+    state = terrain.get('fundamentacaoModelo') or {}
+    context = terrain.get('contextoModelo') or {}
+    evidence = context.get('normativeEvidence') or {}
+    evaluation = terrain.get('avaliacao') or {}
+    content = content_for(source)
+    items = []
+    def add(key, label, points, detail=''):
+        items.append({'key': key, 'label': label, 'points': points, 'grade': grade(points), 'detail': detail})
+    for key, label in [('caracterizacao', 'Caracterização do imóvel avaliando'), ('identificacaoDados', 'Identificação dos dados de mercado')]:
+        saved = state.get(key) or {}
+        selected = saved.get('grau')
+        desc = content.get('descricoes_modelo', {}).get(key, {}).get(selected, '')
+        detail = ' '.join(filter(None, [desc, saved.get('justificativa')]))
+        add(key, label, POINTS.get(selected), detail or 'Enquadramento não informado pelo avaliador.')
+    n, k = number(evidence.get('n')), number(evidence.get('k'))
+    qty = next((points for mult, points in [(6, 3), (4, 2), (3, 1)] if n >= mult*(k+1)), 0) if n is not None and k is not None and k >= 0 else None
+    add('quantidadeDados', 'Quantidade de dados de mercado', qty, f'n = {n}; k = {k}.' if qty is not None else 'n e k indisponíveis no contexto salvo.')
+    extrap = POINTS.get(evaluation.get('fundamentacao'))
+    if extrap is None and 'qtd_extrapolacoes' in evaluation:
+        count = max(Decimal(0),number(evaluation['qtd_extrapolacoes']) or Decimal(0))
+        impact = number(evaluation.get('perc_ext')) or Decimal(0)
+        severe = any(isinstance(item, dict) and item.get('status') == 'grave' for item in (evaluation.get('extrapolacoes') or {}).values())
+        extrap = 0 if severe or (impact is not None and impact > 20) else 3 if count == 0 else 2 if count == 1 and impact is not None and impact <= 15 else 1
+    count_text = evaluation.get('qtd_extrapolacoes')
+    impact_text = evaluation.get('perc_ext')
+    detail = 'Nenhuma variável extrapolada.' if count_text == 0 else f"Variáveis extrapoladas: {count_text if count_text is not None else 'não informado'}." + (f' Impacto: {impact_text}%.' if impact_text is not None else '')
+    add('extrapolacao', 'Extrapolação', extrap, detail)
+    pvalues = [(item.get('name', ''), number(item.get('pValue'))) for item in evidence.get('regressorPValues', []) if isinstance(item, dict)]
+    worst = max(((name, p) for name, p in pvalues if p is not None), key=lambda item: item[1], default=('', None))
+    add('significanciaRegressores', 'Significância dos regressores', threshold(worst[1], [.1,.2,.3]), f'Maior p-valor: {worst[1]} ({worst[0]}).' if worst[1] is not None else 'p-valores indisponíveis.')
+    add('significanciaModelo', 'Teste F', threshold(evidence.get('fPValue'), [.01,.02,.05]), f"p-valor: {evidence.get('fPValue', 'não informado')}.")
+    by_key = {item['key']: item['points'] for item in items}
+    p = [by_key[key] for key in ['caracterizacao','quantidadeDados','identificacaoDados','extrapolacao','significanciaRegressores','significanciaModelo']]
+    total = sum(value for value in p if value is not None)
+    result = 'Pendente'
+    requirements = state.get('requisitosGrauIII') or {}
+    req_keys = [item['key'] for item in content.get('requisitos_modelo', [])]
+    candidate = all(value is not None for value in p) and total >= 16 and all(value >= minimum for value, minimum in zip(p,[2,3,2,3,3,3]))
+    missing_req = candidate and any(requirements.get(key) not in ('sim','nao',True,False) for key in req_keys)
+    if all(value is not None for value in p) and not missing_req:
+        if candidate and all(requirements.get(key) in ('sim',True) for key in req_keys): result = 'Grau III'
+        elif total >= 10 and all(value >= minimum for value, minimum in zip(p,[1,2,1,2,2,2])): result = 'Grau II'
+        elif all(value >= 1 for value in p): result = 'Grau I'
+        else: result = 'Sem enquadramento'
+    return {'items': items, 'totalPoints': total, 'grade': result, 'requirements': requirements, 'missingRequirements': bool(missing_req)}
+
+
+def construction_foundation(source):
+    construction = source.get('construcao') or {}
+    saved = construction.get('fundamentacaoMqc') or (construction.get('avaliacao') or {}).get('fundamentacaoMqc') or {}
+    defs = saved.get('definitions') or {}
+    # Labels are extracted from the very function that assigns the MESA scores.
+    import re
+    rule = content_for(source)['funcoes_mqc']['calcularEnquadramento']
+    options = re.findall(r"definitions\.(\w+) === '([^']+)' \? (\d)", rule)
+    items = []
+    for key, label in [('formaCub','Custo direto'),('tipoBdi','BDI'),('depreciacao','Depreciação física')]:
+        value = defs.get(key)
+        points = next((int(score) for field, text, score in options if field == key and value == text), 1 if value else None)
+        items.append({'label':label,'points':points,'grade':grade(points),'detail':value or 'Critério não informado.'})
+    p = [item['points'] for item in items]
+    total = sum(value for value in p if value is not None)
+    result = 'Pendente'
+    if all(value is not None for value in p):
+        if total >= 7 and p[0] == 3 and min(p[1:]) >= 2: result = 'Grau III'
+        elif total >= 5 and p[0] >= 2 and p[1] >= 2: result = 'Grau II'
+        elif total >= 3: result = 'Grau I'
+        else: result = 'Fora dos critérios'
+    return {'items':items,'totalPoints':total,'grade':result}
+
+
+def global_foundation(source):
+    terrain = model_foundation(source)
+    construction = construction_foundation(source)
+    result = source.get('resultadoComposicao') or {}
+    vt = number((source.get('terreno') or {}).get('valorTotal'))
+    vc = number((source.get('construcao') or {}).get('valorTotal'))
+    # calculate(year).beforeFc in MESA is the sum of these two saved components.
+    total_value = vt+vc if vt is not None and vc is not None else None
+    items = []
+    for label, value, foundation in [('Terreno',vt,terrain),('Construções',vc,construction)]:
+        share = value/total_value if value is not None and total_value is not None and total_value > 0 else None
+        reduced = value is not None and value > 0 and share is not None and share < Decimal('.15')
+        points = 2 if reduced else POINTS.get(foundation['grade'])
+        # Global MESA only recognises the three positive grades.
+        if not reduced and points == 0: points = None
+        items.append({'label':label,'grade':grade(points),'points':points,'detail':'Participação inferior a 15%; atribuídos dois pontos ao item.' if reduced else f"Fundamentação do componente: {foundation['grade']}.", 'share':share})
+    fc = str((source.get('fundamentacaoGlobal') or {}).get('fatorComercializacao') or '')
+    option = next((item for item in content_for(source)['criterios_fc'] if item['value'] == fc), {})
+    items.append({'label':'Fator de comercialização','grade':option.get('grade','Pendente'),'points':option.get('points'),'detail':option.get('label','Critério do Fc não informado.')})
+    p = [item['points'] for item in items]
+    total = sum(value for value in p if value is not None)
+    result_grade = 'Pendente'
+    if all(value is not None for value in p):
+        if total >= 8 and p[0] == p[1] == 3 and p[2] >= 2: result_grade = 'Grau III'
+        elif total >= 5 and p[0] >= 2 and p[1] >= 2: result_grade = 'Grau II'
+        elif total >= 3 and min(p) >= 1: result_grade = 'Grau I'
+        else: result_grade = 'Sem enquadramento'
+    return {'items':items,'totalPoints':total,'grade':result_grade,'terrain':terrain,'construction':construction}

document/generator.py

@@ -11,7 +11,11 @@ from docx import Document
 from docx.shared import Pt, Inches, Cm
 from docx.enum.text import WD_ALIGN_PARAGRAPH
 from docx.enum.table import WD_TABLE_ALIGNMENT
+from docx.oxml import OxmlElement
 
+from .avaliacoes_importadas import conclusion_table, calculation_sections
+from .evolutivo import gerar_corpo_evolutivo, gerar_especificacao_evolutivo
+from models.imported_context import context_key, matching_local
 from .numbering import NumeradorSecoes
 from .formatters import (
     criar_paragrafo_formatado,
@@ -29,7 +33,7 @@ from .formatters import (
 )
 
 from config.settings import TEMPLATES_DIR, TEXTOS_DIR, OUTPUT_DIR
-from models import get_model
+from models import get_model, list_available_models
 from utils.docx_loader import ler_texto_docx, mesclar_documento_fotos
 from .anexos import (
     anexo_banco_dados_cabe_na_largura,
@@ -151,12 +155,16 @@ class LaudoGenerator:
             cell = row.cells[0]
             cell.merge(row.cells[1])
             criar_celula_cabecalho_tabela(cell, text)
+            for paragraph in cell.paragraphs:
+                paragraph.paragraph_format.keep_with_next = True
 
         def add_row(label, value):
             row = table.add_row()
             configurar_linha_tabela_altura(row, 0.6)
             criar_celula_dados_tabela(row.cells[0], label, is_label=True)
             criar_celula_dados_tabela(row.cells[1], str(value) if value else "")
+            if label in ('Valores de Mercado:', 'Referências:'):
+                row._tr.get_or_add_trPr().append(OxmlElement('w:cantSplit'))
 
         # Definição das seções
         secoes = [
@@ -228,15 +236,19 @@ class LaudoGenerator:
 
         add_subsection_title(doc, num.subsecao(), "CARACTERÍSTICAS PARTICULARMENTE DESVALORIZANTES")
 
+        caracteristicas_refs = []
         secoes_motivos = motivos_formatados.get('secoes', [])
         if not secoes_motivos:
             add_placeholder_text(doc)
         else:
             for secao in secoes_motivos:
-                add_subsubsection_title(doc, num.subsubsecao(), secao['titulo'])
+                numero_caracteristica = num.subsubsecao()
+                add_subsubsection_title(doc, numero_caracteristica, secao['titulo'])
+                caracteristicas_refs.append({**secao, 'referencia':numero_caracteristica})
                 p = doc.add_paragraph()
                 p.add_run(f"Status: {secao['status']}").italic = True
                 p.paragraph_format.left_indent = Inches(0.5)
+                p.paragraph_format.keep_with_next = True
                 add_placeholder_text(doc)
 
         # 3. ANÁLISE DE MERCADO
@@ -245,18 +257,34 @@ class LaudoGenerator:
         add_placeholder_text(doc, "[Inserir diagnóstico de mercado]")
 
         add_subsection_title(doc, num.subsecao(), "METODOLOGIA DE AVALIAÇÃO")
-        # Tentar gerar metodologia a partir do modelo
-        modelo_nome = dados.get('modelo_avaliacao', '')
-        modelo = get_model(modelo_nome) if modelo_nome else None
-        if modelo:
-            gerar_anexo_metodologia(doc, modelo, num=num)
+        imported = dados.get('avaliacoes_importadas')
+        evo_refs = None
+        if imported and imported['tipo'] == 'evolutivo':
+            evo_refs = gerar_corpo_evolutivo(doc, imported, num, caracteristicas_refs)
+        elif imported:
+            add_body_text(doc, dados['metodo_avaliacao'])
+            for name in dict.fromkeys(item['modelo'] for item in imported['avaliacoes'] if item['modelo']):
+                modelo = get_model(name) if name in list_available_models() else None
+                if modelo:
+                    add_body_text(doc, f"Modelo {name}")
+                    gerar_anexo_metodologia(doc, modelo, num=num)
+                else:
+                    add_body_text(doc, f"Modelo utilizado: {name}. O modelo não está disponível na biblioteca local para gerar os anexos estatísticos completos.")
         else:
-            add_placeholder_text(doc, "[Inserir metodologia - selecione um modelo]")
+            modelo_nome = dados.get('modelo_avaliacao', '')
+            modelo = get_model(modelo_nome) if modelo_nome else None
+            if modelo:
+                gerar_anexo_metodologia(doc, modelo, num=num)
+            else:
+                add_placeholder_text(doc, "[Inserir metodologia - selecione um modelo]")
 
         # 4. ESPECIFICAÇÃO
         add_section_title(doc, num.secao(), "ESPECIFICAÇÃO DA AVALIAÇÃO")
         add_body_text(doc, f"Método: {dados.get('metodo_avaliacao', '')}")
-        add_placeholder_text(doc)
+        if evo_refs:
+            gerar_especificacao_evolutivo(doc, imported, evo_refs)
+        else:
+            add_placeholder_text(doc)
 
         # 5. CONCLUSÃO
         add_section_title(doc, num.secao(), "CONCLUSÃO TÉCNICA")
@@ -275,19 +303,27 @@ class LaudoGenerator:
 
         add_subsection_title(doc, num.subsecao(), "SOBRE O VALOR DE MERCADO")
         valores_mercado_lista = dados.get('valores_mercado_lista', [])
-        if valores_mercado_lista:
+        if dados.get('avaliacoes_importadas'):
+            conclusion_table(doc, dados['avaliacoes_importadas'])
+        elif valores_mercado_lista:
             self._gerar_tabela_valores_mercado(doc, valores_mercado_lista)
         else:
             add_placeholder_text(doc)
 
         add_subsection_title(doc, num.subsecao(), "OBSERVAÇÕES COMPLEMENTARES")
-        add_placeholder_text(doc, "[Inserir observações]")
+        if evo_refs:
+            for row in imported['avaliacoes']:
+                if row.get('observacoes'):
+                    add_body_text(doc, f"{row['titulo']}: {row['observacoes']}")
+            add_body_text(doc, f"Referências temporais: {dados.get('datas_referencia', '')}. A composição calculada está demonstrada no item {evo_refs['composicao']}; a conclusão e o cabeçalho apresentam os valores finais adotados.")
+        else:
+            add_placeholder_text(doc, "[Inserir observações]")
 
         # 6. ANEXOS (lista)
         add_section_title(doc, num.secao(), "ANEXOS")
         for anexo in ["I. BANCO DE DADOS", "II. PLANILHA DE CÁLCULO", "III. GRÁFICOS",
                       "IV. CÁLCULO DO VALOR", "V. DADOS DO IMÓVEL", "VI. REGISTRO FOTOGRÁFICO"]:
-            add_body_text(doc, anexo)
+            add_body_text(doc, anexo).paragraph_format.keep_with_next = not anexo.startswith("VI.")
 
     def _gerar_tabela_valores_mercado(self, doc: Document, valores_lista: List[Dict]) -> None:
         """Gera uma tabela arejada de valores e lista os valores por extenso abaixo."""
@@ -408,38 +444,84 @@ class LaudoGenerator:
         section = doc.sections[-1]
         return int(section.page_width - section.left_margin - section.right_margin)
 
+    def _gerar_anexos_importados(self, doc, imported):
+        available_names = set(list_available_models())
+        if imported['tipo'] == 'evolutivo':
+            distinct = {context_key(item): item for item in imported['avaliacoes']}
+            models = [(f'{name} — contexto {fingerprint}', matching_local(item)[0]) for (name,fingerprint),item in distinct.items()]
+        else:
+            models = [(name, get_model(name) if name in available_names else None) for name in dict.fromkeys(
+                item['modelo'] for item in imported['avaliacoes'] if item['modelo'])]
+        available = [(name, model) for name, model in models if model is not None]
+        if not available:
+            doc.add_page_break()
+        for title, builder in [
+            ('ANEXO I – BANCO DE DADOS', gerar_anexo_banco_dados),
+            ('ANEXO II – PLANILHA DE CÁLCULO E RESULTADOS ESTATÍSTICOS', gerar_anexo_planilha),
+            ('ANEXO III – GRÁFICOS', gerar_anexo_graficos),
+        ]:
+            if available:
+                landscape = builder == gerar_anexo_banco_dados and any(
+                    not anexo_banco_dados_cabe_na_largura(model, None, self._largura_util_secao_atual(doc))
+                    for _, model in available)
+                if landscape:
+                    iniciar_secao_paisagem(doc)
+                else:
+                    iniciar_secao_retrato(doc)
+            self._criar_titulo_anexo(doc, title)
+            if imported['tipo'] == 'evolutivo':
+                for item in distinct.values():
+                    local, warning = matching_local(item)
+                    if warning:
+                        add_body_text(doc, f"{item['modelo']}: {warning} Os parâmetros e resultados originais permanecem no corpo e no Anexo IV.")
+            if not available:
+                add_body_text(doc, 'Não gerado: o modelo correspondente não está disponível na biblioteca local. Os resultados adotados por ano constam do Anexo IV.')
+            for name, model in available:
+                add_subsection_title(doc, '', name)
+                builder(doc, model)
+        if available:
+            iniciar_secao_retrato(doc)
+        else:
+            doc.add_page_break()
+        self._criar_titulo_anexo(doc, 'ANEXO IV – CÁLCULO DO VALOR POR ANO')
+        calculation_sections(doc, imported)
+
     def _gerar_anexos(self, doc: Document, dados: Dict) -> None:
         """Gera as páginas de anexos a partir dos dados do modelo."""
-        # Tentar carregar o modelo selecionado
-        modelo_nome = dados.get('modelo_avaliacao', '')
-        modelo = get_model(modelo_nome) if modelo_nome else None
-        banco_dados_colunas = dados.get('banco_dados_colunas') or None
-
-        # ANEXO I - BANCO DE DADOS. Usa paisagem apenas quando as colunas
-        # selecionadas não cabem com legibilidade em retrato.
-        if not anexo_banco_dados_cabe_na_largura(
-            modelo,
-            banco_dados_colunas,
-            self._largura_util_secao_atual(doc),
-        ):
-            iniciar_secao_paisagem(doc)
-        self._criar_titulo_anexo(doc, "ANEXO I – BANCO DE DADOS")
-        gerar_anexo_banco_dados(doc, modelo, colunas=banco_dados_colunas)
-
-        # ANEXO II - PLANILHA DE CÁLCULO (volta para retrato)
-        iniciar_secao_retrato(doc)
-        self._criar_titulo_anexo(doc, "ANEXO II – PLANILHA DE CÁLCULO E RESULTADOS ESTATÍSTICOS")
-        gerar_anexo_planilha(doc, modelo)
-
-        # ANEXO III - GRÁFICOS
-        doc.add_page_break()
-        self._criar_titulo_anexo(doc, "ANEXO III – GRÁFICOS")
-        gerar_anexo_graficos(doc, modelo)
+        imported = dados.get('avaliacoes_importadas')
+        if imported:
+            self._gerar_anexos_importados(doc, imported)
+        else:
+            # Tentar carregar o modelo selecionado
+            modelo_nome = dados.get('modelo_avaliacao', '')
+            modelo = get_model(modelo_nome) if modelo_nome else None
+            banco_dados_colunas = dados.get('banco_dados_colunas') or None
+
+            # ANEXO I - BANCO DE DADOS. Usa paisagem apenas quando as colunas
+            # selecionadas não cabem com legibilidade em retrato.
+            if not anexo_banco_dados_cabe_na_largura(
+                modelo,
+                banco_dados_colunas,
+                self._largura_util_secao_atual(doc),
+            ):
+                iniciar_secao_paisagem(doc)
+            self._criar_titulo_anexo(doc, "ANEXO I – BANCO DE DADOS")
+            gerar_anexo_banco_dados(doc, modelo, colunas=banco_dados_colunas)
+
+            # ANEXO II - PLANILHA DE CÁLCULO (volta para retrato)
+            iniciar_secao_retrato(doc)
+            self._criar_titulo_anexo(doc, "ANEXO II – PLANILHA DE CÁLCULO E RESULTADOS ESTATÍSTICOS")
+            gerar_anexo_planilha(doc, modelo)
+
+            # ANEXO III - GRÁFICOS
+            doc.add_page_break()
+            self._criar_titulo_anexo(doc, "ANEXO III – GRÁFICOS")
+            gerar_anexo_graficos(doc, modelo)
 
-        # ANEXO IV - CÁLCULO DO VALOR
-        doc.add_page_break()
-        self._criar_titulo_anexo(doc, "ANEXO IV – CÁLCULO DO VALOR")
-        gerar_anexo_calculo(doc, modelo)
+            # ANEXO IV - CÁLCULO DO VALOR
+            doc.add_page_break()
+            self._criar_titulo_anexo(doc, "ANEXO IV – CÁLCULO DO VALOR")
+            gerar_anexo_calculo(doc, modelo)
 
         # ANEXO V - DADOS E LOCALIZAÇÃO (placeholder manual)
         doc.add_page_break()

document/mesa_content.py

@@ -0,0 +1,16 @@
+"""Versioned documentary content extracted from MESA, never manually duplicated."""
+import json
+from functools import lru_cache
+from config.settings import BASE_DIR
+
+
+@lru_cache(maxsize=1)
+def current_content():
+    return json.loads((BASE_DIR / 'config/mesa_documentacao.json').read_text())
+
+
+def content_for(source):
+    saved = source.get('documentacaoTecnica') or {}
+    keys = ('notas','referencias','normas','redutores_termos','funcoes_mqc','criterios_fc','descricoes_modelo','requisitos_modelo')
+    valid = isinstance(saved,dict) and saved.get('versao') == 1 and saved.get('identificador') and all(key in saved for key in keys)
+    return saved if valid else current_content()

document/numbering.py

@@ -21,7 +21,7 @@ class NumeradorSecoes:
         Args:
             secao_inicial: Número inicial para seções (0 = começa em 1)
         """
-        self.contadores = [secao_inicial, 0, 0, 0]
+        self.contadores = [secao_inicial, 0, 0, 0, 0]
 
     def _reset_niveis_abaixo(self, nivel: int) -> None:
         """Reseta contadores de níveis abaixo do especificado."""
@@ -49,8 +49,14 @@ class NumeradorSecoes:
     def subsubsubsecao(self) -> str:
         """Incrementa e retorna número da sub-sub-subseção (ex: '1.1.1.1')."""
         self.contadores[3] += 1
+        self._reset_niveis_abaixo(3)
         return f"{self.contadores[0]}.{self.contadores[1]}.{self.contadores[2]}.{self.contadores[3]}"
 
+    def subsubsubsubsecao(self) -> str:
+        """Incrementa o quinto nível (ex: '3.3.2.2.1')."""
+        self.contadores[4] += 1
+        return '.'.join(map(str,self.contadores))
+
     def numero_atual(self, nivel: int = 0) -> str:
         """Retorna o número atual de um nível sem incrementar."""
         if nivel == 0:
@@ -59,8 +65,10 @@ class NumeradorSecoes:
             return f"{self.contadores[0]}.{self.contadores[1]}"
         elif nivel == 2:
             return f"{self.contadores[0]}.{self.contadores[1]}.{self.contadores[2]}"
-        else:
+        elif nivel == 3:
             return f"{self.contadores[0]}.{self.contadores[1]}.{self.contadores[2]}.{self.contadores[3]}"
+        else:
+            return '.'.join(map(str,self.contadores))
 
     def definir_secao(self, numero: int) -> None:
         """Define manualmente o número da seção atual."""

document/territorial_narrative.py

@@ -0,0 +1,253 @@
+"""Narrative from the recorded property conditions to the adopted land value.
+
+Percentages and effects come from the saved MESA assessment. Legal references
+identify the condition without replacing the historical percentages or results.
+"""
+from collections import OrderedDict
+import re
+import unicodedata
+
+from .evo_adjustments import REDUCERS, applied_reducers
+from .fundamentacao import number
+from .evolutivo import (source, terrain, result, ref, fmt, pct, complement,
+                        heading, add_body_text)
+
+# Original arts. 56, 60 and 61 and the 2019 wording of art. 88 checked on
+# 21/10/2026. Percentages remain those recorded in the assessment.
+DECREE_SOURCE = 'https://legislacao.portoalegre.rs.gov.br/media/sapl/public/normajuridica/sirel/Norma_16500_20091110_1.html'
+DECREE = 'Decreto Municipal nº 16.500, de 10 de novembro de 2009'
+AMENDMENT_SOURCE = 'https://dopaonlineupload.procempa.com.br/dopaonlineupload/3123_ce_272713_1.pdf'
+ARTICLE_88_DECREE = DECREE+', na redação dada pelo Decreto Municipal nº 20.396, de 11 de novembro de 2019'
+ARTICLE_88_LETTERS = {
+    'redutor88I': {'app': 'a', 'diretriz_logradouro': 'b', 'faixa_redes': 'c',
+                   'alta_tensao': 'd', 'ocupacoes_irregulares': 'e'},
+    'redutor88II': {'sem_agua': 'a', 'sem_luz': 'b', 'sem_esgoto': 'c', 'sem_pavimentacao': 'd'},
+}
+ALIASES = {
+    'app': ['APP', 'área de preservação permanente'],
+    'diretriz_logradouro': ['diretriz de logradouro', 'diretriz para implantação de logradouro'],
+    'faixa_redes': ['faixa não edificável', 'passagem de redes'],
+    'alta_tensao': ['alta tensão'],
+    'ocupacoes_irregulares': ['ocupação irregular', 'ocupações irregulares'],
+    'vila': ['imóvel em vila'], 'encravado': ['terreno encravado'],
+    'triangular_ate_1000': ['terreno triangular', 'terreno interno triangular'],
+    'topografia': ['topografia desfavorável', 'condições topográficas', 'declive', 'aclive', 'desnível'],
+    'agua': ['inundação', 'alagamento', 'enchente'],
+    'apan': ['APAN', 'área de proteção do ambiente natural', 'área de proteção ao ambiente natural'],
+}
+
+
+def normalized(text):
+    text = ''.join(c for c in unicodedata.normalize('NFKD',str(text)) if not unicodedata.combining(c))
+    return ' '.join(re.findall(r'[a-z0-9]+',text.casefold()))
+
+
+def condition_refs(labels, characteristics):
+    """Only refer to actual numbered headings; no guessed positional mapping."""
+    phrases = [normalized(label) for label in labels if normalized(label)]
+    matches = []
+    for item in characteristics:
+        title = ' '+normalized(item.get('titulo',''))+' '
+        if any(' '+phrase+' ' in title for phrase in phrases):
+            reference = item.get('referencia')
+            if reference and reference not in matches: matches.append(reference)
+    return matches
+
+
+def reference_sentence(labels, characteristics):
+    refs = condition_refs(labels,characteristics)
+    if not refs:
+        return 'Não há remissão específica a uma característica individualizada do capítulo 2.2 para esta condição.'
+    if len(refs)==1:
+        return f'A condição é examinada no item {refs[0]}, ao qual se remete sua caracterização.'
+    return 'As condições são examinadas nos itens '+join_words(refs)+', aos quais se remete sua caracterização.'
+
+
+def join_words(items):
+    return items[0] if len(items)==1 else ', '.join(items[:-1])+' e '+items[-1]
+
+
+def config_for(row):
+    return ((terrain(row).get('avaliacao') or {}).get('ajuste_territorial') or {}).get('configuracao') or {}
+
+
+def weighted_conditions(row):
+    catalog = (source(row).get('catalogoAjustes') or {}).get('art_88_i') or {}
+    config = config_for(row)
+    minimum = number(catalog.get('limite_minimo_area'))
+    if minimum is None: return []
+    conditions = []
+    for item in catalog.get('condicoes') or []:
+        code = item.get('codigo')
+        area = number(((config.get('art_88_i') or {}).get('condicoes',{}).get(code) or {}).get('percentual_area'))
+        rate = number(item.get('redutor',item.get('percentual_reducao')))
+        if area is not None and area>minimum and rate is not None and rate>0:
+            conditions.append((code,item.get('rotulo') or code,area,rate,minimum))
+    return conditions
+
+
+def scope(rows, selected):
+    if len(selected)==len(rows): return 'Para todas as referências avaliadas'
+    return 'Para '+join_words([ref(row) for row in selected])
+
+
+def grouped_prose(doc, rows, entries):
+    variants = OrderedDict()
+    for row,text in entries: variants.setdefault(text,[]).append(row)
+    for text,selected in variants.items():
+        add_body_text(doc,scope(rows,selected)+', '+text).paragraph_format.keep_together = True
+
+
+def legal_reference(key, codes=()):
+    if key in ARTICLE_88_LETTERS:
+        clause = 'I' if key == 'redutor88I' else 'II'
+        reference = f'art. 88, inciso {clause}'
+        mapping = ARTICLE_88_LETTERS[key]
+        # A missing/unknown condition must not inherit another condition's letter.
+        if codes and all(code in mapping for code in codes):
+            letters = list(dict.fromkeys('“'+mapping[code]+'”' for code in codes))
+            reference += (', alínea ' if len(letters)==1 else ', alíneas ')+join_words(letters)
+        return reference
+    if key in ('redutorTopografia', 'redutorAgua', 'apan'):
+        return 'art. 88, § 5º'
+    if key=='redutor6061':
+        articles = []
+        if 'vila' in codes: articles.append('art. 60, caput')
+        if 'encravado' in codes: articles.append('art. 61, inciso I')
+        if 'triangular_ate_1000' in codes: articles.append('art. 61, inciso II')
+        return join_words(articles) if articles else ''
+    return ''
+
+
+def legal_basis(key, codes=()):
+    reference = legal_reference(key, codes)
+    if not reference:
+        return 'A memória não identifica a hipótese legal deste ajuste; o fundamento específico não pode ser atribuído apenas a partir do resultado numérico.'
+    if key=='redutor6061':
+        return f'O enquadramento da configuração do terreno fundamenta-se no {reference} do {DECREE}. O art. 56, parágrafo único, admite que a correção seja efetuada no preço do metro quadrado, pelos mesmos coeficientes.'
+    text = f'O tratamento desta condição fundamenta-se no {reference} do {ARTICLE_88_DECREE}.'
+    if key in ('redutorTopografia', 'redutorAgua', 'apan'):
+        text += ' O dispositivo admite a identificação particularizada de outras hipóteses de desvalorização e a avaliação de seu impacto, desde que fundamentadas tecnicamente.'
+    return text
+
+
+def reducer_parts(row, key, label, rate):
+    """Split only documented, effective conditions, without revaluing the land."""
+    saved = source(row).get('catalogoAjustes') or {}
+    config = config_for(row)
+    if key=='redutor88I':
+        parts = []
+        for code,name,area,reference_rate,minimum in weighted_conditions(row):
+            text = f'a condição {name} foi considerada sobre {pct(area,True)} da área territorial. O percentual de referência registrado é de {pct(reference_rate,True)} sobre a parcela atingida; sua contribuição ponderada corresponde a {pct(area*reference_rate,True)} do valor unitário. O atingimento supera o limiar de {pct(minimum,True)} registrado para a incidência do ajuste.'
+            parts.append((key+':'+code,name,[name]+ALIASES.get(code,[]),text,[code]))
+        if parts: return parts
+    elif key=='redutor6061':
+        codes = (config.get('art_60_61') or {}).get('selecionados') or []
+        choices = [item for item in (saved.get('art_60_61') or {}).get('condicoes',[])
+                   if item.get('codigo') in codes and number(item.get('redutor'))==rate]
+        if choices:
+            names = [item.get('rotulo') or item['codigo'] for item in choices]
+            labels = names+[alias for item in choices for alias in ALIASES.get(item['codigo'],[])]
+            return [(key,'Configuração do terreno',labels,f'considerou-se {join_words(names)}, aplicando-se a redução de {pct(rate,True)} ao valor unitário territorial. Entre as condições selecionadas nos arts. 60 e 61, este é o maior percentual efetivamente utilizado; os percentuais não são somados.',[item['codigo'] for item in choices])]
+    elif key=='redutorTopografia':
+        descriptions,labels = [],[]
+        for part,rate_key in [('relevo','redutorRelevo'),('nivel_rua','redutorNivel')]:
+            code = (config.get('topografia') or {}).get(part)
+            item = next((item for item in (saved.get('topografia') or {}).get(part,[]) if item.get('codigo')==code),{})
+            part_rate = number(result(row).get(rate_key)) if rate_key in result(row) else number(item.get('redutor'))
+            if item and part_rate is not None and part_rate>0:
+                name = item.get('rotulo') or code
+                labels.append(name);descriptions.append(f'{name} ({pct(part_rate,True)})')
+        if descriptions:
+            return [(key,'Condições topográficas',labels+ALIASES['topografia'],f'foram consideradas as condições {join_words(descriptions)}. Suas parcelas integram o ajuste topográfico, cuja redução efetiva registrada é de {pct(rate,True)} do valor unitário territorial.',[])]
+    elif key=='redutorAgua':
+        code = (config.get('agua') or {}).get('situacao')
+        item = next((item for item in (saved.get('agua') or {}).get('condicoes',[]) if item.get('codigo')==code),{})
+        if item:
+            name = item.get('rotulo') or code
+            return [(key,'Inundação e ação da água',[name]+ALIASES['agua'],f'a situação considerada foi {name}, com redução efetiva de {pct(rate,True)} do valor unitário territorial.',[])]
+    # A missing catalog or breakdown must not be replaced with today's rates.
+    text = f'o resultado da avaliação registra redução de {pct(rate,True)} do valor unitário territorial.' if rate is not None else 'o arquivo registra esta etapa de ajuste, mas não preserva seu percentual efetivo.'
+    return [(key,label,[label],text+' A condição específica e os parâmetros de incidência não foram preservados em detalhe.',[])]
+
+
+def summarize_restrictions(doc,rows):
+    entries = []
+    for row in rows:
+        active = {key:rate for key,label,rate in applied_reducers(row,True)}
+        if 'redutor88I' not in active: continue
+        rate = active['redutor88I']
+        text = f'consideradas em conjunto as restrições ponderadas pela área, a redução efetiva registrada é de {pct(rate,True)} do valor unitário territorial.'
+        conditions = weighted_conditions(row)
+        weighted = sum(area*reference for code,name,area,reference,minimum in conditions)
+        if conditions and rate is not None and abs(weighted-rate)>number('0.000000001'):
+            text += ' A soma das contribuições ponderadas não coincide com esse percentual salvo; a divergência requer conferência, preservando-se o resultado de origem.'
+        entries.append((row,text))
+    grouped_prose(doc,rows,entries)
+
+
+def gerar_ajustes_territoriais(doc, rows, num, characteristics):
+    groups = OrderedDict()
+    for row in rows:
+        for key,label,rate in applied_reducers(row,True):
+            for identity,title,labels,text,codes in reducer_parts(row,key,label,rate):
+                groups.setdefault(identity,[]).append((row,key,title,labels,text,codes))
+    if groups:
+        add_body_text(doc,'A passagem da estimativa do modelo ao valor territorial adotado considera as condições particulares do imóvel examinadas no capítulo 2.2. Cada ajuste efetivamente aplicado é fundamentado nos itens seguintes, com indicação da condição de incidência e do percentual utilizado em cada referência.')
+        if any(identity.startswith('redutor88I:') for identity in groups):
+            add_body_text(doc,'As contribuições das restrições ponderadas pela área são somadas para formar um único redutor. Esse fator participa da composição multiplicativa com os demais ajustes territoriais, antes da escolha do valor no campo de arbítrio.')
+        order = {key:i for i,key in enumerate(REDUCERS)}
+        ordered = sorted(groups.items(),key=lambda pair:order.get(pair[0].split(':',1)[0],len(order)))
+        restrictions = [identity for identity in groups if identity.startswith('redutor88I:')]
+        for identity,entries in ordered:
+            first = entries[0]
+            heading(doc,num,first[2],5)
+            # Group the full narrative so historical labels or legal hypotheses
+            # are never silently borrowed from another exercise.
+            variants = OrderedDict()
+            for row,key,title,labels,text,codes in entries:
+                opening = reference_sentence(labels,characteristics)+' '+legal_basis(key,codes)
+                variants.setdefault(opening,[]).append((row,text))
+            for opening,details in variants.items():
+                add_body_text(doc,opening).paragraph_format.keep_with_next = True
+                grouped_prose(doc,rows,details)
+            if restrictions and identity==restrictions[-1]:
+                summarize_restrictions(doc,rows)
+    else:
+        add_body_text(doc,'O resultado salvo não registra redutores territoriais com efeito identificado. A passagem ao valor adotado considera a escolha no campo de arbítrio e a área de aplicação, demonstradas a seguir.')
+    campo_arbitrio(doc,rows,num,characteristics)
+
+
+def campo_arbitrio(doc, rows, num, characteristics):
+    active = [row for row in rows if number(result(row).get('fatorCaFinal')) not in (None,1)]
+    # A public choice justification can matter even when the final factor is 1.
+    justified = any((row.get('complementos') or {}).get('justificativa_vu') for row in rows)
+    if not active and not justified: return
+    heading(doc,num,'Escolha do valor no campo de arbítrio',5)
+    add_body_text(doc,'Após a incidência dos ajustes territoriais, a escolha do valor unitário é tratada no campo de arbítrio da estimativa, no âmbito da metodologia da ABNT NBR 14653-2. O fator adotado expressa essa decisão técnica e deve ser lido em conjunto com sua justificativa.')
+    apan = [row for row in active if (number(result(row).get('redutorApan')) or 0)>0]
+    if apan:
+        add_body_text(doc,reference_sentence(ALIASES['apan'],characteristics)+' '+legal_basis('apan')+' A influência da APAN participa desta decisão, sem constituir um redutor autônomo a ser descontado novamente.')
+        grouped_prose(doc,rows,[(row,f'a área atingida por APAN é de {pct((config_for(row).get("apan") or {}).get("percentual_area"),True)}, com referência de influência de {pct(result(row).get("redutorApan"),True)}. O fator final escolhido para o campo de arbítrio é {fmt(result(row).get("fatorCaFinal"),4)}.') for row in apan])
+    entries = []
+    for row in rows:
+        factor = number(result(row).get('fatorCaFinal'))
+        reason = complement(row,'justificativa_vu','')
+        if factor in (None,1) and not reason: continue
+        text = f'o fator do campo de arbítrio adotado foi {fmt(factor,4)}. ' if factor is not None else 'o fator do campo de arbítrio não foi preservado no arquivo. '
+        text += 'A justificativa técnica registrada para essa escolha é: '+reason if reason else 'A justificativa técnica dessa escolha não foi informada no arquivo.'
+        entries.append((row,text))
+    grouped_prose(doc,rows,entries)
+
+
+def justificar_area(doc,rows):
+    entries = []
+    for row in rows:
+        model_area = number(terrain(row).get('areaModelo',row['avaliacao'].get('valor_area')))
+        area = number(row.get('area'))
+        if model_area is None or area is None or model_area==area: continue
+        reason = complement(row,'justificativa_area','')
+        text = f'o modelo utilizou a área de {fmt(model_area)} m² para estimar o valor unitário, enquanto sua aplicação ao imóvel considerou {fmt(area)} m². '
+        text += 'A distinção de áreas foi justificada nos seguintes termos: '+reason if reason else 'A justificativa para a distinção de áreas não foi informada no arquivo.'
+        entries.append((row,text))
+    grouped_prose(doc,rows,entries)

frontend/package.json

@@ -4,6 +4,7 @@
   "version": "0.1.0",
   "type": "module",
   "scripts": {
+    "test": "node --test tests/*.test.mjs",
     "dev": "vite",
     "build": "vite build",
     "preview": "vite preview --host 0.0.0.0 --port 4173"

frontend/src/App.jsx

@@ -1,4 +1,8 @@
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
+
+import ImportacaoAvaliacoes from "./ImportacaoAvaliacoes";
+import RevisaoAvaliacao from "./RevisaoAvaliacao";
+import { adoptedValues, applyImportDefaults, importDefaults, REVIEW_FIELDS } from "./importDefaults";
 
 const API_BASE = (
   import.meta.env.VITE_API_BASE_URL ||
@@ -6,27 +10,16 @@ const API_BASE = (
 ).trim();
 
 const TAB_LABELS = [
+  "Início · Importar avaliação",
   "1. Solicitação",
   "2. Documentação",
   "3. Motivos Desvalorizantes",
   "4. Imóvel Objeto",
   "5. Avaliação",
-  "6. Valores de Mercado",
-  "7. Registro Fotográfico",
-  "8. Gerar Documento",
+  "6. Registro Fotográfico",
+  "7. Gerar Documento",
 ];
 
-const DEFAULT_UNSELECTED_COLUMNS = new Set([
-  "REGISTRO",
-  "IMO-INSC",
-  "CTM",
-  "NUMERO",
-  "NUM",
-  "UNIDADE",
-  "COMPLEMENTO",
-  "COMPL",
-]);
-
 const emptyMotivo = {
   descricao: "",
   alegado: true,
@@ -43,8 +36,7 @@ const normalizeApiUrl = (path) => {
   return `${base}${route}`;
 };
 
-const isSelectedByDefault = (columnName) =>
-  !DEFAULT_UNSELECTED_COLUMNS.has(String(columnName).trim().toLocaleUpperCase("pt-BR"));
+
 
 const applyCurrencyMask = (value) => {
   if (!value) {
@@ -166,10 +158,13 @@ const applyDummyToForm = (base, dummy) => {
 function App() {
   const [options, setOptions] = useState(null);
   const [form, setForm] = useState(null);
-  const [activeTab, setActiveTab] = useState(0);
+  const [activeTab, setActiveTab] = useState(-1);
+  const editedFields = useRef(new Set());
+  const previousDefaults = useRef({});
 
-  const [anoInicial, setAnoInicial] = useState(2020);
-  const [anoFinal, setAnoFinal] = useState(new Date().getFullYear());
+  const [importacao, setImportacao] = useState(null);
+  const [importEpoch, setImportEpoch] = useState(0);
+  const [loadingImport, setLoadingImport] = useState(false);
 
   const [pdfFile, setPdfFile] = useState(null);
   const [registroFotoFile, setRegistroFotoFile] = useState(null);
@@ -177,9 +172,7 @@ function App() {
   const [loadingOptions, setLoadingOptions] = useState(true);
   const [loadingPdf, setLoadingPdf] = useState(false);
   const [loadingGenerate, setLoadingGenerate] = useState(false);
-  const [loadingYears, setLoadingYears] = useState(false);
-  const [loadingColumns, setLoadingColumns] = useState(false);
-  const [databaseColumns, setDatabaseColumns] = useState([]);
+
 
   const [error, setError] = useState("");
   const [pdfWarnings, setPdfWarnings] = useState([]);
@@ -201,8 +194,7 @@ function App() {
 
         setForm(buildEmptyForm(payload));
 
-        setAnoInicial(payload.defaults?.ano_inicial_mercado ?? 2020);
-        setAnoFinal(payload.defaults?.ano_final_mercado ?? new Date().getFullYear());
+
       } catch (err) {
         setError(String(err));
       } finally {
@@ -220,82 +212,28 @@ function App() {
     return normalizeApiUrl(result.download_url);
   }, [result]);
 
-  const limits = options?.limits || {};
-  const selectedColumns = useMemo(
-    () => databaseColumns.filter((column) => column.selected).map((column) => column.name),
-    [databaseColumns],
-  );
-
   useEffect(() => {
-    const modelName = form?.modelo_avaliacao;
-    if (!modelName) {
-      setDatabaseColumns([]);
-      return undefined;
-    }
-
-    const controller = new AbortController();
-    const loadColumns = async () => {
-      setLoadingColumns(true);
-      try {
-        const response = await fetch(
-          normalizeApiUrl(`/api/models/${encodeURIComponent(modelName)}/columns`),
-          { signal: controller.signal },
-        );
-        const payload = await response.json();
-        if (!response.ok) {
-          throw new Error(payload.detail || "Não foi possível carregar as colunas do modelo.");
-        }
-        setDatabaseColumns(
-          (payload.columns || []).map((name) => ({ name, selected: isSelectedByDefault(name) })),
-        );
-      } catch (err) {
-        if (err.name !== "AbortError") {
-          setDatabaseColumns([]);
-          setError(String(err));
-        }
-      } finally {
-        if (!controller.signal.aborted) {
-          setLoadingColumns(false);
-        }
-      }
-    };
+    const defaults = importDefaults(importacao);
+    const previous = previousDefaults.current;
+    setForm((current) => applyImportDefaults(current, defaults, previous, editedFields.current));
+    previousDefaults.current = defaults;
+  }, [importacao]);
+
+  const handleImportChange = (value) => {
+    setImportacao(value);
+    setResult(null);
+    setError("");
+  };
 
-    loadColumns();
-    return () => controller.abort();
-  }, [form?.modelo_avaliacao]);
+  useEffect(() => { setResult(null); }, [form, registroFotoFile]);
 
+  const limits = options?.limits || {};
   const updateField = (field, value) => {
+    editedFields.current.add(field);
+    setResult(null);
     setForm((prev) => ({ ...prev, [field]: value }));
   };
 
-  const toggleDatabaseColumn = (columnName) => {
-    setDatabaseColumns((current) =>
-      current.map((column) =>
-        column.name === columnName ? { ...column, selected: !column.selected } : column,
-      ),
-    );
-  };
-
-  const moveDatabaseColumn = (index, direction) => {
-    setDatabaseColumns((current) => {
-      const targetIndex = index + direction;
-      if (targetIndex < 0 || targetIndex >= current.length) {
-        return current;
-      }
-      const next = [...current];
-      [next[index], next[targetIndex]] = [next[targetIndex], next[index]];
-      return next;
-    });
-  };
-
-  const selectAllDatabaseColumns = () => {
-    setDatabaseColumns((current) => current.map((column) => ({ ...column, selected: true })));
-  };
-
-  const clearDatabaseColumns = () => {
-    setDatabaseColumns((current) => current.map((column) => ({ ...column, selected: false })));
-  };
-
   const updateStringList = (field, index, value) => {
     setForm((prev) => {
       const list = [...prev[field]];
@@ -323,6 +261,8 @@ function App() {
   };
 
   const updateMotivo = (index, patch) => {
+    editedFields.current.add('motivos_desvalorizantes');
+    setResult(null);
     setForm((prev) => {
       const next = [...prev.motivos_desvalorizantes];
       next[index] = { ...next[index], ...patch };
@@ -331,6 +271,7 @@ function App() {
   };
 
   const addMotivo = () => {
+    editedFields.current.add('motivos_desvalorizantes');
     setForm((prev) => {
       if (prev.motivos_desvalorizantes.length >= limits.max_motivos_desvalorizantes) {
         return prev;
@@ -343,6 +284,7 @@ function App() {
   };
 
   const removeMotivo = () => {
+    editedFields.current.add('motivos_desvalorizantes');
     setForm((prev) => {
       if (prev.motivos_desvalorizantes.length <= 1) {
         return prev;
@@ -354,50 +296,6 @@ function App() {
     });
   };
 
-  const updateValorMercado = (index, patch) => {
-    setForm((prev) => {
-      const next = [...prev.valores_mercado];
-      next[index] = { ...next[index], ...patch };
-      return { ...prev, valores_mercado: next };
-    });
-  };
-
-  const handleGenerateYears = async () => {
-    setLoadingYears(true);
-    setError("");
-
-    try {
-      const response = await fetch(normalizeApiUrl("/api/market-values/generate"), {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          ano_inicial: Number(anoInicial),
-          ano_final: Number(anoFinal),
-        }),
-      });
-
-      if (!response.ok) {
-        const body = await response.json().catch(() => ({}));
-        throw new Error(body.detail || "Erro ao gerar anos.");
-      }
-
-      const payload = await response.json();
-      setForm((prev) => ({
-        ...prev,
-        valores_mercado: payload.anos.map((ano) => ({ ano, valor: "" })),
-        datas_referencia: payload.referencias || "",
-      }));
-    } catch (err) {
-      setError(String(err));
-    } finally {
-      setLoadingYears(false);
-    }
-  };
-
-  const handleClearYears = () => {
-    setForm((prev) => ({ ...prev, valores_mercado: [], datas_referencia: "" }));
-  };
-
   const handleExtractPdf = async () => {
     if (!pdfFile) {
       setError("Selecione um arquivo PDF antes de processar.");
@@ -458,6 +356,8 @@ function App() {
       return;
     }
 
+    setResult(null);
+
     setForm((prev) => {
       const dropdowns = options.dropdowns || {};
       const demoBase = {
@@ -470,25 +370,37 @@ function App() {
         metodo_avaliacao: dropdowns.metodos_avaliacao?.[0] || prev.metodo_avaliacao,
         modelo_avaliacao: options.models?.[0] || prev.modelo_avaliacao,
       };
-      return applyDummyToForm(demoBase, options.dummy);
+      const example = applyDummyToForm(demoBase, options.dummy);
+      if (importacao) {
+        for (const field of [...REVIEW_FIELDS, 'motivos_desvalorizantes']) example[field] = prev[field];
+      }
+      return example;
     });
   };
 
   const handleClearForm = () => {
+    editedFields.current.clear();
+    previousDefaults.current = {};
     setForm(buildEmptyForm(options));
-    setDatabaseColumns([]);
+    setImportacao(null);
+    setPdfFile(null);
+    setRegistroFotoFile(null);
+    setImportEpoch((current) => current + 1);
     setError("");
     setPdfWarnings([]);
     setResult(null);
+    setActiveTab(-1);
   };
 
   const handleGenerateDocument = async () => {
-    if (loadingColumns) {
-      setError("Aguarde o carregamento das colunas do banco de dados.");
+    if (loadingImport || !importacao) {
+      setError("Importe um arquivo .ame ou .evo antes de gerar o documento.");
+      setActiveTab(-1);
       return;
     }
-    if (databaseColumns.length > 0 && selectedColumns.length === 0) {
-      setError("Selecione ao menos uma coluna para o Anexo I - Banco de Dados.");
+    if (importacao.preview.avaliacoes.some((item) => !/^(19|20|21)\d{2}$/.test(importacao.anos[item.id] || ''))) {
+      setError("Informe o ano de todas as avaliações na etapa inicial de importação.");
+      setActiveTab(-1);
       return;
     }
 
@@ -502,12 +414,15 @@ function App() {
         documentacao_padrao: form.documentacao_padrao.filter((item) => item.trim()),
         documentacao_especifica: form.documentacao_especifica.filter((item) => item.trim()),
         motivos_desvalorizantes: form.motivos_desvalorizantes.filter((item) => item.descricao.trim()),
-        valores_mercado: form.valores_mercado.filter((item) => item.ano && item.valor),
-        banco_dados_colunas: selectedColumns,
+        valores_mercado: [],
+        banco_dados_colunas: null,
+        importacao_avaliacoes: { referencia_anos: importacao.referenciaAnos, anos: importacao.anos, objeto_modelo: importacao.objeto,
+          valores_adotados: adoptedValues(importacao), complementos: importacao.complementos || {}, campos_editados: REVIEW_FIELDS.filter((field) => editedFields.current.has(field)) },
       };
 
       const formData = new FormData();
       formData.append("payload", JSON.stringify(payload));
+      formData.append("arquivo_avaliacoes", importacao.file);
       if (registroFotoFile) {
         formData.append("registro_fotografico", registroFotoFile);
       }
@@ -524,7 +439,7 @@ function App() {
 
       const generated = await response.json();
       setResult(generated);
-      setActiveTab(7);
+      setActiveTab(6);
     } catch (err) {
       setError(String(err));
     } finally {
@@ -563,8 +478,8 @@ function App() {
             <button
               key={label}
               type="button"
-              className={index === activeTab ? "tab-btn active" : "tab-btn"}
-              onClick={() => setActiveTab(index)}
+              className={index - 1 === activeTab ? "tab-btn active" : "tab-btn"}
+              onClick={() => setActiveTab(index - 1)}
             >
               {label}
             </button>
@@ -572,6 +487,14 @@ function App() {
         </nav>
 
         <main className="tab-panel">
+        {activeTab === -1 && (
+          <section className="form-section">
+            <h2>Comece pela avaliação</h2>
+            <p className="muted-message">Importe o arquivo da MESA para preencher os motivos desvalorizantes e os dados da avaliação. Os campos continuarão editáveis nas etapas seguintes; suas alterações manuais serão preservadas.</p>
+            <ImportacaoAvaliacoes key={importEpoch} value={importacao} onChange={handleImportChange} onLoading={setLoadingImport} apiUrl={normalizeApiUrl} />
+            <button type="button" className="primary-btn" disabled={!importacao || loadingImport} onClick={() => setActiveTab(0)}>Continuar para a solicitação</button>
+          </section>
+        )}
         {activeTab === 0 && (
           <section className="form-section">
             <h2>Dados Gerais</h2>
@@ -733,7 +656,8 @@ function App() {
 
         {activeTab === 2 && (
           <section className="form-section">
-            <h2>Motivos Desvalorizantes Alegados</h2>
+            <h2>Motivos Desvalorizantes</h2>
+            <p className="muted-message">As condições identificadas na avaliação vêm preenchidas por padrão. Revise a descrição e indique quais foram alegadas pelo contribuinte e confirmadas na análise.</p>
             {form.motivos_desvalorizantes.map((item, index) => (
               <div key={`motivo-${index}`} className="motivo-row">
                 <input
@@ -884,6 +808,7 @@ function App() {
                   value={form.unidade_responsavel}
                   onChange={(event) => updateField("unidade_responsavel", event.target.value)}
                 >
+                  <option value="">Selecione a unidade responsável</option>
                   {options.dropdowns.unidades_responsaveis.map((item) => (
                     <option key={item} value={item}>
                       {item}
@@ -909,6 +834,7 @@ function App() {
                   value={form.tecnico_responsavel}
                   onChange={(event) => updateField("tecnico_responsavel", event.target.value)}
                 >
+                  <option value="">Selecione o técnico responsável</option>
                   {options.dropdowns.tecnicos_responsaveis.map((item) => (
                     <option key={item} value={item}>
                       {item}
@@ -927,171 +853,11 @@ function App() {
               )}
             </div>
 
-            <div className="grid-2">
-              <label>
-                Método de Avaliação
-                <select
-                  value={form.metodo_avaliacao}
-                  onChange={(event) => updateField("metodo_avaliacao", event.target.value)}
-                >
-                  {options.dropdowns.metodos_avaliacao.map((item) => (
-                    <option key={item} value={item}>
-                      {item}
-                    </option>
-                  ))}
-                </select>
-              </label>
-              {form.metodo_avaliacao === "Outros" && (
-                <label>
-                  Especifique
-                  <input
-                    value={form.metodo_avaliacao_custom}
-                    onChange={(event) => updateField("metodo_avaliacao_custom", event.target.value)}
-                  />
-                </label>
-              )}
-            </div>
-
-            <label>
-              Modelo de Avaliação (.dai)
-              <select
-                value={form.modelo_avaliacao}
-                onChange={(event) => updateField("modelo_avaliacao", event.target.value)}
-              >
-                {options.models.length === 0 && <option value="">Nenhum modelo encontrado</option>}
-                {options.models.map((item) => (
-                  <option key={item} value={item}>
-                    {item}
-                  </option>
-                ))}
-              </select>
-            </label>
-
-            <div className="columns-section">
-              <div className="columns-heading">
-                <div>
-                  <h3>Colunas do Anexo I - Banco de Dados</h3>
-                  <p className="muted-message">
-                    Selecione e ordene as colunas que serão exibidas no anexo do modelo.
-                  </p>
-                </div>
-                <span className="columns-counter">{selectedColumns.length} selecionadas</span>
-              </div>
-
-              <div className="inline-buttons">
-                <button type="button" onClick={selectAllDatabaseColumns} disabled={loadingColumns}>
-                  Todas
-                </button>
-                <button type="button" onClick={clearDatabaseColumns} disabled={loadingColumns}>
-                  Nenhuma
-                </button>
-              </div>
-
-              {loadingColumns ? (
-                <p className="muted-message">Carregando colunas do modelo...</p>
-              ) : (
-                <div className="columns-list">
-                  {databaseColumns.map((column, index) => (
-                    <div className="column-row" key={column.name}>
-                      <label className="checkbox-line">
-                        <input
-                          type="checkbox"
-                          checked={column.selected}
-                          onChange={() => toggleDatabaseColumn(column.name)}
-                        />
-                        {column.name}
-                      </label>
-                      <div className="column-order-actions">
-                        <button
-                          type="button"
-                          onClick={() => moveDatabaseColumn(index, -1)}
-                          disabled={index === 0}
-                          aria-label={`Mover ${column.name} para cima`}
-                        >
-                          ↑
-                        </button>
-                        <button
-                          type="button"
-                          onClick={() => moveDatabaseColumn(index, 1)}
-                          disabled={index === databaseColumns.length - 1}
-                          aria-label={`Mover ${column.name} para baixo`}
-                        >
-                          ↓
-                        </button>
-                      </div>
-                    </div>
-                  ))}
-                </div>
-              )}
-            </div>
+            <RevisaoAvaliacao form={form} onFieldChange={updateField} value={importacao} onChange={handleImportChange} onImport={() => setActiveTab(-1)} />
           </section>
         )}
 
         {activeTab === 5 && (
-          <section className="form-section">
-            <h2>Definir Intervalo de Anos</h2>
-            <div className="grid-3">
-              <label>
-                Ano Inicial
-                <input
-                  type="number"
-                  value={anoInicial}
-                  onChange={(event) => setAnoInicial(event.target.value)}
-                />
-              </label>
-              <label>
-                Ano Final
-                <input
-                  type="number"
-                  value={anoFinal}
-                  onChange={(event) => setAnoFinal(event.target.value)}
-                />
-              </label>
-              <div className="inline-buttons">
-                <button type="button" onClick={handleGenerateYears} disabled={loadingYears}>
-                  {loadingYears ? "Gerando..." : "Gerar Campos"}
-                </button>
-                <button type="button" onClick={handleClearYears}>
-                  Limpar
-                </button>
-              </div>
-            </div>
-
-            <h2>Valores por Ano</h2>
-            {form.valores_mercado.length === 0 && (
-              <p className="muted-message">Nenhum ano gerado ainda. Defina o intervalo acima.</p>
-            )}
-            {form.valores_mercado.map((item, index) => (
-              <div key={`vm-${index}`} className="grid-2 compact-row">
-                <label>
-                  Ano
-                  <input value={item.ano} disabled readOnly />
-                </label>
-                <label>
-                  Valor (R$)
-                  <input
-                    value={item.valor}
-                    onChange={(event) => updateValorMercado(index, { valor: event.target.value })}
-                    onBlur={(event) =>
-                      updateValorMercado(index, { valor: applyCurrencyMask(event.target.value) })
-                    }
-                    placeholder="R$ 0,00"
-                  />
-                </label>
-              </div>
-            ))}
-
-            <label>
-              Datas de Referência
-              <input
-                value={form.datas_referencia}
-                onChange={(event) => updateField("datas_referencia", event.target.value)}
-              />
-            </label>
-          </section>
-        )}
-
-        {activeTab === 6 && (
           <section className="form-section">
             <h2>Registro Fotográfico</h2>
             <p className="muted-message">
@@ -1108,11 +874,11 @@ function App() {
           </section>
         )}
 
-        {activeTab === 7 && (
+        {activeTab === 6 && (
           <section className="form-section">
             <h2>Gerar Laudo de Avaliação</h2>
             <p className="muted-message">Confira as abas anteriores e execute a geração do documento.</p>
-            <button type="button" className="primary-btn" onClick={handleGenerateDocument} disabled={loadingGenerate}>
+            <button type="button" className="primary-btn" onClick={handleGenerateDocument} disabled={loadingGenerate || loadingImport || !importacao}>
               {loadingGenerate ? "Gerando Documento..." : "Gerar Documento"}
             </button>
 

frontend/src/EvolutivoReview.jsx

@@ -0,0 +1,63 @@
+const fields = [
+  ['justificativa_vu', 'Escolha do valor unitário e do campo de arbítrio'],
+  ['justificativa_area', 'Diferença entre área do modelo e área de aplicação'],
+  ['justificativa_fc', 'Escolha do fator de comercialização'],
+  ['ajustes_nao_aplicados', 'Ajustes expressamente não aplicados e justificativa'],
+];
+const gradeOptions = ['', 'Grau III', 'Grau II', 'Grau I', 'Sem enquadramento'];
+export const documentaryValues = (value, row) => ({ ...row.complementos, ...value.complementos?.[row.id],
+  bdi: { ...row.complementos?.bdi, ...value.complementos?.[row.id]?.bdi },
+  requisitos_grau_iii: { ...row.complementos?.requisitos_grau_iii, ...value.complementos?.[row.id]?.requisitos_grau_iii } });
+
+export default function EvolutivoReview({ value, row, onChange, changed }) {
+  if (value.preview.tipo !== 'evolutivo') return null;
+  const current = documentaryValues(value, row);
+  const review = row.revisao_documental || {};
+  const set = (key, text) => onChange({ ...value, complementos: { ...value.complementos, [row.id]: { ...current, [key]: text } } });
+  const reuse = (key) => {
+    const next = { ...value.complementos };
+    for (const target of value.preview.avaliacoes) next[target.id] = { ...documentaryValues(value, target), [key]: current[key] };
+    onChange({ ...value, complementos: next });
+  };
+  const reuseBdi = (construction) => {
+    const next = { ...value.complementos };
+    for (const target of value.preview.avaliacoes) {
+      const matches = (target.revisao_documental?.construcoes || []).filter((item) => item.grupo === construction.grupo);
+      if (matches.length !== 1) continue;
+      const saved = documentaryValues(value,target);
+      next[target.id] = { ...saved, bdi: { ...saved.bdi, [matches[0].id]: current.bdi?.[construction.id] || '' } };
+    }
+    onChange({ ...value, complementos: next });
+  };
+  return <details className="evolutivo-review">
+    <summary>Revisar fundamentos e complementos desta avaliação</summary>
+    <p>As definições técnicas de CUB, BDI, depreciação e redutores são incluídas automaticamente a partir da MESA. Aqui entram as decisões específicas do trabalho. Campos ausentes ficam identificados como pendentes no laudo.</p>
+    <p>Área do modelo: {review.area_modelo ?? 'não informada'} m² · Área de aplicação: {review.area_aplicacao ?? 'não informada'} m²</p>
+    <p>Enquadramentos na origem: terreno {review.fundamentacao?.terrain || 'pendente'}; construções {review.fundamentacao?.construction || 'pendente'}; global {review.fundamentacao?.global || 'pendente'}. As alterações serão consideradas na geração.</p>
+    {!!review.pendencias?.length && <p className="muted-message">Lacunas identificadas no arquivo: {review.pendencias.join('; ')}.</p>}
+    {(review.conferencias || []).map((warning, index) => <p role="status" className="muted-message" key={index}>{warning}</p>)}
+    {fields.map(([key, label]) => <div className="documentary-field" key={key}>
+      <label>{label}<textarea rows={3} value={current[key] || ''} onChange={(event) => set(key, event.target.value)} placeholder="Complemento específico do avaliador" /></label>
+      {value.preview.avaliacoes.length > 1 && <button type="button" disabled={!current[key]} onClick={() => reuse(key)}>Usar esta justificativa nos demais exercícios</button>}
+    </div>)}
+    <h5>BDI por construção</h5>
+    {(review.construcoes || []).map((construction) => <div key={construction.id}><label>{construction.nome} · BDI {construction.bdi ?? 'não informado'}% — justificativa
+      <textarea rows={3} value={current.bdi?.[construction.id] || ''} onChange={(event) => set('bdi', { ...current.bdi, [construction.id]: event.target.value })} />
+    </label>{value.preview.avaliacoes.length > 1 && <button type="button" disabled={!current.bdi?.[construction.id]} onClick={() => reuseBdi(construction)}>Usar para esta sequência nos demais exercícios</button>}</div>)}
+    {changed && <label>Critério do valor final adotado<textarea rows={3} value={current.criterio_adocao || ''} onChange={(event) => set('criterio_adocao', event.target.value)} placeholder="Explique a diferença em relação ao resultado calculado" /></label>}
+    <h5>Critérios de fundamentação do terreno</h5>
+    <p className="muted-message">A precisão e o critério de extrapolação não substituem a fundamentação completa. Os demais critérios automáticos usam as evidências estatísticas preservadas.</p>
+    {[['caracterizacao', 'Caracterização do avaliando'], ['identificacao', 'Identificação dos dados de mercado']].map(([prefix, label]) => <div className="grid-2" key={prefix}>
+      <label>{label}<select value={current[`${prefix}_grau`] || ''} onChange={(event) => set(`${prefix}_grau`, event.target.value)}>{gradeOptions.map((grade) => <option key={grade} value={grade}>{grade || 'Não informado'}</option>)}</select></label>
+      <label>Justificativa de {label.toLowerCase()}<textarea rows={2} value={current[`${prefix}_justificativa`] || ''} onChange={(event) => set(`${prefix}_justificativa`, event.target.value)} /></label>
+    </div>)}
+    <details><summary>Requisitos adicionais para Grau III do terreno</summary>
+      {(review.requisitos_modelo || []).map((requirement) => <label key={requirement.key}>{requirement.label}<select value={current.requisitos_grau_iii?.[requirement.key] === true ? 'sim' : current.requisitos_grau_iii?.[requirement.key] === false ? 'nao' : current.requisitos_grau_iii?.[requirement.key] || ''} onChange={(event) => set('requisitos_grau_iii', { ...current.requisitos_grau_iii, [requirement.key]: event.target.value })}>
+        <option value="">Não informado</option><option value="sim">Sim</option><option value="nao">Não</option>
+      </select></label>)}
+    </details>
+    <label>Critério de fundamentação do fator de comercialização<select value={current.fc_criterio || ''} onChange={(event) => set('fc_criterio', event.target.value)}>
+      <option value="">Não informado</option>{(review.criterios_fc || []).map((option) => <option key={option.value} value={option.value}>{option.label}</option>)}
+    </select></label>
+  </details>;
+}

frontend/src/ImportacaoAvaliacoes.jsx

@@ -0,0 +1,89 @@
+import { useEffect, useRef, useState } from 'react';
+
+const reais = (value) => value == null ? '—' : Number(value).toLocaleString('pt-BR', { style: 'currency', currency: 'BRL' });
+
+export default function ImportacaoAvaliacoes({ value, onChange, onLoading, apiUrl }) {
+  const request = useRef(null);
+  const [error, setError] = useState('');
+  const [busy, setBusy] = useState(false);
+  useEffect(() => () => { request.current?.abort(); onLoading(false); }, [onLoading]);
+
+  async function upload(file) {
+    request.current?.abort();
+    const controller = new AbortController();
+    request.current = controller;
+    setError('');
+    onChange(null);
+    if (!file) { setBusy(false); onLoading(false); return; }
+    if (!/\.(ame|evo)$/i.test(file.name) || file.size > 50 * 1024 * 1024) {
+      setError('Envie um arquivo .ame ou .evo de até 50 MB.');
+      setBusy(false); onLoading(false); return;
+    }
+    setBusy(true); onLoading(true);
+    try {
+      const data = new FormData();
+      data.append('arquivo', file);
+      const response = await fetch(apiUrl('/api/avaliacoes/importar'), { method: 'POST', body: data, signal: controller.signal });
+      const preview = await response.json();
+      if (!response.ok) throw new Error(preview.detail || 'Não foi possível ler a avaliação.');
+      if (controller.signal.aborted) return;
+      onChange({ file, preview, referenciaAnos: 'ano_base', objeto: 'Objeto avaliado por modelo', valoresAdotados: {}, anos: Object.fromEntries(preview.avaliacoes.map((item) => [item.id, item.ano_sugerido || ''])) });
+    } catch (err) {
+      if (err.name !== 'AbortError') setError(err.message);
+    } finally {
+      if (!controller.signal.aborted) { setBusy(false); onLoading(false); }
+    }
+  }
+  const years = value ? Object.values(value.anos).filter(Boolean) : [];
+  const duplicate = new Set(years).size !== years.length;
+  return <div className="importacao-avaliacoes">
+    <h3>Importar avaliações do MESA</h3>
+    <p>Envie um arquivo .ame com avaliações por modelo ou .evo com composições de terreno e construção. Os valores salvos serão organizados por ano no laudo.</p>
+    <label>Arquivo de avaliações (.ame ou .evo)
+      <input type="file" accept=".ame,.evo" onClick={(event) => { event.currentTarget.value = ''; }} onChange={(event) => upload(event.target.files?.[0])} />
+    </label>
+    {busy && <p role="status">Lendo avaliações…</p>}
+    {error && <p className="error-message" role="alert">{error}</p>}
+    {value && <>
+      <p><strong>{value.preview.arquivo}</strong> · {value.preview.avaliacoes.length} avaliação(ões) · {value.preview.tipo === 'evolutivo' ? 'Método evolutivo' : 'Modelo estatístico'}</p>
+      <div className="grid-2">
+        <label>Os anos informados representam
+          <select value={value.referenciaAnos} onChange={(event) => onChange({ ...value, referenciaAnos: event.target.value })}>
+            <option value="ano_base">Ano do modelo / ano-base (exercício no ano seguinte)</option>
+            <option value="exercicio_iptu">Exercício do IPTU (ano-base anterior)</option>
+          </select>
+        </label>
+        {value.preview.tipo === 'modelo' && <label>Objeto avaliado pelo modelo
+          <input value={value.objeto} onChange={(event) => onChange({ ...value, objeto: event.target.value })} placeholder="Ex.: terreno, imóvel completo, unidade comercial" />
+        </label>}
+      </div>
+      <p className="muted-message">Confira os anos detectados. O cenário com todos os anos em zero usa o ano indicado no título da avaliação. Referências ausentes ou divergentes precisam ser preenchidas antes de gerar o documento.</p>
+      {duplicate && <p className="muted-message">Há mais de uma avaliação para o mesmo ano. Elas serão identificadas pelo título e apresentadas separadamente, sem somar seus valores.</p>}
+      {value.preview.avaliacoes.map((item) => {
+        const year = Number(value.anos[item.id]);
+        const valid = /^(19|20|21)\d{2}$/.test(value.anos[item.id]);
+        const base = year - (value.referenciaAnos === 'exercicio_iptu' ? 1 : 0);
+        return <section className="importacao-avaliacao" key={item.id}>
+          <div className="grid-2">
+            <div>
+              <h4>{valid ? `Exercício ${base + 1}` : item.titulo}{item.cenario_base ? ' · Cenário base' : ''}</h4>
+              <p>{valid && !/^(19|20|21)\d{2}$/.test(item.titulo.trim()) && !item.cenario_base ? `${item.titulo} · ` : ''}{item.modelo}</p>
+            </div>
+            <label>{value.referenciaAnos === 'ano_base' ? 'Ano-base' : 'Exercício IPTU'}
+              <input type="number" min="1900" max="2199" required value={value.anos[item.id]} onChange={(event) => onChange({ ...value, anos: { ...value.anos, [item.id]: event.target.value } })} />
+              <small>{valid ? `Ano-base ${base} / IPTU ${base + 1}` : 'Informe o ano desta avaliação'}</small>
+            </label>
+          </div>
+          <dl className="importacao-valores">
+            {value.preview.tipo === 'evolutivo' && <><div><dt>Terreno</dt><dd>{reais(item.valor_terreno)}</dd></div><div><dt>Construção</dt><dd>{reais(item.valor_construcao)}</dd></div></>}
+            <div><dt>Valor total adotado</dt><dd>{reais(item.valor_total)}</dd></div>
+          </dl>
+          {item.avisos.map((warning, index) => <p className="muted-message" key={index}>{warning}</p>)}
+        </section>;
+      })}
+      {value.preview.tipo === 'evolutivo' && <p className="muted-message">Terreno e construção são componentes anteriores aos redutores de imóvel e ao fator de comercialização. O total adotado é o resultado final salvo no MESA.</p>}
+      {value.preview.tipo === 'evolutivo' && <p className="muted-message">O corpo do laudo apresentará terreno, construções, redutores, CUB, BDI, depreciação, composição e fundamentação. Revise as justificativas específicas em “5. Avaliação”.</p>}
+      <p className="muted-message">Os anexos estatísticos completos dependem da correspondência da versão do modelo local com a avaliação salva. O cálculo por ano é gerado com os resultados do arquivo.</p>
+    </>}
+  </div>;
+}

frontend/src/RevisaoAvaliacao.jsx

@@ -0,0 +1,33 @@
+import { moneyInput } from './importDefaults';
+import EvolutivoReview from './EvolutivoReview';
+
+export default function RevisaoAvaliacao({ form, onFieldChange, value, onChange, onImport }) {
+  if (!value) return <div className="importacao-avaliacoes"><p>Importe a avaliação para preencher os dados desta seção.</p><button type="button" onClick={onImport}>Importar avaliação</button></div>;
+  return <div className="importacao-avaliacoes">
+    <h3>Dados da avaliação</h3>
+    <p className="muted-message">Os campos foram preenchidos a partir de {value.preview.arquivo}. Você pode editá-los para o laudo.</p>
+    <label>Método de avaliação<input value={form.metodo_avaliacao} onChange={(event) => onFieldChange('metodo_avaliacao', event.target.value)} /></label>
+    <label>Modelo(s) utilizado(s)<input value={form.modelo_avaliacao} onChange={(event) => onFieldChange('modelo_avaliacao', event.target.value)} /></label>
+    <label>Referências<textarea aria-label="Referências" rows={2} value={form.datas_referencia} onChange={(event) => onFieldChange('datas_referencia', event.target.value)} /></label>
+    <h3>Valores de mercado adotados no laudo</h3>
+    <p className="muted-message">O padrão é o valor salvo na MESA. Alterações ficam registradas junto com o valor de origem na memória do laudo.</p>
+    {value.preview.avaliacoes.map((row) => {
+      const selected = String(value.anos[row.id] || '');
+      const valid = /^(19|20|21)\d{2}$/.test(selected);
+      const base = Number(selected) - (value.referenciaAnos === 'exercicio_iptu' ? 1 : 0);
+      const changed = Object.hasOwn(value.valoresAdotados || {}, row.id);
+      return <section className="importacao-avaliacao" key={row.id}>
+        <h4>{valid ? `Exercício ${base + 1} · Ano-base ${base}` : 'Ano de referência pendente'} · {row.titulo}</h4>
+        <p className="muted-message">Valor registrado na MESA: R$ {moneyInput(row.valor_total)}</p>
+        <label>Valor adotado (R$)<input inputMode="decimal" value={changed ? value.valoresAdotados[row.id] : moneyInput(row.valor_total)} onChange={(event) => onChange({ ...value, valoresAdotados: { ...value.valoresAdotados, [row.id]: event.target.value } })} /></label>
+        {changed && <button type="button" onClick={() => {
+          const next = { ...value.valoresAdotados };
+          delete next[row.id];
+          onChange({ ...value, valoresAdotados: next });
+        }}>Usar valor da MESA</button>}
+        <EvolutivoReview value={value} row={row} onChange={onChange} changed={changed} />
+      </section>;
+    })}
+    <button type="button" onClick={onImport}>Revisar arquivo e anos da importação</button>
+  </div>;
+}

frontend/src/importDefaults.js

@@ -0,0 +1,55 @@
+export const EMPTY_REASON = { descricao: '', alegado: true, confirmado: false };
+export const REVIEW_FIELDS = ['metodo_avaliacao', 'modelo_avaliacao', 'datas_referencia'];
+
+export function importDefaults(value) {
+  if (!value) return {};
+  const suggestions = value.preview.sugestoes || {};
+  const rows = value.preview.avaliacoes;
+  const baseYears = rows.map((row) => {
+    const year = String(value.anos[row.id] || '');
+    return /^(19|20|21)\d{2}$/.test(year)
+      ? Number(year) - (value.referenciaAnos === 'exercicio_iptu' ? 1 : 0) : null;
+  }).filter((year) => year !== null).sort((a, b) => a - b);
+  return {
+    metodo_avaliacao: suggestions.metodo_avaliacao || ('Método Comparativo Dados de Mercado - ABNT NBR 14.653-2' + (value.preview.tipo === 'evolutivo' ? ' e Método de Quantificação de Custo' : '')),
+    modelo_avaliacao: suggestions.modelo_avaliacao ?? [...new Set(rows.map((row) => row.modelo).filter(Boolean))].join(', '),
+    datas_referencia: [...new Set(baseYears)].map((year) => `Dezembro/${year}`).join(', '),
+    motivos_desvalorizantes: suggestions.motivos_desvalorizantes?.length
+      ? suggestions.motivos_desvalorizantes.map((item) => ({ ...item })) : [{ ...EMPTY_REASON }],
+  };
+}
+
+export function applyImportDefaults(form, next, previous, edited) {
+  if (!form) return form;
+  const patch = {};
+  for (const field of new Set([...Object.keys(previous), ...Object.keys(next)])) {
+    if (edited.has(field)) continue;
+    const value = next[field] ?? (field === 'motivos_desvalorizantes' ? [{ ...EMPTY_REASON }] : '');
+    if (JSON.stringify(form[field]) !== JSON.stringify(value)) patch[field] = value;
+  }
+  return Object.keys(patch).length ? { ...form, ...patch } : form;
+}
+
+export function decimalValue(input) {
+  const value = String(input ?? '').trim().replace(/^R\$\s*/, '');
+  if (value.includes(',')) {
+    if (!/^(?:\d{1,3}(?:\.\d{3})+|\d+),\d{1,2}$/.test(value)) return null;
+    return value.replace(/\./g, '').replace(',', '.');
+  }
+  return /^\d+(?:\.\d{1,2})?$/.test(value) ? value : null;
+}
+
+export function moneyInput(value) {
+  const [whole, cents = '00'] = String(value).split('.');
+  return `${whole.replace(/\B(?=(\d{3})+(?!\d))/g, '.')},${cents.padEnd(2, '0')}`;
+}
+
+export function adoptedValues(value) {
+  const output = {};
+  for (const [id, input] of Object.entries(value.valoresAdotados || {})) {
+    const parsed = decimalValue(input);
+    if (parsed === null) throw new Error('Informe valores de mercado válidos na seção 5. Avaliação.');
+    output[id] = parsed;
+  }
+  return output;
+}

frontend/src/styles.css

@@ -485,3 +485,15 @@ button:disabled {
     flex-direction: column;
   }
 }
+
+.importacao-avaliacoes { display: grid; gap: 16px; }
+.importacao-avaliacao { padding: 16px; border: 1px solid #d4dce3; border-radius: 10px; background: #f8fafb; }
+.importacao-avaliacao h4 { margin: 0 0 6px; }
+.importacao-valores { display: flex; flex-wrap: wrap; gap: 20px; margin: 16px 0 0; }
+.importacao-valores dt { color: #536874; font-size: 13px; }
+.importacao-valores dd { margin: 4px 0 0; font-weight: 700; }
+.evolutivo-review { margin-top: 1rem; padding-top: .75rem; border-top: 1px solid #d7dde4; }
+.evolutivo-review summary { cursor: pointer; font-weight: 600; margin-bottom: .75rem; }
+.evolutivo-review h5 { font-size: 1rem; margin: 1.25rem 0 .5rem; }
+.evolutivo-review label { margin: .7rem 0; }
+.documentary-field { margin: 1rem 0; }

frontend/tests/importDefaults.test.mjs

@@ -0,0 +1,55 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { adoptedValues, applyImportDefaults, importDefaults, decimalValue, EMPTY_REASON } from '../src/importDefaults.js';
+
+const imported = (patch = {}) => ({
+  preview: { tipo: 'evolutivo', avaliacoes: [{ id: 'evo-1', modelo: 'MODELO_A' }, { id: 'evo-2', modelo: 'MODELO_A' }],
+    sugestoes: { motivos_desvalorizantes: [{ descricao: 'Sem esgoto', alegado: false, confirmado: true }] } },
+  referenciaAnos: 'ano_base', anos: { 'evo-1': '2025', 'evo-2': '2023' }, ...patch,
+});
+
+test('importação preenche motivos, método, modelo e referências ordenadas', () => {
+  const defaults = importDefaults(imported());
+  assert.equal(defaults.metodo_avaliacao, 'Método Comparativo Dados de Mercado - ABNT NBR 14.653-2 e Método de Quantificação de Custo');
+  assert.equal(defaults.modelo_avaliacao, 'MODELO_A');
+  assert.equal(defaults.datas_referencia, 'Dezembro/2023, Dezembro/2025');
+  assert.deepEqual(defaults.motivos_desvalorizantes, [{ descricao: 'Sem esgoto', alegado: false, confirmado: true }]);
+});
+
+test('corrigir exercício ou ano-base atualiza somente os campos ainda automáticos', () => {
+  const previous = importDefaults(imported());
+  const next = importDefaults(imported({ referenciaAnos: 'exercicio_iptu' }));
+  const form = { ...previous, modelo_avaliacao: 'Texto revisado', motivos_desvalorizantes: [] };
+  const result = applyImportDefaults(form, next, previous, new Set(['modelo_avaliacao', 'motivos_desvalorizantes']));
+  assert.equal(result.datas_referencia, 'Dezembro/2022, Dezembro/2024');
+  assert.equal(result.modelo_avaliacao, 'Texto revisado');
+  assert.deepEqual(result.motivos_desvalorizantes, []);
+});
+
+test('trocar arquivo substitui sugestões e preserva inclusive edições vazias', () => {
+  const previous = importDefaults(imported());
+  const next = { ...previous, modelo_avaliacao: 'MODELO_B', datas_referencia: 'Dezembro/2020' };
+  const result = applyImportDefaults({ ...previous, datas_referencia: '' }, next, previous, new Set(['datas_referencia']));
+  assert.equal(result.modelo_avaliacao, 'MODELO_B');
+  assert.equal(result.datas_referencia, '');
+});
+
+test('remover arquivo limpa sugestões antigas e mantém campos manuais', () => {
+  const previous = importDefaults(imported());
+  const result = applyImportDefaults({ ...previous, numero_laudo: 'LA_01', modelo_avaliacao: 'Manual' }, {}, previous, new Set(['modelo_avaliacao']));
+  assert.equal(result.modelo_avaliacao, 'Manual');
+  assert.equal(result.metodo_avaliacao, '');
+  assert.equal(result.numero_laudo, 'LA_01');
+  assert.deepEqual(result.motivos_desvalorizantes, [EMPTY_REASON]);
+});
+
+test('referências pendentes não são adivinhadas', () => {
+  assert.equal(importDefaults(imported({ anos: {} })).datas_referencia, '');
+});
+
+test('valores adotados aceitam reais e zero sem perder a parte decimal', () => {
+  assert.deepEqual(adoptedValues({ valoresAdotados: { a: 'R$ 1.234.567,89', b: '0,00', c: '100.12' } }),
+    { a: '1234567.89', b: '0.00', c: '100.12' });
+  for (const input of ['', '-1', 'NaN', '1..2,00', '1,234', '1e3']) assert.equal(decimalValue(input), null);
+  assert.throws(() => adoptedValues({ valoresAdotados: { a: '' } }), /valores de mercado válidos/);
+});

models/anos.py

@@ -0,0 +1,95 @@
+"""Identificação das variáveis temporais e da referência registrada no modelo."""
+import re
+from typing import Optional
+
+import pandas as pd
+
+
+def periodo_variavel_ano(nome: str) -> Optional[tuple[tuple[int, ...], bool]]:
+    """Retorna os anos da dicotômica e se ela significa 'a partir de'."""
+    nome = str(nome)
+    ano = r"((?:19|20)\d{2}|2100)"
+    individual = re.fullmatch(rf"(?:a|ANO_?)?{ano}", nome)
+    if individual:
+        return (int(individual[1]),), False
+    a_partir = re.fullmatch(rf"AP{ano}", nome)
+    if a_partir:
+        return (int(a_partir[1]),), True
+    grupo = re.fullmatch(r"ANOS_((?:(?:19|20)\d{2}|2100)(?:_(?:(?:19|20)\d{2}|2100))+)", nome)
+    if grupo:
+        return tuple(int(valor) for valor in grupo[1].split("_")), False
+    abreviado = re.fullmatch(rf"{ano}/(\d{{2}})", nome)
+    if abreviado:
+        primeiro = int(abreviado[1])
+        return (primeiro, primeiro // 100 * 100 + int(abreviado[2])), False
+    return None
+
+
+def ano_base_explicito(referencia_temporal: dict, colunas_ano: list[str]) -> Optional[int]:
+    """Read the declared reference only when it belongs to these annual variables."""
+    if not isinstance(referencia_temporal, dict) or referencia_temporal.get('tipo') != 'ano':
+        return None
+    bases = referencia_temporal.get('anos_base')
+    variaveis = referencia_temporal.get('variaveis_ano')
+    if (not isinstance(bases, list) or len(bases) != 1
+            or not isinstance(variaveis, list) or not colunas_ano
+            or set(map(str, variaveis)) != set(map(str, colunas_ano))):
+        return None
+    if not re.fullmatch(r'(?:19|20)\d{2}|2100', str(bases[0])):
+        return None
+    base = int(bases[0])
+    for nome in colunas_ano:
+        periodo = periodo_variavel_ano(str(nome))
+        if periodo is None:
+            return None
+        anos, a_partir = periodo
+        if (a_partir and base >= anos[0]) or (not a_partir and base in anos):
+            return None
+    return base
+
+
+def detectar_ano_base(df: pd.DataFrame, colunas_ano: list[str], referencia_temporal=None) -> Optional[int]:
+    """Confere o ano original dos registros em que todas as dicotômicas são zero.
+
+    Uma referência ausente, ambígua ou incompatível com as dicotômicas não é
+    substituída por um ano presumido.
+    """
+    # New DAI files declare the reference independently of a source ANO column.
+    # Keep inference from original data for older files only.
+    if referencia_temporal is not None:
+        return ano_base_explicito(referencia_temporal, colunas_ano)
+    if not isinstance(df, pd.DataFrame) or df.empty or not colunas_ano:
+        return None
+    periodos = {coluna: periodo_variavel_ano(coluna) for coluna in colunas_ano}
+    if any(periodo is None for periodo in periodos.values()):
+        return None
+    # Alguns arquivos antigos usam inteiros como nomes das colunas de ano.
+    nomes = {str(coluna): coluna for coluna in df.columns}
+    if any(coluna not in nomes for coluna in colunas_ano):
+        return None
+    anuais = df[[nomes[coluna] for coluna in colunas_ano]].apply(pd.to_numeric, errors="coerce")
+    if anuais.isna().any().any() or not anuais.isin([0, 1]).all().all():
+        return None
+    if anuais.sum(axis=1).gt(1).any():
+        return None
+    registros_base = anuais.eq(0).all(axis=1)
+    if not registros_base.any():
+        return None
+
+    candidatos = []
+    for coluna in df.columns:
+        if re.sub(r"[\s_-]", "", str(coluna)).casefold() not in ("ano", "anobase"):
+            continue
+        anos = pd.to_numeric(df[coluna], errors="coerce")
+        if anos.isna().any() or not anos.between(1900, 2100).all() or not anos.mod(1).eq(0).all():
+            continue
+        consistente = True
+        for nome, (periodo, a_partir) in periodos.items():
+            esperado = anos.ge(periodo[0]) if a_partir else anos.isin(periodo)
+            if not anuais[nomes[nome]].eq(esperado.astype(int)).all():
+                consistente = False
+                break
+        referencias = anos[registros_base].unique()
+        if consistente and len(referencias) == 1:
+            candidatos.append(int(referencias[0]))
+    return candidatos[0] if candidatos and len(set(candidatos)) == 1 else None

models/construction_identity.py

@@ -0,0 +1,13 @@
+"""Annual MQC copies get new UUIDs; group by property and sequence instead."""
+import json
+import re
+
+
+def construction_identity(source, construction, index):
+    name = str((source.get('construcao') or {}).get('fonteNome') or '')
+    registration = re.search(r'inscri[çc][aã]o\s*[:\-]?\s*([\d.\-/]+)',name,re.I)
+    unit = source.get('imovelId') or source.get('unidadeId') or source.get('identificacaoImovel')
+    unit = unit or (registration[1] if registration else '')
+    location = (source.get('terreno') or {}).get('localizacao') or {}
+    return json.dumps([unit,location.get('lat'),location.get('lon'),construction.get('seq') or index+1,
+                       construction.get('nome') or '',construction.get('anoConstrucao') or ''],ensure_ascii=False)

models/hf_repository.py

@@ -0,0 +1,101 @@
+"""Read the MESA model dataset with revision-aware caching; never use bundled DAI files."""
+import os
+from pathlib import Path, PurePosixPath
+from threading import RLock
+from time import monotonic
+
+from .model_loader import load_model
+
+
+class ModelRepositoryError(RuntimeError):
+    pass
+
+
+def use_hf_repository():
+    if any(os.getenv(key, '').strip() for key in ('SPACE_ID', 'SPACE_AUTHOR_NAME', 'HF_SPACE_ID')):
+        return True
+    return os.getenv('MODELOS_REPOSITORIO_PROVIDER', 'local').strip().lower() in {
+        'hf', 'hf_dataset', 'dataset', 'huggingface',
+    }
+
+
+class HfModelRegistry:
+    def __init__(self):
+        self.repo_id = os.getenv('MODELOS_REPOSITORIO_HF_REPO_ID', 'gui-sparim/repositorio_mesa').strip()
+        self.revision = os.getenv('MODELOS_REPOSITORIO_HF_REVISION', 'main').strip()
+        self.subdir = os.getenv('MODELOS_REPOSITORIO_HF_SUBDIR', 'modelos_dai').strip().strip('/')
+        if '..' in PurePosixPath(self.subdir).parts or '\\' in self.subdir:
+            raise ModelRepositoryError('Pasta do repositório de modelos inválida.')
+        self.ttl = max(0, float(os.getenv('MODELOS_REPOSITORIO_HF_CACHE_TTL_SECONDS', '300')))
+        self._revision_sha = None
+        self._files = {}
+        self._checked_at = 0
+        self._cache = {}
+        self._lock = RLock()
+
+    def _token(self):
+        return next((os.getenv(key) for key in ('HF_TOKEN', 'HUGGINGFACE_HUB_TOKEN', 'HUGGINGFACE_TOKEN')
+                     if os.getenv(key)), None)
+
+    def _refresh(self):
+        if self._revision_sha and monotonic() - self._checked_at < self.ttl:
+            return
+        try:
+            from huggingface_hub import HfApi
+            info = HfApi().dataset_info(self.repo_id, revision=self.revision, token=self._token())
+            if not info.sha:
+                raise ValueError('Revisão ausente')
+            prefix = self.subdir + '/' if self.subdir else ''
+            files = {}
+            for entry in info.siblings or []:
+                filename = entry.rfilename
+                if not filename.startswith(prefix):
+                    continue
+                relative = filename[len(prefix):]
+                if '/' not in relative and '\\' not in relative and relative.endswith('.dai'):
+                    files[Path(relative).stem] = filename
+        except Exception as exc:
+            raise ModelRepositoryError(
+                'Não foi possível consultar o repositório de modelos da MESA. '
+                'Confira a conexão e o secret HF_TOKEN com permissão de leitura do dataset.'
+            ) from exc
+        if info.sha != self._revision_sha:
+            self._cache.clear()
+        self._revision_sha = info.sha
+        self._files = files
+        self._checked_at = monotonic()
+
+    def discover_models(self):
+        with self._lock:
+            self._refresh()
+            return sorted(self._files)
+
+    def list_models(self):
+        return self.discover_models()
+
+    def get_model(self, name):
+        with self._lock:
+            self._refresh()
+            if name not in self._files:
+                return None
+            if name in self._cache:
+                return self._cache[name]
+            try:
+                from huggingface_hub import hf_hub_download
+                path = hf_hub_download(repo_id=self.repo_id, repo_type='dataset',
+                                       filename=self._files[name], revision=self._revision_sha,
+                                       token=self._token())
+            except Exception as exc:
+                raise ModelRepositoryError('Não foi possível baixar o modelo solicitado do repositório da MESA.') from exc
+            model = load_model(Path(path))
+            if model is None:
+                raise ModelRepositoryError('O modelo da MESA não pôde ser carregado nesta versão do gerador.')
+            self._cache[name] = model
+            return model
+
+    def clear_cache(self):
+        with self._lock:
+            self._cache.clear()
+            self._revision_sha = None
+            self._files = {}
+            self._checked_at = 0

models/imported_context.py

@@ -0,0 +1,95 @@
+"""Use the imported model snapshot; local names alone do not establish identity."""
+import hashlib
+import json
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from . import get_model, list_available_models
+from .model_data import ModelData
+from .anos import detectar_ano_base, periodo_variavel_ano
+
+
+def context_key(row):
+    terrain = row.get('evolutivo', {}).get('terreno', {})
+    context = terrain.get('contextoModelo') or {}
+    return row.get('modelo', ''), hashlib.sha256(json.dumps(context, sort_keys=True, ensure_ascii=False).encode()).hexdigest()[:12]
+
+
+def matching_local(row):
+    name = row.get('modelo')
+    context = row.get('evolutivo', {}).get('terreno', {}).get('contextoModelo') or {}
+    if name not in list_available_models():
+        return None, 'Modelo indisponível no catálogo.'
+    local = get_model(name)
+    if not context:
+        return None, 'O arquivo não preserva o contexto necessário para confirmar a versão do modelo do catálogo.'
+    prediction = context.get('prediction') or {}
+    names, params = prediction.get('names') or [], prediction.get('params') or []
+    sm = local.modelos_sm if local else None
+    try:
+        local_names = list(map(str, sm.model.exog_names))
+        same = names == local_names and len(params) == len(sm.params) and np.allclose(params, sm.params, rtol=1e-12, atol=1e-12)
+        # Equal parameters are necessary, but not sufficient: verify fitted data too.
+        x = context.get('transformacoes', {}).get('X')
+        y = context.get('transformacoes', {}).get('y')
+        portable_x = pd.DataFrame(x).reindex(columns=names, fill_value=1).to_numpy(dtype=float)
+        portable_y = np.asarray(y, dtype=float).reshape(-1)
+        same = same and portable_x.shape == sm.model.exog.shape and portable_y.shape == sm.model.endog.shape
+        same = same and np.allclose(portable_x, sm.model.exog, rtol=1e-12, atol=1e-12) and np.allclose(portable_y, sm.model.endog, rtol=1e-12, atol=1e-12)
+        covariance = np.asarray(prediction.get('covariance'),dtype=float)
+        same = same and covariance.shape == np.asarray(sm.cov_params()).shape and np.allclose(covariance,sm.cov_params(),rtol=1e-12,atol=1e-12)
+        same = same and context.get('transformacoes',{}).get('info') == local.formatted_top_transformation_info
+        if same:
+            return local, ''
+    except (AttributeError, TypeError, ValueError, KeyError):
+        pass
+    return None, 'A correspondência da versão do catálogo não foi confirmada com os coeficientes e a amostra salvos; os anexos desse modelo não serão usados.'
+
+
+def snapshot_model(row):
+    context = row.get('evolutivo', {}).get('terreno', {}).get('contextoModelo') or {}
+    prediction = context.get('prediction') or {}
+    names, params = prediction.get('names') or [], prediction.get('params') or []
+    if not names or len(names) != len(params):
+        return None
+    raw = context.get('dados', {}).get('df') or {}
+    try:
+        df = pd.DataFrame(**raw) if isinstance(raw, dict) and 'columns' in raw else pd.DataFrame(raw)
+    except (ValueError, TypeError):
+        df = pd.DataFrame()
+    transforms = context.get('transformacoes') or {}
+    info = transforms.get('info') or []
+    mapping = dict(item.split(': ', 1) for item in info if isinstance(item, str) and ': ' in item)
+    # Transcribe the fitted expression; do not fit or evaluate a new model.
+    terms = []
+    for name, param in zip(names, params):
+        coefficient = format(float(param), '.12g')
+        if name == 'const':
+            terms.append(coefficient)
+        else:
+            transformed = mapping.get(name, '(x)').replace('x', f'[{name}]')
+            terms.append(f'({coefficient} × {transformed})')
+    dependent = next((item.split(': ', 1) for item in info if isinstance(item, str) and ': ' in item and item.split(': ', 1)[0] not in names), ['Y', 'y'])
+    lhs = dependent[1].replace('y', dependent[0])
+    evidence = context.get('normativeEvidence') or {}
+    annual_names = [str(name) for name in names if periodo_variavel_ano(str(name))]
+    reference = context.get('referencia_temporal')
+    base_year = detectar_ano_base(df, annual_names, reference)
+    if base_year is None and reference is None:
+        # Legacy EVO contexts omitted the declaration. A name alone is not
+        # enough to borrow it: matching_local verifies the fitted model/data.
+        local, _ = matching_local(row)
+        if local is not None:
+            base_year = local.ano_base
+    return ModelData(
+        nome=row.get('modelo') or context.get('name') or 'Modelo importado', path=Path('contexto_importado'),
+        xy_preview=df, tabelas_coef=pd.DataFrame({'coef': params}, index=names),
+        modelos_resumos={'n': evidence.get('n', len(df)), 'k': evidence.get('k', len(names)-1),
+                         'r2': evidence.get('r2'), 'equacao': f'{lhs} = ' + ' + '.join(terms)},
+        formatted_top_transformation_info=info,
+        variaveis_dicotomicas=transforms.get('dicotomicas') or [],
+        periodo_dados_mercado=context.get('periodo_dados_mercado') or {},
+        ano_base=base_year,
+    )

models/model_data.py

@@ -35,6 +35,7 @@ class ModelData:
     variaveis_dicotomicas: List[str] = field(default_factory=list)
     periodo_dados_mercado: Dict[str, Any] = field(default_factory=dict)
     graf_model: str = ""
+    ano_base: Optional[int] = None
 
     @property
     def r2(self) -> Optional[float]:

models/model_loader.py

@@ -11,6 +11,7 @@ import joblib
 import pandas as pd
 
 from .model_data import ModelData
+from .anos import detectar_ano_base, periodo_variavel_ano
 
 
 def _get_first(container: dict[str, Any], *keys: str, default: Any = None) -> Any:
@@ -208,6 +209,15 @@ def load_model(dai_path: Path) -> Optional[ModelData]:
             modelo_dict, "sm", "statsmodels", "statsmodels_result", default=None
         )
 
+        # O preview da modelagem pode omitir a coluna original ANO. Identifique
+        # a referência nos dados de origem antes de descartar essa informação.
+        dados_ano = _as_dataframe(_get_first(
+            dados, "df", "xy_preview", "df_preview", "df_modelagem", "preview",
+            default=xy_preview,
+        ))
+        colunas_ano = [str(coluna) for coluna in tabelas_coef.index
+                       if periodo_variavel_ano(str(coluna)) is not None]
+
         model = ModelData(
             nome=dai_path.stem,
             path=dai_path,
@@ -242,6 +252,7 @@ def load_model(dai_path: Path) -> Optional[ModelData]:
                 )
             ),
             graf_model='',
+            ano_base=detectar_ano_base(dados_ano, colunas_ano, data_dict.get('referencia_temporal')),
         )
     except (KeyError, TypeError) as e:
         print(f"Erro ao processar estrutura de {dai_path}: {e}")

models/registry.py

@@ -1,12 +1,14 @@
 """
 Registro de modelos de avaliação.
-Descobre automaticamente modelos disponíveis na pasta models/files/.
+Usa o dataset da MESA em Spaces e os arquivos locais no desenvolvimento.
 """
+import os
 from pathlib import Path
 from typing import List, Optional, Dict
 
 from .model_data import ModelData
 from .model_loader import load_model
+from .hf_repository import HfModelRegistry, use_hf_repository
 
 
 class ModelRegistry:
@@ -74,10 +76,10 @@ class ModelRegistry:
 
 
 # Instância global do registro
-_registry: Optional[ModelRegistry] = None
+_registry: Optional[ModelRegistry | HfModelRegistry] = None
 
 
-def get_registry(models_dir: Optional[Path] = None) -> ModelRegistry:
+def get_registry(models_dir: Optional[Path] = None) -> ModelRegistry | HfModelRegistry:
     """
     Obtém a instância global do registro.
 
@@ -85,15 +87,17 @@ def get_registry(models_dir: Optional[Path] = None) -> ModelRegistry:
         models_dir: Diretório dos modelos (usa padrão se não fornecido)
 
     Returns:
-        Instância do ModelRegistry
+        Registro da fonte configurada para o ambiente
     """
     global _registry
 
     if _registry is None:
-        if models_dir is None:
+        if use_hf_repository():
+            _registry = HfModelRegistry()
+        else:
             # Caminho padrão relativo ao projeto
-            models_dir = Path(__file__).parent / "files"
-        _registry = ModelRegistry(models_dir)
+            models_dir = models_dir or Path(os.getenv('MODELOS_REPOSITORIO_LOCAL_DIR') or Path(__file__).parent / 'files')
+            _registry = ModelRegistry(models_dir)
 
     return _registry
 

requirements.txt

@@ -12,3 +12,4 @@ matplotlib
 scipy
 plotly
 numpy
+huggingface_hub>=0.34,<2

run_dev.sh

@@ -6,6 +6,49 @@ VENV_PYTHON="$ROOT_DIR/.venv/bin/python"
 BACKEND_PID=""
 FRONTEND_PID=""
 
+find_available_ports() {
+  "$VENV_PYTHON" - "${PORT:-8000}" "${FRONTEND_PORT:-5173}" <<'PY'
+import errno
+import socket
+import sys
+
+
+def next_port(value, reserved=()):
+    start = int(value)
+    if not 1 <= start <= 65535:
+        raise ValueError(f"Porta inválida: {value}")
+    for port in range(start, 65536):
+        if port in reserved:
+            continue
+        addresses = [(socket.AF_INET, "0.0.0.0")]
+        if socket.has_ipv6:
+            addresses.append((socket.AF_INET6, "::"))
+        available = True
+        for family, host in addresses:
+            try:
+                # Sem SO_REUSEADDR: no macOS ele pode permitir um bind em
+                # 0.0.0.0 mesmo com outro serviço escutando em 127.0.0.1.
+                with socket.socket(family, socket.SOCK_STREAM) as probe:
+                    probe.bind((host, port))
+                    probe.listen(1)
+            except OSError as error:
+                if error.errno in (errno.EAFNOSUPPORT, errno.EADDRNOTAVAIL):
+                    continue
+                if error.errno in (errno.EADDRINUSE, errno.EACCES):
+                    available = False
+                    break
+                raise
+        if available:
+            return port
+    raise RuntimeError(f"Nenhuma porta disponível a partir de {start}")
+
+
+backend_port = next_port(sys.argv[1])
+frontend_port = next_port(sys.argv[2], reserved=(backend_port,))
+print(backend_port, frontend_port)
+PY
+}
+
 find_homebrew_python() {
   if [[ -x "/opt/homebrew/opt/python@3.14/bin/python3" ]]; then
     printf '%s\n' "/opt/homebrew/opt/python@3.14/bin/python3"
@@ -34,8 +77,16 @@ cleanup() {
   echo "Encerrando backend e frontend..."
   terminate_tree "$BACKEND_PID"
   terminate_tree "$FRONTEND_PID"
+  if [[ -n "$BACKEND_PID" ]]; then
+    wait "$BACKEND_PID" 2>/dev/null || true
+  fi
+  if [[ -n "$FRONTEND_PID" ]]; then
+    wait "$FRONTEND_PID" 2>/dev/null || true
+  fi
 }
-trap cleanup EXIT INT TERM
+trap cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
 
 terminate_tree() {
   local pid="${1:-}"
@@ -50,14 +101,26 @@ terminate_tree() {
   kill "$pid" 2>/dev/null || true
 }
 
-echo "Subindo backend em http://localhost:${PORT:-8000}"
+AVAILABLE_PORTS="$(find_available_ports)"
+read -r BACKEND_PORT FRONTEND_PORT <<< "$AVAILABLE_PORTS"
+BACKEND_URL="http://localhost:$BACKEND_PORT"
+FRONTEND_URL="http://localhost:$FRONTEND_PORT"
+
+# O backend permite a origem escolhida e o Vite usa a porta real da API,
+# inclusive quando há um VITE_API_BASE_URL antigo no frontend/.env.
+export PORT="$BACKEND_PORT"
+export CORS_ORIGINS="${CORS_ORIGINS:+$CORS_ORIGINS,}$FRONTEND_URL,http://127.0.0.1:$FRONTEND_PORT"
+export VITE_API_BASE_URL="$BACKEND_URL"
+
+cd "$ROOT_DIR"
+echo "Subindo backend em $BACKEND_URL"
 "$VENV_PYTHON" "$ROOT_DIR/app.py" &
 BACKEND_PID=$!
 
-echo "Subindo frontend em http://localhost:5173"
+echo "Subindo frontend em $FRONTEND_URL"
 (
   cd "$ROOT_DIR/frontend"
-  npm run dev -- --host 0.0.0.0
+  npm run dev -- --host 0.0.0.0 --port "$FRONTEND_PORT" --strictPort
 ) &
 FRONTEND_PID=$!
 

scripts/sync_mesa_documentacao.mjs

@@ -0,0 +1,85 @@
+// Extrai os conteúdos compartilhados da MESA sem copiar definições manualmente.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const mesa = path.resolve(process.argv[2] || path.join(root, '..', 'mesa-frame'));
+const require = createRequire(path.join(mesa, 'frontend/package.json'));
+const { parse } = require('@babel/parser');
+const sources = {};
+function ast(relative) {
+  const text = fs.readFileSync(path.join(mesa, relative), 'utf8');
+  sources[relative] = crypto.createHash('sha256').update(text).digest('hex');
+  return parse(text, { sourceType: 'module', plugins: ['jsx'] });
+}
+function walk(node, fn) {
+  if (!node || typeof node !== 'object') return;
+  fn(node);
+  for (const value of Object.values(node)) {
+    if (Array.isArray(value)) value.forEach((child) => walk(child, fn));
+    else if (value && typeof value === 'object') walk(value, fn);
+  }
+}
+function literal(node) {
+  if (['StringLiteral', 'NumericLiteral', 'BooleanLiteral'].includes(node?.type)) return node.value;
+  if (node?.type === 'NullLiteral') return null;
+  if (node?.type === 'ArrayExpression') return node.elements.map(literal);
+  if (node?.type === 'ObjectExpression') return Object.fromEntries(node.properties.map((prop) => [prop.key.name || prop.key.value, literal(prop.value)]));
+  if (node?.type === 'UnaryExpression' && node.operator === '-') return -literal(node.argument);
+  throw new Error(`Conteúdo não literal: ${node?.type}`);
+}
+function variable(tree, name) {
+  let result;
+  walk(tree, (node) => { if (node.type === 'VariableDeclarator' && node.id.name === name) result = node.init; });
+  if (!result) throw new Error(`Variável ausente na MESA: ${name}`);
+  return result;
+}
+const refs = ast('frontend/src/mqc/data/referenceData.js');
+const notes = ast('frontend/src/mqc/wordExportOptions.js');
+const norms = ast('frontend/src/components/NormativeReference.jsx');
+const reducers = ast('frontend/src/components/RedutoresAvaliacaoModal.jsx');
+const dep = ast('frontend/src/mqc/calculations.js');
+const models = ast('frontend/src/modelFoundation.js');
+const global = ast('frontend/src/globalFoundation.js');
+const exports = ast('frontend/src/mqc/exporters.js');
+const redutoresTermos = {};
+walk(variable(reducers, 'memoriaCompleta'), (node) => {
+  if (node.type !== 'ObjectExpression') return;
+  const props = Object.fromEntries(node.properties.filter((p) => p.type === 'ObjectProperty').map((p) => [p.key.name || p.key.value, p.value]));
+  if (props.nome?.type === 'StringLiteral' && props.descricao?.type === 'StringLiteral') redutoresTermos[props.nome.value] = props.descricao.value;
+});
+const functions = {};
+for (const name of ['calcularDepreciacao', 'calcularKd', 'calcularEnquadramento']) {
+  walk(dep, (node) => { if (node.type === 'FunctionDeclaration' && node.id.name === name) functions[name] = fs.readFileSync(path.join(mesa, 'frontend/src/mqc/calculations.js'), 'utf8').slice(node.start, node.end); });
+}
+const annotations = {};
+walk(exports, (node) => { if (node.type === 'FunctionDeclaration' && ['wordCubTypeExplanation', 'wordMixExplanation', 'wordLifeAdjustmentExplanation'].includes(node.id.name)) annotations[node.id.name] = fs.readFileSync(path.join(mesa, 'frontend/src/mqc/exporters.js'), 'utf8').slice(node.start, node.end); });
+const areaNotes = [];
+walk(notes, (node) => {
+  if (node.type === 'FunctionDeclaration' && node.id.name === 'wordAreaHeaderNote') {
+    walk(node, (child) => { if (child.type === 'StringLiteral' && child.value.includes(': área')) areaNotes.push(child.value); });
+  }
+});
+// As fórmulas e critérios passam a ter a mesma origem do conteúdo da interface.
+const catalog = {
+  versao: 1, fontes: sources,
+  notas: Object.fromEntries(literal(variable(notes, 'WORD_HEADER_NOTES'))),
+  notas_area: areaNotes,
+  referencias: Object.fromEntries(['bdiAdicionais', 'bdiTiposConstrucao', 'estadosConservacao', 'vidaUtilTipos', 'valorResidualReferencias', 'areaEquivalenteCoeficientes', 'siglasCub'].map((name) => [name, literal(variable(refs, name))])),
+  normas: literal(variable(norms, 'REFERENCES')),
+  redutores_termos: redutoresTermos,
+  funcoes_mqc: functions,
+  anotacoes_mqc: annotations,
+  criterios_fc: literal(variable(global, 'FC_FOUNDATION_OPTIONS')),
+  descricoes_modelo: literal(variable(models, 'MODEL_FOUNDATION_MANUAL_DESCRIPTIONS')),
+  requisitos_modelo: literal(variable(models, 'MODEL_FOUNDATION_REQUIREMENTS')),
+};
+const encoded = JSON.stringify(catalog);
+catalog.identificador = crypto.createHash('sha256').update(encoded).digest('hex').slice(0, 16);
+fs.writeFileSync(path.join(root, 'config/mesa_documentacao.json'), JSON.stringify(catalog, null, 2) + '\n');
+// O mesmo pacote acompanha as novas exportações EVO para leitura histórica.
+fs.writeFileSync(path.join(mesa, 'frontend/src/evolutivo/documentacaoTecnica.json'), JSON.stringify(catalog, null, 2) + '\n');
+console.log(`Conteúdo técnico sincronizado da MESA: ${catalog.identificador}`);

scripts/sync_mesa_redutores.py

@@ -0,0 +1,25 @@
+"""Sincroniza o catálogo versionado da MESA sem importar seu backend."""
+import ast
+import json
+from pathlib import Path
+import sys
+
+root = Path(__file__).resolve().parents[1]
+mesa = Path(sys.argv[1]) if len(sys.argv) > 1 else root.parent / "mesa-frame"
+source = mesa / "backend/app/core/redutores_territoriais.py"
+tree = ast.parse(source.read_text(encoding="utf-8"))
+version = next(ast.literal_eval(node.value) for node in tree.body
+               if isinstance(node, ast.Assign)
+               and any(isinstance(target, ast.Name) and target.id == "VERSAO_REGRAS_REDUTORES" for target in node.targets))
+catalog = next(node.value for node in tree.body if isinstance(node, ast.AnnAssign)
+               and isinstance(node.target, ast.Name) and node.target.id == "CATALOGO_REDUTORES")
+
+class ResolveVersion(ast.NodeTransformer):
+    def visit_Name(self, node):
+        return ast.Constant(value=version) if node.id == "VERSAO_REGRAS_REDUTORES" else node
+
+data = {"origem": "mesa-frame/backend/app/core/redutores_territoriais.py",
+        "catalogo": ast.literal_eval(ResolveVersion().visit(catalog))}
+destination = root / "config/mesa_redutores.json"
+destination.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+print(f"Catálogo sincronizado: {version}")

tests/test_anos.py

@@ -0,0 +1,138 @@
+from pathlib import Path
+from tempfile import TemporaryDirectory
+import unittest
+
+import joblib
+import pandas as pd
+from docx import Document
+
+from document.anexos.metodologia import gerar_anexo_metodologia
+from models.anos import detectar_ano_base, periodo_variavel_ano
+from models.model_data import ModelData
+from models.model_loader import load_model
+
+
+def texto_metodologia(colunas, ano_base=None):
+    modelo = ModelData(
+        nome="TESTE", path=Path("teste.dai"), ano_base=ano_base,
+        tabelas_coef=pd.DataFrame({"coef": [1] * (len(colunas) + 1)}, index=["const", *colunas]),
+    )
+    doc = Document()
+    gerar_anexo_metodologia(doc, modelo)
+    return "\n".join(paragrafo.text for paragrafo in doc.paragraphs)
+
+
+class AnosTests(unittest.TestCase):
+    def test_usa_referencia_declarada_sem_coluna_ano(self):
+        columns = ['2022', '2023', '2024', 'AP2025']
+        reference = {'tipo': 'ano', 'anos_base': [2021], 'variaveis_ano': columns}
+        df = pd.DataFrame({'2022': [0, 1], '2023': [0, 0], '2024': [0, 0], 'AP2025': [0, 0]})
+        self.assertIsNone(detectar_ano_base(df, columns))
+        self.assertEqual(detectar_ano_base(df, columns, reference), 2021)
+        self.assertEqual(detectar_ano_base(pd.DataFrame(), columns, reference), 2021)
+
+    def test_nao_usa_declaracao_ambigua_ou_de_outro_modelo(self):
+        columns = ['2022', 'AP2025']
+        reference = {'tipo': 'ano', 'anos_base': [2021], 'variaveis_ano': columns}
+        for change in [{'anos_base': [2020, 2021]}, {'anos_base': [2022]},
+                       {'anos_base': [2026]}, {'anos_base': [True]},
+                       {'anos_base': [2021.5]}, {'variaveis_ano': ['2022']}, {'tipo': 'data'}]:
+            with self.subTest(change=change):
+                self.assertIsNone(detectar_ano_base(pd.DataFrame(), columns, {**reference, **change}))
+
+    def test_loader_le_ano_base_explicitamente_salvo_no_dai(self):
+        columns = ['2022', 'AP2025']
+        package = {'referencia_temporal': {'tipo': 'ano', 'anos_base': [2021], 'variaveis_ano': columns},
+                   'dados': {'df': pd.DataFrame({'2022': [0, 1], 'AP2025': [0, 0]})},
+                   'modelo': {'coeficientes': pd.DataFrame({'coef': [1, 2, 3]}, index=['const', *columns])}}
+        with TemporaryDirectory() as folder:
+            path = Path(folder) / 'referencia.dai'
+            joblib.dump(package, path)
+            model = load_model(path)
+        self.assertEqual(model.ano_base, 2021)
+        doc = Document()
+        gerar_anexo_metodologia(doc, model)
+        text = '\n'.join(p.text for p in doc.paragraphs)
+        self.assertIn('2021 (ano-base do modelo)', text)
+        self.assertNotIn('Ano-base não identificado', text)
+
+    def test_reconhece_formatos_presentes_nos_modelos(self):
+        for nome, esperado in {
+            "2024": ((2024,), False), "a2024": ((2024,), False),
+            "ANO2024": ((2024,), False), "ANO_2024": ((2024,), False),
+            "AP2024": ((2024,), True), "2018/19": ((2018, 2019), False),
+            "ANOS_2025_2026": ((2025, 2026), False),
+            "ANO": None, "IDADE+1": None, "CONSTR_ANO": None,
+        }.items():
+            with self.subTest(nome=nome):
+                self.assertEqual(periodo_variavel_ano(nome), esperado)
+
+    def test_usa_ano_registrado_mesmo_com_lacuna(self):
+        df = pd.DataFrame({"ANO": [2012, 2015, 2017], "2015": [0, 1, 0], "2017": [0, 0, 1]})
+        self.assertEqual(detectar_ano_base(df, ["2015", "2017"]), 2012)
+        texto = texto_metodologia(["2015", "2017"], 2012)
+        self.assertIn("[2015] e [2017] = 0, se o dado é de 2012 (ano-base do modelo).", texto)
+        self.assertNotIn("2014", texto)
+
+    def test_aceita_ano_base_e_valores_salvos_como_texto(self):
+        df = pd.DataFrame({"ANO BASE": ["2010", "2015"], "a2015": ["0", "1"]})
+        self.assertEqual(detectar_ano_base(df, ["a2015"]), 2010)
+
+    def test_aceita_coluna_anual_com_nome_inteiro(self):
+        df = pd.DataFrame({"ANO": [2010, 2015], 2015: [0, 1]})
+        self.assertEqual(detectar_ano_base(df, ["2015"]), 2010)
+
+    def test_ap_sozinho_tem_referencia_explicita_e_nao_falha(self):
+        df = pd.DataFrame({"ANO": [2018, 2023, 2025], "AP2023": [0, 1, 1]})
+        self.assertEqual(detectar_ano_base(df, ["AP2023"]), 2018)
+        texto = texto_metodologia(["AP2023"], 2018)
+        self.assertIn("[AP2023] = 1, se o dado é a partir de 2023", texto)
+        self.assertIn("[AP2023] = 0, se o dado é de 2018", texto)
+
+    def test_anos_agrupados(self):
+        df = pd.DataFrame({"ANO": [2012, 2025, 2026], "ANOS_2025_2026": [0, 1, 1]})
+        self.assertEqual(detectar_ano_base(df, ["ANOS_2025_2026"]), 2012)
+        self.assertIn("se o dado é de 2025 ou 2026", texto_metodologia(["ANOS_2025_2026"], 2012))
+
+    def test_nao_presume_referencia_ausente_ambigua_ou_inconsistente(self):
+        casos = [
+            {"2015": [0, 1]},
+            {"ANO": [2012, 2013, 2015], "2015": [0, 0, 1]},
+            {"ANO": [2012, 2016], "2015": [0, 1]},
+            {"ANO": [2012, 2015], "2015": [0, 0]},
+            {"ANO": [2015], "2015": [1]},
+            {"ANO": [2012, None], "2015": [0, 1]},
+            {"ANO": [2012, 2015], "2015": [0, 0.5]},
+            {"ANO": [2012, 2015], "ANO BASE": [2013, 2015], "2015": [0, 1]},
+        ]
+        for dados in casos:
+            with self.subTest(dados=dados):
+                self.assertIsNone(detectar_ano_base(pd.DataFrame(dados), ["2015"]))
+        texto = texto_metodologia(["2015"])
+        self.assertIn("Ano-base não identificado no modelo", texto)
+        self.assertNotIn("2014", texto)
+
+    def test_carregamento_preserva_referencia_omitida_do_preview(self):
+        df = pd.DataFrame({"ANO": [2012, 2015], "2015": [0, 1]})
+        # Um banco amplo é reduzido pelo loader para X + y; ANO fica de fora.
+        for indice in range(45):
+            df[f"aux_{indice}"] = 0
+        pacote = {
+            "dados": {"df": df},
+            "transformacoes": {"X": df[["2015"]], "y": pd.Series([100, 200], name="VALOR")},
+            "modelo": {"coeficientes": pd.DataFrame({"coef": [1, 2]}, index=["const", "2015"])},
+        }
+        with TemporaryDirectory() as pasta:
+            caminho = Path(pasta) / "teste.dai"
+            joblib.dump(pacote, caminho)
+            modelo = load_model(caminho)
+        self.assertIsNotNone(modelo)
+        self.assertNotIn("ANO", modelo.xy_preview.columns)
+        self.assertEqual(modelo.ano_base, 2012)
+        doc = Document()
+        gerar_anexo_metodologia(doc, modelo)
+        self.assertIn("2012 (ano-base do modelo)", "\n".join(p.text for p in doc.paragraphs))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_avaliacoes_import.py

@@ -0,0 +1,268 @@
+import io
+import json
+import unittest
+from unittest.mock import patch
+
+from docx import Document
+from fastapi import UploadFile
+from backend.app.avaliacoes_import import parse_export, resolve_import
+from backend.app.schemas import ImportacaoAvaliacoesInput, LaudoFormInput
+from backend.app.services import _build_generator_payload, generate_laudo_document
+from document.avaliacoes_importadas import conclusion_table, calculation_sections
+from document.generator import LaudoGenerator
+
+
+def ame(rows=None):
+    return {'formato': 'ame', 'versao': 1, 'avaliacoes': rows or [
+        {'id': 'base', 'titulo': 'Ano Base', 'modelo': 'MODELO_TER', 'avaliacao': {
+            'tipo_y': 'unitario', 'valor_area': 100, 'estimado_unitario': 10.12, 'estimado_total': 1012,
+            'valores_x': {'2024': 0, '2025': 0, 'FON': 1}}},
+        {'id': 'ano', 'titulo': '2025', 'modelo': 'MODELO_TER', 'avaliacao': {
+            'tipo_y': 'unitario', 'valor_area': 100, 'estimado_unitario': 12.34, 'estimado_total': 1234,
+            'valores_x': {'2024': 0, '2025': 1, 'FON': 1}}},
+    ]}
+
+
+def evo():
+    return {'format': 'mesa-evolutivo', 'version': 2, 'anos': [{
+        'identificacao': 'Imóvel', 'referencia': 'dezembro de 2025', 'concluida': True,
+        'terreno': {'modelo': 'MODELO_TER', 'valorTotal': '1000', 'area': '100',
+                    'avaliacao': {'valores_x': {'2025': 1}, 'estimado_unitario': 10}},
+        'construcao': {'valorTotal': '500', 'anoReferencia': '2025', 'construcoes': []},
+        'resultadoComposicao': {'valorTerrenoPgv': 1000, 'valorConstrucao': 500,
+                                'valorTotal': 1215, 'fatorFcAplicado': .9, 'erros': []},
+    }]}
+
+
+def parse(data, filename='teste.ame'):
+    return parse_export(json.dumps(data).encode(), filename)
+
+
+class AvaliacoesImportTests(unittest.TestCase):
+    def test_importacao_sugere_motivos_registrados_sem_presumir_alegacao(self):
+        data = ame()
+        for row in data['avaliacoes']:
+            row['avaliacao']['ajuste_territorial'] = {'configuracao': {
+                'art_88_i': {'condicoes': {'app': {'percentual_area': .2}, 'alta_tensao': {'percentual_area': 0}}},
+                'art_88_ii': {'selecionados': ['sem_esgoto']},
+                'topografia': {'relevo': 'declive_5_10'},
+            }}
+        parsed = parse(data)
+        reasons = parsed['sugestoes']['motivos_desvalorizantes']
+        self.assertEqual([reason['descricao'] for reason in reasons],
+                         ['Área de Preservação Permanente', 'Sem disponibilidade do serviço público de esgoto', 'Declive de 5% até 10%'])
+        self.assertTrue(all(reason['confirmado'] and not reason['alegado'] for reason in reasons))
+        self.assertEqual(parsed['sugestoes']['modelo_avaliacao'], 'MODELO_TER')
+
+    def test_evo_usa_catalogo_salvo_para_sugestao_do_motivo(self):
+        data = evo()
+        year = data['anos'][0]
+        year['catalogoAjustes'] = {'art_88_ii': {'condicoes': [{'codigo': 'condicao_salva', 'rotulo': 'Condição registrada no trabalho'}]}}
+        year['terreno']['avaliacao']['ajuste_territorial'] = {'configuracao': {'art_88_ii': {'selecionados': ['condicao_salva']}}}
+        parsed = parse(data, 'teste.evo')
+        self.assertEqual(parsed['sugestoes']['motivos_desvalorizantes'][0]['descricao'], 'Condição registrada no trabalho')
+        self.assertEqual(parsed['sugestoes']['metodo_avaliacao'], 'Método Comparativo Dados de Mercado - ABNT NBR 14.653-2 e Método de Quantificação de Custo')
+
+    def test_sem_ajustes_nao_inventa_motivos(self):
+        self.assertEqual(parse(ame())['sugestoes']['motivos_desvalorizantes'], [])
+
+    def test_valor_editado_preserva_resultado_de_origem(self):
+        parsed = parse(evo(), 'teste.evo')
+        choices = ImportacaoAvaliacoesInput(valores_adotados={'evo-1': '1200'})
+        imported = resolve_import(parsed, choices)
+        row = imported['avaliacoes'][0]
+        self.assertEqual(row['valor_total'], '1200.00')
+        self.assertEqual(row['valor_total_origem'], '1215.00')
+        self.assertEqual(row['valor_terreno'], '1000.00')
+        self.assertEqual(parsed['avaliacoes'][0]['valor_total'], '1215.00')
+        dados, _ = _build_generator_payload(LaudoFormInput(importacao_avaliacoes=choices), None, imported)
+        self.assertIn('R$ 1.200,00', dados['valores_mercado'])
+        doc = Document()
+        calculation_sections(doc, imported)
+        text = '\n'.join(cell.text for table in doc.tables for r in table.rows for cell in r.cells)
+        self.assertIn('Valor total registrado na avaliação de origem', text)
+        self.assertIn('R$ 1.215,00', text)
+        self.assertIn('R$ 1.200,00', text)
+
+    def test_valores_editados_invalidos_ou_de_outro_arquivo_sao_rejeitados(self):
+        parsed = parse(evo(), 'teste.evo')
+        for overrides in ({'evo-1': ''}, {'evo-1': '-1'}, {'evo-1': 'NaN'}, {'ame-1': '10'}):
+            with self.subTest(overrides=overrides), self.assertRaises(ValueError):
+                resolve_import(parsed, ImportacaoAvaliacoesInput(valores_adotados=overrides))
+        self.assertEqual(resolve_import(parsed, ImportacaoAvaliacoesInput(valores_adotados={'evo-1': '0'}))['avaliacoes'][0]['valor_total'], '0.00')
+
+    def test_metadados_editados_e_motivos_manuais_chegam_ao_laudo(self):
+        choices = ImportacaoAvaliacoesInput(campos_editados=['modelo_avaliacao', 'metodo_avaliacao', 'datas_referencia'])
+        payload = LaudoFormInput(importacao_avaliacoes=choices, modelo_avaliacao='Nome revisado',
+            metodo_avaliacao='Método descrito pelo avaliador', datas_referencia='Referência revisada',
+            motivos_desvalorizantes=[{'descricao': 'Condição revisada', 'alegado': True, 'confirmado': False}])
+        imported = resolve_import(parse(evo(), 'teste.evo'), choices)
+        dados, motivos = _build_generator_payload(payload, None, imported)
+        self.assertEqual(dados['modelo_avaliacao'], 'Nome revisado')
+        self.assertEqual(dados['metodo_avaliacao'], 'Método descrito pelo avaliador')
+        self.assertEqual(dados['datas_referencia'], 'Referência revisada')
+        self.assertEqual(dados['avaliacoes_importadas']['avaliacoes'][0]['modelo'], 'MODELO_TER')
+        self.assertIn('Condição revisada', motivos['alegados_texto'])
+        self.assertEqual(motivos['confirmados_texto'], '')
+
+    def test_year_parameters_and_base_require_explicit_base_year(self):
+        parsed = parse(ame())
+        self.assertTrue(parsed['avaliacoes'][0]['cenario_base'])
+        self.assertEqual(parsed['avaliacoes'][1]['ano_sugerido'], '2025')
+        with self.assertRaisesRegex(ValueError, 'Ano Base'):
+            resolve_import(parsed, ImportacaoAvaliacoesInput())
+        resolved = resolve_import(parsed, ImportacaoAvaliacoesInput(anos={'ame-1': '2023'}))
+        self.assertEqual([row['ano'] for row in resolved['avaliacoes']], ['2024', '2026'])
+
+    def test_base_with_explicit_year_title_is_recognized_without_manual_mapping(self):
+        data = ame()
+        data['avaliacoes'][0]['titulo'] = '2023'
+        imported = resolve_import(parse(data), ImportacaoAvaliacoesInput())
+        self.assertEqual(imported['avaliacoes'][0]['ano_base'], '2023')
+        self.assertEqual(imported['avaliacoes'][0]['ano'], '2024')
+        self.assertEqual(imported['avaliacoes'][0]['titulo'], 'Exercício 2024 — Cenário base')
+
+    def test_model_year_2015_is_exercise_2016_in_the_document(self):
+        data = ame([{'titulo': '2015', 'modelo': 'MOD_V_TER_Z4_003F', 'avaliacao': {
+            'valores_x': {'2015': 1, '2016': 0}, 'estimado_total': 34275500}}])
+        imported = resolve_import(parse(data), ImportacaoAvaliacoesInput())
+        row = imported['avaliacoes'][0]
+        self.assertEqual(row['ano_base'], '2015')
+        self.assertEqual(row['ano'], '2016')
+        self.assertEqual(row['titulo'], 'Exercício 2016')
+        self.assertEqual(row['titulo_origem'], '2015')
+        self.assertEqual(row['valor_total'], '34275500.00')
+        doc = Document()
+        calculation_sections(doc, imported)
+        self.assertIn('Exercício 2016 — Ano-base 2015', '\n'.join(p.text for p in doc.paragraphs))
+
+    def test_explicit_iptu_interpretation_and_duplicate_years_are_not_summed(self):
+        parsed = parse(ame())
+        resolved = resolve_import(parsed, ImportacaoAvaliacoesInput(referencia_anos='exercicio_iptu', anos={'ame-1': '2025'}))
+        self.assertEqual(len(resolved['avaliacoes']), 2)
+        self.assertEqual([row['ano_base'] for row in resolved['avaliacoes']], ['2024', '2024'])
+
+    def test_evo_preserves_final_total_instead_of_summing_components(self):
+        resolved = resolve_import(parse(evo(), 'teste.evo'), ImportacaoAvaliacoesInput())
+        row = resolved['avaliacoes'][0]
+        self.assertEqual(row['ano_base'], '2025')
+        self.assertEqual(row['valor_total'], '1215.00')
+        self.assertEqual(row['valor_terreno'], '1000.00')
+        self.assertEqual(row['valor_construcao'], '500.00')
+        doc = Document()
+        conclusion_table(doc, resolved)
+        calculation_sections(doc, resolved)
+        texts = '\n'.join(cell.text for table in doc.tables for row in table.rows for cell in row.cells)
+        self.assertIn('R$ 1.215,00', texts)
+        self.assertIn('R$ 500,00', texts)
+        self.assertIn('IPTU 2026', texts)
+        self.assertNotIn('2026 / 2025', texts)
+
+    def test_conflicting_evo_years_need_confirmation(self):
+        data = evo()
+        data['anos'][0]['construcao']['anoReferencia'] = '2024'
+        row = parse(data, 'teste.evo')['avaliacoes'][0]
+        self.assertIsNone(row['ano_sugerido'])
+        self.assertTrue(row['avisos'])
+
+    def test_evo_base_does_not_infer_terrain_year_from_cub_alone(self):
+        data = evo()
+        data['anos'][0]['referencia'] = ''
+        data['anos'][0]['terreno']['avaliacao']['valores_x'] = {'2025': 0}
+        row = parse(data, 'teste.evo')['avaliacoes'][0]
+        self.assertTrue(row['cenario_base'])
+        self.assertIsNone(row['ano_sugerido'])
+
+    def test_explicit_blank_year_cannot_silently_reuse_a_suggestion(self):
+        parsed = parse(ame())
+        with self.assertRaisesRegex(ValueError, '2025'):
+            resolve_import(parsed, ImportacaoAvaliacoesInput(anos={'ame-1': '2023', 'ame-2': ''}))
+
+    def test_adjusted_value_wins_over_raw_estimate(self):
+        data = ame()
+        data['avaliacoes'][1]['avaliacao']['ajuste_territorial'] = {'resultado': {'valor_total_territorial': 1000.50}}
+        self.assertEqual(parse(data)['avaliacoes'][1]['valor_total'], '1000.50')
+
+    def test_reject_unitary_only_instead_of_documenting_it_as_total(self):
+        data = ame()
+        del data['avaliacoes'][0]['avaliacao']['estimado_total']
+        with self.assertRaisesRegex(ValueError, 'valor total'):
+            parse(data)
+
+    def test_unrecognized_version_json_and_extension(self):
+        for content, name in [(b'{}', 'a.ame'), (b'NaN', 'a.evo'), (b'[]', 'a.ame'), (b'broken', 'a.ame'), (b'{}', 'a.docx')]:
+            with self.subTest(name=name, content=content), self.assertRaises(ValueError):
+                parse_export(content, name)
+
+    def test_missing_evo_result_is_rejected(self):
+        data = evo()
+        del data['anos'][0]['resultadoComposicao']
+        with self.assertRaisesRegex(ValueError, 'incompleta'):
+            parse(data, 'teste.evo')
+
+    def test_generator_payload_uses_imported_values_and_not_dummy_values(self):
+        imported = resolve_import(parse(ame()), ImportacaoAvaliacoesInput(anos={'ame-1': '2023'}))
+        payload = LaudoFormInput(modelo_avaliacao='Modelo dummy', valores_mercado=[{'ano': '2020', 'valor': '999999'}])
+        dados, _ = _build_generator_payload(payload, None, imported)
+        self.assertEqual(dados['modelo_avaliacao'], 'MODELO_TER')
+        self.assertIn('1.012,00', dados['valores_mercado'])
+        self.assertNotIn('999999', dados['valores_mercado'])
+        self.assertEqual(dados['valores_mercado_lista'], [])
+
+    def test_cabecalho_resgata_valores_por_extenso_e_referencias_separadas(self):
+        imported = resolve_import(parse(ame()), ImportacaoAvaliacoesInput(anos={'ame-1': '2023'}))
+        dados, _ = _build_generator_payload(LaudoFormInput(datas_referencia='Referência dummy'), None, imported)
+        self.assertEqual(dados['valores_mercado'],
+                         '2024 - R$ 1.012,00 (mil e doze reais)\n'
+                         '2026 - R$ 1.234,00 (mil e duzentos e trinta e quatro reais)')
+        self.assertEqual(dados['datas_referencia'], 'Dezembro/2023, Dezembro/2025')
+        doc = Document()
+        LaudoGenerator()._gerar_cabecalho(doc, dados)
+        celulas = {row.cells[0].text: row.cells[1].text for row in doc.tables[0].rows}
+        self.assertEqual(celulas['Valores de Mercado:'], dados['valores_mercado'])
+        self.assertEqual(celulas['Referências:'], dados['datas_referencia'])
+        self.assertNotIn('ano-base', celulas['Valores de Mercado:'])
+        for row in doc.tables[0].rows:
+            if row.cells[0].text in ('Valores de Mercado:', 'Referências:'):
+                self.assertTrue(row._tr.xpath('./w:trPr/w:cantSplit'))
+            if row.cells[0].text == 'CONCLUSÃO TÉCNICA':
+                self.assertTrue(row.cells[0].paragraphs[0].paragraph_format.keep_with_next)
+
+    def test_cabecalho_preserva_avaliacoes_distintas_no_mesmo_exercicio(self):
+        data = ame()
+        data['avaliacoes'][0]['titulo'] = 'Terreno A'
+        data['avaliacoes'][1]['titulo'] = 'Terreno B'
+        imported = resolve_import(parse(data), ImportacaoAvaliacoesInput(anos={'ame-1': '2025'}))
+        dados, _ = _build_generator_payload(LaudoFormInput(), None, imported)
+        self.assertIn('2026 (Terreno A) - R$ 1.012,00', dados['valores_mercado'])
+        self.assertIn('2026 (Terreno B) - R$ 1.234,00', dados['valores_mercado'])
+        self.assertEqual(dados['datas_referencia'], 'Dezembro/2025')
+
+    def test_cabecalho_evolutivo_usa_total_adotado_por_extenso(self):
+        imported = resolve_import(parse(evo(), 'teste.evo'), ImportacaoAvaliacoesInput())
+        dados, _ = _build_generator_payload(LaudoFormInput(), None, imported)
+        self.assertEqual(dados['valores_mercado'],
+                         '2026 - R$ 1.215,00 (mil e duzentos e quinze reais)')
+        self.assertEqual(dados['datas_referencia'], 'Dezembro/2025')
+
+    def test_cabecalho_manual_preserva_formato_anterior(self):
+        payload = LaudoFormInput(valores_mercado=[{'ano': '2025', 'valor': '500.000,00'}],
+                                 datas_referencia='Dezembro/2024')
+        dados, _ = _build_generator_payload(payload, None)
+        self.assertEqual(dados['valores_mercado'], '2025 - 500.000,00 (quinhentos mil reais)')
+        self.assertEqual(dados['datas_referencia'], 'Dezembro/2024')
+
+    def test_generation_reparses_the_uploaded_file(self):
+        upload = UploadFile(filename='teste.ame', file=io.BytesIO(json.dumps(ame()).encode()))
+        payload = LaudoFormInput(importacao_avaliacoes={'anos': {'ame-1': '2023'}})
+        with patch('backend.app.services.LaudoGenerator') as factory:
+            factory.return_value.gerar.return_value = __import__('pathlib').Path('test.docx')
+            generate_laudo_document(payload, None, upload)
+            dados = factory.return_value.gerar.call_args.args[0]
+            self.assertEqual(len(dados['avaliacoes_importadas']['avaliacoes']), 2)
+        with self.assertRaisesRegex(ValueError, 'Envie o arquivo'):
+            generate_laudo_document(payload, None)
+
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_evo_adjustments.py

@@ -0,0 +1,105 @@
+import copy
+import unittest
+from decimal import Decimal
+from unittest.mock import patch
+
+from docx import Document
+from document.evo_adjustments import applied_reducers, visible_memory
+from document.evolutivo import gerar_corpo_evolutivo, condition_description
+from document.avaliacoes_importadas import calculation_sections
+from document.numbering import NumeradorSecoes
+from test_evolutivo_documento import fixture, resolved, all_text
+
+
+def body(imported):
+    doc=Document(); n=NumeradorSecoes(3); n.subsecao(); n.subsecao()
+    with patch('document.evolutivo.matching_local',return_value=(None,'')):
+        gerar_corpo_evolutivo(doc,imported,n)
+    return doc
+
+
+class AppliedAdjustmentsTests(unittest.TestCase):
+    def test_neutral_execution_overrides_selected_conditions_and_reference_rates(self):
+        row=resolved(fixture((2021,)))['avaliacoes'][0]
+        row['evolutivo']['resultadoComposicao']['redutor88I']=.7
+        self.assertEqual(applied_reducers(row,True),[])
+        self.assertNotIn('redutores_terreno',[s['codigo'] for s in visible_memory(row)])
+        self.assertIn('redutores_imovel',[s['codigo'] for s in visible_memory(row)])
+
+    def test_legacy_unknown_effect_remains_visible_without_inventing_rate(self):
+        row={'evolutivo':{'resultadoComposicao':{'memoria':[{'codigo':'redutores_terreno','resultado':10}]}}}
+        self.assertEqual(applied_reducers(row,True),[('redutorTerreno','Redução territorial registrada',None)])
+        self.assertEqual(len(visible_memory(row)),1)
+
+    def test_component_fallback_uses_effective_saved_memory(self):
+        row={'evolutivo':{'resultadoComposicao':{'memoria':[{'codigo':'redutores_terreno','fator':.895,'componentes':[
+            {'rotulo':'Art. 88, inciso I','reducao':.105},{'rotulo':'Topografia','reducao':0}]}]}}}
+        self.assertEqual(applied_reducers(row,True),[('redutor88I','Art. 88, inciso I',Decimal('.105'))])
+
+    def test_only_effective_reducers_and_years_appear_in_body_and_annex(self):
+        data=fixture((2021,2022))
+        for year in data['anos']:
+            r=year['resultadoComposicao']; r['memoria'][4]['fator']=1
+            r.update(redutor88I=0,redutor6061=0,redutorTopografia=0,redutorAgua=0,redutor88II=0,redutorImovel=0,redutorApan=0,limiteArt88Aplicado=False)
+        r=data['anos'][0]['resultadoComposicao'];r['redutor88I']=.105;r['memoria'][0].update(fator=.895,componentes=[{'rotulo':'Art. 88, inciso I','reducao':.105},{'rotulo':'Topografia','reducao':0}])
+        imported=resolved(data); before=copy.deepcopy(imported)
+        doc=body(imported);text=all_text(doc)
+        for absent in ['Topografia:','Inundação — aplicado','Arts. 60 e 61:','Limite do art. 88','Art. 88, inciso II','APAN considerada no campo','Componentes de referência da MESA:']:
+            self.assertNotIn(absent,text)
+        t=next(t for t in doc.tables if any(c.text=='Art. 88, inciso I — redução efetiva' for r in t.rows for c in r.cells))
+        reduction=next(r for r in t.rows if r.cells[0].text=='Art. 88, inciso I — redução efetiva')
+        self.assertEqual([c.text for c in reduction.cells[1:]],['10,50%','—'])
+        ann=Document();calculation_sections(ann,imported)
+        self.assertNotIn('Redução do imóvel',all_text(ann));self.assertEqual(imported,before)
+
+    def test_inciso_i_excludes_areas_at_or_below_historical_threshold(self):
+        row=resolved(fixture((2021,)))['avaliacoes'][0]
+        row['evolutivo']['resultadoComposicao']['memoria'][0]['fator']=.895
+        row['evolutivo']['resultadoComposicao']['redutor88I']=.105
+        row['evolutivo']['catalogoAjustes']={'art_88_i':{'limite_minimo_area':.1,'condicoes':[
+            {'codigo':'app','rotulo':'APP aplicada','redutor':.7},{'codigo':'outra','rotulo':'Área não participante','redutor':.85}]}}
+        row['evolutivo']['terreno']['avaliacao']['ajuste_territorial']['configuracao']['art_88_i']={'condicoes':{'app':{'percentual_area':.15},'outra':{'percentual_area':.1}}}
+        text=condition_description(row,True)
+        self.assertIn('APP aplicada',text);self.assertIn('10,50%',text);self.assertNotIn('Área não participante',text)
+
+    def test_6061_describes_only_maximum_selected_condition(self):
+        row={'evolutivo':{'resultadoComposicao':{'redutor6061':.6},'catalogoAjustes':{'art_60_61':{'condicoes':[
+            {'codigo':'vila','rotulo':'Vila menor','redutor':.3},{'codigo':'encravado','rotulo':'Encravado aplicado','redutor':.6}]}},
+            'terreno':{'avaliacao':{'ajuste_territorial':{'configuracao':{'art_60_61':{'selecionados':['vila','encravado']}}}}}}}
+        text=condition_description(row,True)
+        self.assertIn('Encravado aplicado',text);self.assertNotIn('Vila menor',text)
+
+    def test_applied_cap_is_documented_with_effective_not_gross_percentage(self):
+        imported=resolved(fixture((2021,)));r=imported['avaliacoes'][0]['evolutivo']['resultadoComposicao']
+        r.update(redutor88II=.2,redutor88IIBruto=.6,limiteArt88Aplicado=True,valorReferenciaArt88=1000,valorAposIncisoIArt88=187.5,valorAposArt88Bruto=75,valorAposArt88Aplicado=150)
+        r['memoria'][4]['fator']=.8
+        imported['avaliacoes'][0]['evolutivo']['catalogoAjustes']={'limite_reducao_art_88':.85}
+        text=all_text(body(imported))
+        self.assertIn('limite conjunto dos incisos I e II do art. 88, previsto em seu § 3º, foi efetivamente acionado',text)
+        self.assertIn('20,00%',text);self.assertNotIn('60,00%',text);self.assertIn('R$ 150,00',text)
+        self.assertIn('85,00%',text);self.assertIn('15,00%',text)
+
+    def test_composite_cub_and_bdi_tables_deduplicate_across_constructions(self):
+        data=fixture((2021,2022));
+        for y in data['anos']:
+            c=copy.deepcopy(y['construcao']['construcoes'][0]);c.update(id='segundo',seq=2,nome='Galpão B')
+            y['construcao']['construcoes'].append(c)
+        doc=body(resolved(data))
+        weighted=[t for t in doc.tables if t.rows[0].cells[1].text=='Projeto padrão']
+        self.assertEqual(len(weighted),1);self.assertEqual(len(weighted[0].rows),3)
+        calculations=[t for t in doc.tables if any(r.cells[0].text=='Valor da construção - VC (R$)' for r in t.rows)]
+        self.assertEqual(len(calculations),2)
+        for t in calculations:
+            for label in ['CUB histórico (R$/m²)','BDI (%)','Depreciação K','Fator remanescente Kd']:
+                self.assertTrue(any(r.cells[0].text==label for r in t.rows))
+
+    def test_changes_in_characteristics_and_compositions_keep_applicability(self):
+        data=fixture((2021,2022));data['anos'][1]['construcao']['construcoes'][0].update(areaCalculada=80,valorResidual=.2)
+        data['anos'][1]['construcao']['construcoes'][0]['cubComposicaoCalculada'][0]['peso']=50
+        doc=body(resolved(data))
+        t=next(t for t in doc.tables if t.rows[0].cells[1].text=='Tipo / ano')
+        self.assertEqual(len(t.rows),3)
+        self.assertIn('IPTU 2023',t.rows[2].cells[0].text)
+        t=next(t for t in doc.tables if t.rows[0].cells[1].text=='Projeto padrão')
+        self.assertEqual(len(t.rows),5)
+        self.assertIn('IPTU 2022',t.rows[1].cells[0].text);self.assertIn('IPTU 2023',t.rows[3].cells[0].text)

tests/test_evolutivo_documento.py

@@ -0,0 +1,330 @@
+import copy
+import json
+import io
+import zipfile
+from pathlib import Path
+import subprocess
+import unittest
+from unittest.mock import patch
+
+import pandas as pd
+from docx import Document
+
+from backend.app.avaliacoes_import import parse_export, resolve_import
+from backend.app.schemas import ImportacaoAvaliacoesInput, LaudoFormInput
+from backend.app.services import _build_generator_payload
+from document.evolutivo import gerar_corpo_evolutivo, gerar_especificacao_evolutivo, currency, construction_groups, model_analysis
+from document.fundamentacao import global_foundation, model_foundation, construction_foundation
+from document.generator import LaudoGenerator
+from document.mesa_content import current_content
+from document.numbering import NumeradorSecoes
+from models.imported_context import matching_local, snapshot_model
+from models.model_data import ModelData
+
+ROOT = Path(__file__).resolve().parents[1]
+MESA = ROOT.parent / 'mesa-frame'
+
+
+def fixture(years=(2021,2022,2023,2024)):
+    rows = []
+    for year in years:
+        construction = {'id':'construcao-a','seq':1,'nome':'Galpão A','tipoConstrucao':'GALPOES (DEPOSITOS)',
+            'areaTotal':100,'areaCalculada':75,'areaEquivalente':75,'areaOrigem':'equivalente',
+            'areasEquivalentes':[{'descricao':'Área coberta','area':100,'coeficiente':.75}],
+            'cubTipo':'GI (Galpao Industrial)','cubTipoSecundario':'R1-N','cubCompostoAtivo':True,
+            'cubComposicaoCalculada':[{'cubTipo':'GI','peso':60,'valorCub':1000},{'cubTipo':'R1-N','peso':40,'valorCub':2000}],
+            'valorCub':1400,'percentualCubCalculado':80,'custoUnitario':1120,'bdi':'25',
+            'anoConstrucao':1985,'vidaUtil':70,'percentualVidaUtilPadrao':50,'percentualVidaUtil':40,
+            'percentualVidaUtilManualAtivo':True,'percentualVidaUtilJustificativa':'SEGREDO INTERNO',
+            'percentualVidaUtilJustificativaInterna':True,'estadoConservacao':'A - novo','coefHeidecke':0,
+            'depreciacao':.28,'valorResidual':.1,'kd':.748,'vcalcConstSeq':78540}
+        ev = {'valores_x':{'2021':int(year==2021),'ATTOTAL':50000},'tipo_y':'unitario','coluna_area':'ATTOTAL',
+            'valor_area':50000,'estimado':100.123456,'estimado_unitario':100.12,'estimado_total':5006000,
+            'ca_inf':85.105,'ca_sup':115.14,'ic_inf':90.11,'ic_sup':110.12,'precisao':'Grau III','amplitude':20,
+            'fundamentacao':'Grau III','qtd_extrapolacoes':0,'ajuste_territorial':{'configuracao':{'campo_arbitrio':{'justificativa':'Escolha técnica salva','fator':.9}}}}
+        ctx = {'version':1,'name':'MODELO_TESTE','prediction':{'names':['const','2021','ATTOTAL'],'params':[1,.5,-.1]},
+            'transformacoes':{'info':['VUNIT: ln(y)','2021: (x)','ATTOTAL: ln(x)'],'X':[{'2021':1,'ATTOTAL':10}], 'y':[4]},
+            'dados':{'df':{'columns':['ANO','2021','ATTOTAL'],'data':[[2020,0,100],[2021,1,200]],'index':[0,1]}},
+            'periodo_dados_mercado':{'data_inicial':'2020-01-01','data_final':'2021-12-31'},
+            'normativeEvidence':{'n':100,'k':2,'regressorPValues':[{'name':'ATTOTAL','pValue':.05}],'fPValue':.001}}
+        rows.append({'id':f'origem-{year}','identificacao':str(year),'referencia':str(year),'concluida':True,
+            'terreno':{'modelo':'MODELO_TESTE','areaModelo':'50000','areaAplicacao':'4126.73','area':'4126.73',
+                'valorTotal':'400000','valorUnitarioOriginal':100.12,'valorUnitario':90.11,
+                'parametrosAplicados':{'2021':int(year==2021),'ATTOTAL':50000},'avaliacao':ev,'contextoModelo':ctx,
+                'fundamentacaoModelo':{'caracterizacao':{'grau':'Grau II','justificativa':'Caracterização salva'},'identificacaoDados':{'grau':'Grau II','justificativa':'Dados identificados'},
+                    'requisitosGrauIII':{'laudoCompleto':'sim','analiseModelo':'sim','enderecosCompletos':'sim','estimativaCentral':'nao'}}},
+            'construcao':{'valorTotal':'78540','anoReferencia':str(year),'area':100,'construcoes':[construction],
+                'avaliacao':{'cubData':f'{year}-10-01','referenciasCalculo':{}},
+                'fundamentacaoMqc':{'definitions':{'formaCub':'Utilizacao CUB para projeto semelhante ao projeto padrao','tipoBdi':'Justificado','depreciacao':'Por metodos tecnicos consagrados, considerando-se idade, vida util e estado de conservacao'}}},
+            'fundamentacaoGlobal':{'fatorComercializacao':'justificado','justificativa':'Condição comercial salva'},
+            'resultadoComposicao':{'valorTerrenoPgv':400000,'valorConstrucao':78540,'valorAposConstrucao':478540,
+                'valorAposRedutoresImovel':450000,'fatorFcAplicado':.95,'valorTotalCalculado':427500,'valorTotal':427500,
+                'valorUnitarioAposRedutoresTerritoriais':100.12,'valorCa':90.11,'fatorCaFinal':.9,
+                'memoria':[{'codigo':code,'rotulo':label,'fator':factor,'resultado':value,'unidade':unit} for code,label,factor,value,unit in [
+                    ('redutores_terreno','Ajustes territoriais',1,100.12,'R$/m²'),('campo_arbitrio','Campo escolhido',.9,90.11,'R$/m²'),
+                    ('conversao_vu_vt','Conversão territorial',4126.73,400000,'R$'),('adicao_construcao','Composição inicial',1,478540,'R$'),
+                    ('redutores_imovel','Redução do imóvel',.94,450000,'R$'),('fator_comercializacao','Fc final',.95,427500,'R$')]]}})
+    return {'format':'mesa-evolutivo','version':2,'anos':rows}
+
+
+def resolved(data=None, **choices):
+    data = data or fixture()
+    return resolve_import(parse_export(json.dumps(data).encode(),'teste.evo'),ImportacaoAvaliacoesInput(**choices))
+
+
+def all_text(doc):
+    return '\n'.join([p.text for p in doc.paragraphs]+[c.text for t in doc.tables for r in t.rows for c in r.cells])
+
+
+class EvolutivoDocumentTests(unittest.TestCase):
+    def test_paragrafo_estatistico_usa_coeficientes_reais_e_referencia_anexos_por_nome(self):
+        model = ModelData(nome='MODELO', path=Path('modelo.dai'), modelos_resumos={'r2': .9387**2})
+        doc = Document(); model_analysis(doc, model, 'unitario')
+        self.assertEqual(len(doc.paragraphs), 1)
+        text = doc.paragraphs[0].text
+        for value in ['0,9387', 'alto grau de correlação', '88%', 'caráter aleatório.',
+                      'Anexo I - Banco de Dados', 'Anexo II - Planilha de Cálculo e Resultados Estatísticos', 'Anexo III - Gráficos']:
+            self.assertIn(value, text)
+        for value in ['encontra-se dentro do previsto', 'distribuição dos resíduos', 'autocorrelação', 'teste F']:
+            self.assertNotIn(value, text)
+        doc = Document(); model_analysis(doc, model, 'total')
+        self.assertIn('variabilidade do valor total em reais', doc.paragraphs[0].text)
+        model.modelos_resumos = {}
+        doc = Document(); model_analysis(doc, model, 'total')
+        self.assertNotIn('coeficiente', doc.paragraphs[0].text)
+
+    def test_resultados_compactos_tem_notas_nativas_preservadas_ao_reabrir(self):
+        from lxml import etree
+        from docx.oxml.ns import qn
+        from document.footnotes import add_footnote
+        imported = resolved(fixture((2021, 2022, 2023, 2024, 2025, 2026)))
+        doc = Document(); num = NumeradorSecoes(3); num.subsecao(); num.subsecao()
+        gerar_corpo_evolutivo(doc, imported, num)
+        tables = [t for t in doc.tables if any(r.cells[0].text == 'IC 80% Inf.' for r in t.rows)]
+        self.assertEqual(len(tables), 2)
+        labels = [r.cells[0].text for r in tables[0].rows]
+        for label in ['Estimado Unitário', 'CA −15%', 'CA +15%', 'IC 80% Inf.', 'IC 80% Sup.']:
+            self.assertIn(label, labels)
+        stream = io.BytesIO(); doc.save(stream); stream.seek(0)
+        reopened = Document(stream)
+        add_footnote(reopened, reopened.add_paragraph('Nota posterior'), 'Nota posterior preserva as anteriores.')
+        stream = io.BytesIO(); reopened.save(stream)
+        with zipfile.ZipFile(stream) as archive:
+            root = etree.fromstring(archive.read('word/footnotes.xml'))
+            body = etree.fromstring(archive.read('word/document.xml'))
+            refs = body.findall('.//'+qn('w:footnoteReference'))
+            notes = {n.get(qn('w:id')): ''.join(n.itertext()) for n in root if int(n.get(qn('w:id'))) > 0}
+            self.assertEqual(len(refs), 7)
+            self.assertEqual(len(notes), 7)
+            self.assertEqual({r.get(qn('w:id')) for r in refs}, set(notes))
+            self.assertIn('CA: campo de arbítrio', notes['2'])
+            self.assertIn('intervalo de confiança de 80%', notes['3'])
+            self.assertIn('R$ no modelo total', notes['3'])
+
+    def test_restaura_pesquisa_padrao_e_identifica_modelo_somente_na_tabela_da_equacao(self):
+        imported = resolved()
+        doc = Document(); num = NumeradorSecoes(3); num.subsecao(); num.subsecao()
+        gerar_corpo_evolutivo(doc, imported, num)
+        paragraphs = '\n'.join(p.text for p in doc.paragraphs)
+        self.assertIn('Efetuou-se uma pesquisa junto às imobiliárias e às transações através das guias de ITBI', paragraphs)
+        self.assertIn('constituída por 100 imóveis', paragraphs)
+        self.assertIn('entre 1 de janeiro de 2020 e 31 de dezembro de 2021', paragraphs)
+        self.assertIn('empregou-se a regressão múltipla para a homogeneização dos dados', paragraphs)
+        self.assertEqual(paragraphs.count('Efetuou-se uma pesquisa'), 1)
+        self.assertNotIn('MODELO_TESTE', paragraphs)
+        self.assertNotIn('— contexto ', paragraphs)
+        tables = [t for t in doc.tables if [c.text for c in t.rows[0].cells] == ['Modelo', 'Nº de dados', 'Equação']]
+        self.assertEqual(len(tables), 1)
+        self.assertEqual(tables[0].rows[1].cells[0].text, 'MODELO_TESTE')
+        self.assertEqual(tables[0].rows[1].cells[1].text, '100')
+        self.assertIn('VUNIT', tables[0].rows[1].cells[2].text)
+
+    def test_pesquisas_diferentes_preservam_amostras_periodos_e_escopo_das_equacoes(self):
+        data = fixture()
+        context = data['anos'][1]['terreno']['contextoModelo']
+        context['normativeEvidence']['n'] = 75
+        context['periodo_dados_mercado'] = {'data_inicial': '2019-02-01', 'data_final': '2021-03-31'}
+        imported = resolved(data)
+        doc = Document(); num = NumeradorSecoes(3); num.subsecao(); num.subsecao()
+        gerar_corpo_evolutivo(doc, imported, num)
+        text = all_text(doc)
+        self.assertIn('constituída por 100 imóveis', text)
+        self.assertIn('constituída por 75 imóveis', text)
+        self.assertIn('entre 1 de fevereiro de 2019 e 31 de março de 2021', text)
+        self.assertIn('IPTU 2022 / base 2021', text)
+        self.assertIn('IPTU 2023 / base 2022', text)
+        self.assertEqual(text.count('Os elementos amostrais tomados como referência'), 1)
+
+    def test_texto_usa_referencia_explicita_do_contexto_sem_coluna_ano(self):
+        data = fixture((2021,))
+        context = data['anos'][0]['terreno']['contextoModelo']
+        context['referencia_temporal'] = {'tipo': 'ano', 'anos_base': [2020], 'variaveis_ano': ['2021']}
+        context['dados']['df'] = {'columns': ['2021', 'ATTOTAL'], 'data': [[0, 100], [1, 200]], 'index': [0, 1]}
+        imported = resolved(data)
+        self.assertEqual(snapshot_model(imported['avaliacoes'][0]).ano_base, 2020)
+        doc = Document(); num = NumeradorSecoes(3); num.subsecao(); num.subsecao()
+        with patch('document.evolutivo.matching_local', return_value=(None, '')):
+            gerar_corpo_evolutivo(doc, imported, num)
+        self.assertIn('2020 (ano-base do modelo)', all_text(doc))
+        self.assertNotIn('Ano-base não identificado', all_text(doc))
+
+    def test_contexto_antigo_recupera_referencia_apenas_de_versao_local_confirmada(self):
+        row = resolved(fixture((2021,)))['avaliacoes'][0]
+        row['evolutivo']['terreno']['contextoModelo']['dados']['df'] = {}
+        local = ModelData(nome='MODELO_TESTE', path=Path('modelo.dai'), ano_base=2020)
+        with patch('models.imported_context.matching_local', return_value=(local, '')) as match:
+            self.assertEqual(snapshot_model(row).ano_base, 2020)
+            match.assert_called_once_with(row)
+        with patch('models.imported_context.matching_local', return_value=(None, 'Versão divergente')):
+            self.assertIsNone(snapshot_model(row).ano_base)
+
+    def test_annual_construction_uuids_do_not_repeat_the_same_methodology(self):
+        data=fixture()
+        for i,y in enumerate(data['anos']):
+            y['construcao']['construcoes'][0]['id']=f'copia-anual-{i}'
+            y['construcao']['construcoes'][0]['areasEquivalentes'][0]['id']=f'area-{i}'
+        imported=resolved(data)
+        self.assertEqual(len(construction_groups(imported['avaliacoes'])),1)
+        doc=Document();num=NumeradorSecoes(3);num.subsecao();num.subsecao()
+        with patch('document.evolutivo.matching_local',return_value=(None,'')):gerar_corpo_evolutivo(doc,imported,num)
+        self.assertEqual(sum(p.text.startswith('Composição das áreas') for p in doc.paragraphs),1)
+
+    def test_duplicate_exercises_keep_separate_labels_and_results(self):
+        data=fixture((2021,2021));data['anos'][1]['identificacao']='Outra unidade';data['anos'][1]['resultadoComposicao']['valorTotal']=500000
+        imported=resolved(data)
+        self.assertEqual(len(imported['avaliacoes']),2)
+        self.assertTrue(all(row['referencia_duplicada'] for row in imported['avaliacoes']))
+        doc=Document();num=NumeradorSecoes(3);num.subsecao();num.subsecao()
+        with patch('document.evolutivo.matching_local',return_value=(None,'')):gerar_corpo_evolutivo(doc,imported,num)
+        self.assertIn('[evo-1]',all_text(doc));self.assertIn('[evo-2]',all_text(doc))
+        self.assertEqual(imported['avaliacoes'][1]['valor_total'],'500000.00')
+
+    def test_inconsistent_saved_results_are_reported_not_repaired(self):
+        imported=resolved(fixture((2021,)))
+        row=imported['avaliacoes'][0]
+        self.assertTrue(row['revisao_documental']['conferencias'])
+        self.assertEqual(row['valor_terreno'],'400000.00')
+        self.assertEqual(row['valor_total'],'427500.00')
+
+    def test_import_keeps_all_evidence_and_original_untouched(self):
+        data = fixture()
+        before = copy.deepcopy(data)
+        parsed = resolved(data)
+        self.assertEqual(data,before)
+        row = parsed['avaliacoes'][0]
+        self.assertEqual(row['evolutivo']['terreno']['areaModelo'],'50000')
+        self.assertEqual(row['evolutivo']['terreno']['areaAplicacao'],'4126.73')
+        self.assertEqual(row['construcoes'][0]['custoUnitario'],1120)
+        self.assertEqual(row['id_origem'],'origem-2021')
+        self.assertEqual(row['complementos']['justificativa_vu'],'Escolha técnica salva')
+
+    def test_full_body_has_hierarchy_shared_notes_and_saved_operations(self):
+        imported = resolved(complementos={'evo-1':{'justificativa_area':'Unidade autônoma da gleba','bdi':{'construcao-a':'Composição justificada do caso'}}},valores_adotados={'evo-1':'420000'})
+        doc = Document()
+        num = NumeradorSecoes(2); num.secao(); num.subsecao(); num.subsecao()
+        with patch('document.evolutivo.matching_local',return_value=(None,'Modelo sem correspondência confirmada.')):
+            refs = gerar_corpo_evolutivo(doc,imported,num)
+        gerar_especificacao_evolutivo(doc,imported,refs)
+        from document.avaliacoes_importadas import conclusion_table
+        conclusion_table(doc,imported)
+        text = all_text(doc)
+        for part in ['3.3 AVALIAÇÃO DO TERRENO','3.3.1.1 Variáveis','3.4 AVALIAÇÃO DAS CONSTRUÇÕES','3.4.1.3 BDI','3.5 AVALIAÇÃO DO IMÓVEL OBJETO',
+                     'Ross-Heidecke','CUNIT = CUB','Kd = R +','Unidade autônoma da gleba','Composição justificada do caso','50.000,00','4.126,73','10/2021','R$ 427.500,00','R$ 420.000,00','quatrocentos e vinte mil reais','Critério da adoção','CUB composto','Caracterização salva']:
+            self.assertIn(part,text)
+        self.assertNotIn('SEGREDO INTERNO',text)
+        self.assertNotIn('11/2021',text)
+        self.assertEqual(text.count('3.3.1.1 Variáveis'),1)
+        self.assertIn(current_content()['notas']['bdi'],text)
+        self.assertEqual(refs,{'terreno':'3.3','construcoes':'3.4','composicao':'3.5'})
+        composition = next(t for t in doc.tables if any(c.text=='Base antes dos redutores do imóvel' for r in t.rows for c in r.cells))
+        labels = [r.cells[0].text for r in composition.rows]
+        self.assertLess(labels.index('Base antes dos redutores do imóvel'),labels.index('Fc aplicado'))
+        # The complete ordered evidence belongs to the supporting annex.
+        annex=Document(); from document.avaliacoes_importadas import calculation_sections
+        calculation_sections(annex,imported)
+        memory = next(t for t in annex.tables if any(c.text=='Composição inicial' for r in t.rows for c in r.cells))
+        labels=[r.cells[0].text for r in memory.rows]
+        self.assertLess(labels.index('Composição inicial'),labels.index('Fc final'))
+
+
+    def test_applied_parameters_win_over_evaluation_old_values(self):
+        data = fixture((2021,)); data['anos'][0]['terreno']['avaliacao']['valores_x']['ATTOTAL'] = 999999
+        imported = resolved(data)
+        from document.avaliacoes_importadas import calculation_sections
+        doc = Document(); calculation_sections(doc,imported)
+        self.assertIn('50000',all_text(doc)); self.assertNotIn('999999',all_text(doc))
+
+    def test_manual_foundation_and_case_reasons_can_be_overridden_without_recalculation(self):
+        row = resolved(fixture((2021,)),complementos={'evo-1':{'justificativa_vu':'Novo fundamento','caracterizacao_grau':'Grau I','fc_criterio':'arbitrado'}})['avaliacoes'][0]
+        self.assertEqual(row['complementos']['justificativa_vu'],'Novo fundamento')
+        self.assertEqual(model_foundation(row['evolutivo'])['grade'],'Grau II')
+        self.assertEqual(global_foundation(row['evolutivo'])['items'][2]['grade'],'Grau I')
+        self.assertEqual(row['valor_total'],'427500.00')
+
+    def test_does_not_use_local_model_by_name_without_version_evidence(self):
+        row = resolved(fixture((2021,)))['avaliacoes'][0]
+        fake = type('Local',(),{'modelos_sm':None})()
+        with patch('models.imported_context.list_available_models',return_value=['MODELO_TESTE']),patch('models.imported_context.get_model',return_value=fake):
+            model,warning = matching_local(row)
+        self.assertIsNone(model); self.assertIn('não foi confirmada',warning)
+
+    def test_legacy_evo_generates_pending_notes_without_inventing_values(self):
+        data = fixture((2021,)); y = data['anos'][0]
+        y['terreno'].pop('contextoModelo'); y['terreno'].pop('fundamentacaoModelo')
+        y['construcao'].pop('fundamentacaoMqc'); y['construcao']['construcoes']=[]
+        y['resultadoComposicao'].pop('memoria'); y['fundamentacaoGlobal']={}
+        imported = resolved(data)
+        doc=Document(); num=NumeradorSecoes(3); num.subsecao();num.subsecao()
+        refs=gerar_corpo_evolutivo(doc,imported,num);gerar_especificacao_evolutivo(doc,imported,refs)
+        self.assertIn('não preserva o contexto',all_text(doc))
+        self.assertIn('Pendente',all_text(doc))
+
+    def test_header_methods_and_total_agree_with_conclusion(self):
+        imported=resolved(fixture((2021,)),valores_adotados={'evo-1':'420000'})
+        dados,_ = _build_generator_payload(LaudoFormInput(),None,imported)
+        self.assertEqual(dados['metodo_avaliacao'],'Método Comparativo Dados de Mercado - ABNT NBR 14.653-2 e Método de Quantificação de Custo')
+        self.assertIn('R$ 420.000,00',dados['valores_mercado'])
+        self.assertEqual(currency('999999999999.995'),'R$ 1.000.000.000.000,00')
+
+    def test_saved_package_takes_priority_and_sync_catalogs_match(self):
+        saved=copy.deepcopy(current_content()); saved['notas']['bdi']='BDI: referência preservada no trabalho.';saved['identificador']='historico'
+        data=fixture((2021,2022)); data['anos'][0]['documentacaoTecnica']=saved
+        imported=resolved(data);doc=Document();num=NumeradorSecoes(3);num.subsecao();num.subsecao()
+        with patch('document.evolutivo.matching_local',return_value=(None,'')):gerar_corpo_evolutivo(doc,imported,num)
+        self.assertIn('BDI: referência preservada no trabalho.',all_text(doc))
+        self.assertIn(current_content()['notas']['bdi'],all_text(doc))
+        self.assertEqual(current_content(),json.loads((MESA/'frontend/src/evolutivo/documentacaoTecnica.json').read_text()))
+
+    def test_invalid_complements_cannot_target_another_file_or_claim_an_unknown_grade(self):
+        for choices in [{'complementos':{'evo-100':{'justificativa_fc':'x'}}},{'complementos':{'evo-1':{'fc_criterio':'inventado'}}},{'complementos':{'evo-1':{'caracterizacao_grau':'Grau IV'}}}]:
+            with self.subTest(choices=choices),self.assertRaises(ValueError):resolved(fixture((2021,)),**choices)
+
+    def test_foundation_scoring_matches_actual_mesa_algorithms(self):
+        cases=[]
+        for pg in [None,.05,.15,.25,.4]:
+            for manual in ['', 'Grau I','Grau III']:
+                y=fixture((2021,))['anos'][0]
+                y['terreno']['contextoModelo']['normativeEvidence']['regressorPValues']=[{'name':'x','pValue':pg}]
+                y['terreno']['fundamentacaoModelo']['caracterizacao']['grau']=manual
+                cases.append(y)
+        for count,impact in [(None,None),(0,None),(1,None),(1,14),(1,16),(2,21)]:
+            y=fixture((2021,))['anos'][0]; y['terreno']['avaliacao'].pop('fundamentacao')
+            y['terreno']['avaliacao'].update(qtd_extrapolacoes=count,perc_ext=impact);cases.append(y)
+        for bdi in ['','Arbitrado','Calculado']:
+            y=fixture((2021,))['anos'][0];y['construcao']['fundamentacaoMqc']['definitions']['tipoBdi']=bdi;cases.append(y)
+        script="""import {createServer} from 'vite';
+const s=await createServer({server:{middlewareMode:true},appType:'custom',logLevel:'silent'});
+try { const m=await s.ssrLoadModule('/src/globalFoundation.js'); let raw=''; for await(const c of process.stdin)raw+=c;
+process.stdout.write(JSON.stringify(JSON.parse(raw).map(y=>m.calculateGlobalFoundation(y)))); } finally {await s.close();}"""
+        actual=json.loads(subprocess.run(['node','--input-type=module','-e',script],input=json.dumps(cases),text=True,capture_output=True,cwd=MESA/'frontend',check=True).stdout)
+        for y,js in zip(cases,actual):
+            py=global_foundation(y)
+            with self.subTest(manual=y['terreno']['fundamentacaoModelo'],ev=y['terreno']['avaliacao']):
+                self.assertEqual(py['grade'],js['grade'])
+                self.assertEqual(py['totalPoints'],js['totalPoints'])
+                self.assertEqual(py['terrain']['grade'],js['terrainFoundation']['grade'])
+                self.assertEqual(py['construction']['grade'],js['constructionFoundation']['enquadramento'])
+                self.assertEqual({i['key']:i['points'] for i in py['terrain']['items']},{i['key']:i['points'] for i in js['terrainFoundation']['items']})
+
+
+if __name__=='__main__':unittest.main()

tests/test_hf_model_repository.py

@@ -0,0 +1,137 @@
+import os
+import sys
+import unittest
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from types import SimpleNamespace
+from unittest.mock import Mock, patch
+
+import joblib
+import pandas as pd
+from fastapi.testclient import TestClient
+from backend.app.main import app
+from models import registry
+from models.hf_repository import HfModelRegistry, ModelRepositoryError
+
+
+def info(sha, *files):
+    return SimpleNamespace(sha=sha, siblings=[SimpleNamespace(rfilename=f) for f in files])
+
+
+class HfModelRepositoryTests(unittest.TestCase):
+    def setUp(self):
+        self.environment = patch.dict(os.environ, {}, clear=True)
+        self.environment.start()
+        self.saved_registry = registry._registry
+        registry._registry = None
+        self.api = Mock()
+        self.download = Mock(return_value='/cache/sha1/modelos_dai/MODELO.dai')
+        self.hub = SimpleNamespace(HfApi=Mock(return_value=self.api), hf_hub_download=self.download)
+        self.modules = patch.dict(sys.modules, {'huggingface_hub': self.hub})
+        self.modules.start()
+
+    def tearDown(self):
+        registry._registry = self.saved_registry
+        self.modules.stop()
+        self.environment.stop()
+
+    def test_spaces_always_selects_dataset_even_with_local_override(self):
+        for variable in ['SPACE_ID', 'SPACE_AUTHOR_NAME', 'HF_SPACE_ID']:
+            with self.subTest(variable=variable), patch.dict(os.environ, {variable: 'space', 'MODELOS_REPOSITORIO_PROVIDER': 'local'}):
+                registry._registry = None
+                self.assertIsInstance(registry.get_registry(Path('/local/models')), HfModelRegistry)
+        self.assertIsInstance(registry.get_registry(), HfModelRegistry)
+
+    def test_local_development_retains_local_models(self):
+        with TemporaryDirectory() as folder:
+            (Path(folder)/'LOCAL.dai').touch()
+            self.assertEqual(registry.get_registry(Path(folder)).list_models(), ['LOCAL'])
+        self.hub.HfApi.assert_not_called()
+
+    def test_remote_catalog_filters_backups_nested_paths_and_non_models(self):
+        self.api.dataset_info.return_value = info('sha1', 'modelos_dai/MODELO.dai',
+            'modelos_dai/OUTRO.dai', 'modelos_dai/README.md', 'backups/ANTIGO.dai',
+            'modelos_dai/backups/ANTIGO.dai', 'modelos_dai/../ESCAPE.dai')
+        repository = HfModelRegistry()
+        self.assertEqual(repository.list_models(), ['MODELO', 'OUTRO'])
+        self.assertEqual(repository.discover_models(), ['MODELO', 'OUTRO'])
+        self.api.dataset_info.assert_called_once_with('gui-sparim/repositorio_mesa', revision='main', token=None)
+        self.download.assert_not_called()
+        self.assertIsNone(repository.get_model('../ESCAPE'))
+
+    def test_selected_model_uses_pinned_revision_and_authenticated_backend_download(self):
+        os.environ.update(HF_TOKEN='test-secret', MODELOS_REPOSITORIO_HF_REPO_ID='org/mesa',
+                          MODELOS_REPOSITORIO_HF_REVISION='producao', MODELOS_REPOSITORIO_HF_SUBDIR='arquivos')
+        self.api.dataset_info.return_value = info('commit-1', 'arquivos/MODELO.dai')
+        model = object()
+        repository = HfModelRegistry()
+        with patch('models.hf_repository.load_model', return_value=model) as load:
+            self.assertIs(repository.get_model('MODELO'), model)
+            self.assertIs(repository.get_model('MODELO'), model)
+            load.assert_called_once_with(Path(self.download.return_value))
+        self.download.assert_called_once_with(repo_id='org/mesa', repo_type='dataset', filename='arquivos/MODELO.dai', revision='commit-1', token='test-secret')
+
+    def test_new_commit_invalidates_model_cache_and_deleted_models(self):
+        os.environ['MODELOS_REPOSITORIO_HF_CACHE_TTL_SECONDS'] = '0'
+        self.api.dataset_info.side_effect = [info('sha1', 'modelos_dai/MODELO.dai'),
+            info('sha2', 'modelos_dai/MODELO.dai'), info('sha3', 'modelos_dai/NOVO.dai')]
+        repository = HfModelRegistry()
+        first, second = object(), object()
+        with patch('models.hf_repository.load_model', side_effect=[first, second]):
+            self.assertIs(repository.get_model('MODELO'), first)
+            self.assertIs(repository.get_model('MODELO'), second)
+            self.assertIsNone(repository.get_model('MODELO'))
+        self.assertEqual([c.kwargs['revision'] for c in self.download.call_args_list], ['sha1', 'sha2'])
+
+    def test_clear_cache_refreshes_catalog(self):
+        self.api.dataset_info.return_value = info('sha1', 'modelos_dai/MODELO.dai')
+        repository = HfModelRegistry()
+        repository.list_models(); repository.clear_cache(); repository.list_models()
+        self.assertEqual(self.api.dataset_info.call_count, 2)
+
+    def test_access_failure_does_not_use_local_or_stale_models_or_leak_secret(self):
+        os.environ['MODELOS_REPOSITORIO_HF_CACHE_TTL_SECONDS'] = '0'
+        self.api.dataset_info.side_effect = [info('sha1', 'modelos_dai/MODELO.dai'), RuntimeError('test-secret')]
+        repository = HfModelRegistry()
+        self.assertEqual(repository.list_models(), ['MODELO'])
+        with self.assertRaises(ModelRepositoryError) as failure:
+            repository.list_models()
+        self.assertNotIn('test-secret', str(failure.exception))
+        self.assertIn('HF_TOKEN', str(failure.exception))
+
+    def test_download_failure_does_not_load_bundled_model(self):
+        self.api.dataset_info.return_value = info('sha1', 'modelos_dai/MODELO.dai')
+        self.download.side_effect = RuntimeError('test-secret')
+        with patch('models.hf_repository.load_model') as load, self.assertRaises(ModelRepositoryError):
+            HfModelRegistry().get_model('MODELO')
+        load.assert_not_called()
+
+    def test_api_returns_service_unavailable_for_repository_failure(self):
+        os.environ['SPACE_ID'] = 'org/gerador'
+        self.api.dataset_info.side_effect = RuntimeError('test-secret')
+        with TestClient(app) as client:
+            response = client.get('/api/options')
+        self.assertEqual(response.status_code, 503)
+        self.assertIn('repositório de modelos da MESA', response.json()['detail'])
+        self.assertNotIn('test-secret', response.text)
+
+    def test_api_uses_remote_catalog_and_loads_downloaded_dai(self):
+        os.environ['SPACE_ID'] = 'org/gerador'
+        self.api.dataset_info.return_value = info('sha1', 'modelos_dai/REMOTO.dai')
+        with TemporaryDirectory() as folder:
+            path = Path(folder) / 'REMOTO.dai'
+            joblib.dump({'dados': {'df': pd.DataFrame({'AREA': [200], 'VU': [300]})}}, path)
+            self.download.return_value = str(path)
+            with TestClient(app) as client:
+                catalog = client.get('/api/models')
+                columns = client.get('/api/models/REMOTO/columns')
+            self.assertEqual(catalog.status_code, 200)
+            self.assertEqual(catalog.json(), {'models': ['REMOTO']})
+            self.assertEqual(columns.status_code, 200)
+            self.assertEqual(columns.json(), {'modelo': 'REMOTO', 'columns': ['AREA', 'VU']})
+            self.assertEqual(registry.get_model('REMOTO').path, path)
+            self.assertEqual(self.download.call_count, 1)
+
+
+if __name__ == '__main__':
+    unittest.main()