novalon/gym-manage

Fork 0

Files

T

张翔 6e0227f905 docs: 添加健身房管理系统基础设施重构设计规格

2026-04-17 18:10:34 +08:00

16 KiB

Raw Permalink Blame History

健身房管理系统基础设施重构设计规格

文档版本：1.0
创建日期：2026-04-17
作者：张翔
状态：已批准

1. 项目概况

1.1 背景

当前项目为一个通用的后台管理系统，需要根据业务需求调整为健身房管理系统。本次重构仅涉及基础设施层面，包括项目重命名、包名修改、测试迁移和移动端项目创建，不涉及业务功能的修改。

1.2 目标

将 novalon-manage-api 重构为 gym-manage-api
将 novalon-manage-web 重构为 gym-manage-web
创建 gym-manage-uniapp 移动端项目脚手架
创建独立的 e2e-tests 测试目录
整理根目录，保持整洁
修改 Java 包名从 cn.novalon.manage 到 cn.novalon.gym.manage

1.3 远程仓库

https://git.f.novalon.cn/novalon/gym-manage.git

1.4 范围界定

包含：

项目目录和文件重命名
Java 包名修改
Maven/NPM 配置更新
测试文件迁移
UniApp 项目脚手架创建
全局配置和文档更新

不包含：

业务功能修改
数据库表结构修改
API 接口修改
UI/UX 设计调整

2. 最终目录结构

gym-manage/                           # 根目录
├── gym-manage-api/                   # 后端项目（原 novalon-manage-api）
│   ├── manage-app/                   # 主应用模块
│   ├── manage-gateway/               # API 网关模块
│   ├── manage-sys/                   # 系统管理模块
│   ├── manage-db/                    # 数据库模块
│   ├── manage-common/                # 公共模块
│   ├── manage-audit/                 # 审计模块
│   ├── manage-notify/                # 通知模块
│   ├── manage-file/                  # 文件管理模块
│   ├── pom.xml                       # Maven 父 POM
│   └── Dockerfile                    # 后端 Docker 配置
│
├── gym-manage-web/                   # 前端项目（原 novalon-manage-web）
│   ├── src/                          # 源代码
│   ├── public/                       # 静态资源
│   ├── package.json                  # NPM 依赖
│   ├── vite.config.ts                # Vite 配置
│   └── Dockerfile                    # 前端 Docker 配置
│
├── gym-manage-uniapp/                # 移动端项目（新建）
│   ├── src/                          # 源代码
│   │   ├── pages/                    # 页面
│   │   ├── components/               # 组件
│   │   ├── api/                      # API 接口
│   │   ├── store/                    # 状态管理
│   │   └── utils/                    # 工具函数
│   ├── package.json                  # NPM 依赖
│   ├── manifest.json                 # UniApp 配置
│   └── pages.json                    # 页面配置
│
├── e2e-tests/                        # E2E 测试（独立目录）
│   ├── e2e/                          # 测试用例
│   ├── playwright.config.ts          # Playwright 配置
│   ├── package.json                  # 测试依赖
│   └── (其他测试相关文件)
│
├── README.md                         # 项目说明（根目录）
├── docker-compose.yml                # Docker 编排配置
├── .gitignore                        # Git 忽略配置
└── Jenkinsfile                       # CI/CD 配置

3. 核心变更对照表

变更项	原值	新值
后端项目名	novalon-manage-api	gym-manage-api
前端项目名	novalon-manage-web	gym-manage-web
移动端项目	-	gym-manage-uniapp（新建）
测试目录	-	e2e-tests（新建）
Java 包名	cn.novalon.manage	cn.novalon.gym.manage
Maven groupId	cn.novalon.manage	cn.novalon.gym.manage
Maven artifactId	novalon-manage-api	gym-manage-api
NPM 项目名	novalon-manage-web	gym-manage-web

4. 分阶段实施计划

4.1 阶段 1：后端项目重构（gym-manage-api）

目标：将 novalon-manage-api 重构为 gym-manage-api，修改包名和所有引用

步骤：

重命名项目目录

git mv novalon-manage-api gym-manage-api

