@maiyunnet/kebab 9.19.0 → 9.20.0

package/index.d.ts

@@ -5,7 +5,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export declare const VER = "9.19.0";
+export declare const VER = "9.20.0";
 /** --- 框架根目录，以 / 结尾  --- */
 export declare const ROOT_PATH: string;
 /** --- 框架的 LIB，以 / 结尾 --- */

package/index.js

@@ -6,7 +6,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export const VER = '9.19.0';
+export const VER = '9.20.0';
 // --- 服务端用的路径 ---
 const imu = decodeURIComponent(import.meta.url).replace('file://', '').replace(/^\/(\w:)/, '$1');
 /** --- /xxx/xxx --- */

package/lib/sql.d.ts

@@ -10,6 +10,8 @@ export declare enum ESERVICE {
     'MYSQL' = 0,
     'PGSQL' = 1
 }
+/** --- 非空游标值；大整数和日期请使用数据库可比较的字符串 --- */
+export type TCursorValue = string | number;
 /** --- JSON 查询操作符 --- */
 export declare enum EJSON {
     /** --- 包含值 (MySQL: JSON_CONTAINS, PG: @>) --- */
@@ -209,6 +211,15 @@ export declare class Sql {
      * @param d 排序规则
      */
     by(c: string | Array<string | string[]>, d?: 'DESC' | 'ASC'): this;
+    /**
+     * --- 按非空、同向排序字段定位游标并设置排序；字段组合须唯一且有匹配索引 ---
+     * --- 使用行比较，让 PostgreSQL 可以从复合索引边界开始扫描 ---
+     * @param c 排序字段，支持表别名；不支持表达式、GROUP BY 或 UNION
+     * @param values 上一页末行的字段值，省略时读取首批
+     * @param d 扫描方向；读取前一批时反转方向并在取回后反转列表
+     * @returns 当前 SQL 对象
+     */
+    seek(c: string | string[], values?: TCursorValue[], d?: 'DESC' | 'ASC'): this;
     /**
      * --- GROUP BY ---
      * @param c 字段字符串或数组
@@ -230,6 +241,10 @@ export declare class Sql {
      */
     copy(f?: string | string[], opt?: {
         'where'?: string | kebab.Json;
+        /** --- false 时移除本查询的排序，不修改子查询 --- */
+        'order'?: false;
+        /** --- false 时移除本查询的 LIMIT/OFFSET，不修改子查询 --- */
+        'limit'?: false;
     }): Sql;
     /**
      * --- 获取 sql 语句 ---

package/lib/sql.js

@@ -55,6 +55,7 @@ export class Sql {
         this._service = opt.service ?? ESERVICE.MYSQL;
         if (opt.data) {
             this._data = opt.data;
+            this._placeholderCounter = opt.data.length + 1;
         }
         if (opt.sql) {
             this._sql = opt.sql;
@@ -770,6 +771,54 @@ export class Sql {
         this._sql.push(sql);
         return this;
     }
+    /**
+     * --- 按非空、同向排序字段定位游标并设置排序；字段组合须唯一且有匹配索引 ---
+     * --- 使用行比较，让 PostgreSQL 可以从复合索引边界开始扫描 ---
+     * @param c 排序字段，支持表别名；不支持表达式、GROUP BY 或 UNION
+     * @param values 上一页末行的字段值，省略时读取首批
+     * @param d 扫描方向；读取前一批时反转方向并在取回后反转列表
+     * @returns 当前 SQL 对象
+     */
+    seek(c, values, d = 'DESC') {
+        const fields = typeof c === 'string' ? [c] : c;
+        if (!fields.length || new Set(fields).size !== fields.length ||
+            fields.some(field => !/^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)?$/.test(field)) ||
+            !['ASC', 'DESC'].includes(d)) {
+            throw new Error('Invalid cursor ordering');
+        }
+        if (this._sql.some(part => /^ (ORDER BY|LIMIT|GROUP BY|HAVING|UNION|FOR UPDATE)\b/i.test(part))) {
+            throw new Error('seek requires an ungrouped query without ordering or pagination');
+        }
+        if (values !== undefined) {
+            if (values.length !== fields.length || values.some(value => (typeof value !== 'string' && typeof value !== 'number') ||
+                (typeof value === 'number' && (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value)))))) {
+                throw new Error('Invalid cursor values; use strings for large integers');
+            }
+            const columns = fields.map(field => this.field(field));
+            const placeholders = values.map(() => this._placeholder());
+            const left = columns.length === 1 ? columns[0] : `(${columns.join(', ')})`;
+            const right = placeholders.length === 1 ? placeholders[0] : `(${placeholders.join(', ')})`;
+            let condition = `${left} ${d === 'DESC' ? '<' : '>'} ${right}`;
+            if (columns.length > 1) {
+                // --- 显式收紧首列边界，避免已有较宽范围条件让 PG 在索引内遍历到行比较边界 ---
+                condition += ` AND ${columns[0]} ${d === 'DESC' ? '<=' : '>='} ${this._placeholder()}`;
+            }
+            const index = this._sql.findIndex(part => part.startsWith(' WHERE '));
+            if (index === -1) {
+                this._whereDataPosition[0] = this._data.length;
+                this._sql.push(' WHERE ' + condition);
+            }
+            else {
+                this._sql[index] = ` WHERE (${this._sql[index].slice(7)}) AND ${condition}`;
+            }
+            this._data.push(...values);
+            if (columns.length > 1) {
+                this._data.push(values[0]);
+            }
+            this._whereDataPosition[1] = this._data.length;
+        }
+        return this.by(fields, d);
+    }
     /**
      * --- GROUP BY ---
      * @param c 字段字符串或数组
@@ -918,7 +967,13 @@ export class Sql {
                 sql[i] = sql[i].replace(/\$\d+/g, () => `$${counter++}`);
             }
         }
-        return get({
+        for (let i = sql.length - 1; i >= 0; --i) {
+            if ((opt.order === false && sql[i].startsWith(' ORDER BY ')) ||
+                (opt.limit === false && sql[i].startsWith(' LIMIT '))) {
+                sql.splice(i, 1);
+            }
+        }
+        const result = get({
             'service': this._service,
             'ctr': this._ctr,
             'pre': this._pre,
@@ -926,6 +981,10 @@ export class Sql {
             'sql': sql,
             'alias': lCore.clone(this._alias),
         }).hint(this._hint);
+        if (opt.where === undefined) {
+            result._whereDataPosition = [...this._whereDataPosition];
+        }
+        return result;
     }
     // --- 操作 ---
     /**

package/lib/text.d.ts

@@ -1,4 +1,17 @@
 import * as kebab from '#kebab/index.js';
+/**
+ * --- 解析三段正式发行版本 X.Y.Z，不接受前导零、预发行和构建后缀 ---
+ * @param value 待解析的版本
+ * @returns 三段安全整数，无效时返回 null
+ */
+export declare function parseVersion(value: unknown): [number, number, number] | null;
+/**
+ * --- 逐段比较三段正式发行版本 X.Y.Z，不按字符串或浮点数比较 ---
+ * @param version 待比较的版本
+ * @param target 目标版本
+ * @returns 小于返回 -1，等于返回 0，大于返回 1；任一版本无效时返回 null
+ */
+export declare function compareVersion(version: unknown, target: unknown): -1 | 0 | 1 | null;
 /**
  * --- 将文件大小格式化为带单位的字符串 ---
  * @param size 文件大小

package/lib/text.js

@@ -7,6 +7,42 @@ import * as net from 'net';
 import * as kebab from '#kebab/index.js';
 import * as lFs from './fs.js';
 import * as lCore from './core.js';
+/**
+ * --- 解析三段正式发行版本 X.Y.Z，不接受前导零、预发行和构建后缀 ---
+ * @param value 待解析的版本
+ * @returns 三段安全整数，无效时返回 null
+ */
+export function parseVersion(value) {
+    if ((typeof value !== 'string') || (value.length > 64)) {
+        return null;
+    }
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(value);
+    // --- $ 可匹配末尾换行前的位置，必须额外确认匹配完整输入 ---
+    if (match?.[0] !== value) {
+        return null;
+    }
+    const parts = [Number(match[1]), Number(match[2]), Number(match[3])];
+    return parts.every(Number.isSafeInteger) ? parts : null;
+}
+/**
+ * --- 逐段比较三段正式发行版本 X.Y.Z，不按字符串或浮点数比较 ---
+ * @param version 待比较的版本
+ * @param target 目标版本
+ * @returns 小于返回 -1，等于返回 0，大于返回 1；任一版本无效时返回 null
+ */
+export function compareVersion(version, target) {
+    const current = parseVersion(version);
+    const other = parseVersion(target);
+    if (!current || !other) {
+        return null;
+    }
+    for (let index = 0; index < current.length; index++) {
+        if (current[index] !== other[index]) {
+            return current[index] < other[index] ? -1 : 1;
+        }
+    }
+    return 0;
+}
 /**
  * --- 将文件大小格式化为带单位的字符串 ---
  * @param size 文件大小

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maiyunnet/kebab",
-  "version": "9.19.0",
+  "version": "9.20.0",
   "description": "Simple, easy-to-use, and fully-featured Node.js framework that is ready-to-use out of the box.",
   "type": "module",
   "keywords": [

package/sys/ctr.d.ts

@@ -19,6 +19,8 @@ export declare function clearLocaleData(): void;
 export type TValibotResponse<TIssue extends v.BaseIssue<unknown>> = kebab.Json[] | ((issues: [TIssue, ...TIssue[]]) => kebab.Json[]);
 /** --- 在 issue 路径完整后，根据 Kebab 生成的语言键翻译消息 --- */
 export type TValibotTranslate = (key: string, issue: v.BaseIssue<unknown>) => string;
