Design: Sales Quote: Per‐Tab Weight, Volume, and Chargeable Dimensions

Sales Quote: Per-Tab Weight, Volume, and Chargeable Dimensions

1. Overview

Goal: Define Weight, Weight UOM, Volume, Volume UOM, Chargeable, and Chargeable UOM per tab on the Sales Quote (Transport, Air, Sea, Warehousing). Default UOMs for each tab are taken from the respective Settings doctype.

Current state:

• Sales Quote has a single set of fields at the top level: weight, weight_uom, volume, volume_uom, chargeable, chargeable_uom (in section section_break_lgvi).
• These are used when creating Air Shipment, Sea Shipment, Air Booking, Sea Booking, and in Transport vehicle-type capacity validation.
• Default UOMs today come from Transport Capacity Settings (used in capacity/uom_conversion and Transport Order), not from mode-specific Settings.

Target state:

• Each service tab (Sea, Air, Transport, Warehousing) has its own dimensions section with: Weight, Weight UOM, Volume, Volume UOM, Chargeable, Chargeable UOM.
• Default UOMs for each tab come from:
  • Transport → Transport Settings
  • Air → Air Freight Settings
  • Sea → Sea Freight Settings
  • Warehousing → Warehouse Settings (Warehousing module)

Default UOMs are used across doctypes, not only in Sales Quote. Whenever a doctype needs a default weight/volume/chargeable UOM (e.g. new row in a child table, new document), it should take the default from the relevant Settings. A shared API and client/server usage are implemented so that Transport, Air, Sea, and Warehousing doctypes all apply these defaults where required.

---

2. Settings Doctypes

Tab	Settings DocType	Module	Action
Transport	Transport Settings	Transport	Add default_weight_uom, default_volume_uom, default_chargeable_uom (Link to UOM).
Air	Air Freight Settings	Air Freight	Add default_weight_uom, default_volume_uom, default_chargeable_uom.
Sea	Sea Freight Settings	Sea Freight	Add default_weight_uom, default_volume_uom, default_chargeable_uom.
Warehousing	Warehouse Settings	Warehousing	Add default_chargeable_uom only (already has default_weight_uom, default_volume_uom).

Note: Transport Capacity Settings already has default_weight_uom and default_volume_uom for capacity logic. For Sales Quote Transport tab defaults and other transport doctypes, the requirement is to use Transport Settings; hence Transport Settings gets the three default UOM fields. Capacity/conversion code can continue to use Transport Capacity Settings where appropriate.

2.1 Default UOMs used in other doctypes (implemented)

Domain	Settings	Where defaults are applied
Transport	Transport Settings	Transport Job Package: weight_uom, volume_uom defaulted on new row (client form_load and server before_insert).
Air	Air Freight Settings	Air Consolidation Shipments: weight_uom, volume_uom defaulted on new row (client form_load).
Sea	Sea Freight Settings	Sea Consolidation Shipments: weight_uom, volume_uom defaulted on new row (client form_load).
Warehousing	Warehouse Settings	Warehouse Contract Item, Warehouse Job Item, Inbound/Release/Transfer/VAS/Stocktake Order Item, Warehouse Item, etc.: volume_uom, weight_uom (and optionally default_chargeable_uom) via get_default_uoms(company) and client frappe.client.get_value on Warehouse Settings.

Shared API: logistics.utils.default_uom.get_default_uoms_for_domain(domain, company=None) returns { weight_uom, volume_uom, chargeable_uom } from the respective Settings. Whitelisted for client: get_default_uoms_for_domain_api(domain, company).

---

3. Sales Quote Field Layout (Per-Tab Dimensions)

3.1 Remove / Deprecate Top-Level Dimensions

• Remove from the main form (section section_break_lgvi) the single set: weight, weight_uom, volume, volume_uom, chargeable, chargeable_uom.
• Migration: Before removal, a one-time patch will copy existing values into the new per-tab fields (see § 5).

3.2 New Per-Tab Fields (on Sales Quote)

