make-app-sort

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

make-app-sort

Treat toolbar sorting, CanvasTable header sorting, Entity Preset persistence, and Service records

sort

requests as one integrated capability. This Skill owns the consumer contract and sorting semantics; related Skills own their implementation surfaces.

This capability exposes controls only on desktop/tablet. The standard 手机／phone card list does not render a 排序 trigger or CanvasTable 表头/header actions. An already-applied sort may continue to order the shared ordinary-record query so width switching does not reorder data unexpectedly, but phone users cannot edit sort state unless the user explicitly requests a custom mobile sorting experience.

将工具栏排序、CanvasTable 表头排序、Entity Preset 持久化以及 Service 端记录

sort

请求视为一体化能力。本 Skill 负责消费侧契约和排序语义；相关 Skill 负责各自的实现层面。

该能力仅在桌面端/平板端提供控制入口。标准手机端卡片列表不渲染排序触发按钮或 CanvasTable 表头操作项。已应用的排序可继续对共享的普通记录查询生效，因此切换视口宽度不会导致数据意外重排，但手机端用户无法编辑排序状态，除非用户明确要求定制移动端排序体验。

Workflow

工作流

Inspect the host package manager, normalized runtime schema, permission gate, Preset hook/routes, records request lifecycle, CanvasTable header APIs, and tests.
Install
```
@qfei-design/make-app-sort@^0.1.0
```
. Read its
```
package.ai.json
```
and every
```
package.ai.json.readOrder
```
entry, import only public exports and
```
styles.css
```
, and remove copied UI model, panel, styles, or drag behavior.
Build candidates only from normalized runtime fields with a non-empty key and
```
capabilities.sortable === true
```
.
Establish a permission-aware object context. Load schema and Entity Preset, sanitize saved sort, and only then allow the first records request.
Use one host-owned outer Popover with package
```
RecordSortPanel
```
,
```
useRecordSortController
```
, the host's public component adapter, and a stable
```
resetKey
```
token that changes whenever entity or access context changes.
Connect CanvasTable asc/desc actions to the same controller through
```
openWithField(fieldKey, order?)
```
; header actions edit draft only.
Let
```
onConfirm
```
persist only
```
{ sort }
```
, let synchronous
```
onApplied
```
replace applied state, and let a separate records lifecycle react to object context plus applied filter/sort. Always provide
```
onApplyError
```
.
In Service, parse raw PATCH and records input with a strict transport parser, validate fields against current runtime schema, then forward the ordered value to Make Data. Tolerant sanitization is only for saved/upstream reads.
When the writable list uses
```
make-app-actions
```
, hand off the successfully applied sort generation so actions clear selection and invalidate pending precheck/submit work before the new query is actionable. Draft edits, cancel, and save/apply failure preserve the current action selection.
Add the model, UI, header, Preset, permission, concurrency, Service, stale request, and conditional action-selection tests listed in the testing reference.

检查宿主包管理器、标准化运行时 schema、权限闸门、Preset 钩子/路由、记录请求生命周期、CanvasTable 表头 API 及测试用例。
安装
```
@qfei-design/make-app-sort@^0.1.0
```
。读取其
```
package.ai.json
```
及所有
```
package.ai.json.readOrder
```
条目，仅导入公共导出内容和
```
styles.css
```
，移除复制的 UI 模型、面板、样式或拖拽逻辑。
仅从具有非空 key 且
```
capabilities.sortable === true
```
的标准化运行时字段中构建候选项。
建立感知权限的对象上下文。加载 schema 和 Entity Preset，对已保存的排序做清洗，之后才允许发起首次记录请求。
使用宿主提供的外层 Popover，搭配包内的
```
RecordSortPanel
```
、
```
useRecordSortController
```
、宿主的公共组件适配器，以及一个稳定的
```
resetKey
```
令牌——当实体或访问上下文变化时，该令牌会更新。
通过
```
openWithField(fieldKey, order?)
```
将 CanvasTable 的升序/降序操作连接到同一个控制器；表头操作仅编辑草稿。
让
```
onConfirm
```
仅持久化
```
{ sort }
```
，让同步的
```
onApplied
```
替换已应用状态，让独立的记录生命周期响应对象上下文及已应用的筛选/排序。始终提供
```
onApplyError
```
。
在 Service 中，使用严格的传输解析器解析原始 PATCH 请求和记录输入，对照当前运行时 schema 验证字段，然后将排序后的值转发给 Make Data。容错清洗仅用于已保存/上游读取的场景。
当可写列表使用
```
make-app-actions
```
时，移交成功应用的排序版本，以便操作在新查询生效前清除选中状态并作废待处理的预检查/提交任务。草稿编辑、取消以及保存/应用失败时，保留当前操作的选中状态。
添加测试参考中列出的模型、UI、表头、Preset、权限、并发、Service、过期请求及条件化操作选中测试。

