make-app-actions

make-app-actions

将记录操作、权限行为、行级预检、单条编辑/删除，以及桌面端/平板端选择和批量编辑视为一项集成的 Make 记录列表能力。桌面端/平板端的可写列表使用 CanvasTable 选择和标准操作栏。手机列表使用卡片，并且仅复用无头单条记录操作模型；标准手机体验不提供记录选择或批量操作。

此 Skill 负责消费者侧的操作工作流。该 package 负责可复用的选择/操作模型和标准 UI；宿主负责主体状态、Service 请求、查询上下文、字段控件、业务反馈和列表刷新。

工作流

业务新建保存/首次发起、流程状态及审批锁边界使用 make-app-approval。此 skill 继续负责普通记录操作；其行预检、快捷编辑和批量操作不得绕过真实审批状态/锁。审批新建按钮不从普通选择操作栏模型推导，也不在此实现任务审批动作。

1. 检查宿主呈现模式、包管理器、Node/React/UI 库兼容性、 已安装的 CanvasTable 版本和文档、规范化后的运行时架构、主要 权限模型、记录查询状态、Service 路由、编辑/详情界面 以及相关测试。
2. 安装 @qfei-design/make-app-actions@^0.3.1；桌面/平板设备上的 CanvasTable 集成还需要 @qfei-design/canvas-table@^1.3.1。 仅限手机端的无头操作任务不需要添加表格依赖。 先阅读每个相关的已安装 package.json， 并验证其解析出的版本符合所需范围；然后 阅读 package.ai.json，解析 package.ai.json.readOrder，按顺序阅读其中声明的每个 文件，并且仅使用公共导出。更改包集成之前，先阅读 references/package-integration.md。
3. 对于桌面/平板设备，使用已发布的 CanvasTable 1.3.1 契约，其中包含 包适配器所需的公共选择快照、clearSelection、setRowColors 和 clearRowColors API。其公共文档还必须保证业务行颜色始终显示在 选择和悬停背景之上。如果缺少清理 API 或优先级保证，请报告 CanvasTable 升级阻塞问题。使用 canvas-table-integration 处理 CanvasTable 机制；不要深度导入表格内部模块，也不要通过宿主 CSS 修补渲染顺序。
4. 在桌面/平板设备上，启用多选，并使用 resolveCanvasSelectedRecordSnapshot 规范化每个公共 Canvas 选择事件。 保留 selectionIntent；绝不能根据已选数量和总数推断全选。按照 references/selection-and-operation-snapshot.md 中的生命周期处理 CanvasTable 实例 替换和同一查询下 totalCount 的变化；绝不能将操作所拥有的选择重放到替换后的实例中。通过已安装 CanvasTable 的公共契约，将一次受支持的 Shift 范围手势限制为最多 200 条记录；如果该契约无法强制执行此限制，请报告功能阻塞问题，不要在宿主中模拟私有选择状态。CanvasTable 1.3.1 的 GroupTableComponent 不支持 Shift 范围选择；除非已安装的分组表格公共契约 明确新增此功能，否则不要在宿主中模拟 Shift 范围选择。 对于新 App，使用宿主的 ActionButton/IconButton 封装组件和默认 Lucide 图标，通过 MakeAppActionComponents 渲染包的通用 RecordSelectionActionBar，包括 Ant Design 宿主。已发布的 AntD 操作栏适配器内置了 Ant Design 图标；仅在本次图标工作范围之外的现有集成中保留它。
5. 根据当前缓存的主体快照，构建单条记录编辑、单条记录删除以及桌面/平板设备上的多条记录批量编辑操作。让 data.record.update、 data.record.delete 和 data.record.bulkUpdate 相互独立。
6. 在桌面/平板设备上，点击操作时验证解析后的选择和包的批量上限。在手机上，只解析点击的/当前记录； 不应用选择或批量上限。执行适用的包级本地行验证，然后在任何 异步预检查开始前，冻结一个不可变的操作快照。
7. 打开单条记录编辑或批量编辑 UI 前，将完整的冻结目标发送给一个宿主 Service 进行预检查。不要从 UI 调用 Make，也不要将被拒绝的多条记录请求拆分为诊断请求。对于显式选择， 将文档所述 HTTP 200 业务拒绝中的权威 noPermissionRecordIds 映射为精确的整行错误红色反馈。全选拒绝不包含行 ID，仅显示 toast。保留预检查/批量请求中已完成的 HTTP 失败；显式模式下的对象/操作拒绝可能是 HTTP 403，并带有 reason: "permission_denied"，而不是行代码 20000032。
8. 对于批量编辑，根据运行时读取/更新权限和包能力筛选字段。新的 Make App 宿主使用包的公共通用 RecordBatchEditModal，并注入所选设计系统的 Modal、 FieldSelect 和 ModeControl，以满足默认字段图标约定。 这也包括 Ant Design 宿主：0.3.1 中的 AntdRecordBatchEditModal 不提供公共的 FieldSelect 自定义入口。绝不要在其他设计系统中混用 AntD，也不要复制包的模态框。 宿主必须使用其已安装设计系统的公共浮层 API，使注入的弹出层脱离裁剪祖先，并显示在所属对话框之上，同时保留焦点、Escape 和外部点击行为。 桌面/平板设备上的批量编辑字段选项在每个字段名称前显示默认的 Make 字段类型图标；值、模式和候选项均不显示字段图标。 提交时复用冻结的操作快照。
9. 发送一个宿主 Service 批量请求。Service 发送一个 Make /data/v1/field 请求；不要循环执行单条记录更新，也不要将 runRecordBatchMutation 用作 Make 的默认路径。
10. 在选择、对象、访问权限或查询上下文发生变化时，使过期的预检查和提交失效。关键字、筛选、排序、分组或对象上下文发生变化时清除选择。成功的已应用查询交接会清除选择； 草稿编辑以及失败的保存/查询不会重新定义操作目标。
11. 对于手机卡片和详情任务页面，请阅读 references/mobile-card-actions.md： 对点击的/当前记录使用包根目录的无头核心；绝不挂载 CanvasTable 或选择操作栏，也不要提供记录多选或批量操作。卡片操作和详情操作是围绕同一条记录生命周期的两个独立界面；彼此都不能取代对方。
12. 在桌面/平板设备上，如果详情界面的编辑/删除操作由选择栏负责，则从详情界面移除这些命令。保留详情打开作为查看/展示操作。
13. 在报告工作流完成之前，先添加 references/testing-and-pitfalls.md 中的测试。

