87 lines
4.8 KiB
Markdown
87 lines
4.8 KiB
Markdown
# 托盘流转业务部署说明
|
|
|
|
## 适用范围与当前状态
|
|
|
|
本文适用于 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 缓存清理。
|