Skip to content

SUPPORTED_WORKBOOK_LAYOUTS.md

Latest commit

 

History

History
83 lines (53 loc) · 2.34 KB

SUPPORTED_WORKBOOK_LAYOUTS.md

File metadata and controls

83 lines (53 loc) · 2.34 KB
Raw

Supported Workbook Layouts

This branch keeps the existing Quotr-style quote model, but the Excel parser now accepts a small set of explicit workbook variations.

Supported Variations

1. Standard Fixed Layout

Use this when the workbook follows the original sample contract.

  • Worksheet name can be anything
  • Labels are in A1:A8
  • Values are in B1:B8
  • Item headers start on row 10
  • Canonical item headers are used directly

Sample file generated by --bootstrap:

  • sample_data/sample_quote_input.xlsx

2. English Alias Layout

Use this for customer files that keep a quotation sheet but rename columns.

  • Preferred worksheet names include Customer Quote or Quotation
  • Metadata is read from row-based label/value pairs
  • Item headers can start later in the sheet
  • Supported aliases include:
    • Product Name -> Item
    • Specification -> Description
    • UOM -> Unit
    • Qty -> Quantity
    • Sales Price -> Unit Price

Sample file generated by --bootstrap:

  • sample_data/sample_quote_input_alias_layout.xlsx

3. Chinese Label Layout

Use this for Chinese customer workbooks with localized labels.

  • Preferred worksheet names include 报价 or 报价单
  • Metadata labels can use Chinese names such as 客户名称, 报价单号, 有效期至, 折扣
  • Item headers can use Chinese aliases such as 品名, 规格型号, 单位, 数量, 单价

Sample file generated by --bootstrap:

  • sample_data/sample_quote_input_chinese_layout.xlsx

Worksheet Detection Rules

The parser scores each worksheet and selects the best match using:

  • Presence of required item fields after alias normalization
  • Preferred quotation worksheet names
  • Presence of recognizable metadata labels

The parser does not silently accept weak matches. If no worksheet contains a complete required item mapping, parsing fails with a sheet-specific error.

Required Canonical Fields

Every supported layout must still map to these required fields:

  • Item
  • Description
  • Quantity
  • Unit Price

Optional field:

  • Unit

Error Reporting

If a workbook is close to valid but still mismatched, the parser reports:

  • The worksheet name
  • The detected header row
  • The missing canonical field
  • Example aliases that are accepted for that field

This keeps validation strict while making the fix path obvious for real customer files.