@ftisindia/create-app 0.1.5 → 0.2.0

package/template/src/modules/reports/infrastructure/stores/prisma-bulk-action-run.store.ts

@@ -0,0 +1,89 @@
+import { Injectable } from '@nestjs/common';
+import { Prisma, ReportBulkActionRun as ReportBulkActionRunRow } from '@prisma/client';
+import type {
+  ActionRunStatus,
+  BulkActionRunRecord,
+  BulkActionRunStore,
+  NewBulkActionRunRecord,
+} from '@ftisindia/report-builder';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+
+/**
+ * The bulk-action idempotency ledger (report design §6.3, finding #7): the
+ * (orgId, idempotencyKey) unique makes `begin` an atomic claim — exactly one
+ * caller creates the RUNNING row; a retry gets the existing row back and
+ * returns the recorded outcome instead of re-running the verb.
+ */
+@Injectable()
+export class PrismaBulkActionRunStore implements BulkActionRunStore {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async begin(
+    record: NewBulkActionRunRecord,
+  ): Promise<{ created: boolean; run: BulkActionRunRecord }> {
+    try {
+      const row = await this.prisma.reportBulkActionRun.create({
+        data: {
+          orgId: record.orgId,
+          reportKey: record.reportKey,
+          reportVersion: record.reportVersion,
+          action: record.action,
+          idempotencyKey: record.idempotencyKey,
+          status: 'RUNNING',
+        },
+      });
+
+      return { created: true, run: this.toRecord(row) };
+    } catch (error) {
+      if (!(error instanceof Prisma.PrismaClientKnownRequestError) || error.code !== 'P2002') {
+        throw error;
+      }
+
+      const existing = await this.prisma.reportBulkActionRun.findUnique({
+        where: {
+          orgId_idempotencyKey: { orgId: record.orgId, idempotencyKey: record.idempotencyKey },
+        },
+      });
+
+      if (!existing) {
+        // The claiming row vanished between the conflict and the lookup —
+        // surface the original conflict rather than inventing state.
+        throw error;
+      }
+
+      return { created: false, run: this.toRecord(existing) };
+    }
+  }
+
+  async complete(
+    orgId: string,
+    id: string,
+    status: 'DONE' | 'FAILED',
+    result?: unknown,
+  ): Promise<void> {
+    await this.prisma.reportBulkActionRun.updateMany({
+      where: { id, orgId },
+      data: {
+        status,
+        ...(result !== undefined
+          ? { result: result === null ? Prisma.DbNull : (result as Prisma.InputJsonValue) }
+          : {}),
+      },
+    });
+  }
+
+  private toRecord(row: ReportBulkActionRunRow): BulkActionRunRecord {
+    return {
+      id: row.id,
+      orgId: row.orgId,
+      reportKey: row.reportKey,
+      reportVersion: row.reportVersion,
+      action: row.action,
+      idempotencyKey: row.idempotencyKey,
+      status: row.status as ActionRunStatus,
+      result: row.result,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+    };
+  }
+}

package/template/src/modules/reports/infrastructure/stores/prisma-export-job.store.ts

