@dshtrading/connector-longbridge 0.6.2 → 0.7.0

package/README.md

@@ -85,15 +85,38 @@
 |---|---|---|
 | 实时报价 | `GET /v1/quote/realtime?symbol=00700.HK` | `src/rest.ts:184` |
 | K 线 | `GET /v1/quote/candlesticks?symbol=&period=&count=` | `src/rest.ts:221` |
-| 账户资产 | `GET /v1/asset/account` | `src/rest.ts:255` |
-| 持仓 | `GET /v1/trade/stock/position` | `src/rest.ts:289` |
-| 下单 | `POST /v1/trade/order`（`symbol` / `order_type`(MO\|LO) / `side`(Buy\|Sell) / `submitted_quantity` / `submitted_price` / `time_in_force: 'Day'` / `remark?`） | `src/rest.ts:317-329` |
-| 撤单 | `DELETE /v1/trade/order?order_id=` | `src/rest.ts:352-354` |
+| 账户资产 | `GET /v1/asset/account`（上游 `currency` / `total_cash` / `net_assets` → 契约的 `asset` / `free` / `locked`） | `src/rest.ts:255` |
+| 持仓 | **不发请求**：文档化端点 `GET /v1/asset/stock` 的应答缺 api 要求的 `side` / `timestamp`，见下节 | `src/rest.ts:291-304` |
+| 下单 | `POST /v1/trade/order`（`symbol` / `order_type`(MO\|LO) / `side`(Buy\|Sell) / `submitted_quantity` / `submitted_price` / `time_in_force: 'Day'` / `remark?`） | `src/rest.ts:317-327` |
+| 撤单 | `DELETE /v1/trade/order?order_id=` | `src/rest.ts:350-352` |
 
 请求头（`src/rest.ts:136-161`）：`Accept` / `Content-Type` 恒发；`authorization: Bearer <token>`
 在有 access token 时发；`x-api-key` + `x-timestamp`（`Date.now()`）在有 app key 时发；
 `x-api-signature` **只在 appKey、accessToken 与 appSecret 三者齐备**时发（第 148-160 行）。
 
+## 持仓（getPositions）：显式不可用，不返回任何行
+
+`getPositions()` 现在**不发上游请求**，直接抛 `TRADING_NOT_IMPLEMENTED`：api 契约要求的两样真数据在上游不存在，编不出来。
+
+- `@dshtrading/api` 的 `Position` 必填 `side: 'long' | 'short'` 与 `timestamp: number`
+  （`packages/api/src/index.ts:499-520`；`size` 的注释明写「正数；方向由 side 表达」）。
+- 长桥文档化的持仓端点是 `GET /v1/asset/stock`，应答 `data.list[].stock_info[]` 只有
+  `symbol` / `symbol_name` / `currency` / `quantity` / `market` / `available_quantity` /
+  `cost_price` / `init_quantity`（open.longbridge.com「Stock Positions」）。官方 Node SDK
+  `longport@4.3.7` 的 `StockPosition`（`index.d.ts:2377-2399`）字段集完全一致：**没有方向、也没有持仓时间**。
+  源码原先读的 `GET /v1/trade/stock/position` 与 `data.channels[].positions[].unrealized_pnl` 是
+  protobuf SDK 的消息形状，不是这套 HTTP 文档的形状（24 个 trade 文档页里没有该路径，`unrealized_pnl` 也不存在）。
+- `quantity` 是持股数，不是带符号仓位：`quantity > 0 ? 'long' : 'short'` 只要上游给的是绝对值，
+  就会把所有空头标成多头——那是把「数量空白 + 恒显示空头」换成一个更难发现的方向错误。
+  `timestamp` 同理没有来源，用 `Date.now()` 冒充持仓时间也是编数据。
+
+所以这里选「显式不可用」（与 connector-futu / connector-bybit / connector-ccxt 的持仓读数同裁决），
+而不是返回空数组：空数组的语义是「没有持仓」，和「读不到」是两句不同的话。
+
+解除条件（任一）：① api 侧把 `side` / `timestamp` 降为可选；② api 侧新增「持仓快照」类型
+（`size` + 可选 `side` / `timestamp`）；③ 上游给出方向与持仓时间，届时按 `size = |quantity|` 映射
+上游字段，仍不在本地推方向。
+
 ## 周期与契约
 
 - **周期词汇 8 个**：`1m/5m/15m/30m/1h/1d/1w/1M`（`src/rest.ts:24`），到上游的映射是

