@lark-apaas/fullstack-presets 1.1.14 → 1.1.16

package/lib/custom-eslint-rules/index.d.ts

@@ -3,4 +3,10 @@ export declare const customRules: {
     'require-app-container': import("eslint").Rule.RuleModule;
     'no-direct-capability-api': import("eslint").Rule.RuleModule;
     'require-scroll-reveal-hook': import("eslint").Rule.RuleModule;
+    'require-number-wrapped-count': import("eslint").Rule.RuleModule;
+    'require-shared-response-type': import("eslint").Rule.RuleModule;
+    'require-shared-request-type': import("eslint").Rule.RuleModule;
+    'no-welcome-index-route': import("eslint").Rule.RuleModule;
+    'require-index-route': import("eslint").Rule.RuleModule;
+    'no-duplicate-route-component': import("eslint").Rule.RuleModule;
 };

package/lib/custom-eslint-rules/index.js

@@ -8,9 +8,21 @@ const no_nested_styled_jsx_1 = __importDefault(require("./no-nested-styled-jsx")
 const require_app_container_1 = __importDefault(require("./require-app-container"));
 const no_direct_capability_api_1 = __importDefault(require("./no-direct-capability-api"));
 const require_scroll_reveal_hook_1 = __importDefault(require("./require-scroll-reveal-hook"));
+const require_number_wrapped_count_1 = __importDefault(require("./require-number-wrapped-count"));
+const require_shared_response_type_1 = __importDefault(require("./require-shared-response-type"));
+const require_shared_request_type_1 = __importDefault(require("./require-shared-request-type"));
+const no_welcome_index_route_1 = __importDefault(require("./no-welcome-index-route"));
+const require_index_route_1 = __importDefault(require("./require-index-route"));
+const no_duplicate_route_component_1 = __importDefault(require("./no-duplicate-route-component"));
 exports.customRules = {
     'no-nested-styled-jsx': no_nested_styled_jsx_1.default,
     'require-app-container': require_app_container_1.default,
     'no-direct-capability-api': no_direct_capability_api_1.default,
     'require-scroll-reveal-hook': require_scroll_reveal_hook_1.default,
+    'require-number-wrapped-count': require_number_wrapped_count_1.default,
+    'require-shared-response-type': require_shared_response_type_1.default,
+    'require-shared-request-type': require_shared_request_type_1.default,
+    'no-welcome-index-route': no_welcome_index_route_1.default,
+    'require-index-route': require_index_route_1.default,
+    'no-duplicate-route-component': no_duplicate_route_component_1.default,
 };

package/lib/custom-eslint-rules/no-duplicate-route-component.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ESLint rule to disallow duplicate component usage across Route elements within a <Routes>.
+ *
+ * This rule enforces that within any <Routes> element, each JSX component used as the
+ * `element` prop of a <Route> must be unique. Reusing the same component across
+ * multiple routes leads to confusing routing logic.
+ *
+ * Skips:
+ * - Routes without an `element` attribute
+ * - element values that are not JSX elements (e.g., variables, null, false)
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export default rule;

package/lib/custom-eslint-rules/no-duplicate-route-component.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// Serialize a JSXIdentifier or JSXMemberExpression to a stable string key.
+// e.g. JSXIdentifier "Home" → "Home"
+//      JSXMemberExpression "Pages.Home" → "Pages.Home"
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function getJSXName(node) {
+    if (!node)
+        return null;
+    if (node.type === 'JSXIdentifier')
+        return node.name;
+    if (node.type === 'JSXMemberExpression') {
+        const obj = getJSXName(node.object);
+        const prop = node.property?.name;
+        if (obj && prop)
+            return `${obj}.${prop}`;
+    }
+    return null;
+}
+const rule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow the same component being used as the element of multiple Routes within a <Routes>',
+            category: 'Best Practices',
+            recommended: true,
+        },
+        messages: {
+            duplicateRouteComponent: "Component <{{componentName}} /> is already used in another Route's element. Remove the duplicate—keep the index Route if present.",
+        },
+        schema: [],
+    },
+    create(context) {
+        // Stack of seen-component maps, one entry per nested <Routes>
+        const routesStack = [];
+        return {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            JSXElement(node) {
+                const tagName = node.openingElement?.name?.name;
+                if (tagName === 'Routes') {
+                    routesStack.push(new Map());
+                    return;
+                }
+                if (tagName !== 'Route')
+                    return;
+                if (routesStack.length === 0)
+                    return;
+                const seenComponents = routesStack[routesStack.length - 1];
+                const attributes = node.openingElement?.attributes || [];
+                // Find the `element` attribute
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const elementAttr = attributes.find(
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                (attr) => attr.type === 'JSXAttribute' && attr.name?.name === 'element');
+                if (!elementAttr)
+                    return;
+                // element value must be a JSXExpressionContainer containing a JSXElement
+                const attrValue = elementAttr.value;
+                if (attrValue?.type !== 'JSXExpressionContainer')
+                    return;
+                const expression = attrValue.expression;
+                if (!expression || expression.type !== 'JSXElement')
+                    return;
+                const componentName = getJSXName(expression.openingElement?.name);
+                if (!componentName)
+                    return;
+                if (seenComponents.has(componentName)) {
+                    context.report({
+                        node: elementAttr,
+                        messageId: 'duplicateRouteComponent',
+                        data: { componentName },
+                    });
+                }
+                else {
+                    seenComponents.set(componentName, elementAttr);
+                }
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            'JSXElement:exit'(node) {
+                if (node.openingElement?.name?.name === 'Routes') {
+                    routesStack.pop();
+                }
+            },
+        };
+    },
+};
+exports.default = rule;

