test(phase-0): v1.4 京东数据库契约预置——通道接缝黄金 3 绿 + Pending 17 例 skip

This commit is contained in:
2026-11-14 02:27:34 +08:00
parent 64e94458c9
commit 10d73994f5
7 changed files with 371 additions and 0 deletions
@@ -0,0 +1,48 @@
import { test } from 'node:test'
import assert from 'node:assert/strict'
import { existsSync, readFileSync } from 'node:fs'
import { join } from 'node:path'
import { adminPages } from '../src/router/routes.ts'
/** v1.4「京东数据库」后管页契约(蓝图 docs/ITERATION_PLAN.md §3.4 / §4 Phase 5)。
*
* 与 company-menu-route.test.ts 同一取材方式:routes 注册表 + 后端迁移文件对撞。
* Pending 期整组 skip(node:test 原生 skip,零假断言);Phase 5 落地后去掉 skip 跑绿。
* 四处接线(routes / company-scope / operation-guides / V196 菜单迁移)少一处即红,
* 对齐既有护栏 company-menu-route 与 align-operation-guide 的口径。
*/
const V196 = join(process.cwd(), '..', 'backend-java', 'src', 'main', 'resources', 'db',
'V196__jd_database_menu.sql')
const COMPANY_SCOPE = join(process.cwd(), 'src', 'config', 'company-scope.ts')
const OPERATION_GUIDES = join(process.cwd(), 'src', 'layout', 'operation-guides.ts')
const MENU_KEY = 'admin_jd_database'
const ROUTE = 'jd-center/database'
function readIfExists(path: string, what: string): string {
assert.ok(existsSync(path), `${what} 尚未落地(蓝图 §4 Phase 5):${path}`)
return readFileSync(path, 'utf8')
}
test('V196 菜单迁移钉住 column_key 与 route_path', { skip: 'Pending Phase 5: 京东数据库页面落地后激活' }, () => {
const sql = readIfExists(V196, 'V196 迁移')
assert.ok(sql.includes(MENU_KEY), 'V196 缺 column_key admin_jd_database')
assert.ok(sql.includes(ROUTE), 'V196 缺 route_path jd-center/database')
assert.ok(!sql.includes('user_column_permission'), '菜单迁移不得插授权行(V190 惯例)')
})
test('routes 注册表出现京东数据库页面且公司隔离', { skip: 'Pending Phase 5: 京东数据库页面落地后激活' }, () => {
const page = adminPages.find((item) => item.menuKey === MENU_KEY)
assert.ok(page, `routes.ts 缺 menuKey=${MENU_KEY} 的注册行`)
assert.equal(page.path, ROUTE, 'route_path 必须与 V196 菜单一致')
assert.equal(page.title, '京东数据库', '菜单标题以「京东数据库」为准')
assert.equal(page.companyScoped, true, '京东数据库按公司隔离(AC-6)')
})
test('company-scope 与 operation-guides 同轮接线', { skip: 'Pending Phase 5: 京东数据库页面落地后激活' }, () => {
assert.ok(readIfExists(COMPANY_SCOPE, 'company-scope.ts').includes(ROUTE),
'COMPANY_SCOPED_PAGES 缺京东数据库登记(company-tab 护栏会红)')
assert.ok(readIfExists(OPERATION_GUIDES, 'operation-guides.ts').includes('京东数据库'),
'operation-guides 缺京东数据库条目(align-operation-guide 护栏会红)')
})
@@ -0,0 +1,41 @@
import { test } from 'node:test'
import assert from 'node:assert/strict'
import { existsSync, readFileSync } from 'node:fs'
import { join } from 'node:path'
/** v1.4 AC-8 分组契约(蓝图 docs/ITERATION_PLAN.md §3.4 / §4 Phase 5)。
*
* 京东库专属分组(用户拍板):同公司内重名拒绝、删除分组不删商品(group_id 置 NULL)、
* 按公司隔离读写。Pending 期整组 skip;Phase 5 落地控制器与服务后去掉 skip 跑绿。
* 断言落点为源码绊线(与后端 JdIngestPayloadContractTest 同形):
* SQL 全落 XML(铁律 1)、归属读不出不得回填默认公司(铁律 30)。
*/
const BACKEND_JD = join(process.cwd(), '..', 'backend-java', 'src', 'main', 'java',
'com', 'nanri', 'aiimage', 'modules', 'jd')
const GROUP_SERVICE = join(BACKEND_JD, 'service', 'JdProductGroupService.java')
const GROUP_XML = join(process.cwd(), '..', 'backend-java', 'src', 'main', 'resources',
'mapper', 'jd', 'JdProductGroupMapper.xml')
function readIfExists(path: string, what: string): string {
assert.ok(existsSync(path), `${what} 尚未落地(蓝图 §4 Phase 5):${path}`)
return readFileSync(path, 'utf8')
}
test('分组服务钉住重名拒绝与删除不删商品', { skip: 'Pending Phase 5: 分组服务落地后激活' }, () => {
const service = readIfExists(GROUP_SERVICE, 'JdProductGroupService')
assert.ok(service.includes('DuplicateKeyException') || service.includes('重名'),
'同公司重名必须拒绝且不落库(AC-8)')
assert.ok(service.includes('group_id') && service.includes('null'),
'删除分组必须把商品 group_id 置 NULL 而不是删商品(AC-8)')
assert.ok(service.includes('readCompanyIdOrOwn'),
'分组读写必须走 DataReadScope.readCompanyIdOrOwn 公司隔离(铁律 30 配套)')
})
test('分组 SQL 全落 XML 且不做物理删商品', { skip: 'Pending Phase 5: 分组 Mapper 落地后激活' }, () => {
const xml = readIfExists(GROUP_XML, 'JdProductGroupMapper.xml')
assert.ok(!xml.toUpperCase().includes('DELETE FROM biz_jd_product'),
'分组删除不得物理删商品行')
assert.ok(xml.includes('uk_company_group_name') || xml.includes('company_id'),
'分组 SQL 必须按公司隔离')
})
@@ -0,0 +1,53 @@
package com.nanri.aiimage.modules.jd;
import com.nanri.aiimage.common.module.TaskModuleRegistry;
import com.nanri.aiimage.modules.task.model.CollectChannel;
import org.junit.jupiter.api.Test;
import java.util.List;
import java.util.Set;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* v1.4 Phase 0 黄金测试:钉住 Phase 1 即将有意识改动的两个存量接缝的<b>当前</b>形状。
*
* <p>判据来源:蓝图 {@code docs/ITERATION_PLAN.md} §2.2 影响面清单——
* ① {@code TaskModuleRegistry} 新增 {@code JD_SHOP_COLLECT} 注册行;
* ② {@code CollectChannel.LOCAL_DEFAULT_MODULES} 加入 {@code JD_SHOP_COLLECT}
* (不加 = 默认 ONLINE = 任务被推给无紫鸟的 Linux worker,铁律 19 同形坑)。
*
* <p>本类钉的是「改动前」的事实;Phase 1 落地时必须<b>同轮更新</b>这三条断言并激活
* {@code JdChannelDefaultTest},让接缝翻转换成显式评审点。所有既有模块清单、
* LOCAL 默认形状已由 {@code TaskModuleCoverageTest} / {@code CollectChannelTest} 各自钉住,此处不重复。
*/
class JdCollectChannelGoldenTest {
/** 当前注册表恰好 16 个模块且无京东:Phase 1 新增 JD_SHOP_COLLECT 必须同轮更新本清单。 */
@Test
void 京东模块当前未注册进任务模块注册表() {
Set<String> types = TaskModuleRegistry.moduleTypes();
assertEquals(16, types.size(), "Phase 1 新增 JD_SHOP_COLLECT 时更新为 17");
assertTrue(types.containsAll(List.of("APPEARANCE_PATENT", "SIMILAR_ASIN", "SHOP_DATA_CRAWL",
"COLLECT_DATA", "PRICE_TRACK", "PUBLISH", "BRAND")), "既有清单形状漂移,先查别人改动");
assertFalse(types.contains("JD_SHOP_COLLECT"), "当前未注册;出现即有人在未登记蓝图的情况下动了注册表");
}
/** 当前京东模块按 V183 语义默认 ONLINE:Phase 1 改为 LOCAL 时同轮更新本断言。 */
@Test
void 京东模块当前默认通道为ONLINE() {
assertFalse(CollectChannel.defaultFor("JD_SHOP_COLLECT").isLocal(),
"当前未加入 LOCAL 默认;Phase 1 翻转后本断言同步改为 isLocal()");
}
/** 当前京东模块无提交凭据要求:注册表对未注册类型按构造抛参。Phase 1 登记后本断言同轮更新。 */
@Test
void 京东模块当前无提交凭据登记() {
assertThrows(IllegalArgumentException.class,
() -> TaskModuleRegistry.submitSecretModuleOf("JD_SHOP_COLLECT"),
"未注册类型应按构造拒绝;Phase 1 注册后改断言为 Optional.empty()");
}
}
@@ -0,0 +1,72 @@
package com.nanri.aiimage.modules.jd;
import org.junit.jupiter.api.Disabled;
import org.junit.jupiter.api.Test;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.stream.Stream;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* v1.4 AC-1/AC-6 回传 payload 契约源码绊线(蓝图 §3.2)。
*
* <p>键集契约:回传请求体顶层必须消费 {@code batchId / cursor / items / isEnd},
* 行内必须消费 {@code productCode / summary / detail / images};落库必须
* upsert-only({@code INSERT ... ON DUPLICATE KEY UPDATE},B94-01 教训:delete-then-insert
* 曾整批清空 1902 行),游标必须合并写(铁律 30 / B84-01:一次不带 cursor 的请求
* 不得把既有游标抹成 null)。
*
* <p>形态为源码绊线:读实现文件断言契约字面量在位。激活时实现类与 Mapper XML
* 已存在;键改名必须同轮改本判据并在蓝图 §5 登记。
*/
@Disabled("Pending Phase 2: JdResultIngestService 与 JdProductMapper.xml 落地后激活")
class JdIngestPayloadContractTest {
private static final Path JAVA_ROOT = Path.of("src", "main", "java", "com", "nanri", "aiimage");
private static final Path MAPPER_XML =
Path.of("src", "main", "resources", "mapper", "jd", "JdProductMapper.xml");
private static String read(Path path) {
try {
return Files.readString(path);
} catch (IOException ex) {
throw new UncheckedIOException("契约文件缺失(蓝图 §3.2 未落地?): " + path, ex);
}
}
private static Path findInJdModule(String simpleName) throws IOException {
try (Stream<Path> stream = Files.walk(JAVA_ROOT.resolve("modules").resolve("jd"))) {
return stream.filter(p -> p.getFileName().toString().equals(simpleName)).findFirst()
.orElseThrow(() -> new IllegalStateException("未找到 " + simpleName + "(蓝图 §3.2 未落地?)"));
}
}
@Test
void 回传键集在采集控制器与服务中消费() throws IOException {
String ingest = read(findInJdModule("JdResultIngestService.java"));
for (String key : List.of("batchId", "cursor", "items", "isEnd", "productCode", "summary", "detail", "images")) {
assertTrue(ingest.contains(key), "回传 payload 键未消费: " + key);
}
}
@Test
void 行落库必须upsert_only禁止delete_then_insert() {
String xml = read(MAPPER_XML);
assertTrue(xml.contains("ON DUPLICATE KEY UPDATE"), "京东行落库必须 upsert-only(B94-01)");
assertFalse(xml.toUpperCase().contains("DELETE FROM"),
"同步链不得出现 delete-then-insert(B94-01:曾整批清空 1902 行)");
}
@Test
void 游标必须合并写() throws IOException {
String ingest = read(findInJdModule("JdResultIngestService.java"));
assertTrue(ingest.contains("merge") || ingest.contains("沿用前值"),
"cursor 必须合并写(铁律 30 / B84-01:缺件请求不得把游标读成没有)");
}
}
@@ -0,0 +1,94 @@
package com.nanri.aiimage.modules.jd;
import org.junit.jupiter.api.Disabled;
import org.junit.jupiter.api.Test;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.stream.Stream;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* v1.4 数据底座契约(蓝图 §3.1):V193~V196 四支迁移与 {@code aiimage.jd.*} 配置的形状钉子。
*
* <p>激活后成为迁移绊线:已发布迁移一个字节不许改(铁律 10/15),本类断言的就是
* Phase 1 写下的那一份形状——覆盖最新唯一键、归属列显式 NOT NULL(铁律 30)、
* 图片独立桶不落默认桶(铁律 17:默认桶整桶 7 天 ILM)、菜单每公司一行且不插授权行(V190 惯例)。
*/
@Disabled("Pending Phase 1: V193~V196 迁移与 aiimage.jd.* 配置落地后激活")
class JdSchemaContractTest {
private static final Path DB_DIR = Path.of("src", "main", "resources", "db");
private static final Path RESOURCES = Path.of("src", "main", "resources");
private static String read(Path path) {
try {
return Files.readString(path);
} catch (IOException ex) {
throw new UncheckedIOException("契约文件缺失(蓝图 §3.1 未落地?): " + path, ex);
}
}
private static List<String> linesContaining(String text, String needle) {
return text.lines().filter(line -> line.contains(needle)).toList();
}
@Test
void V193_商品主表_覆盖最新唯一键与归属列形状() {
String sql = read(DB_DIR.resolve("V193__jd_product.sql"));
assertTrue(sql.contains("biz_jd_product"), "缺主表");
for (String column : List.of("company_id", "shop_id", "shop_name", "product_code",
"title", "attr_json", "attr_count", "image_count", "main_image_url", "synced_at")) {
assertFalse(linesContaining(sql, "`" + column + "`").isEmpty(), "V193 缺列: " + column);
}
assertTrue(linesContaining(sql, "company_id").stream().anyMatch(line -> line.contains("NOT NULL")),
"company_id 必须 NOT NULL 且无默认值(V189 同形,同步时显式落值)");
assertTrue(sql.contains("uk_company_shop_code"), "覆盖最新语义唯一键 (company_id,shop_id,product_code) 缺失");
}
@Test
void V194_图片表_sha256幂等唯一键() {
String sql = read(DB_DIR.resolve("V194__jd_product_image.sql"));
assertTrue(sql.contains("biz_jd_product_image"), "缺图片表");
for (String column : List.of("product_id", "image_type", "attr_name", "sort_no",
"object_key", "url", "byte_size", "sha256")) {
assertFalse(linesContaining(sql, "`" + column + "`").isEmpty(), "V194 缺列: " + column);
}
assertTrue(sql.contains("uk_product_image"), "同商品同 sha256 幂等唯一键缺失");
}
@Test
void V195_分组表_公司隔离唯一键与商品挂组列() {
String sql = read(DB_DIR.resolve("V195__jd_product_group.sql"));
assertTrue(sql.contains("biz_jd_product_group"), "缺分组表");
assertTrue(sql.contains("uk_company_group_name"), "同公司重名拒绝唯一键缺失");
assertTrue(linesContaining(sql, "ALTER TABLE").stream().anyMatch(line -> line.contains("group_id")),
"V195 必须同时给 biz_jd_product 补 group_id 挂组列");
}
@Test
void V196_菜单_每公司一行且不插授权行() {
String sql = read(DB_DIR.resolve("V196__jd_database_menu.sql"));
assertTrue(sql.contains("admin_jd_database"), "缺 column_key");
assertTrue(sql.contains("jd-center/database"), "缺 route_path");
assertTrue(sql.contains("京东数据库"), "缺菜单名");
assertTrue(sql.contains("admin_group_data"), "父级必须挂本公司 admin_group_data 组行");
assertTrue(sql.contains("NOT EXISTS"), "必须带幂等守卫");
assertFalse(sql.contains("user_column_permission"), "菜单迁移不得插授权行(默认仅 super_admin,V190 惯例)");
}
@Test
void 配置_独立图片桶不落默认桶() {
String appYml = read(RESOURCES.resolve("application.yml"));
assertTrue(linesContaining(appYml, "jd:").size() >= 2, "aiimage.jd 段缺失");
assertTrue(appYml.contains("bucket: jd-products"), "必须独立桶;默认桶 nanri-ai-images 整桶 7 天 ILM 会删光商品图");
assertTrue(appYml.contains("retention-days: 0"), "商品图默认永久保留(0=不设 ILM)");
String exampleYml = read(RESOURCES.resolve("application-local.example.yml"));
assertTrue(linesContaining(exampleYml, "jd:").size() >= 2, "配置模板未同步 aiimage.jd 段(铁律 3)");
}
}
@@ -0,0 +1,24 @@
package com.nanri.aiimage.modules.task.model;
import org.junit.jupiter.api.Disabled;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
/**
* v1.4 AC-1 契约:京东店铺采集只能在本机 Windows + 紫鸟窗口执行,必须默认 LOCAL 通道。
*
* <p>蓝图为 {@code docs/ITERATION_PLAN.md} §4 Phase 1;判据即铁律 19 同形——
* {@code CollectChannel.LOCAL_DEFAULT_MODULES} 不加 {@code JD_SHOP_COLLECT},
* 取页 SQL 就会把它当 ONLINE 派给 Linux worker,而紫鸟只在客户端本机 ⇒ 任务永不执行。
* 当前形状(默认 ONLINE)由黄金测试 {@code JdCollectChannelGoldenTest} 钉住;
* Phase 1 加入 LOCAL 默认后移除本 @Disabled 并跑绿。
*/
class JdChannelDefaultTest {
@Test
@Disabled("Pending Phase 1: CollectChannel.LOCAL_DEFAULT_MODULES 加入 JD_SHOP_COLLECT 后激活")
void 京东采集默认通道必须是LOCAL() {
assertEquals(CollectChannel.LOCAL, CollectChannel.defaultFor("JD_SHOP_COLLECT"));
}
}
+39
View File
@@ -0,0 +1,39 @@
import { test } from 'node:test'
import assert from 'node:assert/strict'
import { existsSync, readFileSync } from 'node:fs'
import { join } from 'node:path'
/** v1.4 AC-1 用户端入口契约(蓝图 docs/ITERATION_PLAN.md §3.2 / §4 Phase 5)。
*
* 「京东采集」以工具台卡片 + 路由 + endpoints 组三件接入用户端(照工具台既有形状):
* 工具卡必须声明非空 permissionKeys(用户端工具按后端 app 菜单 column_key 过滤显隐),
* 路由 /jd-collect,endpoints.ts 有 jdCollect 组。Pending 期整组 skip;
* Phase 5 落地后去掉 skip 跑绿。
*/
const ROUTER = join(process.cwd(), 'src', 'router', 'index.ts')
const TOOL_CATALOG = join(process.cwd(), 'src', 'pages', 'amazon', 'tool-catalog.ts')
const ENDPOINTS = join(process.cwd(), 'src', 'shared', 'api', 'endpoints.ts')
function readIfExists(path: string, what: string): string {
assert.ok(existsSync(path), `${what} 尚未落地(蓝图 §4 Phase 5):${path}`)
return readFileSync(path, 'utf8')
}
test('路由注册京东采集页', { skip: 'Pending Phase 5: 京东采集入口落地后激活' }, () => {
assert.ok(readIfExists(ROUTER, 'router/index.ts').includes('/jd-collect'),
'router 缺 /jd-collect 路由')
})
test('工具台卡片声明京东工具且带权限键', { skip: 'Pending Phase 5: 京东采集入口落地后激活' }, () => {
const catalog = readIfExists(TOOL_CATALOG, 'tool-catalog.ts')
assert.ok(catalog.includes('jd-collect') || catalog.includes('京东采集'),
'TOOL_GROUPS 缺京东采集工具卡')
assert.ok(/jd[\s\S]{0,400}permissionKeys/.test(catalog),
'京东工具卡必须声明非空 permissionKeys(显隐按后端 app 菜单 key 过滤)')
})
test('endpoints 注册 jdCollect 端点组', { skip: 'Pending Phase 5: 京东采集入口落地后激活' }, () => {
assert.ok(readIfExists(ENDPOINTS, 'endpoints.ts').includes('jdCollect'),
'endpoints.ts 缺 jdCollect 端点组(建单/心跳/回传三件)')
})