makeui

makeui

React 权限拒绝提示的实现请阅读 references/permission-feedback.md，使用 @qfei-design/make-app-observability/react 中已验证的 MakeAppPermissionNotice，并通过一个宿主适配器加载软件包 CSS；不要重新实现其 UI。新建或明确升级的反馈集成使用 0.1.10+，使用软件包自有的 Toast 时序，并由宿主负责事件标识和队列清理；保持未改动的旧版 App 的锁定版本。遵守 registry/本地预发布版本门槛。提示展示使用 variant（toast、inline、page），与权限 scope 相互独立。对于对象级/固定页面的读取拒绝，保留已授权的导航和全局身份标题栏，但替换整个业务内容槽位，包括其标题、工具栏、表格标题、卡片、表单和对话框。仅操作权限被拒绝时，保留允许访问的业务 UI 和输入项。请阅读 make-app-permission/references/scoped-route-feedback.md；只有在没有已授权的 App 入口时，才允许显示整页 App 拒绝提示。遵守宿主现有的桌面端/移动端和全局错误出口约定。

在 apps/ui 中进行 Make App 前端 UI 开发时使用此技能。默认技术栈为 React + Vite + React Router，但 makeui 只负责 UI 结构和展示决策。

makeui 负责应用外壳布局、导航布局、列表页布局、工具栏位置、当前用户界面、组件库使用、字段控件展示、新建/编辑/详情布局、用户/部门选择器 UI 行为、响应式 View 组合、视觉状态和 UI 润色。它使用 @qfei-design/make-app-mobile 提供共享的移动端展示基础组件，同时将业务 Controller 留在宿主中。它不负责身份验证/登录、前端构建或发布规则、Service 运行时结构、业务 API/数据契约、权限逻辑、持久化、业务建模、领域映射、canvas-table 内部实现或高级筛选软件包内部实现。对于生成的 Make App，请将此技能与 make-app-permission 配合使用；不要把权限门控视为可选的 UI 润色。

快速开始

需求方案确认后新建或迭代 Make App，先按 make-app-approval 判断是否生成/复用“我的审批”入口。审批新建字段、保存后首次发起、流程状态字段和详情标题 Tag 由该 skill 主责；下文 createFields 新建规则仅用于普通无有效审批配置的场景，已有记录普通编辑保持原 IAM 链路。不要因未绑定流程漏掉导航，也不要因有导航就切换所有表单的字段权限。

