Merge pull request #67 from RayCarterLab/v2.2

release: prepare ExcelAlchemy 2.2.7

Author: ruicore

.github/workflows/ci.yml

@@ -110,9 +110,11 @@ jobs:
       - name: Run smoke scripts
         if: matrix.python-version == '3.14'
         run: |
+          uv pip install fastapi httpx python-multipart
           uv run python scripts/smoke_package.py
           uv run python scripts/smoke_examples.py
           uv run python scripts/generate_example_output_assets.py
+          uv run python scripts/smoke_docs_assets.py
 
       - name: Upload coverage artifact
         if: always() && matrix.python-version == '3.14'

.github/workflows/python-publish.yml

@@ -56,19 +56,23 @@ jobs:
         run: |
           uv venv .pkg-smoke-wheel --python 3.14
           uv pip install --python .pkg-smoke-wheel/bin/python dist/*.whl
+          uv pip install --python .pkg-smoke-wheel/bin/python fastapi httpx python-multipart
           .pkg-smoke-wheel/bin/python -c "import excelalchemy; print(excelalchemy.__version__)"
           .pkg-smoke-wheel/bin/python scripts/smoke_package.py
           .pkg-smoke-wheel/bin/python scripts/smoke_examples.py
           .pkg-smoke-wheel/bin/python scripts/generate_example_output_assets.py
+          .pkg-smoke-wheel/bin/python scripts/smoke_docs_assets.py
 
       - name: Smoke test source distribution installation
         run: |
           uv venv .pkg-smoke-sdist --python 3.14
           uv pip install --python .pkg-smoke-sdist/bin/python dist/*.tar.gz
+          uv pip install --python .pkg-smoke-sdist/bin/python fastapi httpx python-multipart
           .pkg-smoke-sdist/bin/python -c "import excelalchemy; print(excelalchemy.__version__)"
           .pkg-smoke-sdist/bin/python scripts/smoke_package.py
           .pkg-smoke-sdist/bin/python scripts/smoke_examples.py
           .pkg-smoke-sdist/bin/python scripts/generate_example_output_assets.py
+          .pkg-smoke-sdist/bin/python scripts/smoke_docs_assets.py
 
       - name: Set artifact metadata
         id: artifact-meta

CHANGELOG.md

@@ -4,6 +4,70 @@ 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.7] - 2026-04-04
+
+This release continues the stable 2.x line with stronger API-facing result
+payloads, a more complete FastAPI reference application, harder install-time
+smoke verification, and more consistent codec diagnostics.
+
+### Added
+
+- Added `docs/api-response-cookbook.md` with copyable success, data-invalid,
+  and header-invalid response shapes for backend integrations
+- Added request and response contract modules for the FastAPI reference app
+  under `examples/fastapi_reference/schemas.py` and
+  `examples/fastapi_reference/responses.py`
+- Added `scripts/smoke_docs_assets.py` to verify showcase assets and critical
+  result-object/showcase documentation entry points
+- Added logger consistency tests for codec fallback diagnostics
+
+### Changed
+
+- Extended `ImportResult`, `CellErrorMap`, and `RowIssueMap` payload guidance
+  so `code`, `message_key`, `message`, and `display_message` have clearer and
+  more stable frontend-facing roles
+- Strengthened `CellErrorMap` and `RowIssueMap` with summary helpers for
+  aggregation by field, row, and machine-readable code
+- Made `ImportResult.to_api_payload()` a stable top-level integration surface
+  for success, data-invalid, and header-invalid responses
+- Expanded the FastAPI reference app into a more copyable minimal application
+  with request schema, response schema, structured response builder, and
+  cookbook-aligned payloads
+- Hardened release smoke verification so installed-package checks now cover:
+  - successful imports
+  - failed imports
+  - structured error payloads
+  - example asset generation
+  - result-object and showcase docs
+  - FastAPI reference HTTP behavior after dependency installation
+- Unified codec fallback logging under the `excelalchemy.codecs` logger and
+  aligned warning wording across option, parse, and render fallbacks
+
+### Fixed
+
+- Fixed the runnable FastAPI example and the FastAPI reference app so their
+  runtime type annotations work correctly when optional web dependencies are
+  actually installed
+- Fixed stale integration-test expectations after the improved business-facing
+  validation messages landed
+
+### 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
+- `storage=...` remains the recommended 2.x backend configuration path
+- Legacy built-in Minio fields remain part of the 2.x compatibility surface
+
+### Release Summary
+
+- API response payloads are easier to consume from frontends and backend
+  clients
+- the FastAPI reference project now looks more like a copyable minimal app
+- release smoke checks now verify docs, assets, failed-import payloads, and
+  installed FastAPI integrations
+- codec diagnostics are more consistent and easier to filter by logger
+
 ## [2.2.6] - 2026-04-04
 
 This release continues the stable 2.x line with stronger consumer-facing

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.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.
+The current stable release is `2.2.7`, which continues the 2.x line with stronger API-facing result payloads, a more complete FastAPI reference app, harder install-time smoke verification, and more consistent codec 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) · [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)
+[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) · [API Response Cookbook](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/api-response-cookbook.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
 

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) · [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)
+[中文 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) · [API Response Cookbook](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/api-response-cookbook.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.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.
+The current stable release is `2.2.7`, which continues the ExcelAlchemy 2.x line with stronger API-facing result payloads, a more complete FastAPI reference app, harder install-time smoke verification, and more consistent codec diagnostics.
 
 ## At a Glance
 

README_cn.md

@@ -5,7 +5,7 @@
 ExcelAlchemy 是一个面向 Excel 导入导出的 schema-first Python 库。
 它的核心思路不是“读写表格文件”，而是“把 Excel 当成一种带约束的业务契约”。
 
-当前稳定发布版本是 `2.2.6`，它在稳定的 ExcelAlchemy 2.x 线上继续加强了结果对象与接入说明、可复制的 FastAPI 参考项目、更稳的 release smoke 验证，以及更清晰的 codec fallback 诊断信息。
+当前稳定发布版本是 `2.2.7`，它在稳定的 ExcelAlchemy 2.x 线上继续加强了 API 结果载荷、FastAPI 参考应用、安装后真实可用的 release smoke 验证，以及更一致的 codec 诊断信息。
 
 你用 Pydantic 模型定义结构，用 `FieldMeta` 定义 Excel 元数据，用显式的导入/导出流程去完成模板生成、数据校验、错误回写和后端集成。