+/** --- HTTP 重定向状态码 --- */
+export type TRedirectHttpCode = 301 | 302 | 303 | 307 | 308;
 /** --- Valibot 同步校验选项 --- */
 export interface IValibotOptions<TIssue extends v.BaseIssue<unknown>> {
     /** --- 传给 Valibot 的校验配置 --- */
@@ -58,6 +60,21 @@ export type TValibotResult<TSchema extends v.GenericSchema, TIssue extends v.Bas
     readonly issues: [TIssue, ...TIssue[]];
     readonly response: kebab.Json[];
 };
+/** --- React SSR 页面选项 --- */
+export interface IReactPageOptions {
+    /** --- 是否注入客户端水合 bundle，默认 true；设为 false 时仅输出服务端渲染的 HTML --- */
+    'hydrate'?: boolean;
+    /**
+     * --- 路由模式，不传则不注入任何 Router，组件自行管理路由（如 MemoryRouter）或无路由 ---
+     * --- 'browser'：服务端用 StaticRouter，客户端用 BrowserRouter，地址栏与路由联动 ---
+     * --- 组件本身只需使用 Routes/Route/Link 等，不要包含任何 Router 包裹层 ---
+     */
+    'router'?: 'browser';
+    /** --- BrowserRouter 的 basename，相对于 urlBase，默认空字符串 --- */
+    'routerBase'?: string;
+    /** --- 静态资源基础路径，覆盖 config.set.staticPath（支持 CDN） --- */
+    'staticPath'?: string;
+}
 /**
  * --- 判断当前 HTTP 请求是否仍可响应 ---
  * @param req 请求对象
@@ -219,26 +236,14 @@ export declare class Ctr {
      * @param props 传入组件的 props，框架常量自动合并，整体序列化为内联 JSON 供客户端水合复用
      * @param opt 可选配置
      */
