# Vendor Bidding Flow & Super Admin Oversight Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Implement self-service vendor bidding with approval workflow and super admin oversight dashboard. **Architecture:** - Bid submission uses approval gate logic based on tender type + vendor verification + tender config - Super admin users with VENDOR role can toggle between admin and vendor views via context switch - Admin oversight via dedicated `/dashboard/vendor-oversight` page and per-tender bid management **Tech Stack:** Next.js 14, tRPC, Prisma, PostgreSQL, Tailwind CSS --- ## File Structure ``` Modified Files: - prisma/schema.prisma # Add bid fields, TenderNotice.autoApproveBids - src/server/routers/bid.router.ts # Add admin endpoints, approval logic - src/server/routers/auth.router.ts # Add getSession for dual-role check - src/components/layouts/header.tsx # Add context switch toggle - src/lib/permissions.ts # Add bid permissions - src/app/vendor-portal/layout.tsx # Allow super admin with vendor role New Files: - src/app/(dashboard)/vendor-oversight/page.tsx # Main oversight dashboard - src/app/(dashboard)/tender/[id]/bids/page.tsx # Per-tender bid management - src/components/bids/BidApprovalCard.tsx # Pending approval card - src/components/bids/BidStatusBadge.tsx # Status indicator - src/components/bids/BidComparisonTable.tsx # Side-by-side comparison - src/components/bids/VendorBidFilters.tsx # Admin filter bar - src/lib/bid-helpers.ts # Approval path determination ``` --- ## Task 1: Database Schema Updates **Files:** - Modify: `prisma/schema.prisma` - Run: `npx prisma db push` - [ ] **Step 1: Add new BidStatus enum values** ```prisma enum BidStatus { DRAFT PENDING_APPROVAL SUBMITTED WITHDRAWN APPROVED REJECTED } ``` - [ ] **Step 2: Add approval fields to BidSubmission model** ```prisma model BidSubmission { id String @id @default(cuid()) tenderId String vendorId String referenceNo String @unique status BidStatus @default(DRAFT) totalAmount Decimal? @db.Decimal(15, 2) submittedAt DateTime? approvedAt DateTime? approvedById String? rejectedAt DateTime? rejectedById String? rejectionReason String? createdAt DateTime @default(now()) updatedAt DateTime @updatedAt tender TenderNotice @relation(fields: [tenderId], references: [id]) vendor Vendor @relation(fields: [vendorId], references: [id]) approvedBy User? @relation("BidApprovals", fields: [approvedById], references: [id]) rejectedBy User? @relation("BidRejections", fields: [rejectedById], references: [id]) bidLineItems BidLineItem[] versions BidVersion[] @@unique([tenderId, vendorId]) } model User { // ... existing fields ... approvedBids BidSubmission[] @relation("BidApprovals") rejectedBids BidSubmission[] @relation("BidRejections") } ``` - [ ] **Step 3: Add autoApproveBids to TenderNotice** ```prisma model TenderNotice { // ... existing fields ... autoApproveBids Boolean @default(false) } ``` - [ ] **Step 4: Push schema to database** Run: `npx prisma db push` Expected: "The changes have been applied successfully" - [ ] **Step 5: Generate Prisma client** Run: `npx prisma generate` Expected: "Generated Prisma client" - [ ] **Step 6: Commit** ```bash git add prisma/schema.prisma git commit -m "feat: add bid approval fields and autoApproveBids to TenderNotice" ``` --- ## Task 2: Bid Approval Helper Logic **Files:** - Create: `src/lib/bid-helpers.ts` - Modify: `src/server/routers/bid.router.ts` - [ ] **Step 1: Create bid-helpers.ts with approval logic** ```typescript import type { PrismaClient } from "@prisma/generated/client"; import type { VendorVerificationStatus, TenderType, } from "@prisma/generated/client"; export type BidApprovalPath = "DIRECT" | "PENDING_APPROVAL"; export function determineApprovalPath( tenderType: TenderType, vendorVerification: VendorVerificationStatus, tenderAutoApprove: boolean, ): BidApprovalPath { if ( tenderType === "CATEGORY" && vendorVerification === "VERIFIED" && tenderAutoApprove ) { return "DIRECT"; } if (vendorVerification === "VERIFIED") { return "DIRECT"; } return "PENDING_APPROVAL"; } export async function getVendorIdByEmail( db: PrismaClient, email: string, ): Promise { const vendor = await db.vendor.findFirst({ where: { email } }); if (!vendor) { throw new Error("Vendor not found"); } return vendor.id; } ``` - [ ] **Step 2: Commit** ```bash git add src/lib/bid-helpers.ts git commit -m "feat: add bid approval path determination logic" ``` --- ## Task 3: Update Bid Submission Router **Files:** - Modify: `src/server/routers/bid.router.ts:1-304` - [ ] **Step 1: Update imports** ```typescript import { z } from "zod"; import { TRPCError } from "@trpc/server"; import { createTRPCRouter, protectedProcedure, adminProcedure, superAdminProcedure, } from "@/server/trpc"; import type { PrismaClient } from "@prisma/generated/client"; import { Prisma } from "@prisma/generated/client"; import { AuditService } from "@/server/services/audit.service"; import { determineApprovalPath, getVendorIdByEmail } from "@/lib/bid-helpers"; ``` - [ ] **Step 2: Update submit mutation to use approval logic** Replace the existing `submit` mutation body (lines 38-122) with: ```typescript .mutation(async ({ ctx, input }) => { let vendorId: string; let vendor; if (input.vendorId) { vendorId = input.vendorId; vendor = await ctx.db.vendor.findUnique({ where: { id: vendorId } }); } else { if (ctx.session.user.role !== "VENDOR" && ctx.session.user.role !== "SUPER_ADMIN") { throw new TRPCError({ code: "BAD_REQUEST", message: "vendorId is required for non-vendor users", }); } vendorId = await getVendorIdByEmail(ctx.db, ctx.session.user.email); vendor = await ctx.db.vendor.findFirst({ where: { email: ctx.session.user.email } }); } const tender = await ctx.db.tenderNotice.findUnique({ where: { id: input.tenderId }, }); if (!tender) { throw new TRPCError({ code: "NOT_FOUND", message: "Tender not found" }); } if (new Date() > tender.submissionDeadline) { throw new TRPCError({ code: "FORBIDDEN", message: "Submission deadline has passed", }); } const approvalPath = determineApprovalPath( tender.tenderType, vendor!.verificationStatus, tender.autoApproveBids ?? false ); const status = approvalPath === "DIRECT" ? "SUBMITTED" : "PENDING_APPROVAL"; const existing = await ctx.db.bidSubmission.findUnique({ where: { tenderId_vendorId: { tenderId: input.tenderId, vendorId: vendorId!, }, }, }); const count = await ctx.db.bidSubmission.count({ where: { tenderId: input.tenderId }, }); const referenceNo = `BID/${count + 1}`; const lineItems = input.lineItems.map((item) => ({ ...item, totalAmount: item.quotedRate * item.quantity, })); const totalAmount = lineItems.reduce((sum, i) => sum + i.totalAmount, 0); let result; if (existing) { await ctx.db.bidLineItem.deleteMany({ where: { submissionId: existing.id }, }); result = await ctx.db.bidSubmission.update({ where: { id: existing.id }, data: { status, submittedAt: new Date(), totalAmount, bidLineItems: { create: lineItems }, }, }); } else { result = await ctx.db.bidSubmission.create({ data: { tenderId: input.tenderId, vendorId: vendorId!, referenceNo, status, submittedAt: new Date(), totalAmount, bidLineItems: { create: lineItems }, }, }); } await AuditService.log({ userId: ctx.session.user.id, action: "SUBMIT", entityType: "BID_SUBMISSION", entityId: result.id, entityName: referenceNo, changes: [ { field: "tenderId", newValue: input.tenderId }, { field: "vendorId", newValue: vendorId }, { field: "totalAmount", newValue: totalAmount }, { field: "status", newValue: status }, ], }); return result; }), ``` - [ ] **Step 3: Add admin oversight endpoints at end of router** ```typescript getAllBids: superAdminProcedure .input( z.object({ status: z.enum(["PENDING_APPROVAL", "SUBMITTED", "APPROVED", "REJECTED", "DRAFT", "WITHDRAWN"]).optional(), tenderType: z.enum(["PROJECT", "CATEGORY"]).optional(), vendorId: z.string().optional(), fromDate: z.date().optional(), toDate: z.date().optional(), limit: z.number().min(1).max(100).default(20), offset: z.number().min(0).default(0), }), ) .query(async ({ ctx, input }) => { const where: any = {}; if (input.status) where.status = input.status; if (input.vendorId) where.vendorId = input.vendorId; if (input.fromDate || input.toDate) { where.submittedAt = {}; if (input.fromDate) where.submittedAt.gte = input.fromDate; if (input.toDate) where.submittedAt.lte = input.toDate; } if (input.tenderType) { where.tender = { tenderType: input.tenderType }; } return ctx.db.bidSubmission.findMany({ where, include: { vendor: true, tender: true, bidLineItems: { include: { item: true } }, }, take: input.limit, skip: input.offset, orderBy: { submittedAt: "desc" }, }); }), getPendingApprovals: superAdminProcedure.query(async ({ ctx }) => { return ctx.db.bidSubmission.findMany({ where: { status: "PENDING_APPROVAL" }, include: { vendor: true, tender: true, bidLineItems: { include: { item: true } }, }, orderBy: { submittedAt: "asc" }, }); }), approveBid: superAdminProcedure .input( z.object({ bidId: z.string(), notes: z.string().optional(), }), ) .mutation(async ({ ctx, input }) => { const bid = await ctx.db.bidSubmission.findUnique({ where: { id: input.bidId }, include: { tender: true, vendor: true }, }); if (!bid) { throw new TRPCError({ code: "NOT_FOUND", message: "Bid not found" }); } const result = await ctx.db.bidSubmission.update({ where: { id: input.bidId }, data: { status: "APPROVED", approvedAt: new Date(), approvedById: ctx.session.user.id, }, }); await AuditService.log({ userId: ctx.session.user.id, action: "APPROVE", entityType: "BID_SUBMISSION", entityId: input.bidId, entityName: bid.referenceNo, changes: [ { field: "status", oldValue: bid.status, newValue: "APPROVED" }, { field: "notes", newValue: input.notes }, ], }); return result; }), rejectBid: superAdminProcedure .input( z.object({ bidId: z.string(), reason: z.string(), }), ) .mutation(async ({ ctx, input }) => { const bid = await ctx.db.bidSubmission.findUnique({ where: { id: input.bidId }, }); if (!bid) { throw new TRPCError({ code: "NOT_FOUND", message: "Bid not found" }); } const result = await ctx.db.bidSubmission.update({ where: { id: input.bidId }, data: { status: "REJECTED", rejectedAt: new Date(), rejectedById: ctx.session.user.id, rejectionReason: input.reason, }, }); await AuditService.log({ userId: ctx.session.user.id, action: "REJECT", entityType: "BID_SUBMISSION", entityId: input.bidId, entityName: bid.referenceNo, changes: [ { field: "status", oldValue: bid.status, newValue: "REJECTED" }, { field: "reason", newValue: input.reason }, ], }); return result; }), adminWithdrawBid: superAdminProcedure .input( z.object({ bidId: z.string(), reason: z.string(), }), ) .mutation(async ({ ctx, input }) => { const bid = await ctx.db.bidSubmission.findUnique({ where: { id: input.bidId }, }); if (!bid) { throw new TRPCError({ code: "NOT_FOUND", message: "Bid not found" }); } const result = await ctx.db.bidSubmission.update({ where: { id: input.bidId }, data: { status: "WITHDRAWN", }, }); await AuditService.log({ userId: ctx.session.user.id, action: "WITHDRAW", entityType: "BID_SUBMISSION", entityId: input.bidId, entityName: bid.referenceNo, changes: [ { field: "status", oldValue: bid.status, newValue: "WITHDRAWN" }, { field: "reason", newValue: input.reason }, ], }); return result; }), getBidAnalytics: superAdminProcedure.query(async ({ ctx }) => { const [totalBids, pendingBids, approvedBids, rejectedBids, avgAmount] = await Promise.all([ ctx.db.bidSubmission.count(), ctx.db.bidSubmission.count({ where: { status: "PENDING_APPROVAL" } }), ctx.db.bidSubmission.count({ where: { status: "APPROVED" } }), ctx.db.bidSubmission.count({ where: { status: "REJECTED" } }), ctx.db.bidSubmission.aggregate({ _avg: { totalAmount: true }, where: { status: { in: ["SUBMITTED", "APPROVED"] } }, }), ]); return { totalBids, pendingBids, approvedBids, rejectedBids, avgBidAmount: avgAmount._avg.totalAmount ?? 0, }; }), ``` - [ ] **Step 4: Register new endpoints in \_app router** Check `src/server/routers/_app.ts` and ensure bidRouter is registered. - [ ] **Step 5: Commit** ```bash git add src/server/routers/bid.router.ts git commit -m "feat: add approval logic and admin oversight endpoints" ``` --- ## Task 4: Add Bid Permissions **Files:** - Modify: `src/lib/permissions.ts` - [ ] **Step 1: Add bid permissions** ```typescript type Permission = // ... existing permissions ... | "bids:read" // NEW | "bids:approve" // NEW | "bids:reject" // NEW | "bids:withdraw" // NEW | "bids:read:own" // NEW | "bids:edit:own"; // NEW ``` - [ ] **Step 2: Add to SUPER_ADMIN role** ```typescript const rolePermissions: Record = { SUPER_ADMIN: [ // ... existing permissions ... "bids:read", "bids:approve", "bids:reject", "bids:withdraw", ], // ... existing roles ... VENDOR: [ "tenders:read", "bids:submit", // NEW "bids:read:own", // NEW "bids:edit:own", // NEW ], }; ``` - [ ] **Step 3: Commit** ```bash git add src/lib/permissions.ts git commit -m "feat: add bid permissions for vendors and admins" ``` --- ## Task 5: Context Switch Toggle **Files:** - Modify: `src/components/layouts/header.tsx` - Modify: `src/app/vendor-portal/layout.tsx` - [ ] **Step 1: Create view mode context** Create `src/contexts/ViewModeContext.tsx`: ```typescript "use client"; import { createContext, useContext, useState, ReactNode } from "react"; type ViewMode = "admin" | "vendor"; interface ViewModeContextType { mode: ViewMode; setMode: (mode: ViewMode) => void; toggle: () => void; } const ViewModeContext = createContext(undefined); export function ViewModeProvider({ children }: { children: ReactNode }) { const [mode, setMode] = useState("admin"); const toggle = () => { setMode((prev) => (prev === "admin" ? "vendor" : "admin")); }; return ( {children} ); } export function useViewMode() { const context = useContext(ViewModeContext); if (!context) throw new Error("useViewMode must be used within ViewModeProvider"); return context; } ``` - [ ] **Step 2: Update header with context switch toggle** ```typescript "use client"; import { signOut } from "next-auth/react"; import { Button } from "@/components/ui/button"; import { trpc } from "@/trpc/client"; import { useViewMode } from "@/contexts/ViewModeContext"; import { useRouter } from "next/navigation"; export function Header() { const { data: session } = trpc.auth.getSession.useQuery(); const { mode, toggle } = useViewMode(); const router = useRouter(); const isVendorUser = session?.user?.role === "VENDOR" || (session?.user?.role === "SUPER_ADMIN" && hasVendorProfile); const handleToggle = () => { toggle(); if (mode === "admin") { router.push("/vendor-portal/tenders"); } else { router.push("/dashboard"); } }; return (

