--- name: ui-design description: Microi UI 设计系统指南。用于设计 PC Vue、Element Plus、uni-app H5、仪表盘、表单、卡片、渐变、响应式布局、骨架屏、移动安全区和视觉打磨。 --- # Microi吾码设计规范 你正在为 Microi 吾码平台创建界面。所有页面、组件、弹窗必须遵循本规范，打造高级、克制、具有科技感和品牌识别度的视觉体验。 > **适用平台**：PC 端（Vue 3 + Element Plus + SCSS）、移动端 H5/uni-app/原生 WebView（纯 CSS / 无第三方组件库） > **核心理念**：高级但不浮夸，动效丰富但可维护，多端统一同时尊重平台差异 > **变量前缀**：所有 CSS 变量统一使用 `--mci-` 前缀（Microi Interface） --- ## 整体风格定义 - **风格关键词**：高级、通透、科技感、品牌化、轻量精致、视觉张力。 - **质感**：柔和多层阴影、清晰边界、结构化光影、细腻纹理、精致微动效。 - **氛围**：默认亮色多彩主题（colorful + gradient + soft shadow），暗黑主题作为可选切换；避免廉价装饰，优先用布局、层级、动效和真实内容建立高级感。 - **参考吸收**：可参考成熟移动端 UI 灵感库的组件完整度、色彩节奏、入场动效和模板化能力，但 Microi 视觉必须通过 `--mci-*` token 与 MCI-UI 组件形成自己的品牌系统，不照搬第三方外观，也不在吾码源码、文档或样式命名中保留外部 UI 品牌痕迹。 ### Microi 设计模式选择（必须） - 当需求只描述“高级、主流、好看”而没有明确视觉方向时，先从 Microi 内置模式中确定一种主结构：品牌叙事、真实产品流程、趋势构图、沉浸互动、动态首屏或数据工作台；再选择至多两种辅助能力。禁止把多套视觉语言堆成拼盘。 - 设计结果必须被拆成可执行规则：首屏目标、信息层级、栅格与最大宽度、字体层级、语义颜色、间距、圆角/阴影、组件状态、动效时间线、响应式重排、低性能降级和 `prefers-reduced-motion`。 - 先完成默认、加载、空、错误、成功、权限、禁用等真实业务状态，再增加装饰和动效；任何看起来可点击的元素都必须有真实结果。 - 所有成品只使用 Microi 自有内容、`--mci-*` token、`mci-*` 组件/类名和项目合法资产。禁止复制第三方页面、源码、图片、字体、3D 模型、商标或原始设计 token。 - 设计前必须读取 [references/design-pattern-library.md](references/design-pattern-library.md)；涉及登录、订阅、支付、权限、搜索、设置等流程时再读 [references/product-flow-recipes.md](references/product-flow-recipes.md)；涉及滚动、3D、Canvas/WebGL 或动态 Hero 时再读 [references/motion-and-media.md](references/motion-and-media.md)；生成整站或交给 AI 延续设计时使用 [references/mci-design-contract.md](references/mci-design-contract.md)。 - 可运行原创案例位于 [assets/pattern-showcase/index.html](assets/pattern-showcase/index.html)，用于理解结构和状态，不作为需要逐像素复制的模板。 ### 可执行设计契约（整站与长期项目强制） - `MCI-DESIGN.md` 必须同时维护机器可读层和人类可读层：前者保存精确 token、引用和组件状态，后者保存目标用户、情绪、具体视觉隐喻、选择理由和禁区。只有 token 会失去取舍依据，只有形容词无法稳定实现。 - 设计意图按“用户任务 → 主情绪 → 具体视觉隐喻 → 应当/禁止 → token 与组件”收敛。具体隐喻必须能自然约束色彩、材质、密度、形状和动效；禁止只堆“高级、现代、极简、科技”等宽泛词。 - 核心章节固定为：产品与用户、视觉性格、颜色、字体、布局与间距、层级与形状、组件与状态、页面模式、动效与媒体、响应式、安全与降级、应当与禁止。扩展章节放在末尾，未知扩展要保留，核心章节不得重复或用近似拼写另起一套。 - token 使用语义命名并允许组件以 `{路径}` 复用；必须检查缺失/循环引用、错误类型、主色缺失、透明色叠加底、对比度、孤立 token、未覆盖状态和无理由省略。组件至少按适用场景定义 default/hover/focus/pressed/loading/empty/error/disabled/selected/success。 - 契约与实现必须一起评审差异；意外删除、重命名、大范围 token 漂移或只改契约不改页面都视为未完成。运行时变量或其它主题格式只能从已校验的机器块派生，禁止维护第二份手工 token。 - 契约格式必须锁定版本，升级时先检查语义差异再迁移；跨平台校验脚本提供稳定入口。完整结构、示例与验收见 [references/mci-design-contract.md](references/mci-design-contract.md)，新项目复制 [assets/templates/MCI-DESIGN.md](assets/templates/MCI-DESIGN.md)。 --- ## 样式隔离与抗覆盖 - Microi.UI 页面或局部 UI 必须使用 `.mci-page`、`data-mci-ui-root` 或项目级 `.mci-*` 根容器包裹，避免被宿主项目、第三方组件库、Markdown 渲染器的全局 CSS 意外覆盖。 - 所有可复用组件必须使用 `mci-` 前缀和 BEM 风格类名；不要写全局 `button`、`input`、`img`、`table`、`div` 选择器。确实需要 reset 时必须限制在 `.mci-page` 或 `[data-mci-ui-root]` 内。 - 业务页面不得用高优先级全局选择器覆盖 MCI 组件，例如 `.card *`、`button {}`、`img {}`、`.page .mci-card {}`。需要定制时用组件 props、CSS 变量或项目级 wrapper。 - 第三方 UI 组件必须放在项目 wrapper 内，例如 `.mci-third-party-scope`，颜色、圆角、阴影、间距映射到 `--mci-*` token，而不是直接把第三方默认主题暴露到页面。 - Web 项目优先用 Vue `scoped` / CSS Modules / 明确命名空间；uni-app 项目优先用页面级 `mci-*` 根类和组件根类。新增全局样式前必须检查是否会影响其它项目页面。 - 文档站、官网、企业站这类 Markdown/VitePress 项目，应在主题层统一收口视觉，不要在每一篇文档里写互相竞争的散装 CSS。 --- ## 高端视觉标准 - 每个新页面必须有首屏视觉重心：核心数据、主任务、产品/品牌对象或可操作内容应在第一屏明确出现，不能只有说明文字或空白装饰。 - 页面进入必须有轻量入场动效，默认使用 `mci-page-enter` / `mci-fade-up`；列表、商品、指标卡使用 30-60ms 交错延迟，不能整页同时僵硬出现。 - 页面停留时允许微弱的停留动效：扫光、细线流动、图标轻浮动、状态光标闪烁等；振幅必须小，且只用 `transform` / `opacity` / `background-position`。 - 所有可点击元素必须有三态反馈：默认、hover/focus、active/pressed；PC 使用 hover lift，移动端使用按压缩放或背景反馈。 - 扁平风格也要有层次：减少圆角不等于没有阴影，必须保留细边框、柔和投影、hover 伪元素阴影和清晰分组。 - 背景装饰优先使用结构化方案：网格、细线、扫描高光、低透明纹理、内容相关图片或 3D 场景；不要使用离散光球、散点噪声、模糊色块堆叠作为主要视觉。 - 导航栏必须和首屏背景属于同一视觉语境：深色英雄区使用深色玻璃或透明暗底导航，浅色内容页才使用浅色导航；导航文字、Logo、搜索框和下拉入口必须截图检查对比度。 - 主按钮/胶囊按钮必须使用 `inline-flex` 或等价布局垂直居中，明确 `align-items:center`、`justify-content:center`、稳定高度和 `line-height:1`；不能只靠 padding 让文字“看起来差不多”。 - 按钮、标签、Tab、空态行动按钮、登录/授权入口等只要文字语义是居中呈现，就必须同时做到上下居中和左右居中；截图或视觉断言发现文字偏上、偏下、偏左、偏右都算未完成。 - 所有弹窗/对话框默认必须上下左右居中；PC 端应支持通过标题栏拖动，拖动后仍保持在可视区域内；移动端如改为底部抽屉或全屏弹层必须有明确业务理由。弹窗不得贴在左上角、底部或被遮罩/导航/输入框遮挡，截图验收必须覆盖默认居中态和至少一次拖动后的可用状态。 - 禁止在任何交付界面中直接调用浏览器原生 `window.alert`、`window.confirm`、`window.prompt` 或其无前缀别名。简单提示优先使用吾码平台 `Tips`/`DiyCommon.Tips`，确认操作使用 `V8.ConfirmTips`、Element Plus `ElMessageBox`，独立微服务则使用符合本规范的可访问确认弹层；原生浏览器对话框会阻塞线程、无法主题化，也无法满足吾码视觉与自动化标准。 - Toast、错误反馈、提交结果和二次确认必须脱离业务滚动容器：优先 teleport/append 到 `body`，使用 `position:fixed`、明确遮罩和高于宿主弹窗的层级，并在当前可视区域上下左右居中。用户把长弹窗滚到任意位置后仍必须立刻看到完整提示；禁止把反馈放在内容顶部、滚动层内部或仅靠 `top: 0` 伪装固定。 - 确认框必须说明“即将执行什么、作用范围、当前任务状态、确认与取消动作”。只有真实检测到正在执行/排队任务时才能写“已有任务”；没有检测到时应明确“提交后新建任务”，并把并发到来时的排队策略作为条件说明，不能用固定模板误导用户。 - 同一类 UI 在两个及以上页面出现时，必须优先封装为 `Mci*` 或项目级 `mci-*` 组件，通过 props/slots/events 配置标题、说明、图标、按钮、路由、状态和少量变体；不要复制两份卡片、空态、登录提示、按钮组、筛选栏或底部操作栏。 - 卡片背景必须服务页面氛围：暗色科技背景上的展示卡、价格卡、聊天卡不应突然变成大面积灰白卡；浅色卡片只在整体页面转为浅色内容区时使用，并且要有过渡带或区块背景承接。 --- ## PC 后台菜单宫格 / 入口页规范 适用于 `sys_menu` 子菜单入口、工作台快捷入口、后台功能入口页。此类页面是操作入口，不是营销卡片墙，重点是密度克制、对齐稳定、快速识别。 - 宽屏不能无上限铺满一整行。1366-1920 宽度下推荐 6-8 个入口/行；超宽屏也不要因为 `repeat(auto-fill, minmax(..., 1fr))` 自动挤出 10 个以上入口。应使用固定/上限列宽、`max-width`、`justify-content:start` 控制节奏。 - 同一宫格内所有入口卡片必须宽高一致，优先使用固定 `width/height` 或 `aspect-ratio + max-width`。禁止让卡片随标题长度、是否有统计信息而高度不一致。 - 卡片内部必须建立固定槽位：图标区、标题区、辅助信息区。每张卡的图标、标题首行、统计胶囊应在同一水平线上；有无辅助信息都要通过固定 body 高度或预留槽位保持对齐。 - 标题与子菜单统计/辅助胶囊的间距控制在 4-6px，不能贴底，也不能和标题隔得很远。统计胶囊应跟随标题成为一个信息组。 - PC 卡片内边距不小于 14-18px，图标背景到卡片边缘不小于 16px；移动端内边距不小于 12px。不能出现图标、文字、统计贴边的效果。 - 标题最多两行并截断或自然换行，长词必须 `overflow-wrap:anywhere`，不允许撑破卡片。图标按钮、标题、统计文本都要垂直和水平对齐。 - 修改后必须截图验收 1366/1440/1920 桌面宽度和 390 左右移动宽度，检查每行数量、行列对齐、卡片内边距、标题与统计间距、文字溢出和横向滚动。 ## PC 后台数据卡片模式规范 适用于 `diy-table` 卡片模式、任务/应用/客户/资产列表。它是高频数据操作容器，不是营销海报或入口宫格。 - 信息顺序固定为“真实图片或紧凑身份标记 → 标题与状态 → 2—4 个关键字段 → 时间/辅助标签 → 操作区”。标题与状态在首屏可扫读，次要字段不能抢占标题层级。 - 配置了图片但某行无图时，用 40—44px 首字或业务图标承接身份；禁止生成大面积渐变、发光字母、旋转方块等伪图片占据内容高度。真实图片按稳定比例使用 `cover/contain`。 - 无显式配置时桌面默认四列，以最小可读宽度优先；显式 `TableCardCol` 配置必须保留。中等宽度降为三列/两列，移动端单列，禁止为“同屏更多”把标题和四个操作挤进过窄卡片。 - 卡片依靠表面、细边框、轻阴影和 1—2px hover lift 建立层级；不要给每张卡加顶部霓虹线、径向光斑、彩虹渐变或重投影。选中态只改边框/焦点环，不能导致网格跳动。 - 操作区优先一个主动作、一至两个次动作，其余进入“更多”；危险动作不得与主动作同权。按钮使用 8—10px 软圆角而非满屏胶囊，移动端高度不小于 44px。 - 整卡可打开详情时提供可见 `focus-visible`、Enter/Space 触发；内部按钮和选择控件阻止冒泡。骨架屏要复刻图片（如有）、标题、字段和按钮的最终几何，不能先显示大图骨架再塌缩为空白。 - 视觉验收至少覆盖：无图/有图、长标题、多个按钮、选中态、加载/空态、亮/暗主题、1366/1440/1920 桌面与 390 移动。 --- ## 形态模式（圆角 / 扁平） Microi 项目必须支持用户或项目级形态偏好：`data-mci-shape="rounded"` 与 `data-mci-shape="flat"`。 ```css :root { --mci-shape-card: var(--mci-radius-xl); --mci-shape-panel: var(--mci-radius-lg); --mci-shape-button: var(--mci-radius-pill); --mci-shape-input: var(--mci-radius-md); } :root[data-mci-shape="rounded"] { --mci-shape-card: 20px; --mci-shape-panel: 16px; --mci-shape-button: 999px; --mci-shape-input: 12px; } :root[data-mci-shape="flat"] { --mci-shape-card: 6px; --mci-shape-panel: 4px; --mci-shape-button: 4px; --mci-shape-input: 4px; } ``` - 圆角风格适合移动端商城、会员中心、消费类应用、品牌展示页。 - 扁平风格适合 B 端官网、数据看板、工具型 Web、强调效率的页面。 - 所有组件只引用 `--mci-shape-*`，不要在业务页面硬编码一堆 `border-radius`。 - 切换形态时只改变圆角 token，不改变布局尺寸，避免切换主题时页面跳动。 --- ## 颜色体系（CSS Variables — 支持主题切换） 所有颜色必须通过 CSS 变量引用，禁止硬编码色值。变量定义放在全局样式入口（PC 端 `src/styles/mci-design.scss`，移动端 ` ``` --- ## 🚨 移动端低代码项目落地踩坑（必读，2026.5） 实战中频繁出现的 7 类问题，统一按以下规则处理。 ### 1. 路由前缀不要硬编码租户名 - 错误：在 `manifest.json` 写死 `"router": { "base": "/fixed-tenant/" }`。 - 正确：默认使用 `"router": { "base": "/" }`；租户由运行配置、`OsClient` 和请求头/参数确定。 - 不要自行把租户名拼进 API 路径。平台接口使用 `/api/...`、`/apiengine/...` 等标准路由。 ### 2. tabBar 使用本地静态 PNG 图标 - uni-app/微信小程序 tabBar 的 `iconPath`、`selectedIconPath` 使用项目内静态 PNG。 - 不使用 emoji、字体图标、远程 URL；SVG 仅在目标端明确支持并已做真实设备验证时使用。 - 普通态与选中态保持相同画布和轮廓，推荐 60×60 至 81×81 px，并验证深浅色背景可读性。 ### 3. 字号样式不要通配所有 `text` Scoped SCSS 中的 `.entry text { font-size: 40rpx; }` 会同时放大图标文字和子标签。图标、标题、说明必须使用独立 class： ```scss .entry .entry-icon { font-size: 40rpx; } .entry .entry-label { font-size: 22rpx; } ``` ### 4. 个人中心/详情入口按信息层级选布局 - 高频资产、订单状态、服务入口适合 4～5 列网格。 - 设置、安全、协议等低频入口适合纵向列表。 - 单元格须有稳定触控区域、清晰标签和一致间距；不要为了追求密度牺牲可读性。 ### 5. 每个可点击元素都要有反馈 ```scss .cell, .entry-item, .product-card, .zone-card { position: relative; transition: transform .2s ease, box-shadow .2s ease; } .cell:active, .entry-item:active { transform: scale(.94); } @keyframes fadein-up { from { opacity: 0; transform: translateY(16rpx); } to { opacity: 1; transform: translateY(0); } } .animate-fadein { animation: fadein-up .45s ease both; } @media (prefers-reduced-motion: reduce) { .animate-fadein { animation: none; } } ``` 动效只表达状态，不承担业务完成事实；提交、支付、安装等动作仍以服务端返回和可恢复状态为准。 ### 6. 品牌名和 Logo 的用户可见位置保持一致 同步检查 `manifest.json` 的 `name/h5.title`、`pages.json` 的导航标题、登录/注册/首页品牌区、空状态和分享标题。控制台中的技术标识可保留，但用户可见文案必须统一。 ### 7. 接口地址由标准引擎工具维护 - `microi_create_engine`/`microi_upsert_engine` 会维护 `ApiEngineKey`、`ApiAddress` 和路由缓存。 - 写入超时先用标准 get/list 工具回读，不得立即重复创建。 - 禁止通过手工 SQL、直接修改 `sys_apiengine` 或自行拼 Redis Key 修补路由；这会绕过租户、审计、缓存失效和控制面权限。 - 长任务使用后台任务并持久化进度；普通接口写入后以远端回读为最终依据。 ## 🔗 关联字段：保存真实 Id，界面展示可读标签 关联字段的数据库事实值通常是 `XxxId`。表单使用 `JoinForm`、`OpenTable` 或带数据源的 `Select` 显示名称，`SelectSaveField` 保存 `Id`，`SelectLabel` 展示名称。不要因为列表默认显示 Id，就强制所有业务表冗余一对可编辑的 `XxxId/XxxName` 字段。 ### Select 数据源示例 ```json { "DataSource": "Sql", "Sql": "select Id, Name from mall_category where Name like '%$Keyword$%' limit 0,20", "SelectLabel": "Name", "SelectSaveField": "Id", "SelectSaveFormat": "Text", "EnableSearch": true, "DataSourceSqlRemote": true } ``` - `$Keyword$` 是平台数据源占位符，不要把浏览器输入直接拼进任意 SQL。 - 关联表、字段和数据源必须来自当前租户，并受当前表单/菜单的授权与数据范围约束。 - 大表使用远程搜索和分页，不一次性把全表拉到浏览器。 - 列表展示名称优先配置 Join/模块关联字段或受控数据源，不把隐藏 Id 暴露给用户。 ### 什么时候增加 `XxxName` 快照字段 只有在业务明确要求“保存当时名称”、离线展示、历史审计或高频报表需要时才增加 `XxxName`。它是快照/冗余字段，不是外键事实源，并遵守： 1. 后端 SubmitBefore/接口引擎在同一事务内根据 `XxxId` 校验并写入名称。 2. 前端 V8 可以即时回显，但不能作为唯一一致性保障。 3. 关联名称后续变化时，先明确历史快照是否应随之更新。 4. 批量回填必须参数化、可恢复、可幂等，并经过明确写入确认。 ### MCP 建模流程 1. 先用 `microi_get_db_schema` 获取真实表和字段。 2. 使用 `microi_build_field_config` 生成 JoinForm/OpenTable/Select 配置。 3. 使用 `microi_add_field` 或 `microi_update_field` 写入字段。 4. 修改 KeyValue/Config 后回读 `microi_get_field_list`，并执行 `microi_refresh_schema_cache`。 5. 在真实菜单下验证普通角色能看到标签，但不能借数据源越权读取其它表或行。 --- ## 表单布局规范（Column） > 平台默认设计标准：所有 `diy_table` **应使用双列布局** (`Column = 2`)，更紧凑现代，符合主流后台 SaaS 视觉密度。 ### 创建表时 ```jsonc microi_create_table { "name": "Crm_Customer", "description": "客户", "column": 2 // ✅ 默认就是 2，无需显式传，但推荐写明 } ``` ### 修复存量表（一次性把所有 `Column=null` 改成 2） ```jsonc microi_update_table { "name": "Crm_Customer", "column": 2 } ``` ### 何时使用 Column=1（单列） - 工作流审批表单（字段少且需要专注） - 移动端优先表单（手机宽度不够双列） - 含大量富文本/长文本字段的内容编辑表 ### 何时使用 Column=3（三列） - 字段≥18 的"基础档案"类大表（员工、商品 SKU、设备清单） - 桌面分辨率≥1920px 的内部管理后台 > 修改 `Column` 后会自动清缓存（`microi_update_table` 后端走 `UptFormData('diy_table')` + 主动 `RefreshSchemaCache`），前端硬刷新（Ctrl+Shift+R）即可看到效果。 --- ## 表单分组规范：Tabs vs CollapseGroup（强制） > **核心原则**：默认**不分组** → 小业务域用 **`CollapseGroup` 折叠分组** → 只有足够长或强任务隔离的业务域才用 **`Tabs` 分页**。禁止只按字段数判断：双列布局中 8 个短字段约占 4 行，仍不应独占 Tab；普通业务域通常达到 6 个有效表单行才考虑 Tab。 ### 三种分组方式 | 方式 | 存储位置 | 控件 | 适用场景 | |------|---------|------|---------| | **A. 表级 Tab** | `diy_table.Tabs` + 字段 `Tab` | 表单顶部 Tab 条 | 大表单拆 2~5 个业务域，每域通常 ≥6 个有效表单行，或属于扫码/子表/代码编辑等强任务模式 | | **B. 字段级 CollapseGroup** | `diy_field.Component='CollapseGroup'` + `Config.CollapseGroup` | 折叠面板标题 | 小业务域（≤5 个有效表单行），**所有分组同屏可见、可同时展开** | | **C. 字段级 Tabs 控件** | `diy_field.Component='Tabs'` + `Config.FieldTabs` | 字段是 Tab 容器 | 嵌套 Tab 场景（不推荐优先用） | ### 表单规模与分组决策表 | 有效表单行与任务特征 | 推荐方案 | |---------|---------| | ≤ 6 行且无复杂控件 | **不分组**（直接平铺） | | 7 ~ 12 行且无强任务隔离 | `CollapseGroup` 收起次要字段，或直接平铺 | | > 12 行且至少两个业务域各 ≥ 6 行 | `diy_table.Tabs`（大域）或混合（Tab + 嵌套 CollapseGroup） | | 扫码、报工、大型子表、代码编辑等强任务模式 | 可独立使用 `diy_table.Tabs`，不受普通行数阈值限制 | ### CollapseGroup Config 示例 ```jsonc // diy_field 必要字段 { "Component": "CollapseGroup", "Type": "varchar(50)", "Visible": 1, "AppVisible": 1, "Config": "{\"CollapseGroup\":{\"DefaultCollapsed\":false,\"ScopeMode\":\"UntilNextGroup\",\"Description\":\"MRP 运算状态、批次号与时间\",\"Icon\":\"fas fa-calculator\",\"Theme\":\"primary\",\"ShowFieldCount\":true}}" } ``` ### 必做与禁止 - ✅ 任何 Tab / CollapseGroup 必须有 `Description` 解释分组用途。 - ✅ CollapseGroup 必须设 `Icon`（如 `fas fa-calculator`、`fas fa-info-circle`），不默认空白。 - ✅ 修改 Tab/CollapseGroup 配置后必须 `microi_refresh_schema_cache`。 - ❌ **禁止**为 ≤5 个有效表单行的业务域单独建 Tab；8~10 个双列短字段通常也应使用 CollapseGroup。 - ❌ **禁止**仅凭 13~30 个原始字段决定平铺或分 Tab；总有效行超过 6 且存在明确业务域时，至少使用 CollapseGroup 分组。 - ❌ **禁止**给 Tabs/CollapseGroup/Divider/Alert 等布局控件设 `FormWidth=24`（天然占整行）。 - ❌ **禁止**只创建 Tab 不写字段的 `Tab` 归属。 - ❌ 布局优化不得顺带覆盖字段 `Config/V8Code/KeyupV8Code` 或表级 V8 事件；修改前后必须回读比较，发现 Tab 显隐 API 时先适配再迁移。 完整规范、Config JSON 模板、回读验收清单和反例参考见 `microi-form-layout/SKILL.md`。 --- ## 缓存刷新（解决"我改了字段但页面不变"问题） 平台对 `diy_field` 的字段列表有 Redis 缓存，键格式 `Microi:{OsClient}:FormData:diy_table_field_list:{TableId|TableName}`。 **何时缓存会失效**： - ✅ 通过 `microi_add_field` / `microi_update_field` / `microi_update_table` 走原生 API → 自动清 - ✅ 通过低代码后台界面操作（diy_table 表单事件触发）→ 自动清 - ❌ 直接 `V8.FormEngine.UptFormData('diy_field', ...)` → **不会触发清缓存**（这是历史 bug） **何时手动清**： ```jsonc microi_refresh_schema_cache { "tables": ["mall_address", "mall_member"] } ``` 该工具会清除每张表的 6 个 key 变种（`diy_table` / `Diy_Table` / `diy_table_field_list` × `id|name`）。 --- ## 接口引擎匿名访问 登录、注册、首页公共数据等接口必须 `AllowAnonymous=1`，否则未登录用户调用会拿到 `null`： ```jsonc microi_set_engine_anonymous { "apiEngineKeys": ["mall_member_login", "mall_member_register", "mall_home_data"], "allowAnonymous": 1 } ``` ## MCI-UI 与第三方组件库策略 Microi 的 UI 规范不应该只停留在 skills 文档。面向品牌长期建设时，应形成可复用的 MCI-UI 体系：设计变量、基础样式、组件约定、示例站点、移动端与 PC 网站组件库。 - **默认规则**：当用户没有主动指定 UI 风格、UI 库或品牌视觉时，AI 必须默认采用 Microi吾码UI（Microi.UI / MCI-UI）作为移动端、PC 官网、企业网站、产品站、活动页和响应式网站的设计基础。 - **自动识别**：只要项目属于 Microi 生态、吾码源码、吾码客户项目，或需求中出现“移动端项目、网站、企业站、商城、会员中心、资产页、官网、H5、uni-app、Vue3”等关键词，即使用户没有单独说明 UI 风格，也应自动套用本规范与 `Microi.UI/` 组件。 - **落地要求**：业务页面优先使用 `MciPage`、`MciSection`、`MciButton`、`MciCard`、`MciCell`、`MciTabs`、`MciSkeleton`、`MciDataState`、`MciThemePanel` 等组件或项目级 `mci-*` 封装；不要重新发明一套分散样式。 - **例外场景**：后台管理系统继续使用 Element Plus + Microi theme；强行业 UI 或客户指定视觉可以定制主题 token，但仍优先保留 `--mci-*` 变量、骨架屏、安全区和动效规范。 - UniApp 项目不强制业务页面直接依赖某一个第三方 UI 库。推荐把 `uni-ui` 作为官方跨端基础组件底座之一，但业务视觉必须通过 `MCI-UI Mobile` 或项目级 `mci-*` 组件封装承载，避免页面直接散落 `uni-ui/uView/FirstUI/TDesign` 风格。 - PC 后台管理系统继续使用 Element Plus，不替换选型；但主题变量、间距、骨架屏、空态、安全区、表单密度和品牌色必须服从 `--mci-*` 设计变量。 - PC 官网、产品站、文档站、营销页和响应式网站应优先使用 `MCI-UI Web` 的设计变量与轻量组件。只有当页面是强表单、强数据录入或后台化工具时，才引入 Element Plus、TDesign Vue、Naive UI、Arco Design Vue 等成熟组件库作为底座。 - MCI-UI 应分层建设：`@microi/theme` 负责 tokens；`@microi/v8` 负责前端 SDK；`@microi/ui-mobile` 面向 UniApp；`@microi/ui-web` 面向官网和响应式站点；`Microi.Client` 后台则用 Element Plus + MCI theme。 - `microi.doc` 作为 VitePress 官方文档站，应逐步成为 MCI-UI 的展示入口：组件演示、设计变量、移动端骨架屏、安全区、富文本、上传资源、主题切换都应该有可查看示例，而不是只写在 skill 中。 ## MCI-UI 源码落地位置 MCI-UI 已在吾码源码根目录落地：`Microi.UI/`。 - 新的移动端 UniApp/H5 项目应优先使用 `Microi.UI/src/uniapp` 中的 `MciPage`、`MciNavbar`、`MciButton`、`MciCard`、`MciCell`、`MciSection`、`MciTabs`、`MciMetricCard`、`MciActionBar`、`MciAvatar`、`MciProductCard`、`MciSkeleton`、`MciDataState`、`MciRichText`，再按业务补项目组件。 - 新的 PC 官网、产品站、文档站、响应式网站应优先使用 `Microi.UI/src/web` 和 `Microi.UI/src/theme`，不要直接套后台 Element Plus 风格。 - `Microi.UI/src/theme/tokens.css` 是品牌 token 源头；新组件颜色、圆角、阴影、间距、安全区、骨架屏都必须走 `--mci-*` 变量。 - `Microi.UI/src/theme/runtime.js` 是主题运行时入口；项目应通过 `initMciDesign()`、`setMciPalette()`、`setMciShape()`、`setMciTheme()` 统一设置黑白红橙黄绿青蓝紫主色、圆角/扁平、亮暗主题和动效偏好。 - `MciPage` 默认带页面入场动效；业务页如果有特殊路由转场，可以关闭 `animated` 后使用项目级转场，但不能让动态页面无反馈地直接闪现。 - `MciButton`、`MciCard` 必须保留 hover/pressed/focus/sheen 等基础反馈；业务组件可以封装样式，但不能删掉交互状态。 - 第三方 UI 库只能作为底层能力或局部补充，不能绕过 MCI-UI 直接决定产品视觉。