修改 Maven 配置
- 更新父 POM：
  - groupId: cn.novalon.manage → cn.novalon.gym.manage
  - artifactId: novalon-manage-api → gym-manage-api
  - name: Novalon Manage API → Gym Manage API
  - description: 更新为健身房管理系统描述
- 更新所有子模块 POM：
  - parent 引用更新
  - groupId 更新
  - 模块间依赖引用更新
修改 Java 包结构
- 重命名包目录：cn/novalon/manage/ → cn/novalon/gym/manage/
- 更新所有 Java 文件中的 package 声明
- 更新所有 Java 文件中的 import 语句
修改配置文件
- application.yml 等配置文件中的应用名称
- 日志配置中的包名引用

验证

cd gym-manage-api
mvn clean compile
mvn test

验证清单：

后端项目目录已重命名为 gym-manage-api
所有 pom.xml 中的 groupId 已更新为 cn.novalon.gym.manage
所有 pom.xml 中的 artifactId 已更新
所有 Java 文件的 package 声明已更新
所有 Java 文件的 import 语句已更新
配置文件中的应用名称已更新
mvn clean compile 执行成功
单元测试执行成功

提交信息：

refactor(backend): 重命名后端项目为 gym-manage-api，修改包名为 cn.novalon.gym.manage

4.2 阶段 2：前端项目重构（gym-manage-web）

目标：将 novalon-manage-web 重构为 gym-manage-web，更新项目名称和配置

步骤：

重命名项目目录

git mv novalon-manage-web gym-manage-web

修改 NPM 配置
- 更新 package.json：
  - name: novalon-manage-web → gym-manage-web
  - description: 更新为健身房管理系统前端描述
修改代码中的引用
- 更新页面标题、Logo 等品牌相关内容
- 检查 API 请求中的基础路径（如有硬编码）

验证

cd gym-manage-web
npm install
npm run build

验证清单：

前端项目目录已重命名为 gym-manage-web
package.json 中的 name 已更新
页面标题和品牌信息已更新
npm install 执行成功
npm run build 执行成功

提交信息：

refactor(frontend): 重命名前端项目为 gym-manage-web

4.3 阶段 3：测试文件迁移（e2e-tests）

目标：创建独立的 e2e-tests 目录，迁移所有 E2E 测试相关文件

步骤：

创建测试目录结构
```
mkdir -p e2e-tests
```

迁移测试文件

# 迁移测试用例
git mv gym-manage-web/e2e e2e-tests/e2e

# 迁移 Playwright 配置
git mv gym-manage-web/playwright e2e-tests/playwright

# 迁移测试脚本
git mv gym-manage-web/scripts e2e-tests/scripts

# 迁移测试配置文件
git mv gym-manage-web/playwright.config.ts e2e-tests/
git mv gym-manage-web/playwright-complete.config.ts e2e-tests/
git mv gym-manage-web/playwright-simple.config.ts e2e-tests/

创建测试项目的 package.json
- 合并根目录和 web 项目的测试依赖
- 配置测试脚本
调整测试配置
- 更新 playwright.config.ts 中的路径
- 更新测试脚本中的路径引用

清理原项目

# 删除根目录的 package.json（测试依赖已迁移）
git rm package.json

# 清理 web 项目中的测试相关依赖
# （从 gym-manage-web/package.json 中移除 Playwright 相关依赖）

验证

cd e2e-tests
npm install
npm run test:e2e:smoke

验证清单：

e2e-tests 目录已创建
所有测试文件已迁移
playwright.config.ts 路径已调整
测试脚本路径已调整
原项目中的测试文件已清理
根目录的 package.json 已删除
npm run test:e2e:smoke 执行成功

提交信息：

refactor(test): 创建独立的 e2e-tests 目录，迁移测试文件

4.4 阶段 4：创建 UniApp 项目（gym-manage-uniapp）

目标：创建基础的 UniApp 项目脚手架

技术栈：

框架：UniApp + Vue 3
语言：TypeScript
状态管理：Pinia
UI 组件库：uni-ui（官方组件库）
网络请求：uni.request 封装

