Merge pull request #66 from RayCarterLab/v2.2

release: prepare ExcelAlchemy 2.2.6

Author: ruicore

CHANGELOG.md

@@ -4,6 +4,51 @@ All notable changes to this project will be documented in this file.
 
 The format is inspired by Keep a Changelog and versioned according to PEP 440.
 
+## [2.2.6] - 2026-04-04
+
+This release continues the stable 2.x line with stronger consumer-facing
+result-object guidance, a copyable FastAPI reference project, harder release
+smoke validation, and clearer codec fallback diagnostics.
+
+### Added
+
+- Added `docs/result-objects.md` to explain how to read `ImportResult`,
+  `CellErrorMap`, and `RowIssueMap` and how to expose them through backend APIs
+- Added a copyable FastAPI reference project under `examples/fastapi_reference`
+  with separate route, service, storage, and schema modules
+- Added a captured output artifact for the FastAPI reference project and linked
+  it from the examples docs and showcase
+
+### Changed
+
+- Extended `docs/getting-started.md`, `docs/public-api.md`,
+  `docs/examples-showcase.md`, and the README entry points so the result
+  objects and API integration path are easier to discover
+- Strengthened package smoke verification by validating both successful and
+  failed imports, including structured `cell_error_map` and `row_error_map`
+  payloads
+- Expanded example smoke coverage so the FastAPI reference project is exercised
+  directly alongside the existing script-style examples
+- Polished codec fallback warnings so parse failures now produce clearer
+  developer-facing diagnostics with field labels and cleaner exception reasons
+
+### Compatibility Notes
+
+- No public import or export workflow API was removed in this release
+- `ImportResult`, `CellErrorMap`, and `RowIssueMap` remain the stable public
+  result objects for 2.x integrations
+- The FastAPI reference project is additive guidance and does not change the
+  public API surface
+- `storage=...` remains the recommended 2.x backend configuration path
+
+### Release Summary
+
+- result objects are now documented as first-class API integration surfaces
+- the repository now includes a copyable FastAPI reference-project layout
+- release smoke verification checks successful imports, failed imports, and
+  structured error payloads
+- codec fallback warnings are easier to read and more useful during debugging
+
 ## [2.2.5] - 2026-04-04
 
 This release continues the stable 2.x line with error UX polish, clearer
@@ -14,13 +59,18 @@ typing cleanup across the runtime path.
 
 - Added `CellErrorMap` and `RowIssueMap` as richer workbook-facing error access
   containers while preserving 2.x dict-like compatibility
+- Added structured error records and API-friendly payload helpers through
+  `records()` and `to_api_payload()` on both `CellErrorMap` and `RowIssueMap`
 - Added `docs/getting-started.md` to give new users one clear entry point for
   installation, schema declaration, workflow setup, and backend configuration
 - Added `docs/examples-showcase.md` and example-output assets so examples can
   be browsed as a lightweight showcase instead of only as source code
 - Added more business-oriented examples, including employee import,
   create-or-update import, export workflow, selection-heavy forms, and
   date/range field workflows
+- Added a minimal FastAPI reference project with separate route, service,
+  storage, and schema modules so teams can start from a copyable backend
+  layout instead of only single-file examples
 - Added stronger smoke scripts and release checks for installed packages,
   repository examples, and generated example-output assets
 
@@ -34,6 +84,9 @@ typing cleanup across the runtime path.
   output and clearer equality semantics
 - Normalized common validation messages into more natural, workbook-facing
   English such as `This field is required`
+- Made common field-type validation messages more business-oriented by adding
+  expected-format hints for date, date-range, number-range, email, phone,
+  URL, and configured-selection fields
 - Clarified `FieldMetaInfo` as a compatibility facade over layered metadata
   objects and moved more internal consumers and codecs onto `declared`,
   `runtime`, `presentation`, and `constraints`
@@ -44,6 +97,8 @@ typing cleanup across the runtime path.
   public API, migrations, examples, showcase, and PyPI-facing README content
 - Expanded `examples/README.md` into a recommended reading order with expected
   outputs and captured example artifacts
