cmpdd/docs/api.md

本地模块合约

本项目 MVP 没有后端 API。本文定义本地模块之间的目标接口形状，避免 GUI、Excel、Android 自动化逻辑互相耦合。

通用约定

• 模块间传递结构化对象，不传裸字典到处拼字段。
• 错误使用明确异常或结果对象，不能静默返回 None。
• 时间统一使用本地时间并在写入 Excel 时格式化为可读字符串。
• 所有自动化步骤必须携带 task_id，方便日志关联。

通用错误对象建议：

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 §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 §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 列。
• 导入时遇到部分行错误，是阻止全部导入还是只标记错误行。
• 自动读取订单号失败时的人工录入流程。
• 批量执行失败后默认继续下一条还是暂停批次。
• 受控自动支付的默认单笔金额上限、批次金额上限和允许价格偏差。