feat(v2.4): add import platform architecture docs

Author: ruicore

README-pypi.md

@@ -15,7 +15,15 @@ more complete import workflow: clearer template guidance before upload,
 lightweight structural preflight before execution, synchronous lifecycle
 visibility during import, and remediation-oriented payloads after failures.
 
-[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)
+At the top level, that import workflow is:
+
+- template authoring
+- preflight gate
+- import runtime
+- result intelligence
+- artifact and delivery
+
+[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) · [Platform Architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/platform-architecture.md) · [Runtime Model](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/runtime-model.md) · [Integration Blueprints](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/integration-blueprints.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
 
@@ -166,6 +174,9 @@ for configured selection fields.
 ## Learn More
 
 - [Full project README](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README.md)
+- [Platform architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/platform-architecture.md)
+- [Runtime model](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/runtime-model.md)
+- [Integration blueprints](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/integration-blueprints.md)
 - [Architecture notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md)
 - [Locale policy](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/locale.md)
 - [Migration notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md)

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](README_cn.md) · [About](ABOUT.md) · [Getting Started](docs/getting-started.md) · [Integration Roadmap](docs/integration-roadmap.md) · [Result Objects](docs/result-objects.md) · [API Response Cookbook](docs/api-response-cookbook.md) · [Architecture](docs/architecture.md) · [Examples Showcase](docs/examples-showcase.md) · [Public API](docs/public-api.md) · [Locale Policy](docs/locale.md) · [Limitations](docs/limitations.md) · [Performance](docs/performance.md) · [Changelog](CHANGELOG.md) · [Migration Notes](MIGRATIONS.md)
+[中文 README](README_cn.md) · [About](ABOUT.md) · [Getting Started](docs/getting-started.md) · [Integration Roadmap](docs/integration-roadmap.md) · [Platform Architecture](docs/platform-architecture.md) · [Runtime Model](docs/runtime-model.md) · [Integration Blueprints](docs/integration-blueprints.md) · [Result Objects](docs/result-objects.md) · [API Response Cookbook](docs/api-response-cookbook.md) · [Architecture](docs/architecture.md) · [Examples Showcase](docs/examples-showcase.md) · [Public API](docs/public-api.md) · [Locale Policy](docs/locale.md) · [Limitations](docs/limitations.md) · [Performance](docs/performance.md) · [Changelog](CHANGELOG.md) · [Migration Notes](MIGRATIONS.md)
 
 Repository guides: [AGENTS.md](AGENTS.md) · [Repository Map](docs/repo-map.md) · [Domain Model](docs/domain-model.md) · [Invariants](docs/invariants.md) · [Package Guide](src/excelalchemy/README.md) · [Test Guide](tests/README.md) · [Examples Guide](examples/README.md)
 
@@ -26,6 +26,12 @@ upload, lightweight structural preflight before execution, synchronous
 lifecycle visibility during import, and remediation-oriented payloads after
 failures.
 
+For the platform-layer architecture of that workflow, see:
+
+- [`docs/platform-architecture.md`](docs/platform-architecture.md)
+- [`docs/runtime-model.md`](docs/runtime-model.md)
+- [`docs/integration-blueprints.md`](docs/integration-blueprints.md)
+
 ## At a Glance
 
 - Build Excel templates directly from typed Pydantic schemas
@@ -104,12 +110,28 @@ For browser downloads, prefer `template.as_bytes()` with a `Blob`, or return the
 ExcelAlchemy is designed to work as a product-ready import layer rather than
 only a row-validation helper.
 
-The practical workflow in the 2.x line is:
+The top-level import workflow in the 2.x line is:
+
+- template authoring
+- preflight gate
+- import runtime
+- result intelligence
+- artifact and delivery
+
+In practical terms, that usually means:
 
 - generate a template with workbook-facing guidance
 - run `preflight_import(...)` as a lightweight structural gate
 - run `import_data(..., on_event=...)` for full validation and execution
+- inspect `ImportResult`, `CellErrorMap`, and `RowIssueMap`
 - build remediation-oriented payloads if the import fails
