# Boundaries — magento-shippingfields

> **Last verified:** 2026-02-26 (Europe/London)
> **Owner:** Engineering
> **Related:** [architecture.md](architecture.md) | [INTEGRATIONS.md](INTEGRATIONS.md)

---

## Internal Components

| Component | Responsibility | Owns Writes | Notes |
|-----------|---------------|-------------|-------|
| `ShippingFieldsManagement` | REST API implementation — saves fields to quote via CartRepository | `quote` (via CartRepository) | Primary save path for frontend REST call |
| `ShippingInformationManagementPlugin` | Intercepts `saveAddressInformation`; extracts fields from request JSON; saves to quote | `quote` (secondary save path) | Overlap with REST API save path |
| `QuoteRepositoryPlugin` | Syncs extension attributes ↔ quote data on save/get | None — sync only | |
| `CartRepositoryPlugin` | Syncs extension attributes ↔ cart data on save/get | None — sync only | |
| `OrderRepositoryPlugin` | Syncs extension attributes ↔ order data on save/get; reads from request | None — sync only | Reading from request in `afterGet` is unusual |
| `QuoteToOrderPlugin` | Transfers fields from quote to order item on conversion | None — read/set only | May overlap with QuoteSubmitBefore observer |
| `PaymentInformationManagementPlugin` | Debug logging only | None | No field capture |
| `QuoteSubmitBefore` observer | Copies `shipping_date` and `shipping_message` from quote to order | `sales_order` (via order object, Magento core saves) | Fires on `sales_model_service_quote_submit_before` |
| `DeliveryDateConfigProvider` | Provides disabled dates, weekdays, and lead time to frontend | None | Reads `portalpeople/magento-disableddates` collection |
| `ShippingFields` block (view) | Renders fields on admin order view | None | |
| `Edit/ShippingFields` block | Renders editable form on admin order edit | None | |
| `Update` controller | POST handler for admin order field edits | `sales_order` | ACL resource `UNKNOWN — Requires Clarification` |

---

## External Boundaries

| External System | Relationship | Direction | Mechanism | Notes |
|-----------------|-------------|-----------|-----------|-------|
| Magento Checkout Module (`Magento_Checkout`) | Plugin targets | Inbound | `ShippingInformationManagementPlugin`, `PaymentInformationManagementPlugin` | Module declares sequence dependency |
| Magento Quote Module (`Magento_Quote`) | Plugin targets + data store | Bidirectional | `QuoteRepositoryPlugin`, `CartRepositoryPlugin`; `quote` table | Module declares sequence dependency |
| Magento Sales Module (`Magento_Sales`) | Plugin targets + event + data store | Bidirectional | `OrderRepositoryPlugin`; `sales_model_service_quote_submit_before` observer; `sales_order` table | Module declares sequence dependency |
| `portalpeople/magento-disableddates` | Disabled date/weekday source | Inbound | `CollectionFactory` in `DeliveryDateConfigProvider` | **Not declared in `composer.json` require block** |

---

## Data Boundary — Tables

| Table | Action | Mechanism | Owner |
|-------|--------|-----------|-------|
| `quote` | Adds `shipping_date` (DATE, nullable), `shipping_message` (varchar/text, nullable) | `InstallSchema.php` | This module adds columns; Magento owns the table |
| `sales_order` | Adds `shipping_date` (DATE, nullable), `shipping_message` (varchar/text, nullable) | `InstallSchema.php` | This module adds columns; Magento owns the table |

Writes to `quote.shipping_date` / `shipping_message` are made by:
- `ShippingFieldsManagement` (REST API path)
- `ShippingInformationManagementPlugin` (shipping step interception path)

Writes to `sales_order.shipping_date` / `shipping_message` are made by:
- `QuoteSubmitBefore` observer (via order object, Magento core persists)

---

## Gap Classifications

### BOUNDARY GAP
- **What is missing:** `portalpeople/magento-disableddates` is used by `DeliveryDateConfigProvider` but is not declared in `composer.json` require block.
- **Where found:** `/modules/magento-shippingfields/composer.json`, `/modules/magento-shippingfields/src/Model/Checkout/DeliveryDateConfigProvider.php`
- **Minimum addition required:** Add `portalpeople/magento-disableddates` to `composer.json` require, or add a null-guard in `DeliveryDateConfigProvider` if the dependency is optional.

