@ftisindia/create-app 0.1.4 → 0.1.6

package/template/src/modules/reports/presentation/reports-views.controller.ts

@@ -0,0 +1,140 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  Param,
+  ParseUUIDPipe,
+  Patch,
+  Post,
+  Query,
+  UseGuards,
+} from '@nestjs/common';
+import {
+  ApiBearerAuth,
+  ApiCreatedResponse,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiTags,
+} from '@nestjs/swagger';
+import { DeletedResponseDto } from '../../../common/dto/mutation-response.dto';
+import { ApiProtectedErrorResponses } from '../../../common/swagger/api-error-responses';
+import { PermissionGuard } from '../../access-control/application/services/permission.guard';
+import { RequirePermissions } from '../../access-control/presentation/permissions.decorator';
+import { JwtAuthGuard } from '../../auth/infrastructure/passport/jwt-auth.guard';
+import { OrgScopeGuard } from '../../request-context/presentation/org-scope.guard';
+import { ReportsViewsService } from '../application/services/reports-views.service';
+import { CreateSavedViewDto } from '../dto/create-saved-view.dto';
+import { ListViewsQueryDto } from '../dto/list-views-query.dto';
+import {
+  SavedViewListResponseDto,
+  SavedViewResponseDto,
+} from '../dto/saved-view-response.dto';
+import { UpdateSavedViewDto } from '../dto/update-saved-view.dto';
+
+/**
+ * Saved views (design §4, finding #9): personal views need reports.read;
+ * creating a SHARED view (ownerId null) needs reports.update — and the engine
+ * re-checks reports.update on every mutation of a shared view, whatever the
+ * route-level key says.
+ */
+@ApiTags('Reports')
+@ApiBearerAuth()
+@ApiParam({ name: 'orgId', description: 'Organisation ID.', format: 'uuid' })
+@ApiProtectedErrorResponses(404, 409)
+@Controller('organisations/:orgId/reports')
+@UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+export class ReportsViewsController {
+  constructor(private readonly reportsViewsService: ReportsViewsService) {}
+
+  @Get(':key/views')
+  @RequirePermissions('reports.read')
+  @ApiParam({ name: 'key', description: 'Report definition key.' })
+  @ApiOperation({
+    summary:
+      'List saved views (personal + shared), each with a compatibility verdict against the requested version (§4).',
+  })
+  @ApiOkResponse({
+    description: 'Saved views with compatibility verdicts.',
+    type: SavedViewListResponseDto,
+  })
+  list(
+    @Param('orgId') orgId: string,
+    @Param('key') key: string,
+    @Query() query: ListViewsQueryDto,
+  ) {
+    return this.reportsViewsService.list(orgId, key, query);
+  }
+
+  @Post(':key/views')
+  @RequirePermissions('reports.read')
+  @ApiParam({ name: 'key', description: 'Report definition key.' })
+  @ApiOperation({ summary: 'Create a PERSONAL saved view.' })
+  @ApiCreatedResponse({
+    description: 'Created view.',
+    type: SavedViewResponseDto,
+  })
+  createPersonal(
+    @Param('orgId') orgId: string,
+    @Param('key') key: string,
+    @Body() dto: CreateSavedViewDto,
+  ) {
+    return this.reportsViewsService.createPersonal(orgId, key, dto);
+  }
+
+  @Post(':key/views/shared')
+  @RequirePermissions('reports.update')
+  @ApiParam({ name: 'key', description: 'Report definition key.' })
+  @ApiOperation({ summary: 'Create a SHARED (org-wide) saved view (finding #9).' })
+  @ApiCreatedResponse({
+    description: 'Created shared view.',
+    type: SavedViewResponseDto,
+  })
+  createShared(
+    @Param('orgId') orgId: string,
+    @Param('key') key: string,
+    @Body() dto: CreateSavedViewDto,
+  ) {
+    return this.reportsViewsService.createShared(orgId, key, dto);
+  }
+
+  @Patch(':key/views/:viewId')
+  @RequirePermissions('reports.read')
+  @ApiParam({ name: 'key', description: 'Report definition key.' })
+  @ApiParam({ name: 'viewId', description: 'Saved view ID.', format: 'uuid' })
+  @ApiOperation({
+    summary: 'Rename / respec a saved view. Personal: owner only. Shared: reports.update.',
+  })
+  @ApiOkResponse({
+    description: 'Updated view.',
+    type: SavedViewResponseDto,
+  })
+  update(
+    @Param('orgId') orgId: string,
+    @Param('key') key: string,
+    @Param('viewId', ParseUUIDPipe) viewId: string,
+    @Body() dto: UpdateSavedViewDto,
+  ) {
+    return this.reportsViewsService.update(orgId, key, viewId, dto);
+  }
+
+  @Delete(':key/views/:viewId')
+  @RequirePermissions('reports.read')
+  @ApiParam({ name: 'key', description: 'Report definition key.' })
+  @ApiParam({ name: 'viewId', description: 'Saved view ID.', format: 'uuid' })
+  @ApiOperation({
+    summary: 'Delete a saved view. Personal: owner only. Shared: reports.update.',
+  })
+  @ApiOkResponse({
+    description: 'Delete confirmation.',
+    type: DeletedResponseDto,
+  })
+  delete(
+    @Param('orgId') orgId: string,
+    @Param('key') key: string,
+    @Param('viewId', ParseUUIDPipe) viewId: string,
+  ) {
+    return this.reportsViewsService.delete(orgId, key, viewId);
+  }
+}

