e10-data 0.1.18-xiaoe → 0.1.21

package/CHANGELOG.md

@@ -1,5 +1,155 @@
 # 变更记录
 
+## 0.1.21（2026-09-28）—— 新增 `module call`：模块配置接口调用（配置中心驱动）
+
+### 1. 新命令族 `module`（子命令 `call`）
+
+**用途**：**已确定「哪个模块的哪条具体接口」之后**，用本命令一条命令完成取数 ——
+定位模块 → 拉接口清单 → 选接口 → **组参调用** 的前三步仍由技能侧完成，第四步「调用」收敛到本命令。
+
+```bash
+e10-data module call --conf-key <confKey> --group <模块> \
+  [--args '<JSON>'|--args @params.json] [--query "k=v&k2=v2"] \
+  [--method GET|POST|FORM] [--header 'K: V'|--headers '<JSON>'|@file] \
+  [--limit 50] [--fields a,b] [--raw] [--show-params] [--dry-run] [--timeout 60] [--json]
+```
+
+内部一次完成：**精取该条 `confAttrs`**（`confType=api`，按 `confGroup` 二级定位）
+→ 按 `http_method` / `input_params` 组参（GET 拼 query；POST 发 JSON body，`FORM` /
+`api_definition` 含 `x-www-form-urlencoded` 时发表单）
+→ 发请求（**自动禁代理** + `Cookie` / `eteamsid` / `User-Agent: AgentType=…,IsAgent=true` 三件套）
+→ 按外层结构（`datajson` / `data` / `records` / 裸数组）提取精简结果（`rows` / `total` / `data`）。
+
+### 2. 与技能自带 `script/call_module.py` 的等价关系
+
+参数名、退出码、提取口径**全对齐**，可互为替换（`--args` 语义一致、`--query` 多对改用 `&` 连接、
+`--header` 单条 + `--headers` JSON 多条）。差异只有两点：
+
+1. **复用本 CLI 的凭据缓存与 `conf` 通道** —— 不额外起 python、不重复取凭据（少 1~2 次进程）；
+2. **零临时文件** —— body 由内存直发，不落盘。
+
+### 3. 退出码（照 `call_module.py` 语义，`main().catch` 按 `e.exitCode` 退出）
+
+| 码 | 含义 |
+|---|---|
+| 0 | 正常（**空结果也算正常**：0 行 / 计数 0 直接交付） |
+| 2 | 未登录 / 凭据失效（HTTP 401 / 凭据取不到）→ 重登 |
+| 3 | 非 JSON / `confAttrs` 解析失败 / 配置不存在 |
+| 4 | 权限受限（`hasSearchRight=false`；终端态：立即终止，不重试、不换参、不交付为「无数据」） |
+| 6 | 命中 HRM 路径黑名单（`/api/hrm/`、`/api/bs/hrm/`、`/api/app/hrm/` → 拒绝调用） |
+| 7 | 请求失败（网络 / 超时 / HTTP 非 2xx 且非 JSON） |
+| 8 | 用法错误（缺必填 / 参数非法 / `--args` 非 JSON 对象） |
+
+### 4. 功能要点
+
+- `--show-params`：只打印该接口的入/出参说明与请求示例（**不调接口**），替代手工 `conf get` dump 用于正确组参；
+- `--dry-run`：只组装请求不发送，**凭据一律脱敏**；
+- `--limit N`（默认 50，`0` = 不截断）/ `--fields a,b`（每行投影）/ `--raw`（原样输出响应体）；
+- **权限/二次验证标志位识别**：`hasSearchRight=false` 与 `pageUid="checkSecondFail"` 在输出 `flags` 中点名
+  （前者同时以退出码 4 收口）；
+- **INVOICE 自动换取发票云 `token`**：`group` / `module_key` 为 `INVOICE` 时先 `GET /api/inc/proxy/getToken?appType=1`
+  取 `data.token` 写入请求头，**Token 只在内存透传，不打印、不落盘**；
+- **HRM 路径黑名单**在发请求前拒绝（退出码 6），杜绝手工直调 HRM 接口。
+
+### 5. 配套改动（非破坏性）
+
+- `normalizeAuth` / weaver-work-cli 出口 / 进程间凭据缓存**补齐 `userAgent`** 字段
+  （来源 `WEAVER_USER_AGENT`），供 `module call` 组 `AgentType` UA；缺失或形态不符时
+  由 `moduleUserAgent()` 从 `cookie` 的 `agentType=` 推导，再退回 `workbuddy`。**取数链路行为不变**；
+- `main().catch` 支持错误对象自带 `exitCode`（未设置仍为 1，既有命令退出码零变化）。
+
+> 📌 命令参数、输出与退出码是本包**对外契约**；技能侧 `references/support/module-api-query/module-api-query.md`
+> 的「组参调用」步骤可切到本命令（`call_module.py` 保留为兜底）。
+
+## 0.1.20（2026-09-24）—— 凭据来源切换为 `weaver-work-cli`（唯一来源，移除 e10-login 回退）
+
+### 1. 凭据出口改为 `weaver-work-cli auth export-weaver-env`
+
+执行 `auth export-weaver-env --shell posix`，解析 `WEAVER_BASE_URL` / `WEAVER_ETEAMSID` /
+`WEAVER_COOKIE` 三项（正好对应本 CLI 需要的 `baseUrl` / `eteamsid` / `cookie`）。
+凭据**只在进程内存中解析**——不经 shell、不落盘、不打印。
+
+- 入口定位沿用与 e10-login 相同的四段式：`WEAVER_WORK_CLI_ENTRY` → Node 模块解析 →
+  PATH shim → 常见全局前缀；
+- `weaver-work-cli` 的登录态存于 `~/.weaver-work-cli/`（`@napi-rs/keyring` 加密），
+  与 e10-login **完全独立、互不通用**。
+
+### 2. ⚠️ 破坏性变更：移除 e10-login 回退
+
+`AUTH_PROVIDERS` **收敛为只保留 `weaver-work-cli`**。原四个 e10-login 系出口
+（`auth --json` / `whoami --json` / `whoami` 文本 / 明文镜像）**保留函数定义但不再挂载**；
+如需恢复回退，把对应条目加回 `AUTH_PROVIDERS` 数组即可。
+
+- 未取得凭据的报错与 401 提示统一改为「唯一来源 = weaver-work-cli，**不设回退**」，
+  并直接引导 `weaver-work-cli auth login --base-url <域名>`；
+- ⇒ **使用前必须已登录 `weaver-work-cli`**，否则所有需要凭据的命令都会报错
+  （用 `weaver-work-cli auth status --no-check` 确认）。`login xiaoe-env` 不受影响。
+
+### 3. 修复：补齐 `userId` / `tenantKey` 传递
+
+`auth export-weaver-env` **只导出 5 个变量**（`WEAVER_BASE_URL` / `WEAVER_ETEAMSID` /
+`WEAVER_COOKIE` / `WEAVER_USER_AGENT` / `WEAVER_AGENT_TYPE`），**不含 `userId`**。
+而 `auth.userId` 会被部分命令用作「当前登录用户」的默认值——实测 `e10-data attend statis`
+缺它直接报 `ERROR: 缺少查询人员：--user <人员ID>`。
+
+⇒ 在凭据出口内**追加一次 `auth status --json --no-check`** 取回 `userId` / `tenantKey`
+（二者为非凭据身份字段，取不到不影响凭据可用性；凭据进程间 TTL 缓存仍兜住额外开销）。
+
+## 0.1.19（2026-09-24）—— 发现层聚合：新增 `ds find` / `ds describe` / `ds groups`，修复 `--name` 静默失效
+
+### 1. 新增 `ds find`（跨分组找表，进程内并发）
+
+把原来「定分组 → 找表」的多跳串行收敛成一次调用。**关键收益来自进程内并发**：单次 CLI 调用约 5.4s，
+其中「凭据现取」固定约 4.8s 且**与请求条数无关**（实测取 48 条 vs 取 1 条：5.5s vs 5.8s），
+所以 N 个分组分散在 N 个进程里是纯浪费。
+
+- `ds find --name <关键词>`：默认扫**核心 3 组**（业务表单 / e-builder表单 / 流程）+ 语义命中组（≤ `--max-groups`，默认 6）
+- `--all-groups`：扫全部 58 个内置分组 —— 实测 **5.3~5.9s**（对比：逐进程并发 47.5s、逐进程串行 ~313s）
+- 默认集合全 miss 时**自动升级为全分组扫一次**（`--no-escalate` 可关）
+- 输出按**实体归并去重**：同一流程会同时出现在「流程」与 3 个「工作流*效率」分组，去重后落选分组记入 `alsoInGroups`
+- 附带 `routeHint`：**命中分组分布本身就是通道信号**（命中 workflow 类分组 → 该走 WORKFLOW 模块通道，不走数据源）
+- ⚠️ 该端点当前忽略 `name` ⇒ 关键词过滤暂由**本地**完成（抓 `--pages` × `--size` 行后按表名过滤），
+  计数与样例放在 `nameFilter`（**不静默丢弃**），`--loose` 关闭该过滤；**未命中 ≠ 表不存在**（详见第 3 节）
+
+### 2. 新增 `ds describe`（一次并发取回「字段 + 词库」）
+
+两者入参同为 `(groupId, tableId)`、彼此无依赖，故并行合成一次调用（实测 ~0.5s）。
+
+- 字段：归一化为 `main[] / detail[]`（明细子表单独成组），保留 `name / text / type / dbFieldType / isPK / dataKey`
+- 词库：自动带 `data-source-query` 四参数（skillKey + sourceType + sourceGroupId + sourceTableId）；
+  返回 `noLexicon: true` 时是**确定结论**（四参数均取自本次调用），不再是难以区分的 500
+- `relatedFields`：按 groupId/serviceMark **预判**关联字段提取是否适用 ——
+  业务表单（formreport）表名是中文显示名、非物理表名，六类判定全部不适用，该跳必然空转，直接标注不必发起
+- ⚠️ **不做权限校验**：`ds/listByPage` 虽然也回带 appId，但**数据源通道不拦权限**（实测未授权表照样能取到数据），
+  拿它跳过校验 = 权限闸门静默失效。⇒ EB 表取数前的权限闸门仍必须单独执行 `eb perm-page`（appId 只从那次调用取）。
+
+### 3. `ds listByPage` 端点收敛为唯一入口 + 关键词过滤的过渡方案
+
+**端点决策（用户 2026-09-24 确认）：只保留 `/api/dw/newetl/chatBi/ds/listByPage`** ——
+另一条 `/api/ebuilder/common/ds/listByPage` **已从代码中移除**（对应的 `DS_LB_*` 双端点常量、
+`E10_DS_LISTBY_PAGE_ORDER` 环境变量开关一并删除）。现由 `dsListByPage()` 单一封装发起（`DS_LB_PATH`）。
+
+**为什么需要过渡方案**：该端点**当前忽略 `name`**（传 `name`/`tableName`/`keyword`/`searchKey`/`tableText`/`title` 任意字段名，
+都返回该分组全量，实测 8531 条）⇒ 服务端无法按关键词过滤。**后端后续会升级支持 `name`（已确认）**。
+
+⇒ 过渡做法：`ds find` 改为「**分页抓取 + 本地按表名过滤**」，抓取窗口 = `--size`（≤2000）× `--pages`（≤50）。
+
+- 实测后端**接受大 pageSize**（100/500/1000/2000 均按量返回，非只认 100）→ 单次即可覆盖多数分组
+- 输出新增 `nameFilter`：写明 `serverSide:false`、`pages/pageSize/rowsScanned/dropped` 与说明
+- ⚠️ **未命中不再等于「表不存在」**：交付话术与输出都改为「未落在已扫描的 N 行窗口内」，
+  并提示调大 `--size/--pages`；避免把「窗口不够大」误判成「没有这张表」
+- 自动升级全扫增加护栏：窗口 >2000 行时不再自动全扫（否则会变成 58 组 × N 页的请求风暴）
+- **后端支持 `name` 后无需改任何调用方式**：分页与 `total` 语义已按「服务端过滤」写好，届时自动恢复精确过滤
+
+> 参照：两端点返回结构**逐字段相同**（26 个键）；差异在 `name` 是否生效与数据范围
+> （实测 EB 分组：ebuilder 不带 appId=633、chatBi=11535、ebuilder+appId=55，且 `name` 只在前者域内生效）——
+> 这是当初考虑双端点的原因，现按决策统一走 chatBi 端点，并保留 `--app-id` 透传（EB 分组按应用分域时需要）。
+
+### 4. 新增 `ds groups`
+
+打印内置分组清单（含 `groupId` / 中文名 / `serviceMark`）、核心分组与语义规则，便于挑选 `--groups`。
+⚠️ 该清单仅用于 `ds find` 的默认扫描候选集，**不参与任何取数参数推导**；分组随环境变动时用 `--groups` 显式覆盖。
+
 ## 0.1.18（2026-09-24）—— 新增 ds fields-dsl / 收敛凭据明文落盘
 
 ### 1. 新增 `ds fields-dsl` 子命令

