@besile/scm-cli 2026.3.29

package/README.zh.md

@@ -0,0 +1,451 @@
+# SCM CLI
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D14-blue.svg)](https://nodejs.org/)
+
+供应链管理（SCM）系统 CLI 工具 — 在终端中查询大货生产订单、物料订单和 QC 质检订单，对接飞书身份认证系统。
+
+[安装](#安装与快速开始) · [认证](#认证) · [三层命令调用](#三层命令调用) · [快捷命令](#快捷命令-shortcuts) · [进阶用法](#进阶用法) · [安全](#安全与风险提示使用前必读) · [贡献](#贡献)
+
+## 为什么选 scm-cli？
+
+- **飞书身份集成** — 基于飞书 openId 认证，无需记忆额外账号密码
+- **三分钟上手** — 一键安装，交互式登录，从安装到第一次查询只需三步
+- **双层调用架构** — 标准命令（全面控制）→ 快捷命令（快速上手），按需选择
+- **AES 加密存储** — 用户密码和 Token 均加密存储于本地
+- **多格式输出** — 支持 table / json / pretty 三种输出格式
+- **Token 自动续期** — 缓存 Token 自动检查，过期前无缝续期
+
+## 功能
+
+| 类别           | 能力                                                                 |
+| -------------- | -------------------------------------------------------------------- |
+| 🔐 认证管理    | 登录、登出、Token 状态检查、Token 列表管理                               |
+| 📦 大货生产订单 | 查询订单列表，支持订单状态、供应商、商品信息、时间、设计师等多维筛选         |
+| 🧴 物料订单    | 查询物料订单，支持按订单号、大货款号、批次、供应商等条件筛选                 |
+| 🔍 QC 质检订单 | 查询 QC 质检订单，支持质检状态、款号、供应商、时间等筛选条件               |
+
+## 安装与快速开始
+
+### 环境要求
+
+- Node.js（`npm`/`npx`）14+
+- SCM API 服务地址（配置方式见下文）
+
+### 安装
+
+以下两种方式**任选其一**：
+
+**方式一 — 从源码安装（推荐）：**
+
+```bash
+git clone <your-repo-url>
+cd scm-cli
+./install.sh
+```
+
+**方式二 — 手动安装：**
+
+```bash
+# 克隆项目
+git clone <your-repo-url>
+cd scm-cli
+
+# 安装依赖
+npm install
+
+# 链接到全局
+npm link
+```
+
+#### 验证安装
+
+```bash
+scm-cli --help
+```
+
+### 配置
+
+安装完成后，需要配置环境变量才能连接 SCM API：
+
+```bash
+# 方式一：创建 .env 文件（项目根目录）
+cp .env.example .env
+# 编辑 .env 填入以下配置
+
+# 方式二：直接设置环境变量
+export SCM_BASE_URL=http://localhost:48080
+export SCM_DEBUG=false
+```
+
+**可选的环境变量：**
+
+| 变量           | 说明                          | 默认值                                 |
+| -------------- | ----------------------------- | ------------------------------------- |
+| `SCM_BASE_URL` | SCM API 端点地址（**必需**）  | `https://fbscmtest.cogo.club`          |
+| `SCM_DEBUG`    | 开启调试模式                  | `false`                               |
+
+> **说明**：`SCM_AES_KEY` 和 `SCM_AES_IV` 已内置于代码中，无需配置。如需自定义加密密钥，请联系 SCM 系统管理员。
+
+### 快速开始
+
+**第 1 步 — 登录**
+
+```bash
+scm-cli auth login \
+  --openId <飞书openId> \
+  --mobile <手机号> \
+  --password <密码>
+```
+
+**第 2 步 — 查询大货生产订单**
+
+```bash
+# 标准命令
+scm-cli production-orders --openId <openId> --pageSize 20
+
+# 快捷命令（更简洁）
+scm-cli production-orders +list --openId <openId>
+```
+
+**第 3 步 — 查看帮助**
+
+```bash
+scm-cli --help
+scm-cli auth --help
+scm-cli production-orders --help
+```
+
+## 认证
+
+| 命令                          | 说明                                 |
+| ------------------------------ | ------------------------------------ |
+| `auth login`                  | 登录 SCM 系统（基于飞书身份）           |
+| `auth logout`                | 登出，删除本地 Token                   |
+| `auth status`                | 检查 Token 状态                       |
+| `auth token list`            | 列出所有缓存的 Token                   |
+| `auth token show <openId>`   | 显示指定用户的 Token 详情               |
+| `auth token clear <openId>`  | 清除指定用户的 Token                   |
+| `auth token clear-all`       | 清除所有缓存的 Token                    |
+
+```bash
+# 登录
+scm-cli auth login --openId ou_xxxx --mobile 13800138000 --password 123456
+
+# 检查 Token 状态
+scm-cli auth status --openId ou_xxxx
+
+# 查看所有缓存的 Token
+scm-cli auth token list
+
+# 登出
+scm-cli auth logout --openId ou_xxxx
+```
+
+### Token 存储
+
+- Token 缓存路径：`~/.scm_cache/user_tokens.json`
+- 密码使用 **AES-128-CBC** 加密后再传输和存储
+- Token 有效期约 12 小时，过期前自动刷新
+
+## 三层命令调用
+
+CLI 提供两种粒度的调用方式，覆盖从快速查询到精确筛选的全部场景：
+
+### 1. 标准命令
+
+标准命令提供最完整的筛选参数集，适合需要精确控制查询条件的场景：
+
+```bash
+# 大货生产订单 — 所有筛选参数
+scm-cli production-orders \
+  --openId <openId> \
+  --pageNo 1 \
+  --pageSize 20 \
+  --prodStatus 3 \
+  --confirmSupplier 1 \
+  --supplierOrderStatus 1 \
+  --quotationStatus 2 \
+  --washStatus 1 \
+  --qcInspection 1 \
+  --goodsFullCode "款号001" \
+  --goodsBatch "批次001" \
+  --goodsType 0 \
+  --supplierName "某供应商" \
+  --cooperationMode 0 \
+  --pdUserIdList "1,2,3" \
+  --purchaserIdList "4,5,6" \
+  --designerName "设计师A" \
+  --type 2 \
+  --startTime "2026-01-01" \
+  --endTime "2026-12-31" \
+  --saleArea "1,2,3"
+
+# 物料订单 — 所有筛选参数
+scm-cli material-orders \
+  --openId <openId> \
+  --pageNo 1 \
+  --pageSize 20 \
+  --orderNo "MO202603001" \
+  --status 1 \
+  --cooperationMode 0 \
+  --goodsFullCode "款号001" \
+  --goodsBatch "批次001" \
+  --goodsType 0 \
+  --supplierName "某供应商" \
+  --purchaserIdList "4,5,6" \
+  --pdUserIdList "1,2,3" \
+  --designerName "设计师A" \
+  --type 2 \
+  --startTime "2026-01-01" \
+  --endTime "2026-12-31"
+
+# QC 质检订单 — 所有筛选参数
+scm-cli qc-orders \
+  --openId <openId> \
+  --pageNo 1 \
+  --pageSize 20 \
+  --qcOrderStatus 1 \
+  --goodsFullCode "款号001" \
+  --goodsType 1 \
+  --goodsGradeList "A,B" \
+  --supplierName "某供应商" \
+  --midManager "中查管理员A" \
+  --checkGoods "查货人员B" \
+  --tailManager "尾查管理员C" \
+  --qcUserIdList "1,2,3" \
+  --prodManagerIdList "4,5,6" \
+  --purchaserIdList "7,8,9" \
+  --timeType 2 \
+  --startTime "2026-01-01" \
+  --endTime "2026-12-31"
+```
+
+### 2. 快捷命令（Shortcuts）
+
+以 `+` 为前缀，是对人机友好化封装，内置智能默认值，适合快速查询：
+
+```bash
+# 大货生产订单 — 列表查询
+scm-cli production-orders +list --openId <openId>
+
+# 大货生产订单 — 高级查询
+scm-cli production-orders +query \
+  --openId <openId> \
+  --prod-status 3 \
+  --supplier-name "某供应商"
+
+# 物料订单 — 列表查询
+scm-cli material-orders +list --openId <openId>
+
+# QC 质检订单 — 列表查询
+scm-cli qc-orders +list --openId <openId>
+```
+
+## 快捷命令（Shortcuts）
+
+| 命令                           | 说明                                       |
+| ------------------------------ | ------------------------------------------ |
+| `production-orders +list`     | 查询大货生产订单列表（分页，默认 20 条/页）     |
+| `production-orders +query`    | 查询大货生产订单（支持全部筛选条件）           |
+| `material-orders +list`       | 查询物料订单列表（分页）                       |
+| `qc-orders +list`              | 查询 QC 质检订单列表（分页）                  |
+
+### 生产订单快捷命令详解
+
+**`+list` — 快速列表查询**
+
+```bash
+scm-cli production-orders +list \
+  --open-id <openId> \
+  [--page-no 1] \
+  [--page-size 20]
+```
+
+**`+query` — 完整条件查询**
+
+支持以下所有筛选参数：
+
+| 参数                   | 说明                                                                  |
+| --------------------- | --------------------------------------------------------------------- |
+| `--prod-status`      | 大货生产订单状态: `-1`-全部`0`-待确定`1`-待同步`2`-在途中`3`-已完成`100`-已取消 |
+| `--confirm-supplier` | 确认供应商: `0`-未确认`1`-已确认                                           |
+| `--goods-full-code`  | 大货款号                                                                |
+| `--goods-batch`      | 大货批次                                                                 |
+| `--goods-type`       | 大货类型: `0`-首单`1`-加单`2`-翻单                                        |
+| `--supplier-name`    | 供应商名称                                                               |
+| `--cooperation-mode` | 合作模式: `0`-CMT`1`-FOB                                              |
+| `--designer-name`    | 设计师名称                                                               |
+| `--start-time` / `--end-time` | 时间范围 (ISO 8601)                                       |
+| `--qc-inspection`    | QC 质检结果                                                              |
+
+### 物料订单快捷命令详解
+
+**`+list` — 物料订单列表**
+
+```bash
+scm-cli material-orders +list \
+  --open-id <openId> \
+  [--page-no 1] \
+  [--page-size 20] \
+  [--order-no <订单号>] \
+  [--goods-full-code <款号>] \
+  [--goods-batch <批次>] \
+  [--goods-type <类型>] \
+  [--supplier-name <供应商名>] \
+  [--status <状态值>]
+```
+
+### QC 质检订单快捷命令详解
+
+**`+list` — QC 质检订单列表**
+
+```bash
+scm-cli qc-orders +list \
+  --open-id <openId> \
+  [--page-no 1] \
+  [--page-size 10] \
+  [--qc-order-status <状态值>] \
+  [--goods-full-code <款号>] \
+  [--goods-type <类型>] \
+  [--supplier-name <供应商名>] \
+  [--mid-manager <中查管理员>] \
+  [--check-goods <查货人员>] \
+  [--tail-manager <尾查管理员>] \
+  [--qc-user-id-list <QC用户ID列表>] \
+  [--prod-manager-id-list <生产经理ID列表>] \
+  [--purchaser-id-list <采购员ID列表>] \
+  [--time-type <时间类型>] \
+  [--start-time <开始时间>] \
+  [--end-time <结束时间>]
+```
+
+## 进阶用法
+
+### 输出格式
+
+```bash
+--format json      # 完整 JSON 响应（API 原生格式）
+--format pretty    # 人性化格式输出
+--format table     # 易读表格（默认）
+```
+
+```bash
+# 输出 JSON
+scm-cli production-orders +list --openId ou_xxxx --format json
+
+# 输出易读格式
+scm-cli material-orders +list --openId ou_xxxx --format pretty
+```
+
+### 调试模式
+
+```bash
+# 全局调试
+scm-cli --debug production-orders +list --openId ou_xxxx
+
+# 或设置环境变量
+export SCM_DEBUG=true
+scm-cli production-orders +list --openId ou_xxxx
+```
+
+### 常用查询示例
+
+```bash
+# 查询生产中（状态=3）的订单
+scm-cli production-orders +query \
+  --open-id ou_xxxx \
+  --prod-status 3 \
+  --page-size 50
+
+# 查询指定供应商的所有物料订单
+scm-cli material-orders +list \
+  --open-id ou_xxxx \
+  --supplier-name "某服装厂"
+
+# 查询 QC 待检订单
+scm-cli qc-orders +list \
+  --open-id ou_xxxx \
+  --qc-order-status 0
+
+# 按时间范围查询（近一个月）
+scm-cli production-orders +query \
+  --open-id ou_xxxx \
+  --start-time "2026-03-01" \
+  --end-time "2026-04-13"
+```
+
+## 安全与风险提示（使用前必读）
+
+本工具对接 SCM 供应链管理系统，涉及生产订单、物料采购等商业敏感数据。请在使用前充分知悉以下风险：
+
+**认证风险** — Token 缓存于本地文件，密码通过 AES-128-CBC 加密存储，请勿将本工具暴露于不受信任的环境。
+
+**数据安全** — Token 有效期约 12 小时，过期后需要重新认证。请勿将 Token 或配置文件泄露给他人。
+
+**权限管控** — 所有操作权限取决于飞书账号的 SCM 系统授权范围，请按最小权限原则分配飞书身份。
+
+请您充分知悉全部使用风险，使用本工具即视为您自愿承担相关所有责任。
+
+## 项目结构
+
+```
+scm-cli/
+├── bin/
+│   └── scm-cli.js              # CLI 入口点
+├── src/
+│   ├── cmd/                    # Layer 1: Commander 命令注册
+│   │   ├── root.js             # 根命令 + 全局参数（--format, --debug）
+│   │   ├── index.js            # 注册所有子命令
+│   │   ├── auth/               # 认证子命令
+│   │   │   ├── login.js        # 登录
+│   │   │   ├── logout.js       # 登出
+│   │   │   ├── status.js       # Token 状态检查
+│   │   │   └── token.js        # Token 管理（列表/清除）
+│   │   └── orders/             # 订单子命令
+│   │       ├── production-orders.js
+│   │       ├── material-orders.js
+│   │       └── qc-orders.js
+│   ├── shortcuts/               # Layer 2: 快捷命令（Shortcuts）
+│   │   ├── common/
+│   │   │   ├── types.js        # Shortcut 类型定义
+│   │   │   └── runner.js       # Shortcut 执行管道
+│   │   ├── register.js         # 注册 Shortcuts 到命令树
+│   │   ├── production-orders/ # +list, +query 快捷命令
+│   │   ├── material-orders/    # +list 快捷命令
+│   │   └── qc-orders/          # +list 快捷命令
+│   └── internal/                # Layer 3: 核心库
+│       ├── index.js             # 统一导出
+│       ├── client/             # ScmClient 单例
+│       ├── errors/             # 错误类层次结构
+│       ├── output/             # 格式化输出 + 日志
+│       ├── config/             # 配置文件加载
+│       └── auth/               # Token 存储与认证
+├── tests/                      # 测试用例
+├── install.sh                  # 安装脚本
+└── package.json
+```
+
+## 开发
+
+```bash
+# 安装依赖
+npm install
+
+# 运行测试
+npm test
+
+# 监听模式运行测试
+npm run test:watch
+
+# 带覆盖率运行测试
+npm run test:coverage
+```
+
+## 贡献
+
+欢迎提交 Issue 或 Pull Request！对于较大的改动，建议先通过 Issue 讨论。
+
+## 许可证
+
+本项目基于 **MIT 许可证** 开源。

package/bin/scm-cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+/**
+ * Copyright (c) 2026 WFS
+ * SPDX-License-Identifier: MIT
+ *
+ * scm-cli — SCM CLI 工具入口
+ *
+ * 用法:
+ *   scm-cli --help
+ *   scm-cli auth login --openId <openId> --mobile <手机号> --password <密码>
+ *   scm-cli auth logout --openId <openId>
+ *   scm-cli auth status --openId <openId>
+ *   scm-cli production-orders --openId <openId> [--goodsFullCode <款号>]
+ *   scm-cli material-orders --openId <openId> [--orderNo <订单号>]
+ *   scm-cli qc-orders --openId <openId> [--qcOrderStatus <状态>]
+ *   scm-cli production-orders +list --openId <openId> [--format table]
+ *   scm-cli production-orders +query --openId <openId> [--prod-status 3]
+ */
+
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createProgram, buildInternalContext } from '../src/cmd/root.js';
+import { registerCommands } from '../src/cmd/index.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const projectRoot = dirname(__dirname);
+
+const { version } = JSON.parse(readFileSync(join(projectRoot, 'package.json'), 'utf-8'));
+
+const program = createProgram({ version, name: 'scm-cli' });
+const internalCtx = buildInternalContext({ debug: process.env.SCM_DEBUG === 'true' });
+
+registerCommands(program, internalCtx);
+
+program.parse();

package/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Copyright (c) 2026 WFS
+ * SPDX-License-Identifier: MIT
+ *
+ * OpenClaw SCM Plugin entry point.
+ *
+ * SCM 供应链管理插件入口
+ *
+ * 注册工具:
+ * - scm_login: 登录认证
+ * - scm_production_orders: 大货生产订单查询
+ * - scm_material_orders: 物料订单查询
+ * - scm_qc_orders: QC 质检订单查询
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+
+// SCM 客户端
+export { scmClient } from './src/core/scm-client';
+
+// SCM 错误类
+export { ScmError, ScmAuthError, ScmTokenExpiredError, ScmTokenInvalidError, ScmApiError, ScmTimeoutError, ScmNetworkError } from './src/core/scm-errors';
+export type { ScmErrorOptions, ScmApiErrorOptions } from './src/core/scm-errors';
+
+// 工具执行函数 - scm_login
+export { executeScmLogin } from './src/tools/login/execute';
+
+// 工具执行函数 - scm_production_orders
+export { executeProductionOrders } from './src/tools/production-orders/execute';
+
+// 工具执行函数 - scm_material_orders
+export { executeMaterialOrders } from './src/tools/material-orders/execute';
+
+// 工具执行函数 - scm_qc_orders
+export { executeQcOrders, buildRequestBody as buildQcOrdersRequestBody } from './src/tools/qc-orders/execute';
+
+// 工具注册函数
+export { registerScmLoginTool } from './src/tools/login/index';
+export { registerScmProductionOrdersTool } from './src/tools/production-orders/index';
+export { registerScmMaterialOrdersTool } from './src/tools/material-orders/index';
+export { registerScmQcOrdersTool } from './src/tools/qc-orders/index';
+
+// SCM 插件 Channel
+export { scmPlugin } from './src/channel/plugin';
+
+// 工具辅助函数
+export { createToolContext, formatResult, formatSuccess, formatError, formatApiError, getUserToken, clearUserToken } from './src/tools/helpers';
+export type { ToolContext } from './src/tools/helpers';
+
+// 日志辅助函数
+export { scmLogger, setRuntimeLoggerFactory } from './src/core/scm-logger';
+
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: Record<string, unknown>;
+    register(api: OpenClawPluginApi): void;
+};
+export default plugin;

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@besile/scm-cli",
+  "version": "2026.3.29",
+  "description": "SCM CLI — Supply Chain Management CLI Tool",
+  "type": "module",
+  "license": "MIT",
+  "author": "WFS",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wfs/scm-cli"
+  },
+  "keywords": [
+    "scm",
+    "supply-chain",
+    "cli",
+    "production-order",
+    "manufacturing"
+  ],
+  "files": [
+    "bin/",
+    "src/",
+    "index.d.ts"
+  ],
+  "bin": {
+    "scm-cli": "./bin/scm-cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/internal/index.js",
+      "default": "./src/internal/index.js"
+    }
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@larksuiteoapi/node-sdk": "^1.7.0",
+    "@sinclair/typebox": "^0.34.48",
+    "commander": "^14.0.3",
+    "dotenv": "^17.3.1"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.9",
+    "vitest": "^2.0.0"
+  }
+}

