first commit with some docs

.idea/.gitignore

@@ -0,0 +1,10 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Ignored default folder with query files
+/queries/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

developer_doc/pre_design/Robot Market - User Flow.md

@@ -0,0 +1,219 @@
+# Robot Market - User Flow
+
+Source: `Robot Market — Product Requirements Document (1).md`
+
+This document describes the main user flows for Robot Market using Mermaid diagrams. The flows focus on the MVP/current scope and mark payment and wallet behavior as later-phase items.
+
+---
+
+## 1. Role Access Overview
+
+```mermaid
+flowchart TD
+    Visitor[Visitor]
+    Customer[Customer]
+    Admin[Admin]
+    Owner[Owner]
+
+    Visitor --> PublicCatalog[Browse product listing]
+    Visitor --> ProductDetails[View product details, images, specs, prices]
+    Visitor --> PublicPages[View public informational pages]
+    Visitor --> PurchaseIntent{Wants to add to cart or order?}
+    PurchaseIntent --> AuthRequired[Register / login with mobile OTP]
+    AuthRequired --> Customer
+
+    Customer --> CustomerCart[Maintain persistent cart]
+    Customer --> ConfigureProduct[Configure product modules]
+    Customer --> SubmitOrder[Submit order]
+    Customer --> CustomerDashboard[View dashboard, active orders, history]
+    Customer --> CancelBeforeApproval[Cancel eligible orders before admin approval]
+    Customer --> ReviewInvoice[Review final invoice / order]
+
+    Admin --> CatalogManagement[Manage products, specs, images, modules, prices]
+    Admin --> CustomerManagement[Find or register customers]
+    Admin --> AssistedOrdering[Create orders for customers]
+    Admin --> ReviewOrders[Review, modify, approve, decline orders]
+    Admin --> InternalNotes[Add internal notes]
+
+    Owner --> AdminManagement[Add or remove admins]
+    Owner --> Admin
+```
+
+---
+
+## 2. Customer Self-Service Ordering Flow
+
+```mermaid
+flowchart TD
+    Start([Visitor opens Robot Market])
+    Browse[Browse products]
+    Details[View vending machine details]
+    Select[Select vending machine]
+    WantsCart{Add to cart / start order?}
+    Auth{Authenticated?}
+    OTP[Register or login using mobile OTP]
+    AddToCart[Add product to persistent cart]
+    Configure[Select compatible available modules]
+    Price[Show calculated product + module price]
+    Info{Required order info complete?}
+    CompleteInfo[Enter or update customer and delivery info]
+    Submit[Submit order]
+    Submitted[Order status: Submitted]
+    AdminReview[Admin review begins]
+    UnderReview[Order status: Under Review]
+    AdminDecision{Admin decision}
+    RequestInfo[Request additional customer information]
+    Modify[Admin modifies modules, configuration, price, or details]
+    Decline[Order status: Declined]
+    Approve[Order status: Approved]
+    AwaitingPayment[Order status: Awaiting Payment]
+    FinalReview[Customer reviews final invoice / order]
+    Accept{Customer accepts final order?}
+    PaymentLater[Payment gateway / wallet later phase]
+    Cancel[Customer cancels before approval]
+    Cancelled[Order status: Cancelled]
+    End([Flow ends])
+
+    Start --> Browse --> Details --> Select --> WantsCart
+    WantsCart -- No --> Browse
+    WantsCart -- Yes --> Auth
+    Auth -- No --> OTP --> AddToCart
+    Auth -- Yes --> AddToCart
+    AddToCart --> Configure --> Price --> Info
+    Info -- No --> CompleteInfo --> Info
+    Info -- Yes --> Submit --> Submitted --> AdminReview --> UnderReview --> AdminDecision
+
+    Submitted -. Customer may cancel before approval .-> Cancel --> Cancelled --> End
+    UnderReview -. Customer self-editing becomes admin-controlled .-> AdminDecision
+
+    AdminDecision -- Request info --> RequestInfo --> CompleteInfo
+    AdminDecision -- Modify --> Modify --> AdminDecision
+    AdminDecision -- Decline --> Decline --> End
+    AdminDecision -- Approve --> Approve --> AwaitingPayment --> FinalReview --> Accept
+    Accept -- Yes --> PaymentLater --> End
+    Accept -- No --> End
+```
+
+---
+
+## 3. Admin-Assisted Customer Registration and Ordering Flow
+
+```mermaid
+flowchart TD
+    Start([Admin opens admin panel])
+    Auth[Admin authenticates]
+    FindCustomer[Search for existing customer]
+    CustomerFound{Customer exists?}
+    RegisterCustomer[Register customer with first name, last name, mobile number]
+    AuditAccount[Record admin-created account audit event]
+    SelectCustomer[Select customer account]
+    CreateOrder[Create order on behalf of customer]
+    SelectProduct[Select vending machine]
+    ConfigureModules[Configure modules]
+    EnterInfo[Enter required customer and delivery information]
+    ReviewDraft[Review draft order]
+    NeedChanges{Changes needed?}
+    ModifyOrder[Modify configuration, modules, price, or details]
+    Approve[Approve order]
+    AuditOrder[Record admin-created / admin-approved order audit events]
+    CustomerReview[Customer reviews final invoice / order]
+    CustomerAccept{Customer accepts final order?}
+    PaymentLater[Payment gateway / wallet later phase]
+    End([Flow ends])
+
+    Start --> Auth --> FindCustomer --> CustomerFound
+    CustomerFound -- No --> RegisterCustomer --> AuditAccount --> SelectCustomer
+    CustomerFound -- Yes --> SelectCustomer
+    SelectCustomer --> CreateOrder --> SelectProduct --> ConfigureModules --> EnterInfo --> ReviewDraft --> NeedChanges
+    NeedChanges -- Yes --> ModifyOrder --> ReviewDraft
+    NeedChanges -- No --> Approve --> AuditOrder --> CustomerReview --> CustomerAccept
+    CustomerAccept -- Yes --> PaymentLater --> End
+    CustomerAccept -- No --> End
+```
+
+---
+
+## 4. Order Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: Cart / order being prepared
+    Draft --> Submitted: Customer submits order
+    Draft --> Submitted: Admin creates order for customer
+    Draft --> Cancelled: Customer cancels before submission
+
+    Submitted --> Cancelled: Customer cancels before admin approval
+    Submitted --> UnderReview: Admin starts review
+
+    UnderReview --> UnderReview: Admin modifies details, modules, or price
+    UnderReview --> Submitted: Admin requests more information
+    UnderReview --> Declined: Admin declines order
+    UnderReview --> Approved: Admin approves order
+
+    Approved --> AwaitingPayment: Final invoice is available
+    AwaitingPayment --> Paid: Payment succeeds in later phase
+    AwaitingPayment --> Cancelled: Administrative cancellation only
+
+    Declined --> [*]
+    Cancelled --> [*]
+    Paid --> [*]
+```
+
+---
+
+## 5. Admin Catalog and Pricing Management Flow
+
+```mermaid
+flowchart TD
+    Start([Admin opens admin panel])
+    Auth[Admin authenticates]
+    ChooseArea{Management area}
+
+    ProductCRUD[Create / edit / deactivate products]
+    Specs[Manage product specifications]
+    Images[Manage product images]
+    BasePrice[Manage base price]
+    Visibility[Set product active / inactive visibility]
+
+    ModuleCRUD[Create / edit / deactivate modules]
+    ModulePrice[Manage module prices]
+    ModuleAvailability[Manage module availability]
+    Compatibility[Maintain future-ready compatibility data]
+
+    Relationship[Associate modules with products]
+    PublicCatalog[Public catalog reflects active products and available modules]
+    Audit[Record important admin changes for auditability]
+    End([Flow ends])
+
+    Start --> Auth --> ChooseArea
+
+    ChooseArea -- Products --> ProductCRUD --> Specs --> Images --> BasePrice --> Visibility --> Relationship
+    ChooseArea -- Modules --> ModuleCRUD --> ModulePrice --> ModuleAvailability --> Compatibility --> Relationship
+
+    Relationship --> Audit --> PublicCatalog --> End
+```
+
+---
+
+## 6. Final Invoice Acceptance Rule
+
+```mermaid
+flowchart TD
+    AdminReview[Admin reviews submitted or assisted order]
+    Changes{Admin changes order?}
+    NoChange[Keep customer-selected configuration and calculated price]
+    Changed[Modify configuration, modules, price, or details]
+    Approved[Approve final order]
+    Invoice[Customer sees final invoice / order]
+    PaymentIntent{Customer proceeds to payment?}
+    Accepted[Final configuration and price accepted]
+    NotAccepted[No payment acceptance recorded]
+
+    AdminReview --> Changes
+    Changes -- No --> NoChange --> Approved
+    Changes -- Yes --> Changed --> Approved
+    Approved --> Invoice --> PaymentIntent
+    PaymentIntent -- Yes --> Accepted
+    PaymentIntent -- No --> NotAccepted
+```
+

developer_doc/pre_design/Robot Market — Product Requirements Document (1).md

@@ -0,0 +1,762 @@
+# Robot Market — Product Requirements Document
+
+## 1. Product Overview
+
+Robot Market is an e-commerce platform focused on selling vending machines.
+
+Visitors can browse available vending machines, review product specifications and pricing, and access public informational pages without authentication.
+
+When a customer wants to add a product to the cart or begin the ordering process, they must authenticate or register using mobile OTP.
+
+Because some customers may not have sufficient computer knowledge to use the website themselves, administrators must also be able to register customers and create orders on their behalf.
+
+Vending machines can be configured with optional modules. Modules affect the final price and may have compatibility restrictions in the future.
+
+Orders are reviewed by administrators before payment.
+
+---
+
+# 2. Product Goal
+
+The goal is to provide a structured online sales process for vending machines while also supporting customers who cannot independently use the online system.
+
+The platform should allow customers to:
+
+- browse vending machines
+- inspect specifications and prices
+- configure machines using available modules
+- maintain a persistent cart
+- submit orders
+- track their orders
+- review the final invoice/order before payment
+- eventually pay approved orders through the payment gateway or wallet
+
+The platform should allow administrators to:
+
+- manage the product catalog
+- manage modules and pricing
+- register customers
+- create orders on behalf of customers
+- review submitted orders
+- modify customer orders where necessary
+- approve or decline orders
+
+---
+
+# 3. Target Users
+
+Robot Market targets any individual or organization interested in purchasing vending machines.
+
+This includes customers with different levels of technical knowledge.
+
+The system must therefore support both:
+
+1. customer self-service purchasing
+2. admin-assisted customer registration and ordering
+
+---
+
+# 4. User Roles
+
+## Visitor
+
+An unauthenticated visitor can:
+
+- browse products
+- view vending-machine specifications
+- view public pricing
+- access public pages such as About Us
+
+A visitor cannot enter the purchasing process without authentication.
+
+---
+
+## Customer
+
+An authenticated customer can:
+
+- maintain a persistent cart
+- configure vending machines
+- select modules
+- submit orders
+- provide required order information
+- view active and previous orders
+- view order status
+- cancel eligible orders
+- review the final order/invoice
+- eventually pay approved orders
+- eventually access wallet functionality
+
+---
+
+## Admin
+
+An Admin can:
+
+- register a new customer
+- create an order on behalf of a registered customer
+- create products
+- edit products
+- delete/deactivate products
+- manage product specifications
+- manage product images
+- manage modules
+- associate modules with products
+- manage prices
+- review orders
+- modify customer carts/orders
+- modify selected modules
+- modify final prices
+- approve orders
+- decline orders
+- request additional customer information
+- add internal administrative notes
+
+Admin-assisted registration and ordering are first-class product requirements, not workarounds.
+
+---
+
+## Owner
+
+Owner is a higher-privilege internal role.
+
+Currently confirmed additional capability:
+
+- add admins
+- remove admins
+
+Additional differences between Owner and Admin may be introduced later.
+
+---
+
+# 5. Public Website
+
+Unauthenticated visitors can access:
+
+- product listing
+- product details
+- product specifications
+- product images
+- displayed prices
+- About Us
+- other public informational pages
+
+Authentication is not required for browsing.
+
+---
+
+# 6. Authentication and Registration
+
+Customer authentication currently uses:
+
+**Mobile Number + OTP**
+
+Password-based customer login is not required at this stage.
+
+Initial customer registration information includes:
+
+- first name
+- last name
+- mobile number
+
+Authentication becomes required when a customer enters the purchasing process, including adding a product to their persistent cart.
+
+### Admin-Assisted Registration
+
+Administrators must also be able to register customers.
+
+This is intended primarily for customers who cannot comfortably use the online registration process themselves.
+
+The resulting account is a normal customer account and should not become a separate customer type.
+
+The system should record that the account was created through an administrative action for audit purposes.
+
+---
+
+# 7. User Profile
+
+Each customer has one account with associated profile information.
+
+Multiple profiles and multiple saved addresses are not required.
+
+Basic identity information:
+
+- first name
+- last name
+- mobile number
+
+Additional information may include:
+
+- email
+- city
+- address
+- postal code
+- business information
+- banking/POS-related information when required
+
+Whether this data is technically represented through one Profile entity or multiple profile-related entities will be decided during Domain Modeling.
+
+---
+
+# 8. Product Catalog
+
+The primary product type is a vending machine.
+
+Products should support:
+
+- name
+- description
+- images
+- specifications
+- base price
+- available modules
+- availability information
+- active/inactive visibility
+
+Product management through the Admin Panel is required from the first internal release.
+
+Direct database editing must not be necessary for normal product management.
+
+---
+
+# 9. Product Modules
+
+Vending machines can have configurable modules.
+
+A module may contain:
+
+- name
+- description
+- price
+- availability
+- active/inactive state
+- compatibility information
+
+Module selection affects the final vending-machine price.
+
+Initially, module management can remain relatively simple.
+
+However, the domain must allow future compatibility restrictions because some modules may eventually be incompatible with:
+
+- particular vending-machine models
+- other modules
+
+Complex compatibility rules do not need to be implemented prematurely.
+
+---
+
+# 10. Pricing
+
+Product and module prices are managed manually by administrators.
+
+Prices may be changed because of changes in the USD/local-currency exchange rate, but exchange rates are not automatically fetched.
+
+Admins manually manage pricing.
+
+An administrator may also modify the price of a customer's cart/order during review.
+
+The customer does not need to separately approve every administrative price or configuration modification.
+
+Instead, the customer's final acceptance occurs when they review and accept the final invoice/order and proceed to payment.
+
+---
+
+# 11. Shopping Cart
+
+Authenticated customers have a persistent shopping cart.
+
+For the initial implementation:
+
+- one active cart per customer
+- cart survives logout/session expiration
+- products can be added and removed
+- modules can be configured
+- cart eventually becomes an order
+
+Admins must also be able to modify a customer's cart/order when necessary.
+
+### Admin Modification
+
+If an Admin changes:
+
+- modules
+- configuration
+- price
+- other order details
+
+the customer does not need to approve every individual modification.
+
+The final configuration and price must be visible before payment.
+
+By approving the final invoice/order and proceeding to payment, the customer accepts the final configuration and price.
+
+---
+
+# 12. Ordering Flow
+
+## Customer Self-Service Flow
+
+Visitor  
+→ Browse Products  
+→ Select Vending Machine  
+→ Register/Login using OTP  
+→ Add to Cart  
+→ Configure Modules  
+→ Complete Required Information  
+→ Submit Order  
+→ Admin Review  
+→ Admin Modification if Necessary  
+→ Admin Approval  
+→ Customer Reviews Final Invoice/Order  
+→ Payment in Later Phase
+
+## Admin-Assisted Flow
+
+Admin  
+→ Find Existing Customer / Register New Customer  
+→ Create Order for Customer  
+→ Select Product  
+→ Configure Modules  
+→ Enter Required Order Information  
+→ Review/Modify Order  
+→ Approve Order  
+→ Customer Reviews Final Invoice/Order  
+→ Payment in Later Phase
+
+Both flows should ultimately produce the same underlying customer and order concepts.
+
+---
+
+# 13. Order Information
+
+Before an order can be completed, sufficient customer and delivery information must exist.
+
+Expected information includes:
+
+- first name
+- last name
+- mobile number
+- email
+- city
+- address
+- postal code
+- selected vending machine
+- selected modules
+- calculated/final price
+
+The information may be entered by either:
+
+- the customer
+- an authorized Admin acting on behalf of the customer
+
+---
+
+# 14. Administrative Order Review
+
+Orders do not immediately proceed to payment.
+
+Admins review submitted orders first.
+
+Admins should be able to inspect:
+
+- customer information
+- product
+- configuration
+- selected modules
+- price
+- delivery information
+- relevant customer information
+
+Admin actions include:
+
+- approve
+- decline
+- modify price
+- modify modules/configuration
+- request additional information
+- add internal notes
+
+Administrative changes do not require individual customer confirmation.
+
+Final customer acceptance occurs before payment.
+
+---
+
+# 15. Order Edit Rules
+
+Before administrative review/action begins, customers may edit their own order/configuration.
+
+After administrative handling begins, changes become controlled by the administrative workflow.
+
+Admins may modify the configuration and price where required.
+
+The customer is shown the final order/invoice before payment.
+
+Proceeding with payment constitutes acceptance of the final order.
+
+---
+
+# 16. Order Lifecycle
+
+The initial conceptual lifecycle is intentionally simple.
+
+Possible business states include:
+
+- Draft
+- Submitted
+- Under Review
+- Approved
+- Awaiting Payment
+- Paid
+- Declined
+- Cancelled
+
+Payment status should eventually be modeled separately from order status.
+
+The exact state machine will be finalized during Domain Modeling.
+
+---
+
+# 17. Cancellation
+
+Customers may cancel an order before Admin approval.
+
+After Admin approval, cancellation is no longer automatically available as a customer self-service action.
+
+Any later cancellation can be handled administratively.
+
+---
+
+# 18. Production / Fulfillment Status
+
+There is currently **no requirement for a production-process state machine**.
+
+Therefore states such as:
+
+- manufacturing
+- preparing
+- ready
+- shipping
+- delivered
+
+should not be designed into the MVP unless later requested.
+
+Once an order has been paid, the system only needs to represent the required order/payment state for the current business process.
+
+Production tracking can be introduced later.
+
+---
+
+# 19. Customer Dashboard
+
+Authenticated customers should have a dashboard containing the currently relevant information, including:
+
+- profile
+- active orders
+- order history
+- order details
+- configurations
+- final pricing
+- payment information when payment is introduced
+
+Ticketing is not part of the current product scope.
+
+---
+
+# 20. Ticketing
+
+A ticket/support system is **not currently required**.
+
+Ticket entities, ticket APIs, ticket UI, ticket attachments, ticket states, and admin ticket management should not be implemented in the current phases.
+
+A support system can be introduced later if a concrete requirement emerges.
+
+---
+
+# 21. Admin Panel
+
+The Admin Panel is a core part of Robot Market.
+
+## First Internal Release
+
+The first useful internal release should support:
+
+- Admin authentication
+- product CRUD
+- product specifications
+- product images
+- module CRUD
+- product/module relationships
+- pricing management
+
+This allows Admins to populate and maintain the public catalog.
+
+## Customer Management
+
+The Admin Panel must also progressively support:
+
+- customer registration
+- finding registered customers
+- creating an order for a customer
+
+## Order Management
+
+Subsequent functionality includes:
+
+- order list
+- order details
+- customer information
+- order creation
+- order modification
+- module/configuration modification
+- price modification
+- approval
+- decline
+- internal notes
+
+---
+
+# 22. Payment — Later Phase
+
+Online payment is planned for a later implementation phase.
+
+Planned payment methods:
+
+- online payment gateway
+- wallet
+
+Bank transfer may be introduced later.
+
+Payment will have its own lifecycle/state model to correctly handle:
+
+- initiated payments
+- pending payments
+- successful payments
+- failed payments
+- retries
+- cancelled/expired attempts
+
+The exact payment model will be designed during the payment phase.
+
+---
+
+# 23. Wallet — Later Phase
+
+Wallet functionality is planned for a later phase.
+
+The wallet domain should eventually support a proper transaction history rather than only storing a mutable balance.
+
+Initially planned scenarios:
+
+- receive balance from the Saffron platform
+- spend balance on Robot Market orders
+- view transaction history
+
+The initial external transfer direction is:
+
+**Saffron Platform → Robot Market**
+
+Direct wallet top-up, withdrawal, and other advanced operations are not currently required.
+
+---
+
+# 24. Saffron Platform Integration — Later Phase
+
+A separate Saffron commerce platform will eventually integrate with Robot Market.
+
+Users should eventually be able to transfer available value from the Saffron platform into their Robot Market wallet and use it toward vending-machine purchases.
+
+This should influence the future Wallet Domain design but should not complicate the current MVP.
+
+---
+
+# 25. Non-Functional Requirements
+
+The system must provide:
+
+### Persian / RTL
+
+The primary customer interface should support Persian and RTL layout.
+
+### Responsive Design
+
+Support:
+
+- desktop
+- tablet
+- mobile
+
+### SEO
+
+Public product and informational pages should support basic SEO.
+
+Next.js server/static rendering should be used where appropriate.
+
+### Security
+
+At minimum:
+
+- authentication
+- server-side authorization
+- role-based permissions
+- protected Admin APIs/routes
+- secure OTP implementation
+- OTP rate limiting
+- server-side validation
+- secure file uploads
+- secure payment callback handling when payments are implemented
+
+### Auditability
+
+Important Admin operations should be traceable, especially:
+
+- Admin-created customer accounts
+- Admin-created customer orders
+- price changes
+- configuration changes
+- order approval
+- order decline
+- administrative user changes
+
+### Performance
+
+The architecture should provide reasonable performance for normal e-commerce usage without premature high-scale infrastructure.
+
+The system should remain practical for a two-developer team.
+
+---
+
+# 26. MVP Definition
+
+The first complete customer-facing MVP succeeds when:
+
+> A visitor can browse vending machines, register/login using OTP, configure a vending machine, submit an order, and an Admin can review, modify, approve, or decline that order.
+
+Additionally:
+
+> An Admin can register a customer and create the same type of order on that customer's behalf.
+
+The final invoice/order shown before payment represents the customer's final opportunity to review administrative modifications.
+
+---
+
+# 27. Practical Implementation Phases
+
+### Phase 1 — Catalog Foundation
+
+- Admin authentication
+- product CRUD
+- module CRUD
+- product/module relationships
+- pricing
+- public product catalog
+- product details
+
+### Phase 2 — Customer Authentication
+
+- OTP registration
+- OTP login
+- customer profile
+- Admin-assisted customer registration
+
+### Phase 3 — Cart & Orders
+
+- persistent cart
+- module configuration
+- order submission
+- Admin-created customer orders
+- Admin order review
+- Admin modifications
+- approve/decline
+- customer order dashboard
+
+### Phase 4 — Payment
+
+- final invoice/order review
+- payment gateway
+- payment states
+- payment history
+
+### Phase 5 — Wallet & External Balance
+
+- wallet
+- transaction ledger/history
+- wallet payment
+- Saffron → Robot Market balance transfer
+
+---
+
+# 28. Out of Scope / Later
+
+Currently deferred:
+
+- ticketing
+- articles/CMS
+- production/manufacturing workflow states
+- automated currency APIs
+- bank transfer payments
+- wallet implementation in early phases
+- Saffron integration in early phases
+- multiple customer profiles
+- multiple saved addresses
+- advanced inventory until requirements are finalized
+- complex module compatibility rules until required
+- advanced notification system
+- complex CMS
+
+---
+
+# 29. Remaining Product Decisions
+
+Some requirements still require later clarification.
+
+### Inventory
+
+Should products maintain actual stock quantities or only availability states?
+
+### Articles / CMS
+
+What content-management capabilities will eventually be required?
+
+### Owner Permissions
+
+What capabilities beyond Admin management should Owner have?
+
+### Order Composition
+
+Can one order contain multiple separately configured vending machines?
+
+### Notifications
+
+Which events require SMS, email, or in-app notification?
+
+### Customer Management
+
+Beyond Admin-assisted registration/order creation, what customer information can Admins view or modify?
+
+### Formal Documents
+
+Will the system require downloadable:
+
+- proforma invoices
+- invoices
+- payment receipts?
+
+---
+
+# 30. Deferred Technical Decisions
+
+These belong in later technical design rather than the PRD:
+
+- User/Profile entity split
+- database schema
+- API structure
+- exact order state machine
+- module compatibility implementation
+- cart vs order persistence model
+- Admin-on-behalf-of-customer authorization/audit implementation
+- payment architecture
+- wallet ledger architecture
+- Next.js architecture
+- Go backend structure
+- notification architecture