StyleBridge AI｜全球服装选款智能体

项目简介

StyleBridge AI 是一个面向海外服装批发商的跨境服装选款与营销辅助 Demo。当前阶段聚焦俄罗斯市场，以及毛衣、针织衫和秋冬针织产品，通过确定性规则帮助买家完成需求结构化、Top 5 选款、采购组合、轻定制建议、俄语营销素材和英俄双语采购询价草稿。

项目当前已完成第 1—4 轮：

• 第 1 轮：可维护的 Streamlit 项目骨架、五页面导航、中英俄 UI 和 Demo 数据边界；
• 第 2 轮：20 款 Demo 产品、规则型 Top 5 选款、三套采购组合和轻定制建议；
• 第 3 轮：规则型俄语营销素材、结构化 Demo RFQ、English RFQ 和 Russian RFQ；
• 第 4 轮：20 款封版产品图、Moscow 一键 Demo、四步流程导航、页面 CTA 和比赛演示体验优化。

当前业务闭环

Buyer Requirement
→ 规则型 SelectionResult
→ Top 5 推荐
→ 三套采购组合
→ 轻定制建议
├→ 俄语营销素材（供俄罗斯批发商向下游客户展示和推广）
└→ 结构化 Demo RFQ → English RFQ + Russian RFQ

这条链路回答“选什么、怎么买、怎么调整、怎么卖、怎么向供应商询价”。Marketing 与 RFQ 共用 SelectionResult 中已验证的 Buyer Requirement、Top 5 和采购组合，不在页面层重复解释需求。

已实现功能

产品与选款

• 20 款本地 Demo 产品，其中女装 12 款、男装 8 款；
• 20 张封版 WebP 产品图与 20 个产品 ID 严格一一对应，统一为 1024×1280、4:5；
• 图片使用项目内相对路径和 pathlib 解析，缺失、损坏或无权限读取时安全降级为占位提示；
• Buyer Requirement 结构化校验；
• gender 硬过滤；
• 7 维 100 分规则评分与稳定 Top 5 排序；
• 推荐理由和评分拆解；
• 试单组合、标准主推组合、引流与利润组合；
• 颜色、尺码、厚薄、面料和图案方向的轻定制建议。

俄语营销素材

• 每次根据当前 Top 5 动态生成 5 份素材；
• 俄语商品标题、3—5 条核心卖点、短描述、推广文案和 marketing_tags_ru；
• 只使用产品名称、品类、性别、厚薄、风格、颜色等已存在属性；
• 相同输入产生完全一致的结果，不使用随机数、LLM、网络 API 或自动翻译；
• Recommendation Score 仅在 StyleBridge 内部页面展示，不进入对外营销正文；
• 素材定位为俄罗斯批发商面向下游零售客户或消费者的 Demo 展示与推广内容。

Demo RFQ

• 结构化 RFQ 模型包含买家资料、Top 5、所选组合、Demo 比例、轻定制确认请求、预计采购总量、联系信息和备注；
• 只接受当前三套采购组合，组合项只能来自当前 Top 5；
• 预计采购总量允许留空或填写正整数；
• 不根据总量自动计算逐款采购件数；
• 联系方式可留空并生成 Demo 草稿，页面会提示实际沟通前补充；
• 同一 RFQRequest 确定性生成 English RFQ 和 Russian RFQ；
• 英俄正文保持产品 ID、数量、顺序、组合、比例和预计总量一致；
• Buyer Requirement 或采购组合变化后，已生成 RFQ 自动失效；
• RFQ 没有 demo_reference、rfq_id 或正式询价单编号。

Moscow 一键 Demo

首页“立即体验 Moscow Demo”会加载固定的莫斯科女装高领毛衣批发场景，并直接进入 Top 5 选款结果。

• 当前没有已保存需求时直接加载；
• 已有需求时先请求确认，未确认不会覆盖；
• 确认加载后标记需求来源为 Demo，并立即使旧 RFQ 与相关过期状态失效。

