manta/gofaster/FULL_STACK_ENHANCED.md

# 🚀 GoFaster 增强版全栈开发环境

## 📋 功能特性

本增强版全栈开发环境集成了所有优化功能：

### **1. 编码优化**
- ✅ UTF-8 编码支持
- ✅ 中文显示无乱码
- ✅ PowerShell 编码配置

### **2. 日志增强**
- ✅ 详细构建日志
- ✅ 进度条显示
- ✅ 错误详情展示
- ✅ 实时状态监控

### **3. 智能依赖管理**
- ✅ 自动检查前端依赖
- ✅ 自动安装 cross-env
- ✅ 自动检查后端依赖
- ✅ 自动安装 air 工具

### **4. 灵活启动模式**
- ✅ 全栈启动（前后端）
- ✅ 仅启动后端
- ✅ 仅启动前端
- ✅ 调试模式
- ✅ 监听模式

## 🛠️ 使用方法

### **方法 1: 从根目录启动（推荐）**
```powershell
# 全栈启动（标准模式）
.\dev-full.ps1

# 全栈启动（调试模式）
.\dev-full.ps1 -Debug

# 全栈启动（监听模式）
.\dev-full.ps1 -Watch

# 仅启动后端
.\dev-full.ps1 -BackendOnly

# 仅启动前端
.\dev-full.ps1 -FrontendOnly
```

### **方法 2: 从前端目录启动**
```bash
cd app

# 全栈启动（标准模式）
npm run dev:full

# 全栈启动（调试模式）
npm run dev:full-debug

# 全栈启动（监听模式）
npm run dev:full-watch

# 仅启动后端
npm run dev:backend-only

# 仅启动前端
npm run dev:frontend-only
```

### **方法 3: 单独启动服务**
```bash
# 前端增强版
npm run dev:enhanced

# 前端调试版
npm run dev:debug

# 后端热重载
cd backend
air
```

## 🔧 新增功能详解

### **1. 智能依赖检查**
- 自动检查 `node_modules` 是否存在
- 自动安装缺失的依赖
- 自动安装 `cross-env` 工具
- 自动检查并安装 `air` 工具

### **2. 进程管理**
- 显示每个服务的进程 ID (PID)
- 提供进程管理命令
- 智能启动顺序（先后端，后前端）
- 启动状态检查

### **3. 环境配置**
- 自动设置 UTF-8 编码
- 配置 Vue CLI 环境变量
- 设置 Node.js 内存选项
- 配置日志级别

### **4. 错误处理**
- 友好的错误提示
- 详细的故障排除建议
- 状态码检查
- 启动失败处理

## 📁 文件结构

```
gofaster/
├── dev-full.ps1              # 增强版全栈启动脚本
├── app/
│   ├── dev-enhanced.ps1      # 前端增强启动脚本
│   ├── dev-enhanced.bat      # 前端批处理脚本
│   ├── .npmrc                # npm 配置文件
│   ├── vue.config.js         # Vue CLI 增强配置
│   └── package.json          # 包含新脚本的包配置
└── backend/
    ├── .air.toml             # Air 热重载配置
    └── main.go               # 后端主程序
```

## 🚀 启动流程

### **全栈启动流程**
1. **环境检查**：设置编码、环境变量
2. **依赖检查**：检查前端和后端依赖
3. **后端启动**：启动 Go 服务 + Air 热重载
4. **状态检查**：验证后端启动状态
5. **前端启动**：启动 Electron + Vue 热重载
6. **完成提示**：显示服务信息和进程管理命令

### **启动参数说明**
| 参数 | 说明 | 示例 |
|------|------|------|
| `-Debug` | 启用调试模式，显示详细日志 | `.\dev-full.ps1 -Debug` |
| `-Watch` | 启用监听模式，自动重载 | `.\dev-full.ps1 -Watch` |
| `-BackendOnly` | 仅启动后端服务 | `.\dev-full.ps1 -BackendOnly` |
| `-FrontendOnly` | 仅启动前端服务 | `.\dev-full.ps1 -FrontendOnly` |

## 🔍 监控和管理

### **进程信息**
启动完成后会显示：
- 后端进程 ID (PID)
- 前端进程 ID (PID)
- 进程管理命令

### **进程管理命令**
```powershell
# 停止后端
Stop-Process -Id <后端PID>

# 停止前端
Stop-Process -Id <前端PID>

# 停止所有服务
Get-Process | Where-Object {$_.ProcessName -eq 'powershell'} | Stop-Process
```

### **服务状态检查**
- 后端健康检查：`http://localhost:8080/health`
- Swagger 文档：`http://localhost:8080/swagger/index.html`
- 前端应用：Electron 窗口自动打开

## 🚨 故障排除

### **常见问题**

#### **1. 编码问题**
- 确保使用 PowerShell 或 CMD
- 检查系统区域设置
- 使用 `-Debug` 参数查看详细日志

#### **2. 依赖问题**
- 脚本会自动检查和安装依赖
- 如果失败，手动运行 `npm install`
- 检查 Node.js 版本 (推荐 v16+)

#### **3. 端口冲突**
- 检查 8080 端口是否被占用
- 检查 3000 端口是否被占用
- 使用 `netstat -ano | findstr :8080` 查看

#### **4. 启动失败**
- 查看详细错误日志
- 检查 Go 和 Node.js 环境
- 确保在正确的目录下运行

### **调试技巧**
1. **使用调试模式**：`.\dev-full.ps1 -Debug`
2. **查看进程状态**：`Get-Process | Where-Object {$_.ProcessName -eq 'powershell'}`
3. **检查端口占用**：`netstat -ano | findstr :8080`
4. **查看日志文件**：检查各服务的日志输出

## 💡 最佳实践

1. **推荐使用全栈启动**：`.\dev-full.ps1`
2. **开发时使用监听模式**：`.\dev-full.ps1 -Watch`
3. **调试时使用调试模式**：`.\dev-full.ps1 -Debug`
4. **定期清理进程**：避免端口冲突
5. **保持依赖更新**：定期运行 `npm update`

## 🔄 更新日志

- **v2.0.0**: 集成所有增强功能
- **v2.1.0**: 添加智能依赖管理
- **v2.2.0**: 增强进程管理和监控
- **v2.3.0**: 优化启动流程和错误处理