RankFlow AI — Test Specification: Reporting, Compliance & Security

Version: 1.0.0 Date: 2026-06-12 Scope: Monthly/Weekly Reports, Consent, Medical Compliance, Schema Validity, Security Source Specs: email-reports-pdf.md, security-compliance.md, business_flow_map.md §5.7 & §3 (Consent) Test Framework: Vitest + Playwright + MSW + Prisma Test Utils Compliance Framework: DPDPA 2023, GDPR-ready, Medical Content Safety

---

1. Monthly PDF Report Generation#

Flow: Report Data → HTML Template (React) → Playwright (Chromium) → PDF Buffer → S3 Upload → Resend Attachment

Unit Tests#

Integration Tests#

E2E Tests#

Success Criteria (Binary)#

• PDF renders A4 format with print backgrounds enabled
• All 9 report sections appear in generated PDF HTML template
• S3 upload succeeds with ContentType: application/pdf
• Browser process is always closed (no Chromium leaks)
• Report DB record created with correct period, scores, and pdfUrl
• Font wait timeout (2000ms) prevents layout shift in PDF output
• Monthly cron runs only for practices with status = ACTIVE
• Failed PDF generation does not create orphaned Report records

Agent Context (Pre-conditions)#

• Required DB state: Practice (≥1 active), Location linked, Report table empty
• Required env vars: AWS_S3_BUCKET, AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, ENCRYPTION_KEY
• Required external mocks: S3 PutObject → 200 OK, Playwright Chromium available in test env
• Required packages: playwright, @aws-sdk/client-s3, vitest, msw

Verification Commands#

# Unit tests
pnpm test:unit -- src/__tests__/unit/pdf/

# Integration tests
pnpm test:integration -- src/__tests__/integration/pdf/

# E2E test
pnpm test:e2e -- e2e/reporting/monthly-report.spec.ts

---

2. Score Calculation#

Formula: Weighted composite score (0–100) across 5 categories.

Unit Tests#

Integration Tests#

Success Criteria (Binary)#

• Overall score formula exactly matches: 0.25*GBP + 0.25*Citations + 0.20*Reviews + 0.20*Rankings + 0.10*SEO
• Each category score is clamped to [0, 100] before weighting
• Division by zero in GBP baseline returns 0, not Infinity or NaN
• Empty rankings array returns 0, not NaN
• Score recalculation updates DB within 5 seconds of data change event
• Report scores are persisted as integers or 2-decimal floats consistently

Agent Context (Pre-conditions)#

• Required DB state: Practice with linked GbpLocation, Citation, Review, KeywordRanking records
• Required env vars: None (pure math)
• Required external mocks: None

Verification Commands#

pnpm test:unit -- src/__tests__/unit/reporting/score.test.ts
pnpm test:integration -- src/__tests__/integration/reporting/

---

3. Email Report Delivery#

System: Resend API → HTML email + PDF attachment → Webhook tracking (email.delivered, email.opened, email.bounced)

Unit Tests#

Integration Tests#

E2E Tests#

Success Criteria (Binary)#

• HTML email contains correct practiceName, period, scoreOverall, and 4 score breakdown cards
• PDF attachment URL is included in email payload sent to Resend
• Resend webhook signature is verified with HMAC before processing
• email.delivered updates EmailLog.status to DELIVERED and sets deliveredAt
• email.opened updates EmailLog.status to OPENED and sets openedAt
• email.bounced updates EmailLog.status to BOUNCED, sets bouncedAt and bounceReason
• Invalid webhook signature returns 401 without DB mutation
• Batch monthly report sends one email per active practice, no duplicates
• Responsive CSS @media query present for mobile clients
• Bounce reason is stored in EmailLog for admin review

Agent Context (Pre-conditions)#

• Required DB state: Practice (active), User (owner), EmailLog table empty
• Required env vars: RESEND_API_KEY, RESEND_WEBHOOK_SECRET
• Required external mocks: Resend API → { id: "msg_123" }, Resend webhook events

Verification Commands#

pnpm test:unit -- src/__tests__/unit/email/
pnpm test:integration -- src/__tests__/integration/email/
pnpm test:e2e -- e2e/reporting/email-delivery.spec.ts

---

4. Weekly Digest Generation#

Flow: BullMQ cron (Mondays) → Gather top 3 stats → HTML email → Resend → No PDF attachment

Unit Tests#

Integration Tests#

Success Criteria (Binary)#

• Weekly digest contains exactly 3 stats: Maps position, new reviews, posts published
• Digest email has no PDF attachment (lightweight)
• Position change relative to previous week is calculated and displayed
• EmailLog.type = WEEKLY_DIGEST is recorded for tracking
• Digest renders gracefully when all metrics are zero
• Cron runs every Monday morning (configurable via BullMQ or Inngest)

Agent Context (Pre-conditions)#

