feat(addresses): full CRUD UI for client + company multi-address

Client and company detail pages each gain an Addresses tab with click-to-edit
fields wired to the existing CountryCombobox/SubdivisionCombobox primitives.
Adds a primary toggle that demotes the previous primary inside one transaction
so the partial unique index never trips.

- New service helpers: list/add/update/remove ClientAddress + CompanyAddress
- New routes: /api/v1/clients/[id]/addresses[/addressId], same under companies/
- New shared component: <AddressesEditor> reused by both detail surfaces
- Integration tests cover happy path, primary demotion, and tenant scoping

Tests: 747/747 vitest (was 741, +6 address tests).

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

src/app/api/v1/clients/[id]/addresses/[addressId]/route.ts

@@ -0,0 +1,51 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { updateClientAddress, removeClientAddress } from '@/lib/services/clients.service';
+import { optionalCountryIsoSchema, optionalSubdivisionIsoSchema } from '@/lib/validators/i18n';
+
+const updateAddressSchema = z.object({
+  label: z.string().min(1).max(80).optional(),
+  streetAddress: z.string().max(500).optional().nullable(),
+  city: z.string().max(120).optional().nullable(),
+  subdivisionIso: optionalSubdivisionIsoSchema.optional(),
+  postalCode: z.string().max(40).optional().nullable(),
+  countryIso: optionalCountryIsoSchema.optional(),
+  isPrimary: z.boolean().optional(),
+});
+
+export const PATCH = withAuth(
+  withPermission('clients', 'edit', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, updateAddressSchema);
+      const row = await updateClientAddress(params.addressId!, params.id!, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: row });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('clients', 'edit', async (req, ctx, params) => {
+    try {
+      await removeClientAddress(params.addressId!, 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/clients/[id]/addresses/route.ts

@@ -0,0 +1,46 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { listClientAddresses, addClientAddress } from '@/lib/services/clients.service';
+import { optionalCountryIsoSchema, optionalSubdivisionIsoSchema } from '@/lib/validators/i18n';
+
+const addAddressSchema = z.object({
+  label: z.string().min(1).max(80).optional(),
+  streetAddress: z.string().max(500).optional().nullable(),
+  city: z.string().max(120).optional().nullable(),
+  subdivisionIso: optionalSubdivisionIsoSchema.optional(),
+  postalCode: z.string().max(40).optional().nullable(),
+  countryIso: optionalCountryIsoSchema.optional(),
+  isPrimary: z.boolean().optional(),
+});
+
+export const GET = withAuth(
+  withPermission('clients', 'view', async (req, ctx, params) => {
+    try {
+      const rows = await listClientAddresses(params.id!, ctx.portId);
+      return NextResponse.json({ data: rows });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const POST = withAuth(
+  withPermission('clients', 'edit', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, addAddressSchema);
+      const row = await addClientAddress(params.id!, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: row }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/companies/[id]/addresses/[addressId]/route.ts

@@ -0,0 +1,51 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { updateCompanyAddress, removeCompanyAddress } from '@/lib/services/companies.service';
+import { optionalCountryIsoSchema, optionalSubdivisionIsoSchema } from '@/lib/validators/i18n';
+
+const updateAddressSchema = z.object({
+  label: z.string().min(1).max(80).optional(),
+  streetAddress: z.string().max(500).optional().nullable(),
+  city: z.string().max(120).optional().nullable(),
+  subdivisionIso: optionalSubdivisionIsoSchema.optional(),
+  postalCode: z.string().max(40).optional().nullable(),
+  countryIso: optionalCountryIsoSchema.optional(),
+  isPrimary: z.boolean().optional(),
+});
+
+export const PATCH = withAuth(
+  withPermission('companies', 'edit', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, updateAddressSchema);
+      const row = await updateCompanyAddress(params.addressId!, params.id!, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: row });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('companies', 'edit', async (req, ctx, params) => {
+    try {
+      await removeCompanyAddress(params.addressId!, 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/companies/[id]/addresses/route.ts

@@ -0,0 +1,46 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { listCompanyAddresses, addCompanyAddress } from '@/lib/services/companies.service';
+import { optionalCountryIsoSchema, optionalSubdivisionIsoSchema } from '@/lib/validators/i18n';
+
+const addAddressSchema = z.object({
+  label: z.string().min(1).max(80).optional(),
+  streetAddress: z.string().max(500).optional().nullable(),
+  city: z.string().max(120).optional().nullable(),
+  subdivisionIso: optionalSubdivisionIsoSchema.optional(),
+  postalCode: z.string().max(40).optional().nullable(),
+  countryIso: optionalCountryIsoSchema.optional(),
+  isPrimary: z.boolean().optional(),
+});
+
+export const GET = withAuth(
+  withPermission('companies', 'view', async (req, ctx, params) => {
+    try {
+      const rows = await listCompanyAddresses(params.id!, ctx.portId);
+      return NextResponse.json({ data: rows });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const POST = withAuth(
+  withPermission('companies', 'edit', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, addAddressSchema);
+      const row = await addCompanyAddress(params.id!, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: row }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);