# @be-link/pos-cli-nodejs 中文文档

规范地址：https://npmcn.com/package/%40be-link/pos-cli-nodejs/

版本：1\.0\.248
npm 元数据更新时间：2026-11-05T04:08:22.763Z
中文译文更新时间：2026-11-07T23:24:40.890Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40be-link/pos-cli-nodejs
原文对照：https://npmcn.com/package/%40be-link/pos-cli-nodejs/?lang=original
项目主页：https://github.com/snowmountain-top/pos-cli-nodejs#readme
源码仓库：https://github.com/snowmountain-top/pos-cli-nodejs

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：338 kB，90 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2023-10-27T16:44:25.986Z
- 最新版本发布：2026-11-05T04:08:22.562Z
- 近 30 天下载量：2052（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：414（近 12 个月 102 个）

## 中文简介

正向订单服务Nodejs客户端

## 安装

```sh
npm install @be-link/pos-cli-nodejs
```

也可以使用：`pnpm add @be-link/pos-cli-nodejs`、`yarn add @be-link/pos-cli-nodejs`、`bun add @be-link/pos-cli-nodejs`

## README

# pos-cli-nodejs

正向订单服务Nodejs客户端

## 旅顾归属事实查询（开发中）

`AdvisorQueryService` 提供四个固定 DTO 查询方法： `queryAdvisorShareOrderList`、`getAdvisorShareOrderFacts`、 `getAdvisorShareOrderFactsBatch`、`getAdvisorShareAdjustmentCreateFacts`。 返回值不包装完整订单 Proxy；金额 `remainingFeeCent` 是小管家的“合计” （原单 remainFee），quantity 是剩余份数，不是差价数量或实付累计。

这组方法只向 transport 提供四条准确协议路径。保留 `new AdvisorQueryService(transport)`， 使用 `createAdvisorTokenTransport({origin, send})` 装配，send 通常由 `createAdvisorHttpsSender({origin, timeoutMs, maxResponseBytes})` 创建。 origin 必须显式配置为 HTTPS；本轮不修改旧 BaseService 的环境/目标选择。 transport 只允许准确协议相对路径及同 origin 的准确绝对 URL，不接受 query/hash、路径归一化或跨 origin。

每次请求动态读取 `process.env.authorizationTokenInside`（Shield Token），不缓存，缺失/空值时在 HTTP 前拒绝。 仅发送既有 SDK 鉴权 headers：`x-belink-accessType: authorizationTokenInside` 和 `x-belink-authorization: <当前 token>`。不使用旅顾独立签名、私钥或 actor 票据。 `canonicalAdvisorJson` 仍用于严格 JSON 快照；原签名/验签 API 已移除。 调用方身份与旅顾资格由服务端 Shield 和业务授权校验；SDK 不提供认证或资格证明。 业务 body 不接受 caller、actor、买家身份等额外字段。

HTTPS sender 保留显式 timeoutMs、maxResponseBytes，验证证书，不使用环境代理， 不跟随重定向、不重试，不允许额外自报鉴权 headers；响应容量仅为技术容量。 已知契约业务错误码保真，未知异常统一脱敏，不复制凭据或底层 HTTP 配置。 离线检查使用 mock HTTPS，未验证真实网络、代理、证书或服务端联调；未安装或发布新 SDK。

专用sender离线检查：

```bash
out=$(mktemp -d /tmp/pos-sdk-sender.XXXXXX)
tsc src/pos/modules/orderQuery/advisorHttpSender.ts --rootDir src --strict --target ES2020 --module commonjs \
  --typeRoots /opt/homebrew/lib/node_modules/ts-node/node_modules/@types --types node --outDir "$out"
node src/pos/modules/orderQuery/advisorHttpSender.offline.cjs "$out"
```

transport 返回 POS 原生 `{data,message,success?,requestId?}`，本层只解包一次； 不接收 DS 的 code/SUCCESS envelope。方法本身不重试，依赖错误原样传播。 集成方 transport 的重试和错误脱敏仍须单独验证。

无项目依赖时可复现离线检查（不等于 Jest 或完整构建）：

```bash
out=$(mktemp -d /tmp/pos-sdk-advisor.XXXXXX)
tsc src/pos/modules/orderQuery/advisor.ts --strict --target ES2020 --module commonjs \
  --typeRoots /opt/homebrew/lib/node_modules/ts-node/node_modules/@types \
  --types node --outDir "$out"
node src/pos/modules/orderQuery/advisor.offline.cjs "$out"
```

上述 typeRoots 是本机已有 Node 类型声明的位置；其他机器应使用其已安装的声明路径。

## 旅顾订单内部备注（开发中，未发布）

DS 使用隔离实例，不向旧全局单例写入 transport：

