feat(keyword-share): 新增客户端批量同步端点,保住真实使用人/时间与四级类目

工作台「关键词使用记录」与后台管理对不上,根因不是链路不通(后台现存词 426
与桌面 426 逐字相等),而是「谁、何时」两个字段在推拉两个方向上各丢一次:

- 推:markInternal 把 user_name/used_time 硬写成 token 账号与服务器此刻,
  历史使用记录推上去一律变成「同步账号 + 同步那一刻」;
- 拉:selectRows/selectRandomUnused 投影 u.user_name,而 VO 属性叫 usedUser,
  驼峰映射只会认成不存在的 userName ⇒ GET /keywords 的 usedUser 恒为 null;
- 词本体:add() 从不写四级类目,且 keyword_share 侧只有 INSERT IGNORE、
  没有任何 UPSERT,重复词静默 no-op。

处置:
- 修 used_user 别名(两处投影);
- 新增 KeywordShareMapper#upsertBatchFromSync,类目/chinese 按
  COALESCE(NULLIF(VALUES(x),''),x) 非空才覆盖,更新分支不碰 user_name/add_time
  (那是历史归属,不由同步改写);
- 新增 POST /api/keyword-share/sync/import:每行携带 usedUser/usedTime,
  绕开 markInternal 复用现成 KeywordUsageMapper#upsertBatch(本就是 =VALUES(...)),
  不改表结构、不加 Flyway 迁移;
- used 取三态:null=不改动使用状态。按 false 处理会让「只同步词库」的一次
  调用把后台已有使用记录整批删掉;
- 共享 API 账号下的归属失真用服务端名单收口:命中 aiimage.keyword-share-sync
  .used-users 才按姓名落库且落名单里那份写法(全/半角括号归一,否则同一人被
  后管拆成两个使用者);strict 默认 false,名单未填时放行并计 usedUserUnknown,
  避免首次上线把全部记录静默改写成账号名。

顺带:CatchSilenceRatchetTest 要求新增 catch 必须同批净减,而宽松时间解析需要
try/catch ⇒ 把 ShopDataCrawlAdminTasksService 已有的同形状实现抽成
common/support/LooseLocalDateTimeParser 两处共用,净新增 catch 为 0,未放宽基线。

尺子:XML_STATEMENT_TOTAL 140→141,NOT_MIGRATED 点名新 insert(非 select,
XML_SELECT_TOTAL 不动)。

