DEV Community: José Sobral

Component Unit Test fundamentals

José Sobral — Mon, 02 Oct 2023 22:20:27 +0000

I have to be honest with you: on my previous experiences working with React, I've procrastinated a lot on deep dive at component unit testing. Unlike other concepts (like states, props, life cycles), test is a knowledge which you wont learn only by doing over and over again: know the fundamentals of testing is essential to know what to test.

Recently, I've started to work on an application using Vue.js and despite of my lack of knowledge on component testing, I knew something was wrong on its tests. I know that because software testing is something that i’m studying a lot in the previous months and I knew the difference of concepts like behaviour vs implementation tests to evaluate the quality of current tests.

PS: If you want to know more about the overall concepts of tests, check out my recent article about Glenford Myers books, The Art of Software Testing.

Right now, working on an application with a need to component test improving, I had to study some of the fundamentals of component unit testing to start a new history on this company. This article is intend to provide an overview and give some references of how you can go further on your own journey on component unit testing. The main references of this articles are:

Vue Mastery: Real World Testing, with Jessica Sachs
Testing Vue.js Applications, from Edd Yerburgh
Vue Testing Handbook, from Lachlan Miller
Kent C. Dodds’s Blog

Purpose of Test

When it comes to test, starts on its philosophies is a perfect start. Just to give an example of the power of tests philosophy, one that really changed my mind, on Glenford books, was a shift from thinking in test as a process to show that a program works correctly to a greater definition:

Testing is the process of executing a program with the intent of finding errors.

Saying that, on components world, our main philosophy on test is to ensure that the component holds its contracts for the end user. From the Testing Vue.js Applications’ book:

Deciding what unit tests to write is important. If you wrote tests for every property of a component, you would slow development and create an inefficient test suite. One method for deciding what parts of a component should be tested is to use the concept of a component contract. A component contract is the agreement between a component and the rest of the application.
...
The idea of input and output is important in component contracts. A good component unit test should always trigger an input and assert that the component generates the correct output. You should write tests from the perspective of a developer who’s using the component but is unaware of how the component functionality is implemented.

What is NOT the purpose of test

The fallacy of 100% code coverage: Sometimes the test coverage is the only metric that we have to ensure if our test suite are in state of excellence. But we have to be careful because this metric can be misleading. Things like the component contract mentioned above and a user perspective (what are the most crucial parts of your app) are far more effective than be based only on test coverage. Another idea, explained in this article of Kent C. Odds, is that for test coverage an “About” page and a “Checkout” one would be the same thing, but for our end users one is far more important than the other one. This is explained as well by Edd, on Part 1.2.7 of his book:

Not only is it time-consuming to reach the fabled 100% code coverage, but even with 100% code coverage, tests do not always catch bugs. Sometimes you make the wrong assumptions. Maybe you’re testing code that calls an API, and you assume that the API never returns an error; when the API does return an error in production, your app will implode.
You don’t become a test master by striving for 100% code coverage on every app. Like a good MMA fighter who knows when to walk away from a fight, a true testing master knows when to write tests and when not to write tests.

Implementation details: Things like our implementation process (variable names, hard coded label names, etc) are just implementation details, it does not necessary aims to ensure the component contract. Take a look of a test that I've found on my recent Vue.js experience

describe("CarForm", () => {
  it("contains correct form labels", async () => {
    const { queryByText } = renderComponent();

    expect(queryByText("Brand")).toBeTruthy();
    expect(queryByText("Price")).toBeTruthy();
    expect(queryByText("Year")).toBeTruthy();

    expect(queryByText("Submit")).toBeTruthy();
    expect(queryByText("Cancel")).toBeTruthy();
  });
}

This test aims to test form labels; its all implementation details, these names can change easily. When comes to form, things like state changes on submit, submit function being called correctly and submit experience (successful, error) are contracts from forms that are far more important, like this example from Vue Testing Handbook

the framework itself or third party libraries: We do not have to test methods and function from the framework itself neither from third party libraries. You have to trust that the core team from these tools have already done this job.

How to test

The more your tests resemble the way of your software is used, the more confidence they can give you — Kent C. Dodds

On writing component tests, you have to think gradually to test. Use the follow mentality:

1) Create a test suite (describe (…) ) and setup your tests (test(…))

This part is the easiest one: create a describe and a test to ensure your test setup is working correctly. This could be unnecessary but if you do not do that and, for any reason, and there is a problem in the setup, it will make the debug process harder.

2) Mount the component

According to Jessica Sachs, this is the hardest part on writing component unit tests. In this step, your only concern is to make sure your component will be mounted without any error. The difficult can vary from a lot of things, like:

Plug dependencies correctly (like redux, pinia, router, etc) on component;
Set props correctly;
Build mocks correctly;

To go further on this step, read this section called Mounting Options from Vue Test Utils. I’ve tried to find the equivalence for React, but I did not. But this article, talking about Enzyme gave me a good reference.

3) Leave your IDE and think about component contracts

As mentioned above, test is not a part of the software that you simple learn by doing, you have to think about what is going to be tested. At this point of this article, I hope you already built a mentality that your unit tests should:

guarantee that your component contract is going to be satisfied, independent of its implementations
End-user mindset to know the most fundamental contracts️.

Saying that, in this part you will think and write your component contracts — which will be each test case. This will make the processes to build tests easier. An example of this could be checked on Lesson 3, from Vue Mastery Unit Test Course. This lesson is only available for premium accounts but the repo from this lesson is available for free here.

For a RandomNumber component:

<template>
  <div>
    <span>{{ randomNumber }}</span>
    <button @click="getRandomNumber">Generate Random Number</button>
  </div>
</template>
<script>
export default {
  props: {
    min: {
      type: Number,
      default: 1
    },
    max: {
      type: Number,
      default: 10
    }
  },
  data() {
    return {
      randomNumber: 0
    }
  },
  methods: {
    getRandomNumber() {
      this.randomNumber =
        Math.floor(Math.random() * (this.max - this.min + 1)) + this.min
    }
  }
}
</script>

The author draw three contracts:

import RandomNumber from '@/components/RandomNumber'
import { mount } from '@vue/test-utils'

describe('RandomNumber', () => {
  test('By default, randomNumber data value should be 0', () => {
  })
  test('If button is clicked, randomNumber should be between 1 and 10', () => {
  })
  test('If button is clicked (with right props), randomNumber should be between 200 and 300', () => {
  })
})

4) Write your tests

When all the previous parts of this guide are done, write tests should be easy. Here are some final tips and a work material to go further:

Use data-testid to grab selectors: This selectors is a good option because, as a tester, you know for sure that this won’t change; different from classes, ids, names and etc. Read this article to know more.
Think of all the relevant inputs from a end user: This means that you want to check component props, actions (click, mouse over, etc), changing on states and etc. Read this section from Vue Testing Handbook to know more.
Test cases when user do the wrong stuff: You should write tests for situations where your uses calls a form with wrong data, badly formatted data or any other user errors (this is called fault injection). Remember: Testing is the process of executing a program with the intent of finding errors, do not think your user is always do the right thing. Read this article to know more.

Specialists section

From Vue.js repository

This test ensures the agreement that the computed property will fires reactivity and update the value

packages > reactivity > __tests__ > computed.spec.ts