package/lib/custom-eslint-rules/no-welcome-index-route.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ESLint rule to disallow Welcome or PagePlaceholder components as the default home page route.
+ *
+ * This rule enforces that the first-level index route (the actual home page at "/")
+ * should use an actual page component rather than placeholder components from the framework.
+ *
+ * Only checks the first-level index route nested directly under a parent Route (typically Layout).
+ * Only flags Welcome/PagePlaceholder if they are imported from @lark-apaas/client-toolkit.
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export default rule;

package/lib/custom-eslint-rules/no-welcome-index-route.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const rule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow Welcome or PagePlaceholder from @lark-apaas/client-toolkit as the default home page route element',
+            category: 'Best Practices',
+            recommended: true,
+        },
+        messages: {
+            noWelcomeIndex: 'Index route should not use {{componentName}} from @lark-apaas/client-toolkit as the element. Please create and use your own home page component (e.g., HomePage, Dashboard).',
+        },
+        schema: [],
+    },
+    create(context) {
+        // Track imports from @lark-apaas/client-toolkit
+        const toolkitImports = new Set();
+        return {
+            ImportDeclaration(node) {
+                const importNode = node;
+                const source = importNode.source?.value;
+                // Check if importing from @lark-apaas/client-toolkit (any subpath)
+                if (typeof source === 'string' &&
+                    source.startsWith('@lark-apaas/client-toolkit')) {
+                    // Collect all imported names
+                    importNode.specifiers?.forEach(specifier => {
+                        if (specifier.type === 'ImportSpecifier' &&
+                            specifier.imported?.name) {
+                            toolkitImports.add(specifier.imported.name);
+                        }
+                    });
+                }
+            },
+            JSXElement(node) {
+                const element = node;
+                const openingElement = element.openingElement;
+                if (!openingElement)
+                    return;
+                const elementName = openingElement.name;
+                // Check if this is a <Route> element
+                if (elementName.type !== 'JSXIdentifier' ||
+                    elementName.name !== 'Route') {
+                    return;
+                }
+                // Check if it has an index prop that is truthy
+                const indexAttr = openingElement.attributes.find(attr => attr.type === 'JSXAttribute' &&
+                    attr.name?.type === 'JSXIdentifier' &&
+                    attr.name?.name === 'index');
+                // If no index attribute, skip this route
+                if (!indexAttr) {
+                    return;
+                }
+                // Check if index={false} explicitly
+                const indexValue = indexAttr.value;
+                if (indexValue?.type === 'JSXExpressionContainer' &&
+                    indexValue.expression?.type === 'Literal' &&
+                    indexValue.expression.value === false) {
+                    return;
+                }
+                // Check if this is a first-level index route (nested under exactly one parent Route)
+                // The structure should be: <Routes> -> <Route element={<Layout />}> -> <Route index>
+                let routeParentCount = 0;
+                let current = element.parent;
+                while (current) {
+                    if (current.type === 'JSXElement') {
+                        const currentElement = current;
+                        const currentOpeningElement = currentElement.openingElement;
+                        const currentElementName = currentOpeningElement?.name;
+                        if (currentElementName?.type === 'JSXIdentifier' &&
+                            currentElementName.name === 'Route') {
+                            routeParentCount++;
+                        }
+                        else if (currentElementName?.type === 'JSXIdentifier' &&
+                            currentElementName.name === 'Routes') {
+                            // Stop when we reach Routes
+                            break;
+                        }
+                    }
+                    current = current.parent;
+                }
+                // Only check if this is a first-level route (exactly 1 parent Route)
+                // This corresponds to the default home page pattern:
+                // <Routes><Route element={<Layout />}><Route index /></Route></Routes>
+                if (routeParentCount !== 1) {
+                    return;
+                }
+                // Find the element prop
+                const elementProp = openingElement.attributes.find(attr => attr.type === 'JSXAttribute' &&
+                    attr.name?.type === 'JSXIdentifier' &&
+                    attr.name?.name === 'element');
+                if (!elementProp) {
+                    return;
+                }
+                // Check if the element prop value is a JSXExpressionContainer with a JSXElement
+                const propValue = elementProp.value;
+                if (propValue?.type === 'JSXExpressionContainer' &&
+                    propValue.expression?.type === 'JSXElement') {
+                    const jsxElement = propValue.expression;
+                    const jsxOpeningElement = jsxElement.openingElement;
+                    const jsxElementName = jsxOpeningElement?.name;
+                    // Check if the component name is Welcome or PagePlaceholder
+                    if (jsxElementName?.type === 'JSXIdentifier' &&
+                        (jsxElementName.name === 'Welcome' ||
+                            jsxElementName.name === 'PagePlaceholder')) {
+                        const componentName = jsxElementName.name;
+                        // Only report if this component was imported from @lark-apaas/client-toolkit
+                        if (toolkitImports.has(componentName)) {
+                            context.report({
+                                node: elementProp,
+                                messageId: 'noWelcomeIndex',
+                                data: {
+                                    componentName,
+                                },
+                            });
+                        }
+                    }
+                }
+            },
+        };
+    },
+};
+exports.default = rule;

