add subscription upgrade plan

apps/api/src/modules/admin/admin.billing.service.ts

@@ -568,6 +568,7 @@ export async function getBillingAccountDetail(companyId: string) {
             },
           },
           taxRecords: true,
+          subscriptionUpgradeRequest: { select: { id: true, status: true } },
           creditNotes: { orderBy: { createdAt: 'desc' } },
           refunds: { orderBy: { createdAt: 'desc' } },
         },

apps/api/src/modules/admin/admin.manual-payments.service.ts

@@ -335,6 +335,9 @@ export async function confirmManualPayment(invoiceId: string, data: {
         },
       })
       if (!current) throw new NotFoundError('Invoice not found')
+      if (current.invoiceType === 'SUBSCRIPTION_UPGRADE') {
+        throw new ValidationError('Subscription upgrade invoices must be approved through the upgrade review workflow')
+      }
 
       const duplicate = await tx.billingPaymentAttempt.findFirst({
         where: { billingAccountId: current.billingAccountId, idempotencyKey: data.idempotencyKey },

apps/api/src/modules/admin/admin.routes.ts

@@ -8,6 +8,7 @@ import * as subService from '../subscriptions/subscription.service'
 import * as menuService from '../menu/menu.service'
 import * as manualPaymentsService from './admin.manual-payments.service'
 import * as collectionsService from '../subscriptions/subscription.collections.service'
+import * as upgradeService from '../subscriptions/subscription.upgrade.service'
 import { getAdminNotificationInbox, markAdminNotificationRead } from '../../services/notificationService'
 import { presentAdminUser } from './admin.presenter'
 import {
@@ -26,6 +27,7 @@ import {
   menuPreviewSchema, menuAuditLogQuerySchema, menuPlanParamSchema, menuCompanyParamSchema,
   manualPaymentSubmissionIdParamSchema, manualPaymentDocumentParamsSchema,
   manualPaymentSubmissionsQuerySchema, rejectManualPaymentSubmissionSchema, confirmManualPaymentSchema,
+  upgradeRequestsQuerySchema, upgradeRequestIdParamSchema, upgradeCorrectionSchema, upgradeRejectSchema, approveUpgradePaymentSchema,
   collectionsQuerySchema, collectionsCaseIdParamSchema, collectionTaskIdParamSchema,
   collectionsOverrideParamsSchema, collectionsAssigneeSchema, collectionTaskOutcomeSchema, collectionsOverrideSchema,
 } from './admin.schemas'
@@ -403,6 +405,43 @@ router.post('/billing/invoices/:invoiceId/manual-payments', requireAdminAuth, re
   } catch (err) { next(err) }
 })
 
+router.get('/billing/upgrade-requests', requireAdminAuth, requireAdminRole('FINANCE'), async (req, res, next) => {
+  try {
+    const { status } = parseQuery(upgradeRequestsQuerySchema, req)
+    ok(res, await upgradeService.listAdminUpgradeRequests(status))
+  } catch (err) { next(err) }
+})
+
+router.post('/billing/upgrade-requests/:requestId/request-correction', requireAdminAuth, requireAdminRole('FINANCE'), async (req, res, next) => {
+  try {
+    const { requestId } = parseParams(upgradeRequestIdParamSchema, req)
+    const { reason } = parseBody(upgradeCorrectionSchema, req)
+    ok(res, await upgradeService.requestUpgradeCorrection(requestId, reason, req.admin.id, req.ip))
+  } catch (err) { next(err) }
+})
+
+router.post('/billing/upgrade-requests/:requestId/reject-payment', requireAdminAuth, requireAdminRole('FINANCE'), async (req, res, next) => {
+  try {
+    const { requestId } = parseParams(upgradeRequestIdParamSchema, req)
+    const { reason } = parseBody(upgradeRejectSchema, req)
+    ok(res, await upgradeService.rejectUpgradePayment(requestId, reason, req.admin.id, req.ip))
+  } catch (err) { next(err) }
+})
+
+router.post('/billing/upgrade-requests/:requestId/approve-payment', requireAdminAuth, requireAdminRole('FINANCE'), requireFreshAdmin2FA, async (req, res, next) => {
+  try {
+    const { requestId } = parseParams(upgradeRequestIdParamSchema, req)
+    ok(res, await upgradeService.approveUpgradePayment(requestId, parseBody(approveUpgradePaymentSchema, req), req.admin.id, req.ip))
+  } catch (err) { next(err) }
+})
+
+router.post('/billing/upgrade-requests/:requestId/retry-activation', requireAdminAuth, requireAdminRole('FINANCE'), requireFreshAdmin2FA, async (req, res, next) => {
+  try {
+    const { requestId } = parseParams(upgradeRequestIdParamSchema, req)
+    ok(res, await upgradeService.retryUpgradeActivation(requestId, req.admin.id, req.ip))
+  } catch (err) { next(err) }
+})
+
 router.get('/billing/collections', requireAdminAuth, requireAdminRole('FINANCE'), async (req, res, next) => {
   try { ok(res, await collectionsService.listCollectionsCases(parseQuery(collectionsQuerySchema, req))) } catch (err) { next(err) }
 })

apps/api/src/modules/admin/admin.schemas.ts

@@ -332,6 +332,45 @@ export const confirmManualPaymentSchema = z.object({
   fundsVerified: z.literal(true),
 })
 
+export const upgradeRequestsQuerySchema = z.object({
+  status: z.enum([
+    'DRAFT',
+    'QUOTED',
+    'PAYMENT_PENDING',
+    'PAYMENT_REVIEW',
+    'CORRECTION_REQUIRED',
+    'APPROVED',
+    'ACTIVATED',
+    'SCHEDULED',
+    'REJECTED',
+    'EXPIRED',
+    'CANCELLED',
+    'ACTIVATION_FAILED',
+    'SUPERSEDED',
+  ]).optional(),
+})
+
+export const upgradeRequestIdParamSchema = z.object({ requestId: z.string().min(1) })
+
+export const upgradeCorrectionSchema = z.object({
+  reason: z.string().trim().min(3).max(500),
+})
+
+export const upgradeRejectSchema = z.object({
+  reason: z.string().trim().min(3).max(500),
+})
+
+export const approveUpgradePaymentSchema = z.object({
+  submissionId: z.string().min(1),
+  method: z.enum(['BANK_TRANSFER', 'CHECK']),
+  externalReference: manualPaymentReferenceSchema,
+  amount: z.number().int().positive(),
+  receivedAt: z.string().datetime(),
+  note: z.string().trim().max(500).optional(),
+  idempotencyKey: z.string().uuid(),
+  fundsVerified: z.literal(true),
+})
+
 export const collectionsQuerySchema = z.object({
   status: z.enum(['SCHEDULED', 'PRE_DUE', 'GRACE_PERIOD', 'RESOLVED', 'SUSPENDED']).optional(),
   assignedTo: z.string().optional(),