package/README.md

@@ -9,7 +9,7 @@ npm i -g e10-data        # 全局安装
 e10-data --version       # 验证
 ```
 
-> 依赖：认证复用 `weaver-e10-login` 的登录态。**加解密全部由 `e10-login` 负责，本 CLI 不实现任何加解密**（auth 文件由 e10-login 自己的密钥体系加密：1.5.0 起为「每机随机密钥 + OS keychain」，早期版本为固定 seed，只有 e10-login 解得开）。CLI 通过 e10-login 的命令出口取明文凭据，优先级：**① `e10-login auth --json`**（推荐的正式契约）→ **② `e10-login whoami --json`**（其 JSON 带 `cookies` 时）→ **③ `e10-login whoami`**（文本解析，当前实际路径）→ **④ 明文镜像 `~/.workbuddy/e10-login-cache.md`**（兜底，命中时打印告警）。请先安装并登录 weaver-e10-login（`e10-login oidc`）。
+> 依赖：认证**唯一来源 = `weaver-work-cli`（不设回退）**。**加解密全部由 `e10-login` 负责，本 CLI 不实现任何加解密**（auth 文件由 e10-login 自己的密钥体系加密：1.5.0 起为「每机随机密钥 + OS keychain」，早期版本为固定 seed，只有 e10-login 解得开）。CLI 通过 e10-login 的命令出口取明文凭据，优先级：**① `e10-login auth --json`**（推荐的正式契约）→ **② `e10-login whoami --json`**（其 JSON 带 `cookies` 时）→ **③ `e10-login whoami`**（文本解析，当前实际路径）→ **④ 明文镜像 `~/.workbuddy/e10-login-cache.md`**（兜底，命中时打印告警）。请先安装并登录 weaver-e10-login（`e10-login oidc`）。
 >
 > 唯一例外：**`e10-data login xiaoe-env`** 在「还没有任何凭据」时也能独立完成登录（用环境变量里的 XiaoE 全局 token 换 ETEAMSID；换 token 本 CLI 自己算，写 profile 仍交 `e10-login set`）。
 
@@ -25,6 +25,7 @@ e10-data field   id2name|name2id                       关联字段翻译（test
 e10-data conf    get|batch|batch-file|group|group-file|resolve|resolve-file|add|add-file|update|delete   环境参数配置中心（chatBi config map，替代 config-resolve 脚本 URL 直连；confType 默认按 CONN_/DS_/WF_/API_ 前缀推导，可 --type 显式；confType=api 时支持 confGroup 分组，见下）
 e10-data exp     status|manifest|commits|file|pull|init|commit|lock|release|rollback   专家包版本管理
 e10-data attend  statis   考勤假期余额统计 getAttendInfoStatis（hr-attendance 病假/事假等，v0.1.5 新增）
+e10-data module  call     模块配置接口调用（配置中心驱动；已确定「哪个模块的哪条具体接口」之后的统一取数入口，v0.1.21 新增）
 ```
 
 ## 通用约定