package/lib/custom-eslint-rules/require-index-route.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ESLint rule to require a default index route in RoutesComponent.
+ *
+ * This rule enforces that the RoutesComponent must have a first-level index route
+ * to handle the default "/" path. This ensures users don't see a 404 when visiting
+ * the application root.
+ *
+ * Valid configurations:
+ * 1. <Route index element={...} /> (first-level, nested under one parent Route)
+ * 2. <Route path="/" element={...} /> (first-level or top-level)
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export default rule;

package/lib/custom-eslint-rules/require-index-route.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const rule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require a default index route in RoutesComponent to handle the root path',
+            category: 'Best Practices',
+            recommended: true,
+        },
+        messages: {
+            missingIndexRoute: 'RoutesComponent is missing a default home page route. Add either:\n  - <Route index element={<HomePage />} /> (nested under Layout)\n  - <Route path="/" element={<HomePage />} /> (at any level)',
+        },
+        schema: [],
+    },
+    create(context) {
+        let inRoutesComponent = false;
+        let hasDefaultRoute = false;
+        let routeDepth = 0;
+        return {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            VariableDeclarator(node) {
+                // Check if this is RoutesComponent
+                if (node.id?.name === 'RoutesComponent') {
+                    inRoutesComponent = true;
+                    hasDefaultRoute = false;
+                    routeDepth = 0;
+                }
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            'VariableDeclarator:exit'(node) {
+                if (node.id?.name === 'RoutesComponent') {
+                    if (!hasDefaultRoute) {
+                        context.report({
+                            node,
+                            messageId: 'missingIndexRoute',
+                        });
+                    }
+                    inRoutesComponent = false;
+                }
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            JSXElement(node) {
+                if (!inRoutesComponent)
+                    return;
+                const elementName = node.openingElement?.name?.name;
+                // Track Route depth
+                if (elementName === 'Route') {
+                    routeDepth++;
+                    // Only check first-level routes (depth 1 or 2)
+                    // depth 1: <Routes><Route index /></Routes>
+                    // depth 2: <Routes><Route><Route index /></Route></Routes>
+                    if (routeDepth <= 2) {
+                        const attributes = node.openingElement?.attributes || [];
+                        // Check for index attribute
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const indexAttr = attributes.find((attr) => attr.type === 'JSXAttribute' && attr.name?.name === 'index');
+                        if (indexAttr) {
+                            // Make sure it's not index={false}
+                            const isIndexFalse = indexAttr.value?.type === 'JSXExpressionContainer' &&
+                                indexAttr.value.expression?.type === 'Literal' &&
+                                indexAttr.value.expression.value === false;
+                            if (!isIndexFalse) {
+                                hasDefaultRoute = true;
+                            }
+                        }
+                        // Check for path="/"
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const pathAttr = attributes.find((attr) => attr.type === 'JSXAttribute' && attr.name?.name === 'path');
+                        if (pathAttr) {
+                            const value = pathAttr.value;
+                            // Handle path="/"
+                            if (value?.type === 'Literal' && value.value === '/') {
+                                hasDefaultRoute = true;
+                            }
+                            // Handle path={"/"}
+                            if (value?.type === 'JSXExpressionContainer' &&
+                                value.expression?.type === 'Literal' &&
+                                value.expression.value === '/') {
+                                hasDefaultRoute = true;
+                            }
+                        }
+                    }
+                }
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            'JSXElement:exit'(node) {
+                if (!inRoutesComponent)
+                    return;
+                const elementName = node.openingElement?.name?.name;
+                if (elementName === 'Route') {
+                    routeDepth--;
+                }
+            },
+        };
+    },
+};
+exports.default = rule;

package/lib/custom-eslint-rules/require-number-wrapped-count.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ESLint 规则：Drizzle count() 返回值必须用 Number(...) 包裹
+ *
+ * postgres-js 驱动下 Drizzle 的 count() 返回 string 而非 number，
+ * 不包裹 Number() 会导致类型不符预期。
+ *
+ * 通过 import 追踪确认 count 来自 drizzle-orm，避免误匹配其他 count 函数。
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export default rule;

package/lib/custom-eslint-rules/require-number-wrapped-count.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const rule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require Drizzle count() to be wrapped with Number()',
+            category: 'Possible Errors',
+            recommended: true,
+        },
+        schema: [],
+        messages: {
+            unwrappedCount: 'Drizzle count() returns string in postgres-js. Wrap with Number(count(...)) to get a numeric value.',
+        },
+    },
+    create(context) {
+        // 追踪从 drizzle-orm 导入的 count 标识符名
+        const drizzleCountNames = new Set();
+        return {
+            // 收集 import { count } from 'drizzle-orm' 或 import { count as x } from 'drizzle-orm'
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            ImportDeclaration(node) {
+                if (node.source.value !== 'drizzle-orm' &&
+                    !node.source.value.startsWith('drizzle-orm/')) {
+                    return;
+                }
+                for (const specifier of node.specifiers) {
+                    if (specifier.type === 'ImportSpecifier' &&
+                        specifier.imported.name === 'count') {
+                        drizzleCountNames.add(specifier.local.name);
+                    }
+                }
+            },
+            // 检查 count() 调用是否被 Number(...) 包裹
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            CallExpression(node) {
+                // 是否是 count(...) 调用
+                if (node.callee.type !== 'Identifier' ||
+                    !drizzleCountNames.has(node.callee.name)) {
+                    return;
+                }
+                // 检查父节点是否是 Number(count(...))
+                const parent = node.parent;
+                if (parent &&
+                    parent.type === 'CallExpression' &&
+                    parent.callee.type === 'Identifier' &&
+                    parent.callee.name === 'Number') {
+                    return; // 已包裹
+                }
+                // 检查是否在对象属性值位置且 key 是 count（如 { count: count() }）
+                // 这种场景下 count() 是 select 的字段定义，不是直接赋值，跳过
+                if (parent &&
+                    parent.type === 'Property' &&
+                    parent.value === node) {
+                    // 但如果整个 select result 后来被直接当 number 用，那是使用侧的问题
+                    // 这里只检查 count() 的直接调用位置
+                    return;
+                }
+                context.report({
+                    node,
+                    messageId: 'unwrappedCount',
+                });
+            },
+        };
+    },
+};
+exports.default = rule;