package/lib/index.d.ts

@@ -47,10 +47,14 @@ declare class LongbridgeTradeService extends Service implements TradeService {
   }, serviceName?: string);
   getBalance(): Promise<AccountBalance$1>;
   placeOrder(order: OrderRequest): Promise<Order$1>;
-  cancelOrder(orderId: string): Promise<{
-    orderId: string;
-    status: 'canceled';
-  }>;
+  cancelOrder(orderId: string, _symbol?: string): Promise<void>;
+  /**
+   * 单笔订单状态查询（api 契约必选方法，R3 okx 切片 2026-08-29 引入）。本连接器没有单笔
+   * 订单状态端点：必须显式拒绝，绝不编造订单回执——编造回执会被读成「订单存在/不存在」，
+   * 而契约语义是 TRADING_NOT_IMPLEMENTED（不可用）。与 connector-ccxt / connector-bybit /
+   * connector-tushare 的同名方法同形。
+   */
+  getOrder(_symbol: string, _id: string): Promise<Order$1>;
   getPositions(): Promise<Position$1[]>;
   getOrders(): Promise<Order$1[]>;
 }

package/lib/index.js

@@ -1,4 +1,4 @@
-import { INTERVAL_VOCABULARY, LongbridgeRestClient, TradingServiceError, assertSupportedInterval, generateLongbridgeSignature, parseIntervalMs, toLongbridgePeriod, toLongbridgeSymbol as toLongbridgeSymbol$1 } from "./rest.js";
+import { INTERVAL_VOCABULARY, LongbridgeRestClient, TradingServiceError, assertSupportedInterval, generateLongbridgeSignature, parseIntervalMs, toLongbridgePeriod, toLongbridgeSymbol } from "./rest.js";
 import { liveTradingEnabled } from "@dshtrading/authority";
 import { OrderIntentLedger, deriveVenueClientKey, orderFromReceipt, receiptFromOrder } from "@dshtrading/authority/order-intents";
 import { Service } from "@deepseek-ai/cordis";
@@ -111,10 +111,19 @@ var LongbridgeTradeService = class extends Service {
 		});
 		return placed;
 	}
-	async cancelOrder(orderId) {
+	async cancelOrder(orderId, _symbol) {
 		if (!liveTradingEnabled(this.config.liveTrading) || this.config.dryRun) throw new TradingServiceError("TRADING_LIVE_TRADING_DISABLED", "Longbridge TradeService.cancelOrder rejected at the service seam: cancel is a live action and requires a signed live-trading grant (see @dshtrading/authority) with dryRun=false.");
 		return this.client.cancelOrder(void 0, orderId);
 	}
+	/**
+	* 单笔订单状态查询（api 契约必选方法，R3 okx 切片 2026-08-29 引入）。本连接器没有单笔
+	* 订单状态端点：必须显式拒绝，绝不编造订单回执——编造回执会被读成「订单存在/不存在」，
+	* 而契约语义是 TRADING_NOT_IMPLEMENTED（不可用）。与 connector-ccxt / connector-bybit /
+	* connector-tushare 的同名方法同形。
+	*/
+	async getOrder(_symbol, _id) {
+		throw new TradingServiceError("TRADING_NOT_IMPLEMENTED", "Longbridge TradeService.getOrder is not implemented: this connector has no single-order status lookup. That means \"not available\", NOT \"order not found\".");
+	}
 	async getPositions() {
 		return this.client.getPositions();
 	}
@@ -338,4 +347,4 @@ function apply(ctx, config) {
 	});
 }
 //#endregion
