zero-ai 1.0.74 → 1.0.75

package/.r2mo/task/command/ex-api.yaml.example

@@ -0,0 +1,13 @@
+# 复制为 ex-api.yaml 后按项目修改
+# ai ex-api 使用 .r2mo/task/command/ex-api.yaml
+metadata:
+  identifier: "核心标识符"
+  brief: "接口描述"
+  resource: "resource.ambient"
+  level: 1
+  ptype: "权限集 S_PERM_SET 类型"
+  pname: "权限集 S_PERM_SET 名称"
+# target 可选；存在时需配置 ZERO_MODULE 且 DPA 目录 zero-exmodule-{module} 存在
+# target:
+#   root: "ZERO_MODULE"
+#   module: "ambient"

package/.r2mo/task/task-001.md

@@ -1,12 +1,144 @@
 ---
 runAt: 2026-02-12.22-47-18
-title: 开发 ai ex-res 命令
+title: 开发 ai ex-api 命令
 ---
 
 # 任务
 
-开发 `ai ex-res` 命令对已经开发好的 API 进行授权，此命令为固定命令，要完成全套执行操作，系统重启后要保证权限生效，且命令必须拥有幂等性。
+开发 `ai ex-api` 命令对已经开发好的 API 进行授权，此命令为固定命令，要完成全套执行操作，系统重启后要保证权限生效，且命令必须拥有幂等性。
 
-### 基础输入
+### 前置条件
 
