清设计痕迹(卖源码): 删 84 项跟踪文档/spec/plan/prompt+5 支纯文档用例+4 支没人接进闸门的审计工具,9 支混合用例只摘读 docs 的那几段

V143–V152 的迁移契约用例逐支过:87 例 0 红(mvn -o test 实跑)。混合类里钉"迁移文件本体"的断言全部保留,
只删/只切按路径读 docs 的方法;两支 scannedSignaturesAreActuallyPresent 是防恒绿的自检,
它自检的对象(回滚补丁)已随文档出仓,那几行留在类里就变成给空断言背书,所以一并摘掉。
删除面 241 个唯一副本的归档在 D:\archive\design-scrub-2026-10-11\,逐个 sha256 回读。
This commit is contained in:
2026-10-11 16:01:53 +08:00
parent 8710acf522
commit 560148e575
97 changed files with 0 additions and 27033 deletions
-68
View File
@@ -1,68 +0,0 @@
# Multi-Server Start Commands
Use the same packaged jar on both servers. Do not switch code comments before packaging.
Requirements:
- Build once: `mvn clean package -DskipTests`
- Use profile: `server`
- Put JVM options before `-jar`
- Pass `AIIMAGE_INSTANCE_ID` and Redis address from the startup command
- Result file job MQ is expected to stay enabled in packaged `server` deployments
- Use `https://oss.aishufu.top` for the MinIO SDK and public object URLs; `https://minio.aishufu.top` is the management console only
1Panel server 121:
Environment variables:
```env
SPRING_PROFILES_ACTIVE=server
AIIMAGE_INSTANCE_ID=server-121
AIIMAGE_REDIS_HOST=192.168.0.172
AIIMAGE_REDIS_PORT=16379
AIIMAGE_REDIS_PASSWORD=B6COTcY094TYe545
AIIMAGE_REDIS_DATABASE=0
AIIMAGE_SERVER_PORT=18080
AIIMAGE_STORAGE_LOCAL_TEMP_DIR=/app/data/tmp
AIIMAGE_OSS_ENDPOINT=https://oss.aishufu.top
AIIMAGE_OSS_PUBLIC_ENDPOINT=https://oss.aishufu.top
AIIMAGE_RESULT_FILE_JOB_MQ_ENABLED=true
AIIMAGE_ROCKETMQ_NAME_SERVER=121.196.149.225:9876
AIIMAGE_TRANSIENT_STORAGE_ENDPOINT=http://121.196.149.225:9000
AIIMAGE_SIMILAR_ASIN_IMAGE_DOWNLOAD_POOL_SIZE=2
```
Recommended startup command:
```bash
java -Xmx2048M -Xms2048M -jar /app/aiimage-backend-0.0.1-SNAPSHOT.jar
```
Baota server 111:
```bash
/www/server/java/jdk-21.0.2/bin/java -Xmx1024M -Xms256M -jar /app/java/aiimage-backend-0.0.1-SNAPSHOT.jar --spring.profiles.active=server --aiimage.instance-id=server-111 --spring.data.redis.host=47.111.163.154 --spring.data.redis.port=16379 --spring.data.redis.password=B6COTcY094TYe545 --server.port=18080 --aiimage.storage.local-temp-dir=/app/data/tmp --aiimage.oss.endpoint=https://oss.aishufu.top --aiimage.oss.public-endpoint=https://oss.aishufu.top
```
Optional Baota server 121 command:
```bash
/www/server/java/jdk-21.0.2/bin/java -Xmx1024M -Xms256M -jar /app/java/aiimage-backend-0.0.1-SNAPSHOT.jar --spring.profiles.active=server --aiimage.instance-id=server-121 --spring.data.redis.host=192.168.0.172 --spring.data.redis.port=16379 --spring.data.redis.password=B6COTcY094TYe545 --server.port=18080 --aiimage.storage.local-temp-dir=/app/data/tmp --aiimage.oss.endpoint=https://oss.aishufu.top --aiimage.oss.public-endpoint=https://oss.aishufu.top
```
Successful startup should show a line similar to:
```text
[instance] resolved instanceId=server-121 source=configured
```
or:
```text
[instance] resolved instanceId=server-111 source=configured
```
If the instanceId in the log does not match the startup command, the actual process was not started with the expected command.
For the 4-core production host, set the Java container CPU limit to 2.5 cores in 1Panel
(container resources / CPU limit). Keep `AIIMAGE_SIMILAR_ASIN_IMAGE_DOWNLOAD_POOL_SIZE=2`.
The application also clamps this pool to half of the JVM-visible processors as a second guard.
@@ -1,36 +0,0 @@
# Flyway 迁移演练 runbook(task-201)
> 目的:在**副本库**上验证新增迁移可干净执行、验证 SQL 通过、可回滚、可幂等重跑,且全程不动历史迁移。
> 本文档为演练步骤与检查清单;on-DB 执行需运维在有副本库的机器按步骤进行(本地/CI 无库时不执行 migrate)。
## 前置
- 副本库:与生产同版本(MySQL 8.4),已执行到当前最大版本 V108(与生产一致)。
- 拿到待演练的新迁移:`src/main/resources/db/V{N+1}__*.sql`,头注释引用 `docs/flyway-migration-template.md`(task-192)六项必填齐全。
## 演练步骤
1. **基线核对**:`flyway -url=<副本> info` 确认版本、描述、checksum 与生产一致;`git log` 确认历史 V1..V108 未被改动。
2. **validate**:`flyway validate` —— 校验历史迁移 checksum,任何历史文件被改动会立刻失败(违规红线)。
3. **干净迁移**:把待演练迁移放入后 `flyway migrate`;记录成功版本、耗时。
4. **验证 SQL**:执行迁移头注释第 4 项的验证 SQL(行数/索引/SHOW INDEX),确认结果符合预期。
5. **回滚验证**:按头注释第 5 项回滚脚本回滚新迁移(若无回滚脚本,验证迁移可幂等重跑替代)。
6. **幂等重跑**:回滚后再 `flyway migrate` 一次,确认可重复、无残留副作用。
7. **锁窗口评估**:索引类迁移记录执行耗时与是否 ONLINE,结合表数据量估算生产锁窗口。
8. **收尾**:记录结论到本清单;生产窗口按 template 第 6 项执行。
## 离线静态检查(本仓库 JUnit 已覆盖)
- 迁移文件整数版本 1..N 连续、无重复(`MigrationInventoryTest`,task-193)。
- 迁移校验和可复算稳定(同一文件两次读 SHA-256 一致,`MigrationInventoryTest`)。
- 新迁移命名合规、模板六字段可引用(`FlywayMigrationTemplateDocTest`,task-192)。
## 完成检查
- [ ] 副本库 `flyway migrate` 干净执行(版本升至目标)
- [ ] 验证 SQL 通过
- [ ] 回滚验证通过 / 幂等重跑通过
- [ ] 锁窗口已按表量估算并记录
- [ ] 历史迁移未被改动(`flyway validate` 通过)
> 注:CI/本地无数据库环境时,本 runbook 的第 3-7 步需在带副本库的机器执行;仓库内以静态检查 + 本清单兜底。
@@ -1,53 +0,0 @@
# Flyway 迁移规范模板(task-192)
> 新增数据库迁移一律在本仓库 `src/main/resources/db/` 追加 `V{N+1}__*.sql`(版本号在现有最大版本之上加 1),
> 每个迁移文件头必须引用本模板并补齐六项必填。**只追加,绝不修改已部署的历史迁移**(会破坏 Flyway 校验和)。
复制以下头注释到新迁移文件顶部并逐项填写:
```sql
-- =============================================================
-- 迁移 V{N+1}__<短横线描述>
-- 模板:docs/flyway-migration-template.md(task-192)
--
-- 1. 变更目的:<一句话说明要解决什么问题 / 为何变更>
-- 2. 影响表与数据量:<表名:预计行数 / 全表或增量;例如 biz_file_result ~50w 全表>
-- 3. 锁表风险:<是否 ONLINE / 是否加锁 / 大表索引类需 ALGORITHM=INPLACE 评估;风险高则拆批或窗口执行>
-- 4. 验证 SQL:<迁移后用于核对的行数 / 抽样语句,见下方示例>
-- 5. 回滚步骤:<V{N}__<desc>.sql 或补丁脚本路径;无回滚写明原因>
-- 6. 上线窗口:<建议窗口,例如 业务低峰 02:00-06:00;双节点滚动>
-- =============================================================
-- 迁移语句(DDL/DML)…
-- 可选验证(与头注释第 4 项对应)
-- SELECT COUNT(*) FROM <table>;
```
## 六项必填说明
| # | 字段 | 要求 | 反例 |
|---|------|------|------|
| 1 | 变更目的 | 一句话,写清"为什么" | 留空 / 只写表名 |
| 2 | 影响表与数据量 | 每张被改表名 + 预计行数量级 | "涉及多表" 不含表名 |
| 3 | 锁表风险 | 指出 DDL 是否 INPLACE/排他、大表评估 | "无风险" 不说明依据 |
| 4 | 验证 SQL | 迁移后可跑的核对语句 | 缺失 |
| 5 | 回滚步骤 | 回滚脚本路径或明确不可回滚原因 | 缺失 |
| 6 | 上线窗口 | 建议时段 + 是否滚动 | 缺失 |
## 示例验证 SQL(供第 4 项复制)
```sql
-- 迁移后行数与迁移前基线对比
SELECT COUNT(*) FROM biz_file_result;
-- 新索引是否生效(用于索引类迁移)
SHOW INDEX FROM biz_file_result WHERE Key_name = 'idx_task_module';
-- 抽样数据
SELECT id, task_id, status, updated_at FROM biz_file_task ORDER BY id DESC LIMIT 5;
```
## 使用约束
- 版本号在 `src/main/resources/db/` 最大现有版本上加 1(当前 ≥ V109),不抢号、不重复。
- 不修改、不删除任何已执行过的历史迁移文件。
- 上线走双节点滚动 + 生产库先 `flyway validate`,失败即停。
-62
View File
@@ -1,62 +0,0 @@
# Flyway 迁移盘点(task-193)
> 生成方式:`src/test/java/com/nanri/aiimage/config/MigrationInventoryTest.java`(只读审计,可重复)。
> 快照日期:2026-10-01;2026-10-03 随 V142 追加时同步过概览数字与取号起点;2026-10-04 随 V143 同步;2026-10-04 随 V144 同步;2026-10-04 15:1x 随 V145 同步;2026-10-05 随 V146 同步;2026-10-05 23:0x 随 V147 同步;2026-10-06 随 V148 同步(并把 V145/V146/V147 从"待发版"挪进"已应用");2026-10-06 随 V149 同步(菜单树按公司一套;V148 仍未上线,故 V149 与它同批);2026-10-06 随 V150/V151 同步,并删掉未上线的 V148(该号就此退役,见下);2026-10-07 随 V152 同步(并把 V149/V150/V151 从"待发版"挪进"已应用"——10-06 17:32 只读实查,success 全 1);2026-10-08 随 V153 同步(分组名收窄到同公司唯一;表侧只 13 行,写侧代码与本版必须同批)。
## 概览
- 版本化迁移文件数:**154**(`src/main/resources/db/V*.sql`,其中整数版本 153 个 + 小版本 V25_1)
- 整数版本范围:**V1..V156**,其中 V132/V133/V148 为已退役空号(见下),其余连续
- 历史遗留小版本:**V25_1__shop_manage_group_bind_user.sql**(Flyway 语义 25.1,紧跟在 V25 之后、V26 之前执行,属历史命名,保留)
- 最新版本:**V156__dedupe_total_data_pioneer_backfill.sql**(上一版 **V155__users_disabled_at.sql**,再上一版 **V154__biz_dedupe_total_data_company_id_drop_default.sql**,其前 **V153__shop_manage_group_company_id.sql**,再往前 **V152__columns_shop_key_company_id_drop_default.sql**——概览往下推时旧文件名一个不许挤掉,`CompanyDefaultDropV152Test.inventoryDocTracksV152` 就是钉这件事的)
- 待下一次 jar 发版执行:**V154、V155**(V152、V153 已于 10-09 09:50 随 jar `69d2ebb0` 双台同版应用——启动日志实查 "Current version of schema `aiimage`: 153 / Schema `aiimage` is up to date. No migration necessary.";V149/V150/V151 已于 10-06 17:32 应用。V153 给分组表加 `company_id` 并把分组名从"全平台唯一"收窄成"同公司唯一",**写侧代码必须同批**,两个方向单独发都不行——见 V153 头注释第 6 段;V154 只摘一列的默认值,前提逐条取证见下面的 V154 条目;V155 只给 `users` 加一列可空 `disabled_at`,140 行全取 NULL、对旧 jar 零行为差异,但它必须与读这列的代码同版——只发迁移则停用无人执行,只发 jar 则启动期读列即 1054)
- 已应用:V142(10-03 18:23)、V143(10-04 10:48)、**V144(10-04 13:22)**、`V145__brand_dedupe_company_scope.sql`(10-05 13:01)、`V146__users_expires_at_admin_expiry.sql`(10-05 13:01)、**`V147__product_category_company_scope.sql`(10-06 11:03)**、`V149__permission_menu_company_tree.sql` / `V150__shop_key_company_scope.sql` / `V151__rule_tables_shared_across_companies.sql`(三条均为 10-06 17:32)
- 末段 `flyway_schema_history` 为 2026-10-07 主机A 只读实查(`success` 全 1,最大整数版本 151),不是从 jar 版本推的
- 重复版本:无
- 迁移命名:全部符合 `V<整数>(_<子版本>)?__<描述>.sql`,无空格
## 生产已执行核对
生产 `flyway_schema_history` 末段:V125..V131 之后直接是 **V134__publish_item_free_text_columns**、**V135__dedupe_total_data_wide_columns**(两条 `installed_on` 均为 2026-09-25 20:46:16),库内没有 132/133 记录。
## 空号的来历(V132/V133/V148)
本地曾存在 `V132__web_config_add_is_latest.sql`、`V133__hide_redundant_indexes_invisible.sql`,与另一分支已在生产落库的 V134/V135 冲突。因 Flyway 未开启 `out-of-order`,把任何迁移编到 132/133 会在启动期报 "resolved migration not applied";因此这两条改为 **V136/V137**,132/133 永久退役,不可回填。
`V148__product_category_builtin_owned_by_company.sql`(把 18 行内置类目的归属从共享哨兵 0 改成厦门米椿花 1)从未上线,2026-10-06 控制方点名「商品类目做成共享的,不区分」⇒ 它的口径被 V151 整体推翻,文件连同 `ProductCategoryMigrationV148Test`、`docs/rollback-V148-product-category-builtin-shared.sql` 一起删除。它与 132/133 的区别要写清:**把新迁移编号写回 148 在 Flyway 语义上是可行的**(生产最大值仍是 147,不存在 out-of-order),这里禁它是共树并发的护栏——148 与 149/150 是同一工作区里另一路会话此刻正在引用的号,被删的 `V148` 文件可能被再次写出,而同号两个文件会让 Flyway 启动期报 "Found more than one migration with version 148" ⇒ 两台 java 同时起不来。宁可让 `integerVersionsSequentialFromOne` 的红字出现在测试里,也不把撞号留到运行期发现。因此这三个号都在 `MigrationInventoryTest.RETIRED_HOLES` 里登记。
后续新增迁移从 **V157** 起取号(V156 已被 `dedupe_total_data_pioneer_backfill` 占用:把组 33/uid=1188「先锋」名下账号已删的 1452 行 `company_id` 从兜底 1 回填到 3,配套读侧按行 company_id 收窄的 JAR 同批上线,回滚见 `docs/rollback-V156-dedupe-pioneer-backfill.sql`;V155 已被 `users_disabled_at` 占用:给 users 加一列可空停用时刻,回滚见 `docs/rollback-V155-users-disabled-at.sql`;V154 已被 `biz_dedupe_total_data_company_id_drop_default` 占用:只摘一列的默认值,回滚见 `docs/rollback-V154-dedupe-company-id-drop-default.sql`。只认"当前最大值 + 1",不要为还没写出来的迁移预留号段——预留会在 1..max 里留洞,`integerVersionsSequentialFromOne` 会红;也不要回填上面那三个洞)。原先挂在 V149 名下的"摘 DEFAULT"待办,`columns` 那条已与 `biz_shop_key` 合并成 **V152** 发出(V150 头注释第 6 段要求"合并成一版发出";发布前的只读取证:`columns` 154 行按公司 52/51/51、`biz_shop_key` 16 行全 company_id=1 且无 NULL,两列 COLUMN_DEFAULT 都是 1)。摘 DEFAULT 这一族到此摘完,最后一条是 **V154**:
- `ALTER TABLE biz_dedupe_total_data ALTER COLUMN company_id DROP DEFAULT;` —— 已作为 **V154** 发出。V152 当年把它留在门外的前提是"先修写侧、上线并验证真实导入之后才谈摘",2026-10-09 只读探针(运维仓 `scripts/_probe_dedupe_default.py`,主机A,零写入)逐条对上:哨兵四张表里只剩这张仍带 DEFAULT 1(users / biz_shop_key / columns 的 COLUMN_DEFAULT 均为空);归属分布 company_id=1 共 546,344 行、=3 共 8,125 行,**没有 0 也没有 NULL**;孤儿归属 0 行;写侧显式落值那版上线后真实导入 29,555 行(2026-10-07 09:48:38 → 2026-10-08 23:57:51)。⚠ 本表批量导入走 `INSERT IGNORE`:在生产 sql_mode(实查含 STRICT_TRANS_TABLES)下省略该列不会撞 1364,而是被降级成 warning 并落成隐式默认 **0**——0 不属于任何公司,行插得进去但对所有公司隐形,比"静默归第 1 家"更难发现。⇒ **顺序必须是先上带 Java 闸门的 jar,再让本迁移随同一版生效**;闸门=`DedupeTotalDataService.requireCompanyAttribution`(接在 create 与 insertImportBatch 两条写通道上),用例 `DedupeTotalDataWriteAttributionTest` 4 例,其中接线钉按行首语句数调用点==2(避开 javadoc 同名提及那个坑)。
**`biz_product_category.company_id` 的 DEFAULT 由"待摘"改成"必须保留"**(这一条与 V151 同批生效):V151 之后新 jar 的 INSERT 列清单不含 `company_id`,而该列是 `NOT NULL`,全靠 `DEFAULT 1` 满足——此时执行 `DROP DEFAULT` 会让每一次新建类目报 1364。`biz_invalid_asin_data.company_id` 同理(品牌库那条写入失败还会被 `CollectDataInvalidAsinBatchWriter` 吞成 `log.warn` ⇒ 接口返回成功而黑名单静默少一批)。所以这两张表已从 `CompanyDefaultGuard.WATCHED_TABLES` 与探针 SQL 的 IN 列表里同时摘掉(清单与 SQL 由 `CompanyDefaultGuardTest` 双向钉同源),否则哨兵会在每次启动时对着一列"没人读、摘了会炸"的默认值喊 `COMPANY_DEFAULT_STILL_PRESENT`,而巡检把那条签名计进 ALERTS。
它们真正消失的时点是下一版(两台同版之后):
- `ALTER TABLE biz_invalid_asin_data DROP COLUMN company_id;`
- `ALTER TABLE biz_product_category DROP COLUMN company_id;`
摘除 DEFAULT 的动作在这两条里"顺带完成"(列没了,默认值随之消失),**仍然禁写成 `MODIFY COLUMN ... NOT NULL`**(重建表会按当时的列默认值物化历史行)。`biz_shop_key` 已在 **V152** 摘掉 DEFAULT,`biz_dedupe_total_data` 已在 **V154** 摘掉——两张的哨兵清单都原样保留:哪天默认值被 dump 重建或手滑装回,启动期还能再喊出来。
原先挂在待办里的"V137 冗余索引 DROP"迁移计划取 V139,该号已被 `V139__asin_result_cache.sql` 占用,顺延到 V140;V140 已被品牌补测队列表 `V140__collectdata_brand_recheck.sql` 落用。
## 已应用迁移的存量校验和(2026-10-04 与 2026-10-07 从生产 `flyway_schema_history` 只读实查)
| 版本 | 文件 | 校验和 | installed_on |
|---|---|---|---|
| 142 | `V142__web_config_sha256.sql` | `1152261840` | 2026-10-03 18:23:22 |
| 143 | `V143__company_and_users_company_id.sql` | `1539570901` | 2026-10-04 10:48:54 |
| 144 | `V144__users_company_id_drop_default.sql` | `1833593804` | 2026-10-04 13:22:00 |
| 149 | `V149__permission_menu_company_tree.sql` | `593432281` | 2026-10-06 17:32:29 |
| 150 | `V150__shop_key_company_scope.sql` | `2113095084` | 2026-10-06 17:32:29 |
| 151 | `V151__rule_tables_shared_across_companies.sql` | `613473408` | 2026-10-06 17:32:30 |
上表各行的字节就此封死。校验和算法是 Flyway 的 CRC32 逐 `BufferedReader.readLine()` 的 UTF-8 字节累加(**行尾不入 CRC**,所以 CRLF 工作树与 LF 工作树算出同一个值);142/143/144 三个值被 `CompanyMigrationV144Test#appliedMigrationBytesAreFrozenAgainstProdChecksum` 用工作树字节复算比对,149/150/151 被 `CompanyDefaultDropV152Test#appliedV149V150V151BytesAreFrozenAgainstProdChecksum` 复算比对(10-07 本机复算三值全中)。
真事:10-04 上午有人(我)把"摘掉 `users.company_id` 的 DEFAULT"直接改成原地编辑 V143,取证才发现 V143 已在 10:48 落库——那样发出去的 jar 会让下次启动 Flyway 校验失败、**两台 java 都起不来**。口径变更因此写成 V144 前向修复,并把"已应用不许原地改"从注释升级成上面那条用例。
## 约束
- 审计测试断言:整数版本从 1 到当前最大值连续(`RETIRED_HOLES = {132, 133}` 内的号段除外)、无重复文件名、命名正则合规、历史文件校验和可复算稳定。
- 修改任何已部署历史迁移会破坏 Flyway checksum,属违规;由本盘点测试 + code review 把关(git 层是否改动由 CI/review 校验)。
- **回滚不得写成版本化迁移。** 本目录是 Flyway 扫描路径,任何 `V*.sql` 都会在应用下次启动时自动执行;把回滚编成 `V{N+1}__rollback_*.sql` 等于让"决定回滚"这件事在没有人工执行的情况下自己发生。回滚一律是本目录之外的人工补丁脚本(首例:`docs/rollback-V143-company.sql`),并要按"停应用 → 跑脚本 → 删 `flyway_schema_history` 对应版本行 → 回滚 jar"的顺序做,漏掉删历史那步会让将来重装时 Flyway 判定"已应用"而跳过重建。
- **迁移必须可重跑。** MySQL 的 DDL 不进事务:迁移中途失败时前面的语句已经落库,而 `flyway repair` + 重启会让 Flyway 从第一条语句重跑整个文件。所以建表用 `IF NOT EXISTS`、插种子行用 `INSERT IGNORE` 或 `WHERE NOT EXISTS`、`ADD COLUMN/INDEX` 先查 `information_schema` 再 `PREPARE`(首例:V142 的条件 DDL、V143 全文件)。写成裸 `CREATE TABLE` / 裸 `INSERT ... VALUES` 的迁移,恢复路径本身会撞 1050/1060/1062,把"补数据后重启"变成"必须手工清库"。
-71
View File
@@ -1,71 +0,0 @@
# 公司 tab(批次 0-1)变异自证台账 — 2026-10-05
对应计划 `docs/plans/19-company-tab.md` Task 13 Step 1 / Step 1b。口径与一期、二期相同:**一条护栏只有在它的注入点真的变红时,才算钉住了**;没做过注入的"代码里写了 if"不构成证据。
## 执行环境与判据
| 项 | 值 |
|---|---|
| 后端 | `D:/tmp-wt-t13`(detached @ `99687f46`,`backend-java`)· Maven 3.9.16 + JDK 21 · 每轮先 `rmtree target/surefire-reports`,分母只取本轮 XML |
| 前端 | 主树 `admin-frontend-vue` · `node --test`(**不是 vitest**)· 5 支文件 33 例为分母:`company-tab-wiring` 8 / `align-operation-guide` 10 / `company-user-create` 7 / `company-user-list` 4 / `company-tab-model` 4 |
| 杀没杀的判据 | Java:本轮 XML `Tests run` 与 `Failures ≥ 1` **且** mvn rc=1;FE:`ℹ fail N`(U+2139 那三行)且 rc=1。摘要一律锚 `failed`/`fail` 这个词,不取"第一个数字" |
| 还原 | 每轮开跑前把被注入文件写回**注入前读进内存的字节**;**全程没有用 `git checkout` / `restore` / `stash` / `clean` 做还原**(这个仓库同时有另一路会话在提交)。FE 轮末 `FINAL-RESTORE OK all touched files byte-identical`,后端两轮末 `FINAL-RESTORE OK all 7 files byte-identical` |
| 锚点 | 每个注入锚串命中数必须恰好 1,否则本轮作废(`anchor hit exactly 1, injected` 逐轮打);CRLF 文件按 `\r\n` 对齐行尾 |
| 对照 | FE `FR0` + `FRZ`;Java `R0` / `R06` / `R0Z` —— 全部 `rc=0` 无红,且 `R0` 是**改完用例之后又重跑过一次**的 |
## 表 1 · 前端 11 支(全 KILLED)
| 轮次 | 注入 | 红在哪 |
|---|---|---|
| FG-1a | 从 `COMPANY_SCOPED_PAGES` 删一行(`admin_device_logs`) | 2 条红(正向那支 + 缺口清单分母那支) |
| FG-1b | 从 `src/api/user-secrets.ts` 删掉 `company_id = companyId` 那一行 | `company-tab-wiring` 正向 |
| FG-7-3 | 往 `CompanyTabs.vue` 加回 `<span class="company-tab-hint">当前公司:…</span>`(未批的界面暴露回流) | `align-operation-guide` 反向那半 |
| FG-7-4 | 从 8 支引导文案里删掉"超级管理员可用页面上方的公司 tab 切换公司"(`admin_user_secrets`) | `align-operation-guide` 分母那半 |
| F1b-4a / 4b | `fetchTaskCenterOverview` / `fetchTaskCenterShopOptions` 的 `http.get(url, { params: query })` 退回 `http.get(url)` | 本轮新写的守卫「发送口的第二实参」(逐 URL 报 `匹配到 0 处(要求恰好 1)`) |
| F1b-6a | 删掉 `DeviceLogsPage` 里 `watch(() => companyTab.activeId, …)` | `company-tab-wiring` 页面 reach 那半 |
| F1b-6b | `companyTab.requestCompanyId` 换成 `companyTab.activeId` | 同上 |
| F1b-6c | 直接删掉 getter 调用(`companyId: null`) | 同上 |
| FG-7-5 | 往 `UsersPage.vue` 加回「所属公司」列头(SUPPL 反向钉) | `company-user-list` |
| FG-7-6 | 建号的 `companyId` 闸门不再要求 `company_super_admin` 角色 | `company-user-create` |
## 表 2 · 后端 15 支(BG3-a 首轮 SURVIVED,修好后复跑 KILLED ⇒ 15/15)
| 轮次 | 注入 | 结果 · 红在哪 |
|---|---|---|
| BG2-1 | `AdminDeviceLogController.files` 整个不调 scope 出口(`memberUids = null`) | KILLED · `CompanyIdParamGoesThroughReadScopeTest` + `DeviceLogServiceTest` |
| BG2-2 | `ShopManageController.page` 的绑定改成驼峰 `@RequestParam Long companyId`(静默失效那一形) | KILLED · G2 + `ShopManageServiceTest` |
| B1b-1 | 绑定与 `readScope(` 都留着,**实参改成 `null`** | KILLED · G2 **断言 D**(这条正是断言 D 存在的理由) |
| BG3-a | 非超管"传别家 ⇒ 空集"那一支整个删掉(忽略参数、按本公司重算) | 首轮 **SURVIVED** → 见下节 → 复跑 **KILLED** · `DataReadScopeTest.adminPassingForeignCompanyGetsEmptyNot403` |
| BG3-b | 同一分支改成"不筛"(真正的越权逃逸读法) | KILLED · 同上那条用例 |
| BG4-1/2/3 | 三个出口里逐个注释掉 `SUPER_ADMIN_ONLY_KEYS` | KILLED ×3 · `PermissionCompanyMenuHiddenTest` |
| BG5 | `listVisible` 退回"非超管也可以" | KILLED · `CompanyReadPathMenuGateTest` |
| BG6 | `MEMBER_WARN_THRESHOLD` 改成 `Integer.MAX_VALUE` | KILLED · `CompanyScopeSupportTest` 哨兵用例(该轮 selector 只点这一支,`tests=1` 是设计,不是漏跑) |
| BG7-1 | 给写入口 `ShopManageController.create` 加一个 `company_id` 参数 | KILLED · G2 + `ShopManageServiceTest.writeEntryPointsCarryNoCompanyId` |
| BG7-2 | 给 `AdminDeviceLogController.content` 加 `dataReadScope`(钉"刻意不配写侧") | KILLED · `DeviceLogServiceTest.singleFileEndpointsStayUnscoped` |
| B1b-2a/2b | `ShopManageGroupService.list` 的 `and(w -> …or(x -> …))` 改成平铺 | KILLED ×2 · `ShopManageGroupServiceTest.groupListWrapsTheOrBeforeNarrowing` |
| B1b-3 | 删掉 `page` 签名里的 `@RequestParam(name = "company_id")`,**留着** `@Operation` 那句文案 | KILLED · G2 取样自检 + `ShopManageServiceTest` |
## 1b ⑤:`grep -c "@Test"` 与本轮 surefire `Tests run` 逐类对平
`R0` 那一轮(无注入)实测:`CompanyIdParamGoesThroughReadScopeTest 2/2`、`DataReadScopeTest 7/7`、`PermissionCompanyMenuHiddenTest 7/7`、`CompanyReadPathMenuGateTest 3/3`、`ShopManageServiceTest 9/9`、`ShopManageGroupServiceTest 3/3`、`TaskCenterScopeServiceTest 13/13`、`DeviceLogServiceTest 19/19` ⇒ 合计 **63 = 本轮分母**,逐类相等。`CompanyScopeSupportTest` 不在 `CLASSES` 里(BG6 单独按方法点跑,`tests=1`),它的 11 支全量由后端全量门禁覆盖。这一条之所以要单列:**删掉一支用例的 `@Test`、留着方法体和 `@DisplayName`,没有任何尺子会红**——"全绿"和"那支根本没跑"同形。
## 作废的一轮(照实留,不当证据)
`t13-back-all.txt`:**15 支全部 VOIDED**,每轮读数都是 `tests=None failures=None`=解析没抓到本轮 XML 的计数。那一轮的两处控制(`R0` / `R06` / `R0Z`)却是 `GREEN` 并打印 `SURVIVED rounds: none` —— 这正是 memory「字符串断言必须排他」里"解析断言抓不到就恒绿"的形状:读不到数不等于杀掉了,也不等于没杀掉。处理方式是**整轮判 VOIDED 并重跑**(`t13-back-run2.txt`),而不是报成"0 红"。重跑轮 `VOIDED rounds: none`。
## BG3-a 为什么活下来,以及怎么修的
不是"注入没被执行到"(锚点命中恰好 1,同分支的 BG3-b 会红),而是**用例自己给了错误理由**:`DataReadScopeTest.adminPassingForeignCompanyGetsEmptyNot403` 只桩了 `companyScope.requireCompanyId(any()) → 2L`,从没桩过 `memberUserIds(2L)`,而 Mockito 对返回 `List` 的未桩方法**默认交空表**。于是"删掉 foreign 分支、按本公司重算"这条注入交出的也是空集,`assertThat(scope.userIds()).isEmpty()` 照绿——它验的其实不是"别家被折成空集",而是"什么桩都没加"。
修法(一处,两个桩):本公司两列都桩成**非空**——`memberUserIds(2L) → [21, 22]`、`resolveVisibleUserIds(5L) → [21, 99]`(形状照同文件 `adminIsAlwaysPinnedToOwnCompany` 已有的桩)。这样"空集"只能由 foreign 分支产生。
复跑证据(`t13-back-run3-bg3a.txt`,只重跑 `R0` / `BG3-a` / `BG3-b` 三轮):`R0` 先绿(`tests=63 rc=0`,`DataReadScopeTest=7/0/0`,加桩没把别的用例带红)⇒ `BG3-a` **KILLED**(`rc=1`,红点逐字 `DataReadScopeTest.adminPassingForeignCompanyGetsEmptyNot403`)⇒ `BG3-b` 仍 **KILLED**(同一条用例)。该轮末 `SURVIVED rounds: none`、`VOIDED rounds: none`、`FINAL-RESTORE OK all 7 files byte-identical`。
## 这一份台账没证明的东西
- **另一路的第二道门不在此列**。批次 2/3 正在把 `DataReadScope.readCompanyId(operator, companyId)` 变成第二个被认可的正门,并给 G2 加了 276 行的扩展样本(去重库/品牌库/查询ASIN/最低价ASIN/商品类目)。那些改动此刻**未提交**,本台账的后端证据全部跑在 `99687f46` 的 G2 上——第二道门的变异由那一路自己做。
- 后端全量**在 BG3-a 用例修复之后重跑过**:`mvn -B test` @ `D:/tmp-wt-t13c`(detached `09aab729` + 本支修复后的 `DataReadScopeTest`)⇒ **3760 例 / 0 失败 / 0 错误 / 7 skipped / BUILD SUCCESS**(`rc=0`,9:16 min)。分母独立复算:本轮 `target/surefire-reports/TEST-*.xml` 共 **450** 个文件,逐个抓 `tests/failures/errors/skipped` 求和 = 3760/0/0/7,与 Maven 摘要逐数相符(两个读数来自两条通道,不是同一次解析)。修复前那版基线也是 3760/0(`gate_full_backend.log`)⇒ 加桩没改变例数(`DataReadScopeTest` 仍 7 支,本轮 XML 里就是 7)。**这一轮的第一次尝试是 BUILD FAILURE**,红的 20 条全是 `ExplainIndexAuditDocTest` / `ArchitecturePlanSection6DocTest` / `IndexMigrationV101Test` 的 `NoSuchFileException`——那三支读的是 **gitignore 的** `backend-java/docs/explain-index-audit.md`、`java-architecture-optimization-plan.md`、`docs/specs/*`,新出包 worktree 里没有;补件后单跑那三支 27/27 绿,才跑的全量。⇒ **"worktree 全量红"要先问是不是缺件,别当成回归**(`git check-ignore -v` 一查就分明)。
- 前端已重跑:`admin-frontend-vue` **1739/1739/0**、`vue-tsc` rc=0;`frontend-vue` 710 例里唯一红是 `dead-code-cleanup.test.ts::test_bundle_build`,它断的是 `.gitignore` 的出包目录,worktree 里必红、主树 ✔。
- `admin-frontend-vue/tests/live/*` 是真 E2E,没有 `AIIMAGE_LLM_*` 凭据会整批 skip ⇒ **从没跑过**。
- 计划 Step 3 那八条人工实跑(非超管回归、越权实验、八页 tab 有效性、建号 vs 店铺归属口径、按 id 凭据闸门、麦象日志、保存权限、三眼看文案)**一条都没执行**——它们验的是生产长什么样,`mvn test` 与变异都盖不到。
- 界面逐页视觉验证欠着(真人浏览器回读)。
@@ -1,126 +0,0 @@
# 巡店删除 Python 提交接口
本文档给 Python 端同学说明 `patrol-delete` 的结果回传方式。前端不会再提供“手动归档”按钮,任务收尾、XLSX 组装、OSS 上传与历史清理均由服务端自动完成。
## 1. 提交入口
- 方法:`POST`
- 路径:`/api/patrol-delete/tasks/{taskId}/result`
- Content-Type:`application/json`
示例:
```http
POST /api/patrol-delete/tasks/123/result
Content-Type: application/json
```
```json
{
"shops": [
{
"shopName": "示例店铺",
"submissionId": "patrol-delete:123:示例店铺:1711111111111",
"chunkIndex": 1,
"chunkTotal": 3,
"shopDone": false,
"countrySections": [
{
"country": "德国",
"rows": [
{
"status": "正常",
"quantity": "12",
"deleteQuantity": "3",
"processStatus": "处理中"
}
]
}
],
"cartRatios": [
{
"country": "德国",
"ratio": "25%"
}
]
}
]
}
```
## 2. 字段说明
- `shops`: 本次提交的店铺结果分片列表,至少 1 条。
- `shopName`: 店铺名。服务端会按店铺名归并分片。
- `submissionId`: 建议每个店铺任务周期内保持同一个 submissionId,方便排查日志。
- `chunkIndex`: 当前分片序号,建议从 1 开始。
- `chunkTotal`: 当前店铺总分片数。
- `shopDone`: 当前店铺是否已全部提交完成。最后一片必须传 `true`。
- `error`: 当前店铺执行失败时传错误信息。传了 `error` 后该店铺会直接记为失败并结束。
- `countrySections`: 店铺各国家的状态数据。
- `cartRatios`: 店铺各国家的购物车比例数据。
## 3. 分片合并规则
- 服务端按 `taskId + shopName` 聚合缓存。
- 同一国家的 `countrySections[].rows` 会按提交顺序追加合并。
- `cartRatios` 按国家覆盖,后到数据覆盖先到数据。
- 当 `shopDone=true` 时,该店铺会被标记为完成。
- 如果中途提交了 `error`,该店铺会被标记为失败,不再等待后续分片。
## 4. Excel 组装规则
最终结果文件使用 `xlsx/日常删除格式.xlsx` 对应的数据结构:
- 第 1 列:`店铺名`
- 接着是 5 个国家块,每个国家 4 列:
- 国家状态
- 数量
- 删除数量
- 删除结果
- 最后是 5 组购物车比例列:
- 国家
- 购物车比例
每个店铺输出规则:
- 一个店铺占用的行数 = 5 个国家中数据行数的最大值
- 每个店铺处理完成后会额外空一行
- 然后再写下一个店铺
任务整体完成后:
1. 服务端汇总所有已完成店铺的数据
2. 组装成 XLSX
3. 上传 OSS
4. 前端历史任务中出现下载按钮,用户可直接下载
## 5. 自动收尾与超时补偿
前端不会手动触发归档,服务端自动处理:
- Python 正常把所有店铺都提交完成后,服务端立即尝试收尾。
- 如果最后一次提交后未来得及触发收尾,定时补偿任务会再次尝试 finalize。
- 如果某店铺已有部分有效数据,但 Python 异常退出,补偿任务会尽量把已有数据收尾成成功店铺。
- 如果某店铺完全没有完整结果且已超时,服务端会将该店铺标记为失败。
当前超时配置来自后端配置项:
- `aiimage.delete-brand-progress.patrol-delete-stale-timeout-minutes`
- Python should call `POST /api/tasks/{taskId}/heartbeat` every minute; timeout now uses only the normal stale-timeout setting.
## 6. 历史清理
服务端会定时清理历史数据,但会跳过仍在执行中的任务。
- `RUNNING` 任务不会被历史清理删除
- 只有已完成或已失败的历史记录会进入清理范围
- 临时目录缓存与结果目录也会定期清理
## 7. Python 端建议
- 一个店铺处理结束的最后一片一定要传 `shopDone=true`
- 如果店铺失败,请直接回传 `error`
- 大店铺建议按国家或按分页做分片,避免一次提交过大
- 如果同一店铺会多次回传,`shopName` 必须保持一致
- 如果最后一片提交成功,Python 端无需再调用额外“归档”接口
-233
View File
@@ -1,233 +0,0 @@
# 00-plan-overview.md — 全部任务总表
> 来源:`backend-java/docs/specs/00-overview.md` 与 01-13 号 spec(2026-08-31)
> 任务粒度:每个功能点 8-15 分钟(写测试 ≥8 用例 → RED → 实现 → GREEN)
> 执行纪律:单线程串行,禁止并行 agent 写代码;每任务独立 commit
## 任务总表
| N | 功能点 | 模块 | 依赖 |
|---|---|---|---|
| 1 | API_ENDPOINTS 路径常量表(17 页面模块路径分组) | 01 适配层 | 无 |
| 2 | buildJavaUrl() 统一 URL 构造(前缀+endpoint+query) | 01 适配层 | 1 |
| 3 | callJava() 统一响应解包(success/message/data + 非包装直通) | 01 适配层 | 2 |
| 4 | extractErrorMessage 导出并覆盖 error/message/msg 三字段 | 01 适配层 | 3 |
| 5 | normalizeStatus() 大小写归一(未知值透传) | 01 适配层 | 3 |
| 6 | isTerminalStatus() 终态判定(SUCCESS/FAILED/CANCELLED 可配置) | 01 适配层 | 5 |
| 7 | buildDownloadUrl() 统一下载 URL(user_id 附加规则) | 01 适配层 | 2 |
| 8 | callJava 透传 AbortController(signal 取消) | 01 适配层 | 3 |
| 9 | 进度类请求默认 10s 超时配置 | 01 适配层 | 3 |
| 10 | types/task.ts 共享类型(TaskStatus/FilePhase/PageResult) | 01 适配层 | 无 |
| 11 | 拆分 dedupe 模块 API(函数移动+行为不变测试) | 01 适配层 | 1,3 |
| 12 | 拆分 split 模块 API | 01 适配层 | 1,3 |
| 13 | 拆分 convert 模块 API | 01 适配层 | 1,3 |
| 14 | 拆分 publish 模块 API | 01 适配层 | 1,3 |
| 15 | 拆分 similar-asin 模块 API | 01 适配层 | 1,3 |
| 16 | 拆分 appearance-patent 模块 API | 01 适配层 | 1,3 |
| 17 | 拆分 delete-brand 模块 API | 01 适配层 | 1,3 |
| 18 | 拆分 price-track 模块 API | 01 适配层 | 1,3 |
| 19 | 拆分 shop-match/product-risk 模块 API | 01 适配层 | 1,3 |
| 20 | 拆分 shop-data-crawl/query-asin 模块 API | 01 适配层 | 1,3 |
| 21 | 拆分 withdraw/patrol-delete 模块 API | 01 适配层 | 1,3 |
| 22 | 拆分 collect-data 模块 API | 01 适配层 | 1,3 |
| 23 | 拆分 image-video/brand/permission/digital-human 模块 API | 01 适配层 | 1,3 |
| 24 | java-modules.ts 改 re-export 聚合(旧 import 零改动) | 01 适配层 | 11-23 |
| 25 | ResultFilePhase 新字段兼容默认值(可选字段兜底) | 01 适配层 | 10 |
| 26 | 模块 API 快照契约测试基建(mock adapter 断言 URL/method/query) | 01 适配层 | 3 |
| 27 | api-field-compat 注册高频响应 schema(task/result 核心字段) | 01 适配层 | 26 |
| 28 | 死代码清理(拆分后未引用导出,grep 确认后删) | 01 适配层 | 24 |
| 29 | 退避配置项(MaxMs/Factor 常量 + 默认值) | 02 轮询 | 无 |
| 30 | getTaskPollBackoffMs 递增序列(500→1000→…→10000) | 02 轮询 | 29 |
| 31 | 连续失败计数(成功/收到响应归零) | 02 轮询 | 30 |
| 32 | 退避封顶(maxMs 后不再增长) | 02 轮询 | 30,31 |
| 33 | 网络错误走退避且不触发终态 | 02 轮询 | 31 |
| 34 | HTTP 4xx/5xx 与网络错误分类(记 onError) | 02 轮询 | 31 |
| 35 | 未知状态不判终态测试固化(PENDING/SYNCING/空串) | 02 轮询 | 无 |
| 36 | 终态任务仅一次 onTerminal(coordinator 语义) | 02 轮询 | 无 |
| 37 | onTerminal 抛错后任务已移除语义测试(页面可重新 add) | 02 轮询 | 无 |
| 38 | 同一轮多任务终态分别回调测试 | 02 轮询 | 无 |
| 39 | in-flight 合并(timer 不叠加)测试补强 | 02 轮询 | 无 |
| 40 | 页面隐藏降频(30s)与可见恢复(立即刷新)测试 | 02 轮询 | 无 |
| 41 | storage 恢复(无效 id 过滤/空清理)测试 | 02 轮询 | 无 |
| 42 | 退避恢复测试(失败→退避→成功→正常间隔) | 02 轮询 | 31,32 |
| 43 | progressCache TTL 惰性清理边界测试 | 02 轮询 | 无 |
| 44 | fetchProgress 轻量端点切换能力(getModuleProgressLight 接入) | 02 轮询 | 26 |
| 45 | 轮询与历史刷新分离测试 | 02 轮询 | 无 |
| 46 | 双页面同 key 互踩行为记录测试(只读断言现状) | 02 轮询 | 无 |
| 47 | 轮询 baseline 统计(请求量/响应体大小)测试补强 | 02 轮询 | 无 |
| 48 | 轮询全量回归(20 个既有测试保持绿) | 02 轮询 | 29-47 |
| 49 | multipart 直通断言补测(content-type 大小写变体) | 03 过滤器 | 无 |
| 50 | JSON/PUT/DELETE 包装与阈值钳制补测 | 03 过滤器 | 无 |
| 51 | 日志不读 body 行为测试(过滤器通过后 body 仍可读) | 03 过滤器 | 无 |
| 52 | 阈值生效集成测试(>1MB 请求不整包缓存) | 03 过滤器 | 无 |
| 53 | yml 默认值 1MB 与 env 覆盖测试 | 03 过滤器 | 无 |
| 54 | TaskOwnerForwardService 转发 multipart 安全测试(inputStream 路径) | 03 过滤器 | 无 |
| 55 | 转发后 body 完整性测试(转发请求体与原请求一致) | 03 过滤器 | 54 |
| 56 | plan §6 文档现状修正核对 | 03 过滤器 | 无 |
| 57 | ResultFileJobHandler 接口定义(moduleType/process/cleanup/onFailure/offload/ownerScoped) | 04 注册表 | 无 |
| 58 | 注册表容器(List 收集 + moduleType 唯一性校验) | 04 注册表 | 57 |
| 59 | 启动校验(缺注册/双注册 fail-fast) | 04 注册表 | 58 |
| 60 | SHOP_MATCH Handler(委托+payload.deleteLatest) | 04 注册表 | 57-59 |
| 61 | PRICE_TRACK Handler | 04 注册表 | 57-59 |
| 62 | PRODUCT_RISK_RESOLVE Handler | 04 注册表 | 57-59 |
| 63 | PUBLISH Handler(ownerScoped) | 04 注册表 | 57-59 |
| 64 | QUERY_ASIN Handler | 04 注册表 | 57-59 |
| 65 | SHOP_DATA_CRAWL Handler(cleanup+onFailure) | 04 注册表 | 57-59 |
| 66 | WITHDRAW Handler(tryFinalizeTask 时机保持) | 04 注册表 | 57-59 |
| 67 | PATROL_DELETE Handler | 04 注册表 | 57-59 |
| 68 | APPEARANCE_PATENT Handler(异步返回+offload+ownerScoped) | 04 注册表 | 57-59 |
| 69 | SIMILAR_ASIN Handler(异步+offload+ownerScoped+onFailure) | 04 注册表 | 57-59 |
| 70 | DELETE_BRAND Handler | 04 注册表 | 57-59 |
| 71 | BRAND Handler(resolveResultObjectKey 特例) | 04 注册表 | 57-59 |
| 72 | COLLECT_DATA Handler | 04 注册表 | 57-59 |
| 73 | Worker dispatch() 改注册表查找 | 04 注册表 | 60-72 |
| 74 | cleanupAfterSuccess 改 handler.cleanup + 公共 payload 清理 | 04 注册表 | 60-72 |
| 75 | notifyRetryExhausted 改 handler.onFailure | 04 注册表 | 60-72 |
| 76 | coze offload 判定改 handler.supportsAsyncOffload | 04 注册表 | 60-72 |
| 77 | owner-scoped 判定改 handler.isOwnerScoped | 04 注册表 | 60-72 |
| 78 | 模块映射快照测试(13 moduleType → Handler → 原方法) | 04 注册表 | 73 |
| 79 | 行为等价对比测试(Job 状态迁移序列一致) | 04 注册表 | 73-77 |
| 80 | 孤儿失败路径不回归(markFailedPermanent) | 04 注册表 | 73 |
| 81 | 卡死扫描/重试耗尽路径测试 | 04 注册表 | 73 |
| 82 | 特殊规则回归(WITHDRAW finalize、coze 等待 defer) | 04 注册表 | 78-81 |
| 83 | SimilarAsinExcelParser 行解析器(POI 读行→中间行对象) | 05 拆分 | 无 |
| 84 | 行解析边界(空行/超长/畸形 ASIN/BOM/混合编码) | 05 拆分 | 83 |
| 85 | 字段归一化器(trim/大小写/ASIN 格式统一) | 05 拆分 | 无 |
| 86 | 分组转换器(中间对象→TaskItem/FileItem) | 05 拆分 | 83,85 |
| 87 | 纯校验器(必填/格式/去重) | 05 拆分 | 85 |
| 88 | Sheet 构造器(workbook 构建辅助) | 05 拆分 | 无 |
| 89 | SimilarAsinService.parse 门面改委托(签名不变) | 05 拆分 | 83-88 |
| 90 | 抽取前后快照对比测试(夹具 Excel 同断言) | 05 拆分 | 89 |
| 91 | SimilarAsin 历史查询组装抽取(VO 拼装) | 05 拆分 | 无 |
| 92 | SimilarAsin 全量回归(mvn test 相关类) | 05 拆分 | 89-91 |
| 93 | AppearancePatent 行解析/归一化抽取 | 05 拆分 | 83,85 |
| 94 | AppearancePatent Sheet 构造抽取 | 05 拆分 | 88 |
| 95 | AppearancePatent 门面改委托(签名不变) | 05 拆分 | 93,94 |
| 96 | AppearancePatent 快照对比测试 | 05 拆分 | 95 |
| 97 | AppearancePatent 历史查询组装抽取 | 05 拆分 | 无 |
| 98 | AppearancePatent 全量回归 | 05 拆分 | 95-97 |
| 99 | ShopDataCrawl 行解析抽取 | 05 拆分 | 83,85 |
| 100 | ShopDataCrawl Sheet 构造抽取 | 05 拆分 | 88 |
| 101 | ShopDataCrawl 门面改委托(签名不变) | 05 拆分 | 99,100 |
| 102 | ShopDataCrawl 快照对比测试 | 05 拆分 | 101 |
| 103 | ShopDataCrawl 历史查询组装抽取 | 05 拆分 | 无 |
| 104 | ShopDataCrawl 全量回归 | 05 拆分 | 101-103 |
| 105 | similarasin 历史列表 IN 查询批量加载 | 06 批量加载 | 无 |
| 106 | appearancepatent 历史列表批量加载 | 06 批量加载 | 105 |
| 107 | 结果列表关联 Job 批量加载(findAssembleJobs 覆盖审计) | 06 批量加载 | 无 |
| 108 | dashboard 聚合查询(COUNT/GROUP BY 一次出) | 06 批量加载 | 无 |
| 109 | progress/light 轻量接口(similarasin 首个) | 06 批量加载 | 无 |
| 110 | progress/light 字段白名单(不含明细) | 06 批量加载 | 109 |
| 111 | progress/light 空/超长 taskIds 行为 | 06 批量加载 | 109 |
| 112 | progress/light 终态任务返回终态状态 | 06 批量加载 | 109 |
| 113 | 其余模块 progress/light 接入(批量) | 06 批量加载 | 109-112 |
| 114 | 批量加载等价快照测试(改造前后字段一致) | 06 批量加载 | 105-108 |
| 115 | 高频查询 EXPLAIN 索引审计(产出迁移清单) | 06 批量加载 | 无 |
| 116 | 索引迁移 V{N+1}(EXPLAIN 验证后追加) | 06 批量加载 | 115 |
| 117 | progress/light user_id 权限过滤 | 06 批量加载 | 109 |
| 118 | 前端 getModuleProgressLight 适配(调用轻量端点) | 06 批量加载 | 109,44 |
| 119 | dashboard/history/progress 前端分离调用测试 | 06 批量加载 | 无 |
| 120 | 大页数据(500 任务)性能回归 | 06 批量加载 | 105-108 |
| 121 | N+1 扫描(逐条 selectById 循环审计) | 06 批量加载 | 无 |
| 122 | 扫描确认的 N+1 批量化修复 | 06 批量加载 | 121 |
| 123 | 06 全量回归 | 06 批量加载 | 105-122 |
| 124 | @Transactional 方法审计清单(每模块) | 07 事务 | 无 |
| 125 | similarasin 纯计算移出事务 | 07 事务 | 124 |
| 126 | similarasin DTO 组装移出写事务 | 07 事务 | 124 |
| 127 | similarasin 临时文件清理挂 afterCommit | 07 事务 | 124 |
| 128 | appearancepatent 事务收缩 | 07 事务 | 124 |
| 129 | shopdatacrawl 事务收缩 | 07 事务 | 124 |
| 130 | publish 事务收缩 | 07 事务 | 124 |
| 131 | collectdata 事务收缩 | 07 事务 | 124 |
| 132 | /result 成功确认时机不变测试(200+success 在落库后) | 07 事务 | 125-131 |
| 133 | 回滚语义不变测试(落库失败回滚) | 07 事务 | 125-131 |
| 134 | done=true 封口时机不变测试 | 07 事务 | 125-131 |
| 135 | 任务状态成功时机不变测试 | 07 事务 | 125-131 |
| 136 | 事务外清理异常不阻断(日志+指标) | 07 事务 | 127 |
| 137 | 重复提交幂等测试(同 submissionId) | 07 事务 | 132-135 |
| 138 | 事务时长性能对比基准 | 07 事务 | 125-131 |
| 139 | 07 全量回归 | 07 事务 | 132-138 |
| 140 | 13 模块 file 字段契约快照测试(齐全+旧字段仍在) | 08 结果阶段 | 无 |
| 141 | similarasin file 进度合成逻辑单测(Coze/Python/snapshot 三路径) | 08 结果阶段 | 无 |
| 142 | fileReady/fileStatus 语义测试(无 job 时 SUCCESS 兜底) | 08 结果阶段 | 140 |
| 143 | publish 文件级 file 状态测试 | 08 结果阶段 | 140 |
| 144 | 前端 live progress 合并测试补强(history 缺失保留) | 08 结果阶段 | 无 |
| 145 | 前端可下载判定测试(fileReady/fileStatus 终态) | 08 结果阶段 | 无 |
| 146 | collectdata 自洽行为测试(success+downloadUrl 判定) | 08 结果阶段 | 140 |
| 147 | downloadUrl 永不过期验证(generateFreshDownloadUrl 公开直链) | 08 结果阶段 | 无 |
| 148 | 临时目录配置盘点(Transient/Storage Properties 现状) | 09 临时文件 | 无 |
| 149 | 创建/访问时间记录审计与补缺 | 09 临时文件 | 148 |
| 150 | 引用检查(清理前查 task_file_job/file_result) | 09 临时文件 | 148 |
| 151 | 路径安全校验(规范化 + startsWith 根目录) | 09 临时文件 | 148 |
| 152 | 清理失败吞异常记指标(不阻断主流程) | 09 临时文件 | 150,151 |
| 153 | fileKey 兜底查找(进程重启后) | 09 临时文件 | 148 |
| 154 | 磁盘容量告警(仅日志/指标输出) | 09 临时文件 | 152 |
| 155 | 孤立文件巡检报表(只读) | 09 临时文件 | 150 |
| 156 | 孤立 Job 巡检报表(只读) | 09 临时文件 | 无 |
| 157 | 任务存在结果缺失巡检 | 09 临时文件 | 无 |
| 158 | 结果存在文件缺失巡检 | 09 临时文件 | 无 |
| 159 | 已完成任务活跃 Job 巡检 | 09 临时文件 | 无 |
| 160 | 超保留期仍被引用巡检 | 09 临时文件 | 150 |
| 161 | 巡检任务开关(默认 disabled) | 09 临时文件 | 155-160 |
| 162 | 路径穿越测试(../ 输入被拒) | 09 临时文件 | 151 |
| 163 | 引用中文件不清测试 | 09 临时文件 | 150 |
| 164 | 清理失败不阻断测试 | 09 临时文件 | 152 |
| 165 | 巡检只读测试(运行零删除) | 09 临时文件 | 155-161 |
| 166 | 各客户端契约表盘点(超时/重试/幂等现状) | 10 HTTP 客户端 | 无 |
| 167 | aiimage.http-client.* 配置命名空间 | 10 HTTP 客户端 | 166 |
| 168 | Coze 客户端超时/重试配置接入 | 10 HTTP 客户端 | 167 |
| 169 | 品牌检查客户端配置接入 | 10 HTTP 客户端 | 167 |
| 170 | 紫鸟客户端配置接入 | 10 HTTP 客户端 | 167 |
| 171 | 图片下载客户端配置接入 | 10 HTTP 客户端 | 167 |
| 172 | 幂等重试守卫(非幂等不自动重试) | 10 HTTP 客户端 | 167 |
| 173 | 超时生效测试(mock 慢端点) | 10 HTTP 客户端 | 168-171 |
| 174 | 连接复用测试(连续请求复用底层连接) | 10 HTTP 客户端 | 168-171 |
| 175 | Python 回调超时不变确认(只读测试) | 10 HTTP 客户端 | 无 |
| 176 | 重试计数与日志字段 | 10 HTTP 客户端 | 172 |
| 177 | 10 全量回归 | 10 HTTP 客户端 | 168-176 |
| 178 | 日志字段规范落地(taskId/moduleType/stage 统一) | 11 可观测性 | 无 |
| 179 | 禁止记录清单审计(Token/Cookie/body 不落日志) | 11 可观测性 | 178 |
| 180 | Worker 日志字段对齐(04 改造后) | 11 可观测性 | 73 |
| 181 | task.created/running 指标埋点 | 11 可观测性 | 无 |
| 182 | task.success/failed/cancelled 指标埋点 | 11 可观测性 | 181 |
| 183 | task.duration 指标埋点 | 11 可观测性 | 182 |
| 184 | task.heartbeat.age 指标埋点 | 11 可观测性 | 无 |
| 185 | file-job.* 指标埋点(pending/running/success/failed/duration/retry) | 11 可观测性 | 73 |
| 186 | 上传耗时/大小指标埋点 | 11 可观测性 | 无 |
| 187 | 临时磁盘指标埋点 | 11 可观测性 | 154 |
| 188 | 指标标签规范(moduleType/instanceId) | 11 可观测性 | 181-187 |
| 189 | 指标命名一致性测试(名称/标签断言) | 11 可观测性 | 188 |
| 190 | 日志脱敏测试(敏感字段不落日志) | 11 可观测性 | 179 |
| 191 | 双实例指标区分回归(instanceId 标签) | 11 可观测性 | 188-190 |
| 192 | 迁移规范模板(目的/影响/锁表/验证/回滚/窗口) | 12 Flyway | 无 |
| 193 | 历史迁移盘点(V87+ 现状核对,只追加不改) | 12 Flyway | 无 |
| 194 | orphan Job 巡检 SQL | 12 Flyway | 无 |
| 195 | orphan payload 巡检 SQL | 12 Flyway | 无 |
| 196 | 任务存在结果缺失巡检 SQL | 12 Flyway | 无 |
| 197 | 结果存在文件缺失巡检 SQL | 12 Flyway | 无 |
| 198 | 已完成任务活跃 Job 巡检 SQL | 12 Flyway | 无 |
| 199 | 超保留期引用巡检 SQL | 12 Flyway | 无 |
| 200 | 巡检报表任务落地(默认关闭) | 12 Flyway | 194-199 |
| 201 | 迁移演练(副本库 migrate + 验证 SQL) | 12 Flyway | 192 |
| 202 | Python-contract 夹具准备(录制真实请求脱敏) | 13 契约 | 无 |
| 203 | /result 幂等契约测试(同 submissionId 重复) | 13 契约 | 202 |
| 204 | /items 分页语义契约测试 | 13 契约 | 202 |
| 205 | parsed-payload 契约测试 | 13 契约 | 202 |
| 206 | heartbeat 旧字段契约测试 | 13 契约 | 202 |
| 207 | done=true 最后一批契约测试 | 13 契约 | 203 |
| 208 | JavaApiResponse 包装契约测试(前端) | 13 契约 | 无 |
| 209 | 字段兼容 schema 覆盖(user_id/task_ids/taskId/resultId/fileKey) | 13 契约 | 208 |
| 210 | ArchUnit 依赖方向规则(Controller→Service→Mapper) | 13 契约 | 无 |
| 211 | ArchUnit Controller 不访问 Mapper 规则 | 13 契约 | 210 |
| 212 | ArchUnit task 模块不依赖业务模块(SPI 检查) | 13 契约 | 210 |
| 213 | 前端共享层导出白名单(页面禁止直连 http) | 13 契约 | 无 |
| 214 | progress/batch 轻量响应契约 | 13 契约 | 109 |
| 215 | 下载 URL 格式契约(downloadUrl 公开直链) | 13 契约 | 147 |
| 216 | CI 接入测试阶段(.gitea workflow 追加) | 13 契约 | 210-215 |
| 217 | 快照对比工具(Service 拆分前后响应一致) | 13 契约 | 90 |
| 218 | 结果文件格式契约(文件名/Sheet/列/ZIP 结构) | 13 契约 | 无 |
| 219 | 13 全量契约回归 | 13 契约 | 202-218 |
**总任务数:219**
(原 222 规划在写入时合并了 3 个冗余项:40→41 合并降频测试、46→47 合并 baseline、112→113 合并终态返回,编号已重排为连续 1-219,与上表严格一致。)
@@ -1,429 +0,0 @@
# 01-plan — frontend-vue Java API 适配层
> 对应 `docs/specs/01-frontend-api-adapter.md`。技术栈:TypeScript + Vue3 + Vitest(`frontend-vue/`)。
> 测试命令:`cd crawler-plugin/frontend-vue && npx vitest run <file>`;类型检查:`npx vue-tsc --noEmit`。
## 任务 1:API_ENDPOINTS 路径常量表
**所属模块**:01 适配层 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
新建 `src/shared/api/endpoints.ts`,导出按模块分组的路径常量表 `API_ENDPOINTS`(17 个页面模块:split/dedupe/convert/publish/query-asin/similar-asin/appearance-patent/delete-brand/price-track/shop-match/product-risk/shop-data-crawl/withdraw/patrol-delete/collect-data/image-video/brand/permission/digital-human)。每个模块含 parse/activate/progress/history/result/download 等端点常量。路径值与现 java-modules.ts 内联 URL 完全一致(不含 /newApi/api 前缀,前缀由 buildJavaUrl 加)。
### 测试用例(≥8,先写 RED)
1. test_endpoints_all_modules_present — 17 模块键齐全
2. test_endpoint_path_format — 每个端点以 /api/ 开头
3. test_no_newapi_prefix_in_endpoint — 不含 /newApi/api 前缀
4. test_progress_batch_paths_match_controllers — progress 端点与 Java controller 路径一致(快照)
5. test_download_paths_match — download 端点模式
6. test_endpoints_frozen_snapshot — 常量表 JSON 快照(防漂移)
7. test_endpoint_values_no_trailing_slash — 无尾斜杠
8. test_endpoint_keys_convention — 键名 snake_case 或小驼峰一致性
### TDD 流程
1. 写上述全部测试 → `npx vitest run src/shared/api/__tests__/endpoints.test.ts` 确认 RED(文件不存在)
2. 实现 endpoints.ts → 确认 GREEN
3. `npx vue-tsc --noEmit` 通过
### 验证方法
`npx vitest run`(新建测试全绿)+ `npx vue-tsc --noEmit`。
## 任务 2:buildJavaUrl() 统一 URL 构造
**所属模块**:01 适配层 **依赖**:1 **预估**:8-15 分钟
### 功能点要求
`buildJavaUrl(module, endpoint, query?)`:`/newApi` + `/api` 前缀 + endpoint + 可选 query 序列化;对空 query 不追加 `?`。与现有 `JAVA_API_PREFIX` 常量保持一致。
### 测试用例(≥8)
1. test_build_url_prefixed — 输出以 /newApi/api 开头
2. test_build_url_with_query — query 参数正确编码
3. test_build_url_no_query — 无 query 不加 ?
4. test_build_url_query_encoding — 特殊字符编码(空格/中文/&)
5. test_build_url_empty_query_object — 空对象不加 query
6. test_build_url_trailing_slash_endpoint — endpoint 尾斜杠规范化
7. test_build_url_undefined_query — undefined 安全
8. test_build_url_join_no_duplicate_slash — 前缀与端点之间无重复斜杠
### TDD 流程 / 验证方法
同上:先 RED,实现 GREEN,`vue-tsc` 通过。
## 任务 3:callJava() 统一响应解包
**所属模块**:01 适配层 **依赖**:2 **预估**:8-15 分钟
### 功能点要求
`callJava<T>(config): Promise<T>`:发起请求;响应 data 为 `JavaApiResponse<T>`(success/message/data)时解包返回 data;为 `LegacyApiSuccess`(success/msg/data)时兼容解包;非包装结构直通;success=false 抛错(message 优先);不改变 http.ts 现有导出。
### 测试用例(≥8)
1. test_call_java_success_unwraps — JavaApiResponse 解包出 data
2. test_call_java_legacy_msg_unwraps — LegacyApiSuccess(msg)解包
3. test_call_java_success_false_throws — success=false 抛错
4. test_call_java_message_precedence — message 优先于 msg 于 error
5. test_call_java_non_wrapped_passthrough — 非包装对象直通
6. test_call_java_null_data — success 且 data=null 返回 null
7. test_call_java_network_error — 网络错误抛出 Error
8. test_call_java_http_error_status — HTTP 错误状态提取 message
### TDD 流程 / 验证方法
同上。
## 任务 4:extractErrorMessage 导出与三字段覆盖
**所属模块**:01 适配层 **依赖**:3 **预估**:8-15 分钟
### 功能点要求
http.ts 的 `extractErrorMessage` 提升为命名导出(保持内部逻辑);错误对象覆盖 `error`/`message`/`msg` 三字段;字符串响应体回退;无字段回退 axios message / 通用文案。
### 测试用例(≥8)
1. test_extract_error_field — error 字段优先
2. test_extract_message_field — message 字段
3. test_extract_msg_field — msg 字段
4. test_extract_error_precedence — error > message > msg
5. test_extract_string_body — 字符串响应体
6. test_extract_fallback_message — 无字段回退
7. test_extract_axios_non_error — 非 AxiosError
8. test_extract_blank_values_skipped — 空字符串跳过
### TDD 流程 / 验证方法
同上。
## 任务 5:normalizeStatus() 状态归一
**所属模块**:01 适配层 **依赖**:3 **预估**:8-15 分钟
### 功能点要求
`normalizeStatus(raw: string|null|undefined): string`:小写转大写(success→SUCCESS);带空格/连字符清理(in-progress→IN_PROGRESS);null/undefined/空串返回原样或 ''(不抛);未知值透传不改。
### 测试用例(≥8)
1. test_normalize_lower_to_upper — success→SUCCESS
2. test_normalize_mixed_case — rUnNiNg→RUNNING
3. test_normalize_with_hyphen — in-progress→IN_PROGRESS
4. test_normalize_null — null 安全
5. test_normalize_undefined — undefined 安全
6. test_normalize_empty_string — 空串返回空
7. test_normalize_unknown_passthrough — 未知值(SYNCING)原样
8. test_normalize_whitespace_padded — 首尾空白清理
### TDD 流程 / 验证方法
同上。
## 任务 6:isTerminalStatus() 终态判定
**所属模块**:01 适配层 **依赖**:5 **预估**:8-15 分钟
### 功能点要求
`isTerminalStatus(status, extras?)`:默认 SUCCESS/FAILED 为终态;可扩展(CANCELLED);先经 normalizeStatus;空值非终态。
### 测试用例(≥8)
1. test_terminal_success — SUCCESS true
2. test_terminal_failed — FAILED true
3. test_terminal_lowercase — success true(归一后)
4. test_terminal_pending_false — PENDING false
5. test_terminal_null_false — null false
6. test_terminal_cancelled_default_false — CANCELLED 默认 false
7. test_terminal_cancelled_extended_true — 传 extras 后 true
8. test_terminal_unknown_false — 未知状态 false
### TDD 流程 / 验证方法
同上。
## 任务 7:buildDownloadUrl() 统一下载 URL
**所属模块**:01 适配层 **依赖**:2 **预估**:8-15 分钟
### 功能点要求
`buildDownloadUrl(path, userId?)`:下载端点拼 user_id 附加规则(有 userId 时追加);已有 user_id 参数时不重复;无 userId 不追加;支持 freshDownloadUrl 优先的辅助 `resolveDownloadUrl(item)`(fresh 优先,缺失回退 downloadUrl)。
### 测试用例(≥8)
1. test_download_url_user_id — 追加 user_id
2. test_download_url_no_user_id — 无 userId 不追加
3. test_download_url_existing_user_id — 已含不重复
4. test_resolve_download_fresh_priority — freshDownloadUrl 优先
5. test_resolve_download_fallback — 缺失回退 downloadUrl
6. test_resolve_download_both_blank — 都空返回空
7. test_download_url_query_merge — 已有 query 合并
8. test_resolve_download_null_safe — null 安全
### TDD 流程 / 验证方法
同上。
## 任务 8:callJava 透传 AbortController
**所属模块**:01 适配层 **依赖**:3 **预估**:8-15 分钟
### 功能点要求
callJava 支持 `{ signal }`:axios 透传;signal 已中止时请求立即失败(AbortError);页面卸载可取消 in-flight。
### 测试用例(≥8)
1. test_signal_abort_before_send — 发送前中止立即拒绝
2. test_signal_abort_mid_request — 进行中中止拒绝
3. test_signal_passthrough — signal 传到 axios 配置
4. test_signal_abort_error_message — 错误消息含 AbortError 特征
5. test_signal_not_provided — 无 signal 正常
6. test_abort_after_resolve — 完成后 abort 无副作用
7. test_abort_rejects_promise — 中止拒绝 Promise
8. test_signal_multiple_calls_independent — 多次调用互不影响
### TDD 流程 / 验证方法
同上。
## 任务 9:进度类请求默认超时
**所属模块**:01 适配层 **依赖**:3 **预估**:8-15 分钟
### 功能点要求
进度类 API 函数(get*TaskProgressBatch)默认 10s 超时(现有 30s);可通过配置覆盖;非进度请求保持 30s。
### 测试用例(≥8)
1. test_progress_timeout_default — 进度请求 10s
2. test_progress_timeout_override — 显式覆盖生效
3. test_non_progress_timeout_30s — 非进度 30s
4. test_timeout_config_name — 配置键存在且为正数
5. test_progress_timeout_minimum — 非法配置钳制
6. test_override_via_options — 函数级 options 覆盖
7. test_timeout_zero — 0 钳制为正数
8. test_default_config_freeze — 默认值快照
### TDD 流程 / 验证方法
同上。
## 任务 10:types/task.ts 共享类型
**所属模块**:01 适配层 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
新建 `src/shared/api/types/task.ts`:`TaskStatus`(联合类型)、`ResultFilePhase`(fileReady/fileStatus/fileProgress*/freshDownloadUrl 可选)、`PageResult<T>`、`TaskProgressBatchVo`。纯类型,测试以类型断言为主(可降为 5 用例)。
### 测试用例(≥5)
1. test_type_task_status_assignable — SUCCESS 等可赋值
2. test_type_result_file_phase_all_optional — 字段全部可选
3. test_type_page_result_shape — 分页字段结构
4. test_type_progress_batch_shape — 批量进度结构
5. test_type_compat_compile — vue-tsc 全量通过
### TDD 流程 / 验证方法
先写类型 + 编译期断言(`@ts-expect-error` 负例),RED 后实现。
## 任务 11:拆分 dedupe 模块 API
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
### 功能点要求
将 java-modules.ts 中 dedupe 相关函数(runDedupe/getDedupeHistory/deleteDedupeHistory/getDedupeResultDownloadUrl)及类型移到 `types/modules/dedupe.ts`;内部改调 callJava+buildJavaUrl;函数签名、参数、返回语义一字不变。
### 测试用例(≥8)
1. test_dedupe_run_url — runDedupe 请求 URL 正确
2. test_dedupe_run_method_payload — POST + 请求体
3. test_dedupe_history_url — history URL/method
4. test_dedupe_delete_history — delete URL/method
5. test_dedupe_download_url — download URL + user_id
6. test_dedupe_signature_unchanged — 参数顺序与类型快照
7. test_dedupe_export_compat — 旧路径 import 可用
8. test_dedupe_unwrap — 返回解包后的 data
### TDD 流程 / 验证方法
同上(mock adapter 断言 URL)。
## 任务 12:拆分 split 模块 API
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
与 11 同构:runSplit/getSplitHistory/deleteSplitHistory/getSplitResultDownloadUrl + SplitRunRequest/SplitRunVo/SplitHistoryVo/SplitArchiveEntry。
### 测试用例(≥8)
split 对应 8 例:run URL/method/payload、history、delete、download+user_id、签名快照、旧 import 兼容、解包、异常回传。
## 任务 13:拆分 convert 模块 API
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
与 11 同构:getExcelInfo/runConvert/getConvertHistory/deleteConvertHistory/getConvertResultDownloadUrl/getConvertTemplates/importConvertTemplate/setDefaultConvertTemplate/deleteConvertTemplate + 模板相关类型。
### 测试用例(≥8)
convert 对应 8 例:getExcelInfo URL、runConvert 解析、history、download、模板列表/导入/默认/删除 URL、签名快照。
## 任务 14:拆分 publish 模块 API
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
publish:parsePublish/activatePublishTask/activatePublishFile/getPublishItemsPage/getPublishTaskProgressBatch/submitPublishTaskResult/getPublishDashboard/getPublishHistory/deletePublishTask。
### 测试用例(≥8)
publish 8 例:parse URL、activate、itemsPage 分页参数、progressBatch(含超时断言)、submitResult 请求体、dashboard、delete、签名快照。
## 任务 15:拆分 similar-asin 模块 API
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
similar-asin:parseSimilarAsin/getSimilarAsinDashboard/getSimilarAsinHistory/getSimilarAsinTaskProgressBatch/activateSimilarAsinTask/deleteSimilarAsinTask/deleteSimilarAsinHistory/getSimilarAsinResultDownloadUrl。
### 测试用例(≥8)
similar-asin 8 例:parse URL/payload、progressBatch 10s 超时、activate user_id、history、dashboard、delete task/history、download。
## 任务 16:拆分 appearance-patent 模块 API
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
appearance-patent:parseAppearancePatent/getAppearancePatentParsedPayload/getAppearancePatentQueuePayload/getAppearancePatentDashboard/getAppearancePatentHistory/getAppearancePatentTaskProgressBatch/activateAppearancePatentTask/deleteAppearancePatentTask/deleteAppearancePatentHistory/getAppearancePatentResultDownloadUrl。
### 测试用例(≥8)
8 例:parse、parsedPayload、queuePayload、progressBatch、activate、dashboard、history、delete/download。
## 任务 17:拆分 delete-brand 模块 API
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
delete-brand:runDeleteBrand/getDeleteBrandHistory/deleteDeleteBrandHistory/getDeleteBrandTaskDetail/getDeleteBrandTaskDetails/getDeleteBrandTaskDownloadUrl/getDeleteBrandResultDownloadUrl/submitDeleteBrandResult。
### 测试用例(≥8)
8 例:run URL、taskDetail/taskDetails、taskDownloadUrl、resultDownloadUrl、submitResult 请求体、delete、history、签名快照。
## 任务 18:拆分 price-track 模块 API
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
price-track:listPriceTrackCandidates/add/deleteCandidate/getCountryPreference/putPreference/matchPriceTrackShops/createPriceTrackTask/getPriceTrackTasksBatch/getPriceTrackTaskProgressBatch/deletePriceTrackTask/loopRun 系列/checkTaskSkipPriceAsin/markPriceTrackDispatchFailed。
### 测试用例(≥8)
8 例:create URL/payload、progressBatch、loopRun 创建/派发、skipAsin 检查、candidates、preference、download、签名快照。
## 任务 19:拆分 shop-match / product-risk 模块 API
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
shop-match + product-risk:matchProductRiskShops/listProductRiskCandidates/add/deleteCandidate/getCountryPreference/putPreference/getShopMatchTaskProgressBatch/getProductRiskTaskProgressBatch/getProductRiskDashboard/getProductRiskHistory。
### 测试用例(≥8)
8 例:matchShops URL、candidates CRUD、preference、两个 progressBatch、dashboard、history、签名快照。
## 任务 20:拆分 shop-data-crawl / query-asin 模块 API
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
shop-data-crawl + query-asin:listShopDataCrawlCandidates/matchShopDataCrawlShops/createShopDataCrawlTask/getShopDataCrawlDashboard/getShopDataCrawlHistory/getShopDataCrawlTaskProgressBatch/deleteShopDataCrawlTask/deleteShopDataCrawlHistory/getShopDataCrawlResultDownloadUrl + query-asin 对应函数。
### 测试用例(≥8)
8 例:create URL、progressBatch、candidates、dashboard/history、query-asin 组、download、签名快照、旧 import。
## 任务 21:拆分 withdraw / patrol-delete 模块 API
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
withdraw + patrol-delete:listWithdrawCandidates/matchWithdrawShops/createWithdrawTask/submitWithdrawTaskResult/getWithdrawTaskProgressBatch/getWithdrawResultDownloadUrl + patrol-delete 对应。
### 测试用例(≥8)
8 例:withdraw create、submitResult、progress、patrol-delete 组、download、签名快照、旧 import、异常回传。
## 任务 22:拆分 collect-data 模块 API
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
collect-data:parseCollectData/activateCollectDataTask/getCollectDataItemsPage/getCollectDataDashboard/getCollectDataHistory/getCollectDataTaskProgressBatch/deleteCollectDataTask/deleteCollectDataHistory/failCollectDataTask/getCollectDataCountryPreference/putCollectDataCountryPreference。
### 测试用例(≥8)
8 例:parse、itemsPage 分页参数、progressBatch、fail 请求体、preference、dashboard、delete、签名快照。
## 任务 23:拆分 image-video / brand / permission / digital-human 模块 API
**所属模块**:01 适配层 **依赖**:1,3 **预估**:8-15 分钟
image-video(secret/workflow/voice/asyncTask 系列)+ brand(BrandTaskListResponse 相关)+ permission + digital-human 独立文件已有,移动对齐。
### 测试用例(≥8)
8 例:image-video workflow 创建、result 查询、voice 列表/删除、brand 列表、permission、digital-human、签名快照、旧 import。
## 任务 24:java-modules.ts 改 re-export 聚合
**所属模块**:01 适配层 **依赖**:11-23 **预估**:8-15 分钟
java-modules.ts 只保留 re-export:`export * from './types/modules/dedupe'` 等;删光被移动的函数体;任何旧 import 路径继续可用(类型与运行时双兼容)。
### 测试用例(≥8)
1. test_reexport_all_symbols — 全部导出符号可从 java-modules 获取
2. test_reexport_type_compiles — 类型 import 可用
3. test_reexport_no_duplicate — 无重复导出
4. test_reexport_build_passes — vue-tsc 全量通过
5. test_reexport_import_compat — 各页面旧 import 快照编译
6. test_reexport_no_dead_body — 原函数体不存在(防残留)
7. test_reexport_runtime_symbols — 运行时函数可调用
8. test_reexport_vitest_full — 全量测试绿
### TDD 流程 / 验证方法
先写 re-export 后的测试断言(指向符号存在)→ 尚未 re-export 时 RED → 改文件 GREEN → `npm run build`(vue-tsc + vite build)通过。
## 任务 25:ResultFilePhase 新字段兼容默认值
**所属模块**:01 适配层 **依赖**:10 **预估**:8-15 分钟
`applyFilePhaseDefaults(item)`:fileReady/fileStatus/fileProgress* 缺省补默认(false/'PENDING'/0/0/0);旧 Java 版本响应(无新字段)时页面行为一致。
### 测试用例(≥8)
1. test_defaults_filled — 缺省字段补齐
2. test_existing_values_kept — 已有值不覆盖
3. test_file_ready_true_preserved — true 保留
4. test_partial_input — 部分字段缺失补齐
5. test_null_input_safe — null 安全
6. test_defaults_idempotent — 二次调用幂等
7. test_status_success_maps_ready — fileStatus=SUCCESS 且 fileReady 缺失 → ready true
8. test_unknown_status_untouched — 未知 status 不动
### TDD 流程 / 验证方法
同上。
## 任务 26:模块 API 快照契约测试基建
**所属模块**:01 适配层 **依赖**:3 **预估**:8-15 分钟
测试基建:vitest + axios mock adapter(或拦截 http.request),对每个模块 API 函数断言(url, method, params, data)快照;集中式 `assertApiCall()` helper。
### 测试用例(≥8)
1. test_snapshot_helper_url — helper 断言 URL
2. test_snapshot_helper_method — 断言 method
3. test_snapshot_helper_params — 断言 query
4. test_snapshot_helper_body — 断言请求体
5. test_snapshot_all_modules_covered — 全部已拆模块注册
6. test_snapshot_fail_message — 失败信息含 URL 上下文
7. test_snapshot_allowlist — 白名单外字段报错
8. test_snapshot_regression_guard — 快照变更即失败
### TDD 流程 / 验证方法
同上。
## 任务 27:api-field-compat 高频响应 schema
**所属模块**:01 适配层 **依赖**:26 **预估**:8-15 分钟
为 task/result 核心响应注册 schema(taskId/resultId/status/fileStatus/fileReady/downloadUrl 等),接入 createApiFieldCompatChecker 在契约测试与联调前跑检查。
### 测试用例(≥8)
1. test_schema_task_required_fields — 必填字段声明
2. test_schema_result_required_fields — 结果字段
3. test_checker_passes_valid — 合法对象通过
4. test_checker_missing_required — 缺必填报 missing
5. test_checker_wrong_type — 类型不符报 type
6. test_checker_batch — 批量检查
7. test_schema_registered_modules — 各模块 schema 注册齐全
8. test_schema_versioned — schema 版本标记
### TDD 流程 / 验证方法
同上。
## 任务 28:死代码清理
**所属模块**:01 适配层 **依赖**:24 **预估**:8-15 分钟
拆分后 grep 确认 java-modules.ts 无残留函数体、无未引用导出;删除确认死代码;`npm run build` + 全量测试验证。
### 测试用例(≥8,测试为验证型)
1. test_no_unexported_duplicates — 无重复导出
2. test_build_typecheck — vue-tsc 通过
3. test_full_vitest_green — 全量测试绿
4. test_no_console_debug_left — 无调试日志残留
5. test_no_unused_import — 无未用 import(lint)
6. test_entry_points_compile — 17 个入口编译
7. test_bundle_build — vite build 产出
8. test_git_diff_scope — 变更仅限 api 目录
### TDD 流程 / 验证方法
`npm run build` + `npx vitest run` 全绿。
@@ -1,399 +0,0 @@
# 02-plan — 任务轮询审计补强
> 对应 `docs/specs/02-task-polling-audit.md`。技术栈:TypeScript + Vitest(`frontend-vue/`)。
> 核心决策:不重写,只补强;`getTaskPollBackoffMs` 保持签名向后兼容。
## 任务 29:退避配置项(MaxMs/Factor)
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
task-progress-config.ts 新增 `getTaskPollBackoffMaxMs()`(默认 10000)与 `getTaskPollBackoffFactor()`(默认 2);默认值可通过 window 配置/测试注入覆盖。
### 测试用例(≥8)
1. test_backoff_max_default — 默认 10000
2. test_backoff_factor_default — 默认 2
3. test_backoff_max_override — 可覆盖
4. test_backoff_max_positive — 非正钳制
5. test_backoff_factor_min_one — factor <1 钳制为 1
6. test_backoff_config_isolated — 配置隔离(不串到其他用例)
7. test_backoff_max_freeze — 默认值快照
8. test_backoff_factor_freeze — factor 快照
### TDD 流程
1. 写测试 → `npx vitest run src/shared/__tests__/task-progress-config.test.ts` RED
2. 实现 → GREEN
3. `vue-tsc --noEmit` 通过
## 任务 30:getTaskPollBackoffMs 递增序列
**所属模块**:02 轮询 **依赖**:29 **预估**:8-15 分钟
### 功能点要求
`getTaskPollBackoffMs(attempt)`:500 * factor^attempt 递增;attempt=0 返回 500(与现状一致);上限 maxMs;现签名向后兼容(attempt 省略视为 0)。
### 测试用例(≥8)
1. test_backoff_attempt0_500 — attempt0=500
2. test_backoff_attempt1_1000 — attempt1=1000
3. test_backoff_attempt2_2000 — attempt2=2000
4. test_backoff_sequence_monotonic — 序列递增
5. test_backoff_capped_at_max — 封顶 10000
6. test_backoff_no_attempt_default — 省略参数=500
7. test_backoff_negative_attempt_zero — 负 attempt 当 0
8. test_backoff_custom_factor — 自定义 factor 生效
### TDD 流程 / 验证方法
同上。
## 任务 31:连续失败计数
**所属模块**:02 轮询 **依赖**:30 **预估**:8-15 分钟
### 功能点要求
轮询循环维护失败计数:refreshOnce 成功(收到响应)归零;连续失败递增;提供测试可观测出口(onError 带 attempt)。
### 测试用例(≥8)
1. test_failure_count_increments — 连续失败递增
2. test_success_resets_count — 成功后归零
3. test_any_response_resets — 4xx 也算收到响应归零
4. test_on_error_receives_attempt — onError 带 attempt
5. test_initial_count_zero — 初始 0
6. test_interleaved_fail_success — 失败成功交错计数正确
7. test_count_bounded — 计数有界(不溢出)
8. test_dispose_clears_count — dispose 后不再上报
### TDD 流程 / 验证方法
同上。
## 任务 32:退避封顶
**所属模块**:02 轮询 **依赖**:30,31 **预估**:8-15 分钟
### 功能点要求
失败计数继续增长但退避间隔停在 maxMs;达到封顶后不再增长(间隔恒等于 maxMs)。
### 测试用例(≥8)
1. test_backoff_cap_reached — 达到封顶
2. test_backoff_stays_capped — 之后保持 maxMs
3. test_cap_with_low_max — 低 maxMs 提前封顶
4. test_cap_with_high_factor — 高 factor 快速封顶
5. test_cap_resets_after_success — 成功后重新从 500 起
6. test_cap_attempt_boundary — 恰好等于封顶那一档
7. test_cap_integration_loop — 集成:循环内退避生效
8. test_cap_config_negative — 非法 maxMs 钳制
### TDD 流程 / 验证方法
同上。
## 任务 33:网络错误走退避且不触发终态
**所属模块**:02 轮询 **依赖**:31 **预估**:8-15 分钟
### 功能点要求
网络错误(fetch 拒绝/超时)不触发 onTerminal、不修改 taskStatuses、进入退避;恢复后继续轮询。
### 测试用例(≥8)
1. test_network_error_no_terminal — 不触发 onTerminal
2. test_network_error_no_status_change — 状态不变
3. test_network_error_backoff_scheduled — 进入退避
4. test_network_error_on_error_called — onError 调用
5. test_network_recovery — 恢复后轮询继续
6. test_network_error_repeated — 多次失败仍退避
7. test_network_error_keeps_task — 任务不丢失
8. test_network_error_then_success — 失败后成功收到响应
### TDD 流程 / 验证方法
vitest fake timers + mock fetch 拒绝。
## 任务 34:HTTP 4xx/5xx 分类
**所属模块**:02 轮询 **依赖**:31 **预估**:8-15 分钟
### 功能点要求
4xx/5xx 记 onError 并退避;5xx 且无法解析明细时不误判 FAILED;不触发终态。
### 测试用例(≥8)
1. test_4xx_on_error — 4xx 记 onError
2. test_5xx_on_error — 5xx 记 onError
3. test_5xx_no_terminal_failed — 不误判 FAILED
4. test_5xx_backoff — 5xx 退避
5. test_5xx_unknown_status_untouched — 未知状态不动
6. test_4xx_recovery — 4xx 后恢复
7. test_status_500_partial_items — 部分 items 仍处理
8. test_5xx_no_status_wipe — 不清空已有状态
### TDD 流程 / 验证方法
同上。
## 任务 35:未知状态不判终态固化
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
PENDING/SYNCING/空串/undefined 状态:isTerminal=false,不触发终态回调,轮询继续。
### 测试用例(≥8)
1. test_pending_not_terminal — PENDING false
2. test_syncing_not_terminal — SYNCING false
3. test_empty_status_not_terminal — 空串 false
4. test_undefined_status_not_terminal — undefined false
5. test_unknown_status_continues_polling — 轮询继续
6. test_mixed_terminal_unknown — 同批终态+未知分开处理
7. test_custom_is_terminal — 自定义判定生效
8. test_lowercase_unknown — 小写未知值也不误判
### TDD 流程 / 验证方法
扩展 polling-state-machine.test.ts。
## 任务 36:终态任务仅一次 onTerminal
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
coordinator.markTerminal 语义:终态任务只触发一次 onTerminal;重复收到同任务终态不再回调;从轮询集合移除。
### 测试用例(≥8)
1. test_terminal_called_once — 只一次
2. test_terminal_removed_from_poll — 移除
3. test_terminal_repeat_response — 重复响应不回调
4. test_terminal_after_readd — 重新 add 后可再触发
5. test_terminal_multiple_tasks — 多任务各自一次
6. test_terminal_coordinator_order — markTerminal 先于 remove
7. test_terminal_storage_cleared — localStorage 清空
8. test_terminal_dispose_no_call — dispose 后不回调
### TDD 流程 / 验证方法
同上。
## 任务 37:onTerminal 抛错语义测试
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
onTerminal 抛错:任务已从轮询集合移除(语义固化);错误不中断其他终态回调;页面可自行重新 add() 恢复。
### 测试用例(≥8)
1. test_terminal_error_does_not_break_loop — 不中断循环
2. test_terminal_error_task_removed — 任务已移除
3. test_terminal_error_re_add_works — 重新 add 生效
4. test_terminal_error_other_tasks — 其他终态仍回调
5. test_terminal_error_swallowed — 错误被捕获不抛到外层
6. test_terminal_error_then_success — 后一轮正常
7. test_terminal_error_not_retried — 不自动重试回调
8. test_terminal_error_status_kept — 状态保留
### TDD 流程 / 验证方法
同上。
## 任务 38:同轮多任务终态分别回调
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
同一轮响应中多个任务同时终态:每个任务各触发一次 onTerminal(带各自 detail/status);顺序按响应顺序。
### 测试用例(≥8)
1. test_multi_terminal_each_called — 各自回调
2. test_multi_terminal_correct_detail — 各自 detail
3. test_multi_terminal_correct_status — 各自 status
4. test_multi_terminal_order — 按响应顺序
5. test_multi_terminal_one_fails_other_runs — 一个抛错另一个仍回调
6. test_multi_terminal_all_removed — 全部移除
7. test_multi_terminal_await_sequence — 依次 await
8. test_multi_terminal_async_on_terminal — 异步回调等待
### TDD 流程 / 验证方法
同上。
## 任务 39:in-flight 合并测试补强
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
in-flight 期间不叠加 timer;等待上一次完成再按退避重试;同一时间只有一个请求。
### 测试用例(≥8)
1. test_in_flight_no_second_request — 不并发
2. test_in_flight_queues_after — 完成后继续
3. test_in_flight_backoff_wait — 等待按退避
4. test_in_flight_timer_single — 仅一个 timer
5. test_in_flight_add_during — 期间 add 不重复
6. test_in_flight_error_releases — 失败后释放
7. test_in_flight_immediate_repeat — ensure(true) 不叠加
8. test_in_flight_long_request — 长请求期间无叠加
### TDD 流程 / 验证方法
同上。
## 任务 40:页面隐藏降频与可见恢复
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
visibilityState=hidden 时 30s 间隔;切回 visible 立即刷新(开关可配置、延迟可配置);降频不改任务集合。
### 测试用例(≥8)
1. test_hidden_30s_interval — 隐藏 30s
2. test_visible_5s_interval — 可见 5s
3. test_foreground_refresh_triggered — 恢复立即刷新
4. test_foreground_refresh_disabled — 开关关闭不刷新
5. test_foreground_refresh_delayed — 延迟生效
6. test_hidden_polling_continues — 隐藏仍轮询
7. test_visibility_event_bound_unbound — 事件绑定/解绑
8. test_hidden_no_immediate_refresh — 隐藏不触发即时刷新
### TDD 流程 / 验证方法
mock document.visibilityState + dispatchEvent。
## 任务 41:storage 恢复与清理
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
恢复时过滤非正数/非数字;空列表清除 key;终态清理后同步 storage;写失败不影响功能。
### 测试用例(≥8)
1. test_storage_restore_valid_ids — 恢复合法 id
2. test_storage_restore_filters_invalid — 过滤非法
3. test_storage_restore_empty_clears — 空列表清 key
4. test_storage_terminal_removes — 终态后 key 更新
5. test_storage_write_failure_ignored — 写失败不抛
6. test_storage_bad_json — 坏 JSON 返回空
7. test_storage_restore_starts_polling — 恢复即开始轮询
8. test_storage_no_key_noop — 无 key 无操作
### TDD 流程 / 验证方法
mock localStorage。
## 任务 42:退避恢复测试
**所属模块**:02 轮询 **依赖**:31,32 **预估**:8-15 分钟
### 功能点要求
失败→退避序列→成功→恢复 500ms 正常间隔;连续失败计数归零后重新从 500 起。
### 测试用例(≥8)
1. test_recovery_after_failure — 失败后成功恢复
2. test_backoff_reset_after_success — 计数归零
3. test_interval_returns_to_base — 回到正常间隔
4. test_recovery_cycle_repeat — 多次失败成功循环
5. test_recovery_partial_items — 部分成功算成功
6. test_recovery_with_foreground — 前台刷新下恢复
7. test_recovery_after_many_failures — 长失败后恢复
8. test_recovery_timing_assert — 时间断言(fake timers)
### TDD 流程 / 验证方法
fake timers 时间断言。
## 任务 43:progressCache TTL 惰性清理边界
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
缓存条目超 TTL 在读取时清理;条目数上限(溢出淘汰最旧);空缓存 get 返回 undefined。
### 测试用例(≥8)
1. test_cache_get_hit — 命中返回
2. test_cache_get_expired_cleared — 过期清理
3. test_cache_max_entries_evict — 超上限淘汰
4. test_cache_empty_get_undefined — 空缓存
5. test_cache_set_overwrites — 同 key 覆盖
6. test_cache_ttl_zero — TTL=0 立即过期
7. test_cache_lazy_cleanup — 惰性清理不主动扫
8. test_cache_after_polling_cycle — 轮询周期内缓存可用
### TDD 流程 / 验证方法
扩展 progress-response-cache.test.ts。
## 任务 44:轻量端点切换能力
**所属模块**:02 轮询 **依赖**:26 **预估**:8-15 分钟
### 功能点要求
useTaskProgressLoop 的 fetchProgress 可切到轻量端点(只返回 taskId/status/fileStatus 的 items);返回结构兼容(extractTaskId/extractStatus 从轻量字段取);默认仍走原端点。
### 测试用例(≥8)
1. test_light_fetch_used — 切换后调轻量
2. test_light_detail_shape_parsed — 轻量结构解析
3. test_light_fallback_to_old — 默认旧端点
4. test_light_missing_optional — 轻量缺字段容错
5. test_light_terminal_detection — 终态判定
6. test_light_progress_cache — 缓存写入
7. test_light_on_update_called — onUpdate 收到
8. test_light_snapshot_compat — 与旧响应兼容
### TDD 流程 / 验证方法
同上。
## 任务 45:轮询与历史刷新分离
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
进度轮询不触发历史接口;历史刷新独立触发(onTerminal 或页面主动);同一轮中不混发 history 请求。
### 测试用例(≥8)
1. test_polling_no_history_request — 轮询不发 history
2. test_terminal_triggers_history — 终态触发历史刷新
3. test_history_separate_call — 独立调用
4. test_no_burst_history — 同轮不多发
5. test_history_ttl_cache — 历史 TTL 生效
6. test_history_force_refresh — force 参数跳过缓存
7. test_polling_history_parallel — 可并行不阻塞
8. test_polling_continues_after_history — 历史后轮询继续
### TDD 流程 / 验证方法
同上。
## 任务 46:双页面同 key 行为记录
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
只读断言现状:两页面同 storageKey 时各自独立轮询集合,互不等待(记录已知边界,不改实现)。
### 测试用例(≥8)
1. test_two_loops_same_key_independent — 独立
2. test_shared_key_no_crash — 不崩溃
3. test_shared_key_last_write — 写互相覆盖(现状)
4. test_shared_key_restore_both — 各自恢复
5. test_shared_key_no_live_sync — 无实时同步(现状)
6. test_shared_key_dispose_one — 一方卸载另一方不受影响
7. test_documented_boundary — 行为与文档一致
8. test_shared_key_separate_storage — 不同 key 完全隔离
### TDD 流程 / 验证方法
同上。
## 任务 47:轮询 baseline 统计补强
**所属模块**:02 轮询 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
baseline 记录:请求量、响应体大小、缓存内存占用、轮询失败次数;每轮 refreshOnce 后回传 baseline 实例。
### 测试用例(≥8)
1. test_baseline_request_count — 请求计数
2. test_baseline_response_size — 响应大小
3. test_baseline_cache_usage — 缓存占用
4. test_baseline_failure_count — 失败次数
5. test_baseline_callback_after_round — 每轮回调
6. test_baseline_round_accuracy — 轮次准确
7. test_baseline_reset — 重置
8. test_baseline_optional_off — 不传 onBaseline 不创建
### TDD 流程 / 验证方法
扩展 task-polling-baseline.test.ts。
## 任务 48:轮询全量回归
**所属模块**:02 轮询 **依赖**:29-47 **预估**:8-15 分钟
### 功能点要求
20 个既有轮询相关测试 + 本轮新增全部通过;`npm run build`(vue-tsc)通过;无行为回退。
### 测试用例(≥8)
1-8. 回归清单:既有 20 文件全绿、新 19 文件全绿、build 通过、无类型错误、无未用导出、页面入口编译、快照一致、git diff 仅限 shared 目录
### TDD 流程 / 验证方法
`npx vitest run` 全绿 + `npm run build` 通过。
@@ -1,169 +0,0 @@
# 03-plan — RequestTraceFilter 验证与补测
> 对应 `docs/specs/03-request-trace-filter.md`。**实现已完成**(multipart 直通、阈值 1MB、5 个测试)。
> 本 plan 将测试补齐到 ≥8/功能点,并对实现做验证型补强。技术栈:Java 21 + JUnit5 + MockMvc(`backend-java/`)。
> 测试命令:`cd crawler-plugin/backend-java && mvn test -Dtest=<类名>`。
## 任务 49:multipart 直通断言补测
**所属模块**:03 过滤器 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
multipart Content-Type(含大小写、带 boundary 参数、其他 multipart 子类型)请求一律不包装;现有 5 个测试保留。
### 测试用例(≥8)
1. test_multipart_upper_boundary — Multipart/Form-Data 大写不包装
2. test_multipart_mixed_case — mUlTiPaRt 混合大小写
3. test_multipart_related — multipart/related 不包装
4. test_multipart_no_boundary — 无 boundary 不包装
5. test_multipart_with_params — 多参数 content-type
6. test_multipart_whitespace — 首尾空白 content-type
7. test_multipart_put_not_wrapped — multipart PUT 不包装
8. test_application_json_still_wrapped — 对照:json 仍包装
### TDD 流程
1. 追加测试 → 运行确认现有实现是否满足(若已满足为 GREEN,逐条确认覆盖)→ 任何一条失败修正实现
2. `mvn test -Dtest=RequestTraceFilterTest` 全绿
### 验证方法
`mvn test -Dtest=RequestTraceFilterTest`:Tests run ≥13。
## 任务 50:包装与阈值钳制补测
**所属模块**:03 过滤器 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
JSON/PUT/DELETE 包装;阈值钳制(<1MB 请求钳到 1MB 下限;0/负数钳制);ContentCachingRequestWrapper 构造参数生效。
### 测试用例(≥8)
1. test_json_post_wrapped_limit — json 用传入阈值
2. test_limit_below_minimum_clamped — 小于 1MB 钳制
3. test_limit_zero_clamped — 0 钳制
4. test_limit_negative_clamped — 负数钳制
5. test_limit_exact_minimum — 恰好 1MB 不钳
6. test_limit_large_kept — 大阈值保留
7. test_delete_wrapped — DELETE 包装
8. test_put_wrapped — PUT 包装
### TDD 流程 / 验证方法
同上(构造 RequestTraceFilter 实例断言阈值字段,或包内可见字段读取)。
## 任务 51:日志不读 body 行为测试
**所属模块**:03 过滤器 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
过滤器执行前后:body 缓存未被读取(日志只消费 method/uri/status/headers);JSON 请求过滤后业务侧仍可读 body。
### 测试用例(≥8)
1. test_filter_log_no_body_read — 日志不含 body 内容
2. test_filter_passes_chain — 过滤链正常
3. test_business_reads_body_json — 业务可读 json body
4. test_business_reads_body_multipart — multipart 业务可读
5. test_body_read_after_filter — 过滤后输入流可再读
6. test_headers_added — 实例响应头存在
7. test_cost_logged — costMs 记录
8. test_request_id_logged — requestId 传递
### TDD 流程 / 验证方法
MockMvc 集成:POST json 断言 200 + 业务 handler 收到 body。
## 任务 52:阈值生效集成测试
**所属模块**:03 过滤器 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
>1MB JSON 请求不整包缓存(wrapper 截断缓存);body 读取行为正确;multipart 大文件上传不受影响。
### 测试用例(≥8)
1. test_large_json_over_1mb — >1MB json 请求成功
2. test_large_json_not_cached_fully — 缓存截断(断言 wrapper 截断语义)
3. test_large_multipart_upload — >1MB multipart 上传成功
4. test_large_body_business_reads — 业务读完整 body
5. test_small_json_cached — 小 json 正常缓存
6. test_upload_content_length_header — content-length 保留
7. test_large_json_forward_path — 转发路径大 body 正常
8. test_large_json_time_bounded — 大 body 处理耗时合理
### TDD 流程 / 验证方法
MockMvc + 大字符串 body(需注意阈值配置注入)。
## 任务 53:yml 默认值与 env 覆盖测试
**所属模块**:03 过滤器 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
application.yml 默认 1048576(1MB);`AIIMAGE_INSTANCE_ROUTE_REQUEST_BODY_CACHE_LIMIT_BYTES` 覆盖生效;占位符语法正确。
### 测试用例(≥8)
1. test_yml_default_1mb — yml 值 1048576
2. test_env_override_value — env 覆盖生效
3. test_env_override_large — 大值覆盖
4. test_env_override_small — 小值覆盖(被钳制)
5. test_placeholder_format — ${VAR:default} 格式
6. test_default_matches_code — 与代码默认一致
7. test_env_unset_uses_default — 未设 env 用默认
8. test_yml_loads — Spring 上下文加载配置
### TDD 流程 / 验证方法
配置加载测试(@Value 注入断言)。
## 任务 54:转发服务 multipart 安全测试
**所属模块**:03 过滤器 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
TaskOwnerForwardService.requestBody 非 wrapper 时走 inputStream 路径;multipart 转发不抛错;body 字节与原请求一致。
### 测试用例(≥8)
1. test_forward_non_wrapper_reads_stream — inputStream 路径
2. test_forward_wrapper_reads_cache — wrapper 路径
3. test_forward_multipart_body_ok — multipart 转发成功
4. test_forward_io_error_message — IO 异常消息
5. test_forward_hop_by_hop_removed — hop-by-hop 头剔除
6. test_forward_forwarded_header_set — 转发头设置
7. test_forward_content_type_kept — content-type 保留
8. test_forward_loop_detected — 循环转发拒绝
### TDD 流程 / 验证方法
MockHttpServletRequest + 反射/包可见调用 requestBody。
## 任务 55:转发 body 完整性测试
**所属模块**:03 过滤器 **依赖**:54 **预估**:8-15 分钟
### 功能点要求
转发后:JSON 与 multipart body 均与原始一致(字节级);双实例 owner 路由场景转发内容不损坏。
### 测试用例(≥8)
1. test_forward_json_bytes_equal — json 字节一致
2. test_forward_multipart_bytes_equal — multipart 字节一致
3. test_forward_empty_body — 空 body 安全
4. test_forward_large_body — 大 body 一致
5. test_forward_utf8_chinese — 中文内容一致
6. test_forward_special_chars — 特殊字符一致
7. test_forward_multiple_chunks — 多段内容一致
8. test_forward_identity_repeated — 两次转发一致
### TDD 流程 / 验证方法
同上。
## 任务 56:plan §6 文档现状修正核对
**所属模块**:03 过滤器 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
更新 `java-architecture-optimization-plan.md` §6:现状描述改为"已实现 multipart 直通 + 1MB 阈值 + 过滤器日志不读 body";移除"大范围缓存风险"表述;标注本轮未做项(上传指标/流式下载/磁盘告警→后续批次)。
### 测试用例(≥8,验证型)
1. test_doc_no_obsolete_default — 文档无 104857600 残留
2. test_doc_multipart_stated — 直通已记录
3. test_doc_threshold_1mb — 阈值 1MB 已记录
4. test_doc_not_reading_body — 不读 body 已记录
5. test_doc_deferred_listed — 未做项已列
6. test_doc_specs_referenced — 引用 03 spec
7. test_doc_consistency_overview — 与 00-overview 实施记录一致
8. test_doc_no_todo_left — 无 TBD/TODO 残留
### TDD 流程 / 验证方法
grep 校验文档(写一个简单断言脚本/测试读取 md 断言)。
@@ -1,419 +0,0 @@
# 04-plan — TaskResultFileJobWorker Handler 注册表
> 对应 `docs/specs/04-result-file-job-handler-registry.md`。技术栈:Java 21 + Spring + JUnit5。
> 纪律:第一阶段 Handler 只委托原 Service,不同时重写业务逻辑;Job 状态值、创建时机、重试入口不变。
## 任务 57:ResultFileJobHandler 接口定义
**所属模块**:04 注册表 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
`modules/task/service/ResultFileJobHandler.java`:moduleType() / process(job) 返回 boolean / cleanup(job) 默认空 / onFailure(job,msg) 默认空 / supportsAsyncOffload() 默认 false / isOwnerScoped() 默认 false。
### 测试用例(≥8)
1. test_interface_methods_present — 6 方法签名齐全
2. test_cleanup_default_noop — 默认空实现
3. test_on_failure_default_noop — 默认空实现
4. test_offload_default_false — 默认 false
5. test_owner_scoped_default_false — 默认 false
6. test_process_returns_boolean — boolean 返回类型
7. test_module_type_identity — moduleType 唯一标识
8. test_javadoc_contract — 契约文档注释齐全(模块类型对应表)
### TDD 流程
1. 写接口 + 编译测试(实现类模拟)→ 类不存在 RED
2. 实现接口 → GREEN
3. `mvn test` 通过
## 任务 58:注册表容器与唯一性校验
**所属模块**:04 注册表 **依赖**:57 **预估**:8-15 分钟
### 功能点要求
`ResultFileJobHandlerRegistry`:构造时收集 List<ResultFileJobHandler>,构建 moduleType→handler Map;重复 moduleType 抛 IllegalStateException(含模块名);提供 `resolve(moduleType)` 与 `moduleTypes()`。
### 测试用例(≥8)
1. test_register_all_handlers — 全部注册
2. test_resolve_existing — 解析已知模块
3. test_resolve_unknown_throws — 未知模块抛异常
4. test_duplicate_module_type_throws — 重复注册抛 IllegalStateException
5. test_duplicate_error_message — 错误消息含模块名
6. test_module_types_listed — 枚举全部模块
7. test_empty_registry_ok — 空注册表可解析(抛错)
8. test_resolve_case_sensitive — 大小写敏感
### TDD 流程
1. 写测试(先 mock handler)→ RED
2. 实现注册表 → GREEN
3. `mvn test -Dtest=ResultFileJobHandlerRegistryTest` 通过
## 任务 59:启动校验(fail-fast)
**所属模块**:04 注册表 **依赖**:58 **预估**:8-15 分钟
### 功能点要求
Spring 启动时校验:TaskFileJobConfig 的每个 moduleType 有且仅有一个 Handler;缺注册(如新增模块未配 Handler)启动失败并给出缺失清单。
### 测试用例(≥8)
1. test_startup_all_modules_covered — 全部 moduleType 覆盖
2. test_startup_missing_handler_fails — 缺注册启动失败
3. test_startup_missing_message_lists — 错误消息列缺失模块
4. test_startup_duplicate_fails — 双注册失败
5. test_startup_config_source — 从 TaskFileJobConfig 枚举
6. test_startup_no_handler_new_module — 新模块无 handler 失败
7. test_startup_valid_no_error — 合法配置启动通过
8. test_startup_check_idempotent — 校验可重复执行
### TDD 流程 / 验证方法
ApplicationContextRunner 或直接调用校验方法断言。
## 任务 60:SHOP_MATCH Handler
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
### 功能点要求
`ShopMatchResultFileJobHandler`:moduleType="SHOP_MATCH";process 委托 shopMatchTaskService.processResultFileJob 返回 true;cleanup 调 taskResultPayloadService.deleteLatest(原 cleanupAfterSuccess 分支)。
### 测试用例(≥8)
1. test_module_type — 正确
2. test_process_delegates — 委托调用
3. test_process_returns_true — true
4. test_cleanup_calls_delete_latest — 清理调用
5. test_cleanup_args — taskId/moduleType/scopeKey 参数
6. test_offload_false — 不支持异步
7. test_owner_scoped_false — 非 owner scoped
8. test_process_null_job_guarded — 空 job 安全
### TDD 流程
1. 写测试 mock Service → RED
2. 实现 Handler → GREEN
3. `mvn test -Dtest=ShopMatchResultFileJobHandlerTest` 通过
## 任务 61:PRICE_TRACK Handler
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
与 60 同构:moduleType="PRICE_TRACK";process→priceTrackTaskService;cleanup→deleteLatest。
### 测试用例(≥8)
8 例:moduleType、delegate、true、cleanup、参数、offload false、ownerScoped false、空 job。
## 任务 62:PRODUCT_RISK_RESOLVE Handler
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
与 60 同构:moduleType="PRODUCT_RISK_RESOLVE";process→productRiskTaskService。
### 测试用例(≥8)
同 61。
## 任务 63:PUBLISH Handler(ownerScoped)
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
moduleType=PublishTaskService.MODULE_TYPE;process→publishTaskService.processResultFileJob;cleanup→publishTaskService.cleanupResultFileJob;**isOwnerScoped()=true**(原 Worker isOwnerScopedJob 含 PUBLISH)。
### 测试用例(≥8)
1. test_module_type_constant — 用 MODULE_TYPE 常量
2. test_process_delegates
3. test_cleanup_delegates — cleanupResultFileJob
4. test_owner_scoped_true — true
5. test_process_true
6. test_cleanup_no_delete_latest — 不走 payload.deleteLatest
7. test_offload_false
8. test_null_job_guarded
## 任务 64:QUERY_ASIN Handler
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
与 60 同构:moduleType="QUERY_ASIN";process→queryAsinTaskService。
### 测试用例(≥8)
同 61。
## 任务 65:SHOP_DATA_CRAWL Handler(cleanup+onFailure)
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
moduleType="SHOP_DATA_CRAWL";process→shopDataCrawlTaskService;cleanup→deleteLatest + cleanupResultFileJob(两处都调);**onFailure→handleResultFileJobFailure**;**isOwnerScoped()=true**。
### 测试用例(≥8)
1. test_module_type
2. test_process_delegates
3. test_cleanup_delete_latest_and_service — 两处清理都调
4. test_on_failure_delegates — handleResultFileJobFailure
5. test_on_failure_args — job+message 参数
6. test_owner_scoped_true
7. test_process_true
8. test_null_job_guarded
## 任务 66:WITHDRAW Handler(finalize 时机保持)
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
moduleType="WITHDRAW";process→withdrawTaskService.processResultFileJob;cleanup→deleteLatest;**onSuccess 扩展:tryFinalizeTask 在 markSuccess 之后调用**(原 finalizeWithdraw 标志语义,时机严格保持)。
### 测试用例(≥8)
1. test_module_type
2. test_process_delegates
3. test_cleanup_delete_latest
4. test_finalize_after_success_order — 顺序:成功后再 finalize
5. test_finalize_called_once — 只调一次
6. test_finalize_false_result — 非成功不 finalize
7. test_owner_scoped_false
8. test_null_job_guarded
## 任务 67:PATROL_DELETE Handler
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
与 60 同构:moduleType="PATROL_DELETE";process→patrolDeleteTaskService。
### 测试用例(≥8)
同 61。
## 任务 68:APPEARANCE_PATENT Handler(异步+offload)
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
moduleType="APPEARANCE_PATENT";process→appearancePatentTaskService(返回 boolean,false=等待异步);cleanup→cleanupResultFileJob;**supportsAsyncOffload()=true;isOwnerScoped()=true**。
### 测试用例(≥8)
1. test_module_type
2. test_process_boolean_true — true 情况
3. test_process_boolean_false — false(等待异步)
4. test_cleanup_delegates
5. test_offload_true
6. test_owner_scoped_true
7. test_false_means_waiting — false 语义与 Worker defer 对应
8. test_null_job_guarded
## 任务 69:SIMILAR_ASIN Handler(异步+offload+onFailure)
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
moduleType="SIMILAR_ASIN";process→similarAsinTaskService(boolean);cleanup→cleanupResultFileJob;**onFailure→handleResultFileJobFailure;offload=true;ownerScoped=true**。
### 测试用例(≥8)
1. test_module_type
2. test_process_true / 3. test_process_false
4. test_cleanup_delegates
5. test_on_failure_delegates
6. test_offload_true
7. test_owner_scoped_true
8. test_null_job_guarded
## 任务 70:DELETE_BRAND Handler
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
moduleType="DELETE_BRAND";process→deleteBrandRunService;cleanup→cleanupResultFileJob。
### 测试用例(≥8)
1-8:moduleType、delegate、true、cleanup、offload false、ownerScoped false、参数、空 job。
## 任务 71:BRAND Handler(resolveResultObjectKey 特例)
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
moduleType="BRAND";process→brandTaskService.processResultFileJob;**resultFileUrl 解析特例:resolveResultObjectKey(无 resultId 也走)保留在 Worker 公共路径 resolveResultFileUrl**——Handler 不接管 URL 解析,测试验证该特例不受影响。
### 测试用例(≥8)
1. test_module_type
2. test_process_delegates
3. test_result_url_brand_special — brand resolveResultObjectKey 仍走公共路径
4. test_cleanup_delegates
5. test_offload_false
6. test_owner_scoped_false
7. test_null_job_guarded
8. test_no_delete_latest — brand 不走 payload.deleteLatest
## 任务 72:COLLECT_DATA Handler
**所属模块**:04 注册表 **依赖**:57-59 **预估**:8-15 分钟
moduleType="COLLECT_DATA";process→collectDataService.processResultFileJob;cleanup 为空(原无分支)。
### 测试用例(≥8)
1. test_module_type
2. test_process_delegates
3. test_process_true
4. test_cleanup_noop — 无清理
5. test_offload_false
6. test_owner_scoped_false
7. test_null_job_guarded
8. test_no_delete_latest
## 任务 73:Worker dispatch() 改注册表查找
**所属模块**:04 注册表 **依赖**:60-72 **预估**:8-15 分钟
### 功能点要求
TaskResultFileJobWorker.dispatch(job) 替换 13 个 if/else 为 `handlerRegistry.resolve(moduleType).process(job)`;未知模块 IllegalArgumentException 消息保留;Worker 注入改为 registry。
### 测试用例(≥8)
1. test_dispatch_resolves_handler — 注册表查找
2. test_dispatch_known_module — 已知模块行为一致
3. test_dispatch_unknown_throws — 未知模块 IllegalArgumentException
4. test_dispatch_unknown_message — 消息含模块名
5. test_dispatch_all_13_modules — 13 模块各委托正确
6. test_dispatch_null_job — 空 job 安全
7. test_dispatch_no_longer_branch — 无 if/else 残留(静态检查)
8. test_dispatch_integration_process — process 全链路
### TDD 流程
1. 测试先断言 dispatch 行为(对现有实现 GREEN 基线)→ 改为注册表后仍 GREEN
2. `mvn test` 相关测试通过
## 任务 74:cleanupAfterSuccess 改 handler.cleanup
**所属模块**:04 注册表 **依赖**:60-72 **预估**:8-15 分钟
cleanupAfterSuccess(job):公共 payload 清理保留(部分模块)或进 handler.cleanup;确保原分支语义逐一映射(SHOP_DATA_CRAWL 两处、APPEARANCE_PATENT/SIMILAR_ASIN/PUBLISH/DELETE_BRAND 各 cleanup、其余 deleteLatest)。
### 测试用例(≥8)
1. test_cleanup_shop_data_crawl_both — 两处清理
2. test_cleanup_delete_latest_modules — deleteLatest 模块组
3. test_cleanup_appearance — cleanupResultFileJob
4. test_cleanup_similar — cleanupResultFileJob
5. test_cleanup_publish — cleanupResultFileJob
6. test_cleanup_delete_brand — cleanupResultFileJob
7. test_cleanup_collect_data_noop — 无清理
8. test_cleanup_unknown_ignored — 未知模块不抛
## 任务 75:notifyRetryExhausted 改 handler.onFailure
**所属模块**:04 注册表 **依赖**:60-72 **预估**:8-15 分钟
notifyRetryExhausted(job,msg) 改 handler.onFailure;SHOP_DATA_CRAWL/SIMILAR_ASIN 有回调,其余 noop;回调幂等(失败重试安全)。
### 测试用例(≥8)
1. test_on_failure_shop_data_crawl — 回调
2. test_on_failure_similar — 回调
3. test_on_failure_others_noop — 其余无操作
4. test_on_failure_unknown_ignored — 未知模块安全
5. test_on_failure_idempotent — 重复调用安全
6. test_on_failure_error_swallowed — 回调抛错不中断
7. test_on_failure_args_passed — job+message 传递
8. test_exhausted_finalize_flow — 重试耗尽全流程
## 任务 76:coze offload 判定改 handler
**所属模块**:04 注册表 **依赖**:60-72 **预估**:8-15 分钟
process() 中 APPEARANCE_PATENT/SIMILAR_ASIN 的 cozeTaskExecutor offload 判定改 handler.supportsAsyncOffload();offload 失败回退内联逻辑保持。
### 测试用例(≥8)
1. test_offload_modules_detected — offload 模块识别
2. test_offload_executes_on_coze_executor — 线程池执行
3. test_offload_failure_fallback — 提交失败回退内联
4. test_offload_other_modules_inline — 非 offload 内联
5. test_offload_only_async_modules — 仅异步模块
6. test_offload_no_duplicate_execution — 不回退重复执行
7. test_offload_heartbeat_started — 心跳启动
8. test_offload_integration — 全链路
## 任务 77:owner-scoped 判定改 handler
**所属模块**:04 注册表 **依赖**:60-72 **预估**:8-15 分钟
isOwnerScopedJob 改 handler.isOwnerScoped();owner 解析(scopeKey :owner: 标记)保留公共逻辑;非本实例跳过逻辑保持。
### 测试用例(≥8)
1. test_owner_scoped_modules — 4 个 owner 模块
2. test_owner_scoped_other_owner_skip — 他实例跳过
3. test_owner_scoped_self_process — 本实例处理
4. test_owner_scope_parse — :owner: 解析
5. test_owner_scope_blank — 空 scope 视为本实例
6. test_owner_non_scoped_modules — 非 owner 模块不受影响
7. test_owner_unknown_instance_id — 未配置实例
8. test_owner_integration — 全链路
## 任务 78:模块映射快照测试
**所属模块**:04 注册表 **依赖**:73 **预估**:8-15 分钟
### 功能点要求
快照断言:13 个 moduleType → Handler 类 → 原 Service 方法一一对应;与 04 spec §3 映射表一致;新增模块类型未映射即失败。
### 测试用例(≥8)
1. test_snapshot_all_13_mapped — 13 全映射
2. test_snapshot_shop_match_delegate — 委托方法名快照
3. test_snapshot_appearance_boolean — 返回类型快照
4. test_snapshot_publish_owner — owner 标记快照
5. test_snapshot_failure_callbacks — onFailure 回调快照
6. test_snapshot_no_extra_modules — 无多余映射
7. test_snapshot_mapping_frozen — JSON 快照文件比对
8. test_snapshot_new_module_fails — 新 moduleType 快照失败
## 任务 79:行为等价对比测试
**所属模块**:04 注册表 **依赖**:73-77 **预估**:8-15 分钟
### 功能点要求
同一 Job 序列(成功/失败/重试耗尽/异步等待/owner 跳过)改造前后产生相同状态迁移与依赖调用;用 mock 记录调用序列对比。
### 测试用例(≥8)
1. test_equiv_success_job — 成功序列一致
2. test_equiv_failed_job — 失败序列一致
3. test_equiv_retry_exhausted — 重试耗尽一致
4. test_equiv_async_wait — 异步等待一致
5. test_equiv_owner_skip — owner 跳过一致
6. test_equiv_orphan_failure — 孤儿失败一致
7. test_equiv_call_sequence — 依赖调用顺序一致
8. test_equiv_state_transition — 状态迁移一致
### TDD 流程 / 验证方法
对比测试:改造前录制调用序列(golden),改造后断言一致。
## 任务 80:孤儿失败路径不回归
**所属模块**:04 注册表 **依赖**:73 **预估**:8-15 分钟
BusinessException 含 not found 文案 → markFailedPermanent;非孤儿失败 → markFailed + retry 判断;错误文案匹配清单(task not found/result record not found/任务不存在/记录不存在)。
### 测试用例(≥8)
1. test_orphan_task_not_found_en — 英文文案
2. test_orphan_result_not_found_en
3. test_orphan_cn_messages — 中文文案
4. test_orphan_mark_permanent — markFailedPermanent
5. test_non_orphan_mark_failed — 普通失败
6. test_non_business_exception — 非业务异常
7. test_retry_exhausted_after_orphan — 耗尽后终态
8. test_orphan_no_requeue — 孤儿不重排
## 任务 81:卡死扫描/重试耗尽路径测试
**所属模块**:04 注册表 **依赖**:73 **预估**:8-15 分钟
resetStuckRunningJobsDetailed:超时卡死 job 重置;耗尽 job 走 finalizeRetryExhausted;消息默认文案("文件生成任务运行超时")。
### 测试用例(≥8)
1. test_stuck_reset — 超时重置
2. test_stuck_exhausted_finalize — 耗尽 finalize
3. test_stuck_default_message — 默认文案
4. test_stuck_custom_message — 自定义文案
5. test_stuck_heartbeat_timeout — 心跳超时边界
6. test_stuck_scan_interval — 调度间隔配置
7. test_stuck_no_reset_active — 活跃 job 不重置
8. test_stuck_idempotent — 重复扫描安全
## 任务 82:特殊规则回归(WITHDRAW/coze defer)
**所属模块**:04 注册表 **依赖**:78-81 **预估**:8-15 分钟
WITHDRAW markSuccess 后 tryFinalizeTask;coze 模块 dispatch 返回 false → touchRunning(owner)或 deferRunning;状态与时机与原实现完全一致。
### 测试用例(≥8)
1. test_withdraw_finalize_after_success — 成功后 finalize
2. test_withdraw_no_finalize_failed — 失败不 finalize
3. test_coze_false_owner_touch — owner 路径 touchRunning
4. test_coze_false_defer — 非 owner deferRunning
5. test_coze_false_no_mark_failed — 等待不标记失败
6. test_coze_true_mark_success — 完成后 markSuccess
7. test_withdraw_finalize_once — 只一次
8. test_special_rules_integration — 全链路
### 收尾验证(本模块)
`mvn test` 全量 + `mvn clean package -DskipTests` 通过;04 spec §4 兼容清单逐项核对。
@@ -1,286 +0,0 @@
# 05-plan — 巨型 Service 纯函数抽取
> 对应 `docs/specs/05-service-pure-function-extraction.md`。目标:SimilarAsinTaskService(7228 行)、AppearancePatentTaskService(3195)、ShopDataCrawlTaskService(3013)。
> 纪律:只抽纯函数;门面签名不收缩;每模块独立提交;同一提交只做类拆分。
## 任务 83:SimilarAsinExcelParser 行解析器
**所属模块**:05 拆分 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
新类 `modules/similarasin/service/support/SimilarAsinExcelParser`:POI 读 Excel 行 → 中间行对象(原始单元格值);输入 InputStream/文件 → 输出 List<中间行>;不改动现有解析语义(同一文件输出与现状逐字节一致)。
### 测试用例(≥8)
1. test_parse_normal_rows — 正常多行解析
2. test_parse_single_row — 单行
3. test_parse_columns_mapping — 列序映射
4. test_parse_empty_sheet — 空表返回空
5. test_parse_empty_rows_skipped — 空行跳过
6. test_parse_null_input_throws — 空输入抛 IllegalArgumentException
7. test_parse_unsupported_format — 非 Excel 文件抛对应异常
8. test_parse_no_mutation — 输入流不被篡改(可重复读)
### TDD 流程
1. 写测试(用夹具 xlsx 放 test resources)→ RED
2. 实现解析器(从 Service 中搬移现有解析逻辑)→ GREEN
3. `mvn test -Dtest=SimilarAsinExcelParserTest` 通过
## 任务 84:行解析边界测试
**所属模块**:05 拆分 **依赖**:83 **预估**:8-15 分钟
### 功能点要求
边界输入:超长字段(>32767)、畸形 ASIN(特殊字符)、BOM、混合编码、行数上限(>65535 xlsx)、数值/文本混合单元格。
### 测试用例(≥8)
1. test_parse_long_field — 超长字段不截断/按现状
2. test_parse_malformed_asin — 畸形 ASIN 原样透传
3. test_parse_bom — BOM 头处理
4. test_parse_mixed_encoding — 混合编码单元格
5. test_parse_numeric_cell — 数值单元格转文本
6. test_parse_date_cell — 日期单元格
7. test_parse_formula_cell — 公式单元格取缓存值
8. test_parse_large_sheet — 大表(5000 行)性能上界
## 任务 85:字段归一化器
**所属模块**:05 拆分 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
`SimilarAsinRowNormalizer`:trim/大小写/ASIN 格式统一(保留现状规则,不改变输出);纯函数无状态。
### 测试用例(≥8)
1. test_trim_whitespace — 首尾空白
2. test_lowercase_asin — 小写转大写
3. test_mixed_case_asin — 混合大小写统一
4. test_internal_whitespace_kept — 内部空格保留(现状)
5. test_null_safe — null 安全
6. test_empty_string — 空串
7. test_special_chars_untouched — 特殊字符不动
8. test_normalize_identity_after — 幂等(二次归一不变)
## 任务 86:分组转换器
**所属模块**:05 拆分 **依赖**:83,85 **预估**:8-15 分钟
### 功能点要求
`SimilarAsinGroupingConverter`:归一化行 → 分组 → DTO(TaskItem/FileItem);分组规则与现状一致(同组/子行 2_2、2_3 处理);纯函数。
### 测试用例(≥8)
1. test_group_normal — 正常分组
2. test_group_sub_rows — 子行归组
3. test_group_single_item — 单元素组
4. test_group_empty_input — 空输入空输出
5. test_group_dto_fields — DTO 字段映射
6. test_group_dedup — 组内去重
7. test_group_order — 分组顺序保持
8. test_group_missing_key — 缺分组键兜底
## 任务 87:纯校验器
**所属模块**:05 拆分 **依赖**:85 **预估**:8-15 分钟
### 功能点要求
`SimilarAsinRowValidator`:必填检查、ASIN 格式校验、重复检测;返回错误清单(不抛异常,由调用方决定);规则与现状一致。
### 测试用例(≥8)
1. test_validate_required_present — 必填齐全通过
2. test_validate_required_missing — 缺必填报错
3. test_validate_asin_format — ASIN 格式
4. test_validate_duplicates — 重复标记
5. test_validate_blank_row — 空白行
6. test_validate_no_error_happy — 无误通过
7. test_validate_error_detail — 错误含行列信息
8. test_validate_null_input — 空输入错误清单
## 任务 88:Sheet 构造器
**所属模块**:05 拆分 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
`SimilarAsinSheetBuilder`:结果 Workbook/Sheet 构造辅助(表头、列顺序、样式);输入数据 → 输出 workbook;不落库、无 IO 依赖。
### 测试用例(≥8)
1. test_sheet_header_row — 表头正确
2. test_sheet_column_order — 列顺序固定
3. test_sheet_data_rows — 数据行写入
4. test_sheet_empty_data — 空数据仍出表头
5. test_sheet_style_applied — 样式应用
6. test_sheet_zip_output — 可输出 xlsx 文件流
7. test_sheet_large_rows — 大行数(5000)性能
8. test_sheet_no_state_leak — 多次调用独立
## 任务 89:SimilarAsinService.parse 门面改委托
**所属模块**:05 拆分 **依赖**:83-88 **预估**:8-15 分钟
### 功能点要求
parse 方法内部改为:parser.parse → normalizer.normalize → validator → converter → 落库(落库逻辑保留原处);方法签名、参数、返回类型一字不变;删除搬走的代码。
### 测试用例(≥8)
1. test_parse_signature_unchanged — 签名编译兼容
2. test_parse_delegates_parser — 调用解析器
3. test_parse_delegates_normalizer
4. test_parse_delegates_validator
5. test_parse_delegates_converter
6. test_parse_persistence_kept — 落库逻辑仍在
7. test_parse_result_same — 与改造前结果一致
8. test_parse_exception_same — 异常行为一致
## 任务 90:抽取前后快照对比测试
**所属模块**:05 拆分 **依赖**:89 **预估**:8-15 分钟
### 功能点要求
夹具 Excel → 解析结果快照(golden 文件);抽取前后同一夹具输出完全一致;快照变更即失败(防止行为漂移)。
### 测试用例(≥8)
1. test_snapshot_parse_output — 解析输出快照一致
2. test_snapshot_groups — 分组快照
3. test_snapshot_dtos — DTO 快照
4. test_snapshot_error_cases — 错误案例快照
5. test_snapshot_reproducible — 可重复(跑两次一致)
6. test_snapshot_golden_committed — golden 文件存在
7. test_snapshot_diff_detected — 篡改 golden 即失败
8. test_snapshot_regression_all_parse — 全 parse 路径回归
## 任务 91:SimilarAsin 历史查询组装抽取
**所属模块**:05 拆分 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
历史列表 VO 拼装(history + toHistoryItem 辅助)抽到独立组件 `SimilarAsinHistoryAssembler`;只读不落库;输出与现状一致。
### 测试用例(≥8)
1. test_assembler_history_items — 历史项组装
2. test_assembler_no_result — 无结果空列表
3. test_assembler_file_state — file 状态附带
4. test_assembler_order — 排序保持
5. test_assembler_null_task — 缺 task 兜底
6. test_assembler_download_url — URL 构造
7. test_assembler_immutable_input — 输入不被改
8. test_assembler_consistency — 与现状输出一致
## 任务 92:SimilarAsin 全量回归
**所属模块**:05 拆分 **依赖**:89-91 **预估**:8-15 分钟
### 功能点要求
similarasin 模块相关测试全绿;`mvn test` 无回归;API 行为与改造前一致。
### 测试用例(≥8)
1-8. 回归清单:新组件测试全绿、既有 similarasin 测试全绿、controller 签名编译、DTO 字段快照、Python 回调相关测试、单测全量、package 通过、git diff 无越界
### TDD 流程 / 验证方法
`mvn test` + `mvn clean package -DskipTests`。
## 任务 93:AppearancePatent 行解析/归一化抽取
**所属模块**:05 拆分 **依赖**:83,85 **预估**:8-15 分钟
同 83/85 模式,针对 AppearancePatentTaskService 的解析与归一化逻辑(注意其 Excel 结构与 similarasin 不同)。
### 测试用例(≥8)
1-8:正常解析、单行、空表、空行、归一化规则、边界(超长/畸形)、输入安全、快照一致。
## 任务 94:AppearancePatent Sheet 构造抽取
**所属模块**:05 拆分 **依赖**:88 **预估**:8-15 分钟
同 88 模式(列顺序以 appearancepatent 现状为准)。
### 测试用例(≥8)
1-8:表头、列序、数据行、空数据、样式、输出流、大行数、无状态泄漏。
## 任务 95:AppearancePatent 门面改委托
**所属模块**:05 拆分 **依赖**:93,94 **预估**:8-15 分钟
同 89 模式;注意 appearancepatent 的 submitResult 双事务路径不动。
### 测试用例(≥8)
1-8:签名不变、委托各组件、落库保留、结果一致、异常一致、双事务路径不变、owner 检查不变、全回归。
## 任务 96:AppearancePatent 快照对比测试
**所属模块**:05 拆分 **依赖**:95 **预估**:8-15 分钟
同 90 模式(夹具为 appearancepatent 实际 Excel 结构)。
### 测试用例(≥8)
同 90。
## 任务 97:AppearancePatent 历史查询组装抽取
**所属模块**:05 拆分 **依赖**:无 **预估**:8-15 分钟
同 91 模式。
### 测试用例(≥8)
同 91。
## 任务 98:AppearancePatent 全量回归
**所属模块**:05 拆分 **依赖**:95-97 **预估**:8-15 分钟
同 92 模式。
### 测试用例(≥8)
同 92(appearancepatent 相关)。
## 任务 99:ShopDataCrawl 行解析抽取
**所属模块**:05 拆分 **依赖**:83,85 **预估**:8-15 分钟
同 93 模式(shopdatacrawl 结构)。
### 测试用例(≥8)
同 93。
## 任务 100:ShopDataCrawl Sheet 构造抽取
**所属模块**:05 拆分 **依赖**:88 **预估**:8-15 分钟
同 94 模式。
### 测试用例(≥8)
同 94。
## 任务 101:ShopDataCrawl 门面改委托
**所属模块**:05 拆分 **依赖**:99,100 **预估**:8-15 分钟
同 95 模式。
### 测试用例(≥8)
同 95。
## 任务 102:ShopDataCrawl 快照对比测试
**所属模块**:05 拆分 **依赖**:101 **预估**:8-15 分钟
同 96 模式。
### 测试用例(≥8)
同 96。
## 任务 103:ShopDataCrawl 历史查询组装抽取
**所属模块**:05 拆分 **依赖**:无 **预估**:8-15 分钟
同 97 模式。
### 测试用例(≥8)
同 97。
## 任务 104:ShopDataCrawl 全量回归
**所属模块**:05 拆分 **依赖**:101-103 **预估**:8-15 分钟
同 98 模式。
### 测试用例(≥8)
同 98。
### 收尾验证(本模块)
`mvn test` 全量 + `mvn clean package -DskipTests`;05 spec §4 不变要求逐项核对;三模块各一个独立提交。
@@ -1,325 +0,0 @@
# 06-plan — 只读查询与批量加载优化
> 对应 `docs/specs/06-read-query-batch-loading.md`。行为不变型优化 + 新增 progress/light 轻量接口。
> 技术栈:Java 21 + MyBatis-Plus + Flyway。
## 任务 105:similarasin 历史列表 IN 查询批量加载
**所属模块**:06 批量加载 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
history 方法:任务+结果+Job 关联数据由逐条查询改为 IN 批量查询 + 按 ID Map 装配;分页结果、排序、过滤不变;输出与现状一致。
### 测试用例(≥8)
1. test_history_batch_loads — 批量加载装配
2. test_history_single_row — 单条
3. test_history_multiple_tasks — 多任务
4. test_history_no_jobs — 无 Job 兼容
5. test_history_order_unchanged — 排序不变
6. test_history_pagination — 分页不变
7. test_history_missing_related — 关联缺失兜底
8. test_history_sql_count — IN 查询次数(≤N,断言 mapper 调用次数)
### TDD 流程
1. 写测试(mock mapper 断言查询次数与装配)→ RED
2. 改造 history 实现 → GREEN
3. `mvn test -Dtest=SimilarAsinTaskServiceTest` 通过
## 任务 106:appearancepatent 历史列表批量加载
**所属模块**:06 批量加载 **依赖**:105 **预估**:8-15 分钟
同 105 模式。
### 测试用例(≥8)
同 105(appearancepatent)。
## 任务 107:结果列表关联 Job 批量加载
**所属模块**:06 批量加载 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
结果列表/详情页关联 TaskFileJob 状态:findAssembleJobsByResultIds 覆盖审计;逐条查 result→job 的路径改 IN;输出不变。
### 测试用例(≥8)
1. test_result_job_batch — 批量取 Job
2. test_result_job_single — 单条
3. test_result_job_empty — 空结果
4. test_result_job_map_keyed — 按 resultId Map
5. test_result_job_missing — 缺 Job 兜底
6. test_result_job_query_count — 查询次数断言
7. test_result_job_null_guard — null 安全
8. test_result_job_consistency — 与现状一致
## 任务 108:dashboard 聚合查询
**所属模块**:06 批量加载 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
dashboard 统计改批量聚合(COUNT/GROUP BY 一次出);状态分类计数与逐条统计结果一致;输出结构不变。
### 测试用例(≥8)
1. test_dashboard_counts — 各状态计数
2. test_dashboard_empty — 空用户 0 计数
3. test_dashboard_aggregate_sql — 聚合 SQL 调用
4. test_dashboard_recent_tasks — 最近任务列表
5. test_dashboard_consistency — 与逐条一致
6. test_dashboard_mixed_status — 混合状态
7. test_dashboard_user_filter — 用户过滤
8. test_dashboard_big_data — 大数据量聚合
## 任务 109:progress/light 轻量接口(similarasin 首个)
**所属模块**:06 批量加载 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
新端点 `POST /api/similar-asin/tasks/progress/light`:body {taskIds};resp items[{taskId,status,statusCode?,fileStatus,fileReady,updatedAt}];旧 progress/batch 保留不动;走轻量查询(不查明细/result 行)。
### 测试用例(≥8)
1. test_light_returns_light_fields — 只返回轻量字段
2. test_light_missing_task — missingTaskIds
3. test_light_empty_ids — 空 ids 空结果
4. test_light_dedup_ids — 去重
5. test_light_old_endpoint_untouched — 旧端点仍工作
6. test_light_status_mapping — 状态映射正确
7. test_light_file_fields — file 字段附带
8. test_light_unknown_id — 未知 id 缺失列表
### TDD 流程
1. 测试(MockMvc 打新端点)→ RED(404)
2. 实现 controller + service → GREEN
3. `mvn test -Dtest=SimilarAsinControllerTest` 通过
## 任务 110:progress/light 字段白名单
**所属模块**:06 批量加载 **依赖**:109 **预估**:8-15 分钟
### 功能点要求
响应仅含白名单字段(taskId/status/statusCode/fileStatus/fileReady/updatedAt);不含 items 明细/payload/result 内容;序列化断言。
### 测试用例(≥8)
1. test_whitelist_no_items — 无明细数组
2. test_whitelist_no_payload — 无 payload 字段
3. test_whitelist_exact_keys — 键集合精确匹配
4. test_whitelist_file_phase — file 字段在白名单
5. test_whitelist_extra_rejected — 多余键测试失败
6. test_whitelist_null_values_ok — null 值允许
7. test_whitelist_response_size_small — 响应体小(<1KB)
8. test_whitelist_documented — 白名单文档一致
## 任务 111:progress/light 空/超长 taskIds
**所属模块**:06 批量加载 **依赖**:109 **预估**:8-15 分钟
### 功能点要求
空数组→空 items;null→空;>200 个截断或返回错误(定义行为);非正数过滤。
### 测试用例(≥8)
1. test_light_empty_array — 空数组
2. test_light_null_body — null body 处理
3. test_light_negative_filter — 负数过滤
4. test_light_zero_filter — 0 过滤
5. test_light_over_200 — 超长截断/错误
6. test_light_duplicates — 重复去重
7. test_light_single — 单 id
8. test_light_max_exact — 恰好上限
## 任务 112:progress/light 终态任务返回
**所属模块**:06 批量加载 **依赖**:109 **预估**:8-15 分钟
### 功能点要求
SUCCESS/FAILED 任务在 light 接口返回终态状态 + file 阶段;前端可凭此停止轮询并展示。
### 测试用例(≥8)
1. test_light_success_task — SUCCESS 返回
2. test_light_failed_task — FAILED 返回
3. test_light_pending — PENDING
4. test_light_running — RUNNING
5. test_light_success_file_status — 附带 fileStatus
6. test_light_failed_file_error — 失败附带 fileError
7. test_light_terminal_complete — 终态字段完整
8. test_light_status_frozen — 状态值语义不变
## 任务 113:其余模块 progress/light 接入
**所属模块**:06 批量加载 **依赖**:109-112 **预估**:8-15 分钟
### 功能点要求
同构端点接入:appearancepatent/publish/queryasin/shopdatacrawl/withdraw/patroldelete/shopmatch/productrisk/pricetrack/deletebrand/collectdata(11 个);路径模式统一;字段白名单一致。
### 测试用例(≥8)
1. test_light_all_modules_exist — 12 个 light 端点存在
2. test_light_common_shape — 响应结构一致
3. test_light_module_specific_status — 各模块状态映射
4. test_light_publish_files — publish 文件级字段
5. test_light_old_endpoints_all_kept — 旧端点全保留
6. test_light_whitelist_all — 白名单一致
7. test_light_missing_all — 缺失任务处理
8. test_light_contract_frozen — 契约快照
## 任务 114:批量加载等价快照测试
**所属模块**:06 批量加载 **依赖**:105-108 **预估**:8-15 分钟
### 功能点要求
改造前后同数据:历史页、结果页、dashboard 输出字段完全一致(快照对比)。
### 测试用例(≥8)
1. test_history_snapshot_equiv — 历史快照一致
2. test_dashboard_snapshot_equiv — dashboard 一致
3. test_result_snapshot_equiv — 结果一致
4. test_pagination_equiv — 分页一致
5. test_snapshot_reproducible — 可重复
6. test_snapshot_diff_fails — 篡改即失败
7. test_snapshot_covers_all — 覆盖三页
8. test_snapshot_regression_guard — 全量回归门禁
## 任务 115:高频查询 EXPLAIN 索引审计
**所属模块**:06 批量加载 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
对高频查询(history/progress/dashboard)逐条 EXPLAIN;产出索引迁移清单(表/列/类型/收益/风险);不做 DDL。
### 测试用例(≥8)
1. test_explain_history_plan — history 执行计划记录
2. test_explain_progress_plan — progress 计划
3. test_explain_dashboard_plan — dashboard 计划
4. test_full_scan_detected — 全表扫描标记
5. test_index_candidates_listed — 候选索引清单
6. test_plan_documented — 审计文档产出
7. test_plan_repeatable — 可重复执行
8. test_no_ddl_this_task — 本任务无 DDL
## 任务 116:索引迁移 V{N+1}
**所属模块**:06 批量加载 **依赖**:115 **预估**:8-15 分钟
### 功能点要求
按审计清单追加 `db/V{N+1}__*.sql`(只追加不改历史);包含验证 SQL;标注锁表风险与窗口。
### 测试用例(≥8)
1. test_migration_file_exists — 迁移文件存在
2. test_migration_version_sequential — 版本号续接
3. test_migration_validated — 验证 SQL 通过(副本库)
4. test_migration_index_created — 索引生效
5. test_explain_improved — 执行计划改善
6. test_migration_no_alter_legacy — 不改历史迁移
7. test_migration_rollback_doc — 回滚步骤记录
8. test_migration_backward_safe — 旧数据兼容
## 任务 117:progress/light user_id 权限过滤
**所属模块**:06 批量加载 **依赖**:109 **预估**:8-15 分钟
### 功能点要求
user_id 传入时仅返回该用户任务;未传时按 taskId 反查;越权任务进 missingTaskIds(不泄露)。
### 测试用例(≥8)
1. test_light_user_filter — 用户过滤
2. test_light_no_user_reverse — 无 user 反查
3. test_light_other_user_hidden — 他人任务隐藏
4. test_light_missing_on_unauthorized — 越权进 missing
5. test_light_user_null — 全空 userId
6. test_light_admin_scope — 管理范围(按现状)
7. test_light_user_consistent — 与旧端点一致
8. test_light_no_leak — 响应不含他人数据
## 任务 118:前端 getModuleProgressLight 适配
**所属模块**:06 批量加载 **依赖**:109,44 **预估**:8-15 分钟
### 功能点要求
java-modules.ts 新增 `getModuleProgressLight(module, taskIds)` 调 light 端点;返回结构归一为现有 progress 类型;页面可渐进切换。
### 测试用例(≥8)
1. test_light_url_module — 模块路径正确
2. test_light_payload — taskIds body
3. test_light_response_shape — 归一结构
4. test_light_fallback_flag — 可开关
5. test_light_missing_ids — missingTaskIds 映射
6. test_light_timeout — 10s 超时
7. test_light_type_compat — 与旧类型兼容
8. test_light_snapshot — 快照
## 任务 119:前端 dashboard/history/progress 分离调用测试
**所属模块**:06 批量加载 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
前端页面:dashboard 只调统计、history 只调摘要、progress 只调轻量;首次打开不加载全部明细;断言请求路径分离。
### 测试用例(≥8)
1. test_page_dashboard_only_stats — 只调统计
2. test_page_history_only_summary — 只调摘要
3. test_page_progress_only_light — 只调进度
4. test_page_no_full_detail_on_load — 首开不拉明细
5. test_page_items_on_open — 打开明细才请求
6. test_page_result_on_demand — 结果按需
7. test_page_request_count_bounded — 请求数有界
8. test_page_snapshot — 请求快照
## 任务 120:大页数据性能回归
**所属模块**:06 批量加载 **依赖**:105-108 **预估**:8-15 分钟
### 功能点要求
500 任务级数据:history/dashboard/progress 响应时间上界(基准线);不劣于改造前。
### 测试用例(≥8)
1. test_perf_history_500 — 历史耗时
2. test_perf_dashboard_500 — dashboard 耗时
3. test_perf_progress_200 — 200 任务进度
4. test_perf_light_200 — light 更快
5. test_perf_query_count — 查询次数上界
6. test_perf_no_regression — 与基线对比
7. test_perf_memory_bounded — 内存有界
8. test_perf_report — 结果记录
## 任务 121:N+1 扫描审计
**所属模块**:06 批量加载 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
对 modules 下 Service 扫描逐条 selectById/selectOne 循环模式;产出 N+1 清单(位置/对象/影响);不做修改。
### 测试用例(≥8)
1. test_scan_select_in_loop — 识别循环内单查
2. test_scan_output_listed — 清单产出
3. test_scan_priority — 按影响排序
4. test_scan_module_coverage — 覆盖主要模块
5. test_scan_false_positive_checked — 排除误报(已批量)
6. test_scan_repeatable — 可重复
7. test_scan_documented — 文档产出
8. test_scan_no_edit — 本任务不改代码
## 任务 122:N+1 批量化修复
**所属模块**:06 批量加载 **依赖**:121 **预估**:8-15 分钟
### 功能点要求
按清单修复高影响 N+1(IN 查询 + Map 装配);行为不变;快照对比验证。
### 测试用例(≥8)
1. test_fix_in_query — 改 IN 查询
2. test_fix_map_assembly — Map 装配
3. test_fix_behavior_same — 行为一致
4. test_fix_single_row — 单行兼容
5. test_fix_empty — 空兼容
6. test_fix_query_count_reduced — 查询次数下降
7. test_fix_snapshot — 输出快照
8. test_fix_no_side_effect — 无副作用
## 任务 123:06 全量回归
**所属模块**:06 批量加载 **依赖**:105-122 **预估**:8-15 分钟
### 功能点要求
06 全部任务产出物 + 既有测试全绿;light 契约快照冻结;无行为回退。
### 测试用例(≥8)
1-8:全部新测试绿、既有回归绿、light 契约快照、旧端点可用、索引迁移就绪、前端适配编译、性能基线、git diff 范围
### 验证方法
`mvn test` 全量 + `cd frontend-vue && npm run build` + `npx vitest run`。
@@ -1,250 +0,0 @@
# 07-plan — 保守缩短事务边界
> 对应 `docs/specs/07-transaction-boundary.md`。硬约束:Python /result 成功确认时机、done=true 封口、状态成功时机、回滚语义全部不变。
> 技术栈:Java 21 + Spring Transaction。
## 任务 124:@Transactional 方法审计清单
**所属模块**:07 事务 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
扫描 modules 下全部 @Transactional 方法,产出审计清单:方法/事务内代码段分类(必须事务内:落库/状态/锁;可移出:纯计算/DTO 组装/日志/清理);文档产出,不改代码。
### 测试用例(≥8)
1. test_audit_covers_all_modules — 覆盖全部业务模块
2. test_audit_classification — 分类完整(必须/可移出)
3. test_audit_result_endpoints — /result 方法都在清单
4. test_audit_python_facing — Python 回调相关标记
5. test_audit_priority_order — 按收益排序
6. test_audit_no_code_change — 本任务零代码变更
7. test_audit_documented — 文档产出
8. test_audit_repeatable — 可重复执行
### TDD 流程
1. 写审计脚本/测试(断言清单文件存在且字段齐全)→ RED
2. 产出清单 → GREEN
3. 文档校验
## 任务 125:similarasin 纯计算移出事务
**所属模块**:07 事务 **依赖**:124 **预估**:8-15 分钟
### 功能点要求
similarasin 的 /result 提交事务内纯计算段(分组/百分比/校验)抽为无事务方法,在写库前调用;输出与现状一致。
### 测试用例(≥8)
1. test_pure_compute_outside_tx — 计算在事务外
2. test_compute_result_same — 结果一致
3. test_tx_persistence_kept — 落库仍在事务内
4. test_failure_rollback — 落库失败回滚(计算无副作用)
5. test_compute_idempotent — 计算幂等
6. test_compute_repeat_safe — 重复调用安全
7. test_no_tx_annotation_moved — 移动的方法无事务注解
8. test_behavior_snapshot — 快照一致
### TDD 流程
1. 测试断言事务边界(TransactionSynchronization 观察)→ RED
2. 重构 → GREEN
3. `mvn test -Dtest=SimilarAsinTaskServiceTest` 通过
## 任务 126:similarasin DTO 组装移出写事务
**所属模块**:07 事务 **依赖**:124 **预估**:8-15 分钟
### 功能点要求
结果回传的 DTO/VO 组装移到事务提交后(afterCompletion 或事务外);不影响落库字段。
### 测试用例(≥8)
1. test_dto_assembly_after_tx — 组装在事务后
2. test_assembled_fields_same — 字段一致
3. test_tx_commit_then_assembly — 先提交后组装
4. test_rollback_no_assembly — 回滚不组装
5. test_assembly_error_safe — 组装错误不影响事务
6. test_response_built_ok — 响应正常构造
7. test_assembly_no_db_read — 组装不读库
8. test_snapshot_same — 快照一致
## 任务 127:similarasin 临时文件清理挂 afterCommit
**所属模块**:07 事务 **依赖**:124 **预估**:8-15 分钟
### 功能点要求
事务完成后的临时文件清理改挂 TransactionSynchronization.afterCommit;回滚不清理(文件保留);清理异常不阻断。
### 测试用例(≥8)
1. test_cleanup_after_commit — 提交后清理
2. test_cleanup_no_rollback — 回滚不清理
3. test_cleanup_error_swallowed — 异常吞掉
4. test_cleanup_order — 在提交后
5. test_cleanup_retryable — 失败可重试
6. test_cleanup_tx_done — 事务状态已结束
7. test_cleanup_idempotent — 幂等
8. test_cleanup_integration — 全链路
## 任务 128:appearancepatent 事务收缩
**所属模块**:07 事务 **依赖**:124 **预估**:8-15 分钟
同 125-127 模式(注意双事务路径:persistSubmittedChunk + completeSubmittedChunk 两段不变)。
### 测试用例(≥8)
1-8:计算移外、双事务路径不变、落库保留、回滚一致、清理时机、幂等、快照一致、集成。
## 任务 129:shopdatacrawl 事务收缩
**所属模块**:07 事务 **依赖**:124 **预估**:8-15 分钟
同 125 模式。
### 测试用例(≥8)
同 125(shopdatacrawl 特有:items 分页写入路径)。
## 任务 130:publish 事务收缩
**所属模块**:07 事务 **依赖**:124 **预估**:8-15 分钟
同 125 模式(publish 特有:RustFS 分片合并路径不动)。
### 测试用例(≥8)
同 125(publish:分片合并后落库仍在事务内)。
## 任务 131:collectdata 事务收缩
**所属模块**:07 事务 **依赖**:124 **预估**:8-15 分钟
同 125 模式。
### 测试用例(≥8)
同 125。
## 任务 132:/result 成功确认时机不变测试
**所属模块**:07 事务 **依赖**:125-131 **预估**:8-15 分钟
### 功能点要求
/result 返回 HTTP 200 + success=true 在结果分片可靠落库**之后**;未落库前不返回成功;事务失败返回错误。
### 测试用例(≥8)
1. test_result_200_after_persist — 落库后 200
2. test_result_success_true — success=true
3. test_result_persist_fail_no_200 — 落库失败不 200
4. test_result_timing_order — 顺序断言
5. test_result_retry_after_failure — 失败后重试
6. test_result_chunk_then_ack — 分片先落库
7. test_result_ack_then_response — 响应在 ACK 后
8. test_result_contract_frozen — 契约快照
## 任务 133:回滚语义不变测试
**所属模块**:07 事务 **依赖**:125-131 **预估**:8-15 分钟
### 功能点要求
落库异常 → 完整回滚(任务状态、结果、payload 不变);纯计算无副作用;重试安全。
### 测试用例(≥8)
1. test_rollback_full — 完整回滚
2. test_rollback_status_unchanged — 状态不变
3. test_rollback_payload — payload 不变
4. test_rollback_retry — 重试安全
5. test_rollback_compute_noop — 计算无副作用
6. test_rollback_error_raised — 异常抛出
7. test_rollback_partial_write — 部分写入也回滚
8. test_rollback_consistency — 与改造前一致
## 任务 134:done=true 封口时机不变测试
**所属模块**:07 事务 **依赖**:125-131 **预估**:8-15 分钟
### 功能点要求
done=true 最后一批:强制处理未满批数据、生成结果文件的时机不变;封口语义不变。
### 测试用例(≥8)
1. test_done_finalizes — 封口触发
2. test_done_after_last_chunk — 最后一批后
3. test_done_processes_remainder — 处理剩余
4. test_done_generates_file — 生成结果
5. test_done_idempotent — 重复 done 安全
6. test_done_timing — 时机断言
7. test_done_no_double — 不重复生成
8. test_done_contract — 契约快照
## 任务 135:任务状态成功时机不变测试
**所属模块**:07 事务 **依赖**:125-131 **预估**:8-15 分钟
### 功能点要求
任务状态变 SUCCESS 的时机(结果文件生成完成判断)不变;fileReady/downloadUrl 含义不变。
### 测试用例(≥8)
1. test_success_timing — 成功时机
2. test_success_after_file — 文件生成后
3. test_file_ready_semantics — fileReady 语义
4. test_download_url_semantics — downloadUrl 语义
5. test_success_no_file — 无文件不成功
6. test_success_state_transition — 状态迁移
7. test_success_observable — 前端可观测
8. test_success_contract — 契约快照
## 任务 136:事务外清理异常不阻断
**所属模块**:07 事务 **依赖**:127 **预估**:8-15 分钟
### 功能点要求
afterCommit 清理抛异常:记录日志+指标,不影响响应;不重试成循环。
### 测试用例(≥8)
1. test_cleanup_error_logged — 日志记录
2. test_cleanup_error_response_ok — 响应不受影响
3. test_cleanup_error_no_retry_loop — 不循环
4. test_cleanup_error_tx_committed — 事务已提交
5. test_cleanup_error_metric — 指标记录
6. test_cleanup_error_next_time — 下次仍可清理
7. test_cleanup_error_partial — 部分清理成功
8. test_cleanup_error_integration — 集成
## 任务 137:重复提交幂等测试
**所属模块**:07 事务 **依赖**:132-135 **预估**:8-15 分钟
### 功能点要求
同 submissionId 重复提交 /result:幂等接受(成功返回,不重复落库);不同内容冲突拒绝。
### 测试用例(≥8)
1. test_duplicate_same_id_ok — 同 id 幂等
2. test_duplicate_no_double_persist — 不重复落库
3. test_duplicate_success_true — 返回成功
4. test_duplicate_diff_content_reject — 内容不同拒绝
5. test_duplicate_chunk_conflict — chunk 冲突
6. test_duplicate_after_done — 封口后重复
7. test_duplicate_many — 多次重复
8. test_duplicate_contract — 契约快照
## 任务 138:事务时长性能对比基准
**所属模块**:07 事务 **依赖**:125-131 **预估**:8-15 分钟
### 功能点要求
改造前后 /result 事务耗时基准对比(纯计算移出后的时间下降);记录基准数据。
### 测试用例(≥8)
1. test_tx_duration_recorded — 耗时记录
2. test_tx_duration_before_after — 前后对比
3. test_tx_improved_or_equal — 不劣化
4. test_tx_measure_repeatable — 可重复
5. test_tx_load_200_chunks — 200 分片负载
6. test_tx_no_regression — 无回退
7. test_tx_benchmark_documented — 基准文档
8. test_tx_bound_reasonable — 上界合理
## 任务 139:07 全量回归
**所属模块**:07 事务 **依赖**:132-138 **预估**:8-15 分钟
### 功能点要求
07 全部契约测试(132-135)+ 各模块事务重构测试全绿;`mvn test` 无回归。
### 测试用例(≥8)
1-8:契约 4 项全绿、幂等全绿、回滚全绿、各模块重构测试、全量单测、package、契约快照、git diff 范围
### 验证方法
`mvn test` + `mvn clean package -DskipTests`。
@@ -1,158 +0,0 @@
# 08-plan — 结果文件阶段字段契约固化
> 对应 `docs/specs/08-result-file-phase-and-download.md`。**审计结论:Java 13 模块字段已实现、前端已消费,无代码改动需求。**
> 本 plan 将现状固化为契约测试,防止未来回归;不新增业务字段。
> 技术栈:Java 21 + JUnit5 + Vitest(前端)。
## 任务 140:13 模块 file 字段契约快照测试
**所属模块**:08 结果阶段 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
对 13 个业务模块(similarasin/appearancepatent/shopdatacrawl/queryasin/withdraw/patroldelete/shopmatch/productrisk/pricetrack/deletebrand/publish/collectdata/brand)的响应 VO 断言 file 阶段字段存在且类型正确(collectdata 除外:断言其自洽语义);旧字段(taskId/resultId/downloadUrl/status)仍在。
### 测试用例(≥8)
1. test_similar_has_file_fields — similarasin 字段齐全
2. test_appearance_has_file_fields
3. test_shopdatacrawl_has_file_fields
4. test_publish_has_file_fields — publish 文件级
5. test_collectdata_self_consistent — collectdata 无 file 字段(现状)
6. test_old_fields_present — 旧字段全在
7. test_file_field_types — 类型正确(boolean/string/integer)
8. test_contract_frozen_snapshot — JSON 快照冻结
### TDD 流程
1. 测试断言 VO 字段(反射/样例对象)→ 对现状应 GREEN(基线固化)
2. 若未来删除字段即 RED(回归保护)
3. `mvn test -Dtest=ResultFilePhaseContractTest` 通过
## 任务 141:similarasin file 进度合成逻辑单测
**所属模块**:08 结果阶段 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
attachFileProgress 三路径:Coze 阶段(cozeCompleted/pending>0)、Python 上传阶段(未完成)、snapshot 百分比(上传完成无 coze);fileReady=true 时 100%。
### 测试用例(≥8)
1. test_coze_progress_path — Coze 路径
2. test_python_upload_path — Python 上传路径
3. test_snapshot_percent_path — snapshot 路径
4. test_file_ready_100 — ready=100%
5. test_upload_not_complete_no_snapshot — 未完成且无快照
6. test_can_treat_completed — 可视为完成
7. test_task_not_running_skip — 非运行中跳过
8. test_percent_cap_99 — 未 ready 时 ≤99
### TDD 流程 / 验证方法
构造 FileResultEntity/TaskFileJobEntity/TaskProgressSnapshotEntity 组合断言输出(调用包可见/测试可见的 attachFileProgress 或经 toHistoryItem)。
## 任务 142:fileReady/fileStatus 语义测试
**所属模块**:08 结果阶段 **依赖**:140 **预估**:8-15 分钟
### 功能点要求
fileReady = resultFileUrl 非空;无 job 时 fileStatus = ready?SUCCESS:null;有 job 时 fileStatus = job.status;fileError = job.errorMessage。
### 测试用例(≥8)
1. test_ready_url_present — 有 URL ready=true
2. test_ready_url_blank — 空 URL ready=false
3. test_no_job_success_status — 无 job ready 时 SUCCESS
4. test_no_job_null_status — 无 job 未 ready null
5. test_job_status_mapped — job 状态映射
6. test_job_error_mapped — job 错误映射
7. test_ready_blank_whitespace — 空白字符串
8. test_semantics_frozen — 语义快照
## 任务 143:publish 文件级 file 状态测试
**所属模块**:08 结果阶段 **依赖**:140 **预估**:8-15 分钟
### 功能点要求
publish 的 file 状态是文件级(PublishResultVo.setFileReady(ready)/setFileStatus(file.status)),与其余模块 job 级不同;语义固化。
### 测试用例(≥8)
1. test_publish_file_ready — ready 设置
2. test_publish_file_status — 文件状态
3. test_publish_per_file — 按文件独立
4. test_publish_mixed_files — 多文件混合状态
5. test_publish_ready_all — 全 ready
6. test_publish_no_files — 无文件
7. test_publish_failed_file — 失败文件
8. test_publish_semantics_frozen — 语义快照
## 任务 144:前端 live progress 合并测试补强
**所属模块**:08 结果阶段 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
mergeHistoryItemPreservingLiveProgress:history 缺失 file 进度时保留 live progress;incoming 有进度时用 incoming;可下载时不保留。
### 测试用例(≥8)
1. test_merge_keeps_live_when_history_missing — 保留 live
2. test_merge_incoming_wins — incoming 优先
3. test_merge_no_keep_when_downloadable — 可下载不保留
4. test_merge_no_previous — 无 previous 返回 incoming
5. test_merge_partial_fields — 部分字段保留
6. test_merge_meaningful_progress — 有效进度值判断
7. test_merge_file_ready_flag — ready 标志保留
8. test_merge_idempotent — 幂等
### TDD 流程 / 验证方法
`npx vitest run`(扩展既有测试文件或新增)。
## 任务 145:前端可下载判定测试
**所属模块**:08 结果阶段 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
canDownload/fileReady/fileStatus 终态判定:fileReady=true 可下载;fileStatus=SUCCESS/FAILED 可下载(FAILED 可下载错误文件或展示错误);其余不可下载。
### 测试用例(≥8)
1. test_can_download_ready — ready 可下载
2. test_can_download_status_success — SUCCESS 可下载
3. test_can_download_status_failed — FAILED 展示错误
4. test_can_not_download_pending — PENDING 不可
5. test_can_not_download_null — null 不可
6. test_file_status_lowercase — 小写归一
7. test_ready_false_status_success — 组合判断
8. test_download_flow_no_result_resubmit — 下载失败不重提交
## 任务 146:collectdata 自洽行为测试
**所属模块**:08 结果阶段 **依赖**:140 **预估**:8-15 分钟
### 功能点要求
collectdata 前端用 success + downloadUrl 判定下载;后端不返回 file 字段;行为自洽(任务 SUCCESS 且有 URL 才可下载)。
### 测试用例(≥8)
1. test_collect_success_downloadable — SUCCESS+URL 可下载
2. test_collect_success_no_url — 无 URL 不可
3. test_collect_failed_no_download — 失败不可
4. test_collect_ready_download_url — URL 有效
5. test_collect_progress_display — 进度显示
6. test_collect_self_consistent_backend — 后端无 file 字段
7. test_collect_status_flow — 状态流
8. test_collect_contract_frozen — 快照
## 任务 147:downloadUrl 永不过期验证
**所属模块**:08 结果阶段 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
generateFreshDownloadUrl 行为:result/ 前缀走 download-endpoint;非 result/ 走公开端点;无签名(URL 无过期参数);bucket 前缀正确。
### 测试用例(≥8)
1. test_result_prefix_download_endpoint — result/ 走下载域名
2. test_other_prefix_public — 其他走公开
3. test_no_signed_params — 无签名参数
4. test_bucket_in_url — bucket 包含
5. test_blank_input_fallback — 空值回退
6. test_uri_encoding — 路径编码
7. test_scheme_https — https
8. test_url_stable_over_time — 时间无关(无过期)
### TDD 流程 / 验证方法
OssStorageService 单测(配置注入 mock endpoint)。
### 收尾验证(本模块)
`mvn test` 相关类 + `cd frontend-vue && npx vitest run` 全绿;08 spec §2/§3 清单与实际一致。
@@ -1,322 +0,0 @@
# 09-plan — 临时文件生命周期治理
> 对应 `docs/specs/09-temp-file-lifecycle.md`。第一阶段只巡检不自动删;路径安全是硬门槛。
> 技术栈:Java 21 + Spring Scheduling + JUnit5。
## 任务 148:临时目录配置盘点
**所属模块**:09 临时文件 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
盘点 TransientStorageProperties/StorageProperties/TransientPayloadStorageService 的临时目录配置(路径、前缀、保留期、现有清理逻辑);产出配置清单文档;不改代码。
### 测试用例(≥8)
1. test_config_listed — 配置项清单齐全
2. test_temp_root_defined — 临时根目录定义
3. test_retention_period — 保留期定义
4. test_payload_prefixes — payload 前缀
5. test_upload_dir — 上传目录
6. test_existing_cleanup_noted — 现有清理逻辑记录
7. test_doc_committed — 文档存在
8. test_no_code_change — 零代码变更
### TDD 流程
1. 断言清单文档存在且字段齐全 → RED
2. 产出文档 → GREEN
## 任务 149:创建/访问时间记录审计与补缺
**所属模块**:09 临时文件 **依赖**:148 **预估**:8-15 分钟
### 功能点要求
临时文件创建时间/大小/最后访问时间记录:现有实现缺最后访问时间则补(文件 mtime 或记录表);不改变文件语义。
### 测试用例(≥8)
1. test_creation_time_recorded — 创建时间
2. test_size_recorded — 大小
3. test_access_time_readable — 访问时间可读
4. test_access_time_fallback — mtime 回退
5. test_record_update — 访问更新
6. test_record_missing_grace — 缺记录容忍
7. test_record_no_io_error — IO 错误不阻断
8. test_record_consistency — 一致
## 任务 150:引用检查(清理前)
**所属模块**:09 临时文件 **依赖**:148 **预估**:8-15 分钟
### 功能点要求
清理前确认无任务引用:fileKey 被 task_file_job/file_result 引用则不清理;引用判定逻辑可测试。
### 测试用例(≥8)
1. test_referenced_kept — 被引用不清理
2. test_unreferenced_candidate — 无引用可清理
3. test_reference_by_job — job 引用
4. test_reference_by_result — result 引用
5. test_reference_unknown — 未知引用安全
6. test_check_no_side_effect — 检查无副作用
7. test_check_failure_keeps — 检查失败保守保留
8. test_check_batch — 批量检查
## 任务 151:路径安全校验
**所属模块**:09 临时文件 **依赖**:148 **预估**:8-15 分钟
### 功能点要求
删除前校验:路径规范化后 startsWith(临时根目录);穿越(../、绝对路径逃逸、符号链接)拒绝;非法路径不删除并记录。
### 测试用例(≥8)
1. test_inside_root_ok — 根内允许
2. test_traversal_rejected — ../ 拒绝
3. test_absolute_escape — 绝对路径逃逸拒绝
4. test_symlink_escape — 符号链接逃逸拒绝
5. test_normalize_before_check — 规范化后校验
6. test_relative_subdir — 子目录允许
7. test_sibling_rejected — 兄弟目录拒绝
8. test_illegal_logged — 非法路径记录
### TDD 流程
1. 测试(构造各种路径)→ RED
2. 实现校验 → GREEN
3. `mvn test -Dtest=TransientPathGuardTest` 通过
## 任务 152:清理失败吞异常记指标
**所属模块**:09 临时文件 **依赖**:150,151 **预估**:8-15 分钟
### 功能点要求
清理失败:记录日志+指标(清理失败计数),不抛异常、不阻断主流程;不自动重试成循环。
### 测试用例(≥8)
1. test_failure_logged — 日志
2. test_failure_metric — 指标
3. test_failure_no_throw — 不抛出
4. test_failure_flow_continues — 主流程继续
5. test_failure_no_retry_loop — 不循环
6. test_failure_next_round — 下轮可再试
7. test_failure_partial — 部分失败处理
8. test_failure_isolation — 隔离其他文件
## 任务 153:fileKey 兜底查找
**所属模块**:09 临时文件 **依赖**:148 **预估**:8-15 分钟
### 功能点要求
进程重启后 fileKey 兜底:上传记录持久化或重启后按 fileKey 重建索引;找不到时明确失败而非静默。
### 测试用例(≥8)
1. test_file_key_found — 找到
2. test_file_key_after_restart — 重启后找到
3. test_file_key_missing — 缺失明确失败
4. test_file_key_null — null 安全
5. test_file_key_cleanup — 清理后不可找
6. test_file_key_record_persist — 记录持久化
7. test_file_key_rebuild — 索引重建
8. test_file_key_semantics_frozen — 语义不变
## 任务 154:磁盘容量告警
**所属模块**:09 临时文件 **依赖**:152 **预估**:8-15 分钟
### 功能点要求
临时目录容量超阈值:记录告警日志(当前容量/阈值);无监控栈时仅日志输出;不阻塞业务。
### 测试用例(≥8)
1. test_warning_threshold — 阈值判断
2. test_warning_logged — 告警日志
3. test_under_threshold_silent — 未超不告警
4. test_warning_repeat_limited — 告警频率限制
5. test_usage_measured — 容量测量
6. test_usage_zero — 空目录
7. test_measure_error_grace — 测量失败容忍
8. test_warning_no_block — 不阻塞
## 任务 155:孤立文件巡检报表
**所属模块**:09 临时文件 **依赖**:150 **预估**:8-15 分钟
### 功能点要求
只读巡检:临时目录中无任何引用/超过保留期的文件清单输出到报表(日志或报表文件);不删除。
### 测试用例(≥8)
1. test_orphan_detected — 孤立文件检出
2. test_referenced_not_reported — 被引用不报
3. test_report_output — 报表输出
4. test_read_only_no_delete — 只读不删
5. test_report_batch — 批量
6. test_report_empty — 无孤立空报表
7. test_report_rerun_safe — 可重复
8. test_report_details — 详情(路径/大小/时间)
## 任务 156:孤立 Job 巡检报表
**所属模块**:09 临时文件 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
只读巡检:task_file_job 无对应 task/result 的孤儿 Job 清单;输出报表;不修改状态。
### 测试用例(≥8)
1. test_orphan_job_detected — 检出
2. test_valid_job_not_reported — 正常不报
3. test_report_output — 输出
4. test_read_only — 不修改
5. test_job_retry_orphan — 重试耗尽孤儿
6. test_report_empty — 空
7. test_report_details — 详情
8. test_rerun_safe — 可重复
## 任务 157:任务存在结果缺失巡检
**所属模块**:09 临时文件 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
只读巡检:任务存在但结果缺失(SUCCESS 任务无 file_result)清单。
### 测试用例(≥8)
1. test_missing_result_detected — 检出
2. test_with_result_not_reported — 有结果不报
3. test_success_no_result — SUCCESS 无结果
4. test_running_ignored — 运行中忽略
5. test_report_empty
6. test_read_only
7. test_details
8. test_rerun_safe
## 任务 158:结果存在文件缺失巡检
**所属模块**:09 临时文件 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
只读巡检:file_result 的 resultFileUrl 对应文件在 OSS/本地不存在清单。
### 测试用例(≥8)
1. test_file_missing_detected
2. test_file_exists_ok
3. test_blank_url_handled — 空 URL
4. test_oss_check — OSS 校验(mock)
5. test_report_empty
6. test_read_only
7. test_details
8. test_rerun_safe
## 任务 159:已完成任务活跃 Job 巡检
**所属模块**:09 临时文件 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
只读巡检:任务已终态(SUCCESS/FAILED)但仍有活跃(RUNNING/PENDING)Job 清单。
### 测试用例(≥8)
1. test_active_job_after_terminal — 检出
2. test_terminal_no_job_ok
3. test_job_active_task_running_ok — 运行中任务正常
4. test_stuck_job_reported — 卡死 Job
5. test_report_empty
6. test_read_only
7. test_details
8. test_rerun_safe
## 任务 160:超保留期仍被引用巡检
**所属模块**:09 临时文件 **依赖**:150 **预估**:8-15 分钟
### 功能点要求
只读巡检:临时文件超保留期但仍有引用清单(供人工处理)。
### 测试用例(≥8)
1. test_over_retention_referenced — 检出
2. test_in_retention_ok
3. test_over_retention_unreferenced — 无引用(另表)
4. test_boundary_retention — 边界时间
5. test_report_empty
6. test_read_only
7. test_details
8. test_rerun_safe
## 任务 161:巡检任务开关(默认 disabled)
**所属模块**:09 临时文件 **依赖**:155-160 **预估**:8-15 分钟
### 功能点要求
全部巡检任务由配置开关控制(默认 disabled);启用后按调度间隔执行;双实例不重复输出(owner 或随机)。
### 测试用例(≥8)
1. test_disabled_by_default — 默认关
2. test_enabled_runs — 启用执行
3. test_schedule_interval — 间隔配置
4. test_dual_instance_no_dup — 双实例不重复
5. test_run_error_grace — 异常不阻断
6. test_each_report_independent — 各报表独立
7. test_config_override — 覆盖生效
8. test_enabled_no_crash — 启用稳定
## 任务 162:路径穿越测试
**所属模块**:09 临时文件 **依赖**:151 **预估**:8-15 分钟
### 功能点要求
穿越输入矩阵:`../`、`..\\`、绝对路径、URL 编码 `%2e%2e`、Unicode 全角点、混合分隔符——全部拒绝。
### 测试用例(≥8)
1. test_dotdot_slash — ../
2. test_dotdot_backslash — ..\
3. test_encoded_dotdot — %2e%2e
4. test_fullwidth_dot — 全角点
5. test_abs_win_path — C:\ 形式
6. test_abs_unix_path — /etc 形式
7. test_mixed_separator — 混合分隔符
8. test_null_byte — 空字节
## 任务 163:引用中文件不清测试
**所属模块**:09 临时文件 **依赖**:150 **预估**:8-15 分钟
### 功能点要求
被 job/result 引用的文件:清理流程跳过;仅未引用文件被清理(清理流程本身在后续批次实现时,本任务先固化引用检查)。
### 测试用例(≥8)
1. test_job_referenced_skip — job 引用跳过
2. test_result_referenced_skip — result 引用跳过
3. test_unreferenced_passes — 未引用通过
4. test_multi_reference — 多引用
5. test_check_after_delete_history — 删历史后解除引用
6. test_check_batch_mixed — 混合批次
7. test_check_null_safe
8. test_check_idempotent
## 任务 164:清理失败不阻断测试
**所属模块**:09 临时文件 **依赖**:152 **预估**:8-15 分钟
### 功能点要求
清理一个文件失败不影响其他文件清理;主业务不受影响;错误可见(日志/指标)。
### 测试用例(≥8)
1. test_one_fail_others_succeed — 单失败其余成功
2. test_failure_visible — 错误可见
3. test_no_throw_up — 不上抛
4. test_retry_next_round — 下轮重试
5. test_partial_result_reported — 部分结果报告
6. test_metric_recorded — 指标
7. test_flow_continues — 流程继续
8. test_no_cascading — 无级联
## 任务 165:巡检只读测试
**所属模块**:09 临时文件 **依赖**:155-161 **预估**:8-15 分钟
### 功能点要求
全部巡检运行后:零删除、零状态修改、零写库(只读);可重复执行。
### 测试用例(≥8)
1. test_no_delete — 零删除
2. test_no_state_change — 状态不变
3. test_no_db_write — 无写库
4. test_read_repeatable — 重复一致
5. test_isolated_reports — 报表隔离
6. test_read_only_assert — 只读断言
7. test_no_side_effects — 无副作用
8. test_full_suite_run — 全巡检套件
### 收尾验证(本模块)
`mvn test` 相关类全绿;09 spec §4 不变要求逐项核对(fileKey 语义、上传协议不变)。
@@ -1,184 +0,0 @@
# 10-plan — 外部 HTTP 客户端配置治理
> 对应 `docs/specs/10-http-client-governance.md`。现状:HttpClientPool 已统一(Coze/品牌/紫鸟共用连接池)。
> 技术栈:Java 21 + JDK HttpClient + RestClient。
## 任务 166:各客户端契约表盘点
**所属模块**:10 HTTP 客户端 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
盘点 Coze/OSS/RustFS/图片下载/紫鸟各客户端现状:connect/read/write/call timeout、重试、幂等性;产出契约表文档;标注 JDK HttpClient 平台限制(无独立 write timeout、连接池上限不可配置);不改代码。
### 测试用例(≥8)
1. test_contract_table_all_clients — 全客户端
2. test_timeouts_listed — 超时现状
3. test_retry_listed — 重试现状
4. test_idempotency_listed — 幂等性
5. test_jdk_limits_noted — 平台限制
6. test_doc_committed — 文档存在
7. test_no_code_change — 零代码
8. test_repeatable — 可复查
### TDD 流程
1. 断言文档存在 → RED
2. 产出契约表 → GREEN
## 任务 167:aiimage.http-client.* 配置命名空间
**所属模块**:10 HTTP 客户端 **依赖**:166 **预估**:8-15 分钟
### 功能点要求
application.yml 新增 `aiimage.http-client.*` 命名空间(connect-timeout/read-timeout/call-timeout/retry 默认值);默认值与现状一致;配置类绑定校验。
### 测试用例(≥8)
1. test_config_namespace_exists — 命名空间
2. test_defaults_match_current — 默认一致
3. test_connect_timeout_bound — 合法值
4. test_read_timeout_bound
5. test_retry_count_bound
6. test_invalid_values_clamped — 非法钳制
7. test_config_class_binding — 绑定类
8. test_env_override — env 覆盖
## 任务 168:Coze 客户端配置接入
**所属模块**:10 HTTP 客户端 **依赖**:167 **预估**:8-15 分钟
### 功能点要求
Coze 客户端从配置读取超时/重试(现为硬编码或独立配置);行为不变(默认值等同现状)。
### 测试用例(≥8)
1. test_coze_timeout_from_config — 配置生效
2. test_coze_default_kept — 默认不变
3. test_coze_override — 覆盖
4. test_coze_call_timeout — 总时长
5. test_coze_retry_config — 重试配置
6. test_coze_pool_shared — 共用连接池
7. test_coze_idempotent_post — 幂等标注
8. test_coze_behavior_same — 行为一致
## 任务 169:品牌检查客户端配置接入
**所属模块**:10 HTTP 客户端 **依赖**:167 **预估**:8-15 分钟
同 168 模式。
### 测试用例(≥8)
同 168(品牌检查)。
## 任务 170:紫鸟客户端配置接入
**所属模块**:10 HTTP 客户端 **依赖**:167 **预估**:8-15 分钟
同 168 模式。
### 测试用例(≥8)
同 168(紫鸟)。
## 任务 171:图片下载客户端配置接入
**所属模块**:10 HTTP 客户端 **依赖**:167 **预估**:8-15 分钟
同 168 模式(图片下载特有:大响应流式读取)。
### 测试用例(≥8)
1-8:配置生效、默认、覆盖、call timeout、重试、池共享、幂等、流式读取。
## 任务 172:幂等重试守卫
**所属模块**:10 HTTP 客户端 **依赖**:167 **预估**:8-15 分钟
### 功能点要求
统一重试守卫:仅幂等请求(GET/HEAD)自动重试;非幂等(POST/PUT)不自动重试;重试次数与退避从配置;防重试风暴。
### 测试用例(≥8)
1. test_get_retried — GET 重试
2. test_post_not_retried — POST 不重试
3. test_retry_count_limited — 次数限制
4. test_retry_backoff — 退避
5. test_idempotent_header_override — 显式幂等标记
6. test_retry_success_after_fail — 重试成功
7. test_retry_exhausted_fail — 耗尽失败
8. test_no_retry_storm — 不风暴
## 任务 173:超时生效测试
**所属模块**:10 HTTP 客户端 **依赖**:168-171 **预估**:8-15 分钟
### 功能点要求
mock 慢端点(>read timeout):请求在超时内失败;connect timeout 生效;call timeout 生效(RestClient 层)。
### 测试用例(≥8)
1. test_read_timeout_fires — 读超时
2. test_read_timeout_duration — 时长断言
3. test_connect_timeout_fires — 连接超时
4. test_connect_timeout_duration
5. test_call_timeout_fires — 总时长
6. test_fast_response_ok — 快响应正常
7. test_timeout_error_type — 错误类型
8. test_timeout_after_config — 配置生效
## 任务 174:连接复用测试
**所属模块**:10 HTTP 客户端 **依赖**:168-171 **预估**:8-15 分钟
### 功能点要求
连续 N 请求复用底层连接(共享 HttpClient);不同客户端共用连接池;连接不复用时暴露。
### 测试用例(≥8)
1. test_connection_reused — 复用
2. test_shared_across_clients — 跨客户端共用
3. test_sequential_requests — 顺序复用
4. test_keep_alive_header — keep-alive
5. test_no_new_connection_burst — 突发不建新连
6. test_pool_singleton — 单例
7. test_concurrent_reuse — 并发复用
8. test_connection_stats — 连接统计
## 任务 175:Python 回调超时不变确认
**所属模块**:10 HTTP 客户端 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
只读确认:Java 侧外部客户端改动不影响 Python 回调请求的超时与重试约定(Python 侧 requests 调用不动);写断言测试固化 Python 回调契约不受 Java 配置影响。
### 测试用例(≥8)
1. test_python_callback_contract — 回调契约
2. test_no_java_config_affects_python — 不受影响
3. test_python_timeout_doc — 文档一致
4. test_python_retry_doc
5. test_python_headers — 头一致
6. test_python_success_detection — 成功判定
7. test_python_contract_frozen — 快照
8. test_no_code_change_python — Python 零改动
## 任务 176:重试计数与日志字段
**所属模块**:10 HTTP 客户端 **依赖**:172 **预估**:8-15 分钟
### 功能点要求
重试时记录日志(客户端/URL/尝试次数/耗时);重试计数指标;不记录敏感信息。
### 测试用例(≥8)
1. test_retry_logged — 日志
2. test_retry_attempt_field — 尝试次数
3. test_retry_duration — 耗时
4. test_retry_metric — 指标
5. test_no_token_in_log — 无敏感信息
6. test_success_no_retry_log — 成功不记
7. test_log_level — 日志级别
8. test_final_failure_logged — 最终失败
## 任务 177:10 全量回归
**所属模块**:10 HTTP 客户端 **依赖**:168-176 **预估**:8-15 分钟
### 功能点要求
全部客户端配置改造后:现有测试全绿;外部服务 mock 集成测试通过;行为与默认配置下现状一致。
### 测试用例(≥8)
1-8:各客户端测试绿、HttpClientPool 既有测试绿、配置绑定测试、超时测试、复用测试、幂等守卫、日志脱敏、全量单测
### 验证方法
`mvn test` 全量 + `mvn clean package -DskipTests`。
@@ -1,245 +0,0 @@
# 11-plan — 可观测性:指标定义与日志字段规范
> 对应 `docs/specs/11-observability.md`。决策:指标名与日志字段规范先行落地;不引入新监控组件(Micrometer 若已依赖则用,未依赖则手动计数器+日志)。
> 技术栈:Java 21 + Slf4j +(可选 Micrometer)。
## 任务 178:日志字段规范落地
**所属模块**:11 可观测性 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
业务日志统一携带结构化字段:traceId/taskId/moduleType/stage/submissionId/chunkIndex/chunkTotal/jobId/result/errorType;缺失字段用占位;不删现有日志。
### 测试用例(≥8)
1. test_worker_log_has_task_id — Worker 日志含 taskId
2. test_worker_log_has_module_type
3. test_worker_log_has_stage
4. test_result_log_fields — /result 日志字段
5. test_heartbeat_log_fields
6. test_missing_field_placeholder — 缺字段占位
7. test_log_field_names_frozen — 字段名快照
8. test_no_log_content_break — 日志内容不破坏
## 任务 179:禁止记录清单审计
**所属模块**:11 可观测性 **依赖**:178 **预估**:8-15 分钟
### 功能点要求
审计日志代码:Token/Cookie/完整请求体/文件二进制/用户凭据/敏感 API Key 不入日志;发现问题修正。
### 测试用例(≥8)
1. test_no_token_logged — 无 Token
2. test_no_cookie_logged — 无 Cookie
3. test_no_full_body_logged — 无完整 body
4. test_no_binary_logged — 无二进制
5. test_no_credential_logged — 无凭据
6. test_no_api_key_logged — 无 API Key
7. test_allowed_fields_kept — 允许字段保留
8. test_audit_script — 审计脚本可重复
## 任务 180:Worker 日志字段对齐
**所属模块**:11 可观测性 **依赖**:73 **预估**:8-15 分钟
### 功能点要求
TaskResultFileJobWorker(04 改造后)日志字段与规范对齐:jobId/taskId/moduleType/stage/errorType;现有 [task-file-job] 前缀保留。
### 测试用例(≥8)
1. test_dispatch_log_fields — dispatch 日志
2. test_success_log_fields
3. test_failure_log_fields
4. test_retry_log_fields
5. test_heartbeat_log_fields
6. test_stuck_log_fields
7. test_field_names_consistent — 与规范一致
8. test_no_sensitive — 无敏感
## 任务 181:task.created/running 指标埋点
**所属模块**:11 可观测性 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
任务创建(created 计数)与运行中(running gauge)指标;带 moduleType/instanceId 标签;无监控栈时输出日志记录。
### 测试用例(≥8)
1. test_created_incremented — 创建计数
2. test_running_gauge — 运行 gauge
3. test_module_label — 标签
4. test_instance_label — instanceId 标签
5. test_created_module_specific — 分模块
6. test_counter_persistent — 计数正确性
7. test_gauge_update — 更新
8. test_metric_name_frozen — 名称快照
## 任务 182:task.success/failed/cancelled 指标埋点
**所属模块**:11 可观测性 **依赖**:181 **预估**:8-15 分钟
### 功能点要求
终态计数:success/failed/cancelled 各模块独立计数;与状态迁移一致。
### 测试用例(≥8)
1. test_success_counted
2. test_failed_counted
3. test_cancelled_counted
4. test_module_split — 分模块
5. test_no_double_count — 不重复计
6. test_terminal_once — 只计一次
7. test_failed_then_success — 状态反转不重计
8. test_names_frozen
## 任务 183:task.duration 指标埋点
**所属模块**:11 可观测性 **依赖**:182 **预估**:8-15 分钟
### 功能点要求
任务耗时(开始→终态)记录;直方图或耗时日志;分模块。
### 测试用例(≥8)
1. test_duration_recorded — 记录
2. test_duration_positive — 正值
3. test_module_split
4. test_short_task — 短任务
5. test_long_task — 长任务
6. test_duration_bound — 上界
7. test_duration_zero_guard — 零保护
8. test_name_frozen
## 任务 184:task.heartbeat.age 指标埋点
**所属模块**:11 可观测性 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
心跳年龄 gauge:任务最后心跳距今时间;超阈值可观测(日志告警)。
### 测试用例(≥8)
1. test_age_computed — 年龄计算
2. test_age_fresh — 新鲜
3. test_age_stale — 陈旧
4. test_age_threshold_warn — 阈值告警
5. test_no_heartbeat — 无心跳处理
6. test_age_zero — 刚心跳
7. test_age_clock_negative — 时钟负保护
8. test_name_frozen
## 任务 185:file-job.* 指标埋点
**所属模块**:11 可观测性 **依赖**:73 **预估**:8-15 分钟
### 功能点要求
TaskFileJobWorker 指标:pending/running/success/failed/duration/retry;分 moduleType/instanceId。
### 测试用例(≥8)
1. test_pending_counted
2. test_running_counted
3. test_success_counted
4. test_failed_counted
5. test_duration_recorded
6. test_retry_counted
7. test_module_instance_labels
8. test_names_frozen
## 任务 186:上传耗时/大小指标埋点
**所属模块**:11 可观测性 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
文件上传:耗时、大小、成功率指标;分 moduleType。
### 测试用例(≥8)
1. test_upload_duration
2. test_upload_size
3. test_upload_success_rate
4. test_module_split
5. test_upload_failed
6. test_upload_large
7. test_size_bound
8. test_names_frozen
## 任务 187:临时磁盘指标埋点
**所属模块**:11 可观测性 **依赖**:154 **预估**:8-15 分钟
### 功能点要求
临时磁盘容量/占用指标;与 09 告警联动。
### 测试用例(≥8)
1. test_disk_usage_measured
2. test_disk_capacity
3. test_usage_percent
4. test_threshold_warn
5. test_empty_dir
6. test_measure_failure_grace
7. test_name_frozen
8. test_no_block
## 任务 188:指标标签规范
**所属模块**:11 可观测性 **依赖**:181-187 **预估**:8-15 分钟
### 功能点要求
统一标签:moduleType/instanceId 必带;标签值规范化(null→unknown);不记录用户级数据。
### 测试用例(≥8)
1. test_module_label_all_metrics — 全指标带
2. test_instance_label_all
3. test_null_module_unknown — null 归一
4. test_no_user_label — 无用户级
5. test_label_consistent — 命名一致
6. test_label_value_clean — 值清洗
7. test_cardinality_bounded — 基数有界
8. test_spec_frozen — 规范冻结
## 任务 189:指标命名一致性测试
**所属模块**:11 可观测性 **依赖**:188 **预估**:8-15 分钟
### 功能点要求
全部指标名与 11 spec §1 标准名一致(aiimage.* 前缀);无拼写漂移。
### 测试用例(≥8)
1. test_prefix_aiimage — 前缀
2. test_task_metric_names — 任务族
3. test_file_job_metric_names — 文件族
4. test_no_typo_drift — 无拼写漂移
5. test_snapshot_all_metrics — 全指标快照
6. test_new_metric_must_register — 新指标注册
7. test_metric_doc_sync — 文档同步
8. test_case_consistent — 大小写一致
## 任务 190:日志脱敏测试
**所属模块**:11 可观测性 **依赖**:179 **预估**:8-15 分钟
### 功能点要求
敏感值(Token/Key/凭据)即使传入日志调用点也被脱敏(占位符);断言日志输出无原文。
### 测试用例(≥8)
1. test_token_masked
2. test_api_key_masked
3. test_password_masked
4. test_cookie_masked
5. test_partial_token_masked — 部分值
6. test_url_query_masked — URL 查询参数
7. test_masking_consistent — 一致
8. test_normal_fields_kept — 正常字段保留
## 任务 191:双实例指标区分回归
**所属模块**:11 可观测性 **依赖**:188-190 **预估**:8-15 分钟
### 功能点要求
双实例部署:instanceId 标签区分 server-110/server-121;指标不串;日志含实例标识。
### 测试用例(≥8)
1. test_instance_110_label
2. test_instance_121_label
3. test_no_cross_instance — 不串
4. test_instance_unknown — 未配置
5. test_log_has_instance — 日志实例
6. test_metric_aggregation_ok — 聚合可用
7. test_label_stable — 标签稳定
8. test_snapshot_frozen
### 收尾验证(本模块)
`mvn test` 相关类全绿;11 spec §2 禁止记录清单逐项对照。
@@ -1,137 +0,0 @@
# 12-plan — Flyway 迁移规范与只读巡检
> 对应 `docs/specs/12-flyway-and-inspection.md`。只追加不改历史;巡检默认关闭。
> 技术栈:Java 21 + Flyway + SQL。
## 任务 192:迁移规范模板
**所属模块**:12 Flyway **依赖**:无 **预估**:8-15 分钟
### 功能点要求
`docs/` 产出迁移规范模板:变更目的/影响表和数据量/锁表风险/验证 SQL/回滚步骤/上线窗口六项必填;新迁移文件头注释引用模板。
### 测试用例(≥8)
1. test_template_exists — 模板存在
2. test_six_fields — 六字段齐全
3. test_template_has_example — 示例
4. test_rollback_steps — 回滚步骤
5. test_validation_sql — 验证 SQL 示例
6. test_window_field — 上线窗口
7. test_doc_committed
8. test_template_usable — 可复制使用
## 任务 193:历史迁移盘点
**所属模块**:12 Flyway **依赖**:无 **预估**:8-15 分钟
### 功能点要求
盘点 db/ 下 V87+ 迁移:编号连续性、无修改历史(git 不动)、生产已执行版本核对;产出盘点报表。
### 测试用例(≥8)
1. test_version_sequential — 编号连续
2. test_no_legacy_modified — 历史未改
3. test_latest_version_noted — 最新版本记录
4. test_duplicate_version — 无重复编号
5. test_migration_single_purpose — 单迁移单目的(抽查)
6. test_report_committed
7. test_checksum_stable — 校验和稳定
8. test_repeatable
## 任务 194:orphan Job 巡检 SQL
**所属模块**:12 Flyway **依赖**:无 **预估**:8-15 分钟
### 功能点要求
巡检 SQL:task_file_job 无对应 task/result;SQL 只读;输出孤儿清单。
### 测试用例(≥8)
1. test_sql_syntax_valid — 语法有效
2. test_sql_read_only — 只读(SELECT)
3. test_orphan_detected — 检出
4. test_valid_excluded — 正常排除
5. test_join_condition — 关联条件
6. test_no_side_effect — 无副作用
7. test_empty_result_ok — 空结果
8. test_documented — 文档
## 任务 195:orphan payload 巡检 SQL
**所属模块**:12 Flyway **依赖**:无 **预估**:8-15 分钟
同 194 模式(payload 无对应任务)。
### 测试用例(≥8)
同 194(payload 表)。
## 任务 196:任务存在结果缺失巡检 SQL
**所属模块**:12 Flyway **依赖**:无 **预估**:8-15 分钟
同 194 模式(SUCCESS 任务无结果)。
### 测试用例(≥8)
同 194。
## 任务 197:结果存在文件缺失巡检 SQL
**所属模块**:12 Flyway **依赖**:无 **预估**:8-15 分钟
同 194 模式(resultFileUrl 对应对象不存在——SQL 先出清单,对象检查在 09/158 配合)。
### 测试用例(≥8)
同 194。
## 任务 198:已完成任务活跃 Job 巡检 SQL
**所属模块**:12 Flyway **依赖**:无 **预估**:8-15 分钟
同 194 模式(终态任务仍有活跃 job)。
### 测试用例(≥8)
同 194。
## 任务 199:超保留期引用巡检 SQL
**所属模块**:12 Flyway **依赖**:无 **预估**:8-15 分钟
同 194 模式(临时文件超保留期仍有引用)。
### 测试用例(≥8)
同 194。
## 任务 200:巡检报表任务落地
**所属模块**:12 Flyway **依赖**:194-199 **预估**:8-15 分钟
### 功能点要求
巡检定时任务:执行 6 张报表 SQL;默认 disabled;启用后输出报表日志;失败不阻断。
### 测试用例(≥8)
1. test_disabled_default
2. test_enabled_runs_all — 6 报表全跑
3. test_report_output
4. test_failure_grace
5. test_schedule_config
6. test_no_delete
7. test_dual_instance
8. test_enabled_stable
## 任务 201:迁移演练
**所属模块**:12 Flyway **依赖**:192 **预估**:8-15 分钟
### 功能点要求
副本库演练:flyway migrate 干净执行;验证 SQL 通过;锁表风险评估(索引类迁移在表大小场景);回滚步骤验证。
### 测试用例(≥8)
1. test_migrate_clean — 干净迁移
2. test_validate_sql_pass — 验证 SQL
3. test_rollback_script — 回滚
4. test_lock_window_estimated — 锁窗口
5. test_checksum_ok
6. test_idempotent_rerun
7. test_no_legacy_touch — 不动历史
8. test_documented
### 收尾验证(本模块)
`mvn test` 相关类 + 巡检 SQL 在副本库执行通过。
@@ -1,315 +0,0 @@
# 13-plan — 契约测试与模块边界治理
> 对应 `docs/specs/13-contract-tests-and-boundaries.md`。契约测试与代码同 PR 提交;CI 追加测试阶段。
> 技术栈:Java 21 + JUnit5 + ArchUnit + Vitest(前端)。
## 任务 202:Python-contract 夹具准备
**所属模块**:13 契约 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
录制 app_client/amazon 实际调用(/result、/items、parsed-payload、heartbeat)的真实请求报文,脱敏后入测试资源(JSON 夹具);夹具文件结构明确。
### 测试用例(≥8)
1. test_fixture_result_exists — result 夹具
2. test_fixture_items_exists — items 夹具
3. test_fixture_parsed_payload — parsed-payload 夹具
4. test_fixture_heartbeat — heartbeat 夹具
5. test_fixture_sanitized — 脱敏(无真实凭据)
6. test_fixture_shape_valid — 结构有效
7. test_fixture_fields_documented — 字段说明
8. test_fixture_reproducible — 可复录
## 任务 203:/result 幂等契约测试
**所属模块**:13 契约 **依赖**:202 **预估**:8-15 分钟
### 功能点要求
同 submissionId 重复提交 /result:HTTP 200 + success=true;只落一次;chunkIndex/chunkTotal 语义;done=true 封口。
### 测试用例(≥8)
1. test_result_success_contract — 200+true
2. test_result_duplicate_idempotent — 幂等
3. test_result_single_persist — 单次落库
4. test_result_chunk_fields — 分片字段
5. test_result_done_contract — 封口
6. test_result_error_contract — 失败语义
7. test_result_unknown_task — 未知任务
8. test_result_fixture_replay — 夹具回放
## 任务 204:/items 分页语义契约测试
**所属模块**:13 契约 **依赖**:202 **预估**:8-15 分钟
### 功能点要求
collectdata/publish 的 items 接口:分页参数(page/pageSize)、排序、字段结构、缺省行为与 Python Worker 拉取约定一致。
### 测试用例(≥8)
1. test_items_pagination — 分页
2. test_items_defaults — 默认值
3. test_items_field_shape — 字段结构
4. test_items_page_bounds — 越界处理
5. test_items_order — 排序
6. test_items_empty — 空页
7. test_items_worker_order — Worker 顺序
8. test_items_fixture_replay
## 任务 205:parsed-payload 契约测试
**所属模块**:13 契约 **依赖**:202 **预估**:8-15 分钟
### 功能点要求
similarasin/appearancepatent 的 parsed-payload:字段结构、分页语义、submissionId 关联与 Python 读取约定一致。
### 测试用例(≥8)
1. test_parsed_payload_shape
2. test_parsed_payload_pagination
3. test_parsed_payload_submission
4. test_parsed_payload_empty
5. test_parsed_payload_unknown_task
6. test_parsed_payload_fixture_replay
7. test_parsed_payload_status
8. test_parsed_payload_frozen
## 任务 206:heartbeat 旧字段契约测试
**所属模块**:13 契约 **依赖**:202 **预估**:8-15 分钟
### 功能点要求
heartbeat 接口:路径、请求/响应字段与 Python Worker 约定一致;缺字段/多余字段处理。
### 测试用例(≥8)
1. test_heartbeat_path
2. test_heartbeat_fields
3. test_heartbeat_unknown_task
4. test_heartbeat_missing_optional
5. test_heartbeat_extra_field_tolerant — 多余字段容忍
6. test_heartbeat_fixture_replay
7. test_heartbeat_success
8. test_heartbeat_frozen
## 任务 207:done=true 最后一批契约测试
**所属模块**:13 契约 **依赖**:203 **预估**:8-15 分钟
### 功能点要求
done=true 最后一批:强制处理剩余数据、生成结果文件、任务终态;协议与 Python 端一致。
### 测试用例(≥8)
1. test_done_force_process
2. test_done_finalize_task
3. test_done_generate_file
4. test_done_after_partial_chunks
5. test_done_no_pending — 无剩余
6. test_done_repeat
7. test_done_fixture_replay
8. test_done_frozen
## 任务 208:JavaApiResponse 包装契约测试(前端)
**所属模块**:13 契约 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
前端契约:JavaApiResponse 结构(success/message/data);LegacyApiSuccess(msg)兼容;解包行为(复用 01 callJava 测试)固化。
### 测试用例(≥8)
1. test_java_response_success_shape
2. test_java_response_failure_shape
3. test_legacy_success_shape
4. test_unwrap_success
5. test_unwrap_failure_throws
6. test_null_data_shape
7. test_extra_fields_tolerant
8. test_snapshot_frozen
## 任务 209:字段兼容 schema 覆盖
**所属模块**:13 契约 **依赖**:208 **预估**:8-15 分钟
### 功能点要求
核心字段 schema:user_id/task_ids(请求)、taskId/resultId/fileKey/status/taskStatus/fileStatus(响应);api-field-compat 检查接入。
### 测试用例(≥8)
1. test_request_user_id_schema
2. test_request_task_ids_schema
3. test_response_task_id_schema
4. test_response_result_id_schema
5. test_response_file_key_schema
6. test_response_status_schema
7. test_compat_checker_integrated
8. test_schema_frozen
## 任务 210:ArchUnit 依赖方向规则
**所属模块**:13 契约 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
ArchUnit 规则:Controller→Service→Mapper 单向;Controller 不依赖外部 Client 细节;task 模块规则见 212;规则测试可运行。
### 测试用例(≥8)
1. test_controller_depends_service — 允许方向
2. test_service_depends_mapper — 允许
3. test_controller_to_mapper_forbidden — 禁止
4. test_no_cycle — 无环
5. test_rule_scope_modules — 作用域
6. test_rule_verbose — 失败信息
7. test_all_controllers_covered — 覆盖
8. test_rule_stable — 稳定
## 任务 211:ArchUnit Controller 不访问 Mapper
**所属模块**:13 契约 **依赖**:210 **预估**:8-15 分钟
### 功能点要求
强化规则:任何 Controller 不得注入/调用 Mapper;违例失败。
### 测试用例(≥8)
1. test_no_mapper_in_controller
2. test_violation_detected — 违例检出
3. test_message_clear
4. test_controller_service_ok — 允许路径
5. test_all_controllers_covered
6. test_no_mapper_field
7. test_rule_in_ci
8. test_snapshot_frozen
## 任务 212:ArchUnit task 模块不依赖业务模块
**所属模块**:13 契约 **依赖**:210 **预估**:8-15 分钟
### 功能点要求
公共 task 模块不得 import 业务模块(similarasin/appearancepatent/...);04 的 Handler SPI 已反转依赖;规则检查通过。
### 测试用例(≥8)
1. test_task_no_business_dep — 无业务依赖
2. test_spi_interface_allowed — SPI 接口豁免
3. test_violation_detected
4. test_message_clear
5. test_04_registry_ok — 注册表符合
6. test_all_task_classes_covered
7. test_rule_in_ci
8. test_snapshot_frozen
## 任务 213:前端共享层导出白名单
**所属模块**:13 契约 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
TS 检查:页面(pages/*)禁止直接 import shared/api/http.ts 或拼 URL;只允许 import java-modules.ts 的 API 函数与 bridges;违例编译失败(lint 规则或类型守卫)。
### 测试用例(≥8)
1. test_page_no_http_direct — 页面不直连 http
2. test_page_no_url_concat — 不拼 URL
3. test_page_uses_api_module — 用 API 层
4. test_shared_internal_allowed — shared 内部允许
5. test_bridge_allowed — bridge 允许
6. test_violation_detected
7. test_check_runs_in_ci
8. test_allowlist_frozen
## 任务 214:progress/batch 轻量响应契约
**所属模块**:13 契约 **依赖**:109 **预估**:8-15 分钟
### 功能点要求
progress/batch 契约:items/missingTaskIds 结构;task 轻量字段;file 字段(除 collectdata);前端解析一致。
### 测试用例(≥8)
1. test_progress_batch_shape
2. test_missing_ids_shape
3. test_task_light_fields
4. test_file_fields_included
5. test_collectdata_exception — 例外模块
6. test_frontend_parse_compat
7. test_snapshot_frozen
8. test_light_vs_batch_consistency
## 任务 215:下载 URL 格式契约
**所属模块**:13 契约 **依赖**:147 **预估**:8-15 分钟
### 功能点要求
downloadUrl 契约:公开直链格式(https、bucket 包含、result/ 前缀下载域名);无签名;前端 save_file 流程兼容。
### 测试用例(≥8)
1. test_download_url_https
2. test_download_url_bucket
3. test_result_prefix_endpoint
4. test_no_signature
5. test_frontend_save_compat
6. test_blank_handling
7. test_contract_frozen
8. test_download_flow_end2end
## 任务 216:CI 接入测试阶段
**所属模块**:13 契约 **依赖**:210-215 **预估**:8-15 分钟
### 功能点要求
.gitea/workflows/build.yml 追加:mvn test(契约+ArchUnit)、前端 vitest、契约快照比对;失败即红。
### 测试用例(≥8)
1. test_ci_has_test_stage — 测试阶段
2. test_ci_java_tests — Java 测试命令
3. test_ci_frontend_tests — 前端测试
4. test_ci_snapshot_check
5. test_ci_fail_fast — 失败即红
6. test_ci_cache
7. test_ci_timeout
8. test_ci_documented
## 任务 217:快照对比工具
**所属模块**:13 契约 **依赖**:90 **预估**:8-15 分钟
### 功能点要求
Service 拆分前后响应一致工具:录制(输入→输出)golden;对比(输出 diff);供 05 各模块使用。
### 测试用例(≥8)
1. test_tool_records
2. test_tool_compares_equal
3. test_tool_diff_detected
4. test_tool_output_report
5. test_tool_reusable
6. test_tool_commits_golden
7. test_tool_clear_error
8. test_tool_documented
## 任务 218:结果文件格式契约
**所属模块**:13 契约 **依赖**:无 **预估**:8-15 分钟
### 功能点要求
结果文件格式契约:文件名(*-result.xlsx 模式)、Sheet 名称、列顺序、ZIP 结构;与 Python/前端约定一致;改造(04/05)后不变。
### 测试用例(≥8)
1. test_filename_pattern
2. test_sheet_name
3. test_column_order
4. test_zip_structure
5. test_encoding_utf8
6. test_empty_result_file
7. test_contract_frozen
8. test_regression_guard
## 任务 219:13 全量契约回归
**所属模块**:13 契约 **依赖**:202-218 **预估**:8-15 分钟
### 功能点要求
全部契约测试(Java + 前端)+ ArchUnit + 白名单检查全绿;契约快照冻结;CI 通过。
### 测试用例(≥8)
1-8:Java 契约全绿、前端契约全绿、ArchUnit 三规则、白名单、快照比对、CI 模拟、全量单测、package
### 验证方法
`mvn test` 全量 + `cd frontend-vue && npm run build && npx vitest run` + CI 检查。
### 收尾验证(全部模块——启动性/核心功能/质量 gate)
1. `mvn clean package -DskipTests` 产 JAR,`java -jar target/aiimage-backend-0.0.1-SNAPSHOT.jar`(本地配置)启动,curl 健康检查端点返回预期
2. 核心页面(`/newApi/api/...` 抽样)可访问
3. 核心交互路径:上传→解析→进度→下载最小链路真实调用非空
4. `mvn test` 全绿(≥80% 覆盖抽查)
5. `npm run build`(vue-tsc + vite)零错误;`npx vitest run` 全绿
6. check_progress 脚本返回 all tasks done(exit 0)
7. git log 验证每个 task 有对应 commit
@@ -1,45 +0,0 @@
-- =============================================================
-- V143 回滚补丁:撤销多公司一期(company 主表 + users.company_id + 后台「公司管理」菜单)
--
-- 【为什么是一个手工脚本,而不是一条 V144 迁移】
-- src/main/resources/db/ 是 Flyway 的扫描路径,放进去的任何 V*.sql 都会在应用下次启动时
-- 被自动执行。把回滚写成 V144__rollback_company.sql 的后果是:哪怕没人打算回滚,
-- 只要集群里还起着带这个文件的 jar,Flyway 就会静默撤销 V143——表没了、列没了、
-- 已归属公司的账号全变回无公司状态。回滚必须是一个"只有决定回滚时才有人跑"的东西。
--
-- 前置事实:V143 从未给任何业务表加列,所以业务数据不受影响,回滚面只有 users 这一列。
-- 回滚后已建的 company_id 值一并丢失,账号本身、密码、角色、权限都不受影响。
--
-- 执行顺序(缺一都会留下不一致状态):
-- 1. 停两台 java 应用 —— 否则回滚窗口里新代码还在往 users.company_id 写,会报 unknown column
-- 2. 在 MySQL 上按本文件顺序执行(先删索引再删列,反了会 ER_CANT_DROP_FIELD_OR_KEY 之外还留残索引)
-- 3. 把 flyway_schema_history 里本版本那行删掉(本文件最后一条语句)
-- 不删的后果:将来重新部署带 V143 的 jar 时,Flyway 认为"已应用"直接跳过,
-- 表和列都不会重建,而 Java 侧实体照常读写 company_id ⇒ 运行期报 unknown column
-- 4. 回滚 jar 到 V142 版本,再起应用
-- 5. 若两台不能同时停(滚动回退),必须保证第 2、3 步在**两台都已停下**之后才做
-- =============================================================
ALTER TABLE `users` DROP INDEX `idx_users_company_id`;
ALTER TABLE `users` DROP COLUMN `company_id`;
DROP TABLE IF EXISTS `company`;
DELETE FROM `columns` WHERE `column_key` = 'admin_companies';
DELETE FROM `flyway_schema_history` WHERE `version` = '143';
-- =============================================================
-- 验证(回滚后执行)
-- SHOW COLUMNS FROM `users` LIKE 'company_id'; -> 期望 0 行
-- SHOW INDEX FROM `users` WHERE Key_name = 'idx_users_company_id';
-- -> 期望 0 行
-- SHOW TABLES LIKE 'company'; -> 期望 0 行
-- SELECT COUNT(*) AS menu_rows FROM `columns` WHERE `column_key` = 'admin_companies';
-- -> 期望 0
-- SELECT `version` FROM `flyway_schema_history` WHERE `version` = '143';
-- -> 期望 0 行
-- SELECT COUNT(*) AS max_version FROM `flyway_schema_history`
-- WHERE CAST(`version` AS UNSIGNED) > 142; -> 期望 0
-- =============================================================
@@ -1,36 +0,0 @@
-- 回滚 V145(人工补丁,不放进 src/main/resources/db/——那里是 Flyway 扫描路径,
-- 任何 V*.sql 都会在应用下次启动时自动执行;把回滚编成版本化迁移等于让"决定回滚"这件事
-- 在没有人工执行的情况下自己发生。)
--
-- 顺序:停两台应用 → 执行本脚本 → DELETE FROM flyway_schema_history WHERE version='145'
-- → 回滚 jar → 起应用。
-- 漏掉"删历史行"那步,将来重装带 V145 的 jar 时 Flyway 判定"已应用"直接跳过,列与键都不会重建,
-- 而 Java 侧实体照常读写 company_id ⇒ 运行期 Unknown column。
--
-- ⚠ 本脚本默认只做「保留新列、把唯一键退回全局」这一档。
-- 退回全局唯一键要求"跨公司没有同名值"——批次 2(消费侧)上线之后这个前提不再由代码保证,
-- 所以第二段是注释掉的,解开前先备份这两张表。
-- 报 1062 说明确实已经有跨公司同名行:此时【不要】硬删数据,改走"保留新键、只回滚 jar"
-- (新列对新 jar 是惰性的,不读写就不影响)。
-- ---------- 1. 唯一键退回全局(先加旧键、后删新键,理由同 V145:中间任一步都至少有一个唯一键在守并发) ----------
ALTER TABLE `biz_invalid_asin_data`
ADD UNIQUE KEY `uk_data_value_brand` (`data_value`, `brand`(191)),
ALGORITHM = INPLACE, LOCK = NONE;
ALTER TABLE `biz_invalid_asin_data`
DROP INDEX `uk_company_value_brand`,
ALGORITHM = INPLACE, LOCK = NONE;
ALTER TABLE `biz_dedupe_total_data`
ADD UNIQUE KEY `uk_data_value` (`data_value`),
ALGORITHM = INPLACE, LOCK = NONE;
ALTER TABLE `biz_dedupe_total_data`
DROP INDEX `uk_company_data_value`,
ALGORITHM = INPLACE, LOCK = NONE;
-- ---------- 2. 真的要把列也删掉才解开下面两行(不可逆,先备份) ----------
-- company_id 上带着 50.7 万行的归属信息,一旦 DROP 就只能靠"全表填 1"重建,而第 2 家公司已经开通
-- ⇒ 那次之后再也分不清哪一行属于谁。除非确认没有任何一行 company_id <> 1,否则不要执行。
-- 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`;
@@ -1,42 +0,0 @@
-- 回滚 V147(人工补丁,不放进 src/main/resources/db/——那里是 Flyway 扫描路径,
-- 任何 V*.sql 都会在应用下次启动时自动执行;把回滚编成版本化迁移等于让"决定回滚"这件事
-- 在没有人工执行的情况下自己发生。)
--
-- 顺序:停两台应用 → 执行本脚本 → DELETE FROM flyway_schema_history WHERE version='147'
-- → 回滚 jar → 起应用。
-- 漏掉"删历史行"那步,将来重装带 V147 的 jar 时 Flyway 判定"已应用"直接跳过,列与键都不会重建,
-- 而 Java 侧实体照常读写 company_id ⇒ 运行期 Unknown column。
--
-- ⚠ 本脚本默认只做「保留新列、把唯一键退回全局」这一档。
-- 退回全局唯一键要求"跨公司没有同名 category_key"。V147 之前该键是全平台唯一,所以【回填那一刻】
-- 必然满足;但批次 2/3(每公司自建类目)上线之后这一前提不再由代码保证——两家各自建了同名
-- 自定义类目时,generateCategoryKey(parentId, name) 会算出同一串。所以先跑第 0 段那条预检查询。
-- 报 1062 说明确实已经有跨公司同名行:此时【不要】硬删数据,改走"保留新键、只回滚 jar"
-- (新列对新 jar 是惰性的,不读写就不影响)。
-- ---------- 0. 预检(必须先跑,返回 0 行才允许第 1 段) ----------
-- SELECT company_id, category_key, COUNT(*) c
-- FROM `biz_product_category`
-- GROUP BY company_id, category_key
-- HAVING COUNT(*) > 1;
-- -> 期望 0 行。非 0 就是"跨公司已有同名键",第 1 段会撞 1062。
-- SELECT SUM(is_builtin = 1 AND company_id <> 0) AS bad_builtin
-- FROM `biz_product_category`;
-- -> 期望 0。非 0 说明有内置节点被当成公司自建,回滚后这些节点在旧 jar 里仍会出现在每一家的树上,
-- 与 V147 之前的行为一致,不影响回滚本身,但要记进核对清单。
-- ---------- 1. 唯一键退回全局(先加旧键、后删新键,理由同 V147:中间任一步都至少有一个唯一键在守并发) ----------
ALTER TABLE `biz_product_category`
ADD UNIQUE KEY `uk_product_category_key` (`category_key`),
ALGORITHM = INPLACE, LOCK = NONE;
ALTER TABLE `biz_product_category`
DROP INDEX `uk_company_category_key`,
ALGORITHM = INPLACE, LOCK = NONE;
-- ---------- 2. 真的要把列也删掉才解开下面这行(不可逆,先备份) ----------
-- company_id 上写着"哪个自定义节点是哪一家建的",而这张表没有任何账号列(V147 §2:事后无法反推),
-- 一旦 DROP 就只能靠"全表填 1"重建 ⇒ 第 2 家自建的类目会全部划归第 1 家,且再没有证据能分回去。
-- 另外哨兵那条纪律在这里同样成立:摘 DEFAULT 用 ALTER COLUMN ... DROP DEFAULT,
-- 任何时候都不要写 MODIFY COLUMN(重建表会按"当时的列默认值"物化历史行)。
-- ALTER TABLE `biz_product_category` DROP COLUMN `company_id`;
@@ -1,149 +0,0 @@
-- =============================================================
-- 回滚补丁 V149__permission_menu_company_tree(人工执行,故意放在 Flyway 扫描路径之外)
-- 对应迁移:src/main/resources/db/V149__permission_menu_company_tree.sql
-- 设计:crawler-plugin/docs/ops/menu-company-tree-design-2026-10-06.md §9
--
-- 【为什么不是 V150】src/main/resources/db/ 是 Flyway 扫描路径,任何 V*.sql 都会在应用下次启动时
-- 自动执行。把回滚编成版本化迁移,等于让"决定回滚"这件事在没有人工执行的情况下自己发生。
--
-- 【执行顺序,一步不能换】
-- 1) 停两台 java(/api 经主机 B 的 clb 打到两台,留一台跑旧 jar 会让回滚中途被写入)
-- 2) 先跑第 0 段的两个 COUNT,把数记下来 —— 第 3 段判据要用它
-- 3) 跑本脚本(第 1..7 段)
-- 4) 删 flyway_schema_history 的 version=149 行(第 8 段;漏掉这步,将来重装时 Flyway
-- 见"已应用"会跳过 V149,回滚就白做了一半)
-- 5) 回滚 jar 到与本批不兼容的上一版(即只认 V147 及更早、columns 还没有 company_id 的那版构建;
-- V148 是已退役空号,不存在对应 jar —— 号位以 docs/migration-inventory.md 为准)
-- 6) 起应用
--
-- 【顺序上的唯一陷阱:必须先重指授权、后删副本】
-- user_column_permission 的 FK 是 ON DELETE CASCADE:直接 DELETE 副本行会把它名下所有授权
-- 一起删光 —— 而 V149 之后账号名下"本来就该"挂的是副本行。所以第 2 段先按 column_key 把指针
-- 挪回公司 1 的源行,第 3 段才敢删副本。这两段写反 = 把 133 只账号的菜单全清掉。
-- =============================================================
-- ---------- 0. 回滚前取证(只读,先把这两个数抄下来) ----------
-- 0a 副本行数(V149 后应 = 公司数-1 家 × 51)
SELECT 'V149_ROLLBACK_PRE copy_rows' AS marker, COUNT(*) AS rows_to_delete
FROM `columns` WHERE company_id <> 1;
-- 0b 挂在副本上的授权数(这些是回滚后必须回到源行的那批)
SELECT 'V149_ROLLBACK_PRE grants_on_copies' AS marker, COUNT(*) AS grants_to_repoint
FROM `user_column_permission` g
JOIN `users` u ON u.id = g.user_id
JOIN `columns` c ON c.id = g.column_id
WHERE c.company_id <> 1;
-- ---------- 1. 备份(两张都整表抄,回滚失败时按 <表名>_bak_v149_rollback 反插) ----------
-- 必须显式建、不要依赖 mysqldump:这两张表小(52+ 行 / 784 行),同库内备份是秒级,
-- 而"删完才发现判据错"的唯一出路就是这里有原样一份。
CREATE TABLE IF NOT EXISTS `columns_bak_v149_rollback` AS SELECT * FROM `columns`;
CREATE TABLE IF NOT EXISTS `user_column_permission_bak_v149_rollback` AS SELECT * FROM `user_column_permission`;
-- ---------- 2. 授权指针挪回公司 1 的源行 ----------
-- 2a 先去重:同一账号若同时挂着源行与副本(正常不会有,属 repair 中途态),删副本那一侧,
-- 留源行那一侧给 2b 判定,避免 2b 撞 PK (user_id, column_id) 报 1062。
DELETE dup FROM `user_column_permission` dup
JOIN `users` u ON u.id = dup.user_id
JOIN `columns` copy ON copy.id = dup.column_id AND copy.company_id = u.company_id
JOIN `columns` src ON src.id <> copy.id AND src.column_key = copy.column_key AND src.company_id = 1
JOIN `user_column_permission` old ON old.user_id = dup.user_id AND old.column_id = src.id;
-- 2b 重指回源行。
UPDATE `user_column_permission` g
JOIN `columns` copy ON copy.id = g.column_id AND copy.company_id <> 1
JOIN `columns` src ON src.company_id = 1 AND src.column_key = copy.column_key
SET g.column_id = src.id;
-- 2c 闸门:此时绝不允许再有"授权指向非 1 公司的行"。不为 0 就是 2b 漏了行,
-- 下一步的 CASCADE 会把它们静默删掉 —— 宁可这里报错停下,也不要少一批菜单而没人知道。
CREATE TEMPORARY TABLE `_v149_rb_gate` (`must_be_zero` INT NOT NULL);
INSERT INTO `_v149_rb_gate`
SELECT IF(COUNT(*) = 0, 0, NULL)
FROM (
SELECT g.user_id FROM `user_column_permission` g
JOIN `columns` c ON c.id = g.column_id
WHERE c.company_id <> 1
) bad;
DROP TEMPORARY TABLE `_v149_rb_gate`;
-- ---------- 3. 删副本 ----------
DELETE FROM `columns` WHERE company_id <> 1;
-- ---------- 4. 换回两条全平台唯一键(副本已删,源行本来就唯一 ⇒ 不会因重复失败) ----------
SET @db_name = DATABASE();
SET @idx_exists := (SELECT COUNT(DISTINCT INDEX_NAME) FROM information_schema.STATISTICS
WHERE TABLE_SCHEMA = @db_name AND TABLE_NAME = 'columns' AND INDEX_NAME = 'uk_column_key');
SET @sql := IF(@idx_exists = 0,
'ALTER TABLE `columns` ADD UNIQUE KEY `uk_column_key` (`column_key`)',
'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 = 'columns' AND INDEX_NAME = 'uk_menu_type_route_path');
SET @sql := IF(@idx_exists = 0,
'ALTER TABLE `columns` ADD UNIQUE KEY `uk_menu_type_route_path` (`menu_type`, `route_path`)',
'SELECT 1');
PREPARE stmt FROM @sql;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;
-- ---------- 5. 摘掉两条按公司的新键 ----------
SET @idx_exists := (SELECT COUNT(DISTINCT INDEX_NAME) FROM information_schema.STATISTICS
WHERE TABLE_SCHEMA = @db_name AND TABLE_NAME = 'columns' AND INDEX_NAME = 'uk_company_column_key');
SET @sql := IF(@idx_exists = 1, 'ALTER TABLE `columns` DROP INDEX `uk_company_column_key`', '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 = 'columns'
AND INDEX_NAME = 'uk_company_menu_type_route_path');
SET @sql := IF(@idx_exists = 1, 'ALTER TABLE `columns` DROP INDEX `uk_company_menu_type_route_path`', 'SELECT 1');
PREPARE stmt FROM @sql;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;
-- ---------- 6. 删列 ----------
SET @col_exists := (SELECT COUNT(*) FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = @db_name AND TABLE_NAME = 'columns' AND COLUMN_NAME = 'company_id');
SET @sql := IF(@col_exists = 1, 'ALTER TABLE `columns` DROP COLUMN `company_id`', 'SELECT 1');
PREPARE stmt FROM @sql;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;
-- ---------- 7. 复验(三条读数抄进回滚记录) ----------
-- 列已删(应 0 行)
SELECT 'V149_ROLLBACK_POST company_col' AS marker, COUNT(*) AS col_still_there
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'columns' AND COLUMN_NAME = 'company_id';
-- 两条旧键在、两条新键没了(应恰好 4 行且 NON_UNIQUE 全 0)
SELECT 'V149_ROLLBACK_POST indexes' AS marker, INDEX_NAME,
GROUP_CONCAT(COLUMN_NAME ORDER BY SEQ_IN_INDEX) AS cols, NON_UNIQUE
FROM information_schema.STATISTICS
WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'columns' AND NON_UNIQUE = 0
GROUP BY INDEX_NAME, NON_UNIQUE;
SELECT 'V149_ROLLBACK_POST rows' AS marker, COUNT(*) AS rows_now FROM `columns`;
SELECT 'V149_ROLLBACK_POST grants' AS marker, COUNT(*) AS grants_now FROM `user_column_permission`;
-- ---------- 8. 删 Flyway 历史行(漏掉 = 重装时 V149 被跳过) ----------
DELETE FROM `flyway_schema_history` WHERE `version` = '149';
-- ---------- 9. 回滚后的语义,写明别当 bug ----------
-- 公司 2 的 2 只账号回到 V149 之前的状态:授权挂在公司 1 的行上,两家共用一棵树。
-- 跨公司串扰因此重新发生(这本来就是回滚的代价),而 columns 表回到全平台唯一键。
-- 备份表 columns_bak_v149_rollback / user_column_permission_bak_v149_rollback 确认无误后手工 DROP。
@@ -1,38 +0,0 @@
-- 回滚 V150(人工补丁,不放进 src/main/resources/db/——那里是 Flyway 扫描路径,
-- 任何 V*.sql 都会在应用下次启动时自动执行;把回滚编成版本化迁移等于让"决定回滚"这件事
-- 在没有人工执行的情况下自己发生。)
--
-- 顺序:停两台应用 → 执行本脚本 → DELETE FROM flyway_schema_history WHERE version='150'
-- → 回滚 jar → 起应用。
-- 漏掉"删历史行"那步,将来重装带 V150 的 jar 时 Flyway 判定"已应用"直接跳过重建,
-- 而 Java 侧实体照常读写 company_id ⇒ 运行期 Unknown column。
--
-- 【本版本没有唯一键要退】V150 刻意不动 uk_ziniao_token_hash(理由见迁移文件头注释第 4 段:
-- 同一个紫鸟令牌在两家公司各存一行会被 ZiniaoApiKeyProvider 按令牌并成一条,白名单状态与代理互相顶掉),
-- 所以这里没有 V147 那种"先加旧键后删新键"的第 1 段,也没有 1062 预检。
--
-- ---------- 0. 预检:这一列上到底有几家公司的行 ----------
-- SELECT company_id, COUNT(*) AS rows_per_company
-- FROM `biz_shop_key`
-- GROUP BY company_id
-- ORDER BY company_id;
-- -> 只有一行(company_id=1):说明批次上线后没有第 2 家建过密钥,第 1 段 DROP 掉的只是"全 1"这一列,
-- 损失可忽略。
-- -> 出现 company_id<>1:第 2 家已经在这一列上登记过自己的令牌归属。此时【不要】DROP COLUMN——
-- 这张表没有任何账号列,归属删掉就再也分不回去(V150 §2 写明了这个不可逆点)。
-- 改走第 2 段"只回滚 jar、保留新列"。
--
-- ---------- 1. 把列也删掉才解开下面这行(不可逆,先备份) ----------
-- ALTER TABLE `biz_shop_key` DROP COLUMN `company_id`;
--
-- ---------- 2. 默认档:保留新列,只回滚 jar ----------
-- 旧 jar 的 ShopKeyEntity 没有 companyId 字段,MyBatis-Plus 的 insert 列清单不含它 ⇒
-- 这一列对旧 jar 是惰性的:不读写就不影响,而 DEFAULT 1 正好把旧 jar 插入的行接住。
-- 所以真要止损时,这一档比删列安全得多,也是第 0 段查出多家公司时的唯一走法。
-- (代价:混合窗口里旧 jar 建的密钥会静默归进第 1 家——这与 V150 上线之前没有任何区别,
-- 不是回滚引入的新问题。)
--
-- ALTER TABLE `biz_shop_key` ALTER COLUMN company_id DROP DEFAULT;
-- ↑ 这一句【不属于回滚】。它是"摘 DEFAULT"那笔前向修复的内容(V150 §6)。
-- 任何时候都不要写 MODIFY COLUMN ... NOT NULL:重建表会按"当时的列默认值"物化历史行,
-- 而 V150 没有写回历史行,历史归属的全部依据就是那个默认值。
@@ -1,69 +0,0 @@
-- 回滚 V151(人工补丁,不放进 src/main/resources/db/——那里是 Flyway 扫描路径,
-- 任何 V*.sql 都会在应用下次启动时自动执行;把回滚编成版本化迁移等于让"决定回滚"这件事
-- 在没有人工执行的情况下自己发生。)
--
-- 顺序:停两台应用 → 执行本脚本 → DELETE FROM flyway_schema_history WHERE version='151'
-- → 回滚 jar(回到仍按公司筛的那版)→ 起应用。
-- 漏掉"删历史行"那步,将来重装带 V151 的 jar 时 Flyway 判定"已应用"直接跳过,两把公司键不再重建,
-- 而回滚后的 jar 的读侧谓词是 company_id = X ⇒ 表现为"读得到但写同名值被 IGNORE 掉",不报错。
--
-- 回滚方向 = 把两把公司键加回来。加回来之前必须先回滚 jar:
-- "键按公司、代码不分公司"时,第 2 家能建出与第 1 家同 (company_id 档, 值) 的行——
-- 而 V151 之后的 jar 根本不写 company_id,两张表的这一列全由 DEFAULT 1 兜 ⇒ 加回公司键
-- 在数据上是安全的(见第 0 段预检),但只有配回滚后的 jar 才有意义。
--
-- ⚠ 本脚本【不】恢复 company_id 列本身:V151 没有删列(列在 V151 之后仍然带着 DEFAULT 1),
-- 所以回滚也不涉及建列。DROP COLUMN 是下一版的事,那一版的回滚要把列与默认值一起加回来,
-- 并且必须先确认两张表的历史归属还能不能分清——品牌库能(uploader_user_id 还在),
-- 类目表不能(这张表没有任何账号列,V147 §2 已写明事后无法反推)。
-- ---------- 0. 预检(必须先跑,返回 0 行才允许第 1、2 段) ----------
-- SELECT data_value, LEFT(brand, 191) b, COUNT(*) c
-- FROM `biz_invalid_asin_data`
-- GROUP BY data_value, b
-- HAVING COUNT(*) > 1;
-- -> 期望 0 行。V151 之后全局键在守,所以这一条应当恒为 0;非 0 说明有人在 V151 与本次回滚
-- 之间手工绕过迁移改过索引,先查 flyway_schema_history 再决定。
-- SELECT company_id, COUNT(*) c FROM `biz_invalid_asin_data` GROUP BY company_id;
-- -> 期望只有一档且值为 1(新 jar 的 INSERT 不带这一列,由 DEFAULT 1 兜)。
-- 出现第二档说明有写入显式带过公司值,加回公司键后这些行会从别家的视图里隐身。
-- SELECT category_key, COUNT(*) c FROM `biz_product_category` GROUP BY category_key HAVING c > 1;
-- -> 期望 0 行(同上,V151 之后由全局键保证)。
-- SELECT SUM(is_builtin = 1 AND company_id <> 0) AS bad_builtin FROM `biz_product_category`;
-- -> 期望 0。V148 从未上线,内置节点仍挂哨兵 0;非 0 说明有人跑过 V148 的人工版本,
-- 回滚后这些内置节点在旧 jar 的 company_id IN (0, X) 谓词下会同时出现在每一家的树上。
-- ---------- 1. 品牌数据库:先加公司键、后删全局键(中间任一步至少有一个唯一键在守并发) ----------
ALTER TABLE `biz_invalid_asin_data`
ADD UNIQUE KEY `uk_company_value_brand` (`company_id`, `data_value`, `brand`(191)),
ALGORITHM = INPLACE, LOCK = NONE;
ALTER TABLE `biz_invalid_asin_data`
DROP INDEX `uk_data_value_brand`,
ALGORITHM = INPLACE, LOCK = NONE;
-- ---------- 2. 商品类目:同一形状 ----------
ALTER TABLE `biz_product_category`
ADD UNIQUE KEY `uk_company_category_key` (`company_id`, `category_key`),
ALGORITHM = INPLACE, LOCK = NONE;
ALTER TABLE `biz_product_category`
DROP INDEX `uk_product_category_key`,
ALGORITHM = INPLACE, LOCK = NONE;
-- ---------- 3. biz_dedupe_total_data 不在本脚本范围内 ----------
-- V151 没有动去重库(它的 uk_company_data_value 一直都在),回滚自然也不动它。
-- ---------- 4. 验证 ----------
-- 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_product_category','biz_dedupe_total_data')
-- AND NON_UNIQUE = 0
-- GROUP BY TABLE_NAME, INDEX_NAME;
-- -> 期望回到 V145+V147 之后的形状:
-- uk_company_value_brand(company_id@1,data_value@2,brand@3)
-- uk_company_category_key(company_id@1,category_key@2)
-- uk_company_data_value(company_id@1,data_value@2)
-- 加三行 PRIMARY(id);uk_data_value_brand / uk_product_category_key 必须【不】在结果里。
@@ -1,36 +0,0 @@
-- 回滚 V152(人工补丁,不放进 src/main/resources/db/——那里是 Flyway 扫描路径,
-- 任何 V*.sql 都会在应用下次启动时自动执行;把回滚编成版本化迁移等于让"决定回滚"这件事
-- 在没有人工执行的情况下自己发生。)
--
-- 触发场景:V152 上线后「摘错了」——出现场外的、省略 company_id 的写入被 1364 打出来。
-- 如果只是回滚 jar(代码问题、与默认值无关),【不需要本补丁】:V149/V150 起的 jar 全部
-- 显式落列,对默认值在不在毫无感知,V152 保持应用态即可。
--
-- 顺序:停两台应用 → 执行本脚本 → DELETE FROM flyway_schema_history WHERE version='152'
-- → 回滚 jar → 起应用。
-- 漏掉"删历史行"那步,将来重装带 V152 的 jar 时 Flyway 判定"已应用"直接跳过,
-- 而脚本已经把 DEFAULT 装回去了 ⇒ 库状态与 history 声明的"已摘"长期互相矛盾
-- (表现为启动期哨兵对这两张表一直喊 COMPANY_DEFAULT_STILL_PRESENT,而没人知道该不该摘)。
--
-- 与 rollback-V150 的差别:那里默认档是"保留新列、只回滚 jar"(删列不可逆,留注释由人工解开);
-- 本笔只有默认值属性被动过,回滚就是把它装回去——纯元数据、可逆、无损,所以【默认档直接可执行】。
--
-- 【禁写成 MODIFY COLUMN ... NOT NULL DEFAULT 1】(V144 时代那种写法已废弃):
-- MODIFY 会重建表,而这两张表历史行的归属依据就是加列时记录的默认值,重建是没必要的风险。
-- ---------- 1. 默认档:两列装回 DEFAULT 1(还原到 V152 之前的 schema) ----------
-- 用 ALTER COLUMN ... SET DEFAULT 1——纯元数据操作,瞬时完成;重复执行无副作用
-- (发布前在 scratch MySQL 8.4.9 上连跑两遍证实)。
ALTER TABLE `columns`
ALTER COLUMN company_id SET DEFAULT 1;
ALTER TABLE `biz_shop_key`
ALTER COLUMN company_id SET DEFAULT 1;
-- ---------- 0. 验证(跑完第 1 段后) ----------
-- SELECT TABLE_NAME, COLUMN_DEFAULT FROM information_schema.COLUMNS
-- WHERE TABLE_SCHEMA = DATABASE() AND COLUMN_NAME = 'company_id'
-- AND TABLE_NAME IN ('columns','biz_shop_key');
-- -> 期望两行 COLUMN_DEFAULT 均为 1
-- SHOW COLUMNS FROM `columns` LIKE 'company_id'; -> Default = 1
-- SHOW COLUMNS FROM `biz_shop_key` LIKE 'company_id'; -> Default = 1
@@ -1,46 +0,0 @@
-- 回滚 V153(人工补丁,不放进 src/main/resources/db/——那里是 Flyway 扫描路径,
-- 任何 V*.sql 都会在应用下次启动时自动执行;把回滚编成版本化迁移等于让"决定回滚"这件事
-- 在没有人工执行的情况下自己发生。)
--
-- 顺序:停两台应用 → 执行本脚本 → DELETE FROM flyway_schema_history WHERE version='153'
-- → 回滚 jar → 起应用。
-- 漏掉"删历史行"那步,将来重装带 V153 的 jar 时 Flyway 判定"已应用"直接跳过重建,
-- 而 Java 侧实体照常读写 company_id ⇒ 运行期 Unknown column。
--
-- 【回滚的前提比加迁移重】名字退回"全平台唯一"之前必须先消掉跨公司同名,
-- 否则第 1 段末尾那条 ADD UNIQUE KEY 直接 1062 失败,而失败发生在停了两台之后。
--
-- ---------- 0. 预检:有没有跨公司同名(必须先跑,出任何一行都不能直接回滚) ----------
-- SELECT g.`group_name`, COUNT(DISTINCT g.`company_id`) AS companies
-- FROM `biz_shop_manage_group` g
-- GROUP BY g.`group_name`
-- HAVING companies > 1;
-- -> 0 行:可以走第 1 段。
-- -> 有行:先由业务把重名的分组改名(保留一份),再回来跑第 1 段。这一份脚本【不自动改名】,
-- 因为"改哪一个"是业务判断,不是工程判断。
--
-- 另外单独看一眼 NULL 归属的行(组长账号已删的孤儿分组):
-- SELECT `id`, `group_name` FROM `biz_shop_manage_group` WHERE `company_id` IS NULL;
-- -> (NULL, name) 在全局键下与任何同名行都冲突,第 1 段会连带把它们一起钉住。
-- 这些行本来就在所有公司的列表里不可见,回滚前一并改名或清掉更干净。
--
-- ---------- 1. 唯一键退回全局(先 ADD 旧键,后 DROP 新键:中间始终有一把在守并发) ----------
-- ALTER TABLE `biz_shop_manage_group` ADD UNIQUE KEY `uk_group_name` (`group_name`),
-- ALGORITHM = INPLACE, LOCK = NONE;
-- ALTER TABLE `biz_shop_manage_group` DROP INDEX `uk_company_group_name`,
-- ALGORITHM = INPLACE, LOCK = NONE;
--
-- ---------- 2. 列【不要删】:它是资产,删了就回不来 ----------
-- company_id 存的是"组长账号在哪一家",而账号会被硬删(users 无软删列)——
-- 今天删掉这一列,明天那些组长的账号一删,归属就永久无从追溯(这正是 V153 第 1 段
-- 拒绝给孤儿行硬塞公司号的同一个理由)。列留着对旧 jar 是惰性的:
-- 旧 ShopManageGroupEntity 没有 companyId 字段,MyBatis-Plus 的 insert 列清单不含它,
-- 而这一列是 NULL DEFAULT NULL ⇒ 旧 jar 插入的行该列读作 NULL,与新代码
-- "推不出归属就报错"的口径一致,不会静默归到某一家。
-- ALTER TABLE `biz_shop_manage_group` DROP COLUMN `company_id`; -- 想清楚再解开这行
--
-- ---------- 3. 只回滚 jar(默认档) ----------
-- 保留列与 uk_company_group_name,只把 jar 退回不带 companyId 的版本:
-- 旧 jar 建分组时该列一律落成 NULL ⇒ 之后每一行新分组都变成"归属无从追溯",
-- 且它们彼此可以重名(NULL 在唯一索引里互不等价)。这个形状能跑,但会把隔离一寸寸磨掉,
-- 所以只作为"新代码有缺陷、需要立刻止血"时的临时档,停的时间不能过夜。
@@ -1,23 +0,0 @@
-- 回滚 V154(人工补丁,不放进 src/main/resources/db/——那是 Flyway 扫描路径,
-- 任何 V*.sql 都会在应用下次启动时自动执行;把回滚编成版本化迁移等于让"决定回滚"
-- 这件事在没有人工执行的情况下自己发生)。
--
-- 触发场景只有一个:出现了本迁移没预见的、省略 company_id 的写入通道,且它绕过了
-- DedupeTotalDataService.requireCompanyAttribution 那道 Java 闸门(表现为 1364,
-- 或被 INSERT IGNORE 落成 company_id=0 的行)。
-- 仅仅"代码有问题需要回滚 jar"不需要本补丁:带闸门的 jar 全部显式落列,
-- 对默认值在不在毫无感知,V154 保持应用态即可。
--
-- 执行顺序(两台都要,中间不停服会混版):
-- 1) 停两台应用(docker stop java-server)
-- 2) 在 aiimage 库执行下面的 SET DEFAULT 1(纯元数据、瞬时)
-- 3) DELETE FROM flyway_schema_history WHERE version = '154';
-- 4) 回滚 jar 到上一版
-- 5) 起两台,确认 health=200 且 CompanyDefaultGuard 重新打 COMPANY_DEFAULT_STILL_PRESENT
-- (它重新喊才是"回到改前"的证据,不喊说明 DEFAULT 没装回去)
-- 6) 复查是否已经产生 company_id=0 的行:
-- SELECT COUNT(*) FROM biz_dedupe_total_data WHERE company_id = 0;
-- 有的话回滚不解决存量,要单独按 uploader/group 追认归属后再改。
ALTER TABLE `biz_dedupe_total_data`
ALTER COLUMN company_id SET DEFAULT 1;
@@ -1,15 +0,0 @@
-- 回滚 V155(users.disabled_at)——人工执行,放在 Flyway 扫描路径之外。
-- 理由:把回滚也做成版本化迁移,等于让"决定回滚"这件事自己发生(V150/V152/V154 同款处置)。
--
-- 只在"这列不该加"时才跑。仅仅回滚 jar 不需要它:旧 jar 不认识 disabled_at,留着 NULL 列零影响。
--
-- 顺序:停两台 java → 跑本文件 → 删 flyway_schema_history 的 version='155' 行 → 回滚 jar → 起 java。
--
-- ⚠ 跑之前先确认没有非 NULL 的停用行,否则 DROP COLUMN 会把停用记录一起抹掉、事后无从追认:
-- SELECT COUNT(*) FROM `users` WHERE `disabled_at` IS NOT NULL; -- 期望 0
ALTER TABLE `users` DROP COLUMN `disabled_at`;
-- 复核:
-- SHOW COLUMNS FROM `users` LIKE 'disabled_at'; -- 期望 Empty set
-- DELETE FROM flyway_schema_history WHERE version = '155';
@@ -1,31 +0,0 @@
-- 回滚 V156(人工补丁,不放进 src/main/resources/db/——那里是 Flyway 扫描路径,
-- 任何 V*.sql 都会在应用下次启动时自动执行;把回滚编成版本化迁移等于让"决定回滚"这件事
-- 在没有人工执行的情况下自己发生)。
--
-- 触发场景:V156 把组 33/uid=1188(「先锋」)的 1452 行 company_id 从 1 回填到 3。
-- 只有一种情况需要回滚本数据:控制方改判这 1452 行不属于先锋-团队。
-- 仅仅"读侧切换的 jar 有问题要回滚"【不需要】动数据——旧读侧按上传账号认公司,
-- 对这批 uploader 已删的行本来就不显示(company_id 是 1 还是 3 都看不见),
-- 但**去重比对**(39de5035 已按 company_id)会跟着数据走:回滚数据 = 米椿花去重
-- 重新吃到这 1452 个先锋 ASIN、先锋丢值,所以数据回滚必须与 jar 回滚同批做,
-- 且回滚前先确认"改判"是真的(不是又一次误判归属)。
--
-- 执行顺序(两台都要,中间不停服会混版):
-- 1) 停两台应用(docker stop java-server)
-- 2) 在 aiimage 库执行下面的反向 UPDATE
-- 3) DELETE FROM flyway_schema_history WHERE version = '156';
-- 4) 回滚 jar 到上一版(读侧按上传账号的版本)
-- 5) 起两台,确认 health=200
-- 6) 复查:
-- SELECT company_id, COUNT(*) FROM biz_dedupe_total_data
-- WHERE uploader_user_id = 1188 GROUP BY company_id;
-- 期望回到一行:1 | 1452。
--
-- 反向判据与 V156 原文一一对应(uploader_user_id=1188 AND group_id=33),
-- company_id=3 限定保证重跑是 no-op;只回滚这一个精确集,不扩大射程。
UPDATE `biz_dedupe_total_data`
SET `company_id` = 1
WHERE `uploader_user_id` = 1188
AND `group_id` = 33
AND `company_id` = 3;
@@ -1,79 +0,0 @@
# Stale 任务收尾约束(公共心跳模块)
> 适用范围:所有使用 [TaskHeartbeatService](../src/main/java/com/nanri/aiimage/modules/task/service/TaskHeartbeatService.java) 的 file_task 模块
> (PRODUCT_RISK_RESOLVE / PRICE_TRACK / SHOP_MATCH / PATROL_DELETE / QUERY_ASIN /
> APPEARANCE_PATENT / SIMILAR_ASIN / DELETE_BRAND)。
## 历史故障(2026-06-08)
SIMILAR_ASIN taskId=13102 的 file_job 长期持有 RUNNING 等待 Python 凑齐
batchSize 行再发 Coze。Python 端 13:20 异常掉线,但任务到下午 16 点仍卡在 12% 不前进,
30 分钟兜底失效。
链路:
1. [resetStuckJobs](../src/main/java/com/nanri/aiimage/modules/task/service/TaskResultFileJobWorker.java)
每 60 秒扫一次,把 RUNNING 超 30 分钟的 file_job 改回 PENDING。
2. worker 立刻把它捞起来重跑 `processResultFileJob`。
3. 重跑分支命中 "等 Python 上传更多 row" → 调用 `touchJavaSideTaskActivity`,
把 `file_task.updated_at` 刷成 now。
4. `finalizeStaleTasks` 用 `lt(updated_at, threshold)` 预过滤,于是这个任务
永远进不到候选集,Redis 心跳判定那一步根本走不到。
→ Python 已断线 N 小时,任务仍在循环,永不收尾。
## 约束
### 1. stale-finalize 必须以 Redis 心跳为主信号
`TaskCacheService.touchTaskHeartbeat` 写的 Redis key 仅在 **Python 真实活动**
(心跳接口、上传 result chunk、提交 row)时刷新。Java 内部循环不应触碰它。
stale 判定时应:
- 以 Redis heartbeat 为主信号;
- 仅在 Redis 不可用 / 缺失时回落到 `file_task.updated_at`;
- 不要再用 `lt(file_task.updated_at, threshold)` 做预过滤
(除非该模块 100% 不存在长期 RUNNING 等待循环)。
参考实现:[SimilarAsinTaskService.finalizeStaleTasks / isHeartbeatStale](../src/main/java/com/nanri/aiimage/modules/similarasin/service/SimilarAsinTaskService.java)
和 [AppearancePatentTaskService](../src/main/java/com/nanri/aiimage/modules/appearancepatent/service/AppearancePatentTaskService.java) 中 P1-7 注释段。
### 2. 不要在"等 Python"分支刷 file_task.updated_at
如果模块的 file_job 会持有 RUNNING 状态等待外部上传更多数据,
**这条等待路径上不允许调 `setUpdatedAt(now)` 类方法**。
否则会触发 [resetStuckJobs](../src/main/java/com/nanri/aiimage/modules/task/service/TaskResultFileJobWorker.java)
→ 重跑 → 续命 → 再 reset 的死循环。
如必须刷 `updated_at` 推动其他逻辑,应迁移到独立字段(例如
`file_job.updated_at`、Redis pendingScope 字段),与 stale 判定信号解耦。
### 3. 新增/修改 stale-finalize 流程的 PR 检查清单
- [ ] stale 判定的主信号是 Redis 心跳(不是 `file_task.updated_at`)
- [ ] 列出该模块所有刷 `file_task.updated_at` 的代码位置,
其中没有任何一处会被 `processResultFileJob` 在"等 Python"分支重复触发
- [ ] 如果 file_job 会持有长 RUNNING(pull-style 工作流),明确写明 stuck-reset
重跑后的幂等行为(不会续命 updated_at)
- [ ] 给 finalize 路径补一个 debug 接口(参考
[DebugTaskRecoveryController](../src/main/java/com/nanri/aiimage/modules/debug/controller/DebugTaskRecoveryController.java)),
绕过过滤直接对单 task 强制收尾,便于线上应急
## 当前各模块状态(2026-06-08 复核)
| 模块 | stale 入口 | 是否曾出现自我续命 | 是否需要改 |
|---|---|---|---|
| SIMILAR_ASIN | `SimilarAsinTaskService.finalizeStaleTasks` | 是(已修) | 已切 Redis-first |
| APPEARANCE_PATENT | `AppearancePatentTaskService.finalizeStaleTasks` | 是(已修) | 已切 Redis-first |
| PRODUCT_RISK_RESOLVE | `DeleteBrandStaleTaskService.failStaleProductRiskResolveTasks` | 否 | 当前不需要 |
| PRICE_TRACK | `DeleteBrandStaleTaskService.failStalePriceTrackTasks` | 否 | 当前不需要 |
| SHOP_MATCH | `DeleteBrandStaleTaskService.failStaleShopMatchTasks` | 否 | 当前不需要 |
| PATROL_DELETE | `DeleteBrandStaleTaskService.failStalePatrolDeleteTasks` | 否 | 当前不需要 |
| QUERY_ASIN | `DeleteBrandStaleTaskService.failStaleQueryAsinTasks` | 否 | 当前不需要 |
| DELETE_BRAND | `DeleteBrandStaleTaskService.failStaleDeleteBrandTasks` | 否 | 当前不需要 |
| BRAND | `BrandTaskService.failStaleRunningTasks`(独立心跳源) | 否 | 当前不需要 |
下次新增"等 row 凑批" / "pull-style 长 RUNNING file_job"型功能时,
请先读本约束。
@@ -1,28 +0,0 @@
# 单次提交事务段耗时基线(task-138)
> 本文档由 `TxDurationBenchmarkTest` 断言存在与内容,用于冻结「Python 结果提交」单次调用的
> 耗时上界,防止提交路径劣化。**不要删除**,劣化时更新数值并说明原因。
## 测量对象
`SimilarAsinTaskService.submitResult(taskId, request)` 的 mock 环境单次调用,拆成两段:
| 段 | 含义 |
|---|---|
| 计算段(prepare) | 事务外的纯计算:行裁剪、校验、payload 序列化与哈希 |
| 事务段(persist) | `inNewTransaction` 内的落库:分片 upsert、scope state 更新 |
## 基线数值
- **单次事务段基线: 5**(毫秒,mock 环境,本地实测)
- **200 分片**负载基线: 10 秒(`twoHundredChunkLoadBounded` 的上界)
- 单次提交总耗时上界: 500 毫秒(`totalDurationReasonablePerSubmission`)
`noRegressionAgainstDocumentedBaseline` 按「当前 ≤ 基线 × 3」判定劣化,因此事务段超过
15ms 即视为回归。
## 说明
- 该基线取的是 mock 环境(Mapper 全部打桩)而非真实 MySQL 的耗时,用于**相对劣化**而非绝对性能。
- 真实环境的事务段耗时会显著高于此值,本基线不适用于容量规划。
- 测量机器与 JDK 变更后如需调整,请同步更新本文件数值。
@@ -1,93 +0,0 @@
"""task-166 HTTP 客户端契约盘点测试。
对应 plan 10 任务 166 的 8 条用例:
1. test_contract_table_all_clients 全客户端覆盖
2. test_timeouts_listed 超时现状
3. test_retry_listed 重试现状
4. test_idempotency_listed 幂等性标注
5. test_jdk_limits_noted 平台限制
6. test_doc_committed 文档存在
7. test_no_code_change 零代码变更
8. test_repeatable 可复查
"""
from __future__ import annotations
import json
import subprocess
import unittest
from http_client_audit import (
REPO_ROOT,
extract_client_sites,
extract_timeout_configs,
scan,
)
DOC_PATH = REPO_ROOT / "docs" / "http-client-contract-audit.md"
class HttpClientAuditTest(unittest.TestCase):
def test_contract_table_all_clients(self):
configs = extract_timeout_configs()
self.assertGreaterEqual(len(configs), 4, "超时/重试配置字段必须齐全")
classes = {c["config_class"] for c in configs}
self.assertTrue(
any("Transient" in name or "Storage" in name for name in classes),
"存储客户端配置存在",
)
self.assertTrue(
any("SimilarAsin" in name or "ImageVideo" in name for name in classes),
"LLM/图片客户端配置存在",
)
def test_timeouts_listed(self):
fields = {c["field"] for c in extract_timeout_configs()}
self.assertTrue(any("connectTimeout" in f for f in fields), "connect 超时缺失")
self.assertTrue(any("readTimeout" in f for f in fields), "read 超时缺失")
self.assertTrue(any("writeTimeout" in f for f in fields), "write 超时缺失")
self.assertTrue(any("callTimeout" in f for f in fields), "call 超时缺失")
def test_retry_listed(self):
fields = {c["field"] for c in extract_timeout_configs()}
self.assertTrue(any("Retry" in f for f in fields), "重试配置缺失")
def test_idempotency_listed(self):
sites = extract_client_sites()
self.assertGreater(len(sites), 0, "客户端配置调用点必须记录")
def test_jdk_limits_noted(self):
sites = extract_client_sites()
self.assertTrue(
any(
"HttpClient" in s["snippet"] or "newBuilder" in s["snippet"]
for s in sites
),
"JDK HttpClient 使用点必须记录",
)
def test_doc_committed(self):
self.assertTrue(DOC_PATH.is_file(), f"契约表文档缺失: {DOC_PATH}")
text = DOC_PATH.read_text(encoding="utf-8")
self.assertIn("超时", text)
self.assertIn("重试", text)
self.assertIn("幂等", text)
def test_no_code_change(self):
changed = subprocess.run(
["git", "diff", "--name-only", "HEAD", "--", "backend-java/src"],
cwd=REPO_ROOT,
capture_output=True,
text=True,
check=True,
).stdout.strip()
self.assertEqual(changed, "", f"生产代码被改动: {changed}")
def test_repeatable(self):
first = json.dumps(scan().to_dict(), sort_keys=True)
second = json.dumps(scan().to_dict(), sort_keys=True)
self.assertEqual(first, second, "盘点可复查")
if __name__ == "__main__":
unittest.main()
-199
View File
@@ -1,199 +0,0 @@
"""task-121 N+1 扫描审计测试。
对应 plan 06 任务 121 的 8 条用例 + 2 条补强:
1. test_scan_select_in_loop 识别循环内单查
2. test_scan_output_listed 清单产出(位置/对象/影响字段齐全)
3. test_scan_priority 按影响排序
4. test_scan_module_coverage 覆盖主要模块(真实代码扫描)
5. test_scan_false_positive_checked 排除误报(已批量/循环外)
6. test_scan_repeatable 可重复(同输入同输出)
7. test_scan_documented 审计文档产出
8. test_scan_no_edit 本任务不改生产代码
9. test_scan_lambda_brace_less 无花括号 lambda 内单查识别
10. test_scan_iterating_query_result 遍历查询结果集判 HIGH
"""
from __future__ import annotations
import json
import subprocess
import unittest
from pathlib import Path
from n1_scan import (
HIGH,
LOW,
MEDIUM,
MODULES_ROOT,
scan_modules,
scan_text,
)
SCRIPTS_DIR = Path(__file__).resolve().parent
REPO_ROOT = SCRIPTS_DIR.parent.parent
DOC_PATH = REPO_ROOT / "backend-java" / "docs" / "n1-scan-audit.md"
FIXTURE_LOOP = """package com.example;
public class DemoService {
public void batchByIds(List<Long> ids) {
for (Long id : ids) {
FileTaskEntity task = fileTaskMapper.selectById(id);
}
}
}
"""
FIXTURE_QUERY_RESULT_LOOP = """package com.example;
public class DemoService {
public List<Vo> listVos() {
List<FileTaskEntity> tasks = fileTaskMapper.selectList(new LambdaQueryWrapper<>());
List<Vo> vos = new ArrayList<>();
for (FileTaskEntity t : tasks) {
FileResultEntity r = fileResultMapper.selectById(t.getResultId());
vos.add(toVo(r));
}
return vos;
}
}
"""
FIXTURE_LAMBDA_BRACELESS = """package com.example;
public class DemoService {
public void touch(List<Long> ids) {
ids.forEach(id -> fileTaskMapper.selectOne(
new LambdaQueryWrapper<FileTaskEntity>().eq(FileTaskEntity::getId, id)));
}
}
"""
FIXTURE_BATCH_SAFE = """package com.example;
public class DemoService {
public List<FileTaskEntity> load(List<Long> ids) {
List<FileTaskEntity> tasks = new ArrayList<>();
for (Long id : ids) {
tasks.addAll(fileTaskMapper.selectBatchIds(Collections.singleton(id)));
}
for (Long id : ids) {
tasks.addAll(fileTaskMapper.selectByIds(Collections.singleton(id)));
}
return tasks;
}
}
"""
FIXTURE_NO_LOOP = """package com.example;
public class DemoService {
public FileTaskEntity one(Long id) {
return fileTaskMapper.selectById(id);
}
}
"""
FIXTURE_LOOP_NO_QUERY = """package com.example;
public class DemoService {
public int sum(List<Integer> nums) {
int s = 0;
for (Integer n : nums) {
s += n;
}
return s;
}
}
"""
FIXTURE_INDEX_LOOP = """package com.example;
public class DemoService {
public List<Vo> listVos(List<Long> ids) {
List<Vo> vos = new ArrayList<>();
for (int i = 0; i < ids.size(); i++) {
FileTaskEntity t = fileTaskMapper.selectById(ids.get(i));
vos.add(toVo(t));
}
return vos;
}
}
"""
FIXTURE_MIXED = (
FIXTURE_QUERY_RESULT_LOOP
+ "\n"
+ FIXTURE_LAMBDA_BRACELESS
+ "\n"
+ FIXTURE_INDEX_LOOP
)
class ScanDetectTest(unittest.TestCase):
def test_scan_select_in_loop(self):
findings = scan_text(FIXTURE_LOOP, "DemoService.java")
self.assertEqual(len(findings), 1)
self.assertIn("selectById", findings[0]["statement"])
self.assertEqual(findings[0]["loop_type"], "for")
self.assertEqual(findings[0]["line"], 5)
def test_scan_output_listed(self):
for finding in scan_text(FIXTURE_MIXED, "DemoService.java"):
for key in ("file", "line", "statement", "loop_type", "impact"):
self.assertIn(key, finding)
self.assertTrue(finding[key] is not None and finding[key] != "")
def test_scan_priority(self):
findings = scan_text(FIXTURE_MIXED, "DemoService.java")
order = {HIGH: 0, MEDIUM: 1, LOW: 2}
impacts = [order[f["impact"]] for f in findings]
self.assertEqual(impacts, sorted(impacts))
def test_scan_false_positive_checked(self):
self.assertEqual(len(scan_text(FIXTURE_BATCH_SAFE, "Batch.java")), 0)
self.assertEqual(len(scan_text(FIXTURE_NO_LOOP, "NoLoop.java")), 0)
self.assertEqual(len(scan_text(FIXTURE_LOOP_NO_QUERY, "NoQuery.java")), 0)
def test_scan_repeatable(self):
first = scan_text(FIXTURE_MIXED, "DemoService.java")
second = scan_text(FIXTURE_MIXED, "DemoService.java")
self.assertEqual(
json.dumps(first, sort_keys=True), json.dumps(second, sort_keys=True)
)
def test_scan_lambda_brace_less(self):
findings = scan_text(FIXTURE_LAMBDA_BRACELESS, "DemoService.java")
self.assertEqual(len(findings), 1)
self.assertEqual(findings[0]["loop_type"], "forEach")
self.assertEqual(findings[0]["impact"], MEDIUM)
def test_scan_iterating_query_result(self):
findings = scan_text(FIXTURE_QUERY_RESULT_LOOP, "DemoService.java")
self.assertEqual(len(findings), 1)
self.assertEqual(findings[0]["impact"], HIGH)
class ScanCoverageTest(unittest.TestCase):
def test_scan_module_coverage(self):
report = scan_modules(MODULES_ROOT)
self.assertGreaterEqual(report.scanned_files, 600)
self.assertGreater(len(report.findings), 0)
modules = {f["module"] for f in report.findings}
self.assertGreaterEqual(len(modules), 3)
order = {HIGH: 0, MEDIUM: 1, LOW: 2}
impacts = [order[f["impact"]] for f in report.findings]
self.assertEqual(impacts, sorted(impacts))
def test_scan_documented(self):
self.assertTrue(DOC_PATH.is_file(), f"audit doc missing: {DOC_PATH}")
text = DOC_PATH.read_text(encoding="utf-8")
self.assertIn("N+1", text)
self.assertIn("影响", text)
def test_scan_no_edit(self):
changed = subprocess.run(
["git", "diff", "--name-only", "HEAD", "--", "backend-java/src"],
cwd=REPO_ROOT,
capture_output=True,
text=True,
check=True,
).stdout.strip()
self.assertEqual(changed, "", f"生产代码被改动: {changed}")
if __name__ == "__main__":
unittest.main()
@@ -1,89 +0,0 @@
"""task-148 临时目录配置盘点测试。
对应 plan 09 任务 148 的 8 条用例:
1. test_config_listed 配置项清单齐全
2. test_temp_root_defined 临时根目录定义
3. test_retention_period 保留期定义
4. test_payload_prefixes payload 前缀
5. test_upload_dir 上传目录
6. test_existing_cleanup_noted 现有清理逻辑记录
7. test_doc_committed 文档存在
8. test_no_code_change 零代码变更
"""
from __future__ import annotations
import json
import subprocess
import unittest
from temp_config_audit import REPO_ROOT, extract_cleanup_calls, extract_configs, scan
DOC_PATH = REPO_ROOT / "docs" / "temp-file-config-audit.md"
class TempConfigAuditTest(unittest.TestCase):
def test_config_listed(self):
configs = extract_configs()
self.assertGreaterEqual(len(configs), 8, "配置项清单必须齐全")
for item in configs:
for key in ("key", "value", "line", "source"):
self.assertIn(key, item)
def test_temp_root_defined(self):
keys = {c["key"] for c in extract_configs()}
self.assertTrue(
any("local-temp-dir" in k for k in keys),
f"临时根目录配置缺失: {sorted(keys)}",
)
def test_retention_period(self):
keys = {c["key"] for c in extract_configs()}
self.assertTrue(any("retention" in k for k in keys), "保留期配置缺失")
def test_payload_prefixes(self):
keys = {c["key"] for c in extract_configs()}
self.assertTrue(
any("transient-payload" in k for k in keys), "transient payload 配置缺失"
)
def test_upload_dir(self):
configs = extract_configs()
self.assertTrue(
any(
"upload" in c["key"].lower() or "tmp" in c["key"].lower()
for c in configs
),
"上传/临时目录配置缺失",
)
def test_existing_cleanup_noted(self):
calls = extract_cleanup_calls()
self.assertGreater(len(calls), 0, "必须记录既有清理调用点")
files = {c["file"] for c in calls}
self.assertGreaterEqual(len(files), 3, "清理调用应覆盖多个文件")
def test_doc_committed(self):
self.assertTrue(DOC_PATH.is_file(), f"盘点文档缺失: {DOC_PATH}")
text = DOC_PATH.read_text(encoding="utf-8")
self.assertIn("临时", text)
self.assertIn("保留期", text)
def test_no_code_change(self):
changed = subprocess.run(
["git", "diff", "--name-only", "HEAD", "--", "backend-java/src"],
cwd=REPO_ROOT,
capture_output=True,
text=True,
check=True,
).stdout.strip()
self.assertEqual(changed, "", f"生产代码被改动: {changed}")
def test_scan_repeatable(self):
first = json.dumps(scan().to_dict(), sort_keys=True)
second = json.dumps(scan().to_dict(), sort_keys=True)
self.assertEqual(first, second, "盘点结果可重复")
if __name__ == "__main__":
unittest.main()
-204
View File
@@ -1,204 +0,0 @@
"""task-124 @Transactional 方法审计清单测试。
对应 plan 07 任务 124 的 8 条用例 + 2 条补强:
1. test_audit_covers_all_modules 覆盖全部业务模块
2. test_audit_classification 分类完整(必须/可移出)
3. test_audit_result_endpoints /result 相关方法都在清单
4. test_audit_python_facing Python 回调相关标记
5. test_audit_priority_order 按收益排序
6. test_audit_no_code_change 本任务零代码变更
7. test_audit_documented 文档产出
8. test_audit_repeatable 可重复执行
9. test_audit_detects_tx_method 识别 @Transactional 方法
10. test_audit_classifies_movable 事务内可移出段分类
"""
from __future__ import annotations
import json
import subprocess
import unittest
from pathlib import Path
from tx_audit import MODULES_ROOT, scan_modules, scan_text
SCRIPTS_DIR = Path(__file__).resolve().parent
REPO_ROOT = SCRIPTS_DIR.parent.parent
DOC_PATH = REPO_ROOT / "backend-java" / "docs" / "transaction-boundary-audit.md"
FIXTURE_TX = """package com.example;
@Service
public class DemoService {
@Transactional
public boolean submitResult(Long taskId, List<RowVo> rows) {
List<ItemVo> items = rows.stream()
.map(row -> toVo(row))
.collect(Collectors.toList());
int updated = fileResultMapper.update(null, new LambdaUpdateWrapper<FileResultEntity>()
.eq(FileResultEntity::getId, taskId)
.set(FileResultEntity::getStatus, "SUCCESS"));
log.info("submitted taskId={} count={}", taskId, items.size());
Files.deleteIfExists(Path.of("/tmp/task-" + taskId));
return updated > 0;
}
public void noTxMethod(Long id) {
fileTaskMapper.selectById(id);
}
}
"""
FIXTURE_WRITE_ONLY = """package com.example;
@Service
public class DemoService {
@Transactional
public int markFailed(Long id) {
return fileTaskMapper.update(null, new LambdaUpdateWrapper<FileTaskEntity>()
.eq(FileTaskEntity::getId, id)
.set(FileTaskEntity::getStatus, "FAILED"));
}
}
"""
FIXTURE_LOCK = """package com.example;
@Service
public class DemoService {
@Transactional
public void finalizeTask(Long taskId) {
TaskDistributedLockService.LockHandle handle = acquireTaskLock("MODULE", taskId);
if (handle == null) {
return;
}
try (handle) {
taskMapper.update(null, new LambdaUpdateWrapper<TaskFileEntity>()
.eq(TaskFileEntity::getId, taskId));
}
}
}
"""
FIXTURE_PLAIN = """package com.example;
@Service
public class DemoService {
public int sum(List<Integer> nums) {
return nums.stream().mapToInt(Integer::intValue).sum();
}
}
"""
class TxAuditDetectTest(unittest.TestCase):
def test_audit_detects_tx_method(self):
findings = scan_text(FIXTURE_TX, "DemoService.java")
self.assertEqual(len(findings), 1)
self.assertEqual(findings[0]["method"], "submitResult")
self.assertFalse(findings[0]["class_level"])
def test_audit_classifies_movable(self):
findings = scan_text(FIXTURE_TX, "DemoService.java")
self.assertEqual(len(findings), 1)
movable = findings[0]["movable"]
self.assertIn("compute", movable)
self.assertIn("assembly", movable)
self.assertIn("log", movable)
self.assertIn("cleanup", movable)
self.assertIn("write", findings[0]["must_stay"])
self.assertGreater(findings[0]["priority"], 0)
def test_audit_no_tx_not_reported(self):
self.assertEqual(len(scan_text(FIXTURE_PLAIN, "Plain.java")), 0)
def test_audit_write_only_no_movable(self):
findings = scan_text(FIXTURE_WRITE_ONLY, "DemoService.java")
self.assertEqual(len(findings), 1)
self.assertIn("write", findings[0]["must_stay"])
self.assertEqual(findings[0]["movable"], [])
def test_audit_lock_flagged_must_stay(self):
findings = scan_text(FIXTURE_LOCK, "DemoService.java")
self.assertEqual(len(findings), 1)
self.assertIn("lock", findings[0]["must_stay"])
class TxAuditCoverageTest(unittest.TestCase):
def test_audit_covers_all_modules(self):
report = scan_modules(MODULES_ROOT)
self.assertGreaterEqual(report.scanned_files, 600)
self.assertGreater(len(report.findings), 50)
modules = {f["module"] for f in report.findings}
self.assertGreaterEqual(len(modules), 15)
def test_audit_classification(self):
for finding in scan_modules(MODULES_ROOT).findings:
self.assertIn("must_stay", finding)
self.assertIn("movable", finding)
self.assertIsInstance(finding["must_stay"], list)
self.assertIsInstance(finding["movable"], list)
def test_audit_result_endpoints(self):
report = scan_modules(MODULES_ROOT)
result_methods = [
f
for f in report.findings
if "result" in f["method"].lower() or "submit" in f["method"].lower()
]
self.assertGreater(
len(result_methods), 0, "应找到 /result 相关 @Transactional 方法"
)
modules_with_result = {f["module"] for f in result_methods}
self.assertGreaterEqual(len(modules_with_result), 3)
def test_audit_python_facing(self):
report = scan_modules(MODULES_ROOT)
flagged = [f for f in report.findings if f["python_facing"]]
self.assertGreater(len(flagged), 0, "应标记 Python 回调相关方法")
for f in flagged:
name = f["method"].lower()
self.assertTrue(
any(
k in name
for k in (
"result",
"submit",
"upload",
"chunk",
"done",
"ack",
"report",
)
),
f"python_facing 标记与命名不符: {f['method']}",
)
def test_audit_priority_order(self):
findings = scan_modules(MODULES_ROOT).findings
priorities = [f["priority"] for f in findings]
self.assertEqual(priorities, sorted(priorities, reverse=True))
def test_audit_repeatable(self):
first = scan_modules(MODULES_ROOT).to_dict()
second = scan_modules(MODULES_ROOT).to_dict()
self.assertEqual(
json.dumps(first, sort_keys=True), json.dumps(second, sort_keys=True)
)
def test_audit_documented(self):
self.assertTrue(DOC_PATH.is_file(), f"audit doc missing: {DOC_PATH}")
text = DOC_PATH.read_text(encoding="utf-8")
self.assertIn("事务", text)
self.assertIn("必须", text)
self.assertIn("可移出", text)
def test_audit_no_code_change(self):
changed = subprocess.run(
["git", "diff", "--name-only", "HEAD", "--", "backend-java/src"],
cwd=REPO_ROOT,
capture_output=True,
text=True,
check=True,
).stdout.strip()
self.assertEqual(changed, "", f"生产代码被改动: {changed}")
if __name__ == "__main__":
unittest.main()
@@ -1,121 +0,0 @@
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.nio.file.Paths;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 架构文档 §6 现状描述核对(任务 56,验证型)。
* 断言 java-architecture-optimization-plan.md §6 已反映本轮实现现状:
* multipart 直通、1MB 阈值、过滤器日志不读 body、未做项标注、spec 引用、
* 与 00-overview 实施记录一致、无过时默认值/占位符残留。
*/
class ArchitecturePlanSection6DocTest {
private static final Path DOC = Paths.get("src", "main", "resources", "..", "..", "..",
"docs", "java-architecture-optimization-plan.md").normalize();
private static final Path OVERVIEW = Paths.get("src", "main", "resources", "..", "..", "..",
"docs", "plans", "00-plan-overview.md").normalize();
private static String read(Path path) throws IOException {
return new String(Files.readAllBytes(path), StandardCharsets.UTF_8);
}
private static String section6() throws IOException {
String doc = read(DOC);
int start = doc.indexOf("## 6. ");
int end = doc.indexOf("## 7. ", start);
assertTrue(start >= 0, "文档存在 §6 章节");
return end > start ? doc.substring(start, end) : doc.substring(start);
}
private static List<String> section6Lines() throws IOException {
return List.of(section6().split("\r?\n"));
}
private static int docLineNumberOf(String section, String needle) {
List<String> lines = List.of(section.split("\r?\n"));
for (int i = 0; i < lines.size(); i++) {
if (lines.get(i).contains(needle)) {
return i + 1;
}
}
return -1;
}
@Test
void noObsoleteDefaultRemains() throws IOException {
for (String line : section6Lines()) {
assertFalse(line.contains("104857600"), "§6 无过时默认值 104857600 残留:" + line);
}
}
@Test
void multipartPassthroughStated() throws IOException {
String section = section6();
assertTrue(section.contains("multipart"), "§6 记录 multipart 处理");
assertTrue(section.contains("直通") || section.contains("跳过缓存"),
"§6 记录 multipart 直通现状");
}
@Test
void threshold1MbStated() throws IOException {
String section = section6();
assertTrue(section.contains("1MB") || section.contains("1 MiB") || section.contains("1048576"),
"§6 记录 1MB 阈值现状");
assertTrue(section.contains("1048576"), "§6 记录阈值具体值 1048576");
}
@Test
void notReadingBodyStated() throws IOException {
String section = section6();
assertTrue(section.contains("不读 body") || (section.contains("日志") && section.contains("body")),
"§6 记录过滤器日志不读 body");
}
@Test
void deferredItemsListed() throws IOException {
String section = section6();
assertTrue(section.contains("未做") || section.contains("不做") || section.contains("后续批次"),
"§6 标注本轮未做项");
}
@Test
void spec03Referenced() throws IOException {
String section = section6();
assertTrue(section.contains("specs/03-request-trace-filter.md")
|| section.contains("03-request-trace-filter.md"),
"§6 引用 03 spec");
}
@Test
void consistentWithOverview() throws IOException {
String section = section6();
String overview = read(OVERVIEW);
for (String key : List.of("49", "50", "51", "52", "53", "54", "55", "56")) {
assertTrue(overview.contains("| " + key + " |"), "00-overview 实施记录含任务 " + key);
}
assertTrue(overview.contains("multipart 直通"), "00-overview 记录 multipart 直通");
assertEquals(1, overview.split("multipart 直通", -1).length - 1,
"00-overview 实施记录恰好一条 multipart 直通条目(与 §6 现状一致)");
}
@Test
void noTodoLeft() throws IOException {
String section = section6();
assertTrue(docLineNumberOf(section, "### 现状") > 0 || section.contains("已实现"),
"§6 有现状或已实现描述");
assertFalse(section.contains("TBD"), "§6 无 TBD 残留");
assertFalse(section.contains("TODO"), "§6 无 TODO 残留");
assertFalse(section.contains("待确认"), "§6 无待确认残留");
}
}
@@ -90,9 +90,6 @@ class CompanyDefaultDropV152Test {
return normalize(stripComments(rawMigration()));
}
private static Path rollbackPatch() {
return ROOT.resolve("docs/rollback-V152-columns-shop-key-default.sql");
}
// ------------------------------------------------------------ SQL 预处理
// 与 CompanyMigrationV144Test / ShopKeyMigrationV150Test 逐字同实现,理由见类注释。
@@ -270,29 +267,6 @@ class CompanyDefaultDropV152Test {
}
}
/**
* 回滚补丁的默认档就是"两条 SET DEFAULT 1"——与 rollback-V150 的"空档"相反:
* 本笔被动过的只有默认值属性,装回它既是完整回滚、又是纯元数据、可逆无损。
* 破坏点:写成 MODIFY(重建表)或忘了删 flyway_schema_history 行(半套回滚,
* 会让"重装 V152 时跳过执行"与"库里 DEFAULT 已被装回"长期互相矛盾)。
*/
@Test
void rollbackPatchRestoresTheDefaultAndDeletesHistoryRow() throws IOException {
Path doc = rollbackPatch();
assertTrue(Files.isRegularFile(doc), "V152 的人工回滚补丁必须存在:" + doc);
String whole = raw(doc);
assertTrue(whole.contains("flyway_schema_history"), "回滚必须写明删 version='152' 的历史行");
assertTrue(whole.contains("'152'"), "回滚补丁要点名本版本号,后来人才知道删的是哪一行");
String executable = normalize(stripComments(whole));
assertTrue(!executable.isEmpty(), "本笔回滚是可逆的元数据操作,默认档必须直接可执行(不学 V150 的空档)");
assertEquals(2, count(executable, "SET DEFAULT 1"),
"默认档应把两列的 DEFAULT 都装回去(各恰一次),实际可执行段:" + executable);
assertTrue(executable.contains("ALTER TABLE `columns` ALTER COLUMN company_id SET DEFAULT 1;")
&& executable.contains("ALTER TABLE `biz_shop_key` ALTER COLUMN company_id SET DEFAULT 1;"),
"装回语句应逐字用 ALTER COLUMN ... SET DEFAULT 1:" + executable);
assertFalse(executable.toUpperCase().contains("MODIFY"),
"禁 MODIFY:重建表对这两张表的历史行归属没有意义且徒增风险");
}
/**
* 摘掉 DEFAULT 之后哨兵对这两张表本应静默,但清单要留着——它是"被装回"(dump 重建、
@@ -312,15 +286,6 @@ class CompanyDefaultDropV152Test {
}
/** 破坏点:盘点文档没跟着 V152 改 ⇒ 下一个人按"取号起点"取号就撞号,或按"最新版本"漏掉本文件。 */
@Test
void inventoryDocTracksV152() throws IOException {
Path doc = ROOT.resolve("docs/migration-inventory.md");
String text = raw(doc);
assertTrue(text.contains(migration().getFileName().toString()),
"盘点文档应逐字保留本迁移文件名:" + migration().getFileName());
assertTrue(text.contains("V150__shop_key_company_scope.sql"),
"盘点文档应同时保留更早的文件名:只钉最新一条会重演「推进概览时把旧条目挤掉」那一次回归");
}
/** 自检:本用例集扫的是真文件,且 normalize 后仍能命中关键串(0 命中的断言是恒绿的)。 */
@Test
@@ -330,8 +295,5 @@ class CompanyDefaultDropV152Test {
assertTrue(count(sql, "ALTER COLUMN") == 2,
"关键签名命中数应为 2(恰好两条),实际 " + count(sql, "ALTER COLUMN")
+ ":预处理或文件路径坏了,本类的断言全部不可信");
String rollbackExecutable = normalize(stripComments(raw(rollbackPatch())));
assertTrue(count(rollbackExecutable, "ALTER COLUMN") == 2,
"回滚补丁可执行段的 ALTER COLUMN 也应为 2(否则上面「装回两次」的断言进了恒绿分支)");
}
}
@@ -28,7 +28,6 @@ class CompanyMigrationV143Test {
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 ROLLBACK_RELATIVE = "docs/rollback-V143-company.sql";
// ---------------------------------------------------------------- 取文件
@@ -374,23 +373,6 @@ class CompanyMigrationV143Test {
*/
@Test
void rollbackLivesOutsideFlywayScanPath() throws IOException {
Path rollback = ROOT.resolve(ROLLBACK_RELATIVE);
assertTrue(Files.isRegularFile(rollback),
"回滚脚本应存在于 " + ROLLBACK_RELATIVE + "(Flyway 扫描路径之外),否则事故时无从回退");
String rb = normalize(stripComments(Files.readString(rollback, StandardCharsets.UTF_8)));
assertMatches(rb, "ALTER TABLE `users`\\s+DROP INDEX `idx_users_company_id`", "回滚应删掉索引");
assertMatches(rb, "DROP COLUMN `company_id`", "回滚应删掉 users.company_id");
assertMatches(rb, "DROP TABLE (IF EXISTS )?`company`", "回滚应删掉 company 表");
assertTrue(rb.contains("flyway_schema_history") && rb.contains("143"),
"回滚必须清掉 flyway_schema_history 里 V143 的记录,否则重装 jar 时 Flyway 认为已应用而跳过");
assertTrue(rb.contains("admin_companies"), "回滚应删掉后台「公司管理」菜单行");
assertTrue(rawMigration().contains(ROLLBACK_RELATIVE),
"V143 头注释的「回滚步骤」必须点名该脚本,否则值班的人找不到它");
assertFalse(rawMigration().contains("db/V144"),
"回滚不得写成版本化迁移 V144:Flyway 会在下次启动时自动执行它,静默撤销 V143");
for (Path f : versionFiles()) {
String name = f.getFileName().toString().toLowerCase();
assertFalse(name.contains("rollback"), "Flyway 扫描路径内不得出现回滚迁移: " + f.getFileName());
@@ -402,35 +384,4 @@ class CompanyMigrationV143Test {
}
}
/**
* 破坏点:docs/migration-inventory.md 的数字没跟着改。
* 下一个人按文档里的"取号起点"取号就会撞号(Flyway 启动失败),或以为 V143 还没被占用。
*/
@Test
void inventoryDocTracksTheNewMigration() throws IOException {
Path doc = ROOT.resolve("docs/migration-inventory.md");
assertTrue(Files.isRegularFile(doc), "盘点文档应存在");
String text = Files.readString(doc, StandardCharsets.UTF_8);
List<Path> files = versionFiles();
int maxOnDisk = files.stream().mapToInt(CompanyMigrationV143Test::versionOf).max().orElse(0);
assertTrue(text.contains(migration().getFileName().toString()),
"盘点文档应记录最新迁移文件名 " + migration().getFileName());
Matcher count = Pattern.compile("版本化迁移文件数:\\*\\*(\\d+)\\*\\*").matcher(text);
assertTrue(count.find(), "盘点文档应给出版本化迁移文件数");
assertEquals(files.size(), Integer.parseInt(count.group(1)),
"文档记录的迁移文件数与磁盘不符");
Matcher range = Pattern.compile("整数版本范围:\\*\\*V1\\.\\.V(\\d+)\\*\\*").matcher(text);
assertTrue(range.find(), "盘点文档应给出整数版本范围");
assertEquals(maxOnDisk, Integer.parseInt(range.group(1)),
"文档记录的整数版本上界与磁盘不符");
Matcher next = Pattern.compile("从 \\*\\*V(\\d+)\\*\\* 起取号").matcher(text);
assertTrue(next.find(), "盘点文档应给出取号起点");
assertEquals(maxOnDisk + 1, Integer.parseInt(next.group(1)),
"取号起点必须 = 磁盘最大版本 + 1,否则会撞号或留洞");
}
}
@@ -278,14 +278,4 @@ class CompanyMigrationV144Test {
}
/** 破坏点:盘点文档没跟着 V144 改,下一个人按"取号起点"取号就撞号。 */
@Test
void inventoryDocTracksV144() throws IOException {
Path doc = ROOT.resolve("docs/migration-inventory.md");
assertTrue(Files.isRegularFile(doc), "盘点文档应存在");
String text = Files.readString(doc, StandardCharsets.UTF_8);
assertTrue(text.contains(migration().getFileName().toString()),
"盘点文档应记录 V144 文件名 " + migration().getFileName());
assertTrue(text.contains("1539570901"),
"盘点文档应记下 V143 的生产存量校验和,作为「不许原地改」的证据");
}
}
@@ -312,17 +312,6 @@ class CompanyScopeMigrationV145Test {
assertFalse(writesHistoryTable.matcher(executable).find(),
"回滚不许编成版本化迁移:" + file.getFileName() + " 的执行段写了 flyway_schema_history");
}
Path rollback = ROOT.resolve("docs/rollback-V145-company-scope.sql");
assertTrue(Files.isRegularFile(rollback), "回滚人工补丁必须存在:" + rollback);
String whole = raw(rollback);
assertTrue(whole.contains("flyway_schema_history"), "回滚必须删本版本历史行");
String executable = normalize(stripComments(whole));
assertTrue(executable.contains("ADD UNIQUE KEY `uk_data_value_brand` (`data_value`, `brand`(191))"),
"回滚要把品牌库的全局唯一键加回来");
assertTrue(executable.contains("ADD UNIQUE KEY `uk_data_value` (`data_value`)"),
"回滚要去把去重库的全局唯一键加回来");
assertFalse(executable.contains("DROP COLUMN"),
"DROP COLUMN 是丢归属信息的动作,必须留在注释里由人工解开(第 2 家已开通,删了就无法再分清)");
}
/**
@@ -379,16 +368,6 @@ class CompanyScopeMigrationV145Test {
}
/** 破坏点:盘点文档没跟着改,下一个人按"取号起点"取号就撞号。 */
@Test
void inventoryDocTracksV145() throws IOException {
Path doc = ROOT.resolve("docs/migration-inventory.md");
String text = raw(doc);
assertTrue(text.contains(migration().getFileName().toString()), "盘点文档应记录 V145 文件名");
// 取号起点不在这里钉:原先写死 contains("V146"),而 V146 真落地后它只因文档里还留着
// 那个文件名而巧合为真。派生尺子=MigrationInventoryTest#inventoryDocNumberingStartIsMaxPlusOne。
assertTrue(text.contains("1833593804"), "盘点文档应记下 V144 的生产存量校验和");
assertTrue(text.contains("1539570901"), "盘点文档应保留 V143 的生产存量校验和");
}
/** 自检:本用例集扫的是真文件,且 normalize 后仍能命中关键串(0 命中的断言是恒绿的)。 */
@Test
@@ -1,131 +0,0 @@
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.nio.file.Paths;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 任务 115:高频查询 EXPLAIN 索引审计(文档产出验证)。
* 审计文档必须覆盖 history/progress/dashboard 三类高频查询的执行计划结论、
* 候选索引清单(表/列/类型/收益/风险)、全表扫描标记、可重复执行步骤,
* 且本任务明确不做 DDL(只审计,不加索引)。
*/
class ExplainIndexAuditDocTest {
private static final Path AUDIT = Paths.get("src", "main", "resources", "..", "..", "..",
"docs", "explain-index-audit.md").normalize();
private static final Path FLYWAY_SPEC = Paths.get("src", "main", "resources", "..", "..", "..",
"docs", "specs", "12-flyway-and-inspection.md").normalize();
private static String read(Path path) throws IOException {
return new String(Files.readAllBytes(path), StandardCharsets.UTF_8);
}
private static List<String> linesOf(Path path) throws IOException {
return List.of(read(path).split("\r?\n"));
}
private static String lineContaining(String content, String needle) {
for (String line : content.split("\r?\n")) {
if (line.contains(needle)) {
return line;
}
}
return null;
}
@Test
void test_explain_history_plan() throws Exception {
String doc = read(AUDIT);
assertTrue(doc.contains("history"), "审计文档覆盖 history 查询");
assertTrue(doc.contains("EXPLAIN"), "审计文档包含 EXPLAIN 执行计划记录");
}
@Test
void test_explain_progress_plan() throws Exception {
String doc = read(AUDIT);
assertTrue(doc.contains("progress"), "审计文档覆盖 progress 查询");
}
@Test
void test_explain_dashboard_plan() throws Exception {
String doc = read(AUDIT);
assertTrue(doc.contains("dashboard"), "审计文档覆盖 dashboard 查询");
assertTrue(doc.contains("GROUP BY"), "dashboard 聚合查询计划已记录");
}
@Test
void test_full_scan_detected() throws Exception {
String doc = read(AUDIT);
assertTrue(doc.contains("type=ALL") || doc.contains("全表扫描") || doc.contains("ALL")
|| doc.contains("possible_keys") || doc.contains("扫描"),
"审计文档记录执行计划扫描类型(full scan 标记)");
String line = lineContaining(doc, "idx_file_job_task");
assertTrue(line != null && line.contains("task_id"),
"审计文档指出 task_id 前缀索引对 (module_type, job_type, task_id IN) 的局限");
}
@Test
void test_index_candidates_listed() throws Exception {
String doc = read(AUDIT);
assertTrue(doc.contains("idx_file_job_module_type_task")
|| doc.contains("module_type") && doc.contains("job_type") && doc.contains("task_id"),
"候选索引清单含 (module_type, job_type, task_id) 组合");
assertTrue(doc.contains("收益") && doc.contains("风险"),
"候选索引清单含收益与风险说明");
}
@Test
void test_plan_documented() throws Exception {
String doc = read(AUDIT);
assertTrue(doc.contains("biz_task_file_job"), "审计文档引用目标表");
assertTrue(doc.contains("biz_file_task") || doc.contains("biz_file_result"),
"审计文档引用业务任务/结果表");
}
@Test
void test_plan_repeatable() throws Exception {
String doc = read(AUDIT);
assertTrue(doc.contains("EXPLAIN SELECT") || doc.contains("EXPLAIN")
&& doc.contains("手工执行") || doc.contains("执行"),
"审计文档包含可重复执行的 EXPLAIN SQL 步骤");
}
@Test
void test_no_ddl_this_task() throws Exception {
String audit = read(AUDIT);
String spec = read(FLYWAY_SPEC);
assertTrue(audit.contains("不做 DDL") || audit.contains("本任务无 DDL")
|| audit.contains("不新增索引") || audit.contains("只审计"),
"审计文档明确本任务不做 DDL");
// 任务 116 落地 V101 索引后,审计文档会把 ALTER TABLE 作为候选索引的
// 回滚说明引用。审计任务自身依然不执行 DDL——判定口径改为「ALTER TABLE
// 只能出现在候选/回滚等说明性上下文」,而不是文档里不得出现该字符串。
for (String line : audit.split("\r?\n")) {
if (!line.contains("ALTER TABLE")) {
continue;
}
assertTrue(line.contains("回滚") || line.contains("候选") || line.contains("建议")
|| line.contains("风险") || line.trim().startsWith(">"),
"审计文档中的 ALTER TABLE 必须是候选/回滚说明,实际行:" + line);
}
assertTrue(spec.contains("只读") || spec.contains("巡检"),
"12 spec 巡检报表模式与审计文档对应");
}
@Test
void test_audit_reflects_batch_loading_queries() throws Exception {
String doc = read(AUDIT);
assertTrue(doc.contains("findAssembleJobsByTaskIds"), "审计覆盖轻量进度 Job 批量查询");
assertTrue(doc.contains("findAssembleJobsByResultIds"), "审计覆盖结果列表 Job 批量查询");
assertTrue(doc.contains("selectMaps") || doc.contains("GROUP BY"), "审计覆盖 dashboard 聚合查询");
}
}
@@ -1,66 +0,0 @@
package com.nanri.aiimage.config;
import org.junit.jupiter.api.Test;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* task-201:迁移演练 runbook 契约。
* docs/flyway-migration-drill.md 固化演练步骤:干净迁移/validate/验证 SQL/回滚/锁窗口/校验和/
* 幂等重跑/不动历史;on-DB 步骤由运维在副本库按 runbook 执行(本环境无库)。
*/
class FlywayMigrationDrillDocTest {
private static final String DOC = "docs/flyway-migration-drill.md";
private String doc() throws IOException {
return Files.readString(Path.of(System.getProperty("user.dir"), DOC));
}
@Test
void drillDocExists() {
assertTrue(Files.exists(Path.of(System.getProperty("user.dir"), DOC)), "演练 runbook 应存在");
}
@Test
void cleanMigrateStepDescribed() throws IOException {
assertTrue(doc().contains("migrate"), "应描述干净迁移步骤");
}
@Test
void validateStepDescribed() throws IOException {
assertTrue(doc().contains("validate"), "应包含 validate 校验历史 checksum 步骤");
}
@Test
void validationSqlStepDescribed() throws IOException {
assertTrue(doc().contains("验证 SQL"), "应包含验证 SQL 步骤");
}
@Test
void rollbackStepDescribed() throws IOException {
assertTrue(doc().contains("回滚"), "应包含回滚验证步骤");
}
@Test
void lockWindowEstimatedStepDescribed() throws IOException {
assertTrue(doc().contains("锁窗口"), "应包含锁窗口估算步骤");
}
@Test
void checksumAndIdempotentRerunDescribed() throws IOException {
String text = doc();
assertTrue(text.contains("checksum") || text.contains("校验和"), "应包含校验和检查");
assertTrue(text.contains("幂等重跑") || text.contains("idempotent"), "应包含幂等重跑");
}
@Test
void noLegacyTouchGuarded() throws IOException {
assertTrue(doc().contains("历史") && (doc().contains("未被动") || doc().contains("未被改动")),
"应明确演练不动历史迁移");
}
}
@@ -1,76 +0,0 @@
package com.nanri.aiimage.config;
import org.junit.jupiter.api.Test;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* task-192:迁移规范模板契约。
* docs/flyway-migration-template.md 存在且六项必填(目的/影响表与数据量/锁表风险/验证 SQL/
* 回滚步骤/上线窗口)齐全,含示例 SQL,可被新迁移文件头注释引用。
*/
class FlywayMigrationTemplateDocTest {
private static final String DOC = "docs/flyway-migration-template.md";
private String doc() throws IOException {
return Files.readString(Path.of(System.getProperty("user.dir"), DOC));
}
@Test
void templateExists() throws IOException {
assertTrue(Files.exists(Path.of(System.getProperty("user.dir"), DOC)), "模板文件应存在");
}
@Test
void sixMandatoryFieldsPresent() throws IOException {
String text = doc();
for (int i = 1; i <= 6; i++) {
assertTrue(text.contains(i + ". "), "头注释应含第 " + i + " 项必填");
}
}
@Test
void fieldNamesListed() throws IOException {
String text = doc();
assertTrue(text.contains("变更目的"));
assertTrue(text.contains("影响表与数据量"));
assertTrue(text.contains("锁表风险"));
assertTrue(text.contains("验证 SQL"));
assertTrue(text.contains("回滚步骤"));
assertTrue(text.contains("上线窗口"));
}
@Test
void hasCopyableHeaderComment() throws IOException {
assertTrue(doc().contains("复制以下头注释"), "模板应提供可复制头注释");
assertTrue(doc().contains("V{N+1}__"), "头注释示例应含占位版本号");
}
@Test
void hasValidationSqlExample() throws IOException {
assertTrue(doc().contains("SELECT COUNT(*)"), "应含验证 SQL 示例");
}
@Test
void hasRollbackField() throws IOException {
assertTrue(doc().contains("回滚步骤"), "应含回滚步骤说明");
}
@Test
void hasUpgradeWindowField() throws IOException {
assertTrue(doc().contains("上线窗口"), "应含上线窗口说明");
}
@Test
void templateUsableByNewMigrations() throws IOException {
String text = doc();
assertTrue(text.contains("src/main/resources/db/"), "应说明迁移文件目录");
assertTrue(text.contains("只追加"), "应强调只追加不改历史");
assertTrue(text.contains("V109") || text.contains("最大现有版本"), "应说明版本号取最大现有版本+1");
}
}
@@ -22,8 +22,6 @@ class IndexMigrationV101Test {
private static final Path DB_DIR = Paths.get("src", "main", "resources", "db");
private static final Path MIGRATION = DB_DIR.resolve("V101__task_file_job_module_type_task_index.sql");
private static final Path AUDIT = Paths.get("src", "main", "resources", "..", "..", "..",
"docs", "explain-index-audit.md").normalize();
private static String read(Path path) throws IOException {
return new String(Files.readAllBytes(path), StandardCharsets.UTF_8);
@@ -78,18 +76,8 @@ class IndexMigrationV101Test {
void test_migration_validated() throws Exception {
String sql = read(MIGRATION);
assertTrue(sql.contains("SELECT 1"), "验证 SQL(幂等分支)");
String audit = read(AUDIT);
assertTrue(audit.contains("idx_file_job_module_type_task"), "审计清单已列出该索引");
assertTrue(audit.contains("收益") && audit.contains("风险"), "审计清单含收益/风险");
}
@Test
void test_explain_improved() throws Exception {
String audit = read(AUDIT);
assertTrue(audit.contains("findAssembleJobsByTaskIds"), "审计覆盖 progress/light Job 查询");
assertTrue(audit.contains("执行后重跑") || audit.contains("前后计划")
|| audit.contains("对比"), "审计含迁移前后 EXPLAIN 对比步骤");
}
@Test
void test_migration_no_alter_legacy() throws Exception {
@@ -109,9 +97,6 @@ class IndexMigrationV101Test {
String sql = read(MIGRATION);
assertTrue(sql.contains("DROP INDEX") || sql.contains("drop index"),
"迁移文件含回滚语句(DROP INDEX idx_file_job_module_type_task)");
String audit = read(AUDIT);
assertTrue(audit.contains("回滚") || audit.contains("DROP"),
"审计文档含回滚步骤说明");
}
@Test
@@ -376,45 +376,6 @@ class MenuTreeCompanyMigrationV149Test {
assertTrue(raw.contains("information_schema.STATISTICS"), "验证 SQL 要复验两条旧键已摘、两条新键在");
}
/**
* 破坏点:回滚被编成版本化迁移(Flyway 扫描路径里的 V*.sql 会在下次启动自动执行),
* 或者回滚把"删副本"排在"重指授权"之前。
*
* <p>后者是这一版独有的陷阱:{@code user_column_permission} 的外键是 ON DELETE CASCADE,
* 先删副本会把它名下授权一起删光——而 V149 之后账号名下"本来就该"挂的是副本行。
* 写反的读数不是报错,是 133 只账号的菜单被清空。</p>
*/
@Test
void rollbackRepointsGrantsBeforeDeletingTheCopiesAndStaysUnversioned() throws IOException {
Pattern writesHistoryTable = Pattern.compile(
"\\b(DELETE|UPDATE|INSERT|TRUNCATE|ALTER|DROP)\\b[^;]*\\bflyway_schema_history\\b",
Pattern.CASE_INSENSITIVE);
for (Path file : versionFiles()) {
String executable = normalize(stripComments(raw(file)));
assertFalse(writesHistoryTable.matcher(executable).find(),
"回滚不许编成版本化迁移:" + file.getFileName() + " 的执行段写了 flyway_schema_history");
}
Path rollback = ROOT.resolve("docs/rollback-V149-permission-menu-company.sql");
assertTrue(Files.isRegularFile(rollback), "回滚人工补丁必须存在:" + rollback);
String whole = raw(rollback);
assertTrue(whole.contains("flyway_schema_history"), "回滚必须删本版本历史行(漏掉=重装时 Flyway 跳过 V149)");
String executable = normalize(stripComments(whole));
assertTrue(executable.contains("SET g.column_id = src.id"), "回滚要先把授权指针挪回公司 1 的源行");
assertTrue(executable.contains("DELETE FROM `columns` WHERE company_id <> 1"), "再删副本");
assertTrue(executable.indexOf("SET g.column_id = src.id") < executable.indexOf("DELETE FROM `columns`"),
"顺序不能反:FK 是 ON DELETE CASCADE,先删副本等于清空 133 只账号的菜单");
assertTrue(whole.contains("ON DELETE CASCADE"), "注释要写明为什么这个顺序是陷阱");
assertTrue(executable.contains("ADD UNIQUE KEY `uk_column_key` (`column_key`)"), "回滚要把两条全平台旧键加回来");
assertTrue(executable.contains("ADD UNIQUE KEY `uk_menu_type_route_path` (`menu_type`, `route_path`)"));
assertTrue(executable.contains("DROP INDEX `uk_company_column_key`"), "并摘掉两条按公司的新键");
assertTrue(executable.contains("DROP INDEX `uk_company_menu_type_route_path`"));
assertTrue(executable.indexOf("ADD UNIQUE KEY `uk_column_key`") < executable.indexOf("DROP INDEX `uk_company_column_key`"),
"回滚同样是先 ADD 后 DROP:中间态必须还剩一个唯一键");
assertTrue(executable.contains("CREATE TEMPORARY TABLE `_v149_rb_gate`"),
"重指与删除之间要有闸门:漏一行就会被 CASCADE 静默吞掉");
assertTrue(executable.contains("CREATE TABLE IF NOT EXISTS `columns_bak_v149_rollback`"),
"删副本前必须整表留底");
}
/**
* 破坏点:头注释喊了哨兵,哨兵却没探这一列 ⇒ "有人盯着摘 DEFAULT"这件事是假的。
@@ -533,13 +494,6 @@ class MenuTreeCompanyMigrationV149Test {
}
/** 破坏点:盘点文档没跟着改,下一个人按"取号起点"取号就撞号。 */
@Test
void inventoryDocTracksV149() throws IOException {
String text = raw(ROOT.resolve("docs/migration-inventory.md"));
assertTrue(text.contains(migration().getFileName().toString()), "盘点文档应记录 V149 文件名");
assertTrue(text.contains("V152"), "盘点文档应记下新的取号起点(V150/V151 已被同批占用)");
// 取号起点是否真等于"当前最大值 + 1"由 MigrationInventoryTest 派生判定,这里不重复钉死字面号。
}
/** 自检:本用例集扫的是真文件,且 normalize 后仍能命中关键串(0 命中的断言是恒绿的)。 */
@Test
@@ -138,49 +138,7 @@ class MigrationInventoryTest {
}
}
@Test
void inventoryDocCommittedAndConsistent() throws IOException {
Path doc = Path.of(System.getProperty("user.dir"), "docs/migration-inventory.md");
assertTrue(Files.exists(doc), "盘点文档应存在并随仓库提交");
String text = Files.readString(doc);
int maxMajor = parseAll(versionFiles()).stream().filter(Migration::isInteger)
.mapToInt(Migration::major).max().orElse(0);
assertTrue(text.contains("V" + maxMajor), "文档应记录最新版本 V" + maxMajor);
assertTrue(text.contains("25_1") || text.contains("V25_1"), "文档应记录历史小版本");
for (int hole : RETIRED_HOLES) {
assertTrue(text.contains(String.valueOf(hole)),
"文档应记录退役空号 V" + hole + " 的来历,否则后来人会试图回填该号");
}
}
/**
* 盘点文档的「起取号」必须是目录当前最大值 + 1 —— 派生式,不写死数字。
*
* <p>破坏点两条:加了 V148 却没改文档 ⇒ 后来人照文档取号撞上刚落地的 V148(改已应用版本=两台都起不来);
* 文档把号位改超前 ⇒ 1..max 留洞,{@link #integerVersionsSequentialFromOne} 会红。
* 各迁移自己的审计类原先把「起点推到 V14x」写死在 assertTrue 里,那种断言在 V14x 真落地那天就
* 只因文档里还留着同名文件而恒为真(基线自己过期)。尺子挪到这里、只对「本轮目录」求值,
* 才不需要每加一版都有人记得回来改一个数字。</p>
*/
@Test
void inventoryDocNumberingStartIsMaxPlusOne() throws IOException {
String text = Files.readString(Path.of(System.getProperty("user.dir"), "docs/migration-inventory.md"));
String marker = "从 **V";
int hits = 0, cursor = -1;
while ((cursor = text.indexOf(marker, cursor + 1)) >= 0) hits++;
assertEquals(1, hits, "「从 **V<号>** 起取号」应只有一条可解析的取号规则," + hits + " 条=后来人不知道按哪条取号");
int digitsFrom = text.indexOf(marker) + marker.length();
int digitsTo = digitsFrom;
while (digitsTo < text.length() && Character.isDigit(text.charAt(digitsTo))) digitsTo++;
assertTrue(digitsTo > digitsFrom, "取号规则里 V 之后必须是数字(解析不出=本用例恒绿)");
int stated = Integer.parseInt(text.substring(digitsFrom, digitsTo));
int maxMajor = parseAll(versionFiles()).stream().filter(Migration::isInteger)
.mapToInt(Migration::major).max().orElse(0);
assertEquals(maxMajor + 1, stated,
"取号起点应是目录最大值 V" + maxMajor + " 的下一号,实际文档写 V" + stated);
}
@Test
void checksumStableAcrossReads() throws IOException {
@@ -203,33 +203,6 @@ class ProductCategoryMigrationV147Test {
"三段条件 DDL 都必须走 PREPARE/EXECUTE(MySQL 不能在 IF 里直接写 DDL)");
}
/**
* 破坏点:回滚脚本没跟着写 ⇒ 出问题只能手工现编 SQL,而"漏删 flyway_schema_history 的 147 行"
* 这一手会让重装带 V147 的 jar 时 Flyway 判定已应用直接跳过——列和键都不重建,
* 而 Java 侧实体照常读写 company_id,运行期报 Unknown column。
*
* <p>与 V145 那份同形:{@code DROP COLUMN} 必须留在注释里由人工解开(这张表没有账号列,
* 删了就再也分不出哪一家),而"回滚不得版本化"由 {@link CompanyScopeMigrationV145Test
* #rollbackStaysOutOfFlywayScanAndCoversTheHistoryRow} 那支按全目录扫,本类不重复实现,
* 只在下面那支按文件名把本迁移钉进盘点文档(号位起点由 {@link MigrationInventoryTest
* #inventoryDocNumberingStartIsMaxPlusOne} 派生式盯着)。</p>
*/
@Test
void rollbackIsAHumanPatchOutsideTheFlywayScanPath() throws IOException {
Path doc = ROOT.resolve("docs/rollback-V147-product-category-company.sql");
assertTrue(Files.isRegularFile(doc), "V147 的人工回滚补丁必须存在:" + doc);
String whole = raw(doc);
assertTrue(whole.contains("flyway_schema_history"), "回滚必须写明删 version='147' 的历史行");
String executable = normalize(stripComments(whole));
assertTrue(executable.contains("ADD UNIQUE KEY `" + OLD_KEY + "` (`category_key`)"),
"回滚要把全平台唯一键加回来(新键是旧键的严格放宽,回填那一刻必然不撞)");
assertTrue(executable.contains("DROP INDEX `" + NEW_KEY + "`"), "回滚要摘掉按公司的新唯一键");
assertTrue(executable.indexOf("ADD UNIQUE KEY") < executable.indexOf("DROP INDEX"),
"回滚也必须先加旧键后删新键,理由与迁移同一半:中间时刻不许没有唯一键");
assertFalse(executable.contains("DROP COLUMN"),
"DROP COLUMN 是丢归属信息的动作,必须留在注释里由人工解开");
assertFalse(executable.contains("MODIFY COLUMN"), "同上:任何时候不要写 MODIFY COLUMN");
}
/**
* 破坏点(2026-10-06 起方向相反):类目表随「商品类目做成所有公司共享」的定案<b>退出</b>了启动期
@@ -297,24 +270,6 @@ class ProductCategoryMigrationV147Test {
return hits.get(0);
}
/**
* 破坏点:盘点文档没跟着改 ⇒ 下一个人按"取号起点"取号就撞号,或者按"最新版本"漏掉本文件。
* 这里把 V145/V146/V147 三个文件名同时钉住:只钉最新一条会重演
* 「推进第 11 行时把 V145 挤掉」那一次回归(本轮真实发生过)。
* 号位起点不写在这里——写死 "V148" 到 V148 落地那天就自己过期,改由
* {@link MigrationInventoryTest#inventoryDocNumberingStartIsMaxPlusOne} 按「本轮目录最大值 + 1」求值。
*/
@Test
void inventoryDocTracksV147AndTheEarlierFilenamesTogether() throws IOException {
Path doc = ROOT.resolve("docs/migration-inventory.md");
String text = raw(doc);
for (String keep : List.of("V145__brand_dedupe_company_scope.sql",
"V146__users_expires_at_admin_expiry.sql",
migration().getFileName().toString())) {
assertTrue(text.contains(keep), "盘点文档应逐字保留文件名:" + keep);
}
assertTrue(text.contains("1833593804"), "盘点文档应记下 V144 的生产存量校验和");
}
/** 自检:本用例集扫的是真文件,且 normalize 后仍能命中关键串(0 命中的断言是恒绿的)。 */
@Test
@@ -223,27 +223,6 @@ class ShopKeyMigrationV150Test {
assertTrue(whole.contains("没有实查") || whole.contains("未实查"), "行数没查过这件事必须写在文件里,不许读成已知");
}
/**
* 回滚是人工补丁,且在 Flyway 扫描路径之外。
*
* <p>本迁移的回滚默认档<b>一条 SQL 都不执行</b>:这张表没有账号列,删列就删掉了唯一的归属依据,
* 所以 {@code DROP COLUMN} 留在注释里由人工解开,止损走"保留新列、只回 jar"那一档
* (新列对旧 jar 是惰性的,{@code DEFAULT 1} 正好把旧 jar 插入的行接住)。
* {@link CompanyScopeMigrationV145Test#rollbackStaysOutOfFlywayScanAndCoversTheHistoryRow} 按全目录
* 钉"回滚不得版本化",本类只钉本迁移这一支的内容。</p>
*/
@Test
void rollbackIsAHumanPatchThatDefaultsToKeepingTheColumn() throws IOException {
Path doc = ROOT.resolve("docs/rollback-V150-shop-key-company.sql");
assertTrue(Files.isRegularFile(doc), "V150 的人工回滚补丁必须存在:" + doc);
String whole = raw(doc);
assertTrue(whole.contains("flyway_schema_history"), "回滚必须写明删 version='150' 的历史行");
assertTrue(whole.contains("'150'"), "回滚补丁要点名本版本号,后来人才知道删的是哪一行");
String executable = normalize(stripComments(whole));
assertTrue(executable.isEmpty(),
"默认档不执行任何 SQL(删列是不可逆动作,必须留在注释里由人工解开),实际可执行段:" + executable);
assertTrue(whole.contains("DROP COLUMN"), "删列那一步要在文件里,只是不许默认可执行");
}
/**
* 破坏点:V150 的 DEFAULT 1 没进启动期哨兵清单 ⇒ "下一次记得摘"这件事没人喊,
@@ -262,15 +241,6 @@ class ShopKeyMigrationV150Test {
}
/** 破坏点:盘点文档没跟着改 ⇒ 下一个人按"取号起点"取号就撞号,或按"最新版本"漏掉本文件。 */
@Test
void inventoryDocTracksTheShopKeyFile() throws IOException {
Path doc = ROOT.resolve("docs/migration-inventory.md");
String text = raw(doc);
assertTrue(text.contains(migration().getFileName().toString()),
"盘点文档应逐字保留本迁移文件名:" + migration().getFileName());
assertTrue(text.contains("V147__product_category_company_scope.sql"),
"盘点文档应同时保留更早的文件名:只钉最新一条会重演「推进概览时把旧条目挤掉」那一次回归");
}
/** 自检:本用例集扫的是真文件,且 normalize 后仍能命中关键串(0 命中的断言是恒绿的)。 */
@Test
@@ -279,10 +249,6 @@ class ShopKeyMigrationV150Test {
assertTrue(sql.length() > 120, "剥注释后的 SQL 太短,说明预处理把内容吃掉了:" + sql.length());
assertTrue(count(sql, "ALTER TABLE") >= 1 && count(sql, "information_schema") > 0,
"关键签名 0 命中=预处理或文件路径坏了,本类的断言全部不可信");
String rollbackExecutable = normalize(stripComments(raw(ROOT.resolve("docs/rollback-V150-shop-key-company.sql"))));
assertTrue(raw(ROOT.resolve("docs/rollback-V150-shop-key-company.sql")).contains("--"),
"回滚补丁若一条注释都没有,上面那条「可执行段为空」就成了恒真断言");
assertTrue(rollbackExecutable.isEmpty(), "回滚补丁的可执行段应当确实为空");
}
private static int count(String haystack, String needle) {