Use id+slug paths for user products and count their visits.
Align storefront/sitemap URLs with catalog products, add by-id public APIs, and include user-product detail views in the product visit chart. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Alireza Hassani
co-authored by
Cursor
Cursor
parent
3aef62c1b8
commit
6517877bed
@@ -274,7 +274,7 @@ All routes are prefixed with `/api/v1`.
|
||||
| GET | `/tenants/:host/sitemap-videos.xml` | Published videos `/videos/{slug}` |
|
||||
| GET | `/tenants/:host/sitemap-instructions.xml` | Published instructions `/instruction/{slug}` |
|
||||
| GET | `/tenants/:host/sitemap-workshops.xml` | Published workshops `/workshops/{slug}` |
|
||||
| GET | `/tenants/:host/sitemap-user-products.xml` | Published user products `/user-products/{slug}` (module `customer_products`) |
|
||||
| GET | `/tenants/:host/sitemap-user-products.xml` | Published user products `/user-products/{id}/{slug}` (module `customer_products`) |
|
||||
| GET | `/tenants/:host/robots.txt` | robots.txt pointing to apex `/sitemap.xml` |
|
||||
| POST | `/tenants/:host/torob_api/v3/products` | Torob Product API v3 (JWT). Requires store module + `settings.store.torobEnabled`. Nginx: `POST https://{host}/torob_api/v3/products` |
|
||||
| GET | `/tenants/:host/categories/by-id/:categoryId` | Public category by id (for category landing pages) |
|
||||
@@ -363,9 +363,11 @@ Base: `/tenants/:host/user-products`
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/` | List published listings (`name`/`q`, `categoryId`, `cityId`, `countryId`, `condition`, `promoted`, pagination) |
|
||||
| GET | `/:slug` | Details + gallery (`images`, `galleryMediaIds`) + technical values |
|
||||
| GET | `/:slug/technical-info` | Category technical form + values |
|
||||
| GET | `/` | List published listings (`name`/`q`, `categoryId`, `cityId`, `countryId`, `condition`, `promoted`, pagination); items include `pathSlug` |
|
||||
| GET | `/by-id/:id` | Details by id (preferred for `/user-products/{id}/{pathSlug}` pages) |
|
||||
| GET | `/by-id/:id/technical-info` | Category technical form + values by id |
|
||||
| GET | `/:slug` | Details by DB slug (legacy) |
|
||||
| GET | `/:slug/technical-info` | Category technical form + values by slug (legacy) |
|
||||
|
||||
#### Cart (customer — JWT, must be business customer)
|
||||
|
||||
|
||||
@@ -172,9 +172,11 @@ Nginx on the shop apex still proxies bank callbacks (`https://<WEBSITE_DOMAIN>/m
|
||||
|
||||
### User products (customer listings)
|
||||
Public marketplace listings owned by customers — not catalog `products`.
|
||||
- `GET /tenants/{domain}/user-products` — list published (`name`/`q`, `categoryId`, `cityId`, `countryId`, `condition`, `promoted`, pagination)
|
||||
- `GET /tenants/{domain}/user-products/{slug}` — details + gallery (`technicalValues` = values only, no labels)
|
||||
- `GET /tenants/{domain}/user-products/{slug}/technical-info` — **required for specs UI**: `{ form: { fields: [{ id, label, key, type, ... }] }, values: [...] }`
|
||||
- `GET /tenants/{domain}/user-products` — list published (`name`/`q`, `categoryId`, `cityId`, `countryId`, `condition`, `promoted`, pagination). Each item includes `id`, `pathSlug`, `titleFa`/`titleEn`.
|
||||
- `GET /tenants/{domain}/user-products/by-id/{id}` — **preferred** for storefront pages (slug segment is SEO-only)
|
||||
- `GET /tenants/{domain}/user-products/by-id/{id}/technical-info` — specs labels + values by id
|
||||
- `GET /tenants/{domain}/user-products/{slug}` — legacy resolve by DB slug (still supported)
|
||||
- `GET /tenants/{domain}/user-products/{slug}/technical-info` — legacy specs by slug
|
||||
Use product categories from `GET /tenants/{domain}/categories?entityType=product` for filters. Creating/editing listings is customer-dashboard only (`/businesses/.../my-user-products`), not website-facing.
|
||||
|
||||
### Technical details / specs table (catalog products + user products)
|
||||
@@ -183,7 +185,7 @@ Use product categories from `GET /tenants/{domain}/categories?entityType=product
|
||||
| Detail page | Specs endpoint (labels + values) |
|
||||
|-------------|----------------------------------|
|
||||
| `GET .../products/{slug}` or `.../products/by-id/{id}` | `GET .../products/{slug}/technical-info` or `.../products/by-id/{id}/technical-info` |
|
||||
| `GET .../user-products/{slug}` | `GET .../user-products/{slug}/technical-info` |
|
||||
| `GET .../user-products/by-id/{id}` (or `{slug}`) | `GET .../user-products/by-id/{id}/technical-info` (or `{slug}/technical-info`) |
|
||||
|
||||
**How to render:**
|
||||
1. Call `technical-info` (same slug/id as the detail page).
|
||||
@@ -196,12 +198,13 @@ Use product categories from `GET /tenants/{domain}/categories?entityType=product
|
||||
**Wrong:** expecting `fieldName` / `fieldNameFa` on each `technicalValues` item in the product detail response.
|
||||
|
||||
### Analytics (dashboard charts)
|
||||
Page views are recorded **automatically** when the website calls the normal public list/detail APIs (blogs, products, portfolios, videos, store-items, and homepage sliders). No extra website code is required for those.
|
||||
Page views are recorded **automatically** when the website calls the normal public list/detail APIs (blogs, products, user-products, portfolios, videos, store-items, and homepage sliders). No extra website code is required for those.
|
||||
|
||||
Optional explicit record (e.g. custom home without sliders):
|
||||
- `POST /tenants/{domain}/analytics/views` body `{ "kind": "home"|"blog_detail"|"product_detail"|..., "entityId"?: "...", "path"?: "/blog/my-post" }`
|
||||
- `kind` values: `home`, `portfolio_list`, `portfolio_detail`, `product_list`, `product_detail`, `store_item_list`, `store_item_detail`, `blog_list`, `blog_detail`, `video_list`, `video_detail` (legacy aliases `website`/`product`/`portfolio`/`blog` still accepted)
|
||||
- `kind` values: `home`, `portfolio_list`, `portfolio_detail`, `product_list`, `product_detail`, `store_item_list`, `store_item_detail`, `blog_list`, `blog_detail`, `video_list`, `video_detail`, `user_product_list`, `user_product_detail` (legacy aliases `website`/`product`/`portfolio`/`blog` still accepted)
|
||||
- Events kept ~6 months for charts; lifetime totals kept forever in counters.
|
||||
- The business dashboard **Product views** chart counts both `product_detail` and `user_product_detail`.
|
||||
|
||||
### Static images
|
||||
Named slots the business dashboard can replace. Fetch once per page:
|
||||
@@ -274,13 +277,13 @@ Minimal example:
|
||||
- **Canonical detail URLs (Meshkee default for all sites):**
|
||||
- Product: `/products/{id}/{nameFaSlug}` — build `nameFaSlug` from `nameFa` (fallback `title`); resolve page via `GET /tenants/{domain}/products/by-id/{id}` (slug segment is SEO-only; redirect to canonical if it drifts).
|
||||
- Product category: `/products/category/{categoryId}/{nameFaSlug}` — build slug from `nameFa` (fallback `name`); resolve via `GET /tenants/{domain}/categories/by-id/{id}`, then list products with `categoryId`.
|
||||
- User product (customer listing): `/user-products/{slug}` — use the listing’s `slug` from the API; resolve via `GET /tenants/{domain}/user-products/{slug}`.
|
||||
- User product (customer listing): `/user-products/{id}/{pathSlug}` — use `id` + `pathSlug` from the list/detail API (or slugify `titleFa` / `titleEn`); resolve via `GET /tenants/{domain}/user-products/by-id/{id}` (slug segment is SEO-only).
|
||||
- Blog: `/blog/{slug}` — use the blog’s `slug` from the API; resolve via `GET /tenants/{domain}/blogs/{slug}` (or list + match). Prefer slug routes over id.
|
||||
- Portfolio: `/portfolio/{slug}` — use the portfolio’s `slug` from the API; resolve via `GET /tenants/{domain}/portfolios/{slug}`.
|
||||
- Instruction: `/instruction/{slug}` — use the instruction’s `slug` from the API; resolve via `GET /tenants/{domain}/instructions/{slug}`.
|
||||
- Video: `/videos/{slug}` — use the video’s `slug` from the API.
|
||||
- Workshop: `/workshops/{slug}` — use the workshop’s `slug` from the API.
|
||||
- When linking from lists/cards, use the same slug-based detail paths. Category links use `/products/category/{id}/{nameFaSlug}`. User-product cards use `/user-products/{slug}`.
|
||||
- When linking from lists/cards, use the same slug-based detail paths. Category links use `/products/category/{id}/{nameFaSlug}`. User-product cards use `/user-products/{id}/{pathSlug}`.
|
||||
- Omit `templates` in `sitemap-config.json` unless this site uses non-default paths.
|
||||
- **Sitemap files (proxied by nginx — do not ship local copies):**
|
||||
- `/sitemap.xml` — sitemap **index** (lists child sitemaps for enabled modules)
|
||||
|
||||
@@ -1354,11 +1354,27 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "Get user product by id",
|
||||
"request": {
|
||||
"method": "GET",
|
||||
"description": "Preferred for /user-products/{id}/{pathSlug} pages. technicalValues are values only — use technical-info for specs UI.",
|
||||
"url": "{{baseUrl}}/tenants/{{domain}}/user-products/by-id/{{userProductId}}"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "Get user product technical info by id",
|
||||
"request": {
|
||||
"method": "GET",
|
||||
"description": "Required for technical-details UI when page is resolved by id: form.fields (labels) + values.",
|
||||
"url": "{{baseUrl}}/tenants/{{domain}}/user-products/by-id/{{userProductId}}/technical-info"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "Get user product by slug",
|
||||
"request": {
|
||||
"method": "GET",
|
||||
"description": "Listing detail + gallery. technicalValues are values only (fieldId + text/option) — no labels. Use technical-info for specs UI.",
|
||||
"description": "Legacy slug resolve. Prefer by-id for storefront pages. technicalValues are values only (fieldId + text/option) — no labels.",
|
||||
"url": "{{baseUrl}}/tenants/{{domain}}/user-products/{{userProductSlug}}"
|
||||
}
|
||||
},
|
||||
@@ -1366,7 +1382,7 @@
|
||||
"name": "Get user product technical info by slug",
|
||||
"request": {
|
||||
"method": "GET",
|
||||
"description": "Required for technical-details UI: form.fields (labels) + values. Join field.id ↔ value.fieldId. No separate category-variation-fields public endpoint.",
|
||||
"description": "Legacy specs by slug. Prefer by-id technical-info. Join field.id ↔ value.fieldId.",
|
||||
"url": "{{baseUrl}}/tenants/{{domain}}/user-products/{{userProductSlug}}/technical-info"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -143,16 +143,17 @@
|
||||
<h2>User products (customer listings)</h2>
|
||||
<p>
|
||||
Marketplace-style stock listings created by customers. Public read-only under
|
||||
<code>/tenants/{domain}/user-products</code> (list / details / technical-info).
|
||||
<code>/tenants/{domain}/user-products</code> (list / by-id / details / technical-info).
|
||||
Storefront URLs: <code>/user-products/{id}/{pathSlug}</code>.
|
||||
See OpenAPI tag <strong>User Products</strong>.
|
||||
</p>
|
||||
<p>
|
||||
<strong>Technical details:</strong> detail responses include
|
||||
<code>technicalValues</code> with <em>values only</em> (no field labels).
|
||||
For a label→value specs table, call
|
||||
<code>GET /tenants/{domain}/user-products/{slug}/technical-info</code>
|
||||
<code>GET /tenants/{domain}/user-products/by-id/{id}/technical-info</code>
|
||||
(catalog products:
|
||||
<code>.../products/{slug}/technical-info</code>) and join
|
||||
<code>.../products/by-id/{id}/technical-info</code>) and join
|
||||
<code>form.fields[].id</code> ↔ <code>values[].fieldId</code>.
|
||||
There is no public <code>product-category-variation-fields</code> route.
|
||||
</p>
|
||||
|
||||
@@ -39,7 +39,7 @@
|
||||
},
|
||||
{
|
||||
"name": "User Products",
|
||||
"description": "Customer marketplace listings. Detail returns `technicalValues` without labels; use `GET .../user-products/{slug}/technical-info` for form field labels + values."
|
||||
"description": "Customer marketplace listings. Prefer `GET .../user-products/by-id/{id}` for storefront pages. Detail returns `technicalValues` without labels; use `.../technical-info` for form field labels + values."
|
||||
},
|
||||
{
|
||||
"name": "Store"
|
||||
@@ -434,7 +434,7 @@
|
||||
"SEO"
|
||||
],
|
||||
"summary": "User products sitemap urlset",
|
||||
"description": "Published customer marketplace listings. Default paths: `/user-products/{slug}`. Included in the index when the `customer_products` module is enabled. Override path via sitemap-config `templates.userProduct`.",
|
||||
"description": "Published customer marketplace listings. Default paths: `/user-products/{id}/{slug}` (slug from titleFa/titleEn). Included in the index when the `customer_products` module is enabled. Override path via sitemap-config `templates.userProduct`.",
|
||||
"parameters": [
|
||||
{
|
||||
"$ref": "#/components/parameters/domain"
|
||||
@@ -659,6 +659,8 @@
|
||||
"blog_detail",
|
||||
"video_list",
|
||||
"video_detail",
|
||||
"user_product_list",
|
||||
"user_product_detail",
|
||||
"website",
|
||||
"product",
|
||||
"portfolio",
|
||||
@@ -668,7 +670,7 @@
|
||||
},
|
||||
"entityId": {
|
||||
"type": "string",
|
||||
"description": "Required for *_detail kinds (product, portfolio, blog, video, store item)."
|
||||
"description": "Required for *_detail kinds (product, user product, portfolio, blog, video, store item)."
|
||||
},
|
||||
"path": {
|
||||
"type": "string",
|
||||
@@ -1262,7 +1264,64 @@
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "{ items: UserProductListItem[], total, page, pageSize }. Each item includes id, slug, titleFa/titleEn, price, priceCurrency, condition, city/country names, imageUrl, category*, promoted, publishedAt."
|
||||
"description": "{ items: UserProductListItem[], total, page, pageSize }. Each item includes id, slug, pathSlug, titleFa/titleEn, price, priceCurrency, condition, city/country names, imageUrl, category*, promoted, publishedAt."
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/tenants/{domain}/user-products/by-id/{productId}": {
|
||||
"get": {
|
||||
"tags": [
|
||||
"User Products"
|
||||
],
|
||||
"summary": "User product by id (preferred for /user-products/{id}/{pathSlug} pages)",
|
||||
"description": "Full published listing resolved by id. Prefer this for storefront detail pages — the path slug segment is SEO-only.\n\n**Important:** `technicalValues` items are **values only**. For a label→value table, call `GET /tenants/{domain}/user-products/by-id/{productId}/technical-info`.",
|
||||
"parameters": [
|
||||
{
|
||||
"$ref": "#/components/parameters/domain"
|
||||
},
|
||||
{
|
||||
"name": "productId",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "{ product } with gallery, pathSlug, technicalValues (values only), countryId, cityId"
|
||||
},
|
||||
"404": {
|
||||
"description": "Not found or not published"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/tenants/{domain}/user-products/by-id/{productId}/technical-info": {
|
||||
"get": {
|
||||
"tags": [
|
||||
"User Products"
|
||||
],
|
||||
"summary": "User product technical form + values by id",
|
||||
"description": "**Use this for the listing specs UI** when the page is resolved by id. Same shape as the slug technical-info route.",
|
||||
"parameters": [
|
||||
{
|
||||
"$ref": "#/components/parameters/domain"
|
||||
},
|
||||
{
|
||||
"name": "productId",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "{ form: { id, categoryId, fields: [...] } | null, values: [...] }"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user