```typescript
import {
  createAdvisorOrderNoteService, createAdvisorTokenTransport, createAdvisorHttpsSender,
} from '@be-link/pos-cli-nodejs'

const origin = 'https://your-reviewed-pos-origin.example'
const notes = createAdvisorOrderNoteService(createAdvisorTokenTransport({
  origin,
  send: createAdvisorHttpsSender({ origin, timeoutMs: 15000, maxResponseBytes: 1024 * 1024 }),
}))
// actor 必须来自服务端有效登录旅顾记录，绝不能透传客户端作者字段。
const actor = { advisorId: 'trusted-advisor-id', name: '可信姓名' }
await notes.queryAdvisorNotes({ actor, orderId: 'order-id' }) // {orderId,list}
await notes.createAdvisorNote({ actor, orderId: 'order-id', content: '正文' }) // {orderId,noteId}
```

两条固定 POST 路径为 `/note/advisor/query`、`/note/advisor/create`，不使用旧 callApi， 不接受 type、images、status、operatorId 或其他作者字段。原文最多 1000 Unicode 码点， 组合字符按多个码点；拒绝孤立 surrogate，trim 后必须非空，但 SDK 不改写原文，POS trim 落库。 SDK 不是身份或资格证明；订单授权与真实身份仍由 DS/POS 校验。

新入口必须返回 `{success:true,message,data}`；缺失 success、DS code 包壳或错误订单ID均拒绝。 列表逐字段投影，历史 operatorUser/content/type/status/createdAt 的 NULL 原值保留， 未知角色保留，不输出 operatorId、images 或修改人字段，也不生成 capabilities。 默认 `orderNoteService` 未注入 transport，调用新方法 fail closed；旧方法和 callApi 重试策略不变。

内置 sender 与 transport 无自动重试，无回退、重放队列、幂等或去重；宿主自定义 transport 也必须遵守。 根导出 `AdvisorBusinessError` 仅保留已知 POS 4xx 语义码，不复制服务端消息/配置。 POS `DEPENDENCY_UNAVAILABLE` 表示执行前拒绝，`RESULT_UNKNOWN` 表示写结果未知。 本地 `AdvisorNoteError` 提供 code 和 outcome：参数/缺 transport 为 `not_sent`， 交给 transport 后创建异常或坏响应保守为 `unknown`（缺 token 也可能保守归入此类）， 读依赖失败为 `not_applicable`。调用方按错误类/属性分类，不按自由 message 判断，不重放创建。

源码 meta 已增加 ADVISOR，但本仓仍固定已安装的 vitality-meta 1.0.240；未授权发布或升级依赖， 所以当前 SDK `PosConstants` **尚不包含新角色**。本地合同/构建通过不能代替正式包可安装、 角色导出或 POS/DS 联调通过。须先发布真实 meta 版本，再按授权升级/发布 SDK；不能用本地补丁冒充发包。 超时和响应容量须真实长历史验收，示例容量不是业务 SLA。

## 安装

```
npm install @be-link/pos-cli-nodejs
```

## 使用

### 配置环境变量

```
CONTAINER_ENV = SFC(云函数) || CLOUD_RUN(云托管)
```

SDK依赖`CONTAINER_ENV`来识别当前运行环境，默认为`SFC`, 请根据使用SDK的环境来配置该变量。

当`CONTAINER_ENV`为`SFC`时，SDK会从公网访问POS, 否则使用内网域名(更快, 更安全).

### 引入模块

```typescript
// 订单操作类
import { orderCoreService } from '@be-link/pos-cli-nodejs'
// 订单履约类
import { orderFulfillService } from '@be-link/pos-cli-nodejs'
// 商品维度查询订单
import { queryByCommodityService } from '@be-link/pos-cli-nodejs'
// 用户维度查询订单
import { queryByUserService } from '@be-link/pos-cli-nodejs'
// 门店维度查询订单
import { queryByStoreService } from '@be-link/pos-cli-nodejs'
// web端后台查询订单
import { queryByWebService } from '@be-link/pos-cli-nodejs'
// 订单备注类
import { orderNoteService } from '@be-link/pos-cli-nodejs'
// 枚举类
import { PosConstants } from '@be-link/pos-cli-nodejs'
```

## 常见问题

### @be-link/pos-cli-nodejs 是什么？

正向订单服务Nodejs客户端

### 如何安装 @be-link/pos-cli-nodejs？

在项目目录运行 npm install @be-link/pos-cli-nodejs，或使用 pnpm add / yarn add / bun add。

### @be-link/pos-cli-nodejs 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @be-link/pos-cli-nodejs 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @be-link/pos-cli-nodejs 可以商用吗？

@be-link/pos-cli-nodejs 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @be-link/pos-cli-nodejs 的下载量有多少？

根据 npm 官方下载统计，@be-link/pos-cli-nodejs 在 2026/10/08 – 2026/11/06 这 30 天内被下载 2,052 次，日均约 68 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @be-link/pos-cli-nodejs 还在维护吗？

最新版本 1\.0\.248 发布于 2026/11/05（3 天前）；至今共发布 414 个版本，其中过去 12 个月发布了 102 个；首次发布于 2023/10/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。