ShiErFeng/docs/pallet-workflow-deployment.md

托盘流转业务部署说明

适用范围与当前状态

本文适用于 MySQL 增量补丁：

shierfeng-fastapi-backend/sql/patches/20260724_pallet_workflow_mysql.sql

本轮仅生成并审查该补丁，未在真实 MySQL 环境执行，也未清理 Redis 缓存。本文记录的是后续上线步骤，不代表这些操作已经完成。

上线前门禁

执行补丁前必须完成以下准备：

1. 对目标 MySQL 实例进行完整备份，至少覆盖库结构、业务数据、菜单和角色关联数据，并验证备份可读。
2. 在隔离环境完成恢复演练，确认恢复步骤、耗时和责任人，不能只以“备份命令成功”代替可恢复性验证。
3. 由 DBA 人工审查补丁、目标库现状、已有同名表结构、固定菜单 ID 和回退方案。
4. 申请维护窗口，在补丁执行和缓存清理完成前保持后端停止，不接入业务流量。

任一门禁未满足时，不得执行补丁。

MySQL 补丁执行与核对

MySQL DDL 会隐式提交，因此必须将补丁的 DDL、DML 分节执行，并在每一节后逐项核对结果。执行失败时不能假设整个补丁已自动回滚，应立即停止后续步骤，由 DBA 根据实际已提交状态决定人工修复或从已验证备份恢复。

1. DDL 节

1. 先执行补丁中的 DDL 节，逐表核对表结构、索引、外键和约束。
2. CREATE TABLE IF NOT EXISTS 只会跳过已经存在的同名表，不会修复已存在但结构发生漂移的表。发现同名表时，必须先人工比对实际结构；存在差异时停止执行并制定独立修复方案。
3. DDL 节核对通过前，不得继续执行 DML 节。

2. DML 节

1. DML 节包含固定 64 行菜单 seed。执行后必须核对结果恰为 64 行，并确认稳定字段与补丁定义一致。
2. 任一固定 ID 与未知既有数据冲突时，必须停止并由 DBA、业务负责人共同人工处理；不得覆盖、改写或复用未知 ID，也不得绕过冲突继续执行。
3. DML 节核对失败时，不得清理缓存或启动后端。

历史 AI/Agno 遗留表

曾运行过历史 AI/Agno 版本的数据库可能残留以下 11 张表：

• ai_models
• ai_chat_config
• ai_sessions
• ai_memories
• ai_metrics
• ai_eval_runs
• ai_knowledge
• ai_culture
• ai_traces
• ai_spans
• ai_schema_versions

本补丁不会删除或修改这些表。未经另行确认，不得处理这些历史表。后续如需清理，应单独盘点表结构、数据量和外部依赖，完成备份与恢复验证，确认无消费者后，再通过独立变更审批和维护窗口人工执行。

Redis 缓存清理

只有 MySQL 补丁全部执行成功且核对通过后，才能在目标 Redis 实例定向清理以下缓存：

• api_cache:login:user:routers:*
• api_cache:login:user:info:*
• sys_dict:ai_provider_type

对前两类模式应使用 SCAN 定位后逐项删除，只处理明确匹配的键；禁止使用 FLUSHALL。本轮未执行任何 Redis 缓存清理，不能把上述清单视为已清理证明。

启动与运行态验收

只有 MySQL 补丁成功、逐节核对通过并完成上述定向缓存清理后，才可启动后端并开展运行态验收。至少应核对 /getRouters 返回的托盘业务菜单、真实角色权限，以及真实用户与仓库/客户现场映射下的业务访问范围，再验证响应式 Web 页面和 Android PDA HID 扫码回车流程。

本轮未验证项

以下事项需要在后续真实环境中验证，本轮没有完成：

• MySQL 真实建表及约束行为。
• /getRouters 运行态菜单。
• 真实角色与仓库/客户现场映射的端到端（E2E）流程。
• MySQL 行锁、并发和事务回滚行为。
• Redis 缓存清理。