shanxia2.0/docs/sql/pl-stop-cert-management-guide.md

工单 #9 段次用证迁移指引

本指引对应 codex/pl-stop-cert-management。本次开发未连接业务数据库执行迁移，未启动 MySQL 容器；实际 MySQL 5.7 事务、并发和迁移演练仍待验证。

前置结构

沿用工单 #4 的购买证、运输证、合同适用范围、额度流水及计划用证配置。执行前核对目标库已有结构，不要重复执行含 ALTER TABLE ADD COLUMN 的旧脚本：

• 原额度表迁移
• 原计划用证配置
• 原用证菜单

计量版本使用已有 pl_plan.cert_configuration 和额度快照中的 JSON 字段，无新增计量版本列。不要把历史 JSON 缺少版本的计划批量改成 per_stop_v2。

本次新增脚本

确认目标环境、备份并核对前置结构后，按以下顺序执行：

1. 逐段产品合法使用证明：新增 pl_stop_legal_document。IF NOT EXISTS 只避免重复建表，不校正已有同名表结构；已有表须核对字段及唯一索引。
2. Web 五视图菜单：新增合同用证、证件用量两个菜单，并调整现有菜单名称和顺序。脚本限定 shanxia2.0 租户的 Web 根节点，不恢复软删除菜单，不自动给角色授权；其他租户需另行确认目标与菜单 ID。

脚本不迁移历史计划产品附件，不重算或补扣历史额度，不修改业务单据状态。启用本次后端代码前必须完成新资料表迁移；运输计划子数据的引用保护也会查询该表，不能等到首次使用证明页面时再建表。

执行后核对

• 新表字段与 PlStopLegalDocument 一致；唯一索引覆盖租户、计划、段类型及段产品 ID。
• Web 菜单顺序为证件建档、合同用证、证件用量、计划段次用证、合法使用证明；既有角色权限保留。
• 使用合成数据验证同证装货 100、送货 40/60 合计 200，购买证和运输证独立计量；历史单侧计划仍按原口径处理。
• 一个送货段上传资料后，全局显示 1/3、对应合同显示 1/1；其他段仍待上传，历史计划级附件不计入段完成数。
• 在 MySQL 5.7 上验证额度并发、重复提交、失败回滚和资料引用保护；SQLite 回归不能代替这些检查。

如果回退应用版本，保留新表和资料，不使用删表或删除业务数据作为默认回退方式。用户确认验收前，工单和上述真实数据库验证保持待完成状态。