describe('reactivity/computed', () => {
  it('should return updated value', () => {
    const value = reactive<{ foo?: number }>({})
    const cValue = computed(() => value.foo)
    expect(cValue.value).toBe(undefined)
    value.foo = 1
    expect(cValue.value).toBe(1)
  })

From React.js repository

This test even add comments about the agreements from react states

packages > react-refresh > src > __tests__ > ReactFresh-test.js

  it('can preserve state for compatible types', () => {
    if (__DEV__) {
      const HelloV1 = render(() => {
        function Hello() {
          const [val, setVal] = React.useState(0);
          return (
            <p style={{color: 'blue'}} onClick={() => setVal(val + 1)}>
              {val}
            </p>
          );
        }
        $RefreshReg$(Hello, 'Hello');
        return Hello;
      });

      // Bump the state before patching.
      const el = container.firstChild;
      expect(el.textContent).toBe('0');
      expect(el.style.color).toBe('blue');
      act(() => {
        el.dispatchEvent(new MouseEvent('click', {bubbles: true}));
      });
      expect(el.textContent).toBe('1');

      // Perform a hot update.
      const HelloV2 = patch(() => {
        function Hello() {
          const [val, setVal] = React.useState(0);
          return (
            <p style={{color: 'red'}} onClick={() => setVal(val + 1)}>
              {val}
            </p>
          );
        }
        $RefreshReg$(Hello, 'Hello');
        return Hello;
      });

The Art of Software Testing, from Glenford Myers

José Sobral — Fri, 01 Sep 2023 12:21:01 +0000

The rise of AIs has revolutionized numerous industries, among them, our software industry couldn't be an exception: a survey from Github shows that over 90% of developers have already used some type of AI and 40% of them use AIs on a daily routine.

However, despite seeming and indeed being a significant transformation, we need to be aware of some current model limitations, like the lack of understanding of question full context, the biases on responses and the model knowledge limitations.

When it comes to software testing, these limitations of current models turns out to be even more significant:

Lack of Context: When designing tests, it is crucial to have a deep understanding of the application's purpose, its target audience, the most common usage scenarios, and the potential risk areas. For example, a banking app and a casual game will have vastly different risk profiles and user behaviors. A human tester brings to the table a wealth of contextual knowledge, such as which inputs might be more commonly used, which flow controls are more at risk, or which areas of an app are more crucial to its function.
Biases on Responses: The AI model is only as good as the data it was trained on. If the model was trained using data from sources that consistently follow poor practices or outdated methodologies, the AI would reflect those biases. For instance, if all sources suggest an outdated testing approach, the model might recommend it even if it's not the best choice for a given scenario.
Knowledge Limitation: AI models, like ChatGPT, have a "knowledge cutoff", meaning they are not aware of developments, techniques, tools, or best practices introduced after this date. Software testing is a field that evolves rapidly, with new methodologies, tools, and best practices emerging frequently. Human testers can continuously learn and adapt, absorbing the latest knowledge from conferences, workshops, forums, and community interactions. Right now, the model can not.

Let's look at a typical example of a suggestion for unit tests from ChatGPT for a controller name Stores::CollectionsController , which is responsible to fetch collections and associated products based on store entity:

RSpec.describe Stores::CollectionsController, type: :controller do
  let(:store) { create(:store) }
  let(:collection) { create(:collection, store: store) }
  let(:product) { create(:product, collection: collection) }

  describe "GET #show" do
    context "when collection exists" do
      before { get :show, params: { store_id: store.id, collection_id: collection.id } }

      it "assigns the collection" do
        expect(assigns(:collection)).to eq(collection)
      end

      it "assigns the products" do
        expect(assigns(:products)).to include(product)
      end

      it "renders the show template" do
        expect(response).to render_template(:show)
      end
    end

    context "when collection does not exist" do
      before { get :show, params: { store_id: store.id, collection_id: -1 } }

      it "redirects to store path" do
        expect(response).to redirect_to(store_path(store.slug))
      end
    end
  end
end

There are several mistakes in this code provided by AI, lets take a look on two of them:

render_template is deprecated: render_template has been deprecated in more recent versions of RSpec, since 2015.
assigns is an implementation test: assigns was traditionally used to access the instance variables set in the controller. The problem with this is that you're testing the internal implementation of the controller rather than its external output or behavior. Unit tests should focus on the expected behavior and not on how this behavior is internally achieved.

Given this kind of limitations on tests generated by AI's, it's necessary to understand the fundamentals beyond the test writing.

This article aims to provide a summary of concepts presented in the book "The Art of Software Testing" by Glenford Myers, in an attempt to shed light on and introduce the science of testing.

The Psychology of Testing

In the software world, it's common for us to learn by solving problems. This approach is usually very effective, and there's a plethora of articles that correlate problem-solving with software.

However, a thesis raised by the author in Chapter 2 - "The Psychology and Economics of Software Testing" - is that there's a philosophy behind the thinking of constructing tests. Often, this philosophy gets misconstrued, and problem-solving is grounded on incorrect premises. The author states:

The purpose of testing is to show that a program performs its intended functions correctly.

Testing is the process of establishing confidence that a program does what it's supposed to do.

This portrays a testing psychology focused on ensuring that your system works correctly.

However, according to the author, the real psychology behind testing isn't to ensure your system works correctly, but rather to break it. In the author's words:

Testing is the process of executing a program with the intent of finding errors.

This entirely shifts our problem-solving perspective; when our goal is to demonstrate that a program is error-free, we subconsciously select data that has a low likelihood of causing the program to fail.

Another way to spot this testing psychology is the use of the terms "successful" and "unsuccessful", especially when used by product managers. In most projects, PMs categorize a "successful" test when the test finds no errors. We need to start with the assumption that all programs contain errors and the purpose of testing is to locate them.

In summary, it's as if the process of software testing is seen as a process of trying to constantly break your code. In the next section, we'll explore methods to help structure our thinking when attempting to "break our code", that is, to test it.

Black Box Testing

The author introduces two techniques to assist developers in the testing process and on "break things". In the first one, black box testing, we operate under the assumption that our code is a "black box" and we don't test control flows and business rules; we only test how our "black box" handles inputs and what its outputs are.

also known as data driven or input/output-driven testing

Thus, the goal of black box testing is to attempt to break our objects and methods based on different inputs. Some strategies to apply black box testing include:

Equivalence partitioning

This technique divides the software's input space into partitions of equivalent values. The idea here is that if one input in a given partition is valid, then all inputs from that partition are. So, instead of testing each input individually, testers can simply test one representative input from each partition.

in practice

Suppose you have a registration form in your application that accepts an age range of users between 18 and 65 years. The equivalent partitions here would be:

Under 18 years old
Between 18 and 65 years old
Over 65 years old

To test, you can choose a representative age from each partition (for instance, 15, 30, and 70) and check if the system correctly processes each entry.

from django.test import TestCase
from .models import User

class EquivalencePartitioningTest(TestCase):
    def test_underage(self):
        response = self.client.post('/signup/', {'age': 15})
        self.assertContains(response, 'Age is too low')

    def test_valid_age(self):
        response = self.client.post('/signup/', {'age': 30})
        self.assertContains(response, 'Congratulations!')

    def test_over_age(self):
        response = self.client.post('/signup/', {'age': 70})
        self.assertContains(response, 'Age is too high.')

Boundary value analysis

In this technique, the focus is on the boundary values or edge points of the input ranges. Errors commonly occur at these extremities, which is why it's crucial to test values just above, below, and right at the acceptance limits.

in practice

Using the same registration form example mentioned above, the boundary values would be 17, 18, 65, and 66. The goal would be to test these specific values because it's at these boundaries or extremities that errors are most likely to occur. For instance, a user who is 18 years old should be accepted, while a 17-year-old user should not be.

class BoundaryValueAnalysisTest(TestCase):
    def test_age_just_below_boundary(self):
        response = self.client.post('/signup/', {'age': 17})
        self.assertContains(response, 'Age is too low.')

    def test_age_at_lower_boundary(self):
        response = self.client.post('/signup/', {'age': 18})
        self.assertContains(response, 'Congratulations')

    def test_age_at_upper_boundary(self):
        response = self.client.post('/signup/', {'age': 65})
        self.assertContains(response, 'Congratulations!')

    def test_age_just_above_boundary(self):
        response = self.client.post('/signup/', {'age': 66})
        self.assertContains(response, 'Age is too high.')

Cause-effect graphing

This technique involves creating a chart that maps out the relationships between different causes (inputs) and their effects (outcomes). The graph is used to identify and devise test cases that cover all possible combinations of inputs and their resulting effects.

in practice

Let's say you have a form that accepts entries for an event. Causes could include: type of ticket selected, seat availability, event date. The effects could be: purchase confirmation, unavailable seat error, invalid date error, etc. You would create a chart to map all these inputs and their possible outcomes, ensuring that all scenarios are tested. In summary:

Let's consider a simple event booking system.

Causes (Inputs):

Ticket type: Regular, VIP, Student Discount
Seat availability: Available, Unavailable
Event date: Valid Date, Past Date

Effects (Outcomes):

Purchase Confirmation
Unavailable Seat Error
Invalid Date Error
Discount Verification (for student discount)

The graph can be described as:

If Regular or VIP ticket is selected with Available seat and Valid Date, then the outcome is Purchase Confirmation.
If Student Discount ticket is selected with Available seat and Valid Date, then the outcomes are both Purchase Confirmation and Discount Verification.
If any ticket type is chosen with Unavailable seat, regardless of the event date, then the outcome is Unavailable Seat Error.
If any ticket type is selected with either Available or Unavailable seat but with Past Date, then the outcome is Invalid Date Error.

With this cause-effect perception, you can build several tests to try to "break your code".

Error guessing

As the name suggests, this technique is less systematic and more based on the tester's intuition and experience. Testers try to "guess" where errors might be present and craft test cases based on those assumptions. For instance, if a tester knows that a particular kind of input caused issues in previous software, they might decide to test that specific input again.

in practice

class ErrorGuessingTest(TestCase):
    def test_special_characters_in_name(self):
        response = self.client.post('/signup/', {'name': '@John!'})
        self.assertContains(response, 'Invalid chars')

White box Testing

also known as logic-driven

The other technique, white box testing, aims to test the flow control of our code. This approach is commonly used to know the test coverage of our application. However, as the author himself illustrates, in many cases, it's impossible to test all the flows of a particular system. Consider the example below.

In this image, there are 10¹³ possible flows between a and b. It would be impractical to create this number of test cases for our system.

That's one of the reasons why the models limitation mentioned above of the Lack of Context is crucial: only humans can have knowledge of full context of an application and decide which flow control is more critical to test.

In this regard, some techniques are employed in the use of white box testing to guide our process to "break our code" (test):

Statement Coverage

Aims to ensure that each statement or line of code is executed at least once; essential for detecting parts of the code that are not executed under any test scenario - this is what coverage files typically show.

in practice

Let's suppose we have the following authentication function.

def authenticate(username, password):
    user = CustomUser.objects.filter(username=username)

    if not user:
        return 'User not found'

    if not user.is_active:
        return 'User is not active'

    if user.failed_attempts >= 3:
        return 'Account locked due to too many failed attempts'

    if user.password != password:
        user.failed_attempts += 1
        user.save()
        return 'Invalid password'

    user.failed_attempts = 0
    user.save()
    return 'Authentication successful'

This technique ensures that each statement in the code is executed at least once during testing. In the authenticate function, we use statement coverage to ensure that each of the if statements is executed at least once during testing.

def test_authenticate_statement_coverage(self):
    # Test case where user is not found
    result = authenticate('nonexistent_user', 'password')
    self.assertEqual(result, 'User not found')

    # Test case where user is not active
    inactive_user = CustomUser.objects.create(username='inactive_user', is_active=False, password='password')
    result = authenticate('inactive_user', 'password')
    self.assertEqual(result, 'User is not active')

    # Test case where account is locked due to too many failed attempts
    locked_user = CustomUser.objects.create(username='locked_user', failed_attempts=3, password='password')
    result = authenticate('locked_user', 'password')
    self.assertEqual(result, 'Account locked due to too many failed attempts')

    # Test case where password is invalid
    user = CustomUser.objects.create(username='user', password='password')
    result = authenticate('user', 'wrong_password')
    self.assertEqual(result, 'Invalid password')

    # Test case where authentication is successful
    result = authenticate('user', 'password')
    self.assertEqual(result, 'Authentication successful')

Decision Coverage

Ensures that each decision or branch (like an if-else statement) is tested for both options: True or False.

in practice

This technique ensures that each decision point in the code is executed both when the condition is True and when it is False. In the authenticate function, we use decision coverage to ensure that the if user.password != password decision point is executed both when the password is correct and when it is incorrect.

def test_authenticate_decision_coverage(self):
    # Test case where password is invalid
    user = CustomUser.objects.create(username='user', password='password')
    result = authenticate('user', 'wrong_password')
    self.assertEqual(result, 'Invalid password')
    self.assertEqual(user.failed_attempts, 1)

    # Test case when password is valid
    result = authenticate('user', 'password')
    self.assertEqual(result, 'Authentication successful')

Multiple-Condition Coverage

Similar to condition coverage, but goes further. It ensures that all possible combinations of conditions in a decision are tested.

in practice

This technique ensures that each possible combination of conditions in a decision point is executed at least once. In the authentication function, we use multiple-condition coverage to ensure that each possible combination of conditions in the decision point is executed at least once during testing.

def test_authenticate_multiple_condition_coverage(self):
    # Test case where user is not found
    result = authenticate('nonexistent_user', 'password')
    self.assertEqual(result, 'User not found')

    # Test case where user is not active
    inactive_user = CustomUser.objects.create(username='inactive_user', is_active=False, password='password')
    result = authenticate('inactive_user', 'password')
    self.assertEqual(result, 'User is not active')

    # Test case where account is locked due to too many failed attempts
    locked_user = CustomUser.objects.create(username='locked_user', failed_attempts=3, password='password')
    result = authenticate('locked_user', 'password')
    self.assertEqual(result, 'Account locked due to too many failed attempts')

    # Test case where password is invalid
    user = CustomUser.objects.create(username='user', password='password')
    result = authenticate('user', 'wrong_password')
    self.assertEqual(result, 'Invalid password')
    self.assertEqual(user.failed_attempts, 1)

    # Test case where authentication is successful
    result = authenticate('user', 'password')
    self.assertEqual(result, 'Authentication successful')
    self.assertEqual(user.failed_attempts, 0)

    # Test case where password is correct but user is not active
    inactive_user = CustomUser.objects.create(username='inactive_user2', is_active=False, password='password')
    result = authenticate('inactive_user2', 'password')
    self.assertEqual(result, 'User is not active')

    # Test case where password is correct but account is locked
    locked_user = CustomUser.objects.create(username='locked_user2', failed_attempts=3, password='password')
    result = authenticate('locked_user2', 'password')
    self.assertEqual(result, 'Account locked due to too many failed attempts')

Big Apps

To provide some real world examples of these techniques been applied into our industry, I've brought some open source projects code snippets:

React

This code block provides an example of how React codebase uses black box testing to check if given a className (input) that contains \n char, the actual className rendered (output) will still be available.

react/packages/react-dom/src/__tests__
/ReactTestUtils-test.js, Ln 100

it('can scryRenderedDOMComponentsWithClass with className contains \\n', () => {
    class Wrapper extends React.Component {
      render() {
        return (
          <div>
            Hello <span className={'x\ny'}>Jim</span>
          </div>
        );
      }
    }

    const renderedComponent = ReactTestUtils.renderIntoDocument(<Wrapper />);
    const scryResults = ReactTestUtils.scryRenderedDOMComponentsWithClass(
      renderedComponent,
      'x',
    );
    expect(scryResults.length).toBe(1);
  });

Python

This code block provides an example of how Python codebase uses black box testing to check if a Tuple responds to correctly (output) to different arguments (input)

Lib/test/test_tuple.py, Ln 27

def test_constructors(self):
        super().test_constructors()
        # calling built-in types without argument must return empty
        self.assertEqual(tuple(), ())
        t0_3 = (0, 1, 2, 3)
        t0_3_bis = tuple(t0_3)
        self.assertTrue(t0_3 is t0_3_bis)
        self.assertEqual(tuple([]), ())
        self.assertEqual(tuple([0, 1, 2, 3]), (0, 1, 2, 3))
        self.assertEqual(tuple(''), ())
        self.assertEqual(tuple('spam'), ('s', 'p', 'a', 'm'))
        self.assertEqual(tuple(x for x in range(10) if x % 2),
                         (1, 3, 5, 7, 9))

Gitlab

This code block provides an example of how Gitlab codebase uses white box testing to cover multiple status of a custom_email_verification service:

spec/models/service_desk/custom_email_verification_spec.rb, Ln 40

context 'when status is :finished' do
      before do
        subject.mark_as_started!(user)
        subject.mark_as_finished!
      end

      it { is_expected.to validate_absence_of(:token) }
      it { is_expected.to validate_absence_of(:error) }
    end

    context 'when status is :failed' do
      before do
        subject.mark_as_started!(user)
        subject.mark_as_failed!(:smtp_host_issue)
      end

      it { is_expected.to validate_presence_of(:error) }
      it { is_expected.to validate_absence_of(:token) }
    end
  end

Conclusion

The Glendford' book covers much more about testing and i highly recommend you to read the book. The topics I've covered are just some of them that really helps me to criticize tests generated by AI's and have a deeper knowledge of what software test is really about.

If there are specific topics from the book that have been particularly enlightening for you, I'd love to hear about them in the comments. Additionally, if you're aware of any strategies that can improve AI-generated tests, please share them with the community in the comments section.

Why Django uses regex on routes?

José Sobral — Thu, 31 Aug 2023 20:19:59 +0000

Configuration and Why

Django is a web framework which allows you to build your whole application using the concept of a project with one or several apps. There are tons of philosophies originated by this approach (like Modular Development, Separation of Concerns, Plug-n-play Features and etc).

All of these apps are configured by your project. One of these configurations is the ROOT_URLCONF in which allows you to pointer the 'master' url file config. This is fundamental to put in practice the django philosophies mentioned.

Importance of regular expressions

When i've first encountered regular expressions in Django apps, i think that was an over engineering process to build routes (as any junior can think). After some experiences i've understand the reason why and i think these two resources compiles well them

Django Book, The definitive guide to Django: Web Development Done Right

A route example from the book:

from django.conf.urls.defaults import *
from mysite.views import current_datetime
urlpatterns = patterns('',
 (r'^time/$', current_datetime),
)

The author explanation

This concept is best explained by example. If we had instead used the pattern '^time/' (without a dollar sign at the end), then any URL that starts with time/ would match, such as /time/foo and /time/bar, not just /time/. Similarly, if we had left off the initial caret character ('time/$'), Django would match any URL that ends with time/, such as /foo/bar/time/. Thus, we use both the caret and dollar sign to ensure that only the URL /time/ matches. Nothing more, nothing less.

One of the Django founders, on Reddit

In summary, django uses pattern matching to register routes and using regex you can build it in a easy and performatic way.

Open Source Examples

Flagsmith, 2.7k stars

https://github.com/Flagsmith/flagsmith/blob/main/api/api/urls/v1.py

Healthchecks, 6.5k stars

https://github.com/healthchecks/healthchecks

[Subscription] Subscription Flow

José Sobral — Tue, 20 Dec 2022 19:19:08 +0000

Neste manual vamos compartilhar como pensamos o nosso motor de Subscriptions dentro da nossa plataforma.

Chamamos de 'manual' e não 'artigo' pois o objetivo deste documento é ser um guia; por isso, a leitura não precisa ser top down e sim ser uma consulta para sanar eventuais dúvidas.

Esperamos que ajude os DEV's da INK e a todos que este documento tocar :)

Sumário

Seção 1: Principais diferenças de arquitetura entre o PagarMe e a Zoop

Bastidores Zoop
Diferença PagarMe-Zoop: desenho de endpoints
Diferença PagarMe-Zoop: consumo da API via métodos ao inves de JSON's
Arquitetura INK para o consumo da API da Zoop

Seção 2: Novos conceitos de arquitetura gerados pela migração da Zoop

Motor baseado em Webhooks
Expiração Manual de Subscriptions

Seção 3: Atributos essencias de subscription na Zoop e INK

due_date
due_since
expiration_date
is_active (loja)
is_active (subscription)
status
trial

Seção 4: Eventos utilizados

subscription.created
subscription.suspended
subscription.expired
subscription.active
invoice.overdue
invoice.paid

Seção 5: UseCases utilizados

Hashie Gem
Mind Map: Subscription Flow
UC's: webhooks
UC's: checkout
UC's: payment_update

Seção 1: Principais diferenças de arquitetura entre o PagarMe e a Zoop

No início do ano de 2021, demos um grande passo como plataforma: migramos do sistema de pagamentos do PagarMe para a Zoop

Sem entrar no mérito dos prós e contras de cada sistema de pagamento, neste artigo vamos focar no desafio técnico e em como a arquitetura de subscriptions foi idealizada.

Mas antes disso, nos bastidores...

O processo como um todo da migração foi a maior desafio técnico que os Devs da casa tiveram em suas carreiras naquele momento.

E, como todo o processo onde se adquire experiência, muita
coisa é feita na base de porrada e quebração de cabeça.

A história completa dos bastidores da migração ainda será um artigo, mas no resumo, alguns pontos relevantes:

Subdimensionamos o trabalho que seria migrar de um motor de assinaturas para outro
Na nossa arquitetura antiga, não suspendiamos o serviço de assinatura quando ele expirava, por isso não tinhamos experiência em como fazê-lo at all
Por fim, mais importante, quando o assunto é pagamento muito cuidado com a ânsia de lançar logo sua V0...lançar a migração de pagamento da forma que fizemos, foi bastante arriscado e pouco sustentável em matéria de gestão de conhecimento; isso gerou mais de 2 meses de trabalho posterior ao deploy, entre consertar bugs e readaptar novos motores. Além, é claro, de muita dor de cabeça.

Contudo, cá estamos com um motor novo de assinatura e buscando uma forma de registrar os passos que demos. VQV!

Voltando...

Tecnicamente, a maior diferença entre o PagarMe e a Zoop, é que o PagarMe é desenhado para ser implementando com muita velocidade e pouca customização.

Na prática, isso gera duas implicações:

Sistema de pagamento do pagarme chega com os endpoints preparados para a sua aplicação
O consumo da API se da através de métodos desenhados para a sua aplicação

Vamos a cada uma delas!

1-Sistema de pagamento do pagarme chega com os endpoints preparados para a sua aplicação

Por exemplo, para darmos um fetch em uma Subscription pelo PagarMe fazemos:

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

subscription_id = "ID_DA_ASSINATURA"
subscription = PagarMe::Subscription.find_by_id(subscription_id)

Já pela Zoop, precisamos...

a) Criar uma classe que recebe os endpoints
b) Configurar cada um dos tipos de clients, com suas respectivas autenticações
c) No caso da nossa aplicação, criamos uma classe intermediária que modulariza o consumo da API no client side (nosso lado)
d) Por fim, darmos o fetch

A seguir, cada ponto com exemplos...

a) Criar uma classe que recebe os endpoints