@@ -32,7 +33,7 @@ e10-data attend  statis   考勤假期余额统计 getAttendInfoStatis（hr-atte
 - `--json`：原样输出接口 JSON（供脚本/Agent 消费）；默认人读输出。
 - 复杂 JSON/中文参数：推荐 `@文件` 承载（如 `--dsl @q.json`、`--where @cond.json`）。
 - ⚠️ 大整数精度（自动处理）：E10 的 ID 多为 19 位，超过 JS 安全整数（2^53-1≈9e15）。CLI 解析 JSON 时**自动把超范围裸整数转成字符串**再发请求/输出（实测后端接受字符串做 =/IN/BETWEEN 数值比较），无需手动加引号，也不误伤字符串正文。
-- 认证：**加解密由 `e10-login` 负责（本 CLI 不参与）**。凭据出口优先级：`e10-login auth --json` → `e10-login whoami --json` → `e10-login whoami`（文本）→ 明文镜像 `~/.workbuddy/e10-login-cache.md`（兜底，命中时告警）。命中的出口会记入 `~/.e10-cli/.e10-data-auth-mode`（只存模式名、不存凭据），下次优先复用。环境变量：`E10_DATA_AUTH_PROBE=1` 强制重新探测、`E10_DATA_AUTH_MODE=<模式名>` 手动指定、`E10_DATA_QUIET=1` 抑制告警（告警只走 stderr）。**没有任何可用凭据时**用 `e10-data login xiaoe-env` 登录（见下节）。
+- 认证：**加解密由 `e10-login` 负责（本 CLI 不参与）**。凭据出口：`weaver-work-cli auth export-weaver-env`（解析 `WEAVER_BASE_URL` / `WEAVER_ETEAMSID` / `WEAVER_COOKIE`，另补一次 `auth status` 取 `userId` / `tenantKey`），**已移除 e10-login 回退**。命中的出口会记入 `~/.e10-cli/.e10-data-auth-mode`（只存模式名、不存凭据），下次优先复用。环境变量：`E10_DATA_AUTH_PROBE=1` 强制重新探测、`E10_DATA_AUTH_MODE=<模式名>` 手动指定、`E10_DATA_QUIET=1` 抑制告警（告警只走 stderr）。**没有任何可用凭据时**用 `e10-data login xiaoe-env` 登录（见下节）。
 - 版本更新：`npm i -g e10-data@latest`；查看源上最新 `npm view e10-data version`。
 
 ## 性能：免凭据命令与凭据缓存（v0.1.17 新增）