-- 固定角色ID（授权到角色即可）：`e501b47a-c08b-4c83-b12b-95ad82873e96` 
+1. 当前项目中 `.r2mo/task/command/ex-api.yaml` 配置文件必须存在，不存在则直接退出，并且提示用户配置文件缺失。
+2. 环境变量必须，检查这些环境变量必须存在，不存在则跳出
+	```bash
+	export Z_DB_TYPE="MYSQL"   # 数据库类型: MYSQL /   SQLSERVER / ORACLE / POSTGRESQL  
+	export Z_DB_HOST="127.0.0.1"  
+	export Z_DB_PORT="3306"
+	export Z_DBS_INSTANCE=""
+	export Z_DB_APP_USER="r2admin"  
+	export Z_DB_APP_PASS="r2admin"
+	```
+3. 环境变量检查（这个步骤必须）
+	```bash
+	export Z_APP_ID=???
+	export Z_TENANT=???
+	export Z_SIGMA=???
+	```
+4. `ex-api.yaml` 的基本格式
+	```yaml
+	metadata:
+	  identifier: "核心标识符"
+	  brief: "接口描述"
+	  resource: "resource.ambient"
+	  level: ???
+	  ptype: "权限集 S_PERM_SET 类型"
+	  pname: "权限集 S_PERM_SET 名称"
+      keyword: "app.test.data"
+	target:
+	  root: "ZERO_MODULE"
+	  module: "ambient"
+	```
+5. 存在 target 配置多检查一个环境变量 ZERO_MODULE，并且检查`{ZERO_MODULE}/zero-exmodule-{module}` 是否一个标准的DPA架构，若不是则命令退出
+
+### 执行逻辑
+
+1. 检查前置条件是否满足，不检查 `ex-api.yaml` 的格式问题
+2. 参数检查：
+	- `-r "<METHOD> <uri>"` ，其中 `r` 的全称是 `request`
+	- `-s`，其中 `s` 的全称是 `skip`，若如此则只生成 Excel，可能最终不完美（没做去重检查），但交给开发人员处理
+3. 定义表信息
+	- `S_RESOURCE`：资源定义
+	- `S_ACTION`：操作定义
+	- `S_PERMISSION`：权限定义
+	- `S_PERM_SET`：权限集定义
+	- `R_ROLE_PERM`：角色权限定义
+4. 先检查 `S_ACTION` 中是否已经存在当前参数，按列名开发（`METHOD, URI`；不唯一时追加 `SIGMA, APP_ID, TENANT_ID`），只有当 `METHOD, URI` 无法提取唯一记录时追加后续三个查询条件
+	- 若存在不创建数据记录，提取 `S_ACTION` 中的 ID
+	- 若不存在则创建数据记录 / `S_RESOURCE` 需要同步创建（因为 `S_RESOURCE` 资源是新的）
+5. 询问用户：追加新权限 / 执行已有权限，若执行已有权限，按 `S_PERMISSION` 中的 identifier 进行查询让用户选择追加到那个权限（追加到已有权限则直接跳过额外的数据库操作）
+6. 提取数据库中已有的 `S_ROLE` 角色信息，可多选，让用户选择当前 API 授权给哪些角色
+
+## 输出说明
+
+### 数据库输出
+
+- 同步五张表的信息，注意要幂等性，不引起异常
+
+### Excel输出
+
+1. 如果存在 `target` 的配置，则输出项目根目录应该是 `${ZERO_MODULE}/zero-exmodule-{module}`，它必须是 DPA 架构，生成的 `excel` 的信息应该位于 `${ZERO_MODULE}/zero-exmodule-{module}/zero-exmodule-{module}-domain` 的资源目录下，开发时查看一下，有一个 `plugins/***/security/RBAC_RESOURCE` 目录。
+2. Excel 直接覆盖，不提示选择文件；文件名固化为 `identifier-method-uri.xlsx`（uri 中 `/` 转 `-`）；无 target 时输出到 **-api** 项目下 `plugins/.../security/`。
+3. `plugins/***/security/RBAC_ROLE/ADMIN.SUPER/`（固定）写入带 **falcon** 前缀的同名文件（`falcon-identifier-method-uri.xlsx`）；若没有 `target` 则写入当前/ -api 项目下的 `plugins/zero-launcher-configuration/security/` 目录下。
+4. `plugins` 都是从 maven 项目的 src/main/resources 开始计算
+5. 在目标路径下生成对应的 `*.xlsx` 或更改现有的内容
+
+### Excel 样式约定
+
+- **默认模板**：模板位于 R2MO-INIT 项目固定路径 `src/_template/EXCEL/ex-api`，与执行命令所在项目无关；任意项目执行 ai ex-api 均使用该默认模板驱动。
+- **仅填数据，样式与模板完全一致**：除写入的数据单元格 value 外，不修改任何 style（格式、颜色、边框、合并单元格、行数等）。不删行、不清格式、不填色、不设边框，输出与模板在视觉和结构上一致。
+
+### 属性规则
+
+-  `S_RESOURCE`
+	- 资源名称，从 `ex-api.yaml` 中提取
+	- `modelRole` -> UNION 固定值
+	- 资源编码 `res` 前缀加 `S_ACTION` 的 code
+	- `identifier / type / level` 这些配置文件中有
+- `S_ACTION`
+	- 操作编码，读取当前 `identifier` 下的核心操作编码追加 `act` 前缀
+	- 操作名称同 `brief`（和资源一样）
+	- 操作级别同 `S_RESOURCE`
+- `S_PERMISSION`
+	- 权限名称同 `brief`（备注也想通）
+	- 权限码 `perm` 前缀
+	- 所属模型 `identifier`
+- `S_PERM_SET`：参考前边规则提取，配置文件中有
+- 如果出现 `keyword`，则所有编码名称直接追加，不计算，比如
+	- `res.${keyword}`
+	- `act.${keyword}`
+	- `perm.${keyword}`
+
+### 核心输出
+
+- 数据库中建立关系
+- Excel中建立管理
+- Excel中的UUID值固化
+
+### 全局列补充（仅数据库，不写入 Excel）
+
+仅**实体表**写入全局列：S_RESOURCE、S_ACTION、S_PERMISSION。若表中包含以下列则一并写入；Excel 中不输出这些列。关系表 R_ROLE_PERM 只有 ROLE_ID、**PERM_ID** 两列，无全局列。
+
+| 列名 | 取值来源 |
+|------|----------|
+| `sigma` | 环境变量 `Z_SIGMA` |
+| `appId` | 环境变量 `Z_APP_ID` |
+| `tenantId` | 环境变量 `Z_TENANT` |
+| `scope` | 环境变量 `Z_APP` |
+| `createdBy` | 固定值 `9a0d5018-33ad-4c64-80bf-8ae7947c482f`（R2_BY） |
+| `updatedBy` | 固定值 `9a0d5018-33ad-4c64-80bf-8ae7947c482f`（R2_BY） |
+| `createdAt` | 当前时间（R2_NOW） |
+| `updatedAt` | 当前时间（R2_NOW） |
+
+- 全局列在开发时按建表固定写好，执行时不查元数据；Excel 输出中不包含上述全局列，仅做数据库同步。
+
+### 表列信息（开发时对齐，执行时不查元数据）
+
+**所有 SQL 与 Excel 表头列名在开发时按 RBAC 建表（如 zero-exmodule-rbac Flyway）固定写好；ai ex-api 执行时只执行 DML，不访问数据库元数据（不执行 SHOW COLUMNS 等）。**
+
+- **R_ROLE_PERM**：关系表，仅两列 **ROLE_ID**、**PERM_ID**（无 `PERMISSION_ID`）。
+- S_RESOURCE、S_ACTION、S_PERMISSION 实体表列名与 Flyway 一致：S_ACTION 用 **SIGMA/APP_ID/TENANT_ID**（非 Z_*），S_PERMISSION 用 **COMMENT**（非 REMARK）；唯一性查询带 SIGMA 以保证幂等。全局列（SIGMA/APP_ID/TENANT_ID/CREATED_BY/UPDATED_BY/CREATED_AT/UPDATED_AT）在代码中写死，不运行时查表。
+- 开发阶段可用 `node script/scan-rbac-schema.js`（可选 `--write`）核对库表列名与脚本一致；不修改 RBAC 的 Flyway 配置。
+
+### 执行约定（仅 DML，不查元数据）
+
+- ai ex-api 执行时**只执行 DML**（SELECT/INSERT/INSERT IGNORE），**不访问数据库元数据**（如 SHOW COLUMNS）。
+- 表列名在**开发时**按 RBAC 建表（如 Flyway）固定写好，运行时不再查询表结构。
+- **假设**：执行时数据表已存在且结构固定；**禁止**表扫描、DDL、元数据提取（已知表结构，无需运行时获取）。
+
+### 完整打印（成功与失败）
+
+- **启动**：配置路径、request 参数、skip、数据库连接信息。
+- **步骤**：已存在/已创建 S_RESOURCE、S_ACTION、S_PERMISSION，R_ROLE_PERM 同步角色数，Excel 写出路径。
+- **成功**：`[ex-api] 执行完成（幂等）` 及汇总（ACTION_ID、RESOURCE_ID、PERMISSION_ID、授权角色数、Excel 路径）。
+- **失败**：`[ex-api] 执行失败` + 错误信息、错误码、sqlMessage、sql 语句、堆栈。

