文档：补充测试批次操作说明

README.md

@@ -43,14 +43,16 @@
 * 基础资料：菌种、客户、客户现场、产线、仓库、托盘。
 * 业务流程：仓库入库、工厂装填、发货出库、客户现场使用、退回仓库。
 * 只读报表：托盘库存、装填记录、发货出库、产线消耗、退回仓库、托盘追溯。
-* Android PDA 可直接通过浏览器使用响应式 Web 页面，并支持 HID 扫码枪扫码后回车提交。
+* Android PDA 可通过基于 uni-app 的 H5 页面使用，并支持 HID 扫码枪扫码后回车提交。
 
-本轮交付不是 APP/uni-app 原生端，也未调用设备摄像头。上线前请阅读[托盘流转业务部署说明](./docs/pallet-workflow-deployment.md)。
+本轮交付包含 PDA H5 页面，但暂不打包 APK 或其他原生安装包，也未调用设备摄像头。上线前请阅读[托盘流转业务部署说明](./docs/pallet-workflow-deployment.md)。
+
+测试数据批次的创建、授权、历史数据纳入和清理流程请阅读[测试数据批次操作说明](./docs/test-data-batch-operations.md)。
 
 ## 在线体验
 
 * *账号：admin*
-* *密码：admin123*
+* *密码：请通过授权渠道获取，不在仓库中记录*
 * 演示地址：<a href="https://vfadmin.insistence.tech">vfadmin管理系统<a>
 
 ## 项目开发及发布相关
@@ -131,9 +133,9 @@ shierfeng app run --env=dev
 #### 访问
 
 ```bash
-# 默认账号密码
+# 本地账号
 账号：admin
-密码：admin123
+密码：请在目标环境安全配置中设置后手工输入，不在仓库中记录
 
 # 浏览器访问
 地址：http://localhost:80

docs/test-data-batch-operations.md

@@ -0,0 +1,54 @@
+# 测试数据批次操作说明
+
+测试数据采用批次隔离。正式数据的 `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，退出登录后本地批次缓存被清除。
+- 关闭批次后新建和确认操作被拒绝；清理预览与实际执行之间的数据变化会使执行失败而不是误删。
+- 清理完成后，批次闭包中的主数据、单据、明细、库存和事件记录数量与审计摘要一致。