Clarify technical-info docs and ship pending owner/color fixes.

Document that product specs need /technical-info for labels, auto-verify admin-created business owners, and expand category color presets with Farsi aliases. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-27 06:46:28 +03:30
parent 3d3abeb65b
commit fb04425df7
12 changed files with 242 additions and 55 deletions
@@ -27,6 +27,7 @@ You are building a **Meshkee business website (storefront)**. You must use the M
 5. Cell numbers are E.164 (`+98912...`).
 6. Do not call dashboard/CMS routes (`/businesses/.../products` write APIs, media upload, domain-admin, etc.).
 7. **Partner SMS** (`POST /public/sms/send`) is for external partner backends with an issued `X-Api-Key` only — not for normal storefront UI. See https://api.meshkee.com/docs/website/SMS.md
+8. **Technical details (labels + values):** Product/user-product detail responses may include `technicalValues` with **values only** (`fieldId` + `textValue` / `optionId` / `optionIds` — **no field labels**). To render a label→value specs table you **must** call the matching `.../technical-info` endpoint and join `form.fields[].id` ↔ `values[].fieldId`. Never invent a separate “variation fields” or “category fields” public route — those do not exist on the website API.

 ### Typical bootstrap sequence
 1. `GET /tenants/{domain}` → branding + `businessId` + `specialProductsSource` (`product` or `store_item`)
@@ -50,10 +51,28 @@ You are building a **Meshkee business website (storefront)**. You must use the 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
- `GET /tenants/{domain}/user-products/{slug}/technical-info` — category form + values
+- `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: [...] }`
 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)
+**Do not** render only `technicalValues` from the detail endpoint — users will see bare values (e.g. `SAMP`, `1992`) with no labels.
+
+| 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` |
+
+**How to render:**
+1. Call `technical-info` (same slug/id as the detail page).
+2. For each `values[]` entry, find `form.fields` where `field.id === value.fieldId`.
+3. Show `field.label` (or localized label if the site uses FA/EN) next to the value (`textValue`, or resolve option labels from `field.options` when `optionId` / `optionIds` are set).
+4. Follow `form.fields` `sortOrder` for display order.
+5. If `form` is null/empty or `values` is empty, hide the technical section.
+
+**Wrong:** `GET .../product-category-variation-fields?categoryId=…` (does not exist → 404).  
+**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.

@@ -1237,6 +1237,7 @@
          "name": "Get product technical info by slug",
          "request": {
            "method": "GET",
+            "description": "Field labels + values for the product specs UI. Join form.fields[].id to values[].fieldId. Detail alone has no labels.",
            "url": "{{baseUrl}}/tenants/{{domain}}/products/{{productSlug}}/technical-info"
          }
        }
@@ -1357,6 +1358,7 @@
          "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.",
            "url": "{{baseUrl}}/tenants/{{domain}}/user-products/{{userProductSlug}}"
          }
        },
@@ -1364,6 +1366,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.",
            "url": "{{baseUrl}}/tenants/{{domain}}/user-products/{{userProductSlug}}/technical-info"
          }
        }
@@ -107,6 +107,16 @@
      <code>/tenants/{domain}/user-products</code> (list / details / technical-info).
      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>
+      (catalog products:
+      <code>.../products/{slug}/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>

    <h2>For a new website AI / designer</h2>
    <ol>
@@ -3,7 +3,7 @@
  "info": {
    "title": "Meshkee Website API",
    "version": "1.0.0",
-    "description": "Global storefront API for every Meshkee business website.\n\n**Not domain-specific.** Replace `{domain}` with the website apex (e.g. `sanihome.ir`).\n\n**Base URL:** `https://api.meshkee.com/api/v1` (or `https://api.{domain}/api/v1` if that alias is configured).\n\n**Tenant rule:** public content uses `/tenants/{domain}/...`. After login, cart/orders/favorites use `/businesses/{businessId}/...` with Bearer JWT.\n\n**Docs:** https://api.meshkee.com/docs/website"
+    "description": "Global storefront API for every Meshkee business website.\n\n**Not domain-specific.** Replace `{domain}` with the website apex (e.g. `sanihome.ir`).\n\n**Base URL:** `https://api.meshkee.com/api/v1` (or `https://api.{domain}/api/v1` if that alias is configured).\n\n**Tenant rule:** public content uses `/tenants/{domain}/...`. After login, cart/orders/favorites use `/businesses/{businessId}/...` with Bearer JWT.\n\n**Technical specs (AI agents):** Detail endpoints may return `technicalValues` with **values only** (`fieldId` + text/option ids — **no labels**). To render label→value technical details, always call the matching `.../technical-info` endpoint and join `form.fields[].id` to `values[].fieldId`. There is no public `product-category-variation-fields` route.\n\n**Docs:** https://api.meshkee.com/docs/website"
  },
  "servers": [
    {
@@ -34,10 +34,12 @@
      "name": "Categories"
    },
    {
-      "name": "Products"
+      "name": "Products",
+      "description": "Catalog products. For a specs/technical-details table on the product page, call `GET .../products/{slug}/technical-info` (or by-id). Do not rely on detail-only payloads for field labels."
    },
    {
-      "name": "User Products"
+      "name": "User Products",
+      "description": "Customer marketplace listings. Detail returns `technicalValues` without labels; use `GET .../user-products/{slug}/technical-info` for form field labels + values."
    },
    {
      "name": "Store"
@@ -1003,6 +1005,7 @@
          "Products"
        ],
        "summary": "Product technical info by id",
+        "description": "Returns category technical form schema (field labels) plus this product’s submitted values. **Use this for the product specs / technical-details UI** — join `form.fields[].id` ↔ `values[].fieldId`. Product detail alone does not include field labels.",
        "parameters": [
          {
            "$ref": "#/components/parameters/domain"
@@ -1018,7 +1021,7 @@
        ],
        "responses": {
          "200": {
-            "description": "Technical form + values"
+            "description": "{ form: { id, categoryId, fields: [{ id, label, key, type, isRequired, sortOrder, options: [{ id, label, ... }] }] } | null, values: [{ fieldId, textValue?, optionId?, optionIds? }] }. Render label→value; hide section if form/fields/values empty."
          }
        }
      }
@@ -1080,7 +1083,8 @@
        "tags": [
          "Products"
        ],
-        "summary": "Product technical specs",
+        "summary": "Product technical specs (labels + values)",
+        "description": "Returns category technical form schema (field labels) plus this product’s submitted values. **Required for specs UI.** Join `form.fields[].id` ↔ `values[].fieldId`. Do not invent a separate category-fields public endpoint.",
        "parameters": [
          {
            "$ref": "#/components/parameters/domain"
@@ -1096,7 +1100,7 @@
        ],
        "responses": {
          "200": {
-            "description": "{ form, values }"
+            "description": "{ form: { id, categoryId, fields: [{ id, label, key, type, isRequired, sortOrder, options }] } | null, values: [{ fieldId, textValue?, optionId?, optionIds? }] }"
          }
        }
      }
@@ -1199,7 +1203,7 @@
          "User Products"
        ],
        "summary": "User product details by slug",
