super/crawler-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

perf(F5+): 行数据按需拉取（结果行版本信号）+ 修复 progress/light 恒判 missing

Browse Source 
行数据按需拉取（审查 F5 后续）：
- V125 给 biz_file_result 补 updated_at（DEFAULT/ON UPDATE 由数据库维护，
  实体标注 insertStrategy/updateStrategy=NEVER —— 否则 selectById→updateById 的
  写回会把旧值写回去、ON UPDATE 不触发，版本信号静默冻结）
- 装配器回传 rowsVersion=「最后变更时间毫秒#行数」，5 个品牌工具页版本未变即跳过
  带行明细的重型 batch；前端变更信号为 rowsVersion + status/fileStatus/fileReady 复合
  （任务收尾常见「行早写完、之后才置成功」，只看行版本会把界面卡在旧状态）

修复线上缺陷（同一功能验证时暴露）：
- TaskProgressLightAssembler 列裁剪漏选 module_type 却用它做模块过滤 →
  getModuleType() 恒为 null → light 恒把任务判成 missing；第七批把 light 接进
  跟价/定时匹配/商品风险的轮询后，消费方会把运行中任务判为 FAILED
- 补选中列 + 守卫用例 taskQueryMustSelectModuleType（已反向验证：去掉修复即红）
- 前端 lightClaimsAllTasksMissing：整体性 missing 结论用重型端点复核后再采信

