赋码管理大批量生成改造方案（异步任务化）

一、背景

「生成二维码数据包」（POST /mes/pro/bag-code/generate）与「生成原始数据」（POST /mes/pro/bag-code/raw-generate）在几十万条数据量下直接超时，前端收不到响应。

经代码定位，超时不是单一原因，而是三处叠加：

瓶颈	位置	说明
逐条向 Redis 要码	`MesProBagCodeServiceImpl.java:143-144`、`176-177`	每个袋码生成「追溯码 + 业务码」两次，`MesCodeRedisDAO.generate()` 每次执行一次 Redis `SADD` 往返（`MesCodeRedisDAO.java:53`）。30 万袋 = 60 万次网络往返，仅此一步即分钟级
单事务巨量插入	`MesProBagCodeServiceImpl.java:154`、`185`	`insertBatch` 默认 1000 条/批，但整批在同一个 `@Transactional` 内完成，几十万行形成超大事务
同步长请求	Controller 直接返回生成结果	请求线程从头执行到尾；网关/浏览器超时后连接断开，但服务端仍继续写库。用户重试会再生成一整包重复数据，且无幂等保护

此外，selectMaxBagNo() 对 mes_pro_bag_code 做 MAX(bag_no)，当前表没有 bag_no 索引，数据量上来后每次生成都要全表扫描。

二、目标与非目标

目标

几十万条（单次上限 100 万）生成不再依赖单次 HTTP 请求时长，提交后立即返回任务编号。
生成过程可见进度、可取消；失败/取消不留下半成品数据包。
消除逐条 Redis 往返与超大事务，生成吞吐与数据量解耦。
小批量保持同步秒回，不改变使用体验。
接口具备幂等性，网络重试不会重复生成。

非目标

不改造「破损替换」「绑定批次/托盘」等其他赋码操作；它们本身是少量数据的短事务。
不做服务重启后的断点续跑（见 5.7 取舍说明）。
不调整 16 位随机码的生成规则与 biz:code:used 集合机制。

三、总体方案

采用与现有二维码导出任务（MesProQrExportTask）一致的「小批量同步、大批量异步」双路径：

前端提交生成
   │
   ├─ 袋码总数 ≤ sync-threshold（默认 20000）
   │     └─ 请求线程内完成：批量取码 → 分段落库 → 返回原有结果（async=false）
   │
   └─ 袋码总数 > sync-threshold
         ├─ 落任务记录，注册运行态，投递后台线程池，立即返回 taskId + uuid（async=true）
         └─ 前端按 taskId 轮询进度；完成后刷新列表；取消则删除已生成的部分数据

同步与异步共用同一套「分段生成」执行器，避免两份逻辑。

四、任务模型

4.1 状态机

状态值	名称	说明
10	排队中	已落库，等待线程池接管
20	生成中	后台线程执行中
25	取消中	已收到取消请求，正在停止并清理部分数据
30	已完成	全部袋码（及托盘）已落库
40	已取消	用户取消，部分数据已清理
50	已失败	异常终止，部分数据已清理

终态：30 / 40 / 50。

4.2 表结构

新增 mes_pro_bag_code_generate_task：

字段	类型	说明
id	BIGINT	主键
request_id	VARCHAR(64)	幂等键，唯一索引；前端每次提交生成一个 UUID
biz_type	VARCHAR(16)	`PACKAGE`（数据包）/ `RAW`（原始数据）
uuid	VARCHAR(32)	本次生成组 UUID（提交时即生成，失败/取消后用于清理）
item_id / item_code / item_name	BIGINT / VARCHAR	品种快照
unit_type	VARCHAR(32)	计量单位类型（吨 / 48袋 / 100袋）
per_pallet	INT	每托袋数；吨类型为 0
pallet_count	INT	托盘数；原始数据为 0
total_count	INT	袋码总数
finished_count	INT	已生成袋码数
status	TINYINT	状态，见 4.1
error_msg	VARCHAR(500)	失败原因
finish_time	DATETIME	完成/终止时间
creator / create_time / updater / update_time / deleted	—	沿用 `BaseDO`

