openxiangda 1.0.38 → 1.0.40

package/README.md

@@ -40,14 +40,14 @@ openxiangda app snapshot APP_XXXX --profile dev --json
 
 User tokens are stored in `~/.openxiangda/profiles.json` with `0600` permissions. Shared workspace environment values, including `APP_OSS_*`, can live in `~/.openxiangda/.env` and are inherited by new workspaces. Project `.env` files still work and override the global defaults. Project state is stored in `.openxiangda/state.json` and contains only profile-specific resource IDs.
 
-Feedback can be sent to a DingTalk custom robot from the CLI after user confirmation. Store the robot settings in `~/.openxiangda/.env`, not in project files:
+Feedback can be sent to a DingTalk custom robot from the CLI. AI agents should proactively report platform defects, missing capabilities, unclear design rules, repeated workarounds, implementation uncertainty, and user-visible UX gaps during development. Store the robot settings in `~/.openxiangda/.env`, not in project files:
 
 ```env
 OPENXIANGDA_FEEDBACK_DINGTALK_WEBHOOK=https://oapi.dingtalk.com/robot/send?access_token=...
 OPENXIANGDA_FEEDBACK_DINGTALK_SECRET=SEC...
 ```
 
-Preview the sanitized payload first, then submit:
+Submit directly when the report is clear; use preview when robot env is missing or you need to inspect the sanitized payload:
 
 ```bash
 openxiangda feedback preview --profile dev --summary "发布后资源 404" --description "..."
@@ -110,7 +110,7 @@ openxiangda workspace bind --profile dev --app-type APP_XXXX
 
 工程化资源放在工作区 `src/resources/` 下，由 `openxiangda resource validate|plan|publish|pull` 管理。`workspace publish` 会先构建并注册 workspace 表单/页面，再执行非破坏性资源 upsert，这样菜单、权限组、流程和表单设置可以解析最新的 profile-local ID。需要删除平台中 manifest 未声明的资源时，显式传 `--prune`。连接器页面运行时通过 `sdk.connector.invoke()` / `sdk.connector.call("connector.api")` 调用平台运行时接口，第三方密钥只保存在后端连接器配置中。
 
-多表只读查询优先声明 `src/resources/data-views/*.json` 数据视图，而不是在页面里手写多次单表查询再拼数据。数据视图适合工单+客户、订单+商品、项目+成员、报表列表、跨页面复用查询等读多写少场景。发布时 CLI 会把 `formCode` 解析为当前 profile 的 `formUuid`，平台创建 PostgreSQL materialized view；页面通过 `sdk.dataView.query(code, params)` 或 `sdk.dataSource.run()` 查询输出字段。数据视图只读，刷新后才反映源表变化，不适合单表 CRUD、写回源表、强实时状态或简单 linkedForm 下拉。
+多表只读查询和固定口径统计优先声明 `src/resources/data-views/*.json` 数据视图，而不是在页面里手写多次单表查询再拼数据。默认数据视图是行级联表视图，适合工单+客户、订单+商品、项目+成员、报表列表、跨页面复用查询等读多写少场景；`viewType: "aggregate"` 是统计聚合视图，适合按客户、状态、月份等维度预聚合 count/sum/avg/min/max。发布时 CLI 会把 `formCode` 解析为当前 profile 的 `formUuid`，平台创建 PostgreSQL materialized view；页面通过 `sdk.dataView.query(code, params)` 查询行级视图，通过 `sdk.dataView.stats(code, params)` 查询聚合视图，也可以用 `sdk.dataSource.run()` 路由 `dataView.query` / `dataView.stats`。发布前应为常用筛选、排序、统计维度和时间桶声明 `indexes`，并确认用户能接受的刷新延迟；默认不要设置低于 5 分钟的定时刷新。数据视图只读，刷新后才反映源表变化，不适合单表 CRUD、写回源表、强实时状态、临时 BI 查询或简单 linkedForm 下拉。
 
 常用数据视图命令：
 
@@ -122,6 +122,7 @@ openxiangda data-view list --profile dev
 openxiangda data-view status ticket_with_customer --profile dev
 openxiangda data-view refresh ticket_with_customer --profile dev
 openxiangda data-view query ticket_with_customer --query-json query.json --profile dev
+openxiangda data-view stats ticket_stats_by_customer --query-json stats-query.json --profile dev
 ```
 
 AI-authored automation can use code-first resources:

package/lib/cli.js

@@ -107,7 +107,7 @@ Usage:
   openxiangda automation logs <instanceId> [--automation <automationCode|automationId>] [--summary] [--redact] [--json]
   openxiangda automation diagnose <automationCode|automationId> [--redact] [--json]
   openxiangda automation publish|enable|disable <automationCode|automationId>
-  openxiangda data-view list|status|refresh|query <dataViewCode> [--profile name] [--json]
+  openxiangda data-view list|status|refresh|query|stats <dataViewCode> [--profile name] [--json]
   openxiangda permission role-list|role-create|role-bind
   openxiangda permission page-group-list|page-group-create|page-group-bind
   openxiangda permission form-group-list|form-group-create|form-group-bind
@@ -2052,7 +2052,24 @@ async function dataView(args) {
     return;
   }
 
-  fail('用法: openxiangda data-view list|status|refresh|query');
+  if (subcommand === 'stats') {
+    const [code] = positional;
+    if (!code) fail('用法: openxiangda data-view stats <dataViewCode> [--query-json file]');
+    const data = await requestWithAuth(
+      config,
+      target.profileName,
+      `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/data-views/${encodeURIComponent(code)}/stats`,
+      {
+        method: 'POST',
+        body: buildDataViewQueryBody(flags),
+      }
+    );
+    if (flags.json) return writeJson(data);
+    print(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  fail('用法: openxiangda data-view list|status|refresh|query|stats');
 }
 
 async function permission(args) {
@@ -2675,7 +2692,7 @@ async function commands(args) {
       'menu list|create|bind|delete',
       'workflow list|create|bind|pull|publish|delete|validate',
       'automation list|create|bind|pull|publish|unpublish|enable|disable|delete|validate|cron-validate',
-      'data-view list|status|refresh|query',
+      'data-view list|status|refresh|query|stats',
       'permission role-list|role-create|role-bind|role-users|role-add-users',
       'permission page-group-list|page-group-create|page-group-bind',
       'permission form-group-list|form-group-create|form-group-bind|form-summary|menu-permissions',
@@ -3379,11 +3396,24 @@ function validateResourceItem(kind, item, errors, warnings) {
   }
   if (kind === 'dataViews') {
     const definition = item.definition || item;
+    const viewType = String(definition.viewType || 'row').toLowerCase();
     if (!item.name && !definition.name) errors.push(`${label}: 缺少 name`);
     if (!definition.base) errors.push(`${label}: 缺少 base`);
-    if (!Array.isArray(definition.select) || definition.select.length === 0) {
-      errors.push(`${label}: 缺少 select`);
+    if (viewType === 'aggregate') {
+      if (Array.isArray(definition.select) && definition.select.length > 0) {
+        errors.push(`${label}: 聚合数据视图不能同时使用 select`);
+      }
+      if (!Array.isArray(definition.measures) || definition.measures.length === 0) {
+        errors.push(`${label}: 缺少 measures`);
+      }
+    } else if (viewType === 'row') {
+      if (!Array.isArray(definition.select) || definition.select.length === 0) {
+        errors.push(`${label}: 缺少 select`);
+      }
+    } else {
+      errors.push(`${label}: 不支持的 viewType: ${definition.viewType}`);
     }
+    validateDataViewPerformance(label, definition, errors, warnings);
   }
   if (kind === 'pagePermissionGroups' && !item.name) errors.push(`${label}: 缺少 name`);
   if (kind === 'formPermissionGroups') {
@@ -3405,6 +3435,105 @@ function validateResourceItem(kind, item, errors, warnings) {
   }
 }
 
+function validateDataViewPerformance(label, definition, errors, warnings) {
+  const viewType = String(definition.viewType || 'row').toLowerCase();
+  if (viewType !== 'row' && viewType !== 'aggregate') return;
+  const outputAliases = collectDataViewOutputAliases(definition, viewType);
+  const outputAliasSet = new Set(outputAliases);
+  const indexes = Array.isArray(definition.indexes)
+    ? definition.indexes.filter(index => Array.isArray(index.fields) && index.fields.length > 0)
+    : [];
+
+  for (const index of indexes) {
+    for (const field of index.fields || []) {
+      if (!outputAliasSet.has(field)) {
+        errors.push(`${label}: 索引字段不在输出字段中: ${field}`);
+      }
+    }
+  }
+
+  if (!indexes.length) {
+    warnings.push(
+      viewType === 'aggregate'
+        ? `${label}: 聚合数据视图未声明 indexes；请优先索引常用维度、时间桶或排序字段，避免统计查询扫描物化视图`
+        : `${label}: 未声明 indexes；请为常用 filters/order 字段声明索引，避免运行时查询扫描物化视图`
+    );
+  }
+
+  if (viewType === 'aggregate') {
+    const dimensionAliases = new Set(
+      (Array.isArray(definition.dimensions) ? definition.dimensions : [])
+        .map(item => item && item.as)
+        .filter(Boolean)
+    );
+    const indexesCoverDimension =
+      dimensionAliases.size === 0 ||
+      indexes.some(index => index.fields.some(field => dimensionAliases.has(field)));
+    if (indexes.length && !indexesCoverDimension) {
+      warnings.push(`${label}: 聚合数据视图 indexes 未覆盖任何 dimension；按维度筛选或排序时可能扫描物化视图`);
+    }
+    if ((definition.measures || []).some(isCountDistinctMeasure)) {
+      warnings.push(`${label}: 聚合数据视图使用 countDistinct；高基数字段刷新成本较高，请确认数据量和刷新频率`);
+    }
+  }
+
+  const refresh = definition.refresh && typeof definition.refresh === 'object' ? definition.refresh : {};
+  if (refresh.mode === 'scheduled') {
+    const intervalMs = estimateCronIntervalMsFromExpression(refresh.cron);
+    if (intervalMs !== null && intervalMs < 5 * 60 * 1000) {
+      warnings.push(`${label}: 数据视图刷新间隔低于 5 分钟；请先确认业务时间敏感度，高频刷新会增加源表和物化视图压力`);
+    }
+  }
+}
+
+function collectDataViewOutputAliases(definition, viewType) {
+  if (viewType === 'aggregate') {
+    return [
+      ...(Array.isArray(definition.dimensions) ? definition.dimensions : []),
+      ...(Array.isArray(definition.measures) ? definition.measures : []),
+    ]
+      .map(item => item && item.as)
+      .filter(Boolean);
+  }
+  return (Array.isArray(definition.select) ? definition.select : [])
+    .map(item => item && item.as)
+    .filter(Boolean);
+}
+
+function isCountDistinctMeasure(measure) {
+  const normalized = String(measure?.type || '')
+    .toLowerCase()
+    .replace(/[-_]/g, '');
+  return normalized === 'countdistinct' || normalized === 'distinctcount';
+}
+
+function estimateCronIntervalMsFromExpression(cron) {
+  const parts = String(cron || '')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+  if (parts.length < 5) return null;
+  const hasSeconds = parts.length >= 6;
+  const seconds = hasSeconds ? parts[0] : '0';
+  const minutes = hasSeconds ? parts[1] : parts[0];
+  if (seconds === '*') return 1000;
+  const secondStep = parseCronStep(seconds);
+  if (secondStep) return secondStep * 1000;
+  if (seconds === '0') {
+    if (minutes === '*') return 60 * 1000;
+    const minuteStep = parseCronStep(minutes);
+    if (minuteStep) return minuteStep * 60 * 1000;
+  }
+  return null;
+}
+
+function parseCronStep(field) {
+  const match = String(field || '').match(/^(?:\*|0)\/(\d+)$/);
+  if (!match) return null;
+  const value = Number(match[1]);
+  return Number.isFinite(value) && value > 0 ? value : null;
+}
+
 const NOTIFICATION_CHANNELS = new Set([
   'inapp',
   'email',
@@ -5936,6 +6065,7 @@ function buildDataViewQueryBody(flags = {}) {
   if (fields.length > 0) body.fields = fields;
   if (flags['filters-json']) body.filters = readJsonArg(flags['filters-json'], 'filters-json');
   if (flags['filter-json']) body.filters = readJsonArg(flags['filter-json'], 'filter-json');
+  if (flags['having-json']) body.having = readJsonArg(flags['having-json'], 'having-json');
   if (flags['condition-type']) body.conditionType = String(flags['condition-type']).toUpperCase();
   if (flags.keyword || flags.search) body.searchKeyWord = flags.keyword || flags.search;
   if (flags.page) body.currentPage = Number(flags.page);

package/openxiangda-skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openxiangda
-description: Use OpenXiangda for ANY work inside a sy-lowcode-app-workspace or any private low-code platform (OpenXiangda / 湘搭 / 私有化低代码) — publishing / 发布 / 上线 / deploying / 部署 / shipping / releasing / 上传 / pushing apps, pages, forms, workflows, automations; creating / scaffolding / 创建 / 搭建 / 新建 apps, code pages, form pages, workflow forms, JS_CODE nodes; editing / 修改 / 编辑 schemas, options, fields, layouts, menus; managing / 管理 roles, page permission groups, form permission groups, form settings, public access, data views, connectors, notifications; diagnosing / 排查 / 诊断 / 看快照 app snapshots, executions, logs, version drift, profile isolation, token / login / profile issues; running the openxiangda CLI or anything that touches `.openxiangda/state.json`, `~/.openxiangda/profiles.json`, `/openxiangda-api/v1`, `OPENXIANGDA_PROFILE / BASE_URL / ACCESS_TOKEN / APP_TYPE`, `app-workspace.config.ts`. Trigger when the user mentions OpenXiangda / 湘搭 / 私有化低代码 / 低代码平台 / sy-lowcode-app-workspace, or when the workspace contains `.openxiangda/state.json` or `app-workspace.config.ts`. Always prefer this skill over running `pnpm publish:all`, `pnpm publish:oss`, `pnpm register`, or `lowcode-workspace publish-*` directly.
+description: Use OpenXiangda for ANY work inside a sy-lowcode-app-workspace or any private low-code platform (OpenXiangda / 湘搭 / 私有化低代码) — publishing / 发布 / 上线 / deploying / 部署 / shipping / releasing / 上传 / pushing apps, pages, forms, workflows, automations; creating / scaffolding / 创建 / 搭建 / 新建 apps, code pages, form pages, workflow forms, JS_CODE nodes; editing / 修改 / 编辑 schemas, options, fields, layouts, menus; building form-entry UX / 表单录入体验 with OpenXiangda platform form components first, Ant Design / antd-mobile second, and no raw native HTML form controls in generated app code; managing / 管理 roles, page permission groups, form permission groups, form settings, public access, data views, connectors, notifications; proactively collecting and submitting platform feedback / 需求反馈 / 问题反馈 for bugs, unclear design rules, missing platform capabilities, repeated workarounds, and AI uncertainty; diagnosing / 排查 / 诊断 / 看快照 app snapshots, executions, logs, version drift, profile isolation, token / login / profile issues; running the openxiangda CLI or anything that touches `.openxiangda/state.json`, `~/.openxiangda/profiles.json`, `/openxiangda-api/v1`, `OPENXIANGDA_PROFILE / BASE_URL / ACCESS_TOKEN / APP_TYPE`, `app-workspace.config.ts`. Trigger when the user mentions OpenXiangda / 湘搭 / 私有化低代码 / 低代码平台 / sy-lowcode-app-workspace, or when the workspace contains `.openxiangda/state.json` or `app-workspace.config.ts`. Always prefer this skill over running `pnpm publish:all`, `pnpm publish:oss`, `pnpm register`, or `lowcode-workspace publish-*` directly.
 ---
 
 # OpenXiangda
@@ -28,7 +28,7 @@ For any user-facing page (form pages, workflow form pages, custom code pages), O
 | 角色 / 权限组 / 字段权限 / 数据范围 / 公开访问 | `openxiangda-permission-settings` | `openxiangda permission ...` / `openxiangda settings ...` |
 | 看应用结构 / 快照 / 对比 / 诊断 / 排查 / 报错 | `openxiangda-inspect` | `openxiangda app snapshot <APP_XXX> --profile <name> --json` |
 | 登录 / 切换平台 / profile / token / whoami | `openxiangda-core` | `openxiangda env --profile <name>` / `openxiangda auth status` |
-| 多表只读联表查询 / 报表数据源 | `openxiangda-form` (data view) | declare `src/resources/data-views/<code>.json` → `resource publish` |
+| 多表只读联表 / 固定口径统计 / 看板指标 | `openxiangda-form` (data view) | declare `src/resources/data-views/<code>.json` → `resource publish` |
 | 调外部 / 第三方 API / 钉钉 / 自建系统 | `openxiangda-page` (connector) | declare `src/resources/connectors/<code>.json` → `sdk.connector.invoke` |
 
 ### Hard rules — always
@@ -37,6 +37,8 @@ For any user-facing page (form pages, workflow form pages, custom code pages), O
 - ✅ User token lives in `~/.openxiangda/profiles.json`; project state in `.openxiangda/state.json` (IDs only).
 - ✅ Each profile (dev / prod / ...) has its own `appType` and resource IDs; never copy a `formUuid` / `pageId` / `workflowId` / `automationId` across profiles.
 - ✅ Run `openxiangda update check --json` at the start of substantial work; if `updateAvailable`, run `openxiangda update install` and `openxiangda skill install --force`.
+- ✅ For form-entry UX, pick components in this order: OpenXiangda platform form components → `antd` / `antd-mobile` wrappers → custom component only when neither exists.
+- ✅ Proactively submit platform feedback when you discover a defect, missing capability, unclear rule, repeated workaround, user-visible UX gap, or implementation uncertainty worth improving.
 
 ### Hard rules — never
 
@@ -46,6 +48,7 @@ For any user-facing page (form pages, workflow form pages, custom code pages), O
 - ❌ Using `openxiangda form create` / `form publish` / `page publish` as the normal page generation path. They are low-level repair commands.
 - ❌ Running a full publish after editing one file. Default to `--changed --dry-run` → `--changed`, or targeted `--page` / `--form`.
 - ❌ Storing tokens, AK, SK, or third-party API secrets in project files. Shared env (`APP_OSS_*`, feedback robot) goes to `~/.openxiangda/.env`.
+- ❌ Raw native HTML form controls in AI-authored workspace code (`<input>`, `<select>`, `<textarea>`, file inputs, hand-written pickers, hand-written upload controls). They are allowed only inside OpenXiangda SDK/platform component internals.
 
 ## Platform Routing
 
@@ -121,7 +124,7 @@ When the user provides a root domain such as `https://yida.wisejob.cn/`, use it
 - For routine AI edits, avoid reflexive full publish. First run `openxiangda workspace publish --profile <name> --changed --dry-run`, then use `--changed`, `--page <pageCode>`, `--form <formCode>`, or `--only pages/a,forms/b`. Use full publish only when broad shared/config changes intentionally affect many modules.
 - Never store token data in the project directory. User tokens live in `~/.openxiangda/profiles.json`; project state lives in `.openxiangda/state.json` and stores only IDs and mappings.
 - Shared workspace env values such as `APP_OSS_*` should live in `~/.openxiangda/.env` by default. Project `.env` files are only per-workspace overrides.
-- For suspected platform defects, bugs, or product optimization requests, ask the user to confirm first, then use `openxiangda feedback preview` and `openxiangda feedback submit --yes` to send a detailed DingTalk robot report. Include the command, error, relevant files, and logs/context files when available. The CLI redacts tokens, cookies, secrets, phone numbers, and emails before sending.
+- For suspected platform defects, bugs, missing capabilities, unclear design rules, repeated workarounds, AI uncertainty, or product optimization requests, proactively run `openxiangda feedback submit --yes` with a concise summary and detailed description. Include the command, error, relevant files, and logs/context files when available. If robot env is missing or submission fails, run/record `openxiangda feedback preview` and tell the user what could not be sent. After successful submission, tell the user what was reported and include the feedback fingerprint. The CLI redacts tokens, cookies, secrets, phone numbers, and emails before sending.
 - For form pages, every visible field should have a concise user-facing `placeholder`. Use `tips` only for special constraints or non-obvious business rules; do not add tips to every field.
 - Form pages should display only fields the user needs to see. Use `SelectField` / `RadioField` for enums. For data maintained by another form, such as class, college, customer, or project, use `SelectField` with `optionSource.type: "linkedForm"` so the runtime queries form data through the SDK and builds dropdown options; set `remoteSearch: true` and an explicit `searchFieldId` when the source data can be large. Do not make users maintain raw ID text fields, and do not use `AssociationFormField` for new form work.
 - Permission scope keys, computed fields, sync fields, and developer/internal fields should be present only when needed for permissions or logic, and should normally be derived from visible select/person/department fields and marked `behavior: "HIDDEN"`. For select-derived scalar keys, use `valueSync`.
@@ -129,7 +132,7 @@ When the user provides a root domain such as `https://yida.wisejob.cn/`, use it
 - All visible copy in forms and pages must be written for end users. Do not put implementation notes, developer explanations, schema descriptions, or "this area is generated by..." text into page sections, cards, labels, tips, or empty states.
 - Use logical resource codes in local files. Platform-specific IDs such as `formUuid`, `pageId`, `workflowId`, and `automationId` must be isolated by profile.
 - Put engineering-managed resources in `src/resources/` and use `openxiangda resource validate|plan|publish|pull`. `workspace publish` publishes workspace forms/pages first, then runs non-destructive resource upsert. Only pass `--prune` when the user explicitly wants local manifests to delete platform-side extras.
-- For repeated read-only multi-form queries, create a data view manifest in `src/resources/data-views/` and query it with `sdk.dataView.query` or `sdk.dataSource.run`. Use data views for joined list/report/lookup sources where refresh lag is acceptable; do not use them for single-form CRUD, simple linkedForm selects, real-time writes, or write-back. Read `references/data-views.md` before designing one.
+- For repeated read-only multi-form queries or predefined dashboard metrics, create a data view manifest in `src/resources/data-views/`. Use row views plus `sdk.dataView.query` for joined lists/lookups; use `viewType: "aggregate"` plus `sdk.dataView.stats` for count/sum/avg/min/max statistics. Before choosing scheduled refresh, confirm the user's freshness tolerance; default to manual or 10 minutes and above unless fresher data is explicitly required. Add `indexes` for common runtime filters/order fields, aggregate dimensions, and time buckets. Do not use data views for single-form CRUD, simple linkedForm selects, real-time writes, write-back, or ad-hoc BI. Read `references/data-views.md` before designing one.
 - For external APIs, create a connector manifest in `src/resources/connectors/` and call it from pages through `sdk.connector`; never put third-party API keys in page source.
 - Before scaffolding a real app, complex page, data management page, portal shell, status lifecycle, role governance, or automation, read `references/best-practices.md` and pick the architecture first. Prefer copying the relevant pattern from `examples/best-practices/` into `src/` instead of generating a single large page file.
 - Before publishing to another platform, verify the workspace is bound for that profile. Resource IDs from one profile must not be reused for another profile.
@@ -195,5 +198,5 @@ Platform domain knowledge (read these first when generating forms or pages so th
 - `references/style-system.md` — style isolation defaults, legacy namespace compatibility, and flexible Tailwind/CSS guidance. Use this before writing substantial page or form CSS.
 - `references/architecture-patterns.md` — CRUD data flow, `DataManagementList` pattern, recommended directory layout for `src/pages` and `src/forms`. Use this before scaffolding a new page or list view.
 - `references/best-practices.md` — read this before implementing app-level business patterns; it points to `examples/best-practices/` and explains when to use status fields instead of workflow.
-- `references/component-guide.md` — when to pick platform components vs. raw Ant Design vs. custom components, with the rules for option fields. Use this before introducing a new component.
+- `references/component-guide.md` — component priority ladder: platform components first, `antd` / `antd-mobile` fallback, and no raw native form controls in AI-authored app code. Use this before introducing a new component.
 - `references/troubleshooting.md` — known failure modes (missing styles, `options` runtime errors, broken option rendering, etc.) and how to fix them. Use this when something does not behave as expected.

package/openxiangda-skills/references/best-practices.md

@@ -28,6 +28,9 @@ form codes, field names, permissions, and page route names.
    - real approval workflow
    - automation / JS_CODE
    - role governance / permissions
+   - optional admin UI template:
+     `glass-home-dashboard`, `mint-analytics-dashboard`,
+     `ops-monitor-dashboard`, or `work-order-list-drawer`
 2. Read the matching files in `examples/best-practices/`.
 3. Copy the smallest useful slice into `src/`.
 4. Keep view code thin; put reusable business logic in `domain/` and platform
@@ -167,16 +170,22 @@ groups or backend-side JS_CODE checks.
 - Destructive or state-changing actions need confirmation.
 - Show processing feedback and success/failure feedback.
 - On failure, refresh or rollback the affected row instead of leaving stale UI.
+- For PC CRUD, ticket, approval, and data-management pages, use overlay drawers
+  or modals for detail, create, edit, approve/reject, and process forms. Do not
+  keep a permanent right-side detail/form column that narrows the table.
 - Keep interaction styles consistent across PC and mobile, but do not force the
   same layout component onto both viewports.
 
 ## Library Selection
 
-- Do not hand-write mature controls or engines. Use platform components for
-  personnel, departments, files, images, rich text, locations, and data lists.
-- Use `antd` / `antd-mobile` for standard controls, overlays, tables, steps,
-  tabs, forms, and feedback. Avoid raw native inputs unless the behavior is
-  truly trivial and already styled by a wrapper.
+- Do not hand-write mature controls or engines. Use platform components first
+  for form-entry fields, personnel, departments, files, images, rich text,
+  signatures, locations, standard forms, and data lists.
+- Use `antd` / `antd-mobile` as the fallback for non-platform page controls,
+  overlays, tables, steps, tabs, and temporary wrappers for missing platform
+  capabilities. AI-authored app/workspace code must not emit raw native form
+  controls; native inputs belong inside OpenXiangda SDK/platform component
+  internals only.
 - Use ECharts for charts and dashboards.
 - Use GSAP for complex timeline/scroll/sequence animations; simple transitions
   can stay in CSS. If an animation-specific skill is available, read it before
@@ -189,6 +198,21 @@ groups or backend-side JS_CODE checks.
 
 ## Template Catalog
 
+- `glass-home-dashboard`: optional default for PC admin home pages, management
+  portals, and business overviews. Includes sidebar, top search, welcome
+  banner, quick actions, KPI cards, charts, ranking, activity feed, query
+  states, and drawer form actions.
+- `mint-analytics-dashboard`: optional default for data-analysis and BI-like
+  dashboards. Includes dense metric cards, line/bar/donut charts, notifications,
+  todos, business summary, system health, query states, and drawer form actions.
+- `ops-monitor-dashboard`: optional default for realtime operations,
+  monitoring, task execution, alerts, system health, and device status. Uses
+  lightweight CSS motion by default; do not add GSAP unless a real timeline
+  requirement exists.
+- `work-order-list-drawer`: default CRUD/list template for tickets, approvals,
+  data-management pages, orders, and assets. Includes filters, toolbar, status
+  stats, table, loading/empty/error branches, and right-side overlay drawers for
+  detail, create, edit, and process forms.
 - `customer-profile`: standard form schema with validation, members,
   departments, attachments, and child table.
 - `service-ticket-lifecycle`: status lifecycle with ticket form, action-log

package/openxiangda-skills/references/component-guide.md

@@ -6,23 +6,36 @@
 
 ## 1. 核心原则
 
-1. **平台组件优先**：所有平台组件已经接入了组织架构、文件存储、权限、多端适配等平台能力，重写一遍 = 丢能力 + 后续无法维护。
-2. **基于 antd / antd-mobile 包装**：自定义组件必须站在 antd 之上，保证 PC 和移动端的基础体验一致。
-3. **成熟能力先调研开源方案**：图表、动画、拖拽、虚拟列表、富文本、日历、导入导出、复杂表格等，不要直接手写。先查当前项目依赖、官方文档和维护状态，再决定使用库或轻量封装。
-4. **样式默认走 Tailwind 原生类**：业务页面默认使用 Tailwind 原生工具类和任意值；平台变量、平台语义类和 Ant Design token 主要用于平台组件、主题兼容或确实需要统一主题时，不作为业务页面的强制范式。
-5. **谨慎覆盖组件内部 class**：组件库内部类名（`ant-select-selector` 等）是私有 API，下个版本就可能变；确实需要覆盖时要限定页面作用域，并优先考虑组件 props、`className`、CSS 变量或 `ConfigProvider`。
+1. **平台组件优先**：表单录入、平台数据选择、文件能力和数据管理默认先用 `openxiangda` 平台组件。它们已经接入组织架构、文件存储、权限、多端适配和平台数据格式，重写一遍 = 丢能力 + 后续无法维护。
+2. **antd / antd-mobile 是第二选择**：只有平台组件不存在、或正在做非平台数据的页面控件时，才使用 `antd` / `antd-mobile`。自定义组件必须包装它们，不能从原生 DOM 开始造。
+3. **AI-authored app code 禁止原生表单控件**：`src/forms/**`、`src/pages/**`、workspace 模板和示例中不要直接写 `<input>`、`<select>`、`<textarea>`、`<input type="file">`、手写 picker、手写 uploader、手写人员/部门选择器。原生控件只允许出现在 OpenXiangda SDK / 平台组件内部实现。
+4. **成熟能力先调研开源方案**：图表、动画、拖拽、虚拟列表、富文本、日历、导入导出、复杂表格等，不要直接手写。先查当前项目依赖、官方文档和维护状态，再决定使用库或轻量封装。
+5. **样式默认走 Tailwind 原生类**：业务页面默认使用 Tailwind 原生工具类和任意值；平台变量、平台语义类和 Ant Design token 主要用于平台组件、主题兼容或确实需要统一主题时，不作为业务页面的强制范式。
+6. **谨慎覆盖组件内部 class**：组件库内部类名（`ant-select-selector` 等）是私有 API，下个版本就可能变；确实需要覆盖时要限定页面作用域，并优先考虑组件 props、`className`、CSS 变量或 `ConfigProvider`。
 
 ---
 
-## 1.1 开源库选型规则
+## 1.1 组件选择梯度
+
+| 优先级 | 使用对象 | 适用场景 | 禁止事项 |
+| --- | --- | --- | --- |
+| 1 | OpenXiangda 平台组件 | 表单字段、平台数据选择、文件/图片/富文本/签名/定位、数据管理列表、标准表单容器 | 不要用 antd 或原生控件复刻 |
+| 2 | `antd` / `antd-mobile` | 页面筛选、弹窗、抽屉、步骤条、非平台数据控件、平台暂无组件时的临时包装 | 不要手写 DOM 行为；保留 props/ref/a11y/键盘能力 |
+| 3 | 自定义组件 | 平台和 antd 都不能满足的特殊业务交互 | 先反馈平台缺口；实现只写业务适配层 |
+| 4 | 原生 HTML 控件 | 仅 OpenXiangda SDK / 平台组件内部实现 | AI 生成的 app/workspace 代码禁止使用 |
+
+---
+
+## 1.2 开源库选型规则
 
 AI 在实现成熟交互前必须先判断是否已有可靠组件或库：
 
 | 场景 | 优先方案 | 说明 |
 | --- | --- | --- |
-| PC 表单控件、筛选、弹窗、表格、步骤条 | `antd` | 不要用原生 `<input>` / `<select>` 复刻。用 `Input`、`Input.Search`、`Select`、`DatePicker`、`Table`、`Modal`、`Drawer`、`Form` 等。 |
-| 移动端操作、列表、弹层、Tab | `antd-mobile` | 移动端不要强行套 PC 组件。 |
-| 平台数据录入能力 | `openxiangda` 平台字段组件 | 人员、部门、附件、图片、富文本、位置、数据管理列表优先平台组件。 |
+| 表单录入字段 | `openxiangda` 平台字段组件 | 文本、数字、日期、选择、人员、部门、附件、图片、富文本、位置、子表等优先 schema/platform field。 |
+| 平台数据录入能力 | `openxiangda` 平台字段组件 | 人员、部门、附件、图片、富文本、签名、位置、数据管理列表必须平台组件。 |
+| PC 页面控件、筛选、弹窗、表格、步骤条 | `antd` | 仅用于非平台数据控件或平台组件缺失时的包装。不要用原生 `<input>` / `<select>` 复刻。 |
+| 移动端操作、列表、弹层、Tab | `antd-mobile` | 移动端不要强行套 PC 组件；平台字段组件已多端适配时直接用平台组件。 |
 | 图表、仪表盘、经营看板 | `echarts` + `echarts-for-react` | 不要手写 canvas/SVG 图表，除非只是非常小的装饰图形。 |
 | 复杂时间轴动画、编排动画、滚动动画 | `gsap` | 需要动画库时先查 GSAP 官方文档；如果当前 Agent 有动画/GSAP skill，先读取该 skill。简单 hover/transition 用 CSS 即可。 |
 | 拖拽排序、看板、可拖卡片 | `@dnd-kit/*` | 不要自己处理 pointer/mouse/touch 全套事件。 |
@@ -32,10 +45,11 @@ AI 在实现成熟交互前必须先判断是否已有可靠组件或库：
 
 选型流程：
 
-1. 先看模板 `package.json` 已有依赖，已有依赖优先复用。
-2. 没有依赖但功能成熟复杂时，调研官方文档、维护状态、包体积和授权，再通过包管理器加入。
-3. 页面代码只写业务适配层，不复制第三方库内部逻辑。
-4. 新增依赖后，在提交说明或实现注释中保留一句选择原因。
+1. 先查是否已有 OpenXiangda 平台组件或 schema 字段能表达。
+2. 平台没有时，看模板 `package.json` 已有依赖，已有依赖优先复用。
+3. 没有依赖但功能成熟复杂时，调研官方文档、维护状态、包体积和授权，再通过包管理器加入。
+4. 页面代码只写业务适配层，不复制第三方库内部逻辑。
+5. 新增依赖或平台能力缺口后，通过 `openxiangda feedback submit --yes` 反馈选择原因或能力缺口。
 
 ---
 
@@ -70,15 +84,21 @@ import {
 
 ---
 
-## 3. 推荐使用平台组件（可自定义但不建议从零重做）
-
-| 场景 | 平台组件 | 何时考虑自定义 |
-| --- | --- | --- |
-| 下拉选择 | `SelectField` | 需要复杂远程搜索、级联、虚拟滚动时，包装而非重写 |
-| 日期选择 | `DateField` | 特殊日期范围联动、节假日高亮 |
-| 表单容器 | `FormProvider` + `FormRenderer` | 需要极度定制布局（分栏、Tab 嵌套表单） |
-| 审批时间线 | `ApprovalTimeline` | 需要自定义节点渲染（增加业务标签、跳转链接） |
-| 摘要卡片 | `FormSummaryCard` | 需要高度自定义字段展示样式 |
+## 3. 推荐使用平台组件（可自定义但不建议从零重做）
+
+| 场景 | 平台组件 | 何时考虑自定义 |
+| --- | --- | --- |
+| 短文本 | `TextField` | 需要复合输入（如扫码 + 输入）时，包装平台字段或 antd `Input` |
+| 长文本 | `TextAreaField` | 需要模板片段、语音转写等增强时包装 |
+| 数字 | `NumberField` | 需要特殊单位联动或计算器式输入时包装 |
+| 下拉选择 | `SelectField` | 需要复杂远程搜索、级联、虚拟滚动时，包装而非重写 |
+| 多选 / 单选 / 复选 | `MultiSelectField` / `RadioField` / `CheckboxField` | 需要特殊展示时包装 |
+| 日期选择 | `DateField` | 特殊日期范围联动、节假日高亮 |
+| 级联日期 / 级联选择 | `CascadeDateField` / `CascadeSelectField` | 需要特殊联动时包装 |
+| 子表 | `SubFormField` | 需要完整行级业务动作时包装 |
+| 表单容器 | `FormProvider` + `FormRenderer` | 需要极度定制布局（分栏、Tab 嵌套表单） |
+| 审批时间线 | `ApprovalTimeline` | 需要自定义节点渲染（增加业务标签、跳转链接） |
+| 摘要卡片 | `FormSummaryCard` | 需要高度自定义字段展示样式 |
 
 自定义时仍应**包装**这些组件，而不是从 antd 从零实现一遍。
 
@@ -86,7 +106,9 @@ import {
 
 ## 4. 自定义组件开发规范
 
-### 4.1 推荐：基于 antd 包装 + 原生 Tailwind 类
+### 4.1 推荐：平台组件缺失时，基于 antd 包装 + 原生 Tailwind 类
+
+先判断平台组件确实不能满足；如果是平台能力缺口，先用 `openxiangda feedback submit --yes` 反馈，再写本地包装作为临时方案。
 
 ```tsx
 import { Select, SelectProps } from 'antd';
@@ -116,13 +138,14 @@ export function CustomSelect({ options, className, ...rest }: CustomSelectProps)
 - 默认 `cssIsolation: "none"` 时不要额外给弹层加 `sy-app-workspace`；只有 legacy `namespace/shadow` 页面才需要给弹层或容器补 namespace class。
 - 使用 `w-full`、`rounded-md`、`text-slate-600`、`border-slate-200` 等 Tailwind 原生类作为默认基线；如果组件视觉需要精调，可以继续使用 Tailwind 任意值或局部 CSS。
 
-### 4.2 错误：从头实现选择器
-
-```tsx
-// ❌ 反例：丢失键盘导航、可访问性、移动端体验、平台主题
-function BadSelect({ options }) {
-  return (
-    <div style={{ border: '1px solid #d9d9d9', borderRadius: '4px', padding: '4px 11px' }}>
+### 4.2 错误：从头实现选择器或原生表单控件
+
+```tsx
+// ❌ 反例：AI-authored app code 不要这样写。
+// 丢失键盘导航、可访问性、移动端体验、平台主题和平台数据格式。
+function BadSelect({ options }) {
+  return (
+    <div style={{ border: '1px solid #d9d9d9', borderRadius: '4px', padding: '4px 11px' }}>
       {options.map((opt) => (
         <div key={opt.value} onClick={() => /* ... */}>
           {opt.label}
