fix:allow item quantity changes only for pending orders

Reviewed-on: #12

.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.
-

CONTRIBUTING.md

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

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

@@ -90,6 +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,
       created_at TEXT NOT NULL,
       updated_at TEXT NOT NULL
     );
@@ -119,4 +120,8 @@ 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,6 +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"),
   createdAt: text("created_at").notNull(),
   updatedAt: text("updated_at").notNull()
 });

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

@@ -0,0 +1,106 @@
+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

@@ -0,0 +1,91 @@
+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 = "";
+
+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);
+  });
+
+  test("rejects quantity changes for processing orders", async () => {
+    const response = await app.inject({
+      method: "POST",
+      url: "/api/orders/order_2/items/item_3/quantity",
+      headers: { cookie: employeeCookie },
+      payload: { quantity: 2 }
+    });
+
+    expect(response.statusCode).toBe(400);
+  });
+
+  test("rejects quantity changes for shipped orders", async () => {
+    const response = await app.inject({
+      method: "POST",
+      url: "/api/orders/order_3/items/item_4/quantity",
+      headers: { cookie: employeeCookie },
+      payload: { quantity: 1 }
+    });
+
+    expect(response.statusCode).toBe(400);
+  });
+
+  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

@@ -98,6 +98,7 @@ export async function findOrderDetail(context: DatabaseContext, orderId: string)
     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,
@@ -123,6 +124,10 @@ 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

@@ -6,7 +6,7 @@ import { cancelOrder } from "./cancel-order";
 import { getOrder } from "./get-order";
 import { listAuditEvents } from "./list-audit-events";
 import { listOrders } from "./list-orders";
