docs: add Chinese system initialization runbook

docs/superpowers/plans/2026-06-14-system-initialization-bootstrap-runbook.md

@@ -0,0 +1,231 @@
+# 系统初始化执行手册
+
+本手册用于在后端服务器上初始化 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，再做后续验收。