package/.r2mo/task/task-002.md

@@ -0,0 +1,4 @@
+---
+runAt: 2026-02-12.23-18-53
+title: 任务
+---

package/.r2mo/task/task-003.md

@@ -0,0 +1,4 @@
+---
+runAt: 2026-02-13.08-58-12
+title: 任务
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zero-ai",
-  "version": "1.0.74",
+  "version": "1.0.75",
   "description": "Zero Ecotope AI",
   "main": "src/ai.js",
   "bin": {
@@ -38,16 +38,17 @@
     "i": "^0.3.7",
     "immutable": "^4.3.0",
     "inquirer": "^8.2.5",
+    "js-yaml": "^4.1.1",
     "linebyline": "^1.3.0",
     "lodash": "^4.17.21",
     "mkdirp": "^3.0.1",
     "mockjs": "^1.1.0",
+    "mysql2": "^3.11.0",
     "random-js": "^2.1.0",
     "superagent": "^8.0.9",
     "taffydb": "^2.7.3",
     "underscore": "^1.13.6",
-    "uuid": "^9.0.0",
-    "mysql2": "^3.11.0"
+    "uuid": "^9.0.0"
   },
   "homepage": "http://www.vertxai.cn",
   "github": "https://github.com/silentbalanceyh/vertx-ai.git"