package/template/src/modules/reports/reports-forms.module.ts

@@ -0,0 +1,33 @@
+import { Module } from '@nestjs/common';
+import { FormsModule } from '../forms/forms.module';
+import { ReportsModule } from './reports.module';
+import { FormReportSourceProvider } from './infrastructure/forms-adapter/form-report-source.adapter';
+import {
+  EditSubmissionRowAction,
+  UpdateSubmissionStatusRowAction,
+} from './infrastructure/forms-adapter/form-row-actions';
+import { ReportsFormsBridgeBootstrap } from './infrastructure/forms-adapter/forms-bridge-bootstrap.service';
+
+/**
+ * OPTIONAL bridge between the report and form engines (report design
+ * §3.2/§13). Importing it adds form-backed reports (`source.kind: "form"`) and
+ * the delegated editSubmission/updateStatus grid verbs to the running app.
+ *
+ * It is the single artifact aware of BOTH products: it imports FormsModule
+ * (for SubmissionService, the form definition store, and the forms request
+ * context) and ReportsModule (for the engine's shared source-provider and
+ * row-action registries), and wires the form adapter into them at boot.
+ *
+ * Drop this import from AppModule and ReportsModule keeps working over custom
+ * sources alone — the standalone guarantee, made structural at the glue layer.
+ */
+@Module({
+  imports: [FormsModule, ReportsModule],
+  providers: [
+    FormReportSourceProvider,
+    EditSubmissionRowAction,
+    UpdateSubmissionStatusRowAction,
+    ReportsFormsBridgeBootstrap,
+  ],
+})
+export class ReportsFormsModule {}

package/template/src/modules/reports/reports.module.ts

