@pisell/pisellos 2.2.124 → 2.2.126

package/dist/solution/Sales/index.d.ts

@@ -86,12 +86,41 @@ export declare class SalesImpl extends BaseModule implements Module, SalesModule
      */
     private pickBookingsForCurrentPoint;
     /**
-     * 标准化单条 booking：
-     * - 过滤终态（rejected/cancelled/completed）
-     * - 当 deviceTime 早于 currentTime 时，过滤 end_time 早于 currentTime 的历史数据
-     * - 注入 status / isTimeout / reserved_status
+     * 计算 booking 在 current 时刻的执行进度百分比（0-100）。
+     * - startAt/endAt 非法或 totalMinutes <= 0 返回 0
+     * - current 早于 startAt 返回 0，晚于 endAt 返回 100
+     */
+    private calcProgressPercent;
+    /**
+     * 标准化单条 booking 的分发入口：
+     * - 统一过滤 rejected / cancelled（视为没来过）
+     * - current === deviceCurrent 走实时分支（信任 appointment_status）
+     * - 否则走快照分支（纯时间窗判定，忽略 appointment_status 的 arrived/started/completed 差异）
      */
     private normalizeMatchedBooking;
+    /**
+     * 实时模式（current === deviceCurrent）：信任 appointment_status
+     * - 过滤 new / completed（实时视角下视为非活跃数据）
+     * - status 由 getBookingStatus 映射
+     * - occupied 且 current > endAt 标记 isTimeout + timeoutTime
+     * - reserved 且 current < startAt 标记 not_arrived，否则标记 late
+     */
+    private buildRealtimeBooking;
+    /**
+     * 快照模式（current !== deviceCurrent，过去或未来）：忽略 appointment_status
+     * 的实时态差异，仅按 booking 时间窗判定，为 current 提供时间点快照视图。
+     *
+     * - new：视作尚未成为真实预约，过滤
+     * - locked：保留 status=locked，不计算 timeout/late/progress
+     * - 其他非终态：
+     *   - startAt/endAt 非法 → 过滤
+     *   - current > endAt → 过滤（已结束，不入池）
+     *   - current ∈ [startAt, endAt] → occupied，附带 progressPercent
+     *   - current < startAt → reserved + not_arrived，附带 remainingReserveTime
+     *
+     * 快照模式下 isTimeout 恒为 false，lateTime / timeoutTime 始终置空。
+     */
+    private buildSnapshotBooking;
     getResourceBookingList(currentTime: string, bookingList?: BookingData[], deviceTime?: string): Promise<SalesResourceBookingItem[]>;
 }
 export { SalesImpl as Sales };

package/dist/solution/Sales/index.js

