Add import preflight workflow

Author: ruicore

docs/getting-started.md

@@ -193,12 +193,14 @@ These two documents explain:
 If you are integrating ExcelAlchemy into a web backend, the recommended public
 result surface is:
 
+- `ImportPreflightResult`
 - `ImportResult`
 - `alchemy.cell_error_map`
 - `alchemy.row_error_map`
 
 These objects let you return:
 
+- a lightweight preflight summary before import
 - a high-level import summary
 - row-level error summaries
 - cell-level coordinates for UI highlighting
@@ -208,3 +210,44 @@ See:
 - [`docs/result-objects.md`](result-objects.md)
 - [`docs/api-response-cookbook.md`](api-response-cookbook.md)
 - [`examples/fastapi_reference/README.md`](../examples/fastapi_reference/README.md)
+
+## 9. Use Preflight Before Import When You Need A Quick Structural Check
+
+Use `preflight_import(...)` when you want a fast answer to:
+
+- does the configured sheet exist
+- do the headers match the schema
+- does the workbook look structurally importable
+- about how many rows would a later import process
+
+Use `import_data(...)` when you want the full workflow:
+
+- row validation
+- create / update callback execution
+- cell and row error maps
+- result workbook rendering and upload
+
+Typical backend flow:
+
+```python
+preflight = alchemy.preflight_import('employees.xlsx')
+
+if not preflight.is_valid:
+    return {
+        'preflight': preflight.to_api_payload(),
+    }
+
+result = await alchemy.import_data('employees.xlsx', 'employees-result.xlsx')
+
+return {
+    'preflight': preflight.to_api_payload(),
+    'result': result.to_api_payload(),
+    'cell_errors': alchemy.cell_error_map.to_api_payload(),
+    'row_errors': alchemy.row_error_map.to_api_payload(),
+}
+```
+
+Keep this distinction in mind:
+
+- preflight is lightweight and structural
+- import is the full validation and execution path

docs/public-api.md

@@ -34,7 +34,8 @@ These modules are the recommended import paths for application code:
   this additive public surface.
 - `excelalchemy.results`
   Structured import result models such as `ImportResult`,
-  `ValidateResult`, and `ValidateHeaderResult`.
+  `ValidateResult`, `ValidateHeaderResult`, `ImportPreflightResult`, and
+  `ImportPreflightStatus`.
 - `excelalchemy.exceptions`
   Stable exception module for `ConfigError`, `ExcelCellError`,
   `ExcelRowError`, and `ProgrammaticError`.
@@ -52,6 +53,9 @@ These modules are the recommended import paths for application code:
 - `ExcelAlchemy.import_data(..., on_event=...)`
   The additive public hook for synchronous import lifecycle events during one
   import run.
+- `ExcelAlchemy.preflight_import(...)`
+  The additive public hook for lightweight structural validation before full
+  import execution.
 - import inspection names:
   Prefer `worksheet_table`, `header_table`, `cell_error_map`, and
   `row_error_map` when reading import-run state from the facade.

docs/result-objects.md

@@ -14,6 +14,7 @@ If you want copyable success / failure / header-invalid response shapes, see
 
 The most important public result objects are:
 
+- `ImportPreflightResult`
 - `ImportResult`
 - `CellErrorMap`
 - `RowIssueMap`
@@ -302,6 +303,100 @@ response = {
 }
 ```
 
+## `ImportPreflightResult`
+
+`ImportPreflightResult` is the high-level summary of one lightweight structural
+preflight run.
+
+Useful fields include:
+
+- `status`
+  Overall status such as `VALID`, `HEADER_INVALID`, `SHEET_MISSING`, or
+  `STRUCTURE_INVALID`.
+- `sheet_name`
+  The configured worksheet name used for preflight.
+- `sheet_exists`
+  Whether the configured worksheet was found.
+- `has_merged_header`
+  Whether the header block was detected as merged when readable.
+- `estimated_row_count`
+  Estimated number of data rows for a later import run.
+- `structural_issue_codes`
+  Stable machine-readable codes for non-header structural failures.
+
+Typical usage:
+
+```python
+result = alchemy.preflight_import('employees.xlsx')
+
+if result.is_valid:
+    ...
+```
+
+Use preflight when you need a quick structural gate before the real import.
+
+Practical cases:
+
+- reject uploads that are missing the target sheet
+- stop early when headers do not match the schema
+- show a lightweight “looks importable” response before running row validation
+
+Do not treat preflight as a replacement for `import_data(...)`.
+
+Preflight does not do:
+
+- row-level validation
+- create / update execution
+- cell or row error collection
+- result workbook generation
+
+Useful helpers:
+
+- `is_valid`
+- `is_header_invalid`
+- `is_sheet_missing`
+- `is_structure_invalid`
+- `to_api_payload()`
+
+Example payload:
+
+```json
+{
+  "status": "HEADER_INVALID",
+  "is_valid": false,
+  "is_header_invalid": true,
+  "is_sheet_missing": false,
+  "is_structure_invalid": false,
+  "sheet": {
+    "name": "Sheet1",
+    "exists": true,
+    "has_merged_header": false
+  },
+  "summary": {
+    "estimated_row_count": 3,
+    "structural_issue_codes": []
+  },
+  "header_issues": {
+    "is_required_missing": true,
+    "missing_required": ["Age"],
+    "missing_primary": [],
+    "unrecognized": ["Unexpected Column"],
+    "duplicated": []
+  }
+}
+```
+
+Simple workflow:
+
+```python
+preflight = alchemy.preflight_import('employees.xlsx')
+
+if not preflight.is_valid:
+    return {'preflight': preflight.to_api_payload()}
+
+result = await alchemy.import_data('employees.xlsx', 'employees-result.xlsx')
+```
+
 This gives you:
 
 - a stable top-level import summary