feat: add flexible billing frequency support for invoices

Assessment groups can now define billing frequency (monthly, quarterly,
annual) with configurable due months and due day. Invoice generation
respects each group's schedule - only generating invoices when the
selected month is a billing month for that group. Adds a generation
preview showing which groups will be billed, period tracking on
invoices, and billing period context in the payments UI.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

frontend/src/pages/invoices/InvoicesPage.tsx

@@ -1,13 +1,12 @@
-import { useState } from 'react';
+import { useState, useEffect } from 'react';
 import {
   Title, Table, Group, Button, Stack, Text, Badge, Modal,
-  NumberInput, Select, Loader, Center, Card,
+  NumberInput, Select, Loader, Center, Card, Alert,
 } from '@mantine/core';
-import { DateInput } from '@mantine/dates';
 import { useForm } from '@mantine/form';
 import { useDisclosure } from '@mantine/hooks';
 import { notifications } from '@mantine/notifications';
-import { IconFileInvoice, IconSend } from '@tabler/icons-react';
+import { IconSend, IconInfoCircle, IconCheck, IconX } from '@tabler/icons-react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import api from '../../services/api';
 
@@ -15,15 +14,48 @@ interface Invoice {
   id: string; invoice_number: string; unit_number: string; unit_id: string;
   invoice_date: string; due_date: string; invoice_type: string;
   description: string; amount: string; amount_paid: string; balance_due: string;
-  status: string;
+  status: string; period_start: string; period_end: string;
+  assessment_group_name: string; frequency: string;
+}
+
+interface PreviewGroup {
+  id: string;
+  name: string;
+  frequency: string;
+  active_units: number;
+  regular_assessment: string;
+  special_assessment: string;
+  is_billing_month: boolean;
+  total_amount: number;
+  period_description: string;
+}
+
+interface Preview {
+  month: number;
+  year: number;
+  month_name: string;
+  groups: PreviewGroup[];
+  summary: {
+    total_groups_billing: number;
+    total_invoices: number;
+    total_amount: number;
+  };
 }
 
 const statusColors: Record<string, string> = {
   draft: 'gray', sent: 'blue', paid: 'green', partial: 'yellow', overdue: 'red', void: 'dark',
 };
 
+const frequencyColors: Record<string, string> = {
+  monthly: 'blue', quarterly: 'teal', annual: 'violet',
+};
+
+const fmt = (v: string | number) => parseFloat(String(v || '0')).toLocaleString('en-US', { style: 'currency', currency: 'USD' });
+
 export function InvoicesPage() {
   const [bulkOpened, { open: openBulk, close: closeBulk }] = useDisclosure(false);
+  const [preview, setPreview] = useState<Preview | null>(null);
+  const [previewLoading, setPreviewLoading] = useState(false);
   const queryClient = useQueryClient();
 
   const { data: invoices = [], isLoading } = useQuery<Invoice[]>({
@@ -35,13 +67,36 @@ export function InvoicesPage() {
     initialValues: { month: new Date().getMonth() + 1, year: new Date().getFullYear() },
   });
 
+  // Fetch preview when month/year changes
+  const fetchPreview = async (month: number, year: number) => {
+    setPreviewLoading(true);
+    try {
+      const { data } = await api.post('/invoices/generate-preview', { month, year });
+      setPreview(data);
+    } catch {
+      setPreview(null);
+    }
+    setPreviewLoading(false);
+  };
+
+  useEffect(() => {
+    if (bulkOpened) {
+      fetchPreview(bulkForm.values.month, bulkForm.values.year);
+    }
+  }, [bulkOpened, bulkForm.values.month, bulkForm.values.year]);
+
   const bulkMutation = useMutation({
     mutationFn: (values: any) => api.post('/invoices/generate-bulk', values),
     onSuccess: (res) => {
       queryClient.invalidateQueries({ queryKey: ['invoices'] });
       queryClient.invalidateQueries({ queryKey: ['journal-entries'] });
-      notifications.show({ message: `Generated ${res.data.created} invoices`, color: 'green' });
+      const groupInfo = res.data.groups?.map((g: any) => `${g.group_name}: ${g.invoices_created}`).join(', ') || '';
+      notifications.show({
+        message: `Generated ${res.data.created} invoices${groupInfo ? ` (${groupInfo})` : ''}`,
+        color: 'green',
+      });
       closeBulk();
+      setPreview(null);
     },
     onError: (err: any) => { notifications.show({ message: err.response?.data?.message || 'Error', color: 'red' }); },
   });
@@ -54,8 +109,6 @@ export function InvoicesPage() {
     },
   });
 