@@ -0,0 +1,335 @@
+import { Module } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { DiscoveryModule } from '@nestjs/core';
+import {
+  createInMemoryResultCache,
+  ReportActionService,
+  ReportDefinitionService,
+  ReportExportService,
+  ReportQueryService,
+  ReportRowActionRegistry,
+  ReportSourceRegistry,
+  ReportTagService,
+  ReportViewService,
+  SourceProviderRegistry,
+  type ResultCache,
+} from '@ftisindia/report-builder';
+import { AuthModule } from '../auth/auth.module';
+import { ReportsActionsService } from './application/services/reports-actions.service';
+import { ReportsDefinitionsService } from './application/services/reports-definitions.service';
+import { ReportsExportsService } from './application/services/reports-exports.service';
+import { ReportsExportDispatcherService } from './application/services/reports-export-dispatcher.service';
+import { ReportsQueriesService } from './application/services/reports-queries.service';
+import { ReportsSettingsReader } from './application/services/reports-settings-reader.service';
+import { ReportsViewsService } from './application/services/reports-views.service';
+import { CaslReportsAuthorization } from './infrastructure/casl-reports-authorization';
+import { PrismaReportsAuditSink } from './infrastructure/audit-sink.adapter';
+import { ReportsPrismaTxRunner } from './infrastructure/prisma-tx-runner';
+import { PrismaQueryExecutor } from './infrastructure/prisma-query-executor';
+import { PrismaSnapshotRunner } from './infrastructure/prisma-snapshot-runner';
+import { PrismaReportsCatalog } from './infrastructure/prisma-catalog.adapter';
+import { ReportsJobQueueNoop } from './infrastructure/reports-job-queue.adapter';
+import { LocalDiskReportExportStorage } from './infrastructure/storage/local-disk-export-storage.adapter';
+import { RequestReportsContext } from './infrastructure/request-reports-context';
+import { ReportsRegistryBootstrapService } from './infrastructure/registry/registry-bootstrap.service';
+import { ReportsSchemaCheckService } from './infrastructure/schema-check/reports-schema-check.service';
+import {
+  PrismaBulkActionRunStore,
+  PrismaExportJobStore,
+  PrismaReportDefinitionStore,
+  PrismaRowTagStore,
+  PrismaSavedViewStore,
+} from './infrastructure/stores';
+import { ReportsActionsController } from './presentation/reports-actions.controller';
+import { ReportsDefinitionsController } from './presentation/reports-definitions.controller';
+import { ReportsExportController } from './presentation/reports-export.controller';
+import { ReportsExportJobsController } from './presentation/reports-export-jobs.controller';
+import { ReportsQueryController } from './presentation/reports-query.controller';
+import { ReportsViewsController } from './presentation/reports-views.controller';
+import { OrgMembersReportSource } from './sources/org-members.source';
+import { REPORTS_RESULT_CACHE, REPORTS_TOKEN_SECRET } from './reports.tokens';
+
+/**
+ * The reports glue module — binds the framework-free @ftisindia/report-builder
+ * engine to this app's services (request context, CASL RBAC, AuditService,
+ * Prisma) and ships reports-OWNED async-export infrastructure (its own worker
+ * over ReportExportJob + org-scoped file storage). It imports NO FormsModule:
+ * form-backed sources and the delegated grid verbs live in the optional
+ * ReportsFormsModule bridge (§3.2 standalone guarantee). Engine services are
+ * composed here via factories over the adapters and stores; app extensions
+ * register through the @ReportSource/@ReportRowAction decorators.
+ *
+ * The engine core knows nothing about the form builder (the standalone
+ * guarantee, report design §3.2); the forms adapter wired below is what makes
+ * `kind: "form"` sources exist in THIS app.
+ */
+@Module({
+  imports: [AuthModule, DiscoveryModule],
+  controllers: [
+    // Listed before the definitions controller so the literal 'exports'
+    // segment wins over the ':key' parameter on the shared base path.
+    ReportsExportJobsController,
+    ReportsDefinitionsController,
+    ReportsQueryController,
+    ReportsViewsController,
+    ReportsActionsController,
+    ReportsExportController,
+  ],
+  providers: [
+    // Adapters over the ecosystem seams.
+    RequestReportsContext,
+    CaslReportsAuthorization,
+    PrismaReportsAuditSink,
+    ReportsPrismaTxRunner,
+    PrismaQueryExecutor,
+    PrismaSnapshotRunner,
+    PrismaReportsCatalog,
+    // Reports-OWNED async-export infrastructure — no forms outbox / UploadedFile.
+    ReportsJobQueueNoop,
+    LocalDiskReportExportStorage,
+    ReportsExportDispatcherService,
+    // Prisma store implementations of the engine ports.
+    PrismaReportDefinitionStore,
+    PrismaSavedViewStore,
+    PrismaExportJobStore,
+    PrismaBulkActionRunStore,
+    PrismaRowTagStore,
+    ReportsSettingsReader,
+    // Engine registries — singletons; extensions land via the bootstrap scan.
+    { provide: ReportSourceRegistry, useFactory: () => new ReportSourceRegistry() },
+    { provide: SourceProviderRegistry, useFactory: () => new SourceProviderRegistry() },
+    { provide: ReportRowActionRegistry, useFactory: () => new ReportRowActionRegistry() },
+    // Result cache (§5.7) — in-memory by default; rebind the token for Redis.
+    { provide: REPORTS_RESULT_CACHE, useFactory: () => createInMemoryResultCache() },
+    // HMAC key bytes for cursors and action tokens (resolved in reports.config).
+    {
+      provide: REPORTS_TOKEN_SECRET,
+      useFactory: (config: ConfigService) => {
+        const secret = config.get<Uint8Array>('reports.tokenSecret');
+        if (secret === undefined || secret.length === 0) {
+          throw new Error('reports.tokenSecret failed to resolve — check reports.config.ts.');
+        }
+        return secret;
+      },
+      inject: [ConfigService],
+    },
+    // Engine orchestration services, composed over the seams above.
+    {
+      provide: ReportDefinitionService,
+      useFactory: (
+        store: PrismaReportDefinitionStore,
+        providers: SourceProviderRegistry,
+        rowActions: ReportRowActionRegistry,
+        authz: CaslReportsAuthorization,
+        audit: PrismaReportsAuditSink,
+        txRunner: ReportsPrismaTxRunner,
+        catalog: PrismaReportsCatalog,
+        executor: PrismaQueryExecutor,
+        settings: ReportsSettingsReader,
+        secret: Uint8Array,
+      ) =>
+        new ReportDefinitionService({
+          store,
+          providers,
+          rowActions,
+          authz,
+          audit,
+          txRunner,
+          catalog,
+          executor,
+          policyFor: (orgId) => settings.policyFor(orgId),
+          secret,
+        }),
+      inject: [
+        PrismaReportDefinitionStore,
+        SourceProviderRegistry,
+        ReportRowActionRegistry,
+        CaslReportsAuthorization,
+        PrismaReportsAuditSink,
+        ReportsPrismaTxRunner,
+        PrismaReportsCatalog,
+        PrismaQueryExecutor,
+        ReportsSettingsReader,
+        REPORTS_TOKEN_SECRET,
+      ],
+    },
+    {
+      provide: ReportQueryService,
+      useFactory: (
+        store: PrismaReportDefinitionStore,
+        providers: SourceProviderRegistry,
+        rowActions: ReportRowActionRegistry,
+        tags: PrismaRowTagStore,
+        executor: PrismaQueryExecutor,
+        authz: CaslReportsAuthorization,
+        cache: ResultCache,
+        settings: ReportsSettingsReader,
+        secret: Uint8Array,
+      ) =>
+        new ReportQueryService({
+          store,
+          providers,
+          rowActions,
+          tags,
+          executor,
+          authz,
+          cache,
+          policyFor: (orgId) => settings.policyFor(orgId),
+          secret,
+        }),
+      inject: [
+        PrismaReportDefinitionStore,
+        SourceProviderRegistry,
+        ReportRowActionRegistry,
+        PrismaRowTagStore,
+        PrismaQueryExecutor,
+        CaslReportsAuthorization,
+        REPORTS_RESULT_CACHE,
+        ReportsSettingsReader,
+        REPORTS_TOKEN_SECRET,
+      ],
+    },
+    {
+      provide: ReportViewService,
+      useFactory: (
+        views: PrismaSavedViewStore,
+        definitions: PrismaReportDefinitionStore,
+        authz: CaslReportsAuthorization,
+        audit: PrismaReportsAuditSink,
+        txRunner: ReportsPrismaTxRunner,
+      ) => new ReportViewService({ views, definitions, authz, audit, txRunner }),
+      inject: [
+        PrismaSavedViewStore,
+        PrismaReportDefinitionStore,
+        CaslReportsAuthorization,
+        PrismaReportsAuditSink,
+        ReportsPrismaTxRunner,
+      ],
+    },
+    {
+      provide: ReportTagService,
+      useFactory: (
+        tags: PrismaRowTagStore,
+        authz: CaslReportsAuthorization,
+        audit: PrismaReportsAuditSink,
+        settings: ReportsSettingsReader,
+      ) =>
+        new ReportTagService({
+          tags,
+          authz,
+          audit,
+          policyFor: (orgId) => settings.policyFor(orgId),
+        }),
+      inject: [
+        PrismaRowTagStore,
+        CaslReportsAuthorization,
+        PrismaReportsAuditSink,
+        ReportsSettingsReader,
+      ],
+    },
+    {
+      provide: ReportActionService,
+      useFactory: (
+        definitions: PrismaReportDefinitionStore,
+        providers: SourceProviderRegistry,
+        actions: ReportRowActionRegistry,
+        runs: PrismaBulkActionRunStore,
+        executor: PrismaQueryExecutor,
+        authz: CaslReportsAuthorization,
+        audit: PrismaReportsAuditSink,
+        txRunner: ReportsPrismaTxRunner,
+        cache: ResultCache,
+        settings: ReportsSettingsReader,
+        secret: Uint8Array,
+      ) =>
+        new ReportActionService({
+          definitions,
+          providers,
+          actions,
+          runs,
+          executor,
+          authz,
+          audit,
+          txRunner,
+          cache,
+          policyFor: (orgId) => settings.policyFor(orgId),
+          secret,
+          // Glue row actions are Nest providers with their own injection —
+          // the engine's service-locator seam stays empty in this app.
+          services: {},
+        }),
+      inject: [
+        PrismaReportDefinitionStore,
+        SourceProviderRegistry,
+        ReportRowActionRegistry,
+        PrismaBulkActionRunStore,
+        PrismaQueryExecutor,
+        CaslReportsAuthorization,
+        PrismaReportsAuditSink,
+        ReportsPrismaTxRunner,
+        REPORTS_RESULT_CACHE,
+        ReportsSettingsReader,
+        REPORTS_TOKEN_SECRET,
+      ],
+    },
+    {
+      provide: ReportExportService,
+      useFactory: (
+        definitions: PrismaReportDefinitionStore,
+        providers: SourceProviderRegistry,
+        jobs: PrismaExportJobStore,
+        queue: ReportsJobQueueNoop,
+        sink: LocalDiskReportExportStorage,
+        snapshot: PrismaSnapshotRunner,
+        executor: PrismaQueryExecutor,
+        authz: CaslReportsAuthorization,
+        audit: PrismaReportsAuditSink,
+        txRunner: ReportsPrismaTxRunner,
+        settings: ReportsSettingsReader,
+        secret: Uint8Array,
+      ) =>
+        new ReportExportService({
+          definitions,
+          providers,
+          jobs,
+          queue,
+          sink,
+          snapshot,
+          executor,
+          authz,
+          audit,
+          txRunner,
+          policyFor: (orgId) => settings.policyFor(orgId),
+          secret,
+        }),
+      inject: [
+        PrismaReportDefinitionStore,
+        SourceProviderRegistry,
+        PrismaExportJobStore,
+        ReportsJobQueueNoop,
+        LocalDiskReportExportStorage,
+        PrismaSnapshotRunner,
+        PrismaQueryExecutor,
+        CaslReportsAuthorization,
+        PrismaReportsAuditSink,
+        ReportsPrismaTxRunner,
+        ReportsSettingsReader,
+        REPORTS_TOKEN_SECRET,
+      ],
+    },
+    // The example custom source (form-backed sources + delegated form verbs
+    // live in the optional ReportsFormsModule, not here — §3.2 standalone).
+    OrgMembersReportSource,
+    // Startup wiring + background work.
+    ReportsRegistryBootstrapService,
+    ReportsSchemaCheckService,
+    // Thin HTTP-facing services.
+    ReportsDefinitionsService,
+    ReportsQueriesService,
+    ReportsViewsService,
+    ReportsActionsService,
+    ReportsExportsService,
+  ],
+  exports: [ReportSourceRegistry, SourceProviderRegistry, ReportRowActionRegistry],
+})
+export class ReportsModule {}

