批量采集店铺余额，看似只是 “打开页面、抄一个数字”，真正的难点却是确认店铺身份、市场站点和币种，处理登录与页面漂移，并确保 Excel 写入可以审计和回滚。

本文以多店铺运营场景为例，说明如何把本地浏览器桥接、亚马逊 Payments Dashboard 数据读取和 Excel 汇总组织成一条安全、可恢复的自动化流程。文中不包含账号、密钥、内网地址或真实店铺信息。

第三方浏览器、页面结构和平台政策会持续变化。正式运行前，应确认当前版本、账号授权、自动化政策和数据使用边界。验证码与多因素认证必须由人工完成，不应尝试绕过平台安全机制。

# 一、先明确数据口径

本项目读取的目标字段是 Payments Dashboard 页面上的 All Accounts Total Balance 。它是特定时间点、特定店铺和市场站点下的运营数据，不应直接等同于最终会计结算金额。

在编写脚本前，应先确定以下数据契约：

字段	说明	示例
店铺 ID	稳定且唯一的业务标识	`shop_001`
店铺名称	便于人工识别的显示名称	`US Store A`
市场站点	数据所属站点	`amazon.com`
币种	与页面金额一致	`USD`
余额	使用定点小数保存	`1234.56`
采集时间	包含明确时区	`2026-08-22T17:08:06+08:00`
数据状态	成功、空值、待复核或失败	`success`

金额不应直接使用二进制浮点数计算。可以使用 Decimal ，同时保留原始文本，便于后续核对千位分隔符、负数、零值和不同币种格式。

# 二、推荐的系统分层

一个可维护的实现通常包含以下模块：

	配置与凭据层
	↓
	本地浏览器桥接客户端
	↓
	店铺与调试端口解析器
	↓
	页面导航和身份校验器
	↓
	余额提取与数据校验器
	↓
	预览、Excel 写入和审计日志

各模块只承担一种职责：

config ：读取非敏感业务配置，并从环境变量或凭据管理器获取秘密；
bridge_client ：与已授权的本地浏览器桥接服务通信；
session_resolver ：打开指定店铺并获取本次会话的连接信息；
collector ：导航、验证身份并读取余额；
report_writer ：生成预览，执行幂等写入和原子替换；
batch_runner ：控制批量顺序、失败策略和最终汇总；
skill ：记录经过验证的运行条件、命令、成功标志和排错决策。

# 三、把流程写成状态机

与一段从头点到尾的脚本相比，显式状态机更容易恢复和审计：

	PRECHECK
	→ LIST_STORES
	→ OPEN_STORE
	→ VERIFY_IDENTITY
	→ SWITCH_MARKETPLACE
	→ NAVIGATE_PAYMENTS
	→ EXTRACT
	→ VALIDATE
	→ PREVIEW
	→ COMMIT
	→ CLOSE_OWN_SESSION

每个状态都应记录开始时间、结束时间、输入摘要、输出摘要和结果。失败时保存当前状态，而不是让调用方只能看到 “任务失败”。

# 3.1 运行前检查

PRECHECK 至少验证：

本地桥接服务是否可达；
当前调用者是否拥有目标店铺权限；
输出目录是否可写；
报表是否被其他程序占用；
目标站点、币种和时区是否已配置；
是否启用了只预览不落盘的 dry-run 模式。

# 3.2 店铺身份校验

店铺显示名称可能被修改、重复或包含空格差异，因此不能作为唯一依据。推荐使用：

环境 ID 或店铺 ID 作为主键；
页面展示的店铺名称作为二次校验；
市场站点和账号尾号作为附加证据；
任一关键标识不一致时立即停止该店铺流程。

身份不匹配属于安全错误，不能通过刷新页面或盲目重试来掩盖。

# 3.3 市场站点切换

同一卖家账号可能覆盖多个市场站点。脚本进入财务页面前，应确认目标域名、站点名称和币种三者一致。若页面自动跳转到其他站点，必须重新校验，而不是继续读取屏幕上出现的第一个金额。

# 四、安全地接管浏览器会话

本地桥接服务应只监听回环地址，例如 127.0.0.1 ，并要求短期令牌或其他访问控制。令牌只能存放在操作系统凭据管理器或环境变量中，不能写进文章、仓库、命令历史或截图。

WebDriver 地址和 Chrome DevTools Protocol 调试端口是不同概念，具体连接方式取决于浏览器产品、版本与操作系统。应先通过官方文档或受控测试验证，再将适配细节封装在 session_resolver 中。

脚本只应关闭自己创建并能够确认归属的会话，不要按进程名批量结束 Chrome，也不要假定调试端口永远固定。

# 五、页面导航与等待策略

稳定的浏览器自动化依赖页面状态，而不是固定等待秒数。选择器优先级可以是：

平台提供的稳定语义属性；
可访问性角色和可见文本；
相对稳定的结构关系；
CSS 类名或绝对 XPath 作为最后手段。

每一步同时定义成功和失败条件。例如，点击 Payments 后，成功条件可以是页面标题、目标 URL 路径和余额区域同时出现；失败条件可以是登录页、权限不足页、验证码页或超时。

