182 lines
7.1 KiB
Markdown
182 lines
7.1 KiB
Markdown
# Business Bundle Contracts
|
|
|
|
> **Documentation contract only.** No schema, API, or engine.
|
|
> Architecture: [commercial-platform-architecture.md](../architecture/commercial-platform-architecture.md) · [ADR-023](../architecture/adr/ADR-023.md)
|
|
> Contract version: `business-bundle.v1.1` (additive over `v1`)
|
|
|
|
---
|
|
|
|
## 1. Purpose
|
|
|
|
A **Business Bundle** is the platform commercial packaging unit. Bundles remain **lightweight**: they **reference** products, capabilities, automation packs, extensions, pricing, and (via subscription/license plans) commercial grants — they **never embed implementations**.
|
|
|
|
Legacy `services[]` / `modules[]` / `features[]` refs remain valid for compatibility with `commercial.v1` catalogs.
|
|
|
|
---
|
|
|
|
## 2. Aggregates
|
|
|
|
### 2.1 BusinessBundleDefinition
|
|
|
|
| Field | Type | Meaning |
|
|
| --- | --- | --- |
|
|
| `bundle_code` | string | Stable unique code (e.g. `bundle.restaurant.starter`) |
|
|
| `display_name` | string | Human label |
|
|
| `description` | string | Short commercial description |
|
|
| `owner` | string | Always `core-platform` for platform bundles |
|
|
| `status` | enum | `draft` \| `active` \| `deprecated` \| `retired` |
|
|
| `default_version` | string | Current `version_code` pointer |
|
|
| `metadata` | object | See BusinessBundleMetadata |
|
|
| `created_at` / `updated_at` | datetime | Audit (logical) |
|
|
|
|
### 2.2 BusinessBundleVersion
|
|
|
|
| Field | Type | Meaning |
|
|
| --- | --- | --- |
|
|
| `bundle_code` | string | Parent definition |
|
|
| `version_code` | string | Semver-like commercial version (e.g. `2026.07.1`) |
|
|
| `changelog` | string | Human notes |
|
|
| `product_refs[]` | BusinessBundleProductRef | **v1.1** PlatformProduct refs |
|
|
| `capability_refs[]` | BusinessBundleCapabilityRef | **v1.1** Capability Registry refs |
|
|
| `automation_pack_refs[]` | BusinessBundleAutomationPackRef | **v1.1** Automation Catalog refs |
|
|
| `extension_refs[]` | BusinessBundleExtensionRef | **v1.1** Extension Registry refs |
|
|
| `services[]` | BusinessBundleService | Legacy / complementary service refs |
|
|
| `modules[]` | BusinessBundleModule | Legacy module refs |
|
|
| `features[]` | BusinessBundleFeature | Legacy feature refs |
|
|
| `pricing_refs[]` | BusinessBundlePricingReference | Links to Pricing Catalog |
|
|
| `subscription_plan_refs[]` | string[] | **v1.1** Optional `plan_code`s |
|
|
| `license_policy_ref` | string? | **v1.1** Opaque license policy ref |
|
|
| `visibility` | BusinessBundleVisibility | Who may see/select |
|
|
| `lifecycle` | BusinessBundleLifecycle | Commercial lifecycle flags |
|
|
| `recommendation_rule_ids[]` | string[] | Optional rule links |
|
|
| `dependency_edge_ids[]` | string[] | Optional graph edge ids |
|
|
| `effective_from` / `effective_to` | datetime? | Window |
|
|
|
|
### 2.2a BusinessBundleProductRef (v1.1)
|
|
|
|
| Field | Type | Meaning |
|
|
| --- | --- | --- |
|
|
| `product_code` | string | PlatformProductRegistry entry |
|
|
| `required` | bool | |
|
|
| `min_version_code` | string? | |
|
|
|
|
### 2.2b BusinessBundleCapabilityRef (v1.1)
|
|
|
|
| Field | Type | Meaning |
|
|
| --- | --- | --- |
|
|
| `capability_code` | string | Capability Registry |
|
|
| `required` | bool | |
|
|
|
|
### 2.2c BusinessBundleAutomationPackRef (v1.1)
|
|
|
|
| Field | Type | Meaning |
|
|
| --- | --- | --- |
|
|
| `automation_pack_code` | string | Automation Catalog |
|
|
| `required` | bool | |
|
|
|
|
### 2.2d BusinessBundleExtensionRef (v1.1)
|
|
|
|
| Field | Type | Meaning |
|
|
| --- | --- | --- |
|
|
| `extension_code` | string | Extension Registry |
|
|
| `required` | bool | |
|
|
|
|
### 2.3 BusinessBundleService
|
|
|
|
| Field | Type | Meaning |
|
|
| --- | --- | --- |
|
|
| `service_identifier` | string | From service-manifest (e.g. `hospitality`, `payment`) |
|
|
| `required` | bool | Must be entitled for bundle activation |
|
|
| `service_bundle_refs[]` | string[] | Optional opaque L2 pack codes in owning service |
|
|
| `capability_prefix` | string? | Discovery hint only (prefer `capability_refs`) |
|
|
|
|
### 2.4 BusinessBundleModule
|
|
|
|
| Field | Type | Meaning |
|
|
| --- | --- | --- |
|
|
| `module_key` | string | Platform module key (e.g. `hospitality.menu`) |
|
|
| `service_identifier` | string | Owning service |
|
|
| `required` | bool | |
|
|
|
|
### 2.5 BusinessBundleFeature
|
|
|
|
| Field | Type | Meaning |
|
|
| --- | --- | --- |
|
|
| `feature_key` | string | Core L1 / service feature key (e.g. `payment.module.enabled`) |
|
|
| `service_identifier` | string | Owning service or `core-platform` |
|
|
| `required` | bool | |
|
|
|
|
### 2.6 BusinessBundlePricingReference
|
|
|
|
| Field | Type | Meaning |
|
|
| --- | --- | --- |
|
|
| `pricing_item_code` | string | FK-like ref to Pricing Catalog — **no amounts here** |
|
|
| `role` | enum | `primary` \| `addon` \| `enterprise_quote` \| `trial` |
|
|
| `billing_period_hint` | enum? | Informational only; catalog owns periods |
|
|
|
|
### 2.7 BusinessBundleRecommendationRule
|
|
|
|
Logical link only — full shape in [recommendation-contracts.md](recommendation-contracts.md).
|
|
|
|
| Field | Type | Meaning |
|
|
| --- | --- | --- |
|
|
| `rule_id` | string | |
|
|
| `bundle_code` | string | Target recommendation |
|
|
| `priority` | int | Higher wins among ties |
|
|
| `active` | bool | |
|
|
|
|
### 2.8 BusinessBundleVisibility
|
|
|
|
| Field | Type | Meaning |
|
|
| --- | --- | --- |
|
|
| `public_catalog` | bool | Visible on public onboarding |
|
|
| `admin_only` | bool | Platform admin catalog only |
|
|
| `tenant_tiers[]` | string[] | Optional tier gates |
|
|
| `business_type_codes[]` | string[] | Soft filter (recommendations still authoritative) |
|
|
| `regions[]` | string[] | Future regional visibility |
|
|
| `hidden` | bool | Completely hidden |
|
|
|
|
### 2.9 BusinessBundleLifecycle
|
|
|
|
| Field | Type | Meaning |
|
|
| --- | --- | --- |
|
|
| `sellable` | bool | New subscriptions allowed |
|
|
| `renewable` | bool | Existing may renew |
|
|
| `grandfathered` | bool | Existing keep access after deprecate |
|
|
| `replacement_bundle_code` | string? | Migration target |
|
|
|
|
### 2.10 BusinessBundleMetadata
|
|
|
|
| Field | Type | Meaning |
|
|
| --- | --- | --- |
|
|
| `tags[]` | string[] | Search tags |
|
|
| `locale_labels` | map | i18n labels |
|
|
| `icon_key` | string? | Design token / asset key |
|
|
| `sort_order` | int | Catalog order |
|
|
| `ext` | object | Additive reserved bag |
|
|
|
|
---
|
|
|
|
## 3. Invariants
|
|
|
|
1. A version MUST NOT store currency amounts, taxes, coupons, or discounts.
|
|
2. A version MUST NOT embed product/automation/extension implementations — **refs only**.
|
|
3. Prefer `product_refs` + `capability_refs` for new catalog entries; keep legacy service/module/feature refs for compatibility.
|
|
4. Deprecating a definition MUST NOT delete historical subscription refs (future storage).
|
|
5. Frontend MUST NOT invent bundle codes outside the canonical catalog.
|
|
6. Subscriptions and licenses are bound via plan/policy refs — bundles do not own subscription engines.
|
|
|
|
---
|
|
|
|
## 4. Relationship to Payment / Experience L2 packs
|
|
|
|
| Layer | Example | Owner |
|
|
| --- | --- | --- |
|
|
| Business Bundle | `bundle.restaurant.starter` | Core commercial |
|
|
| PlatformProduct | `product.pay` | Product Registry |
|
|
| Capability | `payments` | Capability Registry |
|
|
| Payment L2 | `payment.byo_psp.basic` | Payment |
|
|
| Experience L2 | (service pack codes) | Experience |
|
|
|
|
Business Bundle → product/capability/extension/automation refs → owning registries/services validate locally.
|