@tuturuuu/ui 0.38.0 → 0.39.1

package/src/components/ui/finance/invoices/subscription-admission.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest';
+import {
+  hasInvalidSubscriptionLinks,
+  isSubscriptionContextReady,
+} from './subscription-admission';
+import type { Product, UserGroupProducts } from './types';
+
+const valid: UserGroupProducts = {
+  group_id: 'g',
+  workspace_products: { id: 'p', name: null, product_categories: null },
+  inventory_units: { id: 'u', name: null },
+  warehouse_id: null,
+};
+const products = [
+  { id: 'p', inventory: [{ unit_id: 'u', amount: null }] },
+] as Product[];
+describe('entire linked billing admission', () => {
+  it('accepts valid scoped links without imposing a category or warehouse', () => {
+    expect(hasInvalidSubscriptionLinks([valid], products)).toBe(false);
+  });
+  it.each([
+    { ...valid, inventory_units: null },
+    { ...valid, workspace_products: null },
+    { ...valid, inventory_units: { id: 'other', name: null } },
+    { ...valid, inventory_units: { id: ' ', name: null } },
+  ])(
+    'blocks a malformed linked charge even when another charge is valid',
+    (invalid) => {
+      expect(hasInvalidSubscriptionLinks([valid, invalid], products)).toBe(
+        true
+      );
+    }
+  );
+  it('blocks a disappeared catalog product', () => {
+    expect(hasInvalidSubscriptionLinks([valid], [])).toBe(true);
+  });
+});
+describe('authoritative schedule readiness', () => {
+  const ready = {
+    groupIds: ['g'],
+    scheduledSessionsByGroupId: { g: [] },
+    loading: false,
+    error: null,
+  };
+  it('distinguishes an authoritative empty list from missing data', () => {
+    expect(isSubscriptionContextReady(ready)).toBe(true);
+    expect(
+      isSubscriptionContextReady({
+        ...ready,
+        scheduledSessionsByGroupId: undefined,
+      })
+    ).toBe(false);
+    expect(
+      isSubscriptionContextReady({ ...ready, scheduledSessionsByGroupId: {} })
+    ).toBe(false);
+  });
+  it('does not authorize creation while loading or after a failed refresh with retained data', () => {
+    expect(isSubscriptionContextReady({ ...ready, loading: true })).toBe(false);
+    expect(
+      isSubscriptionContextReady({
+        ...ready,
+        error: new Error('synthetic unavailable'),
+      })
+    ).toBe(false);
+  });
+  it.each(['2026-02-30', '2026-13-01', '2026-01-01T00:00:00Z', 'not-a-date'])(
+    'rejects malformed civil schedule receipt %s',
+    (date) => {
+      expect(
+        isSubscriptionContextReady({
+          ...ready,
+          scheduledSessionsByGroupId: { g: [date] },
+        })
+      ).toBe(false);
+    }
+  );
+});

package/src/components/ui/finance/invoices/subscription-admission.ts

