feat(api): GET/POST /api/v1/yachts

Add yacht list + create routes, export RouteHandler type and inner
handlers so tests can invoke them directly with a mock AuthContext.
New tests/helpers/route-tester.ts provides makeMockCtx/makeMockRequest
reusable by subsequent Task 3.x routes.

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

@@ -0,0 +1,47 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission, type RouteHandler } from '@/lib/api/helpers';
+import { parseQuery, parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { listYachts, createYacht } from '@/lib/services/yachts.service';
+import { listYachtsSchema, createYachtSchema } from '@/lib/validators/yachts';
+
+export const listHandler: RouteHandler = async (req, ctx) => {
+  try {
+    const query = parseQuery(req, listYachtsSchema);
+    const result = await listYachts(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);
+  }
+};
+
+export const createHandler: RouteHandler = async (req, ctx) => {
+  try {
+    const body = await parseBody(req, createYachtSchema);
+    const yacht = await createYacht(ctx.portId, body, {
+      userId: ctx.userId,
+      portId: ctx.portId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+    return NextResponse.json({ data: yacht }, { status: 201 });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const GET = withAuth(withPermission('yachts', 'view', listHandler));
+export const POST = withAuth(withPermission('yachts', 'create', createHandler));

src/lib/api/helpers.ts

@@ -3,12 +3,7 @@ import { NextRequest, NextResponse } from 'next/server';
 
 import { auth } from '@/lib/auth';
 import { db } from '@/lib/db';
-import {
-  portRoleOverrides,
-  ports,
-  userPortRoles,
-  userProfiles,
-} from '@/lib/db/schema';
+import { portRoleOverrides, ports, userPortRoles, userProfiles } from '@/lib/db/schema';
 import { type RolePermissions } from '@/lib/db/schema/users';
 import { createAuditLog } from '@/lib/audit';
 import { errorResponse } from '@/lib/errors';
@@ -40,7 +35,7 @@ export interface AuthContext {
   userAgent: string;
 }
 
-type RouteHandler<T = unknown> = (
+export type RouteHandler<T = unknown> = (
   req: NextRequest,
   ctx: AuthContext,
   params: Record<string, string>,
@@ -133,10 +128,7 @@ export function withAuth(
 
       if (!profile.isSuperAdmin && portId) {
         const portRole = await db.query.userPortRoles.findFirst({
-          where: and(
-            eq(userPortRoles.userId, profile.userId),
-            eq(userPortRoles.portId, portId),
-          ),
+          where: and(eq(userPortRoles.userId, profile.userId), eq(userPortRoles.portId, portId)),
           with: {
             role: true,
             port: true,
@@ -182,8 +174,7 @@ export function withAuth(
           email: session.user.email,
           name: session.user.name,
         },
-        ipAddress:
-          req.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ?? 'unknown',
+        ipAddress: req.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ?? 'unknown',
         userAgent: req.headers.get('user-agent') ?? 'unknown',
       };
 
@@ -213,9 +204,7 @@ export function withPermission(
 ): RouteHandler {
   return async (req, ctx, params) => {
     if (!ctx.isSuperAdmin) {
-      const resourcePerms = ctx.permissions?.[resource] as
-        | Record<string, boolean>
-        | undefined;
+      const resourcePerms = ctx.permissions?.[resource] as Record<string, boolean> | undefined;
 
       if (!resourcePerms || !resourcePerms[action]) {
         logger.warn({ userId: ctx.userId, resource, action }, 'Permission denied');