make-app-group

make-app-group

将工具栏分组、可选的 CanvasTable 表头分组入口、Entity Preset 持久化、Service record-groups 请求、records groupFilter，以及 CanvasTable 分组渲染视为一项集成能力。

此 Skill 负责消费方契约和分组语义。相关 Skill 负责各自的实现层面。

此能力用于桌面端／平板端展示。标准的手机卡片列表不会渲染分组触发器、GroupTableComponent、分组 CanvasTable 或分组叶级导航。如果桌面端 Preset 已应用分组，则在手机端视图请求普通的未分组记录时，保留已保存／草稿状态；不要仅仅因为宽度变化就清除 Preset。

工作流

1. 检查宿主包管理器、规范化运行时 schema、权限门控、Preset 钩子/路由、记录生命周期、现有 CanvasTable 集成和测试。
2. 安装 @qfei-design/make-app-group@^0.1.0。先阅读其 package.ai.json，解析 package.ai.json.readOrder，按顺序读取每个声明文件，仅导入公开导出项和 styles.css，并移除复制的 UI 模型、面板、样式或拖拽行为。
3. 确保已安装 @qfei-design/canvas-table。使用 canvas-table-integration 阅读已安装包的文档，并确认 GroupTableComponent、group:load、group:data:load、setGroup、setData 和 markGroupPageLoadFailed 均为公开接口。
4. 从规范化运行时字段中构建分组候选项，要求字段具有非空键且 capabilities.groupable === true。不得以可见列、示例行、本地 DSL 或字段类型白名单作为事实来源。在桌面端/平板端宿主组件适配器中，在每个分组字段选项前显示默认的 Make 字段类型图标；不要为排序方向或其他选项添加装饰。
5. 将有序的 { fieldKey, order }[] 作为唯一的分组列表值。将其持久化到 Entity Preset 的 group 中；最多使用三个不重复字段。
6. 建立具备权限感知能力的对象上下文。加载 schema 和 Entity Preset，清理已保存的 group，然后再选择普通记录或分组记录加载方式。
7. 使用一个由点击/按压打开并受控的宿主 Popover/Drawer/Modal，搭配包中的 RecordGroupPanel、useRecordGroupController、宿主组件适配器和稳定的 resetKey。将所有通过 portal/teleport 渲染的子弹出层视为外层交互边界的一部分；绝不能因悬停、指针离开、失焦、选择子项值或关闭子弹出层而关闭外层弹出层。
8. 让 onConfirm 仅持久化 { group }，让同步的 onApplied 替换已应用的 group 状态，并让独立的数据生命周期根据对象上下文以及已应用的筛选/排序/分组作出响应。始终提供 onApplyError。
9. 当可写列表使用 make-app-actions 时，传递成功应用的 group 代次，以便 actions 清除选中项并使待处理的预检/提交操作失效。草稿编辑、取消和保存/应用失败均应保留当前 action 选中状态。
10. 在 Service 中，使用严格的传输解析器解析原始 Preset 和查询输入，根据当前运行时 schema 验证 group 字段，然后将有序的 group 值转发给 Make Data。宽松清理仅用于已保存/上游读取的数据。
11. 当已应用的 group 为空时，使用普通记录模式，并省略 Data API 的 group。当已应用的 group 非空时，先请求根分组页，然后初始化或刷新 GroupTableComponent。
12. 根据初始分组筛选条件和所选分组路径条件，使用后端 DNF 表达式规则组合 groupFilter。不要手动拼接复杂表达式。
13. 将 CanvasTable 的 group:load 接入剩余分组层级，将 group:data:load 接入普通记录，并使用包含完整分组路径的 groupFilter。
14. 添加测试参考中列出的模型、UI、Preset、Service、groupFilter、CanvasTable、权限、并发、过期请求和失败页面测试。

主题参考索引

任务 / 主题	阅读
分组值、能力来源、Lookup 支持、group: [] 语义	references/group-model.md
软件包 UI、dnd-kit、草稿生命周期、openWithField、样式	references/ui-and-drag.md
预设注水、应用前保存、分组数据时序、过时请求	references/preset-and-data-flow.md
CEL 字面量处理、DNF 追加、null 和 Lookup 路径条件	references/group-filter-expression.md
UI-Service 路由、Make Data 分组模式、验证和载荷	references/service-contract.md
CanvasTable 分组事件、根级 / 子级 / 叶级加载、渲染重置	references/canvas-table-flow.md
TDD、集成检查、回归和就绪状态	references/testing-and-pitfalls.md
工具栏位置和对象列表布局	使用 makeui
CanvasTable 构建和表头菜单机制	使用 canvas-table-integration
Service 路由 / 适配器代码和边界日志	使用 make-app-service
对象 / 列表访问策略和权限门控	使用 make-app-permission
分组记录选择操作和批量编辑	使用 make-app-actions
高级筛选表达式语义	使用 make-app-filter；生成 CEL 时阅读 makedsl 筛选参考资料
记录排序和表格标题升序 / 降序行为	使用 make-app-sort

不可妥协的不变量