-    protected _loadReactPage(path: string, props?: Record<string, kebab.Json>, opt?: {
-        /** --- 是否注入客户端水合 bundle，默认 true；设为 false 时仅输出服务端渲染的 HTML --- */
-        'hydrate'?: boolean;
-        /**
-         * --- 路由模式，不传则不注入任何 Router，组件自行管理路由（如 MemoryRouter）或无路由 ---
-         * --- 'browser'：服务端用 StaticRouter，客户端用 BrowserRouter，地址栏与路由联动 ---
-         * --- 组件本身只需使用 Routes/Route/Link 等，不要包含任何 Router 包裹层 ---
-         */
-        'router'?: 'browser';
-        /**
-         * --- BrowserRouter 的 basename，相对于 urlBase，默认空字符串 ---
-         * --- 例如组件挂载在 /test/react-router-page，则填 'test/react-router-page' ---
-         */
-        'routerBase'?: string;
-        /**
-         * --- 静态资源基础路径，覆盖 config.set.staticPath，用于指定 CDN 或自定义路径 ---
-         * --- 影响 _staticPath prop 以及水合脚本中 JS 文件的 URL 前缀 ---
-         */
-        'staticPath'?: string;
-    }): Promise<string>;
+    protected _loadReactPage(path: string, props?: Record<string, kebab.Json>, opt?: IReactPageOptions): Promise<string>;
+    /**
+     * --- 记录 React 页面错误并返回脱敏响应 ---
+     * @param message 调试信息
+     * @param detail 日志详情
+     * @returns 脱敏后的 500 页面
+     */
+    private _reactPageError;
     /**
      * --- 设置校验错误返回值 ---
      * @param rtn 返回值数组
@@ -333,10 +338,11 @@ export declare class Ctr {
      */
     protected _loadData<T>(path: string): Promise<T | false | null>;
     /**
-     * --- 跳转（302临时跳转），支持相对本项目根路径的路径或绝对路径 ---
+     * --- 跳转，支持相对本项目根路径的路径或绝对路径 ---
      * @param location 相对或绝对网址
+     * @param httpCode HTTP 重定向状态码，默认 302
      */
