coder-thin-template-backend/script/README.md

# 项目模板重构脚本

这是一个用于将 `heritage-backend` 项目重构为新项目模板的自动化脚本。

## 功能特性

🚀 **全自动重构**：一键完成整个项目的重构过程
📁 **目录重命名**：自动重命名所有模块目录和子模块目录
📦 **Maven配置**：更新所有 pom.xml 文件中的 groupId、artifactId 和模块名
☕ **Java包结构**：重构所有 Java 文件的包名和 import 语句
⚙️ **配置文件**：更新所有配置文件中的包名引用
🗄️ **数据库配置**：重命名 SQL 文件和更新数据库名引用
🔄 **多层级支持**：支持插件模块等多层级子模块结构

## 使用方法

### 1. 进入脚本目录
```bash
cd /Users/leocoder/leocoder/develop/frameworks/heritage/heritage-backend/script
```

### 2. 执行重构脚本
```bash
./project-template-refactor.sh
```

### 3. 按提示输入新项目信息
脚本会提示你输入以下信息：
- **新项目名称**：例如 `my-project-backend`
- **新的GroupId**：例如 `com.company.project`
- **新的包名**：例如 `com.company.project`
- **新的模块前缀**：例如 `my-project`
- **新的数据库名**：例如 `my_project_db`

### 4. 确认配置并开始重构
脚本会显示所有配置信息供你确认，输入 `y` 开始重构。

## 重构内容详解

### 📁 目录结构重构
**原始结构：**
```
/parent-directory/
└── heritage-backend/          ← 项目根目录
    ├── heritage-web/
    ├── heritage-common/
    ├── heritage-model/
    ├── heritage-mybatisplus/
    ├── heritage-modules/
    ├── heritage-plugins/
    │   ├── heritage-easyexcel/
    │   ├── heritage-oss/
    │   ├── heritage-sa-token/
    │   └── ...其他插件模块
    └── sql/
        └── heritage.sql
```

**重构后结构（以 my-project-backend 为例）：**
```
/parent-directory/
├── heritage-backend_backup_*  ← 自动创建的备份
└── my-project-backend/                 ← 重命名后的项目根目录
    ├── my-project-web/
    ├── my-project-common/
    ├── my-project-model/
    ├── my-project-mybatisplus/
    ├── my-project-modules/
    ├── my-project-plugins/
    │   ├── my-project-easyexcel/
    │   ├── my-project-oss/
    │   ├── my-project-sa-token/
    │   └── ...其他插件模块
    └── sql/
        └── my_project_db.sql
```

⭐ **v1.2.0 新特性**：脚本现在会自动重命名项目根目录，无需手动操作！

### 📦 Maven 配置重构
- **groupId**：`org.leocoder.heritage` → `com.company.project`
- **artifactId**：`heritage-*` → `my-project-*`
- **name**：相应模块名称更新
- **依赖引用**：所有模块间依赖的 groupId 和 artifactId

### ☕ Java 包结构重构
- **包声明**：`package org.leocoder.heritage.*` → `package com.company.project.*`
- **import语句**：`import org.leocoder.heritage.*` → `import com.company.project.*`
- **目录结构**：`src/main/java/org.leocoder.heritage/` → `src/main/java/com/company/project/`

### ⚙️ 配置文件重构
- **application.yml / application-dev.yml / application-local.yml**：
  - `packages-to-scan: org.leocoder.heritage` → `packages-to-scan: com.company.project`
  - `projectName: CORDER-ADMIN-THIN` → `projectName: MY-PROJECT-ADMIN`
  - `pool-name: CORDER-HIKARI-DEV` → `pool-name: MY-PROJECT-HIKARI-DEV`
  - `name: coder-web` → `name: my-project-web`
  - `jdbc:mysql://localhost:3306/heritage` → `jdbc:mysql://localhost:3306/new-db-name`
  - `jdbc:mysql://localhost:3306/heritage-backup` → `jdbc:mysql://localhost:3306/new-db-name-backup`
  - `filePath: /path/heritage-backend/` → `filePath: /path/new-project-backend/`
- **logback配置文件**（logback-spring*.xml）：
  - `<contextName>heritage-logback</contextName>` → `<contextName>my-project-logback</contextName>`
  - `<property name="CORDER_ADMIN_LOGS" value="./logs"/>` → `<property name="MY_PROJECT_ADMIN_LOGS" value="./logs"/>`
  - 所有日志路径引用：`${CORDER_ADMIN_LOGS}` → `${MY_PROJECT_ADMIN_LOGS}`
