# Shop2LLM Free v1.1.1 技术文档 — Hero Test Search

## 1. 版本概要

- **版本号**：1.1.1
- **发布日期**：2026-07-02
- **代号**：Hero Test Search — ChatGPT-style Aha Moment
- **整改目标**：将 Test Search 从 Score 卡片隐藏按钮提升为 Dashboard 顶部 Hero 区块，集成 FinCore 云端 LLM 代理，实现 ChatGPT 风格的即时 AI 搜索预览

---

## 2. 改动清单（7 处）

| # | 改动 | 文件路径 | 行号范围 | 描述 |
|---|------|----------|----------|------|
| 1 | 版本号升级 1.1.0 → 1.1.1 | `shop-to-llm.php` | L16, L37 | 同步更新 Plugin Header `Version:` 与 `SHOP_TO_LLM_VERSION` 常量 |
| 2 | `shop_to_llm_handle_test_search()` 扩展 | `shop-to-llm.php` | L478–L534 | 本地配额计数（transient）+ 富产品字段（name/price/currency/in_stock/rating）+ AI 回复字段透传 |
| 3 | 新增 `shop_to_llm_generate_ai_test_reply()` | `shop-to-llm.php` | L536–L605 | FinCore 云端 LLM 代理调用，封装 `wp_remote_post` + 429 优雅降级 |
| 4 | 插入 Hero Test Search 区块 | `shop-to-llm.php` | L1041–L1238 | 黄色渐变卡片 + ChatGPT 风格 UI（输入框 + Ask 按钮 + 配额徽章 + 加载动画 + 结果区）+ JS IIFE |
| 5 | 删除旧 `#stl-test-search-box` 内联面板 | `shop-to-llm.php` | — | 移除原 Score 卡片内的隐藏 Test Search 入口，统一收敛到 Hero 区 |
| 6 | 旧 Test Search JS 重定向 | `shop-to-llm.php` | L1390–L1403 | 原触发逻辑改为 `window.shop2llmFocusHeroSearch()` 调用，平滑迁移历史调用点 |
| 7 | Fix All 按钮联动更新 | `shop-to-llm.php` | L1494–L1500 | `test_mcp` action 内部改为调用 `shop2llmFocusHeroSearch()`，引导用户到 Hero 区查看 AI 结果 |

---

## 3. 后端架构

### 3.1 AJAX Endpoint

- **Hook**：`wp_ajax_shop2llm_test_search`
- **回调**：`shop_to_llm_handle_test_search()`
- **权限**：`current_user_can('manage_woocommerce')`
- **Nonce**：`shop2llm_test_search_nonce`

### 3.2 FinCore 云端端点

- **URL**：`https://api.shop2llm.com/fincore/v1/free/ai-test`
- **Method**：POST
- **Content-Type**：`application/json`

### 3.3 请求 Payload

```json
{
  "site_url": "https://example.com",
  "site_hash": "sha256...",
  "plugin_version": "1.1.1",
  "query": "best selling products",
  "has_woocommerce": true,
  "site_name": "My Store",
  "locale": "en_US",
  "products": [
    {
      "name": "Widget A",
      "price": "19.99",
      "currency": "USD",
      "in_stock": true,
      "rating": 4.5
    }
  ],
  "product_count": 8
}
```

### 3.4 响应

```json
{
  "ai_reply": "Based on your catalog, the top recommended products are..."
}
```

### 3.5 配额与限流

| 层级 | 机制 | 说明 |
|------|------|------|
| 服务端（权威） | `site_hash` + Redis 计数 | 5 次/天/site_hash 硬限流，域名校验 |
| 本地（UI 提示） | transient `shop2llm_test_quota_{date}` | 仅用于前端徽章显示，不作为限流依据 |

### 3.6 优雅降级

| HTTP 状态 | 行为 |
|-----------|------|
| 200 | 解析 `ai_reply` 字段返回 |
| 429 | 返回配额耗尽提示文案，前端徽章变红 |
| 其他错误 / 网络异常 | 返回空字符串 `""`，前端不渲染 AI 气泡 |

### 3.7 Filter 钩子

- **`shop2llm_test_search_daily_limit`**（默认 `5`，可编程覆盖）
- 用途：允许 Pro 版或定制代码提高本地 UI 显示的每日配额上限
- 注意：仅影响 UI 提示，服务端硬限流不可绕过

---

## 4. 前端架构

### 4.1 DOM 结构

| 元素 | 选择器 | 用途 |
|------|--------|------|
| Hero 容器 | `#stl-hero-test-search` | 黄色渐变背景 `#fef3c7 → #fde68a` |
| 输入框 | `#stl-hero-search-input` | 用户输入搜索 query |
| 提交按钮 | `#stl-hero-search-go` | 按钮文案 "Ask ChatGPT →" |
| 配额徽章 | `#stl-test-quota` | 显示 "N tests left today"，0 时变红 |
| 加载动画 | `#stl-hero-loading` | spinner + "Asking ChatGPT about your store..." |
| 结果区 | `#stl-hero-results` | AI 气泡 + 商品卡片渲染容器 |
| AI 气泡 | `.stl-ai-bubble` | 🤖 图标 + ChatGPT-style preview 文本 |
| 商品卡片 | `.stl-product-card` | 48x48 缩略图 + 名称 + 价格 + 库存徽章 + 评分 + 描述 + View 链接 |

### 4.2 全局函数

```javascript
window.shop2llmFocusHeroSearch(query)
```

- **作用**：滚动到 Hero 区块并聚焦输入框，可预填 `query`
- **调用方**：Fix All 按钮、旧 Test Search JS 触发点
- **可见性**：挂载到 `window`，供跨模块调用

### 4.3 JS IIFE 模块

- 位于 `shop-to-llm.php` L1041–L1238 内联 `<script>` 中
- 职责：绑定按钮点击、AJAX 请求、配额徽章更新、结果渲染、错误降级
- 无外部依赖（不依赖 jQuery、React），原生 DOM API 实现

---

## 5. 防滥用架构

### 5.1 客户端/服务端职责分离

| 层 | 可见性 | 职责 |
|----|--------|------|
| 客户端（WordPress 插件） | 开源（可修改） | UI 渲染、payload 组装、配额徽章提示 |
| FinCore 云端 | 闭源（不可绕过） | 真实限流、AI 模型调用、prompt 模板管理 |

### 5.2 真实限流位置

- **服务端**：`site_hash` + Redis 计数 + 域名校验
- **本地 transient** (`shop2llm_test_quota_{date}`)：仅作 UI 提示，**不作为限流依据**
- 客户端任何修改都无法绕过服务端硬限流

### 5.3 Payload 轻量化

- 仅发送：`name` / `price` / `currency` / `in_stock` / `rating`
- **不发送**：完整描述、图片二进制、客户数据、订单数据

### 5.4 输入截断

| 字段 | 最大长度 |
|------|----------|
| `query` | 200 字符 |
| 产品 `name` | 120 字符 |

---

## 6. 测试结果

### 6.1 Plugin Check 合规扫描

- **总计**：428 ERROR / 173 WARNING
- **历史问题**：425/428 ERROR 为历史 `TextDomainMismatch`（`shop2llm` vs `shop-to-llm`），非本次整改引入
- **v1.1.1 新增代码范围**：仅有 `TextDomainMismatch`（与现有代码风格一致）
- **结论**：零新增安全/性能 ERROR

### 6.2 生命周期测试

| 测试项 | 结果 |
|--------|------|
| 停用 → 数据保留 | ✓ |
| 重新激活 → 函数正常注册 | ✓ |
| 卸载 → 7/7 选项清理完毕 | ✓ |

### 6.3 功能测试

| 测试项 | 结果 |
|--------|------|
| 产品搜索：返回 8 个富字段（name/price/currency/in_stock/rating/short_description/url/image_url） | ✓ |
| AI 优雅降级：FinCore 云端未实现时返回空字符串 | ✓ |
| 配额 filter：默认 5，可覆盖到 10 | ✓ |
| Hero HTML 标记：19 个全部 OK | ✓ |
| 版本号：1.1.1 | ✓ |
| Dashboard HTTP 渲染：29 处 Hero 标记匹配 | ✓ |

### 6.4 版本矩阵测试

| WP 版本 | PHP 版本 | 插件激活 | 函数注册 | PHP 语法 | 状态 |
|---------|----------|----------|----------|----------|------|
| 6.9.3 | 8.2 | ✓ | ✓ | ✓ | 完整功能测试通过 |
| 6.0.3 | 7.4.32 | ✓ | ✓ | ✓ | 激活 + 语法校验通过 |
| 7.0 | 8.3.31 | ✓ | ✓ | ✓ | 激活 + 语法校验通过 |

---

## 7. 配套待办

### 7.1 FinCore 服务端端点实现

需实现 `POST /fincore/v1/free/ai-test` 端点：

- **入参**：`site_hash`, `query`, `products[]`
- **出参**：`{ai_reply: string}`
- **限流**：5 次/天/site_hash（Redis）
- **模型路由**：`DeepSeek-chat` → OpenAI fallback
- **Prompt 模板**：固定模板，**不可由客户端覆盖**

### 7.2 TextDomainMismatch 修复（单独版本处理）

- 全局替换 `'shop2llm'` → `'shop-to-llm'`
- 重命名 `.po` / `.mo` 文件
- 不在 v1.1.1 范围内，避免本次整改引入大规模 diff

### 7.3 .pot 文件更新

- 新增 i18n 字符串（Hero 区文案、按钮、配额提示等）
- 同步更新 `languages/shop2llm.pot`

---

## 8. 文件变更清单

| 文件 | 类型 | 变更说明 |
|------|------|----------|
| `platforms/woocommerce/shop-to-llm/shop-to-llm.php` | 主文件 | 5277 → 5407 行（+130 行） |
| `platforms/woocommerce/shop-to-llm/readme.txt` | 文档 | Stable tag + Changelog + Upgrade Notice |
| `platforms/woocommerce/shop-to-llm/changelog.txt` | 文档 | v1.1.1 完整工程条目 |
