@agile-team/mach-report 2.6.1 → 2.8.0

package/README.md

@@ -8,7 +8,7 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/source-2.6.1-2563eb" alt="Source version 2.6.1" />
+  <img src="https://img.shields.io/badge/source-2.8.0-2563eb" alt="Source version 2.8.0" />
   <a href="https://www.npmjs.com/package/@agile-team/mach-report"><img src="https://img.shields.io/npm/v/@agile-team/mach-report?label=npm&color=3178c6" alt="npm version" /></a>
   <a href="https://github.com/ChenyCHENYU/MachReport/actions/workflows/ci.yml"><img src="https://github.com/ChenyCHENYU/MachReport/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
   <a href="https://github.com/ChenyCHENYU/MachReport/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-authorization%20required-dc2626" alt="Authorization required" /></a>
@@ -43,14 +43,14 @@ MachReport 把模板、数据和输出分开：用 TypeScript DSL 或 JSON 定
 | 完整宽表 | 自然列宽、横向滚动、默认 100% 预览；纵向分段窗口化，Excel 自动合并连续 Sheet |
 | 明细与汇总 | 自动折行与分页、重复表头、连续分组小计、末尾总计、页码占位符 |
 | 数据呈现 | 表头与内容独立对齐、类型自动对齐、数值 / 百分比 / 日期格式化、条件格式 |
-| 预览交互 | 双窗口渲染、冻结表头 / 前列、跨页选区、键盘搜索与缩略图、Sheet 导航、可选偏好存储 |
+| 预览交互 | 右下分页、分组导出菜单、内容搜索与字段目录、跨页选区、冻结窗格、Sheet 导航 |
 | 内容编辑 | 默认只读；双击与批量粘贴、原子保存、撤销 / 重做、恢复与变更清单 |
 | Excel 导入 | 多 Sheet、完整宽表、合并单元格、基础样式与缓存公式值转换为可复用模板 |
 | 模板配置 | 轻量属性编辑器、草稿 / 发布 / 历史 / 回滚、CAS 存储适配器、Excel 区域绑定 |
 | 输出 | 浏览器打印、HTML、PDF、真正的 `.xlsx`、逐页 PNG、Word 兼容 HTML `.doc` |
 | 工程接入 | 局部组件、全局插件、异步入口、分层配置、结构化错误与导出告警 |
 | 引擎复用 | 数据 / 参数 JSON Schema、统一 Provider、Node Runtime、浏览器 / Node Worker、流式 Excel |
-| 分析扩展 | 交叉汇总、声明式计算、柱图 / 折线图基础图元；其他图表与二维码通过资源适配器接入 |
+| 分析扩展 | 可选只读选区计算、交叉汇总、声明式计算、柱图 / 折线图基础图元与资源适配 |
 
 数据接口、鉴权与业务规则由宿主应用决定。包内统一校验、分页、编辑事务和版本流程；宿主提供请求与存储适配器。轻量属性编辑器可直接使用；拖拽画布、审批与数据库部署仍由项目按需建设。
 
@@ -60,7 +60,7 @@ MachReport 把模板、数据和输出分开：用 TypeScript DSL 或 JSON 定
 pnpm add @agile-team/mach-report
 ```
 
-Vue 组件要求 Vue `^3.2.0`；主题样式在应用入口引入一次。只使用引擎、PDF 或 XLSX 时，Vue 是可选的，无需导入 `/vue`。发布包声明的 Node.js 要求为 `>=18.0.0`；仓库开发环境要求见[本地开发与验证](#本地开发与验证)。
+Vue 组件要求 Vue `^3.2.47`，最低补丁版已通过现代 TypeScript 严格声明与实际 SSR 验证；主题样式在应用入口引入一次。只使用引擎、PDF 或 XLSX 时，Vue 是可选的，无需导入 `/vue`。发布包声明的 Node.js 要求为 `>=18.0.0`；仓库开发环境要求见[本地开发与验证](#本地开发与验证)。
 
 ## 60 秒开始
 
@@ -210,7 +210,7 @@ Vue 组件默认关闭导入入口，增加一个配置即可选择本机文件
 <MachReportPreview report-id="production" excel-import />
 ```
 
