feat(pipeline): 9→7 stage refactor + v1.1 hardening wave

Replaces the legacy 9-stage pipeline with 7 canonical stages (enquiry → qualified → eoi → reservation → deposit_paid → contract → nurturing) plus three doc sub-status columns (eoi_doc_status, reservation_doc_status, contract_doc_status) that track sent/signed within a single stage instead of branching it. Schema (migration 0062): - interests gains assigned_to, deposit_expected_amount/currency, three doc-status columns, two documenso-id columns, and date_reservation_signed. - New tables: qualification_criteria (per-port admin-configurable), interest_qualifications (per-interest state), payments (deposit / balance / refund records keyed to interest + client). - Default qualification criteria seeded for every existing port. - Dummy-data UPDATEs collapse Sent/Signed pairs and 'completed' into the new stage + doc-status + outcome shape. Migration 0063 adds interest_contact_log.voice_transcript and template_used columns for v1.1-A/B (quick-template buttons + voice transcription via Web Speech API). v1.1 phase work bundled here: - A/B: Quick-template buttons (Call / Visit / Email) + mic toggle on the contact-log compose dialog (useVoiceTranscription hook). - C: berth-rules-engine wraps state writes in pg_advisory_xact_lock with an idempotent re-read; emits rule_evaluated audit traces. - D: Documenso webhook: reservation/contract sub-status stamping moved out of the PDF-download try-block so a download failure no longer swallows the stamp. New integration test coverage. - E: /admin/qualification-criteria CRUD page + admin component. - F: default_new_interest_owner exposed in System Settings. - G: recentActivityCount + active_engagement deal-pulse signal surfaced as a chip on interests + hot-deals card. - H: interest_assigned notification on assignedTo change (skips self-assign, uses a dedupe key). Plus the supporting components: AssignedToChip, DealPulseChip, PaymentsSection, QualificationChecklist, MultiEoiChip, SkipAheadBanner, WonStatusPanel, InterestBerthStatusBanner, SupplementalInfoRequestButton, UserPicker. Tests: 1370/1370 vitest pass (added deal-health unit suite + expanded constants/validators/pipeline-transitions coverage). tsc clean, eslint clean. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-14 03:39:21 +02:00
parent b10bf9bf8e
commit 6b28459c45
110 changed files with 5402 additions and 796 deletions
--- a/src/lib/services/payments.service.ts
+++ b/src/lib/services/payments.service.ts
@@ -0,0 +1,226 @@
+/**
+ * Payment-records service. The CRM does NOT generate invoices — banks invoice
+ * clients directly. We record that money was received (or refunded) with an
+ * optional uploaded receipt for audit purposes.
+ *
+ * Auto-advance: when the running deposit total (SUM where payment_type='deposit'
+ * minus SUM of refunds) reaches `interests.depositExpectedAmount`, the pipeline
+ * stage moves to 'deposit_paid' (no-op if already past).
+ */
+
+import { and, asc, desc, eq, sql } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { interests, payments } from '@/lib/db/schema';
+import { createAuditLog, type AuditMeta } from '@/lib/audit';
+import { NotFoundError, ValidationError } from '@/lib/errors';
+import { emitToRoom } from '@/lib/socket/server';
+import type { CreatePaymentInput, UpdatePaymentInput } from '@/lib/validators/payments';
+
+// ─── Reads ──────────────────────────────────────────────────────────────────
+
+/** All payments for a single interest, newest received first. */
+export async function listPaymentsForInterest(interestId: string, portId: string) {
+  const interest = await db.query.interests.findFirst({
+    where: and(eq(interests.id, interestId), eq(interests.portId, portId)),
+    columns: { id: true },
+  });
+  if (!interest) throw new NotFoundError('Interest');
+
+  return db
+    .select()
+    .from(payments)
+    .where(and(eq(payments.interestId, interestId), eq(payments.portId, portId)))
+    .orderBy(desc(payments.receivedAt), asc(payments.id));
+}
+
+/** Net deposit total for an interest. `deposit` rows add; `refund` rows
+ *  subtract (their `amount` may be either positive or already negative — we
+ *  always treat refunds as deductions to match the UI convention). */
+export async function getDepositTotalForInterest(
+  interestId: string,
+  portId: string,
+): Promise<{ total: string; currency: string }> {
+  const rows = await db
+    .select({
+      paymentType: payments.paymentType,
+      amount: payments.amount,
+      currency: payments.currency,
+    })
+    .from(payments)
+    .where(
+      and(
+        eq(payments.interestId, interestId),
+        eq(payments.portId, portId),
+        sql`${payments.paymentType} IN ('deposit', 'refund')`,
+      ),
+    );
+
+  // Use BigInt-ish accumulator via Number — amounts are EUR scale; we don't
+  // need cent-precise math for the auto-advance gate, but we DO normalize the
+  // sign of refunds so a refund stored as "+200" still subtracts.
+  let net = 0;
+  let currency = 'EUR';
+  for (const row of rows) {
+    const n = Number(row.amount);
+    if (!Number.isFinite(n)) continue;
+    currency = row.currency;
+    net += row.paymentType === 'refund' ? -Math.abs(n) : n;
+  }
+  return { total: net.toFixed(2), currency };
+}
+
+// ─── Writes ─────────────────────────────────────────────────────────────────
+
+export async function createPayment(portId: string, data: CreatePaymentInput, meta: AuditMeta) {
+  // Resolve interest + sanity-check it belongs to this port.
+  const interest = await db.query.interests.findFirst({
+    where: and(eq(interests.id, data.interestId), eq(interests.portId, portId)),
+    columns: { id: true, clientId: true, depositExpectedAmount: true, pipelineStage: true },
+  });
+  if (!interest) throw new NotFoundError('Interest');
+
+  const amountNum = Number(data.amount);
+  if (!Number.isFinite(amountNum) || amountNum === 0) {
+    throw new ValidationError('amount must be a non-zero numeric value');
+  }
+
+  const [row] = await db
+    .insert(payments)
+    .values({
+      portId,
+      interestId: data.interestId,
+      clientId: interest.clientId,
+      paymentType: data.paymentType,
+      amount: data.amount,
+      currency: data.currency,
+      receivedAt: new Date(data.receivedAt),
+      receiptFileId: data.receiptFileId ?? null,
+      notes: data.notes ?? null,
+      recordedBy: meta.userId,
+    })
+    .returning();
+
+  void createAuditLog({
+    userId: meta.userId,
+    portId,
+    action: 'create',
+    entityType: 'payment',
+    entityId: row!.id,
+    newValue: {
+      interestId: data.interestId,
+      paymentType: data.paymentType,
+      amount: data.amount,
+      currency: data.currency,
+    },
+    ipAddress: meta.ipAddress,
+    userAgent: meta.userAgent,
+  });
+
+  emitToRoom(`port:${portId}`, 'payment:created', {
+    paymentId: row!.id,
+    interestId: data.interestId,
+    paymentType: data.paymentType,
+  });
+
+  // Auto-advance: when the running deposit total reaches the expected amount,
+  // promote the stage to 'deposit_paid'. Dynamic import keeps the
+  // payments ↔ interests cycle one-way at module-load time.
+  if (data.paymentType === 'deposit' || data.paymentType === 'refund') {
+    const { total } = await getDepositTotalForInterest(data.interestId, portId);
+    const expected = interest.depositExpectedAmount ? Number(interest.depositExpectedAmount) : null;
+    if (expected !== null && Number.isFinite(expected) && Number(total) >= expected) {
+      const { advanceStageIfBehind } = await import('@/lib/services/interests.service');
+      void advanceStageIfBehind(
+        data.interestId,
+        portId,
+        'deposit_paid',
+        meta,
+        `Deposit total (${total} ${data.currency}) reached expected amount`,
+      );
+
+      // Stamp dateDepositReceived if not already set so the timeline shows
+      // when the threshold was met (not the date of the first payment row).
+      await db
+        .update(interests)
+        .set({ dateDepositReceived: new Date(), updatedAt: new Date() })
+        .where(eq(interests.id, data.interestId));
+
+      // Berth rule fires via the same hook the legacy invoices.ts path uses.
+      const { evaluateRule } = await import('@/lib/services/berth-rules-engine');
+      void evaluateRule('deposit_received', data.interestId, portId, meta);
+    }
+  }
+
+  return row!;
+}
+
+export async function updatePayment(
+  id: string,
+  portId: string,
+  data: UpdatePaymentInput,
+  meta: AuditMeta,
+) {
+  const existing = await db.query.payments.findFirst({
+    where: and(eq(payments.id, id), eq(payments.portId, portId)),
+  });
+  if (!existing) throw new NotFoundError('Payment');
+
+  const next: Record<string, unknown> = {};
+  if (data.paymentType !== undefined) next.paymentType = data.paymentType;
+  if (data.amount !== undefined) next.amount = data.amount;
+  if (data.currency !== undefined) next.currency = data.currency;
+  if (data.receivedAt !== undefined) next.receivedAt = new Date(data.receivedAt);
+  if (data.receiptFileId !== undefined) next.receiptFileId = data.receiptFileId;
+  if (data.notes !== undefined) next.notes = data.notes;
+
+  const [updated] = await db
+    .update(payments)
+    .set(next)
+    .where(and(eq(payments.id, id), eq(payments.portId, portId)))
+    .returning();
+
+  void createAuditLog({
+    userId: meta.userId,
+    portId,
+    action: 'update',
+    entityType: 'payment',
+    entityId: id,
+    oldValue: {
+      paymentType: existing.paymentType,
+      amount: existing.amount,
+      currency: existing.currency,
+    },
+    newValue: next,
+    ipAddress: meta.ipAddress,
+    userAgent: meta.userAgent,
+  });
+
+  return updated!;
+}
+
+export async function deletePayment(id: string, portId: string, meta: AuditMeta) {
+  const existing = await db.query.payments.findFirst({
+    where: and(eq(payments.id, id), eq(payments.portId, portId)),
+  });
+  if (!existing) throw new NotFoundError('Payment');
+
+  await db.delete(payments).where(and(eq(payments.id, id), eq(payments.portId, portId)));
+
+  void createAuditLog({
+    userId: meta.userId,
+    portId,
+    action: 'delete',
+    entityType: 'payment',
+    entityId: id,
+    oldValue: {
+      paymentType: existing.paymentType,
+      amount: existing.amount,
+      currency: existing.currency,
+    },
+    ipAddress: meta.ipAddress,
+    userAgent: meta.userAgent,
+  });
+
+  return { ok: true };
+}