befly 3.9.40 → 3.10.1

package/checks/checkTable.ts

@@ -1,31 +1,7 @@
-// 类型导入
 import type { FieldDefinition } from "../types/validate.js";
-
-// 内部依赖
-import { existsSync } from "node:fs";
-
-// 外部依赖
-import { basename } from "pathe";
+import type { ScanFileResult } from "../utils/scanFiles.js";
 
 import { Logger } from "../lib/logger.js";
-import { projectTableDir } from "../paths.js";
-import { scanAddons, getAddonDir } from "../utils/addonHelper.js";
-// 相对导入
-import { scanFiles } from "../utils/scanFiles.js";
-
-/**
- * 表文件信息接口
- */
-interface TableFileInfo {
-    /** 表文件路径 */
-    file: string;
-    /** 文件类型：project（项目）或 addon（组件） */
-    type: "project" | "addon";
-    /** 如果是 addon 类型，记录 addon 名称 */
-    addonName?: string;
-    /** 类型名称（用于日志） */
-    typeName: string;
-}
 
 /**
  * 保留字段列表
@@ -65,202 +41,180 @@ const MAX_VARCHAR_LENGTH = 65535;
  * 检查表定义文件
  * @throws 当检查失败时抛出异常
  */
-export async function checkTable(): Promise<void> {
-    try {
-        // 收集所有表文件
-        const allTableFiles: TableFileInfo[] = [];
-        let hasError = false;
-
-        // 收集项目表字段定义文件（如果目录存在）
-        if (existsSync(projectTableDir)) {
-            const files = await scanFiles(projectTableDir, "*.json");
-            for (const { filePath } of files) {
-                allTableFiles.push({
-                    file: filePath,
-                    type: "project",
-                    typeName: "项目"
-                });
-            }
+export async function checkTable(tables: ScanFileResult[]): Promise<void> {
+    // 收集所有表文件
+    let hasError = false;
+
+    // 合并进行验证逻辑
+    for (const item of tables) {
+        if (item.type !== "table") {
+            continue;
         }
 
-        // 收集 addon 表字段定义文件
-        const addons = scanAddons();
-        for (const addonName of addons) {
-            const addonTablesDir = getAddonDir(addonName, "tables");
+        const sourceName = typeof item.sourceName === "string" ? item.sourceName : "";
 
-            // 检查 addon tables 目录是否存在
-            if (!existsSync(addonTablesDir)) {
+        try {
+            const fileName = item.fileName;
+            const table = item.content || {};
+            // 1) 文件名小驼峰校验
+            if (!LOWER_CAMEL_CASE_REGEX.test(fileName)) {
+                Logger.warn(`${sourceName}表 ${fileName} 文件名必须使用小驼峰命名（例如 testCustomers.json）`);
+                hasError = true;
                 continue;
             }
 
-            const files = await scanFiles(addonTablesDir, "*.json");
-            for (const { filePath } of files) {
-                allTableFiles.push({
-                    file: filePath,
-                    type: "addon",
-                    typeName: `组件${addonName}`,
-                    addonName: addonName
-                });
-            }
-        }
+            // 检查 table 中的每个验证规则
+            for (const [colKey, fieldDef] of Object.entries(table)) {
+                if (typeof fieldDef !== "object" || fieldDef === null || Array.isArray(fieldDef)) {
+                    Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 规则必须为对象`);
+                    hasError = true;
+                    continue;
+                }
 
-        // 合并进行验证逻辑
-        for (const item of allTableFiles) {
-            const fileName = basename(item.file);
-            const fileBaseName = basename(item.file, ".json");
+                // 检查是否使用了保留字段
+                if (RESERVED_FIELDS.includes(colKey as any)) {
+                    Logger.warn(`${sourceName}表 ${fileName} 文件包含保留字段 ${colKey}，` + `不能在表定义中使用以下字段: ${RESERVED_FIELDS.join(", ")}`);
+                    hasError = true;
+                }
+
+                // 直接使用字段对象
+                const field = fieldDef as FieldDefinition;
+
+                // 检查是否存在非法属性
+                const fieldKeys = Object.keys(field);
+                const illegalProps = fieldKeys.filter((key) => !ALLOWED_FIELD_PROPERTIES.includes(key as any));
+                if (illegalProps.length > 0) {
+                    Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 包含非法属性: ${illegalProps.join(", ")}，` + `允许的属性为: ${ALLOWED_FIELD_PROPERTIES.join(", ")}`);
+                    hasError = true;
+                }
 
-            try {
-                // 1) 文件名小驼峰校验
-                if (!LOWER_CAMEL_CASE_REGEX.test(fileBaseName)) {
-                    Logger.warn(`${item.typeName}表 ${fileName} 文件名必须使用小驼峰命名（例如 testCustomers.json）`);
+                // 检查必填字段：name, type
+                if (!field.name || typeof field.name !== "string") {
+                    Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 缺少必填字段 name 或类型错误`);
+                    hasError = true;
+                    continue;
+                }
+                if (!field.type || typeof field.type !== "string") {
+                    Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 缺少必填字段 type 或类型错误`);
                     hasError = true;
                     continue;
                 }
 
-                // 动态导入 JSON 文件
-                const tableModule = await import(item.file, { with: { type: "json" } });
-                const table = tableModule.default;
+                // 检查可选字段的类型
+                if (field.min !== undefined && !(field.min === null || typeof field.min === "number")) {
+                    Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 字段 min 类型错误，必须为 null 或数字`);
+                    hasError = true;
+                }
+                if (field.max !== undefined && !(field.max === null || typeof field.max === "number")) {
+                    Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 字段 max 类型错误，必须为 null 或数字`);
+                    hasError = true;
+                }
+                if (field.detail !== undefined && typeof field.detail !== "string") {
+                    Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 字段 detail 类型错误，必须为字符串`);
+                    hasError = true;
+                }
+                if (field.index !== undefined && typeof field.index !== "boolean") {
+                    Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 字段 index 类型错误，必须为布尔值`);
+                    hasError = true;
+                }
+                if (field.unique !== undefined && typeof field.unique !== "boolean") {
+                    Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 字段 unique 类型错误，必须为布尔值`);
+                    hasError = true;
+                }
+                if (field.nullable !== undefined && typeof field.nullable !== "boolean") {
+                    Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 字段 nullable 类型错误，必须为布尔值`);
+                    hasError = true;
+                }
+                if (field.unsigned !== undefined && typeof field.unsigned !== "boolean") {
+                    Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 字段 unsigned 类型错误，必须为布尔值`);
+                    hasError = true;
+                }
+                if (field.regexp !== undefined && field.regexp !== null && typeof field.regexp !== "string") {
+                    Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 字段 regexp 类型错误，必须为 null 或字符串`);
+                    hasError = true;
+                }
 
-                // 检查 table 中的每个验证规则
-                for (const [colKey, fieldDef] of Object.entries(table)) {
-                    if (typeof fieldDef !== "object" || fieldDef === null || Array.isArray(fieldDef)) {
-                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 规则必须为对象`);
-                        hasError = true;
-                        continue;
-                    }
+                const { name: fieldName, type: fieldType, min: fieldMin, max: fieldMax, default: fieldDefault } = field;
 
-                    // 检查是否使用了保留字段
-                    if (RESERVED_FIELDS.includes(colKey as any)) {
-                        Logger.warn(`${item.typeName}表 ${fileName} 文件包含保留字段 ${colKey}，` + `不能在表定义中使用以下字段: ${RESERVED_FIELDS.join(", ")}`);
-                        hasError = true;
-                    }
+                // 字段名称必须为中文、数字、字母、下划线、短横线、空格
+                if (!FIELD_NAME_REGEX.test(fieldName)) {
+                    Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 字段名称 "${fieldName}" 格式错误，` + `必须为中文、数字、字母、下划线、短横线、空格`);
+                    hasError = true;
+                }
 
-                    // 直接使用字段对象
-                    const field = fieldDef as FieldDefinition;
+                // 字段类型必须为string,number,text,array_string,array_text之一
+                if (!FIELD_TYPES.includes(fieldType as any)) {
+                    Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 字段类型 "${fieldType}" 格式错误，` + `必须为${FIELD_TYPES.join("、")}之一`);
+                    hasError = true;
+                }
 
-                    // 检查是否存在非法属性
-                    const fieldKeys = Object.keys(field);
-                    const illegalProps = fieldKeys.filter((key) => !ALLOWED_FIELD_PROPERTIES.includes(key as any));
-                    if (illegalProps.length > 0) {
-                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 包含非法属性: ${illegalProps.join(", ")}，` + `允许的属性为: ${ALLOWED_FIELD_PROPERTIES.join(", ")}`);
-                        hasError = true;
-                    }
+                // unsigned 仅对 number 类型有效（且仅 MySQL 语义上生效）
+                if (fieldType !== "number" && field.unsigned !== undefined) {
+                    Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 字段类型为 ${fieldType}，不允许设置 unsigned（仅 number 类型有效）`);
+                    hasError = true;
+                }
 
-                    // 检查必填字段：name, type
-                    if (!field.name || typeof field.name !== "string") {
-                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 缺少必填字段 name 或类型错误`);
-                        hasError = true;
-                        continue;
-                    }
-                    if (!field.type || typeof field.type !== "string") {
-                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 缺少必填字段 type 或类型错误`);
-                        hasError = true;
-                        continue;
-                    }
+                // 约束：unique 与 index 不能同时为 true（否则会重复索引），必须阻断启动。
+                if (field.unique === true && field.index === true) {
+                    Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 同时设置了 unique=true 和 index=true，` + `unique 和 index 不能同时设置，请删除其一（否则会创建重复索引）`);
+                    hasError = true;
+                }
 
-                    // 检查可选字段的类型
-                    if (field.min !== undefined && !(field.min === null || typeof field.min === "number")) {
-                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段 min 类型错误，必须为 null 或数字`);
+                // 约束：当最小值与最大值均为数字时，要求最小值 <= 最大值
+                if (fieldMin !== undefined && fieldMax !== undefined && fieldMin !== null && fieldMax !== null) {
+                    if (fieldMin > fieldMax) {
+                        Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 最小值 "${fieldMin}" 不能大于最大值 "${fieldMax}"`);
                         hasError = true;
                     }
