ShiErFeng/docs/test-data-batch-operations.md

测试数据批次操作说明

测试数据采用批次隔离。正式数据的 test_batch_id 为 NULL，测试数据必须归属于一个 biz_test_batch 批次。系统不会因为安装迁移脚本而自动把历史数据标记为测试数据；历史数据需要由超级管理员逐项预览并纳入批次。

权限边界

• 批次创建、编辑、授权、关闭/重新开启、旧数据纳入和批次清理均由后端校验超级管理员身份。
• 普通用户不能通过前端隐藏、菜单权限或直接调用接口绕过后端校验。
• 普通用户只能看到被授权且状态为 ACTIVE 的批次，并在 PDA 或 Web 测试模式中使用该批次。
• 物理删除不再通过菌种、客户、现场、产线、仓库、托盘、入库和发货页面提供。清理必须以批次为单位执行。

上线前准备

1. 先备份数据库，并确认当前没有正在进行的入库、装填、发货、使用或退回操作。
2. MySQL 只执行 shierfeng-fastapi-backend/sql/patches/20260922_test_data_batch_mysql.sql；PostgreSQL 只执行对应的 _pg.sql 文件，不能同时执行两份。
3. 迁移完成后检查 biz_test_batch、biz_test_batch_user 和各业务表的 test_batch_id 字段及外键。
4. 配置在线清理上限。默认 TEST_BATCH_ONLINE_PURGE_MAX_ROWS=0，表示禁止在线清理；只有明确配置为正整数且批次影响总数不超过上限时，管理页才允许执行清理。预览令牌默认有效期为 TEST_BATCH_PREVIEW_TTL_SECONDS=600 秒。

迁移脚本是一次性增量脚本，重复执行前必须由数据库管理员确认目标表和字段是否已经存在。本文档不替代备份、变更审批和回滚预案。

新建并授权批次

1. 超级管理员登录 Web 管理端，进入“系统管理 -> 测试数据批次”，创建批次并记录批次名称。
2. 在“用户”操作中填写需要参与测试的用户 ID。保存时会完整替换该批次的授权用户列表；留空表示取消全部授权。
3. 用户在 PDA 工作台选择“测试”并选择已授权的 ACTIVE 批次。切换模式会重新打开工作台，清空当前页面未提交的表单和扫码状态。
4. 测试模式下的请求自动携带 X-Test-Batch-Id。批次关闭、清理、撤销授权或失效后，客户端会清除本地批次并回到正式模式。

将历史数据纳入批次

历史数据默认仍是正式数据。只有超级管理员可以在菌种、客户、现场、产线、仓库、托盘以及五类业务页面选择根记录，点击“纳入测试批次”。

纳入操作分为两步：

1. 预览：系统根据根记录计算完整关联闭包，展示将被标记的记录和数量，并生成短时有效的预览令牌。
2. 执行：管理员核对批次名称和影响范围后提交。服务端会重新加锁并计算闭包；范围变化、记录已归属于其他批次、批次关闭或令牌过期时，整个操作失败并回滚。

不要直接修改业务表的 test_batch_id。这样会跳过关联闭包、并发校验和审计记录，可能造成跨批次数据无法清理。

关闭与清理批次

1. 批次完成测试后先点击“关闭”。关闭后不能继续写入该批次，但可以重新开启；重新开启会使已有的清理预览失效。
2. 对 CLOSED 批次点击“清理”，先查看预览中的分类、数量和编号。
3. 只有在线清理上限允许时，输入完整批次名称并确认执行。服务端会校验预览令牌、批次名称、影响范围和当前行数，然后按依赖顺序在一个事务中删除批次闭包。
4. 成功后批次状态变为 PURGED，保留清理时间、执行人和数量摘要；已清理批次不可重新开启或再次写入。

清理是不可逆的数据删除操作。影响总数超过在线上限时，应按运维审批流程执行离线清理，不要通过 SQL 手工绕过系统约束。

验证清单

• 正式模式看不到 test_batch_id 非空的测试记录。
• 普通用户无法看到批次管理页的管理操作，也无法调用纳入和清理接口。
• PDA 测试模式的请求带有正确批次 ID，退出登录后本地批次缓存被清除。
• 关闭批次后新建和确认操作被拒绝；清理预览与实际执行之间的数据变化会使执行失败而不是误删。
• 清理完成后，批次闭包中的主数据、单据、明细、库存和事件记录数量与审计摘要一致。