装上就能干活的 AI 小程序

适用场景

• 需要把**京东物流商家工作台（https://wl.jdl.com）**上「当天已揽收」的运单，整理成运单号、收件人、揽收重量、运费等字段并入库。
• 需要按固定口径（揽收及之后）批量汇总运单，交给远程业务接口、MySQL 数据库，或只保存在本机查看。
• 需要通过后台/定时任务在无人值守时自动采集（应用提供名为「采集并入库运单」的动作，daysAgo 支持 0～90）。
• 采集端不做签名逆向：由页面自己发起查询请求，应用只读取页面响应，适合希望「网页式只读采集」的场景。

核心功能

1. 真实浏览器采集：使用独立浏览器 Profile（jd-waybill-jd-main），登录态可跨运行复用；登录态有效时自动跳过登录与验证码环节。
2. 登录辅助：自动在京东统一登录页（跨域 iframe 内的 #loginname / #nloginpwd）填充已保存的账号密码并提交；出现拼图滑块（JDJRV）时停止自动化，等待人工完成。
3. 按口径采集运单：依次采集「已揽件、运输中、派送中、已送达、已拒收」5 个状态的列表，按下单时间放宽 30 天查询，再按实际揽收时间归日筛选目标日期。
4. 三种数据去向：本地保存 / 远程接口（HTTPS 提交）/ 直连 MySQL（通过 Python 写入）。
5. 自动入库开关：开启后采集完成立即写入；重复运单只跳过，不会重复写入。
6. 结果表格与分页：展示运单号、收件人、揽收重量 kg、运费（预估）、状态、揽收时间，每页 20 条，并显示本次接口总条数与匹配条数。
7. 入库前本地预检：提交前校验幂等键前缀、状态取值、时间格式、日期一致性、重量与运费数值、运单号与收件人，不通过则阻止整批提交。
8. 连通性探活：按 /api/health 探测服务端是否可达（不需要令牌）。
9. 运行记录：后台任务每次执行会写入当次运行记录（含目标日期、去向、采集与写入条数、是否触发自动登录）。

开始使用

前置条件

• 已能访问京东物流商家工作台，并持有可登录的京东账号与密码（用于登录态失效时自动填充）。
• 按所选数据去向准备其一：
  • 远程接口：业务服务根地址，以及单独签发的接口 Token（只含 ingest 权限、只允许 jd 数据源，形如 sft_ 前缀）；服务端需提供 /api/health 与 /api/sources/jd/waybills/upsert。
  • 直连数据库：MySQL 主机、端口（默认 3306）、库名、用户名、密码、表名（默认 jd_waybills），且数据库允许远程连接；首次使用需先「初始化数据库表」。
  • 本地保存：无需额外配置。
• 采集口径相关的选择：揽收日期（手动采集用）、定时偏移（定时任务用，1 表示昨天）、重量口径（默认「复核重量」）。

界面结构

• 顶部显示浏览器连接状态徽标（「已连接」/「未连接」）与当前阶段提示，出错时在顶部显示红色提示条。
• 上半区「采集配置」，下半区「采集结果」，中间分隔条可上下拖动调整两区高度。
• 配置分为：采集流程、采集设置、重量口径、账号配置、服务器配置五个分区，各分区独立保存：
  • 需要点右侧「保存」按钮的分区：采集设置、账号配置、服务器配置中的接口地址/Token 与数据库参数（未保存时显示「未保存」标记，保存后按钮短暂显示「已保存」）。
  • 切换即生效并自动保存的项：重量口径单选项、数据去向单选项、「自动入库」开关。

主要操作步骤

一、一键采集（推荐）

1. 打开应用，确认顶部浏览器徽标与阶段提示。
2. 在「采集设置」中填写揽收日期，点该行「保存」。
3. 在「账号配置」中填写：京东账号、京东密码（点「保存」）；账号短名（默认 jd.main）与账号名称（默认「京东主账号」，点对应行的「保存」）。账号短名决定入库幂等键 jd:<账号短名>:<运单号>，请保持稳定。
4. 在「服务器配置」选择数据去向（本地保存 / 远程接口 / 直连数据库）；选择「远程接口」时填写服务器地址与接口 Token 并保存，可先点「测试连接」探活；选择「直连数据库」时填写主机、端口、库名、用户名、密码、表名并保存，再点「初始化数据库表」。
5. 按需要设置「自动入库」开关（默认开启）。
6. 点「一键采集」，界面按顺序推进：

• ① 打开京东物流商家工作台；
• ② 检查登录态——已登录则提示「登录态有效：已跳过登录与验证码」；未登录则用保存的账号密码填充并提交，如出现拼图滑块，请到弹出的浏览器窗口人工完成；
• ③ 进入运单管理；
• ④ 采集运单列表，并显示各状态分页进度与过滤统计。