-export { Config, INTERVAL_VOCABULARY, LONGBRIDGE_REMARK_RULE, LongbridgeMarketDataService, LongbridgeRestClient, LongbridgeTradeService, ROUTER_PROVIDER, TRADING_HK_MARKET_DATA_KEY, TRADING_HK_TRADE_KEY, TradingServiceError, apply, assertSupportedInterval, generateLongbridgeSignature, name, parseIntervalMs, resolveCredentials, routeAllows, toLongbridgePeriod, toLongbridgeSymbol$1 as toLongbridgeSymbol };
+export { Config, INTERVAL_VOCABULARY, LONGBRIDGE_REMARK_RULE, LongbridgeMarketDataService, LongbridgeRestClient, LongbridgeTradeService, ROUTER_PROVIDER, TRADING_HK_MARKET_DATA_KEY, TRADING_HK_TRADE_KEY, TradingServiceError, apply, assertSupportedInterval, generateLongbridgeSignature, name, parseIntervalMs, resolveCredentials, routeAllows, toLongbridgePeriod, toLongbridgeSymbol };

package/lib/rest.d.ts

@@ -42,6 +42,23 @@ declare class LongbridgeRestClient {
   getTicker(symbol: string): Promise<Ticker$1>;
   getKlines(symbol: string, interval?: Interval$1, limit?: number): Promise<Kline$1[]>;
   getBalance(): Promise<AccountBalance$1>;
+  /**
+   * 持仓快照。**当前显式拒绝，不产出任何行**——上游没有 api 契约要求的那两样真数据：
+   *
+   * - api 的 `Position` 必填 `side: 'long' | 'short'` 与 `timestamp: number`
+   *   （packages/api/src/index.ts:499-520，size 的注释明写「正数；方向由 side 表达」）。
+   * - 长桥文档化的持仓端点是 `GET /v1/asset/stock`，应答 `data.list[].stock_info[]`
+   *   只有 symbol / symbol_name / currency / quantity / market / available_quantity /
+   *   cost_price / init_quantity；官方 SDK 的 `StockPosition`（longport 4.3.7
+   *   index.d.ts:2377-2399）字段集完全一致，同样没有方向、也没有持仓时间。
+   * - `quantity` 是持股数，不是带符号的仓位：`quantity > 0 ? 'long' : 'short'` 这种填充
+   *   只要上游给的是绝对值，就把所有空头标成多头——那是把「数量空白 + 恒显示空头」换成一个
+   *   更难发现的方向错误。`timestamp` 同理没有来源，拿 Date.now() 冒充持仓时间也是编数据。
+   *
+   * 裁决与 connector-futu / connector-bybit / connector-ccxt 的持仓读数同款：不可用就
+   * TRADING_NOT_IMPLEMENTED，绝不返回空数组（空数组的语义是「没有持仓」，与「读不到」是两句
+   * 不同的话）。解除条件见 README「持仓（getPositions）」一节。
+   */
   getPositions(): Promise<Position$1[]>;
   placeOrder(_creds: unknown, req: OrderRequest, remark?: string): Promise<Order$1>;
   cancelOrder(_creds: unknown, orderId: string): Promise<{

package/lib/rest.js

@@ -164,28 +164,36 @@ var LongbridgeRestClient = class {
 	async getBalance() {
 		if (!this.appKey || !this.accessToken) throw new TradingServiceError("TRADING_AUTH_FAILED", "Longbridge: appKey and accessToken are required for getBalance");
 		const res = await this.requestJson("/v1/asset/account");
-		if (res.code !== 0 || !res.data?.list || res.data.list.length === 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Longbridge getBalance failed: ${res.message ?? `code ${res.code}`}`);
-		const first = res.data.list[0];
-		const available = parseFloat(first.total_cash || "0");
-		const total = parseFloat(first.net_assets || first.total_cash || "0");
+		const first = res.data?.list?.[0];
+		if (res.code !== 0 || first === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", "Longbridge getBalance failed: " + (res.message ?? "code " + res.code));
+		const cash = parseFloat(first.total_cash || "0");
+		const netAssets = parseFloat(first.net_assets || first.total_cash || "0");
 		return {
-			currency: first.currency ?? "HKD",
-			available,
-			total
+			asset: first.currency ?? "HKD",
+			free: cash,
+			locked: Math.max(netAssets - cash, 0)
 		};
 	}
+	/**
+	* 持仓快照。**当前显式拒绝，不产出任何行**——上游没有 api 契约要求的那两样真数据：
+	*
+	* - api 的 `Position` 必填 `side: 'long' | 'short'` 与 `timestamp: number`
+	*   （packages/api/src/index.ts:499-520，size 的注释明写「正数；方向由 side 表达」）。
+	* - 长桥文档化的持仓端点是 `GET /v1/asset/stock`，应答 `data.list[].stock_info[]`
+	*   只有 symbol / symbol_name / currency / quantity / market / available_quantity /
+	*   cost_price / init_quantity；官方 SDK 的 `StockPosition`（longport 4.3.7
+	*   index.d.ts:2377-2399）字段集完全一致，同样没有方向、也没有持仓时间。
+	* - `quantity` 是持股数，不是带符号的仓位：`quantity > 0 ? 'long' : 'short'` 这种填充
+	*   只要上游给的是绝对值，就把所有空头标成多头——那是把「数量空白 + 恒显示空头」换成一个
+	*   更难发现的方向错误。`timestamp` 同理没有来源，拿 Date.now() 冒充持仓时间也是编数据。
+	*
+	* 裁决与 connector-futu / connector-bybit / connector-ccxt 的持仓读数同款：不可用就
+	* TRADING_NOT_IMPLEMENTED，绝不返回空数组（空数组的语义是「没有持仓」，与「读不到」是两句
+	* 不同的话）。解除条件见 README「持仓（getPositions）」一节。
+	*/
 	async getPositions() {
 		if (!this.appKey || !this.accessToken) throw new TradingServiceError("TRADING_AUTH_FAILED", "Longbridge: appKey and accessToken are required for getPositions");
-		const res = await this.requestJson("/v1/trade/stock/position");
-		if (res.code !== 0 || !Array.isArray(res.data?.channels)) return [];
-		const positions = [];
-		for (const channel of res.data.channels) if (Array.isArray(channel.positions)) for (const p of channel.positions) positions.push({
-			symbol: toLongbridgeSymbol(p.symbol).canonical,
-			quantity: parseFloat(p.quantity || "0"),
-			entryPrice: parseFloat(p.cost_price || "0"),
-			unrealizedPnl: parseFloat(p.unrealized_pnl || "0")
-		});
-		return positions;
+		throw new TradingServiceError("TRADING_NOT_IMPLEMENTED", "Longbridge TradeService.getPositions is not available: @dshtrading/api Position requires side (long|short) and timestamp, and the Longbridge stock-position snapshot provides neither. The documented endpoint GET /v1/asset/stock answers data.list[].stock_info[] with only symbol, symbol_name, currency, quantity, market, available_quantity, cost_price and init_quantity (the official SDK StockPosition carries the same field set). quantity is a holding count rather than a signed size, so direction cannot be derived, and there is no open time to report. That means \"not available\", NOT \"no positions\".");
 	}
 	async placeOrder(_creds, req, remark) {
 		if (!this.appKey || !this.accessToken) throw new TradingServiceError("TRADING_AUTH_FAILED", "Longbridge: appKey and accessToken are required for placeOrder");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dshtrading/connector-longbridge",
   "description": "长桥（Longbridge）港股连接器：直连券商 OpenAPI（openapi.longportapp.com，HMAC-SHA256 签名 + BYOK 三凭证 ref），实现 MarketDataService/TradeService 与 5 个 hk_* 工具；dry-run 缺省、liveTrading 只是非权威镜像（放行归 @dshtrading/authority 人工签署）、凭证只进 ref。",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -21,13 +21,13 @@
   ],
   "license": "PolyForm-Noncommercial-1.0.0",
   "dependencies": {
-    "@dshtrading/authority": "^0.6.2",
-    "@dshtrading/api": "^0.6.2"
+    "@dshtrading/api": "^0.7.0",
+    "@dshtrading/authority": "^0.7.0"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": ">=4.0.0",
-    "@deepseek-ai/dsh-tools": ">=0.2.1-rc.2",
-    "@deepseek-ai/schemastery": ">=3.18.0"
+    "@deepseek-ai/cordis": ">=4.1.0",
+    "@deepseek-ai/dsh-tools": ">=0.2.2-rc.1",
+    "@deepseek-ai/schemastery": ">=3.19.0"
   },
   "devDependencies": {
     "tsdown": "^0.22.0",