fix: explain IVA query conditions and distinguish integration failures

This commit is contained in:
2026-10-21 13:35:22 +02:00
parent bd5166bd11
commit 0d7b70459d
15 changed files with 327 additions and 24 deletions
@@ -1,5 +1,6 @@
import { useEffect, useState } from 'react';
import { fiscalComponentCodes } from '@/lib/simulation-contract';
import { ivaIssueText, type IvaDiagnostic, type IvaIssue } from '@/lib/iva-diagnostics';
type Parameter = {
parameter_code: string;
@@ -56,6 +57,8 @@ export function SimulationFiscalStatus({
periodStart,
periodEnd,
context,
onDiagnostics,
onCorrect,
}: {
salaryView?: string;
scenarioMode?: string;
@@ -63,8 +66,11 @@ export function SimulationFiscalStatus({
periodStart?: string;
periodEnd?: string;
context?: Record<string, string>;
onDiagnostics?: (issues: IvaIssue[]) => void;
onCorrect?: (field: string) => void;
}) {
const [parameters, setParameters] = useState<Parameter[]>([]);
const [diagnostics, setDiagnostics] = useState<IvaDiagnostic[]>([]);
const [requestState, setRequestState] = useState('idle');
const [retry, setRetry] = useState(0);
@@ -79,10 +85,14 @@ export function SimulationFiscalStatus({
!periodEnd
) {
setParameters([]);
setDiagnostics([]);
onDiagnostics?.([]);
setRequestState('idle');
return;
}
const abort = new AbortController();
setDiagnostics([]);
onDiagnostics?.([]);
setRequestState('loading');
void fetch('/api/v1/tax-parameters/resolve', {
method: 'POST',
@@ -104,11 +114,15 @@ export function SimulationFiscalStatus({
if (!response.ok) throw new Error('lookup_failed');
const payload = (await response.json()) as {
parameters?: Parameter[];
diagnostics?: IvaDiagnostic[];
};
if (abort.signal.aborted) return;
setParameters(
Array.isArray(payload.parameters) ? payload.parameters : [],
);
const details = Array.isArray(payload.diagnostics) ? payload.diagnostics : [];
setDiagnostics(details);
onDiagnostics?.(details.flatMap((detail) => detail.issues));
setRequestState('done');
})
.catch((error: unknown) => {
@@ -158,7 +172,7 @@ export function SimulationFiscalStatus({
{requestState === 'loading'
? 'A consultar parâmetros aprovados para o período e âmbito indicados…'
: requestState === 'error'
? 'Não foi possível consultar os parâmetros; o resultado permanece indeterminado.'
? 'Falha na consulta do sistema: não foi possível obter os parâmetros. O problema não é atribuído às respostas; estas foram preservadas. Tente novamente.'
: !periodStart || !periodEnd
? 'Indique um período exacto. Para periodicidade mensal ou trimestral, seleccione o mês ou trimestre.'
: `Período consultado: ${periodStart} a ${periodEnd}.`}
@@ -186,6 +200,22 @@ export function SimulationFiscalStatus({
{salaryViewMessages[salaryView]}
</p>
)}
{diagnostics.length > 0 && <div role="alert" className="space-y-3 rounded border border-amber-700 p-3">
<h4 className="font-semibold">IVA — taxa geral: condições não satisfeitas</h4>
<p>Não foi possível resolver este parâmetro. As respostas foram preservadas; esta consulta não executa o cálculo do imposto.</p>
{diagnostics.map((detail, index) => <div key={index}>
<ul className="list-disc pl-5">{detail.issues.map((issue, issueIndex) => <li key={issueIndex}>
{ivaIssueText(issue)}{' '}
{issue.field && <a className="underline" href={`#field-${issue.field}`} onClick={(event) => { if (onCorrect) { event.preventDefault(); onCorrect(issue.field!); } }}>Rever {issue.label.toLowerCase()}</a>}
{issue.category === 'system_configuration' && issue.field === 'fiscal_operation' && <a className="ml-2 underline" href="#published-iva">Abrir IVA — taxa geral</a>}
</li>)}</ul>
<details className="mt-2"><summary className="cursor-pointer underline">Ver fundamento</summary>
<p>IVA — taxa geral · versão {detail.rule_version}. Vigência: {detail.validity.start} a {detail.validity.end ?? 'sem data final indicada'}.</p>
<p>{detail.source.title} — {detail.source.diploma}, {detail.source.article}</p>
{detail.source.url?.startsWith('https://') && <a className="underline" href={detail.source.url} target="_blank" rel="noreferrer">Consultar fonte</a>}
</details>
</div>)}
</div>}
<ul className="grid gap-2 sm:grid-cols-2 lg:grid-cols-3">
{fiscalComponentCodes.map((code) => {
const selected =
@@ -211,13 +241,13 @@ export function SimulationFiscalStatus({
</p>
) : parameters.length === 0 ? (
<p className="text-sm">
Indeterminado — nenhum parâmetro publicado
{code === 'IVA' ? 'Indeterminado — não existe uma versão elegível visível nesta consulta. Consulte o diagnóstico do período acima, quando disponível. Sem esse diagnóstico, não é possível distinguir ausência de cobertura de indisponibilidade da regra ou da fonte; não se atribui o problema às suas respostas.' : <>Indeterminado — nenhum parâmetro publicado
aplicável. Faltam parâmetros aprovados para{' '}
{code}, no período {periodStart} a{' '}
{periodEnd} e no âmbito indicado. A consulta
não identifica um conjunto obrigatório de
parâmetros; não é possível determinar o
imposto nem substituir as lacunas por zero.
imposto nem substituir as lacunas por zero.</>}
</p>
) : (
<div className="space-y-2 text-sm">
@@ -227,7 +257,7 @@ export function SimulationFiscalStatus({
className="border-t pt-2"
>
<strong>
{parameter.parameter_code}
{parameter.parameter_code === 'IVA_GENERAL_RATE' ? 'IVA — taxa geral' : parameter.parameter_code}
</strong>
{parameter.status === 'resolved' ? (
<>
@@ -238,10 +268,10 @@ export function SimulationFiscalStatus({
</p>
<p>
Regra{' '}
{parameter.rule_code} v
{parameter.parameter_code === 'IVA_GENERAL_RATE' ? 'IVA — taxa geral' : parameter.rule_code} v
{parameter.rule_version}
; âmbito{' '}
{parameter.scope_key}
{parameter.parameter_code === 'IVA_GENERAL_RATE' ? 'operação interna geral sobre base líquida em MZN' : parameter.scope_key}
</p>
<p>
Vigência:{' '}
@@ -279,13 +309,13 @@ export function SimulationFiscalStatus({
target="_blank"
rel="noreferrer"
>
Consultar fundamento
Ver fundamento
</a>
)}
</>
) : (
<p>
{labels[parameter.status] ??
{(parameter.parameter_code === 'IVA_GENERAL_RATE' && diagnostics.length ? 'Consulte acima cada condição e o fundamento da versão.' : labels[parameter.status]) ??
'Indeterminado — não foi possível validar o parâmetro.'}
</p>
)}
+14 -2
View File
@@ -56,6 +56,7 @@ import { SimulationFinancialTools } from '@/components/simulation-financial-tool
import { SimulationCashflowPlanner } from '@/components/simulation-cashflow-planner';
import { SimulationBusinessPlan } from '@/components/simulation-business-plan';
import { SimulationFiscalStatus } from '@/components/simulation-fiscal-status';
import { ivaIssueText, type IvaIssue } from '@/lib/iva-diagnostics';
import {
ProjectMilestonePlanner,
ProjectTeamPlanner,
@@ -810,6 +811,7 @@ export function SimulationForm() {
});
const [step, setStep] = useState(0);
const [errors, setErrors] = useState<Record<string, string>>({});
const [ivaIssues, setIvaIssues] = useState<IvaIssue[]>([]);
const [serverFieldErrors, setServerFieldErrors] = useState<
Record<string, string>
>({});
@@ -1936,6 +1938,7 @@ export function SimulationForm() {
) {
if (!ready) return;
setContinueLaterSaved(false);
setIvaIssues((previous) => previous.filter((issue) => issue.field !== key));
setServerFieldErrors((previous) => {
const next = { ...previous };
delete next[key];
@@ -3285,6 +3288,7 @@ export function SimulationForm() {
: Boolean(field.required);
const fieldError =
serverFieldErrors[field.key] ?? errors[field.key];
const ivaNotes = ivaIssues.filter((issue) => issue.field === field.key).map((issue, index) => <p key={index} role="note" className="mt-1 text-sm text-amber-950">{ivaIssueText(issue)}</p>);
if (field.options) {
const parentKey =
field.key === 'district_id'
@@ -3331,6 +3335,7 @@ export function SimulationForm() {
}
/>
<FieldGuidance fieldKey={field.key} />
{ivaNotes}
</div>
);
}
@@ -3405,6 +3410,7 @@ export function SimulationForm() {
{fieldError}
</p>
)}
{ivaNotes}
{field.key === 'reduction' && (
<p className="mt-1 text-sm text-slate-600">
Hipótese sua, não representa um
@@ -3609,6 +3615,12 @@ export function SimulationForm() {
aria-label="Consulta de parâmetros fiscais"
>
<SimulationFiscalStatus
onDiagnostics={setIvaIssues}
onCorrect={(key) => {
const target = journeySections.findIndex((section) => (simulationFieldGroups[section.id] ?? []).some((field) => field.key === key));
if (target >= 0) setStep(target);
window.requestAnimationFrame(() => document.getElementById(`field-${key}`)?.focus());
}}
salaryView={String(draft.irps_salary_view ?? '')}
scenarioMode={
openedTool === 'fiscal'
@@ -3618,7 +3630,7 @@ export function SimulationForm() {
component={String(draft.fiscal_component ?? '')}
periodStart={getFiscalPeriodRange(draft)?.start}
periodEnd={getFiscalPeriodRange(draft)?.end}
context={Object.fromEntries(
context={{ ...Object.fromEntries(
[
'fiscal_periodicity',
'fiscal_operation',
@@ -3635,7 +3647,7 @@ export function SimulationForm() {
? [[key, draft[key] as string]]
: [],
),
)}
), ...(typeof draft.fiscal_currency === 'string' && draft.fiscal_currency !== '' ? {currency: draft.fiscal_currency} : {}) }}
/>
</div>
)}
@@ -51,8 +51,8 @@ export function SimulationPublishedIva({ busy, onCalculate }: {
} catch { /* The execution flow already preserves and reports connection errors. */ }
}
return <section aria-label="IVA geral sobre base líquida" className="space-y-3 rounded border border-emerald-700 p-4">
<h4 className="font-semibold">IVA geral sobre base líquida</h4>
return <section id="published-iva" tabIndex={-1} aria-label="IVA — taxa geral" className="space-y-3 rounded border border-emerald-700 p-4">
<h4 className="font-semibold">IVA — taxa geral</h4>
<p role="status">{message}</p>
<p className="text-sm">Cobertura: exigibilidade em 2026, operação interna à taxa geral. A base tributável é indicada por si; não é copiada do orçamento. Sem isenções, taxas reduzidas, bases especiais, importações, deduções, declaração ou pagamento. O cálculo não valida o enquadramento jurídico.</p>
<fieldset disabled={busy} className="space-y-3">