@ftisindia/create-app 0.1.5 → 0.2.0

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

@@ -0,0 +1,156 @@
+import {
+  Body,
+  Controller,
+  Get,
+  HttpCode,
+  Param,
+  Patch,
+  Post,
+  Query,
+  UseGuards,
+} from '@nestjs/common';
+import {
+  ApiBearerAuth,
+  ApiCreatedResponse,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiTags,
+  ApiUnprocessableEntityResponse,
+} from '@nestjs/swagger';
+import { ErrorResponseDto } from '../../../common/dto/error-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 { ReportsDefinitionsService } from '../application/services/reports-definitions.service';
+import { ReportsQueriesService } from '../application/services/reports-queries.service';
+import { CreateReportDefinitionDto } from '../dto/create-report-definition.dto';
+import { ListReportsQueryDto } from '../dto/list-reports-query.dto';
+import {
+  ReportArchivedResponseDto,
+  ReportDefinitionListResponseDto,
+  ReportDefinitionResponseDto,
+} from '../dto/report-definition-response.dto';
+import { ReportMetaQueryDto } from '../dto/report-meta-query.dto';
+import { ReportMetaResponseDto } from '../dto/report-meta-response.dto';
+import { UpdateReportDefinitionDto } from '../dto/update-report-definition.dto';
+
+@ApiTags('Reports')
+@ApiBearerAuth()
+@ApiParam({ name: 'orgId', description: 'Organisation ID.', format: 'uuid' })
+@ApiProtectedErrorResponses(404, 409)
+@ApiUnprocessableEntityResponse({
+  description: 'The report definition failed engine validation or linting (§5.2/§8).',
+  type: ErrorResponseDto,
+})
+@Controller('organisations/:orgId/reports')
+@UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+export class ReportsDefinitionsController {
+  constructor(
+    private readonly reportsDefinitionsService: ReportsDefinitionsService,
+    private readonly reportsQueriesService: ReportsQueriesService,
+  ) {}
+
+  @Get()
+  @RequirePermissions('reports.read')
+  @ApiOperation({ summary: 'List report definitions.' })
+  @ApiOkResponse({
+    description: 'Report definitions.',
+    type: ReportDefinitionListResponseDto,
+  })
+  list(@Param('orgId') orgId: string, @Query() query: ListReportsQueryDto) {
+    return this.reportsDefinitionsService.list(orgId, query);
+  }
+
+  @Post()
+  @RequirePermissions('reports.create')
+  @ApiOperation({ summary: 'Create a new draft report definition version.' })
+  @ApiCreatedResponse({
+    description: 'Created draft definition.',
+    type: ReportDefinitionResponseDto,
+  })
+  create(@Param('orgId') orgId: string, @Body() dto: CreateReportDefinitionDto) {
+    return this.reportsDefinitionsService.create(orgId, dto);
+  }
+
+  @Get(':key')
+  @RequirePermissions('reports.read')
+  @ApiParam({ name: 'key', description: 'Report definition key.' })
+  @ApiOperation({ summary: 'Return the latest version of a report definition.' })
+  @ApiOkResponse({
+    description: 'Latest definition version.',
+    type: ReportDefinitionResponseDto,
+  })
+  getLatest(@Param('orgId') orgId: string, @Param('key') key: string) {
+    return this.reportsDefinitionsService.getLatest(orgId, key);
+  }
+
+  @Patch(':key')
+  @RequirePermissions('reports.update')
+  @ApiParam({ name: 'key', description: 'Report definition key.' })
+  @ApiOperation({
+    summary:
+      'Edit the draft. Editing a published version opens a new draft version (published rows are immutable, §2).',
+  })
+  @ApiOkResponse({
+    description: 'Updated draft definition.',
+    type: ReportDefinitionResponseDto,
+  })
+  update(
+    @Param('orgId') orgId: string,
+    @Param('key') key: string,
+    @Body() dto: UpdateReportDefinitionDto,
+  ) {
+    return this.reportsDefinitionsService.update(orgId, key, dto);
+  }
+
+  @Post(':key/publish')
+  @HttpCode(200)
+  @RequirePermissions('reports.publish')
+  @ApiParam({ name: 'key', description: 'Report definition key.' })
+  @ApiOperation({
+    summary:
+      'Publish the latest draft: the §5.2 layered lint runs here, failing constructively with the suggested migration SQL (§8).',
+  })
+  @ApiOkResponse({
+    description: 'Published definition.',
+    type: ReportDefinitionResponseDto,
+  })
+  publish(@Param('orgId') orgId: string, @Param('key') key: string) {
+    return this.reportsDefinitionsService.publish(orgId, key);
+  }
+
+  @Post(':key/archive')
+  @HttpCode(200)
+  @RequirePermissions('reports.archive')
+  @ApiParam({ name: 'key', description: 'Report definition key.' })
+  @ApiOperation({ summary: 'Archive every version of a report definition.' })
+  @ApiOkResponse({
+    description: 'Archive confirmation.',
+    type: ReportArchivedResponseDto,
+  })
+  archive(@Param('orgId') orgId: string, @Param('key') key: string) {
+    return this.reportsDefinitionsService.archive(orgId, key);
+  }
+
+  @Get(':key/meta')
+  @RequirePermissions('reports.read')
+  @ApiParam({ name: 'key', description: 'Report definition key.' })
+  @ApiOperation({
+    summary:
+      'Return the self-describing grid descriptor: columns, typed operators, actions, export config (§4).',
+  })
+  @ApiOkResponse({
+    description: 'Report metadata descriptor.',
+    type: ReportMetaResponseDto,
+  })
+  meta(
+    @Param('orgId') orgId: string,
+    @Param('key') key: string,
+    @Query() query: ReportMetaQueryDto,
+  ) {
+    return this.reportsQueriesService.meta(orgId, key, query.version ?? null);
+  }
+}

