====== nop-chaos：前端架构 ======

nop-chaos 是 Nop 平台的 Vue3 前端项目，基于 AMIS 框架。后端项目为 nop-entropy（Java）。

前端采用**模型驱动**的架构：后端 Excel 模型直接映射为前端页面，定制通过 Delta 层完成。

===== 前端技术栈 =====

^ 技术 ^ 用途 ^
| Vue 3 | 基础框架 |
| AMIS | 默认页面渲染引擎（百度开源） |
| TypeScript | 开发语言 |
| Vite | 构建工具 |

AMIS 是一个**JSON 驱动的页面渲染框架**——页面结构用 JSON 描述，不需要手写 HTML 模板。这意味着 Nop 平台的后端可以直接生成 JSON 页面定义，前端只需渲染。

===== 页面自动生成 =====

从 Excel 模型到页面的流程：

<code>
Excel 数据模型
    │
    ├─→ orm.xml（实体定义）
    │      │
    │      └─→ xview.xml（页面模型）
    │             │
    │             └─→ JSON 页面定义 → AMIS 渲染
</code>

每个实体自动生成三个标准页面：

  * **列表页** — 分页表格，支持搜索、排序、批量操作
  * **编辑页** — 表单，支持新增和修改
  * **详情页** — 只读展示

这些页面的布局、字段顺序、校验规则全部从 xmeta 元数据推导，无需手写 HTML。

===== 定制页面 =====

和后端一样，前端页面也采用 Delta 定制机制。

自动生成的页面定义放在 `_gen/` 目录下。要定制页面，在 `src/` 目录下创建同名 JSON 文件：

<code>
src/
  main/
    resources/
      _v1/                          ← 定制层
        nop/
          auth/
            pages/
              NopAuthUser/
                NopAuthUser.view.xml  ← 覆盖自动生成的页面定义
</code>

在定制文件中，可以：

  * **调整表单布局** — 修改字段顺序、分组
  * **添加自定义组件** — 引入 AMIS 扩展组件
  * **替换整个页面** — 用 AMIS JSON 完全重写

===== 页面模型（xview.xml） =====

xview.xml 是页面的抽象描述，它不关心具体用哪个前端框架渲染。

<code xml>
<view>
  <form id="edit" title="编辑用户">
    <fields>
      <field name="userName" label="用户名" required="true" />
      <field name="email" label="邮箱" />
      <field name="status" label="状态"  />
    </fields>
  </form>
  <grid id="list" title="用户列表">
    <columns>
      <column name="userName" label="用户名" sortable="true" />
      <column name="email" label="邮箱" />
      <column name="status" label="状态" />
    </columns>
  </grid>
</view>
</code>

运行期，框架将 xview.xml 转换为 AMIS JSON 供浏览器渲染。如果将来到其他前端框架，只需替换转换器。

===== AMIS JSON 示例 =====

后端生成的最终 AMIS JSON 长这样：

<code json>
{
  "type": "page",
  "body": {
    "type": "form",
    "title": "编辑文章",
    "api": "/r/ArticleBizModel__save",
    "body": [
      {
        "type": "input-text",
        "name": "title",
        "label": "文章标题",
        "required": true
      },
      {
        "type": "input-text",
        "name": "author",
        "label": "作者"
      },
      {
        "type": "editor",
        "name": "content",
        "label": "内容"
      }
    ]
  }
}
</code>

AMIS 的 api 字段自动指向后端的 REST 端点 `/r/ArticleBizModel__save`，表单提交时自动调用。

===== 前端目录结构 =====

<code>
nop-chaos/
  packages/
    nop-core/          ← 核心运行时
    nop-amis-editor/   ← AMIS 可视化编辑器
    nop-web-site/      ← 主页面框架
  build/
    dist/              ← 构建产物，被 nop-web 模块打包为 Java jar
  src/
    pages/             ← 手工编写的页面
    components/        ← 自定义组件
</code>

前端的构建产物被包装为 Java 模块（nop-web-site、nop-web-amis-editor），在开发中不需要单独编译前端。

===== 自定义组件 =====

如果 AMIS 内置组件不够用，可以注册自定义 Vue3 组件：

<code typescript>
// 注册一个 AMIS 组件
import { registerAMISRenderer } from 'nop-core';

registerAMISRenderer({
  type: 'my-chart',
  component: {
    props: ['data'],
    template: '<div>自定义图表</div>'
  }
});
</code>

然后在 AMIS JSON 中直接使用：

<code json>
{
  "type": "my-chart",
  "data": "${chartData}"
}
</code>

===== 总结 =====

Nop 前端的特点：

  * **模型驱动** — 页面从 xview.xml 自动生成，不需要手写 HTML
  * **JSON 描述** — AMIS 引擎的 JSON 页面定义易于后端生成和 Delta 定制
  * **Delta 定制** — 与后端一致的定制机制，不修改基础页面
  * **框架无关** — xview.xml 抽象层使得未来可以切换到其他前端框架

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

  * [[https://gitee.com/canonical-entropy/nop-chaos|nop-chaos 前端项目]]
  * [[https://baidu.github.io/amis/|AMIS 官方文档]]
  * [[.:graphql_rest_guide|GraphQL 和 REST API]]