Files
crawler-plugin/backend-java/docs/plans/01-plan-frontend-api-adapter.md
T
huangzd1997 49c3fc1491 docs(仓库): 规划文档改为入库,落盘品牌库/去重库每公司一套二期方案
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」,
代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红),
跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
2026-10-04 13:51:16 +08:00

430 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` 全绿。