feat(permissions): carve out dedicated payments resource

Payments (deposit / balance / refund records on an interest) used to
share `invoices.record_payment`, which forces a port that doesn't
issue invoices at all to still navigate the invoicing permission
group to grant its sales reps payment-recording rights. Splitting
the resource lets admins gate the two surfaces independently.

The new resource has three actions:
  - view   — gates the UI affordance (API reads still go through
             `interests.view`)
  - record — POST / PATCH a payment
  - delete — DELETE a payment record

Seed maps updated for all six system roles; existing role rows +
per-user permission overrides are backfilled by migration 0064 so
upgrades don't silently lose access. Two call sites (POST /interests/
[id]/payments, PATCH /payments/[id]) → payments.record; one
(DELETE /payments/[id]) → payments.delete. The PermissionGates on the
payments-section UI swap to the new keys.

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

src/app/api/v1/interests/[id]/payments/route.ts

@@ -26,7 +26,7 @@ export const GET = withAuth(
 );
 
 export const POST = withAuth(
-  withPermission('invoices', 'record_payment', async (req, ctx, params) => {
+  withPermission('payments', 'record', async (req, ctx, params) => {
     try {
       // Body's interestId must match the URL param — defense-in-depth against
       // a client that sends one ID in the URL but another in the body.

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

@@ -7,7 +7,7 @@ import { updatePaymentSchema } from '@/lib/validators/payments';
 import { deletePayment, updatePayment } from '@/lib/services/payments.service';
 
 export const PATCH = withAuth(
-  withPermission('invoices', 'record_payment', async (req, ctx, params) => {
+  withPermission('payments', 'record', async (req, ctx, params) => {
     try {
       const body = await parseBody(req, updatePaymentSchema);
       const payment = await updatePayment(params.id!, ctx.portId, body, {
@@ -24,7 +24,7 @@ export const PATCH = withAuth(
 );
 
 export const DELETE = withAuth(
-  withPermission('invoices', 'record_payment', async (_req, ctx, params) => {
+  withPermission('payments', 'delete', async (_req, ctx, params) => {
     try {
       await deletePayment(params.id!, ctx.portId, {
         userId: ctx.userId,

src/components/admin/roles/role-form.tsx

@@ -59,6 +59,7 @@ const DEFAULT_PERMISSIONS: Record<string, Record<string, boolean>> = {
     record_payment: false,
     export: false,
   },
+  payments: { view: false, record: false, delete: false },
   files: { view: false, upload: false, edit: false, delete: false, manage_folders: false },
   email: { view: false, send: false, configure_account: false },
   reminders: {
@@ -105,6 +106,7 @@ const GROUP_LABELS: Record<string, string> = {
   documents: 'Documents',
   expenses: 'Expenses',
   invoices: 'Invoices',
+  payments: 'Payments',
   files: 'Files',
   email: 'Email',
   reminders: 'Reminders',

src/components/admin/users/user-permission-matrix.tsx

@@ -36,6 +36,7 @@ const GROUP_LABELS: Record<string, string> = {
   documents: 'Documents',
   expenses: 'Expenses',
   invoices: 'Invoices',
+  payments: 'Payments',
   files: 'Files',
   email: 'Email',
   reminders: 'Reminders',
@@ -78,6 +79,7 @@ const PERMISSION_LEAVES: Record<string, string[]> = {
   ],
   expenses: ['view', 'create', 'edit', 'delete', 'export', 'scan_receipt'],
   invoices: ['view', 'create', 'edit', 'delete', 'send', 'record_payment', 'export'],
+  payments: ['view', 'record', 'delete'],
   files: ['view', 'upload', 'edit', 'delete', 'manage_folders'],
   email: ['view', 'send', 'configure_account'],
   reminders: ['view_own', 'view_all', 'create', 'edit_own', 'edit_all', 'assign_others'],

src/components/interests/payments-section.tsx

@@ -128,7 +128,7 @@ export function PaymentsSection({
             that.
           </p>
         </div>
-        <PermissionGate resource="invoices" action="record_payment">
+        <PermissionGate resource="payments" action="record">
           <Button size="sm" className="h-8 px-3 text-xs" onClick={() => setRecordOpen(true)}>
             <Plus className="size-3.5" aria-hidden />
             Record payment
@@ -184,7 +184,7 @@ export function PaymentsSection({
                   <Receipt className="size-3 text-emerald-600" aria-hidden />
                 ) : null}
               </div>
-              <PermissionGate resource="invoices" action="record_payment">
+              <PermissionGate resource="payments" action="delete">
                 <button
                   type="button"
                   aria-label="Delete payment record"

src/lib/db/migrations/0064_payments_permission.sql

@@ -0,0 +1,32 @@
+-- 0064_payments_permission.sql
+-- ----------------------------------------------------------------------------
+-- Carve out a dedicated `payments` resource from `invoices.record_payment`.
+-- Existing role rows + per-user permission overrides are backfilled so the
+-- new resource defaults to whatever record_payment was, preventing silent
+-- access loss when the call sites switch over.
+
+UPDATE roles
+SET permissions = permissions || jsonb_build_object(
+  'payments', jsonb_build_object(
+    'view',   COALESCE((permissions->'invoices'->>'view')::boolean,            false),
+    'record', COALESCE((permissions->'invoices'->>'record_payment')::boolean,  false),
+    'delete', COALESCE((permissions->'invoices'->>'record_payment')::boolean,  false)
+  )
+)
+WHERE permissions IS NOT NULL
+  AND NOT (permissions ? 'payments');
+
+-- Per-user overrides store a Partial<RolePermissions> as JSONB. Mirror an
+-- explicit invoices.record_payment leaf into payments.{record, delete} so
+-- "Alice can record payments even though her role can't" survives the
+-- carve-out.
+UPDATE user_permission_overrides
+SET permission_overrides = permission_overrides || jsonb_build_object(
+  'payments', jsonb_build_object(
+    'record', (permission_overrides->'invoices'->>'record_payment')::boolean,
+    'delete', (permission_overrides->'invoices'->>'record_payment')::boolean
+  )
+)
+WHERE permission_overrides ? 'invoices'
+  AND (permission_overrides->'invoices') ? 'record_payment'
+  AND NOT (permission_overrides ? 'payments');

src/lib/db/schema/users.ts

@@ -58,6 +58,18 @@ export type RolePermissions = {
     record_payment: boolean;
     export: boolean;
   };
+  /**
+   * Standalone payments resource (deposit / balance / refund records on
+   * an interest). Carved out from `invoices.record_payment` so a port
+   * that does not use the invoicing module at all can still grant
+   * payment-recording rights to sales reps. `view` follows interests.view
+   * at the route level — this gate only governs the UI affordance.
+   */
+  payments: {
+    view: boolean;
+    record: boolean;
+    delete: boolean;
+  };
   files: {
     view: boolean;
     upload: boolean;

src/lib/db/seed-permissions.ts

@@ -50,6 +50,7 @@ export const ALL_PERMISSIONS: RolePermissions = {
     record_payment: true,
     export: true,
   },
+  payments: { view: true, record: true, delete: true },
   files: { view: true, upload: true, edit: true, delete: true, manage_folders: true },
   email: { view: true, send: true, configure_account: true },
   reminders: {
@@ -128,6 +129,7 @@ export const DIRECTOR_PERMISSIONS: RolePermissions = {
     record_payment: true,
     export: true,
   },
+  payments: { view: true, record: true, delete: true },
   files: { view: true, upload: true, edit: true, delete: true, manage_folders: true },
   email: { view: true, send: true, configure_account: true },
   reminders: {
@@ -206,6 +208,7 @@ export const SALES_MANAGER_PERMISSIONS: RolePermissions = {
     record_payment: true,
     export: true,
   },
+  payments: { view: true, record: true, delete: true },
   files: { view: true, upload: true, edit: true, delete: false, manage_folders: true },
   email: { view: true, send: true, configure_account: true },
   reminders: {
@@ -284,6 +287,7 @@ export const SALES_AGENT_PERMISSIONS: RolePermissions = {
     record_payment: true,
     export: true,
   },
+  payments: { view: true, record: true, delete: true },
   files: { view: true, upload: true, edit: false, delete: false, manage_folders: false },
   email: { view: true, send: true, configure_account: true },
   reminders: {
@@ -362,6 +366,7 @@ export const VIEWER_PERMISSIONS: RolePermissions = {
     record_payment: false,
     export: false,
   },
+  payments: { view: true, record: false, delete: false },
   files: { view: true, upload: false, edit: false, delete: false, manage_folders: false },
   email: { view: true, send: false, configure_account: false },
   reminders: {
@@ -443,6 +448,7 @@ export const RESIDENTIAL_PARTNER_PERMISSIONS: RolePermissions = {
     record_payment: false,
     export: false,
   },
+  payments: { view: false, record: false, delete: false },
   files: { view: false, upload: false, edit: false, delete: false, manage_folders: false },
   email: { view: false, send: false, configure_account: false },
   reminders: {

src/lib/validators/roles.ts

@@ -9,6 +9,7 @@ const rolePermissionsSchema = z.object({
   documents: permissionGroupSchema,
   expenses: permissionGroupSchema,
   invoices: permissionGroupSchema,
+  payments: permissionGroupSchema,
   files: permissionGroupSchema,
   email: permissionGroupSchema,
   reminders: permissionGroupSchema,

tests/helpers/factories.ts

@@ -340,6 +340,7 @@ export function makeFullPermissions(): RolePermissions {
       record_payment: true,
       export: true,
     },
+    payments: { view: true, record: true, delete: true },
     files: { view: true, upload: true, edit: true, delete: true, manage_folders: true },
     email: { view: true, send: true, configure_account: true },
     reminders: {
@@ -421,6 +422,7 @@ export function makeViewerPermissions(): RolePermissions {
       record_payment: false,
       export: false,
     },
+    payments: { view: false, record: false, delete: false },
     files: { view: true, upload: false, edit: false, delete: false, manage_folders: false },
     email: { view: true, send: false, configure_account: false },
     reminders: {
@@ -502,6 +504,7 @@ export function makeSalesAgentPermissions(): RolePermissions {
       record_payment: false,
       export: false,
     },
+    payments: { view: false, record: false, delete: false },
     files: { view: true, upload: true, edit: false, delete: false, manage_folders: false },
     email: { view: true, send: true, configure_account: false },
     reminders: {
@@ -583,6 +586,7 @@ export function makeSalesManagerPermissions(): RolePermissions {
       record_payment: true,
       export: true,
     },
+    payments: { view: true, record: true, delete: true },
     files: { view: true, upload: true, edit: true, delete: true, manage_folders: true },
     email: { view: true, send: true, configure_account: false },
     reminders: {