Tender Management System

{isVendorUser && ( )} {session?.user?.name} ({session?.user?.role})
); } ``` - [ ] **Step 3: Update vendor portal layout to allow super admin** Modify `src/app/vendor-portal/layout.tsx`: ```typescript export default async function VendorPortalLayout({ children, }: { children: React.ReactNode; }) { const session = await auth(); // Allow VENDOR role OR SUPER_ADMIN with vendor profile const canAccess = session?.user?.role === "VENDOR" || (session?.user?.role === "SUPER_ADMIN" && (await hasVendorProfile(session.user.email))); if (!canAccess) { redirect("/login"); } // ... rest unchanged } ``` - [ ] **Step 4: Add ViewModeProvider to root layout** Add to `src/app/layout.tsx`: ```typescript import { ViewModeProvider } from "@/contexts/ViewModeContext"; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ); } ``` - [ ] **Step 5: Commit** ```bash git add src/contexts/ViewModeContext.tsx src/components/layouts/header.tsx src/app/vendor-portal/layout.tsx src/app/layout.tsx git commit -m "feat: add vendor/admin context switch toggle" ``` --- ## Task 6: Admin Oversight Pages **Files:** - Create: `src/app/(dashboard)/vendor-oversight/page.tsx` - Create: `src/app/(dashboard)/tender/[id]/bids/page.tsx` - Create: `src/components/bids/BidStatusBadge.tsx` - Create: `src/components/bids/BidApprovalCard.tsx` - Create: `src/components/bids/BidComparisonTable.tsx` - Create: `src/components/bids/VendorBidFilters.tsx` - [ ] **Step 1: Create BidStatusBadge component** ```typescript // src/components/bids/BidStatusBadge.tsx import type { BidStatus } from "@prisma/generated/client"; interface BidStatusBadgeProps { status: BidStatus; } const statusConfig: Record = { DRAFT: { label: "Draft", className: "bg-gray-100 text-gray-800" }, PENDING_APPROVAL: { label: "Pending Approval", className: "bg-yellow-100 text-yellow-800" }, SUBMITTED: { label: "Submitted", className: "bg-blue-100 text-blue-800" }, APPROVED: { label: "Approved", className: "bg-green-100 text-green-800" }, REJECTED: { label: "Rejected", className: "bg-red-100 text-red-800" }, WITHDRAWN: { label: "Withdrawn", className: "bg-gray-100 text-gray-600" }, }; export function BidStatusBadge({ status }: BidStatusBadgeProps) { const config = statusConfig[status] ?? statusConfig.DRAFT; return ( {config.label} ); } ``` - [ ] **Step 2: Create BidApprovalCard component** ```typescript // src/components/bids/BidApprovalCard.tsx "use client"; import { trpc } from "@/trpc/client"; import { Button } from "@/components/ui/button"; import { BidStatusBadge } from "./BidStatusBadge"; import { useState } from "react"; interface BidApprovalCardProps { bid: { id: string; referenceNo: string; totalAmount: any; submittedAt: Date | null; vendor: { name: string; email: string }; tender: { title: string; referenceNo: string }; bidLineItems: { quantity: any; quotedRate: any }[]; }; } export function BidApprovalCard({ bid }: BidApprovalCardProps) { const utils = trpc.useUtils(); const [rejectReason, setRejectReason] = useState(""); const [showReject, setShowReject] = useState(false); const approve = trpc.bid.approveBid.useMutation({ onSuccess: () => utils.bid.getPendingApprovals.invalidate(), }); const reject = trpc.bid.rejectBid.useMutation({ onSuccess: () => utils.bid.getPendingApprovals.invalidate(), }); const handleApprove = () => { approve.mutate({ bidId: bid.id }); }; const handleReject = () => { if (!rejectReason.trim()) return; reject.mutate({ bidId: bid.id, reason: rejectReason }); }; return (

{bid.vendor.name}

{bid.vendor.email}

Tender: {bid.tender.title}

Bid Ref: {bid.referenceNo}

Amount: Rs. {Number(bid.totalAmount).toLocaleString()}

Submitted:{" "} {bid.submittedAt ? new Date(bid.submittedAt).toLocaleString() : "N/A"}

{!showReject ? (
) : (