@@ -130,14 +153,22 @@ function BadSelect({ options }) {
       ))}
     </div>
   );
-}
-```
-
-问题清单：
-- 硬编码颜色 `#d9d9d9` → 切主题失效。
-- 丢失 antd 的键盘 / a11y / 输入法行为。
-- 移动端无适配。
-- 平台主题升级时不会跟随。
+}
+```
+
+```tsx
+// ❌ 反例：表单录入不要直接写原生控件
+<input value={name} onChange={(event) => setName(event.target.value)} />
+<select value={type} onChange={(event) => setType(event.target.value)} />
+<input type="file" onChange={uploadManually} />
+```
+
+问题清单：
+- 硬编码颜色 `#d9d9d9` → 切主题失效。
+- 丢失 antd 的键盘 / a11y / 输入法行为。
+- 移动端无适配。
+- 平台主题升级时不会跟随。
+- 绕过平台表单 schema、字段权限、文件鉴权、组织架构和标准数据格式。
 
 ---
 
@@ -199,11 +230,12 @@ export function ActionButton(props) {
 
 ## 7. 常见错误（AI Agent 高频踩坑）
 
-| 错误 | 正确做法 |
-| --- | --- |
-| 自己写人员选择器（搜员工 + 列表） | 用 `UserSelectField` |
-| 自己实现部门树 | 用 `DepartmentSelectField` |
-| 用 `<input type="file">` 上传 | 用 `AttachmentField` / `ImageField` |
+| 错误 | 正确做法 |
+| --- | --- |
+| 在 `src/forms/**` 或 `src/pages/**` 直接写 `<input>` / `<select>` / `<textarea>` | 用平台字段组件；平台没有时包装 antd / antd-mobile |
+| 自己写人员选择器（搜员工 + 列表） | 用 `UserSelectField` |
+| 自己实现部门树 | 用 `DepartmentSelectField` |
+| 用 `<input type="file">` 上传 | 用 `AttachmentField` / `ImageField` |
 | 用第三方富文本（TinyMCE 等） | 用 `EditorField` |
 | 自己写列表 + 分页 + 导出 | 用 `DataManagementList` |
 | 常规组件大量写 `style={{ color: '#333', padding: 16 }}` | 优先 Tailwind 原生工具类、任意值或局部 CSS；动态值和少量精调 inline style 可接受 |
@@ -216,8 +248,10 @@ export function ActionButton(props) {
 
 ## 速查 Checklist（提交前自检）
 
-- [ ] 涉及人员 / 部门 / 文件 / 图片 / 富文本 / 签名 / 地图 / 列表 → 用了平台组件？
-- [ ] 自定义组件 → 基于 antd / antd-mobile 包装并透传 props？
+- [ ] 涉及人员 / 部门 / 文件 / 图片 / 富文本 / 签名 / 地图 / 列表 → 用了平台组件？
+- [ ] 表单录入字段 → 优先使用了 `TextField` / `SelectField` / `DateField` 等平台字段，而不是 antd 或原生控件？
+- [ ] 自定义组件 → 基于 antd / antd-mobile 包装并透传 props？
+- [ ] app/workspace 源码 → 没有直接出现原生 `<input>` / `<select>` / `<textarea>` / file input / 手写 picker 或 uploader？
 - [ ] 样式 → 默认用 Tailwind 原生类 / 任意值 / 局部 CSS；平台 token 只在主题兼容或平台组件需要时使用，且作用域收敛？
 - [ ] 弹层 → 默认使用正常容器；只有 legacy 隔离页面才额外设置 `sy-app-workspace` 样式作用域？
 - [ ] 多端 → PC 用 antd、Mobile 用 antd-mobile，业务逻辑共享？

package/openxiangda-skills/references/connector-resources.md

@@ -28,7 +28,7 @@ Connector manifests use stable `code` values. The platform maps connector `code`
 
 Notification manifests live under `src/resources/notifications/` and contain `templates` plus `typeConfigs`. See `notifications.md` before generating reminders or message templates.
 
-Data view manifests live under `src/resources/data-views/` and define read-only materialized views for repeated multi-form joins. Use them for joined list/report/lookup sources where refresh lag is acceptable. Do not use them for single-form CRUD, simple linkedForm selects, real-time writes, or write-back. See `data-views.md` before generating one.
+Data view manifests live under `src/resources/data-views/` and define read-only materialized views for repeated multi-form joins or fixed aggregate statistics. Use row views with `sdk.dataView.query` for joined list/report/lookup sources, and aggregate views with `sdk.dataView.stats` for dashboard metrics where refresh lag is acceptable. Before generating one, confirm freshness tolerance and add indexes for common filters, sort fields, dimensions, and date buckets. Do not use them for single-form CRUD, simple linkedForm selects, real-time writes, write-back, or ad-hoc BI. See `data-views.md` before generating one.
 
 ```json
 {