diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 000000000..b2068acd9 --- /dev/null +++ b/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "idea": { + "url": "http://127.0.0.1:64342/stream", + "type": "http" + } + } +} \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 000000000..7b016a89f --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "java.compile.nullAnalysis.mode": "automatic" +} \ No newline at end of file diff --git a/doc/ENVIRONMENT_CHECK_AND_FIX_RECORD.md b/doc/ENVIRONMENT_CHECK_AND_FIX_RECORD.md new file mode 100644 index 000000000..b8b2b534c --- /dev/null +++ b/doc/ENVIRONMENT_CHECK_AND_FIX_RECORD.md @@ -0,0 +1,126 @@ +# litemall 环境检查与问题修复记录 + +> 记录时间：2026-09-18 +> 记录范围：本机（Windows 10）`D:\litemall` 项目的依赖环境检查、问题排查与修复全过程。 +> 结论：修复后系统已可正常运行，管理后台、H5 商城、后端 API 均验证通过。 + +## 1. 结论摘要 + +| 检查项 | 结论 | +| --- | --- | +| 本机环境（JDK 8、Maven 3.6.3、MySQL 5.7） | ✅ 齐全且可用 | +| 后端聚合服务 `litemall-all` | ✅ 可正常启动，API 正常返回数据 | +| 管理后台（`http://localhost:8080/`） | ✅ 修复后正常，默认账号 `admin123 / admin123` | +| H5 商城（`http://localhost:8080/vue/index.html`） | ✅ 修复后正常，首页数据正常加载 | +| 微信小程序相关 | ⚠️ 未配置真实 appid，仅页面与测试数据可用 | + +排查过程中发现并修复了 **4 个问题**，详见第 3 节。 + +## 2. 本机环境检查结果 + +| 项目 | 版本/位置 | 状态 | +| --- | --- | --- | +| JDK | 1.8.0_503，`JAVA_HOME=D:\java` | ✅ 正常 | +| Maven | 3.6.3，`D:\maven\apache-maven-3.6.3` | ✅ 正常 | +| MySQL | 5.7.44，以 `mysqld.exe` 运行在 3306（无 Windows 服务名） | ✅ 正常 | +| 数据库 | `litemall` 库存在，表结构完整；账号 `litemall / litemall123456` 验证通过 | ✅ 正常 | +| 系统默认 Node | v24.18.0 / npm 11.16.0 | ⚠️ 对旧前端工具链不兼容（见问题 1） | +| Node 14（构建用） | v14.21.3，`D:\node\node-v14.21.3-win-x64` | ✅ 正常 | +| Maven 本地仓库 | 已含 litemall 各模块 0.1.0 产物，但 jar 为空壳（见问题 3） | ⚠️ 已修复 | +| 前端依赖 | `litemall-admin`、`litemall-vue` 均已 `npm install` | ✅ 正常 | + +## 3. 发现的问题与修复 + +### 问题 1：系统默认 Node 24 无法构建前端（旧 Vue CLI 工具链） + +- **现象**：项目使用 Vue CLI 3/4（webpack 4）时代的技术栈，Node 24 下构建存在兼容风险。 +- **修复**：改用 Node 14（`D:\node\node-v14.21.3-win-x64`）构建，实测一次通过。 +- **用法**： + ```bash + export PATH="/d/node/node-v14.21.3-win-x64:$PATH" # Git Bash 下 + ``` + 或直接使用该目录下的 `node.exe` / `npm.cmd`。 + +### 问题 2：litemall-vue 构建报错（sass 版本 + 缺依赖） + +- **现象**：`npm run build` 报两处错误： + 1. scss 编译失败：`@import "./mixin/one-border"` 无法解析； + 2. `This dependency was not found: regenerator-runtime/runtime`。 +- **原因**：`package.json` 中 `"sass": "^1.26.2"` 的脱字符版本范围被 npm 解析到 1.104.1，与 sass-loader 7 及旧 scss 语法不兼容；`regenerator-runtime` 未直接声明，npm 新版本提升策略不同导致根目录找不到该包。 +- **修复**（`litemall-vue/package.json`）： + - `"sass": "1.26.2"`（精确锁定，与 litemall-admin 一致）； + - devDependencies 增加 `"regenerator-runtime": "^0.13.11"`； + - 用 Node 14 的 npm 重新 `npm install`。 + +### 问题 3：单独在 litemall-all 模块打包出"缺依赖"的 8MB 坏 jar + +- **现象**：在 `litemall-all` 下执行 `mvn package`，产物 jar 只有 8MB、`BOOT-INF/lib` 仅 13 个 jar，其中 litemall 模块 jar 只有约 460 字节。 +- **原因**：本地 Maven 仓库（`~/.m2`）中 litemall 各模块的 jar 是 460 字节空壳（2026-01-03 的错误产物）。单模块构建时 Spring Boot repackage 从本地仓库解析依赖，只能拿到空壳和父 pom 声明的少量 spring 依赖。 +- **修复**：必须从项目根目录整体 reactor 构建： + ```bash + cd D:\litemall && mvn clean install -DskipTests + ``` + reactor 构建使用各模块源码编译产物而非仓库空壳，同时会把正确的 jar 重新安装回本地仓库。修复后 jar 为 62MB、141 个依赖 jar，完整可用。 + +### 问题 4：生产构建的前端页面报"登录连接超时" + +- **现象**：管理后台和 H5 商城页面都能打开，但登录/首页数据请求失败，弹出"登录连接超时"。 +- **原因**：两个前端的 `.env.production` 中 `VUE_APP_BASE_API` 都是官方占位符，生产构建时被写死进 JS bundle： + - `litemall-admin/.env.production`：`https://www.example.com/admin` + - `litemall-vue/.env.production`：`https://www.example.com/` + 所有请求发往 example.com，axios 5 秒超时后触发兜底弹窗（admin 在 `src/utils/request.js:85`，vue 在 `src/utils/request.js:53`）。 +- **修复**：改为本机后端地址： + - `litemall-admin/.env.production` → `VUE_APP_BASE_API = 'http://localhost:8080/admin'` + - `litemall-vue/.env.production` → `VUE_APP_BASE_API = 'http://localhost:8080/wx'` + +## 4. 修复后的验证结果 + +| 验证项 | 结果 | +| --- | --- | +| 后端启动（`java -jar litemall-all-0.1.0-exec.jar`） | ✅ 约 7~11 秒启动成功 | +| `POST /admin/auth/login`（`admin123 / admin123`） | ✅ `errno:0`，正常返回 token | +| `http://localhost:8080/`（管理后台页面） | ✅ 200 | +| `http://localhost:8080/vue/index.html`（H5 商城页面） | ✅ 200 | +| `GET /wx/home/index`（商城首页 API） | ✅ 200，正常返回商品数据 | +| `GET /wx/index/index`、`GET /admin/index/index` | ✅ 200 | + +注意：`/vue/` 直接访问是 404（Spring Boot 子目录不会自动补 `index.html`），需访问 `/vue/index.html`，这是项目原有行为。 + +## 5. 本机标准构建与启动流程（已验证） + +```bash +# 1. 构建前端（必须用 Node 14） +export PATH="/d/node/node-v14.21.3-win-x64:$PATH" +cd D:/litemall/litemall-admin && npm run build +cd D:/litemall/litemall-vue && npm run build + +# 2. 从根目录整体构建后端（必须 reactor 构建，原因见问题 3） +cd D:/litemall && mvn clean install -DskipTests + +# 3. 启动 +cd D:/litemall/litemall-all && java -jar target/litemall-all-0.1.0-exec.jar +``` + +访问地址： + +- 管理后台：`http://localhost:8080/`（账号 `admin123 / admin123`） +- H5 商城：`http://localhost:8080/vue/index.html` +- 管理 API：`http://localhost:8080/admin/...` +- 商城 API：`http://localhost:8080/wx/...` + +## 6. 未提交 Git 的本地改动清单 + +排查修复涉及以下文件改动（截至 2026-09-18 尚未提交）： + +| 文件 | 改动 | +| --- | --- | +| `litemall-vue/package.json` | sass 锁定 1.26.2；新增 devDependency regenerator-runtime | +| `litemall-vue/package-lock.json` | 随上述依赖调整更新 | +| `litemall-admin/.env.production` | `VUE_APP_BASE_API` 改为 `http://localhost:8080/admin` | +| `litemall-vue/.env.production` | `VUE_APP_BASE_API` 改为 `http://localhost:8080/wx` | + +## 7. 遗留注意点 + +- `litemall-core/src/main/resources/application-core.yml` 中微信 appid/secret、商户号、云存储密钥等仍为官方示例值。微信登录（报 40029 invalid code）、支付、短信、物流等需要真实配置后才能使用，不影响本地页面浏览和测试数据。 +- 默认数据库密码、默认管理员账号属于开发配置，正式部署前必须修改。 +- 管理后台、H5 商城的开发模式（`npm run dev`）不受第 4 节问题影响，因为 `.env.development` 使用相对路径 `/admin`、`/wx` 并走 devServer 代理。 diff --git a/doc/PROJECT_ANALYSIS_AND_USER_MANUAL.md b/doc/PROJECT_ANALYSIS_AND_USER_MANUAL.md new file mode 100644 index 000000000..2437bcc37 --- /dev/null +++ b/doc/PROJECT_ANALYSIS_AND_USER_MANUAL.md @@ -0,0 +1,456 @@ +# litemall 项目分析报告与使用手册 + +本文档基于当前仓库 `D:\litemall` 的实际结构整理，目标是让新成员能够快速理解项目、搭建环境、启动系统、定位配置，并具备二次开发和部署的基本判断。本机环境曾实际排查并修复过一批环境问题（Node 版本、Maven 空壳依赖、前端 API 占位符等），完整记录见同目录 `ENVIRONMENT_CHECK_AND_FIX_RECORD.md`，相关问题答案已并入本文档第 6、7、9、14 章。 + +## 1. 项目概览 + +`litemall` 是一个学习型、原型级的小商城系统，整体由 Spring Boot 后端、Vue 管理后台、微信小程序商城、Vue 移动商城组成。项目覆盖了电商系统的典型链路：商品展示、分类、品牌、购物车、下单、订单、支付、售后、优惠券、团购、会员、后台运营、权限、对象存储、通知和统计报表。 + +当前项目是一个多端商城工程： + +- 后端：Spring Boot 2.1.5.RELEASE + Maven 多模块。 +- 数据库：MySQL + MyBatis + PageHelper + Druid。 +- 管理后台：Vue 2 + Element UI，默认开发端口 `9527`。 +- 移动 H5 商城：Vue 2 + Vant，默认开发端口通常为 `6255`。 +- 微信小程序：原生小程序项目，接口指向 `/wx` 后端。 +- 部署：支持手工部署、外部配置覆盖、Docker Compose。 + +项目适合作为商城系统学习、课程设计、内部原型或二次开发基础。若要正式商用，应先完成安全加固、支付链路重审、依赖升级评估、监控告警、备份恢复和压力测试。 + +## 2. 目录结构分析 + +| 路径 | 作用 | +| --- | --- | +| `pom.xml` | Maven 父工程，统一管理后端模块、版本和依赖。 | +| `litemall-core` | 后端通用能力模块，包括响应封装、校验、微信配置、对象存储、通知、物流、异步任务等。 | +| `litemall-db` | 数据访问模块，包括 MyBatis Mapper、领域对象、业务 Service、数据库脚本。 | +| `litemall-admin-api` | 管理后台 REST API，路径前缀主要为 `/admin`。 | +| `litemall-wx-api` | 小程序/H5 商城 REST API，路径前缀主要为 `/wx`。 | +| `litemall-all` | 聚合后端服务，将 core、db、admin-api、wx-api 打包为一个可运行 Jar。 | +| `litemall-all-war` | WAR 包部署形态。 | +| `litemall-admin` | 管理后台 Vue 前端。 | +| `litemall-vue` | 移动 H5 商城 Vue 前端。 | +| `litemall-wx` | 微信小程序商城端。 | +| `renard-wx` | 另一套微信小程序前端实现。 | +| `litemall-db/sql` | 数据库初始化脚本。 | +| `docker` | Docker Compose 和后端镜像构建配置。 | +| `deploy` | 传统服务器部署脚本和示例配置。 | +| `doc` | 原项目文档和本文档。 | +| `storage` | 本地对象存储目录，上传文件可能写入这里。 | +| `logs` | 本地日志目录。 | + +## 3. 后端架构 + +后端采用 Maven 父子模块结构。推荐开发和本地演示时优先运行 `litemall-all`。它依赖 `core`、`db`、`wx-api` 和 `admin-api`，统一启动后同时提供： + +- 管理后台接口：`http://localhost:8080/admin/...` +- 商城端接口：`http://localhost:8080/wx/...` + +### 3.1 litemall-core + +该模块提供跨业务复用能力： + +- 统一响应工具 `ResponseUtil` +- 全局异常处理 +- 参数校验 +- Jackson 配置 +- CORS 跨域配置 +- 异步任务配置 +- 微信小程序和微信支付配置 +- 邮件、短信通知能力 +- 本地/阿里云/腾讯云/七牛对象存储 +- 物流查询配置 +- 二维码服务 +- 系统配置加载 + +核心配置文件是 `litemall-core/src/main/resources/application-core.yml`。其中包含微信、通知、物流、对象存储等配置。当前文件中存在示例 appid、secret、云存储 key 等字段，正式使用时必须替换为自己的配置，不能直接沿用示例值。 + +### 3.2 litemall-db + +该模块是数据访问层和基础业务服务层： + +- `domain`：数据库表对应的实体对象和 Example 查询对象。 +- `dao`：MyBatis Mapper。 +- `service`：面向业务模块的数据库服务。 +- `util`：订单、优惠券、团购、售后等业务常量与工具。 +- `mybatis`：JSON 类型处理器。 +- `sql`：数据库脚本。 + +核心配置文件是 `litemall-db/src/main/resources/application-db.yml`。默认数据库配置： + +- 地址：`jdbc:mysql://localhost:3306/litemall` +- 用户名：`litemall` +- 密码：`litemall123456` +- 时区：`Asia/Shanghai` + +数据库初始化脚本顺序：`litemall_schema.sql`、`litemall_table.sql`、`litemall_data.sql`。 + +### 3.3 litemall-admin-api + +该模块提供管理后台接口，典型控制器包括会员、商品、订单、售后、推广、系统、配置、统计等模块。管理端安全使用 Apache Shiro，配合角色、权限和验证码能力。管理后台接口通常以 `/admin` 为前缀。 + +### 3.4 litemall-wx-api + +该模块提供小程序和 H5 商城接口，覆盖登录注册、首页、分类、商品、品牌、购物车、订单、地址、收藏、足迹、评价、反馈、优惠券、团购、专题、搜索、售后、文件存储等功能。商城端接口通常以 `/wx` 为前缀。用户登录态使用 JWT 相关工具和 `@LoginUser` 参数解析机制。 + +### 3.5 litemall-all + +这是本地最常用的后端入口。配置文件是 `litemall-all/src/main/resources/application.yml`。 + +```yaml +spring: + profiles: + active: db, core, admin, wx + +server: + port: 8080 +``` + +这表示启动 `litemall-all` 时会同时加载数据库、核心能力、管理端、商城端配置。默认服务端口是 `8080`。 + +## 4. 前端架构 + +### 4.1 管理后台 litemall-admin + +目录：`litemall-admin` + +技术栈：Vue 2.6、Vue Router、Vuex、Element UI、Axios、ECharts、v-charts、vue-element-admin 风格脚手架。 + +主要页面目录： + +- `src/views/user`：会员相关。 +- `src/views/mall`：商城运营相关。 +- `src/views/goods`：商品管理。 +- `src/views/promotion`：推广营销。 +- `src/views/sys`：系统管理。 +- `src/views/config`：配置管理。 +- `src/views/stat`：统计报表。 +- `src/views/profile`：个人中心。 + +开发环境接口配置：`litemall-admin/.env.development` 中的 `VUE_APP_BASE_API = '/admin'`。前端开发服务启动后访问 `http://localhost:9527`。注意生产构建读取的是 `.env.production`，默认是占位符地址，构建前必须修改（见 14.6）。 + +### 4.2 移动 H5 商城 litemall-vue + +目录：`litemall-vue` + +技术栈：Vue 2、Vue Router、Vuex、Vant、Axios。主要页面目录包括 `home`、`items`、`login`、`order`、`user`。开发环境接口配置为 `litemall-vue/.env.development` 中的 `VUE_APP_BASE_API = '/wx'`。启动后通常访问 `http://localhost:6255`。生产构建同样需要先修改 `.env.production` 的接口地址（见 14.6）。该模块原文档中标注为开发中，稳定性弱于管理后台和小程序端。 + +### 4.3 微信小程序 litemall-wx + +目录：`litemall-wx` + +接口配置文件是 `litemall-wx/config/api.js`。默认接口根地址： + +```js +var WxApiRoot = 'http://localhost:8080/wx/'; +``` + +微信小程序开发时，需要在微信开发者工具中导入 `litemall-wx`，并根据实际情况配置自己的小程序 appid。开发阶段可启用“不校验合法域名、web-view、TLS 版本以及 HTTPS 证书”。 + +## 5. 数据库设计与初始化 + +数据库脚本位于 `litemall-db/sql`： + +1. 执行 `litemall_schema.sql`，创建数据库、用户和权限。 +2. 执行 `litemall_table.sql`，创建业务表。 +3. 执行 `litemall_data.sql`，导入测试数据。 + +默认数据库名为 `litemall`，用户名为 `litemall`，密码为 `litemall123456`。 + +设计特点： + +- 表之间没有大量使用数据库外键，主要依赖 Java Service 层维护业务关系。 +- 便于快速修改表结构，但对代码校验和业务一致性要求更高。 +- 上线前建议补充约束、索引、审计日志和关键业务保护。 + +## 6. 本地开发环境准备 + +建议安装：JDK 8 或以上、Maven、MySQL 5.7 或兼容版本、Node.js 和 npm、微信开发者工具、Git、IDEA、VS Code。 + +版本提醒：后端声明 Java 版本为 `1.8`，Spring Boot 版本为 `2.1.5.RELEASE`。管理后台要求 Node `>=8.9`、npm `>=3.0.0`，但**构建前端强烈建议使用 Node 14 及更旧的 LTS 版本**：实测 Node 24 无法可靠构建这套 Vue CLI 3/4（webpack 4）项目。本机已在 `D:\node\node-v14.21.3-win-x64` 放置 Node 14.21.3，构建前执行： + +```bash +export PATH="/d/node/node-v14.21.3-win-x64:$PATH" # Git Bash +``` + +本机当前环境（2026-09-18 已验证可完整运行）：JDK 8（`JAVA_HOME=D:\java`）、Maven 3.6.3、MySQL 5.7（端口 3306，无 Windows 服务名，库 `litemall`，账号 `litemall / litemall123456`）。 + +## 7. 本地启动手册 + +### 7.1 启动数据库 + +确保 MySQL 已启动，然后按顺序导入脚本： + +```bash +mysql -uroot -p < litemall-db/sql/litemall_schema.sql +mysql -uroot -p litemall < litemall-db/sql/litemall_table.sql +mysql -uroot -p litemall < litemall-db/sql/litemall_data.sql +``` + +如果不用命令行，也可以使用 MySQL Workbench 等工具按顺序执行脚本。 + +### 7.2 启动后端 + +**重要：必须在项目根目录整体构建**（reactor 构建）。不要单独进入 `litemall-all` 执行 `mvn package`：如果本地 Maven 仓库中的 litemall 模块 jar 是空壳（本机曾出现 460 字节空壳 jar 的情况），单模块构建会打出只有 8MB、缺少全部业务依赖的坏 jar，启动后接口全部 404。 + +在项目根目录执行： + +```bash +cd D:\litemall +mvn clean install -DskipTests +java -Dfile.encoding=UTF-8 -jar litemall-all/target/litemall-all-0.1.0-exec.jar +``` + +也可以进入 `litemall-all` 模块用 `mvn spring-boot:run` 启动（同样建议先在根目录 `mvn install` 保证依赖完整）。 + +启动成功后可访问： + +- `http://localhost:8080/wx/index/index` +- `http://localhost:8080/admin/index/index` + +如果返回 JSON，说明后端聚合服务正常。 + +如果前端已完成生产构建并打入 jar（见第 9 章），则单 jar 即可同时提供页面： + +- 管理后台：`http://localhost:8080/`（默认账号 `admin123 / admin123`） +- H5 商城：`http://localhost:8080/vue/index.html`（注意 `/vue/` 不带文件名会 404，属 Spring Boot 原有行为） + +### 7.3 启动管理后台 + +```bash +cd litemall-admin +npm install +npm run dev +``` + +访问 `http://localhost:9527`。如果登录页面出现，说明前端服务正常。若登录失败，优先检查后端 `8080` 服务、数据库初始化和代理配置。 + +### 7.4 启动移动 H5 商城 + +```bash +cd litemall-vue +npm install +npm run dev +``` + +访问 `http://localhost:6255`，建议使用 Chrome 手机模拟模式查看。 + +### 7.5 启动微信小程序 + +1. 打开微信开发者工具。 +2. 导入 `litemall-wx` 目录。 +3. 确认 `litemall-wx/config/api.js` 中的 `WxApiRoot` 指向后端，例如 `http://localhost:8080/wx/`。 +4. 开发阶段可关闭合法域名校验。 +5. 点击编译。 + +微信登录、支付、订阅消息等功能依赖真实微信 appid、secret、商户号、支付密钥和回调域名。默认配置只能支持普通页面和测试数据浏览，不能代表完整线上链路。 + +## 8. 常用配置说明 + +| 配置项 | 文件 | 说明 | +| --- | --- | --- | +| 后端端口 | `litemall-all/src/main/resources/application.yml` | 默认 `8080`。 | +| 数据库连接 | `litemall-db/src/main/resources/application-db.yml` | 配置 URL、用户名、密码。 | +| 微信配置 | `litemall-core/src/main/resources/application-core.yml` | 配置 appid、secret、商户号、支付回调。 | +| 对象存储 | `litemall-core/src/main/resources/application-core.yml` | 支持 local、aliyun、tencent、qiniu。 | +| 通知配置 | `litemall-core/src/main/resources/application-core.yml` | 支持邮件、腾讯云短信、阿里云短信。 | +| 管理后台接口 | `litemall-admin/.env.development` | 默认 `/admin`。 | +| H5 商城接口 | `litemall-vue/.env.development` | 默认 `/wx`。 | +| 小程序接口 | `litemall-wx/config/api.js` | 默认 `http://localhost:8080/wx/`。 | + +## 9. 打包与部署 + +后端 Jar 包（从根目录整体构建，原因见 7.2）： + +```bash +cd D:\litemall +mvn clean install -DskipTests +java -Dfile.encoding=UTF-8 -jar litemall-all/target/litemall-all-0.1.0-exec.jar +``` + +管理后台生产构建： + +```bash +cd litemall-admin +npm run build:prod +``` + +移动 H5 生产构建： + +```bash +cd litemall-vue +npm run build:prod +``` + +前端生产构建注意事项： + +- **必须使用 Node 14 或更旧 LTS**（见第 6 章），Node 24 下构建可能失败。 +- **构建前必须修改 `.env.production` 的 `VUE_APP_BASE_API`**。仓库默认值是占位符 `https://www.example.com/...`，会写死进 bundle，导致页面所有请求超时并弹出"登录连接超时"。本机开发时应分别改为： + - `litemall-admin/.env.production` → `http://localhost:8080/admin` + - `litemall-vue/.env.production` → `http://localhost:8080/wx` +- 开发模式（`npm run dev`）不受此影响，因为 `.env.development` 使用相对路径并走 devServer 代理。 + +`litemall-all/pom.xml` 中配置了资源复制：`../litemall-admin/dist` 会复制到 `target/classes/static`，`../litemall-vue/dist` 会复制到 `target/classes/static/vue`。因此如需打包成一个后端 Jar 同时托管前端，应先构建前端，再从根目录构建 `litemall-all`。若 `dist` 目录为空，jar 将不含任何前端页面（根路径 404）。 + +Docker 配置位于 `docker/docker-compose.yml`，包含 `mysql57` 和 `litemall` 两个服务。正式环境必须修改密码、存储卷、网络暴露策略和后端外部配置。 + +## 10. 业务功能地图 + +商城用户端主要功能： + +- 首页、分类、品牌、专题 +- 新品、人气推荐 +- 商品详情、规格、库存 +- 搜索、搜索历史 +- 购物车、下单、取消、支付、确认收货 +- 订单列表、订单详情、售后申请 +- 优惠券领取与使用、团购 +- 收货地址、收藏、足迹、评论、意见反馈、个人中心 + +管理后台主要功能： + +- 会员管理、地址、收藏、足迹、搜索历史、反馈 +- 行政区域、品牌、订单、类目、通用问题、关键词 +- 商品列表、商品上架、商品编辑、用户评论 +- 广告、专题、团购规则、团购活动、优惠券 +- 管理员、角色、权限、通知、对象存储、操作日志 +- 商场配置、小程序配置、运费配置、订单配置 +- 用户统计、订单统计、商品统计 +- 个人中心、通知中心、密码修改 + +## 11. 二次开发指南 + +新增后台接口推荐流程： + +1. 在 `litemall-db` 中确认或新增数据表。 +2. 如需生成实体和 Mapper，使用 MyBatis Generator 配置。 +3. 在 `litemall-db/service` 中封装数据库操作。 +4. 在 `litemall-admin-api/web` 中新增 Controller。 +5. 使用 `ResponseUtil` 返回统一响应。 +6. 如涉及权限，在管理端权限体系中补充权限标识。 +7. 在 `litemall-admin/src/api` 中新增前端请求方法。 +8. 在 `litemall-admin/src/views` 中新增页面或表单。 + +新增商城端接口推荐流程： + +1. 在 `litemall-db` 中准备 Service。 +2. 在 `litemall-wx-api/web` 中新增 `Wx...Controller`。 +3. 需要登录态时使用 `@LoginUser Integer userId`。 +4. 在小程序 `config/api.js` 或 H5 前端 API 文件中补充接口地址。 +5. 在小程序页面或 H5 页面中调用。 + +修改数据库表注意事项： + +- 当前表关系主要靠业务代码维护，不要只改表而忽略 Service 和 Controller。 +- 修改字段后要同步实体、Mapper XML、Example 查询对象。 +- 涉及订单、库存、支付、退款的表结构变更必须补充回归测试。 +- 生产环境应使用迁移脚本，不建议手工直接改库。 + +## 12. 响应格式和错误码 + +后端统一响应大致为： + +```json +{ + "errno": 0, + "errmsg": "成功", + "data": {} +} +``` + +错误码分层： + +- `4xx`：参数或请求使用错误。 +- `5xx`：系统级错误或登录状态错误。 +- `6xx`：管理后台业务错误。 +- `7xx`：商城端业务错误。 + +前端应按错误码做统一处理，具体业务错误再在页面内展示。 + +## 13. 安全与上线风险 + +上线前必须重点处理： + +- 修改默认数据库密码。 +- 修改默认管理员账号和密码。 +- 替换所有示例 appid、secret、云存储密钥、短信密钥、邮件密码。 +- 不要把真实密钥提交到 Git。 +- 关闭或限制 Swagger、调试日志和不必要的公开接口。 +- 后端 `8080` 端口建议只允许内网访问，由 Nginx 反向代理暴露 HTTPS。 +- 小程序上线必须配置合法域名和 HTTPS。 +- 微信支付回调地址必须使用真实 HTTPS 域名。 +- 退款功能风险高，建议增加人工复核、短信验证、限额或改为到微信商户平台人工处理。 +- 图片上传、验证码、登录接口需要限流。 +- 订单、支付、退款、库存等关键操作需要审计日志。 +- 需要定期备份数据库和上传文件目录。 + +## 14. 常见问题 + +### 14.1 后端启动失败，提示数据库连接失败 + +检查 MySQL 是否启动、是否导入了 `litemall_schema.sql`、用户名密码是否仍为 `litemall / litemall123456`，以及 `application-db.yml` 中端口、库名、时区是否正确。 + +### 14.2 管理后台页面能打开，但登录失败 + +检查 `http://localhost:8080/admin/index/index` 是否有响应，管理后台 `.env.development` 是否为 `/admin`，前端开发服务代理是否正常，数据库测试数据是否导入。 + +### 14.3 小程序没有数据 + +检查 `litemall-wx/config/api.js` 的 `WxApiRoot` 是否指向可访问的后端，`http://localhost:8080/wx/home/index` 是否有响应，微信开发者工具是否关闭了开发阶段合法域名校验。手机真机预览时，`localhost` 指的是手机自身，应改成电脑局域网 IP。 + +### 14.4 前端依赖安装失败 + +原因通常是项目较旧、依赖版本较老。建议使用较旧 Node LTS 版本，删除 `node_modules` 后重新安装，使用稳定 npm registry，并避免随意升级 Vue CLI、Webpack、Element UI、Vant 等大版本。 + +### 14.5 图片上传后无法访问 + +检查 `litemall.storage.active` 是否为 `local`，`storagePath` 是否存在且后端进程有写权限，`address` 是否指向正确后端地址。如果部署在服务器，确认反向代理是否允许访问 `/wx/storage/fetch/`。 + +### 14.6 页面能打开，但登录/首页数据弹"登录连接超时" + +这是生产构建最常见的问题：`.env.production` 中的 `VUE_APP_BASE_API` 还是官方占位符 `https://www.example.com/...`，请求发往不存在的地址，axios 5 秒超时后触发前端兜底弹窗（管理后台提示在 `src/utils/request.js:85`，H5 商城在 `src/utils/request.js:53`）。修复：按第 9 章把两个 `.env.production` 改成真实后端地址后重新构建。开发模式下出现该提示，则检查 devServer 代理或后端 8080 服务是否存活。 + +### 14.7 打包出的 jar 很小（几 MB），启动后接口 404 或依赖缺失 + +大概率在 `litemall-all` 下单独执行了 `mvn package`，而本地 Maven 仓库里的 litemall 模块 jar 是空壳（约 460 字节，可用 `ls -la ~/.m2/repository/org/linlinjava/*/0.1.0/*.jar` 检查）。修复：在项目根目录执行 `mvn clean install -DskipTests` 整体 reactor 构建，正常产物约 60MB 以上、`BOOT-INF/lib` 含 140 个左右依赖 jar。 + +### 14.8 H5 商城前端构建报 scss 错误或找不到 regenerator-runtime + +`litemall-vue/package.json` 中 `"sass": "^1.26.2"` 的脱字符范围会装到不兼容的新版本（如 1.104），导致 `@import "./mixin/one-border"` 之类的旧语法编译失败；`regenerator-runtime` 未被直接声明时 npm 新版本也可能不在根目录提升。修复：sass 精确锁定 `"1.26.2"`（与 litemall-admin 一致），devDependencies 补 `"regenerator-runtime": "^0.13.11"`，再用 Node 14 重新 `npm install`。 + +### 14.9 高版本 Node（如 24）下前端构建失败 + +该前端基于 Vue CLI 3/4 + webpack 4，与 Node 17+ 存在 OpenSSL/工具链兼容问题。不要在高版本 Node 下折腾兼容参数，直接使用 Node 14 构建（本机路径 `D:\node\node-v14.21.3-win-x64`），实测一次通过。 + +## 15. 推荐开发顺序 + +1. 导入数据库，启动 `litemall-all`。 +2. 访问 `/wx/index/index` 和 `/admin/index/index` 验证后端。 +3. 启动 `litemall-admin`，熟悉后台功能菜单。 +4. 启动 `litemall-wx` 或 `litemall-vue`，体验用户下单链路。 +5. 阅读 `litemall-db/service`，理解数据操作。 +6. 阅读 `litemall-admin-api/web` 和 `litemall-wx-api/web`，理解接口组织。 +7. 阅读 `litemall-core`，理解配置、存储、通知、异常处理。 +8. 再开始修改业务功能。 + +## 16. 当前项目总体评价 + +优点： + +- 模块划分清晰，适合学习完整商城业务。 +- 管理端、用户端、数据库、部署资料比较齐全。 +- 后端分层直观，Controller、Service、Mapper 易于定位。 +- 支持多种对象存储、通知、微信支付和小程序能力。 +- 聚合模块 `litemall-all` 降低了本地启动复杂度。 + +不足和风险： + +- 项目依赖整体偏旧，前端依赖尤其需要注意 Node 版本兼容（本机实测用 Node 14 可正常构建，Node 24 不可靠）。 +- 前端 `.env.production` 与 `application-core.yml` 默认值均含占位符/示例值，首次打包极易踩坑，需按第 9 章修改后再构建。 +- 默认配置含大量示例密钥和弱密码，上线前必须清理。 +- 数据库缺少外键，业务一致性依赖代码质量。 +- 安全能力偏基础，正式商用需要补充限流、审计、风控和权限加固。 +- H5 移动商城原文档标注仍不稳定。 +- 支付、退款、售后等资金相关流程必须重新评审。 + +结论：该项目适合作为商城系统学习、课程设计、二次开发起点或内部原型。若要正式商用，应先完成安全加固、依赖升级评估、支付链路重审、部署隔离、监控告警、备份恢复和压力测试。 diff --git a/doc/test b/doc/test new file mode 100644 index 000000000..0386f13f6 --- /dev/null +++ b/doc/test @@ -0,0 +1 @@ +26/10/10,14:23第一次推送 \ No newline at end of file diff --git a/litemall-admin/.env.production b/litemall-admin/.env.production index 4c05b9677..b33c32109 100644 --- a/litemall-admin/.env.production +++ b/litemall-admin/.env.production @@ -4,5 +4,5 @@ NODE_ENV = production ENV = 'production' # base api -VUE_APP_BASE_API = 'https://www.example.com/admin' +VUE_APP_BASE_API = 'http://localhost:8080/admin' diff --git a/litemall-vue/.env.production b/litemall-vue/.env.production index 97821ab79..5585cb57f 100644 --- a/litemall-vue/.env.production +++ b/litemall-vue/.env.production @@ -2,4 +2,4 @@ ENV = 'production' # base api -VUE_APP_BASE_API = 'https://www.example.com/' \ No newline at end of file +VUE_APP_BASE_API = 'http://localhost:8080/wx' \ No newline at end of file diff --git a/litemall-vue/package.json b/litemall-vue/package.json index e9b816307..95380e913 100644 --- a/litemall-vue/package.json +++ b/litemall-vue/package.json @@ -32,7 +32,8 @@ "@vue/eslint-config-prettier": "^3.0.5", "babel-plugin-import": "^1.9.1", "babel-plugin-lodash": "^3.3.4", - "sass": "^1.26.2", + "regenerator-runtime": "^0.13.11", + "sass": "1.26.2", "sass-loader": "^7.1.0", "vue-template-compiler": "^2.5.17" }, diff --git a/litemall-vue/src/views/items/detail/index.vue b/litemall-vue/src/views/items/detail/index.vue index 41fb8d5d6..ce9de8345 100755 --- a/litemall-vue/src/views/items/detail/index.vue +++ b/litemall-vue/src/views/items/detail/index.vue @@ -260,7 +260,7 @@ export default { const list = this.setSkuList(); const skuInfo = { price: parseInt(this.goods.info.retailPrice), // 未选择规格时的价格 - stock_num: 0, // TODO 总库存 + stock_num: _.sumBy(this.goods.productList, 'number'), collection_id: '', // 无规格商品skuId取collection_id，否则取所选sku组合对应的id none_sku: false, // 是否无规格商品 hide_stock: true diff --git a/litemall-wx/project.config.json b/litemall-wx/project.config.json index 0a6c5e06a..58129841b 100644 --- a/litemall-wx/project.config.json +++ b/litemall-wx/project.config.json @@ -32,11 +32,15 @@ "minifyWXML": true, "showES6CompileOption": false, "useCompilerPlugins": false, - "ignoreUploadUnusedFiles": true + "ignoreUploadUnusedFiles": true, + "compileWorklet": false, + "enhance": false, + "localPlugins": false, + "condition": false }, "compileType": "miniprogram", "libVersion": "2.4.0", - "appid": "wxa5b486c6b918ecfb", + "appid": "wx5f03b7621a01ec38", "projectname": "litemall-wx", "simulatorType": "wechat", "simulatorPluginLibVersion": {}, @@ -323,5 +327,10 @@ } ] } - } + }, + "packOptions": { + "ignore": [], + "include": [] + }, + "editorSetting": {} } \ No newline at end of file diff --git a/litemall-wx/project.private.config.json b/litemall-wx/project.private.config.json index 4a98289a6..9a34a27b3 100644 --- a/litemall-wx/project.private.config.json +++ b/litemall-wx/project.private.config.json @@ -1,282 +1,23 @@ { - "setting": {}, - "condition": { - "plugin": { - "list": [] - }, - "game": { - "list": [] - }, - "gamePlugin": { - "list": [] - }, - "miniprogram": { - "list": [ - { - "id": -1, - "name": "首页", - "pathName": "pages/index/index", - "query": "" - }, - { - "id": -1, - "name": "专题", - "pathName": "pages/topic/topic", - "query": "" - }, - { - "id": -1, - "name": "专题详情", - "pathName": "pages/topicDetail/topicDetail", - "query": "id=314" - }, - { - "id": -1, - "name": "专题评论列表", - "pathName": "pages/topicComment/topicComment", - "query": "valueId=314&type=1" - }, - { - "id": -1, - "name": "专题评论添加", - "pathName": "pages/topicCommentPost/topicCommentPost", - "query": "valueId=314&type=1" - }, - { - "id": -1, - "name": "品牌", - "pathName": "pages/brand/brand", - "query": "" - }, - { - "id": -1, - "name": "品牌详情", - "pathName": "pages/brandDetail/brandDetail", - "query": "id=1001000" - }, - { - "id": -1, - "name": "人气推荐", - "pathName": "pages/hotGoods/hotGoods", - "query": "" - }, - { - "id": -1, - "name": "新品首发", - "pathName": "pages/newGoods/newGoods", - "query": "" - }, - { - "id": -1, - "name": "分类", - "pathName": "pages/catalog/catalog", - "query": "" - }, - { - "id": -1, - "name": "分类详情", - "pathName": "pages/category/category", - "query": "id=1008002" - }, - { - "id": -1, - "name": "查找", - "pathName": "pages/search/search", - "query": "" - }, - { - "name": "商品", - "pathName": "pages/goods/goods", - "query": "id=1181267", - "scene": null, - "launchMode": "default" - }, - { - "id": -1, - "name": "商品评论列表", - "pathName": "pages/comment/comment", - "query": "valueId=1181000&type=0" - }, - { - "id": -1, - "name": "购物车", - "pathName": "pages/cart/cart", - "query": "" - }, - { - "id": -1, - "name": "下单", - "pathName": "pages/checkout/checkout", - "query": "" - }, - { - "id": -1, - "name": "支付结果", - "pathName": "pages/payResult/payResult", - "query": "" - }, - { - "id": -1, - "name": "我的", - "pathName": "pages/ucenter/index/index", - "query": "" - }, - { - "id": -1, - "name": "我的订单列表", - "pathName": "pages/ucenter/order/order", - "query": "" - }, - { - "id": -1, - "name": "我的订单详情", - "pathName": "pages/ucenter/orderDetail/orderDetail", - "query": "id=1" - }, - { - "id": 22, - "name": "待评价的订单详情", - "pathName": "pages/ucenter/orderDetail/orderDetail", - "query": "id=1" - }, - { - "id": -1, - "name": "购买商品评价", - "pathName": "pages/commentPost/commentPost", - "query": "orderId=2&type=0&valueId=1116011" - }, - { - "id": 22, - "name": "我的优惠券", - "pathName": "pages/ucenter/couponList/couponList", - "query": "" - }, - { - "id": -1, - "name": "我的收藏", - "pathName": "pages/ucenter/collect/collect", - "query": "" - }, - { - "id": -1, - "name": "我的足迹", - "pathName": "pages/ucenter/footprint/footprint", - "query": "" - }, - { - "id": -1, - "name": "我的地址", - "pathName": "pages/ucenter/address/address", - "query": "" - }, - { - "id": -1, - "name": "我的地址添加", - "pathName": "pages/ucenter/addressAdd/addressAdd", - "query": "" - }, - { - "id": -1, - "name": "登录", - "pathName": "pages/auth/login/login", - "query": "" - }, - { - "id": -1, - "name": "账号登录", - "pathName": "pages/auth/accountLogin/accountLogin", - "query": "" - }, - { - "id": -1, - "name": "注册", - "pathName": "pages/auth/register/register", - "query": "" - }, - { - "id": -1, - "name": "找回密码", - "pathName": "pages/auth/reset/reset", - "query": "" - }, - { - "id": -1, - "name": "关于", - "pathName": "pages/about/about", - "query": "" - }, - { - "id": -1, - "name": "测试更新", - "pathName": "pages/index/index", - "query": "" - }, - { - "id": -1, - "name": "意见反馈", - "pathName": "pages/ucenter/feedback/feedback", - "query": "" - }, - { - "id": -1, - "name": "团购专区", - "pathName": "pages/groupon/grouponList/grouponList", - "query": "" - }, - { - "id": -1, - "name": "选择优惠券", - "pathName": "pages/ucenter/couponSelect/couponSelect", - "query": "" - }, - { - "id": -1, - "name": "我的优惠券列表", - "pathName": "pages/ucenter/couponList/couponList", - "query": "" - }, - { - "id": -1, - "name": "优惠券列表", - "pathName": "pages/coupon/coupon", - "query": "" - }, - { - "id": -1, - "name": "帮助中心", - "pathName": "pages/help/help", - "query": "", - "scene": null - }, - { - "id": -1, - "name": "我的团购", - "pathName": "pages/groupon/myGroupon/myGroupon", - "query": "", - "scene": null - }, - { - "id": -1, - "name": "申请售后", - "pathName": "pages/ucenter/aftersale/aftersale", - "query": "id=2", - "scene": null - }, - { - "id": -1, - "name": "售后列表", - "pathName": "pages/ucenter/aftersaleList/aftersaleList", - "query": "", - "scene": null - }, - { - "id": -1, - "name": "售后详情", - "pathName": "pages/ucenter/aftersaleDetail/aftersaleDetail", - "query": "id=1", - "scene": null - } - ] - } - } + "setting": { + "urlCheck": false, + "coverView": true, + "lazyloadPlaceholderEnable": false, + "skylineRenderEnable": false, + "preloadBackgroundData": false, + "autoAudits": false, + "useApiHook": true, + "showShadowRootInWxmlPanel": true, + "useStaticServer": false, + "useLanDebug": false, + "showES6CompileOption": false, + "compileHotReLoad": true, + "checkInvalidKey": true, + "ignoreDevUnusedFiles": true, + "bigPackageSizeSupport": false, + "useIsolateContext": true + }, + "condition": {}, + "libVersion": "3.17.2", + "projectname": "litemall-wx" } \ No newline at end of file