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