openxiangda-skill-kit 2.1.4 → 2.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.1.4",
+  "version": "2.1.7",
   "description": "OpenXiangda 2.0 中文 AI 技能的校验、分发与安装。",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "dependencies": {
-    "openxiangda-devkit-core": "2.12.0"
+    "openxiangda-devkit-core": "2.14.0"
   },
   "devDependencies": {
     "tsx": "4.23.12",

package/skills/openxiangda-v2/references/application-foundation.md

@@ -175,3 +175,23 @@ import 'openxiangda/mobile/styles.css';
 PC 抽屉提供“全屏 / 新开页面 / 关闭”。全屏保留当前表单；新开页面先暂存，再通过草稿 ID 恢复，内容不放入 URL。移动录入使用平台移动字段的分组行式布局、简单标题和底部操作，不放“返回列表”或桌面输入控件；草稿箱和恢复确认使用底部弹层。
 
 自定义表单可从 `openxiangda/react` 使用 `createResourceFormDraftClient(resourceCode, mode, recordId?, viewCode?)`，提供 `list/save/remove/submit`。命名视图只能恢复和提交属于当前视图的草稿；所有视图仍共用每人每个模型 20 份的上限。`save` 使用草稿 ID、expectedRevision 和可编辑字段值；`submit` 消费现有 DataTransactionOperation，不另建 CRUD 后端。此能力需要平台的 authenticated-form-drafts SQL 迁移及对应服务端版本，平台未升级时界面会明确显示暂存失败并保留输入。
+
+## 列表排序声明 {#sortable-fields}
+
+模块化列表视图用 `sortableFields` 声明用户可点击列头排序的列；`defaultSort.field`
+隐式可排序，两者重复出现不报错。与 `filterFields` / `searchableFields` 同构：
+
+```ts
+crud: [{
+  model: 'venues',
+  list: {
+    fields: ['name', 'capacity'],
+    filterFields: ['capacity'],
+    searchableFields: ['name'],
+    sortableFields: ['capacity'],
+    defaultSort: { field: 'name', order: 'asc' },
+  },
+}]
+```
+
+引用未声明字段按编译错误处理；低层 `data.resources[].fields[].sortable` 语义不变。

package/skills/openxiangda-v2/references/declarations-cheatsheet.md

@@ -7,6 +7,7 @@
 | 规则 | 正确写法 |
 | --- | --- |
 | `crud[].model` 必须引用本模块已声明的模型 | `crud: [{ model: 'repair-requests', ... }]` |
+| `user: true` 一行声明即可生成用户端标准面（“我的记录”列表 + 提交表单，双端），并自动成为登录落地页 | `crud: [{ model: 'supply-requests', user: true, ... }]`；多资源时 `user: { home: true }` 指定落地资源，“仅本人”是展示过滤，行级隔离仍用 dataPolicies |
 | 视图 `list`/`form`/`detail` 的 `model` 可省略（继承视图模型）；显式声明时必须与 `crud[].model` 一致 | `list: { fields: [...] }` 即可，不必写 `model` |
 | 每个模型最多 20 个命名视图；命名视图需要稳定 `code` + `name` | `crud: [{ model: 'x', code: 'x-active', name: '进行中', ... }]` |
 | 新建视图的 `form.fields` 必须覆盖全部无默认必填字段，或显式 `generated.create: false` | 检查器会列出缺失字段 |
@@ -21,6 +22,8 @@
 | `audit.read` 可写 `true`（绑定本资源读能力）或能力数组 | `audit: { read: true }` |
 | `resource-ref.*` 必须带 `source` 来源协议 | `{ type: 'resource-ref.single', source: { kind: 'resource', resourceCode: 'repair-requests', labelField: 'title', searchFields: ['title'], pageSize: 20, loadMode: 'search' } }` |
 | `labelField` 必须指向目标资源的 `text.short` / `text.long` 字段 | 不要用流水号/选项字段当 label |
+| 列表可排序列用视图级 `sortableFields` 表达（`defaultSort.field` 隐式可排序） | `list: { sortableFields: ['capacity'], defaultSort: { field: 'name', order: 'asc' } }` |
+| 每个字段都必须带中文/业务 `label`（含子表外键与排序字段） | `{ code: 'requestId', type: 'uuid', label: '所属申请', required: true }` |
 | 子表 `subtable` 的外键是子资源的 **uuid** 字段，排序字段是**可写 number.integer** | 子资源：`{ code: 'requestId', type: 'uuid', required: true }` + `{ code: 'sortOrder', type: 'number.integer', required: true }`；父表：`subtable: { resourceCode: 'repair-items', foreignKey: 'requestId', orderField: 'sortOrder', maxRows: 20 }` |
 | 图片/附件的 `file` 限定数量与大小 | `file: { maxCount: 3, maxSizeMb: 10, accept: ['image/png', 'image/jpeg'] }` |
 
@@ -120,11 +123,12 @@ const requests = {
 const items = {
   code: 'request-items', name: '明细',
   fields: [
-    { code: 'requestId', type: 'uuid', required: true },
-    { code: 'sortOrder', type: 'number.integer', required: true },
-    { code: 'name', type: 'text.short', required: true },
-    { code: 'qty', type: 'number.integer' },
-    { code: 'price', type: 'number.decimal', precision: 12, scale: 2 },
+    // 所有字段（含子表外键/排序）都必须声明中文 label。
+    { code: 'requestId', type: 'uuid', label: '所属申请', required: true },
+    { code: 'sortOrder', type: 'number.integer', label: '排序', required: true },
+    { code: 'name', type: 'text.short', label: '名称', required: true },
+    { code: 'qty', type: 'number.integer', label: '数量' },
+    { code: 'price', type: 'number.decimal', label: '单价', precision: 12, scale: 2 },
   ],
 };
 

package/skills/openxiangda-v2/references/frontend.md

@@ -63,7 +63,22 @@ capability、应用角色和数据策略。前端只根据当前登录用户完
 可替换 Data API adapter。不要调用自定义 Nest CRUD、Function 或 Workflow 来绕过
 Data API。只有真正需要事务或外部系统的动作才使用同源 `/api`。
 
-### 自定义页面消费平台数据 {#data-access}
+### 生成式用户标准面 {#user-surface}
+
+对普通用户（登录基线角色）开放提交的 CRUD 资源，在 CRUD 视图上声明 `user: true` 即可获得
+开箱即用的用户端标准页，无需编写任何 React 代码：
+
+- “我的记录”列表（`/my/<resource>`，移动端 `/m/my/<resource>`）：默认仅显示当前登录用户
+  创建的记录（`created_by` 展示过滤），支持分页、行详情抽屉与“提交”入口。
+- “提交”表单（`/my/<resource>/submit`）：复用标准字段渲染与文件上传，成功后回到列表。
+- 首页接线：首个启用资源自动成为登录落地页与根路径；多资源时用 `user: { home: true }` 显式指定；
+  声明的 `/home` 占位路由保留可用，也可以继续用自定义页面覆盖用户端体验。
+- 能力接线自动完成：列表要求资源 read，提交要求 create；无能力的用户看到标准 403 面。
+
+注意：“仅本人”是页面展示过滤，不是授权边界。需要服务端强制行级隔离时按[数据与权限](data-authz.md)
+声明 dataPolicies。
+
+## 自定义页面消费平台数据 {#data-access}
 
 自定义报表、工具页和用户端页面从 `openxiangda/core` 导入 `createNativeResourceClient`，
 用生成契约里的 surface 直接获得该资源的权威读写客户端；行、字段与操作授权由平台在