• Required DB state: Practice (active), GbpPost, Review, KeywordRanking data for last 7 days
• Required env vars: RESEND_API_KEY
• Required external mocks: Resend API → 200 OK

Verification Commands#

pnpm test:unit -- src/__tests__/unit/email/digest.test.ts
pnpm test:integration -- src/__tests__/integration/email/weekly-digest.test.ts

---

5. Consent Logging#

Legal Basis: DPDPA 2023 (India), GDPR-ready. Consent recorded with timestamp + IP + user agent.

Unit Tests#

Integration Tests#

Compliance Tests#

Success Criteria (Binary)#

• Every required consent (terms, privacy, gbp_auth, data_processing, citation_network) creates a ConsentLog row with granted=true
• Each ConsentLog record contains ipAddress, userAgent, and grantedAt timestamp
• Marketing consent defaults to false (unchecked by default)
• Withdrawal creates a new ConsentLog with granted=false and triggers compliance/data-deletion Inngest event
• Onboarding cannot proceed if any required consent is missing
• Consent DB write failure retries 3× before alerting admin
• GDPR data export includes all ConsentLog records for the practice
• AuditLog records every consent action with action = CONSENT
• Consent records are append-only (no updates to existing rows)
• Invalid IP addresses are rejected by input validation

Agent Context (Pre-conditions)#

• Required DB state: User, Practice, ConsentLog, AuditLog tables empty
• Required env vars: INNGEST_EVENT_KEY (for withdrawal event)
• Required external mocks: Inngest send stubbed to capture events

Verification Commands#

pnpm test:unit -- src/__tests__/unit/compliance/consent.test.ts
pnpm test:integration -- src/__tests__/integration/compliance/
pnpm test:compliance -- src/__tests__/compliance/consent/

---

6. Medical Content Compliance#

Rules: No guaranteed cures, no drug claims, no patient PII in replies, HIPAA-aware handling.

Unit Tests#

Integration Tests#

Compliance Tests#

Success Criteria (Binary)#

• Banned phrases (guaranteed cure, 100% success, permanent solution, miracle treatment) are detected and rejected
• Drug names found in content trigger isCompliant = false when paired with claim verbs
• Review replies never contain patient names, phone numbers, or dates of birth
• Non-compliant AI content is blocked from DB write and triggers regeneration
• After 3 regeneration failures, admin alert is sent and content queues for manual review
• All medical directory profiles contain required disclaimer before publish
• Citation descriptions (30 per practice) all pass compliance filter before submission
• GBP posts with compliance violations are queued as PENDING_REVIEW, not auto-published
• Content quality heuristic enforces minimum length and keyword density limits
• Diagnostic language (you have, prescribe, diagnosis) is rejected in AI-generated content

Agent Context (Pre-conditions)#

• Required DB state: Practice, ContentPiece, DirectoryProfileSection, Review tables
• Required env vars: ANTHROPIC_API_KEY (or mock LLM router)
• Required external mocks: LLM router returning controlled responses (compliant + non-compliant)
• Required data: Banned phrase list, drug name dictionary, disclaimer template

Verification Commands#

pnpm test:unit -- src/__tests__/unit/compliance/medical-filter.test.ts
pnpm test:integration -- src/__tests__/integration/compliance/
pnpm test:compliance -- src/__tests__/compliance/medical/

---

7. Schema Markup Validity#

Standard: JSON-LD, Schema.org (LocalBusiness, MedicalBusiness, Physician, Service, FAQPage, Review). Validated on every deploy.

Unit Tests#

Integration Tests#

Compliance Tests#

Success Criteria (Binary)#

• Every directory profile <head> contains at least one valid JSON-LD <script> block
• Schema @context is exactly https://schema.org
• @type is valid Schema.org type (LocalBusiness, MedicalBusiness, Physician, Service, FAQPage, Review)
• Required fields name, address, telephone are present and non-empty
• Invalid JSON-LD triggers fallback to minimal LocalBusiness schema without breaking deploy
• FAQ schema contains ≥ 8 Q&A pairs for medical vertical pages
• Schema telephone and address match Location table NAP exactly
• Medical practices use MedicalBusiness or Physician type, not generic LocalBusiness
• Schema injection escapes </script> and quote characters to prevent XSS
• ISR revalidation updates schema in HTML within 60 seconds of Practice update
• No duplicate schema blocks of the same type in page <head>
• AggregateRating schema reflects actual Review data average and count

Agent Context (Pre-conditions)#

• Required DB state: Practice with schemaMarkup JSON field, Location, DirectoryProfileSection, Review
• Required env vars: None
• Required external mocks: Google Rich Results Test API (optional, mocked)

Verification Commands#

pnpm test:unit -- src/__tests__/unit/schema/
pnpm test:integration -- src/__tests__/integration/schema/
pnpm test:compliance -- src/__tests__/compliance/schema/