package/script/clear-excel-template-data.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * 清空 src/_template/EXCEL/ex-api 下两个模板 xlsx 中所有 {TABLE} 区域的数据行，只保留表头。
+ * 执行一次后，ai ex-api 只需直接填充数据，无需运行时清除。
+ * 运行：node script/clear-excel-template-data.js
+ */
+const path = require("path");
+const fs = require("fs");
+const ExcelJS = require("exceljs");
+
+const cwd = process.cwd();
+const templateDir = path.resolve(cwd, "src", "_template", "EXCEL", "ex-api");
+const maxCols = 50;
+const limit = 5000;
+
+function scanTableRegions(ws) {
+    if (!ws) return [];
+    const regions = [];
+    let i = 1;
+    while (i <= limit) {
+        const row = ws.getRow(i);
+        const first = row.getCell(1).value;
+        const v = first != null ? String(first).trim() : "";
+        if (v === "{TABLE}") {
+            const tableNameCell = row.getCell(2).value;
+            const tableName = tableNameCell != null ? String(tableNameCell).trim() : "";
+            const headerRowCount = 2;
+            const dataStartRow = i + 1 + headerRowCount;
+            let dataEndRow = dataStartRow - 1;
+            let j = i + 1;
+            while (j <= limit) {
+                const nextRow = ws.getRow(j);
+                const nextFirst = nextRow.getCell(1).value;
+                const nv = nextFirst != null ? String(nextFirst).trim() : "";
+                if (nv === "{TABLE}") {
+                    dataEndRow = j - 1;
+                    break;
+                }
+                dataEndRow = j;
+                j++;
+            }
+            regions.push({ tableName, tableStartRow: i, dataStartRow, dataEndRow });
+            i = dataEndRow + 1;
+            continue;
+        }
+        i++;
+    }
+    return regions;
+}
+
+function clearRegion(ws, dataStartRow, dataEndRow) {
+    for (let r = dataStartRow; r <= dataEndRow; r++) {
+        const row = ws.getRow(r);
+        for (let c = 1; c <= maxCols; c++) row.getCell(c).value = null;
+    }
+}
+
+/** 清除指定行的背景与边框（表间两行空白用） */
+function clearBlankRowFormat(ws, startRow, endRow, maxCols) {
+    if (!ws || endRow < startRow) return;
+    const cols = maxCols || 20;
+    const noFill = { type: "pattern", pattern: "none" };
+    const noBorder = { top: { style: "none" }, left: { style: "none" }, bottom: { style: "none" }, right: { style: "none" } };
+    for (let r = startRow; r <= endRow; r++) {
+        const row = ws.getRow(r);
+        for (let c = 1; c <= cols; c++) {
+            const cell = row.getCell(c);
+            if (cell.fill) cell.fill = noFill;
+            if (cell.border) cell.border = noBorder;
+        }
+    }
+}
+
+/** 表间只保留 2 行空白：删除 (dataStartRow+3) 到 (下一表 tableStartRow-1) 的多余行，从后往前删避免行号变化 */
+function compressTableGaps(ws, regions) {
+    if (!regions || regions.length < 2) return;
+    const BLANK_ROWS = 2;
+    const deletions = [];
+    for (let i = 0; i < regions.length - 1; i++) {
+        const start = regions[i].dataStartRow + 1 + BLANK_ROWS; // 保留 1 行数据位 + 2 空行
+        const end = regions[i + 1].tableStartRow - 1;
+        if (end >= start) {
+            const count = end - start + 1;
+            deletions.push({ start, count });
+        }
+    }
+    deletions.sort((a, b) => b.start - a.start);
+    deletions.forEach(({ start, count }) => {
+        try {
+            ws.spliceRows(start, count);
+        } catch (e) {
+            console.warn("spliceRows(" + start + "," + count + ") 跳过: " + e.message);
+        }
+    });
+}
+
+async function processFile(fileName) {
+    const filePath = path.join(templateDir, fileName);
+    if (!fs.existsSync(filePath)) {
+        console.log("跳过（不存在）: " + filePath);
+        return;
+    }
+    const wb = await new ExcelJS.Workbook().xlsx.readFile(filePath);
+    let cleared = 0;
+    wb.worksheets.forEach((ws) => {
+        const regions = scanTableRegions(ws);
+        regions.forEach((reg) => {
+            clearRegion(ws, reg.dataStartRow, reg.dataEndRow);
+            cleared += Math.max(0, reg.dataEndRow - reg.dataStartRow + 1);
+            clearBlankRowFormat(ws, reg.dataStartRow + 1, reg.dataStartRow + 2, maxCols);
+        });
+        compressTableGaps(ws, regions);
+    });
+    await wb.xlsx.writeFile(filePath);
+    console.log("已清空、压缩并写回: " + fileName + "（清除 " + cleared + " 行，表间仅留 2 行空行）");
+}
+
+async function main() {
+    console.log("模板目录: " + templateDir);
+    await processFile("template-RBAC_RESOURCE.xlsx");
+    await processFile("template-RBAC_ROLE.xlsx");
+    console.log("完成。模板仅保留表头，ai ex-api 将直接填充数据。");
+}
+
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});