- **其他配置文件**：包名和项目相关引用更新

### 🗄️ SQL 文件重构
- **文件重命名**：`heritage.sql` → `my_project_db.sql`
- **数据库名更新**：SQL文件中的数据库名引用更新

## 安全特性

### 🔒 自动备份
脚本执行前会自动创建项目备份：
```
heritage-backend_backup_20250922_143022/
```

### ✅ 验证检查
重构完成后自动验证是否还有旧的引用残留

### 🚫 错误处理
遇到错误时立即停止执行，保护项目完整性

## 重构后操作

重构完成后请执行以下步骤：

### 1. 验证编译
```bash
mvn clean compile
```

### 2. 更新数据库配置
手动检查并更新以下配置文件中的数据库连接信息：
- `*/src/main/resources/application-dev.yml`
- `*/src/main/resources/application-local.yml`

### 3. 验证功能
- 启动应用程序验证功能正常
- 检查所有插件模块是否正常加载

### 4. IDE配置
- 重新导入Maven项目
- 检查项目结构和依赖

### 5. Git管理
```bash
git add .
git commit -m "refactor: 重构项目为新模板"
```

## 注意事项

⚠️ **重要提醒：**
1. 重构前请确保代码已提交到Git仓库
2. 脚本会自动创建备份，但建议额外手动备份重要数据
3. 重构过程不可逆，请谨慎操作
4. 重构后需要手动更新数据库连接配置
5. 如果项目中有自定义的特殊配置，可能需要手动调整

## 故障排除

### 常见问题
1. **权限错误**：确保脚本有可执行权限 `chmod +x project-template-refactor.sh`
2. **路径错误**：确保在正确的项目根目录下执行脚本
3. **Maven错误**：重构后如果编译失败，检查依赖配置是否正确
4. **包名冲突**：如果新包名已存在，选择不同的包名
5. **Bash版本兼容性**：脚本已修复了bash版本兼容性问题
6. **包名未正确替换**：使用修复脚本 `./fix-existing-project.sh`
7. **多余src目录**：使用修复脚本自动清理

### 项目修复工具

#### 1. 快速修复目录名反斜杠问题
如果目录名中出现反斜杠（如 `leocoder\`）：
```bash
./quick-fix-backslash.sh
```

#### 2. 修复遗漏的modules子模块
如果modules目录下的子模块没有被重命名：
```bash
./fix-missing-modules.sh
```

#### 3. 修复已有问题的项目
如果重构过程中出现包名未正确替换或目录结构问题：
```bash
./fix-existing-project.sh
```

#### 4. 检查项目状态
检查项目重构后的整体状态：
```bash
./project-status-check.sh
```

#### 5. 演示logback配置处理
查看logback配置处理效果：
```bash
./logback-demo.sh
```

#### 6. 测试反斜杠修复功能
验证反斜杠问题修复效果：
```bash
./test-backslash-fix.sh
```

#### 7. 测试配置文件修复功能
验证数据库连接字符串和文件路径配置修复效果：
```bash
./test-config-fix.sh
```

### 回滚操作
如果重构出现问题，可以：
1. 删除重构后的项目目录
2. 从备份目录恢复：`cp -r heritage-backend_backup_* heritage-backend`
3. 或使用修复脚本进行增量修复

### 脚本版本信息
- **v1.0.0**：初始版本
- **v1.1.0**：修复bash兼容性问题，改进Java包结构迁移逻辑，增加修复工具
- **v1.1.1**：修复sed正则表达式导致的目录名反斜杠问题，增加快速修复工具
- **v1.2.0**：**重大更新** - 完善反斜杠自动清理，增加项目根目录自动重命名功能
- **v1.2.1**：**关键修复** - 彻底解决反斜杠问题，增强MyBatis XML处理，改进验证逻辑
- **v1.2.2**：**模块修复** - 修复modules子模块重命名遗漏问题，支持多层级子模块处理
- **v1.2.3**：**配置修复** - 修复数据库连接字符串和文件路径配置未更新问题

## 技术支持

如果在使用过程中遇到问题，请：
1. 检查脚本执行日志
2. 查看备份目录是否完整
3. 联系开发团队获取支持

---

**版本**：v1.2.3  
**作者**：Leocoder  
**更新时间**：2025-09-22