`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
21 KiB
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)
- test_endpoints_all_modules_present — 17 模块键齐全
- test_endpoint_path_format — 每个端点以 /api/ 开头
- test_no_newapi_prefix_in_endpoint — 不含 /newApi/api 前缀
- test_progress_batch_paths_match_controllers — progress 端点与 Java controller 路径一致(快照)
- test_download_paths_match — download 端点模式
- test_endpoints_frozen_snapshot — 常量表 JSON 快照(防漂移)
- test_endpoint_values_no_trailing_slash — 无尾斜杠
- test_endpoint_keys_convention — 键名 snake_case 或小驼峰一致性
TDD 流程
- 写上述全部测试 →
npx vitest run src/shared/api/__tests__/endpoints.test.ts确认 RED(文件不存在) - 实现 endpoints.ts → 确认 GREEN
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)
- test_build_url_prefixed — 输出以 /newApi/api 开头
- test_build_url_with_query — query 参数正确编码
- test_build_url_no_query — 无 query 不加 ?
- test_build_url_query_encoding — 特殊字符编码(空格/中文/&)
- test_build_url_empty_query_object — 空对象不加 query
- test_build_url_trailing_slash_endpoint — endpoint 尾斜杠规范化
- test_build_url_undefined_query — undefined 安全
- 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)
- test_call_java_success_unwraps — JavaApiResponse 解包出 data
- test_call_java_legacy_msg_unwraps — LegacyApiSuccess(msg)解包
- test_call_java_success_false_throws — success=false 抛错
- test_call_java_message_precedence — message 优先于 msg 于 error
- test_call_java_non_wrapped_passthrough — 非包装对象直通
- test_call_java_null_data — success 且 data=null 返回 null
- test_call_java_network_error — 网络错误抛出 Error
- test_call_java_http_error_status — HTTP 错误状态提取 message
TDD 流程 / 验证方法
同上。
任务 4:extractErrorMessage 导出与三字段覆盖
所属模块:01 适配层 依赖:3 预估:8-15 分钟
功能点要求
http.ts 的 extractErrorMessage 提升为命名导出(保持内部逻辑);错误对象覆盖 error/message/msg 三字段;字符串响应体回退;无字段回退 axios message / 通用文案。
测试用例(≥8)
- test_extract_error_field — error 字段优先
- test_extract_message_field — message 字段
- test_extract_msg_field — msg 字段
- test_extract_error_precedence — error > message > msg
- test_extract_string_body — 字符串响应体
- test_extract_fallback_message — 无字段回退
- test_extract_axios_non_error — 非 AxiosError
- 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)
- test_normalize_lower_to_upper — success→SUCCESS
- test_normalize_mixed_case — rUnNiNg→RUNNING
- test_normalize_with_hyphen — in-progress→IN_PROGRESS
- test_normalize_null — null 安全
- test_normalize_undefined — undefined 安全
- test_normalize_empty_string — 空串返回空
- test_normalize_unknown_passthrough — 未知值(SYNCING)原样
- test_normalize_whitespace_padded — 首尾空白清理
TDD 流程 / 验证方法
同上。
任务 6:isTerminalStatus() 终态判定
所属模块:01 适配层 依赖:5 预估:8-15 分钟
功能点要求
isTerminalStatus(status, extras?):默认 SUCCESS/FAILED 为终态;可扩展(CANCELLED);先经 normalizeStatus;空值非终态。
测试用例(≥8)
- test_terminal_success — SUCCESS true
- test_terminal_failed — FAILED true
- test_terminal_lowercase — success true(归一后)
- test_terminal_pending_false — PENDING false
- test_terminal_null_false — null false
- test_terminal_cancelled_default_false — CANCELLED 默认 false
- test_terminal_cancelled_extended_true — 传 extras 后 true
- 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)
- test_download_url_user_id — 追加 user_id
- test_download_url_no_user_id — 无 userId 不追加
- test_download_url_existing_user_id — 已含不重复
- test_resolve_download_fresh_priority — freshDownloadUrl 优先
- test_resolve_download_fallback — 缺失回退 downloadUrl
- test_resolve_download_both_blank — 都空返回空
- test_download_url_query_merge — 已有 query 合并
- test_resolve_download_null_safe — null 安全
TDD 流程 / 验证方法
同上。
任务 8:callJava 透传 AbortController
所属模块:01 适配层 依赖:3 预估:8-15 分钟
功能点要求
callJava 支持 { signal }:axios 透传;signal 已中止时请求立即失败(AbortError);页面卸载可取消 in-flight。
测试用例(≥8)
- test_signal_abort_before_send — 发送前中止立即拒绝
- test_signal_abort_mid_request — 进行中中止拒绝
- test_signal_passthrough — signal 传到 axios 配置
- test_signal_abort_error_message — 错误消息含 AbortError 特征
- test_signal_not_provided — 无 signal 正常
- test_abort_after_resolve — 完成后 abort 无副作用
- test_abort_rejects_promise — 中止拒绝 Promise
- test_signal_multiple_calls_independent — 多次调用互不影响
TDD 流程 / 验证方法
同上。
任务 9:进度类请求默认超时
所属模块:01 适配层 依赖:3 预估:8-15 分钟
功能点要求
进度类 API 函数(get*TaskProgressBatch)默认 10s 超时(现有 30s);可通过配置覆盖;非进度请求保持 30s。
测试用例(≥8)
- test_progress_timeout_default — 进度请求 10s
- test_progress_timeout_override — 显式覆盖生效
- test_non_progress_timeout_30s — 非进度 30s
- test_timeout_config_name — 配置键存在且为正数
- test_progress_timeout_minimum — 非法配置钳制
- test_override_via_options — 函数级 options 覆盖
- test_timeout_zero — 0 钳制为正数
- 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)
- test_type_task_status_assignable — SUCCESS 等可赋值
- test_type_result_file_phase_all_optional — 字段全部可选
- test_type_page_result_shape — 分页字段结构
- test_type_progress_batch_shape — 批量进度结构
- 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)
- test_dedupe_run_url — runDedupe 请求 URL 正确
- test_dedupe_run_method_payload — POST + 请求体
- test_dedupe_history_url — history URL/method
- test_dedupe_delete_history — delete URL/method
- test_dedupe_download_url — download URL + user_id
- test_dedupe_signature_unchanged — 参数顺序与类型快照
- test_dedupe_export_compat — 旧路径 import 可用
- 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)
- test_reexport_all_symbols — 全部导出符号可从 java-modules 获取
- test_reexport_type_compiles — 类型 import 可用
- test_reexport_no_duplicate — 无重复导出
- test_reexport_build_passes — vue-tsc 全量通过
- test_reexport_import_compat — 各页面旧 import 快照编译
- test_reexport_no_dead_body — 原函数体不存在(防残留)
- test_reexport_runtime_symbols — 运行时函数可调用
- 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)
- test_defaults_filled — 缺省字段补齐
- test_existing_values_kept — 已有值不覆盖
- test_file_ready_true_preserved — true 保留
- test_partial_input — 部分字段缺失补齐
- test_null_input_safe — null 安全
- test_defaults_idempotent — 二次调用幂等
- test_status_success_maps_ready — fileStatus=SUCCESS 且 fileReady 缺失 → ready true
- 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)
- test_snapshot_helper_url — helper 断言 URL
- test_snapshot_helper_method — 断言 method
- test_snapshot_helper_params — 断言 query
- test_snapshot_helper_body — 断言请求体
- test_snapshot_all_modules_covered — 全部已拆模块注册
- test_snapshot_fail_message — 失败信息含 URL 上下文
- test_snapshot_allowlist — 白名单外字段报错
- 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)
- test_schema_task_required_fields — 必填字段声明
- test_schema_result_required_fields — 结果字段
- test_checker_passes_valid — 合法对象通过
- test_checker_missing_required — 缺必填报 missing
- test_checker_wrong_type — 类型不符报 type
- test_checker_batch — 批量检查
- test_schema_registered_modules — 各模块 schema 注册齐全
- test_schema_versioned — schema 版本标记
TDD 流程 / 验证方法
同上。
任务 28:死代码清理
所属模块:01 适配层 依赖:24 预估:8-15 分钟
拆分后 grep 确认 java-modules.ts 无残留函数体、无未引用导出;删除确认死代码;npm run build + 全量测试验证。
测试用例(≥8,测试为验证型)
- test_no_unexported_duplicates — 无重复导出
- test_build_typecheck — vue-tsc 通过
- test_full_vitest_green — 全量测试绿
- test_no_console_debug_left — 无调试日志残留
- test_no_unused_import — 无未用 import(lint)
- test_entry_points_compile — 17 个入口编译
- test_bundle_build — vite build 产出
- test_git_diff_scope — 变更仅限 api 目录
TDD 流程 / 验证方法
npm run build + npx vitest run 全绿。