package/script/create-ex-api-templates.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * 生成 ai ex-api 使用的 Excel 模板，写入 src/_template/ex-api/
+ * 可与 ZERO_MODULE 下已有 RBAC Excel 格式对齐后，将彼处文件复制到 src/_template/ex-api/ 覆盖本脚本生成的标准模板。
+ * 运行：node script/create-ex-api-templates.js
+ */
+const path = require("path");
+const fs = require("fs");
+const ExcelJS = require("exceljs");
+
+const cwd = process.cwd();
+const templateDir = path.resolve(cwd, "src", "_template", "ex-api");
+
+if (!fs.existsSync(templateDir)) fs.mkdirSync(templateDir, { recursive: true });
+
+async function main() {
+    const wbRes = new ExcelJS.Workbook();
+    wbRes.creator = "ai ex-api template";
+    const wsRes = wbRes.addWorksheet("DATA-RES", { views: [{ state: "frozen", ySplit: 1 }] });
+    wsRes.addRow(["ID", "CODE", "NAME", "IDENTIFIER", "TYPE", "LEVEL", "MODE_ROLE"]);
+
+    const wbRole = new ExcelJS.Workbook();
+    wbRole.creator = "ai ex-api template";
+    const wsRole = wbRole.addWorksheet("DATA-PERM", { views: [{ state: "frozen", ySplit: 1 }] });
+    wsRole.addRow(["ROLE_ID", "PERM_ID"]);
+
+    const outRes = path.join(templateDir, "template-RBAC_RESOURCE.xlsx");
+    const outRole = path.join(templateDir, "template-RBAC_ROLE.xlsx");
+    await wbRes.xlsx.writeFile(outRes);
+    await wbRole.xlsx.writeFile(outRole);
+    console.log("已生成模板：");
+    console.log("  " + outRes);
+    console.log("  " + outRole);
+}
+
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});