-独立引擎或 Node.js 使用同一转换 API：
+独立引擎或 Node.js 使用同一转换 API。导入需要支持 `DecompressionStream("deflate-raw")` 的环境，Node.js 建议使用 22+；Node.js 18 仍支持核心排版与 PDF / XLSX 导出，缺少安全解压能力时导入会明确报错：
 
 ```ts
 import { importExcelTemplate } from "@agile-team/mach-report/xlsx";
@@ -409,9 +409,11 @@ app.use(machReportPlugin, { fetcher, config });
 
 ### 设置入口与零数据反馈
 
-预览工具栏默认提供「设置」，将阅读、冻结窗格、导出、打印与可选数据操作集中在一个入口。使用方声明允许的能力；用户在面板中按需启用。默认偏好仅在当前实例，可显式提供 `preferences` 存储适配器。设置支持键盘操作、焦点约束和 Esc 关闭，无额外 UI 组件库依赖。
+预览默认采用浅色阅读界面：分页与跳页位于右下方，导出格式收在一个菜单，搜索、字段目录和缩放各自成组。空态插图使用淡蓝强调色，可通过 `theme.emptyAccent` 覆盖；主题只影响预览外壳，不改写模板与导出样式。
 
-Ctrl/Cmd+F打开或聚焦搜索，Enter / Shift+Enter切换命中，Esc关闭并返回预览；缩略图可用键盘操作。Tab跨页浏览业务格，到达首末边界后可离开报表。多层合并表头和重复打印表头不会遮蔽业务行的选择坐标。编辑尚未提交时，打开设置会先等待保存，失败保留原输入与焦点。
+「设置」分为常规、工具和高级三页：常规放冻结窗格及宿主的版式配置，工具控制阅读、输出与已授权的数据操作，高级提供可选选区计算。页面仍只传报表与业务参数，不用组装分页器、搜索框或设置面板。默认工具偏好仅在当前实例，可显式提供 `preferences` 存储适配器；交互开关在本实例内调整。设置支持方向键切页、焦点约束和 Esc 关闭，无额外 UI 组件库依赖。
+
+Ctrl/Cmd+F 打开或聚焦内容搜索，输入时显示检索状态与命中数，Enter / Shift+Enter 切换命中，Esc 关闭并返回搜索入口。字段目录将中文列名、字段标识与章节分组放在同一弹层，↑ / ↓ 选择、Enter 定位、Esc 关闭；无匹配和超出可见结果上限都有明确提示。Tab 可跨页浏览业务格，到达首末边界后离开报表。多层合并表头和重复打印表头不会遮蔽业务行的选择坐标。编辑尚未提交时，打开设置先等待保存，失败保留原输入与焦点。
 
 ```vue
 <ReportPreview
@@ -430,6 +432,8 @@ Ctrl/Cmd+F打开或聚焦搜索，Enter / Shift+Enter切换命中，Esc关闭并
 | 配置 | 行为 |
 | --- | --- |
 | `showSettings: false` | 隐藏设置入口，保留原有工具与控制器 API |
+| `interaction: { calculations: true }` | 默认启用只读选区计算；省略时关闭，也可由用户在设置的高级页开启 |
+| `theme: { emptyAccent: "#79a7e8" }` | 覆盖空态插图强调色，默认淡蓝 |
 | `toolbar: { search: false, thumbnails: false, zoom: false }` | 限制对应阅读工具；设置不能绕过宿主限制 |
 | `toolbar: { exportFormats: ['xlsx', 'pdf'] }` | 仅提供指定出口；省略时提供全部现有格式 |
 | `showExport` / `showPrint` / `showPdfWindow` | 保持原有能力上限；设为 `false` 的工具无法在设置中启用 |