app> service_layers > zoop > plans_and_subscriptions > api > endpoints.rb

class Zoop::PlansAndSubscriptions::Api::Endpoints
  def initialize(client, clientV2)
    @client = client
    @clientV2 = clientV2
  end

...

  def subscription_details(subscription_id:)
    path = "subscriptions/#{subscription_id}"
    data = { subscription_id: subscription_id }
    response = @clientV2.get(path: path, data: data)
    begin
      JSON.parse(response)
    rescue => error

      puts "JSON Parse error => #{error}"
    end
  end
end

b) Configurar cada um dos tipos de clients, com suas respectivas autenticações

app> service_layers > zoop > auth > rest_client_api.rb

class Zoop::Auth::RestClientApi
  def initialize
    @api_key = 'key'
    @mkt_place_id = 'key'
    @api_url = 'key'
  end

  def post(path:,data:)
    url = url(path)
    Rails.logger.info data

    request = RestClient::Request.new(method: :post, url: url,payload: data, user: @api_key)
    response = request.execute

    response
  end
...
end

c)No caso da nossa aplicação, criamos uma classe intermediária que modulariza o consumo da API no client side (nosso lado):

app> service_layers > zoop > plans_and_subscriptions > subscriptions > details.rb

class Zoop::PlansAndSubscriptions::Subscriptions::Details
    def initialize(subscription_id:)
        @subscription_id = subscription_id
        @endpoints = Zoop::PlansAndSubscriptions::Api::Endpoints.new(Zoop::Auth::RestClientApi.new, Zoop::Auth::RestClientApiV2.new)
    end

    def execute
        subscription_details = @endpoints.subscription_details(subscription_id: @subscription_id)
    end   
end

d)Por fim, darmos o fetch

subscription_details = Zoop::PlansAndSubscriptions::Subscriptions::Details.new(
subscription_id: @subscription.zoop_subscription_id).execute

2-O consumo da API se da através de métodos desenhados para a sua aplicação

No pagarMe, para você acessar o fim do período de uma subscription (atributo current_period_end) é feito através de:

irb(main):003:0> PagarMe::Subscription.all.last.current_period_end
RestClient.get "https://api.pagar.me/1/subscriptions", "{\"page\":1,\"count\":10}", "Accept"=>"application/json", "Content-Length"=>"21", "Content-Type"=>"application/json; charset=utf8", "User-Agent"=>"pagarme-ruby/2.4.0", "X-PagarMe-User-Agent"=>"pagarme-ruby/2.4.0"
# => 200 OK | application/json 19666 bytes, 0.15s
=> "2021-03-10T00:27:31.849Z"
irb(main):004:0>

Já na Zoop, consumindo a API você recebe JSON's. Com isso, para acessar o fim do período de uma subscription (atributo expiration_date) fazemos:

irb(main):004:0> subscription_details = Zoop::PlansAndSubscriptions::Subscriptions::Details.new(
irb(main):005:1* subscription_id: Subscription.all.last.zoop_subscription_id).execute
  Subscription Load (2.2ms)  SELECT "subscriptions".* FROM "subscriptions" WHERE "subscriptions"."deleted_at" IS NULL ORDER BY "subscriptions"."id" DESC LIMIT $1  [["LIMIT", 1]]
=> {"id"=>"33ea0db33dc3430489527a6f1f2c1b6d", "marketplace_id"=>"aa671febc9d4466b9f34134327c56d20", "plan"=>"561ce6726be74b16b9fe4c51f6a94b03", "currency"=>"BRL", "updated_at"=>"2021-08-02T23:18:30+00:00", "tolerance_period"=>nil, "on_behalf_of"=>"36fabbcd71a540a2b4a34ae338b58069", "payment_method"=>"credit", "due_since"=>nil, "expiration_date"=>"2021-08-16T23:00:00", "created_at"=>"2021-08-02T22:45:53+00:00", "suspended_at"=>"2021-08-02T23:18:30+00:00", "due_date"=>"2021-08-16", "status"=>"suspended", "amount"=>9900, "customer"=>"10066c2410f9427ea3d6553b8dc8baeb"}
irb(main):006:0> subscription_details["expiration_date"]
=> "2021-08-16T23:00:00"
irb(main):007:0>

Essas duas diferenças já mudam drasticamente a maneira como todas as entidades de assinaturas vão se relacionar entre API-INK.

Contudo, a principal questão para o nosso time foi que não pensamos nos processos de interface da API com a nossa aplicação, como

renovação de pagamento
expiração de subscription
exclusão de multiplas subscriptions em caso de upsell
etc

pois no PagarMe, esses processos eram realizados automaticamente no lado do PagarMe.

Com isso, vamos aos principais conceitos de arquitetura trazidos pela escolha da Zoop

Seção 2: Novos conceitos gerados pela migração da Zoop

Motor baseado em Webhooks

Pela Zoop, recomenda-se que usemos os chamados Webhooks para "ouvir" as interações entre a API e a INK.

Na prática, um Webhook é de fato um "gancho" para que quando uma ação ocorra na API, haja uma chamada para o client side informando a ação e o que foi alterado.

Por exemplo, toda vez que houver uma criação de subscription na Zoop, haverá um trigger no evento subscription.created; com isso, podemos criar um Webhook que, toda vez que houver um subscription.created, possamos usar informações deste evento para atualizar nosso banco e aplicar nossas próprias regras de negócio.

Expiração Manual de Subscriptions

Na Zoop, a expiração de uma subscription é feita manualmente.

O que isso significa?

Simples, nós que precisamos dizer quando uma assinatura expira

Na prática isso trouxe uma grande dor de cabeça:

Como vamos setar e atualizar o campo de expiração para que o fluxo de renovação e suspensão de assinatura funcione corretamente?

A resposta à esta pergunta virá na explicação dos UseCases utilizados na nossa aplicação

Seção 3: Atributos essencias de subscription na Zoop e INK

Nesta seção, nosso objetivo é explicar cada um dos principais atributos gerados pela subscription na zoop e na nossa base.

Atributos Zoop

due_date: Data da próxima cobrança para a Subscription
expiration_date: Data de expiração para a Subscription
due_since: Data do último pagamento atribuido a subscription
status: Status que se encontra a Subscription (active, suspended, expired)

Atributos INK

expiration_date: Reflexo direto do expiration_date da Zoop
is_active (store): Booleano que indica se a loja está ativa ou não; caso não esteja, o usuário não conseguirá realizar vendas em sua loja.
is_active (subscription): Booleano que indica se a subscripton está ativa ou não; caso o usuário não possua nenhuma subscription ativa (is_active = true), a loja terá, em tese, um is_active = false
trial: Booleano que diz se a condição de trial para subscription é true ou false
status: Reflexo direto do status vindo da Zoop

