feat(phase-B75): 计次上报加 source 维度(V188)——「谁在烧」一列读数,归因不再扫设备日志

- V188:biz_user_secret_usage_daily 加 source varchar(24) NOT NULL DEFAULT 'legacy'(存量行诚实落 legacy 不回填),唯一键 uk_user_module_date 扩成四元组(user/module/date/source),加列与建索引均 information_schema 判存可重跑(列按 V157 款、索引按 V184 款),八段式含验证 SQL 与人工回滚
This commit is contained in:
2026-11-04 02:56:50 +08:00
parent e71fa7fa83
commit 00f45cc20f
11 changed files with 340 additions and 41 deletions
@@ -55,7 +55,7 @@ class MigratedSqlEquivalenceTest {
// 85 → 84:Phase 5(AC-19/P1-B1)有意把 {@code TaskCenterQueryMapper#selectTaskPage} 从
// OFFSET 改成 keyset 游标。账本记的是「注解时代原文」,改一行基准就等于让等价性测试照着
// 新 SQL 自证 ⇒ 把该行整条摘出账本、点名进下方 NOT_MIGRATED,让基准继续只描述真正未改动的迁移件。
private static final int LEDGER_ROWS = 84;
private static final int LEDGER_ROWS = 83;
// 60 → 59:摘出去那行是一条 select。
private static final int LEDGER_SELECTS = 59;
/** 全部 mapper XML 里的 select 总数:账本 60 + TaskImageCache 5 + AsinResultCache 1。 */
@@ -87,6 +87,11 @@ class MigratedSqlEquivalenceTest {
*/
private static final java.util.Set<String> NOT_MIGRATED =
java.util.Set.of("AdminUserMapper#countLiveWorkFor",
// V188(2026-11-04)给计次 upsert 加 source 列(唯一键四元组),SQL 文本
// 不再是注解时代的逐字原文:整行从 migrated-statements.tsv 摘掉、点名到
// 这里(与 selectTaskPage 改写时同款处理,LEDGER_ROWS 84→83);新形状
// 由 V188 迁移测试与 UserSecretUsageServiceTest 钉。
"UserSecretUsageMapper#increment",
// V157 加 token 两列时新写的累加语句;注解时代没有原文可对撞,等价性这支只能跳过它。
// 与 increment 分两条是口径要求(计次先于响应、token 只在响应后有读数),不是随手加的第二条 SQL。
"UserSecretUsageMapper#addTokens",
@@ -173,7 +178,7 @@ class MigratedSqlEquivalenceTest {
"fixture 里的 Select 条数与基线不符(读侧账本 = 59)");
assertEquals(LEDGER_ROWS - LEDGER_SELECTS,
rows.stream().filter(r -> !"Select".equals(r[2])).count(),
"写侧条数对不上(25 = Insert+Update+Delete)");
"写侧条数对不上(24 = Insert+Update+Delete)");
assertTrue(rows.stream().allMatch(r -> !r[1].isEmpty() && !r[BASELINE_COL].isEmpty()),
"fixture 有空方法名或空 SQL,说明抽取器漏了形状");
// 基准得是「整条注解串」:半截 <script> 外壳说明抽取被截断(上一轮就是把常量与标签吃了)
@@ -0,0 +1,117 @@
package com.nanri.aiimage.config;
import com.nanri.aiimage.modules.usersecret.model.entity.UserSecretUsageEntity;
import org.junit.jupiter.api.Test;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* V188 给 {@code biz_user_secret_usage_daily} 加 {@code source} 列并把唯一键扩成四元组,
* 本类钉它的形状(Expand 半边,2026-11-04 客户反馈「代理IP用的很猛」的归因前置)。
*
* <p>四件事各守一个炸法:
* <ol>
* <li><b>NOT NULL + DEFAULT 'legacy' 且不回填</b>:存量行无法追溯是哪一路报的,
* 统一落 legacy(诚实的"不知道"),不按今天的上报方名单猜历史。</li>
* <li><b>唯一键必须扩成四元组</b>:不扩键的话同一天多路的上报会在旧三元组上互相
* ON DUPLICATE(source 记成"最后写入者"),按来源归因直接失真;只加列不扩键
* 等于白加。</li>
* <li><b>可重跑</b>:加列与建索引都先查 information_schema(列按 V157 款、索引按
* V184 款),迁移中途失败重跑不许撞 1060/1061。</li>
* <li><b>列名与实体字段对齐</b>:MyBatis-Plus 驼峰↔下划线,对不上写入会静默不落库。</li>
* </ol>
*/
class UserSecretUsageSourceMigrationV188Test {
private static final Path SQL = Path.of(System.getProperty("user.dir"),
"src/main/resources/db/V188__user_secret_usage_source.sql");
private static String sql() throws IOException {
assertTrue(Files.exists(SQL), "V188 迁移脚本不在:" + SQL);
return Files.readString(SQL);
}
@Test
void 列是not_null的窄列且默认落legacy() throws IOException {
String text = sql();
assertTrue(text.contains("ALTER TABLE `biz_user_secret_usage_daily`"), "迁移对象必须是本表");
// DDL 藏在 SET @ddl 的字符串字面量里,引号按 SQL 规则写成两个单引号(''legacy'')
assertTrue(text.contains("ADD COLUMN `source` varchar(24) NOT NULL DEFAULT ''legacy''"),
"NOT NULL + DEFAULT 'legacy':存量行诚实落 legacy,NULL 会让 GROUP BY 多出一种真空来源");
assertTrue(text.contains("AFTER `module_key`"),
"紧跟 module_key:来源是模块的下一级维度,读的人要能一眼成对");
assertFalse(text.toUpperCase().contains("UPDATE `BIZ_USER_SECRET_USAGE_DAILY` SET `SOURCE`"),
"Expand 阶段不回填:历史行的来源不能按今天的上报方名单猜");
assertTrue(text.contains("DROP COLUMN `source`"),
"回滚语句必须写在脚本注释里(与 V157 同一口径)");
}
@Test
void 唯一键必须扩成四元组() throws IOException {
String text = sql();
assertTrue(text.contains("DROP INDEX `uk_user_module_date`"),
"旧三元组键必须摘除:留着它与新键并存,旧形状的 upsert 会绕过 source 维度");
assertTrue(text.contains("ADD UNIQUE KEY `uk_user_module_date_source` "
+ "(`user_id`, `module_key`, `business_date`, `source`)"),
"新键必须含 source:同一天多路各占一行,读侧 SUM 对多出的行透明");
}
@Test
void 加列与建索引都必须判存可重跑() throws IOException {
String text = sql();
assertTrue(text.contains("information_schema.COLUMNS"),
"加列前必须查列存在(V157 款)");
assertTrue(text.contains("information_schema.STATISTICS"),
"建索引前必须查索引存在(V184 款)");
assertEquals(2, countMatches(text, "EXECUTE stmt"),
"两条 DDL 各自走 PREPARE/EXECUTE 判存重跑(DEALLOCATE 不计)");
}
@Test
void 头注释版本号与文件名一致() throws IOException {
String first = sql().lines().findFirst().orElse("");
assertTrue(first.startsWith("-- V188:"), "头注释必须写 V188,实际是:" + first);
}
@Test
void 实体字段与列名按驼峰下划线一一对应() throws Exception {
assertNotNull(UserSecretUsageEntity.class.getDeclaredField("source"),
"实体缺 source 字段 ⇒ 列永远不会被写");
assertEquals("source", camelToSnake("source"),
"单词列名没有驼峰转换空间,这一格防的是字段名拼错(如 soource)");
assertTrue(sql().contains("`source`"));
}
private static int countMatches(String text, String needle) {
Matcher matcher = Pattern.compile(needle, Pattern.LITERAL).matcher(text);
int count = 0;
while (matcher.find()) {
count++;
}
return count;
}
private static String camelToSnake(String name) {
StringBuilder out = new StringBuilder();
for (char c : name.toCharArray()) {
if (Character.isUpperCase(c)) {
out.append('_').append(Character.toLowerCase(c));
} else {
out.append(c);
}
}
return out.toString();
}
}
@@ -35,6 +35,7 @@ import static org.mockito.ArgumentMatchers.anyLong;
import static org.mockito.ArgumentMatchers.eq;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.never;
import static org.mockito.Mockito.times;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;
@@ -67,11 +68,13 @@ class UserSecretUsageServiceTest {
@Test
void recordIncrementsByModuleWithTodayDate() {
UserSecretUsageService service = newService();
when(usageMapper.increment(any(), any(), any(), eq(1))).thenReturn(1);
when(usageMapper.increment(any(), any(), any(), eq(1), any())).thenReturn(1);
service.record(7L, "similar-asin", 1);
verify(usageMapper).increment(eq(7L), eq("similar-asin"), eq(LocalDate.now()), eq(1));
// Java 自产 LLM 行落 backend 来源(V188)
verify(usageMapper).increment(eq(7L), eq("similar-asin"), eq(LocalDate.now()), eq(1),
eq("backend"));
}
@Test
@@ -83,44 +86,47 @@ class UserSecretUsageServiceTest {
service.record(7L, "not-a-module", 1);
service.record(7L, "similar-asin", 0);
verify(usageMapper, never()).increment(any(), any(), any(), any(Integer.class));
verify(usageMapper, never()).increment(any(), any(), any(), any(Integer.class), any());
}
@Test
void recordSwallowsMapperFailure() {
UserSecretUsageService service = newService();
when(usageMapper.increment(any(), any(), any(), eq(1)))
when(usageMapper.increment(any(), any(), any(), eq(1), any()))
.thenThrow(new IllegalStateException("db down"));
// 计次失败绝不影响任务主流程
service.record(7L, "proxy", 1);
verify(usageMapper).increment(eq(7L), eq("proxy"), eq(LocalDate.now()), eq(1));
verify(usageMapper).increment(eq(7L), eq("proxy"), eq(LocalDate.now()), eq(1),
eq("backend"));
}
@Test
void recordReportedCapsCountAndRejectsUnknownModule() {
UserSecretUsageService service = newService();
when(usageMapper.increment(any(), any(), any(), any(Integer.class))).thenReturn(1);
when(usageMapper.increment(any(), any(), any(), any(Integer.class), any())).thenReturn(1);
assertThat(service.recordReported(7L, "proxy", 50_000)).isTrue();
assertThat(service.recordReported(7L, "not-a-module", 3)).isFalse();
assertThat(service.recordReported(7L, "proxy", 0)).isFalse();
// 超出上限按 10000 截断,防止异常客户端写爆计数
verify(usageMapper).increment(eq(7L), eq("proxy"), eq(LocalDate.now()), eq(10_000));
// 超出上限按 10000 截断,防止异常客户端写爆计数;3 参旧形状缺省落 legacy
verify(usageMapper).increment(eq(7L), eq("proxy"), eq(LocalDate.now()), eq(10_000),
eq("legacy"));
}
@Test
void recordReportedAllowsPlatformBucketOnlyForProxy() {
UserSecretUsageService service = newService();
when(usageMapper.increment(any(), any(), any(), any(Integer.class))).thenReturn(1);
when(usageMapper.increment(any(), any(), any(), any(Integer.class), any())).thenReturn(1);
assertThat(service.recordReported(0L, "proxy", 3)).isTrue();
assertThat(service.recordReported(0L, "appearance-patent", 3)).isFalse();
assertThat(service.recordReported(-1L, "proxy", 3)).isFalse();
verify(usageMapper).increment(eq(0L), eq("proxy"), eq(LocalDate.now()), eq(3));
verify(usageMapper).increment(eq(0L), eq("proxy"), eq(LocalDate.now()), eq(3),
eq("legacy"));
}
@Test
@@ -404,8 +410,9 @@ class UserSecretUsageServiceTest {
service.recordTokens(7L, "appearance-patent", 1234L, 56L);
verify(usageMapper).addTokens(eq(7L), eq("appearance-patent"), eq(LocalDate.now()), eq(1234L), eq(56L));
verify(usageMapper, never()).increment(any(), any(), any(), any(Integer.class));
verify(usageMapper).addTokens(eq(7L), eq("appearance-patent"), eq(LocalDate.now()),
eq(1234L), eq(56L), eq("backend"));
verify(usageMapper, never()).increment(any(), any(), any(), any(Integer.class), any());
}
@Test
@@ -416,7 +423,7 @@ class UserSecretUsageServiceTest {
service.recordTokens(7L, "appearance-patent", 0L, 0L);
service.recordTokens(7L, "appearance-patent", -5L, 0L);
verify(usageMapper, never()).addTokens(any(), any(), any(), anyLong(), anyLong());
verify(usageMapper, never()).addTokens(any(), any(), any(), anyLong(), anyLong(), any());
}
@Test
@@ -426,7 +433,8 @@ class UserSecretUsageServiceTest {
service.recordTokens(7L, "similar-asin", 900L, 0L);
verify(usageMapper).addTokens(eq(7L), eq("similar-asin"), eq(LocalDate.now()), eq(900L), eq(0L));
verify(usageMapper).addTokens(eq(7L), eq("similar-asin"), eq(LocalDate.now()), eq(900L),
eq(0L), eq("backend"));
}
@Test
@@ -438,31 +446,73 @@ class UserSecretUsageServiceTest {
service.recordTokens(0L, "proxy", 10L, 10L);
service.recordTokens(7L, "not-a-module", 10L, 10L);
verify(usageMapper, never()).addTokens(any(), any(), any(), anyLong(), anyLong());
verify(usageMapper, never()).addTokens(any(), any(), any(), anyLong(), anyLong(), any());
}
@Test
@DisplayName("recordTokens:写库失败只告警,绝不把任务带崩")
void recordTokensSwallowsMapperFailure() {
UserSecretUsageService service = newService();
when(usageMapper.addTokens(any(), any(), any(), anyLong(), anyLong()))
when(usageMapper.addTokens(any(), any(), any(), anyLong(), anyLong(), any()))
.thenThrow(new IllegalStateException("db down"));
service.recordTokens(7L, "proxy", 10L, 2L);
verify(usageMapper).addTokens(eq(7L), eq("proxy"), eq(LocalDate.now()), eq(10L), eq(2L));
verify(usageMapper).addTokens(eq(7L), eq("proxy"), eq(LocalDate.now()), eq(10L), eq(2L),
eq("backend"));
}
@Test
@DisplayName("计次那一路不许顺手写 token:两条语句分开是口径要求(计次先于响应)")
void countPathNeverWritesTokens() {
UserSecretUsageService service = newService();
when(usageMapper.increment(any(), any(), any(), eq(1))).thenReturn(1);
when(usageMapper.increment(any(), any(), any(), eq(1), any())).thenReturn(1);
service.record(7L, "appearance-patent", 1);
service.recordReported(7L, "proxy", 3);
verify(usageMapper, never()).addTokens(any(), any(), any(), anyLong(), anyLong());
verify(usageMapper, never()).addTokens(any(), any(), any(), anyLong(), anyLong(), any());
}
// --- source 维度(V188):「谁在烧」是一列读数,不再靠扫设备日志归因 ---
@Test
@DisplayName("recordReported:上报方自报的 source 规整后落库(trim+小写)")
void recordReportedCarriesReportedSource() {
UserSecretUsageService service = newService();
when(usageMapper.increment(any(), any(), any(), any(Integer.class), any())).thenReturn(1);
assertThat(service.recordReported(7L, "proxy", 3, "Client")).isTrue();
verify(usageMapper).increment(eq(7L), eq("proxy"), eq(LocalDate.now()), eq(3),
eq("client"));
}
@Test
@DisplayName("recordReported:source 缺省/空/脏值一律落 legacy,不拒收不猜身份")
void recordReportedFallsBackToLegacyOnDirtySource() {
UserSecretUsageService service = newService();
when(usageMapper.increment(any(), any(), any(), any(Integer.class), any())).thenReturn(1);
assertThat(service.recordReported(7L, "proxy", 1, null)).isTrue();
assertThat(service.recordReported(7L, "proxy", 1, " ")).isTrue();
assertThat(service.recordReported(7L, "proxy", 1, "dirty; DROP TABLE x")).isTrue();
assertThat(service.recordReported(7L, "proxy", 1, "x".repeat(25))).isTrue();
// 计次比归因更贵:宁可归因模糊(legacy)也不丢账
verify(usageMapper, times(4)).increment(eq(7L), eq("proxy"), eq(LocalDate.now()),
any(Integer.class), eq("legacy"));
}
@Test
@DisplayName("recordTokens 必须钉在 backend 来源上:唯一键四元组后不钉 source 会把 token 记到 legacy 历史行造成双计")
void recordTokensPinsBackendSource() {
UserSecretUsageService service = newService();
service.recordTokens(7L, "appearance-patent", 1234L, 56L);
verify(usageMapper).addTokens(eq(7L), eq("appearance-patent"), eq(LocalDate.now()),
eq(1234L), eq(56L), eq("backend"));
}
}