Skip to content

Partner formal data model

Purpose

This document formalizes the Partner data model required by the internal workflow and partnership contract used by Portugal Odyssey.

Goals: - Ensure all data required to fulfill the partnership contract is captured. - Separate data by logical aggregations. - Clearly distinguish partner-managed vs platform/admin-managed data. - Add fields helpful for operations, workflows, verification, and notifications.

Ownership conventions

  • Partner-managed: data the partner can create/update.
  • Admin-managed: data only the platform can create/update.
  • Mutually agreed / locked: fields that become immutable after both parties consent/sign (changes require new contract/version).

A) Partner basic profile (Partner-managed)

Required for onboarding and general identification.

  • Identifiers
  • id (UUID, system)
  • short_name (string, 3–5 uppercase) (immutable, used as tenant slug)
  • Display / marketing
  • name (string, required)
  • legal_name (string)
  • website (url)
  • description (text)
  • industry (string)
  • business_type (string)
  • Primary contact
  • email (string, required)
  • phone (string)
  • contact_person_name (string)
  • Addresses
  • business_address (Address)

Covers contract parties + licensure + insurance + banking/invoicing.

  • company_name (string, required)
  • tax_id / NIF (string, required)
  • registration_number (string)
  • legal_address (Address)

B2) Representative (Partner-managed)

Required by contract header. - legal_representative.name (string, required) - legal_representative.role (string, required) - legal_representative.document_file_key (file key, optional)

B3) Banking & invoicing (Partner-managed)

Required by payments/invoicing clause. - banking.iban (string, recommended) - banking.bank_name (string) - banking.beneficiary_name (string) - billing.email (string) - billing.vat_number (string) - billing.invoice_requirements (text/json)

B4) Licenses, certifications, insurance (Partner-managed)

Required by contract clauses 3 and 9 + workflow pre-qualification. Stored as a list of records: - type (enum) e.g. RNAAT, AL_REGISTRATION, LIABILITY_INSURANCE, PERSONAL_ACCIDENT, OTHER - number (string) - issuer (string) - valid_from / valid_to (date) - coverage (text/json) - document_file_key (file key)

B5) Admin verification (Admin-managed)

Per document/licence/insurance record: - verification.status (enum PENDING|VERIFIED|REJECTED) - verification.reviewed_by (admin user id) - verification.reviewed_at (timestamp) - verification.reason (text)

C) Operational contacts & channels (Partner-managed)

Required by workflow section 3.1.

  • contacts.reservations (name/email/phone)
  • contacts.finance (name/email/phone)
  • contacts.emergency (name/phone)
  • public_links:
  • instagram, facebook, tripadvisor, booking, google_maps, other[]

D) Service catalog / Annex I (Partner-managed + Admin-approved/locked)

Services already exist in partner_services and should be standardized to support contract annex snapshots.

Per service (Partner-managed fields): - name, short_description, description - parameters: - type_category (tour/accommodation/transport/etc) - location (address + geo) - schedule (days/times) - duration (minutes/hours) - languages[] - capacity.min, capacity.max - included[], not_included[] - customer_requirements[] - safety.measures[] - sustainability.practices[] + free text

Admin-managed fields: - status, type (service taxonomy), approval_required, approved_by, approved_at, admin_notes

Locked after mutual consent (examples): - price currency, core pricing terms, location (if contractually fixed)

E) Financial model / Annex II (Admin-managed + mutually agreed)

Required by contract clause 5 and workflow negotiation.

Partner-level defaults (Admin-managed): - commercial.model (enum NET_RATE|COMMISSION) - commercial.who_charges_customer (enum PLATFORM|PARTNER) - commercial.commission_percent (number, when COMMISSION) - payments.schedule: - frequency (enum WEEKLY|MONTHLY|AFTER_SERVICE) - due_days (int) - currency (ISO) - pricing_fairness.mfn (boolean: partner must not offer worse conditions to PO than other intermediaries)

Service-level overrides (mutually agreed): - net_price, rrp, discount_policies, cancellation_fees

F) Operational conditions & SLAs (Mutually agreed)

Required by contract clauses 6–7.

  • sla.confirm_within_hours (int)
  • sla.min_booking_lead_time_hours (int)
  • sla.min_free_cancel_lead_time_hours (int)
  • sla.punctuality_tolerance_minutes (int)
  • sla.overbooking_rules (text/json)

G) Contract management (Admin-created + Partner-consented)

Required by contract section and workflow steps 5.1–5.2.

Contract (Admin-managed): - status (enum DRAFT|SENT|SIGNED|ACTIVE|SUSPENDED|TERMINATED|EXPIRED) - effective_from, effective_to - initial_term_months - auto_renew (bool) + renewal_term_months - notice_period_days - confidentiality_years - forum (string)

Signature (mutually agreed): - partner_signed_at, partner_signed_by_user_id - signed_document_file_key

Annex snapshots: - Annex I: list of service ids + per-service snapshot - Annex II: commercial terms snapshot - Annex III: cancellation policy set snapshot

Versioning: - immutable contract_versions snapshots for audit.

H) KPIs / performance (Admin-managed; mostly derived)

Required by workflow section 8.

  • kpi.avg_rating
  • kpi.complaints_count
  • kpi.partner_caused_cancellations
  • kpi.punctuality_incidents
  • kpi.revenue_volume
  • kpi.last_reviewed_at

I) Tasks & notifications (System/Admin-generated)

Required to drive actionable UI notifications with deep links.

Task: - assignee_type (PARTNER|ADMIN) - assignee_partner_id (when partner) - type (COMPLETE_PROFILE|UPLOAD_DOC|VERIFY_DOC|SIGN_CONTRACT|REVIEW_SERVICE_PROPOSAL|...) - status (OPEN|COMPLETED|DISMISSED) - priority, due_at - title, description - link (route for deep-link in partner-console/admin-console) - metadata (json)

Notes

  • File storage is via file-service; partner-service stores only file_key + metadata.
  • short_name is the canonical tenant slug; it should be immutable once set.