• 分组为可选功能，除非用户请求启用或分组已存在。在桌面端／平板端，分组启用后，应同时提供工具栏分组、Preset 持久化、Service 契约、分组 CanvasTable 渲染和分组叶子分页。
• 手机／phone 标准列表应隐藏且不渲染分组控件或分组 CanvasTable／GroupTableComponent。phone records 查询使用普通 records 模式，并省略 group／groupFilter，且不得修改已保存的桌面端／平板端分组 Preset。
• 仅使用有序的 { fieldKey, order }[]。拒绝旧版 groupFieldKey、field、sort、方向别名、映射对象、重复项、未知属性，以及超过三项的数组。
• Data API 分组项只允许包含 fieldKey 和 order；分组时 properties 始终无效，即使它是空字符串也不例外。
• 数组顺序即层级契约：索引 0 是根分组，索引 1 是第二层，索引 2 是第三层。
• 只有当字段的规范化运行时 schema 具有非空 key 且 capabilities.groupable === true 时，才可按该字段分组。即使 UI 或 Preset 中包含过时值，Service 仍具有最终决定权。
• 平台指南不得一概禁用 Make.Field.Lookup。Lookup 分组支持取决于运行时 schema capability 和后端关系规则。项目可以添加临时 V1 策略，但本 Skill 不得将其设为平台规则。
• 已应用分组和面板草稿应彼此独立。编辑、拖动、添加、删除、清除、真正的外部点击、子级浮层交互以及标头 openWithField，都不得在确认前请求分组或 records。
• 外层分组浮层应由受控状态管理，且只能通过明确的点击／按下操作打开，绝不能通过悬停或聚焦打开。确认成功后，或验证为真正的外部指针交互后，应关闭浮层。通过 portal／teleport 渲染的 Select、picker、菜单、tooltip、popover 或拖动浮层仍属于受控交互边界，不得关闭分组面板。
• 使用 package useRecordGroupController，并传入 resetKey、onConfirm、同步的 onApplied 和必需的 onApplyError。不得在 onConfirm 或 onApplied 中发送分组数据请求。
• 先保存，再应用。Preset 写入应采用稀疏形式，清除时使用 Preset { group: [] }，filter、sort 和 group 之间不得相互覆盖。
• Data API records 模式中，group 应省略或设为 null。Data API 的 group: [] 无效，绝不能将其用作分组叶子记录请求。
• 分组模式请求应省略 fields 和普通 sort；Make Data 在分组模式下会忽略它们。叶子记录请求应恢复为普通 records 模式，并可包含 fields、filter、groupFilter、sort 和 pagination。
• Schema／Preset 水合和访问权限检查应先于首次 records 或分组请求。实体或权限变更会使旧 generation、面板、标头菜单、已应用状态、分组缓存、叶子缓存和表格查询上下文失效。
• groupFilter 与 filter 相互独立。不得将它们合并为一个表达式。后端会以 AND 关系应用它们。
• 将分组路径条件追加到现有 OR 表达式时，必须保留 DNF：将新条件追加到每个顶层 OR 分支，而不是生成后端无法解析的嵌套表达式。
• 分组叶子页加载失败或被取消时，必须调用 markGroupPageLoadFailed(groupValue, page)，以便 CanvasTable 能够重试该页面。
• 除非产品明确规定并测试了分组编辑生命周期，否则分组 V1 应将单元格编辑视为禁用。
• 可写的分组记录列表可以使用默认的 make-app-actions 选择工作流。在 CanvasTable 1.3.1 下，GroupTableComponent 不支持 Shift 范围选择；不得在宿主中模拟此功能。
• 存在该操作工作流时，只有成功应用的分组 generation 才会清除选择并使待处理的操作工作失效。分组草稿、取消、验证／Preset 失败以及分组查询失败都应保留选择。
• 在 UI-Service 适配器以及 Service 路由／适配器边界添加安全日志，记录进入、成功、失败和过期结果分支。绝不得记录 cookie、token、机密信息、Authorization、完整表达式或记录载荷。

移交事项

• 与 makeui 配合：在桌面端和平板端，将可选的分组触发器放在筛选器之后、排序器之前；标准手机视图会隐藏该触发器，并使用普通记录卡片。本 Skill 负责分组行为和状态。
• 与 canvas-table-integration 配合：该 Skill 负责构建 GroupTableComponent 并处理 CanvasTable 公共 API 的机制；本 Skill 负责确定何时发起请求、请求什么内容，以及如何将分组结果转换为表格。
• 与 make-app-service 配合：本 Skill 定义分组查询和预设语义；Service 负责严格解析、路由、Make 适配器、架构能力验证、日志和测试。
• 与 make-app-permission 配合：该 Skill 负责访问策略；本 Skill 将权限启用/禁用视为对象上下文转换，并据此使分组请求失效。
• 与 make-app-filter 配合：筛选和分组共享表达式语义，但使用不同的请求字段。筛选面板状态以 filter 持久化；分组路径状态是临时的，并通过 groupFilter 发送。
• 与 make-app-sort 配合：排序和分组共享一个 Entity Preset 生命周期，但分别更新维度。排序仅适用于普通记录和分组后的叶记录，不适用于分组模式请求。
• 与 make-app-actions 配合：仅适用于使用操作工作流的可写分组列表。成功应用一个分组代次后，将其移交给该 Skill，以便操作清除选择并使待处理工作失效。草稿和失败路径会保留当前选择；本 Skill 不会触发 CanvasTable 选择事件。