ADDED: new add notes feature for orders backend and frontend

.github/pull_request_template.md

@@ -5,6 +5,7 @@ Describe problem and user or business impact.
 ## Ticket / Assignment
 
 - Ticket:
+- Assignment:
 
 ## What changed
 
@@ -17,6 +18,7 @@ Describe problem and user or business impact.
 List exact commands and manual checks.
 
 ```bash
+bun run check
 bun run test
 bun run build:web
 ```

.gitignore

@@ -8,4 +8,3 @@ bun.lock
 *.sqlite-wal
 dist
 coverage
-pi-session*

AGENTS.md

@@ -1,9 +1,5 @@
 # Typescript Full Stack App Agent
 
-## Coding Conventions
-- Before planning any code plan, check the `CONTRIBUTING.md` file in the root directory of the project to understand and apply coding conventions for this project
-- Instead of reading and parsing the `CONTRIBUTING.md` every time, cache the findings of `CONTRIBUTING.md` and refer to this cache'd file whenever checking the conventions is required
-
 ## Output Rules
 
 ### Response Style
@@ -180,3 +176,4 @@ Skip `discover_context` for narrow tasks with explicit file targets.
 ### Boundaries
 - Recon is read-only unless user requested implementation.
 - Do not treat scout output as complete when evidence suggests missing files.
+

CONTRIBUTING.md

@@ -28,6 +28,7 @@ bun run dev:web
 Common checks:
 
 ```bash
+bun run check
 bun run test
 bun run build:web
 ```

apps/api/src/db/init-db.ts

