Feature: Basic Location Management

As a Business Owner,
I want to define and manage my business’s location,
So that my business can be found easily by my customers and can better serve them.

# NOTE: See the “Location Management” screen mockup images attached below
# NOTE: See the “StreetAddress Entity-Relationship Diagram (ERD)” diagram attached below

Background:
Given I am currently logged in to the system, i.e. my browser has received a currently valid authentication token
And my business is represented by a record in the Organization database table
And I am currently on the "Manage Location" page for my business, conforming to the “Location Management” screen mockup image and specifications
 
Scenario: Successful Location Management
Given there are no records that represent my business location in the StreetAddress database table
When I submit (create/HTTP POST or update/HTTP PATCH) all required, valid StreetAddress data (e.g. StreetAddress1, StreetAddress2, CityName, StateId, CountryId, and PostalCode) to the system’s RESTful endpoint ‘example.com/api/v1/location'
Then this data is stored, along with system-generated and default data in a new or updated record in the StreetAddress database table, referencing my business record in the Organization database table
And a ‘201 Created’ or '200 Success' HTTP response is returned
And the new or updated StreetAddress entity data is returned in valid JSON format
And the new or updated StreetAddress data is displayed on the "Manage Location" page for my business, conforming to the “Location Management” screen mockup image and specifications
And this interaction is logged using the system’s existing structured logging features (available on stdout and stderr streams)

Scenario: Unsuccessful Location Management Due to Invalid or Incomplete Data
Given there are no records that represent my business location in the StreetAddress database table
When I fail to submit (create/HTTP POST or update/HTTP PATCH) all required, valid StreetAddress data (e.g. StreetAddress1, StreetAddress2, CityName, StateId, CountryId, and PostalCode) to the system’s RESTful endpoint ‘example.com/api/v1/location'
Then the resulting exceptions are handled using the system’s existing exception handling features
And no database records are created or updated in the StreetAddress database table
And a ‘400 Bad Request’ HTTP response is returned
And no StreetAddress entity data is returned
And an "Invalid or Incomplete Data" error message is displayed on the "Manage Location" page for my business, conforming to the “Location Management” screen mockup image and specifications
And this interaction is logged using the system’s existing structured logging features (available on stdout and stderr streams)

Scenario: Unsuccessful Location Management Due to Internal Service Error
Given there are no records that represent my business location in the StreetAddress database table
When I submit (create/HTTP POST or update/HTTP PATCH) all required, valid StreetAddress data (e.g. StreetAddress1, StreetAddress2, CityName, StateId, CountryId, and PostalCode) to the system’s RESTful endpoint ‘example.com/api/v1/location'
Then one or more unrecoverable exceptions occur in the StreetAddress service
And the resulting exceptions are handled using the system’s existing exception handling features
And no database records are created in the StreetAddress database table
And a ‘500 Internal Server Error’ HTTP response is returned
And no StreetAddress entity data is returned
And a "Temporary Service Error" error message is displayed on the "Manage Location" page for my business, conforming to the “Location Management” screen mockup image and specifications
And this interaction is logged using the system’s existing structured logging features (available on stdout and stderr streams)

Scenario: Unsuccessful Location Management Due to Unavailable Service
Given there are no records that represent my business location in the StreetAddress database table
When I submit (create/HTTP POST or update/HTTP PATCH) all required, valid StreetAddress data (e.g. StreetAddress1, StreetAddress2, CityName, StateId, CountryId, and PostalCode) to the system’s RESTful endpoint ‘example.com/api/v1/location'
Then the StreetAddress service timeout is exceeded
And the resulting exceptions are handled using the system’s existing exception handling features
And no database records are created in the StreetAddress database table
And a ‘503 Service Unavailable’ HTTP response is returned
And no StreetAddress entity data is returned
And a "Service Timed Out" error message is displayed on the "Manage Location" page for my business, conforming to the “Location Management” screen mockup image and specifications
And this interaction is logged using the system’s existing structured logging features (available on stdout and stderr streams)