1. 检查现有 UI 技术栈、路由、Shell、组件库、样式系统和页面布局约定。对于没有既定库或用户指定库的新项目，使用 references/component-usage.md 中的三选一选择 UI；允许选择兼容的 React 库，只有用户未作选择时才默认使用 Ant Design。
2. 保留宿主项目的数据和身份验证行为。本技能中不要设计登录、令牌、业务 API 路由、Service 编排、部署或构建输出。
3. 使用宿主提供的对象/字段元数据渲染 UI。不要臆造业务字段或 API 契约。
4. 移动端支持是每个新 Make App 的默认交付要求，不是可选增强功能。先阅读冻结的产品契约 references/mobile-product-baseline.md，再阅读 references/mobile-defaults.md、references/mobile-visual-standard.md 和 references/mobile-form-controls.md；除非用户明确选择不支持移动端或要求自定义移动端设计，否则使用 @qfei-design/make-app-mobile。在手机上，创建/编辑/详情字段（File 除外）必须在同一行保留左侧标签槽和右对齐的值槽；TextArea 从两行开始并可增长，多值内容在右侧槽内换行；Number/Currency/Percent 使用纯受控文本输入框，不显示步进器，同时保留统一的精度校验。只有 File 可以使用全宽堆叠字段布局。身份信息和附件字段使用该软件包的 /fields 组件，不要用宿主构建视觉复刻；详情标签页与详情内容共用水平边距。不要通过折叠桌面网格来推导手机字段布局。创建/编辑保存使用右对齐且不带图标的表单页脚；保留桌面/平板行为。对于现有 App，只要涉及移动端或响应式行为，也要阅读这些参考文件。在桌面/移动视图之上保留一个共享的业务 Controller。
5. 默认使用密集型对象管理桌面布局：左侧导航、扁平工作区页眉、紧靠表格上方的局部工具栏，且不添加额外的列表标题卡片。侧边栏颜色遵循项目主题。在手机上使用由软件包提供支持的移动端 Shell 和 mobile-defaults.md 中的任务页默认设置；底部标签根据当前可见业务对象生成，仅当对象数量达到五个时才显示工作台标签。对象数量较少时仍保留工作台的直接路由。
6. 为对象路由添加可见的 UI 状态：加载中、空状态、错误、无权访问、会话过期、未找到、重试，以及渲染错误回退。当 make-app-observability 提供共享请求错误卡片时，无论权限、Schema 和路由是否成功，都要将其全局错误出口挂载在持久化的应用根节点中。其 0.1.9+ 视口负责桌面端和手机端的 Portal 定位；Shell 已挂载时，将宿主负责的重试按钮置于主内容区域中央；Shell 尚未挂载时，则置于持久化应用根节点的回退区域中央，并使用项目现有的按钮组件。阅读 references/app-shell-layout.md，了解挂载、覆盖层和重试按钮位置契约。
7. 在任何视图呈现之前，规范化身份验证/当前上下文身份信息，包括 { userId, avatar, name } 这类响应。桌面端在顶部页眉右侧显示当前登录用户条目，头像严格为 32px，旁边显示纯文本名称。移动端仅在左上角显示头像并打开软件包账户抽屉；租户名称和退出登录的显示方式请阅读 mobile-defaults.md。
8. 对于新的 Make App UI，默认使用平台组件化源码目录结构：src/pages、src/components、src/hooks、src/lib/service-api、src/router 和 src/types；复杂表格/工作流组件应拆分到嵌套的 config、editing、editors、hooks、renderers 和 types 模块中。
9. 对于新的 Make App UI，在实现宿主负责的表单、详情、表格显示或单元格编辑行为之前，先在 apps/ui/src/lib/make-field-types.ts 或宿主项目既定的等效位置创建共享的 Make 字段类型注册表。注册表必须涵盖所有当前 Make.Field.* 类型，并公开显示分组、渲染类型、默认宽度、对齐方式、多值属性、控件/显示提示，以及 UI 控件所需的规范化 field.properties，包括 format、precision、decimalPlaces、maxCount、begin、end 和 symbol。高级筛选运算符和值编辑器仍由软件包负责。同时，对桌面/平板端的字段名称和字段选择列表应用默认 Lucide 字段类型图标契约；手机端使用纯字段标签。每个新 Make App 都必须执行此项，无需等待单独提出图标要求。
10. 桌面/平板端的创建、编辑和详情使用右侧 Drawer 和两列网格。手机端使用由软件包支持的全屏单列任务路由，并阅读 references/mobile-form-controls.md；手机任务页必须切换字段呈现适配器，而不是原样复用桌面弹窗。
11. 自定义表单字段控件必须是由宿主表单控制的适配器：接收并转发宿主表单层传入的 value/onChange/onBlur/id/disabled，并确保提交/校验所见的表单值与显示的选项一致。此要求与 UI 库无关，不要求使用 Ant Design、Arco 或 shadcn。手机端和桌面端的适配器在视觉上可以不同，但必须遵守相同的提交值契约。
12. 通过字段类型显示适配器渲染详情值。如果字段类型有稳定的 Make 显示形式，不要显示原始对象、数组或 JSON 包装文本。
13. 对于生成的 Make App UI，使用 make-app-permission 实现所需的权限门控和字段集交接：普通新建使用权限推导出的 createFields / 创建字段集；审批新建使用 make-app-approval 定义的授权启动配置字段；编辑使用可见字段和可编辑字段集。权限模块负责路由/操作检查、载荷筛选和刷新；makeui 仅渲染授权后的结果。
14. 对于每个可写的 Make 记录列表，将记录操作交由 make-app-actions 处理。桌面/平板端使用 CanvasTable 多选、底部操作栏、单条编辑/删除和批量编辑。手机端使用卡片列表，通过 make-app-actions 无头核心处理点击记录后的编辑/删除，并显示受权限控制的详情操作栏；不得渲染 CanvasTable、记录选择或批量操作。加载 make-app-actions，并阅读其 mobile-card-actions.md 参考文件。makeui 保留选定的组件库，不得仅为使用软件包的模态框而混入 AntD。
15. 搜索是手机端工具栏的默认入口。在 search-only 模式下，当关键词搜索使用 filter.expression 时，使用 make-app-filter 的 compileListFilter，不要添加筛选 Preset、Controller、面板或手机端筛选入口。如果用户要求或现有实现包含高级筛选（包括明确要求筛选、表格筛选或表头筛选），则使用 advanced-filter 模式：筛选行为交由 make-app-filter 处理；随后由 makeui 按照 mobile-defaults.md 所述，在桌面/平板端放置工具栏和 CanvasTable 联动，并在手机端搜索旁放置单独的中等筛选入口。手机端使用列表下拉刷新，不添加独立刷新控件；仅在 advanced-filter 模式下使用移动端软件包的 MobileFilterSheet，而不是桌面筛选 Popover。
16. 如果用户要求或现有实现包含记录分组、多级分组、拖动优先级、分组 CanvasTable、record-groups 或 groupFilter，则将集成行为交由 make-app-group 处理；makeui 仅在桌面/平板端放置其入口。标准手机工具栏隐藏分组。
17. 如果用户要求或现有实现包含记录排序、多字段排序、拖动优先级或表头升序/降序，则将集成行为交由 make-app-sort 处理；makeui 仅在桌面/平板端放置其入口。标准手机工具栏隐藏排序。
18. 如果用户要求或现有实现包含桌面/平板端 Make 记录表格单元格编辑，则将表格接入 canvas-table-integration Track C，作为 Make 显示基础，并使用 Track B 作为编辑增强。makeui 可以放置表格宿主，但不得在页面组件中临时编写单元格编辑器。手机卡片不提供单元格编辑。非标准 CanvasTable 单元格编辑器属于就绪阻断项/交付阻断；不得声称 UI 已就绪、完成或交付。
19. 如果任务提到助手、AI助手、MakeAI AI 助手、Make AI 助手、AI 对话框、SSE、Agent Gateway、@qfei-design/make-ai-assistant、MakeAiTheme 或 maxDrawerWidth，必须先确认平台 make-ai-assistant Skill 已安装且可读取，然后使用它处理软件包、传输、软件包主题、助手内部 UI/样式和响应式行为。如果缺少该 Skill 或无法使用，则使用 make-env-setup 安装/更新 Make 平台 Skills（或说明所需的加载步骤），并暂停助手实现，直至该 Skill 可用。不得根据项目历史或现有项目推断助手行为。只有该 Skill 定义集成后，makeui 才负责周边布局、放置位置和外部容器约束。通用对话框仍属于普通 UI 工作，除非请求明确涉及 AI 助手交互。
20. 对于新的 Make App UI 和非简单 UI 更改，组件化不足属于就绪阻断项。在报告已就绪或完成之前，验证 App.tsx 和路由/页面文件仅负责编排，并确认实现逻辑已拆分到页面、Shell、功能组件、hooks、lib/service-api、字段显示/配置适配器、表格宿主、工具栏和 Drawer 模块中。
21. 仅阅读下方映射中所需的参考文件。 对于移动端交付，安装后使用 scripts/verify-mobile-package-surface.mjs 验证实际安装的包。最低公开 API 版本为 0.1.7，但通用视觉交付基线为 0.1.9，其中包括已修复的 48px 附件上传入口。手机端高级筛选还要求移动端版本为 0.1.11+，筛选版本为 1.1.0+，具体要求见 make-app-filter；验证器失败属于包级阻塞问题，不代表可以在宿主应用中覆盖包内部样式。安装和验证边界请遵循 references/mobile-defaults.md。