+- deliver template or result workbook artifacts through the configured storage seam
+
+For the platform view and runtime sequence behind this workflow, see:
+
+- [`docs/platform-architecture.md`](docs/platform-architecture.md)
+- [`docs/runtime-model.md`](docs/runtime-model.md)
+- [`docs/integration-blueprints.md`](docs/integration-blueprints.md)
 
 Use `preflight_import(...)` when you want a fast answer to:
 
@@ -178,9 +200,10 @@ else:
 
 This keeps one clear separation:
 
-- template and preflight help before execution
-- import handles real validation and persistence
-- remediation helps API and frontend retry flows after failure
+- template authoring and preflight help before execution
+- import runtime handles real validation and persistence
+- result intelligence helps API and frontend retry flows after failure
+- artifact and delivery expose files and URLs after the run
 
 ## When To Use / When Not To Use / Limitations & Gotchas
 
@@ -284,6 +307,10 @@ flowchart TD
 ```
 
 See the full breakdown in [docs/architecture.md](docs/architecture.md).
+For the integration-oriented platform view layered above those components, see
+[docs/platform-architecture.md](docs/platform-architecture.md),
+[docs/runtime-model.md](docs/runtime-model.md), and
+[docs/integration-blueprints.md](docs/integration-blueprints.md).
 
 ## Workflow
 
@@ -590,6 +617,9 @@ More detail is documented in [ABOUT.md](ABOUT.md).
 - [README.md](README.md): product + design overview
 - [README_cn.md](README_cn.md): Chinese usage-oriented guide
 - [ABOUT.md](ABOUT.md): engineering rationale and evolution notes
+- [docs/platform-architecture.md](docs/platform-architecture.md): import platform capability model
+- [docs/runtime-model.md](docs/runtime-model.md): runtime sequence across the import workflow
+- [docs/integration-blueprints.md](docs/integration-blueprints.md): backend/frontend integration patterns
 - [docs/architecture.md](docs/architecture.md): component map and boundaries
 - [docs/limitations.md](docs/limitations.md): practical fit, limitations, and gotchas
 - [docs/performance.md](docs/performance.md): operational guidance for large files, memory, and backend guardrails

README_cn.md

@@ -1,11 +1,24 @@
 # ExcelAlchemy
 
-[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)
+[English README](./README.md) · [项目说明](./ABOUT.md) · [快速开始](./docs/getting-started.md) · [接入路线图](./docs/integration-roadmap.md) · [平台架构](./docs/platform-architecture.md) · [运行时模型](./docs/runtime-model.md) · [集成蓝图](./docs/integration-blueprints.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.8`，它在稳定的 ExcelAlchemy 2.x 线上继续加强了接入路线图、失败导入 API 载荷的 smoke 校验，以及对 FastAPI 参考应用的安装后真实可用验证。
+当前稳定发布版本是 `2.3.0`。在稳定的 ExcelAlchemy 2.x 线上，它进一步补齐了更完整的导入工作流：
+
+- 上传前更清晰的模板引导
+- 执行前更轻量的结构化 preflight gate
+- 导入过程中的同步 lifecycle visibility
+- 导入失败后的 remediation-oriented payload
+
+从平台层视角看，这条导入链路可以概括为：
+
+- 模板编排
+- preflight gate
+- 导入运行时
+- 结果智能
+- 制品与交付
 
 你用 Pydantic 模型定义结构，用 `FieldMeta` 定义 Excel 元数据，用显式的导入/导出流程去完成模板生成、数据校验、错误回写和后端集成。
 
@@ -90,6 +103,12 @@ flowchart LR
     H --> I
 ```
 
+如果你想先看平台层文档，而不是内部组件图，可以继续看：
+
+- [`docs/platform-architecture.md`](./docs/platform-architecture.md)
+- [`docs/runtime-model.md`](./docs/runtime-model.md)
+- [`docs/integration-blueprints.md`](./docs/integration-blueprints.md)
+
 ## 安装
 
 ```bash
