F4-L1: overlay 双层落地——设计器存盘协议(标准层只读,定制落 SYS_PAGE_SCHEMA_OVERLAY)

- 读取顺序 overlay→标准,X-Schema-Layer 响应头;?layer=standard 取底版
- PUT/DELETE /api/page/schema/{id}/overlay(管理员 403,etag=sha256,base_etag 记基版)
- 6.2 已拍板架构的机制载体:升级标准层整体替换,客户定制(overlay)保留

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-06-12 04:23:43 +08:00
parent 964921574b
commit e3ffc18251
4 changed files with 524 additions and 42 deletions

View File

@@ -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 实体建模器一并设计;
- 设计器仅管理员可达,未细分设计权限角色。

View File

@@ -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」提示对比)';