package/script/inspect-excel-templates.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * 检查 src/_template/EXCEL/ex-api 下 template-RBAC_ROLE.xlsx 与 template-RBAC_RESOURCE.xlsx 的详细格式。
+ * 输出：工作表名、行/列数、前若干行单元格内容，便于按模板格式填充。
+ * 运行：node script/inspect-excel-templates.js
+ */
+const path = require("path");
+const fs = require("fs");
+const ExcelJS = require("exceljs");
+
+const cwd = process.cwd();
+const templateDir = path.resolve(cwd, "src", "_template", "EXCEL", "ex-api");
+const maxRows = 15;
+const maxCols = 20;
+
+async function inspectFile(fileName) {
+    const filePath = path.join(templateDir, fileName);
+    if (!fs.existsSync(filePath)) {
+        console.log("\n文件不存在: " + filePath);
+        return null;
+    }
+    const wb = await new ExcelJS.Workbook().xlsx.readFile(filePath);
+    const result = { file: fileName, sheetCount: wb.worksheets.length, sheets: [] };
+    for (let i = 0; i < wb.worksheets.length; i++) {
+        const ws = wb.worksheets[i];
+        const sheetInfo = {
+            name: ws.name,
+            id: ws.id,
+            rowCount: ws.rowCount,
+            columnCount: ws.columnCount,
+            rows: []
+        };
+        const rowCount = Math.min(ws.rowCount || 0, maxRows);
+        const colCount = Math.min((ws.columnCount || 0) + 5, maxCols);
+        for (let r = 1; r <= rowCount; r++) {
+            const row = ws.getRow(r);
+            const cells = [];
+            row.eachCell({ includeEmpty: true }, (cell, colNumber) => {
+                if (colNumber <= colCount) {
+                    let v = cell && cell.value != null ? cell.value : "";
+                    if (v && typeof v === "object" && v.text !== undefined) v = v.text;
+                    if (v && typeof v === "object" && v.result !== undefined) v = v.result;
+                    cells.push(v);
+                }
+            });
+            for (let c = cells.length; c < colCount; c++) cells.push("");
+            sheetInfo.rows.push(cells);
+        }
+        if (sheetInfo.rows.length === 0 && (ws.columnCount || ws.rowCount)) {
+            for (let r = 1; r <= Math.min(5, ws.rowCount || 5); r++) {
+                const row = ws.getRow(r);
+                const cells = [];
+                row.eachCell({ includeEmpty: true }, (cell, colNumber) => {
+                    if (colNumber <= maxCols) cells.push(cell && cell.value != null ? cell.value : "");
+                });
+                sheetInfo.rows.push(cells);
+            }
+        }
+        result.sheets.push(sheetInfo);
+    }
+    return result;
+}
+
+function printResult(obj) {
+    if (!obj) return;
+    console.log("\n========== " + obj.file + " ==========");
+    console.log("工作表数量:", obj.sheetCount);
+    obj.sheets.forEach((sh, idx) => {
+        console.log("\n--- Sheet[" + idx + "] 名称: " + sh.name + " ---");
+        console.log("  行数(约):", sh.rowCount, " 列数(约):", sh.columnCount);
+        sh.rows.forEach((row, rIdx) => {
+            const line = row.map((c) => (c == null ? "" : String(c).slice(0, 30)));
+            console.log("  行" + (rIdx + 1) + ":", JSON.stringify(line));
+        });
+    });
+}
+
+async function main() {
+    console.log("模板目录:", templateDir);
+    const a = await inspectFile("template-RBAC_RESOURCE.xlsx");
+    const b = await inspectFile("template-RBAC_ROLE.xlsx");
+    printResult(a);
+    printResult(b);
+    if (a) {
+        const defPath = path.join(templateDir, "template-def.json");
+        const def = {
+            RBAC_RESOURCE: a.sheets[0] ? { sheetName: a.sheets[0].name, columns: (a.sheets[0].rows[0] || []).map((c) => String(c || "").trim() || null).filter(Boolean) } : null,
+            RBAC_ROLE: b && b.sheets[0] ? { sheetName: b.sheets[0].name, columns: (b.sheets[0].rows[0] || []).map((c) => String(c || "").trim() || null).filter(Boolean) } : null
+        };
+        if (def.RBAC_RESOURCE && def.RBAC_RESOURCE.columns.length) def.RBAC_RESOURCE.columns = def.RBAC_RESOURCE.columns.filter((c) => c);
+        if (def.RBAC_ROLE && def.RBAC_ROLE.columns.length) def.RBAC_ROLE.columns = def.RBAC_ROLE.columns.filter((c) => c);
+        if (!def.RBAC_RESOURCE || !def.RBAC_RESOURCE.columns.length) def.RBAC_RESOURCE = { sheetName: "DATA-RES", columns: ["ID", "CODE", "NAME", "IDENTIFIER", "TYPE", "LEVEL", "MODE_ROLE"] };
+        if (!def.RBAC_ROLE || !def.RBAC_ROLE.columns.length) def.RBAC_ROLE = { sheetName: "DATA-PERM", columns: ["ROLE_ID", "PERM_ID"] };
+        fs.writeFileSync(defPath, JSON.stringify(def, null, 2), "utf-8");
+        console.log("\n已写入 template-def.json（表头从首行解析）");
+    }
+}
+
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});

