# ECShopX-Java **Repository Path**: ShopeX/ECShopX-Java ## Basic Information - **Project Name**: ECShopX-Java - **Description**: ECShopX Java版是一款基于Java技术栈打造的企业级开源交易系统,支持官方商城、新零售O2O、云店连锁、BBC多商户平台、供应链商城等10余种商业模式,统一管理小程序、PC、H5等多端业务,可满足中大型品牌企业及复杂交易场景的业务需求。支持商业用途,并遵循 Apache 2.0 许可协议。 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 0 - **Created**: 2026-09-18 - **Last Updated**: 2026-09-24 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

English / 简体中文
ECShopX-Java 的 Java 后端工程:一套基于 Spring Boot 3 + Java 17 的多模块(1 Bundle = 1 Maven Module)服务端实现,承载从商品、订单、会员、营销到支付与第三方集成的完整业务能力,配合 ECShopX-Java 前端可快速构建多端、多模式的官方商城基座。 ## 项目介绍 `ecshopx-java` 是 ECShopX-Java 商城系统的 Java 服务端,与历史 PHP 版(参见仓库根目录readme_cn)业务语义对齐、配置项一一映射,并按现代 Java 工程实践重新组织为高度模块化的多 Bundle 架构。各业务域(商品、订单、营销、会员、支付、第三方对接等)被拆分为独立 Maven Module,统一在父工程 `cn.shopex:ecshopx` 下管理;运行时由 `ecshopx-bootstrap` 作为 Spring Boot 启动入口,按需聚合所有 Bundle。 ## 适用场景 * **B2C 品牌私域商城**:作为官方小程序、APP、PC 官网、H5 等多端 DTC 商城的统一后端。 * **B2C 员工内购福利平台**:支持多品牌集团开展「员工 & 亲友内购」业务。 * **B2B2C 多商户平台**:打造类似京东、美团的「自营 + 多商户入驻」在线平台。 * **S2B2C 供应链协同**:连接品牌、经销商与终端门店的供应链平台。 * **O2O 品牌云店 + 即时零售**:线上下单、附近门店自提与即时配送。 * **O2O 经销商云店**:聚合所有经销商门店资源,实现「线上下单、门店发货 / 自提」。 ## 项目构成 整个项目为前后端分离技术架构,包含Java服务端、管理后台前端、移动商城前端、web商城前端几个仓库共同构成 - [管理后台 >](https://gitee.com/ShopeX/ECShopX-Java_Admin) - [移动商城(微信小程序/H5) >](https://gitee.com/ShopeX/ECShopX-Java_Mobile) - [Web商城 >](https://gitee.com/ShopeX/ECShopX-Java_web) ## 快速安装 ```bash curl -fsSL https://oss.shopex.cn/ecx/ECX-Java_install.sh | bash ``` 依据脚本提示部署系统 脚本会自动完成: * 检测 Docker 环境 * 克隆前端项目(如不存在) * 启动 Docker 容器(PHP、Nginx、MySQL、Redis) * 配置 Java 应用(安装依赖、数据库迁移、初始化管理员密码) * 编译前端项目(管理后台、H5、web商城) ## 核心特性 ### 模块化架构 * **1 Bundle = 1 Maven Module**:50+ 业务 Bundle(`ecshopx-goods`、`ecshopx-orders`、`ecshopx-promotions`、`ecshopx-members`、`ecshopx-payment` 等)独立打包、独立演进,按需引入。 * **分层清晰**:每个 Bundle 内部遵循 `controller / service / mapper / integration / port` 的轻量分层,跨 Bundle 通过 Port 接口解耦,避免循环依赖。 * **统一启动**:业务 Bundle 仅暴露能力,`ecshopx-bootstrap` 负责装配并以单个 Spring Boot 应用运行。 ### 业务能力 * **商品 / 订单 / 售后**:商品多级类目、SKU、规格、库存、市场价 / 销售价;订单全状态机;售后单与退款。 * **营销**:优惠券(`ecshopx-kaquan`)、积分商城(`ecshopx-pointsmall`)、拼团 / 秒杀 / 满减(`ecshopx-promotions`)、会员等级(`ecshopx-members`)、分销与推广(`ecshopx-distribution` / `ecshopx-popularize`)。 * **多商户与门店**:商户入驻(`ecshopx-merchant`)、门店预约(`ecshopx-reservation`)、导购(`ecshopx-salesperson`)、自助点单(`ecshopx-selfservice`)。 * **支付与对账**:内置 微信支付、支付宝、银联商务(`ecshopx-chinaums-pay`)、AdaPay(`ecshopx-adapay`)、汇付(`ecshopx-hfpay`)等多通道。 * **第三方集成**:微信开放平台 / 小程序 / 公众号(`ecshopx-wechat`)、企业微信(`ecshopx-work-wechat`)、阿里 / 数云 / 聚水潭 / 友数等(`ecshopx-ali` / `ecshopx-shuyun` / `ecshopx-system-link` / `ecshopx-youshu`)。 * **OpenAPI 与跨境**:开放 API 网关(`ecshopx-openapi`)、跨境业务(`ecshopx-cross-border`)。 ### 工程特性 * **Spring Boot 3.5 + Java 17**:使用 Jakarta EE 9+ 命名空间、Spring 6 编程模型。 * **MyBatis-Plus 3.5**:搭配自定义 `FqcnMapperBeanNameGenerator`,多 Bundle 下同名 Mapper 不冲突。 * **Undertow 内嵌容器**:默认开启 `allow-unescaped-characters-in-url`,提升对历史 PHP URL 的兼容性;POST Body 上限 64MB。 * **XXL-JOB 调度**:所有定时任务统一通过 XXL-JOB Executor 注册,admin 独立部署。 * **多 Redis 逻辑库**:默认 / companys / prism / datacube / deposit 等按业务隔离。 ## 系统要求 * **JDK** ≥ 17(推荐 Eclipse Temurin 17) * **Maven** ≥ 3.9(推荐使用根目录自带的 `./mvnw`) * **MySQL** ≥ 5.7(建议 8.0,字符集 `utf8mb4`,时区 `Asia/Shanghai`) * **Redis** ≥ 4.0 * **XXL-JOB Admin**(可选,启用定时任务时必需,部署清单见 `docs/migration/infra/xxl-job/`) ## 工程结构 ``` ECShopX-Java/ ├── pom.xml # 父 POM,统一管理 50+ 业务模块版本 ├── install.sh # 远程一键安装入口(--full / --lite) ├── dev-setup.sh # 全量开发安装 ├── deploy.sh / pack.sh # 极速离线入口(转发到 docker-lite/) ├── docker-compose.dev.yml # 全量编排:mysql + redis + xxl + ecshopx-app ├── docker/ │ ├── Dockerfile.app # 业务镜像(基于 runtime 基础镜像) │ ├── Dockerfile.runtime # 基础镜像:JRE17 + Node20 + OpenResty │ ├── install-secrets.sh # 安装时密码 / JWT │ ├── ecshopx.sql # 业务表结构 + 演示数据 │ └── tables_xxl_job.sql # XXL-Job 调度库 ├── docker-lite/ # 极速离线 pack / deploy ├── ecshopx-bootstrap/ # Spring Boot 启动入口 ├── ... # 其余业务 Bundle └── logs/ ``` 启动主类:`cn.shopex.ecshopx.EcshopxApplication`(位于 `ecshopx-bootstrap`)。 ## 数据库迁移(Flyway) Java 后端使用 Flyway 管理增量 SQL 迁移,迁移文件目录: ```bash ecshopx-bootstrap/src/main/resources/db/migration ``` 默认已开启应用启动自动执行迁移(`spring.flyway.enabled=true`)。Docker 完整/极速安装会在 compose 启动后等待 Java 就绪(启动过程中完成 Flyway)。本地若需手动执行,仍可使用脚本快捷命令;执行记录写入 `flyway_schema_history`。已有数据库会通过 `baselineOnMigrate=true` 从版本 `0` 建立基线,避免首次接入 Flyway 时重跑历史建库 SQL。 ### 生成迁移文件 项目提供 `bin/make-migration` 辅助命令生成符合 Flyway 命名规范的 SQL 文件: ```bash # 在 ecshopx-java 目录下 bin/make-migration add_order_extra_index ``` 默认流程对齐 PHP 项目 `php artisan doctrine:migrations:diff` 的核心逻辑:连接 `spring.datasource.*` 指向的 MySQL 读取当前数据库结构作为 from schema,扫描本地 MyBatis-Plus domain(`@TableName` / `@TableId` / `@TableField`)推导目标结构作为 to schema,然后生成从 from schema 迁移到 to schema 的 SQL。可用 `--filter-expression` 限定表名;默认不会为数据库中存在但 domain 中不存在的表/列生成 DROP,除非显式传入 `--allow-drop`。脚本会对比基础列结构与 `@TableId` 推导出的主键;普通二级索引由于 MyBatis-Plus domain 没有标准索引元数据来源,不会凭空生成。由于 MyBatis-Plus 注解没有 Doctrine ORM 那样完整的列长度、精度、nullable、普通索引等元数据,生成后必须人工检查 SQL 类型、默认值、是否允许 NULL、注释、索引和列顺序。 可通过参数覆盖连接配置或缩小对比范围: ```bash bin/make-migration --profile local add_order_extra_index bin/make-migration --filter-expression '^items$' sync_items bin/make-migration --changed-only add_order_extra_index bin/make-migration --allow-drop sync_domain_schema bin/make-migration --db-url "jdbc:mysql://127.0.0.1:3306/ecshopx" --db-user ecshopx --db-password ecshopx add_order_extra_index ``` 若只需要空模板,可使用: ```bash bin/make-migration --empty manual_data_fix ``` 生成文件格式为 `VyyyyMMddHHmmss__description.sql`,例如: ```text ecshopx-bootstrap/src/main/resources/db/migration/V20260709153000__add_order_extra_index.sql ``` ### 执行迁移 生成并 review 迁移文件后,使用快捷命令手动更新数据库: ```bash bin/make-migration migrate bin/make-migration migrate --profile local bin/make-migration migrate --db-url "jdbc:mysql://127.0.0.1:3306/ecshopx" --db-user ecshopx --db-password ecshopx ``` 该命令会调用 Flyway Maven 插件执行 `migrate`,迁移目录固定为: ```bash ecshopx-bootstrap/src/main/resources/db/migration ``` ## 安装模式 本仓库支持两种部署路径,可按场景选择: | 模式 | 入口 | 适用场景 | |------|------|----------| | **全量开发** | `bash install.sh --full` 或 `./dev-setup.sh` | 本地开发,四端前端 + `docker-compose.dev.yml`(`ecshopx-app` 一体化容器) | | **极速离线** | `bash install.sh --lite` 或 `./deploy.sh` | 客户机离线部署,发行包内含 jar + 预构建前端产物 | ### 运行时拓扑(全量开发 / 极速离线) 全量开发与极速离线共用同一 compose 形态:**mysql + redis + xxl-job-admin + ecshopx-app**(无独立 `gateway` / `ecshopx-web-frontend` 服务)。 | 服务 | 角色 | |------|------| | **mysql** | MySQL 8 + 初始化 SQL | | **redis** | Redis 7 | | **xxl-job-admin** | XXL-Job 调度控制台(宿主机默认 **8080**) | | **ecshopx-app** | 一体化应用容器:Java (:18080) + OpenResty (:80,按域名分流) + Nuxt SSR (:3000) | `ecshopx-app` 内 nginx 监听 **80**,按 `Host` 区分: | 默认域名 | 服务 | |----------|------| | `admin.ecshopx.test` | 管理后台 + `/api` `/storage` `/wechatAuth` → Java | | `h5.ecshopx.test` | H5 静态 | | `www.ecshopx.test` | PC Nuxt SSR | 宿主机默认映射:业务 HTTP **80**、XXL-Job **8080**、Java 直连调试 **18080**。可用 `--http-port` / `--*-host` 覆盖;若域名无法解析,请在本机 hosts 添加 `127.0.0.1 admin.ecshopx.test h5.ecshopx.test www.ecshopx.test`。 **全量开发**(`dev-setup.sh`): - 前端编译统一使用 **Node 20**(`node:20.19.0-alpine`)构建 admin / mobile / PC 四端。 - 开发容器名 `ecshopx-dev-app`;与 mysql、redis、xxl 共四个业务容器。 - 编排文件:`docker-compose.dev.yml`;镜像构建:`docker/Dockerfile.app`。 **极速离线**(`docker-lite/deploy.sh`): - 发行包内含 `docker-lite/app/ecshopx-bootstrap.jar`(部署时直接使用,同步为 `app.jar` 供 compose 挂载)。 - 只需下载一次 `ecshopx-java-*.tar.gz`,无需再单独下载 jar。 ```bash bash docker-lite/deploy.sh --mode b2c \ --http-port 80 \ --admin-host admin.ecshopx.test \ --h5-host h5.ecshopx.test \ --pc-host www.ecshopx.test ``` 极速安装详情见 [`docker-lite/README.md`](docker-lite/README.md)。发行包由 `docker-lite/pack.sh`(或根目录 `./pack.sh`)在构建机上生成 `ecshopx-java-