Stores
- Code: SET-STR
- Module: Settings
- Type: Master Data
1. Overview
A Store is a tenant’s operational unit: a branch, outlet, or warehouse. Each store has one or more addresses, and among them the admin sets one primary address, one billing address, and one shipping address. Stores are the working context throughout the application: users work within the active store they select, transactions such as Purchase Orders are created for that store, and employees are assigned to one or more stores.
Expected outcome: the tenant’s branch structure is recorded neatly, the correct address is used automatically on transaction documents, and stores that no longer operate can be deactivated without deleting their history.
2. Problem
Without structured store data, transactions and addresses across branches are hard to separate and easily mixed up. As a result:
- Businesses with many branches need to separate data and transactions per branch.
- The office address, billing address, and goods receiving address are often different; a wrong address causes goods to be delivered to the wrong place.
- A closed branch must no longer be used for new transactions, but its history must remain viewable.
3. Goals & Non-goals
3.1 Goals
- Each branch’s data and transactions are neatly separated, so one store’s activity does not mix with another’s.
- The correct address is used automatically on transaction documents, without having to re-enter it every time.
- Branches that stop operating can be locked from new transactions without deleting their history.
3.2 Non-goals
- Opening hours, map coordinates, and time zone per store.
- Store hierarchies such as regional or area grouping.
- Store-specific pricing and tax settings; both are managed in their related modules.
4. Business Rules
Business rules are the set of provisions and constraints that apply to Stores throughout the application, on every screen and action that involves it, whoever performs it. These rules are the single source of truth: if another part of this PRD appears to differ, the rules here prevail.
- BR-01 The store code consists of exactly 3 characters.
- BR-02 The store name is required, maximum 20 characters.
- BR-03 Every store must have at least one address from the moment it is created.
- BR-04 The primary, billing, and shipping address roles are each held by exactly one address per store. Assigning a role to another address automatically moves it from the previous address.
- BR-05 The first address created automatically holds all three roles at once.
- BR-06 An inactive store cannot be used to create or edit transactions. Its existing transaction data can still be viewed.
- BR-07 The store’s shipping address becomes the initial shipping address on a Purchase Order.
- BR-08 Every change to store data and its addresses is recorded along with its actor and time.
5. Flow
5.1 Main Flowchart
- Store Data — The admin sets the store’s status, code, and name.
- Address — The store is given at least one address. The first address automatically becomes the primary, billing, and shipping address at once; subsequent addresses hold no role until one is assigned.
- Review — All inputs are reviewed before saving.
- Validation — Inputs are checked before the store is saved. A store that violates the rules cannot be saved, and the errors are shown in the relevant section.
- Store Saved — The store can be used for transactions immediately, according to its status.
- Edit Store Data — Store data and its address list can be updated at any time, including moving address roles to another address.
5.2 Status Lifecycle
| Status | Description | Next |
|---|---|---|
Activeis_active: true | The store operates and can be used for new transactions | Inactive, or deleted |
Inactiveis_active: false | The store does not operate; its transaction data can only be viewed | Active, or deleted |
6. Document Structure
6.1 General
| Field | Type | Required | Default | Rules |
|---|---|---|---|---|
| Status | Enum | Yes | Not selected | Active or Inactive |
| Code | Text | Yes | — | Exactly 3 characters (BR-01) |
| Store Name | Text | Yes | — | Maximum 20 characters (BR-02) |
6.2 Address
| Field | Type | Required | Default | Rules |
|---|---|---|---|---|
| Name | Text | Yes | — | Address label, maximum 20 characters |
| Phone Number | Text | Yes | — | Maximum 15 characters |
| Full Address | Text | Yes | — | Maximum 255 characters |
| Primary Address | Boolean | — | Attached to the first address | Set by the system; exactly one per store (BR-04, BR-05) |
| Billing Address | Boolean | — | Attached to the first address | Set by the system; exactly one per store (BR-04, BR-05) |
| Shipping Address | Boolean | — | Attached to the first address | Set by the system; exactly one per store, used as the initial shipping address on POs (BR-04, BR-07) |
7. UI Structure
This section defines how Stores are displayed and operated: the list columns and form controls along with their option sources. This section only governs display and interaction; content and value rules still follow Document Structure.
7.1 Datatable
| Column | Sortable | Sample Value | Component |
|---|---|---|---|
| Code | Yes | CBI | Text |
| Store Name | Yes | Cianjur Store | Text |
| Address | — | Primary, Billing, Shipping Address | Accordion, only addresses with a role are shown |
| Status | — | Active | Badge |
| Actions | — | View · Edit · Delete | Action Menu |
7.2 Form & Details
Create — A three-step wizard: Store Data, Address, then Review. The Next button validates the current step before moving on. Actions: Next, Save.
Edit — Two tabs, Store Data and Address. Addresses are managed directly per row (add, edit, delete, assign role), each saved instantly.
Detail — Store name, code, and status badge at the top, followed by read-only Store Data and Address tabs. Actions: Edit Data, Delete, and Activity Logs.
Store Data
| Field | Control | Options Source | Behavior |
|---|---|---|---|
| Status | Single Select | Active or Inactive | — |
| Code | Text Input | — | Exactly 3 characters |
| Store Name | Text Input | — | Maximum 20 characters |
Address
| Field | Control | Options Source | Behavior |
|---|---|---|---|
| Name | Text Input | — | — |
| Phone Number | Text Input | — | — |
| Full Address | Textarea | — | — |
| Address Role | Action Menu (“Set as”) | Primary, Billing, Shipping | Only shows roles the address does not have yet; assigning a role removes it from other addresses |
8. User Stories
US-01 - Create a store
As an owner, I want to register a store along with its addresses, so that the store can be used for transactions.
| ID | Acceptance criteria |
|---|---|
| AC-01.1 | The wizard consists of Store Data → Address → Review; the user cannot continue if the required fields in that step are not valid yet. |
| AC-01.2 | Status must be selected; the code must be exactly 3 characters; the name is required, maximum 20 characters. |
| AC-01.3 | At least one address must be added before continuing to Review. |
| AC-01.4 | The first address is automatically marked Primary, Billing, and Shipping. |
| AC-01.5 | The delete address button is hidden if only one address remains. |
| AC-01.6 | On success, a success toast appears and the user is redirected to the store list. |
| AC-01.7 | Error messages appear in the Review step and on the related fields. |
| AC-01.8 | Duplicate store code — rejected on save; the error appears on the code field. |
US-02 - Manage store addresses
As an admin, I want to add, edit, delete, and assign roles to addresses, so that documents use the correct address.
| ID | Acceptance criteria |
|---|---|
| AC-02.1 | An address consists of a name (max 20), phone (max 15), and full address (max 255); all are required. |
| AC-02.2 | The “Set as” menu only shows roles that the address does not have yet. |
| AC-02.3 | Assigning a role to one address removes the same role from other addresses. |
| AC-02.4 | In edit mode, every address action is saved immediately, with a spinner on the address being updated. |
| AC-02.5 | The add, edit, and delete address buttons follow the create, update, and delete permissions. |
| AC-02.6 | Each address shows its role badges (Primary / Billing / Shipping). |
| AC-02.7 | Deleting the last address in edit mode — not prevented while filling in, unlike the create wizard; it must be rejected on save so that BR-03 holds. |
| AC-02.8 | Deleting an address that holds the primary, billing, or shipping role — not prevented while filling in. Needs confirmation: whether it is rejected or its roles are moved (BR-04). |
| AC-02.9 | The store has an address without a role — the address is still saved but does not appear in the Address column of the list (only addresses with a role are shown). |
US-03 - Edit store data
As an owner, I want to change the store’s status, code, or name, so that the data stays accurate.
| ID | Acceptance criteria |
|---|---|
| AC-03.1 | The Edit Data button only appears for users with the update permission. |
| AC-03.2 | Validation is the same as on creation (AC-01.2); the save button is only enabled when there are changes. |
| AC-03.3 | The open tab is kept in the URL (section-tab). |
| AC-03.4 | The store is deactivated while a user is using it as their active store — transaction pages become read-only after the store data is reloaded. |
US-04 - Store list
As an owner, I want to see all stores, so that they are easy to check and manage.
| ID | Acceptance criteria |
|---|---|
| AC-04.1 | Columns: code, store name, address (list of addresses with a role, expandable), and status. |
| AC-04.2 | Keyword search, pagination, default sort by name A–Z. |
| AC-04.3 | Row actions: View, Edit, Delete according to permissions; bulk delete from selected rows. |
| AC-04.4 | The user is not assigned to any store — transaction modules show the no store assigned page. |
US-05 - Delete a store
As an owner, I want to delete a store created by mistake, so that the list stays clean.
| ID | Acceptance criteria |
|---|---|
| AC-05.1 | Single and bulk delete require confirmation and the delete permission. |
| AC-05.2 | If the deletion is rejected, the error message appears as a toast. |
| AC-05.3 | Deleting a store that already has employees or transactions — Needs confirmation: whether it is allowed; if rejected, the error message appears as a toast. |
US-06 - Activity history
As an owner, I want to see the store activity log, so that changes can be traced.
| ID | Acceptance criteria |
|---|---|
| AC-06.1 | The log is available for all stores (in the list) and per store (in the detail), with event, actor, and date range filters. |
9. User Scenarios
| Role | Scenario |
|---|---|
| Owner | Opens a new branch; registers the store with an office address as well as a goods receiving address |
| Admin | Adds a new warehouse address and makes it the shipping address |
| Owner | Deactivates a closed branch so it is not used for new POs |
| Admin | Searches for a store by name to check its billing address |
10. Permissions & Actions
10.1 Permission by Action
| Action | Permission | Condition |
|---|---|---|
| View Store List | settings:store:list:any | — |
| View Activity Logs | settings:store:list:any | — |
| View Store Detail | settings:store:view:store | Only assigned stores |
| Create Store | settings:store:create:any | — |
| Edit Store (General Data) | settings:store:update:any | — |
| Delete Store | settings:store:delete:any | — |
| Add Address | settings:store:create:any | — |
| Edit Address | settings:store:update:any | — |
| Delete Address | settings:store:delete:any | — |
| Assign Address Role | settings:store:update:any | — |
10.2 Action by Status
| Action | Active | Inactive |
|---|---|---|
| View Store Detail | ✓ | ✓ |
| Edit Store (General Data) | ✓ | ✓ |
| Delete Store | ✓ | ✓ |
| Edit Address | ✓ | ✓ |
| Selected as Active Store | ✓ | ✓ |
| Create Transaction (PO, GR, Bill) | ✓ | — |
| Edit Transaction (PO, GR, Bill) | ✓ | — |
11. Notifications
This feature does not trigger any notifications.
12. Dependencies
Related PRDs
- Employees — employees are assigned to stores.
- Purchase Order, Goods Receipt, Bill — transactions are created per store and use the store’s addresses.
- Activity Logs — the source of the activity log.
Effects on other modules
- The store switcher in the layout determines the active store (stored in a cookie) for all transaction modules.
- The inactive status locks edit actions in all transaction modules (BR-06).