Demo 边界

产品数据与产品视觉均为 AI 生成/整理的演示样例；所有内部评分、采购组合比例、营销素材和 RFQ 仅用于展示工作流，不代表真实市场结论、真实供应商、库存、报价或实际在售商品。

当前不具备：

• LLM 或任何外部 AI API；
• 实时市场分析、真实销量、热销排名或利润数据；
• 真实供应商、报价、价格、库存、MOQ、交期或样品政策；
• 自动供应商匹配；
• 图片识别、运行时图片生成或营销海报生成；
• 真实邮件或 WhatsApp 发送；
• PDF、Word 或 Excel 导出；
• 在线下单、正式订单、采购合同、支付、物流、CRM、数据库或用户账号；
• 自动逐款采购件数计算。

RFQ 中对 quotation、MOQ、availability、lead time、customization feasibility 和 sample policy 的内容都是请求供应商进一步确认，不是系统给出的答案或承诺。

项目结构

StyleBridge-AI/
├── app.py
├── assets/
│   └── products/             # 20 张封版 WebP Demo 产品图
├── stylebridge/
│   ├── config.py
│   ├── i18n.py
│   ├── data/                 # JSON 数据访问与校验
│   ├── models/               # 选款、营销与 RFQ 轻量模型
│   ├── services/             # 推荐、组合、定制、营销与 RFQ 纯业务逻辑
│   ├── templates/            # 俄语营销及英俄 RFQ 正文模板
│   └── ui/                   # Streamlit 布局、导航与五个页面
├── data/
│   ├── mock/
│   └── products/
└── tests/

页面层只负责输入、布局和输出，不直接读取产品 JSON，也不包含评分、营销正文或 RFQ 正文模板规则。

Windows 环境准备

项目使用 Python 3.12。建议在项目根目录创建并激活虚拟环境：

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt

本地运行

.\.venv\Scripts\python.exe -m streamlit run app.py

默认运行在 Demo 模式。界面支持中文、英文和俄文；俄语界面与营销正文仍建议由俄语母语者在真实使用前复核。

可选环境变量：

• STYLEBRIDGE_DEMO_MODE：默认 true；
• STYLEBRIDGE_DEFAULT_LANGUAGE：默认 zh，可选 zh、en、ru。

3 分钟比赛 Demo 流程

• 0:00：首页与价值介绍；
• 0:20：加载 Moscow Demo；
• 0:40：查看带产品图、匹配度与推荐理由的 Top 5；
• 1:20：查看三套采购组合和轻定制建议；
• 1:50：查看所选产品的俄语 Marketing 素材；
• 2:20：生成 English RFQ 与 Russian RFQ；
• 3:00：回顾四步业务闭环并结束演示。

测试与代码检查

.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe -m pytest

测试覆盖选款规则、Marketing、RFQ、20 张图片映射与异常降级、Moscow Demo 覆盖保护、三语 UI、四步导航和 Streamlit AppTest 冒烟路径。若 Windows 受限沙箱对 pytest 临时目录返回 WinError 5，可明确指定有权限的临时目录：

.\.venv\Scripts\python.exe -m pytest -p no:cacheprovider --basetemp C:\tmp\stylebridge-pytest

平台无关部署准备

本轮不执行公开部署，也不绑定具体云平台。当前代码以 app.py 作为 Streamlit 入口，并完成以下准备：

• 静态图片由项目内相对路径和 pathlib 解析，兼容 Windows/Linux 路径语义；
• 无 API Key、SSH 私钥、真实个人联系方式、真实供应商敏感数据或运行时网络依赖；
• requirements.txt 包含运行依赖，图片读取异常不会导致应用崩溃。

安全说明

不要把 API Key、.env、Streamlit secrets、密钥或敏感业务数据提交到 Git。提交前应检查工作树，排除 pytest 缓存、临时日志、截图和其他本地文件。