# Pipeline Universe API Contract

Tujuan: menyediakan universe perusahaan/instrumen untuk halaman `pipeline` dan menjalankan screening otomatis sesuai appetite BPKH.

## 1) GET /api/pipeline-universe
Mengambil kandidat yang sudah dinormalisasi.

### Query params
- `sector` optional
- `instrument_type` optional
- `country` optional
- `updated_after` optional ISO date
- `limit` optional integer

### Response
```json
{
  "items": [
    {
      "entityId": "bank-bmi",
      "name": "Bank Muamalat Indonesia",
      "entityType": "bank",
      "country": "ID",
      "sector": "banking",
      "subsector": "islamic-bank",
      "syariahStatus": "compliant",
      "strategicThemes": ["hajj-finance", "umrah-payments"],
      "sourceSystem": "internal_sheet",
      "updatedAt": "2026-04-15T08:00:00Z",
      "instrument": {
        "instrumentId": "bank-bmi-equity",
        "instrumentName": "Equity",
        "instrumentType": "equity",
        "tenorYears": 5,
        "currency": "IDR",
        "targetReturnPct": 13.5,
        "liquidity": "medium"
      },
      "financials": {
        "roa": 1.3,
        "roe": 14.2,
        "car": 18.4,
        "npf": 2.1,
        "bopo": 82.0
      },
      "risk": {
        "rating": "medium",
        "governance": "medium",
        "countryRisk": "low"
      },
      "dataQualityScore": 88
    }
  ],
  "total": 1,
  "asOf": "2026-04-15T08:00:00Z",
  "source": "pipeline-universe-v1"
}
```

## 2) POST /api/pipeline-screen
Menjalankan screening terhadap list kandidat.

### Request
```json
{
  "screeningProfile": "bpkh_2026_base",
  "items": [
    {
      "entityId": "bank-bmi",
      "name": "Bank Muamalat Indonesia",
      "entityType": "bank",
      "country": "ID",
      "sector": "banking",
      "subsector": "islamic-bank",
      "syariahStatus": "compliant",
      "strategicThemes": ["hajj-finance"],
      "sourceSystem": "internal_sheet",
      "instrument": {
        "instrumentId": "bank-bmi-equity",
        "instrumentName": "Equity",
        "instrumentType": "equity",
        "tenorYears": 5,
        "currency": "IDR",
        "targetReturnPct": 13.5,
        "liquidity": "medium"
      },
      "financials": {"roa": 1.3, "roe": 14.2, "car": 18.4, "npf": 2.1, "bopo": 82.0},
      "risk": {"rating": "medium"},
      "dataQualityScore": 88
    }
  ]
}
```

### Response
```json
{
  "results": [
    {
      "entityId": "bank-bmi",
      "eligibilityPass": true,
      "alignmentScore": 82,
      "priorityBand": "high",
      "recommendedStage": "priority",
      "hardFailReasons": [],
      "subScores": {
        "financial": 80,
        "risk": 75,
        "liquidity": 70,
        "strategic": 90,
        "syariah": 100,
        "planFit": 78
      },
      "explanation": "Bank syariah strategis, lolos hard filter, cocok dengan tema hajj-finance."
    }
  ],
  "screeningVersion": "bpkh-screen-v1",
  "screenedAt": "2026-04-15T08:05:00Z"
}
```

## 3) PATCH /api/pipeline-case/:caseId
Menyimpan analyst override.

### Request
```json
{
  "overrideStage": "decision",
  "overrideReason": "Strategic ecosystem relevance outweighs medium liquidity profile",
  "analystName": "Jaka"
}
```

## Catatan implementasi
- Browser sebaiknya **tidak** langsung ke vendor premium.
- Universe sebaiknya di-normalisasi server-side.
- Screening engine idealnya server-side agar audit trail lebih kuat.