diff --git a/backend-java/src/main/java/com/nanri/aiimage/common/service/CompanyScopeSupport.java b/backend-java/src/main/java/com/nanri/aiimage/common/service/CompanyScopeSupport.java new file mode 100644 index 000000000..3517a57ca --- /dev/null +++ b/backend-java/src/main/java/com/nanri/aiimage/common/service/CompanyScopeSupport.java @@ -0,0 +1,49 @@ +package com.nanri.aiimage.common.service; + +import com.nanri.aiimage.common.exception.BusinessException; +import com.nanri.aiimage.common.mapper.AdminUserMapper; +import com.nanri.aiimage.common.model.entity.AdminUserEntity; +import lombok.RequiredArgsConstructor; +import org.springframework.stereotype.Service; + +/** + * 按账号解析归属公司(二期设计文档 §3.1)——数据出口只认这一个入口。 + * + *

一期"业务表零 DDL"靠 {@code user_id → users.company_id} 派生;本期两张规则库表破例物化了 + * {@code company_id}(§2.2),但归属仍然从账号解析,物化列只是把它固定下来、好让唯一键与 + * 消费侧的集合查询用得上。

+ * + *

取不到公司一律抛,不返回 null:调用方一旦把 null 传进实体,MyBatis-Plus 会跳过该列, + * 落库时被 V145 的 {@code DEFAULT 1} 静默兜住——那是"归属失真且不报错"的成因(§6.3)。

+ */ +@Service +@RequiredArgsConstructor +public class CompanyScopeSupport { + + private final AdminUserMapper adminUserMapper; + + public Long requireCompanyId(Long userId) { + if (userId == null || userId <= 0) { + throw new BusinessException("归属账号不能为空"); + } + return requireCompanyId(adminUserMapper.selectById(userId)); + } + + public Long requireCompanyId(AdminUserEntity user) { + if (user == null) { + throw new BusinessException("归属账号不存在"); + } + Long companyId = user.getCompanyId(); + if (companyId == null || companyId <= 0) { + throw new BusinessException(403, "当前账号没有所属公司,无法按公司读写数据"); + } + return companyId; + } + + /** 行级归属闸门:跨公司写/删的第一道,消息由调用方给(前端按它显示,别在这里编文案)。 */ + public void assertSameCompany(Long operatorCompanyId, Long rowCompanyId, String deniedMessage) { + if (rowCompanyId == null || !rowCompanyId.equals(operatorCompanyId)) { + throw new BusinessException(403, deniedMessage); + } + } +} diff --git a/backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyScopeSupportTest.java b/backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyScopeSupportTest.java new file mode 100644 index 000000000..8a7a1ca08 --- /dev/null +++ b/backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyScopeSupportTest.java @@ -0,0 +1,76 @@ +package com.nanri.aiimage.common.service; + +import com.nanri.aiimage.common.exception.BusinessException; +import com.nanri.aiimage.common.mapper.AdminUserMapper; +import com.nanri.aiimage.common.model.entity.AdminUserEntity; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.mockito.InjectMocks; +import org.mockito.Mock; +import org.mockito.junit.jupiter.MockitoExtension; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatThrownBy; +import static org.mockito.Mockito.when; + +/** + * 二期数据隔离的唯一取公司出口(设计文档 §3.1)。 + * + *

这里最重要的不是"能取到公司",而是取不到时必须炸:漏传 company_id 一旦退回 null, + * 下游就落进 V145 的列 DEFAULT=1,第二家公司开通后每个漏传都会静默归到厦门米椿花(§6.3 / §11.2)。

+ */ +@ExtendWith(MockitoExtension.class) +class CompanyScopeSupportTest { + + @Mock AdminUserMapper adminUserMapper; + @InjectMocks CompanyScopeSupport companyScope; + + @Test + void resolvesCompanyIdFromUserIdThroughUsersTable() { + AdminUserEntity user = new AdminUserEntity(); + user.setId(7L); + user.setCompanyId(3L); + when(adminUserMapper.selectById(7L)).thenReturn(user); + + assertThat(companyScope.requireCompanyId(7L)).isEqualTo(3L); + } + + @Test + void nullUserIdFailsFastInsteadOfReturningNull() { + assertThatThrownBy(() -> companyScope.requireCompanyId((Long) null)) + .isInstanceOf(BusinessException.class) + .hasMessageContaining("归属账号"); + } + + @Test + void unknownUserFailsFast() { + when(adminUserMapper.selectById(99L)).thenReturn(null); + + assertThatThrownBy(() -> companyScope.requireCompanyId(99L)) + .isInstanceOf(BusinessException.class) + .hasMessageContaining("归属账号不存在"); + } + + /** V144 之后 users.company_id 已无 DEFAULT:手工 SQL 或旧 dump 重建都可能留下 NULL。 */ + @Test + void userWithoutCompanyFailsFastWith403() { + AdminUserEntity user = new AdminUserEntity(); + user.setId(8L); + user.setCompanyId(null); + when(adminUserMapper.selectById(8L)).thenReturn(user); + + assertThatThrownBy(() -> companyScope.requireCompanyId(8L)) + .isInstanceOf(BusinessException.class) + .hasMessageContaining("没有所属公司"); + } + + @Test + void assertSameCompanyRejectsForeignAndMissingRowCompany() { + companyScope.assertSameCompany(1L, 1L, "无权操作其他公司的数据"); + + assertThatThrownBy(() -> companyScope.assertSameCompany(1L, 2L, "无权操作其他公司的数据")) + .isInstanceOf(BusinessException.class).hasMessageContaining("其他公司"); + assertThatThrownBy(() -> companyScope.assertSameCompany(1L, null, "无权操作其他公司的数据")) + .isInstanceOf(BusinessException.class).hasMessageContaining("其他公司"); + } +} diff --git a/docs/plans/18-brand-dedupe-company-isolation.md b/docs/plans/18-brand-dedupe-company-isolation.md new file mode 100644 index 000000000..d0eddb5c6 --- /dev/null +++ b/docs/plans/18-brand-dedupe-company-isolation.md @@ -0,0 +1,1573 @@ +# 品牌库 / 去重库 按公司隔离(二期)实施计划 + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 把 `biz_invalid_asin_data`(后台「品牌数据库」)与 `biz_dedupe_total_data`(「去重数据汇总」)从"全平台共享一套规则库"改成"每公司一套",并在写入、消费、读取三条链路上都带上 `company_id`。 + +**Architecture:** 新增中央出口 `CompanyScopeSupport`(由 `userId → users.company_id` 解析归属,查不到就 fail-fast,绝不返回 null);V145 在这两张表上破例物化 `company_id`(并把 `biz_invalid_asin_data` 补上 `uploader_user_id` 作审计锚点),唯一键换成以 `company_id` 打头的复合键;写侧每个出口显式带归属、不依赖 DB DEFAULT;消费侧四个裸 SQL 出口各叠 `company_id`;读侧在既有分组范围外面叠一层公司范围。 + +**Tech Stack:** Java 21 / Spring Boot 3.3.9 / MyBatis-Plus 3.5.7(`LambdaQueryWrapper` + 注解 SQL)/ Flyway / MySQL 8 / JUnit 5 + Mockito + AssertJ;Vue 3 + TS(`admin-frontend-vue`)+ `node --test`。 + +**Spec:** `crawler-plugin/docs/ops/brand-dedupe-company-isolation-design-2026-10-04.md`(已批准)。本计划按 § 编号引用它,实施时两份一起读。 + +**基线(2026-10-04 14:0x 实查,不是记忆值):** +- `crawler-plugin` 本地 HEAD = `9e7c1003`;生产在跑的是 jar `e42b37c1…`(两台同版)、**Flyway 已应用到 144**、admin-vue `20261004-132659`。 +- 工作区里**不属于本计划**的未提交改动:`admin-frontend-vue/tests/task-43.test.ts`(另一路会话)、`backend-java/tmp-probe.txt`、`tmp/`。别把它们卷进提交,也别回退。 +- 本计划自带一笔 `.gitignore` 改动(已落盘):`docs/plans/` 与 `backend-java/docs/plans/` 从"不入库"改为入库,所以 `docs/plans/`(17 个文件)和 `backend-java/docs/plans/`(13 个)现在是未跟踪但可见状态;它们不是本计划的产物,提交前先 `git status` 分清。 + +--- + +## Global Constraints(每个任务都受这些约束,逐字照抄自 spec 与既有坑) + +1. **不许原地改已应用到生产的迁移。** V142(校验和 `1152261840`)、V143(`1539570901`)已封死;V144 已在生产应用,其校验和由 Task 2 Step 1 实查后补进冻结清单。`spring.flyway.validate-on-migrate=true` 是硬编码,改字节 = 下次启动两台 java 都起不来。 +2. **迁移逐条幂等**(spec §5.1):`ADD COLUMN`/`ADD INDEX` 先查 `information_schema` 再 `PREPARE`,`DROP INDEX` 先判存在,`UPDATE` 用 `WHERE ... IS NULL` 限定。理由:`flyway repair` + 重启会从第一条语句重跑整个文件,而 MySQL DDL 不进事务。 +3. **回滚不写成 `V146`**(spec §5.6):`src/main/resources/db/` 是 Flyway 扫描路径,版本化回滚等于让人工决定自己发生。回滚 = `backend-java/docs/rollback-V145-company-scope.sql`。 +4. **取号看盘点文档**:当前最大 `V144`、143 个文件,`docs/migration-inventory.md` 已写明"后续新增迁移从 **V145** 起取号"。不许为没写出来的迁移预留号段(1..max 留洞会让 `MigrationInventoryTest#integerVersionsSequentialFromOne` 红)。 +5. **写侧不得依赖数据库 `DEFAULT 1` 兜住漏传**(spec §6.3):实体进 mapper 前 `company_id == null` 必须抛异常。这条 DEFAULT 只为混合版本窗口存在(spec §11.2),且失败很安静——`CollectDataInvalidAsinBatchWriter.java:58-60` 会 `catch (RuntimeException) → log.warn` 跳过整批,接口照样返回成功。 +6. **不许用前缀索引迁就长度**(spec §4,依据 `db/V135:6-9`):去重库 `data_value` 的前缀唯一索引会把"前 N 字符相同"的不同值误判为重复。字节预算已算:`uk_company_value_brand` = 8 + 128×4 + 191×4 = **1284 B**;`uk_company_data_value` = 8 + 512×4 = **2056 B**;都 < 3072(DYNAMIC + utf8mb4)。 +7. **两张 jar 必须同版**:后台 `/api` 经主机 B 的 clb 打到两台。**逐节点复验不能打 `0.0.0.0:18080`**(那是 nginx 轮询池),主机 B 的 java 在 `127.0.0.1:19080`。 +8. **不许 `skipTests` 上线**;`mvn test` 全量门禁**禁止与 Nuitka 打包并行**(`TxDurationBenchmarkTest` 会因抢 CPU 假红);主树禁 `git clean`;不许 `git stash`(红线归因用 detached worktree)。 +9. **生产只做只读取证**,任何 `INSERT/UPDATE/DELETE/ALTER` 都只交付命令、由用户执行(既定工作方式)。只读通道 = `scripts/_prod_watch.py:171 db_sections()`(主机 A 业务库,`docker exec -u mysql`,每条 3 秒超时)。 +10. **隔离今天是"部分强度"**(spec §3.2):`/api/collect-data` 在 `config/AdminApiGuardFilter.java:77` 的 `USER_TOOL_PREFIXES` 里,`aiimage.security.user-tool-guard-enabled` 默认 `false`(`:128`),归属由请求参数自报的 `user_id` 决定。本方案防住诚实串扰,防不住伪造 user_id;这条只有阶段B 能闭合,别在文档或提交信息里写成"已隔离"。 +11. **护栏做进代码出口,不写进注释**(spec §10):四支扫描用例 + 每支配变异自证。变异规矩:每轮开跑前所有被注入文件写回 pristine、还原只认注入前读进内存的字节(**不许 `git checkout`**)、CRLF 锚串先对齐行尾、分母只认本轮扫描结果。 +12. **前端是 `admin-frontend-vue`,不是 `frontend-vue`**(`CLAUDE.md` 只写了后者);两页的分组列/筛选已有超管门控(`tests/align-group-visibility.test.ts:23-31`),公司列照同一模式。 + +--- + +## 文件结构总览 + +| 动作 | 文件 | 责任 | +|---|---|---| +| Create | `backend-java/src/main/java/com/nanri/aiimage/common/service/CompanyScopeSupport.java` | 唯一的"按账号取归属公司"出口 + 同公司断言 | +| Create | `backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyScopeSupportTest.java` | Task 1 的失败测试 | +| Create | `backend-java/src/main/resources/db/V145__brand_dedupe_company_scope.sql` | 加列 / 回填 / NOT NULL 闸门 / 唯一键替换 | +| Create | `backend-java/docs/rollback-V145-company-scope.sql` | 人工回滚补丁(不在 Flyway 扫描路径) | +| Create | `backend-java/src/test/java/com/nanri/aiimage/config/CompanyScopeMigrationV145Test.java` | 迁移文件审计(含幂等形态、新旧键、DEFAULT 倒计时哨兵登记) | +| Modify | `backend-java/src/test/java/com/nanri/aiimage/config/CompanyMigrationV144Test.java` | V144 进冻结清单;删掉"V144 应是最大版本"的过期断言 | +| Modify | `backend-java/docs/migration-inventory.md` | 数字、最新版本、取号起点、V144 校验和行 | +| Create | `backend-java/src/main/java/com/nanri/aiimage/modules/invalidasin/service/InvalidAsinAutoWriteScopeResolver.java` | AUTO 路径的三元归属(company/uploader/group)单点解析 | +| Modify | 品牌库:`InvalidAsinDataEntity.java`、`InvalidAsinDataMapper.java`、`InvalidAsinDataService.java`、`InvalidAsinDataController.java`、`InvalidAsinDataItemVo.java` | 写侧带归属 → 读侧放开 MANUAL 硬条件 | +| Modify | 去重库:`DedupeTotalDataEntity.java`、`DedupeTotalDataMapper.java`、`DedupeTotalDataService.java`、`DedupeTotalDataController.java`、`DedupeTotalDataItemVo.java`、`DedupeRunService.java` | 写侧带归属 → 消费侧带公司 → 读侧叠公司 | +| Modify | 消费侧:`CollectDataBatchQuery.java`、`CollectDataInvalidAsinBatchWriter.java`、`CollectDataService.java`、`CollectDataBrandRecheckInjector.java` | 四个裸 SQL 出口叠 `company_id`;删 `filterByExistingAsin` | +| Create | `backend-java/src/test/java/com/nanri/aiimage/modules/company/CompanyScopeWriteOutletTest.java`、`.../CompanyScopeConsumerOutletTest.java`、`.../CompanyScopeReadPathTest.java` | 护栏 2/3/4(源码扫描 + 可跑断言) | +| Modify | `admin-frontend-vue`:`src/pages/asin/asin-filter.ts`、`dedupe-total-filter.ts`、`dedupe-total-export.ts`、`dedupe-total-model.ts`、`DedupeRegistryPage.vue`、`src/pages/invalidasin/invalid-asin-api.ts`、`invalid-asin-model.ts`、`src/pages/asin/AsinInvalidPage.vue` | 公司列 / 公司筛选 / 弹窗联动 | +| Create | `admin-frontend-vue/tests/company-column-asin-pages.test.ts` | 前端公司可见性护栏 | + +**任务↔批次(spec §11.1):** Task 1–4 = 批次 1(线上行为零变化,且开始记归属,**有截止时间**);Task 5–6 = 批次 2(消费侧,隔离真正生效);Task 7–9 = 批次 3(读侧 + 前端);Task 0 与 Task 10 是取证与验收,不产出运行代码。 + +--- + +## Task 0: 上线前生产只读取证(把 spec §5.4 那两个空填上) + +**Files:** 无代码改动;结果写进 Task 2 的迁移头注释与 spec §5.4。 + +**Interfaces:** +- Produces: `invalidAsinRows`、`dedupeRows`(行数)、`v144Checksum`(生产存量校验和)、`dedupeIndexes`(`biz_dedupe_total_data` 现有索引清单)。 + +- [ ] **Step 1: 跑只读探针(四条查询,各 3 秒超时)** + +```bash +cd "D:/todesk/副业/数富AI" && python -c "import sys; sys.path.insert(0,'scripts'); from _prod_watch import db_sections; rows,raw=db_sections([('cnt','SELECT (SELECT COUNT(*) FROM biz_invalid_asin_data) AS invalid_rows, (SELECT COUNT(*) FROM biz_dedupe_total_data) AS dedupe_rows'),('v144','SELECT version, checksum, installed_on FROM flyway_schema_history WHERE version IN (142,143,144) ORDER BY installed_rank'),('idxd','SHOW INDEX FROM biz_dedupe_total_data'),('idxi','SHOW INDEX FROM biz_invalid_asin_data')], 60); [print('@@'+k+chr(10)+chr(10).join(v)) for k,v in rows.items()]" +``` + +- [ ] **Step 2: 验通道而不是验结论** + +`v144` 段必须**同时**出现 142/143/144 三行,且 142 的 checksum 等于 `1152261840`、143 等于 `1539570901`(这两个是已知真值)。若 142/143 对不上或整段为空,说明是通道问题(掩码层吞字符 / 容器名不对 / 结果被 `head -20` 截断),不是"库里没有"。**不许拿一条空结果去下结论。** + +- [ ] **Step 3: 记下三个数** + +行数用于 §5.4 的锁表风险评估(`ADD UNIQUE INDEX` 是 INPLACE 重建,93 万行级要低峰执行);V144 校验和进 Task 2 Step 1。 + +--- + +## Task 1: `CompanyScopeSupport`——二期唯一的取公司出口 + +**Files:** +- Create: `backend-java/src/main/java/com/nanri/aiimage/common/service/CompanyScopeSupport.java` +- Create: `backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyScopeSupportTest.java` + +**Interfaces:** +- Consumes: `common/mapper/AdminUserMapper`(`extends BaseMapper`)、`common/model/entity/AdminUserEntity.java:28 private Long companyId;` +- Produces: + - `Long requireCompanyId(Long userId)` + - `Long requireCompanyId(AdminUserEntity user)` + - `void assertSameCompany(Long operatorCompanyId, Long rowCompanyId, String deniedMessage)` + +**不做(与 spec §3.1 的偏离,写完要回头补 spec):** §3.1 还列了 `memberUserIds(companyId)`。本期三张表的读范围全部沿用既有的**店铺分组**口径(`resolveAccessScope` / `resolveFixedAccessibleGroupId`),没有"按公司枚举成员"的消费方,先不建(YAGNI)。同理**不搬 role**:`super_admin` 判定今天有 5 份平行实现(`AdminAuthSupport.currentRole`、`DedupeTotalDataService:1264-1268`、`InvalidAsinDataController:120`、`CompanyService:198`、`ShopManageService`),在这里再加第 6 份只会让"按 role 豁免"更难收敛,属独立一笔。 + +- [ ] **Step 1: 写失败的测试** + +Create `CompanyScopeSupportTest.java`: + +```java +package com.nanri.aiimage.common.service; + +import com.nanri.aiimage.common.exception.BusinessException; +import com.nanri.aiimage.common.mapper.AdminUserMapper; +import com.nanri.aiimage.common.model.entity.AdminUserEntity; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.mockito.InjectMocks; +import org.mockito.Mock; +import org.mockito.junit.jupiter.MockitoExtension; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatThrownBy; +import static org.mockito.Mockito.when; + +/** + * 二期数据隔离的唯一取公司出口(设计文档 §3.1)。 + * + *

