befly 3.21.2 → 3.22.1

package/lib/dbParse.js

@@ -0,0 +1,1045 @@
+import { isNonEmptyString, isNullable, isPlainObject, isString } from "../utils/is.js";
+import { snakeCase } from "../utils/util.js";
+import { assertNoExprField, clearDeep, fieldsToSnake, normalizeQualifierField, orderByToSnake, parseFieldAliasParts, parseTableRef, processJoinField, processJoinOn, processJoinOrderBy, processJoinWhere, whereKeysToSnake } from "./dbUtil.js";
+
+function assertNonEmptyString(value, label) {
+    if (!isNonEmptyString(value)) {
+        throw new Error(`${label} 必须是非空字符串`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function assertPlainObjectValue(value, label) {
+    if (!isPlainObject(value)) {
+        throw new Error(`${label} 必须是对象`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function validateWhereObject(where, label, required = false) {
+    if (isNullable(where)) {
+        if (required) {
+            throw new Error(`${label} 必须是对象`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+        return;
+    }
+
+    if (!isPlainObject(where)) {
+        throw new Error(`${label} 必须是对象`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const visitWhereMeta = (currentWhere, currentLabel) => {
+        if (!isPlainObject(currentWhere)) {
+            return;
+        }
+
+        for (const [key, value] of Object.entries(currentWhere)) {
+            if (key === "$exclude") {
+                if (isNullable(value)) {
+                    continue;
+                }
+
+                if (!isPlainObject(value)) {
+                    throw new Error(`${currentLabel}.$exclude 必须是对象`, {
+                        cause: null,
+                        code: "validation"
+                    });
+                }
+
+                for (const [excludeKey, excludeValue] of Object.entries(value)) {
+                    assertNonEmptyString(excludeKey, `${currentLabel}.$exclude 的字段名`);
+                    if (!Array.isArray(excludeValue)) {
+                        throw new Error(`${currentLabel}.$exclude.${excludeKey} 必须是数组`, {
+                            cause: null,
+                            code: "validation"
+                        });
+                    }
+                }
+                continue;
+            }
+
+            if ((key === "$or" || key === "$and") && Array.isArray(value)) {
+                for (let i = 0; i < value.length; i++) {
+                    if (isPlainObject(value[i])) {
+                        visitWhereMeta(value[i], `${currentLabel}.${key}[${i}]`);
+                    }
+                }
+                continue;
+            }
+
+            if (isPlainObject(value)) {
+                visitWhereMeta(value, `${currentLabel}.${key}`);
+            }
+        }
+    };
+
+    visitWhereMeta(where, label);
+}
+
+function validateOrderByItems(orderBy, label) {
+    if (!Array.isArray(orderBy)) {
+        throw new Error(`${label} 必须是数组`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    for (const item of orderBy) {
+        if (!isString(item) || !item.includes("#")) {
+            throw new Error(`${label} 字段必须是 "字段#方向" 格式的字符串`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        const parts = item.split("#");
+        if (parts.length !== 2) {
+            throw new Error(`${label} 字段必须是 "字段#方向" 格式的字符串`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        const field = isString(parts[0]) ? parts[0].trim() : "";
+        const direction = isString(parts[1]) ? parts[1].trim().toUpperCase() : "";
+        if (!field) {
+            throw new Error(`${label} 中字段名不能为空`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+        if (direction !== "ASC" && direction !== "DESC") {
+            throw new Error(`${label} 方向必须是 ASC 或 DESC`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+    }
+}
+
+function assertJoinFieldRef(value, label) {
+    if (!isNonEmptyString(value)) {
+        throw new Error(`${label} 不能为空`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const parts = value.split(".").map((item) => item.trim());
+    if (parts.length !== 2 || !isNonEmptyString(parts[0]) || !isNonEmptyString(parts[1])) {
+        throw new Error(`${label} 必须是 alias.field 格式`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function parseLeftJoinEquality(joinItem) {
+    if (!isNonEmptyString(joinItem)) {
+        return null;
+    }
+
+    const match = joinItem.match(/^([a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*) ([a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*)$/);
+    if (!match) {
+        return null;
+    }
+
+    return {
+        left: match[1],
+        right: match[2]
+    };
+}
+
+function validateLeftJoinItems(leftJoin, label) {
+    if (!Array.isArray(leftJoin)) {
+        throw new Error(`${label} 必须是数组`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    for (let i = 0; i < leftJoin.length; i++) {
+        const joinItem = leftJoin[i];
+        if (!isNonEmptyString(joinItem)) {
+            throw new Error(`${label}[${i}] 必须是非空字符串`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        const parsed = parseLeftJoinEquality(joinItem);
+        if (!parsed) {
+            throw new Error(`${label}[${i}] 必须是 "left.field right.field" 格式（空格表示等于）`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        assertJoinFieldRef(parsed.left, `${label}[${i}] 左侧字段`);
+        assertJoinFieldRef(parsed.right, `${label}[${i}] 右侧字段`);
+    }
+}
+
+function validateQueryOptions(options, label) {
+    if (!isPlainObject(options)) {
+        throw new Error(`${label} 必须是对象`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    if (Array.isArray(options.table)) {
+        if (options.table.length === 0) {
+            throw new Error(`${label}.table 不能为空数组`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        for (let i = 0; i < options.table.length; i++) {
+            assertNonEmptyString(options.table[i], `${label}.table[${i}]`);
+            parseTableRef(options.table[i]);
+        }
+
+        if (Array.isArray(options.leftJoin) && options.leftJoin.length > 0) {
+            if (options.table.length !== options.leftJoin.length + 1) {
+                throw new Error(`${label}.table 与 ${label}.leftJoin 数量不匹配，要求 table.length = leftJoin.length + 1`, {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+        } else if (options.table.length > 1) {
+            throw new Error(`${label}.table 为数组时必须配合 leftJoin 使用`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+    } else {
+        assertNonEmptyString(options.table, `${label}.table`);
+        parseTableRef(options.table);
+
+        if (Array.isArray(options.leftJoin) && options.leftJoin.length > 0) {
+            throw new Error(`${label}.leftJoin 启用时，${label}.table 必须是数组`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+    }
+
+    if (!isNullable(options.where)) {
+        validateWhereObject(options.where, `${label}.where`);
+    }
+
+    if (!isNullable(options.fields) && !Array.isArray(options.fields)) {
+        throw new Error(`${label}.fields 必须是数组`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    if (!isNullable(options.orderBy)) {
+        validateOrderByItems(options.orderBy, `${label}.orderBy`);
+    }
+
+    if (!isNullable(options.leftJoin)) {
+        validateLeftJoinItems(options.leftJoin, `${label}.leftJoin`);
+    }
+
+    if (!isNullable(options.page) && (!Number.isFinite(options.page) || Math.floor(options.page) !== options.page)) {
+        throw new Error(`${label}.page 必须是整数`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    if (!isNullable(options.limit) && (!Number.isFinite(options.limit) || Math.floor(options.limit) !== options.limit)) {
+        throw new Error(`${label}.limit 必须是整数`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function assertBatchDataList(dataList, label) {
+    if (!Array.isArray(dataList)) {
+        throw new Error(`${label} 必须是数组`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    for (let i = 0; i < dataList.length; i++) {
+        if (!isPlainObject(dataList[i])) {
+            throw new Error(`${label}[${i}] 必须是对象`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+    }
+}
+
+function validateNoLeftJoinReadOptions(options, label, joinErrorMessage) {
+    assertNonEmptyString(options.table, `${label}.table`);
+    validateWhereObject(options.where, `${label}.where`, false);
+    if (Array.isArray(options.leftJoin) && options.leftJoin.length > 0) {
+        throw new Error(joinErrorMessage, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    if (Array.isArray(options.table)) {
+        throw new Error(`${label}.table 不支持数组`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const table = isString(options.table) ? options.table.trim() : "";
+    if (!table) {
+        throw new Error(`${label}.table 不能为空`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (table.includes(" ")) {
+        throw new Error(`${label} 不支持别名表写法（table: ${table}）`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (table.includes(".")) {
+        throw new Error(`${label} 不支持 schema.table 写法（table: ${table}）`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    if (!isNullable(options.orderBy)) {
+        validateOrderByItems(options.orderBy, `${label}.orderBy`);
+    }
+    if (!isNullable(options.page) && (!Number.isFinite(options.page) || Math.floor(options.page) !== options.page)) {
+        throw new Error(`${label}.page 必须是整数`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (!isNullable(options.limit) && (!Number.isFinite(options.limit) || Math.floor(options.limit) !== options.limit)) {
+        throw new Error(`${label}.limit 必须是整数`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function assertSafeFieldName(field) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(field)) {
+        throw new Error(`无效的字段名: ${field}，只允许字母、数字和下划线`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function assertPageLimitRange(page, limit, rawTable) {
+    if (page < 1 || page > 10000) {
+        throw new Error(`页码必须在 1 到 10000 之间 (table: ${rawTable}, page: ${page}, limit: ${limit})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (limit < 1 || limit > 100000) {
+        throw new Error(`每页数量必须在 1 到 100000 之间 (table: ${rawTable}, page: ${page}, limit: ${limit})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function validateIncrementOptions(table, field, where, value, label) {
+    assertNonEmptyString(table, `${label}.table`);
+    validateWhereObject(where, `${label}.where`, true);
+    assertSafeFieldName(snakeCase(table));
+    assertSafeFieldName(snakeCase(field));
+    if (typeof value !== "number" || Number.isNaN(value)) {
+        throw new Error(`自增值必须是有效的数字 (table: ${table}, field: ${field}, value: ${value})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function assertEffectiveWhere(where, label) {
+    if (!where || Object.keys(where).length === 0) {
+        throw new Error(`${label} 需要有效的 WHERE 条件`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function assertDefinedParamValue(value) {
+    if (value === undefined) {
+        throw new Error("SQL 参数值 不能为 undefined", {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function normalizeTableRef(tableRef) {
+    const parsed = parseTableRef(tableRef);
+    const schemaPart = parsed.schema ? snakeCase(parsed.schema) : null;
+    const tablePart = snakeCase(parsed.table);
+    const aliasPart = parsed.alias ? snakeCase(parsed.alias) : null;
+    let result = schemaPart ? `${schemaPart}.${tablePart}` : tablePart;
+    if (aliasPart) {
+        result = `${result} ${aliasPart}`;
+    }
+    return result;
+}
+
+function parseFieldSelection(fields) {
+    if (!fields || fields.length === 0) {
+        return { type: "all", fields: [] };
+    }
+
+    if (fields.some((field) => field === "*")) {
+        throw new Error("fields 不支持 * 星号，请使用空数组 [] 或不传参数表示查询所有字段", {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    if (fields.some((field) => !isNonEmptyString(field))) {
+        throw new Error("fields 不能包含空字符串或无效值", {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    for (const rawField of fields) {
+        const checkField = rawField.startsWith("!") ? rawField.substring(1) : rawField;
+        assertNoExprField(checkField);
+    }
+
+    const includeFields = fields.filter((field) => !field.startsWith("!"));
+    const excludeFields = fields.filter((field) => field.startsWith("!"));
+
+    if (includeFields.length > 0 && excludeFields.length === 0) {
+        return { type: "include", fields: includeFields };
+    }
+    if (excludeFields.length > 0 && includeFields.length === 0) {
+        return { type: "exclude", fields: excludeFields.map((field) => field.substring(1)) };
+    }
+
+    throw new Error('fields 不能同时包含普通字段和排除字段（! 开头）。只能使用以下3种方式之一：\n1. 空数组 [] 或不传（查询所有）\n2. 全部指定字段 ["id", "name"]\n3. 全部排除字段 ["!password", "!token"]', {
+        cause: null,
+        code: "validation"
+    });
+}
+
+function getTableQualifier(tableRef) {
+    const parsed = parseTableRef(tableRef);
+    if (parsed.alias) {
+        return snakeCase(parsed.alias);
+    }
+
+    return snakeCase(parsed.table);
+}
+
+function parseJoinFieldSelection(fields, mainTableRef) {
+    if (!fields || fields.length === 0) {
+        throw new Error("leftJoin 查询必须显式传 fields，不支持空 fields 或查询全部字段", {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const mainQualifier = getTableQualifier(mainTableRef);
+    const mainWildcard = `${mainQualifier}.*`;
+    const includeFields = [];
+    const mainExcludeFields = [];
+    let mainAllIncluded = false;
+
+    for (const rawField of fields) {
+        if (!isNonEmptyString(rawField)) {
+            throw new Error("fields 不能包含空字符串或无效值", {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        const trimmed = rawField.trim();
+        if (trimmed === "*") {
+            throw new Error("fields 不支持 * 星号，请使用空数组 [] 或不传参数表示查询所有字段", {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        if (trimmed.startsWith("!")) {
+            const fieldPart = trimmed.substring(1).trim();
+            if (!isNonEmptyString(fieldPart)) {
+                throw new Error("fields 不能包含空字符串或无效值", {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+            if (/\s/.test(fieldPart)) {
+                throw new Error("leftJoin 排除字段不支持别名", {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+
+            assertNoExprField(fieldPart);
+            const normalizedField = normalizeQualifierField(fieldPart);
+            if (normalizedField === mainWildcard) {
+                throw new Error("leftJoin 主表排除字段不能使用 *", {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+            if (!normalizedField.startsWith(`${mainQualifier}.`)) {
+                throw new Error("leftJoin 排除字段仅支持主表字段，请使用主表限定符", {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+
+            mainExcludeFields.push(normalizedField.substring(mainQualifier.length + 1));
+            continue;
+        }
+
+        assertNoExprField(trimmed);
+        const aliasParts = parseFieldAliasParts(trimmed);
+        const normalizedField = normalizeQualifierField(aliasParts ? aliasParts.fieldPart.trim() : trimmed);
+        if (normalizedField === mainWildcard) {
+            if (aliasParts) {
+                throw new Error("leftJoin 主表全字段不支持别名", {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+            mainAllIncluded = true;
+            continue;
+        }
+
+        includeFields.push(trimmed);
+    }
+
+    if (mainExcludeFields.length > 0 && !mainAllIncluded) {
+        throw new Error("leftJoin 使用主表排除字段时，必须同时传主表限定符.*", {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    return {
+        type: "join",
+        includeFields: includeFields,
+        mainAllIncluded: mainAllIncluded,
+        mainExcludeFields: mainExcludeFields,
+        mainQualifier: mainQualifier
+    };
+}
+
+function createWhereRoot(join = "AND") {
+    return { type: "group", join: join, items: [] };
+}
+
+function appendWhereNode(root, node) {
+    if (node) {
+        root.items.push(node);
+    }
+}
+
+function buildArrayOperatorNode(fieldName, operator, value, errorFactory, emptyMessage) {
+    if (!Array.isArray(value)) {
+        throw new Error(errorFactory(operator), {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (value.length === 0) {
+        throw new Error(emptyMessage, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    return { type: "op", field: fieldName, operator: operator, value: value };
+}
+
+function buildRangeOrNullOperatorNode(fieldName, operator, value) {
+    if (operator === "$between" || operator === "$notBetween") {
+        if (Array.isArray(value) && value.length === 2) {
+            return { type: "op", field: fieldName, operator: operator, value: value };
+        }
+        return null;
+    }
+
+    if (value === true) {
+        return { type: "op", field: fieldName, operator: operator, value: value };
+    }
+
+    return null;
+}
+
+function buildOperatorNode(fieldName, operator, value) {
+    switch (operator) {
+        case "$in":
+            return buildArrayOperatorNode(fieldName, operator, value, (currentOperator) => `$in 操作符的值必须是数组 (operator: ${currentOperator})`, "$in 操作符的数组不能为空");
+        case "$notIn":
+            return buildArrayOperatorNode(fieldName, operator, value, (currentOperator) => `$notIn 操作符的值必须是数组 (operator: ${currentOperator})`, "$notIn 操作符的数组不能为空");
+        case "$between":
+        case "$notBetween":
+        case "$null":
+        case "$notNull":
+            return buildRangeOrNullOperatorNode(fieldName, operator, value);
+        case "$like":
+        case "$leftLike":
+        case "$rightLike":
+            if (isString(value) && value.trim() === "") {
+                return null;
+            }
+            assertDefinedParamValue(value);
+            return { type: "op", field: fieldName, operator: operator, value: value };
+        default:
+            assertDefinedParamValue(value);
+            return { type: "op", field: fieldName, operator: operator, value: value };
+    }
+}
+
+function appendFieldCondition(group, key, value) {
+    if (key.includes("$")) {
+        const lastDollarIndex = key.lastIndexOf("$");
+        appendWhereNode(group, buildOperatorNode(key.substring(0, lastDollarIndex), `$${key.substring(lastDollarIndex + 1)}`, value));
+        return;
+    }
+
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        for (const [operator, operatorValue] of Object.entries(value)) {
+            appendWhereNode(group, buildOperatorNode(key, operator, operatorValue));
+        }
+        return;
+    }
+
+    appendWhereNode(group, buildOperatorNode(key, "=", value));
+}
+
+function appendAndConditions(group, value) {
+    if (!Array.isArray(value)) {
+        return;
+    }
+
+    for (const condition of value) {
+        if (!condition || typeof condition !== "object" || Array.isArray(condition)) {
+            continue;
+        }
+
+        const sub = parseWhereObject(condition);
+        if (sub.items.length === 0) {
+            continue;
+        }
+
+        if (sub.join === "AND") {
+            for (const item of sub.items) {
+                group.items.push(item);
+            }
+            continue;
+        }
+
+        group.items.push(sub);
+    }
+}
+
+function appendOrConditions(group, value) {
+    if (!Array.isArray(value)) {
+        return;
+    }
+
+    const orGroup = createWhereRoot("OR");
+    for (const condition of value) {
+        if (!condition || typeof condition !== "object" || Array.isArray(condition)) {
+            continue;
+        }
+
+        const sub = parseWhereObject(condition);
+        if (sub.items.length > 0) {
+            orGroup.items.push(sub);
+        }
+    }
+
+    if (orGroup.items.length > 0) {
+        group.items.push(orGroup);
+    }
+}
+
+function parseWhereObject(whereObj) {
+    if (!whereObj || typeof whereObj !== "object") {
+        return createWhereRoot();
+    }
+
+    const group = createWhereRoot();
+
+    for (const [key, value] of Object.entries(whereObj)) {
+        if (value === undefined) {
+            continue;
+        }
+
+        if (key === "$and") {
+            appendAndConditions(group, value);
+            continue;
+        }
+
+        if (key === "$or") {
+            appendOrConditions(group, value);
+            continue;
+        }
+
+        appendFieldCondition(group, key, value);
+    }
+
+    return group;
+}
+
+function applyDefaultStateFilter(where = {}, table, hasLeftJoin = false, beflyMode = "auto") {
+    if (beflyMode === "manual") {
+        return where;
+    }
+
+    const hasStateCondition = Object.keys(where).some((key) => key.startsWith("state") || key.includes(".state"));
+    if (hasStateCondition) {
+        return where;
+    }
+
+    const result = {};
+    for (const [key, value] of Object.entries(where)) {
+        result[key] = value;
+    }
+
+    if (hasLeftJoin && table) {
+        result[`${table}.state$gt`] = 0;
+        return result;
+    }
+
+    result.state$gt = 0;
+    return result;
+}
+
+function parseLeftJoinItem(joinTable, joinItem) {
+    const parts = joinItem.split(" ");
+    return {
+        type: "left",
+        table: normalizeTableRef(joinTable),
+        on: processJoinOn(`${parts[0]} = ${parts[1]}`)
+    };
+}
+
+function parseStructuredOrderBy(orderBy) {
+    return orderBy.map((item) => {
+        const parts = item.split("#");
+        return {
+            field: parts[0].trim(),
+            dir: parts[1].trim().toUpperCase()
+        };
+    });
+}
+
+export class DbParse {
+    tables;
+    beflyMode;
+    getTableColumns;
+
+    constructor(options = {}) {
+        this.tables = isPlainObject(options.tables) ? options.tables : {};
+        this.beflyMode = options.beflyMode === "manual" ? "manual" : "auto";
+        this.getTableColumns = options.getTableColumns;
+    }
+
+    classifyFields(fields) {
+        return parseFieldSelection(fields);
+    }
+
+    classifyJoinFields(fields, mainTableRef) {
+        return parseJoinFieldSelection(fields, mainTableRef);
+    }
+
+    parseLeftJoinItem(joinTable, joinItem) {
+        return parseLeftJoinItem(joinTable, joinItem);
+    }
+
+    applyDefaultStateFilter(where, table, hasLeftJoin = false) {
+        return applyDefaultStateFilter(where, table, hasLeftJoin, this.beflyMode);
+    }
+
+    async parseRead(options, mode) {
+        const label = mode === "one" ? "getOne.options" : mode === "list" ? "getList.options" : "getAll.options";
+        validateQueryOptions(options, label);
+
+        const hasLeftJoin = Array.isArray(options.leftJoin) && options.leftJoin.length > 0;
+        const classifiedFields = hasLeftJoin ? parseJoinFieldSelection(options.fields, options.table[0]) : parseFieldSelection(options.fields);
+        const cleanWhere = clearDeep(options.where || {});
+
+        let prepared;
+        if (hasLeftJoin) {
+            prepared = await this._normalizeLeftJoinReadOptions(options, cleanWhere, classifiedFields);
+        } else {
+            prepared = await this._normalizeSingleTableReadOptions(options, cleanWhere, classifiedFields);
+        }
+
+        if (mode === "list") {
+            assertPageLimitRange(prepared.page, prepared.limit, options.table);
+        }
+
+        return prepared;
+    }
+
+    parseCount(options) {
+        validateQueryOptions(options, "getCount.options");
+        const cleanWhere = clearDeep(options.where || {});
+        const hasLeftJoin = Array.isArray(options.leftJoin) && options.leftJoin.length > 0;
+
+        if (hasLeftJoin) {
+            return this._normalizeLeftJoinCountOptions(options, cleanWhere);
+        }
+
+        const snakeTable = snakeCase(Array.isArray(options.table) ? options.table[0] : options.table);
+        const normalizedWhere = applyDefaultStateFilter(whereKeysToSnake(cleanWhere), snakeTable, false, this.beflyMode);
+        return {
+            table: snakeTable,
+            fields: [],
+            where: parseWhereObject(normalizedWhere),
+            leftJoins: [],
+            orderBy: [],
+            page: options.page || 1,
+            limit: options.limit || 10
+        };
+    }
+
+    parseExists(options) {
+        validateNoLeftJoinReadOptions(options, "exists", "exists 不支持 leftJoin（请使用显式 query 或拆分查询）");
+        return this._prepareSingleTableWhere(options.table, options.where, true, false, "exists");
+    }
+
+    async parseFieldValue(options) {
+        validateNoLeftJoinReadOptions(options, "getFieldValue", "getFieldValue 不支持 leftJoin（请使用 getOne/getList 并自行取字段）");
+        assertSafeFieldName(options.field);
+
+        const readOptions = {
+            table: options.table,
+            fields: [options.field]
+        };
+        if (options.where !== undefined) readOptions.where = options.where;
+        if (options.orderBy !== undefined) readOptions.orderBy = options.orderBy;
+        if (options.page !== undefined) readOptions.page = options.page;
+        if (options.limit !== undefined) readOptions.limit = options.limit;
+
+        return {
+            field: options.field,
+            prepared: await this.parseRead(readOptions, "one")
+        };
+    }
+
+    parseInsert(options) {
+        assertNonEmptyString(options.table, "insData.table");
+        assertPlainObjectValue(options.data, "insData.data");
+        return {
+            table: options.table,
+            snakeTable: snakeCase(options.table),
+            data: options.data
+        };
+    }
+
+    parseInsertBatch(table, dataList) {
+        assertNonEmptyString(table, "insBatch.table");
+        assertBatchDataList(dataList, "insBatch.dataList");
+        return {
+            table: table,
+            snakeTable: snakeCase(table),
+            dataList: dataList
+        };
+    }
+
+    parseUpdate(options) {
+        assertNonEmptyString(options.table, "updData.table");
+        assertPlainObjectValue(options.data, "updData.data");
+        validateWhereObject(options.where, "updData.where", true);
+        return {
+            table: options.table,
+            snakeTable: snakeCase(options.table),
+            where: this._prepareSingleTableWhere(options.table, options.where, true, true, "updData").where,
+            data: options.data
+        };
+    }
+
+    parseDelete(options, force = false) {
+        const label = force ? "delForce" : "delData";
+        assertNonEmptyString(options.table, `${label}.table`);
+        validateWhereObject(options.where, `${label}.where`, true);
+        return {
+            table: options.table,
+            snakeTable: snakeCase(options.table),
+            where: this._prepareSingleTableWhere(options.table, options.where, !force, true, label).where
+        };
+    }
+
+    parseDelForceBatch(table, ids) {
+        assertNonEmptyString(table, "delForceBatch.table");
+        if (!Array.isArray(ids)) {
+            throw new Error("delForceBatch.ids 必须是数组", {
+                cause: null,
+                code: "validation"
+            });
+        }
+        return {
+            table: table,
+            snakeTable: snakeCase(table),
+            ids: ids
+        };
+    }
+
+    parseUpdateBatch(table, dataList) {
+        assertNonEmptyString(table, "updBatch.table");
+        assertBatchDataList(dataList, "updBatch.dataList");
+        return {
+            table: table,
+            snakeTable: snakeCase(table),
+            dataList: dataList
+        };
+    }
+
+    parseIncrement(table, field, where, value, label = "increment") {
+        validateIncrementOptions(table, field, where, value, label);
+        const prepared = this._prepareSingleTableWhere(table, where, true, true, label);
+        return {
+            table: table,
+            snakeTable: prepared.snakeTable,
+            snakeField: snakeCase(field),
+            where: prepared.where,
+            value: value
+        };
+    }
+
+    async _normalizeLeftJoinReadOptions(options, cleanWhere, classifiedFields) {
+        const mainTableRef = options.table[0];
+        const processedFields = await this._joinFieldsToSnake(mainTableRef, classifiedFields);
+        const joinTableRefs = options.table.slice(1);
+        const normalizedTableRef = normalizeTableRef(mainTableRef);
+        const mainQualifier = getTableQualifier(mainTableRef);
+        const joins = options.leftJoin.map((joinItem, index) => parseLeftJoinItem(joinTableRefs[index], joinItem));
+        const normalizedWhere = applyDefaultStateFilter(processJoinWhere(cleanWhere), mainQualifier, true, this.beflyMode);
+
+        return {
+            table: normalizedTableRef,
+            fields: processedFields,
+            where: parseWhereObject(normalizedWhere),
+            leftJoins: joins,
+            orderBy: parseStructuredOrderBy(processJoinOrderBy(options.orderBy || [])),
+            page: options.page || 1,
+            limit: options.limit || 10
+        };
+    }
+
+    _normalizeLeftJoinCountOptions(options, cleanWhere) {
+        const mainTableRef = options.table[0];
+        const joinTableRefs = options.table.slice(1);
+        const normalizedTableRef = normalizeTableRef(mainTableRef);
+        const mainQualifier = getTableQualifier(mainTableRef);
+        const joins = options.leftJoin.map((joinItem, index) => parseLeftJoinItem(joinTableRefs[index], joinItem));
+        const normalizedWhere = applyDefaultStateFilter(processJoinWhere(cleanWhere), mainQualifier, true, this.beflyMode);
+
+        return {
+            table: normalizedTableRef,
+            fields: [],
+            where: parseWhereObject(normalizedWhere),
+            leftJoins: joins,
+            orderBy: [],
+            page: options.page || 1,
+            limit: options.limit || 10
+        };
+    }
+
+    async _normalizeSingleTableReadOptions(options, cleanWhere, classifiedFields) {
+        const tableRef = Array.isArray(options.table) ? options.table[0] : options.table;
+        const snakeTable = snakeCase(tableRef);
+        const processedFields = await fieldsToSnake(tableRef, classifiedFields, this.getTableColumns);
+        const normalizedWhere = applyDefaultStateFilter(whereKeysToSnake(cleanWhere), snakeTable, false, this.beflyMode);
+
+        return {
+            table: snakeTable,
+            fields: processedFields,
+            where: parseWhereObject(normalizedWhere),
+            leftJoins: [],
+            orderBy: parseStructuredOrderBy(orderByToSnake(options.orderBy || [])),
+            page: options.page || 1,
+            limit: options.limit || 10
+        };
+    }
+
+    _prepareSingleTableWhere(table, where, useDefaultStateFilter, required, label) {
+        const snakeTable = snakeCase(table);
+        const normalizedWhere = whereKeysToSnake(clearDeep(where || {}));
+        if (required) {
+            assertEffectiveWhere(normalizedWhere, label);
+        }
+        const whereWithDefault = useDefaultStateFilter ? applyDefaultStateFilter(normalizedWhere, snakeTable, false, this.beflyMode) : normalizedWhere;
+        return {
+            snakeTable: snakeTable,
+            where: parseWhereObject(whereWithDefault)
+        };
+    }
+
+    async _joinFieldsToSnake(mainTableRef, classifiedFields) {
+        if (classifiedFields.type !== "join") {
+            return [];
+        }
+
+        const processedFields = [];
+        const seenFields = new Set();
+        const pushField = (field) => {
+            if (seenFields.has(field)) {
+                return;
+            }
+            seenFields.add(field);
+            processedFields.push(field);
+        };
+
+        if (classifiedFields.mainAllIncluded) {
+            const mainColumns = await this.getTableColumns(mainTableRef);
+            const excludeFieldSet = new Set(classifiedFields.mainExcludeFields.map((field) => snakeCase(field)));
+
+            for (const column of mainColumns) {
+                if (excludeFieldSet.has(column)) {
+                    continue;
+                }
+                pushField(`${classifiedFields.mainQualifier}.${column}`);
+            }
+        }
+
+        for (const field of classifiedFields.includeFields) {
+            pushField(processJoinField(field));
+        }
+
+        if (processedFields.length === 0) {
+            throw new Error(`排除字段后没有剩余字段可查询。表: ${mainTableRef}, 排除: ${classifiedFields.mainExcludeFields.join(", ")}`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        return processedFields;
+    }
+}