package/template/src/modules/reports/presentation/reports-export-jobs.controller.ts

@@ -0,0 +1,61 @@
+import { Controller, Get, Param, ParseUUIDPipe, StreamableFile, UseGuards } from '@nestjs/common';
+import {
+  ApiBearerAuth,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiProduces,
+  ApiTags,
+} from '@nestjs/swagger';
+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 { ReportsExportsService } from '../application/services/reports-exports.service';
+import { ExportJobResponseDto } from '../dto/export-job-response.dto';
+
+/**
+ * MUST be registered BEFORE ReportsDefinitionsController in the module's
+ * controllers array: both controllers share the 'organisations/:orgId/reports'
+ * base path, and the literal 'exports' segment has to win over the ':key'
+ * parameter route ('exports' is a reserved report key for the same reason).
+ */
+@ApiTags('Reports')
+@ApiBearerAuth()
+@ApiParam({ name: 'orgId', description: 'Organisation ID.', format: 'uuid' })
+@ApiProtectedErrorResponses(404)
+@Controller('organisations/:orgId/reports/exports')
+@UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+export class ReportsExportJobsController {
+  constructor(private readonly reportsExportsService: ReportsExportsService) {}
+
+  @Get(':jobId')
+  @RequirePermissions('reports.export')
+  @ApiParam({ name: 'jobId', description: 'Export job ID.', format: 'uuid' })
+  @ApiOperation({ summary: 'Return the status of an async export job (§9/§10).' })
+  @ApiOkResponse({
+    description: 'Export job status.',
+    type: ExportJobResponseDto,
+  })
+  getJob(@Param('orgId') orgId: string, @Param('jobId', ParseUUIDPipe) jobId: string) {
+    return this.reportsExportsService.getJob(orgId, jobId);
+  }
+
+  @Get(':jobId/download')
+  @RequirePermissions('reports.export')
+  @ApiParam({ name: 'jobId', description: 'Export job ID.', format: 'uuid' })
+  @ApiOperation({ summary: 'Download a finished async export file (§9).' })
+  @ApiProduces('text/csv', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet')
+  @ApiOkResponse({ description: 'The export file stream.' })
+  async download(
+    @Param('orgId') orgId: string,
+    @Param('jobId', ParseUUIDPipe) jobId: string,
+  ): Promise<StreamableFile> {
+    const file = await this.reportsExportsService.download(orgId, jobId);
+    return new StreamableFile(file.stream, {
+      type: file.mimeType,
+      disposition: `attachment; filename="${file.fileName}"`,
+    });
+  }
+}

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

@@ -0,0 +1,76 @@
+import {
+  Body,
+  Controller,
+  Header,
+  HttpCode,
+  Param,
+  Post,
+  Res,
+  StreamableFile,
+  UseGuards,
+} from '@nestjs/common';
+import { Readable } from 'node:stream';
+import type { Response } from 'express';
+import {
+  ApiAcceptedResponse,
+  ApiBearerAuth,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiTags,
+  ApiUnprocessableEntityResponse,
+} from '@nestjs/swagger';
+import { ErrorResponseDto } from '../../../common/dto/error-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 { ReportsExportsService } from '../application/services/reports-exports.service';
+import { ExportJobResponseDto } from '../dto/export-job-response.dto';
+import { ExportRequestDto } from '../dto/export-request.dto';
+
+@ApiTags('Reports')
+@ApiBearerAuth()
+@ApiParam({ name: 'orgId', description: 'Organisation ID.', format: 'uuid' })
+@ApiProtectedErrorResponses(404)
+@ApiUnprocessableEntityResponse({
+  description: 'The export was rejected (snapshot bound exceeded, no exportable columns, §9).',
+  type: ErrorResponseDto,
+})
+@Controller('organisations/:orgId/reports')
+@UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+export class ReportsExportController {
+  constructor(private readonly reportsExportsService: ReportsExportsService) {}
+
+  @Post(':key/export')
+  @HttpCode(200)
+  @Header('Cache-Control', 'no-store')
+  @RequirePermissions('reports.export')
+  @ApiParam({ name: 'key', description: 'Report definition key.' })
+  @ApiOperation({
+    summary:
+      'Export report rows (PII egress — separately permissioned, always audited): sync stream up to the cap, 202 job above it (§9).',
+  })
+  @ApiOkResponse({ description: 'The export file stream (CSV or XLSX).' })
+  @ApiAcceptedResponse({
+    description: 'The selection exceeds the sync cap; an async export job was queued.',
+    type: ExportJobResponseDto,
+  })
+  async export(
+    @Param('orgId') orgId: string,
+    @Param('key') key: string,
+    @Body() dto: ExportRequestDto,
+    @Res({ passthrough: true }) res: Response,
+  ) {
+    const outcome = await this.reportsExportsService.requestExport(orgId, key, dto);
+    if (outcome.kind === 'stream') {
+      return new StreamableFile(Readable.from(outcome.stream), {
+        type: outcome.mimeType,
+        disposition: `attachment; filename="${outcome.fileName}"`,
+      });
+    }
+    res.status(202);
+    return outcome.job;
+  }
+}

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

@@ -0,0 +1,52 @@
+import { Body, Controller, HttpCode, Param, Post, UseGuards } from '@nestjs/common';
+import {
+  ApiBearerAuth,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiRequestTimeoutResponse,
+  ApiTags,
+} from '@nestjs/swagger';
+import { ErrorResponseDto } from '../../../common/dto/error-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 { ReportsQueriesService } from '../application/services/reports-queries.service';
+import { QueryResponseDto } from '../dto/query-response.dto';
+import { QuerySpecDto } from '../dto/query-spec.dto';
+
+@ApiTags('Reports')
+@ApiBearerAuth()
+@ApiParam({ name: 'orgId', description: 'Organisation ID.', format: 'uuid' })
+@ApiProtectedErrorResponses(404)
+@ApiRequestTimeoutResponse({
+  description: 'The report query exceeded its statement budget (§5.2).',
+  type: ErrorResponseDto,
+})
+@Controller('organisations/:orgId/reports')
+@UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+export class ReportsQueryController {
+  constructor(private readonly reportsQueriesService: ReportsQueriesService) {}
+
+  @Post(':key/query')
+  @HttpCode(200)
+  @RequirePermissions('reports.read')
+  @ApiParam({ name: 'key', description: 'Report definition key.' })
+  @ApiOperation({
+    summary:
+      'THE grid endpoint (§4): one declarative QuerySpec for filters, search, sort, keyset paging, counts, and projection.',
+  })
+  @ApiOkResponse({
+    description: 'Query result page.',
+    type: QueryResponseDto,
+  })
+  query(
+    @Param('orgId') orgId: string,
+    @Param('key') key: string,
+    @Body() spec: QuerySpecDto,
+  ) {
+    return this.reportsQueriesService.query(orgId, key, spec);
+  }
+}

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 {}