主题参考表

任务 / 主题	阅读
软件包安装、UI 库兼容性、公共导入、宿主 / 软件包边界	references/package-integration.md
独立操作权限、缓存的主体、操作可见性、拒绝操作的 UI	references/action-permission-model.md
Canvas 选择意图、200 条上限、查询标识、不可变操作快照	references/selection-and-operation-snapshot.md
UI-Service 预检查和批量路由、Make 载荷、错误、调用次数不变量	references/service-contract.md
单项操作行为、批量模态框字段、提交生命周期、过期选择安全性	references/batch-edit-flow.md
手机卡片和详情中的单项编辑 / 删除，不支持记录选择或批量操作	references/mobile-card-actions.md
TDD 矩阵、集成检查、竞态、就绪阻塞项	references/testing-and-pitfalls.md
Canvas 选择事件、clearSelection、行颜色、Shift 选择	使用 canvas-table-integration
主体 IAM 端点、权限资源匹配、字段访问	使用 make-app-permission
服务分层、适配器、验证、日志、请求上下文	使用 make-app-service
工具栏 / 表格位置、Drawer 布局、字段控件	使用 makeui
全局筛选表达式和已应用的筛选状态	使用 make-app-filter
已应用的排序状态	使用 make-app-sort
分组路径和 groupFilter 组合	使用 make-app-group

不容妥协的不变量