A interface entre os atributos ficará clara na seção de UseCases Utilizados

Seção 4: Eventos utilizados

Nesta seção, vamos explicitar cada um dos eventos utlizados pela nossa aplicação, um payload de exemplo e quando idealizamos que eles seriam triggados

subscription.created

Payload

 {
            "created_at": "2021-08-04T12:05:30+00:00",
            "payload": {
                "marketplace_id": "aa671febc9d4466b9f34134327c56d20",
                "suspended_at": null,
                "payment_method": "credit",
                "currency": "BRL",
                "expiration_date": null,
                "due_since": null,
                "amount": 49900,
                "updated_at": "2021-08-04T12:05:30+00:00",
                "created_at": "2021-08-04T12:05:30+00:00",
                "status": "active",
                "id": "b66d91d2963445ef81aab5f173551b21",
                "due_date": "2021-08-18",
                "on_behalf_of": "36fabbcd71a540a2b4a34ae338b58069",
                "plan": "561ce6726be74b16b9fe4c51f6a94b03",
                "tolerance_period": null,
                "customer": "25b1a9c31ebc43fb85975eed7433761e"
            },
            "resource": "event",
            "status": "succeeded",
            "uri": "/v1/marketplaces/aa671febc9d4466b9f34134327c56d20/events/5a55ea1828bc409087f4b6f02bdef9f3",
            "id": "5a55ea1828bc409087f4b6f02bdef9f3",
            "dispatches": [
                {
                    "created_at": "2021-08-04T12:05:40+00:00",
                    "status": "succeeded",
                    "replay": false,
                    "webhook_id": "59c61025a6384edd8295493a4d0f55f5"
                }
            ],
            "type": "subscription.created"
        }

Trigger

No checkout de subscription (app>app_core>subscription>use_cases>checkout>process_subscription_checkout.rb), há a criação da subscription da Zoop e neste momento imaginamos que este evento será triggado.

subscription.suspended

Payload

 {
            "created_at": "2021-08-04T12:15:18+00:00",
            "payload": {
                "payment_method": "credit",
                "currency": "BRL",
                "tolerance_period": null,
                "updated_at": "2021-08-04T12:15:18+00:00",
                "expiration_date": "2021-08-18T23:00:00",
                "created_at": "2021-08-04T12:05:30+00:00",
                "customer": "25b1a9c31ebc43fb85975eed7433761e",
                "on_behalf_of": "36fabbcd71a540a2b4a34ae338b58069",
                "marketplace_id": "aa671febc9d4466b9f34134327c56d20",
                "amount": 49900,
                "suspended_at": "2021-08-04T12:15:18+00:00",
                "status": "suspended",
                "plan": "561ce6726be74b16b9fe4c51f6a94b03",
                "due_date": "2021-08-18",
                "id": "b66d91d2963445ef81aab5f173551b21",
                "due_since": null
            },
            "resource": "event",
            "status": "succeeded",
            "uri": "/v1/marketplaces/aa671febc9d4466b9f34134327c56d20/events/c1a933089175476d86e902a003b3b01e",
            "id": "c1a933089175476d86e902a003b3b01e",
            "dispatches": [
                {
                    "created_at": "2021-08-04T12:15:28+00:00",
                    "status": "succeeded",
                    "replay": false,
                    "webhook_id": "1c10b9ecf9c94687a43d7946d35f6141"
                }
            ],
            "type": "subscription.suspended"
        }

Trigger

Quando o usuário acessa a rota de /user/subscription, caso sua subscription esteja ativa, irá aparecer um botão escrito "Suspender Assinatura". No click deste botão é suspensa a assinatura e é trigado este evento (app>app_core>subscription>use_cases>webhooks>handle_subscription_suspended_event.rb)

subscription.expired

Payload

 {
            "created_at": "2021-08-04T12:28:01+00:00",
            "payload": {
                "payment_method": "credit",
                "on_behalf_of": "36fabbcd71a540a2b4a34ae338b58069",
                "created_at": "2021-04-19T19:26:51+00:00",
                "suspended_at": null,
                "tolerance_period": null,
                "expiration_date": "2021-06-10T09:01:54",
                "amount": 12900,
                "updated_at": "2021-08-04T12:28:01+00:00",
                "id": "67c9583d6b1f408ca2bbad23677901d6",
                "plan": "561ce6726be74b16b9fe4c51f6a94b03",
                "due_date": "2021-05-03",
                "customer": "f4f34cd05e2743029cab8e47a1e03e35",
                "status": "expired",
                "due_since": null,
                "currency": "BRL",
                "marketplace_id": "aa671febc9d4466b9f34134327c56d20"
            },
            "resource": "event",
            "status": "succeeded",
            "uri": "/v1/marketplaces/aa671febc9d4466b9f34134327c56d20/events/12e32795b0ce49dc8a914e36723514f3",
            "id": "12e32795b0ce49dc8a914e36723514f3",
            "dispatches": [
                {
                    "created_at": "2021-08-04T12:28:11+00:00",
                    "status": "succeeded",
                    "replay": false,
                    "webhook_id": "5388ead647cb4e9d93c78f33797e90ff"
                }
            ],
            "type": "subscription.expired"
        }

Trigger

Este evento será triggado quando a subscription chegar na sua data de expiração e não houver renovação da assinatura. Isso acontece quando o usuário não pagou a subscription e, no dia de expiração, a assinatura irá de active para expired

subscription.active

Payload

  {
            "created_at": "2021-08-04T12:58:40+00:00",
            "payload": {
                "payment_method": "credit",
                "currency": "BRL",
                "tolerance_period": null,
                "updated_at": "2021-08-04T12:58:40+00:00",
                "expiration_date": "2021-09-03T23:59:59",
                "created_at": "2021-06-16T13:52:43+00:00",
                "customer": "74369907fd1f446d9777c201be73eef6",
                "on_behalf_of": "36fabbcd71a540a2b4a34ae338b58069",
                "marketplace_id": "aa671febc9d4466b9f34134327c56d20",
                "amount": 12900,
                "suspended_at": null,
                "status": "active",
                "plan": "561ce6726be74b16b9fe4c51f6a94b03",
                "due_date": "2021-07-30",
                "id": "dc9ace773b63461c81139bd00d33c9d0",
                "due_since": "2021-06-30"
            },
            "resource": "event",
            "status": "succeeded",
            "uri": "/v1/marketplaces/aa671febc9d4466b9f34134327c56d20/events/b71e8a87ff0d41798be9033118342c9f",
            "id": "b71e8a87ff0d41798be9033118342c9f",
            "dispatches": [
                {
                    "created_at": "2021-08-04T12:58:50+00:00",
                    "status": "succeeded",
                    "replay": false,
                    "webhook_id": "3286bf41cbf2474d87e29e2331d0fef5"
                }
            ],
            "type": "subscription.active"
        }

Trigger

Este evento terá trigger quando uma assinatura for suspensa e posteriormente for reativada. Isso pode ser feito através do /user/subscription; quando o usuário suspender a assinatura, aparecerá uma opção "Reativar Assinatura". O click deste botão irá reativar a assinatura e triggar este evento

invoice.overdue

Payload

  {
            "resource": "event",
            "created_at": "2021-08-04T13:02:13+00:00",
            "uri": "/v1/marketplaces/aa671febc9d4466b9f34134327c56d20/events/36a24c2ab51746e4887ab5b3d318f32f",
            "status": "succeeded",
            "id": "36a24c2ab51746e4887ab5b3d318f32f",
            "dispatches": [
                {
                    "created_at": "2021-08-04T13:02:23+00:00",
                    "webhook_id": "b23ea12e177c482083b4ea02dae54f7d",
                    "status": "succeeded",
                    "replay": false
                }
            ],
            "type": "invoice.overdue",
            "payload": {
                "id": "56fd660c44c240afb0a3869c6398ab40",
                "setup_amount": null,
                "tolerance_period": null,
                "transactions": [],
                "description": null,
                "on_behalf_of": "36fabbcd71a540a2b4a34ae338b58069",
                "amount": 12900,
                "voided_at": null,
                "due_date": "2021-07-30T00:00:00",
                "status": "failed",
                "retries": 3,
                "payment_method": "credit",
                "paid_at": null,
                "subscription": "dc9ace773b63461c81139bd00d33c9d0",
                "expiration_date": null,
                "resource": "invoice",
                "invoice_customer": {
                    "first_name": "",
                    "last_name": null,
                    "taxpayer_id": null,
                    "id": "74369907fd1f446d9777c201be73eef6",
                    "email": "laurormn@gmail.com"
                },
                "max_retries": 3
            }
        }

Trigger

Primeiramente, um "invoice" é uma fatura. O conceito de fatura geralmente está relacionado com recorrência, quase como se fosse uma "conta" que chega periodicamente para você.

Na nossa aplicação, a única "conta" que chega recorrentemente para os usuários é a subscription. Logo, todos os eventos de invoice, hoje, estão relacionados a subscription.

O invoice.overdue significa que aquela fatura teve o seu número máximo de tentativas de pagamento atingido. Ou seja, o cartão de crédito associado pode estar sem limite disponível, pode não estar mais válido (caso de cartão de crédito virtual que é excluido) entre outras possibilidades. O fato é que o pagamento não aconteceu.

Este evento acontece no due_date (data da pŕoxima cobrança) da assinatura. Se no dia da cobrança ela for mal sucedida, este evento será trigado.

invoice.paid

Payload

{
            "resource": "event",
            "created_at": "2021-08-04T13:03:13+00:00",
            "uri": "/v1/marketplaces/aa671febc9d4466b9f34134327c56d20/events/7dbdc97c63df45f8bd40e80595b9e7a7",
            "status": "succeeded",
            "id": "7dbdc97c63df45f8bd40e80595b9e7a7",
            "dispatches": [
                {
                    "created_at": "2021-08-04T13:03:23+00:00",
                    "webhook_id": "9d453bca7b9947d4987d5e02dec0c692",
                    "status": "succeeded",
                    "replay": false
                }
            ],
            "type": "invoice.paid",
            "payload": {
                "payment_method": "credit",
                "status": "paid",
                "invoice_customer": {
                    "id": "888e1165cddf44d0a8eab133f41f53e5",
                    "taxpayer_id": "34498991000104",
                    "email": "suporte@arquiteturaequestre.com.br",
                    "first_name": "",
                    "last_name": null
                },
                "amount": 12900,
                "voided_at": null,
                "description": null,
                "due_date": "2021-08-04T00:00:00",
                "setup_amount": null,
                "retries": 0,
                "tolerance_period": null,
                "resource": "invoice",
                "paid_at": "2021-08-04T13:03:13+00:00",
                "max_retries": 3,
                "transactions": [
                    {
                        "masked_card": "5226***2794",
                        "card_brand": "MasterCard",
                        "currency": "BRL",
                        "id": "f00d64630d3d4af881a145371775f6b2"
                    }
                ],
                "on_behalf_of": "36fabbcd71a540a2b4a34ae338b58069",
                "id": "35c9881a40654d1d87b1d2e0fe8251b4",
                "subscription": "6bf2e484c5a249a98ca3e12196c5c41c",
                "expiration_date": null
            }
        }

Trigger

Como já explicado no evento anterior, um invoice é uma fatura. O evento ìnvoice.paid diz que uma fatura foi paga. Inclusive neste evento podemos saber a transaction_id relacionada a subscription.

Seção 5: UseCases utilizados

Antes de começarmos a falar sobre os UC, precisamos falar de dois pontos essenciais:

Hashie Gem
Como projetamos cada UC

1-Hashie Gem

Esta é uma Gem que usamos no Flow de Subscription que facilitou muito o nosso lado na hora de manipular os payloads chegados pela Zoop através dos Webhooks

Para resumir a história do uso por de trás da Gem, vamos falar apenas sobre a dor resolvida e como implementamos ela no projeto

Dor resolvida Imagina que, recebendo um hash do evento invoice.paid, por exemplo, queiramos acessar a transaction_id desta fatura.

