feat(po): manager sets advance payment on approval (issue #92)
The approving Manager decides how much of the PO is paid first, via a 0–100% slider on the approval card (default 100% = full). The slider is convenience only — the resolved ABSOLUTE amount is stored on PurchaseOrder.suggestedAdvancePayment (Decimal(12,2), nullable). - schema + migration: add suggestedAdvancePayment (null = no explicit advance ⇒ full payment, preserves legacy behaviour). - approvePo(): accepts the amount, clamps to [0, totalAmount], persists it, records it on the APPROVED audit row. Set once at approval; never edited afterwards. - approval-actions.tsx: whole-percent slider showing the resolved ₹ amount + remaining balance; value sent with Approve / Approve-with-Remarks. - Accounts surface: payment queue + PO detail show the advance; it prefills the FIRST payment amount (only when nothing is paid yet and it is a true partial). Balance runs the normal PARTIALLY_PAID loop. - Not shown on the exported PO/invoice (po-export-layout untouched). - Tests: persist + audit metadata + clamp-to-total. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
dfefd86832
commit
99c928213b
11 changed files with 192 additions and 6 deletions
|
|
@ -106,6 +106,8 @@ Structured format: **`COMPANY/VESSEL/PO_ID/FY`** — e.g. `PMS/HNR1/9000/2024-25
|
|||
|
||||
When Accounts records a payment, a **compulsory payment date** is captured (`PurchaseOrder.paymentDate`) — the input defaults to today and rejects future dates (validated in `processPaymentSchema` and `markPaid`). There is also an editable **`poDate`** field; the exported PO "Date" shows `poDate ?? approvedAt ?? createdAt` (i.e. the approval date once approved, not creation).
|
||||
|
||||
**Advance payment (issue #92):** the approving Manager sets how much of the PO is paid first via a 0–100% slider on the approval card (`approval-actions.tsx`, default 100%). The slider is convenience only — the resolved **absolute amount** is stored on `PurchaseOrder.suggestedAdvancePayment` (`Decimal(12,2)`, nullable; null = no explicit advance ⇒ full payment). `approvePo()` clamps it to `[0, totalAmount]` and records it on the `APPROVED` audit row; it is **set once at approval and never edited after**. Accounts sees it on the payment queue + PO detail, and it **prefills the first payment's amount** (`payment-actions.tsx`, only when nothing is paid yet and the advance is a true partial); the balance then runs through the normal `PARTIALLY_PAID` loop. It does **not** appear on the exported PO/invoice.
|
||||
|
||||
### Vendors
|
||||
|
||||
`Vendor` carries `isVerified`, `gstin`, `pincode` + `latitude`/`longitude` (geocoded for vendor-distance sorting from a Site), and a `VendorContact[]` list. **Submitters can create vendors** (permission `create_vendor`) but they are created **unverified**; a vendor becomes verified when a PO is closed/paid with it, on import, or when a Manager/Accounts/Admin runs `verifyVendor`. Only `manage_vendors` holders may assign a `vendorId` (the formal verified code).
|
||||
|
|
|
|||
|
|
@ -3,6 +3,7 @@
|
|||
import { auth } from "@/auth";
|
||||
import { db } from "@/lib/db";
|
||||
import { canPerformAction } from "@/lib/po-state-machine";
|
||||
import { approvePoSchema } from "@/lib/validations/po";
|
||||
import { notify } from "@/lib/notifier";
|
||||
import { revalidatePath } from "next/cache";
|
||||
|
||||
|
|
@ -12,14 +13,21 @@ export async function approvePo({
|
|||
poId,
|
||||
note,
|
||||
withNote = false,
|
||||
suggestedAdvancePayment,
|
||||
}: {
|
||||
poId: string;
|
||||
note?: string;
|
||||
withNote?: boolean;
|
||||
// Absolute advance the Manager wants paid first (issue #92). Whole amount,
|
||||
// resolved from the approval slider client-side. Omitted ⇒ full payment.
|
||||
suggestedAdvancePayment?: number;
|
||||
}): Promise<ActionResult> {
|
||||
const session = await auth();
|
||||
if (!session?.user) return { error: "Unauthorized" };
|
||||
|
||||
const parsed = approvePoSchema.safeParse({ note, suggestedAdvancePayment });
|
||||
if (!parsed.success) return { error: parsed.error.errors[0]?.message ?? "Validation failed" };
|
||||
|
||||
const po = await db.purchaseOrder.findUnique({
|
||||
where: { id: poId },
|
||||
include: { submitter: true, lineItems: true },
|
||||
|
|
@ -35,17 +43,28 @@ export async function approvePo({
|
|||
return { error: "A vendor must be assigned before approving this PO." };
|
||||
}
|
||||
|
||||
// Resolve the advance: clamp to [0, total]. Undefined ⇒ no explicit advance
|
||||
// (full payment, current default behaviour). The slider always sends a value,
|
||||
// but a malformed/over-total amount is clamped rather than rejected.
|
||||
const total = Number(po.totalAmount);
|
||||
const advance =
|
||||
parsed.data.suggestedAdvancePayment === undefined
|
||||
? null
|
||||
: Math.min(Math.max(parsed.data.suggestedAdvancePayment, 0), total);
|
||||
|
||||
await db.purchaseOrder.update({
|
||||
where: { id: poId },
|
||||
data: {
|
||||
status: "MGR_APPROVED",
|
||||
approvedAt: new Date(),
|
||||
managerNote: note ?? null,
|
||||
suggestedAdvancePayment: advance,
|
||||
actions: {
|
||||
create: {
|
||||
actionType: withNote ? "APPROVED_WITH_NOTE" : "APPROVED",
|
||||
note: note ?? null,
|
||||
actorId: session.user.id,
|
||||
metadata: advance !== null ? { suggestedAdvancePayment: advance } : undefined,
|
||||
},
|
||||
},
|
||||
},
|
||||
|
|
|
|||
|
|
@ -3,21 +3,38 @@
|
|||
import { useState } from "react";
|
||||
import { useRouter } from "next/navigation";
|
||||
import { approvePo, rejectPo, requestEdits, requestVendorId } from "./actions";
|
||||
import { formatCurrency } from "@/lib/utils";
|
||||
import type { POStatus } from "@prisma/client";
|
||||
|
||||
// Resolve the slider percent (whole number) into an absolute advance amount.
|
||||
// 100% is the exact total (no rounding loss on paise); partial advances are
|
||||
// rounded to whole rupees — the slider is convenience, the amount is the record.
|
||||
function advanceAmount(total: number, percent: number): number {
|
||||
if (percent >= 100) return total;
|
||||
if (percent <= 0) return 0;
|
||||
return Math.round((total * percent) / 100);
|
||||
}
|
||||
|
||||
export function ApprovalActions({
|
||||
poId,
|
||||
poStatus,
|
||||
totalAmount = 0,
|
||||
currency = "INR",
|
||||
}: {
|
||||
poId: string;
|
||||
poStatus: POStatus;
|
||||
totalAmount?: number;
|
||||
currency?: string;
|
||||
}) {
|
||||
const router = useRouter();
|
||||
const [note, setNote] = useState("");
|
||||
const [advancePercent, setAdvancePercent] = useState(100);
|
||||
const [activeAction, setActiveAction] = useState<string | null>(null);
|
||||
const [pending, setPending] = useState<string | null>(null);
|
||||
const [error, setError] = useState("");
|
||||
|
||||
const advance = advanceAmount(totalAmount, advancePercent);
|
||||
|
||||
async function dispatch(action: string, requireNote = false) {
|
||||
if (requireNote && !note.trim()) {
|
||||
setError("A note is required for this action.");
|
||||
|
|
@ -26,8 +43,10 @@ export function ApprovalActions({
|
|||
setPending(action);
|
||||
setError("");
|
||||
let result: { ok: true } | { error: string } | undefined;
|
||||
if (action === "approve") result = await approvePo({ poId, note });
|
||||
else if (action === "approve_note") result = await approvePo({ poId, note, withNote: true });
|
||||
// Approvals carry the Manager's advance decision (resolved amount, not %).
|
||||
if (action === "approve") result = await approvePo({ poId, note, suggestedAdvancePayment: advance });
|
||||
else if (action === "approve_note")
|
||||
result = await approvePo({ poId, note, withNote: true, suggestedAdvancePayment: advance });
|
||||
else if (action === "reject") result = await rejectPo({ poId, note });
|
||||
else if (action === "request_edits") result = await requestEdits({ poId, note });
|
||||
else if (action === "request_vendor_id") result = await requestVendorId({ poId });
|
||||
|
|
@ -45,6 +64,37 @@ export function ApprovalActions({
|
|||
<div className="rounded-lg border border-neutral-200 bg-white p-4 md:p-6">
|
||||
<h3 className="text-base font-semibold text-neutral-900 mb-4">Decision</h3>
|
||||
|
||||
{/* Advance payment (issue #92) — Manager decides how much Accounts pays
|
||||
first. 100% = full payment; lower values seed the first part-payment. */}
|
||||
<div className="mb-5 rounded-lg border border-neutral-200 bg-neutral-50 p-3.5">
|
||||
<div className="flex items-center justify-between mb-2">
|
||||
<label htmlFor="advance-slider" className="text-sm font-medium text-neutral-700">
|
||||
Advance payment
|
||||
</label>
|
||||
<span className="text-sm font-semibold text-neutral-900 tabular-nums">
|
||||
{advancePercent}% · {formatCurrency(advance, currency)}
|
||||
</span>
|
||||
</div>
|
||||
<input
|
||||
id="advance-slider"
|
||||
type="range"
|
||||
min={0}
|
||||
max={100}
|
||||
step={1}
|
||||
value={advancePercent}
|
||||
onChange={(e) => setAdvancePercent(Number(e.target.value))}
|
||||
className="w-full accent-primary-600"
|
||||
/>
|
||||
<p className="mt-1.5 text-xs text-neutral-500">
|
||||
{advancePercent >= 100
|
||||
? "Full payment — Accounts will be prompted to pay the whole PO value."
|
||||
: `Accounts will be prompted to pay ${formatCurrency(advance, currency)} first; the balance of ${formatCurrency(
|
||||
Math.max(totalAmount - advance, 0),
|
||||
currency
|
||||
)} follows the usual part-payment flow.`}
|
||||
</p>
|
||||
</div>
|
||||
|
||||
{(activeAction === "reject" || activeAction === "request_edits" || activeAction === "approve_note") && (
|
||||
<div className="mb-4">
|
||||
<label className="block text-sm font-medium text-neutral-700 mb-1.5">
|
||||
|
|
|
|||
|
|
@ -103,7 +103,12 @@ export default async function ApprovalDetailPage({ params }: Props) {
|
|||
|
||||
<div className="mt-4 md:mt-6">
|
||||
{hasSignature ? (
|
||||
<ApprovalActions poId={po.id} poStatus={po.status} />
|
||||
<ApprovalActions
|
||||
poId={po.id}
|
||||
poStatus={po.status}
|
||||
totalAmount={Number(po.totalAmount)}
|
||||
currency={po.currency}
|
||||
/>
|
||||
) : (
|
||||
<div className="rounded-lg border border-warning-200 bg-warning-50 p-4 md:p-5 flex items-start gap-3">
|
||||
<span className="text-warning-500 text-xl leading-none mt-0.5">✎</span>
|
||||
|
|
|
|||
|
|
@ -98,12 +98,25 @@ export default async function PaymentsPage() {
|
|||
Paid {formatCurrency(Number(po.paidAmount), po.currency)} of {formatCurrency(Number(po.totalAmount), po.currency)}
|
||||
</span>
|
||||
)}
|
||||
{/* Manager's advance decision (issue #92) — shown until the first payment lands. */}
|
||||
{po.status === "SENT_FOR_PAYMENT" &&
|
||||
po.paidAmount == null &&
|
||||
po.suggestedAdvancePayment != null &&
|
||||
Number(po.suggestedAdvancePayment) < Number(po.totalAmount) && (
|
||||
<span className="text-xs text-primary-700">
|
||||
Advance requested: {formatCurrency(Number(po.suggestedAdvancePayment), po.currency)} of{" "}
|
||||
{formatCurrency(Number(po.totalAmount), po.currency)}
|
||||
</span>
|
||||
)}
|
||||
</div>
|
||||
<PaymentActions
|
||||
poId={po.id}
|
||||
poStatus={po.status}
|
||||
totalAmount={Number(po.totalAmount)}
|
||||
paidAmount={po.paidAmount != null ? Number(po.paidAmount) : 0}
|
||||
suggestedAdvancePayment={
|
||||
po.suggestedAdvancePayment != null ? Number(po.suggestedAdvancePayment) : null
|
||||
}
|
||||
/>
|
||||
</div>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -10,6 +10,9 @@ interface Props {
|
|||
poStatus: POStatus;
|
||||
totalAmount?: number;
|
||||
paidAmount?: number;
|
||||
// Manager's advance decision (issue #92) — absolute amount. Prefills the FIRST
|
||||
// payment's amount field; ignored once any payment has been recorded.
|
||||
suggestedAdvancePayment?: number | null;
|
||||
}
|
||||
|
||||
// Today's date as a local yyyy-mm-dd string (for <input type="date"> default + max)
|
||||
|
|
@ -19,15 +22,33 @@ function todayLocal(): string {
|
|||
return new Date(d.getTime() - off * 60_000).toISOString().slice(0, 10);
|
||||
}
|
||||
|
||||
export function PaymentActions({ poId, poStatus, totalAmount = 0, paidAmount = 0 }: Props) {
|
||||
export function PaymentActions({
|
||||
poId,
|
||||
poStatus,
|
||||
totalAmount = 0,
|
||||
paidAmount = 0,
|
||||
suggestedAdvancePayment = null,
|
||||
}: Props) {
|
||||
const router = useRouter();
|
||||
const remaining = totalAmount - paidAmount;
|
||||
|
||||
// Prefill the first payment with the Manager's advance, when it's a genuine
|
||||
// partial of the (untouched) total. Nothing paid yet ⇒ first payment; a full
|
||||
// (>= total) advance leaves the field blank so "Confirm Full Payment" is used.
|
||||
const advancePrefill =
|
||||
paidAmount === 0 &&
|
||||
suggestedAdvancePayment != null &&
|
||||
suggestedAdvancePayment > 0 &&
|
||||
suggestedAdvancePayment < remaining
|
||||
? String(suggestedAdvancePayment)
|
||||
: "";
|
||||
|
||||
const [ref, setRef] = useState("");
|
||||
const [amount, setAmount] = useState<string>("");
|
||||
const [amount, setAmount] = useState<string>(advancePrefill);
|
||||
const [paymentDate, setPaymentDate] = useState<string>(todayLocal());
|
||||
const [pending, setPending] = useState(false);
|
||||
const [error, setError] = useState("");
|
||||
|
||||
const remaining = totalAmount - paidAmount;
|
||||
const today = todayLocal();
|
||||
|
||||
async function handleProcessPayment() {
|
||||
|
|
@ -120,6 +141,11 @@ export function PaymentActions({ poId, poStatus, totalAmount = 0, paidAmount = 0
|
|||
className="w-full sm:w-36 rounded-lg border border-neutral-300 px-3 py-2 text-sm focus:border-primary-500 focus:outline-none focus:ring-2 focus:ring-primary-500/20"
|
||||
/>
|
||||
</div>
|
||||
{advancePrefill && (
|
||||
<span className="text-xs text-primary-700">
|
||||
Manager set an advance of {Number(suggestedAdvancePayment).toFixed(2)} — prefilled below; adjust if needed.
|
||||
</span>
|
||||
)}
|
||||
{error && <span className="text-xs text-danger-700">{error}</span>}
|
||||
<div className="flex gap-2 justify-end">
|
||||
{isPartialPayment && (
|
||||
|
|
|
|||
|
|
@ -25,6 +25,7 @@ type PoWithRelations = {
|
|||
paymentRef: string | null;
|
||||
paymentDate?: Date | null;
|
||||
paidAmount?: import("@prisma/client").Prisma.Decimal | null;
|
||||
suggestedAdvancePayment?: import("@prisma/client").Prisma.Decimal | null;
|
||||
piQuotationNo?: string | null;
|
||||
piQuotationDate?: Date | null;
|
||||
requisitionNo?: string | null;
|
||||
|
|
@ -290,6 +291,21 @@ export async function PoDetail({ po, currentUserId, currentRole, readOnly = fals
|
|||
</div>
|
||||
)}
|
||||
|
||||
{/* Manager's advance-payment decision (issue #92) — a partial advance set
|
||||
at approval. Shown to Accounts/Manager from approval through payment. */}
|
||||
{po.suggestedAdvancePayment != null &&
|
||||
Number(po.suggestedAdvancePayment) < Number(po.totalAmount) &&
|
||||
["MGR_APPROVED", "SENT_FOR_PAYMENT", "PARTIALLY_PAID"].includes(po.status) && (
|
||||
<div className="rounded-lg border border-primary-100 bg-primary-50 px-4 py-3">
|
||||
<p className="text-sm font-medium text-primary-700 mb-0.5">Advance payment requested</p>
|
||||
<p className="text-sm text-primary-700">
|
||||
Pay {formatCurrency(Number(po.suggestedAdvancePayment), po.currency)} first (of{" "}
|
||||
{formatCurrency(Number(po.totalAmount), po.currency)}). The balance follows the usual
|
||||
part-payment flow.
|
||||
</p>
|
||||
</div>
|
||||
)}
|
||||
|
||||
{/* Submitter changes banner — shown to managers when PO is resubmitted after edits */}
|
||||
{resubmitSnapshot &&
|
||||
po.status === "MGR_REVIEW" &&
|
||||
|
|
|
|||
|
|
@ -53,6 +53,13 @@ export const createPoSchema = z.object({
|
|||
|
||||
export const approvePoSchema = z.object({
|
||||
note: z.string().optional(),
|
||||
// Absolute advance amount the Manager wants paid first (issue #92). The UI
|
||||
// slider works in whole percent of totalAmount; the resolved amount is what we
|
||||
// persist. Validated against the PO total in the action. Omitted ⇒ full payment.
|
||||
suggestedAdvancePayment: z.coerce
|
||||
.number()
|
||||
.nonnegative("Advance payment cannot be negative")
|
||||
.optional(),
|
||||
});
|
||||
|
||||
export const rejectPoSchema = z.object({
|
||||
|
|
|
|||
|
|
@ -0,0 +1,2 @@
|
|||
-- AlterTable
|
||||
ALTER TABLE "PurchaseOrder" ADD COLUMN "suggestedAdvancePayment" DECIMAL(12,2);
|
||||
|
|
@ -512,6 +512,12 @@ model PurchaseOrder {
|
|||
paymentRef String?
|
||||
paymentDate DateTime?
|
||||
paidAmount Decimal? @db.Decimal(12, 2)
|
||||
// Advance the approving Manager wants paid first (absolute amount, not %).
|
||||
// The approval slider (0–100% of totalAmount) is convenience only — the
|
||||
// resolved amount is stored here. Null on legacy/pre-feature POs ⇒ no explicit
|
||||
// advance, so Accounts defaults to the full remaining balance. Set once at
|
||||
// approval and not edited afterwards (issue #92).
|
||||
suggestedAdvancePayment Decimal? @db.Decimal(12, 2)
|
||||
piQuotationNo String?
|
||||
piQuotationDate DateTime?
|
||||
requisitionNo String?
|
||||
|
|
|
|||
|
|
@ -119,6 +119,46 @@ describe("M-02 — approve PO", () => {
|
|||
});
|
||||
});
|
||||
|
||||
// ── #92: Advance payment decided at approval ─────────────────────────────────
|
||||
|
||||
describe("issue #92 — advance payment on approval", () => {
|
||||
it("persists the manager's advance amount and records it on the audit row", async () => {
|
||||
const poId = await createSubmittedPo(`${PREFIX}Advance`);
|
||||
vi.mocked(auth as unknown as () => Promise<unknown>).mockResolvedValue(makeSession(managerId, "MANAGER"));
|
||||
const before = await db.purchaseOrder.findUniqueOrThrow({ where: { id: poId } });
|
||||
const half = Math.round(Number(before.totalAmount) / 2);
|
||||
|
||||
const result = await approvePo({ poId, suggestedAdvancePayment: half });
|
||||
expect(result).toEqual({ ok: true });
|
||||
|
||||
const po = await db.purchaseOrder.findUniqueOrThrow({ where: { id: poId } });
|
||||
expect(po.status).toBe("MGR_APPROVED");
|
||||
expect(Number(po.suggestedAdvancePayment)).toBe(half);
|
||||
|
||||
const action = await db.pOAction.findFirst({ where: { poId, actionType: "APPROVED" } });
|
||||
expect((action?.metadata as { suggestedAdvancePayment?: number } | null)?.suggestedAdvancePayment).toBe(half);
|
||||
});
|
||||
|
||||
it("defaults to null (full payment) when no advance is provided", async () => {
|
||||
const poId = await createSubmittedPo(`${PREFIX}AdvanceNone`);
|
||||
vi.mocked(auth as unknown as () => Promise<unknown>).mockResolvedValue(makeSession(managerId, "MANAGER"));
|
||||
await approvePo({ poId });
|
||||
const po = await db.purchaseOrder.findUniqueOrThrow({ where: { id: poId } });
|
||||
expect(po.suggestedAdvancePayment).toBeNull();
|
||||
});
|
||||
|
||||
it("clamps an advance above the PO total down to the total", async () => {
|
||||
const poId = await createSubmittedPo(`${PREFIX}AdvanceClamp`);
|
||||
vi.mocked(auth as unknown as () => Promise<unknown>).mockResolvedValue(makeSession(managerId, "MANAGER"));
|
||||
const before = await db.purchaseOrder.findUniqueOrThrow({ where: { id: poId } });
|
||||
const total = Number(before.totalAmount);
|
||||
|
||||
await approvePo({ poId, suggestedAdvancePayment: total + 5000 });
|
||||
const po = await db.purchaseOrder.findUniqueOrThrow({ where: { id: poId } });
|
||||
expect(Number(po.suggestedAdvancePayment)).toBe(total);
|
||||
});
|
||||
});
|
||||
|
||||
// ── M-03: Reject ──────────────────────────────────────────────────────────────
|
||||
|
||||
describe("M-03 — reject PO", () => {
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue