MBTCMS — Municipal Board Tax Collection & Management System

// payments.service.ts - Auto-allocation logic
async create(createPaymentDto: CreatePaymentDto) {
  const payment = await tx.payment.create({
    data: {
      amount: createPaymentDto.amount,
      arrearAmount: createPaymentDto.arrearAmount || 0,
      currentAmount: createPaymentDto.currentAmount || 0,
      // ...
    },
  });

  // Update Allotment balances: arrear first, then current
  if (createPaymentDto.allotmentId) {
    const allotment = await tx.allotment.findUnique({
      where: { id: createPaymentDto.allotmentId },
    });

    let remainingAmount = Number(createPaymentDto.amount);

    // Apply to Arrears first
    if (remainingAmount > 0 && Number(allotment.arrearDemand) > 0) {
      const arrearPayment = Math.min(remainingAmount, Number(allotment.arrearDemand));
      await tx.allotment.update({
        where: { id: createPaymentDto.allotmentId },
        data: { arrearDemand: { decrement: arrearPayment } },
      });
      remainingAmount -= arrearPayment;
    }

    // Apply remaining to Current
    if (remainingAmount > 0) {
      await tx.allotment.update({
        where: { id: createPaymentDto.allotmentId },
        data: { currentDemand: { decrement: remainingAmount } },
      });
    }
  }
}

// period-close.service.ts
async validateTransactionAllowed(financialYear: string) {
  const fy = await this.prisma.financialYear.findFirst({
    where: { year: financialYear },
  });

  if (!fy) {
    throw new BadRequestException('No active financial year found. Please configure a financial year first.');
  }

  if (fy.status === 'CLOSED') {
    throw new BadRequestException('Financial year is closed. New transactions are not allowed.');
  }
}

async closeFinancialYear(year: string) {
  return this.prisma.$transaction(async (tx) => {
    // 1. Calculate new arrear: Old Arrear + Old Current
    const allotments = await tx.allotment.findMany({
      where: { status: 'ACTIVE' },
    });

    for (const allotment of allotments) {
      const newArrear = Number(allotment.arrearDemand) + Number(allotment.currentDemand);
      await tx.allotment.update({
        where: { id: allotment.id },
        data: {
          arrearDemand: newArrear,
          currentDemand: 0,
        },
      });
    }

    // 2. Mark FY as closed
    await tx.financialYear.update({
      where: { year },
      data: { status: 'CLOSED', closedAt: new Date() },
    });
  });
}

// common/interceptors/audit.interceptor.ts
@Injectable()
export class AuditInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();
    const user = request.user;

    return next.handle().pipe(
      tap(async (data) => {
        if (this.isMutatingRequest(request.method)) {
          await this.prisma.auditLog.create({
            data: {
              userId: user?.id,
              userName: user?.name,
              action: `${request.method} ${request.route.path}`,
              entity: this.extractEntityName(request.route.path),
              entityId: data?.id,
              oldValue: request.method !== 'POST' ? await this.getOldValue(request) : null,
              newValue: data,
              remark: request.body.remark,
              ipAddress: request.ip,
              userAgent: request.headers['user-agent'],
            },
          });
        }
      }),
    );
  }
}

// payments.controller.ts
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('ADMIN', 'SUPERUSER', 'TAX_COLLECTOR')
@Post()
async create(@Body() createPaymentDto: CreatePaymentDto, @Request() req) {
  // Collector ID is automatically extracted from JWT
  createPaymentDto.collectorId = req.user.taxCollector?.id;
  return this.paymentsService.create(createPaymentDto);
}

// allotments.service.ts
async create(createAllotmentDto: CreateAllotmentDto) {
  // Check room availability
  const room = await this.prisma.room.findUnique({
    where: { id: createAllotmentDto.roomId },
  });

  if (room.status !== 'VACANT') {
    throw new BadRequestException('Room is not available for allotment. Select a VACANT room.');
  }

  // Create allotment and update room status
  const allotment = await this.prisma.allotment.create({
    data: { ...createAllotmentDto },
  });

  await this.prisma.room.update({
    where: { id: createAllotmentDto.roomId },
    data: { status: 'OCCUPIED' },
  });

  return allotment;
}

// demands.service.ts - Single demand generation
async generateSingle(dto: GenerateSingleDemandDto) {
  const allotment = await this.prisma.allotment.findUnique({
    where: { id: dto.allotmentId },
  });

  // baseTax = Current month's rent from Allotment
  // arrears = Allotment's arrearDemand (previous FY balance)
  const baseTax = Number(allotment.rentAmount);
  const arrears = Number(allotment.arrearDemand);
  const billId = await this.codeGenerator.generateBillId();

  const demand = await tx.demand.create({
    data: {
      allotmentId: dto.allotmentId,
      financialYear: dto.financialYear,
      month: dto.month,
      baseTax,
      arrears,
      totalDemand: baseTax, // Only monthly rent is billed
      billId,
    },
  });

  // Update Allotment current demand
  await tx.allotment.update({
    where: { id: dto.allotmentId },
    data: { currentDemand: { increment: baseTax } },
  });

  return demand;
}

// payments.service.ts
private async generateReceiptNo(): Promise<string> {
  const today = new Date();
  const datePrefix = `MBTCMS-${today.getFullYear()}-${String(today.getMonth() + 1).padStart(2, '0')}-${String(today.getDate()).padStart(2, '0')}`;

  const lastPayment = await this.prisma.payment.findFirst({
    where: { receiptNo: { startsWith: datePrefix } },
    orderBy: { receiptNo: 'desc' },
  });

  let nextSeq = 1;
  if (lastPayment) {
    const lastSeq = parseInt(lastPayment.receiptNo.split('-')[4], 10);
    nextSeq = lastSeq + 1;
  }

  return `${datePrefix}-${String(nextSeq).padStart(4, '0')}`;
}

// common/guards/roles.guard.ts
@Injectable()
export class RolesGuard extends AuthGuard('jwt') {
  canActivate(context: ExecutionContext) {
    return super.canActivate(context);
  }

  handleRequest(err, user, info) {
    if (err || !user) {
      throw err || new UnauthorizedException();
    }
    return user;
  }
}

// Usage in controllers
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('ADMIN')
@Delete(':id')
async delete(id: string) { ... }

# Clone and configure
git clone <repository-url>
cd mbtcms

# Configure environment
cp .env.example .env
# Edit .env with POSTGRES_PASSWORD and JWT_SECRET

# Start with Docker Compose
cd deployment
docker-compose up -d

# Deploy script
bash deploy.sh

npm run build --workspace=backend
npm run build --workspace=frontend
pm2 start ecosystem.config.js