@@ -359,6 +378,9 @@ Minio 只是一个默认实现，真正稳定的接口应该是 `ExcelStorage`
 - [README.md](./README.md): 英文首页，偏作品集表达
 - [README_cn.md](./README_cn.md): 中文说明页，偏使用和理解
 - [ABOUT.md](./ABOUT.md): 设计原则、迁移记录、架构取舍
+- [docs/platform-architecture.md](./docs/platform-architecture.md): 导入平台层能力模型
+- [docs/runtime-model.md](./docs/runtime-model.md): 导入工作流的运行时顺序
+- [docs/integration-blueprints.md](./docs/integration-blueprints.md): 后端 / 前端接入蓝图
 - [docs/architecture.md](./docs/architecture.md): 组件边界与扩展点
 
 ## 开发

docs/architecture.md

@@ -1,5 +1,11 @@
 # Architecture
 
+This page is the internal component view of the repository.
+If you want the integration-oriented platform view introduced for the v2.4
+documentation slice, see [`docs/platform-architecture.md`](platform-architecture.md).
+If you want the runtime sequence on top of that platform view, see
+[`docs/runtime-model.md`](runtime-model.md).
+
 ## Component Map
 
 ```mermaid

docs/getting-started.md

@@ -4,6 +4,11 @@ This page is the fastest way to get productive with ExcelAlchemy.
 
 If you want screenshots and fixed workflow outputs first, see
 [`docs/examples-showcase.md`](examples-showcase.md).
+If you want the platform-layer architecture of the import workflow, see
+[`docs/platform-architecture.md`](platform-architecture.md),
+[`docs/runtime-model.md`](runtime-model.md),
+and
+[`docs/integration-blueprints.md`](integration-blueprints.md).
 If you want the full public surface and compatibility boundaries, see
 [`docs/public-api.md`](public-api.md).
 If you want to understand the result objects and how to surface them through an
@@ -100,6 +105,14 @@ only adds a more helpful header comment in the generated template, for example:
 
 ## 4. Pick The Workflow You Need
 
+Top-level import workflow:
+
+1. template authoring
+2. preflight gate
+3. import runtime
+4. result intelligence
+5. artifact and delivery
+
 Import-only create flow:
 
 ```python

docs/integration-blueprints.md