### API CONTRACT GAP
- **What is missing:** Admin `Update` controller ACL resource is not documented. The controller modifies order data — access should be explicitly restricted.
- **Where found:** `/modules/magento-shippingfields/src/Controller/Adminhtml/Order/Update.php`, `/modules/magento-shippingfields/src/etc/adminhtml/routes.xml`
- **Minimum addition required:** Confirm ACL resource used and document in `API.md`.

### BOUNDARY GAP
- **What is missing:** Dual save paths for `shipping_date` / `shipping_message` — both `ShippingFieldsManagement` (REST API) and `ShippingInformationManagementPlugin` write to quote. It is unclear which is authoritative when both fire.
- **Where found:** `/modules/magento-shippingfields/src/Model/ShippingFieldsManagement.php`, `/modules/magento-shippingfields/src/Plugin/ShippingInformationManagementPlugin.php`
- **Minimum addition required:** Document which path is intended to be authoritative. If both can fire, confirm idempotency.

### BOUNDARY GAP
- **What is missing:** Dual transfer paths from quote to order — both `QuoteSubmitBefore` observer and `QuoteToOrderPlugin` appear to transfer fields. The interaction and priority are undocumented.
- **Where found:** `/modules/magento-shippingfields/src/Observer/QuoteSubmitBefore.php`, `/modules/magento-shippingfields/src/Plugin/QuoteToOrderPlugin.php`
- **Minimum addition required:** Document which path is authoritative or confirm one is a fallback.

### CONFIGURATION GAP
- **What is missing:** Backup files (`sales_order_edit_index.xml.bak`, `place-order-mixin.js.bak`) and stray file (`Untitled-1.html`) in the source tree.
- **Where found:** `/modules/magento-shippingfields/src/view/adminhtml/layout/`, `/modules/magento-shippingfields/src/view/frontend/web/js/action/`, `/modules/magento-shippingfields/src/view/adminhtml/`
- **Minimum addition required:** Remove `.bak` files and `Untitled-1.html` from the repository.

---

## Confirmed Facts

- Module declares sequence dependencies on `Magento_Checkout`, `Magento_Quote`, `Magento_Sales`.
- All six plugins are registered in `src/etc/di.xml`.
- Observer is registered in `src/etc/events.xml` for `sales_model_service_quote_submit_before`.
- Extension attributes are declared for both `CartInterface` and `OrderInterface`.

---

## Unknowns

1. `UNKNOWN — Requires Clarification`: Is the dual save path (REST API + ShippingInformationManagementPlugin) intentional? Which is authoritative?
2. `UNKNOWN — Requires Clarification`: Is `portalpeople/magento-disableddates` a required or optional dependency?
3. `UNKNOWN — Requires Clarification`: What ACL resource does the admin `Update` controller check?
4. `UNKNOWN — Requires Clarification`: Is `QuoteToOrderPlugin` redundant with `QuoteSubmitBefore` observer?

---

## Evidence

- `/modules/magento-shippingfields/src/etc/module.xml`
- `/modules/magento-shippingfields/src/etc/di.xml`
- `/modules/magento-shippingfields/src/etc/events.xml`
- `/modules/magento-shippingfields/src/etc/extension_attributes.xml`
- `/modules/magento-shippingfields/src/etc/webapi.xml`
- `/modules/magento-shippingfields/src/etc/adminhtml/routes.xml`
- `/modules/magento-shippingfields/composer.json`
- `/modules/magento-shippingfields/src/Model/ShippingFieldsManagement.php`
- `/modules/magento-shippingfields/src/Plugin/ShippingInformationManagementPlugin.php`
- `/modules/magento-shippingfields/src/Observer/QuoteSubmitBefore.php`
- `/modules/magento-shippingfields/src/Plugin/QuoteToOrderPlugin.php`
- `/modules/magento-shippingfields/src/Model/Checkout/DeliveryDateConfigProvider.php`