-                    if (field.max !== undefined && !(field.max === null || typeof field.max === "number")) {
-                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段 max 类型错误，必须为 null 或数字`);
+                }
+
+                // 类型联动校验 + 默认值规则
+                if (fieldType === "text" || fieldType === "array_text" || fieldType === "array_number_text") {
+                    // text / array_text / array_number_text：min/max 必须为 null，默认值必须为 null，且不支持索引/唯一约束
+                    if (fieldMin !== undefined && fieldMin !== null) {
+                        Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 的 ${fieldType} 类型最小值应为 null，当前为 "${fieldMin}"`);
                         hasError = true;
                     }
-                    if (field.detail !== undefined && typeof field.detail !== "string") {
-                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段 detail 类型错误，必须为字符串`);
+                    if (fieldMax !== undefined && fieldMax !== null) {
+                        Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 的 ${fieldType} 类型最大长度应为 null，当前为 "${fieldMax}"`);
                         hasError = true;
                     }
-                    if (field.index !== undefined && typeof field.index !== "boolean") {
-                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段 index 类型错误，必须为布尔值`);
+                    if (fieldDefault !== undefined && fieldDefault !== null) {
+                        Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 为 ${fieldType} 类型，默认值必须为 null，当前为 "${fieldDefault}"`);
                         hasError = true;
                     }