@@ -0,0 +1,189 @@
+# Integration Blueprints
+
+This page shows practical integration blueprints for the v2.4 import platform
+layer.
+These are not new product surfaces.
+They are recommended ways to compose the current 2.x capabilities.
+
+If you want the platform capability map, see
+[`docs/platform-architecture.md`](platform-architecture.md).
+If you want the runtime sequence view, see
+[`docs/runtime-model.md`](runtime-model.md).
+If you want detailed result payload shapes, see
+[`docs/result-objects.md`](result-objects.md) and
+[`docs/api-response-cookbook.md`](api-response-cookbook.md).
+
+## Blueprint 1: Backend Worker Import Flow
+
+Use this blueprint when your application already has a worker, queue, or job
+runner and you want ExcelAlchemy to remain the import engine inside that worker.
+
+This is an application-level worker blueprint.
+It is not a claim that ExcelAlchemy ships a worker framework.
+
+### Recommended shape
+
+```mermaid
+flowchart LR
+    U[Spreadsheet User] --> API[Upload API]
+    API --> PF[Preflight Gate]
+    PF -->|valid| Q[App Queue / Worker Trigger]
+    PF -->|invalid| PFR[Preflight Response]
+
+    Q --> W[Backend Worker]
+    W --> EA[ExcelAlchemy import_data(..., on_event=...)]
+    EA --> RES[ImportResult + Issue Maps]
+    EA --> OUT[Result Workbook Upload]
+    RES --> APIRES[API Status Store / Polling Endpoint]
+    OUT --> APIRES
+```
+
+### Why this fits the current platform
+
+- preflight stays a lightweight synchronous gate
+- the worker owns application scheduling and retries
+- `import_data(..., on_event=...)` remains the real runtime entry point
+- lifecycle events can update application job status inline
+- result intelligence remains post-import and machine-readable
+
+### Recommended responsibilities
+
+Upload API:
+
+- accept the workbook reference
+- run `preflight_import(...)`
+- reject obvious structural failures early
+- enqueue only structurally importable workbooks
+
+Backend worker:
+
+- call `import_data(..., on_event=...)`
+- update job status using lifecycle events
+- persist `ImportResult`
+- persist row/cell issue payloads when needed
+- expose result workbook URL when one is produced
+
+Application status endpoint:
+
+- return job state
+- return final result payloads
+- optionally expose remediation payloads for UI consumers
+
+### Important boundaries
+
+- the queue, worker, retry policy, and job persistence belong to the
+  application
+- ExcelAlchemy remains synchronous inside the worker execution
+- do not describe this as an ExcelAlchemy job subsystem
+
+## Blueprint 2: Frontend Remediation Flow
+
+Use this blueprint when a frontend needs both high-level outcome information and
+compact retry guidance after a failed import.
+
+```mermaid
+flowchart TD
+    U[Spreadsheet User] --> FE[Frontend]
+    FE --> API[Backend API]
+    API --> PF[preflight_import(...)]
+
+    PF -->|invalid| PRE[ImportPreflightResult payload]
+    PF -->|valid| RUN[import_data(...)]
+
+    RUN --> R[ImportResult]
+    RUN --> C[CellErrorMap]
+    RUN --> RI[RowIssueMap]
+    RUN --> RP[build_frontend_remediation_payload(...)]
+    RUN --> URL[result workbook URL]
+
+    PRE --> FE
+    R --> FE
+    C --> FE
+    RI --> FE
+    RP --> FE
+    URL --> FE
+```
+
+### Recommended frontend use
+
+Preflight response:
+
+- decide whether the workbook is structurally importable
+- show blocking sheet/header problems before full execution
+
+Result response:
+
+- use `ImportResult` for high-level outcome and counts
+- use `CellErrorMap` for precise field/cell UI highlighting
+- use `RowIssueMap` for list/table summaries
+- use the remediation payload for concise retry guidance
+- use the result workbook URL when the user should download the annotated file
+
+### Recommended response layering
+
+- `preflight`
+  - structural gate result only
+- `result`
+  - overall import outcome
+- `cell_errors`
+  - precise workbook-coordinate issues
+- `row_errors`
+  - grouped row summaries
+- `remediation`
+  - optional condensed retry guidance
+
+### Important boundaries
+
+- remediation payloads are additive and opt-in
+- they do not replace the stable result payloads
+- they should stay conservative and avoid overstating automatic fix guidance
+
+## Blueprint 3: Artifact Delivery Flow
+
+Use this blueprint when delivery of the template artifact and result workbook is
+part of the integration design.
+
+```mermaid
+flowchart LR
+    A[Application] --> T[Template Artifact Request]
+    T --> EA[ExcelAlchemy]
+    EA --> TA[ExcelArtifact]
+    TA --> DL[Browser Download or API Response]
+
+    A --> I[Import Runtime]
+    I --> RW[Rendered Result Workbook]
+    RW --> ST[ExcelStorage Upload]
+    ST --> URL[Result Workbook URL]
+    URL --> API[API Response or Worker Status]
+```
+
+### What this highlights
+
+- template authoring and result delivery share rendering primitives
+- artifact delivery is a platform stage even though it depends on earlier
+  stages
+- storage remains a seam rather than a mandated backend
+
+## Choosing The Right Blueprint
+
+- use the backend worker blueprint when your application already has queued or
+  long-running import orchestration
+- use the frontend remediation blueprint when the UI needs compact retry
+  guidance after validation failures
+- use the artifact delivery blueprint when file delivery semantics are a first
+  class part of the integration
+
+In all three cases, keep the same platform order:
+
+1. template authoring
+2. preflight gate
+3. import runtime
+4. result intelligence
+5. artifact and delivery
+
+## Recommended Reading
+
+- [`docs/platform-architecture.md`](platform-architecture.md)
+- [`docs/runtime-model.md`](runtime-model.md)
+- [`docs/result-objects.md`](result-objects.md)
+- [`docs/api-response-cookbook.md`](api-response-cookbook.md)