befly 3.9.37 → 3.9.38

package/README.md

@@ -293,7 +293,7 @@ export const beflyConfig = { ... };
 
 - **`packages/core`** - Befly 核心框架包（发布到 npm）
 - **`packages/tpl`** - API 项目模板示例
-- **`packages/admin`** - 后台管理系统（Vue3 + TinyVue + 自动导入）
+- **`packages/admin`** - 后台管理系统（Vue3 + TDesign Vue Next + 自动导入）
 
 ## 🚀 快速启动
 

package/docs/api.md

@@ -999,7 +999,7 @@ import adminTable from '../../tables/admin.json';
 export default {
     name: '添加管理员',
     fields: adminTable,
-    required: ['username', 'password', 'roleId'],
+    required: ['username', 'password', 'roleCode'],
     handler: async (befly, ctx) => {
         // 检查用户名是否已存在
         const existing = await befly.db.getOne({
@@ -1014,11 +1014,10 @@ export default {
         // 查询角色信息
         const role = await befly.db.getOne({
             table: 'addon_admin_role',
-            where: { id: ctx.body.roleId },
-            columns: ['code']
+            where: { code: ctx.body.roleCode }
         });
 
-        if (!role?.code) {
+        if (!role) {
             return befly.tool.No('角色不存在');
         }
 
@@ -1032,7 +1031,6 @@ export default {
                 username: ctx.body.username,
                 password: hashedPassword,
                 nickname: ctx.body.nickname,
-                roleId: ctx.body.roleId,
                 roleCode: role.code
             }
         });

package/docs/database.md

@@ -153,7 +153,7 @@ export default {
     name: '用户列表',
     fields: {
         keyword: { name: '关键词', type: 'string', max: 50 },
-        roleId: { name: '角色ID', type: 'number' },
+        status: { name: '状态', type: 'number' },
         state: { name: '状态', type: 'number' }
     },
     handler: async (befly, ctx) => {
@@ -162,7 +162,7 @@ export default {
         const result = await befly.db.getList({
             table: 'user',
             where: {
-                roleId: ctx.body.roleId, // 未传时为 undefined，自动忽略
+                status: ctx.body.status, // 未传时为 undefined，自动忽略
                 state: ctx.body.state, // 未传时为 undefined，自动忽略
                 username$like: ctx.body.keyword ? `%${ctx.body.keyword}%` : undefined // 无关键词时忽略
             },
@@ -441,7 +441,7 @@ const userId = await befly.db.insData({
         username: 'john',
         email: 'john@example.com',
         password: hashedPassword,
-        roleId: 1
+        categoryId: 1
     }
 });
 // 返回新记录的 ID
@@ -502,7 +502,7 @@ const affected = await befly.db.updData({
 await befly.db.updData({
     table: 'user',
     data: { state: 2 },
-    where: { roleId: 5 }
+    where: { status: 5 }
 });
 ```
 
@@ -794,8 +794,8 @@ where: { id: 1 }
 // → WHERE id = 1
 
 // 多条件（AND）
-where: { state: 1, roleId: 2 }
-// → WHERE state = 1 AND role_id = 2
+where: { state: 1, status: 2 }
+// → WHERE state = 1 AND status = 2
 ```
 
 ### 比较操作符
@@ -842,9 +842,9 @@ where: {
 ```typescript
 // 显式 AND（通常不需要，多条件默认就是 AND）
 where: {
-    $and: [{ state: 1 }, { roleId: 2 }];
+    $and: [{ state: 1 }, { status: 2 }];
 }
-// → WHERE state = 1 AND role_id = 2
+// → WHERE state = 1 AND status = 2
 ```
 
 **组合使用**
@@ -867,9 +867,9 @@ where: {
 
 ```typescript
 where: {
-    roleId$in: [1, 2, 3];
+    categoryId$in: [1, 2, 3];
 }
-// → WHERE role_id IN (1, 2, 3)
+// → WHERE category_id IN (1, 2, 3)
 
 where: {
     status$in: ['pending', 'processing'];
@@ -1075,7 +1075,7 @@ export default {
     name: '用户列表',
     fields: {
         keyword: { name: '关键词', type: 'string', max: 50 },
-        roleId: { name: '角色ID', type: 'number' },
+        departmentId: { name: '部门ID', type: 'number' },
         page: Fields.page,
         limit: Fields.limit
     },
@@ -1087,9 +1087,9 @@ export default {
             where.$or = [{ username$like: `%${ctx.body.keyword}%` }, { nickname$like: `%${ctx.body.keyword}%` }, { email$like: `%${ctx.body.keyword}%` }];
         }
 
-        // 角色过滤
-        if (ctx.body.roleId) {
-            where.roleId = ctx.body.roleId;
+        // 部门过滤
+        if (ctx.body.departmentId) {
+            where.departmentId = ctx.body.departmentId;
         }
 
         const result = await befly.db.getList({

package/docs/table.md

@@ -184,8 +184,8 @@ interface FieldDefinition {
         "max": 150,
         "default": 0
     },
-    "roleId": {
-        "name": "角色ID",
+    "userId": {
+        "name": "用户ID",
         "type": "number",
         "min": 1,
         "index": true
@@ -287,8 +287,8 @@ interface FieldDefinition {
 
 ```json
 {
-    "roleId": {
-        "name": "角色ID",
+    "categoryId": {
+        "name": "分类ID",
         "type": "number",
         "index": true
     },
@@ -620,8 +620,8 @@ bun run sync:db --force
         "type": "string",
         "max": 500
     },
-    "roleId": {
-        "name": "角色ID",
+    "departmentId": {
+        "name": "部门ID",
         "type": "number",
         "min": 1,
         "index": true

package/hooks/validator.ts

@@ -19,6 +19,14 @@ const hook: Hook = {
             return;
         }
 
+        // 应用字段默认值
+        for (const [field, fieldDef] of Object.entries(ctx.api.fields)) {
+            // 字段未传值且定义了默认值时，应用默认值
+            if (ctx.body[field] === undefined && (fieldDef as any)?.default !== undefined) {
+                ctx.body[field] = (fieldDef as any).default;
+            }
+        }
+
         // 验证参数
         const result = Validator.validate(ctx.body, ctx.api.fields, ctx.api.required || []);
 

package/lib/cacheHelper.ts

@@ -37,7 +37,6 @@ export class CacheHelper {
             // 从数据库查询所有接口
             const apiList = await this.befly.db.getAll({
                 table: 'addon_admin_api',
-                fields: ['id', 'name', 'path', 'method', 'description', 'addonName', 'addonTitle'],
                 orderBy: ['addonName#ASC', 'path#ASC']
             });
 
@@ -67,7 +66,6 @@ export class CacheHelper {
             // 从数据库查询所有菜单
             const menus = await this.befly.db.getAll({
                 table: 'addon_admin_menu',
-                fields: ['id', 'pid', 'name', 'path', 'icon', 'type', 'sort'],
                 orderBy: ['sort#ASC', 'id#ASC']
             });
 
@@ -100,12 +98,10 @@ export class CacheHelper {
             // 并行查询角色和接口（利用自动 pipeline）
             const [roles, allApis] = await Promise.all([
                 this.befly.db.getAll({
-                    table: 'addon_admin_role',
-                    fields: ['id', 'code', 'apis']
+                    table: 'addon_admin_role'
                 }),
                 this.befly.db.getAll({
-                    table: 'addon_admin_api',
-                    fields: ['id', 'path', 'method']
+                    table: 'addon_admin_api'
                 })
             ]);
 

package/lib/dbHelper.ts

@@ -283,7 +283,7 @@ export class DbHelper {
 
         // 联查时使用特殊处理逻辑
         if (hasJoins) {
-            // 联查时字段直接处理（支持表别名）
+            // 联查时字段直接处理（支持表名.字段名格式）
             const processedFields = (options.fields || []).map((f) => this.processJoinField(f));
 
             return {
@@ -339,15 +339,26 @@ export class DbHelper {
     /**
      * 添加默认的 state 过滤条件
      * 默认查询 state > 0 的数据（排除已删除和特殊状态）
+     * @param where - where 条件
+     * @param table - 主表名（JOIN 查询时需要，用于添加表名前缀避免歧义）
+     * @param hasJoins - 是否有 JOIN 查询
      */
-    private addDefaultStateFilter(where: WhereConditions = {}): WhereConditions {
+    private addDefaultStateFilter(where: WhereConditions = {}, table?: string, hasJoins: boolean = false): WhereConditions {
         // 如果用户已经指定了 state 条件，优先使用用户的条件
-        const hasStateCondition = Object.keys(where).some((key) => key.startsWith('state'));
+        const hasStateCondition = Object.keys(where).some((key) => key.startsWith('state') || key.includes('.state'));
 
         if (hasStateCondition) {
             return where;
         }
 
+        // JOIN 查询时需要指定主表名前缀避免歧义
+        if (hasJoins && table) {
+            return {
+                ...where,
+                [`${table}.state$gt`]: 0
+            };
+        }
+
         // 默认查询 state > 0 的数据
         return {
             ...where,
@@ -541,7 +552,10 @@ export class DbHelper {
     async getCount(options: Omit<QueryOptions, 'fields' | 'page' | 'limit' | 'orderBy'>): Promise<number> {
         const { table, where, joins } = await this.prepareQueryOptions(options as QueryOptions);
 
-        const builder = new SqlBuilder().select(['COUNT(*) as count']).from(table).where(this.addDefaultStateFilter(where));
+        const builder = new SqlBuilder()
+            .select(['COUNT(*) as count'])
+            .from(table)
+            .where(this.addDefaultStateFilter(where, table, !!joins));
 
         // 添加 JOIN
         this.applyJoins(builder, joins);
@@ -571,7 +585,10 @@ export class DbHelper {
     async getOne<T extends Record<string, any> = Record<string, any>>(options: QueryOptions): Promise<T | null> {
         const { table, fields, where, joins } = await this.prepareQueryOptions(options);
 
-        const builder = new SqlBuilder().select(fields).from(table).where(this.addDefaultStateFilter(where));
+        const builder = new SqlBuilder()
+            .select(fields)
+            .from(table)
+            .where(this.addDefaultStateFilter(where, table, !!joins));
 
         // 添加 JOIN
         this.applyJoins(builder, joins);
@@ -623,7 +640,7 @@ export class DbHelper {
         }
 
         // 构建查询
-        const whereFiltered = this.addDefaultStateFilter(prepared.where);
+        const whereFiltered = this.addDefaultStateFilter(prepared.where, prepared.table, !!prepared.joins);
 
         // 查询总数
         const countBuilder = new SqlBuilder().select(['COUNT(*) as total']).from(prepared.table).where(whereFiltered);
@@ -698,7 +715,7 @@ export class DbHelper {
 
         const prepared = await this.prepareQueryOptions({ ...options, page: 1, limit: 10 });
 
-        const whereFiltered = this.addDefaultStateFilter(prepared.where);
+        const whereFiltered = this.addDefaultStateFilter(prepared.where, prepared.table, !!prepared.joins);
 
         // 查询真实总数
         const countBuilder = new SqlBuilder().select(['COUNT(*) as total']).from(prepared.table).where(whereFiltered);
@@ -893,7 +910,7 @@ export class DbHelper {
         };
 
         // 构建 SQL
-        const whereFiltered = this.addDefaultStateFilter(snakeWhere);
+        const whereFiltered = this.addDefaultStateFilter(snakeWhere, snakeTable, false);
         const builder = new SqlBuilder().where(whereFiltered);
         const { sql, params } = builder.toUpdateSql(snakeTable, processed);
 
@@ -1003,7 +1020,11 @@ export class DbHelper {
         const { table, where } = await this.prepareQueryOptions({ ...options, page: 1, limit: 1 });
 
         // 使用 COUNT(1) 性能更好
-        const builder = new SqlBuilder().select(['COUNT(1) as cnt']).from(table).where(this.addDefaultStateFilter(where)).limit(1);
+        const builder = new SqlBuilder()
+            .select(['COUNT(1) as cnt'])
+            .from(table)
+            .where(this.addDefaultStateFilter(where, table, false))
+            .limit(1);
 
         const { sql, params } = builder.toSelectSql();
         const result = await this.executeWithConn(sql, params);
@@ -1084,7 +1105,7 @@ export class DbHelper {
         const snakeWhere = this.whereKeysToSnake(cleanWhere);
 
         // 使用 SqlBuilder 构建安全的 WHERE 条件
-        const whereFiltered = this.addDefaultStateFilter(snakeWhere);
+        const whereFiltered = this.addDefaultStateFilter(snakeWhere, snakeTable, false);
         const builder = new SqlBuilder().where(whereFiltered);
         const { sql: whereClause, params: whereParams } = builder.getWhereConditions();
 

package/loader/loadApis.ts

@@ -24,16 +24,16 @@ import type { ApiRoute } from '../types/api.js';
  */
 const PRESET_FIELDS: Record<string, any> = {
     '@id': { name: 'ID', type: 'number', min: 1, max: null },
-    '@page': { name: '页码', type: 'number', min: 1, max: 9999 },
-    '@limit': { name: '每页数量', type: 'number', min: 1, max: 100 },
-    '@keyword': { name: '关键词', type: 'string', min: 1, max: 50 },
-    '@state': { name: '状态', type: 'number', min: 0, max: 2 }
+    '@page': { name: '页码', type: 'number', min: 1, max: 9999, default: 1 },
+    '@limit': { name: '每页数量', type: 'number', min: 1, max: 100, default: 30 },
+    '@keyword': { name: '关键词', type: 'string', min: 0, max: 50 },
+    '@state': { name: '状态', type: 'number', regex: '^[0-2]$' }
 };
 
 /**
  * 处理字段定义，将 @ 符号引用替换为实际字段定义
  */
-function processFields(fields: Record<string, any>): Record<string, any> {
+function processFields(fields: Record<string, any>, apiName: string, routePath: string): Record<string, any> {
     if (!fields || typeof fields !== 'object') return fields;
 
     const processed: Record<string, any> = {};
@@ -43,8 +43,9 @@ function processFields(fields: Record<string, any>): Record<string, any> {
             if (PRESET_FIELDS[value]) {
                 processed[key] = PRESET_FIELDS[value];
             } else {
-                // 未找到预定义字段，保持原值
-                processed[key] = value;
+                // 未找到预定义字段，抛出错误
+                const validKeys = Object.keys(PRESET_FIELDS).join(', ');
+                throw new Error(`API [${apiName}] (${routePath}) 字段 [${key}] 引用了未定义的预设字段 "${value}"。可用的预设字段有: ${validKeys}`);
             }
         } else {
             // 普通字段定义，保持原样
@@ -110,13 +111,14 @@ export async function loadApis(apis: Map<string, ApiRoute>): Promise<void> {
                 // 设置默认值
                 const methodStr = (api.method || 'POST').toUpperCase();
                 api.auth = api.auth !== undefined ? api.auth : true;
-                // 处理字段定义，将 @ 引用替换为实际字段定义
-                api.fields = processFields(api.fields || {});
-                api.required = api.required || [];
 
-                // 构建路由路径（不含方法）
+                // 构建路由路径（用于错误提示）
                 const routePath = `/api${apiFile.routePrefix}${apiFile.relativePath}`;
 
+                // 处理字段定义，将 @ 引用替换为实际字段定义
+                api.fields = processFields(api.fields || {}, api.name || apiFile.relativePath, routePath);
+                api.required = api.required || [];
+
                 // 支持逗号分隔的多方法，拆分后分别注册
                 const methods = methodStr
                     .split(',')

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "befly",
-    "version": "3.9.37",
+    "version": "3.9.38",
     "description": "Befly - 为 Bun 专属打造的 TypeScript API 接口框架核心引擎",
     "type": "module",
     "private": false,
@@ -74,7 +74,7 @@
         "pino": "^10.1.0",
         "pino-roll": "^4.0.0"
     },
-    "gitHead": "e078b94f087ddf21f289b55ab86c0b8dce105807",
+    "gitHead": "8cb371928961c63d6c3c416c6dd667f8fe285376",
     "devDependencies": {
         "typescript": "^5.9.3"
     }

package/sync/syncApi.ts

@@ -199,7 +199,6 @@ async function syncApis(helper: any, apis: ApiInfo[]): Promise<void> {
 async function deleteObsoleteRecords(helper: any, apiPaths: Set<string>): Promise<void> {
     const allRecords = await helper.getAll({
         table: 'addon_admin_api',
-        fields: ['id', 'addonName', 'path', 'method'],
         where: { state$gte: 0 }
     });
 
@@ -250,8 +249,7 @@ export async function syncApiCommand(options: SyncApiOptions = {}): Promise<void
         try {
             const apiList = await helper.getAll({
                 table: 'addon_admin_api',
-                fields: ['id', 'name', 'path', 'method', 'description', 'addonName', 'addonTitle'],
-                orderBy: ['addonName#ASC', 'path#ASC']
+                orderBy: ['id#ASC']
             });
 
             const redisHelper = new RedisHelper();

package/sync/syncDev.ts

@@ -179,7 +179,6 @@ export async function syncDevCommand(options: SyncDevOptions = {}): Promise<void
             email: beflyConfig.devEmail,
             username: 'dev',
             password: hashed,
-            roleId: devRole.id,
             roleCode: 'dev',
             roleType: 'admin'
         };

package/sync/syncMenu.ts

@@ -231,8 +231,7 @@ async function syncMenuRecursive(helper: any, menu: MenuConfig, pid: number, exi
  */
 async function syncMenus(helper: any, menus: MenuConfig[]): Promise<void> {
     const allExistingMenus = await helper.getAll({
-        table: 'addon_admin_menu',
-        fields: ['id', 'pid', 'name', 'path', 'sort']
+        table: 'addon_admin_menu'
     });
     const existingMenuMap = new Map<string, any>();
     for (const menu of allExistingMenus.lists) {
@@ -368,7 +367,6 @@ export async function syncMenuCommand(options: SyncMenuOptions = {}): Promise<vo
         // 7. 获取最终菜单数据（用于缓存）
         const allMenusData = await helper.getAll({
             table: 'addon_admin_menu',
-            fields: ['id', 'pid', 'name', 'path', 'sort'],
             orderBy: ['sort#ASC', 'id#ASC']
         });