> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CE to PF-12 Integration Contract

> This document defines the integration contract between CE-05 (Pipeline & Reporting) and PF-12 (Reports System). CE-05 creates report definitions in PF-12 for s…

**Version:** 1.0.0\
**Created:** 2026-01-23\
**Status:** 📋 Specification

***

## Overview

This document defines the integration contract between CE-05 (Pipeline & Reporting) and PF-12 (Reports System). CE-05 creates report definitions in PF-12 for scheduled report generation and export functionality.

***

## Integration Pattern

**Pattern:** Platform Integration Layer (Pattern 1)\
**Direction:** CE-05 → PF-12 (CE-05 is the consumer)

```text theme={null}
┌─────────────────┐     ┌─────────────────┐
│     CE-05       │────▶│     PF-12       │
│ Pipeline Report │     │ Reports System  │
└─────────────────┘     └─────────────────┘
        │                       │
        ▼                       ▼
┌─────────────────┐     ┌─────────────────┐
│ Report Defns    │     │ execute-report  │
│ (pf_reports)    │     │ Edge Function   │
└─────────────────┘     └─────────────────┘
```

***

## Report Definitions

### Lead Pipeline Report

| Field            | Value                                                                             |
| ---------------- | --------------------------------------------------------------------------------- |
| `report_key`     | `ce_lead_pipeline`                                                                |
| `name`           | Lead Pipeline Report                                                              |
| `description`    | Lead counts by stage, conversion rates, and average time to convert               |
| `module`         | `ce`                                                                              |
| `sql_query`      | `SELECT * FROM ce_lead_pipeline_metrics WHERE organization_id = :organization_id` |
| `parameters`     | `{ "date_from": "date", "date_to": "date", "assigned_to": "uuid?" }`              |
| `formats`        | `["csv", "pdf"]`                                                                  |
| `permission_key` | `ce.pipeline.export`                                                              |

### Partner Scorecard Report

| Field            | Value                                                                         |
| ---------------- | ----------------------------------------------------------------------------- |
| `report_key`     | `ce_partner_scorecard`                                                        |
| `name`           | Partner Scorecard Report                                                      |
| `description`    | Partner performance metrics with success rates and trends                     |
| `module`         | `ce`                                                                          |
| `sql_query`      | `SELECT * FROM ce_partner_scorecard WHERE organization_id = :organization_id` |
| `parameters`     | `{ "date_from": "date", "date_to": "date", "partner_type": "string?" }`       |
| `formats`        | `["csv", "pdf"]`                                                              |
| `permission_key` | `ce.scorecard.export`                                                         |

### Call Analytics Report

| Field            | Value                                                                                    |
| ---------------- | ---------------------------------------------------------------------------------------- |
| `report_key`     | `ce_call_analytics`                                                                      |
| `name`           | Call Analytics Report                                                                    |
| `description`    | Call volume, disposition breakdown, and recording coverage                               |
| `module`         | `ce`                                                                                     |
| `sql_query`      | `SELECT * FROM ce_call_analytics WHERE organization_id = :organization_id`               |
| `parameters`     | `{ "date_from": "date", "date_to": "date", "user_id": "uuid?", "direction": "string?" }` |
| `formats`        | `["csv", "pdf"]`                                                                         |
| `permission_key` | `ce.analytics.export`                                                                    |

### Activity Analytics Report

| Field            | Value                                                                                               |
| ---------------- | --------------------------------------------------------------------------------------------------- |
| `report_key`     | `ce_activity_analytics`                                                                             |
| `name`           | Activity Analytics Report                                                                           |
| `description`    | Activity counts by type and subject, follow-up rates                                                |
| `module`         | `ce`                                                                                                |
| `sql_query`      | `SELECT * FROM ce_activity_analytics WHERE organization_id = :organization_id`                      |
| `parameters`     | `{ "date_from": "date", "date_to": "date", "activity_type": "string?", "subject_type": "string?" }` |
| `formats`        | `["csv", "pdf"]`                                                                                    |
| `permission_key` | `ce.analytics.export`                                                                               |

***

## Scheduled Reports

### Default Schedules

| Report             | Frequency | Recipients             | Time             |
| ------------------ | --------- | ---------------------- | ---------------- |
| Lead Pipeline      | Daily     | Program Directors      | 06:00 UTC        |
| Partner Scorecard  | Weekly    | Business Dev Directors | Monday 08:00 UTC |
| Call Analytics     | Weekly    | Supervisors            | Monday 08:00 UTC |
| Activity Analytics | Weekly    | Program Directors      | Monday 08:00 UTC |

### PHI/PII Protection

1. **Secure Storage:** Reports generated to access-controlled storage referenced by `pf_report_schedules`
2. **Notification Only:** Email via PF-10 contains secure portal link only, no PHI/PII
3. **Auto-Expiry:** Generated reports auto-expire after 30 days
4. **Audit Logging:** All report access logged to `pf_audit_logs`

### Role-Based Recipients

Recipients pulled from user roles, not hardcoded:

* Program Director → Lead Pipeline, Activity Analytics
* Business Development Director → Partner Scorecard
* Supervisor → Call Analytics

***

## API Contract

### Export Report (Synchronous)

```typescript theme={null}
import { ReportService } from '@/platform/reports';

// CE-05 components call PF-12 for export
const exportReport = async (params: {
  reportKey: 'ce_lead_pipeline' | 'ce_partner_scorecard' | 'ce_call_analytics' | 'ce_activity_analytics';
  organizationId: string;
  format: 'csv' | 'pdf';
  parameters: Record<string, unknown>;
}) => {
  return ReportService.generateReport(params);
};
```

### Schedule Report (Admin Only)

```typescript theme={null}
import { ReportService } from '@/platform/reports';

// Org admin schedules recurring report
const scheduleReport = async (params: {
  reportKey: string;
  organizationId: string;
  frequency: 'daily' | 'weekly' | 'monthly';
  recipients: { roleId: string }[];
  parameters: Record<string, unknown>;
}) => {
  return ReportService.createSchedule(params);
};
```

***

## Error Handling

| Error Code          | Description                          | User Message                                       |
| ------------------- | ------------------------------------ | -------------------------------------------------- |
| `REPORT_NOT_FOUND`  | Report definition not in pf\_reports | "Report configuration not found. Contact support." |
| `PERMISSION_DENIED` | User lacks export permission         | "You don't have permission to export this report." |
| `GENERATION_FAILED` | Report generation error              | "Failed to generate report. Please try again."     |
| `SCHEDULE_FAILED`   | Schedule creation error              | "Failed to schedule report. Please try again."     |

***

## Dependencies

### Required PF-12 Tables

* `pf_reports` - Report definitions
* `pf_report_schedules` - Scheduled report configurations
* `pf_report_executions` - Execution history
* `pf_report_permissions` - Permission mappings

### Required Views (CE-05)

* `ce_lead_pipeline_metrics`
* `ce_partner_scorecard`
* `ce_call_analytics`
* `ce_activity_analytics`

***

## Testing Requirements

### Integration Tests

1. Report definition exists in `pf_reports`
2. Report generates successfully with sample data
3. Scheduled report executes on schedule
4. Export respects permission keys
5. PHI/PII protection in email notifications

### Security Tests

1. Cross-organization access blocked
2. Permission keys enforced
3. Audit logging verified
4. Auto-expiry working

***

## References

* **PF-12 Spec:** `specs/pf/specs/PF-12-reports-system.md`
* **CE-05 Spec:** `specs/ce/specs/CE-05-pipeline-reporting.md`
* **Integration Patterns:** `docs/architecture/integrations/index.md`