make-app-sort

make-app-sort

将工具栏排序、CanvasTable 表头排序、Entity Preset 持久化和 Service 记录 sort 请求视为一项集成能力。此 Skill 负责使用方契约和排序语义；相关 Skill 负责各自实现部分。

此能力仅在桌面端／平板端提供控件。标准手机卡片列表不会显示排序触发器或 CanvasTable 表头操作。已应用的排序仍可继续影响共享的普通记录查询，避免切换屏幕宽度时数据意外重新排序；但除非用户明确要求自定义移动端排序体验，否则手机用户无法编辑排序状态。

工作流

1. 检查宿主包管理器、规范化运行时架构、权限门控、Preset 钩子／路由、记录请求生命周期、CanvasTable 表头 API 和测试。
2. 安装 @qfei-design/make-app-sort@^0.1.0。读取其 package.ai.json 和每个 package.ai.json.readOrder 条目，仅导入公开导出项和 styles.css，并移除复制而来的 UI 模型、面板、样式或拖动行为。
3. 仅使用具有非空键且 capabilities.sortable === true 的规范化运行时字段构建候选项。在桌面端／平板端宿主组件适配器中，每个排序字段选项前显示默认的 Make 字段类型图标；不要为排序方向或其他选项添加装饰。
4. 建立考虑权限的对象上下文。加载架构和 Entity Preset，清理已保存的排序，然后才允许发起首次记录请求。
5. 使用一个由宿主拥有的外层 Popover，配合包中的 RecordSortPanel、useRecordSortController、宿主的公开组件适配器，以及一个上下文实体或访问上下文变化时会变更的稳定 resetKey 令牌。
6. 通过 openWithField(fieldKey, order?) 将 CanvasTable 升序／降序操作连接到同一控制器；表头操作只编辑草稿。
7. 让 onConfirm 仅持久化 { sort }，让同步的 onApplied 替换已应用状态，并让独立的记录生命周期响应对象上下文以及已应用的筛选／排序。始终提供 onApplyError。
8. 在 Service 中，使用严格的传输解析器解析原始 PATCH 和记录输入，根据当前运行时架构验证字段，然后将有序值转发给 Make Data。仅对已保存／上游读取使用宽容清理。
9. 如果可写列表使用 make-app-actions，应移交已成功应用的排序代次，以便操作在新查询可执行前清除选择并使待处理的预检／提交工作失效。草稿编辑、取消以及保存／应用失败都应保留当前操作选择。
10. 添加测试参考中列出的模型、UI、表头、Preset、权限、并发、Service、过期请求和有条件的操作选择测试。

主题参考索引

任务／主题	阅读
排序值、可排序能力、验证、清理、最多五级	references/sort-model.md
面板 UI、dnd-kit、草稿生命周期、openWithField、样式	references/ui-and-drag.md
Preset 加载、先保存后应用、记录时序、过期请求	references/preset-and-data-flow.md
UI-Service 路由、Make Preset 适配器、记录验证和负载	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 分组、record-groups、groupFilter	使用 make-app-group
可写列表选择操作和已应用查询失效	使用 make-app-actions

不可妥协的约束

• 排序是可选功能，除非用户提出要求或已有此功能。对于桌面端／平板端，一旦纳入范围，就必须同时实现工具栏排序、CanvasTable 表头联动、Preset 持久化和记录排序。
• 手机端标准列表应隐藏且不渲染排序控件或 CanvasTable 表头操作。不要将桌面端排序按钮放入手机端工具栏。
• 仅使用 { fieldKey, order }[]。拒绝旧格式 { field, order }、未知键、无效方向、重复项，以及超过 5 项的数组。
• 将数组顺序视为优先级：索引 0 的排序优先级最高。
• 仅当字段的规范化运行时 schema 有非空 key，且 capabilities.sortable === true 时，该字段才可排序。不得使用字段类型允许列表、可见表格列、示例行或本地 DSL 作为事实来源。
• 将已应用的排序与面板草稿分开管理。编辑、拖动、添加、删除、清空、点击外部和按 Escape 时，都不得在确认前查询记录。
• 使用包中的 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 路由／适配器边界添加安全日志，记录进入、成功、失败和结果过期分支。绝不记录 Cookie、令牌、密钥、Authorization 或完整的敏感记录数据。

分组边界

分组由 make-app-group 和 capabilities.groupable 管理；此 Skill 不得添加分组 UI、record-groups 载荷、groupFilter 表达式组合或 Preset group 写入。稀疏排序更新必须保留现有分组维度。

交接

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