diff --git a/.gitignore b/.gitignore index 2eb116d..0eeeb28 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,14 @@ +# Java +*.class +*.jar +*.war +*.ear +*.nar +hs_err_pid* +replay_pid* + # Maven target/ -!.mvn/wrapper/maven-wrapper.jar pom.xml.tag pom.xml.releaseBackup pom.xml.versionsBackup @@ -9,33 +17,134 @@ release.properties dependency-reduced-pom.xml buildNumber.properties .mvn/timing.properties +.mvn/wrapper/maven-wrapper.jar -# IDE +# Node.js +node_modules/ +npm-debug.log* +yarn-debug.log* +yarn-error.log* +lerna-debug.log* +.pnpm-debug.log* + +# Build outputs +dist/ +build/ +out/ +*.tsbuildinfo + +# Environment variables +.env +.env.local +.env.development.local +.env.test.local +.env.production.local +.env.*.local + +# IDE - IntelliJ IDEA .idea/ *.iws *.iml *.ipr -.vscode/ +out/ + +# IDE - Eclipse .settings/ .classpath .project +.metadata/ +bin/ +tmp/ -# OS +# IDE - VS Code +.vscode/* +!.vscode/settings.json +!.vscode/tasks.json +!.vscode/launch.json +!.vscode/extensions.json +*.code-workspace + +# IDE - NetBeans +nbproject/private/ +nbbuild/ +nbdist/ +nbactions.xml +nb-configuration.xml + +# OS - macOS .DS_Store +.AppleDouble +.LSOverride +._* +.Spotlight-V100 +.Trashes + +# OS - Windows Thumbs.db +ehthumbs.db +Desktop.ini +$RECYCLE.BIN/ + +# OS - Linux +*~ # Logs logs/ *.log +log/ + +# Testing +coverage/ +.nyc_output/ +test-results/ +test-output/ +*.lcov + +# Playwright +playwright-report/ +playwright/.cache/ +test-results/ +e2e/debug/ +debug-*.png # Temporary files -*.tmp -*.bak *.swp -*~ +*.swo +*.tmp +*.temp +*.bak +*.cache -# Java -*.class +# Package files +*.7z +*.dmg +*.gz +*.iso *.jar -*.war -*.ear +*.rar +*.tar +*.zip + +# Database +*.db +*.sqlite +*.sqlite3 +*.h2.db + +# Spring Boot +spring-shell.log + +# Application specific +novalon-manage-api/manage-app/backend.log + +# docs (except superpowers specs) +docs/* +!docs/superpowers/ +docs/superpowers/* +!docs/superpowers/specs/ + +# .trae +.trae/ + +# agent +AGENTS.md \ No newline at end of file diff --git a/docs/superpowers/specs/2026-04-17-gym-manage-refactor-design.md b/docs/superpowers/specs/2026-04-17-gym-manage-refactor-design.md new file mode 100644 index 0000000..1c52706 --- /dev/null +++ b/docs/superpowers/specs/2026-04-17-gym-manage-refactor-design.md @@ -0,0 +1,634 @@ +# 健身房管理系统基础设施重构设计规格 + +**文档版本**：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 + +# 或者使用 revert（保留回滚记录） +git revert +``` + +### 7.2 完全回滚 + +如果需要完全回滚到重构前的状态： + +```bash +# 找到重构前的最后一个提交 +git log --oneline --grep="refactor" + +# 回滚到该提交 +git reset --hard + +# 强制推送到远程（谨慎使用） +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 +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' {} + +``` + +--- + +**文档结束**