7. 采集完成后：

• 「自动入库」开启：按所选去向写入，结果区显示「已提交到接口 / 已写入数据库 / 已保存到本地」及新增、更新、重复跳过、失败条数。
• 「自动入库」关闭：只提示已采集条数，可点结果区的「重新写入」手动写入。

二、分步操作

按需依次点击流程行中的按钮，每一步都会自动跳过已完成的前置环节：

1. 1. 打开工作台：打开/复用浏览器窗口并进入工作台，随后提示登录态是否有效。
2. 2. 登录（已登录自动跳过）：登录态有效则直接提示跳过；无效则填充账号密码并等待登录完成（最长等待约 180 秒，可在浏览器窗口完成滑块后继续）。
3. 3. 进入运单管理：跳转运单管理页并等待内嵌列表页加载，若仍停留在登录页会提示先完成登录。
4. 4. 采集并写入：采集运单列表，并按「自动入库」开关决定是否写入。
5. 清空：清空当前页面展示的采集结果与分页记录（不删除已写入的本地、接口或数据库数据）。

三、结果查看与重新写入

• 「采集结果」区顶部显示本次的日期、账号短名、数据去向（本地保存时还会显示本机累计条数）。
• 阶段/结果提示示例：「接口共 N 条；符合「YYYY-MM-DD 揽收及之后」的 M 条（排除 状态不符 …、无揽收时间 …、非目标日期 …、字段缺失 …）」。
• 表格列：运单号、收件人、揽收重量 kg、运费（预估）、状态、揽收时间；无数据时显示「暂无采集结果」；表格下方为页码与页数提示（每页 20 条）。
• 想对已采集的列表重新写入（例如先关掉自动入库、稍后手动入库），点「重新写入」。

四、后台/定时动作「采集并入库运单」

• 使用前需先在小程序界面保存好配置。动作执行前会校验：远程接口模式必须有服务器地址与 Token，直连数据库模式必须有主机、库名与用户名，否则直接报错且不可重试。
• 未保存京东登录凭据时，配置校验仍可通过，但登录态失效后后台任务无法自动登录，需要先人工登录一次。
• 执行流程：以后台模式打开独立 Profile 的浏览器 → 打开运单管理页 → 登录态不足时用保存的凭据自动登录 → 进入运单管理 → 采集目标日期（由 daysAgo 计算的本地日期）运单 → 本地预检 → 按去向写入 → 返回 fetched / matched / inserted / updated 并关闭窗口。
• 该动作并发为单实例，且会产生外部写入副作用。

采集口径与字段说明

注意事项

• 验证码只能人工完成：出现拼图滑块时程序不识别、不拖动、不绕过，请在弹出的浏览器窗口中手动处理。
• 密码错误立即停止：登录被判定为账号或密码不匹配时会停止执行且不重试，请核对凭据后重新执行。
• 采集过程只读：仅读取页面自身请求的响应，不点击任何写操作。
• 凭据保存在本机：京东账号与密码、接口 Token、数据库密码均按明文保存于本机存储，仅用于自动填充与写入；入库记录只保存账号短名与脱敏登录账号。
• 令牌最小权限：请为京东段单独签发只含 ingest、只允许 jd 数据源的令牌，不要复用其他数据源的令牌。接口写入常见报错：401（令牌无效或过期）、403（权限不足，需只 ingest 且只 jd）、413（单批条数超上限）、422（某条记录被服务端拒绝）。
• 本地预检会阻止整批提交：任一条记录不满足幂等键前缀、状态取值、时间格式与日期一致、重量/运费非负、运单号与收件人非空，就会整批不写入，请先修正配置（如账号短名）后重试。
• 接口单批上限：应用按每批 50 条拆分提交，并在批次之间等待约 1.2 秒；服务端上限为 500 条/批。
• 查询与翻页限制：每个状态最多翻 30 页，页面每页 10 条；若某页未捕获到列表响应或翻页控件不可用，会在结果区显示「分页记录」说明并继续后续状态。
• 未进入运单管理就采集：会提示页面上找不到内嵌的运单列表页；停在登录页时采集会立即失败并提示先完成登录。
• 直连数据库：需数据库允许远程连接；表名只允许字母、数字与下划线；执行前请先「初始化数据库表」，重复执行写入时按记录键去重，无变化记为跳过。
• 探活说明：连通性测试只调用 /api/health，不需要令牌，令牌在真正写入时校验。
• 结果缓存：采集结果会缓存在本机并用于展示；「清空」只影响界面展示，不影响已写入的数据。
• 时间与日期：定时任务的目标日期按触发时刻的本地日期减去「定时偏移」计算；「定时偏移」有效范围为 0～90，超出会被约束到该范围。