Merge pull request #68 from RayCarterLab/v2.2

release: prepare ExcelAlchemy 2.2.8

Author: ruicore

.github/workflows/ci.yml

@@ -115,6 +115,7 @@ jobs:
           uv run python scripts/smoke_examples.py
           uv run python scripts/generate_example_output_assets.py
           uv run python scripts/smoke_docs_assets.py
+          uv run python scripts/smoke_api_payload_snapshot.py
 
       - name: Upload coverage artifact
         if: always() && matrix.python-version == '3.14'

.github/workflows/python-publish.yml

@@ -62,6 +62,8 @@ jobs:
           .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
+          .pkg-smoke-wheel/bin/python scripts/smoke_api_payload_snapshot.py
+          .pkg-smoke-wheel/bin/python -m examples.fastapi_reference.app
 
       - name: Smoke test source distribution installation
         run: |
@@ -73,6 +75,8 @@ jobs:
           .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
+          .pkg-smoke-sdist/bin/python scripts/smoke_api_payload_snapshot.py
+          .pkg-smoke-sdist/bin/python -m examples.fastapi_reference.app
 
       - name: Set artifact metadata
         id: artifact-meta

CHANGELOG.md

@@ -4,6 +4,44 @@ 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.8] - 2026-04-05
+
+This release continues the stable 2.x line with a clearer integration reading
+path, stronger API payload smoke verification, and a more production-shaped
+reference-app release flow.
+
+### Added
+
+- Added `docs/integration-roadmap.md` to give new adopters a role-based reading
+  path for first-time integration, backend APIs, frontend error rendering, and
+  migration work
+- Added `scripts/smoke_api_payload_snapshot.py` and a generated
+  `import-failure-api-payload.json` snapshot under `files/example-outputs/`
+
+### Changed
+
+- Expanded release smoke so wheel and source-distribution verification now
+  compare a stable import-failure API payload snapshot instead of only checking
+  ad hoc fields
+- Extended release verification so installed-package smoke runs the
+  `examples.fastapi_reference.app` demo directly after dependency installation
+- Cross-linked the new integration roadmap from onboarding, API-facing, and
+  PyPI-facing docs
+
+### 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
+
+### Release Summary
+
+- new users now have a clearer “what to read first” path
+- release smoke now checks a stable import-failure payload shape
+- installed-package verification exercises the FastAPI reference app more
+  directly
+
 ## [2.2.7] - 2026-04-04
 
 This release continues the stable 2.x line with stronger API-facing result

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.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.
+The current stable release is `2.2.8`, which continues the 2.x line with a clearer integration roadmap, stronger import-failure payload smoke verification, and more direct install-time validation of the FastAPI reference app.
 
