From 6d991326a59780348d23f6d0af8226b8d7234deb Mon Sep 17 00:00:00 2001 From: skycurtain Date: Tue, 14 Apr 2026 14:20:46 +0800 Subject: [PATCH] =?UTF-8?q?refactor:=20=E7=AE=80=E5=8C=96schema=E7=BB=93?= =?UTF-8?q?=E6=9E=84=EF=BC=8C=E6=9B=B4=E6=96=B0AGENTS.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 56 +++++++++++++++++-- .../application/application.ts | 0 .../{design-mode => }/application/index.ts | 0 .../component/component-data.ts | 0 .../component/component-layout.ts | 0 .../{design-mode => }/component/component.ts | 0 .../{design-mode => }/component/index.ts | 0 .../{design-mode => }/core/condition.ts | 0 .../{design-mode => }/core/css-properties.ts | 0 .../core/dynamic-expression.ts | 0 src/schema/{design-mode => }/core/entity.ts | 0 src/schema/{design-mode => }/core/index.ts | 0 .../{design-mode => }/core/json-value.ts | 0 .../{design-mode => }/core/rest-request.ts | 0 .../data-source/data-source-by-database.ts | 0 .../data-source/data-source-by-rest.ts | 0 .../data-source/data-source.ts | 0 .../{design-mode => }/data-source/index.ts | 0 src/schema/{design-mode => }/filter/filter.ts | 0 src/schema/{design-mode => }/filter/index.ts | 0 src/schema/{design-mode => }/index.ts | 0 .../{design-mode => }/interaction/action.ts | 0 .../{design-mode => }/interaction/index.ts | 0 .../interaction/interaction.ts | 0 .../{design-mode => }/mutation/index.ts | 0 .../mutation/mutation-config.ts | 0 .../{design-mode => }/mutation/mutation.ts | 0 src/schema/{design-mode => }/page/index.ts | 0 .../{design-mode => }/page/page-layout.ts | 0 src/schema/{design-mode => }/page/page.ts | 0 src/schema/{design-mode => }/query/index.ts | 0 .../{design-mode => }/query/query-config.ts | 0 src/schema/{design-mode => }/query/query.ts | 0 src/schema/{design-mode => }/route/index.ts | 0 src/schema/{design-mode => }/route/route.ts | 0 .../{design-mode => }/variable/index.ts | 0 .../{design-mode => }/variable/variable.ts | 0 37 files changed, 51 insertions(+), 5 deletions(-) rename src/schema/{design-mode => }/application/application.ts (100%) rename src/schema/{design-mode => }/application/index.ts (100%) rename src/schema/{design-mode => }/component/component-data.ts (100%) rename src/schema/{design-mode => }/component/component-layout.ts (100%) rename src/schema/{design-mode => }/component/component.ts (100%) rename src/schema/{design-mode => }/component/index.ts (100%) rename src/schema/{design-mode => }/core/condition.ts (100%) rename src/schema/{design-mode => }/core/css-properties.ts (100%) rename src/schema/{design-mode => }/core/dynamic-expression.ts (100%) rename src/schema/{design-mode => }/core/entity.ts (100%) rename src/schema/{design-mode => }/core/index.ts (100%) rename src/schema/{design-mode => }/core/json-value.ts (100%) rename src/schema/{design-mode => }/core/rest-request.ts (100%) rename src/schema/{design-mode => }/data-source/data-source-by-database.ts (100%) rename src/schema/{design-mode => }/data-source/data-source-by-rest.ts (100%) rename src/schema/{design-mode => }/data-source/data-source.ts (100%) rename src/schema/{design-mode => }/data-source/index.ts (100%) rename src/schema/{design-mode => }/filter/filter.ts (100%) rename src/schema/{design-mode => }/filter/index.ts (100%) rename src/schema/{design-mode => }/index.ts (100%) rename src/schema/{design-mode => }/interaction/action.ts (100%) rename src/schema/{design-mode => }/interaction/index.ts (100%) rename src/schema/{design-mode => }/interaction/interaction.ts (100%) rename src/schema/{design-mode => }/mutation/index.ts (100%) rename src/schema/{design-mode => }/mutation/mutation-config.ts (100%) rename src/schema/{design-mode => }/mutation/mutation.ts (100%) rename src/schema/{design-mode => }/page/index.ts (100%) rename src/schema/{design-mode => }/page/page-layout.ts (100%) rename src/schema/{design-mode => }/page/page.ts (100%) rename src/schema/{design-mode => }/query/index.ts (100%) rename src/schema/{design-mode => }/query/query-config.ts (100%) rename src/schema/{design-mode => }/query/query.ts (100%) rename src/schema/{design-mode => }/route/index.ts (100%) rename src/schema/{design-mode => }/route/route.ts (100%) rename src/schema/{design-mode => }/variable/index.ts (100%) rename src/schema/{design-mode => }/variable/variable.ts (100%) diff --git a/AGENTS.md b/AGENTS.md index 0214117..cc560b7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,15 +2,61 @@ ## 项目介绍 -本项目的实现目标是设计一个尽可能通用的低代码设计器平台的核心数据结构，该平台能够支持以拖拽和配置组件、路由、状态、事件、过滤器、页面等元素，以可视化的交互方式搭建业务应用、数字大屏等系统。 +本项目的实现目标是设计一个尽可能通用的低代码设计器平台的核心数据结构，该平台能够支持以拖拽和配置组件、路由、状态、事件、过滤器、页面等实体元素，以可视化的交互方式搭建数字大屏、中后台系统以及产品官网等多类应用。 -所谓“核心数据结构”，主要是在平台中设计应用或大屏系统时，设计器需要持有的各类配置信息，大致可以分为设计时配置和运行时配置。 +其中，当前阶段的首要目标场景是**数字大屏**。围绕该场景，平台的核心 `Schema` 结构已经进行了更深入的分析、约束与推演；而对于中后台系统与产品官网场景，现阶段主要完成的是字段层面的前瞻性预留，以保证整体结构具备后续扩展空间，但尚未进行同等深度的专项分析与完备性验证。 -设计时配置指用户在设计器中拖拽、配置组件、路由、状态、事件、过滤器、页面等元素时，设计器需要保存的配置信息。 +所谓“核心数据结构”，主要是在平台中设计应用或大屏系统时所依赖的一套统一配置蓝图。 -运行时配置指用户在设计器中完成应用或大屏系统的设计后，需要在运行时加载的配置信息。 +这套蓝图既需要能够描述设计时配置，也需要能够描述运行时配置，其中： -现阶段的实现目标即是构造能够描述上述设计时配置和运行时配置的核心数据结构。 +- 设计时配置，指用户在设计器中拖拽、配置组件、路由、状态、事件、过滤器、页面等元素时，需要被持久化保存的配置信息。 +- 运行时配置，指用户完成设计后，在最终应用运行时需要被加载和消费的配置信息。 + +在本项目中，`Schema` 的角色应被明确定位为：**整个应用配置的持久化表现形式与统一交换格式**。 + +用户保存到数据库的是这份 `Schema`，导出到本地的是这份 `Schema`，从外部导入到平台中的也是这份 `Schema`。但平台在运行过程中，**不会直接以 `Schema` 作为工作内存来驱动各项能力**。相反，平台会在导入 `Schema` 后，将其解析、校验、规范化，并拆分到与各引擎职责对应的内部状态 `Store` 中；而在保存、导出或发布时，再将各引擎 `Store` 中的稳定数据重新聚合为 `Schema`，用于持久化或输出。 + +因此可以认为： + +- `Schema` 面向持久化、导入导出与跨边界交换； +- `Store` 面向平台运行时、引擎协作与高频状态操作。 + +此外，平台在整体运行语义上需要明确区分 `设计态（Design Mode）`、`预览态（Preview Mode）` 与 `运行态（Runtime Mode）` 三种模式。三态的切换应被视为平台的**运行时上下文（AppMode）** 差异，而不是 `Schema` 本身的结构差异。换言之，`AppMode` 不属于需要持久化存储的 `Schema` 蓝图，而应由外部宿主容器或平台运行时环境显式注入。 + +其中： + +- `设计态` 用于可视化编辑、拖拽编排与配置应用结构； +- `运行态` 用于面向最终用户提供纯净、完整的应用运行体验； +- `预览态` 则用于在不进入正式运行环境的前提下，以尽可能接近真实运行态的方式对应用进行预览、验证与调试。 + +`预览态` 既不同于可任意编辑配置的 `设计态`，也不同于面向最终用户的纯净 `运行态`，而是一种介于两者之间的**受控运行模式**。在该模式下，平台应尽可能复用与 `运行态` 相同的 `Schema` 渲染主链路，放行业务交互、数据请求、事件流转与页面跳转，使用户或实施人员能够提前验证应用在真实运行中的行为表现。 + +同时，`预览态` 还应具备必要的白盒调试与观测能力，用于辅助定位应用配置中的问题，例如： + +- 数据请求的发起、成功、失败与错误信息； +- 过滤器接收的输入参数是否正确，以及过滤结果是否异常； +- 事件流的触发顺序、条件命中情况、动作执行过程与中断原因； +- 表达式求值、生命周期触发、关键动作执行等运行日志； +- 将错误、警告与日志尽可能关联到具体的组件、事件、过滤器、数据源或动作节点。 + +因此，`预览态` 需要被纳入平台整体架构设计中，但其影响应主要体现在运行时上下文、引擎挂载策略、错误处理策略以及内部 `Store` 的组织方式上，而不应膨胀为一套独立的 `Schema` 结构维度。 + +`Schema` 仍只负责承载跨模式稳定且需要被持久化的应用配置，而模式切换过程中产生的会话状态、派生状态、调试状态、缓存状态与临时控制状态，应由运行时 `Store` 负责管理。 + +在完成核心 `Schema` 结构设计的里程碑阶段后，项目下一阶段的重点将转向整个平台的技术路线与实现方案设计。 + +这意味着，后续工作不再仅仅聚焦于“应用配置如何被描述”，而是要进一步回答：平台应如何基于既定 `Schema` 组织内部状态 `Store`、构建运行时上下文、拆分核心模块，并驱动各个引擎协同工作。 + +其中，一个关键目标是逐步明确并落地平台的五大核心引擎，包括： + +- 工作区引擎 +- 画布引擎 +- 渲染引擎 +- 数据引擎 +- 交互引擎 + +现阶段的实现目标，是在既定 `Schema` 蓝图的基础上，进一步规划整个平台的技术架构、状态模型与引擎协作机制，为后续设计器与运行时系统的工程化实现提供稳定依据。 在技术栈方面，本项目希望积极拥抱 `React` + `Vite` 的最新生态体系，包括但不限于 `React`、`React Router` 或 `Tanstack Router`、`Tanstack Query`、`Zustand` 等。 diff --git a/src/schema/design-mode/application/application.ts b/src/schema/application/application.ts similarity index 100% rename from src/schema/design-mode/application/application.ts rename to src/schema/application/application.ts diff --git a/src/schema/design-mode/application/index.ts b/src/schema/application/index.ts similarity index 100% rename from src/schema/design-mode/application/index.ts rename to src/schema/application/index.ts diff --git a/src/schema/design-mode/component/component-data.ts b/src/schema/component/component-data.ts similarity index 100% rename from src/schema/design-mode/component/component-data.ts rename to src/schema/component/component-data.ts diff --git a/src/schema/design-mode/component/component-layout.ts b/src/schema/component/component-layout.ts similarity index 100% rename from src/schema/design-mode/component/component-layout.ts rename to src/schema/component/component-layout.ts diff --git a/src/schema/design-mode/component/component.ts b/src/schema/component/component.ts similarity index 100% rename from src/schema/design-mode/component/component.ts rename to src/schema/component/component.ts diff --git a/src/schema/design-mode/component/index.ts b/src/schema/component/index.ts similarity index 100% rename from src/schema/design-mode/component/index.ts rename to src/schema/component/index.ts diff --git a/src/schema/design-mode/core/condition.ts b/src/schema/core/condition.ts similarity index 100% rename from src/schema/design-mode/core/condition.ts rename to src/schema/core/condition.ts diff --git a/src/schema/design-mode/core/css-properties.ts b/src/schema/core/css-properties.ts similarity index 100% rename from src/schema/design-mode/core/css-properties.ts rename to src/schema/core/css-properties.ts diff --git a/src/schema/design-mode/core/dynamic-expression.ts b/src/schema/core/dynamic-expression.ts similarity index 100% rename from src/schema/design-mode/core/dynamic-expression.ts rename to src/schema/core/dynamic-expression.ts diff --git a/src/schema/design-mode/core/entity.ts b/src/schema/core/entity.ts similarity index 100% rename from src/schema/design-mode/core/entity.ts rename to src/schema/core/entity.ts diff --git a/src/schema/design-mode/core/index.ts b/src/schema/core/index.ts similarity index 100% rename from src/schema/design-mode/core/index.ts rename to src/schema/core/index.ts diff --git a/src/schema/design-mode/core/json-value.ts b/src/schema/core/json-value.ts similarity index 100% rename from src/schema/design-mode/core/json-value.ts rename to src/schema/core/json-value.ts diff --git a/src/schema/design-mode/core/rest-request.ts b/src/schema/core/rest-request.ts similarity index 100% rename from src/schema/design-mode/core/rest-request.ts rename to src/schema/core/rest-request.ts diff --git a/src/schema/design-mode/data-source/data-source-by-database.ts b/src/schema/data-source/data-source-by-database.ts similarity index 100% rename from src/schema/design-mode/data-source/data-source-by-database.ts rename to src/schema/data-source/data-source-by-database.ts diff --git a/src/schema/design-mode/data-source/data-source-by-rest.ts b/src/schema/data-source/data-source-by-rest.ts similarity index 100% rename from src/schema/design-mode/data-source/data-source-by-rest.ts rename to src/schema/data-source/data-source-by-rest.ts diff --git a/src/schema/design-mode/data-source/data-source.ts b/src/schema/data-source/data-source.ts similarity index 100% rename from src/schema/design-mode/data-source/data-source.ts rename to src/schema/data-source/data-source.ts diff --git a/src/schema/design-mode/data-source/index.ts b/src/schema/data-source/index.ts similarity index 100% rename from src/schema/design-mode/data-source/index.ts rename to src/schema/data-source/index.ts diff --git a/src/schema/design-mode/filter/filter.ts b/src/schema/filter/filter.ts similarity index 100% rename from src/schema/design-mode/filter/filter.ts rename to src/schema/filter/filter.ts diff --git a/src/schema/design-mode/filter/index.ts b/src/schema/filter/index.ts similarity index 100% rename from src/schema/design-mode/filter/index.ts rename to src/schema/filter/index.ts diff --git a/src/schema/design-mode/index.ts b/src/schema/index.ts similarity index 100% rename from src/schema/design-mode/index.ts rename to src/schema/index.ts diff --git a/src/schema/design-mode/interaction/action.ts b/src/schema/interaction/action.ts similarity index 100% rename from src/schema/design-mode/interaction/action.ts rename to src/schema/interaction/action.ts diff --git a/src/schema/design-mode/interaction/index.ts b/src/schema/interaction/index.ts similarity index 100% rename from src/schema/design-mode/interaction/index.ts rename to src/schema/interaction/index.ts diff --git a/src/schema/design-mode/interaction/interaction.ts b/src/schema/interaction/interaction.ts similarity index 100% rename from src/schema/design-mode/interaction/interaction.ts rename to src/schema/interaction/interaction.ts diff --git a/src/schema/design-mode/mutation/index.ts b/src/schema/mutation/index.ts similarity index 100% rename from src/schema/design-mode/mutation/index.ts rename to src/schema/mutation/index.ts diff --git a/src/schema/design-mode/mutation/mutation-config.ts b/src/schema/mutation/mutation-config.ts similarity index 100% rename from src/schema/design-mode/mutation/mutation-config.ts rename to src/schema/mutation/mutation-config.ts diff --git a/src/schema/design-mode/mutation/mutation.ts b/src/schema/mutation/mutation.ts similarity index 100% rename from src/schema/design-mode/mutation/mutation.ts rename to src/schema/mutation/mutation.ts diff --git a/src/schema/design-mode/page/index.ts b/src/schema/page/index.ts similarity index 100% rename from src/schema/design-mode/page/index.ts rename to src/schema/page/index.ts diff --git a/src/schema/design-mode/page/page-layout.ts b/src/schema/page/page-layout.ts similarity index 100% rename from src/schema/design-mode/page/page-layout.ts rename to src/schema/page/page-layout.ts diff --git a/src/schema/design-mode/page/page.ts b/src/schema/page/page.ts similarity index 100% rename from src/schema/design-mode/page/page.ts rename to src/schema/page/page.ts diff --git a/src/schema/design-mode/query/index.ts b/src/schema/query/index.ts similarity index 100% rename from src/schema/design-mode/query/index.ts rename to src/schema/query/index.ts diff --git a/src/schema/design-mode/query/query-config.ts b/src/schema/query/query-config.ts similarity index 100% rename from src/schema/design-mode/query/query-config.ts rename to src/schema/query/query-config.ts diff --git a/src/schema/design-mode/query/query.ts b/src/schema/query/query.ts similarity index 100% rename from src/schema/design-mode/query/query.ts rename to src/schema/query/query.ts diff --git a/src/schema/design-mode/route/index.ts b/src/schema/route/index.ts similarity index 100% rename from src/schema/design-mode/route/index.ts rename to src/schema/route/index.ts diff --git a/src/schema/design-mode/route/route.ts b/src/schema/route/route.ts similarity index 100% rename from src/schema/design-mode/route/route.ts rename to src/schema/route/route.ts diff --git a/src/schema/design-mode/variable/index.ts b/src/schema/variable/index.ts similarity index 100% rename from src/schema/design-mode/variable/index.ts rename to src/schema/variable/index.ts diff --git a/src/schema/design-mode/variable/variable.ts b/src/schema/variable/variable.ts similarity index 100% rename from src/schema/design-mode/variable/variable.ts rename to src/schema/variable/variable.ts