Para isso, quando chega o payload de exemplo:

 {
            "resource": "event",
            "created_at": "2021-08-04T14:42:13+00:00",
            "uri": "/v1/marketplaces/aa671febc9d4466b9f34134327c56d20/events/190dc7e15d414005aafe90d028ec54c3",
            "status": "succeeded",
            "id": "190dc7e15d414005aafe90d028ec54c3",
            "dispatches": [
                {
                    "created_at": "2021-08-04T14:42:23+00:00",
                    "webhook_id": "9d453bca7b9947d4987d5e02dec0c692",
                    "status": "succeeded",
                    "replay": false
                }
            ],
            "type": "invoice.paid",
            "payload": {
                "payment_method": "credit",
                "status": "paid",
                "invoice_customer": {
                    "id": "a6080bb9b36c4af8a9c9fce651fd7ea8",
                    "taxpayer_id": "39123487828",
                    "email": "weynerenan@gmail.com",
                    "first_name": "Renan",
                    "last_name": "Weyne"
                },
                "amount": 12900,
                "voided_at": null,
                "description": "Fatura avulsa de assinatura para loja 3w",
                "due_date": "2021-08-04T00:00:00",
                "setup_amount": null,
                "retries": 0,
                "tolerance_period": null,
                "resource": "invoice",
                "paid_at": "2021-08-04T14:42:13+00:00",
                "max_retries": 3,
                "transactions": [
                    {
                        "masked_card": "5502***5987",
                        "card_brand": "MasterCard",
                        "currency": "BRL",
                        "id": "dcab432a48e445e3b5c42a0e91400bdb"
                    }
                ],
                "on_behalf_of": "36fabbcd71a540a2b4a34ae338b58069",
                "id": "f304c7eb4d8d464b96e94e44a33a1e35",
                "subscription": "5c99dfbb6dd745db9e75159f9b8912e9",
                "expiration_date": null
            }
        }

Podemos colocar este numa variável event e extrair o transaction_id através de:

event["payload"]["transactions"][0]["id"]

O Hashie chega para prevenir esta sintax! Com ele, podemos buscar o chave de um hash através de métodos intuitivos e que facilitam muito o manejo de objetos com estrutura em hash.

No exemplo do payload, com o Hashie, poderíamos extrair o transaction_id fazendo:

@event_params = event_params
@transactions = (@event_params.deep_find("transactions"))[0]
@transactions["id"]

E por isso usamos o Hashie! Para facilitar a sintax de manipulação de objetos com estrutura em hash :)

Implementação no Projeto

A implementação aconteceu em 3 etapas

a) Adicionar no projeto os módulos associados ao Hashie.
app>services>hashie>deep_find.rb
app>services>hashie>deep_locate.rb
app>services>hashie>deep_fetch.rb

b) Criamos um Presenter* que recebe o hash como params na chamada da nossa aplicação pelo webhook da Zoop chamado ParametersPresenter

class ParametersPresenter < BasePresenter
  def initialize(event_params:)
    @event_params = event_params
  end

  def build
    @event_params.permit! rescue nil
    hash_params = @event_params.to_h rescue @event_params

    hash_params.extend Hashie::Extensions::DeepFind
    hash_params.extend Hashie::Extensions::DeepFetch
    hash_params.extend Hashie::Extensions::DeepLocate
  end
end

Este Presenter tem como finalidade adaptar um objeto que chega como ActionController::Paramaters para um objeto Hash com métodos do Hashie como o deep_find mostrado anteriormente.

c) Damos um build em cada UC para transformar um ActionController::Parameters um Hash com PowerUps da gem do Hashie

Exemplo:

module Subscription::UseCases::Webhooks
  class HandleInvoicePaidEvent
    def self.build(event_params:)
      new(
        event_params: ParametersPresenter.new(event_params: event_params).build
      )
    end

Pronto! Agora já sabemos como usar o Hashie :)

2-Como projetamos cada UC

Para este projeto, estreiamos o conceito de Mind Map na INK.

O objetivo era ter visualmente um fluxo de como cada ação do usuário refletia um evento na Zoop e, consequentemente, um script na nossa aplicação.

Este Mind Map foi essencial para estruturarmos a interface de cada atributo da INK com a Zoop e pensarmos na execução de cada UC

Hora dos UC's...

use_cases>webhooks

handle_invoice_paid_event.rb

Abaixo cada um dos métodos que são executados no evento invoice.paid

app>app_core>subscription>use_cases>webhooks>handle_invoice_paid.event.rb

    def execute
      set_active_status_into_db
      reactivate_status_into_zoop
      set_store_is_active
      set_subscription_is_active
      set_db_expiration_date
      set_zoop_expiration_date
      remove_trial
      create_subscription_invoice_record
    end

Interfaces:
a) Atributo status sendo setado active na Zoop e na INK
b) Atributo is_active da loja sendo setado para true
c) Atributo is_active da subscription sendo setado para true
d) Atributo trial sendo setado para false pois houve pagamento
e) Criação de um SubscriptionInvoice para acessarmos o invoice na nossa base com mais facilidade.
f) Atributo expiration_date sendo atualizado na Zoop e na INK. Ambos serão atualizados para o dia de hoje + dias do plano (anual, mensal); o final do dia que resultará esta operação, será o novo expiration_date

    def set_zoop_expiration_date
      current_expiration_date       = @subscription.expiration_date
      plan_days                     = @subscription.plan.interval

      Subscription::UpdateExpirationDateJob.perform_later(
        subscription: @subscription,
        expiration_date: plan_days.days.from_now.end_of_day.strftime('%Y-%m-%dT%H:%M:%S')
      )
    end

PS: A escolha do final do dia foi proposital. Isso ocorre pois o due_date (próxima cobrança) irá acontecer no início do dia, então caso não haja pagamento ao longo do dia, no final do dia haverá expiração

handle_invoice_overdue.rb

Abaixo cada um dos métodos que são executados no evento invoice.overdue

      def execute
        notify_invalid_credit_card_to_user
      end

Interfaces
a) Não há interfaces de atributos; aqui apenas notificamos o usuário do cartão de crédito inválido.

handle_subscription_active_event.rb

Abaixo cada um dos métodos que são executados no evento subscription.active

    def execute
      set_status
    end

Interface
a) Atualizamos o atributo status na nossa base para active.

handle_subscription_created_event.rb

Abaixo cada um dos métodos que são executados no evento subscription.created

    def execute
      set_trial
      set_status
      set_db_expiration_date
      set_zoop_expiration_date
    end

Interfaces
a) Setamos o atributo trial para true dado que a subscription acabou de ser criada
b) Setamos o atributo status para active
c) Setamos o atributo expiration_date para o due_date da subscription, no final do dia.

handle_subscription_expired_event.rb

Abaixo cada um dos métodos que são executados no evento subscription.expired

    def execute
      set_status
      set_subscription_is_active
      handle_store_is_active
    end

Interfaces
a) Atributo status setado para expired
b) Atributo is_active da subscription é setado para false
c) Caso não hajam subscriptions com status active para aquele usuário, sua loja será desativada.

handle_subscription_suspended_event.rb

Abaixo cada um dos métodos que são executados no evento subscription.suspended

    def execute
      set_status
      handle_store_block
    end

Interfaces:
a) Setamos o atributo status para suspended
b) Lançamos um BackgroundJob para acontecer no dia da expiração da subscription; quando este BJ rodar, caso não hajam subscription com is_active=true, a loja será desativada.

Isso precisou ser feito pois as subscriptions suspended não migram para expired no dia da expiração; ou seja, elas nunca terão evento subscription.expired e precisamos usar este BJ para assegurar a desativação.

Exemplo:

        {
            "payment_method": "credit",
            "currency": "BRL",
            "tolerance_period": null,
            "updated_at": "2021-06-10T11:56:04+00:00",
            "expiration_date": "2021-06-10T08:56:02",
            "created_at": "2021-02-25T13:21:57+00:00",
            "customer": "a0ddaadd8c474a3193dcb153d88e0ea2",
            "on_behalf_of": "36fabbcd71a540a2b4a34ae338b58069",
            "marketplace_id": "aa671febc9d4466b9f34134327c56d20",
            "amount": 12900,
            "suspended_at": "2021-05-17T19:36:34+00:00",
            "status": "suspended",
            "plan": "561ce6726be74b16b9fe4c51f6a94b03",
            "due_date": "2021-06-11",
            "id": "3ced54f621d340bda03e7b39ceb34caf",
            "due_since": "2021-03-11"
        }

Subscription com expiration_date para 2021-06-10T08:56:02 (data já ocorrida) e mesmo assim com status suspended; mais uma vez, subscriptions suspended não triggam subscription.expired

Checkout

process_subscription_checkout.rb

        def execute
            create_buyer_id
            suspend_old_subscription
            create_zoop_subscription
            associate_credit_card_to_customer
            create_subscription_database_subscription
            create_store
        end

Payment Update

handle_subscription_reactivation_process.rb

        def execute
            associate_new_credit_card_to_zoop_customer
            associate_new_credit_card_token_to_subscription
            create_single_invoice
        end

Aqui, para reativarmos uma loja que está desativada, há um checkout especial (https://reserva.ink/subscriptions/reactivation/checkout).

Nele, simplesmente associamos um novo cartão de crédito ao usuário e criamos uma fatura avulsa para ser paga instanteamente.

Quando ela for paga, o evento invoice.paid será triggado e a loja será reativada.

handle_credit_card_change_process.rb

        def execute
            associate_new_credit_card_to_zoop_customer
            associate_new_credit_card_token_to_subscription
        end

[Dashboard] Máscara de Campo

José Sobral — Tue, 20 Dec 2022 19:17:30 +0000

Neste artigo vamos explicar como foi realizada a implementação do projeto de Máscara de Campo no nosso Dashboard

Como tudo que fazemos aqui na INK, o nosso Dashboard 2.0 lançado no mês passado (Jun/ 2021) foi feito na base do MVP...Let's make nossa V0.

imagem da seção 'Financeiro' do novo dashboard

Como toda v0, muitas partes da aplicação não foram implementadas; e, uma muita importante que implementamos recentemente, foi a máscara de campo e neste artigo vamos documentar como pensamos este projeto.

Escopo do Artigo

Estratégia do projeto
Biblioteca de Máscara de Campo
Uso da Biblioteca
Máscara de Campo criadas
Implementação no Projeto

Estratégia do projeto

Recentemente no nosso time de Tech, estamos enfrentando um momento muito especial que acomete todo o time de tecnologia: como os Devs podem organizar o pensamento e criar uma gestão de conhecimento dentro do time?

Se algum Dev que estiver lendo este artigo e achar que a resposta é óbvia, estamos abertos a ouvi-la através do jose.sobral@reserva.ink.

Contudo, aqui na INK a resposta à esta pergunta ainda está em construção e nesta seção do artigo, vamos explicitar como estamos construindo esta resposta

A melhor forma, até então, que estamos pensando esta gestão de conhecimentos é através de Mapas Mentais. Com eles, podemos pensar e compartilhar o pensamento visualmente através de conceitos com relacionamentos, cores e identidades próprias.

No projeto de Máscara de Campo, construimos um mapa onde no centro temos todas seções do Dashboard (Painel INK, Financeiro, Produtos e etc) e uma ramificação para cada uma destas seções contendo os formulários presentes nesta seção.

Então, por exemplo, temos um fórmulário dentro de seção de Cupom para criação de cupom. Nele, mapeamos todos os inputs presentes nesta seção e quais as máscaras de cada campo levaria

No pensamos na cor salmão, temos o nome do campo, o datatype do campo e o nome do component_id que levaria as propriedades de máscara de campo através de um jQuery

Dessa forma, qualquer Dev que quiser ver a estruturação do projeto pode acessar a publicação do mapa:

Mapa Mental - Mask Field

E, até então, essa é a nossa primeira resposta (a tal da V0) para a gestão de conhecimentos no time de tecnologia da INK :)

Biblioteca de Máscara de Campo

Para este projeto usamos a biblioteca de máscara de campo criada pelo Igor Escobar

Além de uma documentação fácil, a biblioteca é construída usando jQuery que é uma ferramenta bem difundida na arquitetura da INK.

Uso da Biblioteca

Para implementarmos a máscara de campo com o uso desta biblioteca, alguns tricks foram necessários.

1) Como trazer um regex para um caracter?

Para trazermos um regex para um caracter, podemos usar o conceito de pattern da documentação.

Com ele, conseguimos desenhar um regex para cada um dos caracteres do campo que estamos aplicando a máscara!

