# ADR-000: Discovery Baseline — magento-shippingfields

> **Status:** Accepted
> **Date:** 2026-02-26 (Europe/London)
> **Author:** AI-assisted engineering review
> **Scope:** Read-only discovery audit — no code changes made

---

## Context

This ADR captures the discovered architecture state of `PortalPeople_ShippingFields` as found during initial documentation audit. It records confirmed facts, unknowns, and follow-up actions required before the module can be considered fully documented.

---

## Confirmed Facts

1. Module ID: `PortalPeople_ShippingFields`. PSR-4 namespace: `PortalPeople\ShippingFields\`.
2. Package: `portalpeople/magento-shippingfields` v1.0.18 (`composer.json`) — `setup_version="1.0.0"` in `module.xml` (conflict).
3. Purpose: Adds `shipping_date` and `shipping_message` fields to Magento 2 checkout, quote, and order.
4. Module declares sequence dependencies on `Magento_Checkout`, `Magento_Quote`, `Magento_Sales`.
5. REST API endpoint: `POST /V1/carts/mine/save-shipping-fields` (anonymous auth). Returns `bool`.
6. Six plugins registered: `ShippingInformationManagementPlugin` (primary capture), `QuoteRepositoryPlugin`, `CartRepositoryPlugin`, `OrderRepositoryPlugin`, `QuoteToOrderPlugin`, `PaymentInformationManagementPlugin` (logging only).
7. Observer: `QuoteSubmitBefore` fires on `sales_model_service_quote_submit_before` — copies fields from quote to order.
8. Extension attributes declared for `CartInterface` and `OrderInterface`.
9. DB: Two columns (`shipping_date`, `shipping_message`) added to both `quote` and `sales_order` via `InstallSchema.php`.
10. `DeliveryDateConfigProvider` provides disabled weekdays, disabled dates (from `portalpeople/magento-disableddates`), and lead time to frontend via `window.checkoutConfig.portalpeopleShippingFields`.
11. `portalpeople/magento-disableddates` is used by `DeliveryDateConfigProvider` but **not declared in `composer.json` require block**.
12. Frontend: three JS mixins — `set-shipping-information-mixin.js` (shipping step), `place-order-mixin.js` (order placement), `date-disabled-weekdays-mixin.js` (date picker).
13. `place-order-mixin.js` uses synchronous AJAX (`async: false`) — blocks browser main thread; deprecated in browsers.
14. Admin: `ShippingFields` block (view), `Edit/ShippingFields` block (edit), `Update` controller (POST save).
15. Admin `Update` controller ACL resource not confirmed from source.
16. Dual save path: both REST API (`ShippingFieldsManagement`) and `ShippingInformationManagementPlugin` write to quote.
17. Dual transfer path: both `QuoteSubmitBefore` observer and `QuoteToOrderPlugin` transfer fields from quote to order.
18. `PaymentInformationManagementPlugin` performs debug logging only — no field capture.
19. Logging is PSR-3, verbose, emoji-prefixed. No structured log context. No correlation IDs.
20. Backup files in source: `sales_order_edit_index.xml.bak`, `place-order-mixin.js.bak`. Stray file: `Untitled-1.html`.
21. No PHPUnit test configuration found.
22. `shipping_message` is a free-text field — may contain customer personal data.

---

## Unknowns

1. `UNKNOWN — Requires Clarification`: Is `portalpeople/magento-disableddates` a required or optional dependency?
2. `UNKNOWN — Requires Clarification`: Does `DeliveryDateConfigProvider` guard against the absence of `magento-disableddates`?
3. `UNKNOWN — Requires Clarification`: Is the dual save path (REST API + `ShippingInformationManagementPlugin`) intentional? Which is authoritative?
4. `UNKNOWN — Requires Clarification`: Is `QuoteToOrderPlugin` redundant with `QuoteSubmitBefore` observer?
5. `UNKNOWN — Requires Clarification`: What ACL resource protects the admin `Update` controller?
6. `UNKNOWN — Requires Clarification`: Does `set-shipping-information-mixin.js` block checkout on REST API failure?
7. `UNKNOWN — Requires Clarification`: Is `shipping_date` required on the frontend?
8. `UNKNOWN — Requires Clarification`: Exact column types for `shipping_date` and `shipping_message`.
9. `UNKNOWN — Requires Clarification`: What log channel does the PSR-3 logger write to?
10. `UNKNOWN — Requires Clarification`: What is the canonical version of this module?
11. `UNKNOWN — Requires Clarification`: Is there a data retention policy for `shipping_date` and `shipping_message`?
12. `UNKNOWN — Requires Clarification`: Has GDPR assessment been done for `shipping_message` free-text field?

---

## Follow-up Actions

1. Add `portalpeople/magento-disableddates` to `composer.json` require, or add null-guard in `DeliveryDateConfigProvider` if optional.
2. Replace synchronous AJAX (`async: false`) in `place-order-mixin.js` with async call.
3. Confirm and document which save path is authoritative (REST API vs `ShippingInformationManagementPlugin`).
4. Confirm and document which transfer path is authoritative (observer vs `QuoteToOrderPlugin`).
5. Confirm ACL resource on admin `Update` controller; document in `API.md`.
6. Remove backup files (`*.bak`) and stray file (`Untitled-1.html`) from repository.
7. Align version strings: `composer.json` v1.0.18 vs `module.xml` `setup_version="1.0.0"`.
8. Confirm exact DB column types and update `DATA_OWNERSHIP.md`.
9. Add PHPUnit tests for `ShippingFieldsManagement`, `QuoteSubmitBefore`, and plugin conditions.
10. Review `shipping_message` for GDPR logging implications; add redaction if needed.

---

## Evidence

- `/modules/magento-shippingfields/composer.json`
- `/modules/magento-shippingfields/src/etc/module.xml`
- `/modules/magento-shippingfields/src/etc/events.xml`
- `/modules/magento-shippingfields/src/etc/di.xml`
- `/modules/magento-shippingfields/src/etc/frontend/di.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/src/Api/ShippingFieldsInterface.php`
- `/modules/magento-shippingfields/src/Model/ShippingFieldsManagement.php`
- `/modules/magento-shippingfields/src/Model/Checkout/DeliveryDateConfigProvider.php`
- `/modules/magento-shippingfields/src/Observer/QuoteSubmitBefore.php`
- `/modules/magento-shippingfields/src/Plugin/ShippingInformationManagementPlugin.php`
- `/modules/magento-shippingfields/src/Plugin/QuoteToOrderPlugin.php`
- `/modules/magento-shippingfields/src/Controller/Adminhtml/Order/Update.php`
- `/modules/magento-shippingfields/src/Setup/InstallSchema.php`
- `/modules/magento-shippingfields/src/view/frontend/web/js/action/set-shipping-information-mixin.js`
- `/modules/magento-shippingfields/src/view/frontend/web/js/action/place-order-mixin.js`