-  const fmt = (v: string) => parseFloat(v || '0').toLocaleString('en-US', { style: 'currency', currency: 'USD' });
-
   if (isLoading) return <Center h={300}><Loader /></Center>;
 
   const totalOutstanding = invoices.filter(i => i.status !== 'paid' && i.status !== 'void').reduce((s, i) => s + parseFloat(i.balance_due || '0'), 0);
@@ -66,18 +119,19 @@ export function InvoicesPage() {
         <Title order={2}>Invoices</Title>
         <Group>
           <Button variant="outline" onClick={() => lateFeesMutation.mutate()} loading={lateFeesMutation.isPending}>Apply Late Fees</Button>
-          <Button leftSection={<IconSend size={16} />} onClick={openBulk}>Generate Monthly Invoices</Button>
+          <Button leftSection={<IconSend size={16} />} onClick={openBulk}>Generate Invoices</Button>
         </Group>
       </Group>
       <Group>
         <Card withBorder p="sm"><Text size="xs" c="dimmed">Total Invoices</Text><Text fw={700}>{invoices.length}</Text></Card>
-        <Card withBorder p="sm"><Text size="xs" c="dimmed">Outstanding</Text><Text fw={700} c="red">{fmt(String(totalOutstanding))}</Text></Card>
+        <Card withBorder p="sm"><Text size="xs" c="dimmed">Outstanding</Text><Text fw={700} c="red">{fmt(totalOutstanding)}</Text></Card>
       </Group>
       <Table striped highlightOnHover>
         <Table.Thead>
           <Table.Tr>
             <Table.Th>Invoice #</Table.Th><Table.Th>Unit</Table.Th><Table.Th>Date</Table.Th>
-            <Table.Th>Due</Table.Th><Table.Th>Type</Table.Th><Table.Th ta="right">Amount</Table.Th>
+            <Table.Th>Due</Table.Th><Table.Th>Type</Table.Th><Table.Th>Period</Table.Th>
+            <Table.Th ta="right">Amount</Table.Th>
             <Table.Th ta="right">Paid</Table.Th><Table.Th ta="right">Balance</Table.Th><Table.Th>Status</Table.Th>
           </Table.Tr>
         </Table.Thead>
@@ -89,24 +143,92 @@ export function InvoicesPage() {
               <Table.Td>{new Date(i.invoice_date).toLocaleDateString()}</Table.Td>
               <Table.Td>{new Date(i.due_date).toLocaleDateString()}</Table.Td>
               <Table.Td><Badge size="sm" variant="light">{i.invoice_type}</Badge></Table.Td>
+              <Table.Td>
+                {i.period_start && i.period_end ? (
+                  <Text size="xs" c="dimmed">
+                    {new Date(i.period_start).toLocaleDateString(undefined, { month: 'short', year: 'numeric' })}
+                    {i.period_start !== i.period_end && (
+                      <> - {new Date(i.period_end).toLocaleDateString(undefined, { month: 'short', year: 'numeric' })}</>
+                    )}
+                  </Text>
+                ) : (
+                  <Text size="xs" c="dimmed">-</Text>
+                )}
+              </Table.Td>
               <Table.Td ta="right" ff="monospace">{fmt(i.amount)}</Table.Td>
               <Table.Td ta="right" ff="monospace">{fmt(i.amount_paid)}</Table.Td>
               <Table.Td ta="right" ff="monospace" fw={500}>{fmt(i.balance_due)}</Table.Td>
               <Table.Td><Badge color={statusColors[i.status] || 'gray'} size="sm">{i.status}</Badge></Table.Td>
             </Table.Tr>
           ))}