@@ -440,6 +444,50 @@ Ctrl/Cmd+F打开或聚焦搜索，Enter / Shift+Enter切换命中，Esc关闭并
 
 有效报表显示后，组件对已启用的 PDF 出口自动做轻量 HEAD 字体检查，不下载字库或加载 PDF 引擎。结果通过 `state.pdfFont` 提供，资源异常显示可重试提示；实际导出再验证字体文件及文字覆盖范围。部署、跨域与缓存处理见 [PDF 字体指南](https://github.com/ChenyCHENYU/MachReport/blob/main/docs/PDF.md)。
 
+### 可选的只读选区计算
+
+只需一个配置开关；不必开启编辑，也不需要接保存回调：
+
+```vue
+<MachReportPreview report-id="daily" :params="query" :interaction="{ calculations: true }" />
+```
+
+关闭设置，单击起点后用 Shift + 单击或 Shift + 方向键选择数据，再从底部「选区计算」进入高级页。可选求和、平均值、最小值、最大值、数值计数与中位数，或输入 `SUM / COUNT` 等受控摘要表达式；点击「计算选区」才运行，选择过程不会反复重算。取消、切换选区或报表、关闭能力会隔离在途任务与旧结果。
+
+仅原始 `number` 参与；文本编号、数字字符串、日期、布尔和空值排除，真实 `0` 保留。合并格只计一次，同一逻辑表跨页去重，重复表头和结构汇总不叠加。计算采用浮点数，展示小数位不改变源值；应选择单位与量纲一致的数据，不安全整数、除零、溢出和超限均返回诊断。结果仅用于本地分析，不落库、不修改 KPI，也不执行或重算 Excel 原公式。
+
+默认选区最多 100,000 格、扫描预算 200,000，扫描与中位数排序分批让出执行并支持取消。组合公式仅接受摘要名、有限数值、四则运算与括号，限制为 256 字符、64 个 token、16 层深度；不会执行脚本、单元格引用或任意函数。详细操作与边界见[预览交互](https://github.com/ChenyCHENYU/MachReport/blob/main/docs/INTERACTION.md)。
+
+## 完整的日常操作流程
+
+普通页面继续只传报表 ID 和参数。包内默认保护尚未保存的输入与本地草稿；重新查询、导入替换前提供确认，保留焦点与原内容。`state.pendingLocalChanges` 与已保存的净差异 `state.dirty` 分开，已落库的改动不会反复触发丢弃提示。路由离开可复用 `await report.confirmDiscard("leave")`，宿主已有确认组件可通过 `beforeDiscard` 接入。
+
+查询、校验、排版、资源准备、文件生成提供阶段反馈和取消；PDF / Excel / 图片及 HTML / Word 输出报告真实完成单位，无法估算的编码过程不显示虚假百分比。`report.cancelTask()` 与 `state.task` 复用同一状态；忽略取消的自定义接口或导出器也不能用迟到结果覆盖当前报表。
+
+宽表字段目录直接读取模板中的中文列名、多层表头与数据集，支持搜索和跨表精确定位。可选设计器增加列搜索、批量对齐及撤销重做，无需使用方再维护一份列目录。
+
+大宽表适宽时优先挂载当前页和定位目标，其余页面按帧补齐并显示加载占位；切换或卸载取消旧调度。选区只更新变化的属性，减少大量单元格的属性读写。导出仍使用完整计划，使用方无需维护渲染调度。
+
+```ts
+// 在集中配置中声明业务字段能力，页面无需维护编辑器。
+defineMachReportConfig({ defaults: {
+  editable: {
+    fields: {
+      weight: { type: "number", label: "净重", unit: "kg", min: 0, precision: 3 },
+      shift: { type: "enum", options: [{ value: "A", label: "甲班" }, { value: "B", label: "乙班" }] }
+    },
+    save: saveReportCell // 使用项目已有保存方法；持久化批量编辑另提供原子 saveBatch。
+  },
+  output: { fidelity: "strict" } // 已知内容降级时拒绝文件，可在面板查看位置。
+} });
+```
+
+编辑器类型必须与模板的值类型一致；枚举保留原始业务值。公式、受保护格和导入日期不被字段配置解除只读。输出兼容提示支持搜索与定位；默认 `warn` 保留告警并输出，`strict` 拒绝已识别的内容或样式降级。各阅读器、字体与复杂模板仍按实际文件验收。
+
+运行示例后访问 `/product.html`，可体验复杂宽表、A3/A4、类型编辑与诊断；该页面使用明确标识的本地合成数据。
+
+详细流程与取消边界见[产品操作指南](https://github.com/ChenyCHENYU/MachReport/blob/main/docs/PRODUCT_WORKFLOWS.md)。需要复用 Java 后端认证与取数时，可直接运行[Java → Node 参考项目](https://github.com/ChenyCHENYU/MachReport/tree/main/examples/server-java-node)，避免各项目重复拼接 HTTP、精度和下载处理。
+
 ## 接入项目数据
 
 **后端可以只提供业务数据。** 宿主定义模板和取数函数，通过插件 `reports` 或核心 `createReportSource()` 注册；包内自动生成用于预览、打印和导出的 `RenderPlan`。后端无需安装 MachReport，也不必实现专用报表服务；模板也可以由后端存储后返回。
@@ -523,6 +571,8 @@ pnpm test:e2e
 | `pnpm check:quality` | 生产 TS / Vue 函数圈复杂度上限 20，输出可复核统计 |
 | `pnpm check:consumer` | npm 产物在隔离目录的 ESM / CJS 运行与类型验证 |
 | `pnpm test:e2e` | Playwright 浏览器端到端验证 |
+| `pnpm check:compat` | 实际包的严格 ESM/CJS 类型、运行、SSR 与输出兼容检查 |
+| `pnpm check:server-example` | Java→Node 真实 HTTP、精度、错误、取消、下载与混合并发 |
 | `pnpm --filter @agile-team/example-minimal dev` | 启动本地报表示例 |
 
 CI 使用同一套校验命令，并在构建后检查实际发布产物。协作边界、Changesets 与发布流程见 [AGENTS.md](https://github.com/ChenyCHENYU/MachReport/blob/main/AGENTS.md)。
@@ -545,6 +595,7 @@ CI 使用同一套校验命令，并在构建后检查实际发布产物。协
 | 本地报表 | [最小示例](https://github.com/ChenyCHENYU/MachReport/tree/main/examples/minimal)：出库单、工艺卡、多页与多模板预览 |
 | 远程组件 | [模块联邦示例](https://github.com/ChenyCHENYU/MachReport/tree/main/examples/fed-host) · [部署包](https://github.com/ChenyCHENYU/MachReport/tree/main/packages/federation) |
 | 排版与字体 | [字体测量与校准](https://github.com/ChenyCHENYU/MachReport/blob/main/docs/font-calibration.md) |
+| 日常操作与异常恢复 | [产品操作指南](https://github.com/ChenyCHENYU/MachReport/blob/main/docs/PRODUCT_WORKFLOWS.md)：修改保护、长任务、严格输出与路由接入 |
 | 工程质量与还原 | [质量与还原说明](https://github.com/ChenyCHENYU/MachReport/blob/main/docs/QUALITY.md)：复杂度、宿主样式隔离、输出支持矩阵 |
 | 源码分层 | [架构说明](https://github.com/ChenyCHENYU/MachReport/blob/main/docs/ARCHITECTURE.md)：目录职责、hooks、适配器与性能边界 |
 | 版本记录 | [Changelog](https://github.com/ChenyCHENYU/MachReport/blob/main/packages/mach-report/CHANGELOG.md) |
@@ -554,7 +605,7 @@ CI 使用同一套校验命令，并在构建后检查实际发布产物。协
 
 ## 版本与授权
 
-当前源码版本为 `2.6.1`，以 [`packages/mach-report/package.json`](https://github.com/ChenyCHENYU/MachReport/blob/main/packages/mach-report/package.json) 为准；npm 已发布版本由顶部 npm 标识展示。
+当前源码版本为 `2.8.0`，以 [`packages/mach-report/package.json`](https://github.com/ChenyCHENYU/MachReport/blob/main/packages/mach-report/package.json) 为准；npm 已发布版本由顶部 npm 标识展示。
 
 Copyright © 2026 ChenyCHENYU (Agile Team). All rights reserved.