feat(recycle-bin): soft delete + restore for master data

Accidental admin deletes of users/roles/subscriptions/plans/tariffs were
hard and unrecoverable. Now they soft-delete into a recycle bin.

Schema (migration 0012): nullable deleted_at + deleted_by on users, roles,
subscriptions, subscription_plans, tariffs. Additive ADD COLUMN; verified
against a copy of the live DB.

Backend: each resource's DELETE route STAMPS instead of removing; every
catalog list filters deleted_at IS NULL. New recycle-bin module + routes
(GET /api/recycle-bin, POST .../restore, DELETE .../:id purge) gated on a
new recyclebin:read/update/delete permission. A 6-hourly + startup sweep
auto-purges items older than RECYCLE_BIN_RETENTION_DAYS (default 30; 0 =
forever).

Invariants: soft-deleted users can't log in (login rejects deleted_at;
no-lockout counts live admins only); a soft-deleted subscription doesn't
open the barrier; plans are versioned so a delete stamps all versions of
the plan_id (bin shows one item); username/role-name UNIQUE spans deleted
rows so reuse returns a clear 409 pointing at the bin; restore doesn't
auto-cascade a dangling role (guard resolves missing role to empty perms).
The signed append-only ledger is OUT of scope (no delete path).

Web: a Recycle bin tab under Setup (RecycleBin.tsx) with Restore/Purge +
purge confirm; api client + i18n (sq + en parity).

Tests: recycle-bin.test.ts (9 unit) + recycle-bin-routes.test.ts (4
integration: delete -> can't-login -> restore -> login, purge, gating,
409 reuse). server 103/103; build+lint+test 19/19.

Wiki: new concepts/soft-delete.md; local-jwt-auth + index + log updated.

Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V

apps/server/src/routes/users.ts

@@ -1,9 +1,10 @@
 import { randomUUID } from "node:crypto";
 import bcrypt from "bcrypt";
 import type { FastifyInstance } from "fastify";
-import { eq, roles, users, type Db } from "@parking/db";
+import { and, eq, isNull, roles, users, type Db } from "@parking/db";
 import { ADMIN_ROLE_ID } from "@parking/shared";
 import { permissionsFor, requirePermission } from "../auth.js";
+import { softDelete } from "../recycle-bin.js";
 
 // User management (admin). Users are created/edited at runtime here — the
 // install-time seed-admin.mjs only bootstraps the FIRST admin. Each user has one
@@ -64,9 +65,10 @@ export async function userRoutes(app: FastifyInstance, db: Db): Promise<void> {
   const updateGuard = requirePermission("user:update");
   const deleteGuard = requirePermission("user:delete");
 
-  /** Count users currently holding the protected admin role. */
+  /** Count LIVE users currently holding the protected admin role. A soft-deleted admin
+   *  doesn't count — they can't log in — so the no-lockout check uses live admins only. */
   function adminCount(): number {
-    return db.select().from(users).where(eq(users.roleId, ADMIN_ROLE_ID)).all().length;
+    return db.select().from(users).where(and(eq(users.roleId, ADMIN_ROLE_ID), isNull(users.deletedAt))).all().length;
   }
 
   /** True if removing/relocating `userId` from admin would leave zero admins. */
@@ -112,9 +114,10 @@ export async function userRoutes(app: FastifyInstance, db: Db): Promise<void> {
     return false;
   }
 
-  // List all users (no password hashes) + their role names for display.
+  // List all LIVE users (no password hashes) + their role names for display. Soft-deleted
+  // users live in the recycle bin, not here.
   app.get("/api/users", { preHandler: readGuard }, async () => {
-    const rows = db.select().from(users).all();
+    const rows = db.select().from(users).where(isNull(users.deletedAt)).all();
     const roleRows = db.select().from(roles).all();
     const roleName = new Map(roleRows.map((r) => [r.id, r.name]));
     return {
@@ -140,8 +143,15 @@ export async function userRoutes(app: FastifyInstance, db: Db): Promise<void> {
     if (exceedsCaller(req.user.roleId, roleId)) {
       return reply.code(403).send({ error: "cannot assign a role with permissions beyond your own" });
     }
-    if (db.select().from(users).where(eq(users.username, username)).get()) {
-      return reply.code(409).send({ error: "username already exists" });
+    const clash = db.select().from(users).where(eq(users.username, username)).get();
+    if (clash) {
+      // The username is UNIQUE across live AND soft-deleted rows. If a DELETED user holds
+      // it, point the admin at the recycle bin (restore or purge) rather than a bare 409.
+      return reply.code(409).send({
+        error: clash.deletedAt
+          ? "username belongs to a deleted user — restore or purge it from the recycle bin first"
+          : "username already exists",
+      });
     }
     const id = randomUUID();
     const passwordHash = await bcrypt.hash(password, 12);
@@ -221,13 +231,15 @@ export async function userRoutes(app: FastifyInstance, db: Db): Promise<void> {
     },
   );
 
-  // Delete a user. Refused if it's the last admin (no-lockout).
+  // Delete a user — SOFT (recycle bin). Refused if it's the last admin (no-lockout).
+  // The row is stamped deleted (recoverable), not removed; it vanishes from the list and
+  // can't log in. Restore/purge from the recycle bin. See recycle-bin.ts.
   app.delete<{ Params: { id: string } }>(
     "/api/users/:id",
     { preHandler: deleteGuard },
     async (req, reply) => {
       const id = req.params.id;
-      const target = db.select().from(users).where(eq(users.id, id)).get();
+      const target = db.select().from(users).where(and(eq(users.id, id), isNull(users.deletedAt))).get();
       if (!target) {
         return reply.code(404).send({ error: "user not found" });
       }
@@ -238,7 +250,7 @@ export async function userRoutes(app: FastifyInstance, db: Db): Promise<void> {
       if (isLastAdmin(id)) {
         return reply.code(409).send({ error: "cannot delete the last admin" });
       }
-      db.delete(users).where(eq(users.id, id)).run();
+      softDelete(db, "user", id, req.user.sub);
       return { ok: true };
     },
   );