bj_power/bj_power_mes/QUICKSTART.md

快速启动指南

一、数据库初始化

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

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

脚本会自动完成:

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

方式 2: 手动初始化

# 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: 手动启动

启动后端

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

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

启动前端（新终端窗口）

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. 尝试手动删除数据库重建:

   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
   

---

五、其他有用命令

清理数据库种子数据

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

查看数据库表结构

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

查询测试数据

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