@@ -0,0 +1,93 @@
+import { Injectable } from '@nestjs/common';
+import { Prisma, ReportExportJob as ReportExportJobRow } from '@prisma/client';
+import type {
+  EngineTx,
+  ExportJobRecord,
+  ExportJobSpec,
+  ExportJobStatus,
+  ExportJobStore,
+  NewExportJobRecord,
+} from '@ftisindia/report-builder';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+
+@Injectable()
+export class PrismaExportJobStore implements ExportJobStore {
+  constructor(private readonly prisma: PrismaService) {}
+
+  private client(tx?: EngineTx) {
+    return tx ? (tx as unknown as Prisma.TransactionClient) : this.prisma;
+  }
+
+  async create(record: NewExportJobRecord, tx?: EngineTx): Promise<ExportJobRecord> {
+    const row = await this.client(tx).reportExportJob.create({
+      data: {
+        orgId: record.orgId,
+        reportKey: record.reportKey,
+        reportVersion: record.reportVersion,
+        // The FULL spec {spec, format, columns} — replayable and auditable,
+        // never a hash (report design §9, finding #1/#8).
+        spec: record.spec as unknown as Prisma.InputJsonValue,
+        status: 'PENDING',
+        requestedBy: record.requestedBy,
+      },
+    });
+
+    return this.toRecord(row);
+  }
+
+  async findById(orgId: string, id: string): Promise<ExportJobRecord | null> {
+    const row = await this.client().reportExportJob.findFirst({
+      where: { id, orgId },
+    });
+
+    return row ? this.toRecord(row) : null;
+  }
+
+  async markRunning(orgId: string, id: string): Promise<void> {
+    await this.client().reportExportJob.updateMany({
+      where: { id, orgId },
+      data: { status: 'RUNNING' },
+    });
+  }
+
+  async markDone(
+    orgId: string,
+    id: string,
+    outcome: { fileId: string; rowCount: number; asOf: Date },
+  ): Promise<void> {
+    await this.client().reportExportJob.updateMany({
+      where: { id, orgId },
+      data: {
+        status: 'DONE',
+        fileId: outcome.fileId,
+        rowCount: outcome.rowCount,
+        asOf: outcome.asOf,
+      },
+    });
+  }
+
+  async markFailed(orgId: string, id: string, error: string): Promise<void> {
+    await this.client().reportExportJob.updateMany({
+      where: { id, orgId },
+      data: { status: 'FAILED', error },
+    });
+  }
+
+  private toRecord(row: ReportExportJobRow): ExportJobRecord {
+    return {
+      id: row.id,
+      orgId: row.orgId,
+      reportKey: row.reportKey,
+      reportVersion: row.reportVersion,
+      spec: row.spec as unknown as ExportJobSpec,
+      asOf: row.asOf,
+      status: row.status as ExportJobStatus,
+      fileId: row.fileId,
+      rowCount: row.rowCount,
+      error: row.error,
+      requestedBy: row.requestedBy,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+    };
+  }
+}

package/template/src/modules/reports/infrastructure/stores/prisma-report-definition.store.ts