All fields live on the Sales Quote doctype. Each tab gets a Dimensions section with six fields. Naming prefix by tab:

Tab	Field prefix	Section placement
Sea	sea_	Inside Sea tab, before Sea Freight table (e.g. after sea_load_type).
Air	air_	Inside Air tab, before Air Freight table (e.g. after air_load_type).
Transport	transport_	Inside Transport tab, before Transport table (e.g. after transport_template / before section_break_disr).
Warehousing	warehouse_	Inside Warehousing tab, before Warehousing table (e.g. after site).

Field list per tab (repeat for each prefix):

Fieldname	Type	Label	Options/Notes
{prefix}weight	Float	Weight
{prefix}weight_uom	Link	Weight UOM	UOM
{prefix}volume	Float	Volume
{prefix}volume_uom	Link	Volume UOM	UOM
{prefix}chargeable	Float	Chargeable
{prefix}chargeable_uom	Link	Chargeable UOM	UOM

Visibility:

• Sea dimensions: depends_on: eval:doc.is_sea
• Air dimensions: depends_on: eval:doc.is_air
• Transport dimensions: depends_on: eval:doc.is_transport
• Warehousing dimensions: depends_on: eval:doc.is_warehousing

---

4. Default UOM from Settings (Client-Side)

When the user opens the Sales Quote form or focuses a tab, if the corresponding UOM fields for that tab are empty, set them from the respective Settings:

• Sea tab: sea_weight_uom, sea_volume_uom, sea_chargeable_uom from Sea Freight Settings (default_weight_uom, default_volume_uom, default_chargeable_uom).
• Air tab: air_weight_uom, air_volume_uom, air_chargeable_uom from Air Freight Settings (same field names).
• Transport tab: transport_weight_uom, transport_volume_uom, transport_chargeable_uom from Transport Settings (same field names).
• Warehousing tab: warehouse_weight_uom, warehouse_volume_uom, warehouse_chargeable_uom from Warehouse Settings (same field names; Warehouse Settings already has weight/volume; add default_chargeable_uom).

Implementation: in Sales Quote client script, on refresh or when a tab is shown, call a helper that for the active tab (or all visible tabs) fetches the matching Settings and sets the three UOM fields only when they are currently empty.

---

5. Server-Side Usage (Downstream Documents & Validation)

Replace any use of the old top-level weight, volume, chargeable (and their UOMs) with the per-tab fields as below.

Context	Source on Sales Quote
Transport – vehicle type capacity validation (validate_vehicle_type_capacity)	transport_weight, transport_weight_uom, transport_volume, transport_volume_uom (and chargeable if ever needed).
Air – create_air_shipment_from_sales_quote	air_weight, air_volume, air_chargeable (and UOMs if Air Shipment stores them).
Air – create_air_booking_from_sales_quote (both instance and static path)	air_weight, air_volume, air_chargeable; in get_sales_quote_data include air_weight, air_volume, air_chargeable in fetched fields and pass to Air Booking.
Sea – create_sea_shipment_from_sales_quote	sea_weight, sea_volume, sea_chargeable.
Sea – create_sea_booking_from_sales_quote	sea_weight, sea_volume, sea_chargeable.
Warehousing – create_warehouse_contract_from_sales_quote	Use warehouse_weight, warehouse_volume, warehouse_chargeable (and UOMs) if Warehouse Contract or related logic needs dimensions.

Any other code that reads weight, volume, chargeable from Sales Quote for a specific mode (e.g. reports, integrations) must be updated to the corresponding prefixed set.

---

6. Migration (Existing Data)

1. Add all new per-tab fields to Sales Quote (no removal of old fields in the first release if we want a safe rollback).
2. Patch: For every existing Sales Quote row, set:
   • transport_weight = weight, transport_weight_uom = weight_uom, same for volume and chargeable.
   • sea_weight = weight, … (same for Sea).
   • air_weight = weight, … (same for Air).
   • warehouse_weight = weight, … (same for Warehousing).
