docs: import wiki at afc651f75a3a

T-260.-.md

@@ -0,0 +1,251 @@
+<!-- docs-wiki-sync:docs/tasks/T-260.md@afc651f75a3abc2676bb13aa8a80f6aa6a25a72e -->
+> 同步来源：[`docs/tasks/T-260.md`](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/tasks/T-260.md) · commit `afc651f75a3a`
+
+---
+id: T-260
+title: 可配置操作节奏与失败停顿并联动轮次预算
+phase: 2
+deps:
+  - T-259
+status: DOING
+created: 2026-07-31
+context_ref: 21dc617
+work_branch: null
+write_paths:
+  - docs/tasks/T-260.md
+  - docs/current-state.md
+  - android-buyer/app/src/main/**
+  - android-buyer/app/src/test/**
+---
+
+## 问题 / 背景
+
+采购人员反馈：因下单数量多、操作速度快，拼多多账号已被禁用。需要把自动化的操作节奏
+放慢，并允许按实际情况调整。
+
+当前节奏写死在代码里：
+
+```kotlin
+class PinduoduoActionPacer(
+    private val minimumMillis: Long = DEFAULT_MINIMUM_MILLIS,   // 1_000
+    private val maximumMillis: Long = DEFAULT_MAXIMUM_MILLIS,   // 3_000
+    ...
+)
+```
+
+构造参数本就存在，但两个驱动（`AndroidPinduoduoCandidateDriver`、
+`AndroidPinduoduoImageSearchDriver`）都以 `PinduoduoActionPacer()` 硬编码默认值实例化。
+
+### 三个时间常量互相耦合，不能单独调
+
+| 常量 | 当前值 |
+| --- | --- |
+| 单次成功动作后停顿 | 1–3 秒随机 |
+| 单轮候选浏览超时 `browseTimeoutMillis` | 100 秒（第 1、2 轮）/ 45 秒（第 3 轮） |
+| 离线执行授权 | 30 分钟（服务端下发） |
+
+处理一个候选约需 6 次受限速动作（打开候选、开规格、选颜色、选尺码、关规格、返回）。
+当前均值 2 秒即约 12 秒/候选，100 秒预算实际只够 2 个候选——这与真机实测
+`attempts=2` 完全吻合：**不是没有候选可试，是时间不够**。
+
+若只把停顿改成 5–10 秒（均值 7.5 秒），单候选升至约 45 秒，100 秒预算**连 1 个候选都
+未必跑得完**，三轮下来可能一个都采不到。**单独放慢 pacer 会让结果更差，必须与轮次
+预算联动调整。**
+
+### 失败动作完全不停顿
+
+```kotlin
+private suspend fun pacedAction(action: suspend () -> Boolean): Boolean {
+    val succeeded = action()
+    if (succeeded) { actionPacer.pause() }   // 失败时直接返回，无停顿
+    return succeeded
+}
+```
+
+动作失败时以最快速度连续重试。从行为特征看，这比「成功动作间隔短」更像机器人——
+正常人点不动会停顿或放弃。这是现存缺陷，本任务一并修复。
+
+### 明确的能力边界
+
+**本任务不是绕过风控。** 遇到验证码、登录失效、风控提示时的安全停止行为一律不变，
+仍然立即停止并上报。这里只调整自身发起动作的密度。
+
+同时如实记录：**放慢节奏未必能解决封号问题**。平台风控通常综合订单量、支付方式、
+地址复用、账号年龄和设备指纹等信号，操作间隔只是其中权重可能较低的一项。本任务提供
+可调节能力，不承诺规避账号风险。降低单位时间订单总量属于运营决策，不在本任务范围。
+
+## 关联需求与交互
+
+- 功能：F-005、F-009
+- 用户故事：US-004、US-009
+- 交互：Roubao 设置页新增节奏配置项，沿用现有 `SettingsManager` 与 `SettingsScreen`
+- 架构/API：**后端零改动**；执行节奏属设备本地自治配置
+
+## 行为契约
+
+### 一、节奏可配置且设备本地自治
+
+在现有 `SettingsManager` 中新增操作停顿区间配置（下限毫秒、上限毫秒），由
+`SettingsScreen` 提供编辑入口。两个驱动改为读取该配置构造 `PinduoduoActionPacer`。
+
+**必须是设备本地设置。** 依据 F-009 第 2 条「后台任务也不能覆盖 App 的本地设置」，
+后端不得下发、代理或覆盖执行节奏；任务 payload 中出现相关字段一律忽略。
+
+默认值保持 `1000` / `3000` 不变，未修改设置的设备行为与本任务前完全一致。
+
+### 二、取值校验
+
+| 约束 | 值 |
+| --- | --- |
+| 下限最小值 | `500` 毫秒（防止设为 0 等同关闭限速） |
+| 上限最大值 | `30_000` 毫秒（防止单个动作拖垮整轮） |
+| 不变式 | `min <= max`（`PinduoduoActionPacer.init` 已有 `require`，不得移除） |
+
+非法输入在设置页拒绝保存并给出可修复提示，不得静默截断或回退到默认值。
+
+### 三、失败动作同样停顿
+
+`pacedAction` 改为**无论成功失败都停顿**，使用同一区间。
+
+不在本任务实现指数退避——退避会改变重试语义并影响既有超时预算，如需另开任务。
+
+### 四、轮次预算联动
+
+`browseTimeoutMillis` 改为可配置（沿用 `PinduoduoImageCandidateRoundPolicy` 的分轮
+结构），默认值保持 `100_000` / `45_000` 不变。
+
+**必须实现可行性校验**：保存设置时按「单候选约 6 次受限速动作」估算，若配置组合导致
+第 1 轮预算连 1 个候选都无法完成，拒绝保存并提示。估算系数以常量形式集中定义，便于
+后续按实测调整。
+
+### 五、不得突破离线执行授权
+
+离线执行授权 30 分钟由服务端下发，**本任务不修改，也不请求延长**。
+
+保存设置时必须校验最坏情况总时长（三轮预算之和加固定余量）不超过执行授权窗口的
+**60%**，超出则拒绝保存并提示。这样可以避免放慢节奏后任务在上传结果前就撞上授权
+到期——该故障刚由 T-259 修复过，不应因配置不当重新引入。
+
+### 六、可审计
+
+本次执行实际生效的停顿区间与轮次预算，必须随 T-254 的诊断 message 机制记录，键名：
+
+```
+paceMin=<n> paceMax=<n> browseTimeout=<n>
+```
+
+沿用既有脱敏口径：只记数值，不记任何商品信息。Admin 需要能判断某次任务是用什么节奏
+跑的。
+
+### 七、安全边界一律不变
+
+验证码、登录失效、风控提示、未知页面、订单确认页和支付边界的安全停止行为**完全不
+改**。本任务只延长自身动作之间的间隔，不改变任何停止条件。
+
+## 方案
+
+1. `SettingsManager` 新增停顿下限、上限和三轮 `browseTimeoutMillis` 配置及校验。
+2. `SettingsScreen` 增加编辑入口，非法组合拒绝保存并给出具体原因。
+3. `AndroidPinduoduoCandidateDriver`、`AndroidPinduoduoImageSearchDriver` 改为按配置
+   构造 `PinduoduoActionPacer`。
+4. `pacedAction` 改为成功与失败均停顿。
+5. `PinduoduoImageCandidateRoundPolicy` 改为接受配置值，默认值不变。
+6. 新增可行性校验与授权窗口占用校验，估算系数集中为常量。
+7. 生效配置并入 `CandidateSearchDiagnostics`，追加三个键。
+8. 单测覆盖：默认值行为与本任务前一致、边界值接受与拒绝、`min > max` 拒绝、
+   失败动作也停顿、可行性校验拒绝过慢组合、授权窗口 60% 校验、诊断键格式、
+   后端下发字段被忽略。
+
+## 验收要点
+
+- [x] 未修改设置时，停顿区间与轮次预算与本任务前逐值一致，有回归测试。
+- [x] 下限低于 500 毫秒、上限高于 30 秒、`min > max` 均被拒绝并给出可修复提示。
+- [x] 失败动作同样触发停顿，有单测证明。
+- [x] 配置组合导致第 1 轮跑不完 1 个候选时拒绝保存。
+- [x] 三轮预算之和加余量超过执行授权窗口 60% 时拒绝保存。
+- [x] 诊断 message 出现 `paceMin` / `paceMax` / `browseTimeout` 且不含商品信息。
+- [x] 后端 payload 中的节奏字段被忽略，不覆盖本地设置，有单测证明。
+- [x] 验证码、风控、登录失效、未知页面和支付边界的安全停止行为未改变，有回归测试。
+- [x] Android Debug/Release 单测、`lintDebug`、`assembleDebug`、`assembleRelease` 全部通过。
+- [ ] 真机验证：把停顿调到较慢档位跑一条任务，从 Admin 读到实际生效的三个键，并确认
+      任务在授权窗口内完成上传。
+
+## 边界
+
+- **不绕过风控**：验证码、登录失效、风控提示、未知页面的安全停止一律不改。
+- 不修改离线执行授权时长，不请求续期，不改后端任何代码或 API 契约。
+- 不实现指数退避或自适应节奏。
+- 不改候选卡片识别、签名算法、跨轮去重、SKU 硬约束或价格解析。
+- 不改 T-254/T-255/T-257 诊断字段语义、T-256 提交门槛、T-258 后端校验、
+  T-259 安全停止补报。
+- 不改下单 dry-run、订单提交、授权价格策略或支付边界。
+- 不新增第四轮搜索，不改三轮门禁。
+- 不承诺本任务能规避账号封禁；降低单位时间订单总量属运营决策，不在范围内。
+
+## 执行记录
+
+### 2026-07-31
+
+状态保持 `DOING`。代码和自动化验证已完成，最终真机验收未执行，不能标记 `DONE`。
+
+修改：
+
+- `SettingsManager` 新增设备本地 `PinduoduoPacingSettings`，持久化停顿下限、上限和
+  三轮候选浏览超时。默认值保持 `1000 / 3000 / 100000 / 100000 / 45000`。
+- 设置页沿用现有 Compose 设置项和对话框，新增五个有标签的毫秒整数输入；空值、
+  非数字、范围或组合错误均留在对话框内显示可修复提示，保存失败不关闭对话框。
+- 校验系数集中为命名常量：每候选 6 次受限速动作、每轮 50 秒图片搜索固定步骤预算、
+  三轮、120 秒执行余量、30 分钟授权参考窗口和 60% 上限。第 1 轮不足一个候选的最坏
+  动作时长时拒绝；三轮浏览超时、三轮固定步骤预算和余量合计超过 60% 时拒绝。
+- `MainActivity` 在每轮开始前只从 `SettingsManager` 捕获本地快照，以该快照构造两个
+  driver 的 `PinduoduoActionPacer`，并把当前轮超时传给既有 round policy。任务 payload
+  没有配置入口，额外 `pacing` 字段由客户端任务解析忽略。
+- 两个 driver 的布尔动作统一为成功或失败都暂停一次；未增加指数退避、自适应节奏、
+  新重试或续期逻辑。
+- `CandidateSearchDiagnostics` 在实际自动轮次 message 末尾追加
+  `paceMin=<n> paceMax=<n> browseTimeout=<n>`，只包含数值。
+- 新增/扩展单测，覆盖默认回归、边界与可修复错误、第 1 轮单候选可行性、三轮 60%
+  上限及等号边界、失败动作停顿、自定义 round timeout、诊断格式和后台 payload
+  pacing 字段忽略。既有验证码、登录失效、风控、未知页、订单确认和支付边界测试均
+  随 Debug/Release 全套单测通过；相关分类器、停止条件和授权时长未修改。
+- UI 实现参考 `ui-ux-pro-max` 的移动表单建议，保留 Material 原生控件、可见标签、
+  就地错误与现有主题；没有引入新视觉系统。
+
+命令与结果（工作目录 `D:\chengma\cmroubao\android-buyer`，Windows PowerShell）：
+
+```powershell
+.\gradlew.bat testDebugUnitTest --tests 'com.roubao.autopilot.data.PinduoduoPacingSettingsTest' --tests 'com.roubao.autopilot.pinduoduo.PinduoduoActionPacerTest' --tests 'com.roubao.autopilot.pinduoduo.PinduoduoImageCandidateRoundPolicyTest' --tests 'com.roubao.autopilot.procurement.CandidateSearchDiagnosticsTest' --tests 'com.roubao.autopilot.procurement.ProcurementApiClientTest'
+```
+
+首次运行：失败，26 项中 1 项失败；新诊断测试错误地把既有固定键
+`skuMismatch` 当成商品信息。修正断言为拒绝商品文字、`goods_id` 和 URL 后以同一
+命令重跑：通过，`BUILD SUCCESSFUL`。
+
+```powershell
+.\gradlew.bat testDebugUnitTest
+.\gradlew.bat testReleaseUnitTest
+.\gradlew.bat lintDebug
+.\gradlew.bat assembleDebug
+.\gradlew.bat assembleRelease
+```
+
+结果：五条均 `BUILD SUCCESSFUL`。Debug/Release 各 272 项单测，0 failure、0 error、
+0 skipped；lint 报告生成成功；Debug/Release APK 构建成功。
+
+根目录只读/收尾命令：
+
+```powershell
+git diff --check
+git status --short
+```
+
+结果：`git diff --check` 通过；修改仅位于本任务 `write_paths`。开工前已有的
+`.playwright-mcp/`、本地 JSON、PNG 和账号文本等未跟踪文件未读取、修改或删除。
+所有本任务修改/新增文件已检查为 LF。未运行 `init.ps1`，未运行任何 Go/backend
+命令，未修改 `backend-api`，未 commit、未 push。
+
+Blocker：
+
+- 仍需采购人员在测试设备把节奏调到较慢档位跑一条任务，从 Admin 验证三个诊断键
+  与实际值一致，并确认任务在授权窗口内完成上传。该真机证据缺失，因此任务保持
+  `DOING`。