docs

tangwang
1 parent 1ad371d1
Showing 6 changed files with 2543 additions and 1 deletions Show diff stats
docs/店匠app安装-前端开发部署-全流程-笔记.md
docs/店匠相关资料/SHOPLAZZA_I18N_AND_FRONTEND_GUIDE.md
docs/索引字段说明.md -> docs/索引字段说明v1.md
docs/索引字段说明v2-plan.md
docs/索引字段说明v2-参考表结构.md
docs/索引字段说明v2.md
@@ -0,0 +1,1287 @@
+# 店匠（Shoplazza）APP 开发完整指南
+
+## 参考
+https://xp0y6kmku6.feishu.cn/wiki/UsFiwDyGgiDWDwkAe5jcKHbSnHd
+
+## 目录
+
+1. [概述](#概述)
+2. [阶段 1：在店匠 Partner 后台创建新 APP](#阶段-1在店匠-partner-后台创建新-app)
+3. [阶段 2：创建前端项目](#阶段-2创建前端项目)
+4. [阶段 3：开发后端服务](#阶段-3开发后端服务)
+5. [阶段 4：前端开发详解](#阶段-4前端开发详解)
+6. [阶段 5：测试与部署](#阶段-5测试与部署)
+7. [常见问题与最佳实践](#常见问题与最佳实践)
+
+---
+
+## 概述
+
+本指南将帮助您从零开始创建一个完整的店匠（Shoplazza）Public App，包括：
+
+- **前端**：使用 Liquid 模板和 Lessjs 组件库开发主题扩展
+- **后端**：实现 OAuth 2.0 授权流程、HMAC 验证、API 调用
+- **多语言支持**：支持 16 种语言的国际化
+- **主题集成**：与店匠主题深度集成
+
+### 前置要求
+
+- Node.js 14.14.0 或更高版本
+- [Shoplazza 合作伙伴账户](https://partners.shoplazza.com/)
+- [Shoplazza CLI](https://www.shoplazza.dev/docs/overview-3)（用于部署）
+- 后端服务（Java/Spring Boot 或 Node.js/Express）
+- 测试店铺（用于开发测试）
+
+---
+
+## 阶段 1：在店匠 Partner 后台创建新 APP
+
+### 步骤 1.1：登录 Partner 后台
+
+1. 访问：https://partners.shoplazza.com/
+2. 使用合作伙伴账号登录
+3. 进入管理页面：https://partners.shoplazza.com/{partner_id}
+
+### 步骤 1.2：创建新 APP
+
+1. 左侧导航：**Apps**
+2. 点击：**Create App** 或 **创建应用**
+3. 填写信息：
+   - **App Name**：智能推荐1.0（或自定义名称）
+   - **App Type**：**Public App**（公共应用）
+   - **Category**：选择合适分类（如 Product Recommendations）
+4. 点击：**Create** 或 **创建**
+
+### 步骤 1.3：记录关键信息
+
+系统会生成 **Client credentials**（APP 的公共标识符，OAuth 流程以及与 Shoplazza API 互动都会需要）：
+
+- **Client ID**：例如 `x3apOQkj98Aij61BKi1TJ9q6wyfY3HrbmUZJ5FPfSbY`
+- **Client Secret**：例如 `LF71s5gqtPws2i08C9y43uIYXpF_c91ZnqRmS1z8Ekk`
+
+**⚠️ 重要**：请妥善保存这些凭证，后续无法再次查看 Client Secret。
+
+### 步骤 1.4：配置 APP 信息
+
+在 APP 详情页面配置以下信息：
+
+#### 1.4.1 App URL（安装入口）
+
+当商家从应用市场点击"安装"时，店匠会跳转到此 URL：
+
+```
+https://saas-ai-api.essa.top/recommend/oauth/install
+```
+
+**请求参数**：
+- `shop`：店铺域名，例如 `47167113-1.myshoplaza.com`
+- `hmac`：HMAC 签名（用于验证请求来源）
+- `install_from`：安装来源，例如 `app_store`
+- `store_id`：店铺 ID
+
+**完整示例**：
+```
+https://saas-ai-api.essa.top/recommend/oauth/install?
+  hmac=c4caf9b08bdeff7531bb12712ffea860264ec24f5fd953832505c5024d19edca&
+  install_from=app_store&
+  shop=rwerwre.myshoplaza.com&
+  store_id=1339409
+```
+
+#### 1.4.2 Redirect URL（OAuth 回调地址）
+
+商家授权后，店匠会重定向到此 URL：
+
+```
+https://saas-ai-api.essa.top/recommend/oauth/callback
+```
+
+**请求参数**：
+- `code`：授权码（只能使用一次）
+- `hmac`：HMAC 签名
+- `shop`：店铺域名
+- `state`：防 CSRF 攻击的随机值（可选）
+
+#### 1.4.3 Scopes（权限范围）
+
+根据应用功能需求选择权限：
+
+| Scope | 说明 | 是否必需 |
+|-------|------|---------|
+| `read_shop` | 读取店铺信息 | ✅ 推荐 |
+| `read_product` | 读取商品信息 | ✅ 推荐 |
+| `read_customer` | 读取客户信息 | 可选 |
+| `read_order` | 读取订单信息 | 可选 |
+| `read_app_proxy` | 读取应用代理 | 可选 |
+| `write_cart_transform` | 修改购物车 | 可选 |
+
+**推荐配置**（智能推荐 APP）：
+```
+read_shop read_product read_customer
+```
+
+### 步骤 1.5：记录 Extension ID
+
+创建主题扩展后，系统会生成 Extension ID，例如：`580182366958388163`
+
+此 ID 需要在 `shoplazza.extension.toml` 中配置。
+
+---
+
+## 阶段 2：创建前端项目
+
+### 步骤 2.1：创建项目目录
+
+```bash
+# 进入父目录
+cd /home/tw/saas
+
+# 创建新项目目录
+mkdir shoplazza-recommend-app
+cd shoplazza-recommend-app
+```
+
+### 步骤 2.2：初始化项目
+
+#### 方式 1：使用 Shoplazza CLI（推荐）
+
+```bash
+# 安装 Shoplazza CLI（如果未安装）
+npm i -g shoplazza-cli
+
+# 生成项目结构
+shoplazza app generate
+```
+
+#### 方式 2：手动创建
+
+按照以下结构手动创建文件：
+
+```
+shoplazza-recommend-app/
+├── package.json
+├── shoplazza.app.toml
+├── README.md
+├── .gitignore
+└── extensions/
+    └── recommend/
+        ├── shoplazza.extension.toml
+        ├── package.json
+        ├── blocks/
+        │   └── recommend.liquid
+        ├── assets/
+        │   ├── recommend.css
+        │   └── assets-manifest.json
+        ├── snippets/
+        │   └── recommend.liquid
+        └── locales/
+            ├── zh-CN.json
+            └── en-US.json
+```
+
+### 步骤 2.3：创建根目录配置文件
+
+#### 2.3.1 package.json
+
+```json
+{
+  "name": "智能推荐1.0",
+  "version": "1.0.0",
+  "scripts": {
+    "shoplazza": "shoplazza",
+    "info": "shoplazza app info",
+    "generate": "shoplazza app generate",
+    "deploy": "shoplazza app deploy"
+  },
+  "author": "",
+  "license": "ISC",
+  "private": true,
+  "workspaces": [
+    "extensions/*"
+  ]
+}
+```
+
+#### 2.3.2 shoplazza.app.toml
+
+使用步骤 1.3 中获取的 Client ID：
+
+```toml
+# 使用步骤 1.3 中获取的 Client ID
+client_id = "x3apOQkj98Aij61BKi1TJ9q6wyfY3HrbmUZJ5FPfSbY"
+
+# 权限范围（与 Partner 后台配置保持一致）
+scopes = "read_shop read_product read_customer"
+```
+
+#### 2.3.3 .gitignore
+
+```gitignore
+# Dependencies
+node_modules/
+package-lock.json
+yarn.lock
+
+# Build outputs
+app-deploy/
+dist/
+build/
+
+# Environment
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+```
+
+#### 2.3.4 README.md
+
+```markdown
+# 智能推荐 1.0
+
+店匠（Shoplazza）智能推荐 APP 前端项目。
+
+## 快速开始
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 部署应用
+
+```bash
+npm run deploy
+```
+
+### 查看应用信息
+
+```bash
+npm run info
+```
+
+## 项目结构
+
+- `extensions/recommend/`：推荐扩展
+  - `blocks/recommend.liquid`：主组件
+  - `assets/recommend.css`：样式文件
+  - `locales/`：多语言文件
+```
+
+### 步骤 2.4：创建 Extension 配置文件
+
+#### 2.4.1 extensions/recommend/shoplazza.extension.toml
+
+```toml
+# Extension ID（从 Partner 后台获取，或部署后系统生成）
+id = "580182366958388163"
+
+# Extension 名称（与目录名保持一致）
+name = "recommend"
+
+# Extension 类型（theme 表示主题扩展）
+type = "theme"
+```
+
+#### 2.4.2 extensions/recommend/package.json
+
+```json
+{
+  "name": "recommend",
+  "version": "1.0.0",
+  "private": true
+}
+```
+
+---
+
+## 阶段 3：开发后端服务
+
+### 步骤 3.1：OAuth 2.0 授权流程
+
+店匠使用标准的 OAuth 2.0 授权码（Authorization Code）流程：
+
+```
+1. 商家在应用市场点击"安装"
+   ↓
+2. 店匠跳转到 APP URL（步骤 1.4.1）
+   ↓
+3. 后端验证 HMAC 和 shop 参数
+   ↓
+4. 后端重定向到店匠授权页面
+   ↓
+5. 商家在授权页面点击"授权"
+   ↓
+6. 店匠回调 Redirect URL（步骤 1.4.2），携带 code
+   ↓
+7. 后端验证 HMAC，用 code 换取 access_token
+   ↓
+8. 保存 token 到数据库，完成安装
+```
+
+### 步骤 3.2：实现 APP URL 处理（步骤 3）
+
+#### 3.2.1 请求示例
+
+```
+GET https://saas-ai-api.essa.top/recommend/oauth/install?
+  hmac=c4caf9b08bdeff7531bb12712ffea860264ec24f5fd953832505c5024d19edca&
+  install_from=app_store&
+  shop=rwerwre.myshoplaza.com&
+  store_id=1339409
+```
+
+#### 3.2.2 安全检查（必须）
+
+在继续之前，必须执行以下安全检查：
+
+1. **验证 HMAC 签名**
+   - 从查询字符串中移除 `hmac` 参数
+   - 按字典顺序排序剩余参数
+   - 使用 `CLIENT_SECRET` 计算 HMAC-SHA256
+   - 与请求中的 `hmac` 值比较
+
+2. **验证 shop 参数**
+   - 必须是有效的店铺主机名
+   - 必须以 `.myshoplaza.com` 结尾
+
+#### 3.2.3 Java 实现示例
+
+```java
+@RestController
+@RequestMapping("/recommend/oauth")
+public class RecommendOAuthController {
+    
+    @Autowired
+    private ShoplazzaOAuthService oAuthService;
+    
+    /**
+     * 处理 APP 安装请求（步骤 3）
+     */
+    @GetMapping("/install")
+    public ResponseEntity<Void> handleInstall(
+            @RequestParam("shop") String shop,
+            @RequestParam("hmac") String hmac,
+            @RequestParam(value = "install_from", required = false) String installFrom,
+            @RequestParam(value = "store_id", required = false) String storeId,
+            HttpServletRequest request) {
+        
+        // 1. 验证 HMAC
+        Map<String, String> params = new HashMap<>();
+        params.put("shop", shop);
+        params.put("hmac", hmac);
+        if (installFrom != null) params.put("install_from", installFrom);
+        if (storeId != null) params.put("store_id", storeId);
+        
+        if (!oAuthService.verifyHmac(params, hmac)) {
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST).build();
+        }
+        
+        // 2. 验证 shop 参数
+        if (!shop.endsWith(".myshoplaza.com")) {
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST).build();
+        }
+        
+        // 3. 生成授权 URL 并重定向（步骤 4）
+        String authUrl = oAuthService.buildAuthorizationRedirect(shop);
+        return ResponseEntity.status(HttpStatus.FOUND)
+                .header(HttpHeaders.LOCATION, authUrl)
+                .build();
+    }
+}
+```
+
+#### 3.2.4 Node.js 实现示例
+
+```javascript
+const express = require("express");
+const crypto = require("crypto");
+const app = express();
+
+const CLIENT_ID = "x3apOQkj98Aij61BKi1TJ9q6wyfY3HrbmUZJ5FPfSbY";
+const CLIENT_SECRET = "LF71s5gqtPws2i08C9y43uIYXpF_c91ZnqRmS1z8Ekk";
+const REDIRECT_URI = "https://saas-ai-api.essa.top/recommend/oauth/callback";
+
+// HMAC 验证函数
+function verifyHmac(queryParams, receivedHmac) {
+    const map = { ...queryParams };
+    delete map["hmac"];
+    
+    const sortedKeys = Object.keys(map).sort();
+    const message = sortedKeys.map(key => `${key}=${map[key]}`).join('&');
+    
+    const calculatedHmac = crypto
+        .createHmac("sha256", CLIENT_SECRET)
+        .update(message)
+        .digest("hex");
+    
+    return crypto.timingSafeEqual(
+        Buffer.from(calculatedHmac),
+        Buffer.from(receivedHmac)
+    );
+}
+
+// 处理安装请求
+app.get("/recommend/oauth/install", (req, res) => {
+    const { shop, hmac, install_from, store_id } = req.query;
+    
+    // 1. 验证 HMAC
+    if (!verifyHmac(req.query, hmac)) {
+        return res.status(400).send("HMAC validation failed");
+    }
+    
+    // 2. 验证 shop 参数
+    if (!shop || !shop.endsWith(".myshoplaza.com")) {
+        return res.status(400).send("Invalid shop parameter");
+    }
+    
+    // 3. 生成 state（防 CSRF）
+    const state = crypto.randomBytes(16).toString("hex");
+    
+    // 4. 构建授权 URL
+    const scopes = "read_shop read_product read_customer";
+    const authUrl = `https://${shop}/admin/oauth/authorize?` +
+        `client_id=${CLIENT_ID}&` +
+        `scope=${encodeURIComponent(scopes)}&` +
+        `redirect_uri=${encodeURIComponent(REDIRECT_URI)}&` +
+        `response_type=code&` +
+        `state=${state}`;
+    
+    // 5. 重定向到授权页面
+    res.redirect(authUrl);
+});
+```
+
+### 步骤 3.3：实现 OAuth 回调处理（步骤 7-9）
+
+#### 3.3.1 请求示例
+
+```
+GET https://saas-ai-api.essa.top/recommend/oauth/callback?
+  code=wBe-NWHzW21e94YqD4bRKBsJsE2GcZlDzP4oW9w2ddk&
+  hmac=4c396fac1912057b65228f5bbd4a65255961d85a60fba1f1105ddbf27f17b58f&
+  shop=rwerwre.myshoplaza.com&
+  state=abc123
+```
+
+#### 3.3.2 Java 实现示例
+
+```java
+/**
+ * 处理 OAuth 回调（步骤 7-9）
+ */
+@GetMapping("/callback")
+public ResponseEntity<String> handleCallback(
+        @RequestParam("code") String code,
+        @RequestParam("hmac") String hmac,
+        @RequestParam("shop") String shop,
+        @RequestParam(value = "state", required = false) String state) {
+    
+    // 1. 验证 HMAC
+    Map<String, String> params = new HashMap<>();
+    params.put("code", code);
+    params.put("hmac", hmac);
+    params.put("shop", shop);
+    if (state != null) params.put("state", state);
+    
+    if (!oAuthService.verifyHmac(params, hmac)) {
+        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                .body("HMAC validation failed");
+    }
+    
+    // 2. 用 code 换取 access_token
+    ShoplazzaTokenResponse tokenResponse = oAuthService.exchangeForToken(shop, code);
+    
+    // 3. 保存 token 到数据库
+    ShopConfig shopConfig = shopConfigService.saveOrUpdate(shop, tokenResponse);
+    
+    // 4. 返回安装成功页面
+    String successPage = buildSuccessPage(shopConfig);
+    return ResponseEntity.ok()
+            .contentType(MediaType.TEXT_HTML)
+            .body(successPage);
+}
+
+/**
+ * 用 code 换取 access_token
+ */
+public ShoplazzaTokenResponse exchangeForToken(String shop, String code) {
+    String tokenUrl = "https://" + shop + "/admin/oauth/token";
+    
+    Map<String, String> requestBody = new HashMap<>();
+    requestBody.put("client_id", CLIENT_ID);
+    requestBody.put("client_secret", CLIENT_SECRET);
+    requestBody.put("code", code);
+    requestBody.put("grant_type", "authorization_code");
+    requestBody.put("redirect_uri", REDIRECT_URI);
+    
+    // 发送 POST 请求
+    RestTemplate restTemplate = new RestTemplate();
+    HttpHeaders headers = new HttpHeaders();
+    headers.setContentType(MediaType.APPLICATION_JSON);
+    
+    HttpEntity<Map<String, String>> entity = new HttpEntity<>(requestBody, headers);
+    ResponseEntity<ShoplazzaTokenResponse> response = restTemplate.postForEntity(
+            tokenUrl, entity, ShoplazzaTokenResponse.class);
+    
+    return response.getBody();
+}
+```
+
+#### 3.3.3 Token 响应格式
+
+```json
+{
+  "token_type": "Bearer",
+  "expires_at": 1550546245,
+  "access_token": "eyJ0eXAiOiJKV1QiLCJh...",
+  "refresh_token": "def502003d28ba08a964e...",
+  "store_id": "1339409",
+  "store_name": "rwerwre"
+}
+```
+
+### 步骤 3.4：实现 API 调用
+
+获取 access_token 后，可以调用店匠 API：
+
+```java
+/**
+ * 调用店匠 API 示例：获取商品列表
+ */
+public List<Product> getProducts(String shop, String accessToken) {
+    String apiUrl = "https://" + shop + "/openapi/2022-01/products";
+    
+    HttpHeaders headers = new HttpHeaders();
+    headers.set("Access-Token", accessToken);
+    headers.set("Content-Type", "application/json");
+    
+    HttpEntity<?> entity = new HttpEntity<>(headers);
+    
+    RestTemplate restTemplate = new RestTemplate();
+    ResponseEntity<ProductListResponse> response = restTemplate.exchange(
+            apiUrl,
+            HttpMethod.GET,
+            entity,
+            ProductListResponse.class
+    );
+    
+    return response.getBody().getProducts();
+}
+```
+
+---
+
+## 阶段 4：前端开发详解
+
+### 步骤 4.1：创建 Liquid 模板
+
+#### 4.1.1 extensions/recommend/blocks/recommend.liquid
+
+```liquid
+{% comment %}
+  推荐商品组件
+  使用 {% use %} 引入 CSS 文件
+{% endcomment %}
+{% use "recommend.css" %}
+
+<div id="recommend" class="recommend-container">
+  {% comment %} 版本标识（开发测试用）{% endcomment %}
+  <div class="recommend-badge">智能推荐 APP</div>
+  
+  {% comment %} 标题（使用多语言）{% endcomment %}
+  <h2>{{ 'recommend.title' | t }}</h2>
+  
+  {% comment %} 商品列表容器 {% endcomment %}
+  <div class="recommend-products" id="recommend-products">
+    <div class="loading">{{ 'recommend.loading' | t }}</div>
+  </div>
+</div>
+
+<script>
+(function() {
+  {% comment %} 配置信息（店匠会自动注入 shop 对象）{% endcomment %}
+  window.RECOMMEND_CONFIG = {
+    storeId: "{{ shop.domain }}",
+    apiEndpoint: "https://saas-ai-api.essa.top/app-api/app/shoplazza/recommend/products",
+    locale: "{{ shop.locale }}"
+  };
+
+  {% comment %} 获取店铺语言 {% endcomment %}
+  const shopLocale = "{{ shop.locale }}" || "zh-CN";
+  
+  {% comment %} 翻译文本（通过 Liquid 的 t 过滤器获取）{% endcomment %}
+  const translations = {
+    title: "{{ 'recommend.title' | t }}",
+    loading: "{{ 'recommend.loading' | t }}",
+    noResults: "{{ 'recommend.no_results' | t }}",
+    error: "{{ 'recommend.error' | t }}",
+    addToCart: "{{ 'recommend.add_to_cart' | t }}",
+    viewDetails: "{{ 'recommend.view_details' | t }}"
+  };
+
+  {% comment %} 加载推荐商品 {% endcomment %}
+  async function loadRecommendations() {
+    const container = document.getElementById('recommend-products');
+    
+    try {
+      const response = await fetch(
+        `${window.RECOMMEND_CONFIG.apiEndpoint}?storeId=${window.RECOMMEND_CONFIG.storeId}`,
+        {
+          method: 'GET',
+          headers: {
+            'Content-Type': 'application/json'
+          }
+        }
+      );
+      
+      if (!response.ok) {
+        throw new Error('加载失败: ' + response.status);
+      }
+      
+      const data = await response.json();
+      
+      if (data.products && data.products.length > 0) {
+        renderProducts(data.products);
+      } else {
+        container.innerHTML = `<div class="no-results">${translations.noResults}</div>`;
+      }
+    } catch (error) {
+      console.error('加载推荐商品失败:', error);
+      container.innerHTML = `<div class="error">${translations.error}</div>`;
+    }
+  }
+
+  {% comment %} 渲染商品列表 {% endcomment %}
+  function renderProducts(products) {
+    const container = document.getElementById('recommend-products');
+    
+    const html = products.map(product => {
+      const imageUrl = product.image_url || product.image || '/assets/no-image.png';
+      const productUrl = product.url || product.handle || '#';
+      const price = formatPrice(product.price || product.price_formatted || '0.00');
+      
+      return `
+        <div class="product-item" data-product-id="${product.id}">
+          <a href="${productUrl}" class="product-link">
+            <div class="product-image-wrapper">
+              <img 
+                src="${imageUrl}" 
+                alt="${escapeHtml(product.title || product.name || '未知商品')}"
+                class="product-image"
+                onerror="this.src='/assets/no-image.png'"
+              />
+            </div>
+            <div class="product-info">
+              <h3 class="product-title">${escapeHtml(product.title || product.name || '未知商品')}</h3>
+              <div class="product-price">${price}</div>
+              ${product.vendor ? `<div class="product-vendor">${escapeHtml(product.vendor)}</div>` : ''}
+            </div>
+          </a>
+          <button class="add-to-cart-btn" onclick="addToCart('${product.id}')">
+            ${translations.addToCart}
+          </button>
+        </div>
+      `;
+    }).join('');
+    
+    container.innerHTML = html;
+  }
+
+  {% comment %} 工具函数：转义 HTML {% endcomment %}
+  function escapeHtml(text) {
+    const div = document.createElement('div');
+    div.textContent = text;
+    return div.innerHTML;
+  }
+
+  {% comment %} 工具函数：格式化价格 {% endcomment %}
+  function formatPrice(price) {
+    if (typeof price === 'number') {
+      return '¥' + price.toFixed(2);
+    }
+    if (typeof price === 'string') {
+      const num = parseFloat(price);
+      if (!isNaN(num)) {
+        return '¥' + num.toFixed(2);
+      }
+    }
+    return price || '¥0.00';
+  }
+
+  {% comment %} 添加到购物车（示例）{% endcomment %}
+  window.addToCart = function(productId) {
+    console.log('添加到购物车:', productId);
+    // 实现添加到购物车逻辑
+  };
+
+  {% comment %} 初始化 {% endcomment %}
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', loadRecommendations);
+  } else {
+    loadRecommendations();
+  }
+})();
+</script>
+
+{% comment %} Schema 配置（用于主题编辑器）{% endcomment %}
+{% schema %} 
+{
+  "name": {
+    "en-US": "recommend(dev)",
+    "zh-CN": "智能推荐(开发)"
+  },
+  "settings": [
+    {
+      "type": "text",
+      "id": "title",
+      "label": {
+        "en-US": "Title",
+        "zh-CN": "标题"
+      },
+      "default": {
+        "en-US": "Recommended Products",
+        "zh-CN": "推荐商品"
+      }
+    },
+    {
+      "type": "range",
+      "id": "product_count",
+      "label": {
+        "en-US": "Number of products",
+        "zh-CN": "商品数量"
+      },
+      "min": 4,
+      "max": 20,
+      "step": 1,
+      "default": 8
+    }
+  ]
+}
+{% endschema %}
+```
+
+### 步骤 4.2：创建样式文件
+
+#### 4.2.1 extensions/recommend/assets/recommend.css
+
+```css
+/* 推荐商品容器 */
+.recommend-container {
+  width: 100%;
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 20px;
+  font-family: var(--font-body-family, sans-serif);
+  color: var(--color-text, #333);
+  background: var(--color-background, #fff);
+}
+
+/* 版本标识（开发测试用）*/
+.recommend-badge {
+  position: fixed;
+  top: 10px;
+  right: 10px;
+  background: #ff6b6b;
+  color: white;
+  padding: 5px 10px;
+  border-radius: 4px;
+  font-size: 12px;
+  font-weight: bold;
+  z-index: 9999;
+  box-shadow: 0 2px 4px rgba(0,0,0,0.2);
+}
+
+/* 标题 */
+.recommend-container h2 {
+  font-size: 24px;
+  font-weight: 600;
+  margin-bottom: 20px;
+  text-align: center;
+}
+
+/* 商品网格 */
+.recommend-products {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+  gap: 20px;
+  margin-top: 20px;
+}
+
+/* 商品项 */
+.product-item {
+  border: 1px solid var(--color-border, #e0e0e0);
+  border-radius: 8px;
+  overflow: hidden;
+  transition: transform 0.2s, box-shadow 0.2s;
+  background: var(--color-background, #fff);
+}
+
+.product-item:hover {
+  transform: translateY(-4px);
+  box-shadow: 0 4px 12px rgba(0,0,0,0.1);
+}
+
+/* 商品链接 */
+.product-link {
+  text-decoration: none;
+  color: inherit;
+  display: block;
+}
+
+/* 商品图片 */
+.product-image-wrapper {
+  width: 100%;
+  padding-top: 100%; /* 1:1 比例 */
+  position: relative;
+  overflow: hidden;
+  background: #f5f5f5;
+}
+
+.product-image {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+/* 商品信息 */
+.product-info {
+  padding: 12px;
+}
+
+.product-title {
+  font-size: 14px;
+  font-weight: 500;
+  margin: 0 0 8px 0;
+  line-height: 1.4;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+.product-price {
+  font-size: 16px;
+  font-weight: 600;
+  color: var(--color-price, #e74c3c);
+  margin-bottom: 4px;
+}
+
+.product-vendor {
+  font-size: 12px;
+  color: var(--color-text-secondary, #999);
+}
+
+/* 添加到购物车按钮 */
+.add-to-cart-btn {
+  width: 100%;
+  padding: 10px;
+  background: var(--color-button, #007bff);
+  color: white;
+  border: none;
+  border-radius: 4px;
+  font-size: 14px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: background 0.2s;
+}
+
+.add-to-cart-btn:hover {
+  background: var(--color-button-hover, #0056b3);
+}
+
+/* 加载状态 */
+.loading {
+  text-align: center;
+  padding: 40px;
+  color: var(--color-text-secondary, #999);
+}
+
+/* 无结果 */
+.no-results {
+  text-align: center;
+  padding: 40px;
+  color: var(--color-text-secondary, #999);
+}
+
+/* 错误状态 */
+.error {
+  text-align: center;
+  padding: 40px;
+  color: var(--color-error, #e74c3c);
+}
+
+/* 响应式设计 */
+@media (max-width: 749px) {
+  .recommend-container {
+    padding: 10px;
+  }
+  
+  .recommend-products {
+    grid-template-columns: repeat(2, 1fr);
+    gap: 10px;
+  }
+  
+  .recommend-container h2 {
+    font-size: 20px;
+  }
+}
+
+@media (min-width: 750px) and (max-width: 989px) {
+  .recommend-products {
+    grid-template-columns: repeat(3, 1fr);
+  }
+}
+
+@media (min-width: 990px) {
+  .recommend-products {
+    grid-template-columns: repeat(4, 1fr);
+  }
+}
+```
+
+### 步骤 4.3：创建多语言文件
+
+#### 4.3.1 extensions/recommend/locales/zh-CN.json
+
+```json
+{
+  "recommend": {
+    "title": "为您推荐",
+    "loading": "加载中，请稍候...",
+    "no_results": "暂无推荐商品",
+    "error": "加载失败，请重试",
+    "add_to_cart": "加入购物车",
+    "view_details": "查看详情"
+  }
+}
+```
+
+#### 4.3.2 extensions/recommend/locales/en-US.json
+
+```json
+{
+  "recommend": {
+    "title": "Recommended for You",
+    "loading": "Loading, please wait...",
+    "no_results": "No recommended products",
+    "error": "Failed to load, please try again",
+    "add_to_cart": "Add to Cart",
+    "view_details": "View Details"
+  }
+}
+```
+
+#### 4.3.3 支持的语言列表
+
+店匠支持 16 种语言，建议至少提供以下语言文件：
+
+| 语言代码 | 语言名称 | 文件路径 |
+|---------|---------|---------|
+| `zh-CN` | 中文（简体） | `locales/zh-CN.json` |
+| `zh-TW` | 中文（繁体） | `locales/zh-TW.json` |
+| `en-US` | 英语 | `locales/en-US.json` |
+| `ja-JP` | 日语 | `locales/ja-JP.json` |
+| `ko-KR` | 韩语 | `locales/ko-KR.json` |
+
+**完整语言列表**：参考 [多语言支持文档](#多语言支持)
+
+### 步骤 4.4：Lessjs 集成（可选）
+
+Lessjs 是店匠官方提供的前端组件库，基于 Web Components。如需使用，参考：
+
+- [Lessjs 官方文档](https://lessjs.shoplazza.com/latest/docs/introduction/)
+- [Lessjs 自定义组件文档](https://lessjs.shoplazza.com/latest/docs/custom-component/)
+
+**注意**：对于简单的推荐组件，可以不使用 Lessjs，直接使用原生 JavaScript 和 CSS。
+
+---
+
+## 阶段 5：测试与部署
+
+### 步骤 5.1：本地测试
+
+#### 5.1.1 检查项目结构
+
+```bash
+cd /home/tw/saas/shoplazza-recommend-app
+
+# 检查文件结构
+tree -L 3
+
+# 应该看到：
+# shoplazza-recommend-app/
+# ├── package.json
+# ├── shoplazza.app.toml
+# └── extensions/
+#     └── recommend/
+#         ├── shoplazza.extension.toml
+#         ├── blocks/
+#         ├── assets/
+#         └── locales/
+```
+
+#### 5.1.2 验证配置
+
+```bash
+# 查看应用信息
+npm run info
+
+# 应该显示：
+# - App Name: 智能推荐1.0
+# - Client ID: x3apOQkj98Aij61BKi1TJ9q6wyfY3HrbmUZJ5FPfSbY
+# - Extension ID: 580182366958388163
+```
+
+### 步骤 5.2：部署到店匠
+
+#### 5.2.1 登录 Shoplazza CLI
+
+```bash
+# 登录（如果未登录）
+shoplazza login
+
+# 输入 Partner 账号和密码
+```
+
+#### 5.2.2 部署应用
+
+```bash
+# 部署应用
+npm run deploy
+
+# 或者
+shoplazza app deploy
+```
+
+**部署过程**：
+1. CLI 会验证项目配置
+2. 上传扩展文件到店匠服务器
+3. 返回部署结果
+
+### 步骤 5.3：在测试店铺中安装
+
+#### 5.3.1 访问应用市场
+
+1. 登录测试店铺后台
+2. 进入 **应用市场** 或 **Apps**
+3. 搜索您的应用名称（如"智能推荐1.0"）
+4. 点击 **安装** 或 **Install**
+
+#### 5.3.2 OAuth 授权流程
+
+1. 点击安装后，会跳转到您的后端服务（APP URL）
+2. 后端验证 HMAC 和 shop 参数
+3. 重定向到店匠授权页面
+4. 商家点击"授权"
+5. 店匠回调您的后端（Redirect URL）
+6. 后端用 code 换取 access_token
+7. 显示安装成功页面
+
+#### 5.3.3 在主题中添加扩展
+
+1. 进入店铺后台：**在线商店** > **主题** > **自定义**
+2. 在页面中添加 **App 扩展**
+3. 选择 **智能推荐** 扩展
+4. 配置扩展设置（如商品数量）
+5. 保存并发布
+
+### 步骤 5.4：验证功能
+
+#### 5.4.1 前端验证
+
+- [ ] 扩展正确显示在主题编辑器中
+- [ ] 商品列表正确加载
+- [ ] 多语言切换正常
+- [ ] 响应式布局在不同设备上正常
+- [ ] 图片加载正常（包括错误处理）
+
+#### 5.4.2 后端验证
+
+- [ ] OAuth 授权流程正常
+- [ ] HMAC 验证正常
+- [ ] Token 正确保存到数据库
+- [ ] API 调用正常（如获取商品列表）
+
+#### 5.4.3 浏览器控制台检查
+
+打开浏览器开发者工具（F12），检查：
+
+- **Console**：无 JavaScript 错误
+- **Network**：API 请求正常（状态码 200）
+- **Elements**：HTML 结构正确
+
+---
+
+## 常见问题与最佳实践
+
+### 常见问题
+
+#### Q1: HMAC 验证失败
+
+**原因**：
+- Client Secret 配置错误
+- 参数排序不正确
+- HMAC 计算方式错误
+
+**解决方案**：
+1. 确认 `CLIENT_SECRET` 与 Partner 后台一致
+2. 确保参数按字典顺序排序
+3. 使用 `HMAC-SHA256` 算法
+
+#### Q2: 多语言不生效
+
+**原因**：
+- 语言文件路径错误
+- 翻译键名不匹配
+- Liquid 模板语法错误
+
+**解决方案**：
+1. 确认 `locales/{locale}.json` 文件存在
+2. 检查翻译键名是否与模板中的 `{{ 'key' | t }}` 一致
+3. 使用 `{{ shop.locale }}` 获取当前语言
+
+#### Q3: 扩展在主题编辑器中不显示
+
+**原因**：
+- Extension ID 配置错误
+- 部署未成功
+- Schema 配置错误
+
+**解决方案**：
+1. 确认 `shoplazza.extension.toml` 中的 `id` 正确
+2. 重新部署应用：`npm run deploy`
+3. 检查 `{% schema %}` 配置是否正确
+
+#### Q4: API 调用返回 401 未授权
+
+**原因**：
+- Access Token 过期
+- Token 未正确传递
+- API 版本不匹配
+
+**解决方案**：
+1. 使用 `refresh_token` 刷新 Access Token
+2. 确认请求头包含 `Access-Token: {access_token}`
+3. 检查 API 版本（如 `/openapi/2022-01/`）
+
+### 最佳实践
+
+#### 1. 安全性
+
+- ✅ **始终验证 HMAC**：所有来自店匠的请求都必须验证 HMAC
+- ✅ **验证 shop 参数**：确保 shop 以 `.myshoplaza.com` 结尾
+- ✅ **使用 HTTPS**：所有 API 调用必须使用 HTTPS
+- ✅ **保护 Client Secret**：不要将 Client Secret 提交到代码仓库
+
+#### 2. 性能优化
+
+- ✅ **延迟加载**：非关键资源使用 `defer` 或 `async`
+- ✅ **图片优化**：使用响应式图片和 CDN
+- ✅ **缓存策略**：合理使用浏览器缓存和 CDN 缓存
+- ✅ **代码分割**：将大型 JavaScript 拆分为多个模块
+
+#### 3. 用户体验
+
+- ✅ **加载状态**：显示加载中、错误、无结果等状态
+- ✅ **错误处理**：友好的错误提示和重试机制
+- ✅ **响应式设计**：适配移动端、平板、桌面端
+- ✅ **多语言支持**：至少支持中文和英语
+
+#### 4. 代码质量
+
+- ✅ **代码注释**：关键逻辑添加注释
+- ✅ **错误日志**：记录错误日志便于调试
+- ✅ **代码规范**：遵循项目代码规范
+- ✅ **版本控制**：使用 Git 进行版本管理
+
+---
+
+## 参考资源
+
+### 官方文档
+
+- [Shoplazza 开发者文档](https://www.shoplazza.dev/)
+- [Shoplazza CLI 文档](https://www.shoplazza.dev/docs/overview-3)
+- [Lessjs 官方文档](https://lessjs.shoplazza.com/latest/docs/introduction/)
+- [Liquid 模板语言](https://shopify.github.io/liquid/)
+
+### 社区支持
+
+- [Shoplazza 开发者社区](https://community.shoplazza.com/)
+- [GitHub Issues](https://github.com/your-org/shoplazza-recommend-app/issues)
+
+---
+
+## 附录
+
+### A. 完整项目结构
+
+```
+shoplazza-recommend-app/
+├── package.json                    # 项目配置
+├── shoplazza.app.toml              # APP 配置（Client ID）
+├── README.md                       # 项目说明
+├── .gitignore                      # Git 忽略文件
+├── SHOPLAZZA_APP_DEVELOPMENT_GUIDE.md  # 本指南
+└── extensions/
+    └── recommend/                  # 推荐扩展
+        ├── shoplazza.extension.toml # Extension 配置
+        ├── package.json            # Extension 配置
+        ├── blocks/                 # 组件块
+        │   └── recommend.liquid    # 主组件
+        ├── assets/                 # 静态资源
+        │   ├── recommend.css      # 样式文件
+        │   └── assets-manifest.json # 资源清单
+        ├── snippets/               # 代码片段
+        │   └── recommend.liquid    # 可复用片段
+        └── locales/               # 多语言文件
+            ├── zh-CN.json         # 简体中文
+            ├── zh-TW.json         # 繁体中文
+            ├── en-US.json         # 英语
+            ├── ja-JP.json         # 日语
+            └── ko-KR.json         # 韩语
+```
+
+### B. 配置文件模板
+
+#### B.1 shoplazza.app.toml
+
+```toml
+client_id = "YOUR_CLIENT_ID"
+scopes = "read_shop read_product read_customer"
+```
+
+#### B.2 shoplazza.extension.toml
+
+```toml
+id = "YOUR_EXTENSION_ID"
+name = "recommend"
+type = "theme"
+```
+
+### C. OAuth 流程时序图
+
+```
+商家 → 店匠平台 → 后端服务 → 店匠授权页 → 商家授权 → 后端服务 → 数据库
+  ↓        ↓          ↓            ↓           ↓          ↓         ↓
+安装   跳转APP URL  验证HMAC    重定向授权    点击授权   换取Token  保存配置
+```
+
+---
@@ -0,0 +1,648 @@
+# Shoplazza 应用开发指南：多语言支持与前端优化
+
+## 目录
+
+1. [多语言支持](#多语言支持)
+2. [前端优化与 Lessjs 集成](#前端优化与-lessjs-集成)
+3. [与店匠主题的适配](#与店匠主题的适配)
+
+---
+
+## 多语言支持
+
+### 1. 概述
+
+Shoplazza 应用支持 16 种语言，通过 Liquid 模板的 `t` 过滤器和 `shop.locale` 对象实现自动语言适配。
+
+### 2. 支持的语言列表
+
+根据 [Lessjs 文档](https://lessjs.shoplazza.com/latest/docs/introduction/)，Shoplazza 支持以下语言：
+
+| 语言代码 | 语言名称 | 示例文本 |
+|---------|---------|---------|
+| `ar-SA` | 阿拉伯语(沙特阿拉伯) | أضف إلى السلة |
+| `de-DE` | 德语 | In den Warenkorb legen |
+| `en-US` | 英语 | Add to cart |
+| `es-ES` | 西班牙语 | Añadir a la cesta |
+| `fr-FR` | 法语 | Ajouter au panier |
+| `id-ID` | 印度尼西亚语 | Masukkan ke keranjang |
+| `it-IT` | 意大利语 | Aggiungi al carrello |
+| `ja-JP` | 日语 | カートに追加 |
+| `ko-KR` | 韩语 | 카트에 추가하십시오 |
+| `nl-NL` | 荷兰语 | Voeg toe aan winkelkar |
+| `pl-PL` | 波兰语 | Dodaj do koszyka |
+| `pt-PT` | 葡萄牙语 | Adicionar ao carrinho |
+| `ru-RU` | 俄语 | Добавить в корзину |
+| `th-TH` | 泰语 | เพิ่มลงในรถเข็น |
+| `zh-CN` | 中文（简体中文） | 加入购物车 |
+| `zh-TW` | 中文（繁体中文） | 加入購物車 |
+
+### 3. 实现方式
+
+#### 3.1 目录结构
+
+```
+extensions/your-extension/
+├── blocks/
+│   └── your-block.liquid
+├── assets/
+│   └── your-block.css
+└── locales/
+    ├── zh-CN.json
+    ├── en-US.json
+    ├── ko-KR.json
+    ├── ja-JP.json
+    └── ... (其他语言文件)
+```
+
+#### 3.2 语言文件格式
+
+每个语言文件（如 `locales/zh-CN.json`）应包含完整的翻译键值对：
+
+```json
+{
+  "search": {
+    "placeholder": "搜索商品...",
+    "loading": "搜索中，请稍候...",
+    "no_results": "未找到相关商品",
+    "error": "搜索失败，请重试",
+    "results_count": "找到 {count} 个结果",
+    "sort_label": "排序：",
+    "sort_default": "默认排序",
+    "sort_price_asc": "价格：低到高",
+    "sort_price_desc": "价格：高到低",
+    "sort_newest": "最新上架",
+    "facet_category": "类目",
+    "facet_brand": "品牌",
+    "facet_tag": "标签",
+    "pagination_prev": "上一页",
+    "pagination_next": "下一页",
+    "out_of_stock": "缺货",
+    "unknown_product": "未知商品",
+    "enter_keyword": "请输入搜索关键词",
+    "searching": "搜索中..."
+  }
+}
+```
+
+#### 3.3 Liquid 模板中的使用
+
+##### 3.3.1 获取店铺语言
+
+```liquid
+{% comment %} 获取店铺当前语言 {% endcomment %}
+{{ shop.locale }}
+```
+
+##### 3.3.2 使用翻译过滤器
+
+在 HTML 属性中使用：
+
+```liquid
+<input 
+  type="text" 
+  placeholder="{{ 'search.placeholder' | t }}"
+  aria-label="{{ 'search.placeholder' | t }}"
+/>
+```
+
+在 HTML 内容中使用：
+
+```liquid
+<label>{{ 'search.sort_label' | t }}</label>
+```
+
+在 `<option>` 标签中使用（需要配合 JavaScript 确保正确显示）：
+
+```liquid
+<select id="sort-select">
+  <option value="" data-translation-key="sortDefault">
+    {{ 'search.sort_default' | t }}
+  </option>
+  <option value="min_price:asc" data-translation-key="sortPriceAsc">
+    {{ 'search.sort_price_asc' | t }}
+  </option>
+</select>
+```
+
+#### 3.4 JavaScript 中的多语言支持
+
+##### 3.4.1 将翻译传递给 JavaScript
+
+在 `<script>` 标签中，通过 Liquid 将翻译文本传递给 JavaScript：
+
+```javascript
+<script>
+(function() {
+  // 获取店铺语言
+  const shopLocale = "{{ shop.locale }}" || "zh-CN";
+  
+  // 翻译文本（通过 Liquid 的 t 过滤器获取）
+  const translations = {
+    placeholder: "{{ 'search.placeholder' | t }}",
+    loading: "{{ 'search.loading' | t }}",
+    noResults: "{{ 'search.no_results' | t }}",
+    error: "{{ 'search.error' | t }}",
+    resultsCount: "{{ 'search.results_count' | t }}",
+    // ... 更多翻译键
+  };
+  
+  // 工具函数：替换占位符
+  function translate(key, params) {
+    let text = translations[key] || key;
+    if (params) {
+      Object.keys(params).forEach(param => {
+        text = text.replace(`{${param}}`, params[param]);
+      });
+    }
+    return text;
+  }
+  
+  // 使用翻译
+  function showResults(total) {
+    const message = translate('resultsCount', { count: total });
+    document.getElementById('status').textContent = message;
+  }
+})();
+</script>
+```
+
+##### 3.4.2 处理动态内容翻译
+
+对于动态生成的内容（如排序下拉框），需要确保翻译正确显示：
+
+```javascript
+// 初始化排序下拉框文本（确保翻译正确显示）
+function initSortSelect() {
+  const sortSelect = document.getElementById('sort-select');
+  if (sortSelect) {
+    // 遍历所有选项，使用 JavaScript 设置文本
+    Array.from(sortSelect.options).forEach((option, index) => {
+      const translationKey = option.getAttribute('data-translation-key');
+      if (translationKey && translations[translationKey]) {
+        option.text = translations[translationKey];
+      }
+    });
+  }
+}
+
+// 在 DOM 加载完成后初始化
+document.addEventListener('DOMContentLoaded', function() {
+  initSortSelect();
+});
+```
+
+##### 3.4.3 翻译回退机制（可选）
+
+如果 Liquid 翻译失败，可以实现 JavaScript 回退机制：
+
+```javascript
+function checkAndLoadTranslations() {
+  const firstTranslation = translations.placeholder;
+  const isLikelyEnglish = firstTranslation === 'Search products...' || 
+                         firstTranslation === 'search.placeholder' ||
+                         firstTranslation === '';
+  
+  // 如果检测到可能是英语，且店铺语言不是英语，尝试加载正确的翻译
+  if (isLikelyEnglish && shopLocale && shopLocale !== 'en-US' && shopLocale !== 'en') {
+    const localeFile = `/extensions/your-extension/locales/${shopLocale}.json`;
+    fetch(localeFile)
+      .then(response => response.json())
+      .then(data => {
+        if (data && data.search) {
+          // 更新翻译对象
+          translations = {
+            ...translations,
+            placeholder: data.search.placeholder || translations.placeholder,
+            loading: data.search.loading || translations.loading,
+            // ... 更多翻译
+          };
+          
+          // 重新初始化UI
+          initSortSelect();
+        }
+      })
+      .catch(error => {
+        console.warn('Failed to load translation file:', error);
+      });
+  }
+}
+```
+
+### 4. 最佳实践
+
+1. **完整性**：确保所有语言文件包含相同的翻译键，避免缺失导致显示键名
+2. **占位符**：使用 `{count}` 等占位符支持动态内容，如 `"找到 {count} 个结果"`
+3. **命名规范**：使用有意义的键名，如 `search.placeholder` 而不是 `text1`
+4. **测试**：在不同语言环境下测试应用，确保所有文本正确显示
+5. **回退机制**：为关键翻译提供默认值，避免显示空白或键名
+
+---
+
+## 前端优化与 Lessjs 集成
+
+### 1. Lessjs 简介
+
+**Lessjs** 是 Shoplazza（店匠）官方提供的前端组件库，基于 **Web Components** 开发。它提供了：
+
+- 高性能页面构建能力
+- 现成的组件（轮播图、视频、瀑布流等）
+- 自定义组件支持
+- 与 Shoplazza 主题的深度集成
+
+**官方文档**：
+- [Lessjs 简介](https://lessjs.shoplazza.com/latest/docs/introduction/)
+- [自定义组件](https://lessjs.shoplazza.com/latest/docs/custom-component/)
+
+### 2. 引入 Lessjs
+
+#### 2.1 通过 CDN 引入
+
+在 Liquid 模板的 `<head>` 标签中引入 Lessjs：
+
+```liquid
+<head>
+  <meta charset="UTF-8">
+  <title>Your App</title>
+  
+  {% comment %} 引入 Lessjs {% endcomment %}
+  <script async crossorigin="anonymous" src="https://static.staticdj.com/cuttlefish/v1/spz.min.js"></script>
+  
+  {% comment %} Lessjs 加载前的样式（必须）{% endcomment %}
+  <style>
+    body {
+      -webkit-animation: -spz-start 8s steps(1,end) 0s 1 normal both;
+      -moz-animation: -spz-start 8s steps(1,end) 0s 1 normal both;
+      -ms-animation: -spz-start 8s steps(1,end) 0s 1 normal both;
+      animation: -spz-start 8s steps(1,end) 0s 1 normal both;
+    }
+    @-webkit-keyframes -spz-start {
+      from { visibility: hidden; }
+      to { visibility: visible; }
+    }
+    @-moz-keyframes -spz-start {
+      from { visibility: hidden; }
+      to { visibility: visible; }
+    }
+    @-ms-keyframes -spz-start {
+      from { visibility: hidden; }
+      to { visibility: visible; }
+    }
+    @-o-keyframes -spz-start {
+      from { visibility: hidden; }
+      to { visibility: visible; }
+    }
+    @keyframes -spz-start {
+      from { visibility: hidden; }
+      to { visibility: visible; }
+    }
+  </style>
+  <noscript>
+    <style>
+      body {
+        -webkit-animation: none;
+        -moz-animation: none;
+        -ms-animation: none;
+        animation: none;
+      }
+    </style>
+  </noscript>
+</head>
+```
+
+**重要要求**：
+1. 脚本必须带有 `async` 属性
+2. 必须包含上述 CSS 样式，用于在 Lessjs 加载前隐藏页面内容
+3. 必须包含 `<noscript>` 标签的样式回退
+
+#### 2.2 HTML lang 属性
+
+确保 HTML 的 `lang` 属性设置为支持的语言代码之一（见[支持的语言列表](#2-支持的语言列表)）：
+
+```liquid
+<html lang="{{ shop.locale | default: 'zh-CN' }}">
+```
+
+### 3. 创建自定义 Lessjs 组件
+
+#### 3.1 基础结构
+
+Lessjs 自定义组件基于 ES6 class，继承 `SPZ.BaseElement`：
+
+```liquid
+{% comment %} 使用自定义组件 {% endcomment %}
+<spz-custom-ai-search layout="container"></spz-custom-ai-search>
+
+{% comment %} 定义自定义组件 {% endcomment %}
+<spz-script layout="logic" type="application/javascript">
+  class SpzCustomAiSearch extends SPZ.BaseElement {
+    constructor(element) {
+      super(element);
+      // 初始化变量
+      this.searchQuery = '';
+      this.currentPage = 1;
+    }
+
+    isLayoutSupported(layout) {
+      // 支持的布局类型
+      return layout == SPZCore.Layout.CONTAINER;
+    }
+
+    buildCallback() {
+      // 构建回调：组件开始构建时触发，用于初始化
+      console.log('Component building...');
+    }
+
+    mountCallback() {
+      // 挂载回调：组件挂载完成后触发，用于数据请求
+      console.log('Component mounted, fetching data...');
+      this.performSearch();
+    }
+
+    unmountCallback() {
+      // 卸载回调：组件卸载前触发，用于清理
+      console.log('Component unmounting, cleaning up...');
+      // 移除事件监听器等
+    }
+
+    layoutCallback() {
+      // 布局回调：元素及子节点完全挂载完成，用于 DOM 操作
+      console.log('Layout complete, ready for DOM operations');
+    }
+  }
+
+  // 注册自定义组件
+  SPZ.defineElement('spz-custom-ai-search', SpzCustomAiSearch);
+</spz-script>
+```
+
+#### 3.2 命名规范
+
+- **组件名称**：必须以 `spz-custom-` 开头，如 `spz-custom-ai-search`
+- **私有变量/函数**：以 `_` 结尾，如 `this.searchQuery_`
+- **公共 API 方法**：不以 `_` 结尾，如 `this.performSearch()`
+
+#### 3.3 生命周期函数
+
+| 函数名 | 触发时机 | 用途 |
+|--------|---------|------|
+| `constructor` | 组件创建时 | 初始化变量，必须调用 `super(element)` |
+| `isLayoutSupported` | 布局检查时 | 返回组件支持的布局类型 |
+| `buildCallback` | 组件开始构建时 | 初始化工作 |
+| `mountCallback` | 组件挂载完成后 | 数据请求、API 调用 |
+| `unmountCallback` | 组件卸载前 | 清理事件监听、重置变量 |
+| `layoutCallback` | DOM 完全挂载后 | DOM 操作、事件绑定 |
+
+#### 3.4 this 对象
+
+自定义组件中的 `this` 对象提供以下属性和方法：
+
+| 属性/方法 | 说明 |
+|----------|------|
+| `this.element` | 当前组件 DOM 元素 |
+| `this.win` | window 对象 |
+| `this.getViewport()` | 获取 Viewport 服务（参考 [SPZServices 文档](https://lessjs.shoplazza.com/latest/docs/spz-services/)） |
+
+#### 3.5 完整示例：AI 搜索组件
+
+```liquid
+{% use "ai-search.css" %}
+
+<div id="ai-search" class="ai-search-container">
+  <spz-custom-ai-search layout="container">
+    <!-- 搜索框 -->
+    <form class="search-form" id="search-form">
+      <div class="search-input-wrapper">
+        <input 
+          type="text" 
+          id="search-input"
+          class="search-input" 
+          placeholder="{{ 'search.placeholder' | t }}"
+          autocomplete="off"
+        />
+        <button type="submit" class="search-button" id="search-button">
+          <svg class="search-icon" viewBox="0 0 24 24" width="20" height="20">
+            <path d="M15.5 14h-.79l-.28-.27C15.41 12.59 16 11.11 16 9.5 16 5.91 13.09 3 9.5 3S3 5.91 3 9.5 5.91 16 9.5 16c1.61 0 3.09-.59 4.23-1.57l.27.28v.79l5 4.99L20.49 19l-4.99-5zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"/>
+          </svg>
+        </button>
+      </div>
+    </form>
+    
+    <!-- 搜索结果容器 -->
+    <div class="search-results-container" id="search-results-container"></div>
+  </spz-custom-ai-search>
+</div>
+
+<spz-script layout="logic" type="application/javascript">
+  class SpzCustomAiSearch extends SPZ.BaseElement {
+    constructor(element) {
+      super(element);
+      this.apiEndpoint = 'https://saas-ai-api.essa.top/app-api/app/shoplazza/search/';
+      this.state = {
+        query: '',
+        currentPage: 1,
+        pageSize: 20
+      };
+    }
+
+    isLayoutSupported(layout) {
+      return layout == SPZCore.Layout.CONTAINER;
+    }
+
+    buildCallback() {
+      // 初始化翻译
+      this.shopLocale = "{{ shop.locale }}" || "zh-CN";
+      this.translations = {
+        placeholder: "{{ 'search.placeholder' | t }}",
+        loading: "{{ 'search.loading' | t }}",
+        noResults: "{{ 'search.no_results' | t }}",
+        // ... 更多翻译
+      };
+    }
+
+    mountCallback() {
+      // 绑定搜索表单事件
+      const form = this.element.querySelector('#search-form');
+      if (form) {
+        form.addEventListener('submit', (e) => this.handleSearch(e));
+      }
+    }
+
+    async handleSearch(event) {
+      event.preventDefault();
+      
+      const searchInput = this.element.querySelector('#search-input');
+      const query = searchInput.value.trim();
+      
+      if (!query) {
+        alert(this.translations.enterKeyword);
+        return;
+      }
+      
+      this.state.query = query;
+      this.state.currentPage = 1;
+      
+      await this.performSearch();
+    }
+
+    async performSearch() {
+      const resultsContainer = this.element.querySelector('#search-results-container');
+      resultsContainer.innerHTML = `<div class="loading">${this.translations.loading}</div>`;
+      
+      try {
+        const response = await fetch(this.apiEndpoint, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            query: this.state.query,
+            size: this.state.pageSize,
+            from: (this.state.currentPage - 1) * this.state.pageSize
+          })
+        });
+        
+        const data = await response.json();
+        this.renderResults(data);
+      } catch (error) {
+        resultsContainer.innerHTML = `<div class="error">${this.translations.error}</div>`;
+      }
+    }
+
+    renderResults(data) {
+      const resultsContainer = this.element.querySelector('#search-results-container');
+      // 渲染搜索结果...
+    }
+
+    unmountCallback() {
+      // 清理工作
+    }
+  }
+
+  SPZ.defineElement('spz-custom-ai-search', SpzCustomAiSearch);
+</spz-script>
+```
+
+### 4. 使用 Lessjs 的优势
+
+1. **性能优化**：Lessjs 基于 Web Components，提供更好的性能
+2. **主题集成**：与 Shoplazza 主题深度集成，样式更统一
+3. **组件复用**：可以使用 Lessjs 提供的现成组件（轮播图、视频等）
+4. **标准化**：遵循 Shoplazza 的开发规范，减少兼容性问题
+
+---
+
+## 与店匠主题的适配
+
+### 1. 样式适配
+
+#### 1.1 使用主题变量
+
+尽可能使用 Shoplazza 主题提供的 CSS 变量：
+
+```css
+/* 使用主题颜色变量 */
+.ai-search-container {
+  color: var(--color-text, #333);
+  background: var(--color-background, #fff);
+  border-color: var(--color-border, #e0e0e0);
+}
+
+/* 使用主题字体变量 */
+.ai-search-container {
+  font-family: var(--font-body-family, sans-serif);
+  font-size: var(--font-body-size, 14px);
+}
+```
+
+#### 1.2 响应式设计
+
+遵循 Shoplazza 的响应式断点：
+
+```css
+/* 移动端 */
+@media (max-width: 749px) {
+  .ai-search-container {
+    padding: 10px;
+  }
+}
+
+/* 平板 */
+@media (min-width: 750px) and (max-width: 989px) {
+  .ai-search-container {
+    padding: 20px;
+  }
+}
+
+/* 桌面端 */
+@media (min-width: 990px) {
+  .ai-search-container {
+    padding: 30px;
+  }
+}
+```
+
+### 2. 功能适配
+
+#### 2.1 使用 Shoplazza 全局对象
+
+在 JavaScript 中，可以使用 Shoplazza 提供的全局对象：
+
+```javascript
+// 访问店铺信息
+const shopDomain = window.Shopify?.shop || "{{ shop.domain }}";
+const shopLocale = window.Shopify?.locale || "{{ shop.locale }}";
+
+// 使用 Shoplazza 的工具函数（如果可用）
+if (window.Shoplazza?.utils) {
+  // 使用工具函数
+}
+```
+
+#### 2.2 事件处理
+
+遵循 Shoplazza 的事件处理规范：
+
+```javascript
+// 使用事件委托，提高性能
+document.addEventListener('click', (e) => {
+  if (e.target.closest('.search-button')) {
+    handleSearch(e);
+  }
+});
+
+// 避免直接操作 DOM，使用 Lessjs 组件生命周期
+```
+
+### 3. 性能优化建议
+
+1. **延迟加载**：非关键资源使用 `defer` 或 `async`
+2. **图片优化**：使用 Shoplazza 的图片 CDN 和响应式图片
+3. **代码分割**：将大型 JavaScript 拆分为多个模块
+4. **缓存策略**：合理使用浏览器缓存和 CDN 缓存
+
+### 4. 测试清单
+
+- [ ] 在不同语言环境下测试多语言显示
+- [ ] 在不同设备上测试响应式布局
+- [ ] 测试与不同 Shoplazza 主题的兼容性
+- [ ] 测试 Lessjs 组件的加载和渲染
+- [ ] 测试 API 调用的错误处理
+- [ ] 测试页面加载性能
+
+---
+
+## 总结
+
+1. **多语言支持**：使用 Liquid 的 `t` 过滤器和 `shop.locale`，确保所有语言文件完整
+2. **Lessjs 集成**：使用 Lessjs 自定义组件提升性能和主题适配
+3. **主题适配**：使用主题变量和响应式设计，确保与店匠主题良好集成
+
+遵循以上指南，可以开发出高质量、高性能、多语言支持的 Shoplazza 应用。
+
+---
+
+## 参考资源
+
+- [Lessjs 官方文档](https://lessjs.shoplazza.com/latest/docs/introduction/)
+- [Lessjs 自定义组件文档](https://lessjs.shoplazza.com/latest/docs/custom-component/)
+- [Shoplazza 开发者文档](https://www.shoplazza.dev/)
+
@@ -158,7 +158,7 @@ sku全部字段
 商品信息：品名、颜色、尺码，基本上就这三个信息
  
  
-### 分类
+### 分类prefixQuery
 最多三级分类，商品可以指向任何级别的分类
 Field	Type
 category	varchar(255)
@@ -0,0 +1,168 @@
+# 索引重构v2方案
+
+## 概述
+
+根据 `索引字段说明v2.md` 的要求重构Elasticsearch索引映射结构和MySQL到ES的数据导入脚本。
+
+## 主要变更点
+
+### 1. 索引映射结构重构
+
+#### 1.1 多语言文本字段
+
+- 为文本字段添加中英文双字段支持（title_zh/title_en, brief_zh/brief_en, description_zh/description_en, vendor_zh/vendor_en）
+- 中文字段使用 `index_ansj`/`query_ansj` 分析器（对应文档中的hanlp_index/hanlp_standard）
+- 英文字段使用 `english` 分析器
+- **暂时只填充中文字段，英文字段设为空**（不需要语言检测，每个tenant的语言预先知道）
+
+#### 1.2 分类字段多层级支持
+
+类别数据源：
+在spu表中：
+Field Type
+category  varchar(255)
+category_id bigint(20)
+category_google_id  bigint(20)
+category_level  int(11)
+category_path varchar(500)
+
+mapping：
+
+      "category_path_zh": { // 提供模糊查询功能，辅助相关性计算
+        "type": "text",
+        "analyzer": "hanlp_index",
+        "search_analyzer": "hanlp_standard"
+      },
+      "category_path_en": {  // 提供模糊查询功能，辅助相关性计算
+        "type": "text",
+        "analyzer": "english",
+        "search_analyzer": "english"
+      },
+      "category_name_zh": { // 提供模糊查询功能，辅助相关性计算
+        "type": "text",
+        "analyzer": "hanlp_index",
+        "search_analyzer": "hanlp_standard"
+      },
+      "category_name_en": {  // 提供模糊查询功能，辅助相关性计算
+        "type": "text",
+        "analyzer": "english",
+        "search_analyzer": "english"
+      },
+
+      "category_id": {
+        "type": "keyword"
+      },
+      "category_name": {
+        "type": "keyword"
+      },
+      "category_level": {
+        "type": "integer"
+      },
+      "category1_name": { // 不同层级下 可能有同名的情况，因此提供一二三级分开的查询方式
+        "type": "keyword"
+      },
+      "category2_name": {
+        "type": "keyword"
+      },
+      "category3_name": {
+        "type": "keyword"
+      },
+
+
+#### 1.3 SKU字段展开
+
+- 添加 `sku_prices` (float数组) - 所有SKU价格列表
+- 添加 `sku_weights` (long数组) - 重量数值列表（转换为整数克）
+- 添加 `sku_weight_units` (keyword数组) - 重量+单位字符串列表
+- 添加 `total_inventory` (long) - SKU库存总和
+- 保留 `min_price`, `max_price` (float)
+
+#### 1.4 选项字段处理
+
+- 添加 `option1_name`, `option2_name`, `option3_name` (keyword) - SPU级别的选项名称定义
+- 修改SKU嵌套结构：将 `options` 对象改为 `option1_value`, `option2_value`, `option3_value` (keyword)
+- 添加 `specifications` (nested, index=false) - 动态属性，仅用于返回
+
+#### 1.5 标签字段
+
+- `tags` 改为 keyword 数组类型（分割逗号分隔的字符串）
+
+#### 1.6 SKU嵌套结构更新
+
+- 添加 `sku_code` (keyword) 字段
+- 添加 `weight` (float), `weight_unit` (keyword)
+- 将 `options` 对象改为 `option1_value`, `option2_value`, `option3_value`
+- 添加 `image_src` (keyword, index=false)
+
+#### 1.7 删除SEO字段
+
+- **完全删除** `seo_title`, `seo_description`, `seo_keywords` 字段
+- 从索引映射中移除
+- 从数据转换脚本中移除相关处理
+
+### 2. 数据转换脚本重构
+
+#### 2.1 多语言文本处理
+
+- **简化处理**：暂时只填充中文字段（title_zh, brief_zh, description_zh, vendor_zh）
+- 英文字段（title_en, brief_en, description_en, vendor_en）设为空或None
+- 不需要语言检测逻辑
+
+#### 2.2 分类路径解析
+
+- 从 `category_path` 字段按 "/" 分割提取分类层级
+- 分割结果赋值给 `category1_name`, `category2_name`, `category3_name`
+- 生成 `category_path_zh`（暂时填充，`category_path_en` 设为空）
+
+#### 2.3 SKU字段展开计算
+
+- 提取所有SKU的价格，生成 `sku_prices` 数组
+- 提取所有SKU的重量，转换为克（乘以1000），生成 `sku_weights` 数组
+- 生成 `sku_weight_units` 数组（格式："重量值单位"）
+- 计算所有SKU库存总和，赋值给 `total_inventory`
+- 计算 `min_price` 和 `max_price`
+
+#### 2.4 选项字段处理
+
+- SPU级别的选项名称：需要从SPU数据或SKU数据推断（如果SPU表中没有，需要查看是否有选项表）
+- SKU级别的选项值：从SKU的 `option1`, `option2`, `option3` 字段提取
+- 生成 `specifications` 嵌套数组（从选项名称和值对生成）
+
+#### 2.5 标签处理
+
+- `tags` 字段按逗号分割转换为数组
+
+#### 2.6 删除SEO字段处理
+
+- **完全移除** seo_title, seo_description, seo_keywords 相关代码
+
+## 实施步骤
+
+### 步骤1：修改索引映射生成器
+
+**文件**: `indexer/mapping_generator.py` 和相关字段配置
+
+- 更新 `get_es_mapping_for_field` 函数以支持多语言字段
+- 添加分类字段的完整映射生成逻辑
+- 添加SKU展开字段的映射
+- 添加选项字段的映射
+- **删除SEO字段的映射生成**
+
+### 步骤2：重构数据转换脚本
+
+**文件**: `indexer/spu_transformer.py`
+
+- **简化多语言处理**：只填充中文字段（title_zh, brief_zh等），英文字段设为空或None
+- 实现分类路径的解析和展开
+- 实现SKU字段的展开计算（价格、重量、库存）
+- 实现选项字段的处理
+- 更新SKU嵌套结构的生成
+- 处理标签的分割
+- **删除所有SEO字段相关代码**
+
+### 步骤3：更新配置文件
+
+**文件**: `config/config.yaml`
+
+- **删除SEO字段配置**：移除 seo_title, seo_description, seo_keywords 的字段定义
+- 可能需要添加新字段的配置定义，或者直接在代码中生成映射（如果配置系统不支持这些复杂字段）
 \ No newline at end of file
@@ -0,0 +1,81 @@
+spu表全部字段
+"Field"	"Type"	"Null"	"Key"	"Default"	"Extra"
+"id"	"bigint(20)"	"NO"	"PRI"		"auto_increment"
+"shop_id"	"bigint(20)"	"NO"	"MUL"		""
+"shoplazza_id"	"varchar(64)"	"NO"	""		""
+"handle"	"varchar(255)"	"YES"	"MUL"		""
+"title"	"varchar(500)"	"NO"	""		""
+"brief"	"varchar(1000)"	"YES"	""		""
+"description"	"text"	"YES"	""		""
+"spu"	"varchar(100)"	"YES"	""		""
+"vendor"	"varchar(255)"	"YES"	""		""
+"vendor_url"	"varchar(500)"	"YES"	""		""
+"seo_title"	"varchar(500)"	"YES"	""		""
+"seo_description"	"text"	"YES"	""		""
+"seo_keywords"	"text"	"YES"	""		""
+"image_src"	"varchar(500)"	"YES"	""		""
+"image_width"	"int(11)"	"YES"	""		""
+"image_height"	"int(11)"	"YES"	""		""
+"image_path"	"varchar(255)"	"YES"	""		""
+"image_alt"	"varchar(500)"	"YES"	""		""
+"inventory_policy"	"varchar(50)"	"YES"	""		""
+"inventory_quantity"	"int(11)"	"YES"	""	"0"	""
+"inventory_tracking"	"tinyint(1)"	"YES"	""	"0"	""
+"published"	"tinyint(1)"	"YES"	""	"0"	""
+"published_at"	"datetime"	"YES"	"MUL"		""
+"requires_shipping"	"tinyint(1)"	"YES"	""	"1"	""
+"taxable"	"tinyint(1)"	"YES"	""	"0"	""
+"fake_sales"	"int(11)"	"YES"	""	"0"	""
+"display_fake_sales"	"tinyint(1)"	"YES"	""	"0"	""
+"mixed_wholesale"	"tinyint(1)"	"YES"	""	"0"	""
+"need_variant_image"	"tinyint(1)"	"YES"	""	"0"	""
+"has_only_default_variant"	"tinyint(1)"	"YES"	""	"0"	""
+"tags"	"text"	"YES"	""		""
+"note"	"text"	"YES"	""		""
+"category"	"varchar(255)"	"YES"	""		""
+"category_id"	"bigint(20)"	"YES"	""		""
+"category_google_id"	"bigint(20)"	"YES"	""		""
+"category_level"	"int(11)"	"YES"	""		""
+"category_path"	"varchar(500)"	"YES"	""		""
+"shoplazza_created_at"	"datetime"	"YES"	""		""
+"shoplazza_updated_at"	"datetime"	"YES"	"MUL"		""
+"tenant_id"	"bigint(20)"	"NO"	"MUL"		""
+"creator"	"varchar(64)"	"YES"	""	""	""
+"create_time"	"datetime"	"NO"	""	"CURRENT_TIMESTAMP"	""
+"updater"	"varchar(64)"	"YES"	""	""	""
+"update_time"	"datetime"	"NO"	""	"CURRENT_TIMESTAMP"	"on update CURRENT_TIMESTAMP"
+"deleted"	"bit(1)"	"NO"	""	"b'0'"	""
+
+sku全部字段
+"Field"	"Type"	"Null"	"Key"	"Default"	"Extra"
+"id"	"bigint(20)"	"NO"	"PRI"		"auto_increment"
+"spu_id"	"bigint(20)"	"NO"	"MUL"		""
+"shop_id"	"bigint(20)"	"NO"	"MUL"		""
+"shoplazza_id"	"varchar(64)"	"NO"	""		""
+"shoplazza_product_id"	"varchar(64)"	"NO"	"MUL"		""
+"shoplazza_image_id"	"varchar(64)"	"YES"	""		""
+"title"	"varchar(500)"	"YES"	""		""
+"sku"	"varchar(100)"	"YES"	"MUL"		""
+"barcode"	"varchar(100)"	"YES"	""		""
+"position"	"int(11)"	"YES"	""	"0"	""
+"price"	"decimal(10,2)"	"YES"	""		""
+"compare_at_price"	"decimal(10,2)"	"YES"	""		""
+"cost_price"	"decimal(10,2)"	"YES"	""		""
+"option1"	"varchar(255)"	"YES"	""		""
+"option2"	"varchar(255)"	"YES"	""		""
+"option3"	"varchar(255)"	"YES"	""		""
+"inventory_quantity"	"int(11)"	"YES"	""	"0"	""
+"weight"	"decimal(10,2)"	"YES"	""		""
+"weight_unit"	"varchar(10)"	"YES"	""		""
+"image_src"	"varchar(500)"	"YES"	""		""
+"wholesale_price"	"json"	"YES"	""		""
+"note"	"text"	"YES"	""		""
+"extend"	"json"	"YES"	""		""
+"shoplazza_created_at"	"datetime"	"YES"	""		""
+"shoplazza_updated_at"	"datetime"	"YES"	""		""
+"tenant_id"	"bigint(20)"	"NO"	"MUL"		""
+"creator"	"varchar(64)"	"YES"	""	""	""
+"create_time"	"datetime"	"NO"	""	"CURRENT_TIMESTAMP"	""
+"updater"	"varchar(64)"	"YES"	""	""	""
+"update_time"	"datetime"	"NO"	""	"CURRENT_TIMESTAMP"	"on update CURRENT_TIMESTAMP"
+"deleted"	"bit(1)"	"NO"	""	"b'0'"	""
@@ -0,0 +1,358 @@
+SPU-SKU索引方案选型
+1. spu为单位。SKU字段展开作为SPU属性
+1.1 索引方案
+除了title， brielf description seo相关  cate tags vendor所有影响相关性的字段都在spu。 sku只有款式、价格、重量、库存等相关属性。所以，可以以spu为单位建立索引。
+sku中需要参与搜索的属性（比如价格、库存）展开到spu。
+sku的所有需要返回的字段作为nested字段，仅用于返回。
+灌入数据准备
+def build_product_document(product, skus):
+    # 提取价格列表（转换为float，保留两位小数）
+    price_list = [float(sku.price) for sku in skus if sku.price is not None]
+    
+    # 提取重量信息（重量转为int，单位统一为克；重量+单位拼接为字符串）
+    weight_list = [int(float(sku.weight) * 1000) for sku in skus if sku.weight is not None]  # 转为整数克
+    weight_with_unit_list = [f"{sku.weight}{sku.weight_unit}" for sku in skus if sku.weight and sku.weight_unit]
+    
+    # 计算库存总和
+    total_stock = sum([sku.inventory_quantity for sku in skus if sku.inventory_quantity is not None])
+    
+    # 计算价格区间
+    min_price = min(price_list) if price_list else 0.0
+    max_price = max(price_list) if price_list else 0.0
+    
+    return {
+        "spu_id": str(product.id),
+        "title": product.title,
+        
+        # SPU级别的选项名称定义（如：颜色、尺码、材质）
+        "option1_name": getattr(product, 'option1', None),
+        "option2_name": getattr(product, 'option2', None),
+        "option3_name": getattr(product, 'option3', None),
+        
+        # SKU搜索字段（展开）
+        # 价格（int）、重量（int）、重量单位拼接重量（keyword），都以list形式灌入
+        "sku_prices": price_list,  # 所有SKU价格列表，用于范围聚合
+        "sku_weights": weight_list,  # 重量数值列表（转换为整数克）
+        "sku_weight_units": weight_with_unit_list,  # 重量+单位字符串列表
+        
+        # 库存总和 将SKU的库存加起来作为一个值灌入
+        "total_inventory": total_stock,  # SKU库存总和
+        
+        # 售价，灌入3个字段：SKU价格列表、最高价、最低价
+        "min_price": min_price,  # 最低售价
+        "max_price": max_price,  # 最高售价
+        "price_range": {  # 价格区间对象，便于范围查询
+            "gte": min_price,
+            "lte": max_price
+        },
+        
+        # SKU详细信息（nested结构，仅用于返回）
+        "skus": [
+            {
+                "sku_id": str(sku.id),
+                "price": float(sku.price) if sku.price else 0.0,
+                "compare_at_price": float(sku.compare_at_price) if sku.compare_at_price else None,
+                "sku_code": sku.sku,
+                "stock": sku.inventory_quantity,
+                "weight": float(sku.weight) if sku.weight else None,
+                "weight_unit": sku.weight_unit,
+                
+                # SKU级别的选项值（对应SPU的选项名称）
+                "option1_value": sku.option1,
+                "option2_value": sku.option2,
+                "option3_value": sku.option3,
+                
+                "image_src": sku.image_src
+            }
+            for sku in skus
+        ],
+        
+        # 其他SPU级别字段（根据索引文档补充）
+        "tenant_id": str(product.tenant_id),
+        "brief": product.brief,
+        "description": product.description,
+        "vendor": product.vendor,
+        "category": product.category,
+        "tags": product.tags.split(',') if product.tags else [],
+        "seo_title": product.seo_title,
+        "seo_description": product.seo_description,
+        "seo_keywords": product.seo_keywords.split(',') if product.seo_keywords else [],
+        "image_url": product.image_src,
+        "create_time": product.create_time.isoformat() if product.create_time else None,
+        "update_time": product.update_time.isoformat() if product.update_time else None
+    }
+    索引定义
+{
+  "mappings": {
+    "properties": {
+      "tenant_id": {
+        "type": "keyword"
+      },
+      "spu_id": {
+        "type": "keyword"
+      },
+      // 文本相关性相关字段
+      "title_zh": {
+        "type": "text",
+        "analyzer": "hanlp_index",
+        "search_analyzer": "hanlp_standard"
+      },
+      "brief_zh": {
+        "type": "text",
+        "analyzer": "hanlp_index",
+        "search_analyzer": "hanlp_standard"
+      },
+      "description_zh": {
+        "type": "text",
+        "analyzer": "hanlp_index",
+        "search_analyzer": "hanlp_standard"
+      },
+      "vendor_zh": {
+        "type": "text",
+        "analyzer": "hanlp_index",
+        "search_analyzer": "hanlp_standard",
+        "fields": {
+          "keyword": {
+            "type": "keyword",
+            "normalizer": "lowercase"
+          }
+        }
+      },
+
+      "title_en": {
+        "type": "text",
+        "analyzer": "english",
+        "search_analyzer": "english",
+      },
+      "brief_en": {
+        "type": "text",
+        "analyzer": "english",
+        "search_analyzer": "english",
+
+      },
+      "description_en": {
+        "type": "text",
+        "analyzer": "english",
+        "search_analyzer": "english",
+      },
+      "vendor_en": {
+        "type": "text",
+        "analyzer": "english",
+        "search_analyzer": "english",
+        "fields": {
+          "keyword": {
+            "type": "keyword",
+            "normalizer": "lowercase"
+          }
+        }
+      },
+      
+      "tags": {
+        "type": "keyword",
+      },
+
+      
+      "min_price": {
+        "type": "float"
+      },
+      "max_price": {
+        "type": "float"
+      },
+      "compare_at_price": {
+        "type": "float"
+      },
+      "sku_prices": {
+        "type": "float"
+      },
+      "sku_weights": {
+        "type": "long"
+      },
+      "sku_weight_units": {
+        "type": "keyword"
+      },
+      "total_inventory": {
+        "type": "long"
+      },
+      
+      "image_url": {
+        "type": "keyword",
+        "index": false
+      },
+      
+      "title_embedding": {
+        "type": "dense_vector",
+        "dims": 1024,
+        "index": true,
+        "similarity": "dot_product"
+      },
+      
+      "create_time": {
+        "type": "date"
+      },
+      "update_time": {
+        "type": "date"
+      },
+      
+      "option1_name": {
+        "type": "keyword"
+      },
+      "option2_name": {
+        "type": "keyword"
+      },
+      "option3_name": {
+        "type": "keyword"
+      },
+      
+      "skus": {
+        "type": "nested",
+        "properties": {
+          "sku_id": {
+            "type": "keyword"
+          },
+          "price": {
+            "type": "float"
+          },
+          "compare_at_price": {
+            "type": "float"
+          },
+          "sku_code": {
+            "type": "keyword"
+          },
+          "stock": {
+            "type": "long"
+          },
+          "weight": {
+            "type": "float"
+          },
+          "weight_unit": {
+            "type": "keyword"
+          },
+          "option1_value": {
+            "type": "keyword"
+          },
+          "option2_value": {
+            "type": "keyword"
+          },
+          "option3_value": {
+            "type": "keyword"
+          },
+          "image_src": {
+            "type": "keyword",
+            "index": false
+          }
+        }
+      }
+    }
+  }
+}
+1.2 查询方案
+对数组字段使用 dis_max，只取最高分，避免累加。
+其他重点字段
+1. Sku title
+2. category
+2.1 Mysql
+在spu表中：
+Field Type
+category  varchar(255)
+category_id bigint(20)
+category_google_id  bigint(20)
+category_level  int(11)
+category_path varchar(500)
+2.2 ES索引
+2.2.1 输入数据
+  设计 1,2,3级分类 三个字段，的 category  （原始文本）
+2.2.2 索引方法
+  设计要求：
+  1. 支持facet（精确过滤、keyword聚合），并且性能需要足够高。
+  2. 支持普通搜索模糊匹配（用户原始query可能包括分类词）。
+  3. 模糊匹配要考虑多语言
+方案：采用方案2
+  1. categoryPath索引 + Prefix 查询（categoryPath.keyword: "服装/男装"）（如果满足条件的key太多的则性能较差，比如 查询的是一级类目，类目树叶子节点太多时性能较差）
+  2. categoryPath支撑模糊查询 和 多级cate keyword索引支撑精确查询。 索引阶段冗余，查询性能高。
+      "category_path_zh": { // 提供模糊查询功能，辅助相关性计算
+        "type": "text",
+        "analyzer": "hanlp_index",
+        "search_analyzer": "hanlp_standard"
+      },
+      "category_path_en": {  // 提供模糊查询功能，辅助相关性计算
+        "type": "text",
+        "analyzer": "english",
+        "search_analyzer": "english"
+      },
+      "category_path": {  // 用于多层级的筛选、精确匹配
+        "type": "keyword",
+        "normalizer": "lowercase"  
+      },
+      "category_id": {
+        "type": "keyword"
+      },
+      "category_name": {
+        "type": "keyword"
+      },
+      "category_level": {
+        "type": "integer"
+      },
+      "category1_name": { // 不同层级下 可能有同名的情况，因此提供一二三级分开的查询方式
+        "type": "keyword"
+      },
+      "category2_name": {
+        "type": "keyword"
+      },
+      "category3_name": {
+        "type": "keyword"
+      },
+
+3. tags
+3.1 数据源
+多值
+标签
+最多输入250个标签，每个不得超过500字符，多个标签请用「英文逗号」隔开
+新品,热卖,爆款
+耳机,头戴式,爆款
+
+分割后 list形式灌入
+3.2 Mysql
+3.3 ES索引
+3.3.1 输入数据
+3.3.2 索引方法
+4. 供应商
+4.1 数据源
+4.2 Mysql
+4.3 ES索引
+4.3.1 输入数据
+4.3.2 索引方法
+5. 款式/选项值（options）
+5.1 数据源
+以下区域字段，商品属性为M(商品主体)的行需填写款式名称，商品属性为P(子款式)的行需填写款式值信息，商品属性为S(单一款式商品)的行无需填写                
+款式1        款式2        款式3
+最多255字符        最多255字符        最多255字符
+SIZE        COLOR        
+S        red        
+...
+5.2 Mysql
+1. API 在 SPU 的维度直接返回3个属性定义，存储在 shoplazza_product_option 中：
+1. API在 SKU的维度直接返回3个属性值，存储在 shoplazza_product_sku 表的 option 相关的字段中：
+5.3 ES索引
+5.3.1 
+  3nested，支持超过3个属性（动态）。只用作返回，不能查询。节省索引空间
+  "specifications": {
+    "type": "nested",
+    "properties": {
+      "name": { "type": "keyword","index": false },
+      "value": { "type": "keyword","index": false }
+    }
+  },
+  
+6. SEO相关字段
+6.1 数据源
+SEO标题        SEO描述        SEO URL Handle        SEO URL 重定向        SEO关键词
+最多5000字符        最多5000字符        "最多支持输入255字符
+ （SEO URL handle只对SEO URL的「URL参数」部分进行更改，即“products/”后的内容，如：products/「URL参数」
+ ）"        "创建URL重定向，访问修改前链接可跳转到修改后的新链接页面
+「Y」:TRUE 
+「N」:FALSE "        多个关键词请用「英文逗号」隔开
+
+6.2 Mysql
+6.3 ES索引
+6.3.1 输入数据
+6.3.2 索引方法
 \ No newline at end of file