Olha o exemplo de máscara que aplicamos para um campo que deve aceitar um hexadecimal color (#000000)

  $('.hexadecimal-mask').mask(`BAAAAAAA`, {'translation': {
    B: {pattern: /[#]/},
    A: {pattern: /[A-Za-Z0-9]/}
  }});

Com ele, garantimos que o primeiro caracter chegue com o regex /[#]/, ou seja, só aceite # e os demais caracteres sejam letras do alfabeto, maiúsculas ou minúsculas ([A-Za-Z]) ou números [0-9].

2) O que fazer quando queremos aplicar a máscara de campo em um campo que não sabemos o número de caracteres necessários?

No caso da máscara do CPF, sabemos que precisaremos de 11 dígitos; o mesmo é válido para o telefone, data de nascimento, etc.

Agora, é campos como "primeiro nome"? Ou "valor do desconto"?

Aqui entrou o segundo trick no uso da biblioteca!

Quando não sabemos o número de caracteres necessários, podemos ativar a flag de optional: true e colocar tantos caracteres quanto for o limite permitido pelo campo.

Por exemplo:

  $(".alphanumeric-single-word-mask").mask(`${'A'.repeat(200)}`, {'translation': {
    A: {pattern: /^[a-zA-Z0-9çÇ]/, optional: true},
  }});

Aqui criamos uma máscara que permite até 200 caracteres - fazemos isso usando o ${'A'.repeat(200)} e, como eles são opcionais, podemos colocar quantos caracteres desejarmos num range de 1 há 200 caracteres.

Máscara de Campo criadas

Como já exposto anteriormente no artigo, criamos a Máscara de Campo através do jQuery, fazendo com que uma classe levasse a um input as propriedades da máscara daquele campo.

Por exemplo, na seção de Cadastro de Loja da nossa plataforma, o usuário precisa colocar o seu CPF, no formato XXX.XXX.XXX-XX.

Neste exemplo, precisamos de um campo que aceite apenas números e que haja uma pontuação no lugar desejado, conforme o formato do CPF. Por isso, para este campo, será atribuído a máscara:

cpf-mask
Campo só aceitará números e terá o formato XXX.XXX.XXX-XX

As classes que criamos para este projeto foram:

app > assets > javascipts > dashboard > utils > mask.js

$(".alphabetic-multiple-words-with-accent-mask").mask(`${'A'.repeat(500)}`, {'translation': {
    A: {pattern: /^[a-zA-ZàèìòùÀÈÌÒÙáéíóúýÁÉÍÓÚÝâêîôûÂÊÎÔÛãñõÃÑÕäëïöüÿÄËÏÖÜŸçÇ_ ]/, optional: true},
  }});

  $(".alphabetic-single-word-with-accent-mask").mask(`${'A'.repeat(200)}`, {'translation': {
    A: {pattern: /^[a-zA-ZàèìòùÀÈÌÒÙáéíóúýÁÉÍÓÚÝâêîôûÂÊÎÔÛãñõÃÑÕäëïöüÿÄËÏÖÜŸçÇ]/, optional: true},
  }});

  $(".numeric-mask").mask(`${'0'.repeat(20)}`);

  $('.phone-mask').mask('(00) 00000-0000');

  $('.cpf-mask').mask('000.000.000-00', {reverse: true});

  $('.cnpj-mask').mask('00.000.000/0000-00', {reverse: true});

  $('.cep-mask').mask('00000-000');

  $(".alphanumeric-single-word-mask").mask(`${'A'.repeat(200)}`, {'translation': {
    A: {pattern: /^[a-zA-Z0-9çÇ]/, optional: true},
  }});

  $(".alphanumeric-single-word-with-accent-mask").mask(`${'A'.repeat(200)}`, {'translation': {
    A: {pattern: /^[a-zA-Z0-9àèìòùÀÈÌÒÙáéíóúýÁÉÍÓÚÝâêîôûÂÊÎÔÛãñõÃÑÕäëïöüÿÄËÏÖÜŸçÇ]/, optional: true},
  }});

  $(".alphanumeric-single-word-uppercase-mask").mask(`${'A'.repeat(200)}`, {'translation': {
    A: {pattern: /^[A-Z0-9Ç]/, optional: true},
  }});

  $(".alphanumeric-single-word-lowercase-mask").mask(`${'A'.repeat(200)}`, {'translation': {
    A: {pattern: /[a-z0-9]/, optional: true},
  }});

  $(".alphanumeric-multiple-word-with-accent-mask").mask(`${'A'.repeat(500)}`, {'translation': {
    A: {pattern: /^[a-zA-Z0-9àèìòùÀÈÌÒÙáéíóúýÁÉÍÓÚÝâêîôûÂÊÎÔÛãñõÃÑÕäëïöüÿÄËÏÖÜŸçÇ_ ]/, optional: true},
  }});

  $(".alphanumeric-multiple-word-with-accent-up-to-15-char-mask").mask(`${'A'.repeat(15)}`, {'translation': {
    A: {pattern: /^[a-zA-Z0-9àèìòùÀÈÌÒÙáéíóúýÁÉÍÓÚÝâêîôûÂÊÎÔÛãñõÃÑÕäëïöüÿÄËÏÖÜŸçÇ_ ]/, optional: true},
  }});

  $('.float-mask').mask(`1${'1'.repeat(50)}.11`, {'translation': {
    1: {pattern: /[0-9]/, optional: true}
  }});

  $('.art-price-mask').mask(`211.11`, {'translation': {
    1: {pattern: /[0-9]/, optional: true},
    2: {pattern: /[1]/, optional: true}
  }});

  $(".art-range-price").attr('type', 'number');

  $(".art-range-price").attr({
    "max" : 159,        
    "min" : 59          
  });


  $('.hexadecimal-mask').mask(`BAAAAAAA`, {'translation': {
    B: {pattern: /[#]/},
    A: {pattern: /[A-Z0-9]/}
  }});

  $('.social-media-mask').mask(`${'A'.repeat(200)}`, {'translation': {
    A: {pattern: /[A-Za-z0-9(),-_.,]/, optional: true}
  }});

Implementação no Projeto

Por fim, para implementarmos a máscara no projeto, aplicamos em cada component de input da aplicação o devido component_class

Dessa forma:

<div class="col s12 m12 l6">
  <%= render partial: 'user/dashboard/components/input/text_field_with_helper', locals: {
    title: 'Valor do desconto',
    helper_text: 'Valor em R$',
    name:'coupon[value]',
    component_class: "float-mask"
  } %> 
</div>

Com amor e carinho,

Sobral, INK

Shrine Photo Uploader – Galeria de Fotos

José Sobral — Mon, 18 Jan 2021 22:36:31 +0000

Você já tentou criar uma aplicação web que permitisse upload de fotos? Nós, da Reserva INK já e gostaríamos de partilhar sobre a experiência de como criar uma feature iradíssima em Rails =)

Feature:

Usuários fazem upload de suas fotos

Relacionam à suas camisetas

Exibimos uma galeria de fotos e as respectivas imagens associadas a cada foto

Toolkit: Shrine

Neste artigo, contaremos um pouco mais sobre como instalar o Shrine e como utilizamos ele para criar a Galeria de Fotos da INK. Toda a aplicação desta feature foi escrita no paradigma MVC (Model View Controller), em Rails e tentaremos passar em detalhes a construção de cada parte do código.

Lembrando que a nossa intenção é muito mais compartilhar o conhecimento do que se mostrar referência na linguagem. Dito isso, se você tiver quaisquer sugestões de como poderíamos fazer melhor cada um dos passos a seguir ou apenas quiser conversar sobre a feature, estamos de braços abertos para receber feedbacks através do jose.sobral@reserva.ink

1-Como instalar o shrine do zero
2-Como configuramos em nossa aplicação

a)Model
I-Modelagem de dados
II-Criando os models no rails
III-Utilizando o shrine para guardar as imagens

b)View
I-Como criar o layout do form que guardará suas imagens II-Relacionar fotos e camisetas

c)Controller
I-Criando a galeria de cada loja
II-CRUD de fotos
III-Relacionamento de fotos e camisetas

1-Como instalar

A instalação do Shrine é bem tranquila e segue basicamente dois passos:

a) gemfile
gem "shrine", "~> 3.0"

b) config > initializers > shrine.rb

require "shrine"
require "shrine/storage/file_system"

if Rails.env.development? 
    Shrine.storages = {
        cache:  Shrine::Storage::FileSystem.new(“public”, prefix: “uploads/cache”)
        store: Shrine::Storage::FileSystem.new(“public”, prefix: “uploads”),


elsif Rails.env.Production? 
    Require ‘shrine/storage/s3’

    s3_options = {
        ***Suas credenciais do S3***
    }
    Shrine.storages = {
        cache: Shrine::Storage::S3.new(prefix: ‘cache’, **s3_options), # temporary
        store: Shrine::Storage::S3.new(prefix: ‘store, **s3options),       # permanent
}

end

Shrine.plugin :activerecord           # loads Active Record integration
Shrine.plugin :cached_attachment_data # enables retaining cached file across form redisplays
Shrine.plugin :restore_cached_data    # extracts metadata for assigned cached files

Diferenciamos o Storage para o ambiente de Desenvolvimento e para o ambiente de Produção.

Quando a feature está no ar, o armazenamento de dados ocorre através do S3.
Em desenvolvimento, o upload é realizado para um banco local.

2-Como configuraramos em nossa aplicação

a)Model

i-Modelagem de dados

Para início de conversa, falemos sobre como a modelagem de dados foi feita. No ínicio, sabíamos que teriam dois fluxos de dados através das entidades:

Galeria
Fotos
Relacionamento fotos-produto

Por isso, quando começamos o projeto pensamos em criar três Models: Picture e GalleryRelatedProducts e Gallery, da seguinte forma:

Gallery

Estruturando o problema:

Cada seller teria sua própria galeria
Por enquanto, na nossa arquitetura atual, cada loja teria apenas uma galeria

Decisão

ID Store_id

Com esta modelagem, cada loja teria sua própria galeria (Store_id) e, no futuro, se quisermos que cada loja tenha mais de uma galeria, não teríamos que remodelar todo nosso Model pois poderíamos ter ID’s diferentes para o mesmo Store_id.

Picture

Estruturando o problema:

Cada loja precisava possuir suas próprias fotos
A mesma loja pode ter N fotos

Decisão:

ID Gallery_id Image_data

Com essa modelagem, cada foto teria seu próprio ID e saberíamos qual o owner da foto através do gallery_id

GalleryRelatedProducts

Estruturando o problema:

Cada loja poderia se relacionar N fotos ao mesmo produto
Cada Foto, poderia ser associada a N fotos

Decisão

ID Picture_id Art_id

Com isso, conseguimos criar um model N-N, que permite que a mesma foto (picture_id único) se relacione com tantas artes quanto necessário (Art_id) e vice e versa.

ii-Criando os models no rails

Para criar os models executamos através do cmd,

$ rails generate model Gallery store:references
$ rails generate model Picture gallery:references image_data:text
$ rails generate model PictureRelatedProduct picture:references art:references

PS1: O comando “references” cria automaticamente uma foreign_key com o model que veio chamado antes dos “:”

PS2: O campo “image_data” não foi escolhido por acaso, a documentação do shrine pede que utilizemos o nome do tipo de arquivo seguido de “data” para este atributo. Genericamente: _data

iii-Utilizando o shrine para guardar as imagens

Neste passo você começará a sentir a potência do Shrine. Descreveremos em 3 passos como fazer esta configuração

Primeiro passo: Criamos uma classe uploader, herdando métodos do Shrine

app > uploaders > store_picture_uploader.rb

Class StorePictureUploader < Shrine
end

Segundo passo: Na model que receberemos os dados do Upload (picture, no nosso caso), faremos uma chamada desta classe que criamos em (i)

app > models > picture.rb

class Picture < ApplicationRecord
    include StorePictureUploader::Attachment(:image) 
end

Com isso, garantimos que os dados que chegarão neste atributo (image_data) chegarão através do Shrine.

PS: Usamos :image pois foi o nome do campo que criamos no model Picture (image_data), tirando a palavra “data”.

Terceiro passo: Não tem passo 3, é só isso mesmo :)

b)View

Arquivos utilizados:
app > views > user > dashboard > galleries > index.html.erb
app > views > user > dashboard > galleries > edit_image.html.erb