索引：

UNIQUE KEY uk_request_id (request_id)
KEY idx_status (status)
KEY idx_uuid (uuid)

迁移脚本：sql/mysql/mes_pro_bag_code_generate_task.sql。

4.3 袋码表索引

新增 KEY idx_bag_no (bag_no)，用于 selectMaxBagNo() 与袋序号排序。

迁移脚本：sql/mysql/mes_pro_bag_code_bag_no_index.sql（先查 information_schema.statistics 再建，兼容重复执行）。

五、详细设计

5.1 接口

1）生成数据包 / 原始数据（沿用原路径）

方法	路径	说明
POST	`/mes/pro/bag-code/generate`	合并后的数据包生成入口
POST	`/mes/pro/bag-code/raw-generate`	原始袋码生成入口

请求参数不变。响应扩展：

字段	类型	说明
async	Boolean	true=已转后台任务；false=本次同步完成
taskId	Long	异步任务编号；同步时为 null
uuid	String	生成组 UUID，两种模式都返回
type / perPallet	String / Integer	数据包模式下返回
totalCount	Integer	袋码总数
palletCount	Integer	托盘总数；原始数据为 0
palletIds	List<Long>	仅同步完成时返回；异步模式为 null，避免上千个 ID 撑大响应

后端按 totalCount 自动分流，前端不需要各自计算阈值。

2）任务查询（轮询）

方法	路径	说明
GET	`/mes/pro/bag-code/generate-task/get?id=`	查询任务状态与进度

响应字段：id、bizType、status、statusName、progress（0~100）、totalCount、finishedCount、palletCount、itemId、itemCode、itemName、unitType、perPallet、uuid、errorMsg、createTime、finishTime。

3）任务取消

方法	路径	说明
POST	`/mes/pro/bag-code/generate-task/cancel?id=`	请求取消；已终态任务拒绝

权限：提交/取消用 mes:pro-bag-code:create，查询用 mes:pro-bag-code:query。

5.2 提交阶段

校验品种、计量单位类型，换算袋码总数（与原逻辑一致）。
数量校验：totalCount ≤ maxTaskCount（默认 1,000,000），超出直接报错。
幂等处理：requestId 非空时先查任务表；命中则直接返回已有任务，不重复生成。并发重复提交由 uk_request_id 唯一索引兜底，捕获冲突后回查。
数量 ≤ syncThreshold：走同步执行，返回 async=false。
数量 > syncThreshold：

生成任务 UUID；
插入任务记录（状态=10）；
先注册内存运行态，再投递线程池（与导出任务一致，避免清理任务误回收）；
返回 async=true、taskId、uuid、totalCount、palletCount。

并发闸门：同一时间最多 maxConcurrentTasks（默认 1）个生成任务。占用失败时返回「已有生成任务进行中」并带上当前任务进度。
线程池拒绝时把任务置为失败并归还并发许可。

5.3 批量取码（核心优化）

将「逐条 SADD」改为「批量脚本写入」：

Java 侧按 5000 个一批生成候选码（ThreadLocalRandom 精确生成 16 位数字）。
一次 Lua 脚本原子完成：逐个 SADD 到 biz:code:used，返回本批实际写入成功的码。
若成功数不足（随机碰撞，概率极低），只对缺额继续生成下一批，直到凑齐。
追溯码与业务码各走一次批量流程。

效果：30 万袋从 60 万次网络往返降到约 120 次（每次 5000 个）。

袋码与托盘码都走该批量方法；generate() 保留给其他少量场景。

5.4 分段落库

