ShiErFeng/docs/pallet-workflow-deployment.md

托盘流转业务部署说明

适用范围与当前状态

本文适用于 MySQL 增量补丁：

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

2026-07-27 已在本地主工作区 .env.dev 指向的 MySQL 8.0.36 执行该补丁，且完成下述本地核对。其他环境尚未执行，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 节核对失败时，不得清理缓存或启动后端。

3. 2026-07-27 本地执行记录

1. 执行前备份：/private/tmp/shierfeng-fastapi-before-pallet-workflow-20260727-1925.sql，文件权限 600，大小 69,180 字节，SHA-256 为 a217a7b071c7e3ecda0d4c94dd1010711b6061025148689156405b70a02f6c7e。已校验文件非空、可读且包含核心系统表；未执行恢复演练。
2. DDL 分节执行成功：新增 18 张 biz_* InnoDB 表，业务域幂等键的复合唯一索引列顺序已核对。
3. DML 分节使用标准 mysql 批处理执行，未使用 --force 或 continue-on-error 模式。64 条新业务菜单已写入，旧 AI/外链菜单、AI 字典及旧角色映射已核对为 0。
4. 新菜单没有自动授予普通角色；后续应通过现有角色菜单机制按实际职责分配。

历史 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 扫码回车流程。

本地环境已使用独立查询参数验证管理员 /getRouters：包含 3 个新业务目录和 17 个业务页面，不包含 AI 管理或“施尔丰仓库”。该结果不等于已完成 Redis 清理，也不代表普通角色已完成授权验收。

本轮未验证项

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

• 备份恢复演练。
• 真实角色与仓库/客户现场映射的端到端（E2E）流程。
• MySQL 行锁、并发和事务回滚行为。
• Redis 缓存清理。