package/script/read-ex-api-templates.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * 解读 src/_template/ex-api 下两个 xlsx，提取工作表名与首行表头，生成 template-def.json 供 ai ex-api 按模版生成。
+ * 运行：node script/read-ex-api-templates.js
+ */
+const path = require("path");
+const fs = require("fs");
+const ExcelJS = require("exceljs");
+
+const cwd = process.cwd();
+const templateDir = path.resolve(cwd, "src", "_template", "ex-api");
+const resPath = path.join(templateDir, "template-RBAC_RESOURCE.xlsx");
+const rolePath = path.join(templateDir, "template-RBAC_ROLE.xlsx");
+
+async function readSheetDef(filePath, key) {
+    if (!fs.existsSync(filePath)) {
+        console.warn("文件不存在，跳过: " + filePath);
+        return null;
+    }
+    const wb = await new ExcelJS.Workbook().xlsx.readFile(filePath);
+    const ws = wb.worksheets[0];
+    if (!ws) return null;
+    const sheetName = ws.name;
+    const firstRow = ws.getRow(1);
+    const columns = [];
+    firstRow.eachCell({ includeEmpty: true }, (cell, colNumber) => {
+        const v = cell && cell.value != null ? String(cell.value).trim() : "";
+        columns.push(v || "Column" + colNumber);
+    });
+    return { sheetName, columns };
+}
+
+async function main() {
+    const RBAC_RESOURCE = await readSheetDef(resPath, "RBAC_RESOURCE");
+    const RBAC_ROLE = await readSheetDef(rolePath, "RBAC_ROLE");
+
+    const def = {
+        RBAC_RESOURCE: RBAC_RESOURCE || { sheetName: "DATA-RES", columns: ["ID", "CODE", "NAME", "IDENTIFIER", "TYPE", "LEVEL", "MODE_ROLE"] },
+        RBAC_ROLE: RBAC_ROLE || { sheetName: "DATA-PERM", columns: ["ROLE_ID", "PERM_ID"] }
+    };
+
+    const outPath = path.join(templateDir, "template-def.json");
+    fs.writeFileSync(outPath, JSON.stringify(def, null, 2), "utf-8");
+    console.log("已解读 xlsx 并写入模版定义：" + outPath);
+    console.log(JSON.stringify(def, null, 2));
+}
+
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});