@@ -0,0 +1,171 @@
+import { Injectable } from '@nestjs/common';
+import { Prisma, ReportDefinition as ReportDefinitionRow } from '@prisma/client';
+import {
+  ReportConflictError,
+  ReportNotFoundError,
+  type CompiledDefinitionMeta,
+  type EngineTx,
+  type NewReportDefinitionRecord,
+  type ReportDefinition,
+  type ReportDefinitionPatch,
+  type ReportDefinitionRecord,
+  type ReportDefinitionStatus,
+  type ReportDefinitionStore,
+} from '@ftisindia/report-builder';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+
+@Injectable()
+export class PrismaReportDefinitionStore implements ReportDefinitionStore {
+  constructor(private readonly prisma: PrismaService) {}
+
+  private client(tx?: EngineTx) {
+    return tx ? (tx as unknown as Prisma.TransactionClient) : this.prisma;
+  }
+
+  async create(record: NewReportDefinitionRecord, tx?: EngineTx): Promise<ReportDefinitionRecord> {
+    try {
+      const row = await this.client(tx).reportDefinition.create({
+        data: {
+          orgId: record.orgId,
+          key: record.key,
+          version: record.version,
+          status: record.status,
+          schema: record.schema as unknown as Prisma.InputJsonValue,
+        },
+      });
+
+      return this.toRecord(row);
+    } catch (error) {
+      // The (orgId, key, version) unique — a concurrent draft/publish race.
+      if (error instanceof Prisma.PrismaClientKnownRequestError && error.code === 'P2002') {
+        throw new ReportConflictError(
+          `Report definition "${record.key}" v${record.version} already exists in this organisation.`,
+        );
+      }
+      throw error;
+    }
+  }
+
+  async update(
+    orgId: string,
+    key: string,
+    version: number,
+    patch: ReportDefinitionPatch,
+    tx?: EngineTx,
+  ): Promise<ReportDefinitionRecord> {
+    const client = this.client(tx);
+
+    const existing = await client.reportDefinition.findUnique({
+      where: { orgId_key_version: { orgId, key, version } },
+      select: { id: true },
+    });
+
+    if (!existing) {
+      throw new ReportNotFoundError(
+        `Report definition "${key}" v${version} was not found in this organisation.`,
+      );
+    }
+
+    const row = await client.reportDefinition.update({
+      where: { id: existing.id },
+      data: {
+        ...(patch.status !== undefined ? { status: patch.status } : {}),
+        ...(patch.schema !== undefined
+          ? { schema: patch.schema as unknown as Prisma.InputJsonValue }
+          : {}),
+        ...(patch.compiled !== undefined
+          ? {
+              compiled:
+                patch.compiled === null
+                  ? Prisma.DbNull
+                  : (patch.compiled as unknown as Prisma.InputJsonValue),
+            }
+          : {}),
+      },
+    });
+
+    return this.toRecord(row);
+  }
+
+  async findByKeyVersion(
+    orgId: string,
+    key: string,
+    version: number,
+    tx?: EngineTx,
+  ): Promise<ReportDefinitionRecord | null> {
+    const row = await this.client(tx).reportDefinition.findUnique({
+      where: { orgId_key_version: { orgId, key, version } },
+    });
+
+    return row ? this.toRecord(row) : null;
+  }
+
+  async findLatest(
+    orgId: string,
+    key: string,
+    status?: ReportDefinitionStatus,
+  ): Promise<ReportDefinitionRecord | null> {
+    const row = await this.client().reportDefinition.findFirst({
+      where: { orgId, key, ...(status ? { status } : {}) },
+      orderBy: { version: 'desc' },
+    });
+
+    return row ? this.toRecord(row) : null;
+  }
+
+  async findAllByKeyStatus(
+    orgId: string,
+    key: string,
+    status: ReportDefinitionStatus,
+    tx?: EngineTx,
+  ): Promise<ReportDefinitionRecord[]> {
+    const rows = await this.client(tx).reportDefinition.findMany({
+      where: { orgId, key, status },
+      orderBy: { version: 'desc' },
+    });
+
+    return rows.map((row) => this.toRecord(row));
+  }
+
+  async list(
+    orgId: string,
+    options: { status?: ReportDefinitionStatus; cursor?: string; limit: number },
+  ): Promise<ReportDefinitionRecord[]> {
+    const rows = await this.client().reportDefinition.findMany({
+      where: { orgId, ...(options.status ? { status: options.status } : {}) },
+      orderBy: [{ key: 'asc' }, { version: 'desc' }],
+      take: options.limit,
+      ...(options.cursor
+        ? {
+            cursor: { id: options.cursor },
+            skip: 1,
+          }
+        : {}),
+    });
+
+    return rows.map((row) => this.toRecord(row));
+  }
+
+  async maxVersion(orgId: string, key: string, tx?: EngineTx): Promise<number> {
+    const result = await this.client(tx).reportDefinition.aggregate({
+      _max: { version: true },
+      where: { orgId, key },
+    });
+
+    return result._max.version ?? 0;
+  }
+
+  private toRecord(row: ReportDefinitionRow): ReportDefinitionRecord {
+    return {
+      id: row.id,
+      orgId: row.orgId,
+      key: row.key,
+      version: row.version,
+      status: row.status as ReportDefinitionStatus,
+      schema: row.schema as unknown as ReportDefinition,
+      compiled: row.compiled === null ? null : (row.compiled as unknown as CompiledDefinitionMeta),
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+    };
+  }
+}

