make-app-group

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

make-app-group

Treat toolbar grouping, optional CanvasTable header grouping entry, Entity Preset persistence, Service

record-groups

requests, records

groupFilter

, and CanvasTable grouped rendering as one integrated capability.

This Skill owns the consumer contract and grouping semantics. Related Skills own their implementation surfaces.

This capability is a desktop/tablet presentation. The standard 手机／phone card list does not render a 分组 trigger,

GroupTableComponent

, grouped CanvasTable, or grouped leaf navigation. If a desktop Preset already has an applied group, keep that saved/draft state intact while the phone View requests ordinary ungrouped records; do not clear the Preset merely because the width changed.

将工具栏分组、可选的 CanvasTable 表头分组入口、Entity Preset 持久化、服务端

record-groups

请求、记录

groupFilter

以及 CanvasTable 分组渲染视为一项一体化能力。

本技能负责定义消费侧契约和分组语义，相关技能负责各自的实现层面。

本能力为桌面端/平板端展示特性。标准的手机／phone 卡片列表不会渲染分组触发器、

GroupTableComponent

、分组后的 CanvasTable 或分组叶子节点导航。如果桌面端 Preset 已经应用了分组，当手机端视图请求普通未分组记录时，需保持该已保存/草稿状态不变；不得仅因视口宽度变化就清除 Preset。

Workflow

工作流程

Inspect the host package manager, normalized runtime schema, permission gate, Preset hook/routes, records lifecycle, existing CanvasTable integration, and tests.
Install
```
@qfei-design/make-app-group@^0.1.0
```
. Read its
```
package.ai.json
```
first, parse
```
package.ai.json.readOrder
```
, read every declared file in order, import only public exports and
```
styles.css
```
, and remove copied UI model, panel, styles, or drag behavior.

Ensure

@qfei-design/canvas-table

is installed. Use

canvas-table-integration

to read the installed package docs and verify

GroupTableComponent

group:load

group:data:load

setGroup

setData

, and

markGroupPageLoadFailed

are public.

Build grouping candidates from normalized runtime fields with a non-empty key and
```
capabilities.groupable === true
```
. Do not use visible columns, sample rows, local DSL, or field-type allowlists as the source of truth.
Use ordered
```
{ fieldKey, order }[]
```
as the only grouped-list value. Persist it in Entity Preset
```
group
```
; use at most three unique fields.
Establish a permission-aware object context. Load schema and Entity Preset, sanitize saved group, and only then choose plain-record or grouped-record loading.
Use one controlled, click/press-opened host Popover/Drawer/Modal with package
```
RecordGroupPanel
```
,
```
useRecordGroupController
```
, the host component adapter, and a stable
```
resetKey
```
. Treat all portalled/teleported child popups as part of the outer interaction boundary; never close from hover, pointer leave, blur, child value selection, or child-overlay close.
Let
```
onConfirm
```
persist only
```
{ group }
```
, let synchronous
```
onApplied
```
replace applied group state, and let a separate data lifecycle react to object context plus applied filter/sort/group. Always provide
```
onApplyError
```
.
When the writable list uses
```
make-app-actions
```
, hand off the successfully applied group generation so actions clear selection and invalidate pending precheck/submit work. Draft edits, cancel, and save/apply failure preserve the current action selection.
In Service, parse raw Preset and query input with a strict transport parser, validate group fields against current runtime schema, then forward the ordered group value to Make Data. Tolerant sanitization is only for saved/upstream reads.
When applied group is empty, use ordinary records mode and omit Data API
```
group
```
. When applied group is non-empty, first request the root group page, then initialize or refresh
```
GroupTableComponent
```
.
Compose
```
groupFilter
```
from the initial group filter plus selected group path conditions using the backend DNF expression rules. Do not concatenate complex expressions by hand.
Wire CanvasTable
```
group:load
```
to the remaining group levels and
```
group:data:load
```
to ordinary records with full group path
```
groupFilter
```
.
Add the model, UI, Preset, Service, groupFilter, CanvasTable, permission, concurrency, stale request, and failure-page tests listed in the testing reference.

检查宿主包管理器、标准化运行时 schema、权限闸门、Preset 钩子/路由、记录生命周期、现有 CanvasTable 集成情况以及测试。
安装
```
@qfei-design/make-app-group@^0.1.0
```
。首先读取其
```
package.ai.json
```
，解析
```
package.ai.json.readOrder
```
，按顺序读取所有声明的文件，仅导入公开导出内容和
```
styles.css
```
，移除复制的 UI 模型、面板、样式或拖拽行为。

