sales documents

2026-03-15 11:44:14 -05:00
parent e2254d020e
commit a9d31730f8
15 changed files with 628 additions and 115 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -16,7 +16,7 @@ MRP Codex is a modular Manufacturing Resource Planning platform intended to be a
 - filesystem-backed attachments
 - CRM customers/vendors, hierarchy, contacts, lifecycle metadata, and attachments
 - inventory items, BOMs, warehouses, locations, transactions, item attachments, and item pricing
- sales quotes, sales orders, and purchase orders
+- sales quotes, sales orders, approvals, revision history, and purchase orders
 - purchase-order supporting documents and vendor-side purchasing visibility
 - shipping shipments, packing-slip PDFs, shipping labels, bills of lading, and logistics attachments
 - projects with customer/commercial/shipment linkage, owners, due dates, notes, and attachments
@@ -117,11 +117,10 @@ If implementation changes invalidate those docs, update them in the same change

 Near-term priorities are:

-1. Sales approvals and document revision history
-2. Planning and gantt scheduling with live project/manufacturing data
-3. Inventory transfers, reservations, and deeper stock controls
-4. Broader audit-trail coverage and operational diagnostics
-5. Code-splitting and bundle-size reduction
+1. Planning and gantt scheduling with live project/manufacturing data
+2. Inventory transfers, reservations, and deeper stock controls
+3. Broader audit-trail coverage and operational diagnostics
+4. Code-splitting and bundle-size reduction

 When adding new modules, preserve the ability to extend the system without refactoring the existing app shell.

--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,8 @@ This file is the running release and change log for MRP Codex. Keep it updated w

 ### Added

+- Sales approval actions with approved-by/approved-at stamps on quotes and sales orders
+- Automatic sales-document revision history with authored reasons and per-revision snapshots
 - Projects domain foundation with customer, owner, due date, priority, notes, and attachment support
 - Project linkage to sales quotes, sales orders, and shipments for cross-module delivery tracking
 - Project list/detail/create/edit workflows and app-shell navigation entry
@@ -20,11 +22,12 @@ This file is the running release and change log for MRP Codex. Keep it updated w

 - The dashboard now treats Projects as a live first-class module alongside CRM, inventory, sales, and shipping
 - The dashboard now treats Manufacturing as a live first-class module alongside CRM, inventory, sales, shipping, and projects
+- Sales quote and sales-order detail pages now surface approval state and revision history directly in the operational workflow
 - Project editing now uses searchable pickers for customer, owner, quote, sales-order, and shipment linkage instead of static operational dropdowns
 - Project detail now surfaces linked work orders and can launch pre-seeded manufacturing records
 - Purchase-order detail now links back to the vendor CRM record and supports direct supporting-document management on the PO itself
 - Vendor CRM detail now exposes purchasing activity and can launch pre-seeded purchase orders
- Roadmap and project docs now treat sales approvals and document revision history as the next active priority after the vendor-document and stabilization pass
+- Roadmap and project docs now treat planning and gantt scheduling as the next active priority after the sales approval and revision-history slice

 ## 2026-03-15

--- a/INSTRUCTIONS.md
+++ b/INSTRUCTIONS.md
@@ -16,6 +16,7 @@ This repository implements the platform foundation milestone:
 - CRM foundation through reseller hierarchy, contacts, attachments, and lifecycle metadata
 - inventory master data, BOM, warehouse, stock-location, transactions, and item attachments
 - sales quotes and sales orders with quick actions and quote conversion
+- sales approvals, approval stamps, and automatic revision history on quotes and sales orders
 - purchase orders with quick actions and searchable vendor/SKU entry
 - purchase orders restricted to inventory items flagged as purchasable
 - purchase receiving foundation with inventory posting and receipt history
@@ -59,7 +60,6 @@ This repository implements the platform foundation milestone:

 ## Next roadmap candidates

- sales approvals and document revision history
 - planning and gantt scheduling with live project/manufacturing data
 - inventory transfers, reservations, and deeper stock controls
 - broader audit and operations maturity
--- a/README.md
+++ b/README.md
@@ -16,6 +16,7 @@ Current foundation scope includes:
 - CRM contact history, account contacts, and shared attachments
 - inventory item master, BOM, warehouse, stock-location, and stock-transaction flows
 - sales quotes and sales orders with searchable customer and SKU entry
+- sales approvals, approval stamps, and automatic revision history on quotes and sales orders
 - purchase orders with searchable vendor and SKU entry, restricted to purchasable inventory items
 - purchase receiving with warehouse/location posting and receipt history against purchase orders
 - branded quote, sales-order, and purchase-order PDFs through the shared backend document pipeline
@@ -44,17 +45,15 @@ Planned cross-module execution areas:

 Near-term priorities:

-1. Sales approvals and revision history
-2. Planning and gantt scheduling with live project/manufacturing data
-3. Inventory transfers, reservations, and deeper stock controls
-4. Broader audit-trail coverage and operational diagnostics
-5. Code-splitting and bundle-size reduction
+1. Planning and gantt scheduling with live project/manufacturing data
+2. Inventory transfers, reservations, and deeper stock controls
+3. Broader audit-trail coverage and operational diagnostics
+4. Code-splitting and bundle-size reduction

 Revisit / deferred items:

 - local Windows Prisma migration reliability
 - frontend code-splitting and bundle-size reduction
- sales approvals and revision history
 - inventory transfers, reservations, and deeper stock controls
 - deeper audit-trail coverage

@@ -222,11 +221,13 @@ The current sales foundation supports:
 - quote conversion into a sales order
 - line-level unit prices populated from the selected inventory item default price
 - branded quote and sales-order PDFs through the shared document pipeline
+- approval stamps and revision history directly on quote and sales-order detail pages
+- revision-reason capture when editing customer-facing sales documents

 QOL direction:

 - line duplication and faster keyboard-heavy line editing
- stronger revision/approval flow
+- revision comparison view and restore-style workflows
 - richer PDF output for quotes and sales orders

 This module introduces `sales.read` and `sales.write` permissions. After updating the code, restart the server against the migrated database so bootstrap can upsert the new permissions onto the default administrator role.
@@ -311,6 +312,7 @@ As of March 14, 2026, the latest committed domain migrations include:
 - purchase-order foundation
 - purchase receiving foundation
 - branded sales and purchasing PDF templates
+- sales approvals and document revision history
 - inventory default price support
 - sales totals and commercial fields
 - shipping foundation
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -58,7 +58,7 @@ MRP Codex is being built as a streamlined, modular manufacturing resource planni
 - Prisma migration execution is committed and documented, but local Windows Node 24 schema-engine behavior remains inconsistent; use Node 22 or Docker for migration execution
 - The frontend bundle is functional but should be code-split later, especially around the gantt module
 - CRM reporting is now functional, but broader account-role depth and downstream document rollups can still evolve later
