@acorex-platform/module-report-management-client 0.0.18 → 0.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acorex-platform/module-report-management-client",
-  "version": "0.0.18",
+  "version": "0.0.24",
   "sideEffects": false,
   "peerDependencies": {
     "@angular/common": "^21.0.0",

package/types/acorex-platform-module-report-management-client-contracts.d.ts

@@ -1,7 +1,17 @@
 import { AXPWidgetColumnNode } from '@acorex-platform/framework-shared/widget-core';
-import { AXPCommand } from '@acorex-platform/framework-shared/runtime';
-import { AXPQuerySort, AXPEntity } from '@acorex-platform/framework-shared/entity';
-import { AXPFilterClause, AXPActionMenuItem, AXPSystemActionType, AXPCategoryEntity, AXPWidgetNode, AXPExportOptions } from '@acorex-platform/framework-shared/core';
+import { AXPQuerySort, AXPEntityModel } from '@acorex-platform/framework-shared/entity';
+import { AXPMultiLanguageString, AXPCategoryEntity, AXPWidgetNode, AXPActionMenuItem, AXPSystemActionType, AXPExportOptions, AXPRuntimeQueryResult, AXPRuntimeCollectionData } from '@acorex-platform/framework-shared/core';
+
+declare const AXMReportManagementCommandKeys: {
+    readonly RecalculateQuerySnapshots: "ReportManagement:RecalculateQuerySnapshots";
+    readonly RefreshQuerySnapshots: "ReportManagement:RefreshQuerySnapshots";
+    readonly ReportGeneration: {
+        readonly Create: "ReportManagement:ReportGeneration:Create";
+        readonly Execute: "ReportManagement:ReportGeneration:Execute";
+    };
+};
+declare const AXM_RECALCULATE_QUERY_SNAPSHOTS_COMMAND_KEY: "ReportManagement:RecalculateQuerySnapshots";
+declare const AXM_REFRESH_QUERY_SNAPSHOTS_COMMAND_KEY: "ReportManagement:RefreshQuerySnapshots";
 
 declare const AXPReportManagementFeatureKeys: {
     readonly ReportBuilder: "ReportManagement:Feature:ReportBuilder";
@@ -17,22 +27,38 @@ declare const AXPReportManagementMenuKeys: {
     readonly DataSets: "report-management:menu:data-sets";
 };
 
+/**
+ * Insights & Reporting capabilities used by this module.
+ * Domain capability keys for this module. Root groups live in `AXPCommonPermissionGroupKeys` (common contracts).
+ */
+declare const AXPInsightsReportingPermissionKeys: {
+    readonly Access: "InsightsReporting:Permission:Access";
+    readonly MaintainReports: "InsightsReporting:Permission:MaintainReports";
+    readonly MaintainData: "InsightsReporting:Permission:MaintainData";
+    readonly ViewActivityInsight: "InsightsReporting:Permission:ViewActivityInsight";
+    readonly ManageActivityInsight: "InsightsReporting:Permission:ManageActivityInsight";
+    readonly Setup: "InsightsReporting:Permission:Setup";
+};
+/**
+ * @deprecated Prefer {@link AXPInsightsReportingPermissionKeys}.
+ * Legacy nested shape kept so existing imports compile during migration.
+ */
 declare const AXMPermissionsKeys: {
-    ReportManagement: {
-        Management: string;
-        Report: {
-            Management: string;
-            View: string;
-            Create: string;
-            Update: string;
-            Delete: string;
+    readonly ReportManagement: {
+        readonly Management: "InsightsReporting:Permission:MaintainReports";
+        readonly Report: {
+            readonly Management: "InsightsReporting:Permission:MaintainReports";
+            readonly View: "InsightsReporting:Permission:MaintainReports";
+            readonly Create: "InsightsReporting:Permission:MaintainReports";
+            readonly Update: "InsightsReporting:Permission:MaintainReports";
+            readonly Delete: "InsightsReporting:Permission:MaintainReports";
         };
-        Category: {
-            Management: string;
-            View: string;
-            Create: string;
-            Update: string;
-            Delete: string;
+        readonly Category: {
+            readonly Management: "InsightsReporting:Permission:Setup";
+            readonly View: "InsightsReporting:Permission:Setup";
+            readonly Create: "InsightsReporting:Permission:Setup";
+            readonly Update: "InsightsReporting:Permission:Setup";
+            readonly Delete: "InsightsReporting:Permission:Setup";
         };
     };
 };
@@ -56,8 +82,8 @@ declare const RootConfig: {
             readonly icon: "fa-light fa-default";
         };
         readonly category: {
-            readonly name: "Category";
-            readonly fullName: `${string}.Category`;
+            readonly name: "ReportCategory";
+            readonly fullName: `${string}.ReportCategory`;
             readonly title: `@${string}:reports.entities.category.title`;
             readonly titlePlural: `@${string}:reports.entities.category.plural`;
             readonly icon: "fa-light fa-folder";
@@ -69,6 +95,27 @@ declare const RootConfig: {
             readonly titlePlural: `@${string}:reports.entities.report.plural`;
             readonly icon: "fa-light fa-file-chart-pie";
         };
+        readonly querySnapshotPolicy: {
+            readonly name: "QuerySnapshotPolicy";
+            readonly fullName: `${string}.QuerySnapshotPolicy`;
+            readonly title: `@${string}:query-snapshots.entities.policy.title`;
+            readonly titlePlural: `@${string}:query-snapshots.entities.policy.plural`;
+            readonly icon: "fa-light fa-sliders";
+        };
+        readonly querySnapshot: {
+            readonly name: "QuerySnapshot";
+            readonly fullName: `${string}.QuerySnapshot`;
+            readonly title: `@${string}:query-snapshots.entities.snapshot.title`;
+            readonly titlePlural: `@${string}:query-snapshots.entities.snapshot.plural`;
+            readonly icon: "fa-light fa-camera";
+        };
+        readonly reportGenerationRequest: {
+            readonly name: "ReportGenerationRequest";
+            readonly fullName: `${string}.ReportGenerationRequest`;
+            readonly title: `@${string}:report-generation.entities.request.title`;
+            readonly titlePlural: `@${string}:report-generation.entities.request.plural`;
+            readonly icon: "fa-light fa-file-export";
+        };
     };
 };
 
@@ -93,15 +140,70 @@ type AXPReportLayoutType = 'table' | 'chart' | 'cards' | 'custom' | 'pdf';
  */
 interface AXPReportCategory extends AXPCategoryEntity {
 }
+/** How an entity-bound report is surfaced on the host entity UI. */
+type AXPReportEntityDisplay = 'action' | 'page' | 'popup';
+/**
+ * Parameter value on an entity binding:
+ * - field path / expression string (e.g. `id`)
+ * - `'today'` → local calendar day `{ from, to }`
+ * - explicit `{ from, to }` date range
+ */
+type AXPReportEntityParameterValue = string | {
+    from: string;
+    to: string;
+};
+/** Binds a report to a host entity type for Reports page discovery. */
+interface AXPReportEntityBinding {
+    /** Fully qualified entity type, e.g. `SecurityManagement.User`. */
+    entity: string;
+    /** Optional list title (i18n key or plain text). Falls back to report title. */
+    title?: string;
+    /** Optional list description (i18n key or plain text). Falls back to report description. */
+    description?: string;
+    layoutId?: string;
+    /**
+     * Where to surface the report. Defaults to `['page']` (Reports side-menu page).
+     * `action` / `popup` are retained for data compatibility but are not contributed as entity Actions.
+     */
+    display?: AXPReportEntityDisplay | AXPReportEntityDisplay[];
+    /**
+     * Map report parameter path → entity field / expression / date token.
+     * Example: `{ userId: 'id', dateRange: 'today' }`
+     */
+    parameters?: Record<string, AXPReportEntityParameterValue>;
+    order?: number;
+}
 interface AXPReportDefinition {
     id: string;
-    title: string;
-    description?: string;
+    title: AXPMultiLanguageString;
+    description?: AXPMultiLanguageString;
     categoryIds: string[];
     parameterGroups: AXPReportParameterGroup[];
     permissions?: string[];
     layouts: AXPReportLayoutDefinition[];
     defaultLayoutId: string;
+    /** Optional host-entity bindings for the entity `reports` plugin. */
+    entities?: AXPReportEntityBinding[];
+    /** Background / choose / interactive generation options. Omitted = interactive. */
+    generation?: AXPReportGenerationOptions;
+}
+type AXPReportGenerationMode = 'interactive' | 'background' | 'choose';
+type AXPReportArtifactKind = 'viewer' | 'pdf' | 'excel' | 'csv';
+type AXPReportFreezeLayouts = 'current' | 'all';
+interface AXPReportGenerationOptions {
+    /** Omitted = interactive (today’s viewer). */
+    mode?: AXPReportGenerationMode;
+    /** Default `['viewer']` when mode is background or choose. */
+    formats?: AXPReportArtifactKind[];
+    executionTimeoutMs?: number;
+    /** Default 30. Used to set `expiresAt` when the run finishes. */
+    retentionDays?: number;
+    /** Default `'all'` query layouts. `'current'` freezes only the layout the user ran. */
+    freezeLayouts?: AXPReportFreezeLayouts;
+    /** Default true. Store layout/title/parameter snapshot in the viewer freeze file. */
+    pinDefinition?: boolean;
+    /** Demo/local only. Worker waits this long after marking the run running. */
+    simulateDelayMs?: number;
 }
 type AXPReportLayoutAction = AXPActionMenuItem & {
     priority: 'primary' | 'secondary';
@@ -111,8 +213,8 @@ type AXPReportLayoutAction = AXPActionMenuItem & {
  */
 interface AXPReportLayoutDefinition {
     id: string;
-    title: string;
-    description?: string;
+    title: AXPMultiLanguageString;
+    description?: AXPMultiLanguageString;
     icon?: string;
     layout: AXPReportLayout;
     dataSource?: AXPReportDataSource;
@@ -122,14 +224,19 @@ interface AXPReportLayoutDefinition {
 }
 interface AXPReportParameterGroup {
     name: string;
-    title: string;
-    description?: string;
+    title: AXPMultiLanguageString;
+    description?: AXPMultiLanguageString;
     parameters: AXPReportParameter[];
 }
 interface AXPReportParameter {
     path: string;
-    title: string;
-    description?: string;
+    title: AXPMultiLanguageString;
+    description?: AXPMultiLanguageString;
+    /**
+     * Boolean or expression (e.g. `{{ permission.check("…") }}` / `{{ feature.check("…") }}`).
+     * Omitted / `true` means visible. Evaluated by the Report Viewer layout renderer.
+     */
+    visible?: boolean | string;
     widget: AXPWidgetNode;
 }
 type AXPReportDataSource = AXPQueryDataSource | AXPCustomDataSource | AXPAggregatedDataSource | AXPTransformedDataSource;
@@ -288,7 +395,13 @@ interface AXPChartDataMapping {
  */
 interface AXPChartStyling {
     colorScheme?: 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'custom';
+    /** Palette applied by series index when `seriesColors` is not set. */
     customColors?: string[];
+    /**
+     * Per-series fill colors keyed by chart category id/label
+     * (e.g. Online → success, Away → warning, Busy → danger).
+     */
+    seriesColors?: Record<string, string>;
     gridLines?: boolean;
     legend?: {
         show: boolean;
@@ -384,7 +497,11 @@ interface AXPReportPdfOptions {
 interface AXPReportColumn {
     field: string;
     title?: string;
-    visible?: boolean;
+    /**
+     * Boolean or expression (e.g. `{{ permission.check("…") }}`).
+     * Omitted / `true` means visible. Evaluated when building the table view.
+     */
+    visible?: boolean | string;
     width?: number | 'auto';
     align?: 'left' | 'center' | 'right';
     /** When true, column header supports interactive sort (opt-in). */
@@ -438,7 +555,7 @@ interface AXPReportHeaderFooter {
  */
 interface AXPLayoutSwitcherOption {
     id: string;
-    title: string;
+    title: AXPMultiLanguageString;
     icon?: string;
     type: AXPReportLayoutType;
 }
@@ -450,105 +567,148 @@ interface AXPReportLayoutState {
     activeLayoutId: string;
     availableLayouts: AXPLayoutSwitcherOption[];
 }
-/**
- * Layout validation result
- */
-interface AXPLayoutValidationResult {
-    isValid: boolean;
-    errors: string[];
-    layoutId: string;
-}
-/**
- * Data source resolution result for a specific layout
- */
-interface AXPLayoutDataSourceResolution {
-    layoutId: string;
-    dataSource: AXPReportDataSource;
-    source: 'layout' | 'report' | 'none';
+
+type AXPReportGenerationStatus = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+type AXPReportGenerationTrigger = 'manual' | 'schedule' | 'export';
+interface AXPReportGenerationArtifact {
+    kind: AXPReportArtifactKind;
+    fileId?: string;
+    contentType?: string;
+    fileName?: string;
+    rowCount?: number;
+    byteLength?: number;
+    lastError?: string;
+}
+interface AXMReportGenerationRequest extends AXPEntityModel<string> {
+    reportId: string;
+    layoutId?: string;
+    layoutIds?: string[];
+    parameters?: Record<string, unknown>;
+    formats: AXPReportArtifactKind[];
+    trigger: AXPReportGenerationTrigger;
+    status: AXPReportGenerationStatus;
+    requestedBy?: string;
+    jobId?: string;
+    scheduleId?: string;
+    scheduledOccurrence?: string;
+    startedAt?: string;
+    completedAt?: string;
+    durationMs?: number;
+    lastError?: string;
+    expiresAt?: string;
+    sourceRequestId?: string;
+    artifacts: AXPReportGenerationArtifact[];
+}
+interface AXPReportViewerFreeze {
+    version: 1;
+    reportId: string;
+    generatedAt: string;
+    parameters: Record<string, unknown>;
+    definition?: {
+        title: AXPMultiLanguageString;
+        defaultLayoutId: string;
+        layouts: AXPReportLayoutDefinition[];
+    };
+    dataSources: Array<{
+        layoutId: string;
+        queryName: string;
+        result: AXPRuntimeQueryResult;
+    }>;
 }
-/**
- * Layout execution context with resolved data source
- */
-interface AXPLayoutExecutionContext {
+interface AXPReportGenerationCreateInput {
     reportId: string;
-    layoutId: string;
-    dataSource: AXPReportDataSource;
-    filters: AXPFilterClause;
-    skip?: number;
-    take?: number;
-    /** Runtime/user sort — platform shape `{ name, dir }`. */
-    sort?: AXPQuerySort[];
+    layoutId?: string;
+    layoutIds?: string[];
+    parameters?: Record<string, unknown>;
+    formats?: AXPReportArtifactKind[];
+    trigger?: AXPReportGenerationTrigger;
+    sourceRequestId?: string;
+    scheduleId?: string;
+    scheduledOccurrence?: string;
+}
+interface AXPReportGenerationCreateResult {
+    id: string;
+    jobId?: string;
+    status: AXPReportGenerationStatus;
 }
-type AXPExecutionReportResult = {
-    type: 'table';
-    items: Record<string, unknown>[];
-    total: number;
-    summary?: AXPReportTableSummaryResult;
-} | {
-    type: 'chart';
-    data: Record<string, unknown>;
-} | {
-    type: 'cards';
-    items: Record<string, unknown>[];
-} | {
-    type: 'custom';
-    data: unknown;
-} | {
-    type: 'pdf';
-    url?: string;
-    base64?: string;
-    blob?: Blob;
-    filename?: string;
-};
-type AXPExecutionReportCommandResult = AXPReportLayout & {
-    data: AXPExecutionReportResult;
-};
-interface AXPExecutionReportCommand extends AXPCommand<AXPLayoutExecutionContext, AXPExecutionReportCommandResult> {
+interface AXPReportGenerationExecuteInput {
+    reportRequestId: string;
 }
-/**
- * Report execution status and metadata
- */
-interface AXPReportExecutionStatus {
-    reportId: string;
-    layoutId: string;
-    status: 'pending' | 'executing' | 'completed' | 'failed' | 'cancelled';
-    startTime: Date;
-    endTime?: Date;
-    duration?: number;
-    recordCount?: number;
-    error?: AXPReportExecutionError;
+interface AXPReportGenerationExecuteResult {
+    reportRequestId: string;
+    fileIds: string[];
+    rowCount?: number;
 }
-/**
- * Detailed error information for report execution
- */
-interface AXPReportExecutionError {
-    code: string;
-    message: string;
-    details?: Record<string, unknown>;
-    stack?: string;
+interface AXPReportGenerationGetInput {
+    id: string;
 }
-/**
- * Report execution request with options
- */
-interface AXPReportExecutionRequest {
-    reportId: string;
-    layoutId: string;
-    parameters: Record<string, unknown>;
-    options?: AXPReportExecutionOptions;
+interface AXPReportGenerationGetViewerFreezeInput {
+    id: string;
 }
-/**
- * Options for report execution
- */
-interface AXPReportExecutionOptions {
-    timeout?: number;
-    priority?: 'low' | 'normal' | 'high';
-    cache?: boolean;
-    cacheTimeout?: number;
+interface AXPReportGenerationListMineInput {
+    skip?: number;
+    take?: number;
 }
 
-declare function reportEntityFactory(): Promise<AXPEntity | null>;
+declare const AXMReportManagementQueryKeys: {
+    readonly Category: {
+        readonly ListRoot: "ReportManagement:Category:ListRoot";
+        readonly GetById: "ReportManagement:Category:GetById";
+    };
+    readonly Report: {
+        readonly GetDefinition: "ReportManagement:Report:GetDefinition";
+    };
+    readonly ReportGeneration: {
+        readonly Get: "ReportManagement:ReportGeneration:Get";
+        readonly ListMine: "ReportManagement:ReportGeneration:ListMine";
+        readonly GetViewerFreeze: "ReportManagement:ReportGeneration:GetViewerFreeze";
+    };
+};
 
-declare function reportCategoryEntityFactory(): Promise<AXPEntity | null>;
+type AXMQuerySnapshotTriggerOperation = 'create' | 'update' | 'delete';
+interface AXMQuerySnapshotPolicyTriggers {
+    entities: string[];
+    operations: AXMQuerySnapshotTriggerOperation[];
+    debounceMs: number;
+}
+interface AXMQuerySnapshotPolicyEntityModel extends AXPEntityModel<string> {
+    queryName: string;
+    enabled: boolean;
+    schedule: string;
+    staleAfterMs: number;
+    triggers: AXMQuerySnapshotPolicyTriggers;
+}
+
+type AXMQuerySnapshotStatus = 'ready' | 'stale' | 'failed';
+type AXMQuerySnapshotPayload = {
+    success: true;
+    kind: 'value';
+    data: unknown;
+} | {
+    success: true;
+    kind: 'object';
+    data: unknown;
+} | {
+    success: true;
+    kind: 'collection';
+    data: AXPRuntimeCollectionData;
+};
+interface AXMQuerySnapshotEntityModel extends AXPEntityModel<string> {
+    key: string;
+    status: AXMQuerySnapshotStatus;
+    calculatedAt: string;
+    durationMs: number;
+    lastError?: string;
+    payload: AXMQuerySnapshotPayload;
+}
+interface AXMRecalculateQuerySnapshotsInput {
+    tenantId?: string;
+    applicationId?: string;
+    queryKeys?: string[];
+}
+interface AXMRefreshQuerySnapshotsInput {
+    queryKeys?: string[];
+}
 
-export { AXMPermissionsKeys, AXPReportManagementFeatureKeys, AXPReportManagementMenuKeys, RootConfig, reportCategoryEntityFactory, reportEntityFactory };
-export type { AXPAggregatedDataSource, AXPAggregation, AXPChartAxisConfig, AXPChartDataMapping, AXPChartInteractivity, AXPChartStyling, AXPConditionalFormatRule, AXPCustomDataSource, AXPDataTransformation, AXPExecutionReportCommand, AXPExecutionReportCommandResult, AXPExecutionReportResult, AXPLayoutDataSourceResolution, AXPLayoutExecutionContext, AXPLayoutSwitcherOption, AXPLayoutValidationResult, AXPQueryDataSource, AXPReportCategory, AXPReportChartLayout, AXPReportChartOptions, AXPReportColumn, AXPReportColumnInteractivity, AXPReportDataSource, AXPReportDefinition, AXPReportDrillDownConfig, AXPReportExecutionError, AXPReportExecutionOptions, AXPReportExecutionRequest, AXPReportExecutionStatus, AXPReportGroupByDefinition, AXPReportHeaderFooter, AXPReportLayout, AXPReportLayoutAction, AXPReportLayoutDefinition, AXPReportLayoutState, AXPReportLayoutType, AXPReportParameter, AXPReportParameterBinding, AXPReportParameterGroup, AXPReportPdfLayout, AXPReportPdfOptions, AXPReportSummaryOptions, AXPReportTableLayout, AXPReportTableLayoutRowAction, AXPReportTableSummaryResult, AXPTableOptions, AXPTransformedDataSource };
+export { AXMPermissionsKeys, AXMReportManagementCommandKeys, AXMReportManagementQueryKeys, AXM_RECALCULATE_QUERY_SNAPSHOTS_COMMAND_KEY, AXM_REFRESH_QUERY_SNAPSHOTS_COMMAND_KEY, AXPInsightsReportingPermissionKeys, AXPReportManagementFeatureKeys, AXPReportManagementMenuKeys, RootConfig };
+export type { AXMQuerySnapshotEntityModel, AXMQuerySnapshotPayload, AXMQuerySnapshotPolicyEntityModel, AXMQuerySnapshotPolicyTriggers, AXMQuerySnapshotStatus, AXMQuerySnapshotTriggerOperation, AXMRecalculateQuerySnapshotsInput, AXMRefreshQuerySnapshotsInput, AXMReportGenerationRequest, AXPAggregatedDataSource, AXPAggregation, AXPChartAxisConfig, AXPChartDataMapping, AXPChartInteractivity, AXPChartStyling, AXPConditionalFormatRule, AXPCustomDataSource, AXPDataTransformation, AXPLayoutSwitcherOption, AXPQueryDataSource, AXPReportArtifactKind, AXPReportCategory, AXPReportChartLayout, AXPReportChartOptions, AXPReportColumn, AXPReportColumnInteractivity, AXPReportDataSource, AXPReportDefinition, AXPReportDrillDownConfig, AXPReportEntityBinding, AXPReportEntityDisplay, AXPReportEntityParameterValue, AXPReportFreezeLayouts, AXPReportGenerationArtifact, AXPReportGenerationCreateInput, AXPReportGenerationCreateResult, AXPReportGenerationExecuteInput, AXPReportGenerationExecuteResult, AXPReportGenerationGetInput, AXPReportGenerationGetViewerFreezeInput, AXPReportGenerationListMineInput, AXPReportGenerationMode, AXPReportGenerationOptions, AXPReportGenerationStatus, AXPReportGenerationTrigger, AXPReportGroupByDefinition, AXPReportHeaderFooter, AXPReportLayout, AXPReportLayoutAction, AXPReportLayoutDefinition, AXPReportLayoutState, AXPReportLayoutType, AXPReportParameter, AXPReportParameterBinding, AXPReportParameterGroup, AXPReportPdfLayout, AXPReportPdfOptions, AXPReportSummaryOptions, AXPReportTableLayout, AXPReportTableLayoutRowAction, AXPReportTableSummaryResult, AXPReportViewerFreeze, AXPTableOptions, AXPTransformedDataSource };