# 系统初始化执行手册

本手册用于在后端服务器上初始化 ForgeFlow ERP 客户数据库。请注意：重置模式会清理目标数据库中的业务数据，正式执行前必须再次确认目标库、备份路径和是否清理实体文件。

## 适用场景

全新初始化模式 `fresh` 适用于全新客户数据库或空数据库结构。它会创建数据库、创建 ERP 与小程序相关全部表，并写入最小系统骨架。

重置初始化模式 `reset` 适用于已经部署过、但需要正式启用前清理测试数据的数据库。它会先执行 MySQL 备份，再清空业务数据、主数据、人员账号、小程序数据，并重建最小系统骨架。

默认不会删除 PDF、照片等实体文件。只有显式增加 `--delete-files` 时，才会清理系统管理范围内的文件目录内容。

## 执行前检查

执行前先进入后端目录并激活虚拟环境：

```bash
cd /home/souplearn/ERP/ForgeFlow-ERP/backend
source .venv/bin/activate
```

确认 `.env` 中数据库配置指向正确目标：

```bash
grep -E "MYSQL_HOST|MYSQL_PORT|MYSQL_DATABASE|MYSQL_USER" .env
```

确认后端能连接数据库：

```bash
curl -s http://127.0.0.1:8000/api/system/health | python3 -m json.tool
```

## 全新数据库初始化

新客户全新部署时使用全新初始化模式 `fresh`：

```bash
python scripts/system_initialize.py fresh \
  --company-name 百华 \
  --admin-name 超级管理员 \
  --admin-phone 13800000000 \
  --admin-password '正式密码' \
  --smart-operation-report on
```

执行成功后，命令行会输出：

```text
mode=fresh
database=<数据库地址>:<端口>/<数据库名>
backup_path=
summary_path=
admin_username=13800000000
```

## 已有测试库重置

已有测试数据、需要正式启用前清理时使用重置初始化模式 `reset`。该模式必须显式传入确认参数 `--confirm-reset`：

```bash
python scripts/system_initialize.py reset \
  --company-name 百华 \
  --admin-name 超级管理员 \
  --admin-phone 13800000000 \
  --admin-password '正式密码' \
  --smart-operation-report on \
  --confirm-reset
```

执行成功后，命令行会输出：

```text
mode=reset
database=<数据库地址>:<端口>/<数据库名>
backup_path=/path/to/system_init_backup_<timestamp>.sql
summary_path=/path/to/system_init_summary_<timestamp>.json
admin_username=13800000000
```

备份和执行摘要默认写入：

```text
outputs/cleanup_backups/
```

## 可选文件清理

默认重置初始化只清数据库记录，不删除实体文件。

如确实需要同时清理系统托管的历史文件，才增加 `--delete-files`：

```bash
python scripts/system_initialize.py reset \
  --company-name 百华 \
  --admin-name 超级管理员 \
  --admin-phone 13800000000 \
  --admin-password '正式密码' \
  --smart-operation-report on \
  --confirm-reset \
  --delete-files
```

`--delete-files` 只会删除以下目录中的子文件和子目录，不会删除目录本身：

```text
outputs/document_archives
outputs/document_archive_batches
backend/uploads/logistics
```

## 初始化后验证

先验证 API 健康状态：

```bash
curl -s http://127.0.0.1:8000/api/system/health | python3 -m json.tool
```

再验证核心数据状态。为了避免密码出现在命令行参数中，使用临时 MySQL 配置文件：

```bash
MYSQL_DEFAULTS_FILE="$(mktemp)"
chmod 600 "$MYSQL_DEFAULTS_FILE"
cat > "$MYSQL_DEFAULTS_FILE" <<EOF
[client]
host=$MYSQL_HOST
port=$MYSQL_PORT
user=$MYSQL_USER
password=$MYSQL_PASSWORD
default-character-set=utf8mb4
EOF

mysql --defaults-extra-file="$MYSQL_DEFAULTS_FILE" "$MYSQL_DATABASE" -e "
SELECT COUNT(*) AS customer_count FROM md_customer;
SELECT COUNT(*) AS supplier_count FROM md_supplier;
SELECT COUNT(*) AS stock_lot_count FROM wh_stock_lot;
SELECT COUNT(*) AS sales_order_count FROM so_sales_order;
SELECT COUNT(*) AS admin_count FROM sys_user WHERE username='13800000000' AND is_super_admin=1;
"

rm -f "$MYSQL_DEFAULTS_FILE"
```

预期结果：

```text
customer_count = 0
supplier_count = 0
stock_lot_count = 0
sales_order_count = 0
admin_count = 1
```

然后用初始化账号登录 ERP：

```text
账号：初始化时填写的管理员手机号
密码：初始化时填写的管理员密码
```

## 执行摘要检查

重置初始化执行后检查 JSON 格式的执行摘要：

```bash
python3 -m json.tool outputs/cleanup_backups/system_init_summary_<timestamp>.json
```

重点确认：

```text
mode
database
backup_path
summary_path
counts_before
counts_after
seeded.admin_username
```

如果使用了 `--delete-files`，还应看到：

```text
seeded.deleted_file_count
seeded.deleted_dir_count
```

## 回滚方式

如果重置初始化后发现目标数据库选错，先停止相关服务，避免继续写入：

```bash
sudo systemctl stop forgeflow-backend
```

然后使用本次生成的备份 SQL 恢复：

```bash
MYSQL_DEFAULTS_FILE="$(mktemp)"
chmod 600 "$MYSQL_DEFAULTS_FILE"
cat > "$MYSQL_DEFAULTS_FILE" <<EOF
[client]
host=$MYSQL_HOST
port=$MYSQL_PORT
user=$MYSQL_USER
password=$MYSQL_PASSWORD
default-character-set=utf8mb4
EOF

mysql --defaults-extra-file="$MYSQL_DEFAULTS_FILE" "$MYSQL_DATABASE" < outputs/cleanup_backups/system_init_backup_<timestamp>.sql

rm -f "$MYSQL_DEFAULTS_FILE"
```

恢复完成后再启动服务：

```bash
sudo systemctl start forgeflow-backend
```

## 安全提醒

正式环境执行重置初始化前必须确认：

1. `.env` 中的 `MYSQL_HOST`、`MYSQL_PORT`、`MYSQL_DATABASE` 是目标测试库或待初始化客户库。
2. 已经明确允许清理该库中的现有数据。
3. `outputs/cleanup_backups` 有足够磁盘空间保存备份。
4. 没有显式传入 `--delete-files` 时，不会删除 PDF、照片等实体文件。
5. 只有确认要清理实体文件时，才允许传入 `--delete-files`。
6. 执行后必须先保存备份 SQL，再做后续验收。