package/lib/custom-eslint-rules/require-shared-request-type.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ESLint 规则：客户端 HTTP 调用必须使用 shared/ 目录下定义的响应类型
+ *
+ * 强制前端 API 调用声明响应类型，且类型必须从 shared/ 导入，
+ * 让前后端共享类型定义，避免类型不一致。
+ *
+ * 仅检查调用自有后端接口（URL 以 /api/ 开头）的请求。
+ * 三方接口（绝对 URL、其他前缀）跳过，不强制 shared 类型。
+ *
+ * 检查逻辑（纯 AST）：
+ * 1. 匹配 axiosForBackend 的 HTTP 调用
+ * 2. 检查第一个参数 URL 是否以 /api/ 开头（自有接口）
+ * 3. 检查调用是否有泛型参数，且类型从 shared/ 路径导入
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export default rule;

package/lib/custom-eslint-rules/require-shared-request-type.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// 匹配的 HTTP 客户端方法
+const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'request']);
+// 只匹配 axiosForBackend —— 前端统一使用的 HTTP 客户端
+const HTTP_CLIENTS = new Set(['axiosForBackend']);
+const rule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require HTTP calls to use response types defined in shared/',
+            category: 'Possible Errors',
+            recommended: true,
+        },
+        schema: [],
+        messages: {
+            missingResponseType: 'HTTP call must declare a response type via generic parameter (e.g. apiClient.get<MyResponse>(...)). Define the type in shared/api.interface.ts.',
+            responseTypeNotFromShared: 'HTTP response type "{{typeName}}" must be defined in shared/api.interface.ts. Import it from @shared/ or shared/ path.',
+        },
+    },
+    create(context) {
+        // 追踪从 shared/ 路径导入的类型名
+        const sharedTypeNames = new Set();
+        return {
+            // 收集从 shared/ 导入的类型名
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            ImportDeclaration(node) {
+                const source = node.source.value;
+                if (source.includes('shared/') ||
+                    source.startsWith('@shared/')) {
+                    for (const specifier of node.specifiers) {
+                        if (specifier.local?.name) {
+                            sharedTypeNames.add(specifier.local.name);
+                        }
+                    }
+                }
+            },
+            // 检查 HTTP 调用
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            CallExpression(node) {
+                if (!isHttpCall(node))
+                    return;
+                // 只检查自有后端接口（URL 以 /api/ 开头），三方接口跳过
+                if (!isOwnApiCall(node))
+                    return;
+                // 检查是否有泛型参数 axiosForBackend.get<Type>(...)
+                const typeArgs = node.typeArguments || node.typeParameters;
+                if (!typeArgs || typeArgs.params.length === 0) {
+                    context.report({
+                        node: node.callee,
+                        messageId: 'missingResponseType',
+                    });
+                    return;
+                }
+                // 提取第一个泛型参数的类型名
+                const typeParam = typeArgs.params[0];
+                const typeName = extractTypeName(typeParam);
+                if (!typeName)
+                    return; // 基本类型或无法解析，跳过
+                // 检查类型是否从 shared/ 导入
+                if (!sharedTypeNames.has(typeName)) {
+                    context.report({
+                        node: typeParam,
+                        messageId: 'responseTypeNotFromShared',
+                        data: { typeName },
+                    });
+                }
+            },
+        };
+    },
+};
+/**
+ * 判断是否是 HTTP 调用：
+ * - axios.get/post/...()
+ * - apiClient.get/post/...()
+ * - fetch() (全局)
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isHttpCall(node) {
+    const callee = node.callee;
+    // axios.get(url) / apiClient.post(url) 等
+    // 只匹配已知的 HTTP 客户端对象,避免误匹配业务方法
+    // 不匹配 fetch()（原生 fetch 不支持泛型参数）
+    if (callee.type === 'MemberExpression' &&
+        callee.object.type === 'Identifier' &&
+        callee.property.type === 'Identifier' &&
+        HTTP_CLIENTS.has(callee.object.name) &&
+        HTTP_METHODS.has(callee.property.name)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * 判断请求是否是自有后端接口（URL 以 /api/ 开头）。
+ * 三方接口（绝对 URL https://...、其他前缀 /open-api/... 等）跳过。
+ * 无法解析 URL（变量、模板表达式）时保守跳过，宁漏勿杀。
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isOwnApiCall(node) {
+    const firstArg = node.arguments?.[0];
+    if (!firstArg)
+        return false;
+    // 字符串字面量: '/api/users'
+    if (firstArg.type === 'Literal' && typeof firstArg.value === 'string') {
+        return firstArg.value.startsWith('/api/') || firstArg.value.startsWith('api/');
+    }
+    // 模板字面量无表达式: `/api/users`
+    if (firstArg.type === 'TemplateLiteral' && firstArg.expressions.length === 0) {
+        const raw = firstArg.quasis[0]?.value?.raw || '';
+        return raw.startsWith('/api/') || raw.startsWith('api/');
+    }
+    // 模板字面量有表达式: `/api/users/${id}` — 检查开头部分
+    if (firstArg.type === 'TemplateLiteral' && firstArg.quasis.length > 0) {
+        const raw = firstArg.quasis[0]?.value?.raw || '';
+        return raw.startsWith('/api/') || raw.startsWith('api/');
+    }
+    // 变量或其他动态表达式 — 无法判断，保守跳过
+    return false;
+}
+/**
+ * 从类型参数 AST 中提取主要类型名。
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractTypeName(typeNode) {
+    // SomeType
+    if (typeNode.type === 'TSTypeReference' && typeNode.typeName?.type === 'Identifier') {
+        return typeNode.typeName.name;
+    }
+    // SomeType[]
+    if (typeNode.type === 'TSArrayType') {
+        return extractTypeName(typeNode.elementType);
+    }
+    // 基本类型 → 跳过
+    if (typeNode.type === 'TSVoidKeyword' || typeNode.type === 'TSStringKeyword' ||
+        typeNode.type === 'TSNumberKeyword' || typeNode.type === 'TSBooleanKeyword' ||
+        typeNode.type === 'TSAnyKeyword') {
+        return null;
+    }
+    return null;
+}
+exports.default = rule;

package/lib/custom-eslint-rules/require-shared-response-type.d.ts

@@ -0,0 +1,15 @@
+/**
+ * ESLint 规则：Controller 路由方法的返回类型必须定义在 shared/ 目录下
+ *
+ * 强制 agent 把 Controller 方法的返回类型写到 shared/api.interface.ts，
+ * 让前后端共享类型定义，避免类型不一致。
+ *
+ * 检查逻辑（纯 AST，不需要 TypeChecker）：
+ * 1. 找到有 @Controller 装饰器的 class
+ * 2. 找到有 @Get/@Post/@Put/@Patch/@Delete 装饰器的方法
+ * 3. 检查方法是否有显式返回类型注解
+ * 4. 如果有，追踪类型名是否通过 import 从 shared/ 路径导入
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export default rule;

package/lib/custom-eslint-rules/require-shared-response-type.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const HTTP_DECORATORS = new Set(['Get', 'Post', 'Put', 'Patch', 'Delete']);
+const rule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require Controller route methods to use return types defined in shared/',
+            category: 'Possible Errors',
+            recommended: true,
+        },
+        schema: [],
+        messages: {
+            missingReturnType: 'Controller route method must have an explicit return type annotation.',
+            returnTypeNotFromShared: 'Controller return type "{{typeName}}" must be defined in shared/api.interface.ts. Import it from @shared/ or shared/ path.',
+        },
+    },
+    create(context) {
+        // 追踪从 shared/ 路径导入的类型名
+        const sharedTypeNames = new Set();
+        return {
+            // 收集从 shared/ 导入的类型名
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            ImportDeclaration(node) {
+                const source = node.source.value;
+                if (source.includes('shared/') ||
+                    source.startsWith('@shared/')) {
+                    for (const specifier of node.specifiers) {
+                        if (specifier.local?.name) {
+                            sharedTypeNames.add(specifier.local.name);
+                        }
+                    }
+                }
+            },
+            // 检查 Controller class 的路由方法
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            MethodDefinition(node) {
+                // 检查方法是否有 HTTP 装饰器
+                const decorators = node.decorators;
+                if (!decorators || decorators.length === 0)
+                    return;
+                const hasHttpDecorator = decorators.some((d) => {
+                    const expr = d.expression;
+                    // @Get() / @Post() 等
+                    if (expr.type === 'CallExpression' && expr.callee.type === 'Identifier') {
+                        return HTTP_DECORATORS.has(expr.callee.name);
+                    }
+                    // @Get (无括号,不常见但合法)
+                    if (expr.type === 'Identifier') {
+                        return HTTP_DECORATORS.has(expr.name);
+                    }
+                    return false;
+                });
+                if (!hasHttpDecorator)
+                    return;
+                // 检查父节点是否是 @Controller 装饰的 class
+                const classNode = node.parent?.parent;
+                if (!classNode || classNode.type !== 'ClassDeclaration')
+                    return;
+                const classDecorators = classNode.decorators;
+                if (!classDecorators)
+                    return;
+                const hasControllerDecorator = classDecorators.some((d) => {
+                    const expr = d.expression;
+                    if (expr.type === 'CallExpression' && expr.callee.type === 'Identifier') {
+                        return expr.callee.name === 'Controller';
+                    }
+                    if (expr.type === 'Identifier') {
+                        return expr.name === 'Controller';
+                    }
+                    return false;
+                });
+                if (!hasControllerDecorator)
+                    return;
+                // 检查方法是否有显式返回类型
+                const returnType = node.value?.returnType?.typeAnnotation;
+                if (!returnType) {
+                    context.report({
+                        node: node.key,
+                        messageId: 'missingReturnType',
+                    });
+                    return;
+                }
+                // 提取返回类型名（处理 Promise<T> 的情况）
+                const typeName = extractTypeName(returnType);
+                if (!typeName)
+                    return; // 无法解析的复杂类型，跳过
+                // 检查类型是否从 shared/ 导入
+                if (!sharedTypeNames.has(typeName)) {
+                    context.report({
+                        node: node.key,
+                        messageId: 'returnTypeNotFromShared',
+                        data: { typeName },
+                    });
+                }
+            },
+        };
+    },
+};
+/**
+ * 从返回类型 AST 中提取主要类型名。
+ * 处理：Promise<T> → T, T → T, T[] → T
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractTypeName(typeNode) {
+    // Promise<SomeType> → 提取 SomeType
+    if (typeNode.type === 'TSTypeReference' &&
+        typeNode.typeName?.name === 'Promise' &&
+        typeNode.typeArguments?.params?.length === 1) {
+        return extractTypeName(typeNode.typeArguments.params[0]);
+    }
+    // SomeType → 直接返回名字
+    if (typeNode.type === 'TSTypeReference' && typeNode.typeName?.type === 'Identifier') {
+        return typeNode.typeName.name;
+    }
+    // SomeType[] → 提取 SomeType
+    if (typeNode.type === 'TSArrayType') {
+        return extractTypeName(typeNode.elementType);
+    }
+    // 基本类型 (string, number, void, boolean) → 跳过检查
+    if (typeNode.type === 'TSVoidKeyword' || typeNode.type === 'TSStringKeyword' ||
+        typeNode.type === 'TSNumberKeyword' || typeNode.type === 'TSBooleanKeyword' ||
+        typeNode.type === 'TSAnyKeyword') {
+        return null;
+    }
+    return null;
+}
+exports.default = rule;

package/lib/recommend/eslint/eslint-client.d.ts

@@ -19,6 +19,12 @@ declare const _default: {
                 'require-app-container': import("eslint").Rule.RuleModule;
                 'no-direct-capability-api': import("eslint").Rule.RuleModule;
                 'require-scroll-reveal-hook': import("eslint").Rule.RuleModule;
+                'require-number-wrapped-count': import("eslint").Rule.RuleModule;
+                'require-shared-response-type': import("eslint").Rule.RuleModule;
+                'require-shared-request-type': import("eslint").Rule.RuleModule;
+                'no-welcome-index-route': import("eslint").Rule.RuleModule;
+                'require-index-route': import("eslint").Rule.RuleModule;
+                'no-duplicate-route-component': import("eslint").Rule.RuleModule;
             };
         };
     };

package/lib/recommend/eslint/index.d.ts

@@ -22,6 +22,12 @@ export declare const eslintPresets: {
                     'require-app-container': import("eslint").Rule.RuleModule;
                     'no-direct-capability-api': import("eslint").Rule.RuleModule;
                     'require-scroll-reveal-hook': import("eslint").Rule.RuleModule;
+                    'require-number-wrapped-count': import("eslint").Rule.RuleModule;
+                    'require-shared-response-type': import("eslint").Rule.RuleModule;
+                    'require-shared-request-type': import("eslint").Rule.RuleModule;
+                    'no-welcome-index-route': import("eslint").Rule.RuleModule;
+                    'require-index-route': import("eslint").Rule.RuleModule;
+                    'no-duplicate-route-component': import("eslint").Rule.RuleModule;
                 };
             };
         };

package/lib/simple/recommend/eslint/eslint-client.d.ts

@@ -15,14 +15,6 @@ declare const _default: ({
         globals: any;
     };
     plugins: {
-        '@lark-apaas': {
-            rules: {
-                'no-nested-styled-jsx': import("eslint").Rule.RuleModule;
-                'require-app-container': import("eslint").Rule.RuleModule;
-                'no-direct-capability-api': import("eslint").Rule.RuleModule;
-                'require-scroll-reveal-hook': import("eslint").Rule.RuleModule;
-            };
-        };
         'react-hooks': any;
         import: any;
     };
@@ -45,6 +37,9 @@ declare const _default: ({
             selector: string;
             message: string;
         })[];
+        '@lark-apaas/no-welcome-index-route': string;
+        '@lark-apaas/require-index-route': string;
+        '@lark-apaas/no-duplicate-route-component': string;
     };
 } | null)[];
 export default _default;

package/lib/simple/recommend/eslint/eslint-client.js

@@ -7,7 +7,6 @@ const tseslint = require('typescript-eslint');
 const importPlugin = require('eslint-plugin-import');
 const fs = require('fs');
 const path = require('path');
-const custom_eslint_rules_1 = require("../../../custom-eslint-rules");
 // 检查是否启用宽松 lint 模式
 const isLooseMode = process.env.FORCE_FRAMEWORK_LINT_LOOSE_MODE === 'true';
 // 读取项目 package.json 中的 flags 配置
@@ -114,10 +113,12 @@ const strictSyntaxRules = [
         selector: "CallExpression[callee.name='confirm']",
     },
 ];
-const looseSpecificPlugins = {
-    '@lark-apaas': { rules: custom_eslint_rules_1.customRules },
-};
-// 宽松模式下覆盖的规则
+// 宽松模式专用，请勿删除
+// 注意：@lark-apaas 插件在 index.ts 统一注册，这里不再重复
+const looseSpecificPlugins = {};
+// 宽松模式专用，请勿删除
+const looseSpecificRules = {};
+// 宽松模式下覆盖的规则（关闭非关键规则）
 const looseOverrideRules = isLooseMode
     ? {
         '@typescript-eslint/no-unsafe-function-type': 'off',
@@ -168,6 +169,8 @@ const baseConfig = {
         // 平台规则：禁止直接调用 capability 内部 API，应使用 capabilityClient
         '@lark-apaas/no-direct-capability-api': 'error',
         '@lark-apaas/no-nested-styled-jsx': 'error',
+        // 自定义规则：HTTP 调用响应类型必须定义在 shared/
+        '@lark-apaas/require-shared-request-type': 'error',
         // TypeScript 规则
         '@typescript-eslint/no-unused-vars': 'off', // 未使用变量检查关闭
         '@typescript-eslint/no-explicit-any': 'off', // 允许使用 any 类型
@@ -201,6 +204,12 @@ const baseConfig = {
                         message: "Importing from 'next/link' is prohibited. Please use the `Link` component from 'react-router-dom' for navigation.",
                     },
                 ],
+                patterns: [
+                    {
+                        group: ['antd/es/table', 'antd/es/table/*', 'antd/lib/table', 'antd/lib/table/*'],
+                        message: "Importing Table from 'antd' is prohibited. Please use '@lark-apaas/client-toolkit/antd-table' instead.",
+                    },
+                ],
             },
         ],
         'no-restricted-syntax': [
@@ -209,6 +218,8 @@ const baseConfig = {
             // 注意：严格模式的 strictSyntaxRules 仍然应用于所有文件
             ...(isLooseMode ? [] : strictSyntaxRules),
         ],
+        // 宽松模式专用规则
+        ...looseSpecificRules,
         // 宽松模式下覆盖上述规则
         ...looseOverrideRules,
     },
@@ -225,6 +236,9 @@ const appTsxConfig = isLooseMode
                 ...baseSyntaxRules,
                 ...exports.looseRestrictSyntaxRules,
             ],
+            '@lark-apaas/no-welcome-index-route': 'error',
+            '@lark-apaas/require-index-route': 'error',
+            '@lark-apaas/no-duplicate-route-component': 'error',
         },
     }
     : null;

package/lib/simple/recommend/eslint/eslint-server.d.ts

@@ -52,6 +52,12 @@ declare const _default: {
         '@darraghor/nestjs-typed/api-method-should-specify-api-operation': string;
         '@darraghor/nestjs-typed/api-enum-property-best-practices': string;
         '@darraghor/nestjs-typed/all-properties-are-whitelisted': string;
+        '@lark-apaas/require-number-wrapped-count': string;
+        '@lark-apaas/require-shared-response-type': string;
+        'no-restricted-syntax': (string | {
+            selector: string;
+            message: string;
+        })[];
     };
 };
 export default _default;

package/lib/simple/recommend/eslint/eslint-server.js

@@ -73,5 +73,17 @@ exports.default = {
         '@darraghor/nestjs-typed/api-method-should-specify-api-operation': 'off',
         '@darraghor/nestjs-typed/api-enum-property-best-practices': 'off',
         '@darraghor/nestjs-typed/all-properties-are-whitelisted': 'off',
+        // 自定义规则：Drizzle count() 必须 Number() 包裹
+        '@lark-apaas/require-number-wrapped-count': 'error',
+        // 自定义规则：Controller 返回类型必须定义在 shared/
+        '@lark-apaas/require-shared-response-type': 'error',
+        // Drizzle ORM 规则
+        'no-restricted-syntax': [
+            'error',
+            {
+                selector: "CallExpression[callee.property.name=/^(values|set)$/] Property[key.name=/^(_created_at|_updated_at|_created_by|_updated_by)$/]",
+                message: 'Audit columns (_created_at/_updated_at/_created_by/_updated_by) are auto-populated by the platform. Do not set them in .values() or .set() calls.',
+            },
+        ],
     },
 };

package/lib/simple/recommend/eslint/index.d.ts

@@ -14,14 +14,6 @@ export declare const eslintPresets: {
             globals: any;
         };
         plugins: {
-            '@lark-apaas': {
-                rules: {
-                    'no-nested-styled-jsx': import("eslint").Rule.RuleModule;
-                    'require-app-container': import("eslint").Rule.RuleModule;
-                    'no-direct-capability-api': import("eslint").Rule.RuleModule;
-                    'require-scroll-reveal-hook': import("eslint").Rule.RuleModule;
-                };
-            };
             'react-hooks': any;
             import: any;
         };
@@ -44,11 +36,50 @@ export declare const eslintPresets: {
                 selector: string;
                 message: string;
             })[];
+            '@lark-apaas/no-welcome-index-route': string;
+            '@lark-apaas/require-index-route': string;
+            '@lark-apaas/no-duplicate-route-component': string;
         };
     } | null)[] | {
+        name: string;
+        plugins: {
+            '@lark-apaas': {
+                rules: {
+                    'no-nested-styled-jsx': import("eslint").Rule.RuleModule;
+                    'require-app-container': import("eslint").Rule.RuleModule;
+                    'no-direct-capability-api': import("eslint").Rule.RuleModule;
+                    'require-scroll-reveal-hook': import("eslint").Rule.RuleModule;
+                    'require-number-wrapped-count': import("eslint").Rule.RuleModule;
+                    'require-shared-response-type': import("eslint").Rule.RuleModule;
+                    'require-shared-request-type': import("eslint").Rule.RuleModule;
+                    'no-welcome-index-route': import("eslint").Rule.RuleModule;
+                    'require-index-route': import("eslint").Rule.RuleModule;
+                    'no-duplicate-route-component': import("eslint").Rule.RuleModule;
+                };
+            };
+        };
+    } | {
         ignores: string[];
     })[];
     server: ({
         readonly rules: Readonly<import("eslint").Linter.RulesRecord>;
-    } | import("typescript-eslint/dist/compatibility-types").CompatibleConfig)[];
+    } | import("typescript-eslint/dist/compatibility-types").CompatibleConfig | {
+        name: string;
+        plugins: {
+            '@lark-apaas': {
+                rules: {
+                    'no-nested-styled-jsx': import("eslint").Rule.RuleModule;
+                    'require-app-container': import("eslint").Rule.RuleModule;
+                    'no-direct-capability-api': import("eslint").Rule.RuleModule;
+                    'require-scroll-reveal-hook': import("eslint").Rule.RuleModule;
+                    'require-number-wrapped-count': import("eslint").Rule.RuleModule;
+                    'require-shared-response-type': import("eslint").Rule.RuleModule;
+                    'require-shared-request-type': import("eslint").Rule.RuleModule;
+                    'no-welcome-index-route': import("eslint").Rule.RuleModule;
+                    'require-index-route': import("eslint").Rule.RuleModule;
+                    'no-duplicate-route-component': import("eslint").Rule.RuleModule;
+                };
+            };
+        };
+    })[];
 };

package/lib/simple/recommend/eslint/index.js

@@ -9,6 +9,7 @@ const eslint_server_1 = __importDefault(require("./eslint-server"));
 const js_1 = __importDefault(require("@eslint/js"));
 const typescript_eslint_1 = __importDefault(require("typescript-eslint"));
 const eslint_plugin_nestjs_typed_1 = __importDefault(require("@darraghor/eslint-plugin-nestjs-typed"));
+const custom_eslint_rules_1 = require("../../../custom-eslint-rules");
 const testFileIgnorePatterns = [
     '**/__tests__/**',
     '**/*.test.js',
