Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,331 @@
/**
* Admin marketing-funnel lead detail (Phase 05 #78, layer 4).
*
* Shows the full lead profile, status transition buttons (forward/back through
* the new→contacted→qualified→trial→customer state-machine, with churned and
* disqualified terminal branches), an inline notes editor, and the LeadEvent
* activity timeline (captures, status changes, notes, conversion).
*/
import {
ActionFunctionArgs,
Form,
Link,
LoaderFunctionArgs,
redirect,
useActionData,
useLoaderData,
} from "react-router";
import { useTranslation } from "react-i18next";
import { LeadStatus } from "@toolctrl/db/prisma-browser";
import { adminPath } from "~/utils/app/CanonicalUrlUtils";
import {
appendNote,
getLead,
updateLeadStatus,
} from "~/utils/leads/leads.db.server";
import { verifyUserHasPermission } from "~/utils/helpers/.server/PermissionsService";
import { getUserInfo } from "~/utils/session.server";
import { convertLeadToTenant, LeadConversionDisabledError, LeadNotFoundError } from "~/utils/leads/convertLead.server";
import { getAvailableTenantSlug } from "~/utils/services/tenantService";
import { getAvailableTenantInboundAddress } from "~/utils/services/emailService";
import { createScopedLogger } from "~/utils/logger.server";
import { getTranslations } from "~/locale/i18next.server";
import { useLocaleFormatters } from "~/locale/format";
const adminLeadLogger = createScopedLogger("admin.marketing-leads");
const STATUSES: LeadStatus[] = ["new", "contacted", "qualified", "trial", "customer", "churned", "disqualified"];
const STATUS_COLOR: Record<LeadStatus, string> = {
new: "bg-blue-100 text-blue-800",
contacted: "bg-sky-100 text-sky-800",
qualified: "bg-violet-100 text-violet-800",
trial: "bg-amber-100 text-amber-800",
customer: "bg-emerald-100 text-emerald-800",
churned: "bg-rose-100 text-rose-800",
disqualified: "bg-gray-100 text-gray-700",
};
type Loader = Awaited<ReturnType<typeof loader>>;
type LoaderData = Loader extends Response ? never : Loader;
export const loader = async ({ params, request }: LoaderFunctionArgs) => {
await verifyUserHasPermission(request, "admin.marketing.leads.view");
const id = params.id;
if (!id) throw new Response(null, { status: 404 });
const lead = await getLead(id);
if (!lead) throw new Response(null, { status: 404 });
return { lead };
};
export const action = async ({ params, request }: ActionFunctionArgs) => {
await verifyUserHasPermission(request, "admin.marketing.leads.manage");
const { t } = await getTranslations(request);
const id = params.id;
if (!id) throw new Response(null, { status: 404 });
const form = await request.formData();
const op = form.get("op")?.toString();
const user = await getUserInfo(request);
if (op === "status") {
const next = form.get("status")?.toString();
if (!next || !STATUSES.includes(next as LeadStatus)) {
return { error: t("admin.marketingLeads.errors.invalidStatus") };
}
await updateLeadStatus(id, next as LeadStatus, user.userId);
return redirect(`${adminPath("marketing-leads", { mode: "host-aware" })}/${id}`);
}
if (op === "note") {
const body = (form.get("body")?.toString() ?? "").trim();
if (!body) return { error: t("admin.marketingLeads.errors.noteRequired") };
await appendNote(id, body, user.userId);
return redirect(`${adminPath("marketing-leads", { mode: "host-aware" })}/${id}`);
}
if (op === "convert") {
// Phase 2 (Phase 05 #79): admin-override conversion. Looks up the lead,
// resolves a unique slug + inbound address, then invokes the atomic
// conversion service. Already-converted leads return success silently.
const lead = await getLead(id);
if (!lead) return { error: t("admin.marketingLeads.errors.leadNotFound") };
if (lead.convertedToTenantId) {
return redirect(`${adminPath("marketing-leads", { mode: "host-aware" })}/${id}`);
}
const planIdRaw = form.get("planId")?.toString().trim();
const tenantNameRaw = form.get("tenantName")?.toString().trim();
const tenantName =
tenantNameRaw && tenantNameRaw.length > 0
? tenantNameRaw
: (lead.company?.trim() || `${(lead.firstName ?? "Lead").trim()} ${(lead.lastName ?? lead.email).trim()}`).slice(0, 80);
const slug = await getAvailableTenantSlug({ name: tenantName });
const inboundAddress = await getAvailableTenantInboundAddress(tenantName);
try {
await convertLeadToTenant({
leadId: id,
targetStatus: "trial",
conversionPath: "admin-override",
actorId: user.userId,
planId: planIdRaw && planIdRaw.length > 0 ? planIdRaw : null,
tenant: { name: tenantName, slug, inboundAddress },
});
} catch (err) {
if (err instanceof LeadConversionDisabledError) {
return { error: t("admin.marketingLeads.errors.conversionDisabled") };
}
if (err instanceof LeadNotFoundError) {
return { error: t("admin.marketingLeads.errors.leadNotFound") };
}
adminLeadLogger.error(
{ op: "convert", leadId: id, err: { name: (err as Error).name, message: "[redacted]" } },
"admin lead-to-tenant conversion failed"
);
return { error: t("admin.marketingLeads.errors.conversionFailed") };
}
// Fall back to an audit event in the lead timeline; the conversion
// service already wrote the canonical `converted` LeadEvent so this is
// intentionally NOT another appendLeadEvent call.
return redirect(`${adminPath("marketing-leads", { mode: "host-aware" })}/${id}`);
}
return { error: t("admin.marketingLeads.errors.unknownOperation") };
};
export default function LeadDetail() {
const { lead } = useLoaderData() as LoaderData;
const actionData = useActionData() as { error?: string } | undefined;
const { t } = useTranslation();
const formatters = useLocaleFormatters();
const fullName = [lead.firstName, lead.lastName].filter(Boolean).join(" ");
const notSet = t("shared.notSet");
const notesBody = ((lead.notes ?? null) as { body?: string } | null)?.body ?? "";
return (
<div className="mx-auto mb-12 max-w-5xl space-y-5 px-4 py-4 sm:px-6 lg:px-8">
<div className="border-border flex items-center justify-between border-b pb-5">
<div>
<div className="text-muted-foreground text-xs uppercase">
<Link
to={adminPath("marketing-leads", { mode: "host-aware" })}
className="hover:underline"
>
{t("admin.marketingLeads.title")}
</Link>
</div>
<h1 className="text-lg font-medium leading-6">{lead.email}</h1>
<div className="text-muted-foreground mt-1 text-sm">
{fullName || notSet} {lead.company ? `· ${lead.company}` : ""}
</div>
</div>
<span className={`rounded px-2 py-1 text-xs ${STATUS_COLOR[lead.status]}`}>{t(`admin.marketingLeads.statuses.${lead.status}`)}</span>
</div>
{actionData?.error ? (
<div className="rounded-md border border-rose-200 bg-rose-50 px-3 py-2 text-sm text-rose-900">
{actionData.error}
</div>
) : null}
<div className="grid gap-4 sm:grid-cols-2">
<section className="space-y-2 rounded-md border p-4">
<h2 className="text-sm font-medium uppercase tracking-wide">
{t("admin.marketingLeads.detail.profile")}
</h2>
<dl className="grid grid-cols-2 gap-x-3 gap-y-1 text-sm">
<dt className="text-muted-foreground">{t("admin.marketingLeads.col.email")}</dt>
<dd>{lead.email}</dd>
<dt className="text-muted-foreground">{t("admin.marketingLeads.col.name")}</dt>
<dd>{fullName || notSet}</dd>
<dt className="text-muted-foreground">{t("admin.marketingLeads.col.company")}</dt>
<dd>{lead.company ?? notSet}</dd>
<dt className="text-muted-foreground">{t("admin.marketingLeads.detail.phone")}</dt>
<dd>{lead.phone ?? notSet}</dd>
<dt className="text-muted-foreground">{t("admin.marketingLeads.col.source")}</dt>
<dd>{lead.source ?? notSet}</dd>
<dt className="text-muted-foreground">{t("admin.marketingLeads.detail.score")}</dt>
<dd>{formatters.number(lead.score)}</dd>
</dl>
</section>
<section className="space-y-2 rounded-md border p-4">
<h2 className="text-sm font-medium uppercase tracking-wide">
{t("admin.marketingLeads.detail.attribution")}
</h2>
<dl className="grid grid-cols-2 gap-x-3 gap-y-1 text-sm">
<dt className="text-muted-foreground">utm_source</dt>
<dd>{lead.utmSource ?? notSet}</dd>
<dt className="text-muted-foreground">utm_medium</dt>
<dd>{lead.utmMedium ?? notSet}</dd>
<dt className="text-muted-foreground">utm_campaign</dt>
<dd>{lead.utmCampaign ?? notSet}</dd>
<dt className="text-muted-foreground">utm_term</dt>
<dd>{lead.utmTerm ?? notSet}</dd>
<dt className="text-muted-foreground">utm_content</dt>
<dd>{lead.utmContent ?? notSet}</dd>
<dt className="text-muted-foreground">gclid</dt>
<dd className="truncate">{lead.gclid ?? notSet}</dd>
<dt className="text-muted-foreground">fbclid</dt>
<dd className="truncate">{lead.fbclid ?? notSet}</dd>
<dt className="text-muted-foreground">{t("admin.marketingLeads.detail.referrer")}</dt>
<dd className="truncate">{lead.referrer ?? notSet}</dd>
<dt className="text-muted-foreground">{t("admin.marketingLeads.detail.landingPage")}</dt>
<dd className="truncate">{lead.landingPage ?? notSet}</dd>
<dt className="text-muted-foreground">{t("admin.marketingLeads.detail.firstSeen")}</dt>
<dd>{formatters.dateTime(lead.firstSeenAt, { dateStyle: "medium", timeStyle: "short" })}</dd>
</dl>
</section>
</div>
<section className="space-y-2 rounded-md border p-4">
<h2 className="text-sm font-medium uppercase tracking-wide">
{t("admin.marketingLeads.detail.statusTransition")}
</h2>
<Form method="post" className="flex flex-wrap items-center gap-2">
<input type="hidden" name="op" value="status" />
{STATUSES.map((s) => (
<button
key={s}
type="submit"
name="status"
value={s}
disabled={lead.status === s}
className={`rounded-md border px-3 py-1 text-sm ${
lead.status === s ? "cursor-not-allowed opacity-50" : "hover:bg-muted"
} ${STATUS_COLOR[s]}`}
>
{t(`admin.marketingLeads.statuses.${s}`)}
</button>
))}
</Form>
{lead.status !== "customer" && !lead.convertedToTenantId ? (
<Form
method="post"
className="space-y-2 border-t border-dashed pt-3"
onSubmit={(e) => {
// Native confirm dialog is sufficient — the conversion is
// a server-side atomic transaction so accidental clicks are
// recoverable via Tenant.deactivate. No need for a modal.
if (!window.confirm(t("admin.marketingLeads.detail.confirmCreateTenant"))) {
e.preventDefault();
}
}}
>
<input type="hidden" name="op" value="convert" />
<div className="flex flex-wrap items-end gap-2">
<label className="space-y-1 text-xs text-muted-foreground">
<span>{t("admin.marketingLeads.detail.tenantName")}</span>
<input
type="text"
name="tenantName"
defaultValue={lead.company ?? ""}
placeholder={t("admin.marketingLeads.detail.tenantNamePlaceholder")}
className="border-border block w-56 rounded-md border px-2 py-1 text-sm"
/>
</label>
<label className="space-y-1 text-xs text-muted-foreground">
<span>{t("admin.marketingLeads.detail.planIdOptional")}</span>
<input
type="text"
name="planId"
placeholder={t("admin.marketingLeads.detail.planIdPlaceholder")}
className="border-border block w-56 rounded-md border px-2 py-1 text-sm"
/>
</label>
<button
type="submit"
className="rounded-md bg-emerald-600 px-3 py-1.5 text-sm text-white hover:bg-emerald-700"
>
{t("admin.marketingLeads.detail.convertToTenant")}
</button>
</div>
</Form>
) : null}
{lead.convertedToTenantId ? (
<div className="rounded-md border border-emerald-200 bg-emerald-50 px-2 py-1 text-xs text-emerald-900">
{t("admin.marketingLeads.detail.convertedToTenant", { tenantId: lead.convertedToTenantId })}
</div>
) : null}
</section>
<section className="space-y-2 rounded-md border p-4">
<h2 className="text-sm font-medium uppercase tracking-wide">
{t("admin.marketingLeads.detail.notes")}
</h2>
<Form method="post" className="space-y-2">
<input type="hidden" name="op" value="note" />
<textarea
name="body"
defaultValue={notesBody}
rows={4}
className="border-border w-full rounded-md border px-3 py-2 text-sm"
/>
<button type="submit" className="bg-primary text-primary-foreground rounded-md px-3 py-1.5 text-sm">
{t("admin.marketingLeads.detail.saveNote")}
</button>
</Form>
</section>
<section className="space-y-2 rounded-md border p-4">
<h2 className="text-sm font-medium uppercase tracking-wide">
{t("admin.marketingLeads.detail.timeline")}
</h2>
{lead.events.length === 0 ? (
<p className="text-muted-foreground text-sm">{t("admin.marketingLeads.detail.timelineEmpty")}</p>
) : (
<ul className="divide-border divide-y">
{lead.events.map((ev) => (
<li key={ev.id} className="flex items-start justify-between py-2 text-sm">
<div>
<div className="font-medium">{t(`admin.marketingLeads.events.${ev.type}`, { defaultValue: ev.type })}</div>
<pre className="text-muted-foreground mt-1 whitespace-pre-wrap text-xs">
{JSON.stringify(ev.payload, null, 2)}
</pre>
</div>
<div className="text-muted-foreground shrink-0 text-xs">
{formatters.dateTime(ev.createdAt, { dateStyle: "medium", timeStyle: "short" })}
</div>
</li>
))}
</ul>
)}
</section>
</div>
);
}
@@ -0,0 +1,224 @@
/**
* Admin marketing-funnel lead inbox — list view (Phase 05 #78).
*
* GET /admin/marketing-leads with optional ?status=&source=&search=&page=
* query parameters. Renders a filterable table with the seven funnel-stage
* badges as filter shortcuts and a search box matching email/name/company.
*/
import { Form, Link, LoaderFunctionArgs, useLoaderData, useSearchParams } from "react-router";
import { useTranslation } from "react-i18next";
import { LeadStatus } from "@toolctrl/db/prisma-browser";
import { createAuditEvent } from "@toolctrl/db/audit-events.server";
import { adminPath } from "~/utils/app/CanonicalUrlUtils";
import { LEAD_EXPORT_MAX, listLeads, listLeadsForExport, type LeadListResult } from "~/utils/leads/leads.db.server";
import { leadsCsvFilename, serializeLeadsCsv } from "~/utils/leads/leadsCsv";
import { verifyUserHasPermission } from "~/utils/helpers/.server/PermissionsService";
import { getUserInfo } from "~/utils/session.server";
import { useLocaleFormatters } from "~/locale/format";
import { db } from "~/utils/db.server";
type LoaderData = LeadListResult & {
filters: { status: string | null; source: string | null; search: string | null };
statusCounts: Record<LeadStatus | "all", number>;
};
const STATUSES: LeadStatus[] = ["new", "contacted", "qualified", "trial", "customer", "churned", "disqualified"];
function parseStatus(value: string | null): LeadStatus | undefined {
if (!value) return undefined;
return STATUSES.includes(value as LeadStatus) ? (value as LeadStatus) : undefined;
}
export const loader = async ({ request }: LoaderFunctionArgs) => {
await verifyUserHasPermission(request, "admin.marketing.leads.view");
const url = new URL(request.url);
const status = parseStatus(url.searchParams.get("status"));
const source = url.searchParams.get("source") ?? undefined;
const search = url.searchParams.get("search") ?? undefined;
if (url.searchParams.get("export") === "csv") {
const rows = await listLeadsForExport({ status, source, search });
const csv = serializeLeadsCsv(rows);
const actor = await getUserInfo(request);
await createAuditEvent({
action: "admin.marketing.leads.csv_export",
actorType: "admin",
actorId: actor.userId ?? null,
targetType: "lead",
dataSensitivity: "pii",
regulatoryScope: ["gdpr"],
sourceModule: "admin.marketing-leads",
metadata: {
rowCount: rows.length,
truncated: rows.length >= LEAD_EXPORT_MAX,
filters: {
status: status ?? null,
source: source ?? null,
search: search ?? null,
},
},
});
return new Response(csv, {
headers: {
"Content-Type": "text/csv; charset=utf-8",
"Content-Disposition": `attachment; filename="${leadsCsvFilename()}"`,
"Cache-Control": "no-store",
},
});
}
const page = Math.max(1, Number(url.searchParams.get("page") ?? "1"));
const list = await listLeads({ status, source, search, page });
const grouped = await db.lead.groupBy({ by: ["status"], _count: { _all: true } });
const counts: Record<string, number> = { all: 0 };
for (const s of STATUSES) counts[s] = 0;
for (const g of grouped) {
counts[g.status] = g._count._all;
counts.all += g._count._all;
}
const data: LoaderData = {
...list,
filters: {
status: url.searchParams.get("status"),
source: url.searchParams.get("source"),
search: url.searchParams.get("search"),
},
statusCounts: counts as Record<LeadStatus | "all", number>,
};
return Response.json(data);
};
const STATUS_COLOR: Record<LeadStatus, string> = {
new: "bg-blue-100 text-blue-800",
contacted: "bg-sky-100 text-sky-800",
qualified: "bg-violet-100 text-violet-800",
trial: "bg-amber-100 text-amber-800",
customer: "bg-emerald-100 text-emerald-800",
churned: "bg-rose-100 text-rose-800",
disqualified: "bg-gray-100 text-gray-700",
};
export default function MarketingLeadsIndex() {
const data = useLoaderData<LoaderData>();
const [params] = useSearchParams();
const { t } = useTranslation();
const formatters = useLocaleFormatters();
const totalPages = Math.max(1, Math.ceil(data.total / data.pageSize));
const notSet = t("shared.notSet");
function filterLink(status: LeadStatus | null) {
const next = new URLSearchParams(params);
if (status) next.set("status", status);
else next.delete("status");
next.delete("page");
return `${adminPath("marketing-leads", { mode: "host-aware" })}?${next.toString()}`;
}
const exportHref = (() => {
const next = new URLSearchParams(params);
next.delete("page");
next.set("export", "csv");
return `${adminPath("marketing-leads", { mode: "host-aware" })}?${next.toString()}`;
})();
return (
<div className="mx-auto mb-12 max-w-7xl space-y-5 px-4 py-4 sm:px-6 lg:px-8">
<div className="border-border flex flex-col gap-2 border-b pb-5 sm:flex-row sm:items-center sm:justify-between">
<div>
<h1 className="text-lg font-medium leading-6">{t("admin.marketingLeads.title")}</h1>
<p className="text-muted-foreground mt-1 text-sm">{t("admin.marketingLeads.subtitle")}</p>
</div>
<div className="flex items-center gap-3">
<div className="text-muted-foreground text-sm">
{t("admin.marketingLeads.totalLeads", { count: data.statusCounts.all, formattedCount: formatters.number(data.statusCounts.all) })}
</div>
<a
href={exportHref}
download
className="hover:bg-muted rounded-md border px-3 py-1 text-sm"
data-testid="leads-export-csv"
>
{t("admin.marketingLeads.exportCsv")}
</a>
</div>
</div>
<div className="flex flex-wrap items-center gap-2">
<Link to={filterLink(null)} className={`rounded-md border px-3 py-1 text-sm ${!data.filters.status ? "bg-secondary" : "hover:bg-muted"}`}>
{t("shared.all")} <span className="text-muted-foreground">({formatters.number(data.statusCounts.all)})</span>
</Link>
{STATUSES.map((s) => (
<Link key={s} to={filterLink(s)} className={`rounded-md border px-3 py-1 text-sm ${data.filters.status === s ? "bg-secondary" : "hover:bg-muted"}`}>
<span className={`mr-1 inline-block rounded px-1.5 py-0.5 text-xs ${STATUS_COLOR[s]}`}>{t(`admin.marketingLeads.statuses.${s}`)}</span>
<span className="text-muted-foreground">({formatters.number(data.statusCounts[s] ?? 0)})</span>
</Link>
))}
</div>
<Form method="get" className="flex flex-wrap items-center gap-2">
{data.filters.status ? <input type="hidden" name="status" value={data.filters.status} /> : null}
<input name="search" defaultValue={data.filters.search ?? ""} placeholder={t("admin.marketingLeads.searchPlaceholder")} className="border-border w-full max-w-md rounded-md border px-3 py-1.5 text-sm" />
<input name="source" defaultValue={data.filters.source ?? ""} placeholder={t("admin.marketingLeads.sourcePlaceholder")} className="border-border w-48 rounded-md border px-3 py-1.5 text-sm" />
<button type="submit" className="bg-primary text-primary-foreground rounded-md px-3 py-1.5 text-sm">{t("shared.filter")}</button>
</Form>
<div className="overflow-hidden rounded-md border">
<table className="w-full text-sm">
<thead className="bg-muted/40 text-muted-foreground text-xs uppercase">
<tr>
<th className="px-3 py-2 text-left">{t("admin.marketingLeads.col.email")}</th>
<th className="px-3 py-2 text-left">{t("admin.marketingLeads.col.name")}</th>
<th className="px-3 py-2 text-left">{t("admin.marketingLeads.col.company")}</th>
<th className="px-3 py-2 text-left">{t("admin.marketingLeads.col.source")}</th>
<th className="px-3 py-2 text-left">{t("admin.marketingLeads.col.status")}</th>
<th className="px-3 py-2 text-left">{t("admin.marketingLeads.col.utm")}</th>
<th className="px-3 py-2 text-left">{t("admin.marketingLeads.col.created")}</th>
</tr>
</thead>
<tbody>
{data.items.length === 0 ? (
<tr><td colSpan={7} className="text-muted-foreground px-3 py-6 text-center">{t("admin.marketingLeads.empty")}</td></tr>
) : (
data.items.map((row) => (
<tr key={row.id} className="border-border hover:bg-muted/30 border-t">
<td className="px-3 py-2"><Link to={`${adminPath("marketing-leads", { mode: "host-aware" })}/${row.id}`} className="text-primary hover:underline">{row.email}</Link></td>
<td className="px-3 py-2">{[row.firstName, row.lastName].filter(Boolean).join(" ") || notSet}</td>
<td className="px-3 py-2">{row.company ?? notSet}</td>
<td className="px-3 py-2">{row.source ?? notSet}</td>
<td className="px-3 py-2">
<span className={`rounded px-1.5 py-0.5 text-xs ${STATUS_COLOR[row.status]}`}>{t(`admin.marketingLeads.statuses.${row.status}`)}</span>
</td>
<td className="text-muted-foreground px-3 py-2 text-xs">{[row.utmSource, row.utmCampaign].filter(Boolean).join(" / ") || notSet}</td>
<td className="text-muted-foreground px-3 py-2 text-xs">
{formatters.dateTime(row.createdAt, { dateStyle: "medium", timeStyle: "short" })}
</td>
</tr>
))
)}
</tbody>
</table>
</div>
{totalPages > 1 ? (
<div className="flex items-center justify-between text-sm">
<div className="text-muted-foreground">
{t("admin.marketingLeads.pagination", {
page: data.page,
total: totalPages,
formattedPage: formatters.number(data.page),
formattedTotal: formatters.number(totalPages),
})}
</div>
<div className="flex gap-2">
{data.page > 1 ? (
<Link to={(() => { const next = new URLSearchParams(params); next.set("page", String(data.page - 1)); return `?${next.toString()}`; })()} className="hover:bg-muted rounded-md border px-3 py-1">{t("shared.previous")}</Link>
) : null}
{data.page < totalPages ? (
<Link to={(() => { const next = new URLSearchParams(params); next.set("page", String(data.page + 1)); return `?${next.toString()}`; })()} className="hover:bg-muted rounded-md border px-3 py-1">{t("shared.next")}</Link>
) : null}
</div>
</div>
) : null}
</div>
);
}