确保已安装

@qfei-design/canvas-table

。使用

canvas-table-integration

读取已安装包的文档，验证

GroupTableComponent

、

group:load

、

group:data:load

、

setGroup

、

setData

和

markGroupPageLoadFailed

均为公开接口。

基于标准化运行时字段构建分组候选项，这些字段需满足键非空且
```
capabilities.groupable === true
```
。不得将可见列、示例行、本地 DSL 或字段类型白名单作为事实来源。
仅使用有序的
```
{ fieldKey, order }[]
```
作为分组列表的值。将其持久化存储在 Entity Preset 的
```
group
```
字段中；最多使用三个不同的字段。
建立感知权限的对象上下文。加载 schema 和 Entity Preset，对已保存的分组做清洗处理，之后再选择加载普通记录还是分组记录。
使用一个受控的、通过点击/按压打开的宿主 Popover/Drawer/Modal，搭配包内的
```
RecordGroupPanel
```
、
```
useRecordGroupController
```
、宿主组件适配器以及稳定的
```
resetKey
```
。将所有通过 portal/teleport 渲染的子弹窗视为外部交互边界的一部分；不得因悬停、指针移出、失焦、子项值选择或子浮层关闭而关闭。
让
```
onConfirm
```
仅持久化
```
{ group }
```
，让同步的
```
onApplied
```
替换已应用的分组状态，由独立的数据生命周期响应对象上下文以及已应用的过滤/排序/分组。必须始终提供
```
onApplyError
```
。
当可写列表使用
```
make-app-actions
```
时，移交成功应用的分组版本，以便操作模块清除选择并作废待处理的预检查/提交任务。草稿编辑、取消以及保存/应用失败时，保留当前的操作选择状态。
在服务端，使用严格的传输解析器解析原始 Preset 和查询输入，对照当前运行时 schema 验证分组字段，然后将有序的分组值转发给 Make Data。宽容模式的清洗仅适用于已保存/上游读取的场景。
当已应用的分组为空时，使用普通记录模式并省略 Data API 的
```
group
```
参数。当已应用的分组非空时，先请求根分组页面，再初始化或刷新
```
GroupTableComponent
```
。
基于初始分组过滤器加上选中的分组路径条件，遵循后端 DNF 表达式规则组合生成
```
groupFilter
```
。不得手动拼接复杂表达式。
将 CanvasTable 的
```
group:load
```
绑定到剩余的分组层级，将
```
group:data:load
```
绑定到带有完整分组路径
```
groupFilter
```
的普通记录请求。
添加测试参考中列出的模型、UI、Preset、服务端、groupFilter、CanvasTable、权限、并发、过期请求、失败页面相关的测试。

Topic reference map

主题参考映射

Task / topic	Read
Group value, capability source, Lookup support, `group: []` semantics	`references/group-model.md`
Package UI, dnd-kit, draft lifecycle, `openWithField` , styles	`references/ui-and-drag.md`
Preset hydration, save-before-apply, group data timing, stale requests	`references/preset-and-data-flow.md`
CEL literal handling, DNF append, null and Lookup path conditions	`references/group-filter-expression.md`
UI-Service routes, Make Data grouping mode, validation and payload	`references/service-contract.md`
CanvasTable group events, root/child/leaf loading, render reset	`references/canvas-table-flow.md`
TDD, integration checks, regressions and readiness	`references/testing-and-pitfalls.md`
Toolbar placement and object-list layout	Use `makeui`
CanvasTable construction and header menu mechanics	Use `canvas-table-integration`
Service route/adapter code and boundary logs	Use `make-app-service`
Object/list access policy and permission gates	Use `make-app-permission`
Grouped record selection actions and batch editing	Use `make-app-actions`
Advanced-filter expression semantics	Use `make-app-filter` ; read `makedsl` filter references when generating CEL
Record sorting and table-header asc/desc behavior	Use `make-app-sort`

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

Non-negotiable invariants

不可违背的约束