一次性分配袋序号：任务开始时调用一次 allocateBagNoStart(totalCount, selectMaxBagNo())，后续各段用 startNo + offset 推算。取消产生的序号空洞允许存在（序号只要求唯一、不回退），因此不要按段重复分配。
托盘（仅数据包模式）：按 1000 个/批插入，保留 palletId 与 tempCode 两个数组供袋码段引用，避免堆积整表 DO。
袋码：按 chunkSize（默认 5000）分段落库，每段落库后回写一次 finished_count。
事务边界：每个分段的插入在独立的 REQUIRES_NEW 事务中完成，避免几十万行单事务。分段方法必须由执行器跨 Bean 调用，保证事务代理生效。
每段开始前检查取消标记与最长运行时间，段内不再做数据库查询。

5.5 进度与节流

finished_count 每段（5000 条）更新一次，30 万条约 60 次更新，开销可忽略。
生成过程以数据库写入为主，不叠加 CPU 密集操作，因此不做 CPU 节流；仅保留最长运行时间（默认 30 分钟）兜底。
每段写入前检查取消标记。

5.6 取消

取消接口把内存中的取消标记置位，任务进入「取消中」。
执行线程在当前分段结束后停止，随后：

物理删除该 uuid 下已生成的袋码（DELETE ... WHERE uuid = ? LIMIT 5000 循环）；
物理删除本次已创建的托盘：托盘表新增 generate_uuid 记录生成组，按 DELETE ... WHERE generate_uuid = ? AND batch_id IS NULL AND code IS NULL LIMIT 5000 循环。该条件确保只删从未入批次的临时托盘，不会误删用户后续已绑定的托盘；
任务置为「已取消」。

任务不在本进程运行（进程重启后的残留）时，取消接口直接清理残留数据并置为「已取消」。

说明：生成一半的数据包不可用，必须清理。这里采用物理删除而非逻辑删除，是因为这些行从未对外展示，逻辑删除只会留下几十万条垃圾并浪费索引空间；用户主动删除已生成数据包仍沿用原有逻辑删除逻辑。

5.7 失败与重启回收

执行异常：清理该 uuid 的部分数据，任务置为「已失败」，error_msg 截断到 500 字符。
进程重启：内存运行态丢失。启动后与每 5 分钟一次的清理任务扫描非终态任务，凡不在运行态注册表中的，一律置为「已失败」并清理部分数据。
不实现断点续跑：续跑需要精确处理分段事务边界、托盘映射与取消空洞，复杂度高；而重新生成一次的成本远低于维护续跑状态机。UI 明确提示“任务中断，请重新生成”。

5.8 幂等与重复提交

前端每次打开生成弹窗生成一个 requestId，同一次提交的重试复用同一个值（如网络重试）。
后端以 requestId 唯一索引保证同一请求只落一个任务；重复提交直接返回已有任务。
不传 requestId 时仍可用，但失去网络级幂等保护；前端必须传。

5.9 配置项

新增 mes.bag-code.generate 前缀配置：

配置	默认值	说明
sync-threshold	20000	不超过该数量同步生成
chunk-size	5000	每段袋码/每批取码数量
max-concurrent-tasks	1	同时运行的后台生成任务数
max-task-count	1000000	单次生成袋码上限
max-runtime-minutes	30	单任务最长运行时间
poll-interval-seconds	2	仅作为前端轮询建议值下发（可选）

六、前端联调要点

本节只描述行为与字段，不提供前端代码。

6.1 涉及页面

赋码管理列表页（mes/pro/bagCode）
「生成二维码数据包」弹窗（generate-form.vue）
「生成原始数据」入口（如存在独立弹窗，同样处理）

6.2 提交流程

打开生成弹窗时生成一个 requestId（UUID），关闭重开则重新生成；同一次提交的自动重试复用同一个 requestId。
调用原生成接口，请求体增加 requestId。
响应 async=false：维持现有成功提示与列表刷新行为。
响应 async=true：弹窗不立即关闭，展示进度条，按 poll-interval-seconds（建议 2 秒）轮询任务查询接口，直到状态进入终态。

状态 30：提示“生成完成，共 N 条袋码”，关闭弹窗并刷新列表。
状态 40：提示“任务已取消”。
状态 50：展示 errorMsg，允许用户重新提交（重新生成 requestId）。

