停止跟踪本地工具和日志并完善生产迁移交付

shierfeng-fastapi-backend/sql/README.md

@@ -0,0 +1,48 @@
+# MySQL 初始化与升级
+
+## 新建空库
+
+使用 [shierfeng-fastapi.sql](./shierfeng-fastapi.sql)。建表与初始化菜单已经包含截至 2026-10-08 的最新结构：
+
+- 测试数据批次、隧道主数据及隧道菜单。
+- 库存 `tunnel_id`、`trace_no`，使用、退回、事件的隧道关联与批次快照；使用记录 `line_id` 可空。
+- 装填记录的 `production_date`、`expiry_date` 及日期约束。
+- 发货收货状态、人员、时间、幂等字段，库存 `site_arrived_at`，在途状态和收货事件及菜单。
+- 使用记录和托盘事件的 `fifo_skip_reason`、`fifo_recommendation`。
+
+**全量脚本含 `DROP TABLE`，仅用于新空库，禁止用于已有业务库升级。** 新库初始化后不要再执行对应的历史增量补丁，否则可能遇到重复字段、表或菜单冲突。
+
+Docker Compose 仅在 MySQL 数据卷首次为空时自动执行初始化 SQL。更新代码、替换 SQL 文件或重启容器不会自动升级已有库；不要删除数据卷来触发初始化。
+
+## 已有生产库：已存在隧道表和物料日期，缺少关联字段
+
+适用于已核对的 `shierfeng-fastapi` / MySQL 8.0.46 生产结构。完整的停写、备份、独立恢复演练、逐份执行和验收流程见 [生产 Compose 物料流转增量迁移](./production-compose-material-flow-migration-20261008.md)。
+
+在该文档全部门禁满足后，按顺序使用：
+
+1. [生产隧道关联补齐](./patches/20261008_prod_existing_tunnel_repair_mysql.sql)：保留已有隧道表和日期，补齐库存等表的关联列、外键及菜单。
+2. [收货补丁](./patches/20261008_shipment_receipt_mysql.sql)。
+3. [FIFO 补丁](./patches/20261008_usage_fifo_mysql.sql)。
+
+配套只读检查：
+
+- [原字段基线](./checks/20261008_prod_material_flow_baseline.sql)：停写后在迁移前、后各执行一次，逐行比较原数据。
+- [迁移验收](./checks/20261008_prod_material_flow_verify.sql)：检查字段、约束、菜单及历史数据状态；查询退出码为 0 不代表每项均通过，仍须核对结果。
+
+这是特定起点的一次性升级路线，不是幂等脚本。其他结构、部分迁移或已经升级的库必须重新核对，不能盲目重复执行；MySQL DDL 隐式提交，失败时不能依赖 `ROLLBACK` 撤销已完成的结构变更。
+
+本次仅交付文件，没有执行本地或生产数据库操作，也没有启停服务或修改 Compose 配置。生产执行仍须单独审批；不要在本机开发库运行该生产路线。
+
+## 业务说明与离线验证
+
+- [托盘流转业务部署说明](./pallet-workflow-deployment.md)：业务规则与历史执行记录；历史记录不能替代当前环境的迁移证明。
+- [测试数据批次操作说明](./test-data-batch-operations.md)：权限、纳入与批次清理流程。
+
+使用已安装后端依赖的 Python 环境，从项目根目录运行下列离线契约检查；不导入应用、不连接数据库：
+
+```bash
+python -B shierfeng-fastapi-backend/tests/module_business/test_sql_contract.py -q
+python -B shierfeng-fastapi-backend/tests/module_business/test_prod_tunnel_repair_sql.py -q
+```
+
+离线检查不能替代真实 MySQL 的恢复演练和迁移验收。