feat: enforce AI page recipe gate

This commit is contained in:
2026-06-17 12:33:09 +08:00
parent e55072598e
commit fcc5719bc6
12 changed files with 414 additions and 11 deletions

View File

@@ -164,9 +164,21 @@ public final class PageBlueprintCompiler {
required(blueprint.entityName(), "entityName");
required(blueprint.primaryKey(), "primaryKey");
required(blueprint.displayField(), "displayField");
if (blueprint.fields().isEmpty()) {
if (blueprint.fields() == null || blueprint.fields().isEmpty()) {
throw new IllegalArgumentException("fields must not be empty");
}
boolean displayFieldExists = false;
for (PageBlueprintField field : blueprint.fields()) {
required(field.name(), "field.name");
required(field.label(), "field.label");
required(field.type(), "field.type");
if (field.name().equals(blueprint.displayField())) {
displayFieldExists = true;
}
}
if (!displayFieldExists) {
throw new IllegalArgumentException("displayField must match one blueprint field");
}
if (blueprint.pageSize() < 1 || blueprint.pageSize() > 200) {
throw new IllegalArgumentException("pageSize must be between 1 and 200");
}

View File

@@ -0,0 +1,24 @@
package com.eip4.platform.metadata.schema.blueprint;
import java.util.List;
import java.util.Map;
public record PageRecipeDefinition(
String recipe,
int schemaVersion,
String title,
Map<String, String> fieldMappings,
List<String> gates) {
public PageRecipeDefinition {
if (recipe == null || recipe.isBlank()) {
throw new IllegalArgumentException("recipe is required");
}
if (schemaVersion < 1) {
throw new IllegalArgumentException("schemaVersion must be positive");
}
title = title == null ? "" : title;
fieldMappings = Map.copyOf(fieldMappings == null ? Map.of() : fieldMappings);
gates = List.copyOf(gates == null ? List.of() : gates);
}
}

View File

@@ -0,0 +1,66 @@
package com.eip4.platform.metadata.schema.blueprint;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
public final class PageRecipeRegistry {
private final Map<String, PageRecipeDefinition> recipes;
public PageRecipeRegistry(List<PageRecipeDefinition> definitions) {
Map<String, PageRecipeDefinition> ordered = new LinkedHashMap<>();
for (PageRecipeDefinition definition : definitions == null ? List.<PageRecipeDefinition>of() : definitions) {
PageRecipeDefinition previous = ordered.put(definition.recipe(), definition);
if (previous != null) {
throw new IllegalArgumentException("Duplicate page recipe: " + definition.recipe());
}
}
this.recipes = Map.copyOf(ordered);
}
public static PageRecipeRegistry defaults() {
return new PageRecipeRegistry(List.of(maintenanceCrud()));
}
public Optional<PageRecipeDefinition> find(String recipe) {
if (recipe == null || recipe.isBlank()) {
return Optional.empty();
}
return Optional.ofNullable(recipes.get(recipe));
}
public boolean supports(String recipe) {
return find(recipe).isPresent();
}
public ObjectNode compile(PageBlueprint blueprint, ObjectMapper objectMapper) {
if (!supports(blueprint == null ? null : blueprint.recipe())) {
String recipe = blueprint == null ? "" : blueprint.recipe();
throw new IllegalArgumentException("Unsupported page recipe: " + recipe);
}
return switch (blueprint.recipe()) {
case PageBlueprint.RECIPE_MAINTENANCE_CRUD -> new PageBlueprintCompiler(objectMapper).compile(blueprint);
default -> throw new IllegalArgumentException("Unsupported page recipe: " + blueprint.recipe());
};
}
private static PageRecipeDefinition maintenanceCrud() {
return new PageRecipeDefinition(
PageBlueprint.RECIPE_MAINTENANCE_CRUD,
PageBlueprint.VERSION,
"EIP4 maintenance CRUD page",
Map.of(
"string", "input-text",
"integer", "input-number",
"number", "input-number",
"date", "input-date",
"datetime", "input-datetime",
"boolean", "switch"),
List.of("page-recipe", "typed-page-schema", "amis-schema", "local-smoke", "playwright-render"));
}
}

View File

@@ -0,0 +1,14 @@
package com.eip4.platform.metadata.schema.blueprint;
import java.util.List;
public record PageRecipeValidationReport(
String recipe,
boolean valid,
List<String> messages) {
public PageRecipeValidationReport {
recipe = recipe == null ? "" : recipe;
messages = List.copyOf(messages == null ? List.of() : messages);
}
}

View File

@@ -0,0 +1,126 @@
package com.eip4.platform.metadata.schema.blueprint;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
public final class PageRecipeValidator {
private final ObjectMapper objectMapper;
private final PageRecipeRegistry registry;
public PageRecipeValidator(ObjectMapper objectMapper, PageRecipeRegistry registry) {
this.objectMapper = objectMapper;
this.registry = registry;
}
public static PageRecipeValidator defaults() {
return new PageRecipeValidator(new ObjectMapper(), PageRecipeRegistry.defaults());
}
public PageRecipeValidationReport validate(PageBlueprint blueprint, JsonNode schema) {
List<String> messages = new ArrayList<>();
if (blueprint == null) {
return report("", List.of("pageBlueprint metadata is required when pageRecipe is declared"));
}
String recipe = blueprint.recipe();
registry.find(recipe).ifPresentOrElse(
definition -> {
if (definition.schemaVersion() != blueprint.schemaVersion()) {
messages.add("pageBlueprintVersion 与 recipe 版本不一致: expected="
+ definition.schemaVersion() + ", actual=" + blueprint.schemaVersion());
}
},
() -> messages.add("未注册的 page recipe: " + recipe));
if (schema == null || !schema.isObject()) {
messages.add("PAGE_SCHEMA payload 顶层必须是 JSON object");
return report(recipe, messages);
}
if (messages.isEmpty()) {
try {
JsonNode expected = registry.compile(blueprint, objectMapper);
if (!expected.equals(schema)) {
String difference = firstDifference(expected, schema, "$");
messages.add("PAGE_SCHEMA payload 与 recipe 编译结果不一致"
+ (difference == null ? "" : ": " + difference));
}
} catch (IllegalArgumentException ex) {
messages.add(ex.getMessage());
}
}
return report(recipe, messages);
}
private static PageRecipeValidationReport report(String recipe, List<String> messages) {
return new PageRecipeValidationReport(recipe, messages.isEmpty(), messages.stream().limit(20).toList());
}
private static String firstDifference(JsonNode expected, JsonNode actual, String path) {
if (expected == null && actual == null) {
return null;
}
if (expected == null || actual == null) {
return path + " expected=" + valueSummary(expected) + ", actual=" + valueSummary(actual);
}
if (expected.isObject() && actual.isObject()) {
Iterator<Map.Entry<String, JsonNode>> fields = expected.fields();
while (fields.hasNext()) {
Map.Entry<String, JsonNode> entry = fields.next();
JsonNode actualChild = actual.get(entry.getKey());
if (actualChild == null) {
return child(path, entry.getKey()) + " missing";
}
String difference = firstDifference(entry.getValue(), actualChild, child(path, entry.getKey()));
if (difference != null) {
return difference;
}
}
Iterator<String> actualNames = actual.fieldNames();
while (actualNames.hasNext()) {
String name = actualNames.next();
if (!expected.has(name)) {
return child(path, name) + " unexpected=" + valueSummary(actual.get(name));
}
}
return null;
}
if (expected.isArray() && actual.isArray()) {
if (expected.size() != actual.size()) {
return path + " array size expected=" + expected.size() + ", actual=" + actual.size();
}
for (int i = 0; i < expected.size(); i++) {
String difference = firstDifference(expected.get(i), actual.get(i), path + "[" + i + "]");
if (difference != null) {
return difference;
}
}
return null;
}
if (!expected.equals(actual)) {
return path + " expected=" + valueSummary(expected) + ", actual=" + valueSummary(actual);
}
return null;
}
private static String child(String path, String field) {
if (field.matches("[A-Za-z_][A-Za-z0-9_]*")) {
return path + "." + field;
}
return path + "['" + field.replace("'", "\\'") + "']";
}
private static String valueSummary(JsonNode node) {
if (node == null || node.isNull()) {
return "null";
}
String text = node.isTextual() ? node.asText() : node.toString();
if (text.length() > 80) {
return text.substring(0, 77) + "...";
}
return text;
}
}

View File

@@ -0,0 +1,61 @@
package com.eip4.platform.metadata.schema.blueprint;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
import java.util.List;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
class PageRecipeValidatorTest {
private static final ObjectMapper MAPPER = new ObjectMapper();
private final PageRecipeValidator validator = new PageRecipeValidator(MAPPER, PageRecipeRegistry.defaults());
@Test
@DisplayName("page recipe 校验接受 compiler 标准输出")
void acceptsCompiledRecipeOutput() {
PageBlueprint blueprint = blueprint();
ObjectNode schema = new PageBlueprintCompiler(MAPPER).compile(blueprint);
PageRecipeValidationReport report = validator.validate(blueprint, schema);
assertTrue(report.valid());
}
@Test
@DisplayName("page recipe 校验拒绝被篡改的 schema")
void rejectsSchemaThatDiffersFromCompilerOutput() {
PageBlueprint blueprint = blueprint();
ObjectNode schema = new PageBlueprintCompiler(MAPPER).compile(blueprint);
schema.put("title", "被篡改标题");
PageRecipeValidationReport report = validator.validate(blueprint, schema);
assertFalse(report.valid());
assertTrue(report.messages().get(0).contains("$.title"));
}
private static PageBlueprint blueprint() {
return new PageBlueprint(
PageBlueprint.VERSION,
PageBlueprint.RECIPE_MAINTENANCE_CRUD,
"eip4ai-contract-type",
"合同类型维护",
"EIP4AI_CONTRACT_TYPE",
"合同类型",
"EIP4AI_CONTRACT_TYPE_ID",
"NAME",
List.of(
new PageBlueprintField("NAME", "名称", "string", true, true, true),
new PageBlueprintField("ENABLED", "启用", "boolean", false, true, true)),
true,
true,
true,
20);
}
}