-                    if (field.unique !== undefined && typeof field.unique !== "boolean") {
-                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段 unique 类型错误，必须为布尔值`);
+
+                    if (field.index === true) {
+                        Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 为 ${fieldType} 类型，不支持创建索引（index=true 无效）`);
                         hasError = true;
                     }
-                    if (field.nullable !== undefined && typeof field.nullable !== "boolean") {
-                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段 nullable 类型错误，必须为布尔值`);
+                    if (field.unique === true) {
+                        Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 为 ${fieldType} 类型，不支持唯一约束（unique=true 无效）`);
                         hasError = true;
                     }
-                    if (field.unsigned !== undefined && typeof field.unsigned !== "boolean") {
-                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段 unsigned 类型错误，必须为布尔值`);
+                } else if (fieldType === "string" || fieldType === "array_string" || fieldType === "array_number_string") {
+                    if (fieldMax !== undefined && (fieldMax === null || typeof fieldMax !== "number")) {
+                        Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 为 ${fieldType} 类型，` + `最大长度必须为数字，当前为 "${fieldMax}"`);
                         hasError = true;
-                    }
-                    if (field.regexp !== undefined && field.regexp !== null && typeof field.regexp !== "string") {
-                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段 regexp 类型错误，必须为 null 或字符串`);
+                    } else if (fieldMax !== undefined && fieldMax > MAX_VARCHAR_LENGTH) {
+                        Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 最大长度 ${fieldMax} 越界，` + `${fieldType} 类型长度必须在 1..${MAX_VARCHAR_LENGTH} 范围内`);
                         hasError = true;
                     }
