Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
@@ -0,0 +1,111 @@
|
||||
import { CatalogError, type CatalogErrorDefinition, type JsonValue } from "./errors.js";
|
||||
|
||||
/**
|
||||
* Mass-action guard (M005 / Pflichtenheft A.10.1).
|
||||
*
|
||||
* A bulk action that touches many records is "never armed directly": the user
|
||||
* first sees a preview with the concrete impact ("würde 1.400 Personen betreffen,
|
||||
* hier die ersten 5: …") and must explicitly confirm. This module is the generic,
|
||||
* pure cross-cutting guard for that handshake; the caller computes the affected
|
||||
* count + sample (a query) and threads the decision into its action.
|
||||
*/
|
||||
|
||||
export type MassActionPolicy = {
|
||||
/** Above this affected count, explicit user confirmation is required (A.10.1). */
|
||||
confirmThreshold: number;
|
||||
/** Above this affected count the action is blocked entirely. Omit for no hard cap. */
|
||||
hardLimit?: number;
|
||||
};
|
||||
|
||||
export type MassActionPreview<T = unknown> = {
|
||||
readonly affected: number;
|
||||
readonly sample: readonly T[];
|
||||
readonly requiresConfirmation: boolean;
|
||||
readonly exceedsHardLimit: boolean;
|
||||
};
|
||||
|
||||
export type MassActionInput = {
|
||||
/** Number of records the action would affect right now. */
|
||||
affected: number;
|
||||
policy: MassActionPolicy;
|
||||
/**
|
||||
* The affected count the user saw and confirmed. Must equal the current
|
||||
* `affected` to proceed past the confirmation threshold — this rejects
|
||||
* scope-drift (confirming a small preview, then applying to a larger set).
|
||||
*/
|
||||
confirmedAffected?: number;
|
||||
};
|
||||
|
||||
export type MassActionDecision =
|
||||
| { readonly status: "allowed"; readonly affected: number; readonly confirmed: boolean }
|
||||
| { readonly status: "requires_confirmation"; readonly affected: number; readonly confirmThreshold: number }
|
||||
| { readonly status: "blocked"; readonly reason: "exceeds_hard_limit"; readonly affected: number; readonly hardLimit: number };
|
||||
|
||||
export const massActionErrors = {
|
||||
confirmationRequired: {
|
||||
code: "foundation.mass_action_confirmation_required",
|
||||
status: 409,
|
||||
i18nKey: "foundation.errors.massActionConfirmationRequired",
|
||||
},
|
||||
exceedsLimit: {
|
||||
code: "foundation.mass_action_exceeds_limit",
|
||||
status: 422,
|
||||
i18nKey: "foundation.errors.massActionExceedsLimit",
|
||||
},
|
||||
} satisfies Record<string, CatalogErrorDefinition>;
|
||||
|
||||
const DEFAULT_SAMPLE_SIZE = 5;
|
||||
|
||||
/**
|
||||
* Build the preview shown to the user before a mass action: the affected count,
|
||||
* a bounded sample of the affected items, and whether confirmation / a hard cap
|
||||
* applies. The caller supplies the already-fetched `items`.
|
||||
*/
|
||||
export function previewMassAction<T>(input: {
|
||||
affected: number;
|
||||
items?: readonly T[];
|
||||
sampleSize?: number;
|
||||
policy: MassActionPolicy;
|
||||
}): MassActionPreview<T> {
|
||||
const sampleSize = input.sampleSize ?? DEFAULT_SAMPLE_SIZE;
|
||||
const sample = (input.items ?? []).slice(0, Math.max(0, sampleSize));
|
||||
const exceedsHardLimit = typeof input.policy.hardLimit === "number" && input.affected > input.policy.hardLimit;
|
||||
const requiresConfirmation = !exceedsHardLimit && input.affected > input.policy.confirmThreshold;
|
||||
return { affected: input.affected, sample, requiresConfirmation, exceedsHardLimit };
|
||||
}
|
||||
|
||||
/** Pure policy decision for a mass action. */
|
||||
export function evaluateMassAction(input: MassActionInput): MassActionDecision {
|
||||
const { affected, policy, confirmedAffected } = input;
|
||||
if (typeof policy.hardLimit === "number" && affected > policy.hardLimit) {
|
||||
return { status: "blocked", reason: "exceeds_hard_limit", affected, hardLimit: policy.hardLimit };
|
||||
}
|
||||
if (affected <= policy.confirmThreshold) {
|
||||
return { status: "allowed", affected, confirmed: false };
|
||||
}
|
||||
if (confirmedAffected === affected) {
|
||||
return { status: "allowed", affected, confirmed: true };
|
||||
}
|
||||
return { status: "requires_confirmation", affected, confirmThreshold: policy.confirmThreshold };
|
||||
}
|
||||
|
||||
/**
|
||||
* Assert a mass action may proceed, throwing a `CatalogError` otherwise:
|
||||
* `exceedsLimit` (422) when over the hard cap, `confirmationRequired` (409) when
|
||||
* the user has not confirmed the current affected count. Returns the decision on
|
||||
* success.
|
||||
*/
|
||||
export function assertMassActionAllowed(input: MassActionInput, details?: Record<string, JsonValue>): MassActionDecision {
|
||||
const decision = evaluateMassAction(input);
|
||||
if (decision.status === "blocked") {
|
||||
throw new CatalogError(massActionErrors.exceedsLimit, { affected: decision.affected, hardLimit: decision.hardLimit, ...details });
|
||||
}
|
||||
if (decision.status === "requires_confirmation") {
|
||||
throw new CatalogError(massActionErrors.confirmationRequired, {
|
||||
affected: decision.affected,
|
||||
confirmThreshold: decision.confirmThreshold,
|
||||
...details,
|
||||
});
|
||||
}
|
||||
return decision;
|
||||
}
|
||||
Reference in new issue
Block a user