验证:mvn -o test-compile rc=0;后端整面 mvn -o test 4892 passed/0 failed/18 skipped。
本机无 MySQL,端到端未跑,真链路待客户端联调(ops BACKLOG B44)。
This commit is contained in:
2026-10-26 19:17:26 +08:00
parent b8abdc1eec
commit e0abd33ed4
15 changed files with 786 additions and 18 deletions
@@ -65,6 +65,8 @@ class MigratedSqlEquivalenceTest {
// (SqlLayeringConventionTest.XML_STATEMENT_TOTAL 同轮 128 → 129)。
// 89 → 99:关键词使用记录管理端(keywordusage 模块)新写 10 条只读 select,逐条点入
// (SqlLayeringConventionTest.XML_STATEMENT_TOTAL 同轮 130 → 140)。
// 99 → 99:客户端全量同步新写 1 条 insert(KeywordShareMapper#upsertBatchFromSync),
// 点名进 NOT_MIGRATED 但不是 select ⇒ select 总数不动(SqlLayeringConventionTest 同轮 140 → 141)。
private static final int XML_SELECT_TOTAL = 99;
/**
@@ -90,6 +92,9 @@ class MigratedSqlEquivalenceTest {
"KeywordShareMapper#selectSubCategoryCounts",
"KeywordShareMapper#selectCategoryL3Counts",
"KeywordShareMapper#selectExistingKeywords",
// 工作台客户端全量同步新写的词本体 UPSERT:注解时代没有原文可对撞,按新写语句点名留痕。
// 它是 insert 不是 select,故 XML_SELECT_TOTAL 不随之变。
"KeywordShareMapper#upsertBatchFromSync",
// brandgating 模块(品牌Gating库并入管理后台,2026-10-23)新写 8 条 select。
"BrandGatingMapper#countByFilter",
"BrandGatingMapper#selectRows",
@@ -83,7 +83,9 @@ class SqlLayeringConventionTest {
// 129 → 130:CR-01 新增 {@code LoginUserMapper#incrementSessionEpoch}(会话世代原子自增),
// 新写语句直接进 mapper/auth/LoginUserMapper.xml,同轮登记进 NOT_MIGRATED。
// 130 → 140:关键词使用记录管理端(keywordusage 模块,1 份 XML 10 条只读 select)新写语句。
private static final int XML_STATEMENT_TOTAL = 140;
// 140 → 141:工作台客户端全量同步新增 {@code KeywordShareMapper#upsertBatchFromSync}
// (词本体 UPSERT,把客户端的四级类目写进既有行),同轮登记进 NOT_MIGRATED。
private static final int XML_STATEMENT_TOTAL = 141;
/**
* wrapper 里夹带函数级 SQL 的现状("这不是简单单表"的证据),文件名 → 条数:
@@ -1,5 +1,6 @@
package com.nanri.aiimage.modules.keywordshare.service;
import com.nanri.aiimage.config.KeywordShareSyncProperties;
import com.nanri.aiimage.modules.keywordshare.mapper.KeywordAddLogMapper;
import com.nanri.aiimage.modules.keywordshare.mapper.KeywordDeleteLogMapper;
import com.nanri.aiimage.modules.keywordshare.mapper.KeywordShareMapper;
@@ -12,9 +13,11 @@ import com.nanri.aiimage.modules.keywordshare.model.entity.KeywordShareEntity;
import com.nanri.aiimage.modules.keywordshare.model.entity.KeywordUsageEntity;
import com.nanri.aiimage.modules.keywordshare.model.dto.KeywordShareAddRequest;
import com.nanri.aiimage.modules.keywordshare.model.dto.KeywordShareDeleteRequest;
import com.nanri.aiimage.modules.keywordshare.model.dto.KeywordShareSyncImportRequest;
import com.nanri.aiimage.modules.keywordshare.model.dto.KeywordUsageBatchRequest;
import com.nanri.aiimage.modules.keywordshare.model.vo.KeywordSharePageVo;
import com.nanri.aiimage.modules.keywordshare.model.vo.KeywordShareRowVo;
import com.nanri.aiimage.modules.keywordshare.model.vo.KeywordShareSyncResultVo;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
@@ -58,8 +61,19 @@ class KeywordShareServiceTest {
private KeywordDeleteLogMapper keywordDeleteLogMapper;
private KeywordShareService newService() {
return newService(new KeywordShareSyncProperties());
}
private KeywordShareService newService(KeywordShareSyncProperties syncProperties) {
return new KeywordShareService(keywordShareMapper, keywordUsageMapper,
keywordAddLogMapper, keywordDeleteLogMapper);
keywordAddLogMapper, keywordDeleteLogMapper, syncProperties);
}
private static KeywordShareSyncProperties rosterOf(boolean strict, String... names) {
KeywordShareSyncProperties properties = new KeywordShareSyncProperties();
properties.setStrict(strict);
properties.setUsedUsers(List.of(names));
return properties;
}
private static KeywordShareRowVo row(long id, String keyword, boolean used, String usedUser) {
@@ -476,4 +490,201 @@ class KeywordShareServiceTest {
.contains("company_id", "user_name")
.doesNotContain("${");
}
// ---------------------------------------------------------------- 客户端全量同步
private static KeywordShareSyncImportRequest.Item syncItem(String country, String keyword, Boolean used,
String usedUser, String usedTime) {
KeywordShareSyncImportRequest.Item item = new KeywordShareSyncImportRequest.Item();
item.setCountry(country);
item.setKeyword(keyword);
item.setUsed(used);
item.setUsedUser(usedUser);
item.setUsedTime(usedTime);
return item;
}
private static KeywordShareSyncImportRequest syncRequest(List<KeywordShareSyncImportRequest.Item> items) {
KeywordShareSyncImportRequest request = new KeywordShareSyncImportRequest();
request.setItems(items);
return request;
}
@Test
@DisplayName("sync/import:客户端传来的 usedTime/usedUser 与四级类目原样落库,不被服务端此刻与账号覆盖")
void syncImportKeepsClientUsedTimeUserAndCategories() {
KeywordShareSyncImportRequest.Item item = syncItem("英国", "wraps", true, "阿武(吴棋龙)", "2026-10-25T22:59:26");
item.setChinese("包裹");
item.setCategory("衣物鞋类");
item.setSubCategory("包包");
item.setCategoryL3("其他包包");
item.setCategoryL4("其他包包");
item.setKtype("主关键词");
item.setSource("本地导入");
KeywordShareService service = newService(rosterOf(true, "阿武(吴棋龙)"));
LocalDateTime before = LocalDateTime.now();
KeywordShareSyncResultVo vo = service.syncImport(syncRequest(List.of(item)), COMPANY_ID, "kw_share_api");
// 这条用例存在的理由:mark() 走的是 used_time=now()、user_name=token 账号,
// 同步历史时会被改写成「谁在同步那一刻用的」,真实使用人与使用时刻双双丢失。
ArgumentCaptor<List<KeywordUsageEntity>> usageCaptor = ArgumentCaptor.forClass(List.class);
verify(keywordUsageMapper).upsertBatch(usageCaptor.capture());
KeywordUsageEntity usage = usageCaptor.getValue().get(0);
assertThat(usage.getUserName()).isEqualTo("阿武(吴棋龙)");
assertThat(usage.getUsedTime()).isEqualTo(LocalDateTime.of(2026, 10, 25, 22, 59, 26))
.isBefore(before);
assertThat(usage.getCompanyId()).isEqualTo(COMPANY_ID);
ArgumentCaptor<List<KeywordShareEntity>> wordCaptor = ArgumentCaptor.forClass(List.class);
verify(keywordShareMapper).upsertBatchFromSync(wordCaptor.capture());
KeywordShareEntity word = wordCaptor.getValue().get(0);
assertThat(word.getCategory()).isEqualTo("衣物鞋类");
assertThat(word.getSubCategory()).isEqualTo("包包");
assertThat(word.getCategoryL3()).isEqualTo("其他包包");
// 词本体的 user_name 是「添加人」,新词就是本次同步账号——它和使用人是两回事
assertThat(word.getUserName()).isEqualTo("kw_share_api");
assertThat(vo.getAdded()).isEqualTo(1);
assertThat(vo.getUpdated()).isZero();
assertThat(vo.getUsedUserFallback()).isZero();
assertThat(vo.getUsedUserUnknown()).isZero();
assertThat(vo.getUsedTimeFallback()).isZero();
}
@Test
@DisplayName("sync/import:名单外姓名 strict=true 回退账号名并计数,strict=false 放行但仍计 unknown")
void syncImportResolvesOperatorAgainstRoster() {
// 半角括号写法要能命中全角名单,否则同一个人会被后管拆成两个使用者
KeywordShareSyncImportRequest.Item hit = syncItem("英国", "basket", true, "阿武(吴棋龙)", "2026-10-01 08:00:00");
KeywordShareSyncImportRequest.Item miss = syncItem("英国", "hanger", true, "陌生人", "2026-10-01 08:00:00");
ArgumentCaptor<List<KeywordUsageEntity>> captor = ArgumentCaptor.forClass(List.class);
KeywordShareSyncResultVo strict = newService(rosterOf(true, "阿武(吴棋龙)"))
.syncImport(syncRequest(List.of(hit, miss)), COMPANY_ID, "kw_share_api");
verify(keywordUsageMapper).upsertBatch(captor.capture());
// 命中名单后落的是名单里那份写法:客户端传半角也不能让它把同一个人拆成两个使用者
assertThat(captor.getValue()).extracting(KeywordUsageEntity::getUserName)
.containsExactly("阿武(吴棋龙)", "kw_share_api");
assertThat(strict.getUsedUserFallback()).isEqualTo(1);
assertThat(strict.getUsedUserUnknown()).isEqualTo(1);
KeywordShareSyncResultVo lenient = newService(rosterOf(false, "阿武(吴棋龙)"))
.syncImport(syncRequest(List.of(hit, miss)), COMPANY_ID, "kw_share_api");
assertThat(lenient.getUsedUserFallback()).isZero();
assertThat(lenient.getUsedUserUnknown()).isEqualTo(1);
}
@Test
@DisplayName("sync/import:脏时间按行降级——1970 丢使用状态但词照收、未来值钳到此刻、缺失回退此刻")
void syncImportDegradesDirtyUsedTimePerRow() {
KeywordShareSyncImportRequest.Item ancient = syncItem("英国", "ancient", true, "阿武(吴棋龙)", "1970-01-01T00:00:00");
KeywordShareSyncImportRequest.Item future = syncItem("英国", "future", true, "阿武(吴棋龙)", "2099-01-01T00:00:00");
KeywordShareSyncImportRequest.Item missing = syncItem("英国", "missing", true, "阿武(吴棋龙)", " ");
KeywordShareSyncImportRequest.Item unparsable = syncItem("英国", "garbage", true, "阿武(吴棋龙)", "昨天下午");
LocalDateTime before = LocalDateTime.now();
KeywordShareSyncResultVo vo = newService(rosterOf(true, "阿武(吴棋龙)"))
.syncImport(syncRequest(List.of(ancient, future, missing, unparsable)), COMPANY_ID, "kw_share_api");
assertThat(vo.getUsageSkipped()).isEqualTo(1);
assertThat(vo.getUsedTimeClamped()).isEqualTo(1);
assertThat(vo.getUsedTimeFallback()).isEqualTo(2);
// 一颗脏时间戳不该打掉整批:四个词全部入库,只有 ancient 的使用状态被丢
assertThat(vo.getAdded()).isEqualTo(4);
ArgumentCaptor<List<KeywordShareEntity>> wordCaptor = ArgumentCaptor.forClass(List.class);
verify(keywordShareMapper).upsertBatchFromSync(wordCaptor.capture());
assertThat(wordCaptor.getValue()).extracting(KeywordShareEntity::getKeyword)
.containsExactly("ancient", "future", "missing", "garbage");
ArgumentCaptor<List<KeywordUsageEntity>> usageCaptor = ArgumentCaptor.forClass(List.class);
verify(keywordUsageMapper).upsertBatch(usageCaptor.capture());
assertThat(usageCaptor.getValue()).hasSize(3)
.allSatisfy(row -> assertThat(row.getUsedTime()).isAfterOrEqualTo(before));
}
@Test
@DisplayName("sync/import:used=false 删使用记录;dryRun 只统计不写;空键与批内重复计入 skipped")
void syncImportDeletesUsageAndHonoursDryRun() {
List<KeywordShareSyncImportRequest.Item> items = List.of(
syncItem("英国", "keep", false, null, null),
syncItem("英国", "drop", true, "阿武(吴棋龙)", "2026-10-01T08:00:00"),
syncItem("英国", "drop", true, "阿武(吴棋龙)", "2026-10-01T08:00:00"),
syncItem("", "no-country", true, "阿武(吴棋龙)", "2026-10-01T08:00:00"));
KeywordShareSyncImportRequest request = syncRequest(items);
KeywordShareService service = newService(rosterOf(true, "阿武(吴棋龙)"));
KeywordShareSyncImportRequest dryRunRequest = syncRequest(items);
dryRunRequest.setDryRun(true);
KeywordShareSyncResultVo dryRun = service.syncImport(dryRunRequest, COMPANY_ID, "kw_share_api");
assertThat(dryRun.isDryRun()).isTrue();
assertThat(dryRun.getSkipped()).isEqualTo(2);
assertThat(dryRun.getAdded()).isEqualTo(2);
verify(keywordShareMapper, never()).upsertBatchFromSync(anyList());
verify(keywordUsageMapper, never()).upsertBatch(anyList());
verify(keywordUsageMapper, never()).deleteBatch(any(), anyList());
KeywordShareSyncResultVo real = service.syncImport(request, COMPANY_ID, "kw_share_api");
assertThat(real.isDryRun()).isFalse();
ArgumentCaptor<List<KeywordShareKey>> deleteCaptor = ArgumentCaptor.forClass(List.class);
verify(keywordUsageMapper).deleteBatch(eq(COMPANY_ID), deleteCaptor.capture());
assertThat(deleteCaptor.getValue()).extracting(KeywordShareKey::getKeyword).containsExactly("keep");
assertThat(real.getUsageDeleted()).isEqualTo(1);
}
@Test
@DisplayName("sync/import:used 不传=不碰使用状态(只同步词库不能把后台已有使用记录删掉)")
void syncImportLeavesUsageUntouchedWhenUsedFlagOmitted() {
KeywordShareSyncImportRequest.Item wordOnly = syncItem("英国", "wraps", null, null, null);
wordOnly.setCategory("衣物鞋类");
KeywordShareSyncResultVo vo = newService(rosterOf(true, "阿武(吴棋龙)"))
.syncImport(syncRequest(List.of(wordOnly)), COMPANY_ID, "kw_share_api");
assertThat(vo.getAdded()).isEqualTo(1);
assertThat(vo.getUsageUpserted()).isZero();
assertThat(vo.getUsageDeleted()).isZero();
verify(keywordUsageMapper, never()).upsertBatch(anyList());
verify(keywordUsageMapper, never()).deleteBatch(any(), anyList());
ArgumentCaptor<List<KeywordShareEntity>> captor = ArgumentCaptor.forClass(List.class);
verify(keywordShareMapper).upsertBatchFromSync(captor.capture());
assertThat(captor.getValue().get(0).getCategory()).isEqualTo("衣物鞋类");
}
@Test
@DisplayName("sync/import:写侧按 500 行分片,不把整批塞进一条 SQL 的占位符里")
void syncImportShardsWrites() {
List<KeywordShareSyncImportRequest.Item> items = new java.util.ArrayList<>();
for (int i = 0; i < 1200; i++) {
items.add(syncItem("英国", "kw-" + i, true, "阿武(吴棋龙)", "2026-10-01T08:00:00"));
}
KeywordShareSyncResultVo vo = newService(rosterOf(true, "阿武(吴棋龙)"))
.syncImport(syncRequest(items), COMPANY_ID, "kw_share_api");
assertThat(vo.getAdded()).isEqualTo(1200);
ArgumentCaptor<List<KeywordShareEntity>> wordCaptor = ArgumentCaptor.forClass(List.class);
verify(keywordShareMapper, org.mockito.Mockito.times(3)).upsertBatchFromSync(wordCaptor.capture());
assertThat(wordCaptor.getAllValues()).extracting(List::size).containsExactly(500, 500, 200);
ArgumentCaptor<List<KeywordUsageEntity>> usageCaptor = ArgumentCaptor.forClass(List.class);
verify(keywordUsageMapper, org.mockito.Mockito.times(3)).upsertBatch(usageCaptor.capture());
assertThat(usageCaptor.getAllValues()).extracting(List::size).containsExactly(500, 500, 200);
}
@Test
@DisplayName("sync/import 的 UPSERT SQL:类目非空才覆盖,且更新分支不得改写添加人与添加时间")
void syncUpsertKeepsCategoriesAndProvenance() throws Exception {
String xml = Files.readString(Path.of(
"src/main/resources/mapper/keywordshare/KeywordShareMapper.xml"), StandardCharsets.UTF_8);
String upsert = xml.substring(xml.indexOf("<insert id=\"upsertBatchFromSync\">"));
assertThat(upsert).contains("ON DUPLICATE KEY UPDATE")
.contains("category = COALESCE(NULLIF(VALUES(category), ''), category)")
.contains("sub_category = COALESCE(NULLIF(VALUES(sub_category), ''), sub_category)")
.doesNotContain("${");
// 更新分支只碰类目/释义/类型/来源:user_name、add_time 是历史归属,同步无权改写
String updateBranch = upsert.substring(upsert.indexOf("ON DUPLICATE KEY UPDATE"));
assertThat(updateBranch).doesNotContain("user_name =")
.doesNotContain("add_time =");
}
}