@@ -0,0 +1,101 @@
+import type { Product, UserGroupProducts } from './types';
+import {
+  getMonthStartDate,
+  isSubscriptionRangeFullyPaidForGroups,
+  parseLocalCalendarDate,
+  type SubscriptionCoverageInvoice,
+} from './utils';
+
+export function hasInvalidSubscriptionLinks(
+  links: UserGroupProducts[],
+  products: Product[]
+): boolean {
+  return links.some((link) => {
+    const productId = link.workspace_products?.id;
+    const unitId = link.inventory_units?.id;
+    if (
+      typeof productId !== 'string' ||
+      !productId.trim() ||
+      typeof unitId !== 'string' ||
+      !unitId.trim()
+    )
+      return true;
+    const product = products.find((item) => item.id === productId);
+    return (
+      !product ||
+      !Array.isArray(product.inventory) ||
+      !product.inventory.some((inventory) => inventory.unit_id === unitId)
+    );
+  });
+}
+
+export function isSubscriptionContextReady({
+  groupIds,
+  scheduledSessionsByGroupId,
+  loading,
+  error,
+}: {
+  groupIds: string[];
+  scheduledSessionsByGroupId?: Record<string, string[]>;
+  loading: boolean;
+  error: unknown;
+}): boolean {
+  return (
+    !loading &&
+    !error &&
+    !!scheduledSessionsByGroupId &&
+    groupIds.every(
+      (id) =>
+        Object.hasOwn(scheduledSessionsByGroupId, id) &&
+        Array.isArray(scheduledSessionsByGroupId[id]) &&
+        scheduledSessionsByGroupId[id]!.every(
+          (date) =>
+            typeof date === 'string' &&
+            /^\d{4}-\d{2}-\d{2}$/.test(date) &&
+            !Number.isNaN(parseLocalCalendarDate(date).getTime())
+        )
+    )
+  );
+}
+
+export function isSelectedSubscriptionRangePaid(
+  groupIds: string[],
+  month: string,
+  monthCount: number,
+  invoices: SubscriptionCoverageInvoice[]
+): boolean {
+  if (
+    !groupIds.length ||
+    !month ||
+    Number.isNaN(getMonthStartDate(month).getTime())
+  )
+    return false;
+  return isSubscriptionRangeFullyPaidForGroups(
+    groupIds,
+    month,
+    monthCount,
+    invoices
+  );
+}
+
+export function getSubscriptionBlockReason(
+  invalidLinks: boolean,
+  ready: boolean,
+  pending: boolean,
+  errors: unknown[],
+  groupIds: string[],
+  scheduledSessionsByGroupId?: Record<string, string[]>
+) {
+  if (invalidLinks) return 'invalid_subscription_inventory' as const;
+  if (
+    !ready ||
+    !isSubscriptionContextReady({
+      groupIds,
+      scheduledSessionsByGroupId,
+      loading: pending,
+      error: errors.some(Boolean),
+    })
+  )
+    return 'subscription_context_not_ready' as const;
+  return undefined;
+}

package/src/components/ui/finance/invoices/subscription-billing-groups.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, it } from 'vitest';
-import { mergeBillingSessionDates } from './subscription-billing-groups';
+import {
+  getBillingScheduleWindow,
+  mergeBillingSessionDates,
+} from './subscription-billing-groups';
 import { getBillableQuantityForGroupRange, type UserGroup } from './utils';
 
 describe('subscription billing session dates', () => {
@@ -44,3 +47,161 @@ describe('subscription billing session dates', () => {
     ).toBe(7);
   });
 });