---

8. Security#

Layers: Token Encryption (AES-256-GCM), RBAC, Rate Limiting, Input Validation, SQL Injection Prevention, Audit Logging.

Unit Tests#

Integration Tests#

Security Tests#

Success Criteria (Binary)#

• encrypt(plaintext) → decrypt(ciphertext) round-trip returns exact original plaintext
• Encrypted token in DB is never stored as plaintext; ciphertext is 3-part base64 colon-delimited
• Tampering with authTag or ciphertext causes decrypt to throw (authentication failure)
• publicProcedure requires no auth; protectedProcedure requires auth; practiceProcedure requires auth + practice membership; adminProcedure requires role = ADMIN
• CLIENT attempting adminProcedure receives 403 FORBIDDEN with no DB mutation
• Rate limit of 100 req/min enforced globally; skill.execute limited to 10/min; content.generate limited to 5/min
• 101st request in 1-minute window returns 429 Too Many Requests
• Zod validation rejects invalid inputs before any DB operation
• DOMPurify removes <script> tags and dangerous HTML from user inputs
• Prisma parameterized queries prevent SQL injection; no raw string concatenation in $queryRaw
• Every mutation creates an AuditLog row with action, entityType, oldValue, newValue, ipAddress, userAgent
• Request ID is propagated to response header x-request-id and all audit logs
• Session expires after 7 days; refreshes after 24 hours of inactivity
• Data export returns only requesting user's own practice data (no cross-practice leakage)
• Soft delete wipes tokens, anonymizes reviews, and preserves audit logs for 7 years
• Health check endpoint is public but contains no secrets, tokens, or env vars
• Webhook signature verification uses HMAC with timestamp tolerance to prevent replay attacks
• Docker container runs as non-root nextjs user (UID 1001)
• Content-Security-Policy header present on all page responses
• Dependency audit passes with zero high-severity vulnerabilities

Agent Context (Pre-conditions)#

• Required DB state: User (roles: ADMIN, CLIENT, EDITOR, VIEWER), Practice, GbpAccount, AuditLog
• Required env vars: ENCRYPTION_KEY (32-byte), BETTER_AUTH_SECRET, RESEND_WEBHOOK_SECRET
• Required external mocks: Resend webhook signature, tRPC context builder
• Required packages: crypto, zod, isomorphic-dompurify, vitest, msw

Verification Commands#

# Unit tests
pnpm test:unit -- src/__tests__/unit/security/

# Integration tests
pnpm test:integration -- src/__tests__/integration/security/

# Security tests
pnpm test:security -- src/__tests__/security/

# Static audit
pnpm audit --audit-level=high
pnpm exec secretlint "**/*"

---

9. Mock Data Registry#

Mock Factories#

// src/__tests__/factories/report.ts
export const createMockReportData = (overrides?: Partial<ReportData>): ReportData => ({
  practiceName: "Dr. Smith Dental Clinic",
  period: "January 2025",
  scoreOverall: 78,
  scoreGbp: 82,
  scoreCitations: 76,
  scoreReviews: 85,
  scoreRankings: 70,
  scoreSeo: 88,

  gbpViews: 1240,
  gbpClicks: 340,
  gbpCalls: 45,
  gbpDirections: 28,
  gbpPostsPublished: 6,

  citationsLive: 24,
  citationsVerified: 30,
  napConsistency: 0.95,

  reviewAvg: 4.2,
  reviewsNew: 8,
  reviewsReplied: 6,
  replyRate: 0.75,

  keywordsTop10: 12,
  keywordsTop3: 3,
  rankings: [
    { keyword: "dentist in Kochi", currentRank: 3, previousRank: 5, change: -2 },
    { keyword: "dental clinic Kochi", currentRank: 7, previousRank: 8, change: -1 },
    { keyword: "root canal treatment Kochi", currentRank: 12, previousRank: 15, change: -3 },
    { keyword: "best dentist Kochi", currentRank: null, previousRank: null, change: 0 },
  ],

  actionItems: [
    "Add 3 more photos to your Google Business Profile this week.",
    "Respond to the 2 unanswered reviews from last month.",
    "Post a holiday greeting on social media to boost engagement.",
  ],

  reportUrl: "https://app.rankflow.in/dashboard/reports/report-123",
  pdfUrl: "https://rankflow-reports.s3.ap-south-1.amazonaws.com/reports/report-prac-123-January-2025.pdf",
  ...overrides,
});

// src/__tests__/factories/digest.ts
export const createMockDigestData = (overrides?: Partial<DigestData>) => ({
  practiceName: "Dr. Smith Dental Clinic",
  mapsPosition: 3,
  previousPosition: 4,
  newReviews: 4,
  reviewAvg: 4.8,
  postsPublished: 2,
  dashboardUrl: "https://app.rankflow.in/dashboard",
  ...overrides,
});

