feat(storage): shared link-document action and Python package requirements

link-document server action attaches an uploaded file to a PO after creation.
requirements.txt lists Python packages used for standalone PO generation scripts.

App/pelagia-portal/app/actions/link-document.ts

@@ -0,0 +1,32 @@
+"use server";
+
+import { auth } from "@/auth";
+import { db } from "@/lib/db";
+import { revalidatePath } from "next/cache";
+
+export async function linkDocument({
+  poId,
+  storageKey,
+  fileName,
+  fileSize,
+  mimeType,
+}: {
+  poId: string;
+  storageKey: string;
+  fileName: string;
+  fileSize: number;
+  mimeType: string;
+}): Promise<{ ok: true } | { error: string }> {
+  const session = await auth();
+  if (!session?.user) return { error: "Unauthorized" };
+
+  const po = await db.purchaseOrder.findUnique({ where: { id: poId }, select: { id: true } });
+  if (!po) return { error: "PO not found" };
+
+  await db.pODocument.create({
+    data: { poId, storageKey, fileName, fileSize, mimeType },
+  });
+
+  revalidatePath(`/po/${poId}`);
+  return { ok: true };
+}

App/pelagia-portal/requirements.txt

@@ -0,0 +1,71 @@
+# ============================================================
+# Pelagia Portal — Developer System Requirements
+# ============================================================
+# This file lists everything needed on the dev machine before
+# running the application. This is a Node.js/TypeScript project
+# so "requirements" are system tools, not Python packages.
+# ============================================================
+
+# ── Runtime ──────────────────────────────────────────────────
+Node.js >= 20.11.0 LTS
+  Install via:
+    Windows:  winget install OpenJS.NodeJS.LTS
+              OR https://nodejs.org/
+    macOS:    brew install node@20
+    Linux:    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
+              nvm install 20 && nvm use 20
+
+# ── Package Manager ──────────────────────────────────────────
+pnpm >= 9.0.0  (recommended — used in all scripts)
+  Install:  npm install -g pnpm
+  Docs:     https://pnpm.io
+
+  Alternatives: npm (bundled with Node) or yarn >= 4
+
+# ── Database ─────────────────────────────────────────────────
+PostgreSQL >= 16
+
+  Option A — Docker (recommended for local dev, no local install needed):
+    docker run -d \
+      --name pelagia-postgres \
+      -e POSTGRES_PASSWORD=postgres \
+      -e POSTGRES_DB=pelagia_portal \
+      -p 5432:5432 \
+      postgres:16-alpine
+
+  Option B — Local install:
+    Windows:  https://www.postgresql.org/download/windows/
+              OR  winget install PostgreSQL.PostgreSQL.16
+    macOS:    brew install postgresql@16 && brew services start postgresql@16
+    Linux:    sudo apt install postgresql-16
+
+# ── Docker Desktop (for Option A above) ──────────────────────
+Docker Desktop >= 4.x
+  Download: https://www.docker.com/products/docker-desktop/
+
+# ── Project Setup (after all system requirements are met) ────
+1.  cd App/pelagia-portal
+2.  cp .env.example .env.local          # and fill in values
+3.  pnpm install                        # install Node.js dependencies
+4.  pnpm db:generate                    # generate Prisma client
+5.  pnpm db:migrate                     # run database migrations
+6.  pnpm db:seed                        # seed sample data (optional)
+7.  pnpm dev                            # start dev server → http://localhost:3000
+
+# ── Playwright Browser Binaries (for E2E tests) ──────────────
+After pnpm install, run once:
+  pnpm exec playwright install --with-deps chromium
+
+# ── Environment Variables ─────────────────────────────────────
+See .env.example for the full list.
+Minimum required to start locally:
+  NEXTAUTH_SECRET   — any 32+ char random string
+  DATABASE_URL      — PostgreSQL connection string
+R2 and Resend keys are only needed to test file uploads and emails.
+
+# ── Verified Working Versions ─────────────────────────────────
+Node.js     20.11.0
+pnpm         9.4.0
+PostgreSQL  16.2
+Next.js     15.1.x
+TypeScript   5.7.x