O usuário terá acesso a três interfaces:

Upload de fotos
Alterar e Deletar fotos / associar foto a um produto
Galeria que exibirá suas fotos os clientes de uma loja

PS: A interface de exibição das fotos não entrará neste artigo pois utilizamos uma arquitetura DDD (Domain Driven Design). Posteriormente, em outro artigo falaremos sobre como utilizamos esta arquitetura.

Sendo assim, vamos explorar as duas primeiras interfaces

I-Como criar o layout do form que guardará suas imagens

Upload de fotos

app > views > user > dashboard > galleries > index.html.erb

<%= form_for :picture, url: gallery_upload_path do |f| %>
    <%= f.hidden_field :image %>
    <%= f.file_field :image %>
    <%= f.submit “Enviar foto” %>
<% end %>

Debugando:

:picture -> Model que estaremos enviando as informações do form
:image -> Atributo que estaremos enviando a imagem. Lembrando que, mesmo o nome do campo sendo image_data, deixamos apenas image segunda a documentação do Shrine
gallery_upload_path -> Rota de post para onde enviaremos as informações de upload

post '/user/dashboard/gallery/', to: 'user/dashboard/galleries#upload', as: :gallery_upload

Adicionando um CSS e helpers de bootstrap…

Deletar fotos

app > views > user > dashboard > galleries > edit_image.html.erb

<%= link_to gallery_delete_picture_path(@image.id) do%>
    <button> Deletar Foto da Galeria </button>
<% end %>

Debugando:

@image = Picture.find(params[:pic_id])
gallery_delete_picture_path -> Rota para deletar uma imagem no banco. Ela pede um parâmetro que é a ID da foto

get '/user/dashboard/gallery/delete/:id', to: 'user/dashboard/galleries#delete', as: :gallery_delete_picture

Debugando:

:picture -> model para onde enviaremos o form
onchange: ‘this.form.submit()’; -> com isso, fazemos que o próprio botão de escolha da foto seja o mesmo de submit.
gallery_update_picture_path -> Rota para atualizarmos uma imagem no banco

post '/user/dashboard/gallery/update/:pic_id', to: 'user/dashboard/galleries#update', as: :gallery_update_picture

II-Relacionamento de fotos e artes

Adicionar relação

<%= link_to gallery_insert_related_path(art.id, @image.id) %>
    <button> Adicionar </button>
<% end %>

Debugando:

art -> Para exibimos todas as artes do usuário no carrosel, fizemos um:

<% arts.each do |art| %>
<%= link_to gallery_insert_related_path(art.id, @image.id) %>
<button> Adicionar </button>
<% end %>
<% end %>

PS: Por isso que acessamos a variável “art”. Além disso, @arts = @store.arts, sendo @store a variável que instanciamos através do before_action

gallery_insert_related_path -> Rota para chamarmos a action de criação do relacionamento

get '/user/dashboard/gallery/insert_related/:art_id/:pic_id', to: 'user/dashboard/galleries#insert_related', as: :gallery_insert_related

Remover relação

<%= link_to gallery_remove_related_path(art.id, @image.id) %>
    <button> Remove </button>
<% end %>

Debugando:

gallery_remove_related_path -> Rota deletarmos uma associação do model GalleryRelatedPicture

get '/user/dashboard/remove_related/:art_id/:pic_id', to: 'user/dashboard/galleries#remove_related', as: :gallery_remove_related

c)Controller

app > controllers > user > dashboard > galleries_controller.rb

I-Criando a galeria de cada loja

Para criarmos uma galeria para o usuário, utilizamos o método before_action do rails. Com ele, assim que o usuário acessa a página do seu respectivo controller, antes de tudo, é executada uma ação.

Nossa lógica então foi fazer o seguinte: Assim que o usuário acessar a galeria através de seu dashboard, faremos:

app/controllers/galleries_controller.rb

class User::Dashboard::GalleriesController > ApplicationController
    before_action :load_store_and_galley
….

private
def load_store_and_gallery
    load_gallery
    load_store
end 

def  load_gallery
    @gallery = current_user&.store&.gallery || Gallery.new(store: current_user&.store)
end

def load_store
    @store = current_user&.store
end

Debugando:

current_user -> método nativo do rails para sabermos qual o usuário atual que está na nossa aplicação
& -> Com ele, a nossa aplicação não irá quebrar caso uma das chamadas seja “nil”

II-CRUD de fotos

Insert

Como mostramos na view, estamos usando um form_for, passando a rota gallery_upload_path como argumento

form_for

<%= form_for :picture, url: gallery_upload_path do |f| %>

gallery_upload_path

post '/user/dashboard/gallery/', to: 'user/dashboard/galleries#upload', as: :gallery_upload

A action upload, ficou assim:

def upload
    @picture = Picture.new(post_params)
    @picture.gallery = @gallery

    if !@picture.save
        flash[:error] = @picture.errors.messages[:image] 
    end
end


private
def post_params
    params.require(:picture).permit(:image)
end

Debugando:

@gallery -> conseguimos acessar a variável de instância @gallery mesmo sem tê-la chamado neste action pois criamos ele usando o before_action. Logo, todas as actions do controller gallery terão acesso a esta variável
flash[:error] = @picture.errors.message[:image] -> em @picture, estamos instanciando um novo objeto do model Picture, logo ele retornará um ActiveRecord. Com isso, conseguimos acessar alguns métodos de objeto ActiveRecord, entre eles o objeto errors.message. Mas antes de falar sobre este método, mostraremos uma das validações que fizemos neste model.

app > models > picture.rb

validate :validate_image
...
def validate_image
if image.blank?
Errors.add(:image, ‘Por favor, adicione uma imagem’)
return
end
end

Com isso, fazemos com que, caso a imagem venha vazia (submit sem upload), adicionemos um “error” ao objeto Picture que foi instanciado (@picture = Picture.new no nossso caso) e não salvemos a imagem vazia no banco.

Por isso podemos combinar:

if !@picture.save → caso a imagem não seja salva no banco
@picture.errors.message[:image] → chamemos o log de erro que causou o não-salvamento do atributo :image

Update

Também mostrado na view, usamos um form_for passando a rota gallery_update_picture_path.

form_for

<%= form_for :picture, url: gallery_update_picture_path(@image.id) do |f| %>

gallery_update_picture_path

post '/user/dashboard/gallery/update/:pic_id', to: 'user/dashboard/galleries#update', as: :gallery_update_picture

app > controllers > galleries_controller.rb

def update
@picture = Picture.find_by(id: params[:pic_id])

if @picture.update(post_params)
    flash[:error] = @picture.errors.full_messages.first
    end
end

Debugando:

@picture.update -> Como @picture é um objeto ActiveRecord, conseguimos utiizar o método udpate
@picture.errors.full_messages.first -> Como não estamos instanciando um objeto novo no model Picture, a validação validate_image mostrada é executada de forma diferente. A saída que achamos para conseguimos carregar o log dos erros gerados foi usar este método chamado full_messages.first.

Delete

Esse foi o mais simples. Tivemos apenas que criar um link_to para a rota de delete – gallery_delete_picture_path e executar os devidos comandos no controller

link_to

get '/user/dashboard/gallery/delete/:id', to: 'user/dashboard/galleries#delete', as: :gallery_delete_picture

gallery_delete_picture

get '/user/dashboard/gallery/delete/:id', to: 'user/dashboard/galleries#delete', as: :gallery_delete_picture

app > controllers > galleries_controller.rb

def delete
    @gallery_picture = Picture.find_by(id: params[:id])

    @gallery_picture.destroy

    redirect_to user_dashboard_gallery_path
end

Debugando:

params[:id] -> ID da imagem que desejamos excluir
.destroy -> método para deletar um objeto ActiveRecord
redirect_to -> método para redirecionamos o usuário para uma rota
user_dashboard_gallery_path ->

get '/user/dashboard/gallery(/:page)', to: 'user/dashboard/galleries#index', as: :user_dashboard_gallery

III-Relacionamento de fotos e artes

Adicionar relação foto – arte

Foi bem simples fazer. Colocamos aquele botão “adicionar” que mostramos na view e, por trás do panos do controller fizemos

app > controllers > galleries_controller.rb

def insert_related
    @picture = Picture.find_by(id: params[:id])
    @related = GalleryRelatedPicture.new(art_id: params[:art_id], picture: @picture, gallery: @gallery)

    @related.save

    flash[:error] = @related.errors.full_messages.first if @related.errors

    redirect_to request.referrer 
end

Debugando:

request.referrer -> Com este método conseguimos chamar a rota que o usuário estava antes da sua atual. Em outras palavras, é como dar um “click to go back” na seta para esquerda do seu navegador

Removendo relação foto – arte

A lógica foi bem parecida com adição: colocamos um link_to para a rota de remover relação (gallery_remove_related_path) passando os atributos art.id e @image.id nesta rota.

gallery_remove_related_path

get '/user/dashboard/remove_related/:art_id/:pic_id', to: 'user/dashboard/galleries#remove_related', as: :gallery_remove_related

app > controllers > galleries_controller.rb

def remove_related
    @related = GalleryRelatedPicture.find_by(art_id: params[:art_id], picture_id: params[:pic_id], gallery_id: @gallery.id)

    @related.destroy

    redirect_back(fallback_locatin: root_path)
end

Debugando:

redirect_back(fallback_location: root_path) -> método semalhante ao request.referrer. Caso tenha alguma diferença gritante, gostaríamos de ouvi-la leitor =)

Depois poucas semanas desta feature no ar já temos mais de 1000 fotos no model Picture. A percepção dos usuário foi excelente e temos muito orgulho do impacto dela na loja de cada usuário.

https://www.reserva.ink/owm/gallery

https://www.reserva.ink/blogdocavaco/gallery

https://www.reserva.ink/inspiringgirls/gallery

Ficou alguma dúvida, crítica ou sugestão? Fala com a gente, estamos em busca de criar uma rede de Devs que programem em Rails para compartilhamos cada vez mais nossos aprendizados =)

Abração!

Galeria de Fotos com o Shrine

José Sobral — Fri, 25 Sep 2020 14:18:38 +0000

Você já tentou criar uma aplicação web que permitisse upload de fotos? Nós, da Reserva INK já e gostaríamos de partilhar sobre a experiência de como criar uma feature iradíssima em Rails =)

Feature: Galeria de fotos

1-Usuários fazem upload de suas fotos

2-Relacionam a suas camisetas

3-Exibimos uma galeria de fotos e as respectivas imagens associadas a cada foto

Toolkit: Shrine

Mãos ao código!

Como instalar o shrine do zero
Como configuramos em nossa aplicação

a) Model

Modelagem de dados
Criando os models no rails
Utilizando o shrine para guardar as imagens

b) View

Como criar o layout do form que guardará suas imagens
Relacionar fotos e camisetas

c) Controller

Criando a galeria de cada loja
CRUD de fotos
Relacionamento de fotos-camisetas

1-Como instalar o shrine do zero

A instalação do Shrine é bem tranquila e segue basicamente dois passos:

a) Gemfile

gem "shrine", "~> 3.0"

b) config > initializers > shrine.rb*

require "shrine"
require "shrine/storage/file_system"

if Rails.env.development? 
    Shrine.storages = {
        cache:  Shrine::Storage::FileSystem.new(“public”, prefix: “uploads/cache”)
        store: Shrine::Storage::FileSystem.new(“public”, prefix: “uploads”),


elsif Rails.env.Production? 
    Require ‘shrine/storage/s3’

    s3_options = {
        ***Suas credenciais do S3***
    }
    Shrine.storages = {
        cache: Shrine::Storage::S3.new(prefix: ‘cache’, **s3_options), # temporary
        store: Shrine::Storage::S3.new(prefix: ‘store, **s3options),       # permanent
}

end

Shrine.plugin :activerecord           # loads Active Record integration
Shrine.plugin :cached_attachment_data # enables retaining cached file across form redisplays
Shrine.plugin :restore_cached_data    # extracts metadata for assigned cached files

Diferenciamos o Storage para o ambiente de Desenvolvimento e para o ambiente de Produção.

Quando a feature está no ar, o armazenamento de dados ocorre através do S3.
Em desenvolvimento, o upload é realizado para um banco local.

2-Como configuramos em nossa aplicação

a) MODEL

Modelagem de dados