• 已安装的 package.json 是权威的软件包版本来源。对于此 Skill，在读取 package.ai.json 之前，先解析 @qfei-design/make-app-actions@^0.3.1；其已发布的 0.3.1 清单中的版本和安装字段已过时，仍为 0.3.0，不得因此降级集成。
• 在桌面端／平板端，解析 @qfei-design/canvas-table@^1.3.1，以获取已发布的行颜色 优先级和 clearRowColors 契约。对于可写的 CanvasTable 记录操作列表，不得接受 1.3.0，也不得在宿主代码中模拟缺失的行为。仅限手机端的无头单记录操作集成不需要 CanvasTable。
• 桌面端／平板端的 Make CanvasTable 记录列表默认启用可选择行和标准操作栏。严格只读的列表只有在 只读是对象／产品能力，而不只是当前用户缺少写入权限时，才可选择显式关闭；即使用户没有可用操作， 仍使用方案二。
• 在桌面端／平板端，恰好选中一条记录时，根据编辑和删除各自独立的权限显示相应操作。选中两条或 更多记录时，仅依据 data.record.bulkUpdate 和可用于批量编辑的字段显示批量编辑。
• 在桌面端／平板端，如果没有可用的选中项操作，仍使用方案二：显示选中数量、锁图标、 暂无可用的操作 和关闭控件。
• 手机端记录列表使用卡片，而非 CanvasTable。它们不提供记录多选、全选、Shift 选择、选择操作栏、 批量编辑或任何其他批量操作。这不影响表单字段的多选。
• 手机卡片仅通过软件包无头核心解析被点击的记录。它可以分别显示单条记录的编辑／删除操作，但不得 根据旧的桌面端选择快照确定操作目标。卸载桌面端 CanvasTable 时清除操作选择；返回时，新实例从空选择开始。
• 操作点击和提交时使用当前缓存的主体权限。不得在每次操作时重新获取主体。
• 将软件包的本地行检查视为即时反馈，而非最终授权。行预检查和最终写入端点仍具有权威性。
• 预检查前冻结目标模式、ID 或排除项、选中数量、对象／实体标识、filter 和 groupFilter。预检查和 mutation 必须使用同一快照。不得臆造未文档化的 snapshotToken／不透明令牌，也不得用它替代目标； 只有已安装宿主的 Service 契约明确定义并验证了此类令牌时，才可使用。
• 保持 filter 和 groupFilter 相互独立且原样不变。仅当目标为全选时才接受它们，并由后端语义组合， 不得通过 UI 或 Service 字符串重写来组合。
• 显式选择列表和排除列表各自最多允许 200 个 ID。显式选择超过 200 个时应阻止操作，不打开模态框， 并保留选择，以便用户取消选择行。
• 一次受支持的 Shift 范围选择手势最多选择 200 条记录。通过已安装 CanvasTable 的公开契约实现此限制； 如果不具备该能力，不得在宿主代码中添加自有的键盘／范围选择内部逻辑。
• 显式预检查返回 HTTP 200、业务拒绝，且包含权威的 noPermissionRecordIds 时，应阻止操作、显示规范的拒绝提示， 并仅为这些确切行应用宿主错误红色行样式。被拒绝的行在选中或悬停时仍须显示此语义颜色。通过 clearRowColors 清除操作拥有的命令颜色；不得使用 setRowColors(rowKeys, undefined) 清理。全选返回 403 时不会返回行 ID，应显示相同提示，且绝不得臆造要高亮的行。
• 一次操作最多发起一个 Make 权限预检查请求和一个最终 Make mutation 请求。绝不得使用逐 ID 诊断或逐记录更新循环。
• 选择／查询竞态不得打开过时的 UI、应用过时反馈、清除更新后的选择，或提交与预检查目标不同的目标。
• CanvasTable 实例替换时，恰好清除一次由操作拥有的选择。同一查询的总数增长时，重新规范化当前公开快照；总数缩减时，通过已安装的公开 clearSelection() 契约清除选择。
• 批量字段使用运行时 schema 和字段权限。绝不得将不受支持的复杂字段降级为普通输入框。
• 共享批量模态框不包含自动化流程控件。
• 不得在 Arco、shadcn/ui 或其他非 AntD 宿主中引入 Ant Design。使用带宿主组件注入能力的软件包通用 RecordBatchEditModal；宿主不得复制软件包的模态框状态或验证行为。

交接

• 与 canvas-table-integration：它负责 CanvasTable 公开的选择/高亮机制；本 Skill 负责定义这些快照如何驱动操作状态和写入。
• 与 make-app-permission：它负责主体加载和权限匹配；本 Skill 使用缓存的结果，并负责独立的操作语义。
• 与 make-app-service：本 Skill 定义操作请求契约和时序；Service 负责严格解析器、Make 适配器、登录上下文转发、日志和测试。
• 与 makeui：它负责周边列表、选用的组件库、Drawer、任务路由和卡片操作的视觉效果；本 Skill 负责包级操作状态、手机端单条记录操作生命周期、桌面端/平板端标准底部操作栏的位置、支持的模态框适配器和操作生命周期。
• 与筛选/排序/分组 Skills：使用其最近一次成功应用的查询上下文。任何成功应用的查询变更都会清除选择并使待处理的操作失效；草稿编辑和保存/查询失败会保留当前选择。groupFilter 组合逻辑由 make-app-group 负责。