-import { changeOrderItemQuantity } from "./update-order-item";
+import { changeOrderItemQuantity, updateOrderNotes } from "./update-order-item";
 import { changeShippingAddress } from "./update-shipping-address";
 
 interface OrderRouteOptions {
@@ -33,6 +33,10 @@ interface CancelBody {
   reason?: string;
 }
 
+interface NotesBody {
+  notes: string;
+}
+
 type AuthenticatedRequest = FastifyRequest & { currentUser: AuthUser };
 
 export const registerOrderRoutes: FastifyPluginAsync<OrderRouteOptions> = async (app, options) => {
@@ -95,6 +99,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", 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,8 +1,6 @@
 import type { OrderStatus } from "@orderops/shared/order-status";
 
-export function canEditOrderItems(status: OrderStatus) {
-  return status === "pending" || status === "processing";
-}
+export { canEditOrderItems } from "@orderops/shared/order-status";
 
 export function canEditShippingAddress(status: OrderStatus) {
   return status === "pending" || status === "processing";

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, updateOrderTimestamp } from "./order-repository";
+import { appendAuditEvent, findOrderDetail, findOrderItemRecord, updateOrderItemQuantity, updateOrderNotes as saveOrderNotes, updateOrderTimestamp } from "./order-repository";
 
 export async function changeOrderItemQuantity(
   context: DatabaseContext,
@@ -47,3 +47,44 @@ 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

@@ -21,6 +21,13 @@ 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,6 +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 { OrderSummaryPanel } from "./order-summary";
 import { ShippingAddressForm } from "./shipping-address-form";
 
@@ -9,6 +10,7 @@ interface OrderDetailPageProps {
   auditEvents: AuditEvent[];
   onUpdateQuantity: (itemId: string, quantity: number) => Promise<void>;
   onSaveAddress: (address: Address) => Promise<void>;
+  onSaveNotes: (notes: string) => Promise<void>;
   onCancel: () => Promise<void>;
 }
 
@@ -17,6 +19,7 @@ export function OrderDetailPage({
   auditEvents,
   onUpdateQuantity,
   onSaveAddress,
+  onSaveNotes,
   onCancel
 }: OrderDetailPageProps) {
   return (
@@ -29,6 +32,7 @@ export function OrderDetailPage({
       </div>
       <OrderItemsPanel order={order} onUpdateQuantity={onUpdateQuantity} />
       <ShippingAddressForm order={order} onSave={onSaveAddress} />
+      <OrderNotes order={order} onSave={onSaveNotes} />
       <AuditTimeline events={auditEvents} />
     </div>
   );

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

@@ -1,5 +1,5 @@
 import { useState } from "react";
-import type { OrderDetail } from "@orderops/shared";
+import { canEditOrderItems, type OrderDetail } from "@orderops/shared";
 
 interface OrderItemsPanelProps {
   order: OrderDetail;
@@ -9,10 +9,12 @@ interface OrderItemsPanelProps {
 function QuantityForm({
   itemId,
   quantity,
+  isEditable,
   onSave
 }: {
   itemId: string;
   quantity: number;
+  isEditable: boolean;
   onSave: (itemId: string, quantity: number) => Promise<void>;
 }) {
   const [value, setValue] = useState(String(quantity));
@@ -26,12 +28,17 @@ function QuantityForm({
       }}
     >
       <input
-        className="w-16 rounded-md border border-slate-300 px-2 py-1 text-sm"
+        className="w-16 rounded-md border border-slate-300 px-2 py-1 text-sm disabled:bg-slate-100 disabled:text-slate-500"
+        disabled={!isEditable}
         inputMode="numeric"
         value={value}
         onChange={(event) => setValue(event.target.value)}
       />
-      <button className="rounded-md bg-blue-600 px-3 py-1 text-sm font-medium text-white" type="submit">
+      <button
+        className="rounded-md bg-blue-600 px-3 py-1 text-sm font-medium text-white disabled:cursor-not-allowed disabled:bg-slate-300"
+        disabled={!isEditable}
+        type="submit"
+      >
         Save
       </button>
     </form>
@@ -39,9 +46,12 @@ function QuantityForm({
 }
 
 export function OrderItemsPanel({ order, onUpdateQuantity }: OrderItemsPanelProps) {
+  const isEditable = canEditOrderItems(order.status);
+
   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">Items</h3>
+      {isEditable ? null : <p className="mb-3 text-sm text-slate-500">Quantities can only be changed while the order is pending.</p>}
       <div className="space-y-3">
         {order.items.map((item) => (
           <div key={item.id} className="rounded-lg border border-slate-200 p-3">
@@ -51,7 +61,7 @@ export function OrderItemsPanel({ order, onUpdateQuantity }: OrderItemsPanelProp
                 <div className="text-sm text-slate-600">{item.sku}</div>
                 <div className="text-sm text-slate-500">Available: {item.availableQuantity}</div>
               </div>
-              <QuantityForm itemId={item.id} quantity={item.quantity} onSave={onUpdateQuantity} />
+              <QuantityForm itemId={item.id} quantity={item.quantity} isEditable={isEditable} onSave={onUpdateQuantity} />
             </div>
           </div>
         ))}

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

@@ -0,0 +1,37 @@
+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, updateShippingAddress } from "./order-api";
+import { cancelOrder, getOrder, listAuditEvents, updateOrderItemQuantity, updateOrderNotes, updateShippingAddress } from "./order-api";
 import { OrderDetailPage } from "./order-detail-page";
 
 interface ToastState {
@@ -86,6 +86,7 @@ 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.")}
         />
       ) : null}

packages/shared/src/order-detail.ts

@@ -19,6 +19,7 @@ export interface OrderDetail {
   status: OrderStatus;
   createdAt: string;
   updatedAt: string;
+  notes: string | null;
   customer: CustomerSummary;
   shippingAddress: Address;
   items: OrderItemDetail[];

packages/shared/src/order-status.ts

@@ -1,3 +1,9 @@
 export const orderStatuses = ["pending", "processing", "shipped", "cancelled", "refunded"] as const;
 
 export type OrderStatus = (typeof orderStatuses)[number];
+
+// Item quantities can only be adjusted before fulfillment starts. Shared so the UI
+// matches the API rule; the API stays the authoritative check.
+export function canEditOrderItems(status: OrderStatus) {
+  return status === "pending";
+}