@@ -21,6 +21,7 @@ function resetLegacySchema(sqlite: Database) {
     DROP TABLE IF EXISTS sessions;
     DROP TABLE IF EXISTS audit_events;
     DROP TABLE IF EXISTS refunds;
+    DROP TABLE IF EXISTS order_notes;
     DROP TABLE IF EXISTS order_items;
     DROP TABLE IF EXISTS orders;
     DROP TABLE IF EXISTS inventory;
@@ -90,7 +91,6 @@ export function initializeDatabase(sqlite: Database) {
       customer_id TEXT NOT NULL REFERENCES users(id),
       shipping_address_id TEXT NOT NULL REFERENCES addresses(id),
       status TEXT NOT NULL,
-      notes TEXT,
       created_at TEXT NOT NULL,
       updated_at TEXT NOT NULL
     );
@@ -103,6 +103,14 @@ export function initializeDatabase(sqlite: Database) {
       unit_price_cents INTEGER NOT NULL
     );
 
+    CREATE TABLE IF NOT EXISTS order_notes (
+      id TEXT PRIMARY KEY,
+      order_id TEXT NOT NULL REFERENCES orders(id),
+      body TEXT NOT NULL,
+      author_user_id TEXT NOT NULL REFERENCES users(id),
+      created_at TEXT NOT NULL
+    );
+
     CREATE TABLE IF NOT EXISTS refunds (
       id TEXT PRIMARY KEY,
       order_id TEXT NOT NULL REFERENCES orders(id),
@@ -120,8 +128,4 @@ export function initializeDatabase(sqlite: Database) {
       created_at TEXT NOT NULL
     );
   `);
-
-  if (!columnExists(sqlite, "orders", "notes")) {
-    sqlite.exec("ALTER TABLE orders ADD COLUMN notes TEXT");
-  }
 }

apps/api/src/db/schema/orders.ts

@@ -9,7 +9,6 @@ export const orders = sqliteTable("orders", {
   customerId: text("customer_id").notNull().references(() => users.id),
   shippingAddressId: text("shipping_address_id").notNull().references(() => addresses.id),
   status: text("status").notNull(),
-  notes: text("notes"),
   createdAt: text("created_at").notNull(),
   updatedAt: text("updated_at").notNull()
 });
@@ -21,3 +20,11 @@ export const orderItems = sqliteTable("order_items", {
   quantity: integer("quantity").notNull(),
   unitPriceCents: integer("unit_price_cents").notNull()
 });
+
+export const orderNotes = sqliteTable("order_notes", {
+  id: text("id").primaryKey(),
+  orderId: text("order_id").notNull().references(() => orders.id),
+  body: text("body").notNull(),
+  authorUserId: text("author_user_id").notNull().references(() => users.id),
+  createdAt: text("created_at").notNull()
+});

apps/api/src/orders/add-order-note.ts

@@ -0,0 +1,29 @@
+import type { DatabaseContext } from "../db/database";
+import { findOrderDetail, insertOrderNote } from "./order-repository";
+
+export async function addOrderNote(
+  context: DatabaseContext,
+  input: {
+    orderId: string;
+    authorUserId: string;
+    body: string;
+  }
+) {
+  if (!input.body.trim() || input.body.length >= 2000) {
+    return { statusCode: 400, message: "Note must be non-empty and less than 2000 characters." } as const;
+  }
+
+  const order = await findOrderDetail(context, input.orderId);
+
+  if (!order) {
+    return { statusCode: 404, message: "Order not found." } as const;
+  }
+
+  const note = await insertOrderNote(context, input);
+
+  if (!note) {
+    return { statusCode: 404, message: "Author not found." } as const;
+  }
+
+  return { statusCode: 200, note } as const;
+}

apps/api/src/orders/order-notes-assignment-2.test.ts

@@ -1,106 +0,0 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import type { AppWithContext } from "../app";
-import { buildApp } from "../app";
-import { createUser } from "../users/user-repository";
-
-let app: AppWithContext;
-let employeeCookie = "";
-let customerCookie = "";
-
-function firstHeader(value: string | string[] | undefined): string {
-  return Array.isArray(value) ? value[0] ?? "" : value ?? "";
-}
-
-async function login(username: string) {
-  const response = await app.inject({ method: "POST", url: "/api/login", payload: { username } });
-  return firstHeader(response.headers["set-cookie"]);
-}
-
-beforeEach(async () => {
-  app = await buildApp(":memory:");
-
-  await createUser(app.dbContext, {
-    username: "dev-employee",
-    name: "Dev Employee",
-    email: "dev.employee@example.com",
-    role: "employee"
-  });
-
-  employeeCookie = await login("dev-employee");
-  customerCookie = await login("john-smith");
-});
-
-afterEach(async () => {
-  await app.close();
-});
-
-describe("assignment 2 internal order notes", () => {
-  test("allows employee users to attach notes to an order", async () => {
-    const response = await app.inject({
-      method: "POST",
-      url: "/api/orders/order_1/notes",
-      headers: { cookie: employeeCookie },
-      payload: { notes: "Follow up with warehouse before shipping." }
-    });
-
-    const order = response.json();
-
-    expect(response.statusCode).toBe(200);
-    expect(order.orderNumber).toBe("ORD-1001");
-    expect(order.notes).toBe("Follow up with warehouse before shipping.");
-    expect(order.items).toHaveLength(2);
-  });
-
-  test("returns persisted notes when the order is viewed later", async () => {
-    const updateResponse = await app.inject({
-      method: "POST",
-      url: "/api/orders/order_1/notes",
-      headers: { cookie: employeeCookie },
-      payload: { notes: "Customer requested gift receipt." }
-    });
-
-    expect(updateResponse.statusCode).toBe(200);
-
-    const detailResponse = await app.inject({
-      method: "GET",
-      url: "/api/orders/order_1",
-      headers: { cookie: employeeCookie }
-    });
-
-    expect(detailResponse.statusCode).toBe(200);
-    expect(detailResponse.json().notes).toBe("Customer requested gift receipt.");
-  });
-
-  test("rejects customer users when attaching notes", async () => {
-    const response = await app.inject({
-      method: "POST",
-      url: "/api/orders/order_1/notes",
-      headers: { cookie: customerCookie },
-      payload: { notes: "Customer should not be able to add this." }
-    });
-
-    expect(response.statusCode).toBe(403);
-  });
-
-  test("rejects empty notes", async () => {
-    const response = await app.inject({
-      method: "POST",
-      url: "/api/orders/order_1/notes",
-      headers: { cookie: employeeCookie },
-      payload: { notes: "   " }
-    });
-
-    expect(response.statusCode).toBe(400);
-  });
-
-  test("rejects notes beyond the accepted length limit", async () => {
-    const response = await app.inject({
-      method: "POST",
-      url: "/api/orders/order_1/notes",
-      headers: { cookie: employeeCookie },
-      payload: { notes: "x".repeat(1001) }
-    });
-
-    expect(response.statusCode).toBe(400);
-  });
-});

apps/api/src/orders/order-quantity-assignment-3.test.ts

@@ -1,98 +0,0 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import type { AppWithContext } from "../app";
-import { buildApp } from "../app";
-import { createUser } from "../users/user-repository";
-import { findOrderDetail, listOrderAuditEvents, updateOrderStatus } from "./order-repository";
-
-let app: AppWithContext;
-let employeeCookie = "";
-
-function firstHeader(value: string | string[] | undefined) {
-  return (Array.isArray(value) ? value[0] : value) ?? "";
-}
-
-async function login(username: string) {
-  const response = await app.inject({ method: "POST", url: "/api/login", payload: { username } });
-  return firstHeader(response.headers["set-cookie"]);
-}
-
-beforeEach(async () => {
-  app = await buildApp(":memory:");
-
-  await createUser(app.dbContext, {
-    username: "dev-employee",
-    name: "Dev Employee",
-    email: "dev.employee@example.com",
-    role: "employee"
-  });
-
-  employeeCookie = await login("dev-employee");
-});
-
-afterEach(async () => {
-  await app.close();
-});
-
-describe("assignment 3 quantity validation", () => {
-  test("allows quantity changes for pending orders", async () => {
-    const response = await app.inject({
-      method: "POST",
-      url: "/api/orders/order_1/items/item_1/quantity",
-      headers: { cookie: employeeCookie },
-      payload: { quantity: 5 }
-    });
-
-    expect(response.statusCode).toBe(200);
-    expect(response.json().items.find((item: { id: string }) => item.id === "item_1")?.quantity).toBe(5);
-    const order = await findOrderDetail(app.dbContext, "order_1");
-    expect(order?.items.find((item) => item.id === "item_1")?.quantity).toBe(5);
-    const events = await listOrderAuditEvents(app.dbContext, "order_1");
-    expect(events.filter((event) => event.type === "order.item.quantity_changed")).toEqual([
-      expect.objectContaining({ actor: "dev-employee", message: "Updated item item_1 quantity to 5." })
-    ]);
-  });
-
-  for (const status of ["processing", "shipped", "cancelled", "refunded"] as const) {
-    test(`rejects quantity changes for ${status} orders without side effects`, async () => {
-      await updateOrderStatus(app.dbContext, "order_1", status, "2025-01-16T10:00:00.000Z");
-      const beforeOrder = await findOrderDetail(app.dbContext, "order_1");
-      const beforeEvents = await listOrderAuditEvents(app.dbContext, "order_1");
-
-      for (const payload of [{ quantity: 5 }, { quantity: 5, status: "pending" }]) {
-        const response = await app.inject({
-          method: "POST",
-          url: "/api/orders/order_1/items/item_1/quantity",
-          headers: { cookie: employeeCookie },
-          payload
-        });
-
-        expect(response.statusCode).toBe(400);
-        expect(response.json<{ message: string }>()).toEqual({ message: "Order items cannot be changed for this order status." });
-        expect(await findOrderDetail(app.dbContext, "order_1")).toEqual(beforeOrder);
-        expect(await listOrderAuditEvents(app.dbContext, "order_1")).toEqual(beforeEvents);
-      }
-    });
-  }
-
-  test("rejects quantity outside the allowed range", async () => {
-    const response = await app.inject({
-      method: "POST",
-      url: "/api/orders/order_1/items/item_1/quantity",
-      headers: { cookie: employeeCookie },
-      payload: { quantity: 0 }
-    });
-
-    expect(response.statusCode).toBe(400);
-  });
-
-  test("rejects quantity above effective inventory", async () => {
-    const response = await app.inject({
-      method: "POST",
-      url: "/api/orders/order_1/items/item_1/quantity",
-      headers: { cookie: employeeCookie },
-      payload: { quantity: 9 }
-    });
-
-    expect(response.statusCode).toBe(400);
-  });
-});

apps/api/src/orders/order-repository.ts

@@ -1,7 +1,7 @@
-import type { Address, AuditEvent, OrderDetail, OrderItemDetail, OrderSummary } from "@orderops/shared";
+import type { Address, AuditEvent, Note, OrderDetail, OrderItemDetail, OrderSummary } from "@orderops/shared";
 import { and, asc, desc, eq, inArray, or, sql } from "drizzle-orm";
 import type { DatabaseContext } from "../db/database";
-import { addresses, auditEvents, inventory, orderItems, orders, products, users } from "../db/schema";
+import { addresses, auditEvents, inventory, orderItems, orderNotes, orders, products, users } from "../db/schema";
 
 function toAddress(row: typeof addresses.$inferSelect): Address {
   return {
@@ -35,13 +35,13 @@ function toOrderItemDetail(row: {
 }
 
 export async function listOrderSummaries(context: DatabaseContext, query?: string) {
-  const search = query?.trim().toLowerCase();
+  const search = query?.trim();
 
   const filters = search
     ? or(
-        sql`instr(lower(${orders.orderNumber}), ${search}) > 0`,
+        sql`instr(${orders.orderNumber}, ${search}) > 0`,
-        sql`instr(lower(${users.name}), ${search}) > 0`,
+        sql`instr(${users.name}, ${search}) > 0`,
-        sql`instr(lower(${users.email}), ${search}) > 0`
+        sql`instr(${users.email}, ${search}) > 0`
       )
     : undefined;
 
@@ -92,23 +92,64 @@ export async function findOrderDetail(context: DatabaseContext, orderId: string)
     .where(eq(orderItems.orderId, orderId))
     .orderBy(asc(orderItems.id));
 
+  const notes = await context.db
+    .select({
+      id: orderNotes.id,
+      orderId: orderNotes.orderId,
+      body: orderNotes.body,
+      authorUserId: orderNotes.authorUserId,
+      authorName: users.name,
+      createdAt: orderNotes.createdAt
+    })
+    .from(orderNotes)
+    .innerJoin(users, eq(orderNotes.authorUserId, users.id))
+    .where(eq(orderNotes.orderId, orderId))
+    .orderBy(desc(orderNotes.createdAt));
+
   return {
     id: header.order.id,
     orderNumber: header.order.orderNumber,
     status: header.order.status as OrderDetail["status"],
     createdAt: header.order.createdAt,
     updatedAt: header.order.updatedAt,
-    notes: header.order.notes,
     customer: {
       id: header.customer.id,
       name: header.customer.name,
       email: header.customer.email
     },
     shippingAddress: toAddress(header.address),
-    items: itemRows.map(toOrderItemDetail)
+    items: itemRows.map(toOrderItemDetail),
+    notes
   } satisfies OrderDetail;
 }
 
+export async function insertOrderNote(
+  context: DatabaseContext,
+  input: {
+    orderId: string;
+    authorUserId: string;
+    body: string;
+  }
+) {
+  const [author] = await context.db.select({ name: users.name }).from(users).where(eq(users.id, input.authorUserId));
+
+  if (!author) {
+    return null;
+  }
+
+  const note = {
+    id: crypto.randomUUID(),
+    orderId: input.orderId,
+    body: input.body,
+    authorUserId: input.authorUserId,
+    createdAt: new Date().toISOString()
+  } satisfies typeof orderNotes.$inferInsert;
+
+  await context.db.insert(orderNotes).values(note);
+
+  return { ...note, authorName: author.name } satisfies Note;
+}
+
 export async function findOrderItemRecord(context: DatabaseContext, orderId: string, itemId: string) {
   const [row] = await context.db
     .select({ order: orders, item: orderItems, inventory })
@@ -124,10 +165,6 @@ export async function updateOrderItemQuantity(context: DatabaseContext, itemId:
   await context.db.update(orderItems).set({ quantity }).where(eq(orderItems.id, itemId));
 }
 
-export async function updateOrderNotes(context: DatabaseContext, orderId: string, notes: string) {
-  await context.db.update(orders).set({ notes }).where(eq(orders.id, orderId));
-}
-
 export async function updateOrderTimestamp(context: DatabaseContext, orderId: string, updatedAt: string) {
   await context.db.update(orders).set({ updatedAt }).where(eq(orders.id, orderId));
 }

apps/api/src/orders/order-routes.ts

@@ -2,11 +2,12 @@ import type { Address, AuthUser } from "@orderops/shared";
 import type { FastifyPluginAsync, FastifyRequest } from "fastify";
 import { requireEmployeeUser } from "../auth/current-user";
 import type { DatabaseContext } from "../db/database";
+import { addOrderNote } from "./add-order-note";
 import { cancelOrder } from "./cancel-order";
 import { getOrder } from "./get-order";
 import { listAuditEvents } from "./list-audit-events";
 import { listOrders } from "./list-orders";
-import { changeOrderItemQuantity, updateOrderNotes } from "./update-order-item";
+import { changeOrderItemQuantity } from "./update-order-item";
 import { changeShippingAddress } from "./update-shipping-address";
 
 interface OrderRouteOptions {
@@ -33,8 +34,8 @@ interface CancelBody {
   reason?: string;
 }
 
-interface NotesBody {
+interface NoteBody {
-  notes: string;
+  body: string;
 }
 
 type AuthenticatedRequest = FastifyRequest & { currentUser: AuthUser };
@@ -73,6 +74,31 @@ export const registerOrderRoutes: FastifyPluginAsync<OrderRouteOptions> = async
 
   app.get<{ Params: IdParams }>("/orders/:orderId/audit-events", async (request) => listAuditEvents(options.db, request.params.orderId));
 
+  app.post<{ Params: IdParams; Body: NoteBody }>("/orders/:orderId/notes", {
+    schema: {
+      body: {
+        type: "object",
+        required: ["body"],
+        properties: {
+          body: { type: "string", minLength: 1, maxLength: 1999 }
+        }
+      }
+    }
+  }, async (request, reply) => {
+    const currentUser = (request as AuthenticatedRequest).currentUser;
+    const result = await addOrderNote(options.db, {
+      orderId: request.params.orderId,
+      authorUserId: currentUser.id,
+      body: request.body.body
+    });
+
+    if (result.statusCode !== 200) {
+      return reply.code(result.statusCode).send({ message: result.message });
+    }
+
+    return result.note;
+  });
+
   app.post<{ Params: OrderItemParams; Body: QuantityBody }>("/orders/:orderId/items/:itemId/quantity", {
     schema: {
       body: {
@@ -99,31 +125,6 @@ export const registerOrderRoutes: FastifyPluginAsync<OrderRouteOptions> = async
     return result.order;
   });
 
-  app.post<{ Params: IdParams; Body: NotesBody }>("/orders/:orderId/notes", {
-    schema: {
-      body: {
-        type: "object",
-        required: ["notes"],
-        properties: {
-          notes: { type: "string", maxLength: 1000 }
-        }
-      }
-    }
-  }, async (request, reply) => {
-    const currentUser = (request as AuthenticatedRequest).currentUser;
-    const result = await updateOrderNotes(options.db, {
-      orderId: request.params.orderId,
-      notes: request.body.notes,
-      actor: currentUser.username
-    });
-
-    if (result.statusCode !== 200) {
-      return reply.code(result.statusCode).send({ message: result.message });
-    }
-
-    return result.order;
-  });
-
   app.post<{ Params: IdParams; Body: Address }>("/orders/:orderId/shipping-address", {
     schema: {
       body: {

apps/api/src/orders/order-status.ts

@@ -1,7 +1,7 @@
 import type { OrderStatus } from "@orderops/shared/order-status";
 
 export function canEditOrderItems(status: OrderStatus) {
-  return status === "pending";
+  return status === "pending" || status === "processing";
 }
 
 export function canEditShippingAddress(status: OrderStatus) {

apps/api/src/orders/orders-routes.test.ts

@@ -1,11 +1,15 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import type { Note, OrderDetail } from "@orderops/shared";
+import { eq } from "drizzle-orm";
 import type { AppWithContext } from "../app";
 import { buildApp } from "../app";
+import { orderNotes, users } from "../db/schema";
 import { createUser } from "../users/user-repository";
 
 let app: AppWithContext;
 let employeeCookie = "";
 let customerCookie = "";
+let employeeId = "";
 
 async function login(username: string) {
   const response = await app.inject({ method: "POST", url: "/api/login", payload: { username } });
@@ -15,13 +19,14 @@ async function login(username: string) {
 beforeEach(async () => {
   app = await buildApp(":memory:");
 
-  await createUser(app.dbContext, {
+  const employee = await createUser(app.dbContext, {
     username: "dev-employee",
     name: "Dev Employee",
     email: "dev.employee@example.com",
     role: "employee"
   });
 
+  employeeId = employee.id;
   employeeCookie = await login("dev-employee");
   customerCookie = await login("john-smith");
 });
@@ -30,6 +35,161 @@ afterEach(async () => {
   await app.close();
 });
 
+describe("order notes", () => {
+  async function createNote(orderId: string, body: string) {
+    const response = await app.inject({
+      method: "POST",
+      url: `/api/orders/${orderId}/notes`,
+      headers: { cookie: employeeCookie },
+      payload: { body }
+    });
+
+    expect(response.statusCode).toBe(200);
+    return response.json<Note>();
+  }
+
+  async function getNotes(orderId: string) {
+    const response = await app.inject({
+      method: "GET",
+      url: `/api/orders/${orderId}`,
+      headers: { cookie: employeeCookie }
+    });
+
+    expect(response.statusCode).toBe(200);
+    return response.json<OrderDetail>().notes;
+  }
+
+  test("creates a note and retrieves it with its order", async () => {
+    expect(await getNotes("order_1")).toEqual([]);
+    const startedAt = Date.now();
+    const note = await createNote("order_1", "Call the warehouse before shipping.");
+
+    expect(note.id).toBeTruthy();
+    expect(note.orderId).toBe("order_1");
+    expect(note.body).toBe("Call the warehouse before shipping.");
+    expect(note.authorUserId).toBe(employeeId);
+    expect(note.authorName).toBe("Dev Employee");
+    expect(Date.parse(note.createdAt)).toBeGreaterThanOrEqual(startedAt);
+    expect(Date.parse(note.createdAt)).toBeLessThanOrEqual(Date.now());
+    expect(await getNotes("order_1")).toEqual([note]);
+  });
+
+  test("resolves the author's current display name when retrieving notes", async () => {
+    const note = await createNote("order_1", "Waiting for confirmation.");
+    await app.dbContext.db.update(users).set({ name: "Updated Employee" }).where(eq(users.id, employeeId));
+
+    expect(await getNotes("order_1")).toEqual([{ ...note, authorName: "Updated Employee" }]);
+  });
+
+  test("uses session authorship instead of an author supplied in the payload", async () => {
+    const otherEmployee = await createUser(app.dbContext, {
+      username: "other-employee",
+      name: "Other Employee",
+      email: "other.employee@example.com",
+      role: "employee"
+    });
+    const response = await app.inject({
+      method: "POST",
+      url: "/api/orders/order_1/notes",
+      headers: { cookie: employeeCookie },
+      payload: { body: "Internal context", authorUserId: otherEmployee.id, authorName: otherEmployee.name }
+    });
+
+    expect(response.statusCode).toBe(200);
+    const note = response.json<Note>();
+    expect(note.authorUserId).toBe(employeeId);
+    expect(note.authorName).toBe("Dev Employee");
+    expect(await getNotes("order_1")).toEqual([note]);
+  });
+
+  test("rejects customers and anonymous users from adding or reading order notes", async () => {
+    const note = await createNote("order_1", "Employee-only context");
+
+    for (const access of [{ cookie: customerCookie, statusCode: 403 }, { cookie: "", statusCode: 401 }]) {
+      const headers = { cookie: access.cookie };
+      const createResponse = await app.inject({
+        method: "POST",
+        url: "/api/orders/order_1/notes",
+        headers,
+        payload: { body: "Unauthorized note" }
+      });
+      const readResponse = await app.inject({ method: "GET", url: "/api/orders/order_1", headers });
+
+      expect(createResponse.statusCode).toBe(access.statusCode);
+      expect(readResponse.statusCode).toBe(access.statusCode);
+      expect(readResponse.body).not.toContain(note.body);
+    }
+
+    expect(await getNotes("order_1")).toEqual([note]);
+  });
+
+  for (const { label, body } of [
+    { label: "empty", body: "" },
+    { label: "whitespace-only", body: " \n\t " },
+    { label: "2000-character", body: "x".repeat(2000) },
+    { label: "over-length", body: "x".repeat(2001) }
+  ]) {
+    test(`rejects ${label} notes without saving them`, async () => {
+      const response = await app.inject({
+        method: "POST",
+        url: "/api/orders/order_1/notes",
+        headers: { cookie: employeeCookie },
+        payload: { body }
+      });
+
+      expect(response.statusCode).toBe(400);
+      expect(await getNotes("order_1")).toEqual([]);
+    });
+  }
+
+  test("accepts a note just below the 2000-character limit", async () => {
+    const body = "x".repeat(1999);
+    const note = await createNote("order_1", body);
+
+    expect(note.body).toBe(body);
+    expect(await getNotes("order_1")).toEqual([note]);
+  });
+
+  test("returns not found when adding a note to a missing order", async () => {
+    const response = await app.inject({
+      method: "POST",
+      url: "/api/orders/missing-order/notes",
+      headers: { cookie: employeeCookie },
+      payload: { body: "Follow up" }
+    });
+
+    expect(response.statusCode).toBe(404);
+    expect(response.json<{ message: string }>()).toEqual({ message: "Order not found." });
+    expect(await app.dbContext.db.select().from(orderNotes)).toEqual([]);
+  });
+
+  test("returns notes newest first regardless of insertion order", async () => {
+    const middle = await createNote("order_1", "Middle note");
+    const newest = await createNote("order_1", "Newest note");
+    const oldest = await createNote("order_1", "Oldest note");
+
+    // Fixed timestamps keep ordering independent of clock resolution and test speed.
+    for (const [note, createdAt] of [
+      [middle, "2026-01-02T00:00:00.000Z"],
+      [newest, "2026-01-03T00:00:00.000Z"],
+      [oldest, "2026-01-01T00:00:00.000Z"]
+    ] as const) {
+      await app.dbContext.db.update(orderNotes).set({ createdAt }).where(eq(orderNotes.id, note.id));
+    }
+
+    expect((await getNotes("order_1")).map((note) => note.id)).toEqual([newest.id, middle.id, oldest.id]);
+  });
+
+  test("keeps notes isolated to their own orders", async () => {
+    const first = await createNote("order_1", "First order context");
+    const second = await createNote("order_2", "Second order context");
+
+    expect(await getNotes("order_1")).toEqual([first]);
+    expect(await getNotes("order_2")).toEqual([second]);
+    expect(await getNotes("order_3")).toEqual([]);
+  });
+});
+
 describe("order routes", () => {
   test("rejects customer access", async () => {
     const response = await app.inject({ method: "GET", url: "/api/orders", headers: { cookie: customerCookie } });

apps/api/src/orders/update-order-item.ts

@@ -1,6 +1,6 @@
 import type { DatabaseContext } from "../db/database";
 import { canEditOrderItems } from "./order-status";
-import { appendAuditEvent, findOrderDetail, findOrderItemRecord, updateOrderItemQuantity, updateOrderNotes as saveOrderNotes, updateOrderTimestamp } from "./order-repository";
+import { appendAuditEvent, findOrderDetail, findOrderItemRecord, updateOrderItemQuantity, updateOrderTimestamp } from "./order-repository";
 
 export async function changeOrderItemQuantity(
   context: DatabaseContext,
@@ -47,44 +47,3 @@ export async function changeOrderItemQuantity(
     order: await findOrderDetail(context, input.orderId)
   } as const;
 }
-
-export async function updateOrderNotes(
-  context: DatabaseContext,
-  input: {
-    orderId: string;
-    notes: string;
-    actor: string;
-  }
-) {
-  const order = await findOrderDetail(context, input.orderId);
-
-  if (!order) {
-    return { statusCode: 404, message: "Order not found." } as const;
-  }
-
-  const notes = input.notes.trim();
-
-  if (!notes) {
-    return { statusCode: 400, message: "Notes cannot be empty." } as const;
-  }
-
-  if (notes.length > 1000) {
-    return { statusCode: 400, message: "Notes must be 1000 characters or fewer." } as const;
-  }
-
-  const updatedAt = new Date().toISOString();
-  await saveOrderNotes(context, input.orderId, notes);
-  await updateOrderTimestamp(context, input.orderId, updatedAt);
-  await appendAuditEvent(context, {
-    orderId: input.orderId,
-    actor: input.actor,
-    type: "order.notes_updated",
-    message: "Updated internal order notes.",
-    createdAt: updatedAt
-  });
-
-  return {
-    statusCode: 200,
-    order: await findOrderDetail(context, input.orderId)
-  } as const;
-}

apps/web/src/orders/order-api.ts

@@ -1,4 +1,4 @@
-import type { Address, AuditEvent, OrderDetail, OrderSummary } from "@orderops/shared";
+import type { Address, AuditEvent, Note, OrderDetail, OrderSummary } from "@orderops/shared";
 import { apiRequest } from "../lib/api-client";
 
 export function listOrders(query: string) {
@@ -14,6 +14,13 @@ export function listAuditEvents(orderId: string) {
   return apiRequest<AuditEvent[]>(`/api/orders/${orderId}/audit-events`);
 }
 
+export function addOrderNote(orderId: string, body: string) {
+  return apiRequest<Note>(`/api/orders/${orderId}/notes`, {
+    method: "POST",
+    body: JSON.stringify({ body })
+  });
+}
+
 export function updateOrderItemQuantity(orderId: string, itemId: string, quantity: number) {
   return apiRequest<OrderDetail>(`/api/orders/${orderId}/items/${itemId}/quantity`, {
     method: "POST",
@@ -21,13 +28,6 @@ export function updateOrderItemQuantity(orderId: string, itemId: string, quantit
   });
 }
 
-export function updateOrderNotes(orderId: string, notes: string) {
-  return apiRequest<OrderDetail>(`/api/orders/${orderId}/notes`, {
-    method: "POST",
-    body: JSON.stringify({ notes })
-  });
-}
-
 export function updateShippingAddress(orderId: string, address: Address) {
   return apiRequest<OrderDetail>(`/api/orders/${orderId}/shipping-address`, {
     method: "POST",

apps/web/src/orders/order-detail-page.tsx

@@ -1,7 +1,7 @@
 import type { Address, AuditEvent, OrderDetail } from "@orderops/shared";
 import { AuditTimeline } from "./audit-timeline";
 import { OrderItemsPanel } from "./order-items-panel";
-import { OrderNotes } from "./order-notes";
+import { OrderNotesPanel } from "./order-notes-panel";
 import { OrderSummaryPanel } from "./order-summary";
 import { ShippingAddressForm } from "./shipping-address-form";
 
@@ -10,8 +10,8 @@ interface OrderDetailPageProps {
   auditEvents: AuditEvent[];
   onUpdateQuantity: (itemId: string, quantity: number) => Promise<void>;
   onSaveAddress: (address: Address) => Promise<void>;
-  onSaveNotes: (notes: string) => Promise<void>;
   onCancel: () => Promise<void>;
+  onAddNote: (body: string) => Promise<void>;
 }
 
 export function OrderDetailPage({
@@ -19,8 +19,8 @@ export function OrderDetailPage({
   auditEvents,
   onUpdateQuantity,
   onSaveAddress,
-  onSaveNotes,
+  onCancel,
-  onCancel
+  onAddNote
 }: OrderDetailPageProps) {
   return (
     <div className="space-y-4">
@@ -32,7 +32,7 @@ export function OrderDetailPage({
       </div>
       <OrderItemsPanel order={order} onUpdateQuantity={onUpdateQuantity} />
       <ShippingAddressForm order={order} onSave={onSaveAddress} />
-      <OrderNotes order={order} onSave={onSaveNotes} />
+      <OrderNotesPanel key={order.id} order={order} onAddNote={onAddNote} />
       <AuditTimeline events={auditEvents} />
     </div>
   );

apps/web/src/orders/order-notes-panel.tsx

@@ -0,0 +1,90 @@
+import { useState } from "react";
+import type { OrderDetail } from "@orderops/shared";
+
+interface OrderNotesPanelProps {
+  order: OrderDetail;
+  onAddNote: (body: string) => Promise<void>;
+}
+
+export function OrderNotesPanel({ order, onAddNote }: OrderNotesPanelProps) {
+  const [body, setBody] = useState("");
+  const [isPending, setIsPending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const notes = [...order.notes].sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt));
+
+  return (
+    <section className="rounded-xl border border-slate-200 bg-white p-4 shadow-sm">
+      <h3 className="mb-3 text-sm font-semibold text-slate-700">Internal notes</h3>
+      {notes.length ? (
+        <ul className="space-y-3">
+          {notes.map((note) => (
+            <li key={note.id} className="rounded-lg border border-slate-200 p-3">
+              <div className="text-xs text-slate-500">
+                Author: {note.authorName} {"\u00b7"} <time dateTime={note.createdAt}>{new Date(note.createdAt).toLocaleString()}</time>
+              </div>
+              <p className="mt-1 whitespace-pre-wrap [overflow-wrap:anywhere] text-sm text-slate-900">{note.body}</p>
+            </li>
+          ))}
+        </ul>
+      ) : (
+        <p className="text-sm text-slate-500">No internal notes yet.</p>
+      )}
+      <form
+        className="mt-4 space-y-3"
+        aria-busy={isPending}
+        onSubmit={async (event) => {
+          event.preventDefault();
+
+          if (isPending) {
+            return;
+          }
+
+          if (!body.trim() || body.length >= 2000) {
+            setError("Note must be non-empty and less than 2000 characters.");
+            return;
+          }
+
+          setIsPending(true);
+          setError(null);
+
+          try {
+            await onAddNote(body);
+            setBody("");
+          } catch (caught: unknown) {
+            setError(caught instanceof Error ? caught.message : "Failed to add note.");
+          } finally {
+            setIsPending(false);
+          }
+        }}
+      >
+        <label className="block text-sm text-slate-700">
+          <span className="mb-1 block">Add an internal note</span>
+          <textarea
+            className="w-full rounded-lg border border-slate-300 px-3 py-2 disabled:opacity-50"
+            rows={4}
+            maxLength={1999}
+            required
+            disabled={isPending}
+            value={body}
+            onChange={(event) => {
+              setBody(event.target.value);
+              setError(null);
+            }}
+          />
+        </label>
+        {error ? (
+          <div className="rounded-xl border border-red-200 bg-red-50 px-4 py-3 text-sm text-red-700" role="alert">
+            {error}
+          </div>
+        ) : null}
+        <button
+          className="rounded-md bg-slate-900 px-4 py-2 text-sm font-medium text-white disabled:cursor-not-allowed disabled:opacity-50"
+          type="submit"
+          disabled={isPending || !body.trim()}
+        >
+          {isPending ? "Adding note..." : "Add note"}
+        </button>
+      </form>
+    </section>
+  );
+}

apps/web/src/orders/order-notes.tsx

@@ -1,37 +0,0 @@
-import { useState } from "react";
-import type { OrderDetail } from "@orderops/shared";
-
-interface OrderNotesProps {
-  order: OrderDetail;
-  onSave: (notes: string) => Promise<void>;
-}
-
-export function OrderNotes({ order, onSave }: OrderNotesProps) {
-  const [notes, setNotes] = useState(order.notes ?? "");
-
-  return (
-    <section className="rounded-xl border border-slate-200 bg-white p-4 shadow-sm">
-      <h3 className="mb-3 text-sm font-semibold text-slate-700">Internal notes</h3>
-      <form
-        className="space-y-3"
-        onSubmit={async (event) => {
-          event.preventDefault();
-          await onSave(notes);
-        }}
-      >
-        <label className="block text-sm text-slate-700">
-          <span className="mb-1 block">Notes</span>
-          <textarea
-            className="w-full resize-none rounded-lg border border-slate-300 px-3 py-2"
-            rows={5}
-            value={notes}
-            onChange={(event) => setNotes(event.target.value)}
-          />
-        </label>
-        <button className="rounded-md bg-slate-900 px-4 py-2 text-sm font-medium text-white" type="submit">
-          Save notes
-        </button>
-      </form>
-    </section>
-  );
-}

apps/web/src/orders/order-page.tsx

@@ -2,7 +2,7 @@ import { useEffect, useState } from "react";
 import type { Address, AuditEvent, OrderDetail } from "@orderops/shared";
 import { Link, useParams } from "react-router-dom";
 import { Toast } from "../ui/toast";
-import { cancelOrder, getOrder, listAuditEvents, updateOrderItemQuantity, updateOrderNotes, updateShippingAddress } from "./order-api";
+import { addOrderNote, cancelOrder, getOrder, listAuditEvents, updateOrderItemQuantity, updateShippingAddress } from "./order-api";
 import { OrderDetailPage } from "./order-detail-page";
 
 interface ToastState {
@@ -72,6 +72,33 @@ export function OrderPage() {
     }
   }
 
+  async function handleAddNote(body: string) {
+    try {
+      if (!orderId) {
+        throw new Error("Order not found.");
+      }
+
+      setError(null);
+      await addOrderNote(orderId, body);
+    } catch (caught) {
+      setToast({
+        message: caught instanceof Error ? caught.message : "Failed to add note.",
+        variant: "error"
+      });
+      throw caught;
+    }
+
+    try {
+      await refreshOrder(orderId);
+      setToast({ message: "Note added.", variant: "success" });
+    } catch {
+      setToast({
+        message: "Note saved, but the page didn't refresh — reload to see it.",
+        variant: "error"
+      });
+    }
+  }
+
   return (
     <div className="space-y-4">
       <Link className="inline-flex text-sm font-medium text-blue-600 hover:text-blue-700" to="/orders">
@@ -86,8 +113,8 @@ export function OrderPage() {
           auditEvents={auditEvents}
           onUpdateQuantity={(itemId, quantity) => runAction(() => updateOrderItemQuantity(order.id, itemId, quantity), "Quantity saved.")}
           onSaveAddress={(address: Address) => runAction(() => updateShippingAddress(order.id, address), "Shipping address saved.")}
-          onSaveNotes={(notes) => runAction(() => updateOrderNotes(order.id, notes), "Notes saved.")}
           onCancel={() => runAction(() => cancelOrder(order.id), "Order cancelled.")}
+          onAddNote={handleAddNote}
         />
       ) : null}
     </div>

packages/shared/src/order-detail.ts

@@ -13,14 +13,23 @@ export interface OrderItemDetail {
   availableQuantity: number;
 }
 
+export interface Note {
+  id: string;
+  orderId: string;
+  body: string;
+  authorUserId: string;
+  authorName: string;
+  createdAt: string;
+}
+
 export interface OrderDetail {
   id: string;
   orderNumber: string;
   status: OrderStatus;
   createdAt: string;
   updatedAt: string;
-  notes: string | null;
   customer: CustomerSummary;
   shippingAddress: Address;
   items: OrderItemDetail[];
+  notes: Note[];
 }