====== NOP Chaos Flux：可逆计算的前端运行时 ======

NOP Chaos Flux 是 Nop 平台的前端运行时和渲染框架，项目地址 [[https://github.com/entropy-cloud/nop-chaos-flux|nop-chaos-flux]]。它与后端 nop-entropy 共享同一种设计哲学：**可逆计算的差量定制**，但从前端的角度重新实现。

Flux 用一句口号概括自己：**"Schema that executes, not just renders"**——它不只是在渲染 JSON 描述的页面，而是在执行一个结构化模型。

===== Flux 与 AMIS 的关系 =====

Nop 前端此前基于 [[https://baidu.github.io/amis/|百度 AMIS]] 框架（nop-chaos-next）。Flux 在此基础上进一步演化：

^ 对比维度 ^ NOP Chaos Next ^ NOP Chaos Flux ^
| 定位 | 企业应用框架 | 低代码运行时与渲染框架 |
| 渲染层 | 基于 AMIS（React 19） | 自定义渲染架构 |
| 状态管理 | Zustand + React Query | 框架无关的 Zustand store |
| 核心能力 | 插件系统 + 扩展体系 | 七个原语构建的运行时 |
| 设计器 | 集成第三方 | 内建 Flow/Report/电子表格设计器 |
| 适用场景 | 业务团队构建应用 | 平台团队构建低代码基础设施 |

简单说：**Flux 是 "How to generate UI from JSON"**，Next 是 "How to build extensible business applications"。Future 可以集成 Flux 的设计器和运行时能力。

===== 七个原语 =====

Flux 的核心很小——只有七个原语。表单、表格、对话框、设计器都在这些原语之上构建：

| 原语 | 职责 |
|------|------|
| Template | 编译后的程序结构、区域组合、生命周期锚点 |
| ScopeRef | 词法作用域数据环境 |
| Value | 字面量、表达式、模板、数组、对象的执行模型 |
| Resource | 运行时持有的值生产者（如数据加载） |
| Reaction | 声明式 watch/effect 原语 |
| Capability | 副作用唯一的授权通道 |
| Host Projection | 宿主状态的只读投影，注入 schema 可见的作用域 |

===== 架构分层 =====

Flux 的包结构遵循清晰的分层架构：

<code>
flux-core           → 原语契约、共享类型、纯工具函数
flux-formula        → 表达式和模板编译
flux-compiler       → Schema 编译、标准化、诊断
flux-action-core    → Action 降级、选择器分类、控制流执行
flux-runtime        → 作用域、Action、校验、页面和表单运行时
flux-react          → React 桥接（hooks、渲染句柄）
  ↓
renderers           → 页面、布局、表单、数据渲染器
designers           → 流程设计器、报表设计器、电子表格、文字编辑器
</code>

这种分层的目的是：**可逆计算的编译期概念在前端找到对应**。表达式在运行时之前编译，值语义统一，作用域词法明确。

===== 30 秒示例 =====

一个简单的表单定义：

<code json>
{
  "type": "form",
  "data": {
    "name": "Alice"
  },
  "body": [
    {
      "type": "text",
      "text": "Hello ${name || 'Anonymous'}"
    },
    {
      "type": "input-text",
      "name": "name",
      "label": "Name",
      "required": true,
      "minLength": 3
    }
  ],
  "actions": [
    {
      "type": "button",
      "label": "Save",
      "onClick": {
        "action": "submitForm"
      }
    }
  ]
}
</code>

Flux 的处理流程：

  1. **编译期** — 分析 JSON，标记哪些值是表达式（${}）、哪些是字面量、哪些是模板
  2. **运行期** — 实例化 ScopeRef，建立词法作用域
  3. **渲染期** — React 根据编译结果渲染对应组件
  4. **交互期** — 表单校验、数据绑定、Action 路由

===== Flow Designer 设计器 =====

Flux 内建了一个流程设计器工作台，包含：

  * 节点面板（拖拽添加）
  * 画布编辑（连线、布局）
  * 属性面板（选中节点后编辑参数）
  * 工具栏（缩放、撤销、重做）

这是可逆计算思维在前端的体现——流程定义本身是一个结构化 DSL，可以在设计器中以可视化方式编辑，然后序列化为 JSON 存储，后端可以对该 JSON 施加 Delta 定制。

===== 与前端的 Delta 定制 =====

Flux 的 JSON Schema 设计天然支持差量合并：

  * 基础页面定义由后端自动生成
  * 定制层通过 Delta 机制覆盖或扩展基础定义
  * 合并后的 JSON 送入 Flux 编译执行

这意味着前后端共享同一种定制哲学——不修改基础产物，通过叠加差量层实现定制。

===== 项目状态 =====

  * 开发语言：TypeScript
  * 构建工具：Vite + pnpm monorepo
  * 测试框架：Vitest + Playwright
  * UI 框架：React 19 + TailwindCSS 4
  * 许可证：MIT
  * 当前入口：apps/playground（本地运行 pnpm dev 后访问 :5173）

===== 快速体验 =====

<code bash>
git clone https://github.com/entropy-cloud/nop-chaos-flux.git
cd nop-chaos-flux
pnpm install
pnpm dev
</code>

浏览器打开 http://localhost:5173 后，推荐从以下场景入手：

  * **Flux Basic** — 表单、校验、数据绑定
  * **Flow Designer** — 流程设计器工作台
  * **Debugger Lab** — 诊断工具、事件追踪

===== 进一步阅读 =====

  * [[.:frontend_guide|Nop 平台前端架构]]
  * [[https://github.com/entropy-cloud/nop-chaos-flux/tree/master/docs|Flux 文档索引]]
  * [[https://github.com/entropy-cloud/nop-chaos-flux/blob/master/docs/articles/flux-design-introduction.md|Flux 设计介绍]]