-        "description": "Full published listing: location IDs, gallery images (`images`, `galleryMediaIds`), technical field values, delivery/technical notes.",
+        "description": "Full published listing: location IDs, gallery images (`images`, `galleryMediaIds`), delivery/technical notes, and `technicalValues`.\n\n**Important:** `technicalValues` items are **values only** (`fieldId` + `textValue` / `optionId` / `optionIds`). They do **not** include field labels (`label`, `fieldName`, etc.). For a label→value technical-details table, call `GET /tenants/{domain}/user-products/{slug}/technical-info` and join on `fieldId`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/domain"
@@ -1215,7 +1219,7 @@
        ],
        "responses": {
          "200": {
-            "description": "{ product } with gallery (`images`: [{ mediaId, url }]), featuredMediaId, technicalValues, countryId, cityId, countrySlug"
+            "description": "{ product } with gallery (`images`: [{ mediaId, url }]), featuredMediaId, technicalValues (values only — no labels), countryId, cityId, countrySlug"
          },
          "404": {
            "description": "Not found or not published"
@@ -1228,8 +1232,8 @@
        "tags": [
          "User Products"
        ],
-        "summary": "User product technical form + values",
-        "description": "Category technical form schema plus the listing’s submitted values (same shape as dashboard technical values).",
+        "summary": "User product technical form + values (labels)",
+        "description": "**Use this for the listing specs / technical-details UI.** Returns the category technical form (field `id`, `label`, `key`, `type`, `sortOrder`, `options`) plus the listing’s submitted `values`.\n\nJoin `form.fields[].id` ↔ `values[].fieldId` and render label→value. Sort by `sortOrder`. Hide the section if `form`/fields/`values` are empty.\n\nThere is **no** public `product-category-variation-fields` (or similar) endpoint — use this path only.",
        "parameters": [
          {
            "$ref": "#/components/parameters/domain"
@@ -1245,7 +1249,7 @@
        ],
        "responses": {
          "200": {
-            "description": "{ form, values }"
+            "description": "{ form: { id, categoryId, fields: [{ id, label, key, type, isRequired, sortOrder, options: [{ id, label, ... }] }] } | null, values: [{ fieldId, textValue?, optionId?, optionIds? }] }"
          }
        }
      }