diff --git a/README.md b/README.md index 76788d1..34fabf1 100644 --- a/README.md +++ b/README.md @@ -85,6 +85,8 @@ java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai feature-package java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release verify --package-file target/ai-runs/package.json java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release export --package-file target/ai-runs/package.json --output target/ai-runs/package.eip4pkg.json java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release import-preview --package-file target/ai-runs/package.eip4pkg.json +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release diff --left target/ai-runs/package-old.json --right target/ai-runs/package.json +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release rollback-plan --package-file target/ai-runs/package.eip4pkg.json --output target/ai-runs/rollback-plan.json ``` ## tools/ diff --git a/docs/AI_AGENT_Nocobase_ADOPTION_PLAN.md b/docs/AI_AGENT_Nocobase_ADOPTION_PLAN.md index 2f2ef4f..8229b92 100644 --- a/docs/AI_AGENT_Nocobase_ADOPTION_PLAN.md +++ b/docs/AI_AGENT_Nocobase_ADOPTION_PLAN.md @@ -124,7 +124,7 @@ EIP4 当前已经有实体、页面 schema、服务流、菜单、smoke、部署 - `eip4 release package` - `eip4 release verify` - `eip4 release apply --require-approval` -- `eip4 release rollback --package-id` +- `eip4 release rollback-plan --package-file FILE --output FILE` 验收标准: @@ -138,6 +138,7 @@ EIP4 当前已经有实体、页面 schema、服务流、菜单、smoke、部署 - 参考 NocoBase revision 创建前检查版本控制插件的思路,EIP4 后续 revision restore/diff 不能只依赖 JSON 快照,必须有发布系统能力检查。 - 新增 `eip4 release verify --package-file FILE`,先做离线发布前门禁,阻断未替换占位符和缺失本地 evidence 的功能包。 - 新增 `eip4 release export/import-preview`,形成 `.eip4pkg.json` 文件格式和 checksum 门禁;导入预览不写环境、不启用功能。 +- 新增 `eip4 release diff/rollback-plan`,先落地离线差异检查和计划型回滚;回滚计划不执行生产 SQL。 - 详细源码对照见 `docs/AI_AGENT_Nocobase_SOURCE_REVIEW.md`。 ### P4:Typed Page Schema 和组件注册表 @@ -191,6 +192,6 @@ EIP4 应该借鉴的是边界和流程: | P0 | 完成 | `platform-ai` 主链路已提交 | | P1 | 第一版完成 | 已新增 `platform-cli` 和 Skills 规范骨架 | | P2 | 第一版完成 | 已新增功能包快照、里程碑 revision、CLI 命令和持久化表 | -| P3 | 进行中 | 已完成 env registry/current env/cross-env guard/release verify/export/import-preview 第一版 | +| P3 | 进行中 | 已完成 env registry/current env/cross-env guard/release verify/export/import-preview/diff/rollback-plan 第一版 | | P4 | 待开始 | 依赖页面 schema 现状清理 | | P5 | 待开始 | 依赖权限、审计、工具白名单成熟 | diff --git a/docs/AI_AGENT_Nocobase_SOURCE_REVIEW.md b/docs/AI_AGENT_Nocobase_SOURCE_REVIEW.md index f804c95..d973c2c 100644 --- a/docs/AI_AGENT_Nocobase_SOURCE_REVIEW.md +++ b/docs/AI_AGENT_Nocobase_SOURCE_REVIEW.md @@ -46,6 +46,8 @@ - 新增 `eip4 release verify --package-file FILE`,离线检查功能包是否具备本地门禁 evidence、人审标记、SQL/rollback,并阻断 `${...}` 占位符。 - 新增 `eip4 release export --package-file FILE --output FILE`,将功能包封装为 `.eip4pkg.json`,包含格式版本和 SHA-256 checksum。 - 新增 `eip4 release import-preview --package-file FILE`,离线验证 `.eip4pkg.json` checksum 和发布门禁,不写任何环境。 +- 新增 `eip4 release diff --left FILE --right FILE`,离线比较两个功能包或 `.eip4pkg.json` 的标识、SQL、rollback SQL 和 manifest 差异。 +- 新增 `eip4 release rollback-plan --package-file FILE --output FILE`,只生成结构化回滚计划,不执行生产写入。 ## 三、后续实现顺序 @@ -79,12 +81,20 @@ ### P3-3:Revision diff/restore +状态:第一版完成。 + 目标: - revision diff - rollback plan - rollback 只生成计划和 SQL,不默认执行生产写入 +第一版已落地: + +- diff: 比较两个普通 feature package JSON 或 `.eip4pkg.json`,支持 checksum 校验和 JSON 输出。 +- rollback-plan: 生成 `EIP4_ROLLBACK_PLAN` JSON,包含 package/task/changeSet、rollback SQL、source evidence 和人审要求。 +- rollback-plan 会阻断 rollback SQL 中的 `${...}` 占位符;命令不连接环境、不落库、不执行 SQL。 + ### P4:Typed UI Registry 目标: diff --git a/docs/skills/eip4-release-manage.md b/docs/skills/eip4-release-manage.md index 691190e..94621a8 100644 --- a/docs/skills/eip4-release-manage.md +++ b/docs/skills/eip4-release-manage.md @@ -52,15 +52,31 @@ java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release import-pre --package-file target/ai-runs/feature-package.eip4pkg.json ``` -6. 确认部署包包含: +6. 如存在上一版功能包,先做离线差异检查: + +```bash +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release diff \ + --left target/ai-runs/feature-package-old.json \ + --right target/ai-runs/feature-package.json +``` + +7. 需要回滚预案时,只生成回滚计划文件: + +```bash +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release rollback-plan \ + --package-file target/ai-runs/feature-package.eip4pkg.json \ + --output target/ai-runs/rollback-plan.json +``` + +8. 确认部署包包含: - manifest - SQL 草案 - rollback SQL - 本地 apply evidence - smoke evidence - repair evidence -7. 确认部署包需要人工审批。 -8. 如果包含 `${parentMenuId}` 等占位符,必须人工替换并复核;`release verify` 默认会阻断这类包。 +9. 确认部署包需要人工审批。 +10. 如果包含 `${parentMenuId}` 等占位符,必须人工替换并复核;`release verify` 默认会阻断这类包。 ## 线上 bug 修复路径 @@ -77,3 +93,4 @@ java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release import-pre - 不把 smoke 失败的变更包交给发布流程。 - 不发布 `release verify` 失败的功能包。 - 不把 `import-preview` 当成导入或启用;它只是离线检查。 +- 不把 `rollback-plan` 当成回滚执行;它只生成计划和 SQL 清单。 diff --git a/platform-cli/src/main/java/com/eip4/platform/cli/Eip4Cli.java b/platform-cli/src/main/java/com/eip4/platform/cli/Eip4Cli.java index 5d6ca42..ad2dc92 100644 --- a/platform-cli/src/main/java/com/eip4/platform/cli/Eip4Cli.java +++ b/platform-cli/src/main/java/com/eip4/platform/cli/Eip4Cli.java @@ -11,9 +11,11 @@ import java.security.NoSuchAlgorithmException; import java.util.ArrayList; import java.util.HexFormat; import java.util.LinkedHashMap; +import java.util.LinkedHashSet; import java.util.List; import java.util.Locale; import java.util.Map; +import java.util.Set; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; @@ -94,13 +96,50 @@ public final class Eip4Cli { return 0; } return switch (args[1]) { + case "diff" -> runReleaseDiff(args, out, err); case "export" -> runReleaseExport(args, out); case "import-preview" -> runReleaseImportPreview(args, out, err); + case "rollback-plan" -> runReleaseRollbackPlan(args, out, err); case "verify" -> runReleaseVerify(args, out, err); default -> fail(err, "Unknown release command: " + args[1]); }; } + private int runReleaseDiff(String[] args, PrintStream out, PrintStream err) throws IOException { + Options options = Options.parse(args, 2); + Path leftFile = Path.of(requiredPart(options.single("left"), "left")); + Path rightFile = Path.of(requiredPart(options.single("right"), "right")); + JsonNode leftRoot = objectMapper.readTree(Files.readString(leftFile, StandardCharsets.UTF_8)); + JsonNode rightRoot = objectMapper.readTree(Files.readString(rightFile, StandardCharsets.UTF_8)); + List blockers = new ArrayList<>(); + validateEnvelope(leftRoot, blockers, false); + validateEnvelope(rightRoot, blockers, false); + JsonNode leftPayload = packagePayload(leftRoot); + JsonNode rightPayload = packagePayload(rightRoot); + JsonNode leftDeploymentPackage = deploymentPackage(leftPayload); + JsonNode rightDeploymentPackage = deploymentPackage(rightPayload); + ObjectNode report = buildReleaseDiff(leftPayload, rightPayload, leftDeploymentPackage, rightDeploymentPackage); + report.put("status", blockers.isEmpty() ? "PASSED" : "FAILED"); + ArrayNode blockerNodes = report.putArray("blockers"); + blockers.forEach(blockerNodes::add); + if (!blockers.isEmpty()) { + return printReleaseOperationFailed("Release diff", blockers, err); + } + if (options.has("json-output")) { + out.println(objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(report)); + return 0; + } + out.println("Release diff " + (report.path("changed").asBoolean(false) ? "CHANGED" : "UNCHANGED")); + out.println("leftPackageId: " + report.path("leftPackageId").asText()); + out.println("rightPackageId: " + report.path("rightPackageId").asText()); + printArrayDiffSummary(report.path("sqlStatements"), out, "sqlStatements"); + printArrayDiffSummary(report.path("rollbackSqlStatements"), out, "rollbackSqlStatements"); + if (report.path("manifestChanged").asBoolean(false)) { + out.println("manifest: changed"); + } + return 0; + } + private int runReleaseExport(String[] args, PrintStream out) throws IOException { Options options = Options.parse(args, 2); Path packageFile = Path.of(requiredPart(options.single("package-file"), "package-file")); @@ -134,6 +173,33 @@ public final class Eip4Cli { return printReleaseValidation(validation, options, out, err, "Import preview"); } + private int runReleaseRollbackPlan(String[] args, PrintStream out, PrintStream err) throws IOException { + Options options = Options.parse(args, 2); + Path packageFile = Path.of(requiredPart(options.single("package-file"), "package-file")); + Path output = Path.of(requiredPart(options.single("output"), "output")); + JsonNode raw = objectMapper.readTree(Files.readString(packageFile, StandardCharsets.UTF_8)); + List blockers = new ArrayList<>(); + validateEnvelope(raw, blockers, false); + JsonNode payload = packagePayload(raw); + JsonNode deploymentPackage = deploymentPackage(payload); + validateRollbackPlanSource(payload, deploymentPackage, blockers); + if (!blockers.isEmpty()) { + return printReleaseOperationFailed("Rollback plan", blockers, err); + } + ObjectNode plan = buildRollbackPlan(raw, payload, deploymentPackage); + if (output.getParent() != null) { + Files.createDirectories(output.getParent()); + } + Files.writeString(output, + objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(plan) + System.lineSeparator(), + StandardCharsets.UTF_8); + out.println("Wrote rollback plan: " + output.toAbsolutePath()); + out.println("packageId: " + plan.path("packageId").asText()); + out.println("rollbackSqlStatements: " + plan.path("rollbackSqlStatements").size()); + out.println("mode: " + plan.path("mode").asText()); + return 0; + } + private int runReleaseVerify(String[] args, PrintStream out, PrintStream err) throws IOException { Options options = Options.parse(args, 2); Path packageFile = Path.of(requiredPart(options.single("package-file"), "package-file")); @@ -169,6 +235,80 @@ public final class Eip4Cli { return new ReleaseValidation(report, List.copyOf(blockers), List.copyOf(warnings)); } + private ObjectNode buildReleaseDiff(JsonNode leftPayload, JsonNode rightPayload, + JsonNode leftDeploymentPackage, JsonNode rightDeploymentPackage) { + ObjectNode report = objectMapper.createObjectNode(); + String leftPackageId = packageId(leftPayload, leftDeploymentPackage); + String rightPackageId = packageId(rightPayload, rightDeploymentPackage); + report.put("leftPackageId", leftPackageId); + report.put("rightPackageId", rightPackageId); + ObjectNode fields = report.putObject("fields"); + putScalarDiff(fields, "packageId", leftPackageId, rightPackageId); + putScalarDiff(fields, "taskId", text(leftDeploymentPackage, "taskId"), text(rightDeploymentPackage, "taskId")); + putScalarDiff(fields, "changeSetId", text(leftDeploymentPackage, "changeSetId"), + text(rightDeploymentPackage, "changeSetId")); + ObjectNode sqlDiff = textArrayDiff(leftDeploymentPackage.path("sqlStatements"), + rightDeploymentPackage.path("sqlStatements")); + ObjectNode rollbackDiff = textArrayDiff(leftDeploymentPackage.path("rollbackSqlStatements"), + rightDeploymentPackage.path("rollbackSqlStatements")); + report.set("sqlStatements", sqlDiff); + report.set("rollbackSqlStatements", rollbackDiff); + boolean manifestChanged = !leftDeploymentPackage.path("manifest").equals(rightDeploymentPackage.path("manifest")); + report.put("manifestChanged", manifestChanged); + boolean fieldsChanged = fieldsChanged(fields); + report.put("changed", fieldsChanged + || sqlDiff.path("changed").asBoolean(false) + || rollbackDiff.path("changed").asBoolean(false) + || manifestChanged); + return report; + } + + private ObjectNode buildRollbackPlan(JsonNode root, JsonNode payload, JsonNode deploymentPackage) { + ObjectNode plan = objectMapper.createObjectNode(); + plan.put("type", "EIP4_ROLLBACK_PLAN"); + plan.put("version", 1); + plan.put("generatedAt", System.currentTimeMillis()); + plan.put("packageId", packageId(payload, deploymentPackage)); + plan.put("taskId", text(deploymentPackage, "taskId")); + plan.put("changeSetId", text(deploymentPackage, "changeSetId")); + plan.put("sourceChecksum", root.path("checksum").asText("")); + plan.put("requiresHumanApproval", true); + plan.put("mode", "PLAN_ONLY"); + plan.put("policy", "Review and apply through the approved release process. This file does not execute SQL."); + ArrayNode rollback = plan.putArray("rollbackSqlStatements"); + textValues(deploymentPackage.path("rollbackSqlStatements")).forEach(rollback::add); + ArrayNode sourceEvidence = plan.putArray("sourceRunEvidence"); + if (deploymentPackage.path("runEvidence").isArray()) { + deploymentPackage.path("runEvidence").forEach(sourceEvidence::add); + } + ArrayNode warnings = plan.putArray("warnings"); + warnings.add("Generated offline; no production SQL was executed."); + deploymentPackage.path("warnings").forEach(warning -> warnings.add(warning.asText())); + return plan; + } + + private void validateRollbackPlanSource(JsonNode payload, JsonNode deploymentPackage, List blockers) { + if (!payload.isObject()) { + blockers.add("payload 必须是功能包 JSON object"); + } + if (!deploymentPackage.isObject()) { + blockers.add("deploymentPackage 必须是 JSON object"); + return; + } + if (packageId(payload, deploymentPackage).isBlank()) { + blockers.add("packageId 不能为空"); + } + if (!deploymentPackage.path("requiresHumanApproval").asBoolean(false)) { + blockers.add("deploymentPackage.requiresHumanApproval 必须是 true"); + } + if (!hasTextArrayItems(deploymentPackage.path("rollbackSqlStatements"))) { + blockers.add("rollbackSqlStatements 不能为空"); + } + if (containsPlaceholder(deploymentPackage.path("rollbackSqlStatements"))) { + blockers.add("rollbackSqlStatements 仍包含 ${...} 占位符,必须人工替换后再生成回滚计划"); + } + } + private void validateEnvelope(JsonNode root, List blockers, boolean requireEnvelope) throws IOException { if (!root.has("format")) { if (requireEnvelope) { @@ -265,6 +405,12 @@ public final class Eip4Cli { return validation.blockers().isEmpty() ? 0 : 2; } + private int printReleaseOperationFailed(String label, List blockers, PrintStream err) { + err.println(label + " FAILED"); + blockers.forEach(blocker -> err.println("- " + blocker)); + return 2; + } + private int runEnvAdd(String[] args, PrintStream out) throws IOException { Options options = Options.parse(args, 2); String name = requiredPart(options.single("name"), "name"); @@ -598,6 +744,68 @@ public final class Eip4Cli { return false; } + private List textValues(JsonNode node) { + List values = new ArrayList<>(); + if (!node.isArray()) { + return values; + } + for (JsonNode item : node) { + String value = item.asText(""); + if (!value.isBlank()) { + values.add(value); + } + } + return values; + } + + private ObjectNode textArrayDiff(JsonNode left, JsonNode right) { + List leftValues = textValues(left); + List rightValues = textValues(right); + Set leftSet = new LinkedHashSet<>(leftValues); + Set rightSet = new LinkedHashSet<>(rightValues); + ObjectNode node = objectMapper.createObjectNode(); + node.put("leftCount", leftValues.size()); + node.put("rightCount", rightValues.size()); + ArrayNode added = node.putArray("added"); + for (String value : rightSet) { + if (!leftSet.contains(value)) { + added.add(value); + } + } + ArrayNode removed = node.putArray("removed"); + for (String value : leftSet) { + if (!rightSet.contains(value)) { + removed.add(value); + } + } + boolean orderChanged = added.isEmpty() && removed.isEmpty() && !leftValues.equals(rightValues); + node.put("orderChanged", orderChanged); + node.put("changed", !added.isEmpty() || !removed.isEmpty() || orderChanged); + return node; + } + + private void putScalarDiff(ObjectNode parent, String field, String left, String right) { + ObjectNode node = parent.putObject(field); + node.put("left", left); + node.put("right", right); + node.put("changed", !left.equals(right)); + } + + private boolean fieldsChanged(ObjectNode fields) { + for (JsonNode field : fields) { + if (field.path("changed").asBoolean(false)) { + return true; + } + } + return false; + } + + private void printArrayDiffSummary(JsonNode diff, PrintStream out, String label) { + out.println(label + ": added=" + diff.path("added").size() + + ", removed=" + diff.path("removed").size() + + ", orderChanged=" + diff.path("orderChanged").asBoolean(false)); + } + private boolean hasRunEvidence(JsonNode runEvidence, String runType, String status) { if (!runEvidence.isArray()) { return false; @@ -665,8 +873,10 @@ public final class Eip4Cli { eip4 env current eip4 env status [--env NAME|--base-url URL|--all] eip4 ai auto-develop --objective TEXT --feature-name NAME --table-name TABLE --entity-name NAME --template-id ID --menu-name NAME --field column:label:type[:length][:required] + eip4 release diff --left FILE --right FILE eip4 release export --package-file FILE --output FILE eip4 release import-preview --package-file FILE + eip4 release rollback-plan --package-file FILE --output FILE eip4 release verify --package-file FILE Environment: @@ -678,8 +888,10 @@ public final class Eip4Cli { private void printReleaseHelp(PrintStream out) { out.println(""" Usage: + eip4 release diff --left FILE --right FILE [--json-output] eip4 release export --package-file FILE --output FILE eip4 release import-preview --package-file FILE [--json-output] + eip4 release rollback-plan --package-file FILE --output FILE eip4 release verify --package-file FILE [--json-output] """); } diff --git a/platform-cli/src/test/java/com/eip4/platform/cli/Eip4CliTest.java b/platform-cli/src/test/java/com/eip4/platform/cli/Eip4CliTest.java index 7d5482d..102667b 100644 --- a/platform-cli/src/test/java/com/eip4/platform/cli/Eip4CliTest.java +++ b/platform-cli/src/test/java/com/eip4/platform/cli/Eip4CliTest.java @@ -316,18 +316,87 @@ class Eip4CliTest { assertTrue(preview.err().contains("checksum 不匹配")); } + @Test + void releaseDiffReportsSqlAndRollbackChanges() throws Exception { + Path left = packageFile("left-package.json", "aipkg-left", + "insert into sys_page_schema values ('left')", + "delete from sys_page_schema where id = 'left'"); + Path right = packageFile("right-package.json", "aipkg-right", + "insert into sys_page_schema values ('right')", + "delete from sys_page_schema where id = 'right'"); + + CliResult result = run(new CapturingClient(new Eip4HttpResponse(200, "{}")), + "release", "diff", + "--left", left.toString(), + "--right", right.toString(), + "--json-output"); + + assertEquals(0, result.code()); + JsonNode report = objectMapper.readTree(result.out()); + assertTrue(report.path("changed").asBoolean()); + assertEquals("aipkg-left", report.path("leftPackageId").asText()); + assertEquals("aipkg-right", report.path("rightPackageId").asText()); + assertEquals(1, report.path("sqlStatements").path("added").size()); + assertTrue(report.path("sqlStatements").path("added").get(0).asText().contains("'right'")); + assertEquals(1, report.path("rollbackSqlStatements").path("removed").size()); + } + + @Test + void releaseRollbackPlanWritesPlanOnlyArtifact() throws Exception { + Path source = validPackageFile("package-source.json"); + Path planFile = tempDir.resolve("rollback-plan.json"); + + CliResult result = run(new CapturingClient(new Eip4HttpResponse(200, "{}")), + "release", "rollback-plan", + "--package-file", source.toString(), + "--output", planFile.toString()); + + assertEquals(0, result.code()); + JsonNode plan = objectMapper.readTree(Files.readString(planFile)); + assertEquals("EIP4_ROLLBACK_PLAN", plan.path("type").asText()); + assertEquals("PLAN_ONLY", plan.path("mode").asText()); + assertEquals("aipkg-1", plan.path("packageId").asText()); + assertTrue(plan.path("requiresHumanApproval").asBoolean()); + assertEquals(1, plan.path("rollbackSqlStatements").size()); + assertTrue(plan.path("policy").asText().contains("does not execute SQL")); + assertTrue(result.out().contains("Wrote rollback plan")); + } + + @Test + void releaseRollbackPlanBlocksRollbackPlaceholders() throws Exception { + Path source = packageFile("package-with-rollback-placeholder.json", "aipkg-placeholder", + "insert into sys_page_schema values ('x')", + "delete from sys_page_schema where id = '${pageSchemaId}'"); + Path planFile = tempDir.resolve("rollback-plan.json"); + + CliResult result = run(new CapturingClient(new Eip4HttpResponse(200, "{}")), + "release", "rollback-plan", + "--package-file", source.toString(), + "--output", planFile.toString()); + + assertEquals(2, result.code()); + assertTrue(result.err().contains("Rollback plan FAILED")); + assertTrue(result.err().contains("rollbackSqlStatements 仍包含")); + } + private Path validPackageFile(String name) throws Exception { + return packageFile(name, "aipkg-1", + "insert into sys_page_schema values ('x')", + "delete from sys_page_schema where id = 'x'"); + } + + private Path packageFile(String name, String packageId, String sql, String rollbackSql) throws Exception { Path file = tempDir.resolve(name); Files.writeString(file, """ { - "id": "aipkg-1", + "id": "%s", "deploymentPackage": { "taskId": "ait-1", "changeSetId": "aics-1", "status": "READY_FOR_HUMAN_REVIEW", "requiresHumanApproval": true, - "sqlStatements": ["insert into sys_page_schema values ('x')"], - "rollbackSqlStatements": ["delete from sys_page_schema where id = 'x'"], + "sqlStatements": [%s], + "rollbackSqlStatements": [%s], "warnings": [], "runEvidence": [ {"runType": "LOCAL_APPLY", "status": "PASSED"}, @@ -335,7 +404,8 @@ class Eip4CliTest { ] } } - """, StandardCharsets.UTF_8); + """.formatted(packageId, objectMapper.writeValueAsString(sql), + objectMapper.writeValueAsString(rollbackSql)), StandardCharsets.UTF_8); return file; }