步骤：

创建项目目录结构

mkdir -p gym-manage-uniapp/src/{pages,components,api,store,utils,static}

创建配置文件
- package.json：NPM 依赖配置
- manifest.json：应用配置
- pages.json：页面配置
- tsconfig.json：TypeScript 配置
- vite.config.ts：Vite 配置
创建基础文件
- src/main.ts：应用入口
- src/App.vue：应用根组件
- src/pages/index/index.vue：首页占位符
- src/pages/login/index.vue：登录页占位符
- src/api/request.ts：请求封装
- src/store/index.ts：Pinia 配置
- src/store/user.ts：用户状态

验证

cd gym-manage-uniapp
npm install
npm run dev:h5

验证清单：

gym-manage-uniapp 目录已创建
基础目录结构已创建
配置文件已创建
基础页面占位符已创建
npm run dev:h5 执行成功

提交信息：

feat(mobile): 创建 gym-manage-uniapp 项目脚手架

4.5 阶段 5：根目录整理与文档更新

目标：清理根目录，更新全局配置和文档

步骤：

更新全局配置
- 更新 docker-compose.yml：
  - 服务名称更新
  - 卷挂载路径更新
  - 环境变量更新
- 更新 Jenkinsfile：
  - 项目路径更新
  - 构建命令更新
- 更新 .gitignore（如需要）
更新文档
- 更新 README.md：
  - 项目名称：健身房管理系统
  - 项目描述
  - 目录结构说明
  - 快速开始指南
  - 技术栈说明
清理临时文件
- 删除不再需要的临时文件
- 确保根目录只保留全局性文件

最终验证

# Docker Compose 验证
docker-compose down -v
docker-compose up -d
docker-compose ps
docker-compose logs

# 检查服务通信
curl http://localhost:8084/actuator/health
curl http://localhost:3001

验证清单：

docker-compose.yml 已更新
Jenkinsfile 已更新
README.md 已更新
根目录整洁，无冗余文件
Docker Compose 启动成功
服务间通信正常

提交信息：

docs: 更新项目文档和全局配置

5. 关键技术细节

5.1 Maven 模块依赖关系

manage-app (主应用)
  ├── depends on: manage-sys, manage-db, manage-common, manage-audit, manage-notify, manage-file
  └── 可执行 JAR

manage-gateway (网关)
  ├── depends on: manage-common
  └── 可执行 JAR

manage-sys (系统模块)
  ├── depends on: manage-common, manage-db
  └── 普通 JAR

manage-db (数据库模块)
  ├── depends on: manage-common
  └── 普通 JAR

manage-common (公共模块)
  └── 普通 JAR（基础依赖）

manage-audit, manage-notify, manage-file
  ├── depends on: manage-common
  └── 普通 JAR

5.2 Spring Boot 配置文件更新

# application.yml
spring:
  application:
    name: gym-manage-api  # 原 novalon-manage-api

# 日志配置
logging:
  level:
    cn.novalon.gym.manage: DEBUG  # 原 cn.novalon.manage

5.3 Playwright 配置调整

原配置（在 gym-manage-web/playwright.config.ts）：

testDir: './e2e',  // 相对于 web 项目根目录

新配置（在 e2e-tests/playwright.config.ts）：

testDir: './e2e',  // 相对于 e2e-tests 根目录
baseURL: 'http://localhost:3001',  // 前端服务地址

5.4 UniApp 项目配置

manifest.json：

{
  "name": "健身房管理系统",
  "appid": "",
  "description": "健身房管理移动端应用",
  "versionName": "1.0.0",
  "versionCode": "100"
}

pages.json：

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    },
    {
      "path": "pages/login/index",
      "style": {
        "navigationBarTitleText": "登录"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "健身房管理",
    "navigationBarBackgroundColor": "#F8F8F8",
    "backgroundColor": "#F8F8F8"
  }
}

6. 风险评估与应对措施

6.1 风险 1：包名修改导致编译失败

风险等级：🔴 高

应对措施：