Grouping is optional until requested or already present. On desktop/tablet, once in scope, deliver toolbar grouping, Preset persistence, Service contracts, grouped CanvasTable rendering, and grouped leaf pagination together.
手机／phone standard lists hide and do not render 分组/group controls or grouped CanvasTable/
```
GroupTableComponent
```
. The phone records query uses ordinary records mode and omits
```
group
```
/
```
groupFilter
```
without mutating the saved desktop/tablet group Preset.
Use only ordered
```
{ fieldKey, order }[]
```
. Reject legacy
```
groupFieldKey
```
,
```
field
```
,
```
sort
```
, direction aliases, map objects, duplicates, unknown properties, and more than three entries.
A Data API group item only allows
```
fieldKey
```
and
```
order
```
;
```
properties
```
is always invalid for grouping, including an empty string.
Array order is the hierarchy contract: index 0 is the root group, index 1 is the second level, and index 2 is the third level.
A field is groupable only when its normalized runtime schema has a non-empty key and
```
capabilities.groupable === true
```
. Service remains authoritative when the UI or Preset contains stale values.
Do not blanket-disable
```
Make.Field.Lookup
```
in platform guidance. Lookup grouping support is determined by runtime schema capability and backend relation rules. A project may add a temporary V1 policy, but this Skill must not encode that as a platform rule.
Keep applied group and panel draft separate. Editing, dragging, adding, deleting, clearing, true outside click, child-overlay interaction, and header
```
openWithField
```
must not request groups or records before confirm.
The outer grouping overlay is controlled and opens only by explicit click/press, never hover or focus. Close it after confirm succeeds or after a verified true outside pointer interaction. A Select, picker, menu, tooltip, popover, or drag overlay rendered through portal/teleport remains inside the owned interaction boundary and must not close the grouping panel.
Use package
```
useRecordGroupController
```
with
```
resetKey
```
,
```
onConfirm
```
, synchronous
```
onApplied
```
, and required
```
onApplyError
```
. Do not put group-data requests in
```
onConfirm
```
or
```
onApplied
```
.
Save before apply. Preset writes are sparse, clear uses Preset
```
{ group: [] }
```
, and filter, sort, and group never overwrite one another.
Data API records mode uses
```
group
```
omitted or
```
null
```
. Data API
```
group: []
```
is invalid and must never be used as the grouped leaf-record request.
Grouping mode requests omit
```
fields
```
and ordinary
```
sort
```
; Make Data ignores them in grouping mode. Leaf-record requests return to ordinary records mode and may include
```
fields
```
,
```
filter
```
,
```
groupFilter
```
,
```
sort
```
, and
```
pagination
```
.
Schema/Preset hydration and access checks gate the first records or group request. Entity or permission changes invalidate the old generation, panel, header menu, applied state, group cache, leaf cache, and table query context.
```
groupFilter
```
is independent from
```
filter
```
. Do not merge them into one expression. Backend applies them as an AND relationship.
Appending group path conditions to an existing OR expression must preserve DNF: append the new condition to every top-level OR branch rather than producing a nested expression that the backend cannot parse.
Grouped leaf page failure or cancellation must call
```
markGroupPageLoadFailed(groupValue, page)
```
so CanvasTable can retry that page.
Grouped V1 should treat cell editing as disabled unless the product explicitly defines and tests a grouped edit lifecycle.
Writable grouped record lists may use the default
```
make-app-actions
```
selection workflow. Under CanvasTable 1.3.1,
```
GroupTableComponent
```
does not support Shift range selection; do not emulate it in the host.
When that action workflow is present, only a successfully applied group generation clears selection and invalidates pending action work. Group drafts, cancel, validation/Preset failure, and failed group queries preserve selection.
Add safe boundary logs at UI-Service adapters and Service route/adapters for entry, success, failure, and stale-result branches. Never log cookies, tokens, secrets, Authorization, full expressions, or record payloads.

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

Handoffs

协作交接

With
```
makeui
```
: place the optional group trigger after filter and before sort on desktop/tablet; the standard phone View hides it and uses ordinary record cards. This Skill owns group behavior and state.
With
```
canvas-table-integration
```
: it owns
```
GroupTableComponent
```
construction and CanvasTable public API mechanics; this Skill owns when and what to request and how to translate grouping results into the table.
With
```
make-app-service
```
: this Skill defines group query and Preset semantics; Service owns strict parsing, routes, Make adapters, schema capability validation, logs, and tests.
With
```
make-app-permission
```
: it owns access policy; this Skill treats permission enable/disable as an object-context transition that invalidates group requests.
With
```
make-app-filter
```
: filter and group share expression semantics but stay in separate request fields. Filter panel state is persisted as
```
filter
```
; grouping path state is transient and sent as
```
groupFilter
```
.
With
```
make-app-sort
```
: sort and group share one Entity Preset lifecycle but update dimensions independently. Sort applies only to ordinary records and grouped leaf records, not to grouping-mode requests.
With
```
make-app-actions
```
: only for writable grouped lists using the action workflow, hand off a successfully applied group generation so actions clear selection and invalidate pending work. Draft and failure paths preserve the current selection; this Skill does not emit CanvasTable selection events.

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