bj_power/bj_power_mes/打包部署.md

# 打包部署

> 本文档同时面向 **AI 助手**（约束和规则）和 **运维人员**（操作步骤）。

---

## 一、AI 约束（必读）

### 1.1 打包环境

- **构建机**：macOS（Go 交叉编译到 Windows）
- **目标平台**：Windows amd64

### 1.2 构建命令

```bash
# 前端构建 + 交叉编译 + 复制资源文件，输出到 bin/
bash build-windows.sh
```

### 1.3 编译参数硬约束

| 参数 | 值 | 原因 |
|------|-----|------|
| `CGO_ENABLED` | `0` | 纯 Go 项目，禁用 CGO 才能跨平台编译 |
| `GOOS` | `windows` | 目标平台 |
| `GOARCH` | `amd64` | 64 位 |
| `-ldflags` | `-s -w -H=windowsgui` | 去除调试信息 + 隐藏命令行窗口 |
| `-trimpath` | 必须 | 去除源码路径信息 |

### 1.4 构建前置条件

1. **ent/ 代码已生成**：`ent/` 目录在 `.gitignore` 中，不提交 git。若 `ent/` 不存在，需先执行 `go generate ./schema/...`
2. **前端已构建**：脚本会自动执行 `npm run build`，但需确保 `node_modules` 已安装
3. **Go 版本**：`go.mod` 中 `go 1.25.0`

### 1.5 数据库工具编译规则

- `schema/tools/migrate.go` — 编译为 `migrate.exe`，必须同时编译 `app.go`：`go build migrate.go app.go`
- `schema/tools/data.go` — 编译为 `data.exe`，必须同时编译 `app.go`：`go build data.go app.go`
- 两个文件都有 `//go:build ignore`，不可单独编译，必须显式指定文件列表
- `app.go` 提供 `getAppDir()` 和 `loadDBConfig()` 公共函数

### 1.6 输出目录

- 输出到 `bin/`（与 `build.bat` 保持一致，`.gitignore` 中已忽略）
- 目录结构：

```
bin/
├── spherical.exe          # 主程序（GUI 模式，隐藏控制台）
├── migrate.exe            # 数据库表结构迁移
├── data.exe               # 数据初始化（signals/seed/admin）
├── app.ico                # 托盘图标
├── etc/
│   └── spherical-api.yaml # 配置文件
└── doc/
    ├── signals.sql        # PLC 信号定义（146 条）
    ├── data.sql           # 设备/配方/产品种子数据
    ├── reset.sql          # 生产数据重置脚本
    ├── engine_schema.sql  # 新引擎表结构（recipe_step_resource 等）
    └── new_recipe.sql     # 新引擎配方种子数据
```

### 1.7 禁止事项

- 禁止修改 `build-windows.sh` 中的 `CGO_ENABLED=0`、`GOOS=windows`、`-H=windowsgui`
- 禁止在 `bin/` 目录中放入 `go.mod`、`go.sum`、源码文件
- 禁止将 `public/` 打包到 `bin/`（前端已通过 `//go:embed public` 嵌入 exe）
- 数据库工具 `data.go` 和 `migrate.go` 的路由定位依赖 `getAppDir()`（基于 exe 路径），不要改为基于 `go.mod` 的定位方式

---

## 二、技术栈版本

| 组件 | 版本 | 说明 |
|------|------|------|
| Go | 1.25.0 | go.mod |
| pgx | v5.7.4 | PostgreSQL 驱动，支持 PG 12-17 |
| PostgreSQL | **17**（推荐） | 兼容 12-17 |
| Node.js | 18+ | 前端构建 |
| Vite | 7.x | 前端构建工具 |
| React | 18.x | 前端框架 |
| ent | 0.14.x | ORM |

---

## 三、Windows 部署步骤（给人看）

### 3.1 环境准备