-          {invoices.length === 0 && <Table.Tr><Table.Td colSpan={9}><Text ta="center" c="dimmed" py="lg">No invoices yet</Text></Table.Td></Table.Tr>}
+          {invoices.length === 0 && <Table.Tr><Table.Td colSpan={10}><Text ta="center" c="dimmed" py="lg">No invoices yet</Text></Table.Td></Table.Tr>}
         </Table.Tbody>
       </Table>
-      <Modal opened={bulkOpened} onClose={closeBulk} title="Generate Monthly Assessments">
+
+      <Modal opened={bulkOpened} onClose={() => { closeBulk(); setPreview(null); }} title="Generate Assessments" size="lg">
         <form onSubmit={bulkForm.onSubmit((v) => bulkMutation.mutate(v))}>
           <Stack>
             <Group grow>
               <Select label="Month" data={Array.from({length:12},(_,i)=>({value:String(i+1),label:new Date(2026,i).toLocaleString('default',{month:'long'})}))} value={String(bulkForm.values.month)} onChange={(v)=>bulkForm.setFieldValue('month',Number(v))} />
               <NumberInput label="Year" {...bulkForm.getInputProps('year')} />
             </Group>
-            <Text size="sm" c="dimmed">This will generate invoices for all active units based on their monthly assessment amount.</Text>
-            <Button type="submit" loading={bulkMutation.isPending}>Generate Invoices</Button>
+
+            {previewLoading && <Center py="md"><Loader size="sm" /></Center>}
+
+            {preview && !previewLoading && (
+              <Stack gap="xs">
+                <Text size="sm" fw={600}>Billing Preview for {preview.month_name} {preview.year}</Text>
+
+                {preview.groups.map((g) => (
+                  <Card key={g.id} withBorder p="xs" style={{ opacity: g.is_billing_month ? 1 : 0.5 }}>
+                    <Group justify="space-between">
+                      <Group gap="xs">
+                        {g.is_billing_month && g.active_units > 0
+                          ? <IconCheck size={16} color="green" />
+                          : <IconX size={16} color="gray" />
+                        }
+                        <div>
+                          <Group gap={6}>
+                            <Text size="sm" fw={500}>{g.name}</Text>
+                            <Badge size="xs" color={frequencyColors[g.frequency]} variant="light">
+                              {g.frequency}
+                            </Badge>
+                          </Group>
+                          <Text size="xs" c="dimmed">
+                            {g.is_billing_month
+                              ? `${g.active_units} units - ${g.period_description}`
+                              : `Not a billing month for this group`
+                            }
+                          </Text>
+                        </div>
+                      </Group>
+                      {g.is_billing_month && (
+                        <Text size="sm" fw={500} ff="monospace">{fmt(g.total_amount)}</Text>
+                      )}
+                    </Group>
+                  </Card>
+                ))}
+
+                {preview.summary.total_invoices > 0 ? (
+                  <Alert icon={<IconInfoCircle size={16} />} color="blue" variant="light">
+                    Will generate {preview.summary.total_invoices} invoices across{' '}
+                    {preview.summary.total_groups_billing} group(s) totaling {fmt(preview.summary.total_amount)}
+                  </Alert>
+                ) : (
+                  <Alert icon={<IconInfoCircle size={16} />} color="yellow" variant="light">
+                    No assessment groups have billing scheduled for {preview.month_name}. No invoices will be generated.
+                  </Alert>
+                )}
+              </Stack>
+            )}
+
+            <Button
+              type="submit"
+              loading={bulkMutation.isPending}
+              disabled={!preview || preview.summary.total_invoices === 0}
+            >
+              Generate {preview?.summary.total_invoices || 0} Invoices
+            </Button>
           </Stack>
         </form>
       </Modal>