add:internal order notes for employees

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.github/pull_request_template.md

@@ -5,7 +5,6 @@ Describe problem and user or business impact.
 ## Ticket / Assignment
 
 - Ticket:
-- Assignment:
 
 ## What changed
 
@@ -18,7 +17,6 @@ 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,3 +8,4 @@ bun.lock
 *.sqlite-wal
 dist
 coverage
+pi-session*

AGENTS.md

@@ -1,5 +1,9 @@
 # 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
@@ -176,4 +180,3 @@ 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.
-

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

@@ -90,7 +90,7 @@ 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 NOT NULL DEFAULT '',
+      notes TEXT,
       created_at TEXT NOT NULL,
       updated_at TEXT NOT NULL
     );
@@ -121,7 +121,8 @@ export function initializeDatabase(sqlite: Database) {
     );
   `);
 
-  if (tableExists(sqlite, "orders") && !columnExists(sqlite, "orders", "notes")) {
-    sqlite.exec(`ALTER TABLE orders ADD COLUMN notes TEXT NOT NULL DEFAULT ''`);
+  // Databases created before internal order notes existed keep their orders table, so add the column in place.
+  if (!columnExists(sqlite, "orders", "notes")) {
+    sqlite.exec("ALTER TABLE orders ADD COLUMN notes TEXT;");
   }
 }

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

@@ -9,7 +9,7 @@ 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").notNull().default(""),
+  notes: text("notes"),
   createdAt: text("created_at").notNull(),
   updatedAt: text("updated_at").notNull()
 });

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

@@ -35,13 +35,13 @@ function toOrderItemDetail(row: {
 }
 
 export async function listOrderSummaries(context: DatabaseContext, query?: string) {
-  const search = query?.trim();
+  const search = query?.trim().toLowerCase();
 
   const filters = search
     ? or(
-        sql`instr(lower(${orders.orderNumber}), lower(${search})) > 0`,
-        sql`instr(lower(${users.name}), lower(${search})) > 0`,
-        sql`instr(lower(${users.email}), lower(${search})) > 0`
+        sql`instr(lower(${orders.orderNumber}), ${search}) > 0`,
+        sql`instr(lower(${users.name}), ${search}) > 0`,
+        sql`instr(lower(${users.email}), ${search}) > 0`
       )
     : undefined;
 
@@ -96,7 +96,6 @@ export async function findOrderDetail(context: DatabaseContext, orderId: string)
     id: header.order.id,
     orderNumber: header.order.orderNumber,
     status: header.order.status as OrderDetail["status"],
-    notes: header.order.notes,
     createdAt: header.order.createdAt,
     updatedAt: header.order.updatedAt,
     customer: {
@@ -105,7 +104,8 @@ export async function findOrderDetail(context: DatabaseContext, orderId: string)
       email: header.customer.email
     },
     shippingAddress: toAddress(header.address),
-    items: itemRows.map(toOrderItemDetail)
+    items: itemRows.map(toOrderItemDetail),
+    notes: header.order.notes
   } satisfies OrderDetail;
 }
 

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

@@ -7,7 +7,7 @@ import { getOrder } from "./get-order";
 import { listAuditEvents } from "./list-audit-events";
 import { listOrders } from "./list-orders";
 import { changeOrderItemQuantity } from "./update-order-item";
-import { changeOrderNotes } from "./update-notes";
+import { changeOrderNotes } from "./update-order-notes";
 import { changeShippingAddress } from "./update-shipping-address";
 
 interface OrderRouteOptions {
@@ -30,14 +30,14 @@ interface QuantityBody {
   quantity: number;
 }
 
-interface NotesBody {
-  notes: string;
-}
-
 interface CancelBody {
   reason?: string;
 }
 
+interface NotesBody {
+  notes: string;
+}
+
 type AuthenticatedRequest = FastifyRequest & { currentUser: AuthUser };
 
 export const registerOrderRoutes: FastifyPluginAsync<OrderRouteOptions> = async (app, options) => {
@@ -100,31 +100,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" }
-        }
-      }
-    }
-  }, async (request, reply) => {
-    const currentUser = (request as AuthenticatedRequest).currentUser;
-    const result = await changeOrderNotes(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: {
@@ -164,6 +139,31 @@ 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" }
+        }
+      }
+    }
+  }, async (request, reply) => {
+    const currentUser = (request as AuthenticatedRequest).currentUser;
+    const result = await changeOrderNotes(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: CancelBody }>("/orders/:orderId/cancel", {
     schema: {
       body: {

apps/api/src/orders/order-search-assignment-1.test.ts

@@ -7,7 +7,7 @@ let app: AppWithContext;
 let employeeCookie = "";
 
 function firstHeader(value: string | string[] | undefined) {
-  return Array.isArray(value) ? (value[0] ?? "") : value ?? "";
+  return Array.isArray(value) ? value[0] : value ?? "";
 }
 
 async function login(username: string) {

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

@@ -1,8 +1,7 @@
+import { maxOrderNotesLength } from "@orderops/shared";
 import type { DatabaseContext } from "../db/database";
 import { appendAuditEvent, findOrderDetail, updateOrderNotes } from "./order-repository";
 
-export const NOTES_MAX_LENGTH = 1000;
-
 export async function changeOrderNotes(
   context: DatabaseContext,
   input: {
@@ -11,22 +10,22 @@ export async function changeOrderNotes(
     actor: string;
   }
 ) {
+  const notes = input.notes.trim();
+
+  if (!notes) {
+    return { statusCode: 400, message: "Notes cannot be empty." } as const;
+  }
+
+  if (notes.length > maxOrderNotesLength) {
+    return { statusCode: 400, message: `Notes cannot be longer than ${maxOrderNotesLength} characters.` } as const;
+  }
+
   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.length === 0) {
-    return { statusCode: 400, message: "Notes cannot be empty." } as const;
-  }
-
-  if (notes.length > NOTES_MAX_LENGTH) {
-    return { statusCode: 400, message: `Notes cannot exceed ${NOTES_MAX_LENGTH} characters.` } as const;
-  }
-
   const updatedAt = new Date().toISOString();
   await updateOrderNotes(context, input.orderId, notes, updatedAt);
   await appendAuditEvent(context, {

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 { OrderNotesPanel } from "./order-notes";
+import { OrderNotesPanel } from "./order-notes-panel";
 import { OrderSummaryPanel } from "./order-summary";
 import { ShippingAddressForm } from "./shipping-address-form";
 
@@ -25,7 +25,6 @@ export function OrderDetailPage({
   return (
     <div className="space-y-4">
       <OrderSummaryPanel order={order} />
-      <OrderNotesPanel notes={order.notes} onSave={onSaveNotes} />
       <div className="flex justify-end">
         <button className="rounded-md bg-red-600 px-4 py-2 text-sm font-medium text-white" onClick={() => void onCancel()} type="button">
           Cancel order
@@ -34,6 +33,7 @@ export function OrderDetailPage({
       <OrderItemsPanel order={order} onUpdateQuantity={onUpdateQuantity} />
       <ShippingAddressForm order={order} onSave={onSaveAddress} />
       <AuditTimeline events={auditEvents} />
+      <OrderNotesPanel order={order} onSave={onSaveNotes} />
     </div>
   );
 }

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

@@ -0,0 +1,42 @@
+import { useState } from "react";
+import { maxOrderNotesLength, type OrderDetail } from "@orderops/shared";
+
+interface OrderNotesPanelProps {
+  order: OrderDetail;
+  onSave: (notes: string) => Promise<void>;
+}
+
+export function OrderNotesPanel({ order, onSave }: OrderNotesPanelProps) {
+  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 for the OrderOps team</span>
+          <textarea
+            className="w-full rounded-lg border border-slate-300 px-3 py-2"
+            maxLength={maxOrderNotesLength}
+            rows={4}
+            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 disabled:opacity-50"
+          disabled={!notes.trim()}
+          type="submit"
+        >
+          Save notes
+        </button>
+      </form>
+    </section>
+  );
+}

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

@@ -1,60 +0,0 @@
-import { useState } from "react";
-
-export const NOTES_MAX_LENGTH = 1000;
-
-interface OrderNotesProps {
-  notes: string;
-  onSave: (notes: string) => Promise<void>;
-}
-
-export function OrderNotesPanel({ notes, onSave }: OrderNotesProps) {
-  const [draft, setDraft] = useState(notes);
-  const [isSaving, setIsSaving] = useState(false);
-  const trimmed = draft.trim();
-  const isDisabled = isSaving || trimmed.length === 0 || trimmed === notes;
-
-  async function handleSave() {
-    if (isDisabled) {
-      return;
-    }
-
-    setIsSaving(true);
-    try {
-      await onSave(trimmed);
-    } finally {
-      setIsSaving(false);
-    }
-  }
-
-  return (
-    <section className="rounded-xl border border-slate-200 bg-white p-4 shadow-sm">
-      <div className="mb-3 flex items-center justify-between">
-        <h3 className="text-sm font-semibold text-slate-700">Internal notes</h3>
-        <span className="text-xs text-slate-500">{draft.length}/{NOTES_MAX_LENGTH}</span>
-      </div>
-      {notes ? (
-        <p className="mb-3 whitespace-pre-wrap text-sm text-slate-700">{notes}</p>
-      ) : (
-        <p className="mb-3 text-sm text-slate-400">No internal notes yet. Add context for teammates following up on this order.</p>
-      )}
-      <textarea
-        className="w-full resize-y rounded-lg border border-slate-300 px-3 py-2 text-sm text-slate-900 focus:border-blue-500 focus:outline-none"
-        maxLength={NOTES_MAX_LENGTH}
-        onChange={(event) => setDraft(event.target.value)}
-        placeholder="Add internal notes..."
-        rows={3}
-        value={draft}
-      />
-      <div className="mt-3 flex justify-end">
-        <button
-          className="rounded-md bg-blue-600 px-4 py-2 text-sm font-medium text-white disabled:cursor-not-allowed disabled:opacity-50"
-          disabled={isDisabled}
-          onClick={() => void handleSave()}
-          type="button"
-        >
-          {isSaving ? "Saving..." : "Save notes"}
-        </button>
-      </div>
-    </section>
-  );
-}

packages/shared/src/order-detail.ts

@@ -3,6 +3,9 @@ import type { CustomerSummary } from "./customer";
 import type { Money } from "./money";
 import type { OrderStatus } from "./order-status";
 
+// Internal order notes are capped so they stay a short follow-up context, not a document.
+export const maxOrderNotesLength = 1000;
+
 export interface OrderItemDetail {
   id: string;
   productId: string;
@@ -17,10 +20,10 @@ export interface OrderDetail {
   id: string;
   orderNumber: string;
   status: OrderStatus;
-  notes: string;
   createdAt: string;
   updatedAt: string;
   customer: CustomerSummary;
   shippingAddress: Address;
   items: OrderItemDetail[];
+  notes: string | null;
 }