@hadoan

Prompt: Implement "Create Import Shipment" screen (replace stub at /import/shipments/new)

You are implementing the business behavior for the Create Import Shipment screen in the Corely web app. The page currently shows: "Shipment creation is not available in this screen yet." Replace that stub with a fully working creation flow.

Non-negotiable first step (must do before building anything)

1. Scan the repo to learn how Corely does:

• Navigation + routing + breadcrumbs
• CRUD "New" screens and form layout standards
• Permission + workspace capability gating
• Validation messages, toasts, error states, loading states
• "Create → redirect to detail" patterns
• How idempotency keys / correlation IDs are attached on create actions (if the app uses them)

2. Read the docs folder (and any module standards) to align behavior:

• Import Shipments module doc (endpoints, statuses, required fields, business rules)
• UI/CRUD standards docs
• RBAC + capability docs

Then write a short "Behavior Plan" (1 page max) describing:

• What the user can do on this screen
• What fields are required vs optional
• What happens when they click Create
• Where they go next and why

---

Business goal

Enable Customs/Accounting users to start a new import shipment draft quickly, with enough structure to manage the shipment lifecycle and later allocate landed costs and create traceable lots.

This screen creates a DRAFT shipment using the existing Import Shipments API:

• POST /import/shipments

---

Who uses this screen

Primary users

• Customs user: creates shipments, enters container/BOL, manages milestones, uploads/attaches documents (if available), tracks clearance.
• Accounting user: confirms costs (FOB/freight/duties/taxes), ensures data quality for landed cost allocation and reporting.

Access rules

• Screen is visible only when workspace capability import.basic is enabled.
• Only users with import.shipments.manage can create shipments.
• Users with only import.shipments.read must not be able to create (hide "New" button and block direct URL access gracefully).

---

Screen: expected user experience

Page framing

• URL: /import/shipments/new
• Breadcrumb: Import / Shipments / New
• Title: Create Shipment
• Subtitle: Start a new import shipment draft

Primary actions

• Create Draft (primary button)
• Cancel (secondary; returns to shipments list)

Behavior: Create Draft

When clicked:

1. Validate required fields.

2. Create the shipment in DRAFT status.

3. On success:

   • Show a success confirmation (toast/banner).
   • Redirect to the newly created shipment detail page: /import/shipments/:id.

4. On error:

   • Show field-level errors for validation problems.
   • Show a clear global error message for server/network issues.
   • Keep entered form values intact.

---

Form content (business fields + validations)

Section A — Supplier & Reference (required to create)

Supplier (required)

• Choose from existing Parties marked as supplier (or supplier-capable).
• Validation: must be present.

Supplier reference (optional)

• Free text reference from supplier.

Shipment number (display only, optional)

• If Corely auto-numbers shipments, show "Assigned after create".

---

Section B — Shipping mode & transport (recommended at create, not mandatory)

Shipping mode (recommended)

• SEA / AIR / LAND / COURIER
• Default: the most common mode in the system (or blank if no pattern).

Carrier / forwarder (optional)

• Free text.

Vessel name / Voyage number (optional)

• Used mainly for SEA mode.

Bill of Lading / AWB number (optional at create; may be required later to submit depending on settings)

Container number / Seal number (optional)

• Multiple containers can be future scope; for now accept one container per shipment (or follow existing model).

---

Section C — Route & dates (optional at create; helps tracking)

Origin country / origin port (optional)
Destination country / destination port (optional)

Timeline dates (optional)

• Departure date
• ETA (estimated arrival)
• Actual arrival date
• Clearance date
• Received date (normally set when shipment is received, not during create)

Validation behavior:

• Dates must be valid calendar dates.
• If both departure and ETA exist: ETA must not be earlier than departure.

---

Section D — Shipment lines (optional to create, required to submit later)

Lines represent products in the shipment.

Minimum behavior for MVP

• Allow creating a shipment with zero lines (draft).

• Provide an easy way to add lines on this screen or immediately after create on detail page.

• If lines are supported on create:

  • Provide an "Add line" action that lets user add multiple products.

Line fields

• Product (required if line exists)

  • Select from Catalog items.
  • If Catalog item has HS code, auto-fill HS code (editable).

• HS code (optional but recommended)

• Ordered quantity (required if line exists; must be > 0)

• Unit FOB cost (optional)

  • If entered, line FOB cost is calculated.

• Line FOB cost (auto-calculated display; optional override only if business rules allow)

• Weight (kg) (optional; supports later allocation by weight)

• Volume (m3) (optional; supports later allocation by volume)

Line totals

• Show totals summary when lines exist:

  • Total ordered quantity
  • Total FOB (if costs provided)

---

Section E — Costs (optional at create; supports later landed cost)

Costs are not mandatory to create draft but should be available to input early.

Fields (either as structured cost lines or summary fields—follow existing design):

• Freight
• Insurance
• Duties
• Taxes
• Other

Behavior:

• Show Total landed cost = FOB + Freight + Insurance + Duties + Taxes + Other
• If FOB not known yet, show total as "Partial: excludes FOB" or equivalent.

---

Status behavior (business workflow alignment)

• Creating from this screen always produces DRAFT.

• The screen should not attempt to "Submit" the shipment.

• Submission rules (enforced elsewhere but visible as guidance):

  • Must have at least one line to submit.
  • May require BOL or Commercial Invoice depending on ImportSettings.

---

Guardrails & messaging (business language)

• If user lacks permission:
  "You don’t have access to create import shipments. Contact an admin to request access."
• If capability missing:
  "Import features aren’t enabled for this workspace."
• If validation fails:
  "Please fill the required fields to create a draft shipment."

---

Acceptance criteria (must pass)

1. A user with capability import.basic and permission import.shipments.manage can:

• Open /import/shipments/new
• Fill supplier (+ optional fields)
• Click Create Draft
• See success confirmation
• Land on shipment detail page with status DRAFT

2. A user without import.shipments.manage cannot create:

• The "New shipment" entry is hidden/disabled per Corely convention
• Directly visiting /import/shipments/new shows an access message and no create action

3. The form enforces required inputs:

• Supplier is required
• If any shipment line is added, product + ordered quantity are required and quantity > 0

4. The screen keeps user input on error and provides clear business-readable messages.

5. The screen uses consistent Corely UI patterns:

• Breadcrumbs, page header, buttons, error states, loading states

---

Deliverable (what you must change)

Replace the stub content on the New Shipment screen with a working "Create Draft Shipment" experience that matches the above behavior and integrates with the existing Import Shipments API.

Do not add new features beyond creation unless they are required to fulfill the behavior above.

---

Final output format (what you should produce after scanning repo/docs)

1. Behavior Plan (1 page max)
2. Implementation that makes the screen functional (no stub)
3. Manual QA checklist:

• authorized create
• unauthorized access
• validation errors
• success redirect