1. 安装 **PostgreSQL 17**：[下载](https://www.postgresql.org/download/windows/)
   - 安装时设置超级用户密码，端口保持默认 **5432**
2. 安装 **Node.js** 18+（如果需要在 Windows 上重新构建前端）

### 3.2 部署文件

将 `bin/` 整个目录复制到 Windows 电脑，例如 `D:\spherical\`

### 3.3 修改配置

编辑 `etc/spherical-api.yaml`，修改数据库密码：

```yaml
Database:
  Host: 127.0.0.1
  Port: 5432
  User: postgres
  Password: 你的密码    # ← 必须修改
  Dbname: spherical
```

### 3.4 创建数据库

用 **pgAdmin** 或 **psql** 执行：

```sql
CREATE DATABASE spherical;
```

### 3.5 初始化数据库

打开 **命令提示符**（cmd），进入部署目录，**依次执行**：

```bash
cd D:\spherical

# 1. 创建表结构（根据 ent schema 自动建表）
migrate.exe

# 2. 导入 PLC 信号定义（146 条）
data.exe signals

# 3. 导入设备/配方/产品种子数据
data.exe seed

# 4. 创建管理员账号
data.exe admin

# 5. 初始化新引擎（创建引擎表结构 + 导入配方种子数据）
#    交互式命令，输入 y 确认
data.exe new-engine
```

> **重要：** 步骤 5 必须执行。新引擎依赖 `recipe_step_resource/signal/action/decision`、`resource_lock`、`job_step` 等表与配方数据，缺少会导致产线无法运行（引擎找不到配方/资源）。

#### 数据库工具命令一览

所有 `data.exe` 支持的命令（在 cmd 中运行）：

| 命令 | 说明 | 是否交互 |
|------|------|:---:|
| `data.exe signals` | 导入 PLC 信号定义到 `signal` 表 | 否 |
| `data.exe seed` | 导入设备类型、设备实例、槽位、配方、产品类型 | 否 |
| `data.exe admin` | 创建默认管理员账号 admin/admin123 | 否 |
| `data.exe reset-pwd` | 重置 admin 密码为 admin123 | 否 |
| `data.exe reset` | 清空所有生产数据，恢复设备槽位为空闲 | 是（需输入 y 确认） |
| `data.exe reset-all` | 完全重建数据库：删表 → 建表 → 导入种子数据 + 管理员 + 信号 + 迁移（含新引擎表结构） | 是（需输入 y 确认） |
| `data.exe migrate` | 执行数据库结构迁移（幂等，列不存在时跳过） | 是（需输入 y 确认） |
| `data.exe new-engine` | 初始化新引擎：创建引擎表结构 + 导入配方数据（已有数据库升级用，reset-all 已包含） | 是（需输入 y 确认） |

支持一次执行多个命令：
```bash
data.exe seed admin signals    # 依次执行 seed、admin、signals
```

#### migrate.exe 说明

`migrate.exe` 等价于 `data.exe migrate`，用于数据库表结构迁移。首次部署时使用 `migrate.exe` 创建所有表结构，后续 schema 变更后使用 `data.exe migrate` 执行增量迁移。

> **注意：** `data.exe` 和 `migrate.exe` 是控制台程序，必须从 **命令提示符（cmd）** 运行，不要双击执行（窗口会一闪而过）。交互式命令（如 `reset-all`）运行后会提示输入 `y` 确认，输入后按回车继续。

### 3.6 启动系统

```bash
spherical.exe
```

- 首次运行自动创建桌面快捷方式「华德零件自动化生产线管控系统」
- 程序在系统托盘运行，右键托盘图标可打开页面 / 设置开机启动 / 退出
- 浏览器自动打开 `http://127.0.0.1:8888`

### 3.7 登录

| 用户名 | 密码 |
|--------|------|
| `admin` | `admin123` |

### 3.8 数据重置

#### 方式一：完全重建（推荐用于 schema 变更后）

清空数据库并重新导入所有数据：

```bash
data.exe reset-all
```

运行后会提示「警告：此操作将删除所有表并重建数据库！所有数据将永久丢失！输入 y 继续:」，输入 `y` 回车确认。

> `reset-all` 已包含新引擎初始化（`new-engine` 的全部内容），重建后即可直接运行 mockrun/产线，无需再单独执行 `data.exe new-engine`。

#### 方式二：仅清空生产数据

保留基础配置（设备、产品、配方、PLC 信号、用户），仅清空工单、工件、事件日志等生产数据：

```bash
data.exe reset
```

#### 方式三：手动执行 SQL

```bash
psql -U postgres -d spherical -f doc/reset.sql
data.exe seed
```

#### 其他维护命令

```bash
data.exe reset-pwd    # 重置 admin 密码为 admin123
data.exe migrate      # 执行数据库结构增量迁移
```

---

## 四、常见问题

| 问题 | 解决 |
|------|------|
| 运行 exe 提示缺少 DLL | 安装 [Visual C++ Redistributable](https://aka.ms/vs/17/release/vc_redist.x64.exe) |
| 数据库连接失败 | 检查 `etc/spherical-api.yaml` 中密码是否正确，PostgreSQL 服务是否启动 |
| 端口被占用 | 修改 `etc/spherical-api.yaml` 中 `Port` 字段 |
| 快捷方式没出现 | 检查 PowerShell 执行策略：`Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` |
| 开机启动不生效 | 以管理员身份运行一次，在托盘菜单中重新勾选 |
| `data.exe` 或 `migrate.exe` 双击一闪而过 | 这是控制台程序，必须从 **命令提示符（cmd）** 运行，不要双击 |
| `data.exe reset-all` 无响应 | 程序在等待输入 `y` 确认，看清提示后输入 `y` 回车。如果仍然无响应，检查 `etc/spherical-api.yaml` 中数据库配置是否正确 |
| 数据库工具连接失败 | 工具从 `etc/spherical-api.yaml` 读取数据库配置，路径基于 exe 所在目录。确保 `etc/` 目录与 `data.exe` 在同一级 |