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
@@ -131,3 +131,8 @@ AIIMAGE_ZINIAO_SESSION_TTL_HOURS=2
AIIMAGE_ZINIAO_SHOPS_CACHE_MINUTES=30
AIIMAGE_ZINIAO_CONNECT_TIMEOUT_SECONDS=5
AIIMAGE_ZINIAO_READ_TIMEOUT_SECONDS=15
# 工作台客户端关键词全量同步(POST /api/keyword-share/sync/import)。
# 客户端每行自报真实使用人,服务端只接受名单内姓名并按名单写法落库;名单为空时必须保持 strict=false。
AIIMAGE_KEYWORD_SHARE_SYNC_STRICT=false
AIIMAGE_KEYWORD_SHARE_SYNC_USED_USERS=
@@ -260,6 +260,12 @@ aiimage:
cron: ${AIIMAGE_MODULE_CLEANUP_CRON:0 0 0 * * *}
retention-days: ${AIIMAGE_MODULE_CLEANUP_RETENTION_DAYS:7}
module-types: ${AIIMAGE_MODULE_CLEANUP_MODULE_TYPES:DEDUPE,SPLIT,CONVERT,DELETE_BRAND,PRODUCT_RISK_RESOLVE,PRICE_TRACK,SHOP_MATCH,PATROL_DELETE,QUERY_ASIN,WITHDRAW,APPEARANCE_PATENT,SIMILAR_ASIN,COLLECT_DATA}
# 工作台客户端全量同步(POST /api/keyword-share/sync/import)。客户端每行自报真实使用人,
# 服务端只接受名单内姓名、并统一按名单里那份写法落库(避免全/半角括号把同一个人拆成两个使用者)。
# 名单为空时必须保持 strict=false:否则首次上线会把全部记录静默改写成同步账号名,比现状更糟。
keyword-share-sync:
strict: ${AIIMAGE_KEYWORD_SHARE_SYNC_STRICT:false}
used-users: ${AIIMAGE_KEYWORD_SHARE_SYNC_USED_USERS:}
# 以下为各业务表的保留期清理(2026-09-16 统一补齐):这些表此前只增不删,
# 或只有"读的时候顺手删一行"这类碰运气的清理。全部按天分批删除、带分布式锁单实例执行。
device-log:
@@ -36,8 +36,9 @@
</select>
<select id="selectRows" resultType="com.nanri.aiimage.modules.keywordshare.model.vo.KeywordShareRowVo">
<!-- used_user 别名不可省:VO 属性叫 usedUser,驼峰映射只会把 user_name 认成不存在的 userName。 -->
SELECT k.id, k.country, k.keyword, k.chinese, k.category, k.sub_category, k.category_l3, k.category_l4,
(u.country IS NOT NULL) AS used, u.used_time, u.user_name
(u.country IS NOT NULL) AS used, u.used_time, u.user_name AS used_user
FROM <include refid="usageJoin"/>
WHERE <include refid="filterConds"/>
ORDER BY (u.country IS NULL) ASC, u.used_time ASC
@@ -46,7 +47,7 @@
<select id="selectRandomUnused" resultType="com.nanri.aiimage.modules.keywordshare.model.vo.KeywordShareRowVo">
SELECT k.id, k.country, k.keyword, k.chinese, k.category, k.sub_category, k.category_l3, k.category_l4,
(u.country IS NOT NULL) AS used, u.used_time, u.user_name
(u.country IS NOT NULL) AS used, u.used_time, u.user_name AS used_user
FROM <include refid="usageJoin"/>
WHERE <include refid="filterConds"/>
ORDER BY RAND()
@@ -135,4 +136,28 @@
#{row.subCategory}, #{row.categoryL3}, #{row.categoryL4}, #{row.userName}, #{row.addTime}, #{row.companyId})
</foreach>
</insert>
<!-- 客户端全量同步专用 UPSERT。与 insertBatchIgnore 的分工:那条只补新词、重复行静默跳过;
这条要把客户端本地那份「四级类目」写进已存在的行——add() 从不设类目,主库存量行的类目是空的。
命中 uk_comp_cw 时只覆盖非空值(COALESCE(NULLIF(...))):客户端是四级类目的唯一权威源,
但一次不带类目的同步不该把已导入的类目永久打回空串,所以「主动清空」不走这条路。
user_name/add_time(添加人与添加时间)在更新分支一律不动:那是历史归属,不由同步改写。 -->
<insert id="upsertBatchFromSync">
INSERT INTO keyword_share
(country, keyword, chinese, ktype, source, category, sub_category, category_l3, category_l4,
user_name, add_time, company_id)
VALUES
<foreach collection="rows" item="row" separator=",">
(#{row.country}, #{row.keyword}, #{row.chinese}, #{row.ktype}, #{row.source}, #{row.category},
#{row.subCategory}, #{row.categoryL3}, #{row.categoryL4}, #{row.userName}, #{row.addTime}, #{row.companyId})
</foreach>
ON DUPLICATE KEY UPDATE
chinese = COALESCE(NULLIF(VALUES(chinese), ''), chinese),
ktype = COALESCE(NULLIF(VALUES(ktype), ''), ktype),
source = COALESCE(NULLIF(VALUES(source), ''), source),
category = COALESCE(NULLIF(VALUES(category), ''), category),
sub_category = COALESCE(NULLIF(VALUES(sub_category), ''), sub_category),
category_l3 = COALESCE(NULLIF(VALUES(category_l3), ''), category_l3),
category_l4 = COALESCE(NULLIF(VALUES(category_l4), ''), category_l4)
</insert>
</mapper>