feat: add referral conversion report

scripts/api-integration-test.js

@@ -10204,6 +10204,49 @@ async function testReferralAndCrmGrowth() {
   assert.equal(agentCommissionSummary.item?.grossAmountCents >= 2990, true, 'agent commission summary should include gross amount');
   assert.equal(agentCommissionSummary.item?.commissionAmountCents >= 1217, true, 'agent commission should apply member and batch rates');
 
+  const conversionReport = await request('/api/referral/conversion-report', {
+    userId: TENANT_ADMIN_USER_ID,
+    query: { startDate: today, endDate: today, referrerUserId: TENANT_AGENT_USER_ID, limit: 10 },
+  });
+  assert.equal(conversionReport.item?.range?.referrerUserId, TENANT_AGENT_USER_ID, 'conversion report should support referrer filter');
+  assert.equal(conversionReport.item?.summary?.leadCount >= 1, true, 'conversion report should include protected leads');
+  assert.equal(conversionReport.item?.summary?.paidSourceCount >= 2, true, 'conversion report should include paid order and activation code');
+  assert.equal(conversionReport.item?.summary?.grossAmountCents >= 2990, true, 'conversion report should include gross amount');
+  assert.equal(conversionReport.item?.summary?.commissionAmountCents >= 1217, true, 'conversion report should reuse commission rate precedence');
+  assert.equal(conversionReport.item?.summary?.conversionRate > 0, true, 'conversion report should calculate conversion rate');
+  assert.ok(conversionReport.item?.byReferrer?.some(item => item.referrerUserId === TENANT_AGENT_USER_ID), 'conversion report should group by referrer');
+  assert.ok(conversionReport.item?.dailyTrend?.some(item => item.date === today && Number(item.paidSourceCount || 0) >= 2), 'conversion report should include daily paid sources');
+  assert.ok(conversionReport.item?.funnel?.some(item => item.key === 'converted'), 'conversion report should include funnel summary');
+  assert.ok(!JSON.stringify(conversionReport).includes('crm-secret-smoke'), 'conversion report must not leak CRM secret');
+
+  const agentConversionReport = await request('/api/referral/conversion-report', {
+    userId: TENANT_AGENT_USER_ID,
+    query: { startDate: today, endDate: today },
+  });
+  assert.equal(agentConversionReport.item?.range?.referrerUserId, TENANT_AGENT_USER_ID, 'agent conversion report should be scoped to self');
+  assert.ok(agentConversionReport.item?.byReferrer?.every(item => item.referrerUserId === TENANT_AGENT_USER_ID), 'agent conversion report should not expose other referrers');
+
+  const agentOtherConversionDenied = await request('/api/referral/conversion-report', {
+    userId: TENANT_AGENT_USER_ID,
+    query: { startDate: today, endDate: today, referrerUserId: TENANT_SALES_USER_ID },
+    expectStatus: 403,
+  });
+  assert.equal(agentOtherConversionDenied.code, 'REFERRAL_SCOPE_REQUIRED', 'agent should not read another referrer conversion report');
+
+  const studentConversionDenied = await request('/api/referral/conversion-report', {
+    query: { startDate: today, endDate: today },
+    expectStatus: 403,
+  });
+  assert.equal(studentConversionDenied.code, 'TENANT_ADMIN_REQUIRED', 'student should not access conversion report');
+
+  const partnerConversionDenied = await request('/api/referral/conversion-report', {
+    tenantId: PARTNER_TENANT_ID,
+    userId: TENANT_AGENT_USER_ID,
+    query: { startDate: today, endDate: today },
+    expectStatus: 403,
+  });
+  assert.equal(partnerConversionDenied.code, 'TENANT_ADMIN_REQUIRED', 'conversion report APIs must be tenant isolated');
+
   const salesOtherCommissionDenied = await request('/api/commission/summary', {
     userId: TENANT_AGENT_USER_ID,
     query: { startDate: today, endDate: today, referrerUserId: TENANT_SALES_USER_ID },