Files
Investidor-V2/resources/js/lib/business-plan-guidance.ts
T

690 lines
25 KiB
TypeScript

export type PlanWarningLimits = {
grossMarginPercent: number;
cashExpenseMonths: number;
annualGrowthPercent: number;
creditDays: number;
debtAssetsPercent: number;
};
export const defaultPlanWarningLimits: PlanWarningLimits = {
grossMarginPercent: 15,
cashExpenseMonths: 1,
annualGrowthPercent: 100,
creditDays: 90,
debtAssetsPercent: 70,
};
export function isPlanWarningLimits(
value: unknown,
): value is PlanWarningLimits {
if (!value || typeof value !== 'object' || Array.isArray(value))
return false;
const limits = value as Record<string, unknown>;
return (
Object.keys(limits).length === 5 &&
Object.keys(defaultPlanWarningLimits).every(
(key) =>
typeof limits[key] === 'number' &&
Number.isFinite(limits[key]) &&
(!['cashExpenseMonths', 'creditDays'].includes(key) ||
Number(limits[key]) >= 0),
)
);
}
export type PlanWarning = { id: string; message: string };
export type PlanWarningMetrics = {
optionalTexts?: { label: string; value: string }[];
fundingGap?: number;
currency?: string;
netProfit?: number;
sales?: number;
directCosts?: number;
monthlyBreakEven?: number | null;
monthlyExpenses?: number;
cash?: number;
growthPercent?: number;
creditDays?: number;
liabilities?: number;
assets?: number;
ownAndInvestorCapital?: number;
};
/** Guidance only: warnings never change the inputs or determine validity. */
export function businessPlanWarnings(
metrics: PlanWarningMetrics,
limits: PlanWarningLimits = defaultPlanWarningLimits,
): PlanWarning[] {
const warnings: PlanWarning[] = [];
const add = (id: string, message: string) => warnings.push({ id, message });
if (metrics.optionalTexts?.some((field) => !field.value.trim()))
add(
'optional-texts',
'Pode completar estas secções para um relatório mais convincente.',
);
if ((metrics.fundingGap ?? 0) > 0)
add(
'funding',
`O financiamento indicado não cobre o investimento necessário. Faltam ${metrics.fundingGap!.toLocaleString('pt-MZ', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}${metrics.currency ? ` ${metrics.currency}` : ''}.`,
);
if (metrics.netProfit !== undefined && metrics.netProfit < 0)
add(
'loss',
'Neste ano o negócio dá prejuízo. Reveja as vendas ou os custos, ou confirme que é o esperado.',
);
if (
metrics.sales !== undefined &&
metrics.sales > 0 &&
metrics.directCosts !== undefined
) {
if (
(100 * (metrics.sales - metrics.directCosts)) / metrics.sales <
limits.grossMarginPercent
)
add(
'margin',
'A margem bruta é baixa e deixa pouca folga para cobrir as despesas.',
);
if (
metrics.monthlyBreakEven != null &&
metrics.monthlyBreakEven > metrics.sales / 12
)
add(
'break-even',
'As vendas mensais médias não atingem o ponto de equilíbrio. O negócio só cobre os custos com mais vendas.',
);
}
if (
metrics.cash !== undefined &&
metrics.monthlyExpenses !== undefined &&
metrics.cash < metrics.monthlyExpenses * limits.cashExpenseMonths
)
add(
'cash',
limits.cashExpenseMonths === 1
? 'A caixa disponível cobre menos de um mês de despesas. Considere reforçar o financiamento.'
: `A caixa disponível cobre menos de ${limits.cashExpenseMonths.toLocaleString('pt-MZ')} meses de despesas. Considere reforçar o financiamento.`,
);
if (
metrics.growthPercent !== undefined &&
metrics.growthPercent > limits.annualGrowthPercent
)
add(
'growth',
'O crescimento indicado é muito elevado. Confirme que é realista.',
);
if (
metrics.creditDays !== undefined &&
metrics.creditDays > limits.creditDays
)
add(
'credit',
'Prazos de recebimento longos pressionam a caixa. Confirme o prazo indicado.',
);
if (
metrics.assets !== undefined &&
metrics.assets > 0 &&
metrics.liabilities !== undefined &&
(metrics.liabilities / metrics.assets) * 100 > limits.debtAssetsPercent
)
add(
'debt',
'O peso das dívidas é elevado e pode dificultar o acesso a crédito.',
);
if (metrics.ownAndInvestorCapital === 0)
add(
'capital',
'Não indicou capital próprio nem de investidor. Todo o financiamento vem de empréstimos ou fica por definir.',
);
return warnings;
}
export type AnnualReferencePlan = {
startupExpenses: { label: string; amount: string }[];
openingCash: string;
otherCurrentAssets: string;
longTermAssets: string;
ownerCapital: string;
investorCapital: string;
loans: string;
additionalMoney: string;
years: {
year: number;
sales: string;
directCosts: string;
payroll: string;
payrollCharges: string;
otherOperatingExpenses: string;
interest: string;
taxes: string;
cashReceived: string;
cashSpent: string;
vatReceived: string;
vatPaid: string;
}[];
};
/** Values explicitly supplied by the owner; currency must be chosen in the form. */
export function newAnnualReferencePlan(): AnnualReferencePlan {
return {
startupExpenses: [
{ label: 'Constituição da sociedade', amount: '25000' },
{ label: 'Material de escritório', amount: '50000' },
{ label: 'Seguros', amount: '0' },
{ label: 'Rendas', amount: '0' },
{ label: 'Computadores', amount: '250000' },
{ label: 'Desenvolvimento do portal', amount: '1000000' },
],
openingCash: '90000',
otherCurrentAssets: '150000',
longTermAssets: '260250',
ownerCapital: '0',
investorCapital: '0',
loans: '0',
additionalMoney: '0',
years: [
{
year: 2025,
sales: '14537',
directCosts: '12538',
payroll: '2100',
payrollCharges: '315',
otherOperatingExpenses: '0',
interest: '0',
taxes: '0',
cashReceived: '16539',
cashSpent: '15783',
vatReceived: '2471',
vatPaid: '2471',
},
{
year: 2026,
sales: '21500',
directCosts: '16200',
payroll: '2800',
payrollCharges: '420',
otherOperatingExpenses: '0',
interest: '0',
taxes: '624',
cashReceived: '24930',
cashSpent: '23923',
vatReceived: '3655',
vatPaid: '3655',
},
{
year: 2027,
sales: '23875',
directCosts: '18325',
payroll: '2800',
payrollCharges: '420',
otherOperatingExpenses: '0',
interest: '0',
taxes: '699',
cashReceived: '27857',
cashSpent: '26122',
vatReceived: '4059',
vatPaid: '4059',
},
],
};
}
/** Preserve incomplete numeric drafts as entered, but accept only the example's schema. */
export function restoreAnnualExampleSnapshot(
snapshot?: string,
): AnnualReferencePlan | null {
if (!snapshot || snapshot.length > 12000) return null;
try {
const decoded = JSON.parse(snapshot);
if (
decoded.version !== 1 ||
decoded.kind !== 'synthetic-annual-example'
)
return null;
const plan = decoded.plan;
const template = newAnnualReferencePlan();
const numericDraft = (value: unknown) =>
typeof value === 'string' && value.length <= 40;
for (const key of [
'openingCash',
'otherCurrentAssets',
'longTermAssets',
'ownerCapital',
'investorCapital',
'loans',
'additionalMoney',
] as const)
if (!numericDraft(plan[key])) return null;
if (
!Array.isArray(plan.startupExpenses) ||
plan.startupExpenses.length !== template.startupExpenses.length ||
plan.startupExpenses.some(
(row: { label: unknown; amount: unknown }, i: number) =>
row.label !== template.startupExpenses[i].label ||
!numericDraft(row.amount),
)
)
return null;
if (
!Array.isArray(plan.years) ||
plan.years.length !== template.years.length ||
plan.years.some(
(row: Record<string, unknown>, i: number) =>
row.year !== template.years[i].year ||
Object.keys(template.years[i]).some(
(key) => key !== 'year' && !numericDraft(row[key]),
),
)
)
return null;
// Do not accept unrelated fields or investor data into this example.
if (
JSON.stringify(Object.keys(plan).sort()) !==
JSON.stringify(Object.keys(template).sort()) ||
plan.years.some(
(row: Record<string, unknown>, i: number) =>
JSON.stringify(Object.keys(row).sort()) !==
JSON.stringify(Object.keys(template.years[i]).sort()),
) ||
plan.startupExpenses.some(
(row: Record<string, unknown>) =>
Object.keys(row).sort().join(',') !== 'amount,label',
)
)
return null;
return plan as AnnualReferencePlan;
} catch {
return null;
}
}
export function serializeAnnualExampleSnapshot(
plan: AnnualReferencePlan,
): string {
const snapshot = JSON.stringify({
version: 1,
kind: 'synthetic-annual-example',
plan,
});
if (!restoreAnnualExampleSnapshot(snapshot))
throw new Error('Não foi possível guardar o cenário de exemplo.');
return snapshot;
}
function money(value: string): bigint {
if (value.length > 40 || !/^\d+(?:\.\d{1,2})?$/.test(value.trim()))
throw new Error(
value.trim() === ''
? 'Preencha este campo para continuar.'
: Number(value) < 0
? 'Este valor não pode ser negativo.'
: 'Introduza apenas números (ex.: 25.000).',
);
const [whole, fraction = ''] = value.trim().split('.');
return BigInt(whole) * 100n + BigInt(fraction.padEnd(2, '0'));
}
function decimal(value: bigint): string {
const abs = value < 0n ? -value : value;
return `${value < 0n ? '-' : ''}${abs / 100n}.${String(abs % 100n).padStart(2, '0')}`;
}
export type DecisionBalanceInput = {
cash: string;
receivables: string;
inventory: string;
otherCurrentAssets: string;
longTermAssets: string;
accumulatedDepreciation: string;
currentLiabilities: string;
longTermLiabilities: string;
paidCapital: string;
retainedResults: string;
periodResult: string;
};
/** Exact monetary reconciliation; no balancing entry or rounding tolerance. */
export function checkDecisionBalance(input: DecisionBalanceInput) {
const signed = (value: string) =>
value.startsWith('-') ? -money(value.slice(1)) : money(value);
const currentAssets =
money(input.cash) +
money(input.receivables) +
money(input.inventory) +
money(input.otherCurrentAssets);
const netLongTermAssets =
money(input.longTermAssets) - money(input.accumulatedDepreciation);
if (netLongTermAssets < 0n)
throw new Error(
'A depreciação acumulada não pode exceder os activos de longo prazo.',
);
const assets = currentAssets + netLongTermAssets;
const liabilities =
money(input.currentLiabilities) + money(input.longTermLiabilities);
const capital =
money(input.paidCapital) +
signed(input.retainedResults) +
signed(input.periodResult);
const difference = assets - liabilities - capital;
return {
currentAssets: decimal(currentAssets),
netLongTermAssets: decimal(netLongTermAssets),
assets: decimal(assets),
liabilities: decimal(liabilities),
capital: decimal(capital),
liabilitiesAndCapital: decimal(liabilities + capital),
difference: decimal(difference),
balanced: difference === 0n,
error:
difference === 0n
? null
: `Os valores não estão equilibrados: os activos diferem dos passivos e capital em ${decimal(difference < 0n ? -difference : difference)}. Reveja os dados introduzidos.`,
};
}
/** Ratios use reconciled statement data; an absent/zero denominator is unknown. */
export function calculateDecisionRatios(
input: DecisionBalanceInput,
sales: string,
previousSales?: string,
) {
const balance = checkDecisionBalance(input);
if (!balance.balanced) throw new Error(balance.error!);
const ratio = (numerator: string, denominator: string) =>
Number(denominator) === 0
? null
: Number(numerator) / Number(denominator);
const revenue = decimal(money(sales));
const previous =
previousSales === undefined ? null : decimal(money(previousSales));
const profit = input.periodResult.startsWith('-')
? decimal(-money(input.periodResult.slice(1)))
: decimal(money(input.periodResult));
return {
salesGrowth:
previous === null || Number(previous) === 0
? null
: Number(revenue) / Number(previous) - 1,
currentLiquidity: ratio(
balance.currentAssets,
decimal(money(input.currentLiabilities)),
),
debtAssets: ratio(balance.liabilities, balance.assets),
netMargin: ratio(profit, revenue),
returnOnEquity: ratio(profit, balance.capital),
};
}
/** Illustrative allocation, in cents; never a reconstruction of historical months. */
function allocateMonths(total: bigint, weights: bigint[]) {
const denominator = weights.reduce((sum, value) => sum + value, 0n);
const effective = denominator === 0n ? weights.map(() => 1n) : weights;
const divisor = denominator === 0n ? BigInt(weights.length) : denominator;
const rows = effective.map((weight, index) => ({
index,
amount: (total * weight) / divisor,
remainder: (total * weight) % divisor,
}));
let remaining = total - rows.reduce((sum, row) => sum + row.amount, 0n);
for (const row of [...rows].sort((a, b) =>
a.remainder === b.remainder
? a.index - b.index
: a.remainder > b.remainder
? -1
: 1,
)) {
if (remaining === 0n) break;
row.amount += 1n;
remaining -= 1n;
}
return rows.map((row) => row.amount);
}
export function calculateAnnualReferencePlan(plan: AnnualReferencePlan) {
const startupExpenses = plan.startupExpenses.reduce(
(sum, row) => sum + money(row.amount),
0n,
);
const openingCash = money(plan.openingCash);
const assets =
openingCash +
money(plan.otherCurrentAssets) +
money(plan.longTermAssets);
const requiredFunding = startupExpenses + assets;
const availableFunding =
money(plan.ownerCapital) +
money(plan.investorCapital) +
money(plan.loans) +
money(plan.additionalMoney);
// A projection of the required capital is not confirmation of financing.
const capitalToMobilise =
requiredFunding > availableFunding
? requiredFunding - availableFunding
: 0n;
const projectedCapital =
availableFunding + capitalToMobilise - money(plan.loans);
let cash =
openingCash + availableFunding + capitalToMobilise - requiredFunding;
let receivables = 0n;
let operatingLiabilities = 0n;
let vatBalance = 0n;
let accumulatedResults = -startupExpenses;
const years = plan.years.map((year, index) => {
const sales = money(year.sales),
costs = money(year.directCosts);
if (sales === 0n && costs > 0n)
throw new Error(
'Indique as vendas previstas para calcular a margem e o ponto de equilíbrio.',
);
if (sales > 0n && costs >= sales)
throw new Error(
'Com este custo variável não há margem para cobrir os custos fixos. Reveja o custo variável ou o preço.',
);
const grossMargin = sales - costs;
const operatingExpenses =
money(year.payroll) +
money(year.payrollCharges) +
money(year.otherOperatingExpenses);
const operatingProfit = grossMargin - operatingExpenses;
const netProfit =
operatingProfit - money(year.interest) - money(year.taxes);
const cashFlow = money(year.cashReceived) - money(year.cashSpent);
const openingYearCash = cash;
const openingReceivables = receivables;
const openingLiabilities = operatingLiabilities;
const openingResults = accumulatedResults;
const openingVatBalance = vatBalance;
const vatReceived = money(year.vatReceived);
const vatPaid = money(year.vatPaid);
if (
vatReceived > money(year.cashReceived) ||
vatPaid > money(year.cashSpent)
)
throw new Error(
'O IVA de caixa não pode exceder os respectivos recebimentos ou pagamentos.',
);
receivables += sales - (money(year.cashReceived) - vatReceived);
operatingLiabilities +=
costs +
operatingExpenses +
money(year.interest) +
money(year.taxes) -
(money(year.cashSpent) - vatPaid);
accumulatedResults += netProfit;
vatBalance += vatReceived - vatPaid;
cash += cashFlow;
const closingAssets =
cash +
receivables +
money(plan.otherCurrentAssets) +
money(plan.longTermAssets);
const closingCapital = projectedCapital + accumulatedResults;
const closingLiabilities =
operatingLiabilities + money(plan.loans) + vatBalance;
// Explicit model assumptions: repeat the example's aggregate seasonal
// profile; allocate cash net of VAT proportionally to accrued amounts.
const salesWeights = [
680n,
748n,
824n,
905n,
990n,
1095n,
1203n,
1324n,
1458n,
1604n,
1765n,
1941n,
];
const costWeights = [
586n,
644n,
710n,
781n,
860n,
945n,
1038n,
1142n,
1257n,
1383n,
1520n,
1672n,
];
const monthlySales = allocateMonths(sales, salesWeights);
const monthlyCosts = allocateMonths(costs, costWeights);
const equalWeights = salesWeights.map(() => 1n);
const monthlyExpenses = [
year.payroll,
year.payrollCharges,
year.otherOperatingExpenses,
year.interest,
year.taxes,
].map((value) => allocateMonths(money(value), equalWeights));
const accrued = monthlyCosts.map(
(value, i) =>
value + monthlyExpenses.reduce((sum, row) => sum + row[i], 0n),
);
const receipts = allocateMonths(
money(year.cashReceived) - vatReceived,
monthlySales,
);
const payments = allocateMonths(
money(year.cashSpent) - vatPaid,
accrued,
);
const vatReceipts = allocateMonths(vatReceived, salesWeights);
const vatPayments = allocateMonths(vatPaid, salesWeights);
let monthCash = openingYearCash,
monthReceivables = openingReceivables,
monthLiabilities = openingLiabilities,
monthResults = openingResults;
let monthVatBalance = openingVatBalance;
const illustrativeMonths = monthlySales.map((revenue, i) => {
const profit = revenue - accrued[i];
const received = receipts[i] + vatReceipts[i];
const spent = payments[i] + vatPayments[i];
monthCash += received - spent;
monthReceivables += revenue - receipts[i];
monthLiabilities += accrued[i] - payments[i];
monthResults += profit;
monthVatBalance += vatReceipts[i] - vatPayments[i];
const monthAssets =
monthCash +
monthReceivables +
money(plan.otherCurrentAssets) +
money(plan.longTermAssets);
return {
month: i + 1,
sales: decimal(revenue),
directCosts: decimal(monthlyCosts[i]),
grossMargin: decimal(revenue - monthlyCosts[i]),
payroll: decimal(monthlyExpenses[0][i]),
payrollCharges: decimal(monthlyExpenses[1][i]),
otherOperatingExpenses: decimal(monthlyExpenses[2][i]),
operatingExpenses: decimal(
monthlyExpenses[0][i] +
monthlyExpenses[1][i] +
monthlyExpenses[2][i],
),
operatingProfit: decimal(
profit + monthlyExpenses[3][i] + monthlyExpenses[4][i],
),
interest: decimal(monthlyExpenses[3][i]),
taxes: decimal(monthlyExpenses[4][i]),
netProfit: decimal(profit),
cashReceived: decimal(received),
cashSpent: decimal(spent),
cashFlow: decimal(received - spent),
closingCash: decimal(monthCash),
receivables: decimal(monthReceivables),
operatingLiabilities: decimal(monthLiabilities),
vatBalance: decimal(monthVatBalance),
closingAssets: decimal(monthAssets),
closingLiabilities: decimal(
monthLiabilities + monthVatBalance + money(plan.loans),
),
closingCapital: decimal(projectedCapital + monthResults),
balanceDifference: decimal(
monthAssets -
monthLiabilities -
monthVatBalance -
money(plan.loans) -
projectedCapital -
monthResults,
),
};
});
// Keep the unrounded gross-margin fraction in the break-even formula.
const monthlyBreakEven =
grossMargin > 0n
? (Number(operatingExpenses) * Number(sales)) /
(1200 * Number(grossMargin))
: null;
const previousSales =
index > 0 ? money(plan.years[index - 1].sales) : null;
const growthPercent =
previousSales !== null && previousSales > 0n
? (Number(sales - previousSales) / Number(previousSales)) * 100
: null;
return {
year: year.year,
sales: decimal(sales),
directCosts: decimal(costs),
grossMargin: decimal(grossMargin),
grossMarginPercent:
sales > 0n ? (Number(grossMargin) / Number(sales)) * 100 : null,
operatingExpenses: decimal(operatingExpenses),
operatingProfit: decimal(operatingProfit),
netProfit: decimal(netProfit),
netMarginPercent:
sales > 0n ? (Number(netProfit) / Number(sales)) * 100 : null,
cashFlow: decimal(cashFlow),
closingCash: decimal(cash),
receivables: decimal(receivables),
operatingLiabilities: decimal(operatingLiabilities),
closingAssets: decimal(closingAssets),
closingCapital: decimal(closingCapital),
closingLiabilities: decimal(closingLiabilities),
vatBalance: decimal(vatBalance),
balanceDifference: decimal(
closingAssets - closingLiabilities - closingCapital,
),
illustrativeMonths,
monthlyFixedCosts: Number(operatingExpenses) / 1200,
monthlyBreakEven,
growthPercent,
};
});
return {
startupExpenses: decimal(startupExpenses),
assets: decimal(assets),
requiredFunding: decimal(requiredFunding),
availableFunding: decimal(availableFunding),
capitalToMobilise: decimal(capitalToMobilise),
fundingGap: decimal(
requiredFunding > availableFunding
? requiredFunding - availableFunding
: 0n,
),
years,
monthlyStatus: 'por reconciliar' as const,
};
}