package/template/src/modules/reports/infrastructure/stores/prisma-row-tag.store.ts

@@ -0,0 +1,110 @@
+import { Injectable } from '@nestjs/common';
+import { Prisma } from '@prisma/client';
+import type { EngineTx, RowTagStore } from '@ftisindia/report-builder';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+
+/**
+ * Org-scoped row tags & labels (report design §7): one table, one mechanism.
+ * The (orgId, sourceKind, sourceKey, rowId, tag) unique + createMany
+ * skipDuplicates make addTags idempotent per link; the engine normalizes tag
+ * text before it reaches this store.
+ */
+@Injectable()
+export class PrismaRowTagStore implements RowTagStore {
+  constructor(private readonly prisma: PrismaService) {}
+
+  private client(tx?: EngineTx) {
+    return tx ? (tx as unknown as Prisma.TransactionClient) : this.prisma;
+  }
+
+  async addTags(
+    orgId: string,
+    sourceKind: string,
+    sourceKey: string,
+    rowIds: readonly string[],
+    tags: readonly string[],
+    createdBy: string,
+    tx?: EngineTx,
+  ): Promise<number> {
+    if (rowIds.length === 0 || tags.length === 0) {
+      return 0;
+    }
+
+    const result = await this.client(tx).reportRowTag.createMany({
+      data: rowIds.flatMap((rowId) =>
+        tags.map((tag) => ({ orgId, sourceKind, sourceKey, rowId, tag, createdBy })),
+      ),
+      // Existing (org, source, row, tag) links are silently kept — the count
+      // returned is the number of NEW links, per the port contract.
+      skipDuplicates: true,
+    });
+
+    return result.count;
+  }
+
+  async removeTags(
+    orgId: string,
+    sourceKind: string,
+    sourceKey: string,
+    rowIds: readonly string[],
+    tags: readonly string[],
+    tx?: EngineTx,
+  ): Promise<number> {
+    if (rowIds.length === 0 || tags.length === 0) {
+      return 0;
+    }
+
+    const result = await this.client(tx).reportRowTag.deleteMany({
+      where: {
+        orgId,
+        sourceKind,
+        sourceKey,
+        rowId: { in: [...rowIds] },
+        tag: { in: [...tags] },
+      },
+    });
+
+    return result.count;
+  }
+
+  async tagsForRows(
+    orgId: string,
+    sourceKind: string,
+    sourceKey: string,
+    rowIds: readonly string[],
+  ): Promise<Map<string, string[]>> {
+    if (rowIds.length === 0) {
+      return new Map();
+    }
+
+    // One indexed lookup per page — (orgId, sourceKind, sourceKey, rowId).
+    const rows = await this.client().reportRowTag.findMany({
+      where: { orgId, sourceKind, sourceKey, rowId: { in: [...rowIds] } },
+      select: { rowId: true, tag: true },
+      orderBy: { tag: 'asc' },
+    });
+
+    const tagsByRow = new Map<string, string[]>();
+    for (const row of rows) {
+      const tags = tagsByRow.get(row.rowId);
+      if (tags) {
+        tags.push(row.tag);
+      } else {
+        tagsByRow.set(row.rowId, [row.tag]);
+      }
+    }
+
+    return tagsByRow;
+  }
+
+  async listTags(orgId: string, sourceKind: string, sourceKey: string): Promise<string[]> {
+    const rows = await this.client().reportRowTag.findMany({
+      where: { orgId, sourceKind, sourceKey },
+      select: { tag: true },
+      distinct: ['tag'],
+      orderBy: { tag: 'asc' },
+    });
+
+    return rows.map((row) => row.tag);
+  }
+}

package/template/src/modules/reports/infrastructure/stores/prisma-saved-view.store.ts

