# Commercial Admin Portal — Screen Specification

> **Specification only.** No React routes, components, or APIs in this wave.  
> ADR: [ADR-023](../architecture/adr/ADR-023.md)

---

## 1. Scope

Platform-admin commercial governance screens. Customer onboarding UX is out of scope for this spec (Wave 1 onboarding remains a separate consumer of generated catalogs).

Audience: platform operators / commercial admins.

---

## 2. Screens

### 2.1 Bundle Management

| Element | Spec |
| --- | --- |
| List | All `BusinessBundleDefinition` with status, default version, sellable flag |
| Detail | Versions, services/modules/features refs, pricing refs, visibility, lifecycle |
| Actions | Create draft, publish version, deprecate, set replacement, toggle visibility |
| Forbidden | Editing list prices inline (link to Pricing Management) |

### 2.2 Pricing Management

| Element | Spec |
| --- | --- |
| List | PricingCatalogItem by model/status/currency |
| Detail | Model, amount (or enterprise quote), trial/promo windows, future tax/region fields read-only reserved |
| Actions | Create/retire items; never mutate historical subscription bindings in UI without policy |

### 2.3 Business Types

| Element | Spec |
| --- | --- |
| List | Business type catalog |
| Detail | Recommended bundles/services/modules/features |
| Actions | Edit recommendations; activate/deactivate type |

### 2.4 Recommendations

| Element | Spec |
| --- | --- |
| Rule list | RecommendationRule priority/active |
| Rule editor | Match predicates + emit targets |
| Simulator | Paste RecommendationRequest → show RecommendationResult + rule_trace |
| Forbidden | AI model configuration |

### 2.5 Subscriptions

| Element | Spec |
| --- | --- |
| List | Filter by tenant, status, plan |
| Detail | Items, period, renewal/cancel/grace, linked license |
| Actions | Request cancel per policy; admin suspend (future engine) |

### 2.6 Licenses

| Element | Spec |
| --- | --- |
| List | By tenant / status |
| Detail | Bundle, entitlement grant refs, validity |
| Actions | Request revoke/suspend (emits events; no direct vertical writes) |

### 2.7 Entitlements

| Element | Spec |
| --- | --- |
| Tenant view | Service/module/feature matrix + visibility |
| Quota view | Quota + usage limits |
| Actions | Admin grant/override with audit reason (future engine) |

### 2.8 Activation Logs

| Element | Spec |
| --- | --- |
| List | Pipelines by `correlation_id`, tenant, status |
| Detail | Step timeline with pending/succeeded/failed |
| Actions | Retry failed step (future); export |

---

## 3. Navigation (suggested IA)

```
Commercial
  ├─ Bundles
  ├─ Pricing
  ├─ Business Types
  ├─ Recommendation Rules
  ├─ Subscriptions
  ├─ Licenses
  ├─ Entitlements
  └─ Activation Logs
```

Permission prefix (logical, future): `commercial.admin.*`

---

## 4. Data binding rule

All screens MUST bind to Core commercial APIs/contracts when implemented.  
Until then, this document is the UI contract. Frontend MUST NOT invent a parallel catalog.