package/script/scan-rbac-schema.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * 扫描 RBAC 相关表结构，输出列信息，用于对齐 ai ex-api 等命令的 SQL 列名。
+ * 使用前请 source .r2mo/app.env 或设置环境变量：
+ *   Z_DB_HOST, Z_DB_PORT, Z_DB_APP_USER, Z_DB_APP_PASS, Z_DBS_INSTANCE
+ * 运行：node script/scan-rbac-schema.js
+ * 可选：--write 将结果写入 .r2mo/task/rbac-schema.txt
+ */
+const path = require("path");
+const fs = require("fs");
+
+const cwd = process.cwd();
+
+function getArtifactIdFromPom(dir) {
+    const pomPath = path.resolve(dir, "pom.xml");
+    if (!fs.existsSync(pomPath)) return null;
+    let content = fs.readFileSync(pomPath, "utf-8");
+    content = content.replace(/<parent>[\s\S]*?<\/parent>/i, "");
+    const m = content.match(/<artifactId>([^<]+)<\/artifactId>/);
+    return m ? m[1].trim() : null;
+}
+
+function resolveAppEnvPath(dir) {
+    const primary = path.resolve(dir, ".r2mo", "app.env");
+    if (fs.existsSync(primary)) return primary;
+    const artifactId = getArtifactIdFromPom(dir) || path.basename(dir);
+    if (artifactId && artifactId !== ".") {
+        const apiEnv = path.resolve(dir, artifactId + "-api", ".r2mo", "app.env");
+        if (fs.existsSync(apiEnv)) return apiEnv;
+    }
+    return primary;
+}
+
+const appEnvPath = resolveAppEnvPath(cwd);
+if (fs.existsSync(appEnvPath)) {
+    const content = fs.readFileSync(appEnvPath, "utf-8");
+    content.split(/\r?\n/).forEach((line) => {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("#") || !trimmed.startsWith("export ")) return;
+        const match = trimmed.match(/^export\s+([A-Za-z0-9_]+)=["']?([^"'\n]*)["']?/);
+        if (match) process.env[match[1]] = match[2].trim();
+    });
+}
+
+const required = ["Z_DB_APP_USER", "Z_DB_APP_PASS", "Z_DBS_INSTANCE"];
+const missing = required.filter((k) => !process.env[k] || !String(process.env[k]).trim());
+if (missing.length > 0) {
+    console.error("缺少环境变量：" + missing.join(", "));
+    console.error("请 source .r2mo/app.env 或设置 Z_DB_APP_USER, Z_DB_APP_PASS, Z_DBS_INSTANCE");
+    process.exit(1);
+}
+
+const mysql = require("mysql2/promise");
+const dbConfig = {
+    host: process.env.Z_DB_HOST || "127.0.0.1",
+    port: parseInt(process.env.Z_DB_PORT || "3306", 10),
+    user: process.env.Z_DB_APP_USER,
+    password: process.env.Z_DB_APP_PASS,
+    database: process.env.Z_DBS_INSTANCE
+};
+
+const TABLES = ["S_RESOURCE", "S_ACTION", "S_PERMISSION", "S_PERM_SET", "R_ROLE_PERM"];
+
+async function main() {
+    const conn = await mysql.createConnection(dbConfig);
+    const lines = [];
+    try {
+        const header = "数据库：" + dbConfig.database + " @ " + dbConfig.host + ":" + dbConfig.port;
+        console.log(header);
+        lines.push(header);
+        lines.push("（以下列名用于对齐 ai ex-api / ex-perm 等命令的 SQL，请勿手写列名，以扫描为准）");
+        lines.push("---");
+        for (const table of TABLES) {
+            try {
+                const [rows] = await conn.execute("SHOW COLUMNS FROM `" + table.replace(/`/g, "") + "`");
+                const columns = rows.map((r) => r.Field);
+                const line = table + " 列：" + columns.join(", ");
+                console.log(line);
+                lines.push(line);
+            } catch (e) {
+                const msg = table + "：表不存在或无权限 - " + e.message;
+                console.log(msg);
+                lines.push(msg);
+            }
+        }
+    } finally {
+        await conn.end();
+    }
+    const writeOut = process.argv.includes("--write");
+    if (writeOut && lines.length > 0) {
+        const outPath = path.resolve(cwd, ".r2mo", "task", "rbac-schema.txt");
+        const dir = path.dirname(outPath);
+        if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(outPath, lines.join("\n") + "\n", "utf-8");
+        console.log("已写入：" + outPath);
+    }
+}
+
+main().catch((e) => {
+    console.error(e.message);
+    process.exit(1);
+});

package/src/_template/EXCEL/ex-api/README.md

@@ -0,0 +1,13 @@
+# ai ex-api Excel 模板（R2MO-INIT 默认模板）
+
+模板固定位于 **R2MO-INIT** 项目下的 `src/_template/EXCEL/ex-api`，与执行命令所在项目无关：任意项目执行 `ai ex-api` 时，均使用本目录下的默认模板驱动生成 RBAC_RESOURCE / RBAC_ROLE 的 xlsx，保证输出风格与模板一致。
+
+- **template-RBAC_RESOURCE.xlsx**：RBAC 资源/权限集（S_PERM_SET 等 {TABLE} 区域）。
+- **template-RBAC_ROLE.xlsx**：RBAC 角色权限（R_ROLE_PERM 等 {TABLE} 区域）。
+
+模板仅保留表头结构（含 `{TABLE}`、中文表头、英文驼峰列名），**数据行已预清空**。ai ex-api 输出时**只写入数据单元格的 value**，除此以外不修改任何 style（格式、颜色、边框、合并单元格等），不删行、不清格式，输出与模板完全一致。
+
+- **清空并压缩模板（一次性）**：在 r2mo-init 根目录执行  
+  `node script/clear-excel-template-data.js`  
+  会清除上述两个 xlsx 中所有 {TABLE} 区域的数据行，并将表间空隙压缩为仅 2 行空白，写回后 ai ex-api 仅填充。
+- 若从 ZERO_MODULE 复制了新 xlsx 覆盖本目录模板，需重新执行一次上述脚本再使用。

package/src/_template/EXCEL/ex-api/template-def.json

@@ -0,0 +1,21 @@
+{
+  "RBAC_RESOURCE": {
+    "sheetName": "DATA-RES",
+    "columns": [
+      "ID",
+      "CODE",
+      "NAME",
+      "IDENTIFIER",
+      "TYPE",
+      "LEVEL",
+      "MODE_ROLE"
+    ]
+  },
+  "RBAC_ROLE": {
+    "sheetName": "DATA-PERM",
+    "columns": [
+      "ROLE_ID",
+      "PERM_ID"
+    ]
+  }
+}