package/template/src/modules/reports/reports.tokens.ts

@@ -0,0 +1,11 @@
+/**
+ * DI tokens for swappable reports seams. The defaults are bound in
+ * reports.module.ts; apps override them with custom providers (e.g. a
+ * Redis-backed ResultCache) without touching the module internals.
+ */
+
+/** Binds the engine's ResultCache port (report design §5.7). */
+export const REPORTS_RESULT_CACHE = Symbol('REPORTS_RESULT_CACHE');
+
+/** Key bytes for cursor/action-token HMACs (report design §5.3/§6.3). */
+export const REPORTS_TOKEN_SECRET = Symbol('REPORTS_TOKEN_SECRET');

package/template/src/modules/reports/sources/org-members.source.ts

@@ -0,0 +1,112 @@
+import { Injectable } from '@nestjs/common';
+import type { ReportSourceDef, SourceManifest, SourceQuery } from '@ftisindia/report-builder';
+import { ReportSource } from '../infrastructure/registry/report-extension.decorators';
+
+/**
+ * `kind: "custom"` example source (report design §3.2) over the template's own
+ * Membership/User/Role tables — the Phase-1 milestone proof (§14): a complete
+ * report with NO form-builder involvement, demonstrating the standalone
+ * guarantee before form integration exists.
+ *
+ * The contract split (§3): this class declares STRUCTURE only — the compiler
+ * owns query construction. It never sees a QuerySpec, so it cannot be injected
+ * and cannot bypass the allowlist.
+ *
+ * Nullability is read off prisma/schema.prisma, not assumed: User.displayName
+ * and User.email are nullable (String?), so their sortable columns are
+ * COALESCE-wrapped to '' and declared nullable: false — NULL poisons keyset
+ * predicates (§5.3). Role.name and the Membership columns are NOT NULL.
+ *
+ * Index specs are honest documentation (§5.2): they name the indexes an app
+ * WOULD create to publish this source on the indexed tier (org-leading btrees
+ * are impossible for User-side columns — User carries no orgId — so those
+ * specs live on "User" without the org prefix). The shipped example report
+ * runs on the LIVE tier, where the catalog lint does not require them.
+ */
+@Injectable()
+@ReportSource()
+export class OrgMembersReportSource implements ReportSourceDef {
+  readonly key = 'org-members';
+
+  manifest(): SourceManifest {
+    return {
+      // Membership id — the stable row identity tags and actions bind to (§7).
+      rowId: 'm."id"',
+      orgScoped: true,
+      columns: [
+        {
+          id: 'displayName',
+          sql: `COALESCE(u."displayName", '')`,
+          type: 'text',
+          sortable: true,
+          filterable: true,
+          searchable: true,
+          search: { mode: 'trgm' },
+          nullable: false,
+          collation: 'C',
+          index: {
+            name: 'idx_rb_member_display',
+            kind: 'btree',
+            table: 'User',
+            expr: `COALESCE("displayName", '') COLLATE "C"`,
+          },
+          // A btree cannot carry gin_trgm_ops — search gets its own index.
+          searchIndex: {
+            name: 'idx_rb_member_display_trgm',
+            kind: 'gin',
+            table: 'User',
+            expr: `COALESCE("displayName", '') gin_trgm_ops`,
+          },
+        },
+        {
+          id: 'email',
+          // User.email is String? in schema.prisma — surrogate '' keeps the
+          // sort key non-null (§5.3).
+          sql: `COALESCE(u."email", '')`,
+          type: 'text',
+          sortable: true,
+          filterable: true,
+          nullable: false,
+          collation: 'C',
+        },
+        {
+          id: 'role',
+          sql: 'r."name"',
+          type: 'text',
+          sortable: true,
+          filterable: true,
+          nullable: false,
+          collation: 'C',
+        },
+        {
+          id: 'status',
+          // MembershipStatus enum → text for binds and projection.
+          sql: 'm."status"::text',
+          type: 'enum',
+          filterable: true,
+          nullable: false,
+        },
+        {
+          id: 'joinedAt',
+          sql: 'm."createdAt"',
+          type: 'datetime',
+          valueKind: 'native',
+          sortable: true,
+          nullable: false,
+        },
+      ],
+    };
+  }
+
+  /** FROM/JOIN only — WHERE/ORDER/LIMIT belong to the compiler (§3). */
+  baseQuery(): SourceQuery {
+    return {
+      from:
+        '"Membership" m' +
+        ' JOIN "User" u ON u."id" = m."userId"' +
+        ' JOIN "Role" r ON r."id" = m."roleId"',
+      orgColumn: 'm."orgId"',
+      primaryTable: 'Membership',
+    };
+  }
+}