From 000542a036a77b8c0801c613677f32f3ee2a187c Mon Sep 17 00:00:00 2001
From: Zain <lhlyzh@outlook.com>
Date: Wed, 18 Feb 2026 22:22:39 +0800
Subject: [PATCH] docs: add P1 enhancements design

---
 ...26-02-18-p1-renamer-enhancements-design.md | 91 +++++++++++++++++++
 1 file changed, 91 insertions(+)
 create mode 100644 docs/plans/2026-02-18-p1-renamer-enhancements-design.md

diff --git a/docs/plans/2026-02-18-p1-renamer-enhancements-design.md b/docs/plans/2026-02-18-p1-renamer-enhancements-design.md
new file mode 100644
index 0000000..f2c76ce
--- /dev/null
+++ b/docs/plans/2026-02-18-p1-renamer-enhancements-design.md
@@ -0,0 +1,91 @@
+# P1 Enhancements Design (冲突检测 / 自适应节流 / 崩溃恢复)
+
+**Date:** 2026-02-18
+
+## Goal
+在当前扩展中补齐三项 P1 能力：
+1) 执行前的外部冲突检测 + 策略选择；
+2) 自适应节流（仅拉长请求间隔）；
+3) 崩溃恢复流程在面板打开时可触达。
+
+## Scope
+- 覆盖三项能力的 UI 交互与核心逻辑接入。
+- 保持现有执行引擎并发语义不变。
+- 不引入新平台适配或规则类型。
+
+## Non-goals
+- 不调整最大并发（仅动态调整 requestInterval）。
+- 不改变现有规则引擎与 preview 逻辑。
+- 不引入新的 UI 页面，仅在现有面板内提示/弹窗。
+
+## Decisions
+- 冲突检测采用“执行前统一检测 + 策略选择”。
+- 自适应节流只拉长请求间隔，不调并发。
+- 崩溃恢复在面板打开时自动检测并弹窗。
+
+## Architecture
+
+### 1) 外部冲突检测（UI 执行前）
+- 接入点：`file-selector-panel.ts` 的 `handleExecute()`。
+- 流程：
+  1. 计算当前 `selectedFiles` + `newNameMap`。
+  2. 调用 `ConflictDetector.detectConflicts(files, newNames)`。
+  3. 若有冲突 -> 弹窗 `showConflictResolutionDialog()` 选择策略。
+  4. 根据策略 `resolveConflicts(...)` 生成 `resolvedNames`。
+  5. 用 `resolvedNames` 生成任务列表，并交给 `BatchExecutor` 执行。
+- 错误兜底：冲突检测失败时提示用户是否继续执行（默认取消）。
+
+### 2) 自适应节流（BatchExecutor 内）
+- 新增 `adaptiveIntervalFactor`（初始 1.0）。
+- `waitForRequestSlot()` 使用 `requestInterval * factor` 作为实际间隔。
+- 在 `processTask` 识别“限流/重试信号”时上调 factor（例如 x1.5, capped）。
+- 识别策略：基于错误对象特征（如 `code/errno`、错误名或消息包含“TooManyRequests/429/频繁”等）。
+- 可选回落：连续成功 N 次后缓慢回落 factor（保持稳定性）。
+
+### 3) 崩溃恢复接入
+- 面板打开时调用 `initCrashRecovery(adapter)`。
+- 执行开始前调用 `crashRecovery.saveOperationState` 写入任务与规则。
+- 执行中根据进度调用 `crashRecovery.markAsCompleted/markAsFailed`。
+- 执行完成/取消后 `crashRecovery.clearOperationState`。
+
+## Data Flow
+
+### 冲突检测
+```
+用户点击执行
+  -> 构造 newNames
+  -> detectConflicts
+  -> showConflictResolutionDialog
+  -> resolveConflicts
+  -> BatchExecutor(tasks)
+```
+
+### 自适应节流
+```
+processTask -> detectBackoffSignal(error)
+  -> increase adaptiveIntervalFactor
+  -> waitForRequestSlot uses interval * factor
+```
+
+### 崩溃恢复
+```
+面板打开 -> initCrashRecovery(adapter)
+执行开始 -> saveOperationState
+执行中 -> markAsCompleted/markAsFailed
+完成/取消 -> clearOperationState
+```
+
+## Error Handling
+- 冲突检测失败：提示“检测失败，是否继续执行？”默认取消。
+- 策略选择取消：终止执行。
+- 恢复失败：提示失败原因并清理恢复状态。
+
+## Testing Strategy (TDD)
+- 新增单元测试：
+  - 冲突检测/策略解析生成的任务是否正确。
+  - 自适应节流：触发 backoff 信号后间隔增长。
+- 回归：原有执行流程应保持一致（并发/暂停/取消不变）。
+
+## Rollout
+- 功能在现有面板内呈现，无需迁移数据。
+- 若出现问题，可通过配置开关回退（如将 backoff 逻辑禁用）。