+
+describe('bounded authoritative schedule responses', () => {
+  const groupId = 'bounded-class';
+  const window = { startDate: '2026-09-01', endDate: '2026-10-01' };
+  const groups: UserGroup[] = [
+    {
+      workspace_user_groups: {
+        id: groupId,
+        name: 'Synthetic class',
+        // Dates outside the requested September window are historical data.
+        sessions: ['2026-08-31', '2026-09-06', '2026-10-04'],
+      } as NonNullable<UserGroup['workspace_user_groups']>,
+    },
+  ];
+  const quantity = (userGroups: UserGroup[]) =>
+    getBillableQuantityForGroupRange({
+      groupId,
+      userGroups,
+      selectedMonth: '2026-09',
+      useAttendanceBased: false,
+      userAttendance: [],
+      now: new Date('2026-09-15T12:00:00Z'),
+      workspaceTimezone: 'Asia/Ho_Chi_Minh',
+    });
+
+  it('does not bill a removed same-window date from a nonempty authoritative response', () => {
+    // The context route queried [2026-09-01, 2026-10-01). September 6 is
+    // absent from its scheduled/cancellation-aware result, not extra billing.
+    const merged = mergeBillingSessionDates(
+      groups,
+      {
+        [groupId]: ['2026-09-05', '2026-09-12'],
+      },
+      window
+    );
+    expect(quantity(merged)).toBe(2);
+    expect(merged[0]?.workspace_user_groups?.sessions).toEqual([
+      '2026-08-31',
+      '2026-09-05',
+      '2026-09-12',
+      '2026-10-04',
+    ]);
+    expect(groups[0]?.workspace_user_groups?.sessions).toEqual([
+      '2026-08-31',
+      '2026-09-06',
+      '2026-10-04',
+    ]);
+  });
+
+  it('accepts an authoritative empty window without deleting historical dates', () => {
+    const merged = mergeBillingSessionDates(groups, { [groupId]: [] }, window);
+    expect(quantity(merged)).toBe(0);
+    expect(merged[0]?.workspace_user_groups?.sessions).toEqual([
+      '2026-08-31',
+      '2026-10-04',
+    ]);
+  });
+
+  it('retains legacy dates when no authoritative response has arrived', () => {
+    const merged = mergeBillingSessionDates(groups, undefined, window);
+    expect(quantity(merged)).toBe(1);
+    expect(merged[0]).toBe(groups[0]);
+  });
+
+  it('does not crash or acquire authority from a malformed non-array group receipt', () => {
+    const merged = mergeBillingSessionDates(
+      groups,
+      { [groupId]: {} } as unknown as Record<string, string[]>,
+      window
+    );
+    expect(quantity(merged)).toBe(1);
+    expect(merged[0]).toBe(groups[0]);
+  });
+
+  it('does not treat a missing group key as an authoritative empty result', () => {
+    const merged = mergeBillingSessionDates(groups, {}, window);
+    expect(quantity(merged)).toBe(1);
+    expect(merged[0]).toBe(groups[0]);
+  });
+});
+
+describe('prepaid civil authority boundaries', () => {
+  it.each([
+    ['2026-12', 2, '2027-02-01'],
+    ['2026-01', 12, '2027-01-01'],
+    ['2026-01', 0, '2026-02-01'],
+    ['2026-01', 99, '2027-01-01'],
+  ] as const)('bounds %s for %i prepaid months', (month, count, endDate) => {
+    expect(getBillingScheduleWindow(month, count)).toEqual({
+      startDate: `${month}-01`,
+      endDate,
+    });
+  });
+  it('rejects an invalid civil month', () => {
+    expect(getBillingScheduleWindow('2026-13', 2)).toBeUndefined();
+  });
+  it('limits authoritative replacements and incoming dates to the prepaid year-crossing window', () => {
+    const window = getBillingScheduleWindow('2026-12', 2)!;
+    const groups = [
+      {
+        workspace_user_groups: {
+          id: 'g',
+          sessions: ['2026-11-30', '2026-12-06', '2027-01-03', '2027-02-01'],
+        } as NonNullable<UserGroup['workspace_user_groups']>,
+      },
+    ];
+    const merged = mergeBillingSessionDates(
+      groups,
+      {
+        g: [
+          '2026-11-29',
+          '2026-12-05',
+          '2027-01-02',
+          '2027-01-02',
+          '2027-02-02',
+        ],
+      },
+      window
+    );
+    expect(merged[0]?.workspace_user_groups?.sessions).toEqual([
+      '2026-11-30',
+      '2026-12-05',
+      '2027-01-02',
+      '2027-02-01',
+    ]);
+    for (const workspaceTimezone of [
+      'Pacific/Honolulu',
+      'Asia/Ho_Chi_Minh',
+      'Pacific/Kiritimati',
+    ]) {
+      expect(
+        getBillableQuantityForGroupRange({
+          groupId: 'g',
+          userGroups: merged,
+          selectedMonth: '2026-12',
+          prepaidMonthCount: 2,
+          useAttendanceBased: false,
+          userAttendance: [],
+          workspaceTimezone,
+          now: new Date('2026-12-31T15:00:00Z'),
+        })
+      ).toBe(2);
+      expect(
+        getBillableQuantityForGroupRange({
+          groupId: 'g',
+          userGroups: merged,
+          selectedMonth: '2026-12',
+          prepaidMonthCount: 2,
+          useAttendanceBased: false,
+          userAttendance: [],
+          workspaceTimezone,
+          latestInvoices: [{ group_id: 'g', covered_months: ['2027-01-01'] }],
+          now: new Date('2026-12-31T15:00:00Z'),
+        })
+      ).toBe(1);
+    }
+  });
+});

package/src/components/ui/finance/invoices/subscription-billing-groups.ts