Para início de conversa, falemos sobre como a modelagem de dados foi feita. No ínicio, sabíamos que teriam três fluxos de dados através das entidades:

Galeria
Fotos
Relacionamento fotos-camiseta

Por isso, quando começamos o projeto pensamos em criar três Models:

Gallery
Pictures
GalleryRelatedProducts

Gallery

Estruturando o problema:

Cada seller teria sua própria galeria
Por enquanto, na nossa arquitetura atual, cada loja teria apenas uma galeria

Decisão

ID | Store_id

Com esta modelagem, cada loja teria sua própria galeria (Store_id) e, no futuro, se quisermos que cada loja tenha mais de uma galeria, não teríamos que remodelar todo nosso Model pois poderíamos ter ID’s diferentes para o mesmo Store_id.

Picture

Estruturando o problema:

Cada loja precisava possuir suas próprias fotos
A mesma loja pode ter N fotos

Decisão:

ID | Gallery_id | Image_data

Com essa modelagem, cada foto teria seu próprio ID e saberíamos qual o owner da foto através do gallery_id

GalleryRelatedProducts

Estruturando o problema:

Cada loja poderia relacionar N fotos a mesma camiseta
Cada foto poderia ser associada a N camisetas

Decisão

ID | Picture_id | Art_id

Com isso, conseguimos criar um model N-N, que permite que a mesma foto (picture_id único) se relacione com tantas camisetas quanto necessário (Art_id) e vice e versa.

Criando os models no rails

Para criar os models executamos através do cmd,

$ rails generate model Gallery store:references

$ rails generate model Picture gallery:references image_data:text

$ rails generate model PictureRelatedProduct picture:references art:references

PS1: O comando references cria automaticamente uma foreign_key com o model que veio chamado antes dos “:”

PS2: O campo image_data não foi escolhido por acaso, a documentação do shrine pede que utilizemos o nome do tipo de arquivo seguido de “data” para este atributo.
Genericamente: <name>_data

Utilizando o shrine para guardar as imagens

Neste passo você começará a sentir a potência do Shrine.

Descreveremos em 3 passos como fazer esta configuração

Primeiro passo: Criamos uma classe uploader, herdando métodos do Shrine

app > uploaders > store_picture_uploader.rb

Class StorePictureUploader < Shrine
end

Segundo passo: Na model que receberemos os dados do Upload (picture, no nosso caso), faremos uma chamada desta classe que criamos em (i)

app > models > picture.rb

class Picture < ApplicationRecord
    include StorePictureUploader::Attachment(:image) 
end

Com isso, garantimos que os dados que chegarem neste atributo (image_data) venham através do Shrine.

*PS: Usamos :image pois foi o nome do campo que criamos no model Picture (`image_data ), tirando a palavra “data”. *

Terceiro passo: Não tem passo 3, é só isso mesmo :)

b) VIEW

Arquivos utilizados:

app > views > user > dashboard > galleries > index.html.erb

app > views > user > dashboard > galleries > edit_image.html.erb

O usuário terá acesso a três interfaces:

Upload de fotos
Alterar e Deletar fotos / associar foto a um produto
Galeria que exibirá suas fotos aos customers da loja

Vamos explorar as duas primeiras interfaces

Como criar o layout do form que guardará suas imagens

Upload de fotos

app > views > user > dashboard > galleries > index.html.erb

<%= form_for :picture, url: gallery_upload_path do |f| %>
<%= f.hidden_field :image %>
<%= f.file_field :image %>
<%= f.submit “Enviar foto” %>
<% end %>

Debugando:

:picture → Model que estaremos enviando as informações do form
:image → Atributo que estaremos enviando a imagem. Lembrando que, mesmo o nome do campo sendo image_data, deixamos apenas image segunda a documentação do Shrine
gallery_upload_path → Rota de post para onde enviaremos as informações de upload

post '/user/dashboard/gallery/', to: 'user/dashboard/galleries#upload', as: :gallery_upload

Adicionando um CSS e helpers de bootstrap…

Deletar fotos

app > views > user > dashboard > galleries > edit_image.html.erb

<%= link_to gallery_delete_picture_path(@image.id) do%> Deletar Foto da Galeria <% end %>

Debugando:

@image = Picture.find(params[:pic_id])
allery_delete_picture_path → Rota para deletar uma imagem no banco. Ela pede um parâmetro que é a ID da foto

get '/user/dashboard/gallery/delete/:id', to: 'user/dashboard/galleries#delete', as: :gallery_delete_picture

Alterar fotos

app > views > user > dashboard > galleries > edit_image.html.erb

<%= form_for :picture, url: gallery_update_picture_path(@image.id) do |f| %> <%= f.hidden_field :image %> <%= f.file_field :image, onchange: ‘this.form.submit();’ %> <% end %>

Debugando:

:picture → model para onde enviaremos o form
onchange: this.form.submit(); → com isso, fazemos que o próprio botão de escolha da foto seja o mesmo de submit.
gallery_update_picture_path → Rota para atualizarmos uma imagem no banco

post '/user/dashboard/gallery/update/:pic_id', to: 'user/dashboard/galleries#update', as: :gallery_update_picture

Relacionamento de fotos-camisetas

Adicionar relação

<%= link_to gallery_insert_related_path(art.id, @image.id) %> Adicionar <% end %>

Debugando:

art - Para exibimos todas as artes do usuário no carrosel, fizemos um

<% arts.each do |art| %>

<%= link_to gallery_insert_related_path(param1, param2) %>

Adicionar

<% end %>

*PS: param1 = art.id , param2 = @image.id *

*PS2: Por isso que acessamos a variável art. Além disso, @arts = @store.arts, sendo @store a variável que instanciamos através do before_action *

Debugando

gallery_insert_related_path → Rota para chamarmos a action de criação do relacionamento

get '/user/dashboard/gallery/insert_related/:art_id/:pic_id', to: 'user/dashboard/galleries#insert_related', as: :gallery_insert_related

Remover relação

<%= link_to gallery_remove_related_path(art.id, @image.id) %> Remove <% end %>

Debugando:

gallery_remove_related_path → Rota deletarmos uma associação do model GalleryRelatedPicture

get '/user/dashboard/remove_related/:art_id/:pic_id', to: 'user/dashboard/galleries#remove_related', as: :gallery_remove_related

C) CONTROLLER

app > controllers > user > dashboard > galleries_controller.rb

Criando a galeria de cada loja

Para criarmos uma galeria para o usuário, utilizamos o método before_action do rails. Com ele, assim que o usuário acessa a página do seu respectivo controller, antes de tudo, é executada uma ação.

Nossa lógica então foi fazer o seguinte: Assim que o usuário acessar a galeria através de seu dashboard, faremos:

galleries_controller.rb

class User::Dashboard::GalleriesController > ApplicationController
before_action :load_store_and_galley

private
def load_store_and_gallery
load_gallery
load_store
end

def load_gallery
@gallery = current_user&.store&.gallery || Gallery.new(store: current_user&.store)
end

def load_store
@store = current_user&.store
end

Debugando:

current_user = método nativo do rails para sabermos qual o usuário atual que está na nossa aplicação
operador & = Com ele, a nossa aplicação não irá quebrar caso uma das chamadas seja nil

CRUD de fotos

Insert

Como mostramos na view, estamos usando um form_for, passando a rota gallery_upload_path como argumento

form_for

<%= form_for :picture, url: gallery_upload_path do |f| %>

gallery_upload_path

post '/user/dashboard/gallery/', to: 'user/dashboard/galleries#upload', as: :gallery_upload

A action upload, mencionada na rota acima ficou assim:

galleries_controller.rb

def upload
@picture = Picture.new(post_params)
@picture.gallery = @gallery
if !@picture.save
flash[:error] = @picture.errors.messages[:image]
end
end

private
def post_params
params.require(:picture).permit(:image)
end

Debugando:

@gallery → conseguimos acessar a variável de instância @gallery mesmo sem tê-la chamado neste action pois criamos ele usando o before_action. Logo, todas as actions do controller gallery terão acesso a esta variável
flash[:error] = @picture.errors.message[:image] → em @picture, estamos instanciando um novo objeto do model Picture, logo ele retornará um ActiveRecord. Com isso, conseguimos acessar alguns métodos de objeto ActiveRecord, entre eles o objeto errors.message. Mas antes de falar sobre este método, mostraremos uma das validações que fizemos neste model.

app > models > picture.rb

validate :validate_image

def validate_image

if image.blank?

Errors.add(:image, ‘Por favor, adicione uma imagem’)
return
end

end

Por isso podemos combinar if !@picture.save → caso a imagem não seja salva no banco, @picture.errors.message[:image] → chamemos o log de erro que causou o não-salvamento do atributo :image.

Update

Também mostrado na view, usamos um form_for passando a rota gallery_update_picture_path.

form_for

<%= form_for :picture, url: gallery_update_picture_path(@image.id) do |f| %>

gallery_update_picture_path

post '/user/dashboard/gallery/update/:pic_id', to: 'user/dashboard/galleries#update', as: :gallery_update_picture

galleries_controller.rb

def update
@picture = Picture.find_by(id: params[:pic_id])

if @picture.update(post_params)
    flash[:error] = @picture.errors.full_messages.first
end

end

Debugando:

@picture.update → Como @picture é um objeto ActiveRecord, conseguimos utiizar o método udpate
@picture.errors.full_messages.first → Como não estamos instanciando um objeto novo no model Picture, a validação validate_image mostrada é executada de forma diferente. A saída que achamos para conseguimos carregar o log dos erros gerados foi usar este método chamado full_messages.first.

Delete

Esse foi o mais simples. Tivemos apenas que criar um link_to para a rota de delete – gallery_delete_picture_path e executar os devidos comandos no controller

link_to

<%= link_to gallery_delete_picture_path(@image.id) do%>

gallery_delete_picture

get '/user/dashboard/gallery/delete/:id', to: 'user/dashboard/galleries#delete', as: :gallery_delete_picture

galleries_controller.rb

def delete
@gallery_picture = Picture.find_by(id: params[:id])

@gallery_picture . destroy

redirect_to user_dashboard_gallery_path

end

Debugando:

params[:id] → ID da imagem que desejamos excluir
.destroy → método para deletar um objeto ActiveRecord
redirect_to → método para redirecionamos o usuário para uma rota
user_dashboard_gallery_path →

get '/user/dashboard/gallery(/:page)', to: 'user/dashboard/galleries#index', as: :user_dashboard_gallery

Relacionamento de fotos-camisetas

# Adicionar relação foto – arte

Foi bem simples fazer. Colocamos aquele botão “adicionar” que mostramos na view e, por trás do panos do controller fizemos

galleries_controller.rb

def insert_related
@picture = Picture.find_by(id: params[:id])
@related = GalleryRelatedPicture.new(art_id: params[:art_id], picture: @picture, gallery: @gallery)

@related.save

flash[:error] = @related.errors.full_messages.first if @related.errors

redirect_to request.referrer

end

Debugando:

request.referrer → Com este método conseguimos chamar a rota que o usuário estava antes da sua atual. Em outras palavras, é como dar um “click to go back” na seta para esquerda do seu navegador

Removendo relação foto-camiseta

A lógica foi bem parecida com adição: colocamos um link_to para a rota de remover relação (gallery_remove_related_path) passando os atributos art.id e @image.id nesta rota.

gallery_remove_related_path

get '/user/dashboard/remove_related/:art_id/:pic_id', to: 'user/dashboard/galleries#remove_related', as: :gallery_remove_related

galleries_controller.rb

def remove_related
@related = GalleryRelatedPicture.find_by(art_id: params[:art_id], picture_id: params[:pic_id], gallery_id: @gallery.id)

@related.destroy

redirect_back(fallback_location: root_path)

end

Debugando:

redirect_back(fallback_location: root_path) → método semalhante ao request.referrer. Caso tenha alguma diferença gritante, gostaríamos de ouvi-la leitor =)

Depois poucas semanas desta feature no ar já temos mais de 1000 fotos no model Picture. A percepção dos usuário foi excelente e temos muito orgulho do impacto dela na loja de cada usuário. Alguns exemplos:

Owm

Blog do Cavaco

Inspiring Girls

Ficou alguma dúvida, crítica ou sugestão? Fala com a gente, estamos em busca de criar uma rede de Devs que programem em Rails para compartilhamos cada vez mais nossos aprendizados =)

Abração!