微信小店订单管理工作台

把用户的微信小店订单、售后、物流拦截数据，变成一套跑在本机的可视化工作台：

两个板块是一个系统的两个侧栏：板块1 左侧栏点「发货订单匹配」就会嵌入板块2，不需要用户记第二个网址。

什么时候用

• 用户要「看订单 / 看售后 / 看退货 / 看物流拦截 / 查未发货退款 / 导出订单」
• 用户要「把快递面单明细和系统的发货记录对一下 / 找出两边不一致的运单」
• 用户要「打开订单工作台 / 订单管理系统」

首次使用：必须先配店铺凭据

系统不带任何凭据，必须先让用户填自己的 AppID / AppSecret。走 scripts/setup.py：

python "<skill_dir>/scripts/setup.py"

它会：释放程序到 ~/微信小店订单管理工作台/ → 检查依赖与 Node → 引导用户粘贴凭据（或告诉他们手动编辑 config/stores.json）。

如果用户还没拿到凭据，告诉他们：

1. 打开 <https://store.weixin.qq.com> → 左侧「服务市场」→「自研」
2. 新建（或打开）自研应用 → 在「开发配置 / 密钥」看到 AppID（wx 开头 18 位）与 AppSecret（32 位）
3. AppSecret 只完整显示一次，先复制保存

> ⚠️ 凭据等同于店铺后台钥匙。不要把它写进对话记录、不要提交到仓库、不要在群聊里发。只让它待在用户本机的 config/stores.json 里。

启动

python "<skill_dir>/scripts/launch.py"

• 会自动释放/更新程序、跑自检、启动服务并打开浏览器
• 只做检查不启动：python "<skill_dir>/scripts/launch.py" --check
• 指定端口：--port 8765
• 板块2 由板块1 自动拉起（POST /api/shipmatch/ensure，幂等），不用单独启动
• 停止：关掉那个命令行窗口，或 Ctrl+C

启动之后怎么用（告诉用户的话）

板块1：选时间口径（默认「售后完成时间」）+ 时间区间 + 店铺 → 点 开始查询 → 看板与明细刷新 → 需要就导出 CSV。
时间区间口径是左闭右开：填 9-01 ~ 9-14 = 9-01 00:00:00 起（含）到 9-14 00:00:00 止（不含）。

板块2：先在板块1 点「确认查询」（口径条变绿色「已确认」）→ 上传两个 Excel → 点「开始匹配」。
匹配结果分四类：双方一致 / 仅店铺端有 / 仅快递端有 / 信息不一致。

环境要求

• Python 3.10+，依赖 requests openpyxl（缺失时 pip install -r requirements.txt）
• Node.js 22+（板块2 用，Node 内置 node:sqlite，无需额外安装数据库）
• 如果机器上装了 WorkBuddy，它自带的 Python / Node 会被自动识别使用

数据在哪

默认全部落在 ~/微信小店订单管理工作台/ 下：

• config/stores.json —— 店铺凭据（敏感）
• data/ —— 订单 / 售后数据
• data_cache/ —— 查询缓存与操作日志
• shipmatch/data/shipmatch.db —— 面单匹配用 SQLite

系统只与 api.weixin.qq.com 通信，不向任何第三方上传数据。删掉这个目录 = 完全卸载。

排错

见 references/常见问题.md。最常见的三类：

1. 提示找不到 Python → 装 Python 并勾选 Add python.exe to PATH
2. 提示缺少 requests / openpyxl → 按提示跑 pip install -r requirements.txt
3. 查询报 token 错误 → AppID / AppSecret 填错，回 config/stores.json 核对

注意

• 这是本地服务，只监听 127.0.0.1。不要把它暴露到公网 —— 它带着用户店铺的完整密钥与订单数据。
• 不要替用户修改 data/ 下的数据文件，也不要删 data_cache/：里面有「一次拦截永久拦截」的证据固化字段，删了不可逆。
• 需要重新生成单文件离线快照时：cd 程序目录/workbench && python build.py。