toanhoang/ubi-dan-itam
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add Assignment validation + CRUD (src/lib/assignments.ts)

Browse Source 
createAssignment() enforces the XOR (assetItemId/licenseId) at the Zod
layer and the AssetItem.status/License.seatsUsed business rules inside a
single prisma.$transaction(), using atomic WHERE-guarded updateMany() calls
(not plain read-then-write) to close the seat-overbooking and
double-assignment race conditions flagged for License by code-reviewer.
returnAssignment() reverses those side-effects the same way and closes the
double-return race with the same pattern.
This commit is contained in:
toanhoang
2026-08-02 21:19:28 -04:00
parent 07b01cd707
commit a72b8dbbbe
1 changed files with 409 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/lib/assignments.ts
+409
View File
@@ -0,0 +1,409 @@
import { z } from "zod";
import { Prisma } from "@prisma/client";
import { prisma } from "./prisma";
export interface AssignmentRecord {
id: string;
employee_id: string;
asset_item_id: string | null;
license_id: string | null;
assigned_at: string;
returned_at: string | null;
signed_at: string | null;
created_at: string;
}
// assignedAt/returnedAt/signedAt are all deliberately NOT accepted from the
// client at creation time — same precedent as AssetItem.status always
// starting "in_stock" and License.seatsUsed always starting 0:
// assignedAt is a system-set "moment of assignment" timestamp
// (Prisma's @default(now()) on Assignment.assignedAt), returnedAt must be
// null on creation (an Assignment cannot be created already-returned — that
// would make no sense given the seat/status side-effects below), and
// signedAt (marking handover paperwork as signed) is not wired to any
// endpoint in this task at all — see feature-implementer report's "Out of
// scope" section. It stays null until a future "mark as signed" operation
// is built.
export interface CreateAssignmentInput {
employeeId: string;
assetItemId?: string | null;
licenseId?: string | null;
}
export type ValidationResult =
| { ok: true; value: CreateAssignmentInput }
| { ok: false; error: string };
// Mirrors src/lib/purchase-orders.ts's dateString helper — accepts any
// string Date.parse() can handle and transforms it into a Date for Prisma.
function dateString(message: string) {
return z
.string({ required_error: message, invalid_type_error: message })
.refine((value) => !Number.isNaN(Date.parse(value)), { message })
.transform((value) => new Date(value));
}
const createAssignmentSchema = z
.object({
// FK to Employee — only a UUID *format* check here, whether it
// references a real employee is left to Prisma's own FK constraint at
// insert time (see createAssignment()'s P2003 handling below). Mirrors
// src/lib/requests.ts's employee_id handling.
employeeId: z
.string({ required_error: "employeeId is required and must be a valid UUID string" })
.uuid("employeeId is required and must be a valid UUID string"),
// Exactly one of assetItemId/licenseId must be set — see the .refine()
// below for the XOR check. Unlike other nullable FKs in this codebase
// (e.g. AssetItem.purchaseOrderId), whether these reference a real row
// is NOT deferred entirely to Prisma's insert-time FK constraint —
// createAssignment() needs to read the referenced row anyway (to check
// AssetItem.status / License.seatsUsed business rules), so existence is
// checked explicitly inside the transaction instead. Only format
// validation happens here at the Zod layer.
assetItemId: z
.string({ invalid_type_error: "assetItemId must be a valid UUID string" })
.uuid("assetItemId must be a valid UUID string")
.optional()
.nullable(),
licenseId: z
.string({ invalid_type_error: "licenseId must be a valid UUID string" })
.uuid("licenseId must be a valid UUID string")
.optional()
.nullable(),
})
.refine(
(value) => {
const hasAssetItem = value.assetItemId !== undefined && value.assetItemId !== null;
const hasLicense = value.licenseId !== undefined && value.licenseId !== null;
// XOR: exactly one of the two must be set.
return hasAssetItem !== hasLicense;
},
{
message: "Exactly one of assetItemId or licenseId must be set (not both, not neither)",
// Attach the error to both fields so it surfaces regardless of which
// one the caller looks at first — mirrors
// src/lib/purchase-orders.ts's receivedAt/receivedById co-nullability
// refine, which attaches to a single path for the same reason.
path: ["assetItemId"],
}
);
/**
* Validates raw (untyped) assignment-creation input. employeeId must be a
* valid UUID string. Exactly one of assetItemId/licenseId must be a valid
* UUID string (XOR — both set or both unset is rejected). assignedAt,
* returnedAt, and signedAt are not accepted here — see CreateAssignmentInput's
* doc comment for why.
*/
export function validateCreateAssignmentInput(input: {
employeeId?: unknown;
assetItemId?: unknown;
licenseId?: unknown;
}): ValidationResult {
const result = createAssignmentSchema.safeParse(input);
if (!result.success) {
const message = result.error.issues[0]?.message ?? "Invalid input";
return { ok: false, error: message };
}
return { ok: true, value: result.data };
}
const returnAssignmentSchema = z.object({
// Optional — defaults to "now" at the time returnAssignment() runs if not
// provided (mirrors Assignment.assignedAt's own default-now behavior at
// creation). Accepting an explicit value lets a caller backdate a return
// (e.g. recording a return that was physically handled yesterday but only
// entered into the system today) — same spirit as PurchaseOrder accepting
// an explicit receivedAt rather than always stamping "now".
returnedAt: dateString("returnedAt must be a valid date string").optional(),
});
export type ReturnValidationResult =
| { ok: true; value: { returnedAt?: Date } }
| { ok: false; error: string };
/**
* Validates raw (untyped) assignment-return input. returnedAt is optional
* but must be a valid date string if present.
*/
export function validateReturnAssignmentInput(input: {
returnedAt?: unknown;
}): ReturnValidationResult {
const result = returnAssignmentSchema.safeParse(input);
if (!result.success) {
const message = result.error.issues[0]?.message ?? "Invalid input";
return { ok: false, error: message };
}
return { ok: true, value: result.data };
}
function toRecord(row: {
id: string;
employeeId: string;
assetItemId: string | null;
licenseId: string | null;
assignedAt: Date;
returnedAt: Date | null;
signedAt: Date | null;
createdAt: Date;
}): AssignmentRecord {
return {
id: row.id,
employee_id: row.employeeId,
asset_item_id: row.assetItemId,
license_id: row.licenseId,
assigned_at: row.assignedAt.toISOString(),
returned_at: row.returnedAt ? row.returnedAt.toISOString() : null,
signed_at: row.signedAt ? row.signedAt.toISOString() : null,
created_at: row.createdAt.toISOString(),
};
}
// Internal error type used to carry a clean, already-user-facing message out
// of the `prisma.$transaction()` callback below, distinguishing
// application-level business-rule rejections (400) from unexpected/infra
// errors (rethrown as-is). Not exported — callers only ever see the
// {ok,error} result shape.
class AssignmentBusinessError extends Error {
constructor(message: string) {
super(message);
this.name = "AssignmentBusinessError";
}
}
class AssignmentNotFoundError extends Error {
constructor() {
super("Assignment not found");
this.name = "AssignmentNotFoundError";
}
}
export type CreateAssignmentResult =
| { ok: true; value: AssignmentRecord }
| { ok: false; error: string };
/**
* Creates an Assignment (assigns an AssetItem or a License seat to an
* Employee), enforcing every business rule from docs/
* asset-license-management.md's "## Assignment (chốt 2026-08-02)" section
* inside a single `prisma.$transaction()`:
*
* - AssetItem branch: rejects if the AssetItem doesn't exist, rejects if its
* current status isn't "in_stock" (stakeholder-confirmed precondition —
* see the doc's "chốt 2026-08-02 (2)" note), rejects if there's already an
* ACTIVE Assignment (returnedAt IS NULL) for it (explicit
* belt-and-suspenders invariant per the doc, on top of the status check),
* then atomically flips AssetItem.status to "assigned".
* - License branch: rejects if the License doesn't exist, rejects if
* seatsUsed >= seatsTotal (no overbooking), then atomically increments
* seatsUsed by 1.
*
* Race-condition note (read this before touching the transaction body):
* both branches use a two-step "read for validation, then conditional
* `updateMany` with a WHERE guard" pattern instead of a plain read-then-write
* (`findUnique` then `update`). The WHERE-guarded `updateMany` — e.g.
* `updateMany({ where: { id, status: "in_stock" }, data: { status:
* "assigned" } })` — is the actual race-closing mechanism: Postgres
* evaluates and applies that as a single atomic UPDATE statement, taking a
* row lock for its duration. Two concurrent transactions racing on the same
* AssetItem/License row serialize on that lock — the first to commit wins,
* and the second's WHERE clause is re-evaluated against the now-committed
* row and no longer matches, so its `updateMany` returns `count: 0`, which
* this function treats as a "lost the race" rejection. This is why the
* `findUnique` calls right before each `updateMany` are NOT the
* race-closing check by themselves (there's a real TOCTOU gap between a
* `findUnique` and a later `update` in isolation) — they only exist to
* produce a specific, friendly error message (not-found vs. wrong-status vs.
* no-seats) for the *common* (non-racing) case; the `updateMany`'s `count`
* is always re-checked afterwards and is what actually gets trusted.
* seatsTotal itself is read once via that same `findUnique` and reused in
* the `updateMany`'s WHERE clause (`seatsUsed: { lt: seatsTotal }`) — this
* is safe because nothing in this codebase ever mutates seatsTotal after
* creation (no update endpoint exists for it), so it can't go stale between
* the read and the write within the same transaction.
*
* The explicit "no existing active Assignment for this AssetItem" check
* (`tx.assignment.findFirst({ where: { assetItemId, returnedAt: null } })`)
* is intentionally layered BEFORE the atomic status update, as defense in
* depth against AssetItem.status/Assignment-row drift (e.g. manual DB
* intervention) — under normal operation this codebase always keeps
* `status === "assigned"` in exact sync with "has an active Assignment", so
* the atomic status-guarded `updateMany` above is what actually closes the
* concurrency race for the AssetItem branch; this check does not need its
* own atomic guard on top because the transaction's row lock (from the
* subsequent `updateMany`) is what makes the overall operation safe, not
* this read on its own.
*/
export async function createAssignment(
input: CreateAssignmentInput
): Promise<CreateAssignmentResult> {
try {
const created = await prisma.$transaction(async (tx) => {
if (input.assetItemId) {
const assetItem = await tx.assetItem.findUnique({ where: { id: input.assetItemId } });
if (!assetItem) {
throw new AssignmentBusinessError(
"assetItemId does not reference an existing asset item"
);
}
if (assetItem.status !== "in_stock") {
throw new AssignmentBusinessError(
`assetItemId refers to an AssetItem that is not in_stock (current status: ${assetItem.status})`
);
}
const existingActive = await tx.assignment.findFirst({
where: { assetItemId: input.assetItemId, returnedAt: null },
});
if (existingActive) {
throw new AssignmentBusinessError(
"assetItemId already has an active assignment (returnedAt IS NULL)"
);
}
// Atomic race-closing gate — see this function's doc comment.
const statusUpdate = await tx.assetItem.updateMany({
where: { id: input.assetItemId, status: "in_stock" },
data: { status: "assigned" },
});
if (statusUpdate.count === 0) {
throw new AssignmentBusinessError(
"assetItemId refers to an AssetItem that is not in_stock (lost a race to another concurrent assignment)"
);
}
}
if (input.licenseId) {
const license = await tx.license.findUnique({ where: { id: input.licenseId } });
if (!license) {
throw new AssignmentBusinessError("licenseId does not reference an existing license");
}
if (license.seatsUsed >= license.seatsTotal) {
throw new AssignmentBusinessError(
"licenseId has no seats remaining (seatsUsed >= seatsTotal)"
);
}
// Atomic race-closing gate — see this function's doc comment.
const seatUpdate = await tx.license.updateMany({
where: { id: input.licenseId, seatsUsed: { lt: license.seatsTotal } },
data: { seatsUsed: { increment: 1 } },
});
if (seatUpdate.count === 0) {
throw new AssignmentBusinessError(
"licenseId has no seats remaining (lost a race to another concurrent assignment)"
);
}
}
return tx.assignment.create({
data: {
employeeId: input.employeeId,
assetItemId: input.assetItemId ?? null,
licenseId: input.licenseId ?? null,
},
});
});
return { ok: true, value: toRecord(created) };
} catch (error) {
if (error instanceof AssignmentBusinessError) {
return { ok: false, error: error.message };
}
// Only employeeId can still fail with a raw FK violation here —
// assetItemId/licenseId existence is already fully resolved above
// (found-or-rejected before the transaction ever reaches
// tx.assignment.create()).
if (error instanceof Prisma.PrismaClientKnownRequestError && error.code === "P2003") {
return { ok: false, error: "employeeId does not reference an existing employee" };
}
throw error;
}
}
export async function listAssignments(): Promise<AssignmentRecord[]> {
const rows = await prisma.assignment.findMany({
orderBy: [{ createdAt: "desc" }, { id: "desc" }],
});
return rows.map(toRecord);
}
export type ReturnAssignmentResult =
| { ok: true; value: AssignmentRecord }
| { ok: false; status: 404 | 400; error: string };
/**
* Marks an Assignment as returned (sets returnedAt), and reverses its
* side-effects from createAssignment() inside the same transaction:
* - If assetItemId is set: flips AssetItem.status back to "in_stock" —
* always, regardless of any RMA/repair path (there isn't one built yet,
* per the task's instructions; see feature-implementer report).
* - If licenseId is set: atomically decrements License.seatsUsed by 1.
*
* Race-condition note: double-return is closed the same way as
* createAssignment()'s races — an atomic, WHERE-guarded `updateMany`
* (`where: { id, returnedAt: null }`) is the actual gate. Two concurrent
* PATCH-return calls against the same Assignment race on that row's UPDATE
* lock; only the first to commit gets `count: 1`, the second gets `count: 0`
* and is rejected as "already returned". The initial `findUnique` (used to
* read assetItemId/licenseId for the AssetItem/License side-effects, and to
* distinguish "not found" from "already returned" in the common case) is
* NOT itself the race-closing check, same caveat as createAssignment()'s
* doc comment. Decrementing seatsUsed does not need its own conditional
* `updateMany` guard the way incrementing did on the assign side — a bare
* `{ decrement: 1 }` is a single atomic UPDATE with no upper bound to
* enforce (unlike assign's seatsUsed < seatsTotal check), so a plain
* `update()` is race-safe on its own here.
*/
export async function returnAssignment(
id: string,
input: { returnedAt?: Date }
): Promise<ReturnAssignmentResult> {
try {
const updated = await prisma.$transaction(async (tx) => {
const assignment = await tx.assignment.findUnique({ where: { id } });
if (!assignment) {
throw new AssignmentNotFoundError();
}
const returnedAt = input.returnedAt ?? new Date();
// Atomic race-closing gate — see this function's doc comment. Also
// doubles as the "already returned" rejection in the non-racing case,
// since `assignment.returnedAt !== null` implies this WHERE clause
// won't match either.
const claim = await tx.assignment.updateMany({
where: { id, returnedAt: null },
data: { returnedAt },
});
if (claim.count === 0) {
throw new AssignmentBusinessError("Assignment has already been returned");
}
if (assignment.assetItemId) {
await tx.assetItem.update({
where: { id: assignment.assetItemId },
data: { status: "in_stock" },
});
}
if (assignment.licenseId) {
await tx.license.update({
where: { id: assignment.licenseId },
data: { seatsUsed: { decrement: 1 } },
});
}
return tx.assignment.findUniqueOrThrow({ where: { id } });
});
return { ok: true, value: toRecord(updated) };
} catch (error) {
if (error instanceof AssignmentNotFoundError) {
return { ok: false, status: 404, error: "Assignment not found" };
}
if (error instanceof AssignmentBusinessError) {
return { ok: false, status: 400, error: error.message };
}
throw error;
}
}