Version every negotiated term: widen the header snapshot and diff the accessorial schedule

client/apps/web/src/lib/__tests__/version-summary.test.ts

@@ -0,0 +1,84 @@
+import type { RateAgreementVersion } from "@trenova/shared/types/rate";
+import { describe, expect, it } from "vitest";
+import { describeVersion } from "../version-summary";
+
+const CHARGE_ID = "acc_01K2ZX8Y4M5N6P7Q8R9S0T1V2W";
+
+function version(overrides: Partial<RateAgreementVersion>): RateAgreementVersion {
+  return {
+    versionNumber: 2,
+    effectiveFrom: 1_700_000_000,
+    changeMessage: "",
+    ...overrides,
+  } as RateAgreementVersion;
+}
+
+describe("describeVersion", () => {
+  it("prefers the change message when one was written", () => {
+    const v = version({
+      changeMessage: "Annual renegotiation",
+      changeSummary: { currency: { from: "USD", to: "CAD" } },
+    });
+    expect(describeVersion(v)).toBe("Annual renegotiation");
+  });
+
+  it("humanizes header field paths instead of echoing camelCase keys", () => {
+    const v = version({
+      changeSummary: {
+        agreementEffectiveFrom: { from: 1, to: 2 },
+        defaultMinCharge: { from: "100", to: "150" },
+      },
+    });
+    const text = describeVersion(v);
+    expect(text).toContain("Effective from");
+    expect(text).toContain("Default minimum charge");
+    expect(text).not.toContain("agreementEffectiveFrom");
+  });
+
+  it("names an accessorial term change by the charge's code, never its id", () => {
+    const v = version({
+      changeSummary: {
+        [`accessorialTerms.${CHARGE_ID}.amount`]: { from: "25", to: "40" },
+      },
+      accessorialNames: { [CHARGE_ID]: "DETENTION" },
+    });
+    const text = describeVersion(v);
+    expect(text).toContain("DETENTION");
+    expect(text).not.toContain(CHARGE_ID);
+  });
+
+  it("reads an added accessorial as an addition", () => {
+    const v = version({
+      changeSummary: {
+        [`accessorialTerms.${CHARGE_ID}`]: { to: { amount: "75" } },
+      },
+      accessorialNames: { [CHARGE_ID]: "TONU" },
+    });
+    expect(describeVersion(v)).toContain("Added TONU accessorial");
+  });
+
+  it("falls back to a plain phrase when the charge cannot be named", () => {
+    const v = version({
+      changeSummary: {
+        [`accessorialTerms.${CHARGE_ID}`]: { from: { amount: "75" } },
+      },
+    });
+    const text = describeVersion(v);
+    expect(text).toContain("Removed accessorial");
+    expect(text).not.toContain(CHARGE_ID);
+  });
+
+  it("collapses fuel binding sub-fields into one phrase", () => {
+    const v = version({
+      changeSummary: {
+        "fuelTerms.fuelSurchargeProgramId": { from: "fsp_1", to: "fsp_2" },
+        "fuelTerms.capAmount": { from: null, to: "500" },
+      },
+    });
+    expect(describeVersion(v)).toBe("Fuel terms");
+  });
+
+  it("shows a dash when nothing is recorded", () => {
+    expect(describeVersion(version({}))).toBe("—");
+  });
+});

client/apps/web/src/lib/version-summary.ts

@@ -0,0 +1,104 @@
+import type { RateAgreementVersion } from "@trenova/shared/types/rate";
+
+/**
+ * Labels for the header terms a version can record, in the words the form uses.
+ * A path missing from this map falls back to its raw key, so a newly versioned
+ * field degrades to legible-but-plain rather than to nothing.
+ */
+const HEADER_FIELD_LABELS: Record<string, string> = {
+  partyType: "Party type",
+  customerId: "Customer",
+  carrierId: "Carrier",
+  code: "Code",
+  name: "Name",
+  description: "Description",
+  agreementType: "Agreement type",
+  contractRef: "Contract reference",
+  documentId: "Contract document",
+  priority: "Priority",
+  agreementEffectiveFrom: "Effective from",
+  agreementEffectiveTo: "Effective to",
+  autoRenew: "Auto-renew",
+  renewalNoticeDays: "Renewal notice days",
+  billToCustomerId: "Bill-to customer",
+  currency: "Currency",
+  defaultMinCharge: "Default minimum charge",
+  defaultMaxCharge: "Default maximum charge",
+  roundingMode: "Rounding",
+  roundingPrecision: "Rounding precision",
+  marginFloorPercent: "Margin floor",
+  maxPayPercentOfSell: "Max pay percent of sell",
+};
+
+const ACCESSORIAL_FIELD_LABELS: Record<string, string> = {
+  method: "method",
+  rateUnit: "rate unit",
+  amount: "amount",
+  waived: "waiver",
+  autoApply: "auto-apply",
+  applyCondition: "condition",
+  freeUnits: "free units",
+  maxAmount: "cap",
+  formulaTemplateId: "rating method",
+  serviceTypeIds: "applicability",
+  shipmentTypeIds: "applicability",
+  appliesFrom: "window",
+  appliesTo: "window",
+};
+
+const ACCESSORIAL_PREFIX = "accessorialTerms.";
+
+type FieldChange = { from?: unknown; to?: unknown };
+
+function accessorialPhrase(
+  path: string,
+  change: FieldChange,
+  names: Record<string, string>,
+): string {
+  const rest = path.slice(ACCESSORIAL_PREFIX.length);
+  const dot = rest.indexOf(".");
+  const chargeId = dot === -1 ? rest : rest.slice(0, dot);
+  const field = dot === -1 ? "" : rest.slice(dot + 1);
+  const name = names[chargeId];
+
+  if (!field) {
+    // A whole term appearing or vanishing is the schedule itself changing.
+    const added = change.to != null;
+    if (added) return name ? `Added ${name} accessorial` : "Added accessorial";
+    return name ? `Removed ${name} accessorial` : "Removed accessorial";
+  }
+
+  const fieldLabel = ACCESSORIAL_FIELD_LABELS[field] ?? field;
+  return name ? `${name} ${fieldLabel}` : `Accessorial ${fieldLabel}`;
+}
+
+/**
+ * One line saying what a version changed, written for the person reading the
+ * history — field names in the form's words, accessorials named by their
+ * charge's code, and never a record id.
+ */
+export function describeVersion(version: RateAgreementVersion): string {
+  if (version.changeMessage) return version.changeMessage;
+
+  const summary = version.changeSummary ?? {};
+  const names = version.accessorialNames ?? {};
+
+  const phrases: string[] = [];
+  for (const [path, change] of Object.entries(summary)) {
+    let phrase: string;
+    if (path.startsWith(ACCESSORIAL_PREFIX)) {
+      phrase = accessorialPhrase(path, change as FieldChange, names);
+    } else if (path === "fuelTerms" || path.startsWith("fuelTerms.")) {
+      phrase = "Fuel terms";
+    } else {
+      phrase = HEADER_FIELD_LABELS[path] ?? path;
+    }
+    if (!phrases.includes(phrase)) {
+      phrases.push(phrase);
+    }
+  }
+
+  if (phrases.length === 0) return "—";
+
+  return phrases.join(", ");
+}

