文档：补充托盘业务部署说明

docs/pallet-workflow-deployment.md

@@ -0,0 +1,78 @@
+# 托盘流转业务部署说明
+
+## 适用范围与当前状态
+
+本文适用于 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 缓存清理。