389 lines
11 KiB
Markdown
389 lines
11 KiB
Markdown
# 系统标准初始化工具设计
|
||
|
||
## 背景
|
||
|
||
当前系统已经从嘉恒测试环境切到百华客制化分支。数据库中存在大量嘉恒/测试业务数据，百华正式启用前需要初始化为干净系统。
|
||
|
||
这次初始化不能只做一次性清库脚本。后续给其他公司部署时，也需要一套标准工具，能够在全新的 MySQL 数据库上完成建库、建表和系统骨架初始化，同时也能对已经建好表、已经产生测试数据的系统做正式启用前重置。
|
||
|
||
## 目标
|
||
|
||
初始化工具提供两个模式：
|
||
|
||
- `fresh`：面向全新 MySQL 或全新 schema，创建 ERP 数据库下所有 ERP 表和智能报工小程序相关表，并写入最小系统骨架。
|
||
- `reset`：面向已有 schema，先备份，再清空业务数据、主数据、人员账号、小程序数据，然后重建最小系统骨架。
|
||
|
||
初始化完成后，系统应满足：
|
||
|
||
- 可以用一个超级管理员账号登录 ERP。
|
||
- 系统权限、菜单、角色关系完整。
|
||
- 六大仓库和默认库位存在，后续可直接做出入库。
|
||
- 系统配置存在，例如原材料库存批次前缀、是否对接智能报工小程序。
|
||
- 没有嘉恒或测试业务数据、客户、供应商、物料、产品、库存、订单、报工、发货、财务、单据归档数据残留。
|
||
- 如果后续客户购买小程序，小程序后端所需表也已经创建好。
|
||
|
||
## 非目标
|
||
|
||
- 不做客户真实主数据导入。客户、供应商、物料、产品、BOM、工艺路线后续用现有导入功能导入。
|
||
- 默认不删除上传文件和 PDF 实体文件，只清数据库记录。文件删除作为显式参数单独开启。
|
||
- 不重命名数据库 schema，例如仍可使用当前 `jiaheng_erp` 作为历史技术库名，避免改动部署配置和小程序连接。
|
||
- 不在初始化工具里修改业务逻辑。
|
||
|
||
## 命令形态
|
||
|
||
建议新增入口：
|
||
|
||
```bash
|
||
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_HOST`
|
||
- `MYSQL_PORT`
|
||
- `MYSQL_DATABASE`
|
||
- `MYSQL_USER`
|
||
- `MYSQL_PASSWORD`
|
||
|
||
## 模式一：fresh
|
||
|
||
`fresh` 用于全新部署，是后续交付其他公司最常用的路径。
|
||
|
||
流程：
|
||
|
||
1. 读取 `.env` 中的 MySQL 连接信息。
|
||
2. 连接 MySQL server。
|
||
3. 如果目标 database 不存在，执行 `CREATE DATABASE`。
|
||
4. 切换到目标 database。
|
||
5. 创建 ERP 全量表。
|
||
6. 创建小程序全量表。
|
||
7. 执行所有已纳入标准基线的 patch。
|
||
8. 初始化系统权限、角色、角色权限。
|
||
9. 初始化系统配置。
|
||
10. 初始化单位、物料分类等基础字典。
|
||
11. 初始化六大仓库和默认库位。
|
||
12. 初始化根组织节点、超级管理员人员、超级管理员系统账号、用户角色绑定。
|
||
13. 输出初始化报告。
|
||
|
||
`fresh` 模式不写入任何业务主数据和业务流水。
|
||
|
||
## 模式二：reset
|
||
|
||
`reset` 用于已有系统正式启用前清理，例如这次百华切换。
|
||
|
||
流程：
|
||
|
||
1. 读取 `.env` 中的 MySQL 连接信息。
|
||
2. 检查必须显式传入 `--confirm-reset`。
|
||
3. 打印目标数据库连接摘要，包括 host、port、database、当前时间。
|
||
4. 统计关键表行数。
|
||
5. 强制导出备份 SQL 到 `outputs/cleanup_backups/system_init_backup_<timestamp>.sql`。
|
||
6. `SET FOREIGN_KEY_CHECKS=0`。
|
||
7. 清空业务流水表。
|
||
8. 清空库存表。
|
||
9. 清空业务主数据表。
|
||
10. 清空人员、组织、账号、组织绑定、角色绑定。
|
||
11. 清空小程序业务数据和小程序主数据。
|
||
12. 清空系统广播、单据归档记录。
|
||
13. 重置相关自增 ID。
|
||
14. 重建系统权限、角色、角色权限、系统配置、单位、分类、仓库、库位、根组织、超级管理员。
|
||
15. `SET FOREIGN_KEY_CHECKS=1`。
|
||
16. 再次统计关键表行数。
|
||
17. 输出 JSON 报告到 `outputs/cleanup_backups/system_init_summary_<timestamp>.json`。
|
||
|
||
## 小程序表覆盖范围
|
||
|
||
ERP 当前代码已映射部分小程序表，但小程序后端模型更完整。标准初始化必须覆盖两侧共同需要的完整表集合。
|
||
|
||
小程序基础主数据：
|
||
|
||
- `attendance_points`
|
||
- `personnel`
|
||
- `person_roles`
|
||
- `person_attendance_points`
|
||
- `products`
|
||
- `equipment`
|
||
- `work_schedules`
|
||
|
||
小程序业务数据：
|
||
|
||
- `work_sessions`
|
||
- `work_session_devices`
|
||
- `production_reports`
|
||
- `production_report_items`
|
||
- `report_audit_logs`
|
||
- `mold_lock_feedbacks`
|
||
- `device_qrcodes`
|
||
- `device_qrcode_batch_tasks`
|
||
- `notices`
|
||
- `notice_points`
|
||
- `reconciliation_ledger_entries`
|
||
|
||
`fresh` 模式需要创建这些表。`reset` 模式需要清空这些表，并只重建必要的考勤点/管理员人员数据。
|
||
|
||
## 清理表分层
|
||
|
||
### 业务流水表
|
||
|
||
销售：
|
||
|
||
- `so_sales_order_item`
|
||
- `so_sales_order`
|
||
- `so_delivery_item`
|
||
- `so_delivery`
|
||
|
||
采购：
|
||
|
||
- `po_purchase_order_sales_order`
|
||
- `po_purchase_order_item`
|
||
- `po_purchase_order`
|
||
- `po_receipt_item`
|
||
- `po_receipt`
|
||
- `po_purchase_return_item`
|
||
- `po_purchase_return`
|
||
|
||
库存：
|
||
|
||
- `wh_special_adjustment_line`
|
||
- `wh_special_adjustment`
|
||
- `wh_stocktake_adjustment`
|
||
- `wh_stocktake_line`
|
||
- `wh_stocktake_warehouse`
|
||
- `wh_stocktake`
|
||
- `wh_inventory_txn`
|
||
- `wh_stock_balance`
|
||
- `wh_stock_lot`
|
||
|
||
生产：
|
||
|
||
- `pp_production_batch_ledger_txn`
|
||
- `pp_production_batch_ledger`
|
||
- `pp_completion_receipt_item`
|
||
- `pp_completion_receipt`
|
||
- `pp_scrap_record`
|
||
- `pp_operation_report`
|
||
- `pp_material_issue_item`
|
||
- `pp_material_issue`
|
||
- `pp_work_order_material_issue`
|
||
- `pp_work_order_operation`
|
||
- `pp_work_order_material`
|
||
- `pp_work_order`
|
||
|
||
发货与售后：
|
||
|
||
- `rt_return_disposition`
|
||
- `rt_return_item`
|
||
- `rt_return_order`
|
||
|
||
财务：
|
||
|
||
- `fi_statement_snapshot`
|
||
- `fi_cost_allocation`
|
||
- `fi_overhead_entry`
|
||
- `fi_accounting_period`
|
||
- `reconciliation_ledger_entries`
|
||
|
||
单据归档：
|
||
|
||
- `document_archives`
|
||
|
||
MRP：
|
||
|
||
- `mrp_material_demand`
|
||
|
||
### 业务主数据表
|
||
|
||
- `em_maintenance_order`
|
||
- `em_maintenance_plan`
|
||
- `em_equipment`
|
||
- `md_bom_item`
|
||
- `md_bom`
|
||
- `md_process_route_operation`
|
||
- `md_process_route`
|
||
- `md_work_center`
|
||
- `md_process`
|
||
- `md_product`
|
||
- `md_material`
|
||
- `md_item`
|
||
- `md_customer`
|
||
- `md_supplier`
|
||
|
||
### 组织和账号
|
||
|
||
选择标准为“只保留一个超级管理员”。
|
||
|
||
需要清空：
|
||
|
||
- `sys_user_role`
|
||
- `sys_user`
|
||
- `sys_org_manager_binding`
|
||
- `sys_org_employee_binding`
|
||
- `hr_employee`
|
||
- `sys_department`
|
||
|
||
需要重建：
|
||
|
||
- 根组织节点，例如 `COMPANY_ROOT`
|
||
- 超级管理员人员
|
||
- 超级管理员系统账号
|
||
- 超级管理员角色绑定
|
||
|
||
### 系统骨架
|
||
|
||
需要保留或重建：
|
||
|
||
- `sys_permission`
|
||
- `sys_role`
|
||
- `sys_role_permission`
|
||
- `sys_system_config`
|
||
- `sys_ai_assistant_config`
|
||
- `md_unit`
|
||
- `md_item_category`
|
||
- `wh_warehouse`
|
||
- `wh_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` 模式必须生成备份：
|
||
|
||
```text
|
||
outputs/cleanup_backups/system_init_backup_<timestamp>.sql
|
||
```
|
||
|
||
必须生成报告：
|
||
|
||
```text
|
||
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` 返回数据库连接正常。
|
||
- 初始化后用超级管理员登录成功。
|
||
- 初始化后打开仓库页面不会因为缺仓库/库位报错。
|
||
- 初始化后打开系统权限管理页面能看到根组织节点和超级管理员。
|
||
|
||
人工验收：
|
||
|
||
- 前端登录成功。
|
||
- 左侧菜单正常。
|
||
- 基础资料中客户、供应商、产品、物料为空。
|
||
- 六大仓库库存为空，但仓库入口可正常进入。
|
||
- 销售、采购、生产、发货、财务台账为空。
|
||
- 系统管理中只有初始化创建的超级管理员账号。
|
||
|
||
## 实施顺序
|
||
|
||
1. 补齐小程序完整 SQLAlchemy 模型或标准 SQL，确保初始化可创建小程序全部表。
|
||
2. 新增初始化脚本 `backend/scripts/system_initialize.py`。
|
||
3. 新增 SQL seed/cleanup 分组文件。
|
||
4. 编写测试覆盖 `fresh` 和 `reset`。
|
||
5. 在本地测试库执行 `fresh`。
|
||
6. 在本地测试库导入当前测试数据后执行 `reset`。
|
||
7. 确认报告和备份文件。
|
||
8. 用户审核后，在百华服务器数据库执行 `reset`。
|
||
|
||
## 开放决策
|
||
|
||
本设计已固定采用“只保留一个超级管理员”的账号策略。
|
||
|
||
执行前仍需确定：
|
||
|
||
- 百华超级管理员姓名、手机号、初始密码。
|
||
- 百华是否默认开启智能报工小程序对接。
|
||
- 是否在本次初始化时删除服务器上的历史上传图片和 PDF 实体文件。默认不删除。
|