装上就能干活的 AI 小程序

顺丰工作台通过真实浏览器登录顺丰系统，采集指定日期的已揽收运单，整理出运单号、收件人、实际重量、实际运费、状态和揽收时间，并按配置写入本地、远程接口或 MySQL 数据库。支持一键自动采集，也可手动分步执行；采集完成后可选通过钉钉机器人发送运行通知。

适用场景

• 每天定时或手动汇总顺丰当天（或近 N 天）已揽收运单。
• 需要把运单、收件人、实际重量、实际运费等信息统一写入自有业务系统或数据库。
• 需要多个顺丰账号分开标识，并用账号短名区分记录来源。
• 需要无人值守运行时通过钉钉接收采集结果或人工介入提醒。

核心功能

• 一键自动采集：自动串起「打开顺丰 → 登录 → 进入查单页 → 采集运单 → 写入数据」，每步按真实页面状态检测，页面慢时等待、瞬时失败自动重试。
• 手动分步执行：可逐步执行打开顺丰、进入密码登录、填充登录、进入查单页、采集并写入，便于人工排查。
• 多数据去向：本地保存、远程接口、直连 MySQL 数据库三种方式，可随时切换。
• 自动入库去重：同一运单号重复采集时跳过，不重复写入；字段有变化时更新。
• 钉钉通知：支持每次运行、仅失败时、仅需人工时三种策略，需要人机校验时可立即提醒。
• 后台采集动作：提供「采集并入库运单」动作，可配合定时任务按 daysAgo 采集指定天数前的运单。

开始使用

使用前需在左侧导航中完成以下配置：

1. 「系统配置」：填写顺丰账号与密码（用于自动填充登录）；填写账号短名与账号名称。
2. 「存储配置」：选择数据去向，并按所选方式填写参数。
3. 「服务配置」：确认揽收日期与定时偏移。

数据去向配置

• 本地保存：采集后只保存在本机，不对外发送。
• 远程接口：需要填写服务器地址与接口 Token；程序会向「服务器地址 + /sf/waybills/upsert」发送 POST JSON，使用 Bearer Token 鉴权。
• 直连数据库：需要填写主机、端口、库名、用户名、密码和表名（默认 sf_waybills），并先点击「初始化数据库表」创建表；数据库需允许远程连接。

账号与凭据说明

• 顺丰账号密码明文保存在本机，仅用于自动填充登录。
• 写入记录时只保存账号短名与脱敏后的登录账号，不保存明文密码。

主要操作步骤

一键自动采集

1. 进入「工作台」。
2. 确认已保存顺丰凭据和数据去向配置。
3. 点击「一键自动采集」。
4. 界面按步骤显示进度：打开顺丰 → 进入密码登录 → 填充并提交登录 → 进入查单页 → 采集运单 → 写入数据。每步显示待执行、执行中、已完成、已跳过、已阻断、失败或已取消及耗时。
5. 运行中可点击「停止」，等待当前步骤结束后中止；已完成的步骤与已采集结果保留。
6. 完成后在「采集结果」区查看记录和写入统计。

手动分步执行

在工作台展开「手动分步执行」，按顺序点击：

1. 「1. 打开顺丰」：新建或复用真实浏览器窗口并打开顺丰页面。
2. 「2. 进入密码登录」：切换至顺丰账户中心密码登录页。
3. 「3. 填充登录」：使用已保存账号密码自动填充并提交登录；如出现滑块验证，需人工完成后继续。
4. 「4. 进入查单页」：打开运单查询页并等待表头就绪。
5. 「5. 采集并写入」：按页面会话查询运单，过滤后展示结果；若「自动入库」开启则同时写入，否则可稍后点击「重新写入」。

点击「清空」可清空当前结果列表。

采集结果

• 结果表每页 20 条，仅显示已按揽收时间和运单状态过滤后的记录。
• 列包括：运单号、收件人、实际重量 kg、实际运费、状态、揽收时间。
• 实际运费无法解析时显示「-」；重量保留三位小数，运费保留两位小数。
• 工具栏显示日期、账号与去向；本地模式显示累计条数。
• 若自动入库关闭或未写入，可点击「重新写入」手动提交当前结果。

采集与过滤规则

• 查询按每页 50 条、最多 10 页翻页。
• 查询接口按下单时间回退 6 天（覆盖近 7 天下单记录），取回后再按揽收时间归属目标日期。
• 仅保留揽收时间以目标日期开头的记录。
• 排除待揽收（状态码 10）及无法识别状态的记录；已揽收（20/30/40）、已签收（50）、已退回（60）进入结果。
• 缺少运单号、揽收时间或实际重量无效的记录会被过滤。

数据写入规则

• 记录以「账号短名 + 运单号」作为唯一键去重。
• 已存在且字段无变化时跳过；字段变化时更新；不存在时新增。
• 本地模式按运单号去重保存，不对外发送。
• 接口模式通过 HTTPS 提交到配置的接口；接口返回非 2xx 或 success=false 时报错。
• 数据库模式由 Python 运行时使用 pymysql 执行 UPSERT，需先初始化表；表名只允许字母、数字和下划线。

运行通知（钉钉）

• 在「系统配置 → 运行通知」中开启「钉钉机器人通知」。
• 填写机器人地址（需 https:// 开头）；可选填加签密钥。
• 若机器人使用「自定义关键词」安全设置，关键词请填「顺丰运单采集」。
• 通知策略：每次运行 / 仅失败时 / 仅需人工时。
• 可开启「需要人工时立即提醒」，检测到人机校验时先发一条。
• 点击「发送测试通知」验证配置。

后台采集动作

• 小程序提供「采集并入库运单」动作，按已保存的账号与接口配置查询顺丰查单页，过滤目标日期已揽收运单并提交。
• 参数 daysAgo 范围 0–90，表示采集几天前；未传时使用「服务配置」中保存的定时偏移，默认 1（昨天）。
• 执行结果返回 fetched（接口取回条数）、matched（匹配条数）、inserted（新增）、updated（更新）。

注意事项

• 顺丰账号密码明文保存在本机，请在本机可信环境使用。
• 登录时如弹出滑块等人机校验，应用不会自动识别或拖动验证码，需人工在浏览器窗口完成；完成后流程会自动继续。
• 登录提交后若超过约 5 分钟仍未离开登录页，会判定需要人工处理。
• 登录态失效（HTTP 401/403）会阻断采集，需重新登录后再采集。
• 远程接口与直连数据库需先填齐参数，配置类错误不会自动重试。
• 定时偏移 1 表示昨天；揽收日期用于手动与一键采集。
• 页面结构或顺丰改版可能导致识别失败，此时可改用手动分步执行排查。