@@ -429,36 +429,57 @@ export var SalesImpl = /*#__PURE__*/function (_BaseModule) {
     }
 
     /**
-     * 标准化单条 booking：
-     * - 过滤终态（rejected/cancelled/completed）
-     * - 当 deviceTime 早于 currentTime 时，过滤 end_time 早于 currentTime 的历史数据
-     * - 注入 status / isTimeout / reserved_status
+     * 计算 booking 在 current 时刻的执行进度百分比（0-100）。
+     * - startAt/endAt 非法或 totalMinutes <= 0 返回 0
+     * - current 早于 startAt 返回 0，晚于 endAt 返回 100
+     */
+  }, {
+    key: "calcProgressPercent",
+    value: function calcProgressPercent(current, startAt, endAt) {
+      if (!startAt.isValid() || !endAt.isValid()) return 0;
+      var totalMinutes = endAt.diff(startAt, 'minute');
+      if (totalMinutes <= 0) return 0;
+      var elapsedMinutes = current.diff(startAt, 'minute');
+      if (elapsedMinutes <= 0) return 0;
+      if (elapsedMinutes >= totalMinutes) return 100;
+      return Math.floor(elapsedMinutes / totalMinutes * 100);
+    }
+
+    /**
+     * 标准化单条 booking 的分发入口：
+     * - 统一过滤 rejected / cancelled（视为没来过）
+     * - current === deviceCurrent 走实时分支（信任 appointment_status）
+     * - 否则走快照分支（纯时间窗判定，忽略 appointment_status 的 arrived/started/completed 差异）
      */
   }, {
     key: "normalizeMatchedBooking",
     value: function normalizeMatchedBooking(current, deviceCurrent, booking) {
       var _ref3, _booking$appointment_;
       var appointmentStatus = String((_ref3 = (_booking$appointment_ = booking.appointment_status) !== null && _booking$appointment_ !== void 0 ? _booking$appointment_ : booking.status) !== null && _ref3 !== void 0 ? _ref3 : '');
-      if (appointmentStatus === 'new' || appointmentStatus === 'rejected' || appointmentStatus === 'cancelled' || appointmentStatus === 'completed') {
-        return null;
-      }
+      if (appointmentStatus === 'rejected' || appointmentStatus === 'cancelled') return null;
+      var startAt = this.toBookingDateTime(booking.start_date, booking.start_time);
       var endAt = this.toBookingDateTime(booking.end_date, booking.end_time);
-      var shouldFilterHistoryByCurrent = deviceCurrent.isBefore(current);
-      if (shouldFilterHistoryByCurrent && endAt.isValid() && endAt.isBefore(current)) return null;
+      if (current.isSame(deviceCurrent)) {
+        return this.buildRealtimeBooking(current, booking, appointmentStatus, startAt, endAt);
+      }
+      return this.buildSnapshotBooking(current, booking, appointmentStatus, startAt, endAt);
+    }
+
+    /**
+     * 实时模式（current === deviceCurrent）：信任 appointment_status
+     * - 过滤 new / completed（实时视角下视为非活跃数据）
+     * - status 由 getBookingStatus 映射
+     * - occupied 且 current > endAt 标记 isTimeout + timeoutTime
+     * - reserved 且 current < startAt 标记 not_arrived，否则标记 late
+     */
+  }, {
+    key: "buildRealtimeBooking",
+    value: function buildRealtimeBooking(current, booking, appointmentStatus, startAt, endAt) {
+      if (appointmentStatus === 'new' || appointmentStatus === 'completed') return null;
       var bookingStatus = this.getBookingStatus(appointmentStatus);
-      var startAt = this.toBookingDateTime(booking.start_date, booking.start_time);
       var isTimeout = bookingStatus === 'occupied' && endAt.isValid() && current.isAfter(endAt);
       var timeoutTime = isTimeout ? current.diff(endAt, 'minute') : undefined;
-      var progressPercent = function () {
-        if (bookingStatus !== 'occupied') return 0;
-        if (!startAt.isValid() || !endAt.isValid()) return 0;
-        var totalMinutes = endAt.diff(startAt, 'minute');
-        if (totalMinutes <= 0) return 0;
-        var elapsedMinutes = current.diff(startAt, 'minute');
-        if (elapsedMinutes <= 0) return 0;
-        if (elapsedMinutes >= totalMinutes) return 100;
-        return Math.floor(elapsedMinutes / totalMinutes * 100);
-      }();
+      var progressPercent = bookingStatus === 'occupied' ? this.calcProgressPercent(current, startAt, endAt) : 0;
       var reservedStatus;
       var lateTime;
       var remainingReserveTime;
@@ -471,24 +492,6 @@ export var SalesImpl = /*#__PURE__*/function (_BaseModule) {
           lateTime = Math.max(current.diff(startAt, 'minute'), 0);
         }
       }
-      // 未来查询投影：查询时间晚于设备时间时，预留+迟到且 end_time 仍在查询时间之后的预约强制视为占用
-      if (current.isAfter(deviceCurrent) && bookingStatus === 'reserved' && reservedStatus === 'late' && endAt.isValid() && endAt.isSameOrAfter(current)) {
-        bookingStatus = 'occupied';
-        reservedStatus = undefined;
-        lateTime = undefined;
-        remainingReserveTime = undefined;
-        isTimeout = false;
-        timeoutTime = undefined;
-        progressPercent = function () {
-          if (!startAt.isValid() || !endAt.isValid()) return 0;
-          var totalMinutes = endAt.diff(startAt, 'minute');
-          if (totalMinutes <= 0) return 0;
-          var elapsedMinutes = current.diff(startAt, 'minute');
-          if (elapsedMinutes <= 0) return 0;
-          if (elapsedMinutes >= totalMinutes) return 100;
-          return Math.floor(elapsedMinutes / totalMinutes * 100);
-        }();
-      }
       return _objectSpread(_objectSpread({}, booking), {}, {
         status: bookingStatus,
         isTimeout: isTimeout,
@@ -499,6 +502,59 @@ export var SalesImpl = /*#__PURE__*/function (_BaseModule) {
         remainingReserveTime: remainingReserveTime
       });
     }
+
+    /**
+     * 快照模式（current !== deviceCurrent，过去或未来）：忽略 appointment_status
+     * 的实时态差异，仅按 booking 时间窗判定，为 current 提供时间点快照视图。
+     *
+     * - new：视作尚未成为真实预约，过滤
+     * - locked：保留 status=locked，不计算 timeout/late/progress
+     * - 其他非终态：
+     *   - startAt/endAt 非法 → 过滤
+     *   - current > endAt → 过滤（已结束，不入池）
+     *   - current ∈ [startAt, endAt] → occupied，附带 progressPercent
+     *   - current < startAt → reserved + not_arrived，附带 remainingReserveTime
+     *
+     * 快照模式下 isTimeout 恒为 false，lateTime / timeoutTime 始终置空。
+     */
+  }, {
+    key: "buildSnapshotBooking",
+    value: function buildSnapshotBooking(current, booking, appointmentStatus, startAt, endAt) {
+      if (appointmentStatus === 'new') return null;
+      if (appointmentStatus === 'locked') {
+        return _objectSpread(_objectSpread({}, booking), {}, {
+          status: 'locked',
+          isTimeout: false,
+          timeoutTime: undefined,
+          progressPercent: 0,
+          lateTime: undefined,
+          reserved_status: undefined,
+          remainingReserveTime: undefined
+        });
+      }
+      if (!startAt.isValid() || !endAt.isValid()) return null;
+      if (current.isAfter(endAt)) return null;
+      if (this.isSameOrAfter(current, startAt) && this.isSameOrBefore(current, endAt)) {
+        return _objectSpread(_objectSpread({}, booking), {}, {
+          status: 'occupied',
+          isTimeout: false,
+          timeoutTime: undefined,
+          progressPercent: this.calcProgressPercent(current, startAt, endAt),
+          lateTime: undefined,
+          reserved_status: undefined,
+          remainingReserveTime: undefined
+        });
+      }
+      return _objectSpread(_objectSpread({}, booking), {}, {
+        status: 'reserved',
+        isTimeout: false,
+        timeoutTime: undefined,
+        progressPercent: 0,
+        lateTime: undefined,
+        reserved_status: 'not_arrived',
+        remainingReserveTime: Math.max(startAt.diff(current, 'minute'), 0)
+      });
+    }
   }, {
     key: "getResourceBookingList",
     value: function () {

package/lib/core/index.js

@@ -50,6 +50,7 @@ var PisellOSCore = class {
       this.serverOptions = options.server;
     }
     this.initialize(options);
+    console.log("initialize12341");
   }
   initialize(options) {
     if (options == null ? void 0 : options.plugins) {

package/lib/modules/Quotation/index.d.ts

@@ -0,0 +1,48 @@
+import { Module, PisellCore, ModuleOptions } from '../../types';
+import { BaseModule } from '../BaseModule';
+import type { ScheduleItem } from '../Schedule/types';
+import type { QuotationItem } from './types';
+export type { QuotationItem, QuotationProductData, QuotationSchedule, QuotationState } from './types';
+export declare class QuotationModule extends BaseModule implements Module {
+    protected defaultName: string;
+    protected defaultVersion: string;
+    private request;
+    private store;
+    private scheduleResolver?;
+    constructor(name?: string, version?: string);
+    initialize(core: PisellCore, options: ModuleOptions): Promise<void>;
+    loadQuotations(params?: {
+        channel?: string;
+    }): Promise<void>;
+    getQuotationList(): QuotationItem[];
+    /**
+     * Look up the quotation price for a specific product (+ optional variant) at a given datetime.
+     * Returns the price as a string (e.g. "300.00"), or null if no quotation applies.
+     *
+     * Priority: iterates quotations already sorted by `sort` ascending (lowest = highest priority).
+     * First matching quotation whose schedule covers `datetime` and whose product_data contains
+     * the requested productId wins.
+     */
+    getPriceForProduct(params: {
+        productId: number;
+        variantId?: number;
+        datetime: string;
+    }): string | null;
+    getQuotationShelfId(params: {
+        productId: number;
+        variantId?: number;
+        datetime: string;
+    }): number;
+    /**
+     * Batch pre-compute quotation prices for a set of products across multiple time points.
+     * Key format: `${productId}:${timePoint}`
+     * This avoids repeated schedule matching when the same product appears in multiple resource rows.
+     */
+    buildProductPriceMap(params: {
+        productIds: number[];
+        timePoints: string[];
+    }): Map<string, string | null>;
+    setScheduleResolver(resolver: (id: number) => ScheduleItem | undefined): void;
+    private isQuotationActiveAt;
+    private findProductData;
+}

package/lib/modules/Quotation/index.js

@@ -0,0 +1,152 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/modules/Quotation/index.ts
+var Quotation_exports = {};
+__export(Quotation_exports, {
+  QuotationModule: () => QuotationModule
+});
+module.exports = __toCommonJS(Quotation_exports);
+var import_BaseModule = require("../BaseModule");
+var import_getDateIsInSchedule = require("../Schedule/getDateIsInSchedule");
+var QuotationModule = class extends import_BaseModule.BaseModule {
+  constructor(name, version) {
+    super(name, version);
+    this.defaultName = "quotation";
+    this.defaultVersion = "1.0.0";
+    this.store = { list: [] };
+  }
+  async initialize(core, options) {
+    this.core = core;
+    this.request = core.getPlugin("request");
+    if (!this.request)
+      throw new Error("QuotationModule 需要 request 插件支持");
+    this.store = { list: [] };
+  }
+  async loadQuotations(params) {
+    var _a;
+    const query = {};
+    if (params == null ? void 0 : params.channel)
+      query.channel = params.channel;
+    if ((params == null ? void 0 : params.channel) === "online_store") {
+      query.channel = "online-store";
+    }
+    const res = await this.request.get(
+      "/quotation/available",
+      query,
+      { useCache: false }
+    );
+    const list = ((_a = res == null ? void 0 : res.data) == null ? void 0 : _a.list) || (res == null ? void 0 : res.list) || [];
+    list.sort((a, b) => a.sort - b.sort);
+    this.store.list = list;
+  }
+  getQuotationList() {
+    return this.store.list;
+  }
+  /**
+   * Look up the quotation price for a specific product (+ optional variant) at a given datetime.
+   * Returns the price as a string (e.g. "300.00"), or null if no quotation applies.
+   *
+   * Priority: iterates quotations already sorted by `sort` ascending (lowest = highest priority).
+   * First matching quotation whose schedule covers `datetime` and whose product_data contains
+   * the requested productId wins.
+   */
+  getPriceForProduct(params) {
+    const { productId, variantId, datetime } = params;
+    for (const quotation of this.store.list) {
+      if (!this.isQuotationActiveAt(quotation, datetime))
+        continue;
+      const match = this.findProductData(quotation.product_data, productId, variantId);
+      if (!match)
+        continue;
+      if (match.value === 0)
+        continue;
+      return String(match.value);
+    }
+    return null;
+  }
+  getQuotationShelfId(params) {
+    const { productId, variantId, datetime } = params;
+    for (const quotation of this.store.list) {
+      if (!this.isQuotationActiveAt(quotation, datetime))
+        continue;
+      const match = this.findProductData(quotation.product_data, productId, variantId);
+      if (!match || match.value === 0)
+        continue;
+      return quotation.id;
+    }
+    return 0;
+  }
+  /**
+   * Batch pre-compute quotation prices for a set of products across multiple time points.
+   * Key format: `${productId}:${timePoint}`
+   * This avoids repeated schedule matching when the same product appears in multiple resource rows.
+   */
+  buildProductPriceMap(params) {
+    const map = /* @__PURE__ */ new Map();
+    if (!this.store.list.length)
+      return map;
+    for (const productId of params.productIds) {
+      for (const timePoint of params.timePoints) {
+        const key = `${productId}:${timePoint}`;
+        const price = this.getPriceForProduct({ productId, datetime: timePoint });
+        if (price !== null) {
+          map.set(key, price);
+        }
+      }
+    }
+    return map;
+  }
+  setScheduleResolver(resolver) {
+    this.scheduleResolver = resolver;
+  }
+  isQuotationActiveAt(quotation, datetime) {
+    var _a;
+    if (!((_a = quotation.schedule) == null ? void 0 : _a.length))
+      return false;
+    const scheduleItems = quotation.schedule.map((s) => {
+      var _a2;
+      const full = (_a2 = this.scheduleResolver) == null ? void 0 : _a2.call(this, s.id);
+      if (full)
+        return full;
+      return {
+        ...s,
+        repeat_type: s.repeat_type || "none",
+        repeat_rule: s.repeat_rule || null,
+        time_slot: s.time_slot || []
+      };
+    });
+    return (0, import_getDateIsInSchedule.getDateIsInSchedule)(datetime, scheduleItems);
+  }
+  findProductData(productData, productId, variantId) {
+    if (variantId && variantId !== 0) {
+      const variantMatch = productData.find(
+        (p) => p.product_id === productId && p.variant_id === variantId
+      );
+      if (variantMatch)
+        return variantMatch;
+    }
+    return productData.find(
+      (p) => p.product_id === productId && p.variant_id === 0
+    );
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  QuotationModule
+});

package/lib/modules/Quotation/types.d.ts

@@ -0,0 +1,42 @@
+export interface QuotationProductData {
+    id: number;
+    shelf_id: number;
+    product_id: number;
+    variant_id: number;
+    type: string;
+    value: number;
+}
+export interface QuotationSchedule {
+    id: number;
+    name: string;
+    type: 'standard' | 'time-slots' | 'designation';
+    start_time: string;
+    end_time: string;
+    is_all: number;
+    repeat_type?: string;
+    repeat_rule?: any;
+    designation?: any;
+    time_slot?: Array<{
+        start_time: string;
+        end_time: string;
+    }>;
+    pivot?: Record<string, any>;
+}
+export interface QuotationItem {
+    id: number;
+    shop_id: number;
+    shelf_type_id?: number;
+    name: string;
+    description?: string;
+    status: string;
+    sort: number;
+    channel: string[];
+    created_at?: string;
+    updated_at?: string;
+    deleted_at?: string | null;
+    schedule: QuotationSchedule[];
+    product_data: QuotationProductData[];
+}
+export interface QuotationState {
+    list: QuotationItem[];
+}

package/lib/modules/Quotation/types.js

@@ -0,0 +1,17 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/modules/Quotation/types.ts
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/lib/server/index.d.ts

@@ -254,6 +254,17 @@ declare class Server {
      * 转发到资源模块去
      */
     private handleResourceList;
+    /**
+     * 代理刷新单个本地订单：
+     * - 入参：order_id（data 或 url query）
+     * - 流程：本地存在性校验 → 调后端 /order/sales/{id}?with[]=... → 覆盖本地 → 落 SQLite → emit onOrdersChanged
+     * - 监听级联：onOrdersChanged 触发订单/预约/bookingRemoteCache 三路订阅者推送
+     */
+    private handleUpdateLocalOrder;
+    /**
+     * 从 url 中解析指定 query 参数，兼容相对路径与绝对路径
+     */
+    private extractQueryParam;
     /**
      * 从 url 或路由 path 解析 pathname（不含 query，去掉末尾 /）
      */

package/lib/server/index.js

@@ -313,6 +313,86 @@ var Server = class {
         status: true
       };
     };
+    /**
+     * 代理刷新单个本地订单：
+     * - 入参：order_id（data 或 url query）
+     * - 流程：本地存在性校验 → 调后端 /order/sales/{id}?with[]=... → 覆盖本地 → 落 SQLite → emit onOrdersChanged
+     * - 监听级联：onOrdersChanged 触发订单/预约/bookingRemoteCache 三路订阅者推送
+     */
+    this.handleUpdateLocalOrder = async ({ url, data }) => {
+      var _a;
+      const rawOrderId = (data && typeof data === "object" ? data.order_id : void 0) ?? this.extractQueryParam(url, "order_id");
+      const orderId = rawOrderId === void 0 || rawOrderId === null || rawOrderId === "" ? null : String(rawOrderId).trim();
+      this.logInfo("handleUpdateLocalOrder: 开始处理", { url, orderId });
+      if (!orderId) {
+        this.logWarning("handleUpdateLocalOrder: order_id 缺失", { url, data });
+        return { code: 400, status: false, message: "order_id 缺失", data: null };
+      }
+      if (!this.order) {
+        this.logError("handleUpdateLocalOrder: Order 模块未注册");
+        return { code: 500, status: false, message: "Order 模块未注册", data: null };
+      }
+      if (!this.order.getOrderByOrderId(orderId)) {
+        this.logInfo("handleUpdateLocalOrder: 本地不存在该订单，忽略", { orderId });
+        return {
+          code: 200,
+          status: true,
+          message: "本地无此订单，已忽略",
+          data: { overwritten: false }
+        };
+      }
+      if (!((_a = this.app) == null ? void 0 : _a.request)) {
+        this.logError("handleUpdateLocalOrder: app.request 不可用");
+        return { code: 500, status: false, message: "app.request 不可用", data: null };
+      }
+      const backendPath = `/shop/order/sales/${encodeURIComponent(
+        orderId
+      )}?with%5B%5D=products&with%5B%5D=scheduleEvents&with%5B%5D=customer`;
+      try {
+        const response = await this.app.request.get(backendPath, void 0, {
+          isShopApi: true
+        });
+        const fresh = (response == null ? void 0 : response.data) ?? response;
+        if (!fresh || typeof fresh !== "object" || fresh.order_id == null) {
+          this.logError("handleUpdateLocalOrder: 后端返回订单为空", {
+            orderId,
+            backendPath
+          });
+          return {
+            code: 500,
+            status: false,
+            message: "后端返回订单为空",
+            data: null
+          };
+        }
+        const { overwritten } = await this.order.overwriteExistingOrder(
+          fresh
+        );
+        this.logInfo("handleUpdateLocalOrder: 覆盖完成", {
+          orderId,
+          overwritten
+        });
+        return {
+          code: 200,
+          status: true,
+          message: "",
+          data: { overwritten, order_id: orderId }
+        };
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        this.logError("handleUpdateLocalOrder: 请求失败", {
+          orderId,
+          backendPath,
+          error: errorMessage
+        });
+        return {
+          code: 500,
+          status: false,
+          message: errorMessage,
+          data: null
+        };
+      }
+    };
     /**
      * GET /shop/schedule/floor-plan* 前缀路由：读本地 store；支持 subscriberId + callback 订阅更新
      */
@@ -958,6 +1038,11 @@ var Server = class {
         method: "get",
         path: "/shop/form/resource/page",
         handler: this.handleResourceList.bind(this)
+      },
+      {
+        method: "get",
+        path: "/update/localOrder",
+        handler: this.handleUpdateLocalOrder.bind(this)
       }
     ]);
     this.registerPrefixRoutes([
@@ -1420,6 +1505,37 @@ var Server = class {
       };
     }
   }
+  /**
+   * 从 url 中解析指定 query 参数，兼容相对路径与绝对路径
+   */
+  extractQueryParam(url, key) {
+    if (!url)
+      return null;
+    try {
+      const target = url.startsWith("http") ? new URL(url) : new URL(url, "http://placeholder.local");
+      const value = target.searchParams.get(key);
+      return value ?? null;
+    } catch {
+      const queryIndex = url.indexOf("?");
+      if (queryIndex < 0)
+        return null;
+      const query = url.slice(queryIndex + 1);
+      for (const pair of query.split("&")) {
+        if (!pair)
+          continue;
+        const [rawKey, rawValue = ""] = pair.split("=");
+        try {
+          if (decodeURIComponent(rawKey) === key) {
+            return decodeURIComponent(rawValue);
+          }
+        } catch {
+          if (rawKey === key)
+            return rawValue;
+        }
+      }
+      return null;
+    }
+  }
   /**
    * 从 url 或路由 path 解析 pathname（不含 query，去掉末尾 /）
    */

package/lib/server/modules/order/index.d.ts

@@ -40,6 +40,13 @@ export declare class OrderModule extends BaseModule implements Module {
     getOrderByOrderId(orderId: OrderId): OrderData | undefined;
     loadOrdersByServer(): Promise<OrderData[]>;
     getOrdersByResourceId(resourceId: string | number): OrderData[];
+    /**
+     * 仅覆盖本地已存在的订单；不存在则直接跳过，不落库、不 emit。
+     * 适用于"按 order_id 主动刷新本地订单详情"的代理场景。
+     */
+    overwriteExistingOrder(fresh: OrderData): Promise<{
+        overwritten: boolean;
+    }>;
     /**
      * 通过 SSE 按自定义 query 拉取订单（支持 select/with 精简字段）
      */