@jiaoyubaocn/workbuddy-order 0.0.0-stage → 1.2.0

package/README.md

@@ -1,3 +1,423 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# workbuddy-order
+
+教育宝**内部订单查询**工具。登录管理后台帐号后，按状态、日期、机构、渠道、关键词等条件查询后台订单/用户列表，并以表格或 JSON 返回；同时提供 MCP 服务形态，可直接接入 WorkBuddy。
+
+- 运行时：Node.js 18+，**零第三方依赖**（只用内置 `fetch/fs/crypto/http/readline`）
+- 数据源：`https://apidata-admin.jiaoyubao.cn`
+- 接口：`101000` 登录、`400450` 订单/用户列表、`400456/400457/400458/400459/400460/400461/400462/400463/400472/400130` 字典
+- 不影响 .NET 编译（独立目录，未加入 `datacache.csproj`）
+
+## 目录
+
+```
+workbuddy-order/
+├── cli.js            命令行入口（login/logout/whoami/orders/count/dict/raw）
+├── server.js         MCP 入口（HTTP 或 stdio）
+├── lib/
+│   ├── http.js       接口传输：key 组装、超时重试、POST 回退、错误分类
+│   ├── auth.js       101000 登录、MD5 凭证、本地缓存与自动续登
+│   ├── dict.js       字典拉取、缓存、中文名 → 编号
+│   ├── order.js      400450 参数映射、分页、字段裁剪
+│   ├── format.js     表格/键值渲染（中文按 2 宽对齐）
+│   └── tools.js      MCP 工具定义与实现
+├── deploy/           服务器部署（Windows/IIS 为主，含 Nginx 附录）
+│   ├── README.md     部署手册：https://apidata-admin.jiaoyubao.cn/mcp
+│   ├── iis/          反向代理 web.config（子应用 / 站点根两种）
+│   └── windows/      NSSM 服务安装脚本
+└── test/
+    ├── mock-api.js   本地假接口
+    └── smoke.js      冒烟测试（29 项）
+```
+
+## 发布到 npmjs.com 与员工安装
+
+零依赖 Node 18+ 包，装完得到两个全局命令：`jyb-order`（CLI）、`jyb-order-mcp`（MCP stdio 服务）。
+
+- 包名：`@jiaoyubaocn/workbuddy-order`
+- 包页：https://www.npmjs.com/package/@jiaoyubaocn/workbuddy-order
+
+### 首次发布（维护者，本机执行一次）
+
+```bash
+npm login        # 浏览器登录 npmjs.com（账号 joysiftcn，需对 @jiaoyubaocn 组织有写权限）
+publish.cmd      # 跑冒烟测试 → 发布到 @jiaoyubaocn
+```
+
+`publish.cmd` 内部等价于：
+
+```bash
+npm pkg set name=@jiaoyubaocn/workbuddy-order
+npm test
+npm publish --access public     # scoped 包不带 --access public 会被拒绝（402）
+```
+
+**2FA 注意**：账号开启两步验证后，普通 Publish token 会被 403 拒绝（`Two-factor authentication or granular access token with bypass 2fa enabled is required`）。必须使用 **Automation** 类型的 Classic token（或勾选 Bypass 2FA 的 Granular token），或发布时加 `--otp=<6位验证码>`：
+
+```bash
+npm publish --access public --otp=123456
+```
+
+### 员工安装（一条命令）
+
+```bash
+npm install -g @jiaoyubaocn/workbuddy-order
+```
+
+装完直接可用，无需再配路径：
+
+```bash
+jyb-order login --user=zhangsan --password='******'
+jyb-order orders --days=7
+jyb-order whoami
+```
+
+WorkBuddy 走 MCP 时填：
+
+```
+command: jyb-order-mcp
+args:    ["--stdio"]
+```
+
+### 发新版本
+
+```bash
+npm version patch     # 或 minor / major；会自动改 version 并打 git tag
+publish.cmd           # 同一版本号不能重复发布
+```
+
+员工升级：`npm update -g @<scope>/workbuddy-order`，`jyb-order --version` 确认。
+
+### 注意事项
+
+- **包内容公网可下载**：`lib/` 源码、接口地址（`apidata-admin.jiaoyubao.cn`）、字段语义都会公开。若不希望公开，改用内网 Verdaccio（`npx verdaccio`，发布 `--registry http://内网IP:4873/`）或 tgz 共享分发。
+- **scoped 包名必须全小写**，scope 就是你 npm 账号用户名（个人账号无需建组织即可发布）。
+- 登录凭证存在 `C:\ProgramData\jyb-order-mcp`，与安装/升级/卸载无关。
+- 本机 npm 不认 UNC 路径（`\\host\share` 会被误解析成 `C:\host\share`），所以不要把共享盘路径直接喂给 `npm install -g`；tgz 需先映射盘符再安装。
+
+## 快速开始
+
+```bash
+cd datacache/cs/workbuddy-order
+
+# 1) 登录（帐号就是后台登录用的帐号，需要互联网出口可访问 apidata-admin）
+node cli.js login --user=zhangsan --password='******' --ip=1.2.3.4
+
+# 2) 查最近 7 天订单
+node cli.js orders --days=7
+
+# 3) 按状态 + 关键词
+node cli.js orders --state=已报名 --word=13800000000 --word-type=电话 --days=30
+
+# 4) 只要总数
+node cli.js count --state=已报名 --days=30
+
+# 5) 机器可读
+node cli.js orders --days=7 --json
+```
+
+登录成功后 passport 会写入 `~/.jyb-workbuddy/credentials.json`（Windows 为 `%USERPROFILE%\.jyb-workbuddy\credentials.json`），后续命令自动复用；凭证剩余有效期低于 10% 时自动续登，接口返回鉴权失败时自动重登一次并重试。
+
+> 只保存密码的 MD5，不保存明文。可用 `--no-save` 完全不落盘。
+> 若已有浏览器中的 `admuserpassport`，可 `node cli.js login --passport=xxxx` 直接保存。
+
+## 微信扫码登录（网页授权）
+
+除帐号密码外，支持用微信扫码登录（101000 的 `checkway=20` + `wxwebcode`）。后台自己用 code 换 openid，本地不接触公众号 secret。
+
+### 一条命令完成（扫完自动登录）
+
+```bash
+jyb-order login --wx
+```
+
+它会生成一次性 state、打开扫码页、等扫码。手机授权后页面把 code 回传给服务端，
+终端 2 秒内自动取回并完成登录，**不需要复制粘贴**。
+
+扫码页：`https://m.jiaoyubao.cn/manage/admincli/wxlogin.html`
+（单文件静态页，源码与上传说明见 `deploy/wx-admincli/`）
+
+链路：
+
+```
+jyb-order login --wx
+  └─ 生成 state → 打开 wxlogin.html?state=xxx
+       └─ 手机扫码 → 微信授权 → 页面回调 ?code=xxx&state=xxx
+            └─ 页面 POST /mcp/wx/handoff（一次性票据，5 分钟）
+                 └─ CLI 轮询 GET /mcp/wx/poll?state=xxx 取走 code
+                      └─ 本地调 101000 → passport → 保存凭证
+```
+
+### 微信绑定了多个后台帐号
+
+第一步不会直接登录，而是列出候选：
+
+```
+该微信绑定了 6 个后台帐号，请选择要登录的一个：
+  1) admin           管理员
+  2) lijingjing_cw   李靖靖
+  ...
+```
+
+再执行 `jyb-order login --select=2`（序号或 usercode 都行）。选择状态在本地缓存 10 分钟，用过即失效。
+
+二次提交的协议实测结论（2026-11-07，admin 帐号 / 6 个候选）：后台要求
+**session cookie + usercode + 原始 code** 三样齐全，少了 code 会返回「参数错误！」。
+CLI 按这个顺序尝试，另外两种组合（只带 session、无 session 直连）作为兼容兜底。
+
+> 踩过的坑：`ip` 传空字符串会让 101000 直接返回「参数错误！」，
+> 必须是真实 IP（未配置时用 `127.0.0.1` 兜底）。
+
+### 兜底：手动粘贴
+
+扫码页不可用（没上传、被拦）时，这两条仍能走通：
+
+```bash
+jyb-order login --wx --no-open                      # 只打印地址，不自动开浏览器
+jyb-order login --wx-code="<code 或整条回调网址>"    # 手动提交授权码
+```
+
+### 配置项
+
+| 变量 | 默认值 | 说明 |
+|---|---|---|
+| `JYB_WX_PAGE` | `https://m.jiaoyubao.cn/manage/admincli/wxlogin.html` | 扫码页地址 |
+| `JYB_WX_POLL` | `https://apidata-admin.jiaoyubao.cn/mcp/wx/poll` | CLI 取码端点 |
+| `JYB_WX_TIMEOUT` | `180` | 等待扫码的秒数 |
+| `JYB_WX_ORIGIN` | `https://m.jiaoyubao.cn` | 服务端允许的回传来源（CORS） |
+
+也可用 `login --wx --page=<url> --timeout=60` 临时覆盖前两项。
+
+### 已知限制
+
+- **code 一次性、约 5 分钟有效**：拿到就要用，不能重复提交。
+- **票据只存服务端内存**：服务重启会丢，重新扫码即可，不影响已登录凭证。
+- **凭证过期不能自动续登**：微信登录没有密码可复用，过期后需重新扫码（密码登录仍会自动续登）。
+- **PC 端必须扫码**：网页授权只能在微信客户端内打开，这是微信的限制，不是实现取舍。
+
+## 命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `login` | 登录并保存凭证；`--user --password [--ip] [--expires=1440] [--no-save]`，或 `--passport=值` |
+| `logout` | 清除本地 passport（保留帐号，下次自动重登） |
+| `whoami` | 查看登录状态、帐号、passport 脱敏值、剩余时间；`--verify` 调用 101001 校验 |
+| `orders` | 查询订单列表（400450） |
+| `count` | 只取记录总数（400450 `page=0`） |
+| `dict` | 字典查询与中文转编号 |
+| `raw` | 原样调用接口，如 `raw --action=400457`，用于排查或扩展 |
+
+### orders 常用参数
+
+| 参数 | 说明 |
+| --- | --- |
+| `--state=已报名\|已放弃` | 订单状态，中文或编号，多值用 `\|` |
+| `--sdt=2026-10-01 --edt=2026-11-06` | 日期区间，默认「结束日期前一个月 ~ 今天」 |
+| `--days=30` | 以结束日期为基准往前推 N 天 |
+| `--dttype=报名日期` / `--date-type=1` | 日期类型（对应接口 `dttype`），决定 `--sdt/--edt` 作用在哪种日期上，默认 `0` 订单时间，可传编号或名称，支持唯一前缀简写（如 `结课`→学员结课日期） |
+| `--word=xxx --word-type=电话` | 关键词，类型：电话/微信/QQ/IP/客服日志 |
+| `--comid --memberid --areaid --bigareaid` | 机构、用户、地区 |
+| `--main-class=舞蹈` | 机构主垂直行业（对应 `mainclassid`，只到一级行业）：中文名或编号，细分名会自动归到一级；多值用 `\|` |
+| `--course-class=拉丁舞培训` | 课程行业（对应 `classid`，可精确到细分）：中文名或编号；传一级行业会自动包含其下所有细分 |
+| `--classid=500016 --mainclassid=500016` | 直接传接口编号（等价写法） |
+| `--source --comtype --usertype --useridentity --channel --channel-group --comstate --dzstate` | 中文名自动转编号 |
+| `--mode=按订单\|按用户` | 默认按订单 |
+| `--matchstate --isbesure --isreview --isimportant --myinvite --alertstate --issystemsync --comfollowupstate` | 枚举条件，支持 `全部/未匹配/已匹配` 等中文 |
+| `--op-cs --adv-cs --user-cs` | 运营客服 / 顾问客服 / 用户顾问客服帐号 |
+| `--page=1 --page-size=10` | 分页，每页最大 100 |
+| `--all --max-pages=5` | 自动翻页拉取多页（默认最多 5 页，硬上限 20） |
+| `--full` | 输出客服日志/订单日志/结算信息原文（默认折叠为摘要） |
+| `--fields=ordercode,username,comname` | 自定义表格列 |
+| `--json` / `--quiet` | 输出 JSON / 只输出数据行 |
+
+日期类型（`dttype`）编号对照：
+
+| 编号 | 日期类型 | 编号 | 日期类型 |
+| --- | --- | --- | --- |
+| 0 | 订单时间（默认） | 6 | 学员结课日期 |
+| 1 | 报名日期 | 7 | 订单提醒日期 |
+| 2 | 改报名日期 | 8 | 学员联络日期 |
+| 3 | 客服日期 | 9 | 从帐单删除日期 |
+| 4 | 结算日期 | 10 | 对帐单生成日期 |
+| 5 | 机构日志日期 | 11 | 二次回访日期 |
+
+### 字典
+
+```bash
+node cli.js dict                                   # 列出所有字典类型
+node cli.js dict --type=state --keyword=报名        # 按关键字过滤
+node cli.js dict --type=state --resolve=已报名      # 中文转编号
+node cli.js dict --type=class --keyword=舞蹈        # 查培训类别（行业），level=2 为一级行业
+node cli.js dict --type=class --resolve=拉丁舞      # 行业名转编号（拉丁舞 → 500016007）
+node cli.js dict --type=useridentity --code=901098004
+```
+
+| type | 接口 | 说明 |
+| --- | --- | --- |
+| `state` | 400457 | 订单状态（两级树） |
+| `comtype` | 400456 | 机构类型 |
+| `source` | 400458 | 订单来源 |
+| `usertype` | 400459 | 用户类别（`mtypecode`） |
+| `channel` | 400461 | 渠道（`uid`） |
+| `channelgroup` | 400460 | 渠道分组 |
+| `comstate` | 400462 | 机构合作状态 |
+| `dzstate` | 400463 | 对账状态 |
+| `useridentity` | 400472 | 用户身份（默认前缀 901009，可用 `--code` 覆盖） |
+| `cs` | 400130 | 客服名单 |
+
+字典本地缓存 6 小时（客服 1 小时），接口异常时自动降级使用旧缓存。
+
+## 接入 WorkBuddy（MCP）
+
+### 方式一：HTTP
+
+```bash
+node server.js --port=3100
+# 端点 http://localhost:3100/mcp
+```
+
+MCP 客户端配置：
+
+```json
+{
+  "mcpServers": {
+    "jyb-order": {
+      "type": "http",
+      "url": "http://localhost:3100/mcp"
+    }
+  }
+}
+```
+
+### 方式二：stdio（无需端口，由客户端拉起进程）
+
+```json
+{
+  "mcpServers": {
+    "jyb-order": {
+      "command": "node",
+      "args": ["g:/vss/net/Edu/edufront/EduManage.root/EduManage/datacache/cs/workbuddy-order/server.js", "--stdio"],
+      "env": {
+        "JYB_USERCODE": "zhangsan",
+        "JYB_PASSWORD": "******",
+        "JYB_IP": "1.2.3.4"
+      }
+    }
+  }
+}
+```
+
+### 提供的工具
+
+| 工具 | 说明 |
+| --- | --- |
+| `login` | 用本人后台帐号登录（HTTP 多用户模式：凭证按用户独立保存，只存密码 MD5，并绑定当前会话） |
+| `logout` | 解除会话绑定并使该用户凭证失效 |
+| `login_status` | 查看当前会话绑定的帐号与凭证剩余时间（`verify:true` 会校验凭证） |
+| `query_orders` | 按状态/日期/机构/渠道/关键词/**机构主垂直行业（`main_class`）**/**课程行业（`course_class`）** 等查询订单，返回人读摘要 + `structuredContent` |
+| `list_order_options` | 查询字典；传 `resolve` 可把中文名转成编号 |
+
+工具返回结构：`content[0].text` 为人读文本，`structuredContent` 为机器可读数据；业务错误通过 `isError: true` 返回，便于模型区分"查无数据"与"调用失败"。
+
+### 返回字段含义（400450）
+
+| 字段 | 含义 | 出现位置 |
+| --- | --- | --- |
+| `commission` | **结算金额**（元） | 响应根节点为本次查询的**结算金额合计**；单条记录若返回则为本单结算金额 |
+| `serviceprice` | **学费金额**（元） | 响应根节点为本次查询的**学费金额合计**；单条记录（`orders[].serviceprice`）为本单学费 |
+| `jkrq` | **结课日期** | 单条记录 |
+| `kkrq` | **开课日期** | 单条记录 |
+| `bmrq` | **报名日期** | 单条记录 |
+
+> 根节点合计还包含 `usernum`（用户数）、`comnum`（机构数）、`ordernum`（订单数，按用户模式返回）。
+> 这些合计在 `structuredContent.totals` 中以数值返回，人读摘要显示为「合计：学费金额合计 x 元，结算金额合计 y 元」；表格列头「学费金额」即 `serviceprice`。
+
+### 多用户登录（HTTP 服务模式）
+
+每个人必须用**本人的后台帐号**登录，查询按登录帐号的权限执行（不同人权限不同，结果不同）：
+
+1. 员工在对话里说「帮我登录订单查询，帐号 xxx 密码 xxx」，AI 调用 `login` 工具；
+2. 登录成功后凭证按用户独立存放在服务端（只存密码 MD5），并绑定到当前 MCP 会话；
+3. 之后该会话内所有查询都以该帐号权限执行，凭证临近过期自动续登，无需反复登录；
+4. `logout` 可退出；服务重启后会话绑定丢失，重新调用 `login` 即可。
+
+也支持无状态方式：客户端在请求头带 `X-Jyb-Passport`（值即浏览器登录后的 `admuserpassport` cookie），可跳过 `login` 直接查询。
+
+> HTTP 模式下服务端**不再配置全局帐号**，未登录时所有查询工具直接返回"尚未登录"，避免所有人共享同一权限。
+> stdio/CLI 单机模式不受影响：仍使用本机全局凭证（`~/.jyb-workbuddy/credentials.json`）。
+
+## 部署到服务器
+
+`apidata-admin.jiaoyubao.cn` 就是本项目 `datacache` 站点的域名，直接复用现有 443 与证书：
+
+```
+WorkBuddy → https://apidata-admin.jiaoyubao.cn/mcp → IIS 反代 → 127.0.0.1:3100 Node 服务
+```
+
+在服务器上（管理员 PowerShell）：
+
+```powershell
+cd datacache\cs\workbuddy-order\deploy\windows
+.\install-service.ps1 -UserCode 帐号 -Password '密码' -LoginIp <服务器出口IP> -Nssm C:\tools\nssm\nssm.exe
+```
+
+之后按 `deploy\iis\mcp-app.web.config` 建 IIS 子应用 `/mcp` 即可。完整步骤、安全加固与排障见 [deploy/README.md](deploy/README.md)。
+
+## 环境变量
+
+| 变量 | 说明 |
+| --- | --- |
+| `JYB_API_HOST` | 接口地址，默认 `https://apidata-admin.jiaoyubao.cn`（测试时可指向 mock） |
+| `JYB_USERCODE` | 后台帐号 |
+| `JYB_PASSWORD` | 后台密码（自动转 MD5），或用 `JYB_PASSWORD_MD5` 直接给 MD5 |
+| `JYB_PASSPORT` | 直接提供 passport（优先级最高，不触发登录） |
+| `JYB_IP` | 登录时上报的 IP，默认 `127.0.0.1` |
+| `JYB_CONFIG_DIR` | 凭证与缓存目录，默认 `~/.jyb-workbuddy` |
+| `JYB_TIMEOUT` / `JYB_RETRY` | 单次请求超时（毫秒，默认 15000）/ 失败重试次数（默认 1） |
+
+优先级：命令行参数 > 环境变量 > 配置文件。
+
+## 退出码
+
+| 码 | 含义 |
+| --- | --- |
+| 0 | 成功 |
+| 2 | 参数错误（含中文条件匹配不到） |
+| 3 | 认证失败（帐号密码错误、凭证失效且无法自动重登） |
+| 4 | 无权限（帐号分组不在允许名单） |
+| 5 | 网络异常/超时 |
+| 1 | 其他服务端异常 |
+
+## 常见问题
+
+**1. 返回「无权访问！」**
+服务端要求帐号分组 `admbh` 以 `901011001 / 901011002 / 901011003 / 901011310 / 901011300` 开头。
+
+**2. 查询成功但一条数据都没有**
+400450 会强制按 `r_con_users_city`（`manager=当前帐号`、`isactive=1`）过滤城市，帐号没有被分配城市管理权限时查不到任何订单。CLI 在 `rec=0` 时会输出这条提示。
+
+**3. 登录报「密码不能为空」/「只支持后台用户」**
+101000 只支持 `usertype=0` 的后台用户，且必须同时提供帐号与密码；扫码登录的管理员需要先用 `login --passport=...` 手工导入凭证。
+
+**4. 日志里的 passport**
+所有日志与报错只显示 `前 6 位****后 4 位`，不会打印完整凭证或完整请求 URL。
+
+**5. 手机号被脱敏**
+服务端会根据帐号权限对手机号、日志内容做脱敏（`ishiddencodenumber`），CLI 不再二次处理，避免破坏原始数据。
+
+## 测试
+
+```bash
+cd datacache/cs/workbuddy-order
+node test/smoke.js
+```
+
+使用本地 mock 接口覆盖：未登录状态、自动登录、凭证落盘与复用、状态/多状态/关键词筛选、分页与 `--all`、总数、字典过滤与中文转编号、表格与 `--quiet` 输出、passport 失效自动重登、错误密码退出码、`raw` 调用、MCP HTTP 与 stdio。
+
+## 扩展
+
+新增接口只需两步：
+
+1. 在 `lib/order.js`（或新增模块）里调用 `http.callApi("接口编号", {passport, ip, ...})`；
+2. 在 `lib/tools.js` 的 `TOOLS` 与 `callTool` 中声明工具，并在 `cli.js` 增加命令。
+
+例如订单详情 `400451`、订单日志 `400465`、客服日志 `400466` 均可按此方式接入。