这里最重要的不是"能取到公司",而是取不到时必须炸:漏传 company_id 一旦退回 null, + * 下游就落进 V145 的列 DEFAULT=1,第二家公司开通后每个漏传都会静默归到厦门米椿花(§6.3 / §11.2)。

+ */ +@ExtendWith(MockitoExtension.class) +class CompanyScopeSupportTest { + + @Mock AdminUserMapper adminUserMapper; + @InjectMocks CompanyScopeSupport companyScope; + + @Test + void resolvesCompanyIdFromUserIdThroughUsersTable() { + AdminUserEntity user = new AdminUserEntity(); + user.setId(7L); + user.setCompanyId(3L); + when(adminUserMapper.selectById(7L)).thenReturn(user); + + assertThat(companyScope.requireCompanyId(7L)).isEqualTo(3L); + } + + @Test + void nullUserIdFailsFastInsteadOfReturningNull() { + assertThatThrownBy(() -> companyScope.requireCompanyId((Long) null)) + .isInstanceOf(BusinessException.class) + .hasMessageContaining("归属账号"); + } + + @Test + void unknownUserFailsFast() { + when(adminUserMapper.selectById(99L)).thenReturn(null); + + assertThatThrownBy(() -> companyScope.requireCompanyId(99L)) + .isInstanceOf(BusinessException.class) + .hasMessageContaining("归属账号不存在"); + } + + /** V144 之后 users.company_id 已无 DEFAULT:手工 SQL 或旧 dump 重建都可能留下 NULL。 */ + @Test + void userWithoutCompanyFailsFastWith403() { + AdminUserEntity user = new AdminUserEntity(); + user.setId(8L); + user.setCompanyId(null); + when(adminUserMapper.selectById(8L)).thenReturn(user); + + assertThatThrownBy(() -> companyScope.requireCompanyId(8L)) + .isInstanceOf(BusinessException.class) + .hasMessageContaining("没有所属公司"); + } + + @Test + void assertSameCompanyRejectsForeignAndMissingRowCompany() { + companyScope.assertSameCompany(1L, 1L, "无权操作其他公司的数据"); + + assertThatThrownBy(() -> companyScope.assertSameCompany(1L, 2L, "无权操作其他公司的数据")) + .isInstanceOf(BusinessException.class).hasMessageContaining("其他公司"); + assertThatThrownBy(() -> companyScope.assertSameCompany(1L, null, "无权操作其他公司的数据")) + .isInstanceOf(BusinessException.class).hasMessageContaining("其他公司"); + } +} +``` + +- [ ] **Step 2: 跑红** + +Run: `cd backend-java && mvn -o -B -q test -Dtest=CompanyScopeSupportTest` +Expected: 编译失败 `cannot find symbol: class CompanyScopeSupport`。 + +- [ ] **Step 3: 最小实现** + +```java +package com.nanri.aiimage.common.service; + +import com.nanri.aiimage.common.exception.BusinessException; +import com.nanri.aiimage.common.mapper.AdminUserMapper; +import com.nanri.aiimage.common.model.entity.AdminUserEntity; +import lombok.RequiredArgsConstructor; +import org.springframework.stereotype.Service; + +/** + * 按账号解析归属公司(二期设计文档 §3.1)——数据出口只认这一个入口。 + * + *

一期"业务表零 DDL"靠 {@code user_id → users.company_id} 派生;本期两张规则库表破例物化了 + * {@code company_id}(§2.2),但归属仍然从账号解析,物化列只是把它固定下来、好让唯一键与 + * 消费侧的集合查询用得上。

+ * + *

取不到公司一律抛,不返回 null:调用方一旦把 null 传进实体,MyBatis-Plus 会跳过该列, + * 落库时被 V145 的 {@code DEFAULT 1} 静默兜住——那是"归属失真且不报错"的成因(§6.3)。

+ */ +@Service +@RequiredArgsConstructor +public class CompanyScopeSupport { + + private final AdminUserMapper adminUserMapper; + + public Long requireCompanyId(Long userId) { + if (userId == null || userId <= 0) { + throw new BusinessException("归属账号不能为空"); + } + return requireCompanyId(adminUserMapper.selectById(userId)); + } + + public Long requireCompanyId(AdminUserEntity user) { + if (user == null) { + throw new BusinessException("归属账号不存在"); + } + Long companyId = user.getCompanyId(); + if (companyId == null || companyId <= 0) { + throw new BusinessException(403, "当前账号没有所属公司,无法按公司读写数据"); + } + return companyId; + } + + /** 行级归属闸门:跨公司写/删的第一道,消息由调用方给(前端按它显示,别在这里编文案)。 */ + public void assertSameCompany(Long operatorCompanyId, Long rowCompanyId, String deniedMessage) { + if (rowCompanyId == null || !rowCompanyId.equals(operatorCompanyId)) { + throw new BusinessException(403, deniedMessage); + } + } +} +``` + +- [ ] **Step 4: 跑绿** + +Run: `mvn -o -B -q test -Dtest=CompanyScopeSupportTest` → 5/0。 + +- [ ] **Step 5: 提交** + +```bash +git add backend-java/src/main/java/com/nanri/aiimage/common/service/CompanyScopeSupport.java \ + backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyScopeSupportTest.java +git commit -m "feat(公司隔离): 加 CompanyScopeSupport,取不到公司一律炸不返回 null" +``` + +--- + +## Task 2: V145 迁移 + 回滚脚本 + 迁移审计用例(并把 V144 钉进冻结清单) + +**Files:** +- Create: `backend-java/src/main/resources/db/V145__brand_dedupe_company_scope.sql` +- Create: `backend-java/docs/rollback-V145-company-scope.sql` +- Create: `backend-java/src/test/java/com/nanri/aiimage/config/CompanyScopeMigrationV145Test.java` +- Modify: `backend-java/src/test/java/com/nanri/aiimage/config/CompanyMigrationV144Test.java`(`:46-49` 冻结清单、`:180-182` 过期断言) +- Modify: `backend-java/docs/migration-inventory.md` + +**Interfaces:** +- Consumes: Task 0 的 `v144Checksum`、`invalidAsinRows`、`dedupeRows`。 +- Produces: 列 `biz_invalid_asin_data.company_id/uploader_user_id`、`biz_dedupe_total_data.company_id`;键 `uk_company_value_brand`、`uk_company_data_value`;旧键 `uk_data_value_brand`、`uk_data_value` 消失。 + +- [ ] **Step 1: 把 V144 补进"已应用字节封死"清单** + +`CompanyMigrationV144Test.java:46-49` 改成(校验和用 Task 0 实查值,不许凭记忆填): + +```java + private static final List APPLIED_IN_PROD = List.of( + new Applied("V142__web_config_sha256.sql", 1152261840), + new Applied("V143__company_and_users_company_id.sql", 1539570901), + new Applied("V144__users_company_id_drop_default.sql", /* Task 0 实查 */ 0)); +``` + +同时删掉 `:180-182` 这三行——它断言"V144 应是当前最大版本",V145 一落盘就必然红,而它想防的撞号已由 `MigrationInventoryTest#noDuplicateVersionFiles` 把守: + +```java + int maxOnDisk = versionFiles().stream().mapToInt(CompanyMigrationV144Test::versionOf).max().orElse(0); + assertEquals(144, maxOnDisk, "V144 应是当前最大版本"); +``` + +Run: `mvn -o -B -q test -Dtest=CompanyMigrationV144Test` → 全绿(校验和填错会红在 `appliedMigrationBytesAreFrozenAgainstProdChecksum`,那是预期行为:它拿工作树字节复算 CRC32 比对生产存量值)。 + +- [ ] **Step 2: 写失败的迁移审计用例** + +Create `CompanyScopeMigrationV145Test.java`。骨架沿用 `CompanyMigrationV144Test` 的 `stripComments`/`normalize`/`flywayChecksum`/`VERSION_FILE`(同包,直接抄),断言逐条对应 spec §5: + +```java +package com.nanri.aiimage.config; + +import org.junit.jupiter.api.Test; + +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.ArrayList; +import java.util.List; +import java.util.regex.Matcher; +import java.util.regex.Pattern; +import java.util.stream.Stream; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * V145(品牌库/去重库物化 company_id + 唯一键按公司放宽)的文件审计。 + * 设计:crawler-plugin/docs/ops/brand-dedupe-company-isolation-design-2026-10-04.md §4 / §5。 + * + *

本仓 pom 无 H2、无 testcontainers,迁移跑不起来,所以文件审计是唯一能守住的层—— + * 与 CompanyMigrationV143Test/V144Test 同口径:断言打在剥掉注释后的可执行 SQL 上。