-    protected _location(location: string): false;
+    protected _location(location: string, httpCode?: TRedirectHttpCode): false;
     /**
      * --- 开启 Session ---
      * @param link Kv 或 Db 实例

package/sys/ctr.js

@@ -271,35 +271,28 @@ export class Ctr {
      * @param opt 可选配置
      */
     async _loadReactPage(path, props = {}, opt = {}) {
-        // --- 约定：传入路径不含 .page 后缀，框架自动补全（对应 build 命令的 *.page.tsx 约定）---
-        // --- 服务端读取 tsc 生成的组件 JS，浏览器读取 kebab build 生成的 bundle ---
-        const componentPath = this._config.const.rootPath + 'stc/' + path + '.page.js';
+        // --- 校验服务端组件与客户端水合产物 ---
+        const hydrate = opt.hydrate !== false;
+        const pagePath = `${this._config.const.rootPath}stc/${path}.page`;
+        const componentPath = `${pagePath}.js`;
         if (!await lFs.isFile(componentPath)) {
-            lCore.debug(`[CTR][_loadReactPage] componentPath ${componentPath} is not a file`);
-            lCore.log(this, `[CTR][_loadReactPage] componentPath ${componentPath} is not a file`, '-error');
-            return '';
+            return this._reactPageError(`componentPath ${componentPath} is not a file`);
         }
-        const bundlePath = this._config.const.rootPath + 'stc/' + path + '.page.bundle.js';
-        if ((opt.hydrate !== false) && !await lFs.isFile(bundlePath)) {
-            /** --- 完整错误仅写入服务端日志，避免向客户端暴露文件系统路径 --- */
-            const message = `[CTR][_loadReactPage] bundlePath ${bundlePath} is not a file; ` +
-                `run "npx kebab build -d ${this._config.const.rootPath}stc"`;
-            lCore.debug(message);
-            lCore.log(this, message, '-error');
-            this._httpCode = 500;
-            return '<h1>500 Server Error</h1><hr>Kebab';
+        const bundlePath = `${pagePath}.bundle.js`;
+        if (hydrate && !await lFs.isFile(bundlePath)) {
+            return this._reactPageError(`bundlePath ${bundlePath} is not a file; run "npx kebab build -d ${this._config.const.rootPath}stc"`);
         }
         try {
-            const reactDomServer = await import('react-dom/server');
+            // --- 并行加载 SSR 依赖与页面组件 ---
             const importPath = componentPath.startsWith('/')
                 ? componentPath
                 : `file:///${componentPath.replace(/\\/g, '/')}`;
-            const mod = await import(importPath);
-            const component = mod.default;
-            const react = await import('react');
-            // --- 语言包数据：当前语种的各命名包已由 _loadLocale 合并 ---
-            const localeData = { ...(this._localeData[this._locale] ?? {}) };
-            // --- 把框架常量合并进 props，与 _loadView 行为一致 ---
+            const [react, reactDomServer, page] = await Promise.all([
+                import('react'),
+                import('react-dom/server'),
+                import(importPath),
+            ]);
+            // --- 合并框架 Props 与路由配置 ---
             const staticPath = opt.staticPath ?? this._config.set.staticPath;
             const fullProps = {
                 ...props,
@@ -310,50 +303,50 @@ export class Ctr {
                 '_staticPath': staticPath,
                 '_staticPathFull': this._config.set.staticPathFull,
                 '_locale': this._locale,
-                '_localeData': localeData,
+                '_localeData': { ...(this._localeData[this._locale] ?? {}) },
             };
             if (opt.router === 'browser') {
-                // --- BrowserRouter 的 basename 同时用于服务端 StaticRouter 和客户端水合 ---
-                const base = opt.routerBase ?? '';
-                const routerBase = this._config.const.urlBase + base.replace(/^\//, '');
+                const routerBase = `${this._config.const.urlBase}${(opt.routerBase ?? '').replace(/^\//, '')}`;
                 fullProps['_routerBase'] = routerBase.replace(/\/$/, '');
             }
-            // --- 框架自动注入的 HTML 片段，用户组件无需手动渲染 ---
-            let bodyInject = '';
-            if (opt.hydrate !== false) {
-                // --- propsJson 在渲染前序列化，框架直接注入 HTML，组件无需手动渲染 ---
-                const propsJson = lText.stringifyJson(fullProps).replace(/<\/script>/gi, '<\\/script>');
-                const clientUrl = `${staticPath}${path}.page.bundle.js?v=${this._config.set.staticVer}`;
-                // --- props JSON + 水合脚本注入到 </body> 前 ---
-                bodyInject =
-                    `<script id="__kebab_props__" type="application/json">${propsJson}</script>` +
-                        `<script type="module">import'${clientUrl}';</script>`;
-            }
-            // --- BrowserRouter 模式：服务端用 StaticRouter 渲染，与客户端的 BrowserRouter 等价 ---
-            // --- component 来自动态 import，TypeScript 无法精确推断，需要明确限定 element 类型 ---
-            let element = react.createElement(component, fullProps);
+            // --- 创建页面元素，BrowserRouter 模式下由 StaticRouter 包裹 ---
+            const component = page.default;
+            const pageElement = react.createElement(component, fullProps);
+            let element = pageElement;
             if (opt.router === 'browser') {
-                // --- StaticRouter 在 react-router-dom v7 中从主包直接导出，无需 /server 子路径 ---
-                const lReactRouter = await import('react-router-dom');
-                const reqUrl = this._req.url ?? '/';
-                element = react.createElement(lReactRouter.StaticRouter, {
-                    'location': reqUrl,
+                const reactRouter = await import('react-router-dom');
+                element = react.createElement(reactRouter.StaticRouter, {
+                    'location': this._req.url ?? '/',
                     'basename': fullProps['_routerBase'],
-                }, react.createElement(component, fullProps));
+                }, pageElement);
             }
-            // --- 框架将 props JSON + 水合 bundle 注入到 </body> 前 ---
-            let html = '<!DOCTYPE html>' + reactDomServer.renderToString(element);
-            if (opt.hydrate !== false) {
-                html = html.replace('</body>', bodyInject + '</body>');
+            // --- 渲染完整 HTML，并按需注入客户端水合数据与 bundle ---
+            const html = `<!DOCTYPE html>${reactDomServer.renderToString(element)}`;
+            if (!hydrate) {
+                return html;
             }
-            return html;
+            const propsJson = lText.stringifyJson(fullProps).replace(/<\/script>/gi, '<\\/script>');
+            const clientUrl = `${staticPath}${path}.page.bundle.js?v=${this._config.set.staticVer}`;
+            const propsScript = `<script id="__kebab_props__" type="application/json">${propsJson}</script>`;
+            const hydrateScript = `<script type="module">import'${clientUrl}';</script>`;
+            return html.replace('</body>', `${propsScript}${hydrateScript}</body>`);
         }
         catch (e) {
-            lCore.debug(`[CTR][_loadReactPage] ${e.message ?? ''}`);
-            lCore.log(this, '[CTR][_loadReactPage] ' + lText.stringifyError(e), '-error');
-            return '';
+            return this._reactPageError(e.message ?? '', lText.stringifyError(e));
         }
     }
+    /**
+     * --- 记录 React 页面错误并返回脱敏响应 ---
+     * @param message 调试信息
+     * @param detail 日志详情
+     * @returns 脱敏后的 500 页面
+     */
+    _reactPageError(message, detail = message) {
+        lCore.debug(`[CTR][_loadReactPage] ${message}`);
+        lCore.log(this, `[CTR][_loadReactPage] ${detail}`, '-error');
+        this._httpCode = 500;
+        return '<h1>500 Server Error</h1><hr>Kebab';
+    }
     /**
      * --- 设置校验错误返回值 ---
      * @param rtn 返回值数组
@@ -783,13 +776,15 @@ export class Ctr {
         return json;
     }
     /**
-     * --- 跳转（302临时跳转），支持相对本项目根路径的路径或绝对路径 ---
+     * --- 跳转，支持相对本项目根路径的路径或绝对路径 ---
      * @param location 相对或绝对网址
+     * @param httpCode HTTP 重定向状态码，默认 302
      */
-    _location(location) {
+    _location(location, httpCode = 302) {
+        this._httpCode = httpCode;
         if (this._res) {
             this._res.setHeader('location', lText.urlResolve(this._config.const.urlBase, location));
-            // this._res.writeHead(302); Kebab 中要在最后设置，否则会报错：ERR_HTTP_HEADERS_SENT
+            // this._res.writeHead(httpCode); Kebab 中要在最后设置，否则会报错：ERR_HTTP_HEADERS_SENT
         }
         return false;
     }

package/sys/mod.d.ts

@@ -11,6 +11,13 @@ import * as kebab from '#kebab/index.js';
 export type TOnlyProperties<T> = {
     [K in keyof T as T[K] extends (...args: any[]) => any ? never : K]: T[K];
 };
+/** --- 一批游标查询结果，hasMore 表示扫描方向上还有记录 --- */
+export interface ICursorPage<T extends Record<string, unknown> = Record<string, unknown>> {
+    'list': T[];
+    'hasMore': boolean;
+    'next': lSql.TCursorValue[] | null;
+    'previous': lSql.TCursorValue[] | null;
+}
 /** --- 条数列表 --- */
 export declare class Rows<T extends Mod> implements IRows<T> {
     private readonly _items;
@@ -375,6 +382,31 @@ export default class Mod {
      * --- 获取总条数，自动抛弃 LIMIT，仅用于获取数据的情况（select） ---
      */
     total(f?: string): Promise<number>;
+    /**
+     * --- 从 PostgreSQL 执行计划估算查询总行数，移除外层排序和分页，不执行数据扫描 ---
+     * --- 请在应用游标条件前调用；非 PostgreSQL、框架分表联查或查询失败返回 false，绝不回退到 COUNT ---
+     * @returns 近似行数或 false；估算可能偏差很大，不能用于判断有无下一批
+     */
+    totalEstimate(): Promise<number | false>;
+    /**
+     * --- 读取一批游标数据，多取一条判断后续记录，不使用 OFFSET，不修改原查询 ---
+     * --- 排序字段必须全部非空、同向，且组合唯一；SELECT 中须包含对应字段（同名或指定 keys） ---
+     * @param count 本批数量
+     * @param opt 排序、边界和方向；before 为 true 时读取前一批并恢复展示顺序
+     * @param opt.by 排序字段，支持表别名
+     * @param opt.keys SELECT 结果中对应的字段名，默认去掉 by 的表别名
+     * @param opt.order 展示顺序，默认 DESC
+     * @param opt.cursor 边界行的字段值，首批省略
+     * @param opt.before 是否读取边界前一批，须提供 cursor
+     * @returns 列表、首末行游标和扫描方向上的 hasMore，数据库错误返回 false
+     */
+    allCursor<T extends Record<string, unknown> = Record<string, unknown>>(count: number, opt: {
+        'by': string | string[];
+        'keys'?: string[];
+        'order'?: 'DESC' | 'ASC';
+        'cursor'?: lSql.TCursorValue[];
+        'before'?: boolean;
+    }): Promise<ICursorPage<T> | false>;
     /**
      * --- 根据当前条件，筛选出当前条目该有的数据条数 ---
      */

package/sys/mod.js

@@ -1262,6 +1262,89 @@ export default class Mod {
         }
         return count;
     }
+    /**
+     * --- 从 PostgreSQL 执行计划估算查询总行数，移除外层排序和分页，不执行数据扫描 ---
+     * --- 请在应用游标条件前调用；非 PostgreSQL、框架分表联查或查询失败返回 false，绝不回退到 COUNT ---
+     * @returns 近似行数或 false；估算可能偏差很大，不能用于判断有无下一批
+     */
+    async totalEstimate() {
+        if (this._db.getService() !== lDb.ESERVICE.PGSQL || this._index !== null || this._contain) {
+            return false;
+        }
+        const sql = this._sql.copy(undefined, { 'order': false, 'limit': false });
+        const result = await this._db.query('EXPLAIN (FORMAT JSON) ' + sql.getSql(), sql.getData());
+        if (result.rows === null) {
+            lCore.log(this._ctr ?? {}, '[MOD][totalEstimate] Query failed', '-error');
+            return false;
+        }
+        const plan = result.rows[0]?.['QUERY PLAN'];
+        const parsed = typeof plan === 'string' ? lText.parseJson(plan) : plan;
+        if (!Array.isArray(parsed)) {
+            return false;
+        }
+        const root = parsed[0];
+        if (!root || typeof root !== 'object') {
+            return false;
+        }
+        const node = root['Plan'];
+        if (!node || typeof node !== 'object') {
+            return false;
+        }
+        const rows = node['Plan Rows'];
+        return typeof rows === 'number' && Number.isFinite(rows) && rows >= 0 ? Math.round(rows) : false;
+    }
+    /**
+     * --- 读取一批游标数据，多取一条判断后续记录，不使用 OFFSET，不修改原查询 ---
+     * --- 排序字段必须全部非空、同向，且组合唯一；SELECT 中须包含对应字段（同名或指定 keys） ---
+     * @param count 本批数量
+     * @param opt 排序、边界和方向；before 为 true 时读取前一批并恢复展示顺序
+     * @param opt.by 排序字段，支持表别名
+     * @param opt.keys SELECT 结果中对应的字段名，默认去掉 by 的表别名
+     * @param opt.order 展示顺序，默认 DESC
+     * @param opt.cursor 边界行的字段值，首批省略
+     * @param opt.before 是否读取边界前一批，须提供 cursor
+     * @returns 列表、首末行游标和扫描方向上的 hasMore，数据库错误返回 false
+     */
+    async allCursor(count, opt) {
+        if (!Number.isSafeInteger(count) || count < 1 || count >= Number.MAX_SAFE_INTEGER ||
+            this._index !== null || this._contain || (opt.before && !opt.cursor) ||
+            (opt.order !== undefined && !['ASC', 'DESC'].includes(opt.order))) {
+            throw new Error('Invalid cursor page options; framework sharding and contain are unsupported');
+        }
+        const fields = typeof opt.by === 'string' ? [opt.by] : opt.by;
+        const keys = opt.keys ?? fields.map(field => field.split('.').pop());
+        if (keys.length !== fields.length || new Set(keys).size !== keys.length) {
+            throw new Error('Cursor result keys must match ordering fields');
+        }
+        const order = opt.order ?? 'DESC';
+        const direction = opt.before ? (order === 'DESC' ? 'ASC' : 'DESC') : order;
+        const sql = this._sql.copy(undefined, { 'order': false, 'limit': false });
+        sql.seek(fields, opt.cursor, direction).limit(count + 1);
+        const result = await this._db.query(sql.getSql(), sql.getData());
+        if (result.rows === null) {
+            lCore.log(this._ctr ?? {}, '[MOD][allCursor] Query failed', '-error');
+            return false;
+        }
+        const hasMore = result.rows.length > count;
+        const list = result.rows.slice(0, count);
+        if (opt.before) {
+            list.reverse();
+        }
+        const boundary = (row) => keys.map(key => {
+            const value = row[key];
+            if ((typeof value !== 'string' && typeof value !== 'number') ||
+                (typeof value === 'number' && (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value))))) {
+                throw new Error('Cursor columns must be non-null strings or safe numbers');
+            }
+            return value;
+        });
+        return {
+            'list': list,
+            'hasMore': hasMore,
+            'next': list.length ? boundary(list[list.length - 1]) : null,
+            'previous': list.length ? boundary(list[0]) : null,
+        };
+    }
     /**
      * --- 根据当前条件，筛选出当前条目该有的数据条数 ---
      */

package/sys/route.js

@@ -581,6 +581,8 @@ export async function run(data) {
         data.res.setHeader('expires', new Date(Date.now() + cacheTTL * 1_000).toUTCString());
         data.res.setHeader('cache-control', 'max-age=' + cacheTTL.toString());
     }
+    // --- 记录控制器是否显式设置状态码；未设置时，带 Location 的空响应仍兼容为 302 ---
+    const hasCustomHttpCode = httpCode !== 0;
     // --- 设置自定义 hcode ---
     if (httpCode === 0) {
         httpCode = 200;
@@ -591,7 +593,7 @@ export async function run(data) {
             // --- 已经自行输出过 writeHead，可能自行处理了内容，如 pipe，则不再 writeHead ---
         }
         else {
-            lCore.writeHead(data.res, data.res.getHeader('location') ? 302 : httpCode);
+            lCore.writeHead(data.res, data.res.getHeader('location') && !hasCustomHttpCode ? 302 : httpCode);
         }
         if (!data.res.writableEnded) {
             // --- 如果当前还没结束，则强制关闭连接，一切 pipe 请自行在方法中 await，否则会被中断 ---