openxiangda 1.0.37 → 1.0.39

package/README.md

@@ -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

@@ -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
@@ -129,7 +129,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.

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
 {

package/openxiangda-skills/references/data-views.md

@@ -1,12 +1,13 @@
 # Data View Resources
 
-Data views are OpenXiangda-managed read-only PostgreSQL materialized views. They turn repeated multi-form joins into a published resource under `src/resources/data-views/`.
+Data views are OpenXiangda-managed read-only PostgreSQL materialized views. They turn repeated multi-form joins and predefined aggregate statistics into published resources under `src/resources/data-views/`.
 
 Use a data view when the app needs read-only joined data from multiple forms, such as:
 
 - Ticket list with customer name, owner, SLA, and status fields.
 - Order list with product, customer, and payment fields.
 - Project dashboard combining project, member, task, and risk forms.
+- Dashboard statistics such as monthly ticket count, order amount by customer, or task count by status.
 - Reusable lookup or report data consumed by several pages or automations.
 - Large list pages where repeated client-side cross-form joins would be slow or inconsistent.
 
@@ -16,13 +17,18 @@ Do not use a data view for:
 - Simple one-form dropdown options. Use `SelectField` with `optionSource.type: "linkedForm"`.
 - Writes or write-back. Data views are read-only.
 - Strong real-time views after every form update. Data views update after manual or scheduled refresh.
-- Raw SQL, incremental refresh, source-table trigger refresh, or group-by aggregation. v1 does not support them.
+- Raw SQL, incremental refresh, source-table trigger refresh, ad-hoc BI/pivot/window analysis, or write-heavy realtime dashboards.
 
 ## Authoring
 
 Place manifests in `src/resources/data-views/*.json`. Use logical `formCode` values in source files. The CLI resolves them to the current profile's `formUuid` during `resource publish`.
 
-Minimal example:
+Two view types are supported:
+
+- `viewType: "row"` or omitted: row-level joined materialized view using `select`.
+- `viewType: "aggregate"`: grouped statistics materialized view using `dimensions` and `measures`; query it with `stats`.
+
+Row view example:
 
 ```json
 {
@@ -61,13 +67,67 @@ Minimal example:
 }
 ```
 
+Aggregate statistics example:
+
+```json
+{
+  "code": "ticket_stats_by_customer",
+  "name": "Ticket Stats By Customer",
+  "viewType": "aggregate",
+  "base": { "formCode": "service_ticket", "alias": "ticket" },
+  "joins": [
+    {
+      "type": "left",
+      "formCode": "customer",
+      "alias": "customer",
+      "on": [
+        {
+          "left": "ticket.customer.value",
+          "op": "=",
+          "right": "customer.form_instance_id"
+        }
+      ]
+    }
+  ],
+  "dimensions": [
+    { "field": "customer.name", "as": "customerName" },
+    { "field": "ticket.created_at", "as": "createdMonth", "bucket": "month" }
+  ],
+  "measures": [
+    { "type": "count", "as": "ticketCount" },
+    { "type": "sum", "field": "ticket.amount", "as": "totalAmount" },
+    { "type": "avg", "field": "ticket.amount", "as": "avgAmount" }
+  ],
+  "having": { "field": "ticketCount", "op": ">", "value": 0 },
+  "indexes": [{ "fields": ["customerName", "createdMonth"] }],
+  "refresh": { "mode": "scheduled", "cron": "0 */10 * * * *" },
+  "permissionGroups": [
+    {
+      "code": "ticket_stats_query",
+      "name": "Ticket Stats Query",
+      "roles": ["manager"],
+      "operations": ["query"]
+    }
+  ]
+}
+```
+
 Field reference rules:
 
 - Use `alias.field`, for example `ticket.title`.
 - Use system fields directly, such as `form_instance_id`, `created_at`, `updated_at`, `created_by`, and `tenant_id`.
 - For option-like JSON fields that store `{ label, value }`, use `.value` for joins and `.label` for display when needed.
 - Every `select` item must have an explicit output alias in `as`.
-- Runtime `fields`, `filters`, `order`, indexes, field permissions, and row permissions reference output aliases, not source field references.
+- Aggregate `dimensions` and `measures` also need explicit output aliases in `as`.
+- Runtime `fields`, `filters`, `having`, `order`, indexes, field permissions, and row permissions reference output aliases, not source field references.
+
+Aggregate rules:
+
+- Measures support `count`, `countDistinct`, `sum`, `avg`, `min`, and `max`.
+- `sum` and `avg` only support `NumberField`.
+- Date buckets support `hour`, `day`, `week`, `month`, `quarter`, and `year`, and only apply to `DateField`, `created_at`, and `updated_at`.
+- `where` filters source rows before grouping; `having` filters aggregate output aliases after grouping.
+- Use aggregate views for stable dashboard/query shapes. They are not an ad-hoc BI query engine.
 
 Join rules:
 
@@ -79,6 +139,7 @@ Filters:
 
 - Definition `where` filters source rows before materialization and uses source references such as `ticket.status`.
 - Runtime query filters use output aliases such as `ticketTitle`.
+- Aggregate definition `having` and runtime stats `having` also use output aliases such as `ticketCount`.
 - Supported operators include `=`, `!=`, `<>`, `>`, `>=`, `<`, `<=`, `contains`, `notContains`, `in`, `isEmpty`, and `isNotEmpty`, with aliases such as `eq`, `neq`, `gte`, `lte`, `like`, `is_null`, and `is_not_null`.
 
 Refresh:
@@ -86,12 +147,45 @@ Refresh:
 - `manual` means refresh only when an administrator runs refresh or the resource is recreated.
 - `scheduled` uses cron, for example `0 */10 * * * *`.
 - Query results may be stale. Show or inspect `lastRefreshedAt` when freshness matters.
+- Do not choose a high-frequency schedule by default. Ask or infer how stale the data may be before setting `scheduled`.
 
 Indexes:
 
 - Index output aliases that pages filter or sort by.
+- Row views should index stable IDs and common list filters/sort fields.
+- Aggregate views should index dimensions and date buckets used by charts, filters, drill-downs, or ordering.
+- Do not index every output field or every measure; extra indexes make refresh slower.
 - Use `unique: true` only when the output field combination is truly unique.
 
+## Performance And Freshness
+
+Data views move expensive joins and aggregations from page runtime to materialized-view refresh time. They reduce repeated page pressure only when the view shape, refresh cadence, and indexes are chosen deliberately.
+
+Before creating a data view, confirm these points:
+
+- **Freshness tolerance**: ask whether users need near-real-time data, 10-30 minute freshness, hourly/daily reports, or manual snapshots.
+- **Query shape**: list the fields users will filter, sort, group, or drill down by. These should become output aliases and usually indexes.
+- **Data scope**: if the business only needs active, recent, or in-scope records, put that rule in definition `where` so old/source-irrelevant rows are filtered before materialization.
+- **Visible fields**: output only fields the page or permission rules need. Use hidden scope aliases for data permissions when needed, but do not build one huge catch-all view.
+
+Refresh cadence guidance:
+
+- Use `manual` for admin diagnostics, imported snapshots, low-change reference data, or data that is refreshed after an intentional operation.
+- Use `scheduled` every 10-30 minutes for normal dashboards, joined report lists, and recurring management views.
+- Use hourly or daily schedules for leadership reports, historical statistics, and large aggregate views.
+- Avoid intervals below 5 minutes unless the user explicitly confirms the time sensitivity and expected source-table volume. High-frequency refreshes can pressure both source tables and the materialized view.
+- For strong real-time behavior after each form save, do not use a data view; query the source form directly or design a different backend workflow.
+
+Index guidance:
+
+- Index only materialized-view output aliases, not source references such as `customer.name`.
+- For row views, index IDs used in drill-down (`ticketId`, `customerId`) and common filters/order fields (`statusValue`, `ownerId`, `createdAt`).
+- For aggregate views, index the dimensions/time buckets used in runtime `filters`, `having` drill-downs, and `order` (`customerId`, `statusValue`, `createdMonth`).
+- Keep compound indexes aligned with common query prefixes. For example, dashboard filters by customer then month should use `["customerId", "createdMonth"]`.
+- `searchKeyWord` across many text columns is inherently heavier than structured filters. Prefer explicit `filters` on indexed aliases.
+- `countDistinct` and high-cardinality dimensions are refresh-heavy. Confirm data volume and avoid very frequent schedules.
+- Show `lastRefreshedAt` on pages or in diagnostics when users may notice refresh delay.
+
 ## Permissions
 
 Management APIs require `app:data-view:manage`.
@@ -105,6 +199,7 @@ Permission group behavior:
 - Missing or empty `fieldPermissions` means all output fields are visible.
 - When multiple permission groups match, field permissions are most permissive: a field is visible if any matched group allows it.
 - `dataPermission` is a row condition over output aliases.
+- Hidden output aliases can still be used by `dataPermission`; this is useful for scope keys that should restrict rows but not be returned to pages.
 - Multiple matched row conditions are ORed.
 - If any matched group has no row condition, rows are unrestricted.
 
@@ -127,6 +222,8 @@ 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 --profile dev --fields ticketId,customerName
 openxiangda data-view query ticket_with_customer --profile dev --query-json query.json
+openxiangda data-view stats ticket_stats_by_customer --profile dev --fields customerName,ticketCount
+openxiangda data-view stats ticket_stats_by_customer --profile dev --query-json stats-query.json
 ```
 
 ## Runtime SDK
@@ -145,6 +242,23 @@ const response = await sdk.dataView.query("ticket_with_customer", {
 })
 ```
 
+Aggregate stats query:
+
+```ts
+const response = await sdk.dataView.stats("ticket_stats_by_customer", {
+  fields: ["customerName", "createdMonth", "ticketCount", "totalAmount"],
+  filters: [
+    { field: "customerName", operator: "contains", value: keyword },
+  ],
+  having: [
+    { field: "ticketCount", operator: ">", value: 0 },
+  ],
+  order: [{ field: "ticketCount", isAsc: "n" }],
+  currentPage: 1,
+  pageSize: 20,
+})
+```
+
 The response data is:
 
 ```ts
@@ -170,6 +284,15 @@ export default {
       defaultFilter: [
         { field: "ticketTitle", operator: "isNotEmpty" }
       ]
+    },
+    {
+      key: "ticketStats",
+      type: "dataView.stats",
+      code: "ticket_stats_by_customer",
+      fields: ["customerName", "ticketCount"],
+      defaultHaving: [
+        { field: "ticketCount", operator: ">", value: 0 }
+      ]
     }
   ]
 }
@@ -193,7 +316,8 @@ List page:
 
 Dashboard:
 
-- Use one or more data views as read-optimized sources.
+- Use aggregate data views for stable metrics such as counts, totals, averages, status distribution, and time buckets.
+- Use row data views for drill-down lists behind those metrics.
 - Keep refresh scheduled.
 - Show `lastRefreshedAt` when business users care about freshness.
 
@@ -206,6 +330,7 @@ Reusable lookup:
 Automation diagnosis:
 
 - Query the data view with `openxiangda data-view query --query-json`.
+- Query aggregate views with `openxiangda data-view stats --query-json`.
 - Refresh manually after bulk imports or test data resets.
 
 ## Troubleshooting

package/openxiangda-skills/references/pages/page-sdk.md

@@ -6,11 +6,15 @@ Guidelines:
 
 - Do not hardcode `/openxiangda-api` calls inside end-user page components unless the page is explicitly an admin tool.
 - Prefer SDK modules for form data, user context, permissions, and platform navigation.
-- Use `sdk.dataView.query` for published read-only multi-form data views. Data view runtime queries can filter, sort, paginate, and select only output aliases.
+- Use `sdk.dataView.query` for published read-only multi-form row data views. Use `sdk.dataView.stats` for aggregate data views declared with `viewType: "aggregate"`.
+- Data view runtime queries can filter, sort, paginate, and select only output aliases.
+- Keep data view page calls paginated and field-scoped. Runtime filters/order should use aliases that the data view indexes, especially for aggregate dimensions and date buckets.
 - Use `sdk.dataSource.run()` with a page data source descriptor when the page config should own the data view code, default fields, or default filters.
 - Use `sdk.connector.invoke`, `sdk.connector.call("connector.api")`, or `sdk.connector.download` for external services. The SDK calls the platform runtime connector endpoint; it must not call third-party domains directly.
 - Use `sdk.notification.sendByType` and `batchSendByType` for reusable business messages. Custom notification types must be declared in `src/resources/notifications/` and published with `openxiangda resource publish`.
 - For the current user's department hierarchy, use `sdk.department.getCurrentUserParentDepartments()`; do not hardcode `GET /department/:id/parentDepartments` in page code.
+- Use `sdk.auth.logoutAndRedirect({ loginUrl })` for user logout when the page should return after login. It calls the platform logout endpoint, appends the current page URL as `callback`, and redirects to the login URL. Use `sdk.auth.logout()` only when the page wants to handle redirect itself.
+- Use `sdk.role.getMyRoles()`, `sdk.role.getCurrentRole()`, and `sdk.role.switchAppRole()` for current-user app role switching. Pass `roleId: ""` to switch back to all app roles.
 - Keep API calls behind small local functions so generated UI stays testable.
 - Treat user context and tenant context as runtime-provided values.
 
@@ -30,6 +34,23 @@ const response = await sdk.dataView.query("ticket_with_customer", {
 })
 ```
 
+Data view stats:
+
+```ts
+const response = await sdk.dataView.stats("ticket_stats_by_customer", {
+  fields: ["customerName", "ticketCount", "totalAmount"],
+  filters: [
+    { field: "customerName", operator: "contains", value: keyword },
+  ],
+  having: [
+    { field: "ticketCount", operator: ">", value: 0 },
+  ],
+  order: [{ field: "ticketCount", isAsc: "n" }],
+  currentPage: 1,
+  pageSize: 20,
+})
+```
+
 Data view data source descriptor:
 
 ```ts
@@ -43,6 +64,15 @@ export default {
       defaultFilter: [
         { field: "ticketTitle", operator: "isNotEmpty" }
       ]
+    },
+    {
+      key: "ticketStats",
+      type: "dataView.stats",
+      code: "ticket_stats_by_customer",
+      fields: ["customerName", "ticketCount"],
+      defaultHaving: [
+        { field: "ticketCount", operator: ">", value: 0 }
+      ]
     }
   ]
 }
@@ -55,4 +85,34 @@ const response = await sdk.dataSource.run("tickets", {
 })
 ```
 
-Data view filters and fields use output aliases such as `customerName`, not source references such as `customer.name`. If the page only needs one form, prefer `sdk.form.advancedSearch`. If the page only needs a simple one-form dropdown, prefer linkedForm options.
+Data view filters, having, and fields use output aliases such as `customerName` or `ticketCount`, not source references such as `customer.name`. If the page only needs one form, prefer `sdk.form.advancedSearch`. If the page only needs a simple one-form dropdown, prefer linkedForm options.
+
+Logout and current-user role switching:
+
+```ts
+await sdk.auth.logoutAndRedirect({
+  loginUrl: "/login",
+})
+
+await sdk.auth.logoutAndRedirect({
+  loginUrl: "/login",
+  callbackParamName: "redirect",
+})
+
+await sdk.auth.logout()
+
+const roles = await sdk.role.getMyRoles({ scope: "app" })
+const currentRole = await sdk.role.getCurrentRole({ scope: "app" })
+
+await sdk.role.switchAppRole({
+  roleId: roles.result?.[0]?.id || "",
+})
+
+await sdk.role.switchAppRole({
+  roleId: "",
+})
+
+await sdk.role.switchPlatformRole({
+  roleId: "platform-admin",
+})
+```

package/openxiangda-skills/references/resource-manifest-cheatsheet.md

@@ -61,6 +61,14 @@ const data = await sdk.connector.call("crm.getCustomer", { body: { keyword } });
 
 ## 2. Data View — `src/resources/data-views/<code>.json`
 
+选择规则：
+
+- 多表只读联表列表 / lookup / 报表明细：用行级 data view，页面调用 `sdk.dataView.query`。
+- 固定口径统计 / 看板指标 / 图表数据源：用 `viewType: "aggregate"`，页面调用 `sdk.dataView.stats`。
+- ECharts 或自定义 dashboard 只负责展示；统计口径稳定时，数据源优先沉淀成 aggregate data view。
+- 发布前为常用筛选、排序、维度和时间桶声明 `indexes`，并确认刷新延迟是否能被业务接受。
+- 不用于单表 CRUD、简单 `linkedForm` 下拉、强实时、写回或临时 BI 查询。
+
 ```json
 {
   "code": "ticket_with_customer",
@@ -101,7 +109,35 @@ const list = await sdk.dataView.query("ticket_with_customer", {
 });
 ```
 
-适用：跨表只读联表 / 报表 / 大列表性能优化。**不适用**：单表 CRUD、`linkedForm` 下拉、强实时、写回。完整规则见 [`data-views.md`](data-views.md)。
+统计聚合视图：
+
+```json
+{
+  "code": "ticket_stats_by_customer",
+  "name": "Ticket Stats By Customer",
+  "viewType": "aggregate",
+  "base": { "formCode": "service_ticket", "alias": "ticket" },
+  "dimensions": [
+    { "field": "ticket.customer.value", "as": "customerId" },
+    { "field": "ticket.created_at", "as": "createdMonth", "bucket": "month" }
+  ],
+  "measures": [
+    { "type": "count", "as": "ticketCount" },
+    { "type": "sum", "field": "ticket.amount", "as": "totalAmount" }
+  ],
+  "having": { "field": "ticketCount", "op": ">", "value": 0 },
+  "indexes": [{ "fields": ["customerId", "createdMonth"] }]
+}
+```
+
+```ts
+const stats = await sdk.dataView.stats("ticket_stats_by_customer", {
+  fields: ["customerId", "createdMonth", "ticketCount", "totalAmount"],
+  having: [{ field: "ticketCount", op: ">", value: 0 }],
+});
+```
+
+性能要点：索引只能引用输出 alias；行级视图索引常用 filter/order 字段；聚合视图索引 dimensions/date buckets；`countDistinct` 和高基数维度刷新成本较高；低于 5 分钟的 scheduled refresh 需要用户明确确认时间敏感度。完整规则见 [`data-views.md`](data-views.md)。
 
 ## 3. Notification — `src/resources/notifications/<code>.json`
 

package/openxiangda-skills/skills/openxiangda-page/SKILL.md

@@ -33,7 +33,7 @@ openxiangda workspace publish --profile <name> --page <pageCode>
 - ✅ Default to **native Tailwind utilities** for new pages (`bg-white`, `border-slate-200`, `grid-cols-[240px_1fr]`, ...) and `cssIsolation: "none"`. Keep namespace/shadow only for explicit legacy compatibility.
 - ✅ Split complex pages into `domain/`, `shared/services/`, `shared/hooks/`, `components/`, route/config files, `styles.css` (see `references/best-practices.md` and `references/architecture-patterns.md`).
 - ✅ List/detail/CRUD pages: follow `DataManagementList` pattern from `references/architecture-patterns.md`. Pagination + structured `filterGroup` + `OR`. Never fetch huge `pageSize` and filter in browser.
-- ✅ For external APIs use `src/resources/connectors/<code>.json` + `sdk.connector.invoke()`; for joined read-only queries use `src/resources/data-views/<code>.json`.
+- ✅ For external APIs use `src/resources/connectors/<code>.json` + `sdk.connector.invoke()`; for joined read-only lists use row data views + `sdk.dataView.query`; for stable dashboard metrics use aggregate data views + `sdk.dataView.stats`.
 - ❌ Single-file giant pages. Split per `references/best-practices.md`.
 - ❌ Hardcoded `/view/...&isRenderNav=false` URLs scattered through page code; use the runtime navigation helper.
 - ❌ shadcn token classes like `bg-card` / `text-muted-foreground` / `text-foreground` unless explicitly configured.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "1.0.37",
+  "version": "1.0.39",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {