加拿大 境内折后商品金额满 CA$99.00 免运费 · 部分偏远地区除外
AI 导购使用说明
AI 智能购物助手 — 用户使用指南
源码核对（2026-07-15）：AI 对话、流式输出、停止生成、会话管理和商品比较都经
/bff/ai/*路由，浏览器不直连 AI API。推荐引用的商品必须来自当前检索证据和可见商品集，配额、租户功能开关和会话所有权会在 BFF/API 再次校验。
1. 功能概览
AI 智能购物助手是一款集成在 Trelanto 商城中的对话式商品推荐工具。您可以通过自然语言描述需求，系统将自动检索匹配的商品并给出专业推荐。主要能力包括：
- 自然语言商品搜索：用日常语言描述您需要的商品，AI 自动理解并检索
- 智能商品推荐：根据需求精准匹配，返回评分排序的推荐列表
- 快速意图识别：当您明确说"即将上架""可能上新""随便推荐""只看资料"等表达时，系统会先识别这些购物意图，再决定检索可购买商品、可见目录商品或调研/预告商品
- 商品对比分析：选择多个推荐商品进行横向对比，获取差异与使用场景分析
- 多轮对话上下文：AI 会记住同一会话中的对话历史，支持追问与细化需求
- 中英法三语支持：支持中文、英文和法文三种语言的对话与推荐
- 会话管理：创建、重命名、删除、回收站恢复多个独立对话
2. 进入 AI 助手
在商城首页的导航栏中，点击"AI 助手"入口即可进入 AI 购物助手页面；也可以直接访问当前语言下的 /ai 路径。页面分为三个核心区域：
| 区域 | 说明 |
|---|---|
| 左侧会话列表 | 管理多个对话会话，支持新建、重命名、切换、删除 |
| 中央对话面板 | 显示与 AI 的完整对话内容，包括用户消息和 AI 回复 |
| 右侧推荐面板 | 展示 AI 推荐的商品卡片、对比结果以及商品操作按钮 |
移动端上，会话列表以抽屉形式打开，推荐面板在对话下方展示。整体布局为响应式设计。
3. 功能启用前置条件
AI 助手需要系统管理员在后台开启 AI 功能后才可使用。如果您访问 AI 助手页面时看到"页面不存在"提示，说明该功能当前未启用，请联系管理员。
系统会通过 ai-feature-gate.tsx 组件检测功能开关状态，由 use-ai-feature-config Hook 从 BFF 层获取配置判断是否展示 AI 页面。
4. 创建与管理会话
4.1 创建新会话
点击会话列表上方的"新建会话"按钮即可创建。新会话默认标题会跟随当前语言：中文为"新的 AI 会话"，英文为"New AI Session"，法文为"Nouvelle session IA"。发送第一条消息后，系统会自动根据您的输入内容生成更合适的会话标题。
4.2 切换会话
点击左侧会话列表中的任意会话即可切换。切换后中央面板会加载对应会话的历史消息，右侧推荐面板显示最近一次推荐结果。
4.3 重命名会话
在会话列表中找到目标会话，点击编辑图标，输入新标题后保存。标题最长 60 个字符。
4.4 删除与恢复会话
- 软删除：删除后会话进入回收站，可在"回收站"模式下查看。
- 恢复：在回收站中点击恢复按钮，会话回到正常列表。
- 永久删除：在回收站中对单个会话执行永久删除操作，不可恢复。
- 清空回收站：一键永久删除所有回收站会话。
5. 发送消息与获取推荐
5.1 输入消息
在对话面板底部的输入框中输入您的需求。输入内容限制默认为 1000 个字符，具体上限由系统管理员配置。输入完成后按回车键或点击发送按钮。
示例对话：
用户：我想买一款适合中年人的保健品，预算在200元以内
AI：根据您的需求，为您推荐以下几款适合中年人的保健产品...
5.2 AI 思考过程
发送消息后，AI 进入"思考中"状态。页面会显示思考计时器，提示 AI 正在处理。思考时间通常在 30～90 秒之间（由系统配置控制），如果超过慢速提示阈值，界面会提示"AI 正在深度分析，请耐心等待"。
5.3 流式回复
AI 的回复内容会以流式方式逐步出现在对话面板中，形成类似"打字机"的效果。这确保您无需等待完整回复即可开始阅读。
5.4 推荐结果
AI 回复的文字消息旁边（桌面端为右侧面板，移动端为下方面板）会展示推荐的商品卡片。每张卡片包含：
- 商品图片
- 商品名称与副标题
- 价格
- 库存状态
- 推荐理由与相关性评分
- 商品标签与属性
- 精选标记（Winner / Finalist）：表示 AI 认为最匹配需求的商品
5.5 快速意图识别对推荐范围的影响
默认情况下，AI 优先推荐 publicationStatus=published、salesStatus=available 且有可售库存的商品。当您的消息明确表示"不一定要能买"或"只想看资料"时，系统可放宽到可见目录商品；当您提到"即将上架""可能上新""市场测试"时，系统会把 market_test、coming_soon、preorder 商品纳入候选。安全敏感意图（如孕妇、儿童、过敏、禁忌、治疗等）只会提升安全提示强度，不会降低安全边界。
5.6 无结果处理
当 AI 无法找到匹配的商品时，不会返回空结果，而是生成一段咨询式回复，引导您调整需求描述或给出替代建议。这由 ai-no-result-response.service.ts 提供。
6. 商品对比功能
6.1 选择对比商品
在推荐面板中，您可以勾选多个商品进行对比。最多可同时对比的商品数量由系统配置控制（默认 4 个）。
6.2 查看对比结果
选择完毕后，点击"对比"按钮。系统会调用 AI 对选定商品进行深度对比分析，生成以下内容：
| 对比维度 | 说明 |
|---|---|
| 共同优势 | 所有被对比商品的共同特点 |
| 核心差异 | 各商品之间的关键不同点 |
| 使用场景 | 各商品适合的人群或使用场景 |
| 价格对比 | 价格层面的差异分析 |
| 成分对比 | 成分或材料的差异（适用于保健品等品类） |
对比结果以 Markdown 格式渲染在推荐面板中，同时会记录到会话历史中便于回看。
6.3 多组对比
在同一会话中，您可以进行多次不同的商品对比。每次对比会生成独立的对比组和摘要。
7. 加入购物车
推荐卡片只推荐商品，不替您选择具体规格。图片和标题用于进入商品详情页；卡片按钮只表示购买动作。
按钮状态由系统结构化购买状态决定，而不是由 AI 回复正文决定：
| 按钮 | 含义 |
|---|---|
| 一键加购 | 当前商品存在可直接加入购物车的可售规格；点击后仍会走购物车服务端校验 |
| 选择规格 | 商品有多个规格或需要先确认规格；请选择规格后再加入购物车 |
| 暂不可购 | 商品当前不可购买、无可售规格或状态不允许加入购物车 |
该操作通过 use-ai-add-to-cart.ts Hook 处理，并最终走商城统一购物车校验；只有 publicationStatus=published、salesStatus=available 且存在可售规格的商品才能进入正常结账流程。AI 因快速意图识别展示的调研、预告或预售商品主要用于查看和比较，不能保证可立即加购下单。
8. 配额与使用限制
8.1 对话次数限制
系统按周为周期统计 AI 对话使用次数。不同身份有不同的默认配额：
| 用户类型 | 默认周配额 |
|---|---|
| 已登录用户 | 10 次/周 |
| 匿名用户 | 3 次/周 |
当配额用尽时，发送消息会收到提示"本周 AI 对话次数已达上限"。配额于每周一 UTC 零点自动重置。
8.2 查看剩余配额
页面上方会显示当前配额状态，包括本周使用次数与剩余次数。该信息通过 /ai/quota 接口获取。
9. 排序偏好
在发送消息时，您可以通过界面控件选择推荐排序策略：
| 策略 | 说明 |
|---|---|
| 综合推荐（effectiveness） | 默认策略，综合语义相关度、商品评分等因素 |
| 价格从低到高（price_low） | 按价格升序排列 |
| 价格从高到低（price_high） | 按价格降序排列 |
您也可以在消息中指定价格范围，如"200 元以内"，AI 会自动识别并应用价格过滤。
10. 消息操作
10.1 删除消息
在对话面板中，您可以删除单条消息。删除后该消息不再显示，但不影响其他消息。
10.2 停止生成
在 AI 正在流式输出时，点击"停止"按钮可中断当前生成过程。已输出的部分内容会保留。
11. 多语言支持
AI 助手支持中文、英文和法文三种语言。系统会根据以下优先级确定语言：
- 用户在请求中指定的 locale 参数
- 浏览器 Accept-Language 请求头
- 默认使用中文
切换语言后，AI 会使用对应语言进行回复和推荐。商品信息（标题、描述等）也会显示对应语言的翻译版本。
12. 免责声明
AI 助手的推荐仅供购物参考，不构成专业建议。如涉及健康相关商品，请咨询专业医生。
免责声明：AI 建议仅供购物参考；如涉及健康问题，请咨询专业医生。
13. 常见问题
Q: AI 一直在"思考中"，很长时间没有回复？
A: AI 思考时间通常在 30～90 秒。如果超过这个时间，可能是外部 AI 服务暂时繁忙。请尝试刷新页面或稍后再试。
Q: 推荐结果和我的需求不太匹配？
A: 请尝试更具体地描述需求。例如不要只说"保健品"，可以说"适合老人补钙的保健品，预算 100 元以内"。AI 会根据更多约束条件提供更精准的推荐。
Q: 为什么有的商品标记了"精选"标签？
A: 系统会根据商品与需求的匹配度自动评估，当某个商品的综合评分明显高于其他商品时，会被标记为 Winner（最佳推荐）或 Finalist（优秀候选）。
Q: 匿名用户和登录用户有什么区别？
A: 匿名用户的对话配额更少（默认 3 次/周），且会话不与个人账号关联。登录后配额更大（默认 10 次/周），且会话与账户绑定，可在不同设备间查看。
Q: 对比功能最多支持几个商品？
A: 默认最多 4 个商品同时对比，具体上限由系统管理员配置。
Q: 页面显示"页面不存在"？
A: 这意味着 AI 功能未启用。请联系系统管理员在后台"系统设置"中开启 AI 功能。
14. 技术限制说明
| 限制项 | 默认值 | 说明 |
|---|---|---|
| 单条消息最大字符数 | 1000 | 超出会被截断 |
| 周对话配额（登录用户） | 10 次 | 每周一重置 |
| 周对话配额（匿名用户） | 3 次 | 每周一重置 |
| 同时对比商品数 | 4 个 | 可由管理员调整 |
| AI 回复最大字符数 | 3000 | 超出部分截断 |
| 会话标题长度上限 | 60 字符 | 系统自动生成或手动修改 |
以上限制均可由系统管理员在后台进行调整。