bj_power/bj_power_mes/QUICKSTART.md

# 快速启动指南

## 一、数据库初始化

### 方式 1: 使用自动化脚本（推荐）

```powershell
# 在项目根目录执行
.\scripts\init-db.ps1
```

脚本会自动完成:
1. 创建 `back_cover` 数据库
2. 提示你首次启动应用以创建表结构（Ent ORM 自动迁移）
3. 插入种子数据（用户、设备、产品类型等）

### 方式 2: 手动初始化

```powershell
# 1. 创建数据库
psql -U postgres -c "CREATE DATABASE back_cover;"

# 2. 首次启动应用（自动创建表结构）
cd d:\hardman\back_cover
go run hougai.go -f etc/hougai-api.yaml
# 等待看到 "Starting server at..." 后按 Ctrl+C 停止

# 3. 插入种子数据
psql -U postgres -d back_cover -f doc/data.sql

# 4. 重启应用
go run hougai.go -f etc/hougai-api.yaml
```

### 默认管理员账号

- **用户名**: admin
- **密码**: 123456

---

## 二、启动管理后台

### 方式 1: VS Code 一键启动（推荐）

1. 用 VS Code 打开项目根目录
2. 按 `Ctrl+Shift+P`，选择 **"Tasks: Run Task"**
3. 选择 **"Start Full Stack"**
   - 这会同时启动后端 API 服务（端口 8888）和前端开发服务器（端口 7070）
4. 浏览器会自动打开登录页面

### 方式 2: 手动启动

#### 启动后端

```powershell
cd d:\hardman\back_cover
go run hougai.go -f etc/hougai-api.yaml
```

后端服务将运行在: `http://localhost:8888`

#### 启动前端（新终端窗口）

```powershell
cd d:\hardman\back_cover\frontend
pnpm install    # 首次运行需要
pnpm dev
```

前端开发服务器将运行在: `http://localhost:7070`

浏览器访问: `http://localhost:7070`

---

## 三、VS Code 调试配置

已为你配置好 `.vscode/launch.json`，包含以下调试选项:

### 1. 单独调试后端

- 按 `F5` 或点击 VS Code 左侧的"运行和调试"
- 选择 **"Backend: hougai-api"**
- 点击绿色播放按钮

### 2. 单独调试前端

- 选择 **"Frontend: dev server"**
- 确保前端开发服务器已运行
- 点击绿色播放按钮（会打开 Chrome 浏览器并附加调试）

### 3. 完整栈调试

- 选择 **"Full Stack: Start Backend + Frontend"**
- 会自动启动后端和前端，并在服务就绪时打开浏览器

---

## 四、常见问题

### Q1: psql 命令找不到

**错误信息**: `未找到 psql 命令`

**解决方法**:
1. 安装 PostgreSQL: https://www.postgresql.org/download/windows/
2. 确保 `psql` 在系统 PATH 中（安装时勾选"Add to PATH")
3. 重启终端

### Q2: 数据库连接失败

**错误信息**: `could not connect to server: Connection refused`

**解决方法**:
1. 检查 PostgreSQL 服务是否运行
   - Windows: `services.msc` → 查找 "postgresql-x64-*" 服务 → 确保正在运行
2. 检查端口是否正确（默认 5432）
3. 检查配置文件 `etc/hougai-api.yaml` 中的数据库连接参数

### Q3: 前端无法连接后端

**错误信息**: `Network Error` 或 CORS 错误

**解决方法**:
1. 确保后端服务正在运行（端口 8888）
2. 检查 `frontend/vite.config.ts` 中的代理配置
3. 清除浏览器缓存并重试

### Q4: Ent ORM 表结构创建失败

**错误信息**: 各种 ent 相关错误

**解决方法**:
1. 确认 PostgreSQL 版本 >= 12
2. 检查数据库用户权限（需要 CREATE 权限）
3. 尝试手动删除数据库重建:
   ```powershell
   psql -U postgres -c "DROP DATABASE IF EXISTS back_cover;"
   psql -U postgres -c "CREATE DATABASE back_cover;"
   go run hougai.go -f etc/hougai-api.yaml
   ```

---

## 五、其他有用命令

### 清理数据库种子数据

```powershell
psql -U postgres -d back_cover -f doc/reset.sql
```

### 查看数据库表结构

```powershell
psql -U postgres -d back_cover -c "\dt"           # 查看所有表
psql -U postgres -d back_cover -c "\d equipment"  # 查看 equipment 表结构
```

### 查询测试数据

```powershell
psql -U postgres -d back_cover -c "SELECT * FROM user;"                              # 查询所有用户
psql -U postgres -d back_cover -c "SELECT id, name, equipment_type_id FROM equipment;" # 查询所有设备
psql -U postgres -d back_cover -c "SELECT * FROM product_type WHERE is_active = true;" # 查询活跃产品类型
```

---

## 六、技术架构概要

```
┌─────────────────┐         ┌──────────────────┐
│  前端 (React)    │◄──────►│   后端 (Go)       │
│  :7070 (Vite)   │ HTTP   │   :8888 (go-zero) │
└─────────────────┘         └────────┬─────────┘
                                     │
                                     │ pgx driver
                                     ▼
                              ┌─────────────────┐
                              │ PostgreSQL 12+   │
                              │  database:       │
                              │  back_cover      │
                              └─────────────────┘
```

- **前端**: React 19 + TypeScript + Vite + Semi Design
- **后端**: Go 1.25 + go-zero + Ent ORM
- **数据库**: PostgreSQL 12+
- **通信**: REST API + SSE (Server-Sent Events)

---

## 七、下一步

1. ✅ 完成数据库初始化
2. ✅ 启动后端和前端服务
3. ✅ 浏览器登录管理后台 (`http://localhost:7070`)
4. 📖 阅读项目文档: `系统设计方案.md`
5. 🔧 探索功能模块和设备配置

如有问题，请查看日志文件:
- 后端日志: `hougai.log`
- 浏览器控制台: F12 → Console
- 网络请求: F12 → Network