From 976b48a09d6fa6f296e33896f6a483e8ae48dca2 Mon Sep 17 00:00:00 2001 From: wgm Date: Fri, 17 Jul 2026 15:15:39 +0800 Subject: [PATCH] docs: translate README and generalize LAN URLs --- README.md | 143 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 98 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index dd8d81a..84ac0c3 100644 --- a/README.md +++ b/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 npm install npm run dev ``` -- Editor: http://localhost:5173 -- Published H5: http://localhost:5174/?id=demo-store -- API: http://localhost:3000 +启动后可访问： -### LAN access +- Web 编辑器： +- 已发布 H5： +- API 服务： -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` -- Published H5: `http://192.168.7.6:5174/?id=demo-store` -- API: `http://192.168.7.6:3000` +开发服务默认监听所有网络接口。正常运行 `npm run dev` 后，将地址中的 `localhost` 替换为当前电脑的局域网 IP： -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 +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 ``` -`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. -- `直充 / 卡密`: provides benefit product cards, redemption actions, redemption notices and benefit product lists. -- `添加业务示例组合`: inserts one of each digital-benefit component as an editable starter page. +- 横幅 Banner +- 标题 +- 文本 +- 图片 +- 按钮 +- 商品列表 +- 分割线 +- 间距 +- 双列容器 -## 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. -- 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. -- 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. +- Banner：标题、副标题、多图片、图片说明、轮播开关、循环播放、自动播放间隔、高度、遮罩、对齐和文字颜色。 +- 标题：文字、字号、字重、对齐、内边距和颜色。 +- 文本：多行内容、字号、行高、对齐、内边距、文字和背景颜色。 +- 图片：图片地址、无障碍说明、高度、裁切方式和圆角。 +- 按钮：文字、尺寸、圆角、颜色和安全链接交互。 +- 商品列表：商品增删、名称、价格、图片、列数、间距、图片高度和颜色。 +- 分割线：粗细、间距、线型和颜色。 +- 间距：高度和背景颜色。 +- 双列容器：左右栏独立内容、间距、高度、内边距、对齐和背景颜色。 +- 权益商品卡片：直充/卡密方式、名称、说明、价格、图片、标签、VIP 标识、按钮文案和品牌色。 +- 兑换操作区：主次按钮文案、显隐、圆角和颜色。 +- 兑换说明：栏目标签、标题、多行说明和强调样式。 +- 权益商品列表：权益增删、交付方式、名称、价格、数量显示和卡片样式。 -## Demo boundaries +## 工程结构 -- JSON persistence is single-process and intended for local demonstration, not concurrent production writes. -- Authentication, tenancy, asset upload/CDN conversion, collaborative editing, and database migrations are outside this Demo. -- Images use fixed dimensions and native lazy loading; a production image pipeline should generate WebP/AVIF variants. +- `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 图片处理链路。