feat(tenancies-p2): rename berth_reservations → berth_tenancies (schema + perms + UI)

73-file atomic rename per docs/tenancies-design.md:

- Migration 0085: rename table + indexes + FK constraints; rename
  documents.reservation_id → tenancy_id; migrate jsonb permission maps
  (reservations resource → tenancies; collapse create+activate → manage);
  rewrite historical audit_logs.entity_type='berth_reservation' →
  'berth_tenancy'. FK renames wrapped in DO blocks so dev DBs that pre-date
  the FK additions don't abort.
- Schema: berthReservations → berthTenancies; BerthReservation type →
  BerthTenancy; indexes idx_br_* / idx_brr_* → idx_bt_*.
- RolePermissions: resource { view, create, activate, cancel } collapses to
  { view, manage, cancel }; all 8 default seed bundles + role-form + matrix
  updated.
- Service: berth-reservations.service.ts → berth-tenancies.service.ts;
  endReservation → endTenancy; listReservations → listTenancies.
- API: /api/v1/berth-reservations → /api/v1/tenancies (+ nested [id]);
  /api/v1/berths/[id]/reservations → /api/v1/berths/[id]/tenancies.
- Validators: reservations.ts → tenancies.ts; RESERVATION_STATUSES →
  TENANCY_STATUSES; endReservationSchema → endTenancySchema.
- Routes: /{portSlug}/berth-reservations → /{portSlug}/tenancies;
  /portal/my-reservations → /portal/my-tenancies.
- Components: src/components/reservations/* → src/components/tenancies/*;
  BerthReservationsTab → BerthTenanciesTab; ClientReservationsTab →
  ClientTenanciesTab; ReservationList → TenancyList.
- Socket events: berth_reservation:* → berth_tenancy:*; payload
  reservationId → tenancyId.
- Webhook events: berth_reservation.* → berth_tenancy.*.
- Portal: getPortalUserReservations → getPortalUserTenancies;
  PortalReservation → PortalTenancy; PortalDashboard.counts.activeReservations
  → activeTenancies; PortalNav label "Reservations" → "Tenancies".
- Dossier: DossierReservation → DossierTenancy; reservationDecisions →
  tenancyDecisions across smart-archive-dialog + bulk-archive routes.
- Documents schema: documents.reservationId → documents.tenancyId
  (TS + DB column + index + FK constraint).
- Activity feed label berth_reservation → berth_tenancy (matched against
  migrated historical audit rows).

KEPT (separate concepts):
- Reservation Agreement document type (the contract sent to clients).
- "Reservation" pipeline stage name.
- {{reservation.*}} merge tokens in template authoring.
- interest.reservationStatus / reservationDocStatus / dateReservationSent
  fields (track agreement signing on the deal).
- reservation-agreement-context.ts service (builds merge context for the
  Reservation Agreement doc; only its DB imports were renamed).

Verified: tsc clean, 1480/1480 vitest passing, migration applied.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/app/api/v1/tenancies/[id]/handlers.ts

@@ -0,0 +1,102 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { type RouteHandler } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { requirePermission } from '@/lib/auth/permissions';
+import { errorResponse } from '@/lib/errors';
+import { activate, cancel, endTenancy, getById } from '@/lib/services/berth-tenancies.service';
+
+// ─── PATCH body schema (action-based discriminated union) ────────────────────
+
+const patchBodySchema = z.discriminatedUnion('action', [
+  z.object({
+    action: z.literal('activate'),
+    contractFileId: z.string().optional(),
+    effectiveDate: z.coerce.date().optional(),
+  }),
+  z.object({
+    action: z.literal('end'),
+    endDate: z.coerce.date(),
+    notes: z.string().optional(),
+  }),
+  z.object({
+    action: z.literal('cancel'),
+    reason: z.string().optional(),
+  }),
+]);
+
+// ─── Handlers ────────────────────────────────────────────────────────────────
+
+export const getHandler: RouteHandler = async (_req, ctx, params) => {
+  try {
+    const tenancy = await getById(params.id!, ctx.portId);
+    return NextResponse.json({ data: tenancy });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const patchHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    const body = await parseBody(req, patchBodySchema);
+    const meta = {
+      userId: ctx.userId,
+      portId: ctx.portId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    };
+
+    if (body.action === 'activate') {
+      requirePermission(ctx, 'tenancies', 'manage');
+      const result = await activate(
+        params.id!,
+        ctx.portId,
+        {
+          contractFileId: body.contractFileId,
+          effectiveDate: body.effectiveDate,
+        },
+        meta,
+      );
+      return NextResponse.json({ data: result });
+    }
+
+    if (body.action === 'end') {
+      // `end` is lifecycle progression; same privilege as activate.
+      requirePermission(ctx, 'tenancies', 'manage');
+      const result = await endTenancy(
+        params.id!,
+        ctx.portId,
+        { endDate: body.endDate, notes: body.notes },
+        meta,
+      );
+      return NextResponse.json({ data: result });
+    }
+
+    // action === 'cancel'
+    requirePermission(ctx, 'tenancies', 'cancel');
+    const result = await cancel(params.id!, ctx.portId, { reason: body.reason }, meta);
+    return NextResponse.json({ data: result });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const deleteHandler: RouteHandler = async (_req, ctx, params) => {
+  try {
+    await cancel(
+      params.id!,
+      ctx.portId,
+      {},
+      {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      },
+    );
+    return new NextResponse(null, { status: 204 });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};

src/app/api/v1/tenancies/[id]/route.ts

@@ -0,0 +1,10 @@
+import { withAuth, withPermission } from '@/lib/api/helpers';
+
+import { getHandler, patchHandler, deleteHandler } from './handlers';
+
+export const GET = withAuth(withPermission('tenancies', 'view', getHandler));
+// PATCH cannot use `withPermission` wrapper - the required permission depends
+// on the `action` field in the body. `requirePermission` is called inside the
+// handler after the body is parsed.
+export const PATCH = withAuth(patchHandler);
+export const DELETE = withAuth(withPermission('tenancies', 'cancel', deleteHandler));

src/app/api/v1/tenancies/handlers.ts

@@ -0,0 +1,35 @@
+import { NextResponse } from 'next/server';
+
+import type { AuthContext } from '@/lib/api/helpers';
+import { parseQuery } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { listTenancies } from '@/lib/services/berth-tenancies.service';
+import { listTenanciesSchema } from '@/lib/validators/tenancies';
+
+/**
+ * Port-scoped global list of tenancies across all berths. Inner handler
+ * lives here so it can be invoked directly from integration tests without
+ * the `withAuth(withPermission(...))` wrappers (matches the convention
+ * used throughout `src/app/api/v1/*`).
+ */
+export async function listHandler(req: Request, ctx: AuthContext): Promise<NextResponse> {
+  try {
+    const query = parseQuery(req as never, listTenanciesSchema);
+    const result = await listTenancies(ctx.portId, query);
+    const { page, limit } = query;
+    const totalPages = Math.ceil(result.total / limit);
+    return NextResponse.json({
+      data: result.data,
+      pagination: {
+        page,
+        pageSize: limit,
+        total: result.total,
+        totalPages,
+        hasNextPage: page < totalPages,
+        hasPreviousPage: page > 1,
+      },
+    });
+  } catch (error) {
+    return errorResponse(error);
+  }
+}

src/app/api/v1/tenancies/route.ts

@@ -0,0 +1,4 @@
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { listHandler } from './handlers';
+
+export const GET = withAuth(withPermission('tenancies', 'view', listHandler));