+- Expanded the examples docs and showcase so the new FastAPI reference project
+  is linked from GitHub README, PyPI README, and the examples showcase page
 
 ### Fixed
 

README-pypi.md

@@ -10,9 +10,9 @@ ExcelAlchemy turns Pydantic models into typed workbook contracts:
 - render workbook-facing output in `zh-CN` or `en`
 - keep storage pluggable through `ExcelStorage`
 
-The current stable release is `2.2.5`, which continues the 2.x line with richer import-failure feedback, clearer documentation entry points, stronger examples, and stronger smoke coverage.
+The current stable release is `2.2.6`, which continues the 2.x line with stronger result-object guidance, a copyable FastAPI reference project, more robust smoke verification, and clearer codec fallback diagnostics.
 
-[GitHub Repository](https://github.com/RayCarterLab/ExcelAlchemy) · [Full README](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README.md) · [Getting Started](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/getting-started.md) · [Examples Showcase](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/examples-showcase.md) · [Architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md) · [Migration Notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md)
+[GitHub Repository](https://github.com/RayCarterLab/ExcelAlchemy) · [Full README](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README.md) · [Getting Started](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/getting-started.md) · [Result Objects](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/result-objects.md) · [Examples Showcase](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/examples-showcase.md) · [Architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md) · [Migration Notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md)
 
 ## Screenshots
 
@@ -111,11 +111,38 @@ Full captured outputs:
 - [export-workflow.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/export-workflow.txt)
 - [date-and-range-fields.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/date-and-range-fields.txt)
 - [selection-fields.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/selection-fields.txt)
+- [fastapi-reference.txt](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/fastapi-reference.txt)
 
 For a single GitHub page that combines screenshots, representative workflows,
 and captured outputs, see the
 [Examples Showcase](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/examples-showcase.md).
 
+If you want a copyable FastAPI-oriented reference layout rather than a single
+example script, see the
+[FastAPI reference project](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/fastapi_reference/README.md).
+
+## Error Feedback
+
+ExcelAlchemy keeps workbook-facing validation feedback readable while also
+supporting API-friendly inspection in application code.
+
+The stable 2.x result surface includes:
+
+- `alchemy.cell_error_map`
+- `alchemy.row_error_map`
+
+These objects remain dict-like for compatibility, but also expose helpers such
+as:
+
+- `messages_at(...)`
+- `messages_for_row(...)`
+- `flatten()`
+- `to_api_payload()`
+
+Common field types now also produce more business-oriented error wording, such
+as expected date formats, sample email/phone/URL formats, and clearer messages
+for configured selection fields.
+
 ## Why ExcelAlchemy
 
 - Pydantic v2-based schema extraction and validation

README.md

@@ -6,7 +6,7 @@
 ![Lint](https://img.shields.io/badge/lint-ruff-D7FF64)
 ![Typing](https://img.shields.io/badge/typing-pyright-2C6BED)
 
-[中文 README](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README_cn.md) · [About](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/ABOUT.md) · [Getting Started](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/getting-started.md) · [Architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md) · [Examples Showcase](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/examples-showcase.md) · [Public API](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/public-api.md) · [Locale Policy](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/locale.md) · [Changelog](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/CHANGELOG.md) · [Migration Notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md)
+[中文 README](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README_cn.md) · [About](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/ABOUT.md) · [Getting Started](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/getting-started.md) · [Result Objects](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/result-objects.md) · [Architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md) · [Examples Showcase](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/examples-showcase.md) · [Public API](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/public-api.md) · [Locale Policy](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/locale.md) · [Changelog](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/CHANGELOG.md) · [Migration Notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md)
 
 ExcelAlchemy is a schema-driven Python library for Excel import and export workflows.
 It turns Pydantic models into typed workbook contracts: generate templates, validate uploads, map failures back to rows
@@ -16,7 +16,7 @@ This repository is also a design artifact.
 It documents a series of deliberate engineering choices: `src/` layout, Pydantic v2 migration, pandas removal,
 pluggable storage, `uv`-based workflows, and locale-aware workbook output.
 
-The current stable release is `2.2.5`, which continues the ExcelAlchemy 2.x line with richer import-failure feedback, clearer getting-started and public-API guidance, stronger real-world examples, and stronger release smoke coverage.
+The current stable release is `2.2.6`, which continues the ExcelAlchemy 2.x line with stronger result-object guidance, a copyable FastAPI reference project, more robust release smoke verification, and clearer codec fallback diagnostics.
 
 ## At a Glance
 
@@ -186,6 +186,7 @@ Practical examples live in the repository:
 - [`examples/export_workflow.py`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/export_workflow.py)
 - [`examples/minio_storage.py`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/minio_storage.py)
 - [`examples/fastapi_upload.py`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/fastapi_upload.py)
+- [`examples/fastapi_reference/README.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/fastapi_reference/README.md)
 - [`examples/README.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/README.md)
 
 If you want the recommended reading order, start with
@@ -231,6 +232,7 @@ Full captured outputs:
 - [`files/example-outputs/selection-fields.txt`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/selection-fields.txt)
 - [`files/example-outputs/custom-storage.txt`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/custom-storage.txt)
 - [`files/example-outputs/annotated-schema.txt`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/annotated-schema.txt)
+- [`files/example-outputs/fastapi-reference.txt`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/fastapi-reference.txt)
 
 ## Public API Boundaries
 
@@ -257,6 +259,39 @@ The older aliases:
 still work in the 2.x line as compatibility paths, but new application code
 should use the clearer names above.
 
+## Structured Error Access
+
+Import failures are now easier to inspect programmatically.
+
+- `alchemy.cell_error_map`
+- `alchemy.row_error_map`
+
+Both containers remain dict-like for 2.x compatibility, but they also expose
+clearer helper methods for application code and API handlers:
+
+- `at(...)`
+- `messages_at(...)`
+- `messages_for_row(...)`
+- `numbered_messages_for_row(...)`
+- `flatten()`
+- `to_dict()`
+- `to_api_payload()`
+
+This makes it easier to:
+
+- build frontend-friendly validation responses
+- render row-level and cell-level failure summaries
+- keep workbook feedback and API feedback aligned
+
+Common field types also provide more business-oriented validation wording. For
+example:
+
+- date fields now mention the expected date format
+- date range and number range fields now mention the expected combined input
+- email, phone number, and URL fields now include example formats
+- selection, organization, and staff fields now mention that values must come
+  from the configured options
+
 ## Locale-Aware Workbook Output
 
 `locale` affects workbook-facing display text such as:

README_cn.md

@@ -1,11 +1,11 @@
 # ExcelAlchemy
 
-[English README](./README.md) · [项目说明](./ABOUT.md) · [架构文档](./docs/architecture.md) · [Locale Policy](./docs/locale.md) · [Changelog](./CHANGELOG.md) · [迁移说明](./MIGRATIONS.md)
+[English README](./README.md) · [项目说明](./ABOUT.md) · [快速开始](./docs/getting-started.md) · [结果对象](./docs/result-objects.md) · [架构文档](./docs/architecture.md) · [Locale Policy](./docs/locale.md) · [Changelog](./CHANGELOG.md) · [迁移说明](./MIGRATIONS.md)
 
 ExcelAlchemy 是一个面向 Excel 导入导出的 schema-first Python 库。
 它的核心思路不是“读写表格文件”，而是“把 Excel 当成一种带约束的业务契约”。
 
-当前稳定发布版本是 `2.2.5`，它在稳定的 ExcelAlchemy 2.x 线上继续加强了导入失败反馈、更清晰的入门与 public API 文档、更贴近真实业务的示例，以及更强的 release smoke 验证。
+当前稳定发布版本是 `2.2.6`，它在稳定的 ExcelAlchemy 2.x 线上继续加强了结果对象与接入说明、可复制的 FastAPI 参考项目、更稳的 release smoke 验证，以及更清晰的 codec fallback 诊断信息。
 
 你用 Pydantic 模型定义结构，用 `FieldMeta` 定义 Excel 元数据，用显式的导入/导出流程去完成模板生成、数据校验、错误回写和后端集成。
 
@@ -115,6 +115,7 @@ pip install "ExcelAlchemy[minio]"
 - [`examples/export_workflow.py`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/export_workflow.py)
 - [`examples/minio_storage.py`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/minio_storage.py)
 - [`examples/fastapi_upload.py`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/fastapi_upload.py)
+- [`examples/fastapi_reference/README.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/fastapi_reference/README.md)
 - [`examples/README.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/README.md)
 
 如果你想按推荐顺序来阅读，建议先看
@@ -161,6 +162,7 @@ Uploaded objects: ['employees-export-upload.xlsx']
 - [`files/example-outputs/selection-fields.txt`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/selection-fields.txt)
 - [`files/example-outputs/custom-storage.txt`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/custom-storage.txt)
 - [`files/example-outputs/annotated-schema.txt`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/annotated-schema.txt)
+- [`files/example-outputs/fastapi-reference.txt`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/fastapi-reference.txt)
 
 ## 快速开始
 
@@ -270,6 +272,36 @@ alchemy = ExcelAlchemy(ExporterConfig(Importer, storage=InMemoryExcelStorage()))
 
 在 2.x 里仍然可用，用于兼容旧代码；但新代码建议统一使用前面这组更明确的名字。
 
+## 结构化错误读取
+
+现在导入失败不仅能回写到 workbook，也更适合被后端服务和前端界面读取。
+
+- `alchemy.cell_error_map`
+- `alchemy.row_error_map`
+
+这两个对象在 2.x 中仍然保持 dict 兼容，但同时提供了更适合业务代码使用的辅助方法：
+
+- `at(...)`
+- `messages_at(...)`
+- `messages_for_row(...)`
+- `numbered_messages_for_row(...)`
+- `flatten()`
+- `to_dict()`
+- `to_api_payload()`
+
+这意味着你可以更容易地：
+
+- 构造前端可直接消费的校验响应
+- 渲染按行和按单元格的失败摘要
+- 保持 workbook 提示和 API 提示的一致性
+
+常见字段类型的错误提示也更贴近业务语义了，例如：
+
+- 日期字段会直接提示期望的日期格式
+- 日期区间和数值区间字段会提示期望的组合输入格式
+- 邮箱、手机号、URL 会给出更自然的示例格式
+- 选项、组织、人员类字段会明确提示“必须来自配置项”
+
 ## 为什么这样设计
 
 ### 为什么去掉 pandas

docs/examples-showcase.md

@@ -6,6 +6,9 @@ It complements the repository examples by surfacing the most representative
 workflows, screenshots, and fixed outputs in one place. If you want the full
 guided path through the examples directory, start with
 [`examples/README.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/README.md).
+If you want to see how import results and error maps are meant to be surfaced
+through backend APIs, see
+[`docs/result-objects.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/result-objects.md).
 
 ## What ExcelAlchemy Looks Like
 
@@ -119,6 +122,8 @@ If you want to see how ExcelAlchemy fits into backend systems:
   - [`examples/minio_storage.py`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/minio_storage.py)
 - FastAPI integration:
   - [`examples/fastapi_upload.py`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/fastapi_upload.py)
+  - [`examples/fastapi_reference/README.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/fastapi_reference/README.md)
+  - [`files/example-outputs/fastapi-reference.txt`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/files/example-outputs/fastapi-reference.txt)
 
 ## Recommended Reading Order
 
@@ -134,6 +139,7 @@ showcase:
 7. [`examples/selection_fields.py`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/selection_fields.py)
 8. [`examples/minio_storage.py`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/minio_storage.py)
 9. [`examples/fastapi_upload.py`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/fastapi_upload.py)
+10. [`examples/fastapi_reference/README.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/fastapi_reference/README.md)
 
 Or start with the dedicated guide: