91 lines
5.2 KiB
Markdown
91 lines
5.2 KiB
Markdown
# XShop – Product Specification (v1.0.0)
|
||
|
||
> Persian-first commercial WooCommerce theme. Original implementation, inspired by UX quality of modern Persian e-commerce themes such as BantaShop. Zero copying of source, assets, or branding from references.
|
||
|
||
## 1. Vision
|
||
|
||
XShop is a premium, performant, RTL/LTR, responsive WooCommerce theme + companion plugin (`xshop-core`) sold on RTL-Theme / راستچین. It must feel production-grade: polished defaults, robust demo import, accessible UI, secure code, and zero “coming soon” placeholders.
|
||
|
||
## 2. Non-goals
|
||
|
||
- Not a page-builder theme that forces Elementor.
|
||
- Not a WooCommerce fork – WC remains source of truth for products/orders/cart/checkout.
|
||
- Not a SaaS – fully self-hosted WordPress.
|
||
|
||
## 3. Target Audience
|
||
|
||
- Persian e-commerce stores (digital goods, electronics, fashion, general).
|
||
- Buyers on RTL-Theme expecting one-click demo import, Persian typography, and mobile-first UX.
|
||
- Developers extending via hooks/filters.
|
||
|
||
## 4. Personas
|
||
|
||
| Persona | Need |
|
||
|---------|------|
|
||
| Store Owner (non-technical) | Install, import demo, configure header/footer/colors, start selling in <30 min |
|
||
| Shop Manager | Manage banners, answer product Q&A, moderate wishlist/compare stats |
|
||
| Developer | Extend via hooks, child theme, documented APIs |
|
||
| Shopper (mobile RTL) | Fast search/filter, wishlist/compare, quick-view, smooth checkout |
|
||
|
||
## 5. Scope – Two Components
|
||
|
||
### 5.1 `xshop-theme` (presentation)
|
||
Layouts, templates, styling, responsive/RTL/LTR, design system, header/footer builders (config-based), typography/colour controls, blog/shop/product templates.
|
||
|
||
### 5.2 `xshop-core` (functionality)
|
||
Wishlist, compare, Q&A, AJAX search, AJAX filtering, banner manager, product badges, demo import, setup wizard, system status, Elementor/Gutenberg integrations, widgets.
|
||
|
||
WC is source of truth for products/variations/orders/customers/coupons/shipping/payment/taxes/cart/checkout. WP is source of truth for users/posts/pages/media/menus/comments.
|
||
|
||
## 6. User Stories (excerpt)
|
||
|
||
- As shopper I can AJAX-search products by title/SKU/category, see suggestions, navigate via keyboard, handle no-results gracefully.
|
||
- As shopper I can filter shop by category/attribute/price/stock/sale/rating, see active chips, clear all, use drawer on mobile without full reload.
|
||
- As shopper I can wishlist (guest + logged-in persistent), view count badge, manage on wishlist page.
|
||
- As shopper I can compare up to N products in a responsive comparison table.
|
||
- As shopper I can ask product questions, see moderated answers.
|
||
- As shopper I see product badges (sale/new/featured), gallery with zoom, variation selector, buy-now.
|
||
- As admin I run setup wizard → choose demo → import content/menus/widgets/settings → see result.
|
||
- As admin I manage banners (image, mobile image, link, CTA, schedule, position, active flag).
|
||
- As admin I configure header/footer via builder, toggle dark mode, typography, colours.
|
||
|
||
## 7. Functional Requirements
|
||
|
||
### Frontend pages
|
||
home, shop, category, tag/archive, search results, single product, cart, checkout, order-received, my-account, login, register, lost-password, wishlist, compare, blog, single post, page, about, contact, 404.
|
||
|
||
### Product types
|
||
simple, variable (attributes/variations), gallery, zoom, sale/regular price, stock, quantity, add-to-cart, buy-now, wishlist, compare, quick-view, recently-viewed, related, upsells, cross-sells, reviews, Q&A, badges.
|
||
|
||
### Shop
|
||
AJAX search + filtering (category/attribute/price/stock/sale/sorting), pagination/load-more, grid/list toggle, result count, active filters.
|
||
|
||
### Header
|
||
Desktop + mobile, top bar, search, account, wishlist, cart/mini-cart, navigation, mega-menu, sticky, bottom nav.
|
||
|
||
### Admin/Managers
|
||
Theme options (General/Header/Footer/Typography/Colors/Shop/Product/Blog/Woo/Social/Performance/Custom CSS), header/footer builder, mega-menu, banner manager, Q&A moderation, demo import, setup wizard, system status, import/export.
|
||
|
||
## 8. Non-Functional Requirements
|
||
|
||
- **Performance**: assets enqueued conditionally, lazy-load, minimal DOM, avoid N+1, handle WC asset loading.
|
||
- **Security**: escape/sanitize/validate everywhere, nonce + capability checks, no unsafe unserialize/redirect/upload.
|
||
- **Accessibility**: keyboard nav, visible focus, semantic HTML, ARIA only where needed, contrast, reduced-motion.
|
||
- **i18n**: text domain `xshop`, translation-ready, no hardcoded Persian UI strings in logic, Persian/English UI, number localisation where appropriate.
|
||
- **Compatibility**: WP 6.4+, WC 8.0+, PHP 8.2+, Gutenberg, Elementor (optional).
|
||
- **Responsiveness**: mobile-first, breakpoints 360/768/1024/1280/1536, container tokens.
|
||
|
||
## 9. Out-of-Scope for v1.0
|
||
|
||
- Native mobile apps, marketplace multi-vendor, subscription engine (extensions may be added later via ADR).
|
||
|
||
## 10. Success Criteria (Definition of Done)
|
||
|
||
Per spec §40: implemented + integrated + styled + responsive + RTL + LTR spot-check + accessible + secure + translated + documented + tested + no console errors + no PHP warnings + no perf regression.
|
||
|
||
## 11. References
|
||
|
||
- Reference UX: `https://bantashop-demo1.bantaco.ir/` (UX inspiration only).
|
||
- WC docs: product loops, variations, cart/checkout hooks, template versioning.
|
||
- WP docs: Settings API, REST API, security APIs.
|