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

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

本指引对应工单 #9。2026-11-02 经用户明确授权，代码已快进合入并推送 V3.0（业务及 SQL 提交 baf16d49b），下列两个新增脚本已在已确认的测试库执行成功。未启动 MySQL 容器；真实业务事务、额度并发及完整登录联调仍待验证。

前置结构

沿用工单 #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 回归不能代替这些检查。

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

测试库执行记录（2026-11-02）

• 目标：用户已确认的 47.99.164.66:3306 / shanxia2.0，服务端 MySQL 5.7.36；从主目录 backend/.env 在进程内读取连接配置，未修改配置。
• 前置检查：原额度九表和 pl_plan.cert_configuration 已存在；新资料表与两个新菜单此前不存在。
• 修正菜单迁移：测试库计划用证菜单 ID 为 PL_PLAN_CERT，与前端静态 ID 不同；改按 pl:plan-cert:list + plan-cert 定位，保留租户、Web 根、父级及软删除限制。只读投影验证原脚本漏选、修复后精确命中三行，并通过独立审查。
• 执行结果：建立 pl_stop_legal_document，字段顺序、唯一索引、InnoDB/DYNAMIC/utf8mb4 已核对；菜单事务新增 2 行、更新 3 行。五个视图顺序为 1–5，已软删除分组未恢复，角色授权记录摘要前后一致，未重算历史额度或迁移旧附件。
• 备份及逐步日志：主目录 .local/agent/backups/issue9-test-db-20261102-095421/，含受影响表结构、执行前后菜单记录、原 SQL 与执行校验结果；本地受限权限保存，不纳入 Git。此为本次迁移涉及结构和菜单的备份，不是全库业务数据备份。
• 合并前回归：后端 523 项、Web 194 项通过；应用代码与此前已构建、浏览器验证及独立审查的版本一致，本次仅修正上述 SQL。主目录原 39 个未提交文件内容保持不变。
• 本地主目录已同步 V3.0；现有开发服务自动加载后，8000 健康检查和 3006 页面返回 200，OpenAPI 已含段次证明、合同统计、证件统计新接口。未主动启停服务、未操作生产环境；此连通检查不代表已完成登录后的业务验收。