后端(四面9分批次): 锁跳过留痕、状态词表收成单点、版本硬地板进 yml 并记账

- 14 处「拿不到锁就 continue」过去零日志,现统一带可聚合锚点并有留痕判据
  (LockSkipWitnessTest 7 例 + LockSkipSilentExitGuardrailTest 4 例)。
- 任务状态词表:散落内联集合改由单一定义点判方向(TaskStatusVocabularyRatchetTest 7 例),
  CANCELED/CANCELLED 只做归一映射,没改库值也没改对外契约。
- 版本硬地板三键(min-supported / enforce / rejectUnreported)此前在任何 yml 里 0 处=出厂即惰性;
  现在入册且 enforce=false 走记账模式(ClientVersionFloorConfigTest 9 例),真挡谁留给用户拍。
- 业务码→HTTP 状态只做映射单点 + 开关(默认关,开启前逐字节等价,BusinessErrorHttpStatusTest 8 例);
  直接翻面会让三个前端把业务失败读成网络挂了。
- 验收:mvn -o test 这 5 个类 35 例 0 红(用 python subprocess 起 mvn——bash 里 cmd 包一层
  开的是交互式 cmd,rc 是 cmd 的,会给出假的 rc=0)。
This commit is contained in:
2026-10-09 23:09:37 +08:00
parent 54cfb70a43
commit 15094309cf
63 changed files with 2454 additions and 95 deletions
@@ -0,0 +1,181 @@
package com.nanri.aiimage.common.task;
import java.util.List;
import java.util.Map;
import java.util.Set;
/**
* 任务状态词表的<b>唯一定义点</b>(2026-10-09 评审「流程 6.0」项 2:状态字面量集合散落 33 处/17 文件、没有单一状态机)。
*
* <p>先普查再说收口。2026-10-10 自己数出来的实际词表是 <b>4 套自有 + 1 套外部 + 若干模块内小状态机</b>,
* 不是一个"全局状态机"能覆盖的东西,所以这里按<b>表</b>分组,每组各留自己的口径:
* <ol>
* <li>{@link FileTask}:{@code biz_file_task.status},大写。12 个客户端模块共用这一张表;</li>
* <li>{@link BrandTask}:{@code brand_crawl_tasks.status},<b>小写</b>(该表历史写法就是小写);</li>
* <li>{@link Job}:{@code task_file_job.status},结果作业自己的四态;</li>
* <li>{@link LoopRun}:{@code price_track_loop_run.status},比上面三套多一个 {@code STOPPED};</li>
* <li>外部词表(Coze 工作流 {@code execute_status} 等,见
* {@code ImageVideoAsyncTaskService}):<b>不在这里定义</b>——那是别人家的返回值,
* 收进来等于假装我们能改上游。</li>
* </ol>
*
* <p><b>三条不动的边界</b>(这是本类存在的约束,不是待办):
* <ul>
* <li>不改库里已存的值:{@code COMPLETED}、{@code CANCELED}、小写 {@code cancelled} 都还在库里躺着;</li>
* <li>不改对外 API 的字符串契约:各模块接口原样回显 {@code FileTaskEntity#getStatus()},
* 老行返回 {@code CANCELED} 就继续返回 {@code CANCELED};</li>
* <li>不发明第三个词表:任务终态只有 {@code SUCCESS|COMPLETED|FAILED} 这一套口径,
* 其中 {@code COMPLETED ≡ SUCCESS}(2026-10-04 状态三态收敛已定,见
* {@code TaskCenterQueryMapper#SUCCESS_STATUSES_ORDERED}),别再往上添 {@code DONE}/{@code FINISHED}。</li>
* </ul>
*
* <p>判据在 {@code TaskStatusVocabularyRatchetTest}:新增内联状态集合字面量、新增写死的状态常量声明、
* 词表成员被改动都会红;现存例外按文件台账化。
*/
public final class TaskStatuses {
private TaskStatuses() {
}
/**
* 词表 1:{@code biz_file_task.status}(大写)。12 个客户端模块的公共状态面。
*
* <p>{@code ERROR} 与 {@code COMPLETED} 是历史值:{@code COMPLETED} 并入"成功"口径展示,
* {@code ERROR} 并入"失败"口径展示({@code TaskCenterQueryMapper} 的展开口径),
* 两者都不能从读侧集合里删——删了老行就在任务中心里凭空消失。
*/
public static final class FileTask {
public static final String PENDING = "PENDING";
public static final String RUNNING = "RUNNING";
public static final String SCHEDULED = "SCHEDULED";
public static final String SUCCESS = "SUCCESS";
/** {@code SUCCESS} 的历史拼写;展示上已并入成功,读侧必须继续认。 */
public static final String COMPLETED = "COMPLETED";
public static final String FAILED = "FAILED";
/** 失败口径的历史第二拼写(并入"失败"筛选项)。 */
public static final String ERROR = "ERROR";
public static final String CANCELLED = "CANCELLED";
/**
* {@code CANCELLED} 的历史脏值拼写。<b>当前 Java 代码从不写它</b>
* (实测:全树没有一处把 {@code CANCELED} 写进库),它只可能来自早期 jar/Python 侧留下的行,
* 所以只在读侧接受集合里出现,并由 SQL 的 {@code CASE WHEN} 归一后对外输出。
*/
public static final String CANCELED = "CANCELED";
/** 在跑口径(任务中心「执行中」筛选项与"卡住"判定的同一集合)。 */
public static final Set<String> ACTIVE = Set.of(PENDING, RUNNING, SCHEDULED);
/** {@link #ACTIVE} 的固定顺序版:展开成 SQL {@code IN} 列表时文本要可断言。 */
public static final List<String> ACTIVE_ORDERED = List.of(PENDING, RUNNING, SCHEDULED);
/** 终态集合(历史脏拼写 {@link #CANCELED} 也在内,少一个就有一行永远收不了尾)。 */
public static final Set<String> TERMINAL = Set.of(SUCCESS, FAILED, CANCELLED, CANCELED);
/** 「跑完了」的可数口径(各模块历史页 success/failed 计数用;不含 {@code CANCELED},是原口径,别顺手加宽)。 */
public static final List<String> FINISHED_ORDERED = List.of(SUCCESS, FAILED);
/** 前端「成功」筛选项的展开口径:{@code COMPLETED ≡ SUCCESS}。 */
public static final List<String> SUCCESS_VIEW_ORDERED = List.of(SUCCESS, COMPLETED);
/** 前端「失败」筛选项的展开口径:{@code ERROR} 与取消都按「没成功」并入失败。 */
public static final List<String> FAILED_VIEW_ORDERED = List.of(FAILED, ERROR, CANCELLED);
private FileTask() {
}
}
/**
* 词表 2:{@code brand_crawl_tasks.status}(小写)。这张表从建表起状态就是小写,
* 与 {@link FileTask} 不是一个字符集,混用会让 brand 任务在 UNION 口径里整批消失。
*/
public static final class BrandTask {
public static final String PENDING = "pending";
public static final String RUNNING = "running";
public static final String SUCCESS = "success";
public static final String FAILED = "failed";
/** brand 侧唯一的取消拼写就是这个小写;{@code canceled} 全树没有第二处写点。 */
public static final String CANCELLED = "cancelled";
public static final Set<String> ACTIVE = Set.of(PENDING, RUNNING);
public static final List<String> ACTIVE_ORDERED = List.of(PENDING, RUNNING);
public static final Set<String> TERMINAL = Set.of(SUCCESS, FAILED, CANCELLED);
public static final List<String> TERMINAL_ORDERED = List.of(CANCELLED, FAILED, SUCCESS);
private BrandTask() {
}
}
/** 词表 3:{@code task_file_job.status}——结果作业四态,比任务少一个取消态。 */
public static final class Job {
public static final String PENDING = "PENDING";
public static final String RUNNING = "RUNNING";
public static final String SUCCESS = "SUCCESS";
public static final String FAILED = "FAILED";
/** 在跑口径(作业还在等结果)。 */
public static final List<String> ACTIVE_ORDERED = List.of(PENDING, RUNNING);
/** 可重跑口径:待办 + 失败但没打满重试次数。全树有 6 处,都是这一对。 */
public static final List<String> RETRYABLE_ORDERED = List.of(PENDING, FAILED);
private Job() {
}
}
/** 词表 4:{@code price_track_loop_run.status}——轮次运行态,比 {@link FileTask} 多一个 {@code STOPPED}。 */
public static final class LoopRun {
public static final String RUNNING = "RUNNING";
public static final String SUCCESS = "SUCCESS";
public static final String FAILED = "FAILED";
public static final String STOPPED = "STOPPED";
/** 轮次终态(巡检按这一组判"这一轮不会再自己动了")。 */
public static final Set<String> TERMINAL = Set.of(SUCCESS, FAILED, STOPPED);
private LoopRun() {
}
}
/**
* 取消拼写的归一映射——<b>只用来判断,不用来改写值</b>:不改库、不改对外字符串。
* 键是"读到的原始值",值是"归一后的规范拼写"。
*
* <p>为什么只做取消这一对:实测全树只有 {@code CANCELED}/{@code CANCELLED} 存在同义双拼,
* 其余(SUCCESS/COMPLETED、ERROR/FAILED)是<b>并入展示口径</b>而不是拼写错误,
* 混进同一张归一表会把"历史值"洗成"错别字",后面就没人敢信库值了。
*/
public static final Map<String, String> CANCEL_SPELLINGS = Map.of(
"CANCELED", FileTask.CANCELLED,
"CANCELLED", FileTask.CANCELLED,
"canceled", BrandTask.CANCELLED,
"cancelled", BrandTask.CANCELLED);
/** 是不是"取消"这一族(两种拼写、大小写都认);用于判定,不用于改写。 */
public static boolean isCancelSpelling(String status) {
return status != null && CANCEL_SPELLINGS.containsKey(status);
}
/**
* 归一到规范拼写:两种取消拼写各归各家(大写值归 {@code CANCELLED}、小写值归 {@code cancelled}),
* <b>其它状态原样返回</b>。
*
* <p>刻意不做大小写统一:{@link FileTask} 是大写表、{@link BrandTask} 是小写表,
* 一刀切 upper/lower 会 cross 到对方词表里去。
*/
public static String canonicalizeCancel(String status) {
String mapped = status == null ? null : CANCEL_SPELLINGS.get(status);
return mapped == null ? status : mapped;
}
/**
* 大写词表的全部<b>去重后</b>取值(判据用它核对"没有第五套")。
*
* <p>注意这里必须是去重集合:{@code Job.PENDING} 与 {@code FileTask.PENDING} 是同一个字符串,
* 直接 {@code Set.of(全部常量)} 会在类初始化时抛 {@code duplicate element}——
* 这条判据 2026-10-10 就是这么被抓红的,留着当例子。
*/
public static Set<String> allUppercaseStatuses() {
return Set.copyOf(java.util.Arrays.asList(
FileTask.PENDING, FileTask.RUNNING, FileTask.SCHEDULED, FileTask.SUCCESS,
FileTask.COMPLETED, FileTask.FAILED, FileTask.ERROR, FileTask.CANCELLED,
FileTask.CANCELED, LoopRun.STOPPED));
}
}