Requirements

In this section, we'll define User Stories and Acceptance Criteria for our requirements. You're encouraged to keep these handy as you work through the coming exercises, to remain clear on the purpose served by specific customizations.

A golden rule for User Stories and Acceptance Criteria is that they be written from the standpoint of a software user, describing only what a feature must do and not how it must do it. We have a strange scenario here, in that we're defining requirements specifically for a GraphQL implementation, something that is not part of describing the software user's experience at all! In an ideal scenario, the Acceptance Criteria would only describe how various users need to be able to interact with a feature, and the technical details (from the DB structure to the GraphQL coverage) would only be part of the dev team's design spec.

Since we want to focus only on the GraphQL implementation, the user type in our AC is going to be a "theme implementor". It is for this user - the developer that must consume the GraphQL service to build a front-end application - that we'll tailor our requirements.

User Stories

As a theme implementor, I want a GraphQL query for details on Group Shipping Policies for all customer groups, so that I can display policy info on a dedicated Shipping Policies page.

As a theme implementor, I want a GraphQL query for details on the Group Shipping Policy applicable to a specific customer, so that I can display relevant policy info in the customer's checkout experience without fetching unnecessary data or tracking the user's customer group in the front-end.

As a theme implementor, I want a GraphQL mutation for creating a Shipping Policy Callback record, so that I can create an interface allowing users to register their phone number for a callback.

Acceptance Criteria

1. Magento defines a GraphQL query for fetching Group Shipping Policy details (Shipping Policy Query).
   1. The Shipping Policy Query accepts a boolean argument indicating whether all policies should be returned ("all").
   2. The Shipping Policy Query can accept a fields selection including the following data for each policy:
      1. The policy title
      2. The policy text/description
      3. The associated customer group ID
      4. A list of assigned countries
   3. The country name field of the Shipping Policy Query accepts an argument indicating whether the full country name or ISO code is desired.
2. When a Shipping Policy Query is received by the Magento GraphQL endpoint, details are returned matching the query.
   1. Given that the "all" argument is TRUE, details are returned for all policies.
   2. Given that the "all" argument is FALSE:
      1. Given that no customer authorization token is sent, details are returned for the policy associated with the "Not Logged In" customer group.
      2. Given that a customer authorization token is sent and a valid customer authorized, details are returned for the policy associated with the customer's customer group.
3. Magento defines a GraphQL mutation for registering a Shipping Policy Callback (Policy Callback Mutation).
   1. The Policy Callback Mutation accepts an argument for a phone number.
   2. The Policy Callback Mutation can accept a fields selection including the following data for the resulting Callback record:
      1. The associated policy title
      2. The registered phone number
      3. The creation date/time
4. When a Policy Callback Mutation is received by the Magento GraphQL endpoint, a Shipping Policy Callback record is created with the provided details.
   1. Given that no customer authorization token is sent, the policy associated with the "Not Logged In" customer group is assigned to the Callback record.
   2. Given that a customer authorization token is sent and a valid customer authorized, the policy associated with the customer's customer group is assigned to the Callback record.
5. Given that a customer authorization token is sent for the Shipping Policy Query or Policy Callback Mutation, but the token is not valid, an authorization error will be returned.
6. Given that no policy is associated with the appropriate customer group for a Shipping Policy Query or Policy Callback Mutation, a "not found" error will be returned.

Technical Blueprint

A "Technical Blueprint" refers to specifications about the architecture for a feature, such as a senior engineer or solutions architect might provide to a dev team to supplement the Acceptance Criteria. As we alluded to above, our Acceptance Criteria for this scenario already resemble such a specification more than would be usual for AC, given our target "theme implementor" user type.

We won't belabor the main technical details any further, but there is one aspect of our architecture we should consider that isn't specifically part of our criteria, and that's caching. For the best possible performance from our Magento backend, our architecture should account for proper caching, so we would probably include these items in our spec:

• The results of a Shipping Policy GraphQL query should be cached via the Magento Full Page Cache.
• When the details of a Group Shipping Policy record change, any cached GraphQL query result involving that policy should be invalidated.