feat: dashboard overhaul, chargeability reports, dispo import enhancements, UI polish

Dashboard: expanded chargeability widget, resource/project table widgets with sorting and filters, stat cards with formatMoney integration. Chargeability: new report client with filtering, chargeability-bookings use case, updated dashboard overview logic. Dispo import: TBD project handling, parse-dispo-matrix improvements, stage-dispo-projects resource value scores, new tests. Estimates: CommercialTermsEditor component, commercial-terms engine module, expanded estimate schemas and types. UI: AppShell navigation updates, timeline filter/toolbar enhancements, role management improvements, signin page redesign, Tailwind/globals polish, SystemSettings SMTP section, anonymization support. Tests: new router tests (anonymization, chargeability, effort-rule, entitlement, estimate, experience-multiplier, notification, resource, staffing, vacation). Co-Authored-By: claude-flow <ruv@ruv.net>
2026-03-14 23:29:07 +01:00
parent ad0855902b
commit 625a842d89
74 changed files with 11680 additions and 1583 deletions
@@ -0,0 +1,226 @@
+import { describe, expect, it } from "vitest";
+import {
+  computeCommercialTermsSummary,
+  computeMilestoneAmounts,
+  defaultCommercialTerms,
+  validatePaymentMilestones,
+} from "../estimate/commercial-terms.js";
+import type { CommercialTerms, PaymentMilestone } from "@planarchy/shared";
+
+const BASE_TERMS: CommercialTerms = {
+  pricingModel: "fixed_price",
+  contingencyPercent: 0,
+  discountPercent: 0,
+  paymentTermDays: 30,
+  paymentMilestones: [],
+  warrantyMonths: 0,
+};
+
+describe("computeCommercialTermsSummary", () => {
+  it("returns unchanged totals when contingency and discount are 0", () => {
+    const result = computeCommercialTermsSummary({
+      baseCostCents: 100_000_00,
+      basePriceCents: 150_000_00,
+      terms: BASE_TERMS,
+    });
+
+    expect(result.adjustedCostCents).toBe(100_000_00);
+    expect(result.adjustedPriceCents).toBe(150_000_00);
+    expect(result.contingencyCents).toBe(0);
+    expect(result.discountCents).toBe(0);
+    expect(result.adjustedMarginCents).toBe(50_000_00);
+  });
+
+  it("adds contingency to cost", () => {
+    const result = computeCommercialTermsSummary({
+      baseCostCents: 100_000_00,
+      basePriceCents: 150_000_00,
+      terms: { ...BASE_TERMS, contingencyPercent: 10 },
+    });
+
+    expect(result.contingencyCents).toBe(10_000_00);
+    expect(result.adjustedCostCents).toBe(110_000_00);
+    expect(result.adjustedPriceCents).toBe(150_000_00);
+    expect(result.adjustedMarginCents).toBe(40_000_00);
+  });
+
+  it("subtracts discount from price", () => {
+    const result = computeCommercialTermsSummary({
+      baseCostCents: 100_000_00,
+      basePriceCents: 200_000_00,
+      terms: { ...BASE_TERMS, discountPercent: 5 },
+    });
+
+    expect(result.discountCents).toBe(10_000_00);
+    expect(result.adjustedPriceCents).toBe(190_000_00);
+    expect(result.adjustedCostCents).toBe(100_000_00);
+    expect(result.adjustedMarginCents).toBe(90_000_00);
+  });
+
+  it("applies both contingency and discount together", () => {
+    const result = computeCommercialTermsSummary({
+      baseCostCents: 100_000_00,
+      basePriceCents: 200_000_00,
+      terms: { ...BASE_TERMS, contingencyPercent: 15, discountPercent: 10 },
+    });
+
+    // cost: 100k + 15% = 115k
+    expect(result.adjustedCostCents).toBe(115_000_00);
+    // price: 200k - 10% = 180k
+    expect(result.adjustedPriceCents).toBe(180_000_00);
+    // margin: 180k - 115k = 65k
+    expect(result.adjustedMarginCents).toBe(65_000_00);
+  });
+
+  it("computes margin percent correctly", () => {
+    const result = computeCommercialTermsSummary({
+      baseCostCents: 70_000_00,
+      basePriceCents: 100_000_00,
+      terms: BASE_TERMS,
+    });
+
+    expect(result.adjustedMarginPercent).toBeCloseTo(30, 1);
+  });
+
+  it("handles zero price gracefully (margin% = 0)", () => {
+    const result = computeCommercialTermsSummary({
+      baseCostCents: 50_000_00,
+      basePriceCents: 0,
+      terms: BASE_TERMS,
+    });
+
+    expect(result.adjustedMarginPercent).toBe(0);
+    expect(result.adjustedMarginCents).toBe(-50_000_00);
+  });
+
+  it("handles negative margin when discount exceeds buffer", () => {
+    const result = computeCommercialTermsSummary({
+      baseCostCents: 100_000_00,
+      basePriceCents: 110_000_00,
+      terms: { ...BASE_TERMS, contingencyPercent: 20, discountPercent: 10 },
+    });
+
+    // cost: 100k + 20% = 120k, price: 110k - 10% = 99k → margin = -21k
+    expect(result.adjustedMarginCents).toBe(-21_000_00);
+    expect(result.adjustedMarginPercent).toBeLessThan(0);
+  });
+
+  it("rounds contingency and discount to integer cents", () => {
+    const result = computeCommercialTermsSummary({
+      baseCostCents: 33_333,
+      basePriceCents: 66_667,
+      terms: { ...BASE_TERMS, contingencyPercent: 7.5, discountPercent: 3.3 },
+    });
+
+    expect(Number.isInteger(result.contingencyCents)).toBe(true);
+    expect(Number.isInteger(result.discountCents)).toBe(true);
+    expect(Number.isInteger(result.adjustedCostCents)).toBe(true);
+    expect(Number.isInteger(result.adjustedPriceCents)).toBe(true);
+  });
+});
+
+describe("validatePaymentMilestones", () => {
+  it("returns no warnings for empty milestones", () => {
+    expect(validatePaymentMilestones([])).toEqual([]);
+  });
+
+  it("returns no warnings when milestones sum to 100%", () => {
+    const milestones: PaymentMilestone[] = [
+      { label: "Kickoff", percent: 30 },
+      { label: "Midpoint", percent: 40 },
+      { label: "Delivery", percent: 30 },
+    ];
+    expect(validatePaymentMilestones(milestones)).toEqual([]);
+  });
+
+  it("warns when milestones do not sum to 100%", () => {
+    const milestones: PaymentMilestone[] = [
+      { label: "Kickoff", percent: 30 },
+      { label: "Delivery", percent: 50 },
+    ];
+    const warnings = validatePaymentMilestones(milestones);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("80.0%");
+  });
+
+  it("warns about zero-percent milestones", () => {
+    const milestones: PaymentMilestone[] = [
+      { label: "Kickoff", percent: 0 },
+      { label: "Delivery", percent: 100 },
+    ];
+    const warnings = validatePaymentMilestones(milestones);
+    expect(warnings.some((w) => w.includes("0%"))).toBe(true);
+  });
+
+  it("warns about empty labels", () => {
+    const milestones: PaymentMilestone[] = [
+      { label: "  ", percent: 50 },
+      { label: "End", percent: 50 },
+    ];
+    const warnings = validatePaymentMilestones(milestones);
+    expect(warnings.some((w) => w.includes("empty label"))).toBe(true);
+  });
+
+  it("warns about non-chronological dates", () => {
+    const milestones: PaymentMilestone[] = [
+      { label: "Late", percent: 50, dueDate: "2026-06-01" },
+      { label: "Early", percent: 50, dueDate: "2026-03-01" },
+    ];
+    const warnings = validatePaymentMilestones(milestones);
+    expect(warnings.some((w) => w.includes("earlier date"))).toBe(true);
+  });
+
+  it("ignores date order for milestones without dates", () => {
+    const milestones: PaymentMilestone[] = [
+      { label: "A", percent: 50 },
+      { label: "B", percent: 50, dueDate: "2026-01-01" },
+    ];
+    expect(validatePaymentMilestones(milestones)).toEqual([]);
+  });
+});
+
+describe("computeMilestoneAmounts", () => {
+  it("computes amounts from adjusted price", () => {
+    const milestones: PaymentMilestone[] = [
+      { label: "Kickoff", percent: 30 },
+      { label: "Final", percent: 70 },
+    ];
+    const amounts = computeMilestoneAmounts(100_000_00, milestones);
+
+    expect(amounts).toHaveLength(2);
+    expect(amounts[0]!.amountCents).toBe(30_000_00);
+    expect(amounts[1]!.amountCents).toBe(70_000_00);
+  });
+
+  it("rounds amounts to integer cents", () => {
+    const milestones: PaymentMilestone[] = [
+      { label: "A", percent: 33.33 },
+      { label: "B", percent: 33.33 },
+      { label: "C", percent: 33.34 },
+    ];
+    const amounts = computeMilestoneAmounts(99_999, milestones);
+    for (const a of amounts) {
+      expect(Number.isInteger(a.amountCents)).toBe(true);
+    }
+  });
+
+  it("preserves due dates", () => {
+    const milestones: PaymentMilestone[] = [
+      { label: "M1", percent: 100, dueDate: "2026-06-15" },
+    ];
+    const amounts = computeMilestoneAmounts(50_000_00, milestones);
+    expect(amounts[0]!.dueDate).toBe("2026-06-15");
+  });
+});
+
+describe("defaultCommercialTerms", () => {
+  it("returns valid defaults", () => {
+    const terms = defaultCommercialTerms();
+    expect(terms.pricingModel).toBe("fixed_price");
+    expect(terms.contingencyPercent).toBe(0);
+    expect(terms.discountPercent).toBe(0);
+    expect(terms.paymentTermDays).toBe(30);
+    expect(terms.paymentMilestones).toEqual([]);
+    expect(terms.warrantyMonths).toBe(0);
+  });
+});
@@ -0,0 +1,129 @@
+/**
+ * Pure commercial-terms calculation engine.
+ *
+ * Applies contingency, discount, and payment milestone validation
+ * to base cost/price totals from demand lines.
+ */
+
+import type { CommercialTerms, CommercialTermsSummary, PaymentMilestone } from "@planarchy/shared";
+
+export interface CommercialTermsInput {
+  baseCostCents: number;
+  basePriceCents: number;
+  terms: CommercialTerms;
+}
+
+/**
+ * Compute adjusted totals after applying contingency and discount.
+ *
+ * Contingency is added to cost (risk buffer on cost side).
+ * Discount is subtracted from price (reduction on sell side).
+ *
+ * adjustedCost  = baseCost * (1 + contingency%)
+ * adjustedPrice = basePrice * (1 - discount%)
+ * margin        = adjustedPrice - adjustedCost
+ */
+export function computeCommercialTermsSummary(
+  input: CommercialTermsInput,
+): CommercialTermsSummary {
+  const { baseCostCents, basePriceCents, terms } = input;
+
+  const contingencyFactor = terms.contingencyPercent / 100;
+  const discountFactor = terms.discountPercent / 100;
+
+  const contingencyCents = Math.round(baseCostCents * contingencyFactor);
+  const discountCents = Math.round(basePriceCents * discountFactor);
+
+  const adjustedCostCents = baseCostCents + contingencyCents;
+  const adjustedPriceCents = basePriceCents - discountCents;
+  const adjustedMarginCents = adjustedPriceCents - adjustedCostCents;
+  const adjustedMarginPercent =
+    adjustedPriceCents > 0
+      ? (adjustedMarginCents / adjustedPriceCents) * 100
+      : 0;
+
+  return {
+    baseCostCents,
+    basePriceCents,
+    contingencyCents,
+    discountCents,
+    adjustedCostCents,
+    adjustedPriceCents,
+    adjustedMarginCents,
+    adjustedMarginPercent,
+  };
+}
+
+/**
+ * Validate that payment milestones sum to 100%.
+ * Returns list of validation warnings (empty = valid).
+ */
+export function validatePaymentMilestones(
+  milestones: PaymentMilestone[],
+): string[] {
+  const warnings: string[] = [];
+
+  if (milestones.length === 0) return warnings;
+
+  const totalPercent = milestones.reduce((sum, m) => sum + m.percent, 0);
+
+  if (Math.abs(totalPercent - 100) > 0.01) {
+    warnings.push(
+      `Payment milestones sum to ${totalPercent.toFixed(1)}%, expected 100%`,
+    );
+  }
+
+  for (let i = 0; i < milestones.length; i++) {
+    const m = milestones[i]!;
+    if (m.percent <= 0) {
+      warnings.push(`Milestone "${m.label}" has 0% or negative allocation`);
+    }
+    if (!m.label.trim()) {
+      warnings.push(`Milestone at position ${i + 1} has empty label`);
+    }
+  }
+
+  // Check chronological order when dates are provided
+  const datedMilestones = milestones.filter(
+    (m): m is PaymentMilestone & { dueDate: string } =>
+      m.dueDate != null && m.dueDate !== "",
+  );
+  for (let i = 1; i < datedMilestones.length; i++) {
+    if (datedMilestones[i]!.dueDate < datedMilestones[i - 1]!.dueDate) {
+      warnings.push(
+        `Milestone "${datedMilestones[i]!.label}" has an earlier date than "${datedMilestones[i - 1]!.label}"`,
+      );
+    }
+  }
+
+  return warnings;
+}
+
+/**
+ * Compute per-milestone payment amounts from adjusted price.
+ */
+export function computeMilestoneAmounts(
+  adjustedPriceCents: number,
+  milestones: PaymentMilestone[],
+): Array<{ label: string; percent: number; amountCents: number; dueDate?: string | null }> {
+  return milestones.map((m) => ({
+    label: m.label,
+    percent: m.percent,
+    amountCents: Math.round(adjustedPriceCents * (m.percent / 100)),
+    ...(m.dueDate !== undefined ? { dueDate: m.dueDate } : {}),
+  }));
+}
+
+/**
+ * Default commercial terms for a new estimate.
+ */
+export function defaultCommercialTerms(): CommercialTerms {
+  return {
+    pricingModel: "fixed_price",
+    contingencyPercent: 0,
+    discountPercent: 0,
+    paymentTermDays: 30,
+    paymentMilestones: [],
+    warrantyMonths: 0,
+  };
+}
@@ -1,3 +1,4 @@
+export * from "./commercial-terms.js";
 export * from "./effort-rules.js";
 export * from "./experience-multiplier.js";
 export * from "./export-serializer.js";