# magento-shippingfields

> **Package:** `portalpeople/magento-shippingfields`
> **Module:** `PortalPeople_ShippingFields`
> **Version:** v1.0.18
> **License:** MIT

Magento 2 module that adds two custom fields to the checkout shipping step and Magento order management:

- **Shipping Date** — a date picker (HTML5) for customers to select a preferred delivery date
- **Shipping Message** — a textarea (max 255 chars) for special shipping instructions

Fields are captured at checkout, saved to the quote, transferred to the order on submission, and visible/editable in the Magento admin order view.

---

## Architecture Summary (Authoritative Entry Point)

Before making changes, read:
- [docs/architecture.md](docs/architecture.md)
- [docs/BOUNDARIES.md](docs/BOUNDARIES.md)
- [docs/API.md](docs/API.md)

## Change Discipline (Required)

Before making functional changes to this module:

1. Produce a short written plan:
   - What problem is being solved?
   - Which files will change?
   - Does this affect API.md, BOUNDARIES.md, DATA_OWNERSHIP.md, or OBSERVABILITY.md?
2. Confirm boundary ownership (see docs/BOUNDARIES.md).
3. Update documentation if behaviour changes.
4. If ownership or API behaviour changes, create or update an ADR.

Do not introduce cross-module writes or new integrations without documenting them first.

---

## Installation

```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
```

**Requirements:**
- PHP >= 7.4
- Magento 2 with `magento/module-checkout`, `magento/module-quote`, `magento/module-sales`
- `portalpeople/magento-disableddates` (for disabled date/weekday configuration)

---

## Features

- Custom date and message fields in the checkout shipping step
- Date picker with configurable disabled weekdays and specific disabled dates
- Lead-time enforcement (date selection blocked for the next 2 working days)
- Fields visible and editable in Magento admin order view
- REST API endpoint for saving fields during checkout
- Extension attributes on Quote and Order interfaces
- Fields transferred from quote to order via observer

---

## Documentation

| Document | Purpose |
|----------|---------|
| [docs/architecture.md](docs/architecture.md) | Architecture diagrams (L0/L1/L3) |
| [docs/API.md](docs/API.md) | REST API, extension attributes, event contracts |
| [docs/BOUNDARIES.md](docs/BOUNDARIES.md) | Component boundaries and gap classifications |
| [docs/DATA_OWNERSHIP.md](docs/DATA_OWNERSHIP.md) | DB schema, data ownership, PII |
| [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) | Integration catalogue |
| [docs/OBSERVABILITY.md](docs/OBSERVABILITY.md) | Logging coverage |
| [docs/WORKFLOW.md](docs/WORKFLOW.md) | Local dev setup, known issues, PR checklist |
| [docs/GDPR.md](docs/GDPR.md) | Data protection policy |
| [docs/AUDIT.md](docs/AUDIT.md) | Audit findings |
| [docs/SECURITY.md](docs/SECURITY.md) | Security findings |
| [docs/TODO.md](docs/TODO.md) | Prioritised backlog |
| [docs/SYSTEM_MAP.md](docs/SYSTEM_MAP.md) | L0 context map |
| [docs/adr/ADR-000-discovery-baseline.md](docs/adr/ADR-000-discovery-baseline.md) | Discovery baseline |
