docs: translate README and generalize LAN URLs
This commit is contained in:
wgm
parent
3935948eba
commit
976b48a09d
143
README.md
143
README.md
|
|
@ -1,74 +1,127 @@
|
||||||
# Mosaic Low-code H5 Demo
|
# Mosaic 低代码 H5 Demo
|
||||||
|
|
||||||
## Run
|
一个可运行的低代码 H5 模板示例，包含 Web 编辑器、独立 H5 Renderer、轻量 API、JSON 持久化、不可变发布版本以及端到端测试。
|
||||||
|
|
||||||
|
## 启动项目
|
||||||
|
|
||||||
|
环境要求：Node.js 20 或更高版本。
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm install
|
npm install
|
||||||
npm run dev
|
npm run dev
|
||||||
```
|
```
|
||||||
|
|
||||||
- Editor: http://localhost:5173
|
启动后可访问：
|
||||||
- Published H5: http://localhost:5174/?id=demo-store
|
|
||||||
- API: http://localhost:3000
|
|
||||||
|
|
||||||
### LAN access
|
- Web 编辑器：<http://localhost:5173>
|
||||||
|
- 已发布 H5：<http://localhost:5174/?id=demo-store>
|
||||||
|
- API 服务：<http://localhost:3000>
|
||||||
|
|
||||||
The development services listen on all network interfaces. Start them normally with `npm run dev`, then replace `localhost` with the computer's LAN IP, for example:
|
## 局域网访问
|
||||||
|
|
||||||
- Editor: `http://192.168.7.6:5173`
|
开发服务默认监听所有网络接口。正常运行 `npm run dev` 后，将地址中的 `localhost` 替换为当前电脑的局域网 IP：
|
||||||
- Published H5: `http://192.168.7.6:5174/?id=demo-store`
|
|
||||||
- API: `http://192.168.7.6:3000`
|
|
||||||
|
|
||||||
The editor, iframe preview and H5 API automatically follow the hostname used in the browser. Devices must be on the same local network, and the operating-system firewall must allow Node.js connections.
|
- Web 编辑器：`http://<本机局域网IP>:5173`
|
||||||
|
- 已发布 H5：`http://<本机局域网IP>:5174/?id=demo-store`
|
||||||
|
- API 服务：`http://<本机局域网IP>:3000`
|
||||||
|
|
||||||
## Verify
|
macOS 可使用以下命令查看 Wi-Fi 局域网 IP：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
ipconfig getifaddr en0
|
||||||
|
```
|
||||||
|
|
||||||
|
编辑器、iframe 预览和 H5 API 会自动跟随浏览器当前访问的主机名。访问设备需要与电脑处于同一局域网，并允许 Node.js 通过系统防火墙。
|
||||||
|
|
||||||
|
## 常用命令
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 同时启动 API、编辑器和 H5
|
||||||
|
npm run dev
|
||||||
|
|
||||||
|
# ESLint、TypeScript、Prettier 和构建检查
|
||||||
|
npm run check
|
||||||
|
|
||||||
|
# 构建全部工作区
|
||||||
npm run build
|
npm run build
|
||||||
|
|
||||||
|
# 检查独立 H5 产物不包含编辑器或拖拽依赖
|
||||||
npm run check:h5
|
npm run check:h5
|
||||||
|
|
||||||
|
# 运行 Playwright 端到端测试
|
||||||
npm run test:e2e
|
npm run test:e2e
|
||||||
```
|
```
|
||||||
|
|
||||||
`check:h5` builds the standalone H5 and rejects known editor/drag dependencies. The Playwright flow resets its own draft, drags in a component, publishes it, confirms draft changes do not change mobile output, republishes, and confirms the mobile page updates.
|
## 组件库
|
||||||
|
|
||||||
## Material libraries
|
编辑器顶部可以切换左侧物料面板。切换组件库不会删除画布中已有的区块，因此两套组件也可以在同一个 Schema 中混合使用。
|
||||||
|
|
||||||
Use the segmented switch in the editor header to change the left material palette. Switching libraries never removes blocks already on the page, so marketing and digital-benefit components can also be mixed in one Schema.
|
### 营销组件
|
||||||
|
|
||||||
- `营销组件`: keeps the original Banner, content, image, button, product-list and layout materials.
|
- 横幅 Banner
|
||||||
- `直充 / 卡密`: provides benefit product cards, redemption actions, redemption notices and benefit product lists.
|
- 标题
|
||||||
- `添加业务示例组合`: inserts one of each digital-benefit component as an editable starter page.
|
- 文本
|
||||||
|
- 图片
|
||||||
|
- 按钮
|
||||||
|
- 商品列表
|
||||||
|
- 分割线
|
||||||
|
- 间距
|
||||||
|
- 双列容器
|
||||||
|
|
||||||
## Architecture
|
### 直充 / 卡密组件
|
||||||
|
|
||||||
- `apps/editor`: Vue 3 editor with material and layer panels, iframe canvas, properties, history, draft and publication actions.
|
- 权益商品卡片
|
||||||
- `apps/h5`: standalone H5 entry that reads only the published endpoint and keeps a session Schema cache.
|
- 兑换操作区
|
||||||
- `apps/server`: Express API with JSON persistence, immutable publication snapshots and version lookup endpoints.
|
- 兑换说明
|
||||||
- `packages/page-schema`: Schema types, component whitelist and runtime helpers.
|
- 权益商品列表
|
||||||
- `packages/materials`: centrally registered material labels and defaults.
|
|
||||||
- `packages/renderer`: shared safe Renderer used by preview and mobile H5.
|
|
||||||
- `packages/shared`: shared preview message contract.
|
|
||||||
|
|
||||||
The Demo intentionally uses vertical flow layout and limited two-column composition. It does not execute Schema JavaScript, dynamic component paths, or arbitrary API definitions. Interactions accept only `http(s)` or site-relative links.
|
点击“添加业务示例组合”可以一次插入四种数字权益组件，快速生成可编辑的直充/卡密页面原型。
|
||||||
|
|
||||||
## Component editing
|
## 组件配置能力
|
||||||
|
|
||||||
- Banner: title, subtitle, multiple images and alt text, carousel toggle, looping, autoplay interval, height, overlay, alignment and text color.
|
- Banner：标题、副标题、多图片、图片说明、轮播开关、循环播放、自动播放间隔、高度、遮罩、对齐和文字颜色。
|
||||||
- Title: text, size, weight, alignment, padding and color.
|
- 标题：文字、字号、字重、对齐、内边距和颜色。
|
||||||
- Text: multiline content, size, line height, alignment, padding, foreground and background colors.
|
- 文本：多行内容、字号、行高、对齐、内边距、文字和背景颜色。
|
||||||
- Image: URL, alt text, height, crop mode and radius.
|
- 图片：图片地址、无障碍说明、高度、裁切方式和圆角。
|
||||||
- Button: text, sizing, radius, colors and safe link interaction.
|
- 按钮：文字、尺寸、圆角、颜色和安全链接交互。
|
||||||
- Product list: add/remove products, name, price, image, columns, gap, image height and colors.
|
- 商品列表：商品增删、名称、价格、图片、列数、间距、图片高度和颜色。
|
||||||
- Divider: thickness, spacing, line style and color.
|
- 分割线：粗细、间距、线型和颜色。
|
||||||
- Spacer: live height slider and background color.
|
- 间距：高度和背景颜色。
|
||||||
- Two-column: independent content, gap, height, padding, alignment and per-column backgrounds.
|
- 双列容器：左右栏独立内容、间距、高度、内边距、对齐和背景颜色。
|
||||||
- Benefit product card: direct-recharge/card-code mode, name, description, price, image, badge, VIP marker, action copy and brand colors.
|
- 权益商品卡片：直充/卡密方式、名称、说明、价格、图片、标签、VIP 标识、按钮文案和品牌色。
|
||||||
- Redemption actions: primary/secondary action copy, visibility, radius and colors.
|
- 兑换操作区：主次按钮文案、显隐、圆角和颜色。
|
||||||
- Redemption notice: section label, title, multiline instructions and accent styling.
|
- 兑换说明：栏目标签、标题、多行说明和强调样式。
|
||||||
- Benefit product list: add/remove benefits, delivery mode, name, price, count display and card styling.
|
- 权益商品列表：权益增删、交付方式、名称、价格、数量显示和卡片样式。
|
||||||
|
|
||||||
## Demo boundaries
|
## 工程结构
|
||||||
|
|
||||||
- JSON persistence is single-process and intended for local demonstration, not concurrent production writes.
|
- `apps/editor`：Vue 3 Web 编辑器，包含物料、图层、iframe 画布、属性面板、历史记录、草稿和发布操作。
|
||||||
- Authentication, tenancy, asset upload/CDN conversion, collaborative editing, and database migrations are outside this Demo.
|
- `apps/h5`：独立 H5 入口，只读取已发布 Schema，并提供会话级 Schema 缓存。
|
||||||
- Images use fixed dimensions and native lazy loading; a production image pipeline should generate WebP/AVIF variants.
|
- `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 图片处理链路。
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue