orion/docs/development/migration/store-contact-inheritance.md

Store Contact Inheritance Migration

Overview

Feature: Add contact information fields to Store model with inheritance from Merchant.

Pattern: Nullable with Fallback - Store fields are nullable; if null, inherit from parent merchant at read time.

Benefits:

• Stores inherit merchant contact info by default
• Can override specific fields for store-specific branding/identity
• Can reset to "inherit from merchant" by setting field to null
• Merchant updates automatically reflect in stores that haven't overridden

---

Database Changes

New Columns in store Table

Column	Type	Nullable	Default	Description
contact_email	VARCHAR(255)	Yes	NULL	Override merchant contact email
contact_phone	VARCHAR(50)	Yes	NULL	Override merchant contact phone
website	VARCHAR(255)	Yes	NULL	Override merchant website
business_address	TEXT	Yes	NULL	Override merchant business address
tax_number	VARCHAR(100)	Yes	NULL	Override merchant tax number

Resolution Logic

effective_value = store.field if store.field is not None else store.merchant.field

---

Files to Modify

1. Database Model

• models/database/store.py - Add nullable contact fields

2. Alembic Migration

• alembic/versions/xxx_add_store_contact_fields.py - New migration

3. Pydantic Schemas

• models/schema/store.py:
  • StoreUpdate - Add optional contact fields
  • StoreResponse - Add resolved contact fields
  • StoreDetailResponse - Add contact fields with inheritance indicator

4. Service Layer

• app/services/store_service.py - Add contact resolution helper
• app/services/admin_service.py - Update create/update to handle contact fields

5. API Endpoints

• app/api/v1/admin/stores.py - Update responses to include resolved contact info

6. Frontend

• app/templates/admin/store-edit.html - Add contact fields with inheritance toggle
• static/admin/js/store-edit.js - Handle inheritance UI logic

---

Implementation Steps

Step 1: Database Model

# models/database/store.py

class Store(Base):
    # ... existing fields ...

    # Contact fields (nullable = inherit from merchant)
    contact_email = Column(String(255), nullable=True)
    contact_phone = Column(String(50), nullable=True)
    website = Column(String(255), nullable=True)
    business_address = Column(Text, nullable=True)
    tax_number = Column(String(100), nullable=True)

    # Helper properties for resolved values
    @property
    def effective_contact_email(self) -> str | None:
        return self.contact_email if self.contact_email is not None else (
            self.merchant.contact_email if self.merchant else None
        )

    @property
    def effective_contact_phone(self) -> str | None:
        return self.contact_phone if self.contact_phone is not None else (
            self.merchant.contact_phone if self.merchant else None
        )

    # ... similar for other fields ...

Step 2: Alembic Migration

def upgrade():
    op.add_column('store', sa.Column('contact_email', sa.String(255), nullable=True))
    op.add_column('store', sa.Column('contact_phone', sa.String(50), nullable=True))
    op.add_column('store', sa.Column('website', sa.String(255), nullable=True))
    op.add_column('store', sa.Column('business_address', sa.Text(), nullable=True))
    op.add_column('store', sa.Column('tax_number', sa.String(100), nullable=True))

def downgrade():
    op.drop_column('store', 'tax_number')
    op.drop_column('store', 'business_address')
    op.drop_column('store', 'website')
    op.drop_column('store', 'contact_phone')
    op.drop_column('store', 'contact_email')

Step 3: Pydantic Schemas

# models/schema/store.py

class StoreUpdate(BaseModel):
    # ... existing fields ...

    # Contact fields (None = don't update, empty string could mean "clear/inherit")
    contact_email: str | None = None
    contact_phone: str | None = None
    website: str | None = None
    business_address: str | None = None
    tax_number: str | None = None

class StoreContactInfo(BaseModel):
    """Resolved contact information with inheritance indicators."""
    contact_email: str | None
    contact_phone: str | None
    website: str | None
    business_address: str | None
    tax_number: str | None

    # Inheritance flags
    contact_email_inherited: bool = False
    contact_phone_inherited: bool = False
    website_inherited: bool = False
    business_address_inherited: bool = False
    tax_number_inherited: bool = False