使用 IDE 的重构功能（推荐 IntelliJ IDEA 的 Rename Package）
使用全局搜索确保所有引用都已更新
编译前先执行 mvn clean 清理旧编译产物
每个模块单独编译验证

6.2 风险 2：测试迁移后路径引用错误

风险等级：🟡 中

应对措施：

迁移后立即运行冒烟测试验证
使用相对路径而非绝对路径
保持测试目录结构不变，只改变父目录

6.3 风险 3：Docker Compose 配置失效

风险等级：🟡 中

应对措施：

更新 docker-compose.yml 中的服务名称
更新所有卷挂载路径
更新环境变量配置

6.4 风险 4：Git 历史丢失

风险等级：🟢 低

应对措施：

使用 git mv 命令重命名文件和目录
提交前检查 git status 确保是重命名而非删除+新增
使用 .gitattributes 确保文件编码一致

6.5 风险 5：IDE 缓存问题

风险等级：🟢 低

应对措施：

重构后清理 IDE 缓存
重新导入项目
重建索引

7. 回滚策略

7.1 阶段级回滚

如果某个阶段失败，可以回滚到上一个成功的阶段：

# 查看提交历史
git log --oneline

# 回滚到指定阶段
git reset --hard <commit-hash>

# 或者使用 revert（保留回滚记录）
git revert <commit-hash>

7.2 完全回滚

如果需要完全回滚到重构前的状态：

# 找到重构前的最后一个提交
git log --oneline --grep="refactor"

# 回滚到该提交
git reset --hard <commit-hash>

# 强制推送到远程（谨慎使用）
git push origin master --force

8. 成功标准

所有项目目录和文件正确重命名
所有代码引用正确更新
后端项目编译和测试通过
前端项目构建成功
E2E 测试运行正常
UniApp 项目可正常启动
Docker Compose 服务启动正常
文档更新完整
Git 历史保留完整

9. 附录

9.1 常用命令速查

# 后端编译和测试
cd gym-manage-api
mvn clean compile
mvn test

# 前端构建
cd gym-manage-web
npm install
npm run build

# E2E 测试
cd e2e-tests
npm install
npm run test:e2e:smoke

# UniApp 开发
cd gym-manage-uniapp
npm install
npm run dev:h5

# Docker Compose
docker-compose down -v
docker-compose up -d
docker-compose ps
docker-compose logs

# Git 操作
git status
git log --oneline
git mv <old> <new>
git commit -m "message"

9.2 文件批量替换命令

# 替换包名
find . -type f -name "*.java" -exec sed -i '' 's/cn\.novalon\.manage/cn.novalon.gym.manage/g' {} +

# 替换项目名
find . -type f \( -name "*.xml" -o -name "*.yml" -o -name "*.json" \) -exec sed -i '' 's/novalon-manage-api/gym-manage-api/g' {} +

文档结束

16 KiB Raw Permalink Blame History Unescape Escape

健身房管理系统基础设施重构设计规格

1. 项目概况

1.1 背景

1.2 目标

1.3 远程仓库

1.4 范围界定

2. 最终目录结构

3. 核心变更对照表

4. 分阶段实施计划

4.1 阶段 1：后端项目重构（gym-manage-api）

4.2 阶段 2：前端项目重构（gym-manage-web）

4.3 阶段 3：测试文件迁移（e2e-tests）

4.4 阶段 4：创建 UniApp 项目（gym-manage-uniapp）

4.5 阶段 5：根目录整理与文档更新

5. 关键技术细节

5.1 Maven 模块依赖关系

5.2 Spring Boot 配置文件更新

5.3 Playwright 配置调整

5.4 UniApp 项目配置

6. 风险评估与应对措施

6.1 风险 1：包名修改导致编译失败

6.2 风险 2：测试迁移后路径引用错误

6.3 风险 3：Docker Compose 配置失效

6.4 风险 4：Git 历史丢失

6.5 风险 5：IDE 缓存问题

7. 回滚策略

7.1 阶段级回滚

7.2 完全回滚

8. 成功标准

9. 附录

9.1 常用命令速查

9.2 文件批量替换命令

16 KiB

Raw Permalink Blame History