From 977e7f996ee18e01d2c7da34e6bcbf7b7b36be2b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=84=A6=E9=BE=99=E8=A8=80?= Date: Thu, 24 Sep 2026 09:45:47 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9A=E8=A1=A5=E5=85=85?= =?UTF-8?q?=E6=B5=8B=E8=AF=95=E6=89=B9=E6=AC=A1=E6=93=8D=E4=BD=9C=E8=AF=B4?= =?UTF-8?q?=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 12 ++++--- docs/test-data-batch-operations.md | 54 ++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+), 5 deletions(-) create mode 100644 docs/test-data-batch-operations.md diff --git a/README.md b/README.md index 36d08c3..3d5293f 100644 --- a/README.md +++ b/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* +* *密码：请通过授权渠道获取，不在仓库中记录* * 演示地址：vfadmin管理系统 ## 项目开发及发布相关 @@ -131,9 +133,9 @@ shierfeng app run --env=dev #### 访问 ```bash -# 默认账号密码 +# 本地账号 账号：admin -密码：admin123 +密码：请在目标环境安全配置中设置后手工输入，不在仓库中记录 # 浏览器访问 地址：http://localhost:80 diff --git a/docs/test-data-batch-operations.md b/docs/test-data-batch-operations.md new file mode 100644 index 0000000..ed42410 --- /dev/null +++ b/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，退出登录后本地批次缓存被清除。 +- 关闭批次后新建和确认操作被拒绝；清理预览与实际执行之间的数据变化会使执行失败而不是误删。 +- 清理完成后，批次闭包中的主数据、单据、明细、库存和事件记录数量与审计摘要一致。