主题参考索引

任务 / 主题	阅读
UI 范围、边界、外壳默认设置、动态路由	references/principles.md
已冻结的手机端产品标准，以及对已被取代提案的优先级	references/mobile-product-baseline.md
移动端默认设置、桌面端/移动端平滑切换、移动端外壳/导航/工作台/任务页面/选择器/列表最终状态	references/mobile-defaults.md
手机端创建/编辑/详情字段适配器、日期/时间/选择/查找/文件控件、任务页脚、叠层适配	references/mobile-form-controls.md
已安装移动端包的 iOS 输入、捏合缩放、附件渲染和 48px 上传入口	scripts/verify-mobile-package-surface.mjs
组件结构、模块边界、页面拆分	references/component-structure.md
应用外壳、侧边栏、顶部标题栏、视口高度链	references/app-shell-layout.md
对象列表页面、工具栏位置、默认操作	references/list-page-layout.md
创建/编辑/详情抽屉、堆叠抽屉、遮罩层关闭、标题栏操作	references/drawer-layout.md
基于路由的创建/编辑/详情页面或 URL 可寻址状态	references/page-route-layout.md
组件库选择、字段类型 UI 控件、详情值显示	references/component-usage.md
默认 Lucide 字段类型映射、桌面端/平板端标签与字段选择图标覆盖范围、手机端排除项	references/field-type-icons.md
间距、密度、响应式布局、加载/空状态/错误状态	references/styling-and-responsive.md
应用/资源/操作被拒绝、管理员联系方式、反馈包和重试呈现	references/permission-feedback.md；权限/身份验证语义仍由其所属 Skill 负责
制作记录表格显示或单元格编辑	使用 canvas-table-integration
制作记录选择、底部操作栏、编辑/删除/批量编辑、行预检查	使用 make-app-actions
高级筛选面板、条件构建器、筛选表达式、标题栏字段筛选	使用 make-app-filter
记录分组、拖动优先级、预设分组、record-groups、分组表格流程	使用 make-app-group
记录排序、拖动优先级、预设排序、表头升序/降序	使用 make-app-sort
Make AI 助手、AI助手、MakeAI AI 助手、AI 对话框、SSE、Agent Gateway、make-ai-assistant 包、MakeAiTheme、maxDrawerWidth	使用 make-ai-assistant；包负责内部 UI/样式，而 makeui 负责启动器/面板位置、外壳适配和外部容器约束
单应用权限、路由守卫、操作按钮、字段可编辑性、刷新时重新加载权限	使用 make-app-permission
身份验证、登录、注销处理程序、令牌、会话行为	使用 make-app-auth；makeui 仅负责当前用户菜单的界面和位置
构建输出、Service 运行时、打包、发布就绪状态	使用 make-app-runtime；makeui 不负责运行时契约