package/src/cmd/auth/login.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * Copyright (c) 2026 WFS
+ * SPDX-License-Identifier: MIT
+ *
+ * scm-cli auth login command
+ */
+import { scmClient, loadConfig, createLogger } from '../../internal/index.js';
+
+/**
+ * Execute login
+ *
+ * @param {string} openId - 飞书用户 openId
+ * @param {string} mobile - 手机号
+ * @param {string} password - 密码
+ * @returns {Promise<Object>} Login result
+ */
+export async function doLogin(openId, mobile, password) {
+    const config = loadConfig();
+    const log = createLogger(config.debug);
+
+    // Encrypt password with AES-128-CBC
+    const { createCipheriv } = await import('node:crypto');
+    const cipher = createCipheriv(
+        'aes-128-cbc',
+        Buffer.from(config.aesKey, 'ascii'),
+        Buffer.from(config.aesIv, 'ascii')
+    );
+    const encrypted = Buffer.concat([
+        cipher.update(Buffer.from(password, 'utf-8')),
+        cipher.final(),
+    ]).toString('base64');
+
+    const loginUrl = `${config.baseUrl}/admin-api/system/auth/login`;
+
+    const response = await fetch(loginUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ mobile, password: encrypted }),
+    });
+
+    const data = await response.json();
+
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    if (data.code !== 200 && data.success !== true) {
+        throw new Error(data.msg || `登录失败，错误码: ${data.code}`);
+    }
+
+    const tokenInfo = data.data || {};
+    return {
+        openId,
+        mobile,
+        username: tokenInfo.username || mobile,
+        userId: tokenInfo.userId || '',
+        expiresIn: tokenInfo.expires_in || 12 * 3600,
+        accessToken: tokenInfo.access_token || tokenInfo.token,
+    };
+}
+
+/**
+ * Register auth login subcommand
+ */
+export function loginCommand(program) {
+    program
+        .command('login')
+        .description('登录 SCM 系统')
+        .requiredOption('--openId <openId>', '飞书用户 openId')
+        .requiredOption('--mobile <mobile>', '手机号（11位）')
+        .requiredOption('--password <password>', '密码')
+        .action(async (opts) => {
+            try {
+                console.log('正在登录 SCM...');
+                const result = await doLogin(opts.openId, opts.mobile, opts.password);
+
+                console.log('\n✅ 登录成功！');
+                console.log('───────────────');
+                console.log(`用户:   ${result.username}`);
+                console.log(`User ID: ${result.userId}`);
+                console.log(`Open ID: ${result.openId}`);
+                console.log(`Token:  ${result.accessToken.substring(0, 30)}...`);
+                console.log(`有效期: ${Math.round(result.expiresIn / 60)} 分钟`);
+                console.log('───────────────');
+                console.log('Token 已缓存到 ~/.scm_cache/user_tokens.json');
+            } catch (err) {
+                console.error('\n❌ 登录失败:', err.message);
+                process.exit(1);
+            }
+        });
+}