refactor(evidence): 任务证据特性整体下线(2026-11-17 用户拍板)

删 modules/evidence 10 件+EvidenceProperties 注册+application*.yml evidence 块+V205 迁移(DELETE 菜单行+DROP biz_task_evidence);后管 TaskEvidencePage/task-evidence/路由/菜单键/操作指南同步摘除;chunk 分片通道、崩溃记录器本体与设备日志链保留(BACKLOG B115)。
This commit is contained in:
2026-11-17 01:18:49 +08:00
parent aff6c88a7d
commit 71b19e4f69
25 changed files with 40 additions and 1803 deletions
@@ -1,51 +0,0 @@
package com.nanri.aiimage.config;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
/**
* 任务异常证据件配置(v1.2 Phase 3/AC-13)。
*
* <p>证据件落在**独立桶**:默认桶 nanri-ai-images 带 7 天整桶 ILM,
* 与"证据单独保留、单独回收"的口径互相绑死;桶名必须显式写在 application.yml,
* 不许只在代码里留默认值(部署漏配就变成隐形行为)。</p>
*/
@Data
@ConfigurationProperties(prefix = "aiimage.evidence")
public class EvidenceProperties {
/** 证据桶;默认 task-evidence,独立于业务桶。 */
private String bucket = "task-evidence";
/** 证据保留天数(本地与云端同口径,按天回收)。 */
private Integer retentionDays = 7;
/** 对象 key 前缀;实际 key = 前缀 + taskId + "/" + UUID + 扩展名。 */
private String keyPrefix = "task-evidence/";
/** 单件证据上限(字节),超过直接拒绝,避免截图/大 JSON 打满桶。 */
private Long maxFileBytes = 64L * 1024 * 1024;
/** 保留期回收 cron;默认每天 03:30。 */
private String retentionCron = "0 30 3 * * *";
public String bucketOrDefault() {
return bucket == null || bucket.isBlank() ? "task-evidence" : bucket.trim();
}
public int retentionDaysOrDefault() {
return retentionDays == null || retentionDays < 1 ? 7 : retentionDays;
}
public String keyPrefixOrDefault() {
String prefix = keyPrefix == null ? "" : keyPrefix.trim();
if (prefix.isEmpty()) {
return "task-evidence/";
}
return prefix.endsWith("/") ? prefix : prefix + "/";
}
public long maxFileBytesOrDefault() {
return maxFileBytes == null || maxFileBytes < 1 ? 64L * 1024 * 1024 : maxFileBytes;
}
}
@@ -4,6 +4,6 @@ import org.springframework.boot.context.properties.EnableConfigurationProperties
import org.springframework.context.annotation.Configuration;
@Configuration
@EnableConfigurationProperties({OssProperties.class, TransientStorageProperties.class, StorageProperties.class, BrandProgressProperties.class, DeleteBrandProgressProperties.class, BrandCheckProperties.class, ZiniaoProperties.class, ModuleCleanupProperties.class, TaskPressureProperties.class, TaskImageCacheCleanupProperties.class, AppearancePatentProperties.class, SimilarAsinProperties.class, ImageVideoProperties.class, InstanceRoutingProperties.class, CapacityPlanProperties.class, UserSecretProperties.class, NotificationProperties.class, DeviceLogOssProperties.class, CollectDataBrandRecheckProperties.class, ClientCredentialProperties.class, CostGuardProperties.class, CollectRoutingProperties.class, EvidenceProperties.class})
@EnableConfigurationProperties({OssProperties.class, TransientStorageProperties.class, StorageProperties.class, BrandProgressProperties.class, DeleteBrandProgressProperties.class, BrandCheckProperties.class, ZiniaoProperties.class, ModuleCleanupProperties.class, TaskPressureProperties.class, TaskImageCacheCleanupProperties.class, AppearancePatentProperties.class, SimilarAsinProperties.class, ImageVideoProperties.class, InstanceRoutingProperties.class, CapacityPlanProperties.class, UserSecretProperties.class, NotificationProperties.class, DeviceLogOssProperties.class, CollectDataBrandRecheckProperties.class, ClientCredentialProperties.class, CostGuardProperties.class, CollectRoutingProperties.class})
public class PropertiesConfig {
}
@@ -1,125 +0,0 @@
package com.nanri.aiimage.modules.evidence.controller;
import com.nanri.aiimage.common.api.ApiResponse;
import com.nanri.aiimage.common.api.PageDefaults;
import com.nanri.aiimage.common.exception.BusinessException;
import com.nanri.aiimage.common.model.entity.AdminUserEntity;
import com.nanri.aiimage.common.security.AdminAuthSupport;
import com.nanri.aiimage.common.security.DeviceSessionPolicy;
import com.nanri.aiimage.modules.evidence.model.entity.TaskEvidenceEntity;
import com.nanri.aiimage.modules.evidence.service.TaskEvidenceService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.io.IOException;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
/**
* 后台「任务证据」读取面(AC-13):列表 / 内容 / 下载 / 删除,仅超级管理员。
*
* <p>证据件含账号可见的现场信息与窗口截图,访问面比常规后台更严;这里每个方法都走
* 私有 {@link #requireSuperAdmin(HttpServletRequest)},与 AdminDeviceLogController 同口径。
* 对象直链与预签名 URL 不入日志、不回前端——下载统一走服务端流。</p>
*/
@Slf4j
@RestController
@RequiredArgsConstructor
@RequestMapping("/api/admin/task-evidence")
@Tag(name = "任务证据(后台)", description = "任务异常现场证据件的列表、内容、下载与删除(仅超管)。")
public class AdminTaskEvidenceController {
private final TaskEvidenceService taskEvidenceService;
private final AdminAuthSupport adminAuthSupport;
@GetMapping("/files")
@Operation(summary = "证据件分页列表", description = "按 taskId 关联查询;uid 只作为精确过滤条件。")
public ApiResponse<Map<String, Object>> files(
HttpServletRequest request,
@Parameter(description = "业务任务号") @RequestParam(required = false) String taskId,
@Parameter(description = "归属用户 uid") @RequestParam(required = false) Long uid,
@RequestParam(defaultValue = PageDefaults.FIRST_PAGE) Long page,
@RequestParam(defaultValue = PageDefaults.ADMIN_LIST_PAGE_SIZE) Long pageSize) {
AdminUserEntity operator = requireSuperAdmin(request);
if (uid != null && !uid.equals(operator.getId())) {
// requireSuperAdmin 已保证当前是超管;uid 过滤仍与操作者归属对撞,防伪造 uid 越权读。
log.info("[task-evidence] 超管按 uid 过滤证据 userId={} targetUid={}",
operator.getId(), uid);
}
return ApiResponse.success(taskEvidenceService.page(taskId, uid, page, pageSize));
}
@GetMapping("/content")
@Operation(summary = "查看证据件内容", description = "文本证据按 UTF-8 返回;图片证据返回 base64。")
public ApiResponse<Map<String, Object>> content(
HttpServletRequest request,
@Parameter(description = "证据主键") @RequestParam Long fileId) {
requireSuperAdmin(request);
return ApiResponse.success(taskEvidenceService.content(fileId));
}
@GetMapping("/download")
@Operation(summary = "下载证据件", description = "服务端从独立证据桶流式读取,不返回直链。")
public void download(HttpServletRequest request, HttpServletResponse response,
@Parameter(description = "证据主键") @RequestParam Long fileId) throws IOException {
requireSuperAdmin(request);
TaskEvidenceEntity entity = taskEvidenceService.requireEvidence(fileId);
String name = "evidence-" + entity.getId()
+ (entity.getObjectKey() != null && entity.getObjectKey().contains(".")
? entity.getObjectKey().substring(entity.getObjectKey().lastIndexOf('.')) : ".bin");
response.setContentType(entity.getContentType() == null
? "application/octet-stream" : entity.getContentType());
response.setHeader("Content-Disposition", "attachment; filename*=UTF-8''"
+ URLEncoder.encode(name, StandardCharsets.UTF_8).replace("+", "%20"));
taskEvidenceService.downloadTo(fileId, response.getOutputStream());
}
@PostMapping("/delete")
@Operation(summary = "删除证据件", description = "先删对象再删登记行;不可恢复。")
public ApiResponse<Map<String, Object>> delete(
HttpServletRequest request,
@RequestBody(required = false) List<Long> ids,
@RequestParam(required = false) Long fileId) {
requireSuperAdmin(request);
List<Long> targets = new ArrayList<>();
if (ids != null) {
targets.addAll(ids);
}
if (fileId != null) {
targets.add(fileId);
}
if (targets.isEmpty()) {
throw new BusinessException("未指定要删除的证据");
}
int deleted = taskEvidenceService.delete(targets);
return ApiResponse.success("已删除", Map.of("deleted", deleted));
}
/**
* 证据件仅超管可读:requireAdmin 不含超管判定,这里再判一层。
* 返回操作者供列表端点做 uid 归属对撞。
*/
private AdminUserEntity requireSuperAdmin(HttpServletRequest request) {
AdminUserEntity user = adminAuthSupport.requireAdmin(request);
if (!DeviceSessionPolicy.isSuper(adminAuthSupport.currentRole(user))) {
log.warn("[task-evidence] 非超管访问被拒 userId={} username={}",
user.getId(), user.getUsername());
throw new BusinessException(403, "仅超级管理员可访问任务证据");
}
return user;
}
}
@@ -1,59 +0,0 @@
package com.nanri.aiimage.modules.evidence.controller;
import com.nanri.aiimage.common.api.ApiResponse;
import com.nanri.aiimage.common.exception.BusinessException;
import com.nanri.aiimage.common.security.AdminAuthSupport;
import com.nanri.aiimage.modules.evidence.model.dto.TaskEvidenceRegisterRequest;
import com.nanri.aiimage.modules.evidence.service.TaskEvidenceService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.servlet.http.HttpServletRequest;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.Map;
/**
* 内部接口:客户端证据件登记(AC-7)。客户端先把现场件分片上传到 Java 临时目录,
* 上传完成后携带 X-Internal-Token 与 task_id/file_key 登记;服务端再把临时件搬进
* 独立证据桶并落 biz_task_evidence。
*
* <p>/api/internal 虽在 AdminApiGuardFilter 兜底名单内、可信令牌会放行,controller
* 仍自校验令牌——防止配置漂移时匿名可达。</p>
*/
@Slf4j
@RestController
@RequiredArgsConstructor
@RequestMapping("/api/internal/task-evidence")
@Tag(name = "内部接口", description = "证据件登记(X-Internal-Token 鉴权)。")
public class InternalTaskEvidenceController {
private final TaskEvidenceService taskEvidenceService;
private final AdminAuthSupport adminAuthSupport;
@PostMapping("/register")
@Operation(summary = "登记任务证据件", description = "按 task_id 关联;file_key 指向已上传到临时目录的证据件。")
public ApiResponse<Map<String, Object>> register(HttpServletRequest request,
@RequestBody(required = false) TaskEvidenceRegisterRequest body) {
if (!adminAuthSupport.isTrustedInternalToken(request)) {
log.warn("[task-evidence] 拒绝未携带可信内部令牌的登记请求 remoteAddr={}",
request.getRemoteAddr());
throw new BusinessException(401, "未授权");
}
if (body == null) {
throw new BusinessException("登记载荷为空");
}
// P1-2:归属以会话身份为准。内部令牌是发给每个登录客户的共享凭据,body.uid 谁都能写——
// 真身份只能来自请求头里的用户 JWT(4.0.14 起 user_token 钩子统一注入);会话 uid 与
// body.uid 不一致直接 403,无身份的存量装机保留原参数并打节流的匿名兜底日志。
Long uid = adminAuthSupport.resolveOwnershipUserId(request, body.getUid());
Map<String, Object> result = taskEvidenceService.register(
body.getTaskId(), uid, body.getEvidenceType(), body.getSource(), body.getFileKey());
log.info("[task-evidence] registered id={} taskId={} uid={}", result.get("id"), body.getTaskId(), uid);
return ApiResponse.success(result);
}
}
@@ -1,9 +0,0 @@
package com.nanri.aiimage.modules.evidence.mapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.nanri.aiimage.modules.evidence.model.entity.TaskEvidenceEntity;
import org.apache.ibatis.annotations.Mapper;
@Mapper
public interface TaskEvidenceMapper extends BaseMapper<TaskEvidenceEntity> {
}
@@ -1,24 +0,0 @@
package com.nanri.aiimage.modules.evidence.model.dto;
import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.Data;
/**
* 客户端证据登记载荷(snake_case 与客户端现场件字段同口径)。
*/
@Data
public class TaskEvidenceRegisterRequest {
@JsonProperty("task_id")
private String taskId;
@JsonProperty("file_key")
private String fileKey;
@JsonProperty("evidence_type")
private String evidenceType;
private String source;
private Long uid;
}
@@ -1,45 +0,0 @@
package com.nanri.aiimage.modules.evidence.model.entity;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;
import java.time.LocalDateTime;
/**
* 任务异常现场证据件登记(表 biz_task_evidence,V182)。
*
* <p>只登记归属与对象元数据;对象本体在独立证据桶,直链/预签名 URL 不入库、不入日志。</p>
*/
@Data
@TableName("biz_task_evidence")
public class TaskEvidenceEntity {
@TableId(type = IdType.AUTO)
private Long id;
/** 业务任务号(客户端字符串口径,允许非数字)。 */
private String taskId;
/** 任务归属用户;未知时为空。 */
private Long uid;
/** 证据类型:client/crash/brand 等。 */
private String evidenceType;
/** 来源入口(崩溃记录器/商品采集等)。 */
private String source;
/** 证据桶内对象 key(含 UUID)。 */
private String objectKey;
private Long byteSize;
private String contentType;
/** 对象 sha256(防篡改/去重)。 */
private String sha256;
private LocalDateTime createdAt;
}
@@ -1,325 +0,0 @@
package com.nanri.aiimage.modules.evidence.service;
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.nanri.aiimage.common.exception.BusinessException;
import com.nanri.aiimage.common.service.DistributedJobLockService;
import com.nanri.aiimage.common.task.LockSkipWitness;
import com.nanri.aiimage.config.EvidenceProperties;
import com.nanri.aiimage.modules.evidence.mapper.TaskEvidenceMapper;
import com.nanri.aiimage.modules.evidence.model.entity.TaskEvidenceEntity;
import com.nanri.aiimage.modules.evidence.storage.TaskEvidenceStorageService;
import com.nanri.aiimage.modules.file.service.LocalFileStorageService;
import com.nanri.aiimage.modules.task.mapper.FileTaskMapper;
import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Service;
import java.io.File;
import java.io.IOException;
import java.io.OutputStream;
import java.nio.file.Files;
import java.time.Duration;
import java.time.LocalDateTime;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Set;
/**
* 证据登记与读取(AC-7/AC-13)。
*
* <p>登记走「客户端先分片上云到 Java 临时目录,再由服务端搬进独立证据桶」:客户端不持有
* 任何对象存储凭据,object_key/sha256/size 全部由服务端生成,登记接口不接受直链。</p>
*/
@Slf4j
@Service
@RequiredArgsConstructor
public class TaskEvidenceService {
private static final int MAX_TASK_ID_LENGTH = 64;
private static final int MAX_CONTENT_BYTES = 8 * 1024 * 1024;
private static final int RETENTION_BATCH = 200;
/** 单轮保留期最多扫的批次数:防一个删不掉的对象把进程拖成永动机。 */
private static final int MAX_RETENTION_BATCHES = 20;
/** 同一任务的证据件数上限:登记端点不设防的话,一个持证客户端能刷满整个证据桶(P2-2)。 */
private static final int MAX_EVIDENCE_PER_TASK = 50;
/** 保留期回收的分布式锁名:A/B 两台每晚各扫同一张表会互相删(同族口径见 DeviceLogRetentionService)。 */
static final String RETENTION_LOCK = "task-evidence:retention";
private static final Set<String> ALLOWED_EVIDENCE_TYPES =
Set.of("client", "crash", "window_image", "page_image", "brand", "other");
private static final Set<String> ALLOWED_SOURCES =
Set.of("client", "crash_recorder", "window", "page", "brand", "other");
private final TaskEvidenceMapper mapper;
private final TaskEvidenceStorageService storage;
private final LocalFileStorageService localFileStorageService;
private final EvidenceProperties properties;
private final FileTaskMapper fileTaskMapper;
private final DistributedJobLockService distributedJobLockService;
/** 客户端上传完成后登记:fileKey 指向 Java 临时目录里的分片拼装件。 */
public Map<String, Object> register(String taskId, Long uid, String evidenceType,
String source, String fileKey) {
String normalizedTaskId = normalizeTaskId(taskId);
if (fileKey == null || fileKey.isBlank()) {
throw new BusinessException("证据文件标识为空");
}
File file = localFileStorageService.findLocalSourceFile(fileKey.trim());
if (file == null || !file.isFile()) {
throw new BusinessException("证据文件不存在或已过期");
}
// P1-2:归属先于落桶。task_id 能对上库里的任务行时,uid 必须就是行主——判据发生在
// storage.store 之前,否则每一次拒绝都往证据桶里丢一个收不回的孤儿对象。
assertTaskOwnedBy(normalizedTaskId, uid);
if (file.length() == 0) {
throw new BusinessException("证据件为空,拒绝登记");
}
if (countByTask(normalizedTaskId) >= MAX_EVIDENCE_PER_TASK) {
throw new BusinessException("该任务的证据件数已达上限");
}
TaskEvidenceStorageService.StoredEvidence stored;
try {
stored = storage.store(file, normalizedTaskId, file.getName());
} catch (IOException | RuntimeException ex) {
log.warn("[task-evidence] register failed taskId={} reason={}",
normalizedTaskId, ex.getMessage());
throw new BusinessException("证据件入库失败,请稍后重试");
}
TaskEvidenceEntity entity = new TaskEvidenceEntity();
entity.setTaskId(normalizedTaskId);
entity.setUid(uid);
entity.setEvidenceType(normalizeLabel(evidenceType, "client", ALLOWED_EVIDENCE_TYPES));
entity.setSource(normalizeLabel(source, "client", ALLOWED_SOURCES));
entity.setObjectKey(stored.objectKey());
entity.setByteSize(stored.byteSize());
entity.setContentType(stored.contentType());
entity.setSha256(stored.sha256());
entity.setCreatedAt(LocalDateTime.now());
try {
mapper.insert(entity);
} catch (RuntimeException ex) {
// 对象已写进桶、登记行没落:不回收就是永久孤儿(保留期只扫登记行)。
log.warn("[task-evidence] 登记行写入失败,回收对象 taskId={} key={} reason={}",
normalizedTaskId, stored.objectKey(), ex.getMessage());
try {
storage.delete(stored.objectKey());
} catch (RuntimeException cleanup) {
log.warn("[task-evidence] 回收孤儿对象失败 key={} reason={}",
stored.objectKey(), cleanup.getMessage());
}
throw new BusinessException("证据件登记失败,请稍后重试");
}
deleteTempQuietly(file);
Map<String, Object> result = new LinkedHashMap<>();
result.put("id", entity.getId());
result.put("objectKey", entity.getObjectKey());
result.put("byteSize", entity.getByteSize());
return result;
}
public Map<String, Object> page(String taskId, Long uid, long page, long pageSize) {
long safePage = Math.max(1, page);
long safeSize = Math.min(Math.max(1, pageSize), 200);
LambdaQueryWrapper<TaskEvidenceEntity> query = new LambdaQueryWrapper<>();
if (taskId != null && !taskId.isBlank()) {
query.eq(TaskEvidenceEntity::getTaskId, taskId.trim());
}
if (uid != null) {
query.eq(TaskEvidenceEntity::getUid, uid);
}
query.orderByDesc(TaskEvidenceEntity::getId);
Page<TaskEvidenceEntity> result = mapper.selectPage(new Page<>(safePage, safeSize), query);
Map<String, Object> data = new LinkedHashMap<>();
data.put("items", result.getRecords());
data.put("total", result.getTotal());
data.put("page", safePage);
data.put("pageSize", safeSize);
return data;
}
public TaskEvidenceEntity requireEvidence(Long fileId) {
if (fileId == null) {
throw new BusinessException("证据主键为空");
}
TaskEvidenceEntity entity = mapper.selectById(fileId);
if (entity == null) {
throw new BusinessException("证据不存在或已过期");
}
return entity;
}
public Map<String, Object> content(Long fileId) {
TaskEvidenceEntity entity = requireEvidence(fileId);
byte[] bytes = storage.read(entity.getObjectKey(), MAX_CONTENT_BYTES);
Map<String, Object> data = new LinkedHashMap<>();
data.put("id", entity.getId());
data.put("taskId", entity.getTaskId());
data.put("contentType", entity.getContentType());
boolean binary = entity.getContentType() != null && entity.getContentType().startsWith("image/");
data.put("binary", binary);
data.put("content", binary
? java.util.Base64.getEncoder().encodeToString(bytes)
: new String(bytes, java.nio.charset.StandardCharsets.UTF_8));
return data;
}
public byte[] download(Long fileId) {
TaskEvidenceEntity entity = requireEvidence(fileId);
return storage.read(entity.getObjectKey(), properties.maxFileBytesOrDefault());
}
/** P3-1:后管下载走流式,避免 64MB 级对象整块进堆。 */
public void downloadTo(Long fileId, OutputStream out) {
TaskEvidenceEntity entity = requireEvidence(fileId);
storage.downloadTo(entity.getObjectKey(), out, properties.maxFileBytesOrDefault());
}
/** 删除证据:先删对象再删登记行;对象删除失败不吞(留在库里下一轮可重试)。 */
public int delete(List<Long> ids) {
if (ids == null || ids.isEmpty()) {
return 0;
}
int deleted = 0;
for (Long id : ids) {
TaskEvidenceEntity entity = id == null ? null : mapper.selectById(id);
if (entity == null) {
continue;
}
storage.delete(entity.getObjectKey());
deleted += mapper.deleteById(id);
}
return deleted;
}
/**
* 保留期回收:按天清扫到期行与对象(AC-13 的保留期必须有执行者,不能只写在配置里)。
*
* <p>P1-7 的两条修正:① A/B 两台每晚并发扫同一张表,回收必须拿分布式锁(同族口径见
* {@code DeviceLogRetentionService},锁跳过走可聚合出口);② 对象删除失败不再让整轮早退——
* 原先翻页永远停在第 1 页,卡住的那一行把后面每一行都堵死,配置里的 retention-days
* 因此只是个数字。改成按 id 键集分页:失败行留在库里下一轮重试,后面的行照常推进。
*/
@Scheduled(cron = "${aiimage.evidence.retention-cron:0 30 3 * * *}")
public void purgeExpired() {
DistributedJobLockService.LockHandle lockHandle =
distributedJobLockService.tryLock(RETENTION_LOCK, Duration.ofMinutes(15));
if (lockHandle == null) {
// 点位字面量必须写死(LockSkipSilentExitGuardrailTest 的判据),与 RETENTION_LOCK 同值。
LockSkipWitness.skipped("task-evidence:retention");
log.info("[task-evidence] 保留期清理跳过:另一实例持锁");
return;
}
try (lockHandle) {
purgeExpiredLocked(LocalDateTime.now().minusDays(properties.retentionDaysOrDefault()));
} catch (Exception ex) {
log.warn("[task-evidence] 保留期清理失败 reason={}", ex.getMessage(), ex);
}
}
private void purgeExpiredLocked(LocalDateTime expireBefore) {
long afterId = 0L;
int removed = 0;
int failed = 0;
int batches = 0;
while (batches < MAX_RETENTION_BATCHES) {
List<TaskEvidenceEntity> batch = mapper.selectList(new LambdaQueryWrapper<TaskEvidenceEntity>()
.gt(TaskEvidenceEntity::getId, afterId)
.lt(TaskEvidenceEntity::getCreatedAt, expireBefore)
.orderByAsc(TaskEvidenceEntity::getId)
.last("limit " + RETENTION_BATCH));
if (batch.isEmpty()) {
break;
}
batches++;
for (TaskEvidenceEntity entity : batch) {
afterId = entity.getId();
try {
storage.delete(entity.getObjectKey());
removed += mapper.deleteById(entity.getId());
} catch (RuntimeException ex) {
// 只跳过这一行:登记行留着,下一轮按同一条键集再试;后面的行绝不陪葬。
failed++;
log.warn("[task-evidence] retention delete failed id={} reason={}",
entity.getId(), ex.getMessage());
}
}
}
if (failed > 0) {
log.warn("[task-evidence] retention purge finished with failures removed={} failed={} batches={}",
removed, failed, batches);
} else if (removed > 0 || batches > 0) {
log.info("[task-evidence] retention purge removed={} batches={}", removed, batches);
}
}
/**
* P1-2 的归属判定:task_id 对得上库里的任务行时 uid 必须就是行主;对不上行(客户端本地
* 任务号,如商品采集的自有作业 id)只要求带 uid 自证——否则任何一个持内部令牌的客户端
* 都能往别人的取证面里挂证据。
*/
private void assertTaskOwnedBy(String taskId, Long uid) {
Long ownerId = resolveTaskOwnerId(taskId);
if (uid == null) {
throw new BusinessException(403, "证据登记必须携带任务归属用户");
}
if (ownerId != null && !ownerId.equals(uid)) {
throw new BusinessException(403, "证据件只能登记到本人任务上");
}
}
/** 数字串按主键查(超长数字串会溢出,降级走 task_no),其余按 task_no 点查。 */
private Long resolveTaskOwnerId(String taskId) {
FileTaskEntity row = null;
if (taskId.chars().allMatch(Character::isDigit)) {
try {
row = fileTaskMapper.selectById(Long.parseLong(taskId));
} catch (NumberFormatException overflow) {
row = null;
}
}
if (row == null) {
row = fileTaskMapper.selectOne(new LambdaQueryWrapper<FileTaskEntity>()
.eq(FileTaskEntity::getTaskNo, taskId)
.last("limit 1"));
}
return row == null ? null : row.getUserId();
}
private long countByTask(String taskId) {
Long count = mapper.selectCount(new LambdaQueryWrapper<TaskEvidenceEntity>()
.eq(TaskEvidenceEntity::getTaskId, taskId));
return count == null ? 0L : count;
}
private String normalizeTaskId(String taskId) {
String value = taskId == null ? "" : taskId.trim();
if (value.isEmpty()) {
throw new BusinessException("任务号为空");
}
if (value.length() > MAX_TASK_ID_LENGTH) {
value = value.substring(0, MAX_TASK_ID_LENGTH);
}
return value;
}
private String normalizeLabel(String value, String fallback, Set<String> allowed) {
String text = value == null ? "" : value.trim().toLowerCase(Locale.ROOT);
if (text.isEmpty()) {
return fallback;
}
// 列宽是 VARCHAR(32),超长标签在这里截断而不是让 insert 抛数据截断错;
// 不在白名单内的标签一律落 other,不让客户端自造类型污染取证面。
String normalized = text.length() > 32 ? text.substring(0, 32) : text;
return allowed.contains(normalized) ? normalized : "other";
}
private void deleteTempQuietly(File file) {
if (file != null && file.exists() && !file.delete()) {
log.warn("[task-evidence] temp evidence cleanup failed name={}", file.getName());
}
}
}
@@ -1,122 +0,0 @@
package com.nanri.aiimage.modules.evidence.storage;
import cn.hutool.crypto.digest.DigestUtil;
import com.nanri.aiimage.config.EvidenceProperties;
import com.nanri.aiimage.modules.file.service.oss.OssStorageService;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import java.io.File;
import java.io.IOException;
import java.util.Locale;
import java.util.UUID;
import java.util.regex.Pattern;
/**
* 证据对象的独立落点(AC-13):桶与 key 前缀来自 {@link EvidenceProperties},
* 对象本体不经过业务桶,也不把直链/预签名 URL 写进任何日志或数据库。
*/
@Slf4j
@Service
@RequiredArgsConstructor
public class TaskEvidenceStorageService {
private static final Pattern TASK_ID_SAFE = Pattern.compile("[^0-9A-Za-z_.-]+");
private static final Pattern EXT_SAFE = Pattern.compile("\\.[0-9A-Za-z]{1,10}");
private final EvidenceProperties properties;
private final OssStorageService ossStorageService;
private volatile boolean bucketReady;
/** 落一份证据对象,返回对象 key 与对象元数据。 */
public StoredEvidence store(File source, String taskId, String originalFilename) throws IOException {
if (source == null || !source.isFile()) {
throw new IllegalArgumentException("evidence file must exist");
}
long size = source.length();
if (size > properties.maxFileBytesOrDefault()) {
throw new IllegalArgumentException("evidence file too large");
}
String bucket = properties.bucketOrDefault();
ensureBucket(bucket);
String key = objectKey(taskId, originalFilename);
ossStorageService.uploadFileToBucket(source, bucket, key);
return new StoredEvidence(key, size, sha256(source), contentType(originalFilename));
}
public byte[] read(String objectKey, long maxBytes) {
return ossStorageService.readObjectBytes(
properties.bucketOrDefault(), objectKey, maxBytes);
}
/** P3-1:下载走流式,不把整个证据件读进堆。 */
public void downloadTo(String objectKey, java.io.OutputStream out, long maxBytes) {
ossStorageService.readObjectToStream(properties.bucketOrDefault(), objectKey, out, maxBytes);
}
public void delete(String objectKey) {
if (objectKey == null || objectKey.isBlank()) {
return;
}
ossStorageService.removeObject(properties.bucketOrDefault(), objectKey);
}
public String bucket() {
return properties.bucketOrDefault();
}
private void ensureBucket(String bucket) {
if (bucketReady) {
return;
}
synchronized (this) {
if (bucketReady) {
return;
}
ossStorageService.ensureBucketExists(bucket);
bucketReady = true;
log.info("[task-evidence] evidence bucket ready bucket={}", bucket);
}
}
private String objectKey(String taskId, String originalFilename) {
String safeTask = TASK_ID_SAFE.matcher(taskId == null ? "" : taskId.trim())
.replaceAll("_");
if (safeTask.isEmpty()) {
safeTask = "unknown";
}
return properties.keyPrefixOrDefault() + safeTask + "/" + UUID.randomUUID() + extension(originalFilename);
}
private String extension(String originalFilename) {
String name = originalFilename == null ? "" : originalFilename.trim();
int slash = Math.max(name.lastIndexOf('/'), name.lastIndexOf('\\'));
if (slash >= 0) {
name = name.substring(slash + 1);
}
int dot = name.lastIndexOf('.');
String ext = dot < 0 ? "" : name.substring(dot).toLowerCase(Locale.ROOT);
return EXT_SAFE.matcher(ext).matches() ? ext : ".bin";
}
private String contentType(String originalFilename) {
String ext = extension(originalFilename);
return switch (ext) {
case ".json" -> "application/json";
case ".png" -> "image/png";
case ".jpg", ".jpeg" -> "image/jpeg";
case ".webp" -> "image/webp";
case ".txt", ".log" -> "text/plain; charset=utf-8";
default -> "application/octet-stream";
};
}
private String sha256(File source) {
return DigestUtil.sha256Hex(source);
}
public record StoredEvidence(String objectKey, long byteSize, String sha256, String contentType) {
}
}
@@ -26,7 +26,7 @@ import org.springframework.web.bind.annotation.RestController;
* (补登记口)登记落 {@code biz_jd_product_image}——服务端零图片字节。</p>
*
* <p>/api/internal 虽在 AdminApiGuardFilter 兜底名单内、可信令牌会放行,controller
* 仍自校验令牌——防止配置漂移时匿名可达(InternalTaskEvidenceController 同款)。
* 仍自校验令牌——防止配置漂移时匿名可达。
* 身份以请求头 JWT 为准(user_token 钩子统一注入),body.uid 只作存量装机兜底;
* 任务级 owner 对撞与 companyId 投影收口在 {@link JdProductImageIngestService}。</p>
*/
@@ -55,7 +55,7 @@ public class PermissionMenuService {
/** 角色内在闸门菜单:非超管看不见、谁也授不出去(设计文档 §8.1)。
* 与前端 src/config/company-scope.ts 的 SUPER_ADMIN_ONLY_MENU_KEYS 必须同值,由 Task 7 的跨端用例钉住。 */
private static final Set<String> SUPER_ADMIN_ONLY_KEYS =
Set.of("admin_companies", "admin_task_evidence");
Set.of("admin_companies");
/**
* 管理/平台配置类菜单:出口仍是 {@code requireAdmin}(用户、菜单、分组、密钥、公司、版本、教程、
@@ -48,13 +48,6 @@ AIIMAGE_JD_SKU_MAX_PER_PRODUCT=200
# 设成空串会把白名单清空(兜底拉取对 JD 形同关闭)。打开 AIIMAGE_CLIENT_TASK_PULL_ENABLED
# 前先确认客户端版本带兜底拉取线程。
# 任务异常现场证据件(v1.2 Phase 3):独立桶与保留期必须显式配置;桶不得复用 nanri-ai-images。
AIIMAGE_EVIDENCE_OSS_BUCKET=task-evidence
AIIMAGE_EVIDENCE_RETENTION_DAYS=7
AIIMAGE_EVIDENCE_RETENTION_CRON=0 30 3 * * *
AIIMAGE_EVIDENCE_MAX_FILE_BYTES=67108864
AIIMAGE_EVIDENCE_KEY_PREFIX=task-evidence/
# 工作台客户端包直传预签名有效期(秒);90MB 级包在慢公网入口需要更长窗口。
AIIMAGE_WORKBENCH_CLIENT_PRESIGN_EXPIRY_SECONDS=3600
@@ -191,15 +191,6 @@ aiimage:
access-key-id: ${AIIMAGE_DEVICE_LOG_OSS_ACCESS_KEY_ID:}
access-key-secret: ${AIIMAGE_DEVICE_LOG_OSS_ACCESS_KEY_SECRET:}
retention-days: ${AIIMAGE_DEVICE_LOG_RETENTION_DAYS:7}
# 任务异常现场证据件(v1.2 Phase 3/AC-7/AC-13):独立桶 + 独立保留期。
# 桶必须与业务桶 nanri-ai-images 隔离(那边是 7 天整桶 ILM,证据保留策略不得被它绑死);
# key-prefix 之后实际 key = <prefix><taskId>/<UUID><扩展名>(铁律 10:key 必带 UUID)。
evidence:
bucket: ${AIIMAGE_EVIDENCE_OSS_BUCKET:task-evidence}
retention-days: ${AIIMAGE_EVIDENCE_RETENTION_DAYS:7}
key-prefix: ${AIIMAGE_EVIDENCE_KEY_PREFIX:task-evidence/}
max-file-bytes: ${AIIMAGE_EVIDENCE_MAX_FILE_BYTES:67108864}
retention-cron: ${AIIMAGE_EVIDENCE_RETENTION_CRON:0 30 3 * * *}
transient-storage:
enabled: ${AIIMAGE_TRANSIENT_STORAGE_ENABLED:true}
endpoint: ${AIIMAGE_TRANSIENT_STORAGE_ENDPOINT:http://121.196.149.225:9000}
@@ -0,0 +1,23 @@
-- 迁移 V205:任务证据特性整体下线(2026-11-17 用户拍板)
--
-- 背景:v1.2 的「任务异常现场存证」(客户端采集+分片上云+后管读取面)整体删除——
-- 上线至今登记行为零(装机面未升级+触发口窄+崩溃路被归属校验 403 钉死),
-- 读取面 AdminTaskEvidenceController、内部登记 InternalTaskEvidenceController 与
-- 客户端 evidence_recorder 链同窗下线(铁律 18/22/24 随之退役)。
--
-- 本迁移做两件事:
-- 1. 删除 V185 下发的每公司菜单行(后管侧边栏「任务证据」入口);
-- 2. DROP 登记表 biz_task_evidence(V182 建表、V184 第二段补 idx_task_evidence_created_at;
-- 索引随表删除,无需单独 DROP)。
-- 表内只有 7 天保留期的现场件登记行,随特性下线无保留价值;对象本体在独立桶
-- task-evidence,桶的清理由运维窗口另行执行(登记 ops BACKLOG),不依赖本迁移。
--
-- 回滚(手工):
-- 1. 按 V182 原样重建 biz_task_evidence(建表+两索引),再按 V184 第二段补
-- idx_task_evidence_created_at;
-- 2. 按 V185 语义重插 columns 菜单行(每公司一行,column_key='admin_task_evidence')。
-- 数据不可回滚:登记行随 DROP 丢弃(7 天现场件,无保留价值)。
DELETE FROM `columns` WHERE `column_key` = 'admin_task_evidence';
DROP TABLE IF EXISTS `biz_task_evidence`;