临时批量回收设备脚本

scripts/batch_device_recall/README.md

@@ -0,0 +1,44 @@
+# 批量回收设备脚本
+
+该脚本读取单列 CSV，通过生产环境已有的设备列表和回收接口处理设备，不依赖尚未部署的异步 CSV 批量任务。
+
+默认只预演，不发送 HTTP 请求。只有增加 `--execute` 才会先解析全部设备，再按每批最多 100 台调用 `POST /api/admin/devices/recall`。接口会同步设备及其绑定卡的归属，并保留分配记录和审计日志。
+
+## CSV 格式
+
+首行表头可选，每行填写一个设备 IMEI 或虚拟号：
+
+```csv
+device_identifier
+868120000000001
+VIRTUAL000001
+```
+
+脚本会拦截多列、空值、重复标识、未找到设备、模糊匹配和同一设备被 IMEI、虚拟号重复引用的情况。全部设备预检查通过后才会发送回收请求。
+
+回收目标沿用登录账号的既有接口权限：平台账号回收到平台库存，代理账号只能从直属下级回收到自己的店铺。
+
+## 预演
+
+```bash
+python3 scripts/batch_device_recall/batch_device_recall.py \
+  --base-url https://cmp-api.example.com \
+  --csv scripts/batch_device_recall/devices.example.csv
+```
+
+## 真实执行
+
+推荐通过环境变量传递 Token：
+
+```bash
+JUNHONG_ADMIN_TOKEN='<后台Access Token>' \
+python3 scripts/batch_device_recall/batch_device_recall.py \
+  --base-url https://cmp-api.example.com \
+  --csv /path/to/devices.csv \
+  --remark '生产环境人工批量回收' \
+  --execute
+```
+
+未提供 Token 时，也可使用 `JUNHONG_ADMIN_USERNAME` 和 `JUNHONG_ADMIN_PASSWORD` 自动登录。
+
+结果默认写入输入文件同目录的 `原文件名_回收结果_YYYYMMDD_HHMMSS.csv`。脚本不会自动重试回收请求；网络异常时应先核对设备归属，再决定是否重跑失败项。