轮询期间提供“取消生成”按钮，调用取消接口；按钮点击后置灰，等待任务进入终态。
页面关闭或组件卸载时停止轮询；重新进入页面时，可通过任务编号继续查询（任务编号可暂存在本地状态）。

6.3 字段展示

字段	展示位置	说明
progress	生成弹窗	进度条百分比
finishedCount / totalCount	生成弹窗	文案“已生成 x / y 条”
statusName	生成弹窗	任务状态标签
palletCount	完成提示	数据包模式提示自动生成的托盘数
errorMsg	生成弹窗	失败原因

6.4 注意事项

异步模式响应中 palletIds 为 null，前端不要再用 palletIds.length 判断托盘数，改用 palletCount。
同一用户同时只能运行一个后台生成任务；被拒绝时后端会返回当前任务进度，前端可直接切换为查询该任务。
不要用“请求是否超时”来判断任务失败；提交接口在转异步后应快速返回。

七、性能估算与验收标准

7.1 估算

环节	改造前（30 万袋）	改造后
Redis 取码	60 万次 RTT，分钟级	约 120 次 RTT，秒级
数据库写入	1 个超大事务	60 个 5000 行事务
HTTP 响应	等待全部完成，必然超时	提交后 1 秒内返回 taskId
用户重试	产生重复数据包	幂等键去重

7.2 验收标准

30 万袋码 + 对应托盘可完整生成，进度可从 0 推进到 100。
提交接口在 1 秒内返回；生成过程中列表可正常查询其他数据。
取消后数据库中该 uuid 无残留袋码与托盘，任务状态为已取消。
模拟进程重启：残留任务在一次清理周期内变为已失败，部分数据被清理。
相同 requestId 重复提交只产生一个任务、一个生成组。
2 万条以内仍为同步返回，响应结构与旧版兼容（新增字段不影响旧前端解析）。
现有「破损替换 / 绑定批次 / 绑定托盘 / 导出」回归通过。

八、风险与取舍

风险	应对
Redis `biz:code:used` 集合持续增长（几十万级/次）	现网已有该机制，集合只存 16 字符短串，单次几十万条约几十 MB；后续可评估按前缀分片，本次不动
清理 30 万行部分数据耗时	分段 `DELETE ... LIMIT 5000`，避免长事务与主从延迟尖峰
`bag_no` 为 INT，理论上限约 21 亿	单次上限 100 万；按当前量级可支撑多年，后续如需长期使用再迁移 BIGINT
异步任务期间服务重启	不续跑，标记失败并清理，提示重新生成
同步路径仍受网关超时约束	阈值内单次最多 2 万条，批量取码后预计 1~3 秒，留足余量

九、实施步骤与状态追踪

序号	内容	状态
1	方案文档确认	已完成
2	新增任务表、袋码 `bag_no` 索引、托盘 `generate_uuid` 迁移脚本	已完成
3	新增任务 DO / Mapper / 状态枚举 / 配置项	已完成
4	`MesCodeRedisDAO` 增加批量取码方法	已完成
5	抽取分段生成执行器（同步/异步共用）	已完成
6	新增任务 Service（提交、查询、取消、回收）与线程池配置	已完成
7	改造两个生成接口的同步/异步分流与响应字段	已完成
8	新增任务查询/取消接口与权限	已完成
9	启动与定时清理任务	已完成
10	前端联调（弹窗进度、轮询、取消）	已完成
11	编译检查与大批量实测	已完成（本地 mom-thzy：30 万条约 76 秒生成完毕，提交响应 0.18 秒；取消清理无残留；幂等与并发闸门均验证通过）

迁移脚本

脚本	说明
`sql/mysql/mes_pro_bag_code_generate_task.sql`	任务表
`sql/mysql/mes_pro_bag_code_bag_no_index.sql`	袋码 `bag_no` 索引
`sql/mysql/mes_pro_pallet_generate_uuid.sql`	托盘 `generate_uuid` 列与索引