docs: precipitate HTML report contract for data management

references/ACTIONS.md

@@ -490,7 +490,7 @@ HINT: <next step>
 | 导入 / 重置 | sync 或 async | skill-detail, agent | 可选 |
 | 单条副作用 RPA | async（建议） | agent, skill-detail | **建议** |
 | 批量顺序 pick RPA | async（建议） | toolbar, cron, agent | **建议** |
-## 同步数据 vs 导出当前表 vs 特殊业务报告
+## 同步数据 vs 导出当前表 vs 特殊业务报告 vs HTML 页面
 
 不要混用「导出」一词：
 
@@ -498,12 +498,64 @@ HINT: <next step>
 |------|------|--------|
 | **同步数据**（sync / refresh / collect） | 外部来源 → 技能本地数据库 | 技能 Action / domain service |
 | **导出当前数据表** | 技能本地数据库 → CSV/Excel 等 | 数据管理页**宿主统一导出** |
-| **生成特殊业务报告** | 多表合并、特殊排版或附加计算 | 仅当系统导出无法满足时，才提供独立 `export-*` Action |
+| **生成特殊业务报告（文件）** | 多表合并、特殊排版或附加计算的 **xlsx/csv/json 等文件** | 仅当系统导出无法满足时，才提供独立 `export-*` Action；文件落 `output/` |
+| **HTML 页面报告** | 可在数据管理侧栏预览的整页 HTML | 技能写入 `{skill_data}/html/*.html` + Action id **`render-html`**（见下节） |
 
 同步型 Action 默认：读外部数据、写技能自己的库、**不**生成 CSV/Excel/JSON 文件、不重复实现宿主表导出。兼容旧 export 命令若需要刷新数据，必须调用同一个 sync 业务内核。通用同步语义见 [`SCHEMA.md`](SCHEMA.md) 与 [`../development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。
 
-## inputSchema 与参数表单
+## HTML 页面报告（数据管理预览）
 
+> 一句话：**技能负责生成并覆盖 `html/*.html`；宿主负责发现、预览、用 `render-html` 触发重新生成。**
+
+### 何时用
+
+- 需要**可浏览的整页报告**（KPI + 表格 + 自带样式），而不是再导出一张表
+- 与 `export-*` / 宿主表导出**并列**：HTML 走 `html/`；文件型特殊报告仍走 `output/` + `export-*`
+
+### 目录与发现（宿主契约）
+
+| 项 | 约定 |
+|----|------|
+| 路径 | `{skill_data}/html/*.html`，**只扫一层**（子目录忽略） |
+| helper | `util.runtime_paths.get_html_dir()`；写入用 `service.html_page_service.write_html_page` |
+| 侧栏名 | 取文件内 `<title>`（缺省则用文件名） |
+| 预览 | 宿主 iframe 预览；右键：重新生成 / 浏览器打开 / 刷新 |
+| 模板资源 | 建议放 `assets/html/*.html`（安装包内），渲染后**写出**到数据目录 `html/` |
+
+### Action：`render-html`（固定 id）
+
+宿主「重新生成」**硬编码**查找 Action id `render-html`（见 `service.html_page_service.HOST_HTML_RENDER_ACTION_ID`）。技能未提供该 id → 提示「该技能未提供生成 HTML」。
+
+推荐形态：
+
+| 字段 | 建议 |
+|------|------|
+| `id` | **必须** `render-html` |
+| `executionProfile` | `sync` |
+| `interaction` | `direct` |
+| `placements` | `toolbar` + `skill-detail`（配合表顶栏与 HTML 右键）；可选 `agent` |
+| `bind.tables` | 数据**来源表**（含 `toolbar` 时必填）；宿主从 HTML 页重新生成时会用 bind 补齐跑表上下文 |
+| `steps` | `afterSuccess` → **`refreshCatalog`**（重扫 `htmlPages`；不要只 `reloadTable`） |
+| `entrypoint` | CLI 子命令（如 `render-html`）调用同一写入内核 |
+
+完整 JSON 形状见 [`../assets/examples/render-html.action.example.json`](../assets/examples/render-html.action.example.json)。最小页面壳见 [`../assets/html/example-report.html`](../assets/html/example-report.html)。
+
+### 实现要点
+
+1. 用 `load_html_template` + `render_html_placeholders` + `write_html_page`（原子 `*.tmp` + `os.replace`）覆盖同名文件；**不要**每次另存带时间戳的副本（除非产品明确要求历史版本）。
+2. 页头时间建议用**写出时刻**（「报告生成于」），不要误用业务表里过期的 `generated_at` 冒充「刚重新生成」。
+3. 可选：数据重算成功后调用静默写入（吞掉错误），保持侧栏报告与库一致。
+4. 权限：按业务决定谁能生成（管理员 / 角色）；在 CLI/`cmd_render_html` 内强制校验。
+5. CHANGELOG / 用户说明：模板或样式升级后，提醒「请在数据管理对报告执行一次重新生成」。
+
+### 验收（复制后自测）
+
+- [ ] `html/` 下出现 `.html`，数据管理侧栏能看到报告项，预览正常
+- [ ] 表顶栏（若声明 toolbar）或报告右键「重新生成」能跑通；成功后预览刷新
+- [ ] 未登录/无权限用户被拒绝，且有可读错误
+- [ ] 成功路径带 `refreshCatalog`（或等价让侧栏/预览看到更新）
+
+## inputSchema 与参数表单
 ### 表单字段类型对照（须与 CRUD 对称）
 
 Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件语义**。CRUD 侧配置见 [`SCHEMA.md`](SCHEMA.md)「表单与展示：稳定字段类型」；本表只写 Action 怎么配。