Appearance

01 项目概述 ​

1.1 项目定位 ​

ECShopX Web 是面向 ECShopX 电商业务的 Nuxt 前端应用，覆盖商城首页、商品详情、店铺、购物车、结算、支付、账户中心、订单、售后、收藏和装修页面等场景。

1.2 技术栈 ​

  • 框架：Nuxt 4、Vue 3、Vite。
  • 语言：TypeScript，开启 strict 模式。
  • 状态：Pinia、@pinia/nuxt。
  • 请求：Nuxt $fetch，统一封装为 $api，API Client 按业务域拆分。
  • UI：Nuxt UI、Tailwind CSS、Radix Vue、Lucide Vue。
  • 国际化：@nuxtjs/i18n，语言资源懒加载。
  • 测试：Vitest、Playwright，部分装修组件提供单元测试。

1.3 业务模式 ​

通过 NUXT_PUBLIC_BUSINESS_MODE 配置业务模式，默认值为 b2c。源码中同时存在 B2C、B2B/BBC 模板配置，具体页面和装修模板应根据运行时业务模式选择。

1.4 总体结构 ​

text
浏览器 / SSR
    │
    ├── pages：文件系统路由和页面编排
    ├── components：通用 UI 与业务组件
    ├── composables：交互、请求和业务复用逻辑
    ├── stores：用户、购物车等跨页面状态
    ├── infrastructure/http：按业务域封装 API Client
    ├── decoration-engine：DSL 页面装修渲染
    └── templateEngines：按业务模式选择模板
              │
              └── Nuxt $api → ECShopX 后端接口

1.5 关键设计原则 ​

  1. 页面负责组合业务，不直接堆叠底层请求细节。
  2. API 调用通过 Client 统一封装，模型转换通过 Transformer 处理。
  3. 认证状态由 Pinia 与 Cookie 共同维护，服务端渲染时注意客户端 API 的边界。
  4. 商品价格、数量等领域数据使用值对象，避免金额和数量计算散落在组件中。
  5. 装修页面优先通过 DSL 和注册表渲染，减少页面硬编码。