@@ -1,21 +1,60 @@
 import { useMemo } from 'react';
+import {
+  getCoverageMonths,
+  getCoverageValidUntilMonthValue,
+} from './civil-month';
 import type { UserGroup } from './utils';
 
+export type BillingScheduleWindow = { startDate: string; endDate: string };
+export function getBillingScheduleWindow(
+  month: string,
+  monthCount = 1
+): BillingScheduleWindow | undefined {
+  const months = getCoverageMonths(month, monthCount);
+  if (!months.length) return undefined;
+  return {
+    startDate: `${months[0]}-01`,
+    endDate: `${getCoverageValidUntilMonthValue(month, months.length)}-01`,
+  };
+}
+
 export function mergeBillingSessionDates(
   userGroups: UserGroup[],
-  scheduledSessionsByGroupId?: Record<string, string[]>
+  scheduledSessionsByGroupId?: Record<string, string[]>,
+  window?: BillingScheduleWindow
 ): UserGroup[] {
   return userGroups.map((membership) => {
     const group = membership.workspace_user_groups;
     if (!group) return membership;
-    const planned = scheduledSessionsByGroupId?.[group.id] ?? [];
-    if (planned.length === 0) return membership;
+    const response = scheduledSessionsByGroupId?.[group.id];
+    const planned = Array.isArray(response) ? response : [];
+    const authoritative =
+      !!window &&
+      !!scheduledSessionsByGroupId &&
+      Object.hasOwn(scheduledSessionsByGroupId, group.id) &&
+      Array.isArray(scheduledSessionsByGroupId[group.id]);
+    if (!authoritative && planned.length === 0) return membership;
     const existing = Array.isArray(group.sessions) ? group.sessions : [];
     return {
       ...membership,
       workspace_user_groups: {
         ...group,
-        sessions: Array.from(new Set([...existing, ...planned])),
+        sessions: Array.from(
+          new Set(
+            authoritative
+              ? [
+                  ...existing.filter(
+                    (date) =>
+                      date < window!.startDate || date >= window!.endDate
+                  ),
+                  ...planned.filter(
+                    (date) =>
+                      date >= window!.startDate && date < window!.endDate
+                  ),
+                ]
+              : [...existing, ...planned]
+          )
+        ).sort(),
       },
     };
   });
@@ -31,15 +70,17 @@ export function getGroupsWithScheduleIds(userGroups: UserGroup[]): string[] {
 
 export function useSubscriptionBillingGroups(
   userGroups: UserGroup[],
-  scheduledSessionsByGroupId?: Record<string, string[]>
+  scheduledSessionsByGroupId?: Record<string, string[]>,
+  window?: BillingScheduleWindow
 ) {
   const billingUserGroups = useMemo(
-    () => mergeBillingSessionDates(userGroups, scheduledSessionsByGroupId),
-    [scheduledSessionsByGroupId, userGroups]
+    () =>
+      mergeBillingSessionDates(userGroups, scheduledSessionsByGroupId, window),
+    [scheduledSessionsByGroupId, userGroups, window]
   );
   const groupsWithScheduleIds = useMemo(
-    () => getGroupsWithScheduleIds(userGroups),
-    [userGroups]
+    () => getGroupsWithScheduleIds(billingUserGroups),
+    [billingUserGroups]
   );
   return { billingUserGroups, groupsWithScheduleIds };
 }

package/src/components/ui/finance/invoices/subscription-context-actor.test.tsx

@@ -0,0 +1,246 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { act, cleanup, render, screen, waitFor } from '@testing-library/react';
+import type { SubscriptionInvoiceContextResponse } from '@tuturuuu/internal-api/finance';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  useWorkspaceActor,
+  WorkspaceVisibilityProvider,
+} from '../../../../hooks/use-workspace-visibility';
+import { useSubscriptionInvoiceContext } from './hooks';
+import { invalidateInvoiceMutationQueries } from './query-invalidation';
+
+function context(owner: string): SubscriptionInvoiceContextResponse {
+  return {
+    attendance: [{ date: '2026-09-01', status: owner }],
+    latestInvoices: [],
+    scheduledSessionsByGroupId: { 'group-1': ['2026-09-01'] },
+  };
+}
+function reply(owner: string) {
+  return new Response(JSON.stringify(context(owner)), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+function held() {
+  let resolve!: (response: Response) => void;
+  let reject!: (error: Error) => void;
+  const promise = new Promise<Response>((yes, no) => {
+    resolve = yes;
+    reject = no;
+  });
+  return { promise, resolve, reject };
+}
+const transport = vi.fn();
+let actorLease: ReturnType<typeof useWorkspaceActor>;
+function Probe({ wsId, customerId }: { wsId: string; customerId: string }) {
+  actorLease = useWorkspaceActor();
+  const query = useSubscriptionInvoiceContext(
+    wsId,
+    customerId,
+    ['group-1'],
+    '2026-09'
+  );
+  return (
+    <output aria-label="Synthetic context owner">
+      {query.data?.attendance[0]?.status ?? 'pending'}
+    </output>
+  );
+}
+function mount() {
+  // Matches satellite ClientProviders: the QueryClient survives actor remounts.
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  const view = (actor: string, wsId: string, customerId: string) => (
+    <QueryClientProvider client={client}>
+      <WorkspaceVisibilityProvider actorId={actor}>
+        <Probe wsId={wsId} customerId={customerId} />
+      </WorkspaceVisibilityProvider>
+    </QueryClientProvider>
+  );
+  const result = render(view('account-A', 'ws-1', 'customer-1'));
+  return {
+    ...result,
+    client,
+    redraw: (actor = 'account-A', ws = 'ws-1', customer = 'customer-1') =>
+      result.rerender(view(actor, ws, customer)),
+  };
+}
+async function displayed(owner: string) {
+  await waitFor(() =>
+    expect(screen.getByLabelText('Synthetic context owner')).toHaveTextContent(
+      owner
+    )
+  );
+}
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+});
+beforeEach(() => {
+  transport.mockReset();
+  transport.mockImplementation(() => Promise.resolve(reply('account-A')));
+  vi.stubGlobal('fetch', transport);
+});
+
+describe('actual subscription context transport and shared cache actor lifetime', () => {
+  it('reauthorizes a fresh account-A context after changing to account-B at identical coordinates', async () => {
+    const view = mount();
+    await displayed('account-A');
+    const expired = actorLease;
+    transport.mockImplementation(() => Promise.resolve(reply('account-B')));
+    view.redraw('account-B');
+    expect(() => expired?.assertActive()).toThrow('Workspace account changed');
+    await waitFor(() => expect(transport).toHaveBeenCalledTimes(2));
+    await displayed('account-B');
+    expect(transport.mock.calls[0]?.[0]).toContain(
+      '/api/v1/workspaces/ws-1/finance/invoices/subscription/context'
+    );
+    expect(transport.mock.calls[1]?.[1]).toEqual(
+      expect.objectContaining({
+        cache: 'no-store',
+        signal: expect.any(AbortSignal),
+      })
+    );
+  });
+  it('does not deliver an old account-A held transport into the account-B observer or cache', async () => {
+    const old = held();
+    transport
+      .mockReturnValueOnce(old.promise)
+      .mockImplementation(() => Promise.resolve(reply('account-B')));
+    const view = mount();
+    await waitFor(() => expect(transport).toHaveBeenCalledOnce());
+    const expired = actorLease;
+    view.redraw('account-B');
+    expect(() => expired?.assertActive()).toThrow('Workspace account changed');
+    await act(async () => {
+      old.resolve(reply('account-A'));
+      await old.promise;
+    });
+    await waitFor(() => expect(transport).toHaveBeenCalledTimes(2));
+    await displayed('account-B');
+    expect(
+      view.client
+        .getQueryCache()
+        .getAll()
+        .filter(
+          (entry) =>
+            entry.queryKey[0] === 'subscription-invoice-context' &&
+            entry.getObserversCount() > 0
+        )
+        .map((entry) => entry.state.data)
+    ).toEqual([context('account-B')]);
+  });
+  it('reuses fresh context inside the same actor lifetime', async () => {
+    const view = mount();
+    await displayed('account-A');
+    view.redraw();
+    await displayed('account-A');
+    expect(transport).toHaveBeenCalledOnce();
+  });
+  for (const boundary of ['workspace', 'customer'] as const) {
+    it(`keeps same-actor ${boundary} contexts distinct`, async () => {
+      const view = mount();
+      await displayed('account-A');
+      transport.mockImplementation(() =>
+        Promise.resolve(reply('other-context'))
+      );
+      view.redraw(
+        'account-A',
+        boundary === 'workspace' ? 'ws-2' : 'ws-1',
+        boundary === 'customer' ? 'customer-2' : 'customer-1'
+      );
+      await displayed('other-context');
+      expect(transport).toHaveBeenCalledTimes(2);
+      const url = new URL(transport.mock.calls[1]?.[0]);
+      expect(url.pathname).toContain(
+        boundary === 'workspace' ? '/workspaces/ws-2/' : '/workspaces/ws-1/'
+      );
+      expect(url.searchParams.get('userId')).toBe(
+        boundary === 'customer' ? 'customer-2' : 'customer-1'
+      );
+    });
+  }
+  for (const outcome of ['success', 'error'] as const) {
+    it(`isolates held old account-A ${outcome} after actor ABA`, async () => {
+      const old = held();
+      transport
+        .mockReturnValueOnce(old.promise)
+        .mockImplementation(() => Promise.resolve(reply('new-lifetime')));
+      const view = mount();
+      await waitFor(() => expect(transport).toHaveBeenCalledOnce());
+      const expired = actorLease;
+      view.redraw('account-B');
+      await displayed('new-lifetime');
+      view.redraw('account-A');
+      await displayed('new-lifetime');
+      expect(transport).toHaveBeenCalledTimes(3);
+      expect(() => expired?.assertActive()).toThrow(
+        'Workspace account changed'
+      );
+      await act(async () => {
+        if (outcome === 'success') old.resolve(reply('expired-lifetime'));
+        else old.reject(new Error('Synthetic expired transport failure'));
+        await old.promise.catch(() => {});
+      });
+      await displayed('new-lifetime');
+      const entries = view.client.getQueryCache().getAll();
+      await waitFor(() =>
+        expect(
+          entries.find(
+            (entry) => entry.getObserversCount() === 0 && entry.state.error
+          )?.state.error
+        ).toEqual(new Error('Workspace account changed'))
+      );
+      expect(
+        entries
+          .filter((entry) => entry.getObserversCount() > 0)
+          .map((entry) => entry.state.data)
+      ).toEqual([context('new-lifetime')]);
+      expect(
+        entries
+          .filter(
+            (entry) =>
+              entry.queryKey[0] === 'subscription-invoice-context' &&
+              entry.queryKey[6] === 'account-A'
+          )
+          .map((entry) => entry.queryKey[7])
+      ).toHaveLength(2);
+    });
+  }
+  it('does not admit context requests without a verified actor provider', async () => {
+    const client = new QueryClient();
+    render(
+      <QueryClientProvider client={client}>
+        <Probe wsId="ws-1" customerId="customer-1" />
+      </QueryClientProvider>
+    );
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(transport).not.toHaveBeenCalled();
+    expect(screen.getByLabelText('Synthetic context owner')).toHaveTextContent(
+      'pending'
+    );
+  });
+  it('workspace invalidation still refetches the actor-scoped context', async () => {
+    const view = mount();
+    await displayed('account-A');
+    transport.mockImplementation(() =>
+      Promise.resolve(reply('refreshed-context'))
+    );
+    await act(async () => {
+      await invalidateInvoiceMutationQueries(view.client, 'other-workspace');
+    });
+    expect(transport).toHaveBeenCalledOnce();
+    await act(async () => {
+      await invalidateInvoiceMutationQueries(view.client, 'ws-1');
+    });
+    await displayed('refreshed-context');
+    expect(transport).toHaveBeenCalledTimes(2);
+    expect(
+      view.client.getQueryCache().getAll()[0]?.queryKey.slice(0, 2)
+    ).toEqual(['subscription-invoice-context', 'ws-1']);
+  });
+});