@gct-paas/render 0.1.6-dev.8 → 6.0.0-dev.1

package/README.md

@@ -1 +1,175 @@
+# @gct-paas/render
 
+PaaS 平台**渲染引擎**底包。负责将设计 schema 渲染为运行时页面：设计渲染 controller/state、Event 引擎、表达式、搜索 hooks、RenderNode 注册。挂载 `_gct.register.render` 与 `window._kit`。
+
+> 本文档面向后续开发与 AI 模型阅读：说明渲染注册机制及与 render-web 的分工。
+
+## 包信息
+
+| 项 | 值 |
+| --- | --- |
+| 包名 | `@gct-paas/render` |
+| 入口 | `es/index.mjs`（类型：`es/index.d.ts`） |
+| 全局类型 | `@gct-paas/render/types` |
+| peer | `@gct-paas/api`、`core`、`core-web`、`schema`、`scss`、`vue>=3` |
+
+```ts
+import { renderSetupApp, RenderRegister, RenderNodeRegister } from '@gct-paas/render';
+// 引入即 onInit() → register.render + window._kit
+```
+
+---
+
+## 在 monorepo 中的位置
+
+```
+core → core-web → render（渲染引擎）
+                      └── render-web（Web 渲染产品层）
+```
+
+规划中：`render-mobile` / `render-pad` 为端侧对等层（仓库暂未包含）。
+
+---
+
+## 依赖说明
+
+### 关键 workspace 依赖
+
+| 包 | 用途 |
+| --- | --- |
+| `@gct-paas/core` | `_gct`、PluginPgkUtil、工具 |
+| `@gct-paas/core-web` | 运行时 UI、表单渲染基础 |
+| `@gct-paas/schema` | 渲染 schema 类型 |
+
+### 主要工具依赖
+
+| 依赖 | 用途 |
+| --- | --- |
+| `esprima-next` + `escodegen` | 表达式 AST |
+| `vue3-dnd` | 运行时拖拽 |
+| `bignumber.js` | 数值计算 |
+| `axios` / `qs` | 渲染期请求 |
+
+---
+
+## 源码结构
+
+```
+packages/render/src/
+├── index.ts              # onInit → register.render + _kit
+├── setup-app.ts          # renderSetupApp（locale）
+├── register/             # RenderRegister、RenderNodeRegister
+├── components/           # design-render、design-render-item
+├── controller/           # 渲染 controller 层级
+├── state/                # Pinia/状态：design-render*
+├── Event/                # 页面事件引擎、依赖规则、bizService
+├── providers/            # 节点 provider 扩展
+├── hooks/                # useDesignRenderController 等
+├── utils/                # 表达式、搜索、插件包、field-attrs
+├── modules/vue3-dnd/     # 运行时 DND
+└── constant/             # 数据格式、日期等
+```
+
+---
+
+## 与 `_gct` 的关系
+
+**引入时自动挂载（防重复）：**
+
+```ts
+_gct.register.render = new RenderRegister();
+
+// 插件/套件扩展容器（只读空对象，由各 kit 写入）
+Object.defineProperty(window, '_kit', {
+  value: {},
+  writable: false,
+  configurable: false,
+});
+```
+
+| 全局 | 说明 |
+| --- | --- |
+| `_gct.register.render` | 渲染器总注册（视图、插件等） |
+| `window._kit` | 套件/插件挂载点，供扩展包注册能力 |
+
+运行时还依赖 core-web 的 `_gct.message`、mqtt、store、router 等。
+
+---
+
+## 启动与用法
+
+```ts
+import { setupApp, createAppVue } from '@gct-paas/core';
+import { coreWebSetupApp, coreWebCreateAppVue } from '@gct-paas/core-web';
+import { renderSetupApp } from '@gct-paas/render';
+
+const app = createApp(Root);
+
+await setupApp(app);
+await coreWebSetupApp(app);
+await renderSetupApp(app);     // 注册 render locale
+
+createAppVue(app);
+coreWebCreateAppVue(app);
+
+app.mount('#app');
+```
+
+扩展渲染节点：
+
+```ts
+import {
+  RenderNodeRegister,
+  RenderNodeType,
+  DesignRenderViewPrefix,
+} from '@gct-paas/render';
+
+RenderNodeRegister.register(
+  RenderNodeType.FIELD,
+  () => new MyFieldProvider(),
+  DesignRenderViewPrefix.CARD_VIEW,
+);
+```
+
+（Web 端 card-view 注册见 `@gct-paas/render-web` 的 `renderWebSetupApp`。）
+
+---
+
+## 主要导出速查
+
+| 类别 | 示例 |
+| --- | --- |
+| 启动 | `renderSetupApp`、`onInit` |
+| 注册 | `RenderRegister`、`RenderNodeRegister`、`RenderNodeType` |
+| 渲染 | `design-render` 组件、controller/state |
+| Event | `baseEvent`、Dependency、页面事件 utils |
+| 工具 | 表达式、search hooks、`render-plugin-pkg-util` |
+| 常量 | `DesignRenderViewPrefix`、`data-format` |
+
+---
+
+## 与 `@gct-paas/render-web` 的分工
+
+| 层 | 职责 |
+| --- | --- |
+| **render** | 跨端渲染引擎：controller、Event、register.render、_kit |
+| **render-web** | Web 产品实现：BasicPage、card-view 插件、页面事件、app-mqtt |
+
+---
+
+## 给后续模型的约束
+
+1. 新增渲染 provider → `RenderNodeRegister` + provider 类，类型对齐 schema。
+2. 套件扩展写入 `window._kit`，不要替换整个 `_kit` 对象。
+3. 页面事件/表达式逻辑放 `Event/`，避免在 render-web 重复实现引擎逻辑。
+4. 重复引入 render 包会警告 `register.render` 已存在。
+
+---
+
+## 本地命令
+
+```bash
+cd packages/render
+npm run dev
+npm run build        # lint + vue-tsc + 双 Vite 构建
+```