# Workflow — magento-shippingfields

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

---

## Local Development Setup

### Prerequisites

- PHP >= 7.4
- Magento 2 development environment
- Composer
- `portalpeople/magento-disableddates` installed (required for date picker disabled dates)

### Install

```bash
composer require portalpeople/magento-shippingfields
bin/magento module:enable PortalPeople_ShippingFields
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush
```

### Verify

After install, the following should be present:
- Checkout shipping step shows a date picker and message textarea
- Columns `shipping_date` and `shipping_message` exist on both `quote` and `sales_order` tables
- Admin order view shows a "Shipping Fields" section

---

## Known Issues

| Issue | Severity | Details |
|-------|----------|---------|
| Synchronous AJAX in `place-order-mixin.js` | HIGH | `async: false` blocks the browser main thread — deprecated in browsers |
| `portalpeople/magento-disableddates` not declared in `composer.json` | MEDIUM | Missing dependency declaration — install will not pull it automatically |
| Backup files in source | LOW | `sales_order_edit_index.xml.bak`, `place-order-mixin.js.bak` should be removed |
| Stray file `Untitled-1.html` in adminhtml | LOW | Stray file in `src/view/adminhtml/` — not part of the module |
| Emoji in production logs | LOW | Not enterprise-standard; may not be grep/aggregation-friendly |
| Version mismatch | LOW | `composer.json` v1.0.18 vs `module.xml` `setup_version="1.0.0"` |
| Dual save path ambiguity | MEDIUM | Both REST API and `ShippingInformationManagementPlugin` write fields to quote |
| Admin Update controller ACL | MEDIUM | ACL resource protecting admin order edit not confirmed |

---

## Testing

No PHPUnit test suite exists. All verification is manual.

Manual test scenarios to verify after changes:
1. Complete guest checkout — verify fields appear on order in admin
2. Complete logged-in checkout — verify fields appear on order in admin
3. Admin order edit — verify fields can be updated and saved
4. Test with disabled weekdays configured — verify date picker disables correct days
5. Test with disabled dates configured — verify specific dates are blocked

---

## PR Checklist

- [ ] No non-documentation files modified unless Implementation Mode is explicitly enabled
- [ ] `docs/architecture.md` updated if plugin logic, observer behaviour, or data flow changed
- [ ] `docs/API.md` updated if REST endpoint params, extension attributes, or admin routes changed
- [ ] `docs/BOUNDARIES.md` updated if new dependencies or plugin targets added
- [ ] `docs/DATA_OWNERSHIP.md` updated if new columns added or field types changed
- [ ] `docs/INTEGRATIONS.md` updated if new external integrations added
- [ ] `docs/OBSERVABILITY.md` updated if logging changes
- [ ] `docs/GDPR.md` reviewed if new personal data is collected in `shipping_message` or new fields added
- [ ] Mermaid diagrams updated and standards-compliant
- [ ] Backup `.bak` files not committed
- [ ] Version strings aligned: `composer.json`, `module.xml`
- [ ] All `UNKNOWN — Requires Clarification` tokens resolved or escalated
- [ ] Dual save path behaviour confirmed and documented

---

## Confirmed Facts

- Install follows standard Magento 2 `composer require` + `setup:upgrade` workflow.
- No CLI commands provided by this module.
- No PHPUnit tests exist.

---

## Unknowns

1. `UNKNOWN — Requires Clarification`: Is `portalpeople/magento-disableddates` required in all environments?
2. `UNKNOWN — Requires Clarification`: Is there a staging environment to test checkout fields end-to-end?

---

## Evidence

- `/modules/magento-shippingfields/composer.json`
- `/modules/magento-shippingfields/src/etc/module.xml`
- `/modules/magento-shippingfields/src/Setup/InstallSchema.php`
- `/modules/magento-shippingfields/src/view/frontend/web/js/action/place-order-mixin.js`
