11 KiB
11 KiB
系统标准初始化工具设计
背景
当前系统已经从嘉恒测试环境切到百华客制化分支。数据库中存在大量嘉恒/测试业务数据，百华正式启用前需要初始化为干净系统。
这次初始化不能只做一次性清库脚本。后续给其他公司部署时，也需要一套标准工具，能够在全新的 MySQL 数据库上完成建库、建表和系统骨架初始化，同时也能对已经建好表、已经产生测试数据的系统做正式启用前重置。
目标
初始化工具提供两个模式：
fresh：面向全新 MySQL 或全新 schema，创建 ERP 数据库下所有 ERP 表和智能报工小程序相关表，并写入最小系统骨架。reset：面向已有 schema，先备份，再清空业务数据、主数据、人员账号、小程序数据，然后重建最小系统骨架。
初始化完成后，系统应满足：
- 可以用一个超级管理员账号登录 ERP。
- 系统权限、菜单、角色关系完整。
- 六大仓库和默认库位存在，后续可直接做出入库。
- 系统配置存在，例如原材料库存批次前缀、是否对接智能报工小程序。
- 没有嘉恒或测试业务数据、客户、供应商、物料、产品、库存、订单、报工、发货、财务、单据归档数据残留。
- 如果后续客户购买小程序，小程序后端所需表也已经创建好。
非目标
- 不做客户真实主数据导入。客户、供应商、物料、产品、BOM、工艺路线后续用现有导入功能导入。
- 默认不删除上传文件和 PDF 实体文件，只清数据库记录。文件删除作为显式参数单独开启。
- 不重命名数据库 schema，例如仍可使用当前
jiaheng_erp作为历史技术库名，避免改动部署配置和小程序连接。 - 不在初始化工具里修改业务逻辑。
命令形态
建议新增入口：
python backend/scripts/system_initialize.py fresh \
--company-name 百华 \
--admin-name 超级管理员 \
--admin-phone 13800000000 \
--admin-password '正式密码'
python backend/scripts/system_initialize.py reset \
--company-name 百华 \
--admin-name 超级管理员 \
--admin-phone 13800000000 \
--admin-password '正式密码' \
--confirm-reset
脚本读取 backend/.env 中的 MySQL 连接信息：
MYSQL_HOSTMYSQL_PORTMYSQL_DATABASEMYSQL_USERMYSQL_PASSWORD
模式一：fresh
fresh 用于全新部署，是后续交付其他公司最常用的路径。
流程：
- 读取
.env中的 MySQL 连接信息。 - 连接 MySQL server。
- 如果目标 database 不存在，执行
CREATE DATABASE。 - 切换到目标 database。
- 创建 ERP 全量表。
- 创建小程序全量表。
- 执行所有已纳入标准基线的 patch。
- 初始化系统权限、角色、角色权限。
- 初始化系统配置。
- 初始化单位、物料分类等基础字典。
- 初始化六大仓库和默认库位。
- 初始化根组织节点、超级管理员人员、超级管理员系统账号、用户角色绑定。
- 输出初始化报告。
fresh 模式不写入任何业务主数据和业务流水。
模式二：reset
reset 用于已有系统正式启用前清理，例如这次百华切换。
流程：
- 读取
.env中的 MySQL 连接信息。 - 检查必须显式传入
--confirm-reset。 - 打印目标数据库连接摘要，包括 host、port、database、当前时间。
- 统计关键表行数。
- 强制导出备份 SQL 到
outputs/cleanup_backups/system_init_backup_<timestamp>.sql。 SET FOREIGN_KEY_CHECKS=0。- 清空业务流水表。
- 清空库存表。
- 清空业务主数据表。
- 清空人员、组织、账号、组织绑定、角色绑定。
- 清空小程序业务数据和小程序主数据。
- 清空系统广播、单据归档记录。
- 重置相关自增 ID。
- 重建系统权限、角色、角色权限、系统配置、单位、分类、仓库、库位、根组织、超级管理员。
SET FOREIGN_KEY_CHECKS=1。- 再次统计关键表行数。
- 输出 JSON 报告到
outputs/cleanup_backups/system_init_summary_<timestamp>.json。
小程序表覆盖范围
ERP 当前代码已映射部分小程序表，但小程序后端模型更完整。标准初始化必须覆盖两侧共同需要的完整表集合。
小程序基础主数据：
attendance_pointspersonnelperson_rolesperson_attendance_pointsproductsequipmentwork_schedules
小程序业务数据：
work_sessionswork_session_devicesproduction_reportsproduction_report_itemsreport_audit_logsmold_lock_feedbacksdevice_qrcodesdevice_qrcode_batch_tasksnoticesnotice_pointsreconciliation_ledger_entries
fresh 模式需要创建这些表。reset 模式需要清空这些表，并只重建必要的考勤点/管理员人员数据。
清理表分层
业务流水表
销售：
so_sales_order_itemso_sales_orderso_delivery_itemso_delivery
采购：
po_purchase_order_sales_orderpo_purchase_order_itempo_purchase_orderpo_receipt_itempo_receiptpo_purchase_return_itempo_purchase_return
库存：
wh_special_adjustment_linewh_special_adjustmentwh_stocktake_adjustmentwh_stocktake_linewh_stocktake_warehousewh_stocktakewh_inventory_txnwh_stock_balancewh_stock_lot
生产：
pp_production_batch_ledger_txnpp_production_batch_ledgerpp_completion_receipt_itempp_completion_receiptpp_scrap_recordpp_operation_reportpp_material_issue_itempp_material_issuepp_work_order_material_issuepp_work_order_operationpp_work_order_materialpp_work_order
发货与售后：
rt_return_dispositionrt_return_itemrt_return_order
财务：
fi_statement_snapshotfi_cost_allocationfi_overhead_entryfi_accounting_periodreconciliation_ledger_entries
单据归档：
document_archives
MRP：
mrp_material_demand
业务主数据表
em_maintenance_orderem_maintenance_planem_equipmentmd_bom_itemmd_bommd_process_route_operationmd_process_routemd_work_centermd_processmd_productmd_materialmd_itemmd_customermd_supplier
组织和账号
选择标准为“只保留一个超级管理员”。
需要清空：
sys_user_rolesys_usersys_org_manager_bindingsys_org_employee_bindinghr_employeesys_department
需要重建：
- 根组织节点，例如
COMPANY_ROOT - 超级管理员人员
- 超级管理员系统账号
- 超级管理员角色绑定
系统骨架
需要保留或重建：
sys_permissionsys_rolesys_role_permissionsys_system_configsys_ai_assistant_configmd_unitmd_item_categorywh_warehousewh_location
需要清空：
sys_broadcast_message
系统配置初始化
必须至少初始化：
RAW_MATERIAL_LOT_PREFIX：默认YL。SMART_OPERATION_REPORT_ENABLED：默认可通过参数设置。百华当前建议按实际购买情况设置。- AI 助手名称：默认
<company-name>工艺助手。
配置项必须使用 upsert，确保 fresh 和 reset 都可重复执行。
仓库初始化
初始化六大库和默认库位：
- 原材料库：
RAW - 半成品库：
SEMI - 成品库：
FINISHED - 辅料库：
AUX - 废料库：
SCRAP - 退货库：
RETURN
每个仓库创建一个默认库位。命名可保持当前业务通用名称，例如：
- 原料主库位
- 半成品主库位
- 成品主库位
- 辅料主库位
- 废料主库位
- 退货主库位
仓库名可根据公司名生成，例如 百华原材料库，也可以保持通用名 原材料库。推荐保持通用名，避免系统内部业务文案过长。
备份与报告
reset 模式必须生成备份：
outputs/cleanup_backups/system_init_backup_<timestamp>.sql
必须生成报告：
outputs/cleanup_backups/system_init_summary_<timestamp>.json
报告内容包括：
- 执行模式
- 执行时间
- 数据库 host、port、database
- 备份路径
- 清理表清单
- 每张表清理前行数
- 每张表清理后行数
- 重建骨架数据摘要
- 是否清理文件
- 执行结果
文件清理
默认不删除实体文件，只清数据库引用。
如显式传入 --delete-files，才允许清理：
- 单据归档 PDF 目录
- 批量下载临时 zip 目录
- 辅助照片上传目录
文件清理必须记录到报告中。
安全保护
reset 模式必须满足：
- 未传
--confirm-reset时禁止执行删除，只输出预检摘要。 - 执行前必须成功备份。
- 打印目标 database，并要求命令行参数显式确认。
- 默认拒绝清理未知 database，除非传入
--allow-any-database。 - 清理前后检查
FOREIGN_KEY_CHECKS恢复为1。 - 清理后必须能查询到一个超级管理员用户。
- 清理后业务流水表行数必须为
0。
测试策略
单元测试：
fresh在临时 SQLite 或测试 MySQL schema 上可创建所有 SQLAlchemy metadata 表。reset对带测试数据的测试库执行后，业务表为空。reset后系统账号、角色、权限、仓库、库位、系统配置存在。reset未传--confirm-reset时不会删除数据。- 小程序关键表存在，并可写入最小人员、考勤点、产品清单、报工记录。
集成测试：
- 初始化后调用
/api/system/health返回数据库连接正常。 - 初始化后用超级管理员登录成功。
- 初始化后打开仓库页面不会因为缺仓库/库位报错。
- 初始化后打开系统权限管理页面能看到根组织节点和超级管理员。
人工验收：
- 前端登录成功。
- 左侧菜单正常。
- 基础资料中客户、供应商、产品、物料为空。
- 六大仓库库存为空，但仓库入口可正常进入。
- 销售、采购、生产、发货、财务台账为空。
- 系统管理中只有初始化创建的超级管理员账号。
实施顺序
- 补齐小程序完整 SQLAlchemy 模型或标准 SQL，确保初始化可创建小程序全部表。
- 新增初始化脚本
backend/scripts/system_initialize.py。 - 新增 SQL seed/cleanup 分组文件。
- 编写测试覆盖
fresh和reset。 - 在本地测试库执行
fresh。 - 在本地测试库导入当前测试数据后执行
reset。 - 确认报告和备份文件。
- 用户审核后，在百华服务器数据库执行
reset。
开放决策
本设计已固定采用“只保留一个超级管理员”的账号策略。
执行前仍需确定：
- 百华超级管理员姓名、手机号、初始密码。
- 百华是否默认开启智能报工小程序对接。
- 是否在本次初始化时删除服务器上的历史上传图片和 PDF 实体文件。默认不删除。