@@ -22,6 +23,13 @@ const testFileIgnorePatterns = [
 ];
 const globalIgnoreServerPatterns = ['server/database/.introspect/**', ...testFileIgnorePatterns]; // 全局 eslint server ignore
 const globalIgnoreClientPatterns = ['dist', 'node_modules', 'client/src/api/gen', ...testFileIgnorePatterns]; // 全局 eslint client Ignore
+// @lark-apaas 插件只注册一次，client 和 server config 共享
+const larkApaasPlugin = {
+    name: '@lark-apaas/plugin-registration',
+    plugins: {
+        '@lark-apaas': { rules: custom_eslint_rules_1.customRules },
+    },
+};
 // 只导出纯净的规则配置，不包含基础配置
 // 用户需要在项目配置中自己添加基础配置（eslintJs, tseslint, nestjs 等）
 exports.eslintPresets = {
@@ -29,6 +37,7 @@ exports.eslintPresets = {
         { ignores: globalIgnoreClientPatterns },
         js_1.default.configs.recommended,
         ...typescript_eslint_1.default.configs.recommended,
+        larkApaasPlugin,
         eslint_client_1.default
     ],
     server: [
@@ -36,6 +45,7 @@ exports.eslintPresets = {
         js_1.default.configs.recommended,
         ...typescript_eslint_1.default.configs.recommended,
         ...eslint_plugin_nestjs_typed_1.default.configs.flatRecommended,
+        larkApaasPlugin,
         eslint_server_1.default
     ],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/fullstack-presets",
-  "version": "1.1.14",
+  "version": "1.1.16",
   "files": [
     "lib"
   ],