契约与文档：light 白名单补 rowsVersion（Java 契约测试 / spec 06 §2 / 12 个端点描述）
测试：mvn test 2901 全绿；前端 npm test 765 全绿
This commit is contained in:
黄自达
2026-09-14 12:08:25 +08:00
parent 9166656673
commit 5ea52e5291
32 changed files with 641 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend-java/src/main/java/com/nanri/aiimage/modules/appearancepatent/controller/AppearancePatentController.java
+2 -2
View File
@@ -110,8 +110,8 @@ public class AppearancePatentController {
@PostMapping("/tasks/progress/light")
@Operation(summary = "批量查询任务轻量进度（前端轮询专用）",
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt），"
+ "不查明细/result 行，响应体更小；旧 progress/batch 端点保留不动。")
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt/rowsVersion），"
+ "不返回行明细内容（仅多一次结果行版本聚合查询），响应体更小；旧 progress/batch 端点保留不动。")
public ApiResponse<TaskProgressLightBatchVo> progressLight(@Valid @RequestBody TaskProgressLightRequest request) {
// 透传 userId：此前传 null = 不过滤归属，匿名遍历 taskId 即可读他人任务状态（2026-09 审查）
return ApiResponse.success(service.progressLight(request.getTaskIds(), request.getUserId()));
backend-java/src/main/java/com/nanri/aiimage/modules/collectdata/controller/CollectDataController.java
+2 -2
View File
@@ -121,8 +121,8 @@ public class CollectDataController {
@PostMapping("/tasks/progress/light")
@Operation(summary = "批量查询任务轻量进度（前端轮询专用）",
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt），"
+ "不查明细/result 行，响应体更小；旧 progress/batch 端点保留不动。")
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt/rowsVersion），"
+ "不返回行明细内容（仅多一次结果行版本聚合查询），响应体更小；旧 progress/batch 端点保留不动。")
public ApiResponse<TaskProgressLightBatchVo> progressLight(@Valid @RequestBody TaskProgressLightRequest request) {
// 透传 userId：此前传 null = 不过滤归属，匿名遍历 taskId 即可读他人任务状态（2026-09 审查）
return ApiResponse.success(service.progressLight(request.getTaskIds(), request.getUserId()));
backend-java/src/main/java/com/nanri/aiimage/modules/deletebrand/controller/DeleteBrandRunController.java
+2 -2
View File
@@ -102,8 +102,8 @@ public class DeleteBrandRunController {
@PostMapping("/tasks/progress/light")
@Operation(summary = "批量查询任务轻量进度（前端轮询专用）",
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt），"
+ "不查明细/result 行，响应体更小；旧 progress/batch 端点保留不动。")
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt/rowsVersion），"
+ "不返回行明细内容（仅多一次结果行版本聚合查询），响应体更小；旧 progress/batch 端点保留不动。")
public ApiResponse<TaskProgressLightBatchVo> progressLight(@Valid @RequestBody TaskProgressLightRequest request) {
// 透传 userId：此前传 null = 不过滤归属，匿名遍历 taskId 即可读他人任务状态（2026-09 审查）
return ApiResponse.success(deleteBrandRunService.progressLight(request.getTaskIds(), request.getUserId()));
backend-java/src/main/java/com/nanri/aiimage/modules/patroldelete/controller/PatrolDeleteController.java
+2 -2
View File
@@ -177,8 +177,8 @@ public class PatrolDeleteController {
@PostMapping("/tasks/progress/light")
@Operation(summary = "批量查询任务轻量进度（前端轮询专用）",
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt），"
+ "不查明细/result 行，响应体更小；旧 progress/batch 端点保留不动。")
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt/rowsVersion），"
+ "不返回行明细内容（仅多一次结果行版本聚合查询），响应体更小；旧 progress/batch 端点保留不动。")
public ApiResponse<TaskProgressLightBatchVo> progressLight(@Valid @RequestBody TaskProgressLightRequest request) {
// 透传 userId：此前传 null = 不过滤归属，匿名遍历 taskId 即可读他人任务状态（2026-09 审查）
return ApiResponse.success(patrolDeleteTaskService.progressLight(request.getTaskIds(), request.getUserId()));
backend-java/src/main/java/com/nanri/aiimage/modules/pricetrack/controller/PriceTrackController.java
+2 -2
View File
@@ -279,8 +279,8 @@ public class PriceTrackController {
@PostMapping("/tasks/progress/light")
@Operation(summary = "批量查询任务轻量进度（前端轮询专用）",
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt），"
+ "不查明细/result 行，响应体更小；旧 progress/batch 端点保留不动。")
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt/rowsVersion），"
+ "不返回行明细内容（仅多一次结果行版本聚合查询），响应体更小；旧 progress/batch 端点保留不动。")
public ApiResponse<TaskProgressLightBatchVo> progressLight(@Valid @RequestBody TaskProgressLightRequest request) {
// 透传 userId：此前传 null = 不过滤归属，匿名遍历 taskId 即可读他人任务状态（2026-09 审查）
return ApiResponse.success(priceTrackTaskService.progressLight(request.getTaskIds(), request.getUserId()));
backend-java/src/main/java/com/nanri/aiimage/modules/productrisk/controller/ProductRiskResolveController.java
+2 -2
View File
@@ -177,8 +177,8 @@ public class ProductRiskResolveController {
@PostMapping("/tasks/progress/light")
@Operation(summary = "批量查询任务轻量进度（前端轮询专用）",
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt），"
+ "不查明细/result 行，响应体更小；旧 progress/batch 端点保留不动。")
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt/rowsVersion），"
+ "不返回行明细内容（仅多一次结果行版本聚合查询），响应体更小；旧 progress/batch 端点保留不动。")
public ApiResponse<TaskProgressLightBatchVo> progressLight(@Valid @RequestBody TaskProgressLightRequest request) {
// 透传 userId：此前传 null = 不过滤归属，匿名遍历 taskId 即可读他人任务状态（2026-09 审查）
return ApiResponse.success(productRiskTaskService.progressLight(request.getTaskIds(), request.getUserId()));
backend-java/src/main/java/com/nanri/aiimage/modules/publish/controller/PublishController.java
+2 -2
View File
@@ -108,8 +108,8 @@ public class PublishController {
@PostMapping("/tasks/progress/light")
@Operation(summary = "批量查询任务轻量进度（前端轮询专用）",
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt），"
+ "不查明细/result 行，响应体更小；旧 progress/batch 端点保留不动。user_id 可省略，传入时仅返回该用户的任务。")
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt/rowsVersion），"
+ "不返回行明细内容（仅多一次结果行版本聚合查询），响应体更小；旧 progress/batch 端点保留不动。user_id 可省略，传入时仅返回该用户的任务。")
public ApiResponse<TaskProgressLightBatchVo> progressLight(
@Valid @RequestBody TaskProgressLightRequest request) {
return ApiResponse.success(publishTaskService.progressLight(request.getUserId(), request.getTaskIds()));
backend-java/src/main/java/com/nanri/aiimage/modules/queryasin/controller/QueryAsinTaskController.java
+2 -2
View File
@@ -147,8 +147,8 @@ public class QueryAsinTaskController {
@PostMapping("/tasks/progress/light")
@Operation(summary = "批量查询任务轻量进度（前端轮询专用）",
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt），"
+ "不查明细/result 行，响应体更小；旧 progress/batch 端点保留不动。")
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt/rowsVersion），"
+ "不返回行明细内容（仅多一次结果行版本聚合查询），响应体更小；旧 progress/batch 端点保留不动。")
public ApiResponse<TaskProgressLightBatchVo> progressLight(@Valid @RequestBody TaskProgressLightRequest request) {
// 透传 userId：此前传 null = 不过滤归属，匿名遍历 taskId 即可读他人任务状态（2026-09 审查）
return ApiResponse.success(queryAsinTaskService.progressLight(request.getTaskIds(), request.getUserId()));
backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/controller/ShopDataCrawlTaskController.java
+2 -2
View File
@@ -161,8 +161,8 @@ public class ShopDataCrawlTaskController {
@PostMapping("/tasks/progress/light")
@Operation(summary = "批量查询任务轻量进度（前端轮询专用）",
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt），"
+ "不查明细/result 行，响应体更小；旧 progress/batch 端点保留不动。")
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt/rowsVersion），"
+ "不返回行明细内容（仅多一次结果行版本聚合查询），响应体更小；旧 progress/batch 端点保留不动。")
public ApiResponse<TaskProgressLightBatchVo> progressLight(@Valid @RequestBody TaskProgressLightRequest request) {
// 透传 userId：此前传 null = 不过滤归属，匿名遍历 taskId 即可读他人任务状态（2026-09 审查）
return ApiResponse.success(taskService.progressLight(request.getTaskIds(), request.getUserId()));
backend-java/src/main/java/com/nanri/aiimage/modules/shopmatch/controller/ShopMatchController.java
+2 -2
View File
@@ -201,8 +201,8 @@ public class ShopMatchController {
@PostMapping("/tasks/progress/light")
@Operation(summary = "批量查询任务轻量进度（前端轮询专用）",
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt），"
+ "不查明细/result 行，响应体更小；旧 progress/batch 端点保留不动。")
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt/rowsVersion），"
+ "不返回行明细内容（仅多一次结果行版本聚合查询），响应体更小；旧 progress/batch 端点保留不动。")
public ApiResponse<TaskProgressLightBatchVo> progressLight(@Valid @RequestBody TaskProgressLightRequest request) {
// 透传 userId：此前传 null = 不过滤归属，匿名遍历 taskId 即可读他人任务状态（2026-09 审查）
return ApiResponse.success(shopMatchTaskService.progressLight(request.getTaskIds(), request.getUserId()));
backend-java/src/main/java/com/nanri/aiimage/modules/similarasin/controller/SimilarAsinController.java
+1 -1
View File
@@ -128,7 +128,7 @@ public class SimilarAsinController {
@PostMapping("/tasks/progress/light")
@Operation(summary = "批量查询任务轻量进度（前端轮询专用）",
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileReady/updatedAt），"
+ "不查明细/result 行，响应体更小；旧 progress/batch 端点保留不动。")
+ "不返回行明细内容（仅多一次结果行版本聚合查询），响应体更小；旧 progress/batch 端点保留不动。")
public ApiResponse<SimilarAsinTaskLightBatchVo> progressLight(@Valid @RequestBody SimilarAsinTaskLightRequest request) {
// 归属过滤：只查询属于该用户的任务（userId 未传时保持原行为，兼容未升级调用方）
return ApiResponse.success(service.progressLight(progressOwnershipSupport
backend-java/src/main/java/com/nanri/aiimage/modules/task/mapper/FileResultMapper.java
+26
View File
@@ -1,9 +1,35 @@
package com.nanri.aiimage.modules.task.mapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.nanri.aiimage.modules.task.model.dto.TaskRowsVersionDto;
import com.nanri.aiimage.modules.task.model.entity.FileResultEntity;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;
import org.apache.ibatis.annotations.Select;
import java.util.List;
@Mapper
public interface FileResultMapper extends BaseMapper<FileResultEntity> {
/**
* 各任务结果行的版本（"行数据按需拉取"的变更信号）。
*
* <p>latestRowAt 取 biz_file_result.updated_at（V125 新增，列定义 ON UPDATE CURRENT_TIMESTAMP），
* 原地更新（result_file_url / row_count 等）与新插入都会刷新它；rowCount 用于识别行被删除。
* 前端据 (latestRowAt, rowCount) 判断该任务的行数据是否变化，未变就不必再拉带行明细的重型 batch。
* GROUP BY 走 (task_id) 索引，每任务一行。
*/
@Select("""
<script>
SELECT task_id AS taskId, MAX(updated_at) AS latestRowAt, COUNT(*) AS rowCount
FROM biz_file_result
WHERE module_type = #{moduleType}
AND task_id IN
<foreach item="taskId" collection="taskIds" open="(" separator="," close=")">#{taskId}</foreach>
GROUP BY task_id
</script>
""")
List<TaskRowsVersionDto> selectRowsUpdatedAtByTaskIds(@Param("moduleType") String moduleType,
@Param("taskIds") List<Long> taskIds);
}
backend-java/src/main/java/com/nanri/aiimage/modules/task/model/dto/TaskRowsVersionDto.java
+12
View File
@@ -0,0 +1,12 @@
package com.nanri.aiimage.modules.task.model.dto;
import java.time.LocalDateTime;
/**
* 任务结果行的版本信号（「行数据按需拉取」用，2026-09 审查 F5 后续）。
*
* <p>latestRowAt 是该任务结果行的最后变更时间（biz_file_result.updated_at，见 V125），
* rowCount 是行数——两者一起构成版本：既能发现行内容被原地更新，也能发现行被删除。
*/
public record TaskRowsVersionDto(Long taskId, LocalDateTime latestRowAt, Long rowCount) {
}
backend-java/src/main/java/com/nanri/aiimage/modules/task/model/entity/FileResultEntity.java
+11
View File
@@ -1,6 +1,8 @@
package com.nanri.aiimage.modules.task.model.entity;
import com.baomidou.mybatisplus.annotation.FieldStrategy;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;
@@ -26,4 +28,13 @@ public class FileResultEntity {
private String errorMessage;
private Long userId;
private LocalDateTime createdAt;
/**
* 最后变更时间（V125 新增）：由数据库维护（DEFAULT CURRENT_TIMESTAMP + ON UPDATE CURRENT_TIMESTAMP），
* 作为「该任务结果行是否变化」的版本信号（progress/light 的 rowsVersion）。
*
* <p>禁止应用显式写：MySQL 在 UPDATE 语句显式给该列赋值时**不会**触发自动更新，
* 而本表写回多为 selectById → 改字段 → updateById（实体带着旧值），一旦写回就会冻结版本、让前端漏刷新。
*/
@TableField(value = "updated_at", insertStrategy = FieldStrategy.NEVER, updateStrategy = FieldStrategy.NEVER)
private LocalDateTime updatedAt;
}
backend-java/src/main/java/com/nanri/aiimage/modules/task/model/vo/TaskProgressLightVo.java
+6
View File
@@ -25,4 +25,10 @@ public class TaskProgressLightVo {
private Boolean fileReady;
@Schema(description = "最后更新时间，ISO 本地时间字符串。", example = "2026-04-26T10:05:00")
private String updatedAt;
/**
* 结果行版本（该任务 biz_file_result 行 MAX(updated_at) 的毫秒值，无行时为 null）。
* 前端据此判断"行数据是否有变化"：版本未变就不必再拉取带行明细的重型 batch（行数据按需拉取）。
*/
@Schema(description = "结果行版本（毫秒），用于行数据按需拉取。", example = "1757788800000")
private String rowsVersion;
}
backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskProgressLightAssembler.java
+21
View File
@@ -1,7 +1,9 @@
package com.nanri.aiimage.modules.task.service;
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.nanri.aiimage.modules.task.mapper.FileResultMapper;
import com.nanri.aiimage.modules.task.mapper.FileTaskMapper;
import com.nanri.aiimage.modules.task.model.dto.TaskRowsVersionDto;
import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity;
import com.nanri.aiimage.modules.task.model.entity.TaskFileJobEntity;
import com.nanri.aiimage.modules.task.model.vo.TaskProgressLightBatchVo;
@@ -9,6 +11,7 @@ import com.nanri.aiimage.modules.task.model.vo.TaskProgressLightVo;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Component;
import java.time.ZoneId;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
@@ -28,6 +31,7 @@ public class TaskProgressLightAssembler {
public static final int MAX_TASK_IDS = 200;
private final FileTaskMapper fileTaskMapper;
private final FileResultMapper fileResultMapper;
private final TaskFileJobService taskFileJobService;
public TaskProgressLightBatchVo assemble(String moduleType, Long userId, List<Long> taskIds) {
@@ -41,7 +45,9 @@ public class TaskProgressLightAssembler {
return vo;
}
LambdaQueryWrapper<FileTaskEntity> query = new LambdaQueryWrapper<FileTaskEntity>()
// module_type 必须选中：下面用它做模块过滤，漏选则 getModuleType() 恒为 null → 所有任务被判 missing
.select(FileTaskEntity::getId,
FileTaskEntity::getModuleType,
FileTaskEntity::getStatus,
FileTaskEntity::getUpdatedAt)
.in(FileTaskEntity::getId, normalizedIds);
@@ -55,6 +61,20 @@ public class TaskProgressLightAssembler {
}
}
Map<Long, TaskFileJobEntity> jobMap = taskFileJobService.findAssembleJobsByTaskIds(moduleType, new ArrayList<>(taskMap.keySet()));
// 行数据版本：一次 GROUP BY 拿回每个任务结果行的（最后变更时间, 行数），作为行数据按需拉取的信号
Map<Long, String> rowsVersions = new LinkedHashMap<>();
if (!taskMap.isEmpty()) {
for (TaskRowsVersionDto version : fileResultMapper.selectRowsUpdatedAtByTaskIds(
moduleType, new ArrayList<>(taskMap.keySet()))) {
if (version == null || version.taskId() == null || version.latestRowAt() == null) {
continue;
}
// 编码为「毫秒#行数」：行内容被原地更新与行被删除都会改变该串
rowsVersions.put(version.taskId(), version.latestRowAt()
.atZone(ZoneId.systemDefault()).toInstant().toEpochMilli()
+ "#" + (version.rowCount() == null ? 0L : version.rowCount()));
}
}
for (Long taskId : normalizedIds) {
FileTaskEntity task = taskMap.get(taskId);
if (task == null) {
@@ -69,6 +89,7 @@ public class TaskProgressLightAssembler {
item.setFileStatus(job == null ? null : job.getStatus());
item.setFileError(job == null ? null : job.getErrorMessage());
item.setUpdatedAt(task.getUpdatedAt() == null ? null : task.getUpdatedAt().toString());
item.setRowsVersion(rowsVersions.get(taskId));
vo.getItems().add(item);
}
return vo;
backend-java/src/main/java/com/nanri/aiimage/modules/withdraw/controller/WithdrawTaskController.java
+2 -2
View File
@@ -117,8 +117,8 @@ public class WithdrawTaskController {
@PostMapping("/tasks/progress/light")
@Operation(summary = "批量查询任务轻量进度（前端轮询专用）",
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt），"
+ "不查明细/result 行，响应体更小；旧 progress/batch 端点保留不动。")
description = "与 progress/batch 同输入，只返回轻量字段（taskId/status/statusCode/fileStatus/fileError/fileReady/updatedAt/rowsVersion），"
+ "不返回行明细内容（仅多一次结果行版本聚合查询），响应体更小；旧 progress/batch 端点保留不动。")
public ApiResponse<TaskProgressLightBatchVo> progressLight(@Valid @RequestBody TaskProgressLightRequest request) {
// 透传 userId：此前传 null = 不过滤归属，匿名遍历 taskId 即可读他人任务状态（2026-09 审查）
return ApiResponse.success(withdrawTaskService.progressLight(request.getTaskIds(), request.getUserId()));
backend-java/src/main/resources/db/V125__file_result_updated_at.sql
+29
View File
@@ -0,0 +1,29 @@
-- V125: biz_file_result 增加 updated_at 列（结果行最后变更时间）
--
-- 背景：前端「行数据按需拉取」需要「该任务的结果行是否变化」这一可靠信号——
-- progress/light 端点回传结果行版本，前端版本未变就不拉带行明细的重型 batch。
-- 该表原本只有 created_at：而**原地更新**（result_file_url / row_count / error_message 等，
-- 全项目 20+ 处 updateById）不会刷新任何时间戳，created_at 无法充当版本信号。
--
-- 列由数据库维护（DEFAULT CURRENT_TIMESTAMP + ON UPDATE CURRENT_TIMESTAMP）；
-- Java 侧 FileResultEntity.updatedAt 标注 insertStrategy=NEVER / updateStrategy=NEVER，
-- 保证 MyBatis-Plus 永不显式写它。这是必要的：MySQL 规则是「UPDATE 语句显式给某列赋值时不触发
-- 该列的自动更新」，而本项目写回模式多为 selectById → 改字段 → updateById（实体上带着旧值），
-- 不禁写就会把旧值写回去，版本信号随之失效。
--
-- 风险：ADD COLUMN 走 INSTANT/INPLACE，生产该表仅数百行，秒级完成；建议低峰执行。
-- 回滚：ALTER TABLE biz_file_result DROP COLUMN updated_at;
SET @db_name = DATABASE();
SET @col_exists := (
SELECT COUNT(*) FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = @db_name AND TABLE_NAME = 'biz_file_result' AND COLUMN_NAME = 'updated_at'
);
SET @sql := IF(@col_exists = 0,
'ALTER TABLE biz_file_result ADD COLUMN updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT ''最后变更时间'' AFTER created_at',
'SELECT 1'
);
PREPARE stmt FROM @sql;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;