// src/__tests__/factories/practice.ts
export const createMockPractice = (overrides?: Partial<Practice>) => ({
  id: `prac_${faker.string.nanoid(8)}`,
  businessName: "Dr. Smith Dental Clinic",
  category: "DENTIST",
  plan: "STANDARD",
  status: "ACTIVE",
  directorySlug: "dr-smith-dental",
  schemaMarkup: {
    "@context": "https://schema.org",
    "@type": "MedicalBusiness",
    name: "Dr. Smith Dental Clinic",
    address: {
      "@type": "PostalAddress",
      streetAddress: "123 MG Road",
      addressLocality: "Kochi",
      addressRegion: "Kerala",
      postalCode: "682011",
      addressCountry: "IN",
    },
    telephone: "+91-98765-43210",
    medicalSpecialty: "Dentistry",
  },
  ...overrides,
});

// src/__tests__/factories/location.ts
export const createMockLocation = (overrides?: Partial<Location>) => ({
  id: `loc_${faker.string.nanoid(8)}`,
  practiceId: `prac_${faker.string.nanoid(8)}`,
  isPrimary: true,
  address: "123 MG Road, Kochi, Kerala 682011",
  city: "Kochi",
  state: "Kerala",
  pinCode: "682011",
  phone: "+91-98765-43210",
  email: "contact@drsmithdental.com",
  hours: { mon: "09:00-18:00", tue: "09:00-18:00", sat: "09:00-14:00" },
  ...overrides,
});

// src/__tests__/factories/consent.ts
export const createMockConsentLog = (overrides?: Partial<ConsentLog>) => ({
  id: `cns_${faker.string.nanoid(8)}`,
  userId: `usr_${faker.string.nanoid(8)}`,
  practiceId: `prac_${faker.string.nanoid(8)}`,
  consentType: "terms",
  granted: true,
  ipAddress: "192.168.1.100",
  userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
  grantedAt: new Date("2025-01-15T10:30:00.000Z"),
  ...overrides,
});

// src/__tests__/factories/user.ts
export const createMockUser = (overrides?: Partial<User>) => ({
  id: `usr_${faker.string.nanoid(8)}`,
  email: "dr.smith@example.com",
  name: "Dr. Smith",
  role: "CLIENT",
  createdAt: new Date(),
  ...overrides,
});

// src/__tests__/factories/gbp-account.ts
export const createMockGbpAccount = (overrides?: Partial<GbpAccount>) => ({
  id: `gbp_${faker.string.nanoid(8)}`,
  practiceId: `prac_${faker.string.nanoid(8)}`,
  accountEmail: "dr.smith@gmail.com",
  accessToken: encrypt("ya29.a0ARrdaM_test_access_token"),
  refreshToken: encrypt("1//0test_refresh_token"),
  tokenExpiresAt: new Date(Date.now() + 3600 * 1000),
  scope: ["business.manage"],
  isActive: true,
  ...overrides,
});

Mock External Services (MSW Handlers)#

---

10. Verification Commands#

Run All Tests for This Spec#

# 1. Unit tests
pnpm test:unit -- src/__tests__/unit/pdf/ src/__tests__/unit/email/ src/__tests__/unit/reporting/ src/__tests__/unit/compliance/ src/__tests__/unit/schema/ src/__tests__/unit/security/

# 2. Integration tests
pnpm test:integration -- src/__tests__/integration/pdf/ src/__tests__/integration/email/ src/__tests__/integration/reporting/ src/__tests__/integration/compliance/ src/__tests__/integration/schema/ src/__tests__/integration/security/

# 3. E2E tests
pnpm test:e2e -- e2e/reporting/

# 4. Compliance tests
pnpm test:compliance -- src/__tests__/compliance/

# 5. Security tests
pnpm test:security -- src/__tests__/security/

# 6. Full pipeline (CI)
pnpm test:ci

Coverage Requirements#

CI Pipeline Gates#

Agent Task Template for This Spec#

## Task: [Feature Name]
**Role**: [Compliance_Test_Specialist | Security_Engineer | Reporting_Developer]
**Guidance**: Read `docs/specs/email-reports-pdf.md`, `docs/specs/security-compliance.md`, `docs/test-specs/TEST-reporting-compliance.md`
**Context**: Mock factories in `src/__tests__/factories/`, MSW handlers in `src/__tests__/mocks/`
**Mission**:
1. Write a FAILING test first (TDD)
2. Implement the feature
3. Make the test pass
4. Run the verification command
5. Report: PASS / FAIL with evidence

**Deliverables**:
- [ ] Implementation code
- [ ] Test file(s)
- [ ] VERIFY.md with test output

---

End of Test Specification — RankFlow AI Reporting, Compliance & Security v1.0.0