硬性规则

范围边界

• 请勿在 makeui 中新增或修改身份验证／登录、令牌、OAuth、Cookie、登出行为、会话机制、/api/make/**、域名、网关、部署、Docker/K8s、Node 运行时、包管理器、构建输出或 Service 运行时规则。references/mobile-defaults.md 可能要求对其展示包进行兼容性预检，但不得选择或迁移宿主运行时／包管理器；如有不兼容，应转交 make-app-runtime。
• 请勿在 makeui 中定义业务 API 路径、Service 契约、数据持久化、权限逻辑、审批流程或环境映射。此处唯一允许的端点指导，是 UI 选择器的默认用户／部门候选来源行为。如果宿主文档规定了不同的传输方式，路由名称必须以宿主项目文档和负责该功能的 Service/API 技能为准。
• 除非用户明确选择不配置权限，否则未满足 make-app-permission 要求的单应用权限门控时，不得将生成的 Make App UI 报告为已完成。
• 可写的 Make 记录列表默认使用 make-app-actions。桌面端／平板端由 CanvasTable 负责多选和标准操作栏。手机端使用卡片，并且只复用包提供的无头单记录操作模型；手机端不得渲染 CanvasTable、记录复选框、全选、选择操作栏、批量编辑或其他批量操作。makeui 负责卡片／操作项的布局，但不得复制操作权限模型或 Service 预检生命周期。
• 如果任务涉及身份验证／登录／登出／会话行为，请使用 make-app-auth。如果任务涉及构建输出、Service 运行时、打包或发布就绪规则，请使用 make-app-runtime。
• 如果任务涉及筛选、高级筛选、表格筛选、筛选器构建器、filter.expression 或表头“按该字段筛选”，请使用 make-app-filter。makeui 不得实现或分叉 @qfei-design/make-app-filter 逻辑。桌面端／平板端筛选保留 CanvasTable 表头联动，由 make-app-filter 和 canvas-table-integration 负责；手机端只使用顶层搜索／筛选入口，不得仅为实现表头联动而挂载隐藏的 CanvasTable。
• 如果任务涉及分组、多级分组、拖动优先级、预设分组、record-groups、groupFilter 或分组后的 CanvasTable 渲染，请使用 make-app-group。makeui 不得负责分组模型、dnd-kit 行为、预设时机、Service 负载、groupFilter 组合或分组叶节点分页。
• 如果任务涉及排序、多字段排序、拖动优先级、预设排序或表头升序／降序，请使用 make-app-sort。makeui 不得负责排序模型、dnd-kit 行为、预设时机、Service 负载或表格表头控制器联动。
• 如果任务涉及 Make AI 助手、AI 助手、MakeAI AI 助手、AI 对话框、SSE、Agent Gateway、接入 make-ai-assistant 包、MakeAiTheme 或 maxDrawerWidth，请使用 make-ai-assistant。该包负责助手内部 UI 和样式。makeui 不得负责助手传输、历史记录恢复、Service 网关路由／源站规则、包主题变量、页眉／任务列表／输入区行为、全屏控制或包容器查询行为。
• makeui 可以使用宿主提供的对象／字段元数据进行 UI 渲染，但不得决定如何获取、存储、验证身份或部署这些元数据。
• 对于新建 Make App 以及移动端／响应式改动，请使用公开的 @qfei-design/make-app-mobile 导出项，而不是复制试验项目中的组件。该包负责移动端展示和覆盖层机制；宿主负责业务状态、数据、权限、路由、身份验证和环境检测。用户明确提出的要求可以覆盖默认展示方式。
• 手机端的用户／部门字段默认使用该包 /fields 入口中的 MobileIdentityField，手机端编辑附件默认使用 MobileAttachmentField。请勿在宿主中重建它们的触发标签、身份标记、附件卡片、删除确认或上传入口。宿主仍负责候选 API、ID 规范化、上传／删除／重试请求、记录标识、权限、持久化和表单验证。
• 如果新 Make App UI 仅实现了桌面端视图，不得将其报告为已就绪。除非用户明确选择不实现或要求其他移动端设计，否则应交付基于该包的手机端外壳、导航／工作台、列表和任务页组合、受控选择器行为，以及 references/mobile-defaults.md 中的断点验证。

UI 元数据与状态

• 生成的 UI 使用规范化的、由宿主提供的对象/字段元数据。不要将原始后端 schema 变体直接传递给表格、表单、详情、路由或 shell 组件。
• 新建和编辑表单使用由宿主提供的不同权限结果。普通新建仅渲染获授权的 createFields / 新建字段集；审批新建则渲染 make-app-approval 中获授权的启动配置字段，不要重新应用普通字段交集。编辑先渲染可见字段，再应用可编辑字段集，以控制字段呈现为可写还是只读。makeui 不得重新计算 IAM 访问权限，不得在缺少新建字段时用可见字段代替，也不得直接使用后端的 editableFields。
• 必填校验仅适用于当前模式下实际渲染且已获授权的字段。隐藏或未获授权的必填字段不得阻止新建/编辑提交。
• 新的 Make App UI 必须在 apps/ui/src/lib/make-field-types.ts 或等效的共享注册表中集中管理由宿主定义的字段类型语义。表单控件、详情展示、CanvasTable 列/渲染分派和表格单元格编辑器应使用此注册表，而不是重复定义 Make.Field.* 字符串数组或临时编写 switch 语句。注册表必须保留规范化的 field.properties 及字段类型提示，以便生成的组件使用 schema 特有的 format、precision、decimalPlaces、maxCount、begin、end、symbol 和 useGrouping。注册表仅暴露规范化字段元数据和展示提示；宿主表单/单元格校验应放在独立的纯函数辅助工具中。高级筛选器的运算符、默认值、校验和取值编辑器类型应来自 @qfei-design/make-app-filter 公共 API，而非此注册表。
• apps/dsl 是建模产物，不是 UI 运行时依赖。生成的 UI 不得读取 apps/dsl/**、/dsl/** 或复制的 *.yaml 文件作为字段来源。
• 如果对象/字段元数据缺失或不一致，应显示可见的 UI 依赖项/错误状态，并报告缺失的依赖项。不要臆造业务 API 路径、解析本地 DSL，或在 makeui 中创建虚假的用户/部门/业务回退数据。
• schema、数据、路由和渲染失败必须显示为可见的对象 shell 状态：加载中、空状态、错误、禁止访问、会话过期、重试、未找到或渲染错误。不要让异常导致空白页面。
• Make.Field.Number、Make.Field.Currency 和 Make.Field.Percent 表单适配器必须在提交前强制执行 schema 的小数位数限制：Number.precision、Currency.decimalPlaces 和 Percent.decimalPlaces。保留原始的纯十进制输入文本，并在解析前校验其小数位数；只有通过校验后才能生成有限数字或后端认可的纯数字字符串。小数位数超限时，必须显示字段级错误 最多保留 N 位小数，并阻止该无效提交及其持久化请求；无关的只读元数据和候选项请求仍应可用。除非宿主项目明确记录了舍入策略，否则不要静默舍入。
• 数字表单控件必须在 IME 组合输入无效文本时保留最近一次已提交的数字；不得将临时组合草稿解析为更短的值。桌面/平板控件和手机文本输入应遵循 references/component-usage.md 中“数字输入与 IME 组合输入”下的行为和验证指南。

表单字段受控契约

• 这是 MakeUI 自定义表单字段控件的硬性受控规则和就绪阻断项：在新建／编辑抽屉表单或路由表单中使用的任何自定义字段组件，都必须是由宿主表单控制的适配器。它必须接收并转发宿主表单层提供的 value/onChange/onBlur/id/disabled，以及 name、ref、验证状态和无障碍属性（如果宿主表单提供了这些属性）。
• 显示的选中值必须与提交、保存、解析器或验证从表单存储中读取的值相同。如果用户、部门、查找、选择、日期、文件或自定义选择器在视觉上显示了选项，但宿主表单值仍为空或已过时，则 UI 尚未达到交付就绪状态。
• 自定义选择器组件可以在本地保存临时搜索文本、弹出层打开状态和已获取的选项缓存，但不能只在内部状态中保存选中值。每次提交时，onChange 都必须将规范化后的提交值写回宿主表单，并且必须转发 onBlur，以确保必填验证和已触碰状态正常工作。
• 此规则与组件库无关。不要通过要求使用 Ant Design、Arco、shadcn 或特定的 Form.Item/Select 来修复这些问题；应使用所选项目组件库或项目自有控件，同时遵守宿主表单受控契约。

组件结构与模块化

• 这是 MakeUI 组件化拆分 / 模块化的硬性规则，也是阻碍就绪的因素：新生成的 Make App UI 以及 apps/ui 中非平凡的生成或重构代码，必须按职责拆分，而不是实现为一个页面大小的组件。在完成拆分前，不得报告 UI 已就绪、已完成或已交付。
• 对于新的 Make App UI 项目，默认目录结构应采用平台的组件化目录树：apps/ui/src/pages 用于路由页面，apps/ui/src/components 用于外壳和功能组件，apps/ui/src/hooks 用于可复用的状态 / 数据 hook，apps/ui/src/lib/service-api 用于 UI 到 Service 的调用，apps/ui/src/router 用于路由注册，apps/ui/src/types 用于共享 UI 类型。复杂的表格或工作流组件必须添加嵌套模块，例如 config、editing、editors、hooks、renderers 和 types。
• App.tsx 不得承担数据获取、schema 规范化、表格列构建、表单 / 详情映射、Drawer 状态机、行操作行为或字段渲染等业务实现逻辑。应仅用于 providers、路由挂载和应用级外壳组合。
• 路由 / 页面文件只负责协调布局、读取路由参数、组合功能模块以及衔接最少量的页面状态。不得将数据获取、字段元数据规范化、表格列构建、表单字段映射、Drawer 状态、行操作和渲染细节全部放在一个路由 / 页面组件中。
• 将非平凡 UI 拆分为路由页面、功能模块、可复用组件、hook、数据 / API 适配器和配置构建器。优先遵循宿主项目现有的目录，例如 components、features、hooks、services、api、utils、adapters、pages 或 routes。
• 对于生成的 Make App 工作，扁平的 apps/ui/src 目录结构，或由单个 App.tsx / 路由文件同时负责外壳、路由、数据加载、表格配置、表单、抽屉、行操作和展示适配器，都是就绪缺陷。报告 UI 已完成前，必须先拆分。
• 不要堆积单文件逻辑：如果页面包含多个 UI 区域、可复用行为、复杂状态、Make 字段适配、表格配置，或创建 / 编辑 / 详情界面，应在完成更改前将这些职责提取到命名模块中。
• 非常小的局部编辑可以留在被修改的组件附近，但不得扩大现有的单体文件，也不得混合无关职责。对于新生成的 Make App 脚手架、明确要求的模块化 / 重构，或会新增多区域对象页面、表格配置、表单 / 详情工作流、可复用 Make 字段适配或其他混合职责的更改，此例外不适用。如果一个小型无关编辑涉及已有的单体文件，除非该编辑会加剧职责混杂，否则不要进行大范围拆分；应改为报告后续重构事项。

UI 默认项

• 桌面端／平板端对象列表的默认布局：导航、仅显示标题的扁平工作区标题栏、本地工具栏，然后是 canvas-table。手机布局遵循 references/mobile-defaults.md：单独组合手机工具栏和卡片列表，共用业务 Controller，但不复用或渲染桌面工具栏／表格片段。
• 侧边栏包含品牌区域、分区标签、单行对象项和清晰的当前选中状态。背景色遵循项目主题；不要默认使用深色。
• 侧边栏当前选中项的高亮必须位于侧边栏内容内边距的中央，左右内缩保持一致，且不得溢出到侧边栏边缘。
• 除非用户提出要求，侧边栏项和工作区标题不得添加副标题、描述、辅助说明、Schema 摘要或概览文案。
• 桌面端顶部标题栏的当前用户触发器必须遵循 references/app-shell-layout.md：规范化身份信息、固定 32px 头像和纯文本显示名称，不使用胶囊／卡片外壳；点击后打开包含 退出 的下拉菜单。移动端标题栏仅显示头像，并打开 references/mobile-defaults.md 中的左侧账户抽屉。makeui 仅负责视觉界面；make-app-auth 提供身份信息、运行时检测和操作处理器。
• 在桌面端／平板端，本地工具栏位于表格上方。搜索／筛选／刷新放在左侧，新建放在右侧。不要将刷新放到全局标题栏、对象标题栏、表格标题行、canvas-table 标题区域或列标题区域。此规则不会为手机卡片列表工具栏新增刷新控件。
• 默认对象列表的工作区标题栏与表格之间不得插入摘要／标题卡片。
• 除非用户提出要求，否则不要添加分页、视图、导入／导出、分组、排序、列设置或看板／分栏视图。对于通过 make-app-actions 实现的可写 Make 记录列表，多选是默认例外；其他场景仍需显式启用。
• Make 记录表格必须通过 canvas-table-integration 使用 @qfei-design/canvas-table；不要用 UI 库表格替代。
• 所有新生成的 Make App 图标默认使用 Lucide，除非用户明确要求使用其他图标库。此图标库默认值不会指定或限制 React UI 组件库。桌面端／平板端 Make 字段名称界面默认遵循 references/field-type-icons.md 中的类型映射、覆盖范围和视觉规范：图标固定间距置于名称左侧，垂直对齐且颜色相同。显式指定其他图标库时，仍须保留相同的字段类型和位置，并使用等效图标。CanvasTable 表头也属于此要求；手机字段标签和字段选项列表仍仅显示文本。
• Make 筛选必须通过 make-app-filter 使用 @qfei-design/make-app-filter；不要在 makeui 中生成本地筛选模型辅助工具、运算符矩阵、验证器、CEL 编译器／解析器或自定义高级筛选面板。
• 如果包含筛选，makeui 只负责工具栏位置。在 search-only 模式下，手机工具栏使用中等尺寸的搜索框，不包含筛选触发器、Controller 或面板。在 advanced-filter 模式下，桌面端／平板端将搜索／筛选／刷新放在一起，并关联 CanvasTable 表头；手机则在自己的紧凑工具栏中放置中等尺寸的搜索框和筛选控件。手机使用列表下拉刷新，不单独显示刷新图标／按钮，且不复用桌面端的 listToolbar 或 Popover 渲染片段。移动端筛选面板契约由 make-app-filter 负责。
• 如果包含分组，桌面端／平板端将其触发器放在筛选之后、排序之前。标准手机工具栏不显示分组。分组 UI／模型、Preset 持久化、record-groups、groupFilter 组合、CanvasTable 分组渲染以及分组叶节点分页均由 make-app-group 负责。
• 如果包含排序，桌面端／平板端将其触发器放在分组之后、刷新之前。标准手机工具栏不显示排序。排序 UI／模型、Preset 持久化、records 请求时机以及 CanvasTable 表头关联均由 make-app-sort 负责。
• 生成的 Make App 外壳和对象列表页面不得产生 body 级或整页滚动。根外壳高度固定为视口高度，并将所有溢出滚动限制在所属区域内：较长的侧边栏导航仅在侧边栏内滚动，表格数据仅在 CanvasTable／表格区域内滚动，Drawer 内容仅在 Drawer 主体内滚动，路由页面内容仅在内容区域内滚动。普通对象列表浏览时，不得让 body、应用根节点、外壳或列表页成为滚动容器。
• 即使权限或 Schema 加载失败，全局 make-app-observability 错误出口也必须保持挂载。在 0.1.9+ 中，桌面端和手机端的 MakeAppErrorNoticeViewport 会在挂载后将内容 portal 到 document.body；应由软件包定位队列，并移除旧的宿主 position／inset／padding 覆盖。通过其公开的 zIndex 属性让卡片显示在相关覆盖层之上，并在真实 Shell 中验证所有内容，包括使用 100vh + overflow: hidden 的情况。
• 在桌面端／平板端，CanvasTable 包装器和宿主必须填满可用内容宽度及剩余高度；使用 flex 高度链，或准确的 calc() 回退方案，不要使用固定表格尺寸。
• 在桌面端／平板端，CanvasTable 默认显示 showSN 序号，并通过 bodyRowHeadSuffixOptions 显示悬停时出现的行头详情图标，除非用户明确表示表格不需要此图标。
• 桌面端／平板端 CanvasTable 单元格编辑器由 canvas-table-integration 负责。Make Schema 可编辑表格使用 Track C 和 Track B；新建的 Make App UI 不得在表格单元格内自行实现输入框。手机卡片不是单元格编辑器。字段编辑器复用宿主组件库，并且仅保留 CanvasTable 自身的活动编辑边框作为单元格内边框。
• 对于默认 Make 对象的增删改查，桌面端／平板端的创建／编辑／详情界面使用右侧 Drawer 风格界面。手机端创建／编辑／详情界面使用 references/mobile-defaults.md 中的全屏路由任务页模式；不要将增删改查界面改成底部抽屉。用户明确要求时可选择其他界面。
• 桌面端创建／编辑／详情布局默认使用两列。除非用户明确要求或视口过窄，否则不要将所有字段渲染为单列全宽布局。
• 桌面端／平板端创建／编辑字段默认使用垂直标签的双列网格。常见字段占一列；TextArea、URL／链接、File、Lookup／关联选择器、长文本和富文本控件等宽字段占满整行。此桌面端／平板端网格不适用于手机布局；手机字段遵循 references/mobile-form-controls.md，不得通过折叠此网格来生成手机布局。
• 桌面端／平板端详情视图默认使用紧凑的双列标签／值网格。常见字段占一列；长文本、TextArea、URL／链接富文本值、File、Lookup／关联值、附件较多的值和富内容占满整行。手机详情遵循 references/mobile-form-controls.md：普通标签／值行中的值与右侧边缘对齐。
• 渲染前必须按照 Make 字段类型规范化详情值。{ begin, end } 等日期范围对象或 [begin, end] 等数组应显示为格式化范围，而不是原始 JSON；选择项／用户／部门／文件／Lookup 值使用相应类型的只读渲染器。空值显示为浅色的 -。
• 详情 Drawer／页面标题应在空间允许时显示所选对象或记录的完整标题。标题区域应使用弹性宽度，仅在确实溢出时使用省略号；通过工具提示或无障碍标题保留完整标题。不要创建过窄的标题区域，导致本可显示的标题被截断。
• 创建／编辑表单使用适合字段类型的控件。日期、选择项、用户、部门、文件和 Lookup 字段不得悄然退化为纯文本输入。如果文件上传需要已有记录身份，则创建模式下不显示文件上传控件。
• 创建／编辑自定义表单字段控件必须遵循 component-usage.md 中的宿主表单受控契约：传递 value/onChange/onBlur/id/disabled，保持视觉选中状态与表单存储同步；仅使用本地选中状态属于交付阻断问题。
• 手机创建／编辑／详情必须遵循 references/mobile-form-controls.md。全屏路由加单列 CSS 不等于完成了移动端适配；若仍渲染未经调整的桌面端 DatePicker、RangePicker、Select、Lookup、Upload、禁用表单详情或其他不适合当前视口的控件，则不算完成。
• 如果用户拥有创建权限，但获授权的创建字段集合为空，则必须明确呈现创建界面：显示 暂无可新建字段（或宿主界面的等效文案），禁用提交，并且不得从可见／可编辑字段集合中臆造字段。
• 对于创建、编辑和详情，在完成权限过滤和宿主能力过滤后，得出模式专属的可渲染字段集合。当该集合为空时，只在可用内容区域的中央显示明确的空状态；不要渲染字段网格、表单／详情面板、分区面板／卡片、占位 Form.Item、边框、阴影或固定最小高度的包装器。如果仍有可见只读字段，则可编辑字段集合为空不会触发此状态。保持标题栏／关闭按钮可用；仅创建模式禁用提交并显示 暂无可新建字段。
• Modal、Drawer 或滚动区域内的 Select、DatePicker、Popover、身份选择器和其他弹出控件，必须遵循 component-usage.md 和 styling-and-responsive.md 中的覆盖层 portal 契约：挂载到会裁剪溢出内容的祖先元素之外，并显示在所属界面之上。在会裁剪溢出内容的面板内提高 z-index 不是有效修复方式。
• 用户和部门选择器 UI 必须使用宿主候选项 API，并遵循 references/component-usage.md 中的规范映射；手机端使用 references/mobile-defaults.md 中的受控软件包选择器契约。宿主项目文档优先于生成的 Make App 默认传输方式。
• 不要将字段 Schema 的 options、本地演示数组、行示例、硬编码名称或过时的客户端列表用作用户／部门选择器的数据源。只有在真实候选项 API 正在加载或暂时返回空结果时，才可将当前记录值合并到选项中，以回显已有选择。如果选择器位于高级筛选或 CanvasTable 单元格编辑中，应分别通过 make-app-filter 或 canvas-table-integration 实现界面，同时保留此候选项来源契约。
• 使用 /objects/:objectKey 等动态对象路由。不要为每个对象分别生成硬编码路由组件。

不在范围内

• 身份验证、登录、令牌、登出行为、会话机制或 SDK 集成
• 前端构建产物、包脚本、发布、部署、Docker、K8s 或运行时就绪状态
• 服务结构、服务配置、服务端口、API 代理或 API 编排
• 业务字段或字段含义
• 查询/保存 API 设计
• 与业务策略相关的验证规则
• 权限检查和审批流程
• 业务数据建模或 DSL 变更
• @qfei-design/canvas-table 的实现或单元格编辑生命周期
• @qfei-design/make-app-filter 的实现、操作符矩阵、验证器、CEL 编译器/解析器或面板内部机制