系统难度与我们的实现
难点在于，同一套商品数据要同时服务品牌展示、专业筛选、SKU 选择和交易订单。 任何一个环节脱节，都可能造成用户看到的商品与实际加入购物车的商品、价格或库存不一致。
| 业务难点 | 我们的实现 | 体现的能力 |
|---|---|---|
| 珠宝参数跨多个维度 | 将商品、选项组、变体、SKU、库存和价格分开建模，前端匹配可售变体 | 复杂商品建模与参数驱动交互 |
| 品类、切工与材质需要组合筛选 | 同一维度的多个选择合并，不同维度的结果取交集，并按产品去重 | 组合查询、结果集处理与界面状态管理 |
| 品牌首页和后台选品需要同步 | 首屏推荐、新品、品类与形状模块读取对应商品集合及子集合 | 数据驱动的品牌页面与运营集成 |
| 购物车与结账涉及多个业务对象 | 连接商品变体、订单行、客户、地址、配送方式、支付方式及订单状态 | 多步骤业务流程与前后端协作 |
| 缓存性能与交易实时性需要兼顾 | 公共商品数据使用标签缓存；购物车读取会话数据，变更后刷新相关标签 | 服务端渲染、会话边界与缓存一致性 |
这些实现建立在成熟电商引擎之上。我们的工程价值体现在业务建模、店面实现、接口集成和跨模块协同；Vendure 提供的通用电商能力是系统基础。
产品与交易界面
品牌店面与商品浏览
品牌首页将视觉场景与后台推荐商品连接。首屏商品、新品、品类和切工入口来自电商数据，品牌故事与视觉编排由前端组件承载。
商品目录连接分类树与产品列表，为珠宝品类、切工和材质提供清晰的浏览入口。
实际选择 Rings 后，列表由全部商品切换为该分类的结果。筛选组件根据后台分类及子分类生成，支持组合选择和结果去重。
专业参数与购物车
商品详情呈现图集、Size、Color、Clarity、价格、库存状态和 SKU。规格结构来自商品选项组，可售组合依赖实际变体配置。
真实商品加入购物车后，订单行、单价、数量、总额及优惠码入口共同呈现。金额使用订单接口数据，配送费用在结账时确定。
手机端业务体验
手机端展示商品图集、专业参数选择和购物车。首页及商品列表采用独立的桌面 / 手机呈现组件，商品详情与交易页面按断点调整布局，保持同一套后台数据和接口。
系统架构
架构示意依据项目源码绘制。用户店面与管理后台通过不同的 GraphQL API 接入同一个电商业务核心；服务端承载商品、客户和订单数据，Worker 负责后台任务。
| 层级 | 在项目中的职责 |
|---|---|
| Next.js 店面 | 品牌页面、商品浏览、规格交互、购物车与账户页面 |
| Shop API | 商品与集合查询、当前购物车、客户会话及订单变更 |
| Admin API + Dashboard | 接入 Vendure 的商品、订单、客户与配置管理能力 |
| PostgreSQL | 存储电商核心业务实体与关联数据 |
| Worker / 插件 | 后台任务、搜索索引、邮件与媒体服务的运行基础 |
接口层统一处理 GraphQL 查询、变更、错误结果、认证令牌与渠道请求头，避免各页面重复处理底层通信细节。查询使用 gql.tada 和类型定义连接组件数据结构。
可配置的商品与运营体系
让配置进入用户体验
我们把“可配置”落在商品数据与业务规则上。运营人员维护商品集合、分类、选项和变体；店面读取配置形成展示、筛选与交易入口。
| 配置对象 | 对店面的影响 | 项目依据 |
|---|---|---|
| 推荐与新品集合 | 控制首页首屏推荐和新品展示的选品 | hero-products、new-arrivals 集合查询 |
| 品类与切工分类树 | 生成首页入口及列表筛选项 | categories、shape-types 与子集合读取 |
| 商品选项组 | 生成 Size、Color、Clarity 等参数控件 | 详情接口的 optionGroups 与 options |
| 商品变体 | 对应可售 SKU、价格和库存 | variants、priceWithTax、stockLevel |
| 媒体与商品图集 | 驱动主图、缩略图及展示模块 | 商品资产查询、图集组件与媒体插件 |
| 渠道、配送与优惠 | 为不同销售上下文和订单条件提供配置基础 | 渠道请求头、配送资格查询、优惠码变更接口 |
配置范围： 商品选品、分类、规格和交易规则通过业务后台维护；品牌文案、视觉布局和组件编排由前端组件实现。
后台管理与后续运营
系统接入 Vendure Dashboard，利用其商品、客户、订单及业务配置管理能力。项目同时提供商品导入字段说明，覆盖名称、资产、筛选属性、选项组、SKU、价格、税类及库存，方便商品资料按统一结构准备。
渠道机制、促销条件和订单状态属于 Vendure 的基础能力；店面通过渠道请求头、优惠码接口和订单变更接口与之集成。相关机制可参考 Vendure 架构文档、渠道说明 与 促销说明。渠道与促销的实际业务范围取决于项目配置。
关键工程实现
规格选择与可售 SKU
前端不把页面上的参数标签直接当作商品编号。组件根据选项组形成用户选择，再与变体的选项集合匹配，找到实际可加入购物车的 variantId。
- 从后台读取商品、选项组、选项与变体。
- 通过选项组代码保存和恢复 URL 中的选择。
- 多变体商品需要完整选择后匹配；单变体商品使用该变体。
- 按变体读取含税价格和库存状态。
- 将变体编号与数量提交到购物车接口，并呈现加载、成功或错误状态。
这套结构让专业参数、库存单位和购买行为保持关联。具体商品有哪些可售组合，由后台商品数据决定。
组合筛选逻辑
列表读取后台分类树，将每个筛选维度的选项映射为集合查询。同维度内选择多个选项时合并结果，不同维度之间按产品交集得到结果，再去重并更新展示数量。
例如，用户选择 Rings 和 Necklaces 时，是同类维度内的联合选择；再选择 Round 时，需要与切工维度的结果共同匹配。这个例子说明查询逻辑，不代表截图中的实际选中条件。
实现覆盖初始列表、筛选加载、结果展示、空结果及继续加载，连接从条件选择到商品结果更新的交互过程。
购物车、账户与结账流程
购物车使用 Vendure 的活动订单承载。用户加入商品、修改数量、移除商品或应用优惠码时，前端提交订单变更，并刷新相关数据。
| 步骤 | 前后端协同 |
|---|---|
| 商品到购物车 | 提交 variantId 和数量；接收或延续购物车会话 |
| 登录与客户账户 | 注册、邮箱验证、登录、密码重置；账户页查询资料、地址及历史订单 |
| 收货与账单信息 | 设置订单收货地址，可同步账单地址，并连接地址簿 |
| 配送与支付选择 | 查询当前订单符合条件的配送方式和支付方式 |
| 订单确认 | 先切换到 ArrangingPayment，再提交支付接口并进入确认页 |
结账页面根据已有地址、配送记录和订单状态恢复步骤，并限制后续步骤的访问。订单状态转换由电商引擎约束，前端处理转换错误与接口返回结果。Vendure 订单说明
验证范围： 本次实际核对了公开商品页面、分类筛选和加入购物车后的金额展示；账户与完整结账步骤通过源码检索确认，未登录客户账户或提交付款。本地支付配置使用 dummyPaymentHandler，不据此声称 Stripe、PayPal 或真实收款已接通。
会话与缓存协同
| 工程问题 | 实现方式 |
|---|---|
| 公共商品数据重复读取 | 商品详情、集合、渠道与国家信息采用分层缓存和标签 |
| 购物车属于特定用户 | 读取当前会话的活动订单，使用私有缓存与认证请求 |
| 商品变更后页面需要更新 | 购物车操作刷新 cart / active-order 等标签；配套重验证接口 |
| 登录会话需要服务端管理 | 认证令牌存入 HttpOnly Cookie，生产环境启用 Secure，并使用 SameSite |
这些机制把公共浏览数据与用户交易数据分开管理，为一致的店面体验提供工程基础。
搜索呈现与运行基础
商品页面按后台商品名称、描述及图片生成元数据、canonical 与分享信息；账户和结账等私人页面设置 noindex。媒体服务支持本地或 S3 兼容存储，Server 与 Worker 分工运行，项目文档覆盖启动、API、认证、缓存及常见操作。
这项项目体现的能力
| 能力 | 可核对的具体工作 |
|---|---|
| 理解专业业务并建模 | 把珠宝参数、商品分类、选项组与可售 SKU 组织成数据结构 |
| 将设计落为业务界面 | 完成品牌店面、动态选品、商品图集与桌面 / 手机业务页面 |
| 集成完整业务链路 | 从商品、购物车到客户、地址、配送和订单状态的接口衔接 |
| 构建可运营的系统 | 后台配置、商品导入说明、集合驱动选品与管理 Dashboard 接入 |
| 管理前后端一致性 | 类型化 GraphQL、会话令牌、订单变更与缓存更新协作 |
| 支撑后续扩展 | 店面与电商核心分离，沿用引擎的渠道、插件和管理机制 |
Theoaura 展示了我们把专业业务转化为可操作系统的能力：既能完成品牌界面，也能理解其背后的数据模型、交易规则和运营工作流，将多个模块连接成可持续维护的产品。
资料与说明
- 公开页面：Theoaura 官网。截图采集日期：2026-10-08。
- 内容依据：店面与服务端源码、项目开发文档、商品导入字段说明及公开页面观察。
- 架构和配置图是依据代码绘制的工程示意，界面图片为真实网站截图。
- 案例使用 Next.js 与 Vendure 等开源基础；通用电商引擎及其原生管理能力归对应项目所有，Theoaura 品牌及商品素材归品牌方所有。
- 本案例不包含销售额、转化提升、性能跑分或真实支付验收等未经证实的成果指标。