Topic reference map

主题参考映射

Task / topic	Read
Sort value, sortable capability, validation, sanitization, five-level limit	`references/sort-model.md`
Panel UI, dnd-kit, draft lifecycle, `openWithField` , styles	`references/ui-and-drag.md`
Preset hydration, save-before-apply, records timing, stale requests	`references/preset-and-data-flow.md`
UI-Service routes, Make Preset adapter, records validation and payload	`references/service-contract.md`
TDD, integration checks, regressions and readiness	`references/testing-and-pitfalls.md`
Toolbar placement and object-list layout	Use `makeui`
CanvasTable header menu and suffix 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`
Advanced-filter state and Preset filter persistence	Use `make-app-filter`
Grouping state, Preset group, record-groups, groupFilter	Use `make-app-group`
Writable-list selection actions and applied-query invalidation	Use `make-app-actions`

任务/主题	参考文档
排序值、可排序能力、验证、清洗、五级限制	`references/sort-model.md`
面板 UI、dnd-kit、草稿生命周期、 `openWithField` 、样式	`references/ui-and-drag.md`
Preset 水合、应用前保存、记录请求时序、过期请求	`references/preset-and-data-flow.md`
UI-Service 路由、Make Preset 适配器、记录验证与 payload	`references/service-contract.md`
TDD、集成检查、回归测试与就绪度	`references/testing-and-pitfalls.md`
工具栏位置与对象列表布局	使用 `makeui`
CanvasTable 表头菜单与后缀机制	使用 `canvas-table-integration`
Service 路由/适配器代码与边界日志	使用 `make-app-service`
对象/列表访问策略与权限闸门	使用 `make-app-permission`
高级筛选状态与 Preset 筛选持久化	使用 `make-app-filter`
分组状态、Preset 分组、记录组、groupFilter	使用 `make-app-group`
可写列表选中操作与已应用查询失效	使用 `make-app-actions`

Non-negotiable invariants

不可违背的约束

Sorting is optional until requested or already present. On desktop/tablet, once in scope, deliver toolbar sorting, CanvasTable header linkage, Preset persistence, and records sort together.
手机／phone standard lists hide and do not render 排序/sort controls or CanvasTable 表头/header actions. Do not stack the desktop sort button into the phone toolbar.
Use only
```
{ fieldKey, order }[]
```
. Reject legacy
```
{ field, order }
```
, unknown keys, invalid directions, duplicates, and more than five entries.
Treat array order as priority: index 0 is the highest-priority sort.
A field is sortable only when its normalized runtime schema has a non-empty key and
```
capabilities.sortable === true
```
. Do not use a field-type allowlist, visible table columns, sample rows, or local DSL as the source of truth.
Keep applied sort and panel draft separate. Editing, dragging, adding, deleting, clearing, outside click, and escape must not query records before confirm.

Use package

useRecordSortController

with

resetKey

onConfirm

, synchronous

onApplied

, and required

onApplyError

. Do not put records requests in

onConfirm

onApplied

Save before apply. Preset writes are sparse, clear uses
```
sort: []
```
, and filter, sort, and group dimensions never overwrite one another. Shared saving and error state must remain correct when filter and sort saves overlap.
Schema/Preset hydration and access checks gate the first records request. Object or permission changes invalidate the old generation, panel, header menu, applied state, and table query context, including
```
A -> B -> A
```
.
CanvasTable header asc/desc actions only open or update the shared panel draft through
```
openWithField
```
; they do not bypass confirm or call records directly.
Package helpers own UI model/draft behavior. Service owns strict raw-input parsing; never use tolerant sanitization to accept an invalid PATCH or records query.
Search remains session-only. Do not persist keyword search in Entity Preset.
If
```
make-app-actions
```
is present, only a successfully applied sort generation clears its selection and invalidates pending action work. Draft edits, panel cancel, validation failure, Preset save failure, and failed list queries do not clear or redefine the current action 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, or full sensitive record data.

排序是可选功能，仅在被请求或已存在时启用。在桌面端/平板端，一旦纳入范围，需同时提供工具栏排序、CanvasTable 表头联动、Preset 持久化和记录排序能力。
手机端标准列表会隐藏且不渲染排序控件或 CanvasTable 表头操作项。不得将桌面端排序按钮堆叠到手机端工具栏中。
仅使用
```
{ fieldKey, order }[]
```
格式。拒绝旧版
```
{ field, order }
```
格式、未知 key、无效排序方向、重复项以及超过5条的条目。
数组顺序即为优先级：索引0为最高优先级排序项。
仅当字段的标准化运行时 schema 具有非空 key 且
```
capabilities.sortable === true
```
时，该字段才可排序。不得将字段类型白名单、可见表格列、示例行或本地 DSL 作为事实来源。
已应用排序与面板草稿需相互隔离。编辑、拖拽、新增、删除、清空、点击外部区域、按 Esc 键等操作，在确认前不得触发记录查询。
使用包提供的
```
useRecordSortController
```
，需传入
```
resetKey
```
、
```
onConfirm
```
、同步的
```
onApplied
```
以及必填的
```
onApplyError
```
。不得在
```
onConfirm
```
或
```
onApplied
```
中发起记录请求。
先保存再应用。Preset 写入采用稀疏更新，清空操作为
```
sort: []
```
，筛选、排序和分组维度永远不会互相覆盖。当筛选和排序的保存操作重叠时，共享的保存状态和错误状态必须保持正确。
Schema/Preset 水合与访问检查是首次记录请求的前置条件。对象或权限变更会使旧版本、面板、表头菜单、已应用状态及表格查询上下文失效，包括
```
A -> B -> A
```
这种场景。
CanvasTable 表头的升序/降序操作仅通过
```
openWithField
```
打开或更新共享面板草稿；不得绕过确认步骤或直接调用记录查询。
包内辅助函数负责 UI 模型/草稿行为。Service 负责严格的原始输入解析；绝对不能使用容错清洗来接受无效的 PATCH 请求或记录查询。
搜索仅在会话内有效。不得将关键词搜索持久化到 Entity Preset 中。
若存在
```
make-app-actions
```
，仅成功应用的排序版本会清除其选中状态并作废待处理的操作任务。草稿编辑、面板取消、验证失败、Preset 保存失败以及列表查询失败，均不会清除或重新定义当前操作的选中状态。
在 UI-Service 适配器和 Service 路由/适配器中，为入口、成功、失败和过期结果分支添加安全边界日志。绝对不得记录 cookies、tokens、密钥、Authorization 或完整的敏感记录数据。

Grouping boundary

分组边界

Grouping is owned by

make-app-group

and

capabilities.groupable

; this Skill must not add group UI, record-groups payloads,

groupFilter

expression composition, or Preset

group

writes. Sparse sort updates preserve the existing group dimension.

分组功能由

make-app-group

和

capabilities.groupable

负责；本 Skill 不得添加分组 UI、记录组 payloads、

groupFilter

表达式组合或 Preset

group

写入。稀疏排序更新会保留现有的分组维度。

Handoffs

协作交接

With
```
makeui
```
: place the optional sort trigger after filter and before refresh on desktop/tablet; the standard phone View hides it. This Skill owns sort behavior and state.
With
```
canvas-table-integration
```
: it owns header/menu mechanics; this Skill owns the call to the shared sort panel.
With
```
make-app-service
```
: this Skill defines the contract; 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 sort requests.
With
```
make-app-filter
```
: filter and sort share one Entity Preset lifecycle but update dimensions independently and may save concurrently.
With
```
make-app-group
```
: group and sort share one Entity Preset lifecycle but update dimensions independently. Sort applies to ordinary records and grouped leaf records, while grouping-mode record-groups requests ignore ordinary sort.
With
```
make-app-actions
```
: only for writable lists using the action workflow, hand off a successfully applied sort generation before the new query becomes actionable so actions clear selection and invalidate pending work. Draft and failure paths preserve selection; this Skill does not manipulate CanvasTable selection APIs directly.

与
```
makeui
```
协作：在桌面端/平板端，将可选的排序触发按钮放在筛选之后、刷新之前；标准手机端视图会隐藏该按钮。本 Skill 负责排序行为和状态。
与
```
canvas-table-integration
```
协作：该模块负责表头/菜单机制；本 Skill 负责调用共享排序面板。
与
```
make-app-service
```
协作：本 Skill 定义契约；Service 负责严格解析、路由、Make 适配器、schema 能力验证、日志和测试。
与
```
make-app-permission
```
协作：该模块负责访问策略；本 Skill 将权限启用/禁用视为会使排序请求失效的对象上下文变更。
与
```
make-app-filter
```
协作：筛选和排序共享同一个 Entity Preset 生命周期，但各自独立更新维度，且可并发保存。
与
```
make-app-group
```
协作：分组和排序共享同一个 Entity Preset 生命周期，但各自独立更新维度。排序适用于普通记录和分组后的叶子记录，而分组模式下的记录组请求会忽略普通排序。
与
```
make-app-actions
```
协作：仅针对使用操作工作流的可写列表，在新查询生效前移交成功应用的排序版本，以便操作清除选中状态并作废待处理任务。草稿和失败路径保留选中状态；本 Skill 不直接操作 CanvasTable 的选中 API。