-
-                    const { name: fieldName, type: fieldType, min: fieldMin, max: fieldMax, default: fieldDefault } = field;
-
-                    // 字段名称必须为中文、数字、字母、下划线、短横线、空格
-                    if (!FIELD_NAME_REGEX.test(fieldName)) {
-                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段名称 "${fieldName}" 格式错误，` + `必须为中文、数字、字母、下划线、短横线、空格`);
-                        hasError = true;
-                    }
-
-                    // 字段类型必须为string,number,text,array_string,array_text之一
-                    if (!FIELD_TYPES.includes(fieldType as any)) {
-                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段类型 "${fieldType}" 格式错误，` + `必须为${FIELD_TYPES.join("、")}之一`);
+                } else if (fieldType === "number") {
+                    // number 类型：default 如果存在，必须为 null 或 number
+                    if (fieldDefault !== undefined && fieldDefault !== null && typeof fieldDefault !== "number") {
+                        Logger.warn(`${sourceName}表 ${fileName} 文件 ${colKey} 为 number 类型，` + `默认值必须为数字或 null，当前为 "${fieldDefault}"`);
                         hasError = true;
                     }
-
-                    // 检查 unique 和 index 冲突（警告但不阻断）
-                    if (field.unique && field.index) {
-                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 同时设置了 unique=true 和 index=true，` + `unique 约束会自动创建唯一索引，index=true 将被忽略以避免重复索引`);
-                    }
-
-                    // 约束：当最小值与最大值均为数字时，要求最小值 <= 最大值
-                    if (fieldMin !== undefined && fieldMax !== undefined && fieldMin !== null && fieldMax !== null) {
-                        if (fieldMin > fieldMax) {
-                            Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 最小值 "${fieldMin}" 不能大于最大值 "${fieldMax}"`);
-                            hasError = true;
-                        }
-                    }
-
-                    // 类型联动校验 + 默认值规则
-                    if (fieldType === "text") {
-                        // text：min/max 应该为 null，默认值必须为 null
-                        if (fieldMin !== undefined && fieldMin !== null) {
-                            Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 的 text 类型最小值应为 null，当前为 "${fieldMin}"`);
-                            hasError = true;
-                        }
-                        if (fieldMax !== undefined && fieldMax !== null) {
-                            Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 的 text 类型最大长度应为 null，当前为 "${fieldMax}"`);
-                            hasError = true;
-                        }
-                        if (fieldDefault !== undefined && fieldDefault !== null) {
-                            Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 为 text 类型，默认值必须为 null，当前为 "${fieldDefault}"`);
-                            hasError = true;
-                        }
-                    } else if (fieldType === "string" || fieldType === "array_string" || fieldType === "array_number_string") {
-                        if (fieldMax !== undefined && (fieldMax === null || typeof fieldMax !== "number")) {
-                            Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 为 ${fieldType} 类型，` + `最大长度必须为数字，当前为 "${fieldMax}"`);
-                            hasError = true;
-                        } else if (fieldMax !== undefined && fieldMax > MAX_VARCHAR_LENGTH) {
-                            Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 最大长度 ${fieldMax} 越界，` + `${fieldType} 类型长度必须在 1..${MAX_VARCHAR_LENGTH} 范围内`);
-                            hasError = true;
-                        }
-                    } else if (fieldType === "number") {
-                        // number 类型：default 如果存在，必须为 null 或 number
-                        if (fieldDefault !== undefined && fieldDefault !== null && typeof fieldDefault !== "number") {
-                            Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 为 number 类型，` + `默认值必须为数字或 null，当前为 "${fieldDefault}"`);
-                            hasError = true;
-                        }
-                    }
                 }