-[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)
+[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) · [Integration Roadmap](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/integration-roadmap.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) · [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)
+[中文 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) · [Integration Roadmap](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/integration-roadmap.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.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.
+The current stable release is `2.2.8`, which continues the ExcelAlchemy 2.x line with a clearer integration roadmap, stronger import-failure payload smoke verification, and more direct install-time validation of the FastAPI reference app.
 
 ## At a Glance
 

README_cn.md

@@ -1,11 +1,11 @@
 # ExcelAlchemy
 
-[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)
+[English README](./README.md) · [项目说明](./ABOUT.md) · [快速开始](./docs/getting-started.md) · [接入路线图](./docs/integration-roadmap.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.7`，它在稳定的 ExcelAlchemy 2.x 线上继续加强了 API 结果载荷、FastAPI 参考应用、安装后真实可用的 release smoke 验证，以及更一致的 codec 诊断信息。
+当前稳定发布版本是 `2.2.8`，它在稳定的 ExcelAlchemy 2.x 线上继续加强了接入路线图、失败导入 API 载荷的 smoke 校验，以及对 FastAPI 参考应用的安装后真实可用验证。
 
 你用 Pydantic 模型定义结构，用 `FieldMeta` 定义 Excel 元数据，用显式的导入/导出流程去完成模板生成、数据校验、错误回写和后端集成。
 

docs/api-response-cookbook.md

@@ -37,6 +37,12 @@ Within each error item:
 - use `message` for logs or plain-text APIs
 - use `display_message` when you want ready-to-render UI text
 
+Developer diagnostics are intentionally separate from these payload fields.
+Application logs use named loggers such as `excelalchemy.codecs`,
+`excelalchemy.runtime`, and `excelalchemy.metadata`; API responses should rely
+on `code`, `message_key`, `message`, and `display_message` instead of raw log
+output.
+
 ## 1. Success Response
 
 Use this when the import completed without header or data failures.

docs/getting-started.md

@@ -9,6 +9,8 @@ If you want the full public surface and compatibility boundaries, see
 If you want to understand the result objects and how to surface them through an
 API, see
 [`docs/result-objects.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/result-objects.md).
+If you want a role-based reading path, see
+[`docs/integration-roadmap.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/integration-roadmap.md).
 
 ## 1. Install
 

docs/integration-roadmap.md

@@ -0,0 +1,95 @@
+# Integration Roadmap
+
+This page helps you choose a reading path through the ExcelAlchemy docs based on
+what you are trying to build.
+
+If you want the fastest general entry point, start with
+[`docs/getting-started.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/getting-started.md).
+If you want screenshots and captured workflow output first, see
+[`docs/examples-showcase.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/examples-showcase.md).
+
+## 1. If You Are Integrating ExcelAlchemy For The First Time
+
+Recommended order:
+
+1. [`docs/getting-started.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/getting-started.md)
+2. [`docs/public-api.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/public-api.md)
+3. [`examples/README.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/README.md)
+4. [`docs/examples-showcase.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/examples-showcase.md)
+
+Focus on these concepts first:
+
+- stable import paths
+- schema declaration style
+- `storage=...` as the recommended backend integration path
+- the difference between import, create-or-update, and export workflows
+
+## 2. If You Are Building A Backend API
+
+Recommended order:
+
+1. [`docs/result-objects.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/result-objects.md)
+2. [`docs/api-response-cookbook.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/api-response-cookbook.md)
+3. [`examples/fastapi_reference/README.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/fastapi_reference/README.md)
+4. [`docs/public-api.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/public-api.md)
+
+Focus on these objects:
+
+- `ImportResult`
+- `CellErrorMap`
+- `RowIssueMap`
+
+Use these payload helpers directly in your API layer:
+
+- `ImportResult.to_api_payload()`
+- `CellErrorMap.to_api_payload()`
+- `RowIssueMap.to_api_payload()`
+
+## 3. If You Are Building Frontend Error Displays
+
+Recommended order:
+
+1. [`docs/result-objects.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/result-objects.md)
+2. [`docs/api-response-cookbook.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/api-response-cookbook.md)
+3. [`examples/fastapi_reference/README.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/fastapi_reference/README.md)
+
+Focus on these payload fields:
+
+- `code`
+- `message_key`
+- `message`
+- `display_message`
+
+And these grouped or summary helpers:
+
+- `summary.by_field`
+- `summary.by_row`
+- `summary.by_code`
+- `facets.field_labels`
+- `facets.codes`
+- `facets.row_numbers_for_humans`
+- `grouped.messages_by_field`
+- `grouped.messages_by_row`
+- `grouped.messages_by_code`
+
+## 4. If You Want Copyable Reference Code
+
+Start here:
+
+- [`examples/employee_import_workflow.py`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/employee_import_workflow.py)
+- [`examples/create_or_update_import.py`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/create_or_update_import.py)
+- [`examples/export_workflow.py`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/export_workflow.py)
+- [`examples/fastapi_reference/README.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/examples/fastapi_reference/README.md)
+
+## 5. If You Need Migration And Compatibility Context
+
+Read:
+
+1. [`MIGRATIONS.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md)
+2. [`docs/public-api.md`](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/public-api.md)
+
+This is the best route when you need to answer:
+
+- which imports are stable
+- which imports are compatibility-only
+- how the 2.x line treats legacy Minio configuration

docs/locale.md

@@ -2,12 +2,27 @@
 
 ## Scope
 
-ExcelAlchemy currently distinguishes between two kinds of language output:
+ExcelAlchemy currently distinguishes between three kinds of language output:
 
+- developer diagnostics, intended for logs and runtime troubleshooting
 - runtime messages, intended for Python developers and integrators
 - workbook display text, intended for spreadsheet users
 
-These two layers do not currently share the same locale policy.
+These layers do not currently share the same locale policy.
+
+## Developer Diagnostics Policy
+
+- Developer diagnostics are emitted through named loggers such as:
+  - `excelalchemy.codecs`
+  - `excelalchemy.runtime`
+  - `excelalchemy.metadata`
+- Stability policy: diagnostics are intentionally standardized in English for the
+  2.x line
+- Intended audience: backend developers, operators, and maintainers
+
+Developer diagnostics are not the same surface as API payloads or workbook-facing
+messages. They are designed for logs, traces, and troubleshooting rather than
+end-user rendering.
 
 ## Runtime Message Policy
 
@@ -35,6 +50,7 @@ Workbook display locale affects user-facing spreadsheet text such as:
 
 ## Fallback Rules
 
+- Developer diagnostics fall back to English
 - Runtime messages fall back to the runtime default locale: `en`
 - Workbook display messages fall back to the workbook display default locale: `zh-CN`
 
@@ -67,7 +83,8 @@ alchemy_en = ExcelAlchemy(ImporterConfig(ImporterModel, creator=create_func, loc
 
 The i18n roadmap remains intentionally incremental:
 
-1. keep runtime messages consistently English
-2. keep workbook display locale explicit and stable
-3. add new workbook locales additively
-4. only expand runtime locale support when there is a clear maintenance plan
+1. keep developer diagnostics consistently English
+2. keep runtime messages consistently English
+3. keep workbook display locale explicit and stable
+4. add new workbook locales additively
+5. only expand runtime locale support when there is a clear maintenance plan