class StoreDetailResponse(BaseModel):
    # ... existing fields ...

    # Resolved contact info
    contact_email: str | None
    contact_phone: str | None
    website: str | None
    business_address: str | None
    tax_number: str | None

    # Inheritance indicators (for UI)
    contact_email_inherited: bool
    contact_phone_inherited: bool
    website_inherited: bool
    business_address_inherited: bool
    tax_number_inherited: bool

Step 4: Service Layer Helper

# app/services/store_service.py

def get_resolved_contact_info(self, store: Store) -> dict:
    """
    Get resolved contact information with inheritance flags.

    Returns dict with both values and flags indicating if inherited.
    """
    merchant = store.merchant

    return {
        "contact_email": store.contact_email or (merchant.contact_email if merchant else None),
        "contact_email_inherited": store.contact_email is None and merchant is not None,

        "contact_phone": store.contact_phone or (merchant.contact_phone if merchant else None),
        "contact_phone_inherited": store.contact_phone is None and merchant is not None,

        "website": store.website or (merchant.website if merchant else None),
        "website_inherited": store.website is None and merchant is not None,

        "business_address": store.business_address or (merchant.business_address if merchant else None),
        "business_address_inherited": store.business_address is None and merchant is not None,

        "tax_number": store.tax_number or (merchant.tax_number if merchant else None),
        "tax_number_inherited": store.tax_number is None and merchant is not None,
    }

Step 5: API Endpoint Updates

# app/api/v1/admin/stores.py

@router.get("/{store_identifier}", response_model=StoreDetailResponse)
def get_store_details(...):
    store = store_service.get_store_by_identifier(db, store_identifier)
    contact_info = store_service.get_resolved_contact_info(store)

    return StoreDetailResponse(
        # ... existing fields ...
        **contact_info,  # Includes values and inheritance flags
    )

Step 6: Frontend UI

<!-- Store edit form with inheritance toggle -->
<label class="block text-sm">
    <span class="text-gray-700 dark:text-gray-400">
        Contact Email
        <span x-show="contactEmailInherited" class="text-xs text-purple-500">(inherited from merchant)</span>
    </span>
    <div class="flex gap-2">
        <input type="email" x-model="formData.contact_email"
               :placeholder="merchantContactEmail"
               :class="{ 'bg-gray-100': contactEmailInherited }">
        <button type="button" @click="resetToMerchant('contact_email')"
                x-show="!contactEmailInherited"
                class="text-sm text-purple-600">
            Reset to Merchant
        </button>
    </div>
</label>

---

API Behavior

GET /api/v1/admin/stores/{id}

Returns resolved contact info with inheritance flags:

{
  "id": 1,
  "store_code": "STORE001",
  "name": "My Store",
  "contact_email": "sales@merchant.com",
  "contact_email_inherited": true,
  "contact_phone": "+352 123 456",
  "contact_phone_inherited": false,
  "website": "https://merchant.com",
  "website_inherited": true
}

PUT /api/v1/admin/stores/{id}

To override a field:

{
  "contact_email": "store-specific@example.com"
}

To reset to inherit from merchant (set to null):

{
  "contact_email": null
}

---

Testing Plan

1. Create store - Verify contact fields are null (inheriting)
2. Read store - Verify resolved values come from merchant
3. Update store contact - Verify override works
4. Reset to inherit - Verify setting null restores inheritance
5. Update merchant - Verify change reflects in inheriting stores
6. Update merchant - Verify change does NOT affect overridden stores

---

Rollback Plan

If issues occur:

1. Run downgrade migration: alembic downgrade -1
2. Revert code changes
3. Re-deploy

---

Progress Tracking

• Database model updated
• Alembic migration created and applied
• Pydantic schemas updated
• Service layer helper added
• API endpoints updated
• Frontend forms updated
• Tests written and passing
• Documentation updated