@@ -54,9 +55,10 @@ e10-data attend  statis   考勤假期余额统计 getAttendInfoStatis（hr-atte
 | 变量 | 作用 |
 |---|---|
 | `E10_DATA_CRED_TTL` | 缓存 TTL 秒数，默认 `300` |
-| `E10_DATA_NO_CRED_CACHE=1` | 整体关闭凭据缓存（每次仍直连 e10-login） |
+| `E10_DATA_NO_CRED_CACHE=1` | 整体关闭凭据缓存（每次仍直连 weaver-work-cli） |
 | `E10_DATA_AUTH_PROBE=1` / `E10_DATA_AUTH_MODE=…` | 存在时**绕过缓存**，强制重新解析凭据 |
-| `E10_LOGIN_ENTRY` | 显式指定 `e10-login` 的 JS 入口路径（排障用） |
+| `WEAVER_WORK_CLI_ENTRY` | 显式指定 `weaver-work-cli` 的 JS 入口路径（凭据出口排障用） |
+| `E10_LOGIN_ENTRY` | 显式指定 `e10-login` 的 JS 入口路径（仅 `login xiaoe-env` 落 profile 时用） |
 
 > ⚠️ TTL 采用「先到先得」：若已有一个 TTL=300 的持有者在服务，此时以更短的 `E10_DATA_CRED_TTL` 再调用不会立刻缩短它的寿命（新持有者因通道被占而静默退出）。日常使用无需关注。
 
