161 lines
5.4 KiB
Markdown
161 lines
5.4 KiB
Markdown
# Published Resource — Integration Contracts
|
|
|
|
> **Documentation contracts only.** No APIs or schemas are implemented by this document.
|
|
> Architecture: [published-resource-architecture.md](../architecture/published-resource-architecture.md) · [ADR-022](../architecture/adr/ADR-022.md)
|
|
|
|
All contracts are **versioned conceptually** as `published-resource.v1`, with additive companions:
|
|
|
|
| Contract | Version | Path |
|
|
| --- | --- | --- |
|
|
| Published Resource | `published-resource.v1` | this file |
|
|
| Published Action Registry | `published-action.v1` | [published-action-registry.md](published-action-registry.md) |
|
|
| Public Access | `public-access.v1` | [public-access-contract.md](public-access-contract.md) |
|
|
| Universal Embed | `universal-embed.v1` | [embed-contract.md](embed-contract.md) |
|
|
|
|
Implementations MUST accept unknown additive JSON fields. Breaking changes require a new major contract version and a registered phase.
|
|
|
|
---
|
|
|
|
## 1. Identity
|
|
|
|
| Field | Type | Rules |
|
|
| --- | --- | --- |
|
|
| `publish_id` | UUID | Stable; never reused after delete/archive policy |
|
|
| `tenant_id` | UUID | Mandatory isolation key |
|
|
| `resource_type` | string | Open registry key |
|
|
| `resource_id` | UUID / opaque string | Owner-service aggregate id |
|
|
| `canonical_url` | string | Absolute or path; aligns with reserved prefixes when applicable |
|
|
| `publish_status` | string | Extensible lifecycle |
|
|
| `visibility` | string | Extensible visibility |
|
|
| `owner_service` | string | Service id (`experience`, `hospitality`, …) |
|
|
|
|
Consumers **MUST** store and pass `publish_id` (+ validate `tenant_id`). Consumers **MUST NOT** persist Experience internal table names or require joins into `experience_db`.
|
|
|
|
---
|
|
|
|
## 2. Event payload fragment (conceptual)
|
|
|
|
When a Published Resource is created, published, unpublished, or archived, owner services SHOULD include:
|
|
|
|
```json
|
|
{
|
|
"publish_id": "uuid",
|
|
"tenant_id": "uuid",
|
|
"resource_type": "form",
|
|
"resource_id": "uuid",
|
|
"canonical_url": "/f/{slug-or-id}",
|
|
"publish_status": "published",
|
|
"visibility": "public",
|
|
"owner_service": "experience"
|
|
}
|
|
```
|
|
|
|
Event type names remain owner-prefixed (e.g. `experience.*`, `hospitality.*`). This fragment is the cross-service attachment key.
|
|
|
|
---
|
|
|
|
## 3. Consumer attachment contracts
|
|
|
|
### 3.1 Payment (Torbat Pay)
|
|
|
|
| Concern | Contract |
|
|
| --- | --- |
|
|
| Attach paid checkout | Payment request / session references `publish_id` |
|
|
| Examples | Paid Form, Paid Appointment, Paid Booking, Paid Registration, Paid Event |
|
|
| Forbidden | Reading Experience form/page tables |
|
|
|
|
### 3.2 Communication
|
|
|
|
| Concern | Contract |
|
|
| --- | --- |
|
|
| Triggers | After submit / booking / OTP / notify / campaign |
|
|
| Reference | `publish_id` + Communication `template_key` / channel |
|
|
| Forbidden | Embedding SMS providers in Experience; using Experience rows as contact source of truth |
|
|
|
|
### 3.3 Short Link
|
|
|
|
| Concern | Contract |
|
|
| --- | --- |
|
|
| Resolve | Short code → `publish_id` → canonical URL |
|
|
| Ownership | Reserved (e.g. future Torbat Link) |
|
|
| Forbidden | Hard dependency on Experience internals |
|
|
|
|
### 3.4 QR Code
|
|
|
|
| Concern | Contract |
|
|
| --- | --- |
|
|
| Encode / resolve | QR payload → `publish_id` |
|
|
| Examples | Table, card, poster, event, form, appointment |
|
|
| Ownership | Reserved (e.g. future Torbat QR) and/or vertical adapters |
|
|
|
|
### 3.5 Analytics
|
|
|
|
| Concern | Contract |
|
|
| --- | --- |
|
|
| Metrics key | `publish_id` |
|
|
| Notes | Experience local analytics shells unchanged in ownership |
|
|
|
|
### 3.6 CRM / Booking / Marketplace / Hospitality / Delivery / Loyalty / Sports Center / Future
|
|
|
|
| Concern | Contract |
|
|
| --- | --- |
|
|
| Attachment | Entity or session refs may cite `publish_id` for the public surface |
|
|
| Data ownership | Vertical owns its catalog/order/member aggregates; Experience owns its page/form shells |
|
|
|
|
---
|
|
|
|
## 4. Standalone Form / Survey / Appointment
|
|
|
|
Contractual requirements for Experience (future implementation phases):
|
|
|
|
1. Creating a Form, Survey, or Appointment page **MUST NOT** require an existing Site or Page.
|
|
2. Optional `site_id` / `page_id` binding is allowed.
|
|
3. Publishing MUST allocate a `publish_id` and registry entry usable by Payment/Communication/Link/QR/Analytics.
|
|
|
|
---
|
|
|
|
## 5. Reserved URL prefixes
|
|
|
|
| Prefix | Example resource types |
|
|
| --- | --- |
|
|
| `/s/` | site |
|
|
| `/p/` | page, landing_page |
|
|
| `/f/` | form |
|
|
| `/survey/` | survey |
|
|
| `/book/` | appointment, booking_page |
|
|
| `/menu/` | restaurant_menu |
|
|
| `/card/` | digital_business_card |
|
|
| `/event/` | event |
|
|
|
|
Routing not implemented here.
|
|
|
|
---
|
|
|
|
## 6. Capability discovery additions (reserved)
|
|
|
|
Future discovery responses MAY include additive keys (no API change in this docs patch):
|
|
|
|
```json
|
|
{
|
|
"published_resources": true,
|
|
"published_actions": true,
|
|
"public_access_policies": true,
|
|
"universal_embed": true
|
|
}
|
|
```
|
|
|
|
Action keys, access strategies, and embed types remain open registries advertised by owning services.
|
|
|
|
---
|
|
|
|
## 7. Related Documents
|
|
|
|
- [Published Resource Architecture](../architecture/published-resource-architecture.md)
|
|
- [ADR-022](../architecture/adr/ADR-022.md)
|
|
- [Published Action Registry](published-action-registry.md)
|
|
- [Public Access Contract](public-access-contract.md)
|
|
- [Embed Contract](embed-contract.md)
|
|
- [Payment Contracts](payment-contracts.md)
|
|
- [Services Contracts](services-contracts.md)
|
|
- [Experience Roadmap](../experience-roadmap.md)
|