01 - 项目概述
项目定位
ECShopX-Vshop 是基于 Taro 3.6.25 + React 18 的多端电商前端应用，是 Shopex（商派）面向 B2C 零售场景的核心 C 端产品。支持 微信小程序（weapp） 和 H5 两端编译，覆盖购物、内购、导购、店务(POS)、社区团购、商户入驻、配送员、销售员等丰富业务域。
技术栈
| 层面 | 技术 | 说明 |
|---|---|---|
| 跨端框架 | Taro 3.6.25 | 统一一套代码，编译到微信小程序(weapp) 和 H5 |
| UI 框架 | React 18 | 函数组件 + Hooks 为主，部分页面保留 Class Component |
| 状态管理 | Redux Toolkit + redux-persist | 12 个 Slice，部分状态持久化到 Storage |
| 全局数据层 | Spx（自研） | 内存缓存 + Taro Storage，管理 Token/用户信息/钩子系统 |
| 请求层 | 基于 Taro.request 封装 | 支持 Token 刷新、多租户、多语言注入 |
| 国际化 | i18next + react-i18next | 4 语言（简中/繁中/英/阿拉伯），支持 RTL |
| UI 组件库 | taro-ui 3.x | 二次封装覆盖样式 |
| 样式 | SCSS (dart-sass) | 750px 设计稿，weapp/h5 分平台 mixins |
| 构建 | webpack 5 (5.78.0) | Taro 内置 webpack5 编译器 |
| Node | 16.16.0 | Docker 基础镜像 node-python3:16.16.0-alpine3.16 |
| 代码规范 | ESLint + Prettier + Husky + Commitizen | 提交消息强制 TBID 格式 |
| 包管理 | npm | npm ci 安装，私有 registry |
多端编译策略
项目通过 两个维度 区分运行环境：
维度一：Taro 运行环境（process.env.TARO_ENV）
| 值 | 平台 | 构建/运行脚本 |
|---|---|---|
weapp | 微信小程序 | npm run build:weapp / dev:weapp |
h5 | H5（浏览器） | npm run build:h5 / dev:h5 |
项目当前编译范围限定为 weapp 和 h5 两个平台。
维度二：产品版本（process.env.APP_PLATFORM）
| 值 | 产品名称 | 说明 |
|---|---|---|
standard | 云店（B2C） | 标准版云店，进店规则检查 |
platform | ECShopX（BBC） | 多商户平台模式 |
项目当前产品版本限定为
standard和platform。
代码中通过常量快速判断：
js
export const VERSION_STANDARD = process.env.APP_PLATFORM == 'standard'
export const VERSION_PLATFORM = process.env.APP_PLATFORM == 'platform'整体架构图
┌─────────────────────────────────────────────────────────────┐
│ 多端输出 │
│ 微信小程序 (weapp) │ H5 │
├─────────────────────────────────────────────────────────────┤
│ Taro 3.6.25 + React 18 │
├──────────┬──────────┬──────────┬──────────┬─────────────────┤
│ 路由层 │ 请求层 │ 状态层 │ 数据层 │ 国际化层 │
│ │ │ │ │ │
│app.config│ req.js │ Redux │ Spx │ i18next │
│routeInter│ API类 │ Toolkit │ 全局缓存 │ react-i18next │
│-cept │ Token刷新│ 12 Slice│ Token管理│ 4语言+RTL │
├──────────┴──────────┴──────────┴──────────┴─────────────────┤
│ 组件层 │
│ sp-* 组件库(64+) │ HOCs(6个) │ Hooks(16个) │ taro-ui │
├──────────────────────────────────────────────────────────────┤
│ 业务域 │
│ C端购物 │ 内购 │ 导购 │ 店务POS │ 社区团购 │ 商户入驻 │ ... │
├──────────────────────────────────────────────────────────────┤
│ 样式层 │
│ SCSS: theme → variables → mixins → global → sp-comps │
│ 750px设计稿 │ weapp/h5分平台 │ RTL支持 │ taro-ui覆盖 │
├──────────────────────────────────────────────────────────────┤
│ 构建层 │
│ webpack5 │ dotenv-flow │ defineConstants │ Docker │
└──────────────────────────────────────────────────────────────┘src 目录结构
src/
├── app.js # 应用入口
├── app.config.js # 路由配置（主包+分包+插件）
├── app.scss # 全局样式入口
├── api/ # 请求层
│ ├── req.js # 核心请求封装（API类）
│ ├── index.js # 模块导出（30+模块）
│ ├── consts.js # HTTP状态码常量
│ └── *.js # 各业务域 API 模块
├── spx/ # 全局数据访问器
│ └── index.js # Spx 单例
├── store/ # Redux 状态管理
│ ├── index.js # Store 创建（单例）
│ ├── reducer.js # Reducer 组合
│ ├── storage.js # Storage 适配器
│ └── slices/ # 12 个 Slice
├── components/ # 组件库
│ ├── index.js # 统一导出
│ └── sp-*/ # sp-* 前缀组件
├── hocs/ # 高阶组件
├── hooks/ # 自定义 Hooks
├── i18n/ # 国际化
│ ├── index.js # 对外 API
│ ├── instance.js # i18next 单例
│ └── config-t.js # 编译期翻译表
├── pages/ # 主包页面（22个）
├── subpages/ # 分包页面（24个业务域）
├── marketing/ # 营销模块（分销、秒杀、拼团等）
├── boost/ # 砍价模块
├── plugin/ # 插件系统
│ ├── requestIntercept.js # 请求拦截器
│ ├── routeIntercept.js # 路由拦截器
│ ├── app/ # H5+ App 插件
│ └── router/ # 路由重定向
├── service/ # 服务层
│ ├── form-ids.js # FormId 收集
│ └── tracker/ # 埋点追踪
├── consts/ # 常量定义
├── utils/ # 工具函数（33+文件）
├── style/ # 样式系统（17个SCSS文件）
├── lang/ # 语言资源
├── files/ # 静态文件
└── assets/ # 静态资源核心业务域
| 业务域 | 说明 | 分包/页面 |
|---|---|---|
| C 端购物 | 首页、分类、商品、购物车、结算 | 主包 + subpages/item + subpages/trade |
| 内购 | 企业内购商城，独立路由体系 | subpages/purchase (17页) |
| 导购 | 导购货架、导购员管理 | subpages/guide + subpages/salesman |
| 店务(POS) | 门店收银、取单、改价 | subpages/dianwu (20页) |
| 社区团购 | 开团、团长管理、佣金提现 | subpages/community (27页) |
| 商户入驻 | 商家申请、审核 | subpages/merchant (5页) |
| 配送员 | 配送、售后 | subpages/delivery (9页) |
| 积分商城 | 积分兑换商品 | subpages/pointshop (3页) |
| 营销活动 | 秒杀、拼团、大转盘、加价购 | marketing/ (35+页) |
| 砍价 | 砍价/翻牌活动 | boost/ (6页) |
| UGC内容 | 笔记、话题、图片编辑 | subpages/mdugc (10页) |
| 授权 | 登录、注册、找回密码 | subpages/auth (10页) |
| 会员中心 | 个人信息、积分、等级、收藏 | subpages/member (7页) |
环境变量体系
项目使用 .env + .env.local 双层环境变量管理，通过 dotenv-flow 加载，再经 defineConstants 注入到客户端代码。
核心环境变量
| 变量名 | 用途 |
|---|---|
APP_BASE_URL | 后端 API 基础地址 |
APP_WEBSOCKET | WebSocket 连接地址 |
APP_COMPANY_ID | 企业/租户 ID |
APP_PLATFORM | 产品版本（standard/platform） |
APP_ID | 微信小程序 AppID |
APP_MAP_KEY | 地图 API Key |
APP_MAP_NAME | 地图应用名称 |
APP_IMAGE_CDN | 图片 CDN 域名 |
APP_DEFAULT_LANGUAGE | 默认语言（zhcn） |
APP_HOME_PAGE | 首页路径 |
APP_DIANWU_URL | 店务端 URL |
APP_MERCHANT_URL | 商家入驻 URL |
APP_ADAPAY | 是否启用 Adapay 支付 |
APP_LIVE | 是否启用直播功能 |
APP_TRACK | 埋点追踪服务类型（如 youshu） |
APP_CUSTOM_SERVER | 自定义 H5 服务地址 |
所有以 APP_ 开头的环境变量会自动被 getEnvs() 函数收集并注入。详见 12-构建与部署。
版本演进
- Taro 版本: 3.6.25
- Node 要求: 16.16.0