task-178: 日志字段规范落地（StructuredLog 规范字段集+缺失占位+值消毒，字段名冻结）+ 8 条测试

- 规范字段 traceId/taskId/moduleType/stage/submissionId/chunkIndex/chunkTotal/jobId/result/errorType，顺序与 spec11 §2 一致 - format 只输出规范字段、缺失用 "-" 占位、换行/控制字符消毒、超长截断，防日志注入与字段漂移 - 源码锚点断言 Worker(task-file-job)/心跳(task-heartbeat) 代表性日志已带 taskId/moduleType 核心字段；不删现有日志
2026-09-04 23:37:50 +08:00
parent 05da03c5ba
commit 620ee15a48
2 changed files with 173 additions and 0 deletions
@@ -0,0 +1,101 @@
+package com.nanri.aiimage.config;
+
+import org.junit.jupiter.api.Test;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * task-178：日志字段规范落地契约（spec 11 §2）。
+ *
+ * 规范字段集与缺失占位固化：StructuredLog 只输出规范字段、顺序固定、缺失用 "-" 占位、
+ * 值消毒（换行/控制字符、超长截断）。并用源码锚点断言代表性日志（task-file-job Worker /
+ * task-heartbeat）已携带 taskId/moduleType 等核心字段（不删现有日志）。
+ */
+class StructuredLogFieldSpecTest {
+
+    @Test
+    void canonicalFieldNamesFrozenInSpecOrder() {
+        assertEquals(List.of("traceId", "taskId", "moduleType", "stage",
+                "submissionId", "chunkIndex", "chunkTotal", "jobId", "result", "errorType"),
+                StructuredLog.FIELD_NAMES, "字段名与顺序应冻结，勿漂移");
+    }
+
+    @Test
+    void missingFieldsRenderedWithPlaceholder() {
+        String out = StructuredLog.format(Map.of());
+        assertTrue(out.contains("taskId=-"), "缺失字段应占位，实际: " + out);
+        assertTrue(out.contains("moduleType=-"));
+        assertTrue(out.contains("stage=-"));
+        assertTrue(out.contains("jobId=-"));
+    }
+
+    @Test
+    void partialFieldsKeepCanonicalKeysAndSkipUnknown() {
+        String out = StructuredLog.format(Map.of("taskId", 7L, "jobId", 9L, "unknownField", "x"));
+        assertTrue(out.contains("taskId=7"), "实际: " + out);
+        assertTrue(out.contains("jobId=9"));
+        assertFalse(out.contains("unknownField"), "不应输出非规范字段: " + out);
+        assertTrue(out.contains("stage=-"));
+        assertTrue(out.contains("result=-"));
+        assertTrue(out.contains("errorType=-"));
+    }
+
+    @Test
+    void controlCharsAndNewlineSanitized() {
+        String value = StructuredLog.field("a\nb=1\r");
+        assertFalse(value.contains("\n"), "值内不应出现换行: " + value);
+        assertFalse(value.contains("\r"));
+        assertFalse(value.chars().anyMatch(c -> c < 0x20 && c != ' '), "不应含控制字符");
+        assertTrue(value.contains("b=1"), "普通内容应保留: " + value);
+    }
+
+    @Test
+    void nullEmptyWhitespaceNormalizedToPlaceholder() {
+        assertEquals(StructuredLog.MISSING, StructuredLog.field(null));
+        assertEquals(StructuredLog.MISSING, StructuredLog.field(""));
+        assertEquals(StructuredLog.MISSING, StructuredLog.field("   "));
+    }
+
+    @Test
+    void overlongValueTruncated() {
+        String longValue = "x".repeat(1000);
+        assertEquals(StructuredLog.MAX_VALUE_LENGTH, StructuredLog.field(longValue).length());
+    }
+
+    @Test
+    void workerLogLinesCarryTaskAndModuleFields() throws IOException {
+        String source = readSource("src/main/java/com/nanri/aiimage/modules/task/service/TaskResultFileJobWorker.java");
+        List<String> perJobLines = source.lines()
+                .filter(line -> line.contains("[task-file-job]") && line.contains("jobId="))
+                .toList();
+        assertFalse(perJobLines.isEmpty(), "Worker 应存在按 job 的日志行");
+        for (String line : perJobLines) {
+            assertTrue(line.contains("taskId="), "job 级日志应带 taskId: " + line.trim());
+            assertTrue(line.contains("moduleType="), "job 级日志应带 moduleType: " + line.trim());
+        }
+    }
+
+    @Test
+    void heartbeatLogLinesCarryTaskField() throws IOException {
+        String source = readSource("src/main/java/com/nanri/aiimage/modules/task/service/TaskHeartbeatService.java");
+        List<String> lines = source.lines()
+                .filter(line -> line.contains("[task-heartbeat]") && line.contains("log."))
+                .toList();
+        assertFalse(lines.isEmpty(), "心跳服务应存在日志行");
+        for (String line : lines) {
+            assertTrue(line.contains("taskId="), "心跳日志应带 taskId: " + line.trim());
+        }
+    }
+
+    private static String readSource(String relative) throws IOException {
+        return Files.readString(Path.of(System.getProperty("user.dir"), relative));
+    }
+}