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 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', 'A caixa disponível cobre menos de um mês 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, 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, i: number) => JSON.stringify(Object.keys(row).sort()) !== JSON.stringify(Object.keys(template.years[i]).sort()), ) || plan.startupExpenses.some( (row: Record) => 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, }; }