@@ -0,0 +1,144 @@
+import { Injectable } from '@nestjs/common';
+import { Prisma, ReportSavedView as ReportSavedViewRow } from '@prisma/client';
+import {
+  ReportConflictError,
+  ReportNotFoundError,
+  type EngineTx,
+  type NewSavedViewRecord,
+  type QuerySpec,
+  type SavedViewRecord,
+  type SavedViewStore,
+} from '@ftisindia/report-builder';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+
+@Injectable()
+export class PrismaSavedViewStore implements SavedViewStore {
+  constructor(private readonly prisma: PrismaService) {}
+
+  private client(tx?: EngineTx) {
+    return tx ? (tx as unknown as Prisma.TransactionClient) : this.prisma;
+  }
+
+  async create(record: NewSavedViewRecord, tx?: EngineTx): Promise<SavedViewRecord> {
+    try {
+      const row = await this.client(tx).reportSavedView.create({
+        data: {
+          orgId: record.orgId,
+          reportKey: record.reportKey,
+          reportVersion: record.reportVersion,
+          name: record.name,
+          spec: record.spec as unknown as Prisma.InputJsonValue,
+          ownerId: record.ownerId,
+        },
+      });
+
+      return this.toRecord(row);
+    } catch (error) {
+      if (this.isDuplicateViewName(error)) {
+        throw new ReportConflictError(
+          `A view named "${record.name}" already exists for this report.`,
+        );
+      }
+      throw error;
+    }
+  }
+
+  async update(
+    orgId: string,
+    id: string,
+    patch: { name?: string; spec?: QuerySpec; reportVersion?: number },
+    tx?: EngineTx,
+  ): Promise<SavedViewRecord> {
+    const client = this.client(tx);
+
+    const existing = await client.reportSavedView.findFirst({
+      where: { id, orgId },
+      select: { id: true },
+    });
+
+    if (!existing) {
+      throw new ReportNotFoundError(`Saved view ${id} was not found in this organisation.`);
+    }
+
+    try {
+      const row = await client.reportSavedView.update({
+        where: { id: existing.id },
+        data: {
+          ...(patch.name !== undefined ? { name: patch.name } : {}),
+          ...(patch.spec !== undefined
+            ? { spec: patch.spec as unknown as Prisma.InputJsonValue }
+            : {}),
+          ...(patch.reportVersion !== undefined ? { reportVersion: patch.reportVersion } : {}),
+        },
+      });
+
+      return this.toRecord(row);
+    } catch (error) {
+      if (this.isDuplicateViewName(error)) {
+        throw new ReportConflictError(
+          patch.name === undefined
+            ? 'A view with this name already exists for this report.'
+            : `A view named "${patch.name}" already exists for this report.`,
+        );
+      }
+      throw error;
+    }
+  }
+
+  async delete(orgId: string, id: string, tx?: EngineTx): Promise<void> {
+    await this.client(tx).reportSavedView.deleteMany({
+      where: { id, orgId },
+    });
+  }
+
+  async findById(orgId: string, id: string): Promise<SavedViewRecord | null> {
+    const row = await this.client().reportSavedView.findFirst({
+      where: { id, orgId },
+    });
+
+    return row ? this.toRecord(row) : null;
+  }
+
+  async listByReport(
+    orgId: string,
+    reportKey: string,
+    userId: string,
+  ): Promise<SavedViewRecord[]> {
+    const rows = await this.client().reportSavedView.findMany({
+      // The caller's PERSONAL views plus SHARED views (ownerId null) — never
+      // another user's personal views (report design §4/§12).
+      where: { orgId, reportKey, OR: [{ ownerId: userId }, { ownerId: null }] },
+      orderBy: [{ name: 'asc' }, { createdAt: 'asc' }],
+    });
+
+    return rows.map((row) => this.toRecord(row));
+  }
+
+  /**
+   * View-name uniqueness lives in PARTIAL UNIQUE INDEXES shipped as raw SQL
+   * (report design §12, finding #5 — Postgres treats NULL ownerIds as
+   * distinct, so a Prisma @@unique cannot express it). Prisma maps the
+   * underlying 23505 to P2002 when it can; a raw partial-unique violation may
+   * also surface as an unknown request error, so match the index-name prefix
+   * ("report_view_shared_uq" / "report_view_personal_uq") as the fallback.
+   */
+  private isDuplicateViewName(error: unknown): boolean {
+    if (error instanceof Prisma.PrismaClientKnownRequestError && error.code === 'P2002') {
+      return true;
+    }
+    return error instanceof Error && error.message.includes('report_view_');
+  }
+
+  private toRecord(row: ReportSavedViewRow): SavedViewRecord {
+    return {
+      id: row.id,
+      orgId: row.orgId,
+      reportKey: row.reportKey,
+      reportVersion: row.reportVersion,
+      name: row.name,
+      spec: row.spec as unknown as QuerySpec,
+      ownerId: row.ownerId,
+      createdAt: row.createdAt,
+    };
+  }
+}

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