-            } catch (error: any) {
-                Logger.error(`${item.typeName}表 ${fileName} 解析失败`, error);
-                hasError = true;
             }
+        } catch (error: any) {
+            Logger.error(`${sourceName}表 ${item.fileName} 解析失败`, error);
+            hasError = true;
         }
+    }
 
-        if (hasError) {
-            throw new Error("表结构检查失败");
-        }
-    } catch (error: any) {
-        Logger.error("数据表定义检查过程中出错", error);
-        throw error;
+    if (hasError) {
+        throw new Error("表结构检查失败");
     }
 }

package/docs/README.md

@@ -2,18 +2,24 @@
 
 > Befly 是基于 Bun 的高性能 API 框架
 
+## 文档原则
+
+- 文档只描述**当前实现**：不提供迁移指引、不保留兼容说明、不出现“已迁移/跳转页/占位页”。
+- 如文档与代码行为不一致：**以代码为准**，应直接修正文档。
+- 规则以“可执行/可验证”为标准：给出明确约束（例如 pathname-only、严格校验规则），避免含糊表述。
+
 ## 快速开始
 
 - [Quickstart 快速入门](./guide/quickstart.md) - 5 分钟搭建第一个 API 服务
 
 ## 核心概念
 
-| 文档                                     | 说明                         |
-| ---------------------------------------- | ---------------------------- |
-| [API 开发](./api/api.md)                 | API 定义、字段验证、权限控制 |
-| [Table 表结构](./reference/table.md)     | JSON 表定义格式、字段类型    |
-| [Database 数据库](./plugins/database.md) | CRUD 操作、事务、批量操作    |
-| [Config 配置](./reference/config.md)     | 配置文件、环境分离           |
+| 文档                                     | 说明                                                                  |
+| ---------------------------------------- | --------------------------------------------------------------------- |
+| [API 开发](./api/api.md)                 | API 定义、字段验证、权限控制（[强约束清单](./api/api.md#强约束清单)） |
+| [Table 表结构](./reference/table.md)     | JSON 表定义格式、字段类型                                             |
+| [Database 数据库](./plugins/database.md) | CRUD 操作、事务、批量操作                                             |
+| [Config 配置](./reference/config.md)     | 配置文件、环境分离                                                    |
 
 ## 扩展开发
 
@@ -41,9 +47,9 @@
 
 ## 命令工具
 
-| 文档                             | 说明                  |
-| -------------------------------- | --------------------- |
-| [Sync 同步](./reference/sync.md) | 数据库、API、菜单同步 |
+| 文档                             | 说明                                                                  |
+| -------------------------------- | --------------------------------------------------------------------- |
+| [Sync 同步](./reference/sync.md) | 数据库、API、菜单同步（[强约束清单](./reference/sync.md#强约束清单)） |
 
 ## 实战示例
 
@@ -57,7 +63,7 @@
 
 ### 开发篇
 
-2. **[API](./api/api.md)** - API 路由定义、字段验证、权限控制、响应格式
+2. **[API](./api/api.md)** - API 路由定义、字段验证、权限控制、响应格式（[强约束清单](./api/api.md#强约束清单)）
 3. **[Table](./reference/table.md)** - 表定义格式、字段类型、系统字段、命名规范
 4. **[Database](./plugins/database.md)** - 数据库连接、CRUD 操作、事务处理、批量操作
 5. **[Config](./reference/config.md)** - 配置文件结构、环境分离、运行时配置
@@ -77,7 +83,7 @@
 
 ### 运维篇
 
-13. **[Sync](./reference/sync.md)** - syncDb、syncApi、syncMenu、syncDev 命令
+13. **[Sync](./reference/sync.md)** - syncTable、syncApi、syncMenu、syncDev、syncCache（[强约束清单](./reference/sync.md#强约束清单)）
 
 ## 常用链接
 

package/docs/api/api.md

@@ -8,6 +8,7 @@
     - [目录](#目录)
     - [概述](#概述)
         - [核心特性](#核心特性)
+    - [强约束清单](#强约束清单)
     - [目录结构](#目录结构-1)
         - [项目 API](#项目-api)
         - [Addon API](#addon-api)
@@ -78,6 +79,15 @@ Befly 框架的 API 系统是一套基于约定优于配置的接口开发体系
 
 ---
 
+## 强约束清单
+
+- **权限/路由匹配只看 pathname**：系统内部用于路由匹配与权限判断的值均为 `url.pathname`（例如 `/api/user/login`），与 method 无关。
+- **禁止写法**：禁止把权限或路由路径写成 `POST/api/...` 或 `POST /api/...`（这些只是一种“请求行展示写法”，不能进入任何存储/配置/权限集合）。
+- **routePath 必须严格合法**：必须以 `/api/` 开头、不得包含空格、不得出现 `/api//`。
+- **同一路径多方法共用权限**：同一个 pathname（例如 `/api/user/login`）即使同时注册 GET/POST，也共用同一套权限集合。
+
+---
+
 ## 目录结构
 
 ### 项目 API
@@ -139,7 +149,7 @@ export default {
     fields: {}, // 字段定义（验证规则）
     required: [], // 必填字段列表
     rawBody: false // 是否保留原始请求体
-    // 缓存/限流：已统一迁移为 Hook 能力（见 hook 文档/配置），不再挂载在接口定义上
+    // 缓存/限流：当前实现为 Hook 能力（见 hook 文档/配置），不再挂载在接口定义上
 } as ApiRoute;
 ```
 
@@ -208,7 +218,7 @@ interface RequestContext {
     /** 请求头 */
     headers: Headers;
 
-    /** API 路由路径（如 POST/api/user/login） */
+    /** API 路由路径（url.pathname，例如 /api/user/login；与 method 无关） */
     route: string;
 
     /** 请求唯一 ID */
@@ -1276,6 +1286,8 @@ if (!ctx.user?.id) {
 | `addonAdmin/apis/auth/login.ts` | `POST /api/addon/addonAdmin/auth/login` |
 | `addonAdmin/apis/admin/list.ts` | `POST /api/addon/addonAdmin/admin/list` |
 
+> 注意：上表中的 `POST /api/...` 是“请求行示意”。系统内部生成并存储的 `ctx.route` / 数据库 `routePath` / 角色权限 `role.apis` / Redis 权限缓存都只使用 `url.pathname`（例如 `/api/user/login`），与 method 无关；权限数据禁止写成 `POST /api/...` 或 `POST/api/...`。
+
 ### 多方法注册
 
 当 `method: 'GET,POST'` 时，会同时注册两个路由：
@@ -1283,6 +1295,8 @@ if (!ctx.user?.id) {
 - `GET /api/user/search`
 - `POST /api/user/search`
 
+> 权限校验只看 pathname：如果同一个 pathname 同时注册了多个 method，它们共享同一套权限（以 `/api/user/search` 作为权限值）。
+
 ---
 
 ## BeflyContext 对象

package/docs/guide/quickstart.md

@@ -121,6 +121,8 @@ export default {
 | `apis/user/register.ts` | `POST /api/user/register` |
 | `apis/article/list.ts`  | `POST /api/article/list`  |
 
+> 注意：上面的写法是“HTTP 请求方法 + url.pathname”。系统内部生成并存储的 `routePath`、角色权限 `role.apis` 以及 Redis 权限缓存都只使用 `url.pathname`（例如 `/api/user/login`），与 method 无关，且禁止写成 `POST/api/...` 或 `POST /api/...`。
+
 ---
 
 ## 配置数据库
@@ -135,7 +137,7 @@ export default {
         "type": "mysql",
         "host": "127.0.0.1",
         "port": 3306,
-        "user": "root",
+        "username": "root",
         "password": "your_password",
         "database": "my_api"
     },
@@ -208,15 +210,36 @@ CREATE DATABASE my_api CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
 
 ## 同步数据库
 
-### 运行同步命令
+### 自动同步
 
-```bash
-# 全量同步（表结构 + API + 菜单 + 开发账户）
-bun befly sync
+服务启动时会在**主进程**自动执行同步流程：
+
+1. `syncTable()`：同步表结构
+2. `syncApi()`：同步接口定义
+3. `syncMenu()`：同步菜单定义
+4. `syncDev()`：同步开发账户/开发角色
+5. `syncCache()`：缓存同步收尾（cacheApis + cacheMenus + rebuildRoleApiPermissions）
 
-# 或单独同步
-bun befly sync:db      # 只同步表结构
-bun befly sync:api     # 只同步 API 路由
+如需手动触发，可在代码中调用（一般不建议在请求路径中调用）：
+
+```typescript
+import { syncTable } from "../sync/syncTable.js";
+import { syncApi } from "../sync/syncApi.js";
+import { syncMenu } from "../sync/syncMenu.js";
+import { syncDev } from "../sync/syncDev.js";
+import { syncCache } from "../sync/syncCache.js";
+import { checkMenu } from "../checks/checkMenu.js";
+import { scanSources } from "../utils/scanSources.js";
+
+// ctx：BeflyContext（需已具备 ctx.db / ctx.redis / ctx.cache / ctx.config）
+const sources = await scanSources();
+const checkedMenus = await checkMenu(sources.addons, { disableMenus: ctx.config.disableMenus || [] });
+
+await syncTable(ctx, sources.tables);
+await syncApi(ctx, sources.apis as any);
+await syncMenu(ctx, checkedMenus);
+await syncDev(ctx, { devEmail: ctx.config.devEmail, devPassword: ctx.config.devPassword });
+await syncCache(ctx);
 ```
 
 ### 验证同步结果
@@ -299,8 +322,6 @@ curl -X POST http://localhost:3000/api/user/login \
 ```bash
 # 开发
 bun run dev          # 启动开发服务
-bun befly sync       # 同步数据库
-bun befly sync:db    # 只同步表结构
 
 # 生产
 bun run build        # 构建

package/docs/hooks/hook.md

@@ -541,7 +541,7 @@ export default hook;
         "defaultLimit": 1000,
         "defaultWindow": 60,
         "key": "ip",
-        "skipRoutes": ["/api/health", "GET/api/metrics"],
+        "skipRoutes": ["/api/health", "/api/metrics"],
         "rules": [
             {
                 "route": "/api/auth/*",
@@ -550,7 +550,7 @@ export default hook;
                 "key": "ip"
             },
             {
-                "route": "POST/api/order/create",
+                "route": "/api/order/create",
                 "limit": 5,
                 "window": 60,
                 "key": "user"

package/docs/hooks/rateLimit.md

@@ -22,7 +22,7 @@
                 "key": "ip"
             }
         ],
-        "skipRoutes": ["GET/api/health"]
+        "skipRoutes": ["/api/health"]
     }
 }
 ```