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
@@ -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 的现状("这不是简单单表"的证据),文件名 → 条数: