From a94e59d434de7174f4fda16e73d6a83f29e467a3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=BB=84=E8=87=AA=E8=BE=BE?= <980324341@qq.com>
Date: Tue, 10 Nov 2026 00:47:25 +0800
Subject: [PATCH] =?UTF-8?q?test(phase-0):=20=E7=A1=AE=E8=AE=A4=E5=9F=BA?=
=?UTF-8?q?=E7=BA=BF=E5=85=A8=E7=BB=BF=E5=B9=B6=E9=A2=84=E7=BD=AE=E8=BF=AD?=
=?UTF-8?q?=E4=BB=A3=E9=AA=8C=E6=94=B6=E6=B5=8B=E8=AF=95=E5=A5=91=E7=BA=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
.../appearance-patent-clean-filter.test.ts | 20 ++
.../appearance-patent-clean-page.test.ts | 61 +++++
...earancePatentCleanItemsControllerTest.java | 159 +++++++++++++
.../AppearancePatentCleanSyncTest.java | 129 ++++++++++
.../AppearancePatentChunkRowContractTest.java | 222 ++++++++++++++++++
5 files changed, 591 insertions(+)
create mode 100644 admin-frontend-vue/tests/appearance-patent-clean-filter.test.ts
create mode 100644 admin-frontend-vue/tests/mount/appearance-patent-clean-page.test.ts
create mode 100644 backend-java/src/test/java/com/nanri/aiimage/modules/appearancepatent/controller/AdminAppearancePatentCleanItemsControllerTest.java
create mode 100644 backend-java/src/test/java/com/nanri/aiimage/modules/appearancepatent/service/AppearancePatentCleanSyncTest.java
create mode 100644 backend-java/src/test/java/com/nanri/aiimage/modules/appearancepatent/service/support/AppearancePatentChunkRowContractTest.java
diff --git a/admin-frontend-vue/tests/appearance-patent-clean-filter.test.ts b/admin-frontend-vue/tests/appearance-patent-clean-filter.test.ts
new file mode 100644
index 000000000..a1c615fef
--- /dev/null
+++ b/admin-frontend-vue/tests/appearance-patent-clean-filter.test.ts
@@ -0,0 +1,20 @@
+/**
+ * 外观专利无侵权数据页筛选纯函数(v1.3 AC-5)—— Pending Phase 3。
+ *
+ * Phase 3 组 B 落 `src/pages/patent/appearance-patent-clean-filter.ts`(照 dedupe-total-filter.ts
+ * 拆分:createAppearancePatentCleanFilterState / appearancePatentCleanFilterActive /
+ * toAppearancePatentCleanListParams)后,把下面两条 todo 转成真用例并移除 todo 标记:
+ *
+ * 1. **snake 参数形状**:toAppearancePatentCleanListParams({...}) 产出
+ * `page`/`page_size`(默认 10、上限 100)、`task_id`、`asin`、`country`、
+ * `start_date`/`end_date`(ISO yyyy-MM-dd;空白不下发)——与后端 §3.2 参数归一逐字对撞;
+ * 2. **分页钳制**(铁律 15):page < 1 归 1;page_size 上限 100;
+ * `(page-1)*page_size` 溢出边界样本(page 极大值不得把乘积顶成负数/溢出)。
+ *
+ * 跑法:`node --test tests/appearance-patent-clean-filter.test.ts`(node --test 只收顶层
+ * `tests/*.test.ts`,不递归;纯函数零依赖可直测)
+ */
+import { test } from 'node:test'
+
+test.todo('Pending Phase 3: AC-5 筛选参数——snake page/page_size/task_id/asin/country/start_date/end_date 形状')
+test.todo('Pending Phase 3: AC-5 筛选参数——page 钳制防 (page-1)*page_size 溢出(铁律 15)')
diff --git a/admin-frontend-vue/tests/mount/appearance-patent-clean-page.test.ts b/admin-frontend-vue/tests/mount/appearance-patent-clean-page.test.ts
new file mode 100644
index 000000000..85710082b
--- /dev/null
+++ b/admin-frontend-vue/tests/mount/appearance-patent-clean-page.test.ts
@@ -0,0 +1,61 @@
+/**
+ * 外观专利无侵权数据页(v1.3 AC-5)的挂载契约 —— Pending Phase 3。
+ *
+ * 用户拍板(2026-11-10):展示形式参照「去重数据库」页(DedupeRegistryPage 形态:自绘
+ * `
` 行列表 + `OldPagination.vue` 分页,**不做卡片宫格**);`companyScoped: true`
+ * 公司 Tab;任务号/ASIN/国家/起止时间筛选;`page`/`page_size` snake 参数,响应
+ * `{items, total, page, pageSize}`。默认仅 super_admin 可见(菜单不预授权,判据在后端
+ * AdminAppearancePatentCleanItemsControllerTest 的菜单迁移支,这里只管前端接线)。
+ *
+ * Phase 0 预置的判据(接缝名是判据的一部分,Phase 3 微调必须同步改本文件并登记蓝图 §5):
+ * ① 页面组件落位 `src/pages/patent/AppearancePatentCleanItemsPage.vue`,且确实是
+ * 自绘 table + OldPagination 的分页列表(不是卡片宫格);
+ * ② routes.ts 注册 `patent-center/clean-items`(menuKey `admin_appearance_patent_clean_items`,
+ * companyScoped: true),COMPANY_SCOPED_PAGES 同步登记(company-tab-wiring 护栏随注册自动覆盖);
+ * ③ 挂载行为样本(激活时补齐):mock api 模块 → mount → 翻页/改每页条数、切公司 Tab 重取、
+ * 任务号/ASIN/国家/起止时间筛选生效、空态与加载失败条。
+ *
+ * 跑法:`npx vitest run tests/mount/appearance-patent-clean-page.test.ts`
+ */
+import { readFileSync } from 'node:fs'
+import { fileURLToPath, URL } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+import { adminPages } from '@/router/routes'
+import { COMPANY_SCOPED_PAGES } from '@/config/company-scope'
+
+const PAGE_PATH = 'src/pages/patent/AppearancePatentCleanItemsPage.vue'
+const MENU_KEY = 'admin_appearance_patent_clean_items'
+
+describe.skip('Pending Phase 3: AC-5 外观专利无侵权数据页(分页列表,参照去重数据库页)', () => {
+ it('页面组件落位且是自绘 table + OldPagination 的分页列表', () => {
+ const src = readFileSync(fileURLToPath(new URL(`../../${PAGE_PATH}`, import.meta.url)), 'utf-8')
+ expect(src).toContain('OldPagination')
+ expect(src).toContain(' {
+ const page = adminPages.find((p) => p.path === 'patent-center/clean-items')
+ expect(page).toBeTruthy()
+ expect(page?.menuKey).toBe(MENU_KEY)
+ expect(page?.title).toBe('外观专利无侵权数据')
+ expect(page?.companyScoped).toBe(true)
+ const scoped = COMPANY_SCOPED_PAGES.find((p) => p.menuKey === MENU_KEY)
+ expect(scoped).toBeTruthy()
+ expect(scoped?.pageFiles).toContain(PAGE_PATH)
+ })
+
+ it('挂载后走 snake 分页参数且切公司 Tab 重取(激活时用真组件挂载补齐)', async () => {
+ // 页面组件 Phase 3 才落盘,vite 的 import-analysis 会在收集期解析动态导入 ⇒
+ // 这里必须用运行期字符串 + @vite-ignore 推迟解析;skip 期间永不执行。
+ const pageModule = '@/pages/patent/AppearancePatentCleanItemsPage.vue'
+ // 激活时补齐:vi.mock('@/pages/patent/appearance-patent-clean-api.ts') →
+ // const { default: Page } = await import(pageModule)
+ // mount(Page, { global: { plugins: [createPinia()] } }) →
+ // 断言首次请求 query 的 page/page_size(snake)与 {items,total,page,pageSize} 解包;
+ // 改每页条数/翻页重发;companyTab.activeId 变化触发重取(护栏 company-tab-wiring 同口径)。
+ const { default: Page } = await import(/* @vite-ignore */ pageModule)
+ expect(Page).toBeTruthy()
+ })
+})
diff --git a/backend-java/src/test/java/com/nanri/aiimage/modules/appearancepatent/controller/AdminAppearancePatentCleanItemsControllerTest.java b/backend-java/src/test/java/com/nanri/aiimage/modules/appearancepatent/controller/AdminAppearancePatentCleanItemsControllerTest.java
new file mode 100644
index 000000000..b8af8fc56
--- /dev/null
+++ b/backend-java/src/test/java/com/nanri/aiimage/modules/appearancepatent/controller/AdminAppearancePatentCleanItemsControllerTest.java
@@ -0,0 +1,159 @@
+package com.nanri.aiimage.modules.appearancepatent.controller;
+
+import org.junit.jupiter.api.Disabled;
+import org.junit.jupiter.api.Test;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.stream.Stream;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * AC-4/AC-6/AC-7(v1.3 R2/R4/R5):后管「外观专利无侵权数据」只读查询接口与菜单可见性。
+ *
+ * Pending Phase 3 激活。Phase 0 预置的是接缝判据(接缝名是判据的一部分,Phase 3 微调命名
+ * 必须同步改本文件并在蓝图 §5 登记);激活时除本清单外,再补真实对象的行为样本:
+ *
+ *
+ * - AC-4:公司隔离——超管显式传 company_id 收窄、不传全量;非超管强制本公司(忽略请求
+ * 传参);无凭据/坏凭据按业务码拒绝(200 信封形状;判据认业务码/拒绝文案,不认 HTTP 码,B80-03);
+ * - AC-6:默认仅 super_admin 可见可访问(V21 形状:菜单注册不预授权);被授权角色放行;
+ * page 钳制防 {@code (page-1)*page_size} 溢出(铁律 15);
+ * - AC-7:删除前台任务/历史结果后,后管同步记录仍可查(独立保留)。
+ *
+ */
+@Disabled("Pending Phase 3: AC-4/AC-6/AC-7 后管只读查询接口与菜单可见性(激活时移除本注解)")
+class AdminAppearancePatentCleanItemsControllerTest {
+
+ private static final Path MODULE = Path.of("").toAbsolutePath();
+ private static final Path MAIN = MODULE.resolve("src/main/java/com/nanri/aiimage");
+ private static final Path DB_DIR = MODULE.resolve("src/main/resources/db");
+ private static final Path CONTROLLER =
+ MAIN.resolve("modules/appearancepatent/controller/AdminAppearancePatentCleanItemsController.java");
+ private static final Path MAPPER =
+ MAIN.resolve("modules/appearancepatent/mapper/AppearancePatentCleanItemMapper.java");
+ private static final Path MENU_MIGRATION = DB_DIR.resolve("V190__appearance_patent_clean_menu.sql");
+ private static final String COLUMN_KEY = "admin_appearance_patent_clean_items";
+ private static final String ROUTE_PATH = "patent-center/clean-items";
+
+ @Test
+ void 控制器与只读端点就位() throws IOException {
+ assertTrue(Files.exists(CONTROLLER),
+ "控制器必须落在 " + CONTROLLER + "(蓝图 §2.1 Level 3)");
+ String source = stripComments(Files.readString(CONTROLLER));
+ assertTrue(source.contains("/api/admin/appearance-patent-clean-items"),
+ "端点必须是 GET /api/admin/appearance-patent-clean-items(蓝图 §3.2)");
+ assertTrue(source.contains("@GetMapping"), "查询端点必须落在 @GetMapping");
+ assertFalse(source.contains("@PostMapping") || source.contains("@PutMapping")
+ || source.contains("@DeleteMapping"),
+ "本页只读、无写/删接口(蓝图 §3.2;后管要下载走既有结果直链/任务中心)");
+ }
+
+ @Test
+ void 鉴权闸照去重页私有require形状() throws IOException {
+ String source = stripComments(Files.readString(CONTROLLER));
+ for (String seam : List.of("requireUser", "X-Internal-Token", "isSuper",
+ "getUserColumnPermissions", COLUMN_KEY, ROUTE_PATH, "requireCleanItemsAccess")) {
+ assertTrue(source.contains(seam), "鉴权闸缺接缝 " + seam
+ + "——照 DedupeTotalDataController 私有 requireXxxAccess 形状(JWT→内部令牌回退→超管放行→菜单双匹配)");
+ }
+ assertTrue(source.contains("columnKey") && (source.contains("getRoutePath")),
+ "菜单权限必须 column_key/route_path 双匹配(AC-6:默认不命中即拒)");
+ }
+
+ @Test
+ void 公司隔离走superAdminScopedCompanyId() throws IOException {
+ String source = stripComments(Files.readString(CONTROLLER));
+ assertTrue(source.contains("DataReadScope"), "公司隔离唯一出口是 DataReadScope(蓝图 §2.1 Level 0)");
+ assertTrue(source.contains("superAdminScopedCompanyId"),
+ "读侧必须走 superAdminScopedCompanyId:超管显式传才收窄,非超管强制本公司(AC-4,同去重页口径)");
+ }
+
+ @Test
+ void 分页参数snake且带默认值() throws IOException {
+ String source = stripComments(Files.readString(CONTROLLER));
+ for (String param : List.of("page_size", "start_date", "end_date", "task_id",
+ "country", "asin", "company_id")) {
+ assertTrue(source.contains(param), "查询参数必须 snake_case:" + param + "(蓝图 §3.2,照去重页参数归一形状)");
+ }
+ assertTrue(source.contains("PageDefaults"), "page/page_size 默认值必须取 PageDefaults(page_size 默认 10);"
+ + "page 钳制防 (page-1)*page_size 溢出的行为样本在激活时以真实对象补(铁律 15)");
+ }
+
+ @Test
+ void 查询SQL只落XML不写注解SQL() throws IOException {
+ assertTrue(Files.exists(MAPPER), "查询必须走 AppearancePatentCleanItemMapper(铁律 1)");
+ String mapperSource = stripComments(Files.readString(MAPPER));
+ assertFalse(mapperSource.matches("(?s).*@(Select|Insert|Update|Delete)\\s*\\(.*"),
+ "不得新写注解 SQL(铁律 1:查询 SQL 全部落 XML Mapper)");
+ assertNotNull(findCleanItemMapperXml(), "mapper XML 必须落在 src/main/resources/mapper/**(铁律 1)");
+ }
+
+ @Test
+ void 菜单迁移只插columns不预授权() throws IOException {
+ assertTrue(Files.exists(MENU_MIGRATION), "菜单迁移必须是 " + MENU_MIGRATION.getFileName() + "(蓝图 §3.1)");
+ String sql = stripComments(Files.readString(MENU_MIGRATION))
+ .replaceAll("--[^\n]*", "");
+ assertTrue(sql.contains(COLUMN_KEY), "columns 行的 column_key 必须是 " + COLUMN_KEY);
+ assertTrue(sql.contains("'admin'"), "menu_type 必须是 'admin'(后管菜单)");
+ assertTrue(sql.contains(ROUTE_PATH), "route_path 必须是 " + ROUTE_PATH + "(前端路由)");
+ assertTrue(sql.toUpperCase().contains("NOT EXISTS"), "INSERT 必须带 NOT EXISTS 幂等护栏(V21 形状)");
+ assertFalse(sql.toUpperCase().contains("USER_COLUMN_PERMISSION"),
+ "不得插任何 user_column_permission 授权行(AC-6:默认仅 super_admin 可见,"
+ + "其余角色由超管在权限页手工勾授后才可见)");
+ }
+
+ @Test
+ void 删除链不触碰同步表() throws IOException {
+ // AC-7 结构判据:模块 main 源码里引用 CleanItem 的文件只许是干净清单成员
+ // (同步服务/控制器/Mapper/实体/其专属 Service),任务删除与历史结果删除路径不得触碰。
+ List referencing = new ArrayList<>();
+ try (Stream files = Files.walk(MAIN.resolve("modules/appearancepatent"))) {
+ files.filter(path -> path.toString().endsWith(".java")).forEach(path -> {
+ String relative = MAIN.relativize(path).toString().replace('\\', '/');
+ try {
+ if (stripComments(Files.readString(path)).contains("CleanItem")) {
+ referencing.add(relative);
+ }
+ } catch (IOException ignored) {
+ // 读不出按未引用计,不掩盖判据:文件级读取失败在别的用例里会红
+ }
+ });
+ }
+ assertTrue(referencing.size() >= 3,
+ "激活时应至少有同步服务/控制器/Mapper 三类文件引用 CleanItem,实得 " + referencing.size() + ":扫描空跑防呆");
+ for (String file : referencing) {
+ String name = file.substring(file.lastIndexOf('/') + 1);
+ assertTrue(name.contains("CleanItem") || name.contains("CleanSync"),
+ "CleanItem 只许被其专属文件引用,任务删除/历史路径不得触碰(AC-7:后管记录独立保留)——"
+ + "越界文件:" + file);
+ }
+ }
+
+ private static Path findCleanItemMapperXml() throws IOException {
+ Path resources = MODULE.resolve("src/main/resources/mapper");
+ if (!Files.exists(resources)) {
+ return null;
+ }
+ try (Stream files = Files.walk(resources)) {
+ return files.filter(path -> path.getFileName().toString()
+ .equals("AppearancePatentCleanItemMapper.xml")).findFirst().orElse(null);
+ }
+ }
+
+ private static String stripComments(String source) {
+ String noBlock = source.replaceAll("(?s)/\\*.*?\\*/", "");
+ StringBuilder out = new StringBuilder();
+ for (String line : noBlock.split("\n", -1)) {
+ int idx = line.indexOf("//");
+ out.append(idx >= 0 ? line.substring(0, idx) : line).append('\n');
+ }
+ return out.toString();
+ }
+}
diff --git a/backend-java/src/test/java/com/nanri/aiimage/modules/appearancepatent/service/AppearancePatentCleanSyncTest.java b/backend-java/src/test/java/com/nanri/aiimage/modules/appearancepatent/service/AppearancePatentCleanSyncTest.java
new file mode 100644
index 000000000..b4f8f3b8c
--- /dev/null
+++ b/backend-java/src/test/java/com/nanri/aiimage/modules/appearancepatent/service/AppearancePatentCleanSyncTest.java
@@ -0,0 +1,129 @@
+package com.nanri.aiimage.modules.appearancepatent.service;
+
+import org.junit.jupiter.api.Disabled;
+import org.junit.jupiter.api.Test;
+
+import java.io.IOException;
+import java.lang.reflect.Method;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.stream.Stream;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * AC-1/AC-2/AC-3(v1.3 R1/R5):外观专利出表成功 → 「结论=无侵权」行同步落后管新表。
+ *
+ * Pending Phase 2 激活。Phase 0 预置的是接缝判据(接缝名是判据的一部分,Phase 2 微调命名
+ * 必须同步改本文件并在蓝图 §5 登记);激活时除本清单外,再补真实对象的行为样本:
+ *
+ *
+ * - AC-1:payload N 行、其中 M 行「结论=无侵权」→ {@code biz_appearance_patent_clean_item}
+ * 恰有 M 行;{@code company_id}=任务 owner 用户的 {@code users.company_id};行字段与三因
+ * 字段值等;非无侵权行零落表;owner 读不出 company_id ⇒ 跳过并留日志,不得回填默认公司
+ * (铁律 30:读不出≠没有);
+ * - AC-2:同一任务补检/重试重新出表 → 按 {@code result_id} 覆盖式重写,
+ * {@code uk(result_id, row_no)} 下零重复行;出表失败(success=0/无持久化行)不写任何行;
+ * - AC-3:同步抛任何异常 → 任务终态与 {@code biz_file_result} 不被改写,错误只进日志;
+ * 同步装配路径(shouldAssembleSynchronously 分支)与异步出表作业两条触发点各一支判据。
+ *
+ */
+@Disabled("Pending Phase 2: AC-1/AC-2/AC-3 外观专利无侵权行同步落表(激活时移除本注解)")
+class AppearancePatentCleanSyncTest {
+
+ private static final Path MODULE = Path.of("").toAbsolutePath();
+ private static final Path MAIN = MODULE.resolve("src/main/java/com/nanri/aiimage");
+ private static final String SYNC_SERVICE_FQCN =
+ "com.nanri.aiimage.modules.appearancepatent.service.AppearancePatentCleanSyncService";
+ private static final String SYNC_SERVICE_REL =
+ "modules/appearancepatent/service/AppearancePatentCleanSyncService.java";
+ /** 两条出表成功触发点(蓝图 §2.2/§3.3:异步出表作业 + 同步装配分支)。 */
+ private static final String TRIGGER_1_REL =
+ "modules/appearancepatent/service/support/AppearancePatentResultJobSupport.java";
+ private static final String TRIGGER_2_REL =
+ "modules/appearancepatent/service/AppearancePatentResultFileJobHandler.java";
+
+ @Test
+ void 同步服务类与入口接缝就位() throws Exception {
+ Class> service = Class.forName(SYNC_SERVICE_FQCN,
+ false, Thread.currentThread().getContextClassLoader());
+ assertNotNull(service, "同步服务类必须落在 " + SYNC_SERVICE_REL + "(蓝图 §3.3)");
+ Method entry = null;
+ for (Method candidate : service.getDeclaredMethods()) {
+ if ("syncFromResult".equals(candidate.getName())) {
+ entry = candidate;
+ }
+ }
+ assertNotNull(entry, "入口必须是 syncFromResult(task, result)(蓝图 §3.3;改名先改本判据并登记蓝图 §5)");
+ assertTrue(entry.getParameterCount() == 2,
+ "syncFromResult 入参应为 (task, result) 两个,实得 " + entry.getParameterCount());
+ }
+
+ @Test
+ void 两条出表成功触发点都挂上同步() throws IOException {
+ for (String trigger : new String[]{TRIGGER_1_REL, TRIGGER_2_REL}) {
+ String source = stripComments(read(MAIN.resolve(trigger)));
+ assertTrue(source.contains("syncFromResult") || source.contains("AppearancePatentCleanSyncService"),
+ "出表成功触发点 " + trigger + " 必须调用同步服务(AC-3 要求两条路径都覆盖)");
+ }
+ }
+
+ @Test
+ void 过滤口径引用常量不抄字面量() throws IOException {
+ String source = stripComments(read(MAIN.resolve(SYNC_SERVICE_REL)));
+ assertTrue(source.contains("NO_INFRINGEMENT"),
+ "同步侧必须引用 AppearancePatentLlmClient.NO_INFRINGEMENT 判定「无侵权」(蓝图 §2.2/§3.3)");
+ assertFalse(source.contains("无侵权"),
+ "同步服务不得另抄「无侵权」字面量——判定口径单一来源在 LlmClient(黄金测试已钉模块级单源)");
+ }
+
+ @Test
+ void 覆盖式落表走MapperXML按resultId重写() throws IOException {
+ Path mapper = MAIN.resolve("modules/appearancepatent/mapper/AppearancePatentCleanItemMapper.java");
+ assertTrue(Files.exists(mapper), "同步落表必须走 AppearancePatentCleanItemMapper(铁律 1:SQL 收口 Mapper 层)");
+ Path xml = findCleanItemMapperXml();
+ assertNotNull(xml, "mapper XML 必须落在 src/main/resources/mapper/**(铁律 1)");
+ String sql = stripComments(Files.readString(xml));
+ assertTrue(sql.contains("result_id"), "覆盖式重写的删除与插入都要按 result_id 键(AC-2,同 ShopDataCrawlItemStoreService 模式)");
+ assertTrue(sql.toLowerCase().contains("delete"), "XML 必须含按 result_id 的 delete(delete-then-insert 覆盖式)");
+ assertTrue(sql.toLowerCase().contains("insert"), "XML 必须含批量 insert(分批 ≤500/批,蓝图 §3.3)");
+ }
+
+ @Test
+ void 公司归属显式落列不回填默认公司() throws IOException {
+ String source = stripComments(read(MAIN.resolve(SYNC_SERVICE_REL)));
+ assertTrue(source.contains("companyId") || source.contains("company_id"),
+ "同步落表必须显式解析并物化 company_id(蓝图 §3.1:company_id NOT NULL 无 DEFAULT,"
+ + "V145/V154/V156 先例的终态形状)");
+ assertFalse(source.matches("(?s).*company_?[Ii]d\\s*=\\s*1L;.*"),
+ "不得把 company_id 回填成默认 1——owner 读不出 company_id 必须跳过并留日志(铁律 30,AC-1)");
+ }
+
+ private static Path findCleanItemMapperXml() throws IOException {
+ Path resources = MODULE.resolve("src/main/resources/mapper");
+ if (!Files.exists(resources)) {
+ return null;
+ }
+ try (Stream files = Files.walk(resources)) {
+ return files.filter(path -> path.getFileName().toString()
+ .equals("AppearancePatentCleanItemMapper.xml")).findFirst().orElse(null);
+ }
+ }
+
+ private static String read(Path path) throws IOException {
+ assertTrue(Files.exists(path), "文件必须存在:" + path);
+ return Files.readString(path);
+ }
+
+ private static String stripComments(String source) {
+ String noBlock = source.replaceAll("(?s)/\\*.*?\\*/", "");
+ StringBuilder out = new StringBuilder();
+ for (String line : noBlock.split("\n", -1)) {
+ int idx = line.indexOf("//");
+ out.append(idx >= 0 ? line.substring(0, idx) : line).append('\n');
+ }
+ return out.toString();
+ }
+}
diff --git a/backend-java/src/test/java/com/nanri/aiimage/modules/appearancepatent/service/support/AppearancePatentChunkRowContractTest.java b/backend-java/src/test/java/com/nanri/aiimage/modules/appearancepatent/service/support/AppearancePatentChunkRowContractTest.java
new file mode 100644
index 000000000..d5887e1eb
--- /dev/null
+++ b/backend-java/src/test/java/com/nanri/aiimage/modules/appearancepatent/service/support/AppearancePatentChunkRowContractTest.java
@@ -0,0 +1,222 @@
+package com.nanri.aiimage.modules.appearancepatent.service.support;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.nanri.aiimage.modules.appearancepatent.model.dto.AppearancePatentResultRowDto;
+import com.nanri.aiimage.modules.task.model.entity.TaskChunkEntity;
+import com.nanri.aiimage.modules.task.mapper.TaskChunkMapper;
+import com.nanri.aiimage.modules.task.service.TransientPayloadStorageService;
+import org.junit.jupiter.api.Test;
+
+import java.io.IOException;
+import java.lang.reflect.Field;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.TreeSet;
+import java.util.stream.Stream;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertIterableEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * Phase 0 黄金测试(v1.3 外观专利无侵权数据同步后管,蓝图 §4 Phase 0,立即 Green)。
+ *
+ * v1.3 的同步服务要在出表成功点读 {@code biz_task_chunk.payload_json}、过滤「结论=无侵权」的行
+ * 落后管新表。这份契约钉住它的输入通道,全部判据都是对现网行为的刻画(characterization),
+ * 不含任何待实现逻辑:
+ *
+ *
+ * - 「无侵权」常量快照——判定口径单一来源={@code AppearancePatentLlmClient.NO_INFRINGEMENT}
+ * (蓝图 §2.2:同步侧引用常量,禁止另抄字面量);
+ * - chunk payload 行的 camelCase 键集——{@link AppearancePatentResultRowDto} 全字段序列化
+ * 出 23 个 camelCase 键({@code failureSyntheticStatus} 带 @JsonIgnore 不出键);
+ * - 读侧别名契约——{@code imageUrl→url}、{@code title_reason→titleReason}、
+ * {@code appearance_reason→appearanceReason}、{@code patent_reason→patentReason}(B52 教训:
+ * key 契约漂移必须在通道口钉死,不许同步侧自己猜);
+ * - 端到端黄金样本——序列化 → 真读取链
+ * {@link AppearancePatentResultRowReader#readChunkRows} 值等闭合,且「无侵权」与
+ * 「外观无侵权·商标待复核」按精确相等分得开(用户拍板 ①:严格口径);
+ * - 字面量单源扫描——appearancepatent 模块 main 源码里「无侵权」只许出现在
+ * {@code AppearancePatentLlmClient},同步服务落地(Phase 2)后再抄一份即红。
+ *
+ */
+class AppearancePatentChunkRowContractTest {
+
+ private static final String NO_INFRINGEMENT_LITERAL = "无侵权";
+ private static final String NO_INFRINGEMENT_CONSTANT_FQCN =
+ "com.nanri.aiimage.modules.appearancepatent.client.AppearancePatentLlmClient";
+ private static final Path MODULE = Path.of("").toAbsolutePath();
+ private static final Path MAIN_APPEARANCE_PATENT =
+ MODULE.resolve("src/main/java/com/nanri/aiimage/modules/appearancepatent");
+
+ /** DTO 全字段序列化键集(声明序;布尔 done 非 Boolean 包装差异不影响键名)。 */
+ private static final List PAYLOAD_ROW_KEYS = List.of(
+ "sourceFileKey", "sourceFilename", "rowToken", "groupKey", "id",
+ "asin", "country", "sku", "brand", "price",
+ "url", "title", "error", "done", "status",
+ "titleRisk", "appearanceRisk", "patentRisk", "conclusion",
+ "titleReason", "appearanceReason", "patentReason", "score");
+
+ @Test
+ void 无侵权常量快照单一来源() throws Exception {
+ Class> client = Class.forName(NO_INFRINGEMENT_CONSTANT_FQCN);
+ Field field = client.getDeclaredField("NO_INFRINGEMENT");
+ field.setAccessible(true);
+ assertEquals(NO_INFRINGEMENT_LITERAL, field.get(null),
+ "「无侵权」取值常量快照漂移:NO_INFRINGEMENT 是同步过滤的唯一判定口径"
+ + "(蓝图 §3.3),改值必须同步过蓝图 §5 登记");
+ }
+
+ @Test
+ void chunkPayload行序列化为camelCase键集() throws IOException {
+ ObjectMapper mapper = new ObjectMapper();
+ String json = mapper.writeValueAsString(List.of(fullRow("B0CLEAN001")));
+ JsonNode node = mapper.readTree(json);
+ assertTrue(node.isArray() && node.size() == 1, "样本应为单行数组");
+ Set actual = new TreeSet<>();
+ node.get(0).fieldNames().forEachRemaining(actual::add);
+ Set expected = new TreeSet<>(PAYLOAD_ROW_KEYS);
+ assertEquals(expected, actual,
+ "chunk payload 行键集漂移:同步侧按这些 camelCase 键取值(蓝图 §2.2),"
+ + "加/改键必须先改本判据并过蓝图 §5 登记,不许两边各写各的");
+ }
+
+ @Test
+ void 读侧别名契约从旧形状行恢复字段() throws IOException {
+ ObjectMapper mapper = new ObjectMapper();
+ // 旧客户端/旧载荷的别名形状:图片键 imageUrl、三因 snake_case、行状态 row_status。
+ String legacy = "{\"imageUrl\":\"https://img.example/1.jpg\","
+ + "\"title_reason\":\"标题维度原因\",\"appearance_reason\":\"外观维度原因\","
+ + "\"patent_reason\":\"专利维度原因\",\"row_status\":\"success\"}";
+ AppearancePatentResultRowDto row =
+ mapper.treeToValue(mapper.readTree(legacy), AppearancePatentResultRowDto.class);
+ assertEquals("https://img.example/1.jpg", row.getUrl(), "imageUrl 别名必须落到 url 字段");
+ assertEquals("标题维度原因", row.getTitleReason(), "title_reason 别名必须落到 titleReason");
+ assertEquals("外观维度原因", row.getAppearanceReason(), "appearance_reason 别名必须落到 appearanceReason");
+ assertEquals("专利维度原因", row.getPatentReason(), "patent_reason 别名必须落到 patentReason");
+ assertEquals("success", row.getStatus(), "row_status 别名必须落到 status");
+ }
+
+ @Test
+ void 序列化到读取链值等闭合且无侵权行分得开() throws Exception {
+ ObjectMapper mapper = new ObjectMapper();
+ AppearancePatentResultRowDto clean1 = fullRow("B0CLEAN001");
+ AppearancePatentResultRowDto clean2 = fullRow("B0CLEAN002");
+ AppearancePatentResultRowDto recheck = fullRow("B0RECHK01");
+ recheck.setConclusion("外观无侵权·商标待复核");
+ recheck.setTitleRisk(null);
+ String payloadJson = mapper.writeValueAsString(new ArrayList<>(List.of(clean1, clean2, recheck)));
+
+ TransientPayloadStorageService storage = mock(TransientPayloadStorageService.class);
+ when(storage.resolvePayload(anyString(), anyString())).thenReturn(payloadJson);
+ AppearancePatentResultRowReader reader = new AppearancePatentResultRowReader(
+ "appearance_patent", mapper, storage, mock(TaskChunkMapper.class),
+ value -> value == null ? "" : value, task -> null);
+ TaskChunkEntity chunk = new TaskChunkEntity();
+ chunk.setTaskId(33001L);
+ chunk.setChunkIndex(0);
+ chunk.setPayloadJson("chunk-0.json");
+
+ Map rows = reader.readChunkRows(chunk);
+ assertEquals(3, rows.size(), "三行载荷应原样读回三行");
+ for (AppearancePatentResultRowDto expected : List.of(clean1, clean2, recheck)) {
+ AppearancePatentResultRowDto actual = rows.get(expected.getRowToken());
+ assertNotNull(actual, "行键 " + expected.getRowToken() + " 应能按键读回");
+ for (String key : List.of("asin", "country", "sku", "brand", "price", "title", "url",
+ "conclusion", "titleReason", "appearanceReason", "patentReason")) {
+ fieldValue(expected, actual, key);
+ }
+ }
+ long cleanCount = rows.values().stream()
+ .filter(row -> NO_INFRINGEMENT_LITERAL.equals(row.getConclusion()))
+ .count();
+ assertEquals(2, cleanCount, "严格「结论=无侵权」只应命中 2 行");
+ assertEquals("外观无侵权·商标待复核", rows.get(recheck.getRowToken()).getConclusion(),
+ "待复核行的原值必须原样读回——它的存在且不计入 cleanCount,正是严格口径的分界判据(用户拍板 ①)");
+ }
+
+ /** assertEquals 对 getter 的薄封装:按属性名逐值比对,缺 getter 直接红(新键必须补进契约)。 */
+ private static void fieldValue(AppearancePatentResultRowDto expected,
+ AppearancePatentResultRowDto actual, String property) throws Exception {
+ java.lang.reflect.Method getter = AppearancePatentResultRowDto.class
+ .getMethod("get" + Character.toUpperCase(property.charAt(0)) + property.substring(1));
+ assertEquals(getter.invoke(expected), getter.invoke(actual),
+ "行字段 " + property + " 序列化→读取链闭合后必须值等");
+ }
+
+ @Test
+ void 无侵权字面量在模块main源码只有LlmClient一份() throws IOException {
+ Set flagged = new TreeSet<>();
+ try (Stream files = Files.walk(MAIN_APPEARANCE_PATENT)) {
+ files.filter(path -> path.toString().endsWith(".java"))
+ .forEach(path -> {
+ String relative = MAIN_APPEARANCE_PATENT.relativize(path).toString().replace('\\', '/');
+ if (stripComments(readSafely(path)).contains(NO_INFRINGEMENT_LITERAL)) {
+ flagged.add(relative);
+ }
+ });
+ }
+ assertFalse(flagged.isEmpty(), "扫描空跑=判据失效:LlmClient 自身必须命中");
+ assertIterableEquals(List.of("client/AppearancePatentLlmClient.java"), new ArrayList<>(flagged),
+ "「无侵权」字面量只许存在于 AppearancePatentLlmClient(判定口径单一来源);"
+ + "同步/导出/查询侧一律引用 NO_INFRINGEMENT 常量,注释里的举例不算(本判据已剥离注释)");
+ }
+
+ private static String readSafely(Path path) {
+ try {
+ return Files.readString(path);
+ } catch (IOException ex) {
+ return "";
+ }
+ }
+
+ /** 剥离块注释与行注释后再扫字面量。字符串里的 {@code https://} 会把该行剩余部分当注释截断——
+ * 只可能少报不可能多报,且被截断段不含判定目标字样,可接受。 */
+ private static String stripComments(String source) {
+ String noBlock = source.replaceAll("(?s)/\\*.*?\\*/", "");
+ StringBuilder out = new StringBuilder();
+ for (String line : noBlock.split("\n", -1)) {
+ int idx = line.indexOf("//");
+ out.append(idx >= 0 ? line.substring(0, idx) : line).append('\n');
+ }
+ return out.toString();
+ }
+
+ private static AppearancePatentResultRowDto fullRow(String asin) {
+ AppearancePatentResultRowDto row = new AppearancePatentResultRowDto();
+ row.setSourceFileKey("uploads/20261110/appearance_patent_33001.xlsx");
+ row.setSourceFilename("appearance_patent_33001.xlsx");
+ row.setRowToken("uploads/20261110/appearance_patent_33001.xlsx::row::" + asin);
+ row.setGroupKey("uploads/20261110/appearance_patent_33001.xlsx::2@2");
+ row.setId("2_1");
+ row.setAsin(asin);
+ row.setCountry("英国");
+ row.setSku("SKU-" + asin);
+ row.setBrand("Nike");
+ row.setPrice("12.99");
+ row.setUrl("https://img.example/" + asin + ".jpg");
+ row.setTitle("Women Floral Dress Summer Casual");
+ row.setError("");
+ row.setDone(Boolean.TRUE);
+ row.setStatus("success");
+ row.setTitleRisk("标题未发现明显商标侵权风险。");
+ row.setAppearanceRisk("未发现明显外观设计专利侵权风险。");
+ row.setPatentRisk("未发现明显发明或实用新型专利侵权风险。");
+ row.setConclusion(NO_INFRINGEMENT_LITERAL);
+ row.setTitleReason("标题维度原因");
+ row.setAppearanceReason("外观维度原因");
+ row.setPatentReason("专利维度原因");
+ row.setScore("4.6");
+ return row;
+ }
+}