chengmaandClaude Opus 4.8
541dfab967
建立 harness coding 文档体系并完成一致性修正： - 文档集：AGENTS.md/CLAUDE.md 入口，docs/00-05 规范文档， api.md/routes.md/current-state.md，根目录 tasks.md/progress.md。 - 一致性补丁：TaskStatus 中英映射、支付模式收敛为全局 PaymentConfig、 执行器级 RunnerState 暂停语义、progress 与 current-state 职责边界。 - 工程地基：新增 .gitignore，忽略运行产物/敏感数据与 .claude 本地设置。 - 合规留痕：02 需求新增平台规则与合规风险条目。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
199 lines
5.2 KiB
Markdown
199 lines
5.2 KiB
Markdown
# 本地模块合约
|
|
|
|
> 本项目 MVP 没有后端 API。本文定义本地模块之间的目标接口形状，避免 GUI、Excel、Android 自动化逻辑互相耦合。
|
|
|
|
## 通用约定
|
|
|
|
- 模块间传递结构化对象，不传裸字典到处拼字段。
|
|
- 错误使用明确异常或结果对象，不能静默返回 `None`。
|
|
- 时间统一使用本地时间并在写入 Excel 时格式化为可读字符串。
|
|
- 所有自动化步骤必须携带 `task_id`，方便日志关联。
|
|
|
|
通用错误对象建议：
|
|
|
|
```text
|
|
TaskError
|
|
code: str
|
|
message: str
|
|
step: str
|
|
screenshot_path: str | None
|
|
```
|
|
|
|
## Excel 模块
|
|
|
|
### `load_tasks(file_path) -> list[OrderTask]`
|
|
|
|
职责：
|
|
|
|
- 打开 `.xlsx` 文件。
|
|
- 校验固定表头。
|
|
- 跳过完全空行。
|
|
- 将每一行转换为 `OrderTask`。
|
|
|
|
失败：
|
|
|
|
- 缺少必填列时抛出表头错误。
|
|
- 必填字段为空、数量非法时返回行级错误或阻止导入，具体交互实现时确认。
|
|
|
|
### `create_result_path(source_path) -> result_path`
|
|
|
|
职责：
|
|
|
|
- 根据原文件路径生成默认结果文件名。
|
|
- 默认格式：`原文件名_执行结果.xlsx`。
|
|
- 不覆盖原始 Excel。
|
|
|
|
### `save_task_result(result_path, task) -> None`
|
|
|
|
职责：
|
|
|
|
- 写入指定任务行的状态、订单号、失败原因、执行时间、截图路径。
|
|
- 每条任务完成、失败或进入人工节点后尽快保存。
|
|
|
|
## GUI 模块
|
|
|
|
### `MainWindow.import_excel()`
|
|
|
|
职责：
|
|
|
|
- 让用户选择 Excel 文件。
|
|
- 调用 Excel 模块读取任务。
|
|
- 在表格中展示任务。
|
|
|
|
### `MainWindow.start_selected_tasks()`
|
|
|
|
职责：
|
|
|
|
- 获取当前勾选任务。
|
|
- 按表格顺序交给任务执行器。
|
|
- 执行中禁用重复启动。
|
|
|
|
### `MainWindow.update_task_status(task)`
|
|
|
|
职责：
|
|
|
|
- 更新表格中的状态、订单号、失败原因。
|
|
- 刷新日志和截图区域。
|
|
|
|
## 任务执行器
|
|
|
|
### `TaskRunner.run(tasks) -> None`
|
|
|
|
职责：
|
|
|
|
- 按顺序执行任务。
|
|
- 对每条任务调用拼多多流程模块。
|
|
- 发出状态变化事件给 GUI。
|
|
- 每条任务结束后触发 Excel 回写。
|
|
|
|
### `TaskRunner.pause() -> None` / `TaskRunner.resume() -> None`
|
|
|
|
职责：
|
|
|
|
- `pause()`：把**执行器**状态置为 `PAUSED`，当前任务跑完安全边界后不再领取下一条（执行器级，见 [`04-architecture.md`](04-architecture.md) §4.5）。
|
|
- `resume()`：执行器回到 `RUNNING`，从下一条勾选任务继续。
|
|
- 二者只改 `RunnerState`，不改任何单条任务的 `status`。
|
|
|
|
### `TaskRunner.pause_for_manual(task, reason) -> None`
|
|
|
|
职责：
|
|
|
|
- 将单条任务标记为 `待人工`（任务级，区别于上面的执行器 `pause()`）。
|
|
- 通知 GUI 和运营。
|
|
- 等待用户点击继续、失败或取消。
|
|
|
|
### `TaskRunner.set_payment_config(config: PaymentConfig) -> None`
|
|
|
|
职责：
|
|
|
|
- 接收 GUI 设置的**全局批次级**支付配置（`PaymentConfig`，定义见 [`04-architecture.md`](04-architecture.md) §4.4）。
|
|
- `mode=AUTO` 时配置必须包含单笔金额上限；建议包含批次金额上限和价格允许偏差。
|
|
- 不允许在未配置金额上限时把 `mode` 设为 `AUTO`。
|
|
- 支付模式是全局的，不在单条 `OrderTask` 上保存按行开关。
|
|
|
|
### `TaskRunner.cancel() -> None`
|
|
|
|
职责：
|
|
|
|
- 尽快停止后续任务。
|
|
- 当前任务如果不能安全中断，应标记为 `待人工` 或 `已取消`。
|
|
|
|
## Android 设备模块
|
|
|
|
### `DeviceManager.connect() -> DeviceInfo`
|
|
|
|
职责：
|
|
|
|
- 检查 ADB 设备。
|
|
- 建立 `uiautomator2` 连接。
|
|
- 返回设备型号、序列号、在线状态。
|
|
|
|
### `DeviceManager.screenshot(task_id, step) -> path`
|
|
|
|
职责：
|
|
|
|
- 保存当前手机截图。
|
|
- 返回截图路径。
|
|
|
|
### `DeviceManager.dump_ui(task_id, step) -> path`
|
|
|
|
职责：
|
|
|
|
- 保存当前 UI XML。
|
|
- 返回 XML 路径。
|
|
|
|
## 拼多多流程模块
|
|
|
|
### `PddFlow.open_product(product_url) -> PageState`
|
|
|
|
职责：
|
|
|
|
- 打开商品链接。
|
|
- 等待跳转到拼多多 App。
|
|
- 判断是否进入商品详情页。
|
|
|
|
### `PddFlow.select_sku(sku_items, quantity) -> StepResult`
|
|
|
|
职责：
|
|
|
|
- 打开购买/SKU 面板。
|
|
- 按 `sku_items` 精确匹配规格。
|
|
- 设置数量。
|
|
|
|
### `PddFlow.go_to_order_confirm() -> StepResult`
|
|
|
|
职责：
|
|
|
|
- 进入订单确认页。
|
|
- 读取商品标题、SKU、数量、地址、实付金额等确认信息。
|
|
|
|
### `PddFlow.pay_if_allowed(payment_config, confirm_info) -> StepResult`
|
|
|
|
职责：
|
|
|
|
- 根据支付配置和确认页信息判断是否允许继续支付。
|
|
- 人工确认模式下返回需要人工处理。
|
|
- 受控自动支付模式下，只有商品、SKU、数量、地址、金额、单笔/批次上限全部通过时才继续。
|
|
- 遇到验证码、风控、人脸、短信等安全校验时返回 `待人工`。
|
|
|
|
### `PddFlow.read_order_no() -> str | None`
|
|
|
|
职责：
|
|
|
|
- 在支付完成后尝试读取订单号。
|
|
- 读取失败时返回空，由 GUI 提供人工录入兜底。
|
|
|
|
## 待实现时确认
|
|
|
|
- 真实 Excel 表头是否使用 `SKU信息` 统一字段，还是拆分为多个 SKU 列。
|
|
- 导入时遇到部分行错误，是阻止全部导入还是只标记错误行。
|
|
- 自动读取订单号失败时的人工录入流程。
|
|
- 批量执行失败后默认继续下一条还是暂停批次。
|
|
- 受控自动支付的默认单笔金额上限、批次金额上限和允许价格偏差。
|
|
|
|
|
|
|
|
|
|
|
|
|