client/apps/web/src/routes/rate-agreement/_components/versions-tab.tsx

@@ -10,8 +10,8 @@ import {
   TableRow,
 } from "@trenova/shared/components/ui/table";
 import { formatUnixDateMedium } from "@trenova/shared/lib/date";
-import type { RateAgreementVersion } from "@trenova/shared/types/rate";
 import { ClockIcon } from "lucide-react";
+import { describeVersion } from "@/lib/version-summary";
 
 type VersionsTabProps = {
   /** Absent while the agreement is being created — there is no history yet. */
@@ -88,12 +88,3 @@ export function VersionsTab({ rateAgreementId }: VersionsTabProps) {
     </div>
   );
 }
-
-function describeVersion(version: RateAgreementVersion): string {
-  if (version.changeMessage) return version.changeMessage;
-
-  const changedFields = Object.keys(version.changeSummary ?? {});
-  if (changedFields.length === 0) return "—";
-
-  return changedFields.join(", ");
-}

client/packages/shared/src/types/rate.ts

@@ -395,12 +395,51 @@ export const versionFieldChangeSchema = z.object({
   to: z.unknown().nullish(),
 });
 
+/** One accessorial's negotiated terms as a version recorded them. */
+export const versionAccessorialTermSchema = z.object({
+  method: z.string().nullish(),
+  rateUnit: z.string().nullish(),
+  amount: z.string().nullish(),
+  waived: z.boolean().nullish(),
+  autoApply: z.boolean().nullish(),
+  applyCondition: z.string().nullish(),
+  freeUnits: z.number().int().nullish(),
+  maxAmount: z.string().nullish(),
+  formulaTemplateId: z.string().nullish(),
+  serviceTypeIds: z.array(z.string()).nullish(),
+  shipmentTypeIds: z.array(z.string()).nullish(),
+  appliesFrom: z.number().int().nullish(),
+  appliesTo: z.number().int().nullish(),
+});
+export type VersionAccessorialTerm = z.infer<typeof versionAccessorialTermSchema>;
+
+/** The fuel binding's negotiated terms as a version recorded them. */
+export const versionFuelTermSchema = z.object({
+  fuelSurchargeProgramId: z.string().nullish(),
+  waived: z.boolean().nullish(),
+  pegPriceOverride: z.string().nullish(),
+  incrementRateOverride: z.string().nullish(),
+  capAmount: z.string().nullish(),
+});
+
 export const rateAgreementVersionSchema = z.object({
   id: optionalStringSchema,
   rateAgreementId: optionalStringSchema,
   versionNumber: z.number().int(),
   effectiveFrom: z.number().int(),
   effectiveTo: z.number().int().nullish(),
+  code: z.string().nullish(),
+  name: z.string().nullish(),
+  priority: z.number().int().nullish(),
+  agreementEffectiveFrom: z.number().int().nullish(),
+  agreementEffectiveTo: z.number().int().nullish(),
+  autoRenew: z.boolean().nullish(),
+  renewalNoticeDays: z.number().int().nullish(),
+  billToCustomerId: z.string().nullish(),
+  accessorialTerms: z.record(z.string(), versionAccessorialTermSchema).nullish(),
+  fuelTerms: versionFuelTermSchema.nullish(),
+  /** Accessorial charge id → code, resolved by the server at read time. */
+  accessorialNames: z.record(z.string(), z.string()).nullish(),
   changeMessage: z.string().default(""),
   changeSummary: z.record(z.string(), versionFieldChangeSchema).nullish(),
   createdById: z.string().nullish(),