@@ -263,3 +265,52 @@ e10-data attend statis [--user <人员ID>] [--begin 2026-09-01] [--end 2026-09-3
 - `--json`：原样输出接口 JSON（含 `data.attendStatis` 出勤统计 / `data.attendSummary` 汇总 / `data.leaveInfo` 请假 / `data.outAttend` 外出 / `data.vacationBalanceList` 假期余额）；
 - 默认人读输出：仅列出 `data.vacationBalanceList`（按 title 区分假期类型）——带薪病假 `100584850000000003`、带薪事假 `100584850000000010` 含 `lastRemaining`(历年可请)/`remaining`(今年可请)/`total`(总计可请) 三项。
 
+## module call 模块配置接口调用（v0.1.21 新增）
+
+**用途**：**已确定「哪个模块的哪条具体接口」之后**的统一取数入口。定位模块 → 拉接口清单 → 选接口仍由技能侧完成，
+**第四步「组参调用」收敛到本命令**：精取该条 `confAttrs` → 按 `http_method` / `input_params` 组参
+→ 发请求（自动禁代理 + `Cookie` / `eteamsid` / `User-Agent: AgentType=…,IsAgent=true` 三件套）
+→ 按外层结构（`datajson` / `data` / `records` / 裸数组）提取精简结果。
+
+```bash
+e10-data module call --conf-key <confKey> --group <模块> \
+  [--args '<JSON>'|--args @params.json] [--query "k=v&k2=v2"] \
+  [--method GET|POST|FORM] [--header 'K: V'|--headers '<JSON>'|@file] \
+  [--limit 50] [--fields a,b] [--raw] [--show-params] [--dry-run] [--timeout 60] [--json]
+```
+
+| 参数 | 说明 |
+|---|---|
+| `--conf-key` / `--group` | **必填**；`confKey` 取自模块接口清单，`--group` = 模块唯一标识（confGroup，如 `WORKFLOW` / `EHR` / `DOCUMENT`） |
+| `--args` | 业务参数 JSON 对象；**含中文一律用 `--args @文件`**（规避 shell 编码损坏） |
+| `--query` | 追加 query（`k=v&k2=v2`，多对用 `&` 连接；与 `--args` 合并） |
+| `--method` | 覆盖 `confAttrs.http_method`（`FORM` = `x-www-form-urlencoded`） |
+| `--header` / `--headers` | 追加请求头：单条 `'K: V'`，或 JSON 对象（可 `@文件`） |
+| `--show-params` | **只打印该接口的入/出参说明与请求示例、不调接口** —— 替代手工 `conf get` dump，用于正确组参 |
+| `--dry-run` | 只组装请求不发送（**凭据一律脱敏**） |
+| `--limit` / `--fields` | 列表行数上限（默认 50，`0` = 不截断）/ 每行字段投影 |
+| `--raw` | 不提取，原样输出响应体 |
+
+- **与技能自带 `script/call_module.py` 等价**（参数名 / 退出码 / 提取口径全对齐，可互为替换），差异只有两点：
+  ① **复用本 CLI 的凭据缓存与 `conf` 通道**（不额外起 python、不重复取凭据）；② **零临时文件**（body 内存直发，不落盘）。
+- **退出码**（`main().catch` 按 `e.exitCode` 退出）：`0` 正常（**空结果也算正常**）｜`2` 未登录 / 凭据失效 → 重登
+  ｜`3` 非 JSON / `confAttrs` 异常 / 配置不存在 ｜`4` 权限受限（`hasSearchRight=false`，终端态：立即终止）
+  ｜`6` 命中 HRM 路径黑名单（拒绝调用）｜`7` 请求失败 ｜`8` 用法错误。
+- **标志位点名**：`hasSearchRight=false`（权限受限 ≠ 无数据）与 `pageUid="checkSecondFail"`（二次身份验证：
+  `total` 可信、明细恒 0 行）会在输出 `flags` 中列出，前者同时以退出码 `4` 收口。
+- **INVOICE 自动换取发票云 `token`**：`--group` / `module_key` 为 `INVOICE` 时先 `GET /api/inc/proxy/getToken?appType=1`
+  取 `data.token` 写入请求头；**Token 只在内存透传，不打印、不落盘**。
+- **HRM 路径黑名单**：`/api/hrm/`、`/api/bs/hrm/`、`/api/app/hrm/` 的接口在发请求前直接拒绝（退出码 `6`）——
+  人员 / 部门 / 分部 / 岗位一律走 `weaver-work-cli` 的 `hrm` 子命令。
+
+```bash
+# 看某个接口要什么参数（不调接口）
+e10-data module call --conf-key POST_EHR_GET_REPORT_LIST --group EHR --show-params
+
+# 真实取数（含中文参数走 @文件）
+e10-data module call --conf-key POST_EHR_GET_REPORT_LIST --group EHR --args @params.json --json
+
+# GET 接口 + 只看两行、只留三个字段
+e10-data module call --conf-key GET_XXX --group XXX --query "pageNo=1&pageSize=20" --limit 2 --fields id,name --json
+```
+