gym-manage/docs/superpowers/specs/2026-04-17-gym-manage-refactor-design.md

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

**文档版本**：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`，修改包名和所有引用

**步骤**：

1. **重命名项目目录**
   ```bash
   git mv novalon-manage-api gym-manage-api
   ```

2. **修改 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` 更新
     - 模块间依赖引用更新

3. **修改 Java 包结构**
   - 重命名包目录：`cn/novalon/manage/` → `cn/novalon/gym/manage/`
   - 更新所有 Java 文件中的 `package` 声明
   - 更新所有 Java 文件中的 `import` 语句

4. **修改配置文件**
   - `application.yml` 等配置文件中的应用名称
   - 日志配置中的包名引用

5. **验证**
   ```bash
   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`，更新项目名称和配置

**步骤**：

1. **重命名项目目录**
   ```bash
   git mv novalon-manage-web gym-manage-web
   ```

2. **修改 NPM 配置**
   - 更新 `package.json`：
     - `name`: `novalon-manage-web` → `gym-manage-web`
     - `description`: 更新为健身房管理系统前端描述

3. **修改代码中的引用**
   - 更新页面标题、Logo 等品牌相关内容
   - 检查 API 请求中的基础路径（如有硬编码）

4. **验证**
   ```bash
   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 测试相关文件

**步骤**：

1. **创建测试目录结构**
   ```bash
   mkdir -p e2e-tests
   ```

2. **迁移测试文件**
   ```bash
   # 迁移测试用例
   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/
   ```

3. **创建测试项目的 package.json**
   - 合并根目录和 web 项目的测试依赖
   - 配置测试脚本

4. **调整测试配置**
   - 更新 `playwright.config.ts` 中的路径
   - 更新测试脚本中的路径引用

5. **清理原项目**
   ```bash
   # 删除根目录的 package.json（测试依赖已迁移）
   git rm package.json
   
   # 清理 web 项目中的测试相关依赖
   # （从 gym-manage-web/package.json 中移除 Playwright 相关依赖）
   ```

6. **验证**
   ```bash
   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 封装

**步骤**：

1. **创建项目目录结构**
   ```bash
   mkdir -p gym-manage-uniapp/src/{pages,components,api,store,utils,static}
   ```

2. **创建配置文件**
   - `package.json`：NPM 依赖配置
   - `manifest.json`：应用配置
   - `pages.json`：页面配置
   - `tsconfig.json`：TypeScript 配置
   - `vite.config.ts`：Vite 配置

3. **创建基础文件**
   - `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`：用户状态

4. **验证**
   ```bash
   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：根目录整理与文档更新

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

**步骤**：

1. **更新全局配置**
   - 更新 `docker-compose.yml`：
     - 服务名称更新
     - 卷挂载路径更新
     - 环境变量更新
   - 更新 `Jenkinsfile`：
     - 项目路径更新
     - 构建命令更新
   - 更新 `.gitignore`（如需要）

2. **更新文档**
   - 更新 `README.md`：
     - 项目名称：健身房管理系统
     - 项目描述
     - 目录结构说明
     - 快速开始指南
     - 技术栈说明

3. **清理临时文件**
   - 删除不再需要的临时文件
   - 确保根目录只保留全局性文件

4. **最终验证**
   ```bash
   # 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 配置文件更新

```yaml
# 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`）：
```typescript
testDir: './e2e',  // 相对于 web 项目根目录
```

**新配置**（在 `e2e-tests/playwright.config.ts`）：
```typescript
testDir: './e2e',  // 相对于 e2e-tests 根目录
baseURL: 'http://localhost:3001',  // 前端服务地址
```

### 5.4 UniApp 项目配置

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

**pages.json**：
```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 阶段级回滚

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

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

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

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

### 7.2 完全回滚

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

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

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

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

---

## 8. 成功标准

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

---

## 9. 附录

### 9.1 常用命令速查

```bash
# 后端编译和测试
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 文件批量替换命令

```bash
# 替换包名
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' {} +
```

---

**文档结束**