diff --git a/docs/P1/F4-L1设计器报告.md b/docs/P1/F4-L1设计器报告.md
new file mode 100644
index 0000000..d334b81
--- /dev/null
+++ b/docs/P1/F4-L1设计器报告.md
@@ -0,0 +1,31 @@
+# F4-L1 页面设计器报告(amis-editor 二开 + overlay 双层落地)
+
+> 日期:2026-06-12
+> 依据:《EIP4前端与收尾实施计划.md》F4-L1 + 6.2 标准/overlay 双层架构(已拍板)
+> 结论:L1 最小闭环交付——管理员可视化编辑页面 → 保存自动落 overlay 层 → 渲染 overlay 优先 → 一键还原标准版;e2e 68/68(含 7 个设计器用例)
+
+## 一、overlay 双层协议(后端,platform-metadata)
+
+- 新表 `SYS_PAGE_SCHEMA_OVERLAY`(template_id 主键/schema_json/schema_etag/version/update_time/updated_by/**base_etag**=编辑时所基于的标准层 etag,升级 diff 凭据);DDL `docs/sql/F4-L1_overlay.sql`,双库已执行(eip4dev.eip3 + eip4m0.public)
+- PageSchemaController 读取顺序:**overlay 优先 → 标准层**,响应头 `X-Schema-Layer: overlay|standard` 标明来源;`GET ?layer=standard` 取底版
+- `PUT /api/page/schema/{id}/overlay` 保存(管理员 403 防护,etag=sha256);`DELETE .../overlay` 还原标准版
+- **标准层只写主体仍是转换器+load_page_schema 入库器**——设计器永不触碰标准层,升级时标准层整体替换、overlay 保留并可按 base_etag 提示差异(6.2 设计意图的机制载体)
+
+## 二、设计器前端(eip4-web)
+
+- **选型:多页入口隔离**(editor.html 独立 vite 入口 + src/editor/)——amis-editor 的 npm amis 依赖与主应用本地 SDK 渲染链隔离,主应用包体不受影响
+- 设计器三屏:左组件面板/中画布/右属性(amis-editor 自带);顶部条:保存(→overlay)/还原标准版/预览(开 /page/:id)
+- 入口:页面 Tab 上管理员可见「设计」按钮(PageRenderPage)
+- overlay 与标准版并存时提示「当前编辑的是定制版(基于标准版)」
+
+## 三、验证
+
+- 后端单测(PageSchemaControllerTest 扩展:读取顺序/保存/还原/403)全绿;TSC 干净
+- e2e designer.spec.ts 7 用例:打开设计器→改 label→保存→渲染出 overlay(X-Schema-Layer=overlay)→还原→渲染回标准(X-Schema-Layer=standard);测试页用 sys-admin-user,测后还原零污染
+- 全套 e2e **68/68**
+
+## 四、已知边界(L1.5/L2 后续)
+
+- facade 动词 onEvent 的可视化配置面板未做(编辑时配置不丢即可,已验证);
+- 「另存为应用包/导入包」(6.3 在线导入发布协议)随 L2 实体建模器一并设计;
+- 设计器仅管理员可达,未细分设计权限角色。
diff --git a/docs/sql/F4-L1_overlay.sql b/docs/sql/F4-L1_overlay.sql
new file mode 100644
index 0000000..bfc31b0
--- /dev/null
+++ b/docs/sql/F4-L1_overlay.sql
@@ -0,0 +1,36 @@
+-- ============================================================================
+-- F4-L1 overlay 层建表脚本:SYS_PAGE_SCHEMA_OVERLAY
+-- ----------------------------------------------------------------------------
+-- 架构:标准/overlay 双层。
+-- 标准层 SYS_PAGE_SCHEMA —— platform-converter 转换产物(1493 条),升级时整体替换。
+-- overlay 层(本表) —— 管理员用设计器定制后保存,优先级高于标准层。
+-- 设计器「还原标准版」时 DELETE 本表对应行即可。
+--
+-- 执行范围:
+-- eip4dev.eip3(本地开发库)
+-- eip4m0.public(目标生产库)
+--
+-- base_etag:保存时记录当时标准层 etag(用于设计器「当前定制基于标准版 vX」提示对比)。
+-- schema_etag:overlay schema_json 的内容指纹(sha-256 hex),用于 HTTP ETag/304。
+-- version:首次写入为 1,同 templateId 每次 PUT overlay +1(单调递增,供运维追溯)。
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS sys_page_schema_overlay (
+ template_id character varying(64) NOT NULL,
+ schema_json jsonb NOT NULL,
+ schema_etag character varying(64) NOT NULL,
+ version integer NOT NULL DEFAULT 1,
+ update_time bigint NOT NULL,
+ updated_by character varying(64) NOT NULL,
+ base_etag character varying(64) NOT NULL,
+ CONSTRAINT pk_sys_page_schema_overlay PRIMARY KEY (template_id)
+);
+
+COMMENT ON TABLE sys_page_schema_overlay IS 'F4-L1 设计器 overlay 层(管理员定制版),优先于标准层 sys_page_schema 下发';
+COMMENT ON COLUMN sys_page_schema_overlay.template_id IS 'view_template_id,与 sys_page_schema.template_id 对应';
+COMMENT ON COLUMN sys_page_schema_overlay.schema_json IS '设计器保存的定制 amis schema(顶层 type:page)';
+COMMENT ON COLUMN sys_page_schema_overlay.schema_etag IS 'schema_json 内容指纹(sha-256 hex),HTTP ETag/304 用';
+COMMENT ON COLUMN sys_page_schema_overlay.version IS '单调递增版本(首次 1,每次 PUT +1)';
+COMMENT ON COLUMN sys_page_schema_overlay.update_time IS '保存时间 epoch 毫秒';
+COMMENT ON COLUMN sys_page_schema_overlay.updated_by IS '操作人 sys_user_id';
+COMMENT ON COLUMN sys_page_schema_overlay.base_etag IS '保存时标准层 schema_etag(用于「基于标准版 vX」提示对比)';
diff --git a/platform-metadata/src/main/java/com/eip4/platform/metadata/web/PageSchemaController.java b/platform-metadata/src/main/java/com/eip4/platform/metadata/web/PageSchemaController.java
index 647938b..c36d36a 100644
--- a/platform-metadata/src/main/java/com/eip4/platform/metadata/web/PageSchemaController.java
+++ b/platform-metadata/src/main/java/com/eip4/platform/metadata/web/PageSchemaController.java
@@ -1,61 +1,111 @@
package com.eip4.platform.metadata.web;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import java.util.HexFormat;
+import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
import org.springframework.dao.DataAccessException;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.server.ResponseStatusException;
+
+import com.dsasp.server.common.user.service.LoggedInUser;
+import com.dsasp.server.common.util.UserSession;
import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
/**
- * 页面 schema 服务化端点(P4-4 切流前公共端点之一)。
+ * 页面 schema 服务化端点(P4-4 + F4-L1 双层扩展)。
*
- *
把 platform-converter 的转换产物({@code 转换产物/schema/{view_template_id}.json},1489 个)
- * 经 {@code SchemaImportCli} 入库 {@code SYS_PAGE_SCHEMA} 后,由本端点在线下发——前端
- * eip4-web 在 {@code VITE_SCHEMA_SOURCE=backend} 时读这里(契约见 ../eip4-web/README.md「与后端契约清单」
- * 与 src/api/schema.ts)。
- *
- *
契约(与 eip4-web/src/api/schema.ts 对齐):
+ *
双层读取(F4-L1):
*
- * - {@code GET /api/page/schema/{templateId}} → 200 直接返回 amis 页面 schema(JSON,顶层 type:page);
- * - {@code 404}:模板不存在(库内无该 templateId 记录);
- * - {@code 503}:schema 存储不可用(SYS_PAGE_SCHEMA 表缺失/库异常,即「转换器/产物不可用」)。
+ * - 标准层({@code SYS_PAGE_SCHEMA}):platform-converter 转换产物,升级时整体替换,不可编辑。
+ * - overlay 层({@code SYS_PAGE_SCHEMA_OVERLAY}):管理员通过设计器保存的定制版,优先级高于标准层。
+ *
+ * 读取顺序:overlay 优先 → 标准层;响应头 {@code X-Schema-Layer} 标明来源({@code overlay} / {@code standard})。
+ *
+ * 新增端点(F4-L1):
+ *
+ * - {@code GET /api/page/schema/{templateId}?layer=standard} — 强制取标准层(设计器对比底版用)
+ * - {@code PUT /api/page/schema/{templateId}/overlay} — 保存 overlay(仅管理员)
+ * - {@code DELETE /api/page/schema/{templateId}/overlay} — 还原标准版(仅管理员)
*
*
- * ETag/304:amis schema 不小(KB 级),入库时已算内容指纹({@code schema_etag}=sha-256 hex)。
- * 响应带 {@code ETag} 强校验;请求带匹配的 {@code If-None-Match} 时回 304(空体),省去重复下发与解析。
+ *
原契约不变(与 eip4-web/src/api/schema.ts 对齐):
+ *
+ * - {@code GET /api/page/schema/{templateId}} → 200 直接返回 amis 页面 schema;
+ * - {@code 404}:模板不存在;{@code 503}:schema 存储不可用。
+ * - ETag/304:overlay 存在时 ETag 取 overlay 的 schema_etag。
+ *
*/
+@Tag(name = "页面 schema", description = "F4-L1 标准/overlay 双层 schema 服务化端点")
@RestController
public class PageSchemaController {
+ private static final Logger log = LoggerFactory.getLogger(PageSchemaController.class);
+
+ /** 响应头:标明 schema 来源层(overlay / standard) */
+ public static final String HEADER_SCHEMA_LAYER = "X-Schema-Layer";
+
private final JdbcTemplate jdbcTemplate;
public PageSchemaController(JdbcTemplate jdbcTemplate) {
this.jdbcTemplate = jdbcTemplate;
}
- @Operation(summary = "下发页面 amis schema(带 ETag/304)",
- description = "VITE_SCHEMA_SOURCE=backend 时前端读此端点;404=模板不存在,503=schema 存储不可用")
+ // ================================================================ GET 读取
+
+ @Operation(summary = "下发页面 amis schema(overlay 优先,带 ETag/304,响应头 X-Schema-Layer)",
+ description = "?layer=standard 强制取标准层;默认 overlay 优先→标准层;404=模板不存在,503=schema 存储不可用")
@GetMapping("/api/page/schema/{templateId}")
- public ResponseEntity schema(@PathVariable String templateId,
- @RequestHeader(value = HttpHeaders.IF_NONE_MATCH, required = false)
- String ifNoneMatch) {
+ public ResponseEntity schema(
+ @PathVariable String templateId,
+ @RequestHeader(value = HttpHeaders.IF_NONE_MATCH, required = false) String ifNoneMatch,
+ @RequestParam(value = "layer", required = false) String layer) {
+
+ boolean forceStandard = "standard".equalsIgnoreCase(layer);
+
+ // 1. 尝试 overlay(除非显式要求 standard 层)
+ if (!forceStandard) {
+ try {
+ List