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
@@ -0,0 +1,36 @@
package com.nanri.aiimage.config;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import java.util.ArrayList;
import java.util.List;
/**
* 五国关键词客户端同步({@code /api/keyword-share/sync/import})的服务端参数。
*
* <p>存在的主要理由:工作台按对接文档口径使用**共享专用 API 账号**,而 {@code keyword_usage.user_name}
* 是「谁用了哪个词」的唯一出处。若一律取 token 账号名,多人使用会被记成同一个人,后台按使用者筛选
* 就失去意义;若无条件信任客户端自报姓名,又会把「阿武(扶金凡)/阿武(吴棋龙)」这类同音异写
* 直接灌进留痕表。名单校验是这两者之间的收口:命中名单才按自报姓名落库。</p>
*/
@Data
@ConfigurationProperties(prefix = "aiimage.keyword-share-sync")
public class KeywordShareSyncProperties {
/**
* 可信操作人姓名名单(真人显示名,与 {@code keyword_usage.user_name} 同形)。
* 比对时两侧都做 trim + 全角括号归一,所以名单里写「阿武(吴棋龙)」也能匹配半角写法。
*/
private List<String> usedUsers = new ArrayList<>();
/**
* 名单外姓名的处置。
* <ul>
* <li>{@code false}(默认):放行自报姓名,只在响应里计数回报——首次上线时名单还没填,
* 直接回退会把全部记录静默改写成账号名,比现状更糟;</li>
* <li>{@code true}:名单外一律回退为本次调用的账号名,并计入 {@code usedUserFallback}。</li>
* </ul>
*/
private boolean strict = false;
}
@@ -4,6 +4,6 @@ import org.springframework.boot.context.properties.EnableConfigurationProperties
import org.springframework.context.annotation.Configuration;
@Configuration
@EnableConfigurationProperties({OssProperties.class, TransientStorageProperties.class, StorageProperties.class, BrandProgressProperties.class, DeleteBrandProgressProperties.class, BrandCheckProperties.class, ZiniaoProperties.class, ModuleCleanupProperties.class, TaskPressureProperties.class, TaskImageCacheCleanupProperties.class, AppearancePatentProperties.class, SimilarAsinProperties.class, ImageVideoProperties.class, InstanceRoutingProperties.class, CapacityPlanProperties.class, UserSecretProperties.class, NotificationProperties.class, DeviceLogOssProperties.class, CollectDataBrandRecheckProperties.class, ClientCredentialProperties.class, CostGuardProperties.class})
@EnableConfigurationProperties({OssProperties.class, TransientStorageProperties.class, StorageProperties.class, BrandProgressProperties.class, DeleteBrandProgressProperties.class, BrandCheckProperties.class, ZiniaoProperties.class, ModuleCleanupProperties.class, TaskPressureProperties.class, TaskImageCacheCleanupProperties.class, AppearancePatentProperties.class, SimilarAsinProperties.class, ImageVideoProperties.class, InstanceRoutingProperties.class, CapacityPlanProperties.class, UserSecretProperties.class, NotificationProperties.class, DeviceLogOssProperties.class, CollectDataBrandRecheckProperties.class, ClientCredentialProperties.class, CostGuardProperties.class, KeywordShareSyncProperties.class})
public class PropertiesConfig {
}