- The current sales/purchasing/shipping foundation still does not include approvals, revisions, vendor exception handling, or deeper carrier integration
+- The current sales/purchasing/shipping foundation now includes sales approvals and revision history, but still needs vendor exception handling, deeper carrier integration, and richer document comparison tooling
 - The dashboard is now live-data driven, but still needs richer KPI widgets, alerts, recent-activity queues, and exception reporting as more transactional depth is added
 - The new projects domain is foundational but still needs milestones, project rollups, and deeper inventory/purchasing/manufacturing tie-ins
 - The new manufacturing domain is foundational but still needs routings, labor capture, work-center views, and capacity-aware planning tie-ins
@@ -119,6 +119,7 @@ QOL subfeatures:

 Foundation slice shipped:

+- Sales approval stamps and automatic revision history on quotes and sales orders
 - Purchase-order supporting documents through the shared attachment pipeline
 - Vendor-detail purchasing visibility for recent purchase-order activity

@@ -257,7 +258,6 @@ QOL subfeatures:

 - Local Windows Prisma migration reliability still needs a cleaner documented workflow or tooling wrapper
 - Frontend bundle splitting is still deferred; the Vite chunk-size warning remains
- Sales approvals and document revision history were planned but not yet built
 - Inventory transactions exist, but transfers, reservations, and more advanced stock controls still need follow-up
 - CRM document rollups and broader account-role depth were deferred until more downstream modules exist
 - Audit-trail depth is still thin outside the current record/update flows
@@ -275,8 +275,7 @@ QOL subfeatures:

 ## Near-term priority order

-1. Sales approvals and document revision history
-2. Planning and scheduling with live project/manufacturing data
-3. Inventory transfers, reservations, and deeper stock controls
-4. Broader audit-trail coverage and operational diagnostics
-5. Code-splitting and bundle-size reduction
+1. Planning and scheduling with live project/manufacturing data
+2. Inventory transfers, reservations, and deeper stock controls
+3. Broader audit-trail coverage and operational diagnostics
+4. Code-splitting and bundle-size reduction
--- a/client/src/lib/api.ts
+++ b/client/src/lib/api.ts
@@ -58,6 +58,7 @@ import type {
  SalesCustomerOptionDto,
  SalesDocumentDetailDto,
  SalesDocumentInput,
+  SalesDocumentRevisionDto,
  SalesDocumentStatus,
  SalesDocumentSummaryDto,
 } from "@mrp/shared/dist/sales/types.js";
@@ -537,6 +538,12 @@ export const api = {
      token
    );
  },
+  approveQuote(token: string, quoteId: string) {
+    return request<SalesDocumentDetailDto>(`/api/v1/sales/quotes/${quoteId}/approve`, { method: "POST" }, token);
+  },
+  getQuoteRevisions(token: string, quoteId: string) {
+    return request<SalesDocumentRevisionDto[]>(`/api/v1/sales/quotes/${quoteId}/revisions`, undefined, token);
+  },
  convertQuoteToSalesOrder(token: string, quoteId: string) {
    return request<SalesDocumentDetailDto>(`/api/v1/sales/quotes/${quoteId}/convert`, { method: "POST" }, token);
  },
@@ -566,6 +573,12 @@ export const api = {
      token
    );
  },
+  approveSalesOrder(token: string, orderId: string) {
+    return request<SalesDocumentDetailDto>(`/api/v1/sales/orders/${orderId}/approve`, { method: "POST" }, token);
+  },
+  getSalesOrderRevisions(token: string, orderId: string) {
+    return request<SalesDocumentRevisionDto[]>(`/api/v1/sales/orders/${orderId}/revisions`, undefined, token);
+  },
  getPurchaseOrders(token: string, filters?: { q?: string; status?: PurchaseOrderStatus; vendorId?: string }) {
    return request<PurchaseOrderSummaryDto[]>(
      `/api/v1/purchasing/orders${buildQueryString({
--- a/client/src/modules/sales/SalesDetailPage.tsx
+++ b/client/src/modules/sales/SalesDetailPage.tsx
@@ -21,6 +21,7 @@ export function SalesDetailPage({ entity }: { entity: SalesDocumentEntity }) {
  const [isUpdatingStatus, setIsUpdatingStatus] = useState(false);
  const [isConverting, setIsConverting] = useState(false);
  const [isOpeningPdf, setIsOpeningPdf] = useState(false);
+  const [isApproving, setIsApproving] = useState(false);
  const [shipments, setShipments] = useState<ShipmentSummaryDto[]>([]);

  const canManage = user?.permissions.includes(permissions.salesWrite) ?? false;
@@ -119,6 +120,27 @@ export function SalesDetailPage({ entity }: { entity: SalesDocumentEntity }) {
    }
  }

+  async function handleApprove() {
+    if (!token) {
+      return;
+    }
+
+    setIsApproving(true);
+    setStatus(`Approving ${config.singularLabel.toLowerCase()}...`);
+
+    try {
+      const nextDocument =
+        entity === "quote" ? await api.approveQuote(token, activeDocument.id) : await api.approveSalesOrder(token, activeDocument.id);
+      setDocument(nextDocument);
+      setStatus(`${config.singularLabel} approved.`);
+    } catch (error: unknown) {
+      const message = error instanceof ApiError ? error.message : `Unable to approve ${config.singularLabel.toLowerCase()}.`;
+      setStatus(message);
+    } finally {
+      setIsApproving(false);
+    }
+  }
+
  return (
    <section className="space-y-4">
      <div className="rounded-[28px] border border-line/70 bg-surface/90 p-4 shadow-panel 2xl:p-5">
@@ -129,6 +151,9 @@ export function SalesDetailPage({ entity }: { entity: SalesDocumentEntity }) {
            <p className="mt-1 text-sm text-text">{activeDocument.customerName}</p>
            <div className="mt-3 flex flex-wrap gap-2">
              <SalesStatusBadge status={activeDocument.status} />
+              <span className="inline-flex items-center rounded-full border border-line/70 px-2 py-1 text-xs font-semibold uppercase tracking-[0.16em] text-muted">
+                Rev {activeDocument.currentRevisionNumber}
+              </span>
            </div>
          </div>
          <div className="flex flex-wrap gap-3">
@@ -148,6 +173,16 @@ export function SalesDetailPage({ entity }: { entity: SalesDocumentEntity }) {
                <Link to={`${config.routeBase}/${activeDocument.id}/edit`} className="inline-flex items-center justify-center rounded-2xl bg-brand px-2 py-2 text-sm font-semibold text-white">
                  Edit {config.singularLabel.toLowerCase()}
                </Link>
+                {activeDocument.status !== "APPROVED" ? (
+                  <button
+                    type="button"
+                    onClick={handleApprove}
+                    disabled={isApproving}
+                    className="inline-flex items-center justify-center rounded-2xl border border-emerald-400/40 px-2 py-2 text-sm font-semibold text-emerald-700 disabled:cursor-not-allowed disabled:opacity-60 dark:text-emerald-300"
+                  >
+                    {isApproving ? "Approving..." : "Approve"}
+                  </button>
+                ) : null}
                {entity === "quote" ? (
                  <button
                    type="button"
@@ -205,8 +240,9 @@ export function SalesDetailPage({ entity }: { entity: SalesDocumentEntity }) {
          <div className="mt-2 text-base font-bold text-text">{activeDocument.lineCount}</div>
        </article>
        <article className="rounded-[24px] border border-line/70 bg-surface/90 px-3 py-3 shadow-panel">
-          <p className="text-xs font-semibold uppercase tracking-[0.18em] text-muted">Subtotal</p>
-          <div className="mt-2 text-base font-bold text-text">${activeDocument.subtotal.toFixed(2)}</div>
+          <p className="text-xs font-semibold uppercase tracking-[0.18em] text-muted">Approval</p>
+          <div className="mt-2 text-base font-bold text-text">{activeDocument.approvedAt ? new Date(activeDocument.approvedAt).toLocaleDateString() : "Pending"}</div>
+          <div className="mt-1 text-xs text-muted">{activeDocument.approvedByName ?? "No approver recorded"}</div>
        </article>
      </section>
      <section className="grid gap-3 xl:grid-cols-4">
@@ -229,6 +265,36 @@ export function SalesDetailPage({ entity }: { entity: SalesDocumentEntity }) {
          <div className="mt-2 text-base font-bold text-text">${activeDocument.total.toFixed(2)}</div>
        </article>
      </section>
+      <section className="rounded-[28px] border border-line/70 bg-surface/90 p-4 shadow-panel 2xl:p-5">
+        <div className="flex items-center justify-between gap-3">
+          <div>
+            <p className="text-xs font-semibold uppercase tracking-[0.24em] text-muted">Revision History</p>
+            <p className="mt-2 text-sm text-muted">Automatic snapshots are recorded when the document changes status, content, or approval state.</p>
+          </div>
+        </div>
+        {activeDocument.revisions.length === 0 ? (
+          <div className="mt-6 rounded-3xl border border-dashed border-line/70 bg-page/60 px-4 py-8 text-center text-sm text-muted">
+            No revisions have been recorded yet.
+          </div>
+        ) : (
+          <div className="mt-6 space-y-3">
+            {activeDocument.revisions.map((revision) => (
+              <article key={revision.id} className="rounded-3xl border border-line/70 bg-page/60 p-3">
+                <div className="flex flex-wrap items-start justify-between gap-3">
+                  <div>
+                    <div className="font-semibold text-text">Rev {revision.revisionNumber}</div>
+                    <div className="mt-1 text-sm text-text">{revision.reason}</div>
+                  </div>
+                  <div className="text-right text-xs text-muted">
+                    <div>{new Date(revision.createdAt).toLocaleString()}</div>
+                    <div className="mt-1">{revision.createdByName ?? "System"}</div>
+                  </div>
+                </div>
+              </article>
+            ))}
+          </div>
+        )}
+      </section>
      <div className="grid gap-3 xl:grid-cols-[minmax(0,1.05fr)_minmax(320px,0.95fr)]">
        <article className="rounded-[28px] border border-line/70 bg-surface/90 p-4 shadow-panel 2xl:p-5">
          <p className="text-xs font-semibold uppercase tracking-[0.24em] text-muted">Customer</p>
--- a/client/src/modules/sales/SalesFormPage.tsx
+++ b/client/src/modules/sales/SalesFormPage.tsx
@@ -56,6 +56,7 @@ export function SalesFormPage({ entity, mode }: { entity: SalesDocumentEntity; m
          taxPercent: document.taxPercent,
          freightAmount: document.freightAmount,
          notes: document.notes,
+          revisionReason: "",
          lines: document.lines.map((line) => ({
            itemId: line.itemId,
            description: line.description,
@@ -290,6 +291,17 @@ export function SalesFormPage({ entity, mode }: { entity: SalesDocumentEntity; m
            className="w-full rounded-3xl border border-line/70 bg-page px-2 py-2 text-text outline-none transition focus:border-brand"
          />
        </label>
+        {mode === "edit" ? (
+          <label className="block xl:max-w-xl">
+            <span className="mb-2 block text-sm font-semibold text-text">Revision Reason</span>
+            <input
+              value={form.revisionReason ?? ""}
+              onChange={(event) => updateField("revisionReason", event.target.value)}
+              placeholder="What changed in this revision?"
+              className="w-full rounded-2xl border border-line/70 bg-page px-2 py-2 text-text outline-none transition focus:border-brand"
+            />
+          </label>
+        ) : null}
        <div className="grid gap-3 xl:grid-cols-3">
          <label className="block">
            <span className="mb-2 block text-sm font-semibold text-text">Discount %</span>
--- a/client/src/modules/sales/SalesListPage.tsx
+++ b/client/src/modules/sales/SalesListPage.tsx
@@ -93,6 +93,7 @@ export function SalesListPage({ entity }: { entity: SalesDocumentEntity }) {
                <th className="px-2 py-2">Document</th>
                <th className="px-2 py-2">Customer</th>
                <th className="px-2 py-2">Status</th>
+                <th className="px-2 py-2">Revision</th>
                <th className="px-2 py-2">Issue Date</th>
                <th className="px-2 py-2">Value</th>
                <th className="px-2 py-2">Lines</th>
@@ -110,6 +111,10 @@ export function SalesListPage({ entity }: { entity: SalesDocumentEntity }) {
                  <td className="px-2 py-2">
                    <SalesStatusBadge status={document.status} />
                  </td>
+                  <td className="px-2 py-2 text-muted">
+                    Rev {document.currentRevisionNumber}
+                    {document.approvedAt ? <div className="mt-1 text-xs text-muted">Approved</div> : null}
+                  </td>
                  <td className="px-2 py-2 text-muted">{new Date(document.issueDate).toLocaleDateString()}</td>
                  <td className="px-2 py-2 text-muted">${document.total.toFixed(2)}</td>
                  <td className="px-2 py-2 text-muted">{document.lineCount}</td>
--- a/client/src/modules/sales/config.ts
+++ b/client/src/modules/sales/config.ts
@@ -59,4 +59,5 @@ export const emptySalesDocumentInput: SalesDocumentInput = {
  freightAmount: 0,
  notes: "",
  lines: [],
+  revisionReason: "",
 };
--- a/server/prisma/migrations/20260315183000_sales_approvals_and_revisions/migration.sql
+++ b/server/prisma/migrations/20260315183000_sales_approvals_and_revisions/migration.sql
@@ -0,0 +1,53 @@
+-- AlterTable
+ALTER TABLE "SalesQuote" ADD COLUMN "approvedAt" DATETIME;
+ALTER TABLE "SalesQuote" ADD COLUMN "approvedById" TEXT;
+
+-- AlterTable
+ALTER TABLE "SalesOrder" ADD COLUMN "approvedAt" DATETIME;
+ALTER TABLE "SalesOrder" ADD COLUMN "approvedById" TEXT;
+
+-- CreateTable
+CREATE TABLE "SalesQuoteRevision" (
+    "id" TEXT NOT NULL PRIMARY KEY,
+    "quoteId" TEXT NOT NULL,
+    "revisionNumber" INTEGER NOT NULL,
+    "reason" TEXT NOT NULL,
+    "snapshot" TEXT NOT NULL,
+    "createdById" TEXT,
+    "createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" DATETIME NOT NULL,
+    CONSTRAINT "SalesQuoteRevision_quoteId_fkey" FOREIGN KEY ("quoteId") REFERENCES "SalesQuote" ("id") ON DELETE CASCADE ON UPDATE CASCADE,
+    CONSTRAINT "SalesQuoteRevision_createdById_fkey" FOREIGN KEY ("createdById") REFERENCES "User" ("id") ON DELETE SET NULL ON UPDATE CASCADE
+);
+
+-- CreateTable
+CREATE TABLE "SalesOrderRevision" (
+    "id" TEXT NOT NULL PRIMARY KEY,
+    "orderId" TEXT NOT NULL,
+    "revisionNumber" INTEGER NOT NULL,
+    "reason" TEXT NOT NULL,
+    "snapshot" TEXT NOT NULL,
+    "createdById" TEXT,
+    "createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" DATETIME NOT NULL,
+    CONSTRAINT "SalesOrderRevision_orderId_fkey" FOREIGN KEY ("orderId") REFERENCES "SalesOrder" ("id") ON DELETE CASCADE ON UPDATE CASCADE,
+    CONSTRAINT "SalesOrderRevision_createdById_fkey" FOREIGN KEY ("createdById") REFERENCES "User" ("id") ON DELETE SET NULL ON UPDATE CASCADE
+);
+
+-- CreateIndex
+CREATE INDEX "SalesQuote_approvedById_idx" ON "SalesQuote"("approvedById");
+
+-- CreateIndex
+CREATE INDEX "SalesOrder_approvedById_idx" ON "SalesOrder"("approvedById");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "SalesQuoteRevision_quoteId_revisionNumber_key" ON "SalesQuoteRevision"("quoteId", "revisionNumber");
+
+-- CreateIndex
+CREATE INDEX "SalesQuoteRevision_quoteId_createdAt_idx" ON "SalesQuoteRevision"("quoteId", "createdAt");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "SalesOrderRevision_orderId_revisionNumber_key" ON "SalesOrderRevision"("orderId", "revisionNumber");
+
+-- CreateIndex
+CREATE INDEX "SalesOrderRevision_orderId_createdAt_idx" ON "SalesOrderRevision"("orderId", "createdAt");
--- a/server/prisma/schema.prisma
+++ b/server/prisma/schema.prisma
@@ -24,6 +24,10 @@ model User {
  ownedProjects Project[] @relation("ProjectOwner")
  workOrderMaterialIssues WorkOrderMaterialIssue[]
  workOrderCompletions WorkOrderCompletion[]
+  approvedSalesQuotes SalesQuote[] @relation("SalesQuoteApprovedBy")
+  approvedSalesOrders SalesOrder[] @relation("SalesOrderApprovedBy")
+  salesQuoteRevisionsCreated SalesQuoteRevision[] @relation("SalesQuoteRevisionCreatedBy")
+  salesOrderRevisionsCreated SalesOrderRevision[] @relation("SalesOrderRevisionCreatedBy")
 }

 model Role {
@@ -305,6 +309,8 @@ model SalesQuote {
  status         String
  issueDate      DateTime
  expiresAt      DateTime?
+  approvedAt     DateTime?
+  approvedById   String?
  discountPercent Float   @default(0)
  taxPercent      Float   @default(0)
  freightAmount   Float   @default(0)
@@ -312,8 +318,10 @@ model SalesQuote {
  createdAt      DateTime @default(now())
  updatedAt      DateTime @updatedAt
  customer       Customer @relation(fields: [customerId], references: [id], onDelete: Restrict)
+  approvedBy     User? @relation("SalesQuoteApprovedBy", fields: [approvedById], references: [id], onDelete: SetNull)
  lines          SalesQuoteLine[]
  projects       Project[]
+  revisions      SalesQuoteRevision[]
 }

 model SalesQuoteLine {
@@ -339,6 +347,8 @@ model SalesOrder {
  customerId     String
  status         String
  issueDate      DateTime
+  approvedAt     DateTime?
+  approvedById   String?
  discountPercent Float   @default(0)
  taxPercent      Float   @default(0)
  freightAmount   Float   @default(0)
@@ -346,9 +356,11 @@ model SalesOrder {
  createdAt      DateTime @default(now())
  updatedAt      DateTime @updatedAt
  customer       Customer @relation(fields: [customerId], references: [id], onDelete: Restrict)
+  approvedBy     User? @relation("SalesOrderApprovedBy", fields: [approvedById], references: [id], onDelete: SetNull)
  lines          SalesOrderLine[]
  shipments      Shipment[]
  projects       Project[]
+  revisions      SalesOrderRevision[]
 }

 model SalesOrderLine {
@@ -368,6 +380,38 @@ model SalesOrderLine {
  @@index([orderId, position])
 }

+model SalesQuoteRevision {
+  id             String   @id @default(cuid())
+  quoteId        String
+  revisionNumber Int
+  reason         String
+  snapshot       String
+  createdById    String?
+  createdAt      DateTime @default(now())
+  updatedAt      DateTime @updatedAt
+  quote          SalesQuote @relation(fields: [quoteId], references: [id], onDelete: Cascade)
+  createdBy      User? @relation("SalesQuoteRevisionCreatedBy", fields: [createdById], references: [id], onDelete: SetNull)
+
+  @@unique([quoteId, revisionNumber])
+  @@index([quoteId, createdAt])
+}
+
+model SalesOrderRevision {
+  id             String   @id @default(cuid())
+  orderId        String
+  revisionNumber Int
+  reason         String
+  snapshot       String
+  createdById    String?
+  createdAt      DateTime @default(now())
+  updatedAt      DateTime @updatedAt
+  order          SalesOrder @relation(fields: [orderId], references: [id], onDelete: Cascade)
+  createdBy      User? @relation("SalesOrderRevisionCreatedBy", fields: [createdById], references: [id], onDelete: SetNull)
+
+  @@unique([orderId, revisionNumber])
+  @@index([orderId, createdAt])
+}
+
 model Shipment {
  id             String   @id @default(cuid())
  shipmentNumber String   @unique
--- a/server/src/modules/sales/router.ts
+++ b/server/src/modules/sales/router.ts
@@ -7,9 +7,11 @@ import { fail, ok } from "../../lib/http.js";
 import { requirePermissions } from "../../lib/rbac.js";
 import { inventoryUnitsOfMeasure } from "@mrp/shared/dist/inventory/types.js";
 import {
+  approveSalesDocument,
  convertQuoteToSalesOrder,
  createSalesDocument,
  getSalesDocumentById,
+  listSalesDocumentRevisions,
  listSalesCustomerOptions,
  listSalesDocuments,
  listSalesOrderOptions,
@@ -36,6 +38,7 @@ const quoteSchema = z.object({
  freightAmount: z.number().nonnegative(),
  notes: z.string(),
  lines: z.array(salesLineSchema),
+  revisionReason: z.string().optional(),
 });

 const orderSchema = z.object({
@@ -47,6 +50,7 @@ const orderSchema = z.object({
  freightAmount: z.number().nonnegative(),
  notes: z.string(),
  lines: z.array(salesLineSchema),
+  revisionReason: z.string().optional(),
 });

 const salesListQuerySchema = z.object({
@@ -101,7 +105,7 @@ salesRouter.post("/quotes", requirePermissions([permissions.salesWrite]), async
    return fail(response, 400, "INVALID_INPUT", "Quote payload is invalid.");
  }

-  const result = await createSalesDocument("QUOTE", parsed.data);
+  const result = await createSalesDocument("QUOTE", parsed.data, request.authUser?.id);
  if (!result.ok) {
    return fail(response, 400, "INVALID_INPUT", result.reason);
  }
@@ -120,7 +124,7 @@ salesRouter.put("/quotes/:quoteId", requirePermissions([permissions.salesWrite])
    return fail(response, 400, "INVALID_INPUT", "Quote payload is invalid.");
  }

-  const result = await updateSalesDocument("QUOTE", quoteId, parsed.data);
+  const result = await updateSalesDocument("QUOTE", quoteId, parsed.data, request.authUser?.id);
  if (!result.ok) {
    return fail(response, 400, "INVALID_INPUT", result.reason);
  }
@@ -139,7 +143,7 @@ salesRouter.patch("/quotes/:quoteId/status", requirePermissions([permissions.sal
    return fail(response, 400, "INVALID_INPUT", "Quote status payload is invalid.");
  }

-  const result = await updateSalesDocumentStatus("QUOTE", quoteId, parsed.data.status);
+  const result = await updateSalesDocumentStatus("QUOTE", quoteId, parsed.data.status, request.authUser?.id);
  if (!result.ok) {
    return fail(response, 400, "INVALID_INPUT", result.reason);
  }
@@ -147,13 +151,41 @@ salesRouter.patch("/quotes/:quoteId/status", requirePermissions([permissions.sal
  return ok(response, result.document);
 });

+salesRouter.post("/quotes/:quoteId/approve", requirePermissions([permissions.salesWrite]), async (request, response) => {
+  const quoteId = getRouteParam(request.params.quoteId);
+  if (!quoteId) {
+    return fail(response, 400, "INVALID_INPUT", "Quote id is invalid.");
+  }
+
+  const result = await approveSalesDocument("QUOTE", quoteId, request.authUser?.id);
+  if (!result.ok) {
+    return fail(response, 400, "INVALID_INPUT", result.reason);
+  }
+
+  return ok(response, result.document);
+});
+
+salesRouter.get("/quotes/:quoteId/revisions", requirePermissions([permissions.salesRead]), async (request, response) => {
+  const quoteId = getRouteParam(request.params.quoteId);
+  if (!quoteId) {
+    return fail(response, 400, "INVALID_INPUT", "Quote id is invalid.");
+  }
+
+  const quote = await getSalesDocumentById("QUOTE", quoteId);
+  if (!quote) {
+    return fail(response, 404, "QUOTE_NOT_FOUND", "Quote was not found.");
+  }
+
+  return ok(response, await listSalesDocumentRevisions("QUOTE", quoteId));
+});
+
 salesRouter.post("/quotes/:quoteId/convert", requirePermissions([permissions.salesWrite]), async (request, response) => {
  const quoteId = getRouteParam(request.params.quoteId);
  if (!quoteId) {
    return fail(response, 400, "INVALID_INPUT", "Quote id is invalid.");
  }

-  const result = await convertQuoteToSalesOrder(quoteId);
+  const result = await convertQuoteToSalesOrder(quoteId, request.authUser?.id);
  if (!result.ok) {
    return fail(response, 400, "INVALID_INPUT", result.reason);
  }
@@ -193,7 +225,7 @@ salesRouter.post("/orders", requirePermissions([permissions.salesWrite]), async
  const result = await createSalesDocument("ORDER", {
    ...parsed.data,
    expiresAt: null,
-  });
+  }, request.authUser?.id);
  if (!result.ok) {
    return fail(response, 400, "INVALID_INPUT", result.reason);
  }
@@ -215,7 +247,7 @@ salesRouter.put("/orders/:orderId", requirePermissions([permissions.salesWrite])
  const result = await updateSalesDocument("ORDER", orderId, {
    ...parsed.data,
    expiresAt: null,
-  });
+  }, request.authUser?.id);
  if (!result.ok) {
    return fail(response, 400, "INVALID_INPUT", result.reason);
  }
@@ -234,10 +266,38 @@ salesRouter.patch("/orders/:orderId/status", requirePermissions([permissions.sal
    return fail(response, 400, "INVALID_INPUT", "Sales order status payload is invalid.");
  }

-  const result = await updateSalesDocumentStatus("ORDER", orderId, parsed.data.status);
+  const result = await updateSalesDocumentStatus("ORDER", orderId, parsed.data.status, request.authUser?.id);
  if (!result.ok) {
    return fail(response, 400, "INVALID_INPUT", result.reason);
  }

  return ok(response, result.document);
 });
+
+salesRouter.post("/orders/:orderId/approve", requirePermissions([permissions.salesWrite]), async (request, response) => {
+  const orderId = getRouteParam(request.params.orderId);
+  if (!orderId) {
+    return fail(response, 400, "INVALID_INPUT", "Sales order id is invalid.");
+  }
+
+  const result = await approveSalesDocument("ORDER", orderId, request.authUser?.id);
+  if (!result.ok) {
+    return fail(response, 400, "INVALID_INPUT", result.reason);
+  }
+
+  return ok(response, result.document);
+});
+
+salesRouter.get("/orders/:orderId/revisions", requirePermissions([permissions.salesRead]), async (request, response) => {
+  const orderId = getRouteParam(request.params.orderId);
+  if (!orderId) {
+    return fail(response, 400, "INVALID_INPUT", "Sales order id is invalid.");
+  }
+
+  const order = await getSalesDocumentById("ORDER", orderId);
+  if (!order) {
+    return fail(response, 404, "SALES_ORDER_NOT_FOUND", "Sales order was not found.");
+  }
+
+  return ok(response, await listSalesDocumentRevisions("ORDER", orderId));
+});
--- a/server/src/modules/sales/service.ts
+++ b/server/src/modules/sales/service.ts
@@ -2,6 +2,7 @@ import type {
  SalesCustomerOptionDto,
  SalesDocumentDetailDto,
  SalesDocumentInput,
+  SalesDocumentRevisionDto,
  SalesDocumentStatus,
  SalesDocumentSummaryDto,
  SalesDocumentType,
@@ -60,12 +61,24 @@ type SalesLineRecord = {
  };
 };

+type RevisionRecord = {
+  id: string;
+  revisionNumber: number;
+  reason: string;
+  createdAt: Date;
+  createdBy: {
+    firstName: string;
+    lastName: string;
+  } | null;
+};
+
 type SalesDocumentRecord = {
  id: string;
  documentNumber: string;
  status: string;
  issueDate: Date;
  expiresAt?: Date | null;
+  approvedAt: Date | null;
  discountPercent: number;
  taxPercent: number;
  freightAmount: number;
@@ -77,10 +90,28 @@ type SalesDocumentRecord = {
    name: string;
    email: string;
  };
+  approvedBy: {
+    firstName: string;
+    lastName: string;
+  } | null;
+  revisions: RevisionRecord[];
  lines: SalesLineRecord[];
 };

-const documentConfig = {
+type DocumentConfig = {
+  prefix: string;
+  findMany: typeof prisma.salesQuote.findMany;
+  findUnique: typeof prisma.salesQuote.findUnique;
+  create: typeof prisma.salesQuote.create;
+  update: typeof prisma.salesQuote.update;
+  count: typeof prisma.salesQuote.count;
+  revisionFindMany: typeof prisma.salesQuoteRevision.findMany;
+  revisionAggregate: typeof prisma.salesQuoteRevision.aggregate;
+  revisionCreate: typeof prisma.salesQuoteRevision.create;
+  revisionDocumentField: "quoteId" | "orderId";
+};
+
+const documentConfig: Record<SalesDocumentType, DocumentConfig> = {
  QUOTE: {
    prefix: "Q",
    findMany: (prisma as any).salesQuote.findMany.bind((prisma as any).salesQuote),
@@ -88,6 +119,10 @@ const documentConfig = {
    create: (prisma as any).salesQuote.create.bind((prisma as any).salesQuote),
    update: (prisma as any).salesQuote.update.bind((prisma as any).salesQuote),
    count: (prisma as any).salesQuote.count.bind((prisma as any).salesQuote),
+    revisionFindMany: (prisma as any).salesQuoteRevision.findMany.bind((prisma as any).salesQuoteRevision),
+    revisionAggregate: (prisma as any).salesQuoteRevision.aggregate.bind((prisma as any).salesQuoteRevision),
+    revisionCreate: (prisma as any).salesQuoteRevision.create.bind((prisma as any).salesQuoteRevision),
+    revisionDocumentField: "quoteId",
  },
  ORDER: {
    prefix: "SO",
@@ -96,8 +131,12 @@ const documentConfig = {
    create: (prisma as any).salesOrder.create.bind((prisma as any).salesOrder),
    update: (prisma as any).salesOrder.update.bind((prisma as any).salesOrder),
    count: (prisma as any).salesOrder.count.bind((prisma as any).salesOrder),
+    revisionFindMany: (prisma as any).salesOrderRevision.findMany.bind((prisma as any).salesOrderRevision),
+    revisionAggregate: (prisma as any).salesOrderRevision.aggregate.bind((prisma as any).salesOrderRevision),
+    revisionCreate: (prisma as any).salesOrderRevision.create.bind((prisma as any).salesOrderRevision),
+    revisionDocumentField: "orderId",
  },
-} as const;
+};

 function roundMoney(value: number) {
  return Math.round(value * 100) / 100;
@@ -124,6 +163,24 @@ function calculateTotals(subtotal: number, discountPercent: number, taxPercent:
  };
 }

+function getUserDisplayName(user: { firstName: string; lastName: string } | null) {
+  if (!user) {
+    return null;
+  }
+
+  return `${user.firstName} ${user.lastName}`.trim();
+}
+
+function mapRevision(record: RevisionRecord): SalesDocumentRevisionDto {
+  return {
+    id: record.id,
+    revisionNumber: record.revisionNumber,
+    reason: record.reason,
+    createdAt: record.createdAt.toISOString(),
+    createdByName: getUserDisplayName(record.createdBy),
+  };
+}
+
 function normalizeLines(lines: SalesLineInput[]) {
  return lines
    .map((line, index) => ({
@@ -187,6 +244,10 @@ function mapDocument(record: SalesDocumentRecord): SalesDocumentDetailDto {
    record.taxPercent,
    record.freightAmount
  );
+  const revisions = record.revisions
+    .slice()
+    .sort((left, right) => right.revisionNumber - left.revisionNumber)
+    .map(mapRevision);

  return {
    id: record.id,
@@ -195,6 +256,9 @@ function mapDocument(record: SalesDocumentRecord): SalesDocumentDetailDto {
    customerName: record.customer.name,
    customerEmail: record.customer.email,
    status: record.status as SalesDocumentStatus,
+    approvedAt: record.approvedAt ? record.approvedAt.toISOString() : null,
+    approvedByName: getUserDisplayName(record.approvedBy),
+    currentRevisionNumber: revisions[0]?.revisionNumber ?? 0,
    subtotal: totals.subtotal,
    discountPercent: totals.discountPercent,
    discountAmount: totals.discountAmount,
@@ -209,16 +273,95 @@ function mapDocument(record: SalesDocumentRecord): SalesDocumentDetailDto {
    updatedAt: record.updatedAt.toISOString(),
    lineCount: lines.length,
    lines,
+    revisions,
  };
 }

+function buildRevisionSnapshot(document: SalesDocumentDetailDto) {
+  return JSON.stringify({
+    documentNumber: document.documentNumber,
+    customerId: document.customerId,
+    customerName: document.customerName,
+    status: document.status,
+    approvedAt: document.approvedAt,
+    approvedByName: document.approvedByName,
+    issueDate: document.issueDate,
+    expiresAt: document.expiresAt,
+    discountPercent: document.discountPercent,
+    discountAmount: document.discountAmount,
+    taxPercent: document.taxPercent,
+    taxAmount: document.taxAmount,
+    freightAmount: document.freightAmount,
+    subtotal: document.subtotal,
+    total: document.total,
+    notes: document.notes,
+    lines: document.lines.map((line) => ({
+      itemId: line.itemId,
+      itemSku: line.itemSku,
+      itemName: line.itemName,
+      description: line.description,
+      quantity: line.quantity,
+      unitOfMeasure: line.unitOfMeasure,
+      unitPrice: line.unitPrice,
+      lineTotal: line.lineTotal,
+      position: line.position,
+    })),
+  });
+}
+
+async function createRevision(
+  type: SalesDocumentType,
+  documentId: string,
+  detail: SalesDocumentDetailDto,
+  reason: string,
+  userId?: string
+) {
+  const aggregate = await documentConfig[type].revisionAggregate({
+    where: { [documentConfig[type].revisionDocumentField]: documentId },
+    _max: { revisionNumber: true },
+  });
+  const nextRevisionNumber = (aggregate._max.revisionNumber ?? 0) + 1;
+
+  if (type === "QUOTE") {
+    await prisma.salesQuoteRevision.create({
+      data: {
+        quoteId: documentId,
+        revisionNumber: nextRevisionNumber,
+        reason,
+        snapshot: buildRevisionSnapshot(detail),
+        createdById: userId ?? null,
+      },
+    });
+    return;
+  }
+
+  await prisma.salesOrderRevision.create({
+    data: {
+      orderId: documentId,
+      revisionNumber: nextRevisionNumber,
+      reason,
+      snapshot: buildRevisionSnapshot(detail),
+      createdById: userId ?? null,
+    },
+  });
+}
+
+async function getDocumentDetailOrNull(type: SalesDocumentType, documentId: string) {
+  const record = await documentConfig[type].findUnique({
+    where: { id: documentId },
+    include: buildInclude(),
+  });
+
+  return record ? mapDocument(record as SalesDocumentRecord) : null;
+}
+
 async function nextDocumentNumber(type: SalesDocumentType) {
  const next = (await documentConfig[type].count()) + 1;
  return `${documentConfig[type].prefix}-${String(next).padStart(5, "0")}`;
 }

-function buildInclude(type: SalesDocumentType) {
-  const base = {
+function buildInclude() {
+  return {
    customer: {
      select: {
        id: true,
@@ -226,11 +369,23 @@ function buildInclude(type: SalesDocumentType) {
        email: true,
      },
    },
-  };
-
-  if (type === "QUOTE") {
-    return {
-      ...base,
+    approvedBy: {
+      select: {
+        firstName: true,
+        lastName: true,
+      },
+    },
+    revisions: {
+      include: {
+        createdBy: {
+          select: {
+            firstName: true,
+            lastName: true,
+          },
+        },
+      },
+      orderBy: [{ revisionNumber: "desc" as const }],
+    },
    lines: {
      include: {
        item: {
@@ -241,24 +396,7 @@ function buildInclude(type: SalesDocumentType) {
          },
        },
      },
-        orderBy: [{ position: "asc" }, { createdAt: "asc" }],
-      },
-    };
-  }
-
-  return {
-    ...base,
-    lines: {
-      include: {
-        item: {
-          select: {
-            id: true,
-            sku: true,
-            name: true,
-          },
-        },
-      },
-      orderBy: [{ position: "asc" }, { createdAt: "asc" }],
+      orderBy: [{ position: "asc" as const }, { createdAt: "asc" as const }],
    },
  };
 }
@@ -328,7 +466,7 @@ export async function listSalesDocuments(type: SalesDocumentType, filters: { q?:
          }
        : {}),
    },
-    include: buildInclude(type),
+    include: buildInclude(),
    orderBy: [{ issueDate: "desc" }, { createdAt: "desc" }],
  });

@@ -340,6 +478,9 @@ export async function listSalesDocuments(type: SalesDocumentType, filters: { q?:
      customerId: detail.customerId,
      customerName: detail.customerName,
      status: detail.status,
+      approvedAt: detail.approvedAt,
+      approvedByName: detail.approvedByName,
+      currentRevisionNumber: detail.currentRevisionNumber,
      subtotal: detail.subtotal,
      discountPercent: detail.discountPercent,
      discountAmount: detail.discountAmount,
@@ -357,15 +498,27 @@ export async function listSalesDocuments(type: SalesDocumentType, filters: { q?:
 }

 export async function getSalesDocumentById(type: SalesDocumentType, documentId: string) {
-  const record = await documentConfig[type].findUnique({
-    where: { id: documentId },
-    include: buildInclude(type),
-  });
-
-  return record ? mapDocument(record as SalesDocumentRecord) : null;
+  return getDocumentDetailOrNull(type, documentId);
 }

-export async function createSalesDocument(type: SalesDocumentType, payload: SalesDocumentInput) {
+export async function listSalesDocumentRevisions(type: SalesDocumentType, documentId: string) {
+  const revisions = await documentConfig[type].revisionFindMany({
+    where: { [documentConfig[type].revisionDocumentField]: documentId },
+    include: {
+      createdBy: {
+        select: {
+          firstName: true,
+          lastName: true,
+        },
+      },
+    },
+    orderBy: [{ revisionNumber: "desc" }],
+  });
+
+  return revisions.map((revision: RevisionRecord) => mapRevision(revision));
+}
+
+export async function createSalesDocument(type: SalesDocumentType, payload: SalesDocumentInput, userId?: string) {
  const validatedLines = await validateLines(payload.lines);
  if (!validatedLines.ok) {
    return { ok: false as const, reason: validatedLines.reason };
@@ -382,13 +535,32 @@ export async function createSalesDocument(type: SalesDocumentType, payload: Sale

  const documentNumber = await nextDocumentNumber(type);

-  const created = await documentConfig[type].create({
+  const createdId = await prisma.$transaction(async (tx) => {
+    const created =
+      type === "QUOTE"
+        ? await tx.salesQuote.create({
+            data: {
+              documentNumber,
+              customerId: payload.customerId,
+              status: payload.status,
+              issueDate: new Date(payload.issueDate),
+              expiresAt: payload.expiresAt ? new Date(payload.expiresAt) : null,
+              discountPercent: payload.discountPercent,
+              taxPercent: payload.taxPercent,
+              freightAmount: payload.freightAmount,
+              notes: payload.notes,
+              lines: {
+                create: validatedLines.lines,
+              },
+            },
+            select: { id: true },
+          })
+        : await tx.salesOrder.create({
            data: {
              documentNumber,
              customerId: payload.customerId,
              status: payload.status,
              issueDate: new Date(payload.issueDate),
-      ...(type === "QUOTE" ? { expiresAt: payload.expiresAt ? new Date(payload.expiresAt) : null } : {}),
              discountPercent: payload.discountPercent,
              taxPercent: payload.taxPercent,
              freightAmount: payload.freightAmount,
@@ -400,14 +572,23 @@ export async function createSalesDocument(type: SalesDocumentType, payload: Sale
            select: { id: true },
          });

-  const detail = await getSalesDocumentById(type, created.id);
-  return detail ? { ok: true as const, document: detail } : { ok: false as const, reason: "Unable to load saved document." };
+    return created.id;
+  });
+
+  const detail = await getDocumentDetailOrNull(type, createdId);
+  if (!detail) {
+    return { ok: false as const, reason: "Unable to load saved document." };
+  }
+
+  await createRevision(type, createdId, detail, payload.revisionReason?.trim() || "Initial issue", userId);
+  const refreshed = await getDocumentDetailOrNull(type, createdId);
+  return refreshed ? { ok: true as const, document: refreshed } : { ok: false as const, reason: "Unable to load saved document." };
 }

-export async function updateSalesDocument(type: SalesDocumentType, documentId: string, payload: SalesDocumentInput) {
+export async function updateSalesDocument(type: SalesDocumentType, documentId: string, payload: SalesDocumentInput, userId?: string) {
  const existing = await documentConfig[type].findUnique({
    where: { id: documentId },
-    select: { id: true },
+    select: { id: true, approvedAt: true },
  });

  if (!existing) {
@@ -439,6 +620,8 @@ export async function updateSalesDocument(type: SalesDocumentType, documentId: s
      taxPercent: payload.taxPercent,
      freightAmount: payload.freightAmount,
      notes: payload.notes,
+      approvedAt: payload.status === "APPROVED" ? existing.approvedAt ?? new Date() : null,
+      approvedById: payload.status === "APPROVED" ? userId ?? null : null,
      lines: {
        deleteMany: {},
        create: validatedLines.lines,
@@ -447,14 +630,20 @@ export async function updateSalesDocument(type: SalesDocumentType, documentId: s
    select: { id: true },
  });

-  const detail = await getSalesDocumentById(type, documentId);
-  return detail ? { ok: true as const, document: detail } : { ok: false as const, reason: "Unable to load saved document." };
+  const detail = await getDocumentDetailOrNull(type, documentId);
+  if (!detail) {
+    return { ok: false as const, reason: "Unable to load saved document." };
+  }
+
+  await createRevision(type, documentId, detail, payload.revisionReason?.trim() || "Document edited", userId);
+  const refreshed = await getDocumentDetailOrNull(type, documentId);
+  return refreshed ? { ok: true as const, document: refreshed } : { ok: false as const, reason: "Unable to load saved document." };
 }

-export async function updateSalesDocumentStatus(type: SalesDocumentType, documentId: string, status: SalesDocumentStatus) {
+export async function updateSalesDocumentStatus(type: SalesDocumentType, documentId: string, status: SalesDocumentStatus, userId?: string) {
  const existing = await documentConfig[type].findUnique({
    where: { id: documentId },
-    select: { id: true },
+    select: { id: true, status: true, approvedAt: true },
  });

  if (!existing) {
@@ -463,18 +652,62 @@ export async function updateSalesDocumentStatus(type: SalesDocumentType, documen

  await documentConfig[type].update({
    where: { id: documentId },
-    data: { status },
+    data: {
+      status,
+      approvedAt: status === "APPROVED" ? existing.approvedAt ?? new Date() : null,
+      approvedById: status === "APPROVED" ? userId ?? null : null,
+    },
    select: { id: true },
  });

-  const detail = await getSalesDocumentById(type, documentId);
-  return detail ? { ok: true as const, document: detail } : { ok: false as const, reason: "Unable to load updated document." };
+  const detail = await getDocumentDetailOrNull(type, documentId);
+  if (!detail) {
+    return { ok: false as const, reason: "Unable to load updated document." };
+  }
+
+  await createRevision(type, documentId, detail, `Status changed to ${status}`, userId);
+  const refreshed = await getDocumentDetailOrNull(type, documentId);
+  return refreshed ? { ok: true as const, document: refreshed } : { ok: false as const, reason: "Unable to load updated document." };
 }

-export async function convertQuoteToSalesOrder(quoteId: string) {
+export async function approveSalesDocument(type: SalesDocumentType, documentId: string, userId?: string) {
+  const existing = await documentConfig[type].findUnique({
+    where: { id: documentId },
+    select: { id: true, status: true, approvedAt: true },
+  });
+
+  if (!existing) {
+    return { ok: false as const, reason: "Sales document was not found." };
+  }
+
+  if (existing.status === "CLOSED") {
+    return { ok: false as const, reason: "Closed sales documents cannot be approved." };
+  }
+
+  await documentConfig[type].update({
+    where: { id: documentId },
+    data: {
+      status: "APPROVED",
+      approvedAt: existing.approvedAt ?? new Date(),
+      approvedById: userId ?? null,
+    },
+    select: { id: true },
+  });
+
+  const detail = await getDocumentDetailOrNull(type, documentId);
+  if (!detail) {
+    return { ok: false as const, reason: "Unable to load approved document." };
+  }
+
+  await createRevision(type, documentId, detail, "Document approved", userId);
+  const refreshed = await getDocumentDetailOrNull(type, documentId);
+  return refreshed ? { ok: true as const, document: refreshed } : { ok: false as const, reason: "Unable to load approved document." };
+}
+
+export async function convertQuoteToSalesOrder(quoteId: string, userId?: string) {
  const quote = await documentConfig.QUOTE.findUnique({
    where: { id: quoteId },
-    include: buildInclude("QUOTE"),
+    include: buildInclude(),
  });

  if (!quote) {
@@ -484,7 +717,8 @@ export async function convertQuoteToSalesOrder(quoteId: string) {
  const mappedQuote = mapDocument(quote as SalesDocumentRecord);
  const nextOrderNumber = await nextDocumentNumber("ORDER");

-  const created = await documentConfig.ORDER.create({
+  const createdId = await prisma.$transaction(async (tx) => {
+    const created = await tx.salesOrder.create({
      data: {
        documentNumber: nextOrderNumber,
        customerId: mappedQuote.customerId,
@@ -508,8 +742,17 @@ export async function convertQuoteToSalesOrder(quoteId: string) {
      select: { id: true },
    });

-  const order = await getSalesDocumentById("ORDER", created.id);
-  return order ? { ok: true as const, document: order } : { ok: false as const, reason: "Unable to load converted sales order." };
+    return created.id;
+  });
+
+  const order = await getDocumentDetailOrNull("ORDER", createdId);
+  if (!order) {
+    return { ok: false as const, reason: "Unable to load converted sales order." };
+  }
+
+  await createRevision("ORDER", createdId, order, `Converted from quote ${mappedQuote.documentNumber}`, userId);
+  const refreshed = await getDocumentDetailOrNull("ORDER", createdId);
+  return refreshed ? { ok: true as const, document: refreshed } : { ok: false as const, reason: "Unable to load converted sales order." };
 }

 export async function getSalesDocumentPdfData(type: SalesDocumentType, documentId: string): Promise<SalesDocumentPdfData | null> {
--- a/shared/src/sales/types.ts
+++ b/shared/src/sales/types.ts
@@ -40,6 +40,9 @@ export interface SalesDocumentSummaryDto {
  customerId: string;
  customerName: string;
  status: SalesDocumentStatus;
+  approvedAt: string | null;
+  approvedByName: string | null;
+  currentRevisionNumber: number;
  subtotal: number;
  discountPercent: number;
  discountAmount: number;
@@ -58,6 +61,7 @@ export interface SalesDocumentDetailDto extends SalesDocumentSummaryDto {
  expiresAt: string | null;
  createdAt: string;
  lines: SalesLineDto[];
+  revisions: SalesDocumentRevisionDto[];
 }

 export interface SalesDocumentInput {
@@ -70,4 +74,13 @@ export interface SalesDocumentInput {
  freightAmount: number;
  notes: string;
  lines: SalesLineInput[];
+  revisionReason?: string;
+}
+
+export interface SalesDocumentRevisionDto {
+  id: string;
+  revisionNumber: number;
+  reason: string;
+  createdAt: string;
+  createdByName: string | null;
 }