遇到验证码或多因素认证时，自动化程序应暂停并提示人工接管。人工完成后重新执行身份校验，再从安全检查点继续。

# 六、余额提取与校验

读取页面文字后，不要立即写入报表。建议先构造标准记录：

	{
	"shop_id": "shop_001",
	"marketplace": "amazon.com",
	"currency": "USD",
	"balance": "1234.56",
	"raw_text": "$1,234.56",
	"collected_at": "2026-08-22T17:08:06+08:00",
	"status": "success"
	}

校验器需要覆盖以下情况：

金额包含货币符号、千位分隔符或空格；
余额为零或负数；
页面显示占位符、加载动画或空值；
页面币种与配置不一致；
同一字段出现多个候选值；
页面结构变化导致选择器失效。

对不确定的数据标记为 needs_review ，不要自动转换成零。

# 七、批量执行的失败策略

批量模式不意味着所有错误都应 “记录后继续”。可以按性质分类：

错误类型	示例	建议处理
可重试技术错误	临时超时、短暂网络失败	指数退避后有限重试
会话错误	登录过期、MFA	暂停并等待人工处理
安全错误	店铺身份不匹配	立即熔断，不写入数据
业务错误	币种冲突、金额含义不明	标记待复核，不盲重试
文件错误	Excel 被占用	保留临时结果并提示关闭文件

是否采用 continue-on-error 或 fail-fast 应由任务风险决定。涉及身份、权限或数据口径的异常，默认应触发 fail-fast 。

# 八、Excel 的幂等与原子写入

报表至少可以分为三张表：

余额明细 ：每个店铺、站点和采集批次的原始记录；
执行汇总 ：成功、失败、待复核数量与总耗时；
错误明细 ：错误码、阶段、脱敏说明和是否可重试。

业务唯一键建议使用：

店铺 ID + 市场站点 + 币种 + 采集批次

安全写入流程如下：

读取原文件并确认工作表结构；
在内存中完成更新，先生成变更预览；
将结果写入同一磁盘上的临时文件；
重新打开临时文件，校验表头、行数和关键单元格；
为原文件创建带时间戳的备份；
使用原子替换提交新文件；
失败时保留原文件并输出可恢复信息。

写入文本前还要防止公式注入。以 = , + , - , @ 开头的外部文本不应被 Excel 当作公式执行。

# 九、日志、证据与隐私

结构化日志可以包含：

run_id、shop_id_hash、stage、marketplace、result、duration_ms、error_code

日志、截图、HTML 和网络记录都可能携带账号、Token、订单信息或个人数据，因此应在采集时脱敏，并设置最短必要留存期限。成功路径通常无需保存完整页面；失败截图也应裁剪到能证明问题的最小区域。

# 十、推荐配置方式

非敏感业务配置可以进入版本控制：

	target_marketplace: amazon.com
	expected_currency: USD
	output_file: reports/amazon-balance.xlsx
	dry_run: true
	max_retries: 2
	continue_on_error: false

敏感配置只写变量名和用途：

	BRIDGE_BASE_URL=http://127.0.0.1:<port>
	BRIDGE_ACCESS_TOKEN=<read-from-credential-store>

首次运行建议保持 dry_run: true ，只连接一个已授权的测试店铺，展示将写入的记录而不修改报表。通过人工核对后，再开启单店提交。

# 十一、从单店走向批量

批量准入不应只凭 “一次跑通”。一个可操作的门槛是：

单元测试覆盖金额解析、映射、唯一键和幂等更新；
集成测试覆盖桥接连接、页面导航和临时文件写入；
授权单店覆盖正常余额、零值、登录失效和文件占用；
连续多次运行结果一致，不产生重复行；
身份不匹配、币种冲突和验证码都能安全暂停；
备份恢复与失败续跑经过演练。

只有达到这些退出条件，才逐步扩大店铺数量，并设置速率限制和批量熔断阈值。

# 十二、沉淀为可复用 Skill

当流程稳定后，可将运行知识整理为 Skill。Skill 不是账号凭据，也不是替代业务代码的巨型提示词，而是一份与代码版本对应的操作和诊断契约。

建议包含：

适用场景和触发条件；
授权范围与人工审批点；
输入参数及数据契约；
运行前检查；
单店 dry-run 和正式执行方式；
批量准入门槛；
成功标志和输出文件；
错误分类与排错决策树；
禁止事项和隐私要求；
对应代码版本与变更记录。

当页面、命令或数据字段发生变化时，应同时更新测试、自动化程序和 Skill，避免操作说明与实际实现脱节。

# 十三、上线前检查清单

# 结语

财务数据自动化的价值不只是节省点击时间，而是建立一条身份明确、口径一致、过程可审计、失败可恢复的数据链路。

当店铺身份、页面状态、金额解析、写入事务和人工审批点都被写成可验证规则后，浏览器自动化才真正从 “能运行的脚本” 升级为可长期维护的业务系统。

AI 浏览器自动化亚马逊财务自动化 Excel