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

CHANGELOG.md

@@ -12,6 +12,7 @@
 2.新增移动端模块 (#73)。
 3.新增多worker运行支持 (#76)。
 4.应用新增演示模式 (#78)。
+5.新增托盘流转业务，覆盖基础资料、仓库入库至退回仓库的全流程、只读报表及 Android PDA 浏览器扫码操作。
 
 ### BUG修复
 

README.md

@@ -35,6 +35,18 @@
 16. 在线构建器：拖动表单元素生成相应的HTML代码。
 17. 系统接口：根据业务代码自动生成相关的api接口文档。
 18. 代码生成：配置数据库表信息一键生成前后端代码（python、sql、vue、js），支持下载。
+
+## 托盘流转业务
+
+本轮新增托盘全生命周期流转管理：
+
+* 基础资料：菌种、客户、客户现场、产线、仓库、托盘。
+* 业务流程：仓库入库、工厂装填、发货出库、客户现场使用、退回仓库。
+* 只读报表：托盘库存、装填记录、发货出库、产线消耗、退回仓库、托盘追溯。
+* Android PDA 可直接通过浏览器使用响应式 Web 页面，并支持 HID 扫码枪扫码后回车提交。
+
+本轮交付不是 APP/uni-app 原生端，也未调用设备摄像头。上线前请阅读[托盘流转业务部署说明](./docs/pallet-workflow-deployment.md)。
+
 ## 在线体验
 
 * *账号：admin*

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 缓存清理。