Files
crawler-plugin/docs/plans/18-brand-dedupe-company-isolation.md
T
huangzd1997 67b62cc3d7 docs(计划): 18 号计划补执行记录,写清 Task 3–8 已停、串扰仍未解决
计划正文不改写(它记的是当时的判断),以「执行记录」段做对账:
Task 0/1/2 完成与两处被实查数据推翻的偏离、Task 3–8 按用户指令停止、Task 9 取消并反向执行。

最关键的一条要留在文档最显眼处:**V145 单独上线不解决跨公司串扰**,
A 公司导入的 ASIN 仍会被 B 公司的去重掉,止血点在消费侧那四个裸 SQL 出口(Task 5–6)。
哪天接着做,从这里接。取号起点同时订正为 V146。
2026-10-04 16:15:22 +08:00

1591 lines
102 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 品牌库 / 去重库 按公司隔离(二期)实施计划
> **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. **取号看盘点文档**:V145 已落盘(当前最大 `V145`、144 个文件),`docs/migration-inventory.md` 已写明"后续新增迁移从 **V146** 起取号"。不许为没写出来的迁移预留号段(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 是取证与验收,不产出运行代码。
---
## 执行记录(2026-10-04 15:5x,计划与现状的对账,后来者先读这段)
**已完成:** Task 0(生产只读取证)、Task 1(`CompanyScopeSupport`,已提交 `8cb53e6b`)、Task 2(V145 + 回滚脚本 + 审计用例 + 哨兵扩容 + V144 进冻结清单)。Task 2 的验证:`CompanyScopeMigrationV145Test` 13 例、`CompanyMigrationV144Test` 8 例、`CompanyDefaultGuardTest` 12 例、`MigrationInventoryTest` 8 例全绿;变异自证 17 轮全被杀(含"摘掉 INSTANT 钉法""用 MODIFY 收 nullability""反推 UPDATE 丢幂等限定""回滚把 DROP COLUMN 变成默认动作""原地改已应用的 V144 一个空格")。
**两处对计划的偏离(都是实查数据推翻计划,计划正文未改写,以此段为准):**
1. **Task 2 没按三段式写。** 计划抄的是 V143 的「加可空列 → 全表回填 → MODIFY 收 NOT NULL」。生产 `biz_dedupe_total_data` 实测 **507,306 行 / 181.3 MB**、MySQL **8.4.8**:非末位加列与 `MODIFY` 改 nullability 都要重建表,单语句全表回填会对所有扫描行持 X 锁。V145 因此改成**末位加列 + 显式钉 `ALGORITHM = INSTANT`**、列直接建成 `NOT NULL DEFAULT 1`、索引四条钉 `INPLACE, LOCK = NONE`,回填那一步换成一条**由 users 驱动、带 `d.company_id = 1` 幂等限定**的反推 UPDATE(只动第 2 家账号上传的行,走 `idx_uploader_user_id_id` 点查)。
2. **DEFAULT 的摘除时点被现实压缩。** 计划假定"第二家公司开通前摘掉 DEFAULT",实际 `company.id=2` 已于 **10-04 14:55 开通**(账号 `users.id=1193`,140 个账号里唯一 `company_id<>1`)。所以 V145 保留 `DEFAULT 1`(混合版本窗口必需),把"紧随本次发布出 V146 摘 DEFAULT"写进头注释,并让启动期哨兵 `CompanyDefaultGuard` 从只探 `users` 扩成探 `users` + 两张规则库表。**注意:摘 DEFAULT 必须用 `ALTER TABLE t ALTER COLUMN company_id DROP DEFAULT`(纯元数据),不能照 V144 用 MODIFY——表重建会按当时的列默认值物化 instant 列,把反推好的归属洗回 1。**
**Task 3–8:停止(用户 10-04 15:5x 指令)。** 写侧/消费侧/读侧的公司维度都没有落地,因此**跨公司串扰仍然存在**:A 公司导入的 ASIN 仍会被 B 公司的去重掉,根因是 `uk_data_value` 全局唯一键之外的消费侧裸 SQL(`CollectDataBatchQuery` 等四个出口)不按公司过滤。V145 单独上线**不解决这件事**——它只是让归属开始被记录、并把新唯一键准备好。
**Task 9:取消,反向执行。** 用户同时定案"公司维度不在前端出现",所以两页不加公司列,反而把一期已上线的公司展示全部摘掉(列/筛选/建号选择/顶栏旁白)。建号请求体不再带 `company_id`,归属由后端 `AdminUserService#resolveTargetCompanyId` 落操作者自己的公司——这条前端删下拉的安全依据被 `admin-frontend-vue/tests/company-user-create.test.ts` 用跨仓读取钉成可执行断言(后端两条"落操作者公司"分支少任何一条,前端测试即红)。保留:公司管理页(启用/停用)、后端 `company_id` 接口参数。
顺带修一处被这次改动变成假话的文案:「公司管理」页的引导语原写"建号时选哪家公司",下拉删掉后它承诺了一个不存在的选择器;同时"停用后不能再用于新建账号"也不再成立——`companyService.requireActive` 只有两个调用点(`AdminUserService:211`/`:228`),都要求 `company_id != null`,而页面现在一律不传,所以这条从后台 UI 走不到(接口直连的老调用方仍受保护)。文案改为"落在操作者自己所在的公司,要给别家建号请用那家公司自己的管理员登录",并由 `company-user-create.test.ts` 反向断言这三句失效说法不得回流。
---
## 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<AdminUserEntity>`)、`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)。
*
* <p>这里最重要的不是"能取到公司",而是<b>取不到时必须炸</b>:漏传 company_id 一旦退回 null,
* 下游就落进 V145 的列 DEFAULT=1,第二家公司开通后每个漏传都会静默归到厦门米椿花(§6.3 / §11.2)。</p>
*/
@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)——数据出口只认这一个入口。
*
* <p>一期"业务表零 DDL"靠 {@code user_id → users.company_id} 派生;本期两张规则库表破例物化了
* {@code company_id}(§2.2),但<b>归属仍然从账号解析</b>,物化列只是把它固定下来、好让唯一键与
* 消费侧的集合查询用得上。</p>
*
* <p>取不到公司一律抛,不返回 null:调用方一旦把 null 传进实体,MyBatis-Plus 会跳过该列,
* 落库时被 V145 的 {@code DEFAULT 1} 静默兜住——那是"归属失真且不报错"的成因(§6.3)。</p>
*/
@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> 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。
*
* <p>本仓 pom 无 H2、无 testcontainers,迁移跑不起来,所以文件审计是唯一能守住的层——
* 与 CompanyMigrationV143Test/V144Test 同口径:断言打在剥掉注释后的可执行 SQL 上。</p>
*/
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<String> 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<Path> 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<CollectDataResultRowVo> 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。
*
* <p>为什么打在源码上而不是行为上:V145 的列 DEFAULT=1 会让"漏传"落库成功——
* 只有源码这一层能区分"显式传了本公司"与"被 DEFAULT 兜住"(§11.5.3 承认数据无法区分)。</p>
*/
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<String> 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<String> 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<String> 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<String> 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<String> insertLiterals(String source) {
// 抓 @Insert(""" ... """) 的文本块内容;不做完整 JavaParser,够用即可,但必须能命中真实两处
java.util.List<String> 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<Path> javaSources() {
try (Stream<Path> 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<String> 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("""
<script>
INSERT IGNORE INTO biz_invalid_asin_data
(data_value, brand, record_source, group_id, company_id, uploader_user_id)
VALUES
<foreach collection="rows" item="row" separator=",">
(#{row.dataValue}, #{row.brand}, #{row.recordSource}, #{row.groupId}, #{row.companyId}, #{row.uploaderUserId})
</foreach>
</script>
""")
int insertBatchIgnore(@Param("rows") List<InvalidAsinDataEntity> 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;
/**
* 自动导入写入品牌库时的三元归属:公司(硬边界)+ 账号(审计锚点)+ 分组(可见性)。
*
* <p>group_id 与 company_id 必须一起补:读侧 §7.1 保留"= 固定组",只补公司不补分组的话,
* 新的 AUTO 行仍会因为 group_id IS NULL 对所有非超管永久不可见(§1.3 那个硬条件刚摘掉)。</p>
*
* <p>固定组取"可访问组里 id 最小的那个",与 {@code InvalidAsinDataService:203-212}
* 的 {@code resolveFixedAccessibleGroupId} 同口径——写侧落哪一组 = 读侧看哪一组,这条不变式由
* {@code CompanyScopeReadPathTest} 钉住。</p>
*/
@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<Long> 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 忽略重复,幂等)。
*
* <p>scope 必须在进批次循环之前判完:{@code :58-60} 那个 catch 会把 RuntimeException 吞成
* 一句 log.warn 并跳过整批,接口仍返回成功。归属缺失如果落进那个 catch,表现就是
* "自动导入静默丢数据、没人知道"(设计 §11.2)。</p>
*/
public int writeBatch(List<CollectDataResultRowVo> 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<InvalidAsinDataEntity> query = new LambdaQueryWrapper<InvalidAsinDataEntity>()
.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<Long> groupIds, Set<Long> userIds, Long companyId)`(第四位是本任务新加的;`applyGroupScope` 的读过滤本任务**不动**)
- `private void ensureUnique(String dataValue, Long excludeId, Long companyId)`
- `private boolean existsDataValue(String dataValue, Long companyId)`
- `private ImportBatchResult insertImportBatch(List<String> values, Map<String,String> 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
/**
* 写入口的公司归属:非超管与超管都取操作人自己的公司。
*
* <p>与分组不同,公司【不是】请求参数能决定的——超管能挑分组,不该能挑公司;
* 否则"这条数据归谁"就取决于前端多传一个字段(§6.2 的取值规则)。</p>
*/
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<Long> groupIds, Set<Long> 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<String> selectExistingDataValues(@Param("values") List<String> values, @Param("companyId") Long companyId)`
- `Set<String> DedupeTotalDataService.findExistingComparableValues(Collection<String> values, Long companyId)`
- [ ] **Step 1: 把 provider SQL 换成 `<script>` @Select**
`DedupeTotalDataMapper`:删掉 `SqlProvider` 内联类(两条 `@Select` 合并成一条注解脚本),改成:
```java
@Select("""
<script>
SELECT data_value FROM biz_dedupe_total_data
WHERE company_id = #{companyId}
AND data_value IN
<foreach collection="values" item="value" open="(" separator="," close=")">#{value}</foreach>
</script>
""")
List<String> selectExistingDataValues(@Param("values") List<String> 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<String> findExistingComparableValues(Collection<String> 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<String> 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<CollectDataResultRowVo> 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 必须带租户条件,且不许有第二份无条件的兼容入口。
*
* <p>写侧带 company_id 而消费侧不过滤,结果是新行照样互相过滤——越界发生在读,不是写。
* 这批 SQL 都在 @Select/@Insert 字面量或 QueryWrapper 里,行为测试要靠 mock 才看得见,
* 所以这里既扫源码也留可跑断言(见 CollectDataBatchQueryTest 的 companyId 用例)。</p>
*/
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<Path> users;
try (Stream<Path> 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<CollectDataResultRowVo> 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<String> existing = dedupeTotalDataMapper.selectExistingDataValues(asins, companyId);
...
List<InvalidAsinDataEntity> invalidRows = invalidAsinDataMapper.selectList(
new QueryWrapper<InvalidAsinDataEntity>()
.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<QueryWrapper>` 取 `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<Long>)`(`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<DedupeTotalDataEntity> 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 v-if="isSuperAdmin"[^>]*>公司<\/th>/],
['src/pages/asin/DedupeRegistryPage.vue', /<th v-if="isSuperAdmin"[^>]*>公司<\/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), /<th(?![^>]*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)`。表头/单元格加 `<th v-if="isSuperAdmin" style="width: 140px">公司</th>` / `<td v-if="isSuperAdmin">{{ row.companyName || '-' }}</td>`,空态 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 <jar>`——两台同版、金丝雀过了立刻补第二台;**逐节点复验打 `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 份拷贝就更难收敛)。