@@ -0,0 +1,83 @@
+import { Body, Controller, HttpCode, Param, Post, UseGuards } from '@nestjs/common';
+import {
+  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 { ReportsActionsService } from '../application/services/reports-actions.service';
+import { ActionResultResponseDto } from '../dto/action-result-response.dto';
+import { ExecuteActionDto } from '../dto/execute-action.dto';
+import { PrepareActionDto } from '../dto/prepare-action.dto';
+import { PrepareActionResponseDto } from '../dto/prepare-action-response.dto';
+
+/**
+ * Row actions (design §6) — verbs that DELEGATE, never a second write path.
+ * The route-level key is reports.read (the grid entry point); each action's
+ * own permission keys (action.requiredPermissions, e.g.
+ * 'formSubmissions.update') are enforced INSIDE the engine at execute-time —
+ * the second of §6.1's two layers (attach-time ran at definition save).
+ */
+@ApiTags('Reports')
+@ApiBearerAuth()
+@ApiParam({ name: 'orgId', description: 'Organisation ID.', format: 'uuid' })
+@ApiParam({ name: 'key', description: 'Report definition key.' })
+@ApiParam({ name: 'name', description: 'Registered row-action name.' })
+@ApiProtectedErrorResponses(404, 409, 410)
+@ApiUnprocessableEntityResponse({
+  description: 'The action input failed validation.',
+  type: ErrorResponseDto,
+})
+@Controller('organisations/:orgId/reports')
+@UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+export class ReportsActionsController {
+  constructor(private readonly reportsActionsService: ReportsActionsService) {}
+
+  @Post(':key/actions/:name/prepare')
+  @HttpCode(200)
+  @RequirePermissions('reports.read')
+  @ApiOperation({
+    summary:
+      'Prepare a byFilter bulk action: resolve the selection NOW and sign what was seen (§6.3 step 1).',
+  })
+  @ApiOkResponse({
+    description: 'Expected count plus the signed, short-TTL action token.',
+    type: PrepareActionResponseDto,
+  })
+  prepare(
+    @Param('orgId') orgId: string,
+    @Param('key') key: string,
+    @Param('name') name: string,
+    @Body() dto: PrepareActionDto,
+  ) {
+    return this.reportsActionsService.prepare(orgId, key, name, dto);
+  }
+
+  @Post(':key/actions/:name')
+  @HttpCode(200)
+  @RequirePermissions('reports.read')
+  @ApiOperation({
+    summary:
+      'Execute a row/bulk action: byIds directly, byFilter via the prepared token with drift detection and the idempotency ledger (§6.3).',
+  })
+  @ApiOkResponse({
+    description: 'Execution outcome.',
+    type: ActionResultResponseDto,
+  })
+  execute(
+    @Param('orgId') orgId: string,
+    @Param('key') key: string,
+    @Param('name') name: string,
+    @Body() dto: ExecuteActionDto,
+  ) {
+    return this.reportsActionsService.execute(orgId, key, name, dto);
+  }
+}