# Mosaic 低代码 H5 Demo

一个可运行的低代码 H5 模板示例，包含 Web 编辑器、独立 H5 Renderer、轻量 API、JSON 持久化、不可变发布版本以及端到端测试。

## 启动项目

环境要求：Node.js 20 或更高版本。

```bash
npm install
npm run dev
```

启动后可访问：

- Web 编辑器：<http://localhost:5173>
- 已发布 H5：<http://localhost:5174/?id=demo-store>
- API 服务：<http://localhost:3000>

## 局域网访问

开发服务默认监听所有网络接口。正常运行 `npm run dev` 后，将地址中的 `localhost` 替换为当前电脑的局域网 IP：

- Web 编辑器：`http://<本机局域网IP>:5173`
- 已发布 H5：`http://<本机局域网IP>:5174/?id=demo-store`
- API 服务：`http://<本机局域网IP>:3000`

macOS 可使用以下命令查看 Wi-Fi 局域网 IP：

```bash
ipconfig getifaddr en0
```

编辑器、iframe 预览和 H5 API 会自动跟随浏览器当前访问的主机名。访问设备需要与电脑处于同一局域网，并允许 Node.js 通过系统防火墙。

## 常用命令

```bash
# 同时启动 API、编辑器和 H5
npm run dev

# ESLint、TypeScript、Prettier 和构建检查
npm run check

# 构建全部工作区
npm run build

# 检查独立 H5 产物不包含编辑器或拖拽依赖
npm run check:h5

# 运行 Playwright 端到端测试
npm run test:e2e
```

## 组件库

编辑器顶部可以切换左侧物料面板。切换组件库不会删除画布中已有的区块，因此两套组件也可以在同一个 Schema 中混合使用。

### 营销组件

- 横幅 Banner
- 标题
- 文本
- 图片
- 按钮
- 商品列表
- 分割线
- 间距
- 双列容器

### 直充 / 卡密组件

- 权益商品卡片
- 兑换操作区
- 兑换说明
- 权益商品列表

点击“添加业务示例组合”可以一次插入四种数字权益组件，快速生成可编辑的直充/卡密页面原型。

## 组件配置能力

- Banner：标题、副标题、多图片、图片说明、轮播开关、循环播放、自动播放间隔、高度、遮罩、对齐和文字颜色。
- 标题：文字、字号、字重、对齐、内边距和颜色。
- 文本：多行内容、字号、行高、对齐、内边距、文字和背景颜色。
- 图片：图片地址、无障碍说明、高度、裁切方式和圆角。
- 按钮：文字、尺寸、圆角、颜色和安全链接交互。
- 商品列表：商品增删、名称、价格、图片、列数、间距、图片高度和颜色。
- 分割线：粗细、间距、线型和颜色。
- 间距：高度和背景颜色。
- 双列容器：左右栏独立内容、间距、高度、内边距、对齐和背景颜色。
- 权益商品卡片：直充/卡密方式、名称、说明、价格、图片、标签、VIP 标识、按钮文案和品牌色。
- 兑换操作区：主次按钮文案、显隐、圆角和颜色。
- 兑换说明：栏目标签、标题、多行说明和强调样式。
- 权益商品列表：权益增删、交付方式、名称、价格、数量显示和卡片样式。

## 工程结构

- `apps/editor`：Vue 3 Web 编辑器，包含物料、图层、iframe 画布、属性面板、历史记录、草稿和发布操作。
- `apps/h5`：独立 H5 入口，只读取已发布 Schema，并提供会话级 Schema 缓存。
- `apps/server`：Express API，使用 JSON 文件持久化草稿和不可变发布版本。
- `packages/page-schema`：Schema 类型、组件白名单和运行时校验工具。
- `packages/materials`：统一注册组件名称、默认值和组件库分组。
- `packages/renderer`：编辑器预览与移动端 H5 共用的安全 Renderer。
- `packages/shared`：共享的预览通信协议。

## 数据与发布流程

1. 编辑器从 API 获取草稿。
2. 编辑操作通过 iframe 实时发送给共用 Renderer。
3. “保存草稿”只更新草稿数据。
4. “发布”创建新的不可变版本，并返回成功版本号。
5. 移动端 H5 只读取已发布 Schema，草稿修改不会影响线上版本。
6. 再次发布后，移动端读取最新发布版本。

## 安全约束

- 使用纵向流式区块编排和有限容器嵌套，不支持整页任意绝对定位。
- Schema 不允许任意 JavaScript、`eval`、动态组件路径或任意 API 定义。
- 组件类型需要同时通过前端和服务端白名单校验。
- 交互只允许 `http://`、`https://` 或站内相对路径。
- H5 独立构建，不包含编辑器和拖拽依赖。

## Demo 边界

- JSON 持久化面向本地演示，不适用于生产环境的并发写入。
- 当前未包含登录鉴权、租户隔离、资源上传、CDN 转换、协同编辑和数据库迁移。
- 图片使用固定尺寸与浏览器原生懒加载；生产环境建议接入 WebP/AVIF 图片处理链路。