+ */ +class CompanyScopeMigrationV145Test { + + private static final Path ROOT = Path.of(System.getProperty("user.dir")); + private static final Path DB_DIR = ROOT.resolve("src/main/resources/db"); + private static final Pattern VERSION_FILE = Pattern.compile("^V(\\d+)(?:_(\\d+))?__.*\\.sql$"); + private static final String INVALID = "biz_invalid_asin_data"; + private static final String DEDUPE = "biz_dedupe_total_data"; + + private static Path migration() throws IOException { /* 同 V144Test#migration(),前缀换 V145__ */ } + private static String rawMigration() throws IOException { /* Files.readString(migration(), UTF_8) */ } + private static String statements() throws IOException { /* normalize(stripComments(rawMigration())) */ } + + /** 破坏点:取到已应用的 144(原地改)或预留号段留洞。 */ + @Test + void migrationIsVersionedOneFourFive() throws IOException { /* versionOf == 145;文件名匹配 ^V145__[A-Za-z0-9_.-]+$ */ } + + /** 破坏点:只给一张表加列(另一张的读侧就会拿 null 去过滤,整页空)。 */ + @Test + void bothTablesGetTheCompanyColumn() throws IOException { + String sql = statements(); + for (String table : List.of(INVALID, DEDUPE)) { + assertTrue(sql.contains("ADD COLUMN `company_id` bigint NULL DEFAULT NULL"), + table + " 应先建成可空,回填后再收 NOT NULL"); + assertTrue(Pattern.compile("ALTER TABLE `" + table + "`").matcher(sql).find(), sql); + } + } + + /** 破坏点:AUTO 行永远没有审计锚点,下次再要回填就只能全表填 1(spec §1.1、§3.3)。 */ + @Test + void invalidAsinAlsoGainsUploaderAnchor() throws IOException { + assertTrue(statements().contains("ADD COLUMN `uploader_user_id` bigint NULL DEFAULT NULL")); + } + + /** 破坏点:漏回填直接 NOT NULL(会 1048 炸),或反过来——回填没有 WHERE 限定,重跑会覆盖人工指定的公司。 */ + @Test + void backfillIsRerunnableAndGatedBeforeNotNull() throws IOException { + String sql = statements(); + for (String table : List.of(INVALID, DEDUPE)) { + Matcher update = Pattern.compile("UPDATE `" + table + "` SET `company_id` = 1 WHERE `company_id` IS NULL").matcher(sql); + assertTrue(update.find(), table + " 的回填必须限定 NULL"); + } + // 闸门:MODIFY NOT NULL 排在 UPDATE 之后(MySQL 对残留 NULL 报 1048,让漏回填变成迁移失败) + assertTrue(sql.indexOf("UPDATE `" + DEDUPE + "` SET `company_id` = 1") + < sql.indexOf("MODIFY COLUMN `company_id` bigint NOT NULL"), sql); + } + + /** 破坏点:摘掉 DEFAULT ⇒ 混合版本窗口里旧 jar 的自动导入报 1364,而那个异常被 writer 吞掉=静默丢数(spec §11.2)。 */ + @Test + void keepsDefaultForMixedVersionWindowAndRegistersTheCountdown() throws IOException { + String sql = statements(); + assertTrue(sql.contains("MODIFY COLUMN `company_id` bigint NOT NULL DEFAULT 1"), + "V145 必须带 DEFAULT 1,理由与 V143 同构"); + String raw = rawMigration(); + assertTrue(raw.contains("V144"), "头注释要说明 users.company_id 的 DEFAULT 已由 V144 摘除,本表的还没摘"); + assertTrue(raw.contains("COMPANY_DEFAULT_STILL_PRESENT"), + "头注释必须点名启动期哨兵签名,摘 DEFAULT 的倒计时才有人接"); + } + + /** 破坏点:新唯一键没把 company_id 放第一位,或旧唯一键还在(旧键不删,第二家公司写同一 ASIN 会被 INSERT IGNORE 吞掉——整套改造白做)。 */ + @Test + void uniqueKeysAreReplacedNotLayered() throws IOException { + String sql = statements(); + assertTrue(sql.contains("ADD UNIQUE KEY `uk_company_value_brand` (`company_id`, `data_value`, `brand`(191))"), sql); + assertTrue(sql.contains("ADD UNIQUE KEY `uk_company_data_value` (`company_id`, `data_value`)"), sql); + assertTrue(sql.contains("DROP INDEX `uk_data_value_brand`"), sql); + assertTrue(sql.contains("DROP INDEX `uk_data_value`"), sql); + // 先加新再删旧:中间任何一步失败都至少还有一个唯一键在守并发 + assertTrue(sql.indexOf("ADD UNIQUE KEY `uk_company_data_value`") < sql.indexOf("DROP INDEX `uk_data_value`"), + "顺序必须是先 ADD 后 DROP"); + } + + /** 破坏点:写成裸 ALTER(不可重跑)。逐条数:每个 ADD/DROP 都要有 information_schema 判断。 */ + @Test + void everyConditionalDdlIsGuardedByInformationSchema() throws IOException { + String sql = statements(); + long alters = count(sql, "ALTER TABLE"); + long guards = count(sql, "information_schema"); + assertTrue(guards >= 6, "六处条件 DDL 各自要一次元数据判断,实际 " + guards); + assertEquals(alters, count(sql, "PREPARE stmt FROM @sql"), "每条条件 DDL 都要走 PREPARE"); + assertEquals(alters, count(sql, "DEALLOCATE PREPARE stmt"), "PREPARE 名复用前必须 DEALLOCATE"); + } + + /** 破坏点:动了别的表 / 建了表 / 把 company_id 又塞进第三张表。 */ + @Test + void touchesOnlyTheTwoRuleTables() throws IOException { + List altered = new ArrayList<>(); + Matcher m = Pattern.compile("ALTER TABLE `([a-z_]+)`").matcher(statements()); + while (m.find()) altered.add(m.group(1)); + assertEquals(List.of(INVALID, DEDUPE, INVALID, DEDUPE, INVALID, DEDUPE).stream().distinct().sorted().toList(), + altered.stream().distinct().sorted().toList(), "V145 只允许动这两张表,实际 " + altered); + assertFalse(statements().contains("CREATE TABLE"), "不建新表"); + } + + /** 破坏点:头注释缺项、验证 SQL 缺项、回滚被编成 V146。 */ + @Test + void headerCarriesTemplateAndRollbackStaysOutOfFlywayScan() throws IOException { + String raw = rawMigration(); + for (int i = 1; i <= 6; i++) assertTrue(raw.contains(i + ". "), "头注释缺模板第 " + i + " 项"); + for (String field : List.of("变更目的", "影响表与数据量", "锁表风险", "验证 SQL", "回滚步骤", "上线窗口")) { + assertTrue(raw.contains(field), "头注释应含必填项:" + field); + } + assertTrue(raw.contains("SHOW COLUMNS FROM `biz_invalid_asin_data` LIKE 'company_id'"), "验证 SQL 要核对列"); + assertTrue(raw.contains("Default = 1"), "验证 SQL 要写明期望 Default = 1(混合窗口)"); + assertTrue(raw.contains("INSERT IGNORE 在新键下"), "验证 SQL 要复验新唯一键的幂等语义"); + try (Stream s = Files.list(DB_DIR)) { + assertTrue(s.noneMatch(p -> p.getFileName().toString().startsWith("V146__")), + "回滚不许编成版本化迁移:V146 会被 Flyway 在下次启动自动执行"); + } + Path rollback = ROOT.resolve("docs/rollback-V145-company-scope.sql"); + assertTrue(Files.isRegularFile(rollback), "回滚人工补丁必须存在:" + rollback); + String rollbackText = Files.readString(rollback, StandardCharsets.UTF_8); + assertTrue(rollbackText.contains("flyway_schema_history"), "回滚必须删本版本历史行,否则重装时 Flyway 判定已应用而跳过"); + } + + private static long count(String haystack, String needle) { + int n = 0, i = haystack.indexOf(needle); + while (i >= 0) { n++; i = haystack.indexOf(needle, i + needle.length()); } + return n; + } +} +``` + +> 上面标了 `/* 同 V144Test */` 的四个私有工具方法**必须整段复制** `CompanyMigrationV144Test` 的实现(`stripComments` 要保留单引号字符串字面量里的 `--`,`flywayChecksum` 是 CRC32 逐 `readLine()`),不许另写一版简化实现——注释里的 `--` 一旦被当注释吃掉,断言就打在了残缺 SQL 上。 + +- [ ] **Step 3: 跑红** + +Run: `mvn -o -B -q test -Dtest=CompanyScopeMigrationV145Test` → `缺少 V145__*.sql`。 + +- [ ] **Step 4: 写迁移(完整内容)** + +Create `backend-java/src/main/resources/db/V145__brand_dedupe_company_scope.sql`: + +```sql +-- ============================================================= +-- 迁移 V145__brand_dedupe_company_scope +-- 模板:docs/flyway-migration-template.md +-- 设计:crawler-plugin/docs/ops/brand-dedupe-company-isolation-design-2026-10-04.md §4 / §5 +-- +-- 1. 变更目的:把「品牌数据库」biz_invalid_asin_data 与「去重数据汇总」biz_dedupe_total_data +-- 从"全平台共享一套规则库"改成"每公司一套"。今天 A 公司自动导入的品牌会把 B 公司采集结果里 +-- 同品牌的行过滤掉(§1.2:CollectDataBatchQuery 的两条裸 SQL 没有任何租户条件)。 +-- 这两张表破例物化 company_id(推翻一期 V143:5-8 的"业务表零 DDL",仅限这两张,用户 2026-10-04 定案); +-- 并给 biz_invalid_asin_data 补 uploader_user_id 作归属审计锚点(历史 AUTO 行没有该信息, +-- 从本版本起才记得到"由谁产生",这就是批次 1 必须现在做的唯一理由 §3.3)。 +-- 唯一键改成 company_id 打头:旧键 uk_data_value_brand / uk_data_value 是全平台单行, +-- 不删掉它,第二家公司写同一个 ASIN 会被 INSERT IGNORE 静默丢弃,整套改造白做。 +-- 2. 影响表与数据量:仅这两张表。生产实查行数(Task 0,2026-10-04 __:__): +-- biz_invalid_asin_data = ______ 行;biz_dedupe_total_data = ______ 行(后台列表注释里记的是 +-- 93 万行级)。**别拿后台看到的最大 ID 当行数**——aiimage.sql 快照的 AUTO_INCREMENT 有跳号。 +-- company / users / columns 与其余 55 张业务表一律不动。 +-- 3. 锁表风险:ADD COLUMN 在 MySQL 8 是 INSTANT;MODIFY ... NOT NULL 与 ADD/DROP UNIQUE INDEX 走 +-- INPLACE(重建索引,非 COPY 全表),biz_dedupe_total_data 是十万~百万行级,放低峰执行。 +-- 不碰 biz_task_file_job 等锁热点表。索引字节预算(utf8mb4 DYNAMIC 上限 3072): +-- uk_company_value_brand = 8 + 128*4 + 191*4 = 1284;uk_company_data_value = 8 + 512*4 = 2056。 +-- **不用前缀索引迁就长度**:V135:6-9 已写明 data_value 的前缀唯一索引会把"前 N 字符相同"的 +-- 不同值误判成重复、破坏去重语义。 +-- 4. 验证 SQL:见文件末尾「验证」段。 +-- 5. 回滚步骤:人工补丁 backend-java/docs/rollback-V145-company-scope.sql(在 Flyway 扫描路径之外, +-- 不写成 V146——版本化回滚等于让"决定回滚"这件事在没有人工执行的情况下自己发生)。 +-- 顺序:停两台应用 → 跑脚本 → 删 flyway_schema_history 的 version=145 行 → 回滚 jar → 起应用。 +-- 6. 上线窗口:随 jar 双节点同窗口发布,金丝雀过了立刻补第二台,把混合版本窗口压到分钟级。 +-- DEFAULT 1 是【临时】的,唯一存在理由与本文件同批的旧 jar:其 insertBatchIgnore 列清单不含 +-- company_id,严格模式下会报 1364;而 CollectDataInvalidAsinBatchWriter 把批量写失败 +-- catch 成 log.warn 后跳过整批(:58-60),接口仍返回成功 ⇒ 表现为"自动导入静默丢数据"。 +-- 摘除时机 = 第二家公司开通前(§11.4)。users.company_id 的同款 DEFAULT 已由 V144 摘掉; +-- 本文件这两列的 DEFAULT 由启动期 CompanyDefaultGuard 的 COMPANY_DEFAULT_STILL_PRESENT 盯, +-- 摘除前必须把它扩到这三列(见 CompanyScopeMigrationV145Test 与 §10 护栏 1)。 +-- 写入路径不得依赖本 DEFAULT 兜漏传:CompanyScopeSupport 取不到公司就抛(§6.3)。 +-- +-- 【可重跑性】MySQL 的 DDL 不进事务。本迁移若在 NOT NULL 闸门处失败,前面的加列/回填已落库; +-- 按「补数据 → flyway repair → 重启」恢复时 Flyway 从第一条语句重跑整个文件,所以每条 DDL +-- 都先查 information_schema 再 PREPARE,UPDATE 都带 WHERE ... IS NULL(重跑是 no-op, +-- 不会覆盖人工指定过公司的行)。写法首例见 V143 全文件。 +-- ============================================================= + +SET @db_name = DATABASE(); + +-- ---------- 1. 加列(先可空,回填后收 NOT NULL) ---------- + +SET @col_exists := (SELECT COUNT(*) FROM information_schema.COLUMNS + WHERE TABLE_SCHEMA = @db_name AND TABLE_NAME = 'biz_invalid_asin_data' AND COLUMN_NAME = 'company_id'); +SET @sql := IF(@col_exists = 0, + 'ALTER TABLE `biz_invalid_asin_data` ADD COLUMN `company_id` bigint NULL DEFAULT NULL COMMENT ''所属公司(company.id)'' AFTER `id`', + 'SELECT 1'); +PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt; + +SET @col_exists := (SELECT COUNT(*) FROM information_schema.COLUMNS + WHERE TABLE_SCHEMA = @db_name AND TABLE_NAME = 'biz_invalid_asin_data' AND COLUMN_NAME = 'uploader_user_id'); +SET @sql := IF(@col_exists = 0, + 'ALTER TABLE `biz_invalid_asin_data` ADD COLUMN `uploader_user_id` bigint NULL DEFAULT NULL COMMENT ''归属账号(users.id),历史行为 NULL'' AFTER `company_id`', + 'SELECT 1'); +PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt; + +SET @col_exists := (SELECT COUNT(*) FROM information_schema.COLUMNS + WHERE TABLE_SCHEMA = @db_name AND TABLE_NAME = 'biz_dedupe_total_data' AND COLUMN_NAME = 'company_id'); +SET @sql := IF(@col_exists = 0, + 'ALTER TABLE `biz_dedupe_total_data` ADD COLUMN `company_id` bigint NULL DEFAULT NULL COMMENT ''所属公司(company.id)'' AFTER `id`', + 'SELECT 1'); +PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt; + +-- ---------- 2. 存量回填:现有全部行归厦门米椿花(company.id=1,V143 钉死的那一行) ---------- +-- 只有 1 家公司 ⇒ 这是确定性操作。第二家公司开通之后再跑就永远分不清了(§3.3)。 + +UPDATE `biz_invalid_asin_data` SET `company_id` = 1 WHERE `company_id` IS NULL; +UPDATE `biz_dedupe_total_data` SET `company_id` = 1 WHERE `company_id` IS NULL; + +-- 自检闸门:上一句若漏掉任何一行,这里的 MODIFY ... NOT NULL 会报 1048(Column cannot be null) +-- 让迁移失败,而不是留一堆 NULL 静默通过——NULL 意味着这些行在任何 company_id 过滤下整体失明。 +ALTER TABLE `biz_invalid_asin_data` + MODIFY COLUMN `company_id` bigint NOT NULL DEFAULT 1 COMMENT '所属公司(company.id)'; +ALTER TABLE `biz_dedupe_total_data` + MODIFY COLUMN `company_id` bigint NOT NULL DEFAULT 1 COMMENT '所属公司(company.id)'; + +-- ---------- 3. 唯一键按公司放宽(先 ADD 后 DROP:中间任一步失败都至少还有一个唯一键在守并发) ---------- + +SET @idx_exists := (SELECT COUNT(DISTINCT INDEX_NAME) FROM information_schema.STATISTICS + WHERE TABLE_SCHEMA = @db_name AND TABLE_NAME = 'biz_invalid_asin_data' AND INDEX_NAME = 'uk_company_value_brand'); +SET @sql := IF(@idx_exists = 0, + 'ALTER TABLE `biz_invalid_asin_data` ADD UNIQUE KEY `uk_company_value_brand` (`company_id`, `data_value`, `brand`(191))', + 'SELECT 1'); +PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt; + +SET @idx_exists := (SELECT COUNT(DISTINCT INDEX_NAME) FROM information_schema.STATISTICS + WHERE TABLE_SCHEMA = @db_name AND TABLE_NAME = 'biz_invalid_asin_data' AND INDEX_NAME = 'uk_data_value_brand'); +SET @sql := IF(@idx_exists > 0, + 'ALTER TABLE `biz_invalid_asin_data` DROP INDEX `uk_data_value_brand`', + 'SELECT 1'); +PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt; + +SET @idx_exists := (SELECT COUNT(DISTINCT INDEX_NAME) FROM information_schema.STATISTICS + WHERE TABLE_SCHEMA = @db_name AND TABLE_NAME = 'biz_dedupe_total_data' AND INDEX_NAME = 'uk_company_data_value'); +SET @sql := IF(@idx_exists = 0, + 'ALTER TABLE `biz_dedupe_total_data` ADD UNIQUE KEY `uk_company_data_value` (`company_id`, `data_value`)', + 'SELECT 1'); +PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt; + +SET @idx_exists := (SELECT COUNT(DISTINCT INDEX_NAME) FROM information_schema.STATISTICS + WHERE TABLE_SCHEMA = @db_name AND TABLE_NAME = 'biz_dedupe_total_data' AND INDEX_NAME = 'uk_data_value'); +SET @sql := IF(@idx_exists > 0, + 'ALTER TABLE `biz_dedupe_total_data` DROP INDEX `uk_data_value`', + 'SELECT 1'); +PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt; + +-- ---------- 4. 本迁移刻意不加的索引 ---------- +-- 非超管读路径改成 company_id + group_id 后,仍复用既有 idx_invalid_asin_group_id (V86:69) 与 +-- idx_dedupe_total_data_group_id (V87:48):公司维度今天只有 1 个值,新二级索引零选择性。 +-- 第二家公司开通后若慢日志出现这两张表的行扫描,再单独立项(先例结论:本库的瓶颈是锁不是索引)。 + +-- ============================================================= +-- 验证 SQL(迁移后在库上执行,spec §11.5;上线时必须有人实跑,不许只看启动日志的 Successfully applied) +-- SHOW COLUMNS FROM `biz_invalid_asin_data` LIKE 'company_id'; +-- -> 期望 Null = NO,Default = 1(混合窗口要求带 DEFAULT;第二家公司开通后必须由新迁移摘成 NULL) +-- SHOW COLUMNS FROM `biz_dedupe_total_data` LIKE 'company_id'; +-- -> 期望 Null = NO,Default = 1 +-- SHOW COLUMNS FROM `biz_invalid_asin_data` LIKE 'uploader_user_id'; +-- -> 期望 Null = YES(历史 AUTO 行确实无从追溯,只有新行带值) +-- SELECT COUNT(*) AS total, SUM(company_id IS NULL) AS null_company +-- FROM `biz_invalid_asin_data`; +-- -> 期望 null_company = 0 +-- SELECT COUNT(*) AS total, SUM(company_id IS NULL) AS null_company +-- FROM `biz_dedupe_total_data`; +-- -> 期望 null_company = 0 +-- SELECT TABLE_NAME, INDEX_NAME, GROUP_CONCAT(CONCAT(COLUMN_NAME,'@',SEQ_IN_INDEX) ORDER BY SEQ_IN_INDEX) AS cols +-- FROM information_schema.STATISTICS +-- WHERE TABLE_SCHEMA = DATABASE() +-- AND TABLE_NAME IN ('biz_invalid_asin_data','biz_dedupe_total_data') +-- AND NON_UNIQUE = 0 +-- GROUP BY TABLE_NAME, INDEX_NAME; +-- -> 期望恰好两行:uk_company_value_brand(company_id@1,data_value@2,brand@3)、 +-- uk_company_data_value(company_id@1,data_value@2); +-- 旧的 uk_data_value_brand / uk_data_value 必须【不】在结果里 +-- INSERT IGNORE 在新键下(事务内跑完回滚,或验完删掉测试行,见 §11.5.4): +-- START TRANSACTION; +-- INSERT INTO `biz_dedupe_total_data` (company_id, data_value) VALUES (1, 'ZZTEST0000000001'); +-- INSERT INTO `biz_dedupe_total_data` (company_id, data_value) VALUES (2, 'ZZTEST0000000001'); +-- SELECT COUNT(*) AS two_rows FROM `biz_dedupe_total_data` WHERE data_value = 'ZZTEST0000000001'; +-- ROLLBACK; +-- -> 期望两条 INSERT 都成功、two_rows = 2(同一个值能归两家公司 = 键真的放宽了; +-- 第二条报 1062 就说明旧 uk 还在,本文件第 3 段没跑成) +-- ============================================================= +``` + +> 头注释里两处 `______` 必须用 Task 0 的实查数字填掉;留着下划线 = §5.4 那条"行数必须上线前实查"没还。 + +- [ ] **Step 5: 写回滚补丁** + +Create `backend-java/docs/rollback-V145-company-scope.sql`: + +```sql +-- 回滚 V145(人工补丁,不放进 src/main/resources/db/——那里是 Flyway 扫描路径) +-- 顺序:停两台应用 → 执行本脚本 → DELETE FROM flyway_schema_history WHERE version='145' +-- → 回滚 jar → 起应用。漏掉删历史那步,将来重装带 V145 的 jar 时 Flyway 判定"已应用"直接跳过, +-- 列与键都不会重建,而 Java 侧实体照常读写 company_id ⇒ 运行期 unknown column。 +-- +-- ⚠ 本脚本会丢数据:恢复全局唯一键必须先把跨公司重复的值删到只剩一行(照 V94:16-25 的先例), +-- 而"哪一行的归属是真的"无法自动判定。所以默认只做「保留新列、只做查询侧回退」这一档: +-- 回滚 jar 后 Java 不再读写 company_id,两张表多两列空转,随时可再前滚。 +-- 真的要清列,再解开最后一段(解开前先备份这两张表)。 + +ALTER TABLE `biz_invalid_asin_data` DROP INDEX `uk_company_value_brand`; +ALTER TABLE `biz_invalid_asin_data` ADD UNIQUE KEY `uk_data_value_brand` (`data_value`, `brand`(191)); +ALTER TABLE `biz_dedupe_total_data` DROP INDEX `uk_company_data_value`; +ALTER TABLE `biz_dedupe_total_data` ADD UNIQUE KEY `uk_data_value` (`data_value`); +-- ↑ 这两组只有在"没有任何一家公司之外写过同名值"时才成立;否则 ADD 报 1062。 +-- 报 1062 说明批次 2 已经产生过多公司同名行,此时【不要】硬删数据,改走: +-- 保留新键,只回滚 jar(新列对新 jar 是惰性的)。 + +-- 解开下面三行才会真正 DROP 列(不可逆,先备份): +-- ALTER TABLE `biz_invalid_asin_data` DROP COLUMN `uploader_user_id`, DROP COLUMN `company_id`; +-- ALTER TABLE `biz_dedupe_total_data` DROP COLUMN `company_id`; +``` + +- [ ] **Step 6: 跑绿审计用例** + +Run: `mvn -o -B -q test -Dtest=CompanyScopeMigrationV145Test` +Expected: 全绿。若 `everyConditionalDdlIsGuardedByInformationSchema` 红,说明某条 ALTER 写成了裸语句——那正是恢复路径会撞 1050/1060/1062 的地方。 + +- [ ] **Step 7: 更新盘点文档(`MigrationInventoryTest#inventoryDocCommittedAndConsistent` 会读它)** + +`backend-java/docs/migration-inventory.md`:概览"版本化迁移文件数:**143**"→ **144**;"整数版本范围:**V1..V144**"→ **V1..V145**;"最新版本"→ `V145__brand_dedupe_company_scope.sql`(并注明 V144 已于 10-04 13:2x 随 jar `e4b237c1…` 应用、V145 待下一次发版执行);"后续新增迁移从 **V145** 起取号"→ **V146**;「已应用迁移的存量校验和」表补 144 那一行(校验和与 installed_on 用 Task 0 实查值)。 + +- [ ] **Step 8: 跑迁移族全量** + +Run: `mvn -o -B -q test -Dtest='*Migration*Test'` +Expected: 全绿(含 `MigrationInventoryTest`、`FlywayMigrationTemplateDocTest`、`FlywayMigrationDrillDocTest`、`IndexMigrationV101Test`、`CompanyMigrationV143Test`)。 + +- [ ] **Step 9: 变异自证(护栏 1)** + +Create throwaway `backend-java/tmp-mutation-v145.py`,四个注入点逐个注入、每轮跑一次审计用例、断言"必须红":① 删掉 `WHERE \`company_id\` IS NULL`;② 把 `DROP INDEX \`uk_data_value\`` 那段的 `'SELECT 1'` 与 ALTER 互换(等于旧键没删);③ 把 `NOT NULL DEFAULT 1` 改成 `NOT NULL`;④ 从 `biz_dedupe_total_data` 的加列段里删掉 `company_id`。 +每条都要**先**把文件原字节读进内存再注入,收尾用内存里的字节写回(**不许 `git checkout`**——它会连未提交的实现一起抹掉),最后 `git diff --stat` 必须只剩预期文件。 + +- [ ] **Step 10: 提交** + +```bash +rm backend-java/tmp-mutation-v145.py # 自造临时件收尾要清 +git add backend-java/src/main/resources/db/V145__brand_dedupe_company_scope.sql \ + backend-java/docs/rollback-V145-company-scope.sql \ + backend-java/docs/migration-inventory.md \ + backend-java/src/test/java/com/nanri/aiimage/config/CompanyScopeMigrationV145Test.java \ + backend-java/src/test/java/com/nanri/aiimage/config/CompanyMigrationV144Test.java +git commit -m "feat(公司隔离): V145 给品牌库/去重库物化 company_id 并按公司放宽唯一键" +``` + +--- + +## Task 3: 品牌库写侧带归属(批次 1 的后半) + +**Files:** +- Modify: `modules/invalidasin/model/entity/InvalidAsinDataEntity.java` +- Modify: `modules/invalidasin/mapper/InvalidAsinDataMapper.java`(`insertBatchIgnore` 列清单 `:20-30`) +- Create: `modules/invalidasin/service/InvalidAsinAutoWriteScopeResolver.java` +- Modify: `modules/invalidasin/service/InvalidAsinDataService.java`(`:80-92` create、`:95-117` update、`:120-124` delete、`:145-153` ensureUnique、`:177-193` ensureRecordAccess) +- Modify: `modules/collectdata/util/CollectDataInvalidAsinBatchWriter.java`(`:38`、`:65-79`) +- Modify: `modules/collectdata/service/CollectDataService.java`(`:899`) +- Modify: `modules/collectdata/service/CollectDataBrandRecheckInjector.java`(`:114`) +- Test: `modules/invalidasin/service/InvalidAsinDataServiceTest.java`、`modules/collectdata/util/CollectDataInvalidAsinBatchWriterTest.java`、`modules/collectdata/service/CollectDataBrandRecheckInjectorTest.java`、`modules/collectdata/service/CollectDataServiceTxBoundaryTest.java` +- Create: `src/test/java/com/nanri/aiimage/modules/company/CompanyScopeWriteOutletTest.java`(护栏 2) + +**Interfaces:** +- Consumes: `CompanyScopeSupport.requireCompanyId(Long)`(Task 1)、`ShopManageGroupService.listAccessibleGroupIds(Long, boolean)`(`:71`)。 +- Produces: + - `InvalidAsinAutoWriteScopeResolver.AutoWriteScope(Long companyId, Long uploaderUserId, Long groupId)` + - `InvalidAsinAutoWriteScopeResolver.AutoWriteScope resolve(Long uploaderUserId)` + - `CollectDataInvalidAsinBatchWriter.writeBatch(List rows, AutoWriteScope scope)`(旧签名删除) + +- [ ] **Step 1: 写护栏 2 的失败测试** + +`CompanyScopeWriteOutletTest`(源码扫描 + 可跑断言两半)。扫描分母**由遍历 `src/main/java` 得到**,不许自挑文件: + +```java +package com.nanri.aiimage.modules.company; + +import org.junit.jupiter.api.Test; + +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.List; +import java.util.stream.Collectors; +import java.util.stream.Stream; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 护栏 2(设计 §10.2):两张规则库的每个写出口都必须带 company_id。 + * + *

为什么打在源码上而不是行为上:V145 的列 DEFAULT=1 会让"漏传"落库成功—— + * 只有源码这一层能区分"显式传了本公司"与"被 DEFAULT 兜住"(§11.5.3 承认数据无法区分)。

+ */ +class CompanyScopeWriteOutletTest { + + private static final Path MAIN = Path.of(System.getProperty("user.dir"), "src/main/java"); + + /** INSERT 语句的字面量列清单必须出现 company_id(两处 insertBatchIgnore)。 */ + @Test + void everyInsertIntoTheTwoRuleTablesCarriesCompanyId() throws IOException { + List sqls = javaSources().stream() + .flatMap(p -> insertLiterals(read(p)).stream()) + .filter(sql -> sql.contains("biz_invalid_asin_data") || sql.contains("biz_dedupe_total_data")) + .collect(Collectors.toList()); + assertFalse(sqls.isEmpty(), "扫描必须命中 insertBatchIgnore,0 命中等于没有护栏"); + assertEquals(2, sqls.size(), "品牌库与去重库各一处批量 INSERT,命中数变了要回来改这里"); + for (String sql : sqls) { + assertTrue(sql.contains("company_id"), "批量 INSERT 缺 company_id:" + sql.replaceAll("\\s+", " ")); + } + } + + /** 两个实体的 setCompanyId 必须在每个写方法里被调到(漏一个方法=该路径靠 DEFAULT)。 */ + @Test + void writePathsSetCompanyIdOnTheEntityBeforeHittingTheMapper() throws IOException { + String dedupe = read(MAIN.resolve("com/nanri/aiimage/modules/dedupe/service/DedupeTotalDataService.java")); + assertTrue(dedupe.contains("entity.setCompanyId("), "create 必须显式落公司"); + assertTrue(dedupe.contains("insertImportBatch(List values", 0) || dedupe.contains("insertImportBatch("), + "导入批写入口应仍存在"); + String invalid = read(MAIN.resolve("com/nanri/aiimage/modules/invalidasin/service/InvalidAsinDataService.java")); + assertTrue(invalid.contains("entity.setCompanyId("), "手工新增必须显式落公司"); + assertTrue(invalid.contains("entity.setUploaderUserId("), "手工新增要落审计锚点,否则下次回填又只能全表填 1"); + } + + /** 归属解析只走一个入口:不许出现第二份 company_id 查询。 */ + @Test + void companyResolutionGoesThroughCompanyScopeSupportOnly() throws IOException { + List offenders = javaSources().stream() + .map(CompanyScopeWriteOutletTest::read) + .filter(text -> text.contains("getCompanyId()") && !text.contains("CompanyScopeSupport")) + .map(text -> text.substring(0, Math.min(text.length(), 0)).isEmpty() ? "" : "") + .filter(s -> false) + .collect(Collectors.toList()); + // 上面这条写复杂了;实际断言用文件粒度: + List files = javaSources().stream() + .filter(p -> { String t = read(p); return t.contains(".getCompanyId()") && !t.contains("CompanyScopeSupport") && !t.contains("AdminUserEntity"); }) + .map(p -> p.getFileName().toString()) + .collect(Collectors.toList()); + assertTrue(files.isEmpty(), "company_id 只能从 CompanyScopeSupport 或已加载的 AdminUserEntity 拿,违规:" + files); + } + + private static List insertLiterals(String source) { + // 抓 @Insert(""" ... """) 的文本块内容;不做完整 JavaParser,够用即可,但必须能命中真实两处 + java.util.List out = new java.util.ArrayList<>(); + int i = 0; + while ((i = source.indexOf("@Insert(\"\"\"", i)) >= 0) { + int end = source.indexOf("\"\"\")", i); + if (end < 0) break; + out.add(source.substring(i, end)); + i = end; + } + return out; + } + + private static List javaSources() { + try (Stream s = Files.walk(MAIN)) { + return s.filter(p -> p.toString().endsWith(".java")).collect(Collectors.toList()); + } catch (IOException e) { + throw new IllegalStateException(e); + } + } + + private static String read(Path p) { + try { return Files.readString(p, StandardCharsets.UTF_8); } + catch (IOException e) { throw new IllegalStateException(e); } + } +} +``` + +> 上面 `companyResolutionGoesThroughCompanyScopeSupportOnly` 里那段 `offenders` 是我写复杂了的死代码——**落盘时删掉它,只保留按文件粒度的 `files` 断言**(留一个永远为空的中间变量等于给后人留坑)。另:`assertTrue(dedupe.contains("insertImportBatch(List values", 0) ...)` 那行参数写错了,Step 1 落盘时改成 `dedupe.contains("insertImportBatch(")`。 + +- [ ] **Step 2: 跑红** + +Run: `mvn -o -B -q test -Dtest=CompanyScopeWriteOutletTest` → 两条红(列清单缺 company_id、实体没 setCompanyId)。 + +- [ ] **Step 3: 实体两列 + mapper 列清单** + +`InvalidAsinDataEntity`(`private Long groupId;` 之前插入): + +```java + private Long companyId; + /** 归属账号:AUTO 行由 task.user_id 落,MANUAL 行由操作人落;历史行为 NULL(V145 无从追溯)。 */ + private Long uploaderUserId; +``` + +`InvalidAsinDataMapper.insertBatchIgnore` 整段替换(并订正那段注释——它今天写的是"命中唯一键 (data_value, brand)"): + +```java + /** + * 批量 INSERT IGNORE:命中唯一键 (company_id, data_value, brand(191)) 的重复行静默跳过,幂等。 + * created_at/updated_at 不显式写入:依赖列的 DEFAULT CURRENT_TIMESTAMP(显式传 null 会绕过默认值, + * 在宽松模式下落成 '0000-00-00 00:00:00',随后 NO_ZERO_DATE 读取即报错)。 + * company_id / uploader_user_id / group_id 必须由调用方给值:写 null 会被 MyBatis-Plus 跳过列、 + * 落库时被 V145 的 DEFAULT 1 静默兜住(设计 §6.3 明确禁止)。 + */ + @Insert(""" + + """) + int insertBatchIgnore(@Param("rows") List rows); +``` + +- [ ] **Step 4: AUTO 归属解析器** + +```java +package com.nanri.aiimage.modules.invalidasin.service; + +import com.nanri.aiimage.common.service.CompanyScopeSupport; +import com.nanri.aiimage.modules.shopkey.service.ShopManageGroupService; +import lombok.RequiredArgsConstructor; +import org.springframework.stereotype.Component; + +import java.util.Set; + +/** + * 自动导入写入品牌库时的三元归属:公司(硬边界)+ 账号(审计锚点)+ 分组(可见性)。 + * + *

group_id 与 company_id 必须一起补:读侧 §7.1 保留"= 固定组",只补公司不补分组的话, + * 新的 AUTO 行仍会因为 group_id IS NULL 对所有非超管永久不可见(§1.3 那个硬条件刚摘掉)。

+ * + *

固定组取"可访问组里 id 最小的那个",与 {@code InvalidAsinDataService:203-212} + * 的 {@code resolveFixedAccessibleGroupId} 同口径——写侧落哪一组 = 读侧看哪一组,这条不变式由 + * {@code CompanyScopeReadPathTest} 钉住。

+ */ +@Component +@RequiredArgsConstructor +public class InvalidAsinAutoWriteScopeResolver { + + private final CompanyScopeSupport companyScope; + private final ShopManageGroupService shopManageGroupService; + + public AutoWriteScope resolve(Long uploaderUserId) { + Long companyId = companyScope.requireCompanyId(uploaderUserId); + return new AutoWriteScope(companyId, uploaderUserId, fixedAccessibleGroupId(uploaderUserId)); + } + + /** 解析不出分组不抛:AUTO 行退回"无组"(与今天一致),但公司解析失败必须炸(见 CompanyScopeSupport)。 */ + private Long fixedAccessibleGroupId(Long uploaderUserId) { + Set accessible = shopManageGroupService.listAccessibleGroupIds(uploaderUserId, false); + if (accessible == null) { + return null; + } + return accessible.stream().filter(id -> id != null && id > 0).min(Long::compareTo).orElse(null); + } + + public record AutoWriteScope(Long companyId, Long uploaderUserId, Long groupId) { + } +} +``` + +- [ ] **Step 5: 写侧 fail-fast + 落归属** + +`CollectDataInvalidAsinBatchWriter`:字段不变(**别给 writer 加依赖**,它今天由测试用 `new CollectDataInvalidAsinBatchWriter(mapper, 10)` 直接构造),改方法: + +```java + /** + * 批量写入并返回实际尝试写入的行数(INSERT IGNORE 忽略重复,幂等)。 + * + *

scope 必须在进批次循环之前判完:{@code :58-60} 那个 catch 会把 RuntimeException 吞成 + * 一句 log.warn 并跳过整批,接口仍返回成功。归属缺失如果落进那个 catch,表现就是 + * "自动导入静默丢数据、没人知道"(设计 §11.2)。

+ */ + public int writeBatch(List rows, InvalidAsinAutoWriteScopeResolver.AutoWriteScope scope) { + if (scope == null || scope.companyId() == null) { + throw new IllegalStateException("自动导入品牌库缺 company_id:拒绝依赖 V145 的列 DEFAULT 兜漏传"); + } + if (rows == null || rows.isEmpty()) { + return 0; + } + ... // 批次循环保持原样,只把 toEntity(row) 换成 toEntity(row, scope) + } + + private InvalidAsinDataEntity toEntity(CollectDataResultRowVo row, + InvalidAsinAutoWriteScopeResolver.AutoWriteScope scope) { + if (row == null) return null; + String asin = normalize(row.getAsin()); + String brand = normalize(row.getBrand()).toLowerCase(Locale.ROOT); + if (asin.isBlank() || brand.isBlank()) return null; + InvalidAsinDataEntity entity = new InvalidAsinDataEntity(); + entity.setDataValue(asin); + entity.setBrand(brand); + entity.setRecordSource("AUTO"); + entity.setCompanyId(scope.companyId()); + entity.setUploaderUserId(scope.uploaderUserId()); + entity.setGroupId(scope.groupId()); + return entity; + } +``` + +两个调用点(`CollectDataService.java:899`、`CollectDataBrandRecheckInjector.java:114`)各自从任务账号解析: + +```java +// CollectDataService:task 在锁内已重读;scope 与 :835 的 filter 共用一次解析(Task 6 会把它提成一个变量) +invalidAsinBatchWriter.writeBatch(brandOutcome.rejected(), + invalidAsinAutoWriteScopeResolver.resolve(task.getUserId())); + +// CollectDataBrandRecheckInjector.apply(FileTaskEntity task, ...):task 是形参,:78 +rejectedRows += invalidAsinBatchWriter.writeBatch(chunkRejected, + invalidAsinAutoWriteScopeResolver.resolve(task.getUserId())); +``` + +两处都要新增 `private final InvalidAsinAutoWriteScopeResolver invalidAsinAutoWriteScopeResolver;`(`@RequiredArgsConstructor` 类);`CollectDataBrandRecheckInjectorTest:145` 的 mock 从 `writeBatch(anyList())` 改成 `writeBatch(anyList(), any())`,`CollectDataServiceTxBoundaryTest:211/223/235` 同理,并给这两个测试类补 `@Mock InvalidAsinAutoWriteScopeResolver`。 + +- [ ] **Step 6: 手工写入口** + +`InvalidAsinDataService` 加依赖 `private final CompanyScopeSupport companyScope;`(`@InjectMocks` 会按类型注入;`InvalidAsinDataServiceTest` 补 `@Mock CompanyScopeSupport companyScope;` + `lenient().when(companyScope.requireCompanyId(anyLong())).thenReturn(1L);`)。 + +`create`(`:80-92`)在 `entity.setRecordSource(MANUAL)` 之后补: + +```java + entity.setCompanyId(companyScope.requireCompanyId(operatorId)); + entity.setUploaderUserId(operatorId); +``` + +`ensureUnique`(`:145-153`)改成按公司判重——**只加 company 维度,不碰 brand**:今天它只按 `data_value` 判(比 DB 的 `(data_value, brand)` 更严),保持这个更严的产品口径不变,只把它从"全平台"收成"本公司": + +```java + private void ensureUnique(String dataValue, Long companyId, Long excludeId) { + LambdaQueryWrapper query = new LambdaQueryWrapper() + .eq(InvalidAsinDataEntity::getCompanyId, companyId) + .eq(InvalidAsinDataEntity::getDataValue, dataValue) + .last("LIMIT 1"); + ... + } +``` +两处调用点(`:84`、`:107`)传 `entity.getCompanyId()`/新解析出的公司。**这一步不做会让 B 公司新增 A 公司已有的 ASIN 被服务层提前拒掉,而 DB 新键允许它——写侧唯一键改了、校验没改=白改。** + +`update`(`:95-117`):`company_id` 不进更新语义(不许跨公司移动)。`getById` 出来的实体自带原公司,`updateById` 会原样写回,无需额外语句;跨公司防护由下一步的 `ensureRecordAccess` 承担。 + +- [ ] **Step 7: 行级闸门** + +`ensureRecordAccess`(`:177-193`)签名加 `Long operatorCompanyId`,非超管在既有分组判断**之前**先过公司闸门: + +```java + private ShopManageGroupEntity ensureRecordAccess(InvalidAsinDataEntity entity, Long operatorCompanyId, + Long operatorId, boolean superAdmin) { + if (superAdmin) { + return null; + } + companyScope.assertSameCompany(operatorCompanyId, entity.getCompanyId(), "无权操作其他公司的品牌数据"); + // 以下保持原样(批次 1 仍有 MANUAL 硬条件,批次 3 的 Task 7 才摘) +``` +`update` / `delete` 调用点各传 `companyScope.requireCompanyId(operatorId)`。 + +- [ ] **Step 8: 跑绿 + 全量后端** + +Run: `mvn -o -B -q test -Dtest='InvalidAsin*Test,CollectData*Test,CompanyScope*Test'` → 全绿。 +Run: `mvn -o -B test`(**不与 Nuitka 并行**)→ 记录总数(基线 3602/0/0/7,本任务会新增若干例)。 + +- [ ] **Step 9: 变异自证(护栏 2)** + +注入四条,各自必须让护栏红:① 从 `insertBatchIgnore` 列清单删 `company_id`;② 从 `create` 删 `entity.setCompanyId(`;③ 把 `writeBatch` 开头的 fail-fast 删掉;④ `ensureUnique` 删 `.eq(InvalidAsinDataEntity::getCompanyId, companyId)`。还原只认注入前读进内存的字节。 + +- [ ] **Step 10: 提交** + +```bash +git add backend-java/src/main/java/com/nanri/aiimage/modules/invalidasin \ + backend-java/src/main/java/com/nanri/aiimage/modules/collectdata \ + backend-java/src/test/java/com/nanri/aiimage/modules/invalidasin \ + backend-java/src/test/java/com/nanri/aiimage/modules/collectdata \ + backend-java/src/test/java/com/nanri/aiimage/modules/company/CompanyScopeWriteOutletTest.java +git commit -m "feat(公司隔离): 品牌库每个写出口显式带 company_id/uploader_user_id/group_id" +``` + +--- + +## Task 4: 去重库写侧带归属 + +**Files:** +- Modify: `modules/dedupe/model/entity/DedupeTotalDataEntity.java` +- Modify: `modules/dedupe/mapper/DedupeTotalDataMapper.java`(`insertBatchIgnore` `:30-33`) +- Modify: `modules/dedupe/service/DedupeTotalDataService.java`(`:436-448` create、`:483-528` startImport、`:629-656` runImportTask、`:686-701` importFromExcel、`:707-724` deleteFromExcel、`:726-729` importFromExcelInternal、`:862-872` flushBatch、`:894-945` insertImportBatch、`:1095-1106` update、`:1140-1155` ensureUnique/existsDataValue、`:1179-1205` resolveAccessScope、`:1234-1240` resolveWritableGroup、`:1270-1282` ensureRecordAccess、`:1405` AccessScope) +- Create/Extend: `CompanyScopeWriteOutletTest`(追加去重库断言) + +**Interfaces:** +- Consumes: `CompanyScopeSupport.requireCompanyId(AdminUserEntity)`(该服务已在 `:1253-1262` 加载过 `AdminUserEntity`,**不新增查询**)。 +- Produces: + - `private record AccessScope(boolean allUsers, Set groupIds, Set userIds, Long companyId)`(第四位是本任务新加的;`applyGroupScope` 的读过滤本任务**不动**) + - `private void ensureUnique(String dataValue, Long excludeId, Long companyId)` + - `private boolean existsDataValue(String dataValue, Long companyId)` + - `private ImportBatchResult insertImportBatch(List values, Map countriesByValue, Long groupId, Long companyId, Long uploaderUserId, String uploaderUsername)` + +- [ ] **Step 1: 先写红的测试** + +在 `CompanyScopeWriteOutletTest` 追加(分母仍来自遍历): + +```java + @Test + void dedupeWritePathsCarryCompanyThroughTheAsyncImportThread() throws IOException { + String text = read(MAIN.resolve("com/nanri/aiimage/modules/dedupe/service/DedupeTotalDataService.java")); + assertTrue(text.contains("entity.setCompanyId(companyId)"), "create 与导入批都必须落公司"); + assertTrue(text.contains("insertImportBatch(") && text.contains("Long companyId"), + "异步导入要把公司带到写批次"); + assertTrue(text.contains(".eq(DedupeTotalDataEntity::getCompanyId, companyId)"), + "ensureUnique / existsDataValue 必须按公司判重,否则 B 公司的值被 A 公司的行顶掉"); + } +``` + +Run: `mvn -o -B -q test -Dtest=CompanyScopeWriteOutletTest` → 新增那条红。 + +- [ ] **Step 2: 实体与 mapper** + +`DedupeTotalDataEntity` 在 `private Long groupId;` 之前加 `private Long companyId;`(放在最前也行,但要与 V145 的 `AFTER id` 对应,便于 `SHOW COLUMNS` 复核)。 +`insertBatchIgnore` 列清单加 `company_id`,`VALUES` 里加 `#{row.companyId}`,并把注释里"concurrency guard"那句订正成"同公司内的并发兜底"(新键只在公司内唯一)。 + +- [ ] **Step 3: 公司跟着操作人走(一次解析,贯穿异步线程)** + +`resolveWritableGroup`(`:1234-1240`)旁边加一个同名的公司闸门,**照它现有"请选择分组"那种 fail-fast 形状**: + +```java + /** + * 写入口的公司归属:非超管与超管都取操作人自己的公司。 + * + *

与分组不同,公司【不是】请求参数能决定的——超管能挑分组,不该能挑公司; + * 否则"这条数据归谁"就取决于前端多传一个字段(§6.2 的取值规则)。

+ */ + private Long requireWritableCompanyId(AdminUserEntity operator) { + return companyScope.requireCompanyId(operator); + } +``` + +四个写入口各调一次并把结果与 `group` 一起往下传:`create`(`:436`)、`startImport`(`:487`,在 `resolveWritableGroup` 之后取 companyId,然后作为**新形参**穿过 `runImportTask(...)`(`:629-630`)→ `importFromExcelInternal(...)`(`:726-729`)→ 内部类的字段与 `flushBatch()`(`:862-872`)→ `insertImportBatch(...)`(`:894`);`importFromExcel`(`:686`)同样补一个 `companyId` 形参进 `importFromExcelInternal`;`deleteFromExcel`(`:707`)与 `update`(`:1095`)用 `requireWritableCompanyId(operator)` 做闸门即可(它们不新建行)。 + +> `startImport` 还有 `importGroupMap`(Redis 共享进度 store);**不要**再开一个 `importCompanyMap`——公司只在写库那一刻用,进度可见性沿用分组口径。参数穿过虚拟线程 lambda 时注意 `:516` 那一行的实参顺序必须与 `:629` 的形参顺序一起改。 + +- [ ] **Step 4: 判重按公司** + +`ensureUnique`(`:1140-1148`)加第三个参数 `Long companyId`,wrapper 首行 `.eq(DedupeTotalDataEntity::getCompanyId, companyId)`;`existsDataValue`(`:1150-1155`)同样加公司条件(`:931` 那个 DuplicateKey 回退分支靠它,不加就会把 B 公司的新值误判成"已存在"而少插一行)。调用点:`:440`(create)、`:1100`(update)、`:931`(回退分支,companyId 已在形参里)。 + +- [ ] **Step 5: `AccessScope` 加公司,写闸门先过它** + +`:1405` 变 `private record AccessScope(boolean allUsers, Set groupIds, Set userIds, Long companyId) {}`;`resolveAccessScope`(`:1179-1205`)两个返回点分别给 `null`(超管)与 `requireWritableCompanyId(operator)`(非超管)。 +`ensureRecordAccess`(`:1270-1282`)在 `scope.allUsers()` 之后插一行公司闸门(跨公司的单行改/删/删除导入都会在这儿被拦): + +```java + if (scope.companyId() != null && !scope.companyId().equals(entity.getCompanyId())) { + throw new ResponseStatusException(HttpStatus.FORBIDDEN, "无权操作其他公司的总数据"); + } +``` + +**`applyGroupScope`(`:1207-1232`)本任务不动**——它同时是列表/导出/删除的过滤出口,叠公司属于批次 3 的读侧改动(Task 8),跟着写侧一起改会让"批次 1 线上零变化"这句话失去依据。 + +- [ ] **Step 6: 跑绿 + 提交** + +Run: `mvn -o -B -q test -Dtest='DedupeTotal*Test,CompanyScope*Test'` → 绿。 +Run: `mvn -o -B test` → 全量绿。 + +变异自证(护栏 2 续):① `insertBatchIgnore` 删 `company_id`;② `startImport` 不往 `runImportTask` 传公司(编译不过,改为把 `entity.setCompanyId(companyId)` 换成 `entity.setCompanyId(null)`);③ `ensureUnique` 删公司条件;④ `resolveAccessScope` 非超管分支的 companyId 传 null ⇒ `ensureRecordAccess` 的跨公司拦截红。 + +```bash +git add backend-java/src/main/java/com/nanri/aiimage/modules/dedupe \ + backend-java/src/test/java/com/nanri/aiimage/modules/company/CompanyScopeWriteOutletTest.java +git commit -m "feat(公司隔离): 去重库四个写入口带 company_id,判重与写闸门按公司收窄" +``` + +--- + +## Task 5: 去重库消费侧(隔离在这里才真正生效) + +**Files:** +- Modify: `modules/dedupe/mapper/DedupeTotalDataMapper.java`(`selectExistingDataValues` `:20-21` + `SqlProvider` `:41-47`) +- Modify: `modules/dedupe/service/DedupeTotalDataService.java`(`findExistingComparableValues` `:457-481`、`:902` 调用点、`listComparableValues` `:450-455`、`selectAllDataValues` `:18-19`) +- Modify: `modules/dedupe/service/DedupeRunService.java`(`:680-682` 形参、`:493` 调用点、`:749` 消费点) +- Test: `DedupeTotalDataServiceTest`、`DedupeRunService*Test`、`CollectDataBatchQueryTest` + +**Interfaces:** +- Consumes: Task 4 的 `companyId`(已穿过 `insertImportBatch`)、`FileTaskEntity.getUserId()`(`processFile` 形参 `task`,`DedupeRunService.java:467-469`)。 +- Produces: + - `List selectExistingDataValues(@Param("values") List values, @Param("companyId") Long companyId)` + - `Set DedupeTotalDataService.findExistingComparableValues(Collection values, Long companyId)` + +- [ ] **Step 1: 把 provider SQL 换成 ` + """) + List selectExistingDataValues(@Param("values") List values, @Param("companyId") Long companyId); +``` + +同时删 `selectAllDataValues()`(`:18-19`)与 `listComparableValues()`(service `:450-455`)——**全仓零消费方**(已 grep 确认,只被自己引用),它是一条无租户条件的全表读,留着就是将来被人接进过滤链的旁路(同 §8 让删 `filterByExistingAsin` 的理由)。删 import/方法收尾用编译器(`mvn -o -B -q test-compile`)而不是 grep。 + +- [ ] **Step 2: service 侧 fail-fast + 传公司** + +```java + /** + * 按公司查已存在的值(导入判重与去重任务运行时判重共用,§8 消费方 #3/#4)。 + * companyId 为 null 一律抛:静默不过滤等于退回"全平台共享一套",正是本方案要拆掉的东西。 + */ + public Set findExistingComparableValues(Collection values, Long companyId) { + if (companyId == null || companyId <= 0) { + throw new BusinessException("去重库按公司查询时 company_id 不能为空"); + } + ... // 归一化/distinct/分批逻辑保持原样,只把 mapper 调用换成 selectExistingDataValues(batch, companyId) + } +``` +`:902` 调用点改成 `findExistingComparableValues(values, companyId)`。 + +- [ ] **Step 3: 去重任务运行时判重带上任务归属公司** + +`DedupeRunService.processFile(..., FileTaskEntity task, ...)` 已握着 task;把公司解析放进 `processFile`(每个文件一次 PK 查询,不在 `cleanExcelByStreamRules` 的读循环里): + +```java + Long companyId = companyScope.requireCompanyId(task.getUserId()); + cleanExcelByStreamRules(inputFile, outputFile, request.getSelectedColumns(), + request.isKeepIntegerIds(), request.isKeepUnderscoreIds(), + request.isKeepIntegerMainIdsWhenNoSubIds(), companyId); +``` +`:680-682` 形参表末尾加 `Long companyId`,`:749` 改成 +`Set matchedAsinValues = dedupeTotalDataService.findExistingComparableValues(candidateAsinValues, companyId);` +(`DedupeRunService` 需注入 `CompanyScopeSupport`;测试里补 mock + `lenient().when(companyScope.requireCompanyId(any())).thenReturn(1L)`)。 + +- [ ] **Step 4: 加两条可跑断言 + 跑绿** + +`DedupeTotalDataServiceTest` 补:`findExistingComparableValues(List.of("A"), null)` 抛 `BusinessException`;`findExistingComparableValues(List.of("A"), 3L)` 让 mapper 调用带上 `(anyList(), eq(3L))`(`verify(dedupeTotalDataMapper).selectExistingDataValues(anyList(), eq(3L))`)。 +Run: `mvn -o -B -q test -Dtest='Dedupe*Test,CompanyScope*Test'` → 绿;`mvn -o -B test` → 全量绿。 + +- [ ] **Step 5: 变异(护栏 3 前半)** + +① 把 `WHERE company_id = #{companyId}` 注释掉 → `CompanyScopeConsumerOutletTest`(Task 6 建)应红,先手工 `grep -c` 验一次字符串还在;② `:749` 传 null → service 的 fail-fast 用例红;③ 把 `findExistingComparableValues(values, companyId)` 退回 `findExistingComparableValues(values)` → 编译红(说明没有静默旁路)。 + +```bash +git add backend-java/src/main/java/com/nanri/aiimage/modules/dedupe \ + backend-java/src/test/java/com/nanri/aiimage/modules/dedupe +git commit -m "feat(公司隔离): 去重库两个判重消费方带上 company_id,删掉无租户的全表读旁路" +``` + +--- + +## Task 6: 采集消费侧(`CollectDataBatchQuery`)+ 护栏 3 + +**Files:** +- Modify: `modules/collectdata/util/CollectDataBatchQuery.java`(删 `:38-42` 兼容入口、`:49` 签名、`:58` dedupe 调用、`:75-78` brand 查询) +- Modify: `modules/collectdata/service/CollectDataService.java`(`:810` 之后解析一次、`:835` 调用点) +- Modify: `modules/collectdata/service/CollectDataBrandRecheckInjector.java`(`:125`) +- Test: `CollectDataBatchQueryTest`(约 10 处 `filterByExistingAsin` 全部迁到 `filter(rows, companyId)`)、`CollectDataBrandRecheckInjectorTest:122/182`、`CollectDataServiceTxBoundaryTest:148` +- Create: `src/test/java/com/nanri/aiimage/modules/company/CompanyScopeConsumerOutletTest.java` + +**Interfaces:** +- Consumes: `Task 5` 的 `selectExistingDataValues(values, companyId)`。 +- Produces: `CollectDataBatchQuery.FilterResult filter(List rows, Long companyId)`;`filterByExistingAsin` **不存在**。 + +- [ ] **Step 1: 写护栏 3(先红)** + +```java +package com.nanri.aiimage.modules.company; + +import org.junit.jupiter.api.Test; + +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.List; +import java.util.stream.Collectors; +import java.util.stream.Stream; + +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 护栏 3(设计 §10.3):消费侧那几条裸 SQL 必须带租户条件,且不许有第二份无条件的兼容入口。 + * + *

写侧带 company_id 而消费侧不过滤,结果是新行照样互相过滤——越界发生在读,不是写。 + * 这批 SQL 都在 @Select/@Insert 字面量或 QueryWrapper 里,行为测试要靠 mock 才看得见, + * 所以这里既扫源码也留可跑断言(见 CollectDataBatchQueryTest 的 companyId 用例)。

+ */ +class CompanyScopeConsumerOutletTest { + + private static final Path MAIN = Path.of(System.getProperty("user.dir"), "src/main/java"); + private static final Path BATCH_QUERY = MAIN.resolve("com/nanri/aiimage/modules/collectdata/util/CollectDataBatchQuery.java"); + private static final Path DEDUPE_MAPPER = MAIN.resolve("com/nanri/aiimage/modules/dedupe/mapper/DedupeTotalDataMapper.java"); + + @Test + void dedupeConsumerSqlCarriesTheCompanyPredicate() throws IOException { + String mapper = read(DEDUPE_MAPPER); + assertTrue(mapper.contains("WHERE company_id = #{companyId}"), + "selectExistingDataValues 必须按公司过滤:" + mapper.substring(0, Math.min(mapper.length(), 200))); + assertFalse(mapper.contains("selectAllDataValues"), + "全表无租户取值的旁路必须消失(删 listComparableValues 的理由)"); + } + + @Test + void brandConsumerQueryCarriesTheCompanyColumn() throws IOException { + String text = read(BATCH_QUERY); + assertTrue(text.contains(".eq(\"company_id\", companyId)"), + "品牌库那条集合查询要叠公司条件"); + assertTrue(text.contains("selectExistingDataValues(asins, companyId)"), + "去重库那条要显式传公司"); + } + + /** 破坏点:有人把兼容入口当"历史包袱"加回来,就得到一条永远不带租户的旁路。 */ + @Test + void noUntetheredCompatEntryRemains() throws IOException { + assertFalse(read(BATCH_QUERY).contains("filterByExistingAsin"), + "filterByExistingAsin 生产零调用,留着就是旁路"); + List users; + try (Stream s = Files.walk(MAIN)) { + users = s.filter(p -> p.toString().endsWith(".java")).filter(p -> read(p).contains("filterByExistingAsin")).toList(); + } + assertTrue(users.isEmpty(), "filterByExistingAsin 的引用必须清零,仍在:" + users); + } + + private static String read(Path p) { + try { return Files.readString(p, StandardCharsets.UTF_8); } + catch (IOException e) { throw new IllegalStateException(e); } + } +} +``` + +Run: `mvn -o -B -q test -Dtest=CompanyScopeConsumerOutletTest` → 三条全红。 + +- [ ] **Step 2: 改 `CollectDataBatchQuery`** + +删 `:38-42`(`filterByExistingAsin` 及其 javadoc)。`filter` 改签名并在两条查询上用**列名** QueryWrapper 风格(该类现有注释明确说单测不依赖 MyBatis-Plus lambda 缓存,保持这个口径): + +```java + public FilterResult filter(List rows, Long companyId) { + if (companyId == null || companyId <= 0) { + throw new IllegalStateException("采集过滤缺 company_id:拒绝退回全平台共享的规则库"); + } + if (rows == null || rows.isEmpty()) { + return new FilterResult(List.of(), 0, 0); + } + ... + List existing = dedupeTotalDataMapper.selectExistingDataValues(asins, companyId); + ... + List invalidRows = invalidAsinDataMapper.selectList( + new QueryWrapper() + .select("brand") + .eq("company_id", companyId) + .in("brand", brands)); +``` + +- [ ] **Step 3: 两个调用点各解析一次公司(和 Task 3 的 scope 复用同一次解析)** + +`CollectDataService.submitResult`:`:810` 已有 `probe`(`FileTaskEntity`),在锁外预处理之前解析一次,供 `:835` 的 `filter` 与 `:899` 的 `writeBatch` 共用: + +```java + Long companyId = companyScope.requireCompanyId(probe.getUserId()); + ... + CollectDataBatchQuery.FilterResult filtered = collectDataBatchQuery.filter(rowsForFiltering, companyId); + ... + invalidAsinBatchWriter.writeBatch(brandOutcome.rejected(), + new InvalidAsinAutoWriteScopeResolver.AutoWriteScope( + companyId, task.getUserId(), autoWriteGroupIdOf(task.getUserId()))); +``` + +> 落地时不要把 `AutoWriteScope` 在这里手搭——注入 `InvalidAsinAutoWriteScopeResolver`,调 `resolve(probe.getUserId())` 一次,把结果同时喂给 `filter(..., scope.companyId())` 与 `writeBatch(rows, scope)`。上面这段是为了说明"一次解析、两处用"的形状;**最终代码用 resolver 的返回值**,别出现第二处 group 逻辑。锁外 `probe` 与锁内 `task` 是同一行的两次读,userId 相同(任务归属不会中途变更),所以用 `probe` 解析、锁内复用是安全的——在这行代码上方留一句注释说明这个前提。 + +`CollectDataBrandRecheckInjector.apply`(`:78` 形参带 `task`):`InvalidAsinAutoWriteScopeResolver.AutoWriteScope scope = invalidAsinAutoWriteScopeResolver.resolve(task.getUserId());` 放在 chunk 循环外(每个任务一次),`:114` 用 `writeBatch(chunkRejected, scope)`,`:125` 用 `filter(chunkClean, scope.companyId())`。 + +- [ ] **Step 4: 迁移测试并跑绿** + +`CollectDataBatchQueryTest`:`query.filterByExistingAsin(X)` → `query.filter(X, 1L).kept()`;`when(dedupeMapper.selectExistingDataValues(anyList()))` → `(..., anyLong())`;`:103/:117/:153` 的 `verify(...)` 同步改。补两条新用例:`filter(rows, null)` 抛 `IllegalStateException`;`filter(rows, 7L)` 后 `verify(dedupeMapper).selectExistingDataValues(anyList(), eq(7L))` 且 `invalidAsinDataMapper.selectList` 收到的 wrapper SQL 片段含 `company_id`(用 `ArgumentCaptor` 取 `getCustomSqlSegment()`/`getExpression().getNormalize().getSqlSegments()` 之一,**先实跑确认取到的是非空串**,取不到就退化成只验 `eq(7L)`)。 +`CollectDataServiceTxBoundaryTest:148` → `filter(any(), any())`;`CollectDataBrandRecheckInjectorTest:122/182` → `filter(anyList(), any())`。 +Run: `mvn -o -B -q test -Dtest='CollectData*Test,CompanyScope*Test'` → 绿;再 `mvn -o -B test` 全量。 + +- [ ] **Step 5: 变异(护栏 3 后半)** + +注入:① 把 `.eq("company_id", companyId)` 注释掉;② 把 `WHERE company_id = #{companyId}` 从 mapper 删掉;③ 把 `filterByExistingAsin` 加回来。三条各让对应那条红。**收尾把三个文件按内存里的原始字节写回**,`git status --porcelain` 必须只剩本任务预期的改动。 + +- [ ] **Step 6: 批次 2 上线判断(交付命令,不自行执行)** + +批次 2 含消费侧改动 ⇒ 两台必须同版、金丝雀过了立刻补第二台;发版前先跑既有三取证(有没有人在跑任务)。只交付: + +```bash +python scripts/_deploy_jar_and_restart_both.py <构建出的 jar> +``` + +> 部署属共享系统动作:先向用户复述"要不要现在重启(在飞 LLM 批次代价)",由用户执行或明确授权。**不 skipTests。** + +```bash +git add backend-java/src/main/java/com/nanri/aiimage/modules/collectdata \ + backend-java/src/main/java/com/nanri/aiimage/modules/dedupe \ + backend-java/src/test/java/com/nanri/aiimage/modules/collectdata \ + backend-java/src/test/java/com/nanri/aiimage/modules/company/CompanyScopeConsumerOutletTest.java +git commit -m "feat(公司隔离): 采集过滤两条裸 SQL 叠 company_id,删掉无租户的兼容入口" +``` + +--- + +## Task 7: 品牌库读侧(批次 3:摘 `record_source='MANUAL'` 硬条件) + +**Files:** +- Modify: `modules/invalidasin/service/InvalidAsinDataService.java`(`page` `:34-77`、`ensureRecordAccess` `:177-193`、`toItemVo` `:239-250`) +- Modify: `modules/invalidasin/model/vo/InvalidAsinDataItemVo.java` +- Modify: `modules/invalidasin/controller/InvalidAsinDataController.java`(`page` 参数 `:57-68`) +- Test: `InvalidAsinDataServiceTest`、`InvalidAsinDataControllerTest`、新建 `CompanyScopeReadPathTest` + +**Interfaces:** +- Produces: `page(long page, long pageSize, String keyword, String dataValue, String brand, Long groupId, Long requestedCompanyId, Long operatorId, boolean superAdmin)`;`InvalidAsinDataItemVo.companyId/companyName`。 +- Consumes: `CompanyService.namesByIds(Collection)`(`CompanyService.java:82`,批量补名,**不许逐行查**)。 + +- [ ] **Step 1: 写护栏 4(先红)** + +`CompanyScopeReadPathTest` 两支: + +```java +/** 破坏点:MANUAL 硬条件留着,非超管对本组新的自动导入行永久失明(§1.3)。 */ +@Test void nonSuperAdminListNoLongerHardcodesManualRecordSource() + -> executableLines(InvalidAsinDataService.java) 里不得再出现 "RECORD_SOURCE_MANUAL" + 且必须出现 "InvalidAsinDataEntity::getCompanyId" + +/** 不变式:能写的那一组 = 能看到的那一组(§7.1)。写侧固定组与读侧固定组同源。 */ +@Test void writeAndReadUseTheSameFixedGroup() + -> 源码里 "resolveFixedAccessibleGroupId(operatorId)" 出现次数 == 2(读侧 page + 写侧 requireFixedAccessibleGroupId) + 且 "RECORD_SOURCE_MANUAL" 不再出现在任何 .eq( 之后 + +/** 取样集非空自检(照 CompanyReadPathMenuGateTest#menuGateCallSitesAreActuallyBeingScanned): + * 扫描 0 命中时上面两条恒绿。断言全仓仍能命中 "resolveFixedAccessibleGroupId(" 与 + * "applyGroupScope(" 两处以上,否则红。 */ +@Test void scannedSignaturesAreActuallyPresent() +``` + +- [ ] **Step 2: 改 `page`** + +非超管分支(`:48-55`)从 `eq(recordSource, MANUAL).eq(groupId, fixedGroupId)` 换成: + +```java + Long fixedGroupId = resolveFixedAccessibleGroupId(operatorId); + if (fixedGroupId == null) { + query.eq(InvalidAsinDataEntity::getId, -1L); // 无组可访问 ⇒ 空集,不是"不过滤" + } else { + // 公司硬边界 + 分组维度保持"= 固定组":写侧 resolveManualWriteGroup 非超管只能落这一组 + query.eq(InvalidAsinDataEntity::getCompanyId, companyScope.requireCompanyId(operatorId)) + .eq(InvalidAsinDataEntity::getGroupId, fixedGroupId); + } +``` +超管分支(`:56-57`)保持分组过滤,并加可选公司过滤(参数为 null 就是不过滤;**非超管传了 `company_id` 一律忽略**,见 §9.2): + +```java + } else { + if (groupId != null && groupId > 0) { + query.eq(InvalidAsinDataEntity::getGroupId, groupId); + } + if (requestedCompanyId != null && requestedCompanyId > 0) { + query.eq(InvalidAsinDataEntity::getCompanyId, requestedCompanyId); + } + } +``` +`ensureRecordAccess`(Task 3 已加公司闸门)里删掉 `!isManualRecord(entity) ||` 这半句——保留"本公司 + 固定组"两条即可;`isManualRecord` 仍被 `toItemVo`(`:246`)与 `update`(`:99`)用,**不许顺手删**。 + +- [ ] **Step 3: VO 带公司名** + +`InvalidAsinDataItemVo` 加 `companyId` / `companyName` 两个 `@Schema` 字段;`page` 里按行的 `companyId` 去重后调一次 `companyService.namesByIds(...)`(与既有 `buildGroupNameMap` 同位置),`toItemVo` 加两参。controller 的 `page` 加 `@RequestParam(name = "company_id", required = false) Long companyId` 并传给 service。 +`InvalidAsinDataControllerTest:61/64/66/76/89/92/94` 的实参表各 +1 个 `null`;`InvalidAsinDataServiceTest:88/112/126/143` 同理。 + +- [ ] **Step 4: 跑绿 + 变异(护栏 4)** + +注入:把 `.eq(InvalidAsinDataEntity::getCompanyId, ...)` 换成 `.eq(InvalidAsinDataEntity::getRecordSource, RECORD_SOURCE_MANUAL)` ⇒ 两条断言都该红。 +Run: `mvn -o -B -q test -Dtest='InvalidAsin*Test,CompanyScope*Test'` → 绿。 + +```bash +git commit -am "feat(公司隔离): 品牌库读侧按公司+固定组收窄,摘掉 record_source=MANUAL 硬条件" +``` + +--- + +## Task 8: 去重库读侧与导出(`applyGroupScope` 叠一层公司) + +**Files:** +- Modify: `modules/dedupe/service/DedupeTotalDataService.java`(`applyGroupScope` `:1207-1232`、`page` `:166-216`、`buildExportQuery` `:404-425`、`toItemVo`、`:248-264` `:275-320` 两个导出) +- Modify: `modules/dedupe/model/vo/DedupeTotalDataItemVo.java` +- Modify: `modules/dedupe/controller/DedupeTotalDataController.java`(`page` `:76-93` 与 `/export` `:95-120` 各加一个 `company_id` 参数) +- Modify: `CompanyScopeWriteOutletTest`(追加"读出口带公司"断言,或并进 Task 7 的 `CompanyScopeReadPathTest`) + +**Interfaces:** +- Produces: `buildExportQuery(..., Long requestedCompanyId, AccessScope scope, boolean groupPrevalidated)`;`page(..., Long requestedCompanyId, Long operatorId)`。 + +- [ ] **Step 1: 断言先行** + +在 `CompanyScopeReadPathTest` 补一条:`applyGroupScope` 方法体内必须出现 `scope.companyId()`,且 `allUsers()` 分支之前;`page` 与 `buildExportQuery` 各调用一次 `applyGroupScope`(导出必须走同一个范围出口,否则"列表看不到、导出全给你")。 + +- [ ] **Step 2: 改 `applyGroupScope`** + +```java + private void applyGroupScope(LambdaQueryWrapper query, + AccessScope scope, Long groupId, boolean groupPrevalidated) { + if (!scope.allUsers() && scope.companyId() != null) { + query.eq(DedupeTotalDataEntity::getCompanyId, scope.companyId()); + } + if (groupId != null && groupId > 0) { ... } // 原样 + if (scope.allUsers()) { return; } // 原样 + query.and(wrapper -> { ... }); // 原样 + } +``` +**分组维度一行都不改**:`applyGroupScope` 被列表、两个导出、`deleteByDataValue`、`deleteBatchByDataValues` 共用(`:193/:423/:1160/:1173`),叠这一层公司就同时覆盖读与按值删;这正是 §7.2 说"改一处覆盖两端"的依据。 + +- [ ] **Step 3: 超管可选公司过滤 + VO 公司列** + +`page` 与两个 `write*Export` → `buildExportQuery` 各加 `requestedCompanyId`,只在 `scope.allUsers()` 为真时 `.eq(companyId)`(非超管传了也忽略,同 §9.2)。`DedupeTotalDataItemVo` 加 `companyId/companyName`,`page` 里批量补名同 Task 7。controller 两个 GET 加 `@RequestParam(name="company_id", required=false)`。 + +- [ ] **Step 4: 跑绿 + 变异** + +注入:删掉 `applyGroupScope` 首段 ⇒ 读侧护栏红;把 `buildExportQuery` 的 `applyGroupScope(query, ...)` 换成不过滤 ⇒ "导出不走范围出口"断言红。 +Run: `mvn -o -B -q test -Dtest='Dedupe*Test,CompanyScope*Test'`;再 `mvn -o -B test` 全量(记下总例数)。 + +```bash +git commit -am "feat(公司隔离): 去重库列表与导出叠公司范围,超管可按公司筛" +``` + +--- + +## Task 9: 前端两页(`admin-frontend-vue`) + +**Files:** +- Modify: `src/pages/asin/asin-filter.ts`(`AsinListParams` `:15-29`、`AsinPageQuery` `:32-43`、`toAsinPageQuery` `:75-85`) +- Modify: `src/pages/asin/dedupe-total-filter.ts`(`DedupeTotalFilterState` `:4-16`)、`dedupe-total-export.ts:24-41`、`dedupe-total-model.ts`(`DedupeTotalItem` `:5-15`) +- Modify: `src/pages/asin/DedupeRegistryPage.vue`(公司下拉 `:335-340` 同位置、列 `:373-392`、colspan `:400/:403`、弹窗) +- Modify: `src/pages/invalidasin/invalid-asin-api.ts:9-29`、`src/pages/invalidasin/invalid-asin-model.ts:7-16`、`src/pages/asin/AsinInvalidPage.vue`(`:26` 内联 filter、`:186-191` 筛选、`:199-233` 列/colspan) +- Create: `tests/company-column-asin-pages.test.ts` + +**Interfaces:** +- Consumes: 既有 `src/api/companies.ts:7-10 fetchCompanies()`(`CompanyItem{id, companyName, status, remark}`,来自 `companies-dto.ts:11-18`;**只有 snake_case 会被解析**);`useAdminSessionStore().isSuperAdmin`(`src/stores/admin-session.ts:9,18`)。 +- Produces: 请求参数名 `company_id`(后端 Task 7/8 的新参数)。 + +- [ ] **Step 1: 写失败的前端护栏** + +```ts +// tests/company-column-asin-pages.test.ts +// 不变量:公司列/公司筛选只对超管出现,且非超管一个字节都不许发(后端按会话裁剪,前端发了也忽略)。 +const PAGES = [ + ['src/pages/asin/AsinInvalidPage.vue', /]*>公司<\/th>/], + ['src/pages/asin/DedupeRegistryPage.vue', /]*>公司<\/th>/], +] as const +test('company_column_gated_by_super_admin', () => { + for (const [file, pattern] of PAGES) assert.match(readSource(file), pattern, `${file} 公司列未按超管门控`) +}) +test('company_filter_uses_shared_catalog_endpoint', () => { + for (const [file] of PAGES) { + assert.match(readSource(file), /fetchCompanies/, `${file} 公司候选必须来自 /api/admin/companies(不要另开接口)`) + assert.match(readSource(file), /v-if="isSuperAdmin"[\s\S]{0,220}company_id|companyId/, `${file} 缺公司筛选`) + } +}) +test('ungated_company_column_is_rejected', () => { + for (const [file] of PAGES) assert.doesNotMatch(readSource(file), /]*v-if)[^>]*>公司<\/th>/) +}) +``` + +Run: `cd admin-frontend-vue && node --test tests/company-column-asin-pages.test.ts` → 红。 + +- [ ] **Step 2: 共享参数层** + +`asin-filter.ts`:`AsinListParams` 加 `companyId?: number | null`、`AsinPageQuery` 加 `company_id?: number`,`toAsinPageQuery` 在 `group_id` 那行(`:82`)之后加 `if (typeof params.companyId === 'number' && params.companyId >= 1) query.company_id = params.companyId`。 +`dedupe-total-filter.ts`:状态加 `companyId: number | null`、`createDedupeTotalFilterState()` 返回 `companyId: null`、`dedupeTotalFilterActive` 加 `if (state.companyId != null) return true`、`toDedupeListParams` 透传。 +`dedupe-total-export.ts:24-41`:照 `group_id` 那行加 `if (typeof state.companyId === 'number' && state.companyId >= 1) params.set('company_id', String(state.companyId))`。 +`invalid-asin-api.ts`:`InvalidAsinQuery` 加 `companyId?: number | null`,`toQuery` 加 `if (typeof query.companyId === 'number' && query.companyId >= 1) params.company_id = query.companyId`。 +两个 model(`dedupe-total-model.ts:5-15`、`invalid-asin-model.ts:7-16`)加 `companyId: number | null` 与 `companyName: string`,解析按 snake_case 读 `company_id` / `company_name`。 + +- [ ] **Step 3: 两页各加下拉 + 列,colspan 跟着走** + +照 `DedupeRegistryPage.vue:335-340` 分组下拉的形状,在它**前面**插公司下拉(`v-if="isSuperAdmin"`、`filterable clearable placeholder="全部公司"`、`@change="search"`),`onMounted` 里 `fetchCompanies().then(items => companies.value = items)`。表头/单元格加 `公司` / `{{ row.companyName || '-' }}`,空态 colspan 从 `isSuperAdmin ? 8 : 7` 改成 `isSuperAdmin ? 9 : 7`(两页都是:`DedupeRegistryPage.vue:400/403`、`AsinInvalidPage.vue:230/233`)。 +`AsinInvalidPage.vue:26` 的内联 filter 加 `companyId: null as number | null`,`:60-66` 的请求对象带上它。 + +- [ ] **Step 4: 弹窗联动(§9.3)** + +超管的「新增/导入」弹窗要能选公司,选完之后分组下拉收窄到该公司下的组:现有分组候选来自 `fetchDedupeTotalGroups()`(`dedupe-total-api.ts:35-38`,实际打 `/api/admin/shop-manages/groups`)——**该接口不按公司收窄**,所以今天只有 1 家公司时可以直接把全部分组列出来;实现方式:弹窗里 `companyGroups = computed(() => groups.value)` 并留一句注释说明"店铺分组不携带公司维度(一期定案不复用它当租户键),等阶段B 之后由 groups 接口回带 company_id 再收窄"。**不要**在这里发明一个 company→group 的映射。 + +- [ ] **Step 5: §9.4 文案** + +品牌库「分组」列的"未分组"补 tooltip/说明:`未分组 = 该行为 V145 之前的历史自动导入数据,无归属`。批次 1 之后历史行仍大量显示"未分组"是预期,不写清就会被当成"改造没生效"。 + +- [ ] **Step 6: 跑绿 + 全量前端门禁** + +```bash +cd admin-frontend-vue && node --test tests/company-column-asin-pages.test.ts \ + && node --test tests/*.test.ts && npx vue-tsc --noEmit +``` +基线:干净树 **1687 例 0 红**(10-04 记过一次:`tests/task-43.test.ts` 的 `companyId` 断言由另一路会话补)。若本地跑出任一条与本轮改动无关的红,用 detached worktree 在同批用例上做一次差分再定性,别直接回退别人的文件。 + +```bash +git add admin-frontend-vue/src admin-frontend-vue/tests/company-column-asin-pages.test.ts +git commit -m "feat(公司隔离): 品牌库/去重库两页加公司列与公司筛选(仅超管),弹窗分组联动" +``` + +--- + +## Task 10: 上线与人工验收(`mvn test` 验不到生产库长什么样,这批必须实跑) + +**Files:** 无代码。产物是"执行记录",写进 spec §11.5 对应小节。 + +- [ ] **Step 1: 发版前取证(三查,只读)** + +```bash +python scripts/_prod_watch.py # 值班巡检;ALERTS=0 只回「正常」,† 才计入 +``` +再确认"有没有人在跑任务"决定要不要重启(spec §11.3;`--idle` 白天等不到空窗,别把 IDLE=no 读成没人用)。 + +- [ ] **Step 2: 交付部署命令(由用户执行)** + +`python scripts/_deploy_jar_and_restart_both.py `——两台同版、金丝雀过了立刻补第二台;**逐节点复验打 `127.0.0.1:19080`(B)而不是 `0.0.0.0:18080`**;不 skipTests。 + +- [ ] **Step 3: 跑 V145 末尾「验证 SQL」(Task 2 Step 4 那一段)** + +`SHOW COLUMNS` 两条 + `information_schema.STATISTICS` 那条分组查询(期望恰好两行新键、旧两键不在结果里)。走 Task 0 的 `db_sections` 通道。 + +- [ ] **Step 4: §11.5.3——证明写侧真的显式传了** + +30 分钟内新增的品牌库行:`uploader_user_id IS NOT NULL` 且**等于产生它的那个 task 的 `user_id`**: + +```sql +SELECT d.id, d.company_id, d.uploader_user_id, t.id AS task_id, t.user_id +FROM biz_invalid_asin_data d JOIN biz_task_file_job t ON t.user_id = d.uploader_user_id +WHERE d.created_at > NOW() - INTERVAL 30 MINUTE ORDER BY d.id DESC LIMIT 5; +``` +`uploader_user_id` 没有 DEFAULT,NULL 就直接证明漏传。**同时必须承认**:`company_id` 在只有 1 家公司时无法从数据区分"显式传值"与"DEFAULT 1 兜住",所以"company_id 都有值"不算验收通过——那一面由 Task 3/4 的源码护栏守。 + +- [ ] **Step 5: §11.5.4——双公司插入实验(证唯一键真的放宽)** + +`company_id` 用 1 和一个**不存在的 999**(今天不建第二家公司;实验只验索引宽度,不验外键)在**事务内**跑完 `ROLLBACK`: + +```sql +START TRANSACTION; +INSERT INTO biz_dedupe_total_data (company_id, data_value) VALUES (1, 'ZZTEST0000000001'); +INSERT INTO biz_dedupe_total_data (company_id, data_value) VALUES (999, 'ZZTEST0000000001'); +SELECT COUNT(*) FROM biz_dedupe_total_data WHERE data_value = 'ZZTEST0000000001'; -- 期望 2 +ROLLBACK; +``` +第二条报 1062 ⇒ 旧 `uk_data_value` 还在,Task 2 第 3 段没跑成。**这是本计划唯一一段写生产的 SQL:只在事务里、只插 `ZZTEST` 前缀、只由用户执行。** + +- [ ] **Step 6: 批次 3 的可见性验收** + +用超管与任一 role=admin 账号各开一次两页:非超管应看到"本公司 + 本组"的行(含新的 AUTO 行),且**不应**看到历史 `group_id IS NULL` 的行(§7.1 的刻意切法);超管切公司筛选时应变化(今天只有 1 家公司,切不出差异是正常的,别当失败)。走 `X-Internal-Token` + `?operatorId=` 的服务端重放,不必等用户刷新浏览器。 + +- [ ] **Step 7: 把执行记录写回文档** + +spec §5.4(行数)、§11.5(四条勾选 + 实查值)、`docs/migration-inventory.md`(V145 校验和与 installed_on)。**没跑完不许把 spec 状态从"待评审"改成"已上线"**(§13 的四条待确认也一并落定)。 + +--- + +## 附 A:本计划里"只能同批改"的三对(滞后一条就是线上事故) + +| 一对 | 不同批的后果 | 位置 | +|---|---|---| +| V145 加列 ↔ 两个实体 + 批量 INSERT 列清单 | 只改库不改 jar ⇒ 新行 `company_id` 全靠 DEFAULT,读侧一叠公司就整页空 | Task 2 ↔ 3/4 | +| 品牌库补 `group_id`(AUTO) ↔ 读侧摘 `MANUAL` 硬条件 | 只摘硬条件 ⇒ 非超管一夜看到全部历史无组行;只补 group 不摘 ⇒ 新行照样不可见 | Task 3 ↔ 7 | +| 消费侧叠 `company_id` ↔ 写侧带 `company_id` | 只改写不改读 = 现状不变;只改读不改写 = 别的公司读不到自己刚写的东西,比现状更糟 | Task 5/6 ↔ 3/4 | + +## 附 B:已知不做的东西(别顺手加) + +- 不动 `invalidasin/service/GroupDeletionGuard.java:22` 与 `dedupe/service/GroupDeletionGuard.java:21-27`(去重库那个 `group_id IS NULL` 漏判单独立项,spec §7.3)。 +- 不在本方案里做阶段B 设备令牌(spec §3.2、§12);`/api/collect-data` 收口是"隔离完成"的判定条件,不是本期任务。 +- 不给 `users.company_id` 之外的表再补第三张的公司列(破例只限这两张,spec §12)。 +- 不给这两张表加新的二级索引(Task 2 第 4 段写明理由:今天公司维度只有 1 个值,零选择性)。 +- 不把 `super_admin` 判定收进 `CompanyScopeSupport`(Task 1 写明:先有第 6 份拷贝就更难收敛)。