3. After validation: Remove from the form the old fields weight, weight_uom, volume, volume_uom, chargeable, chargeable_uom (and from field_order), and drop columns if desired in a later patch. Alternatively keep them deprecated and hidden for one version.

---

7. Implementation Checklist

Phase 1: Settings (done)

• Transport Settings – Add section “Default UOM” with default_weight_uom, default_volume_uom, default_chargeable_uom (Link to UOM).
• Air Freight Settings – Add same three fields under “Calculation Settings”.
• Sea Freight Settings – Add same three fields under “Calculation Settings”.
• Warehouse Settings – Add default_chargeable_uom (Link to UOM); keep existing default_weight_uom and default_volume_uom. Add get_default_uoms(company=None) returning volume, weight, chargeable, dimension.

Phase 2: Sales Quote Doctype

• Add dimensions section and 6 fields for Sea tab (sea_weight, sea_weight_uom, sea_volume, sea_volume_uom, sea_chargeable, sea_chargeable_uom) with depends_on for is_sea.
• Add dimensions section and 6 fields for Air tab (air_*) with depends_on for is_air.
• Add dimensions section and 6 fields for Transport tab (transport_*) with depends_on for is_transport.
• Add dimensions section and 6 fields for Warehousing tab (warehouse_*) with depends_on for is_warehousing.
• Remove (or hide and deprecate) the old top-level weight, weight_uom, volume, volume_uom, chargeable, chargeable_uom from the form and field_order.

Phase 3: Client Script (Sales Quote)

• On load/refresh (and optionally on tab focus), for each visible tab, if the tab’s UOM fields are empty, fetch the corresponding Settings and set default_weight_uom, default_volume_uom, default_chargeable_uom into the tab’s three UOM fields.

Phase 4: Server-Side (sales_quote.py and related)

• validate_vehicle_type_capacity: use transport_weight, transport_weight_uom, transport_volume, transport_volume_uom (and Transport Settings or Transport Capacity Settings for defaults if needed).
• create_air_shipment_from_sales_quote: map air_weight, air_volume, air_chargeable (and UOMs if applicable).
• create_sea_shipment_from_sales_quote: map sea_weight, sea_volume, sea_chargeable.
• create_air_booking_from_sales_quote (instance and static): use air_weight, air_volume, air_chargeable; update get_sales_quote_data to fetch and pass air_weight, air_volume, air_chargeable.
• create_sea_booking_from_sales_quote: use sea_weight, sea_volume, sea_chargeable.
• Warehouse Contract creation: use warehouse_weight, warehouse_volume, warehouse_chargeable where dimensions are required.

Phase 5: Migration

• Write patch that copies existing weight, weight_uom, volume, volume_uom, chargeable, chargeable_uom into all four per-tab field sets for existing Sales Quote documents.
• Run patch; verify data; then remove or hide old fields.

Phase 6: Default UOMs in other doctypes (done)

• Shared API – logistics.utils.default_uom.get_default_uoms_for_domain(domain, company) and whitelisted get_default_uoms_for_domain_api(domain, company).
• Transport Job Package – Server before_insert and client form_load set weight_uom, volume_uom from Transport Settings when empty.
• Air Consolidation Shipments – Client form_load sets weight_uom, volume_uom from Air Freight Settings when empty.
• Sea Consolidation Shipments – Client form_load sets weight_uom, volume_uom from Sea Freight Settings when empty.
• Warehouse Settings – get_default_uoms(company) now returns chargeable (and existing volume, weight, dimension) for use in Warehouse Contract Item and other warehousing doctypes.

---

8. Summary

• Weight, Weight UOM, Volume, Volume UOM, Chargeable, Chargeable UOM are defined per tab (Transport, Air, Sea, Warehousing) on the Sales Quote.
• Default UOMs are taken from Transport Settings, Air Freight Settings, Sea Freight Settings, and Warehouse Settings respectively; Settings are extended where these fields do not exist.
• Downstream creation and validation use the tab-specific fields; a one-time migration copies current top-level values into the new per-tab fields before the old fields are removed or deprecated.