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离线检查：

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 或完整构建）：

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：

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, 否则使用内网域名(更快, 更安全).

引入模块

// 订单操作类
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'