befly 3.10.0 → 3.10.1

package/README.md

@@ -220,7 +220,7 @@ export const beflyConfig = {
     redis: {
         host: "127.0.0.1",
         port: 6379,
-        prefix: "befly:"
+        prefix: "befly"
     },
 
     // CORS 跨域配置
@@ -238,6 +238,8 @@ export const beflyConfig = {
 };
 ```
 
+> 注意：`redis.prefix` 不要包含 `:`（系统会自动拼接分隔符）。
+
 ### 数据库连接
 
 通常你不需要手动连接（框架启动期会完成连接并注入插件实例）。
@@ -263,7 +265,7 @@ await Connect.connectRedis({
     host: "127.0.0.1",
     port: 6379,
     db: 0,
-    prefix: "befly:"
+    prefix: "befly"
 });
 
 // 或：同时连接 SQL 和 Redis
@@ -281,7 +283,7 @@ await Connect.connect({
         host: "127.0.0.1",
         port: 6379,
         db: 0,
-        prefix: "befly:"
+        prefix: "befly"
     }
 });
 
@@ -294,19 +296,14 @@ console.log(status.redis.connected); // true/false
 await Connect.disconnect();
 ```
 
-### 配置文件迁移指南
-
-如果你的项目之前使用 `app.config.ts`，请按以下步骤迁移：
+### 配置文件（当前约定）
 
-1. **重命名文件**：`app.config.ts` → `befly.config.ts`
-2. **更新导出名**：`config` → `beflyConfig`
+配置文件名为 `befly.config.ts`，导出名为 `beflyConfig`：
 
 ```typescript
-// 旧写法
-export const config = { ... };
-
-// 新写法
-export const beflyConfig = { ... };
+export const beflyConfig = {
+    // ...
+};
 ```
 
 ## 📖 文档

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)** - syncTable、syncData（内部：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;
 ```
 
@@ -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"
     },
@@ -213,19 +215,31 @@ CREATE DATABASE my_api CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
 服务启动时会在**主进程**自动执行同步流程：
 
 1. `syncTable()`：同步表结构
-2. `syncData()`：固定顺序执行 `syncApi` → `syncMenu` → `syncDev`
+2. `syncApi()`：同步接口定义
+3. `syncMenu()`：同步菜单定义
+4. `syncDev()`：同步开发账户/开发角色
+5. `syncCache()`：缓存同步收尾（cacheApis + cacheMenus + rebuildRoleApiPermissions）
 
 如需手动触发，可在代码中调用（一般不建议在请求路径中调用）：
 
 ```typescript
-import { syncData } from "../sync/syncData.js";
 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.config）
+// 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 syncData();
+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);
 ```
 
 ### 验证同步结果

package/docs/infra/redis.md

@@ -220,9 +220,11 @@ const count = await befly.redis.expireBatch([
 ### saddBatch - 批量添加 Set 成员
 
 ```typescript
+import { CacheKeys } from "befly/lib/cacheKeys";
+
 const count = await befly.redis.saddBatch([
-    { key: "role:admin:apis", members: ["/api/user"] },
-    { key: "role:editor:apis", members: ["/api/article"] }
+    { key: CacheKeys.roleApis("admin"), members: ["/api/user"] },
+    { key: CacheKeys.roleApis("editor"), members: ["/api/article"] }
 ]);
 // 返回: 成功添加的总成员数量
 ```
@@ -230,9 +232,11 @@ const count = await befly.redis.saddBatch([
 ### sismemberBatch - 批量检查 Set 成员
 
 ```typescript
+import { CacheKeys } from "befly/lib/cacheKeys";
+
 const results = await befly.redis.sismemberBatch([
-    { key: "role:admin:apis", member: "/api/user" },
-    { key: "role:admin:apis", member: "/api/user/delete" }
+    { key: CacheKeys.roleApis("admin"), member: "/api/user" },
+    { key: CacheKeys.roleApis("admin"), member: "/api/user/delete" }
 ]);
 // 返回: [true, false]
 ```
@@ -285,11 +289,11 @@ const id = await befly.db.insData({
 import { CacheKeys } from "befly/lib/cacheKeys";
 
 // 获取键名
-const key = CacheKeys.apisAll(); // 'befly:apis:all'
-const key = CacheKeys.menusAll(); // 'befly:menus:all'
-const key = CacheKeys.roleInfo("admin"); // 'befly:role:info:admin'
-const key = CacheKeys.roleApis("admin"); // 'befly:role:apis:admin'
-const key = CacheKeys.tableColumns("user"); // 'befly:table:columns:user'
+const apisAllKey = CacheKeys.apisAll(); // 'befly:apis:all'
+const menusAllKey = CacheKeys.menusAll(); // 'befly:menus:all'
+const adminRoleInfoKey = CacheKeys.roleInfo("admin"); // 'befly:role:info:admin'
+const adminRoleApisKey = CacheKeys.roleApis("admin"); // 'befly:role:apis:admin'
+const userTableColumnsKey = CacheKeys.tableColumns("user"); // 'befly:table:columns:user'
 ```
 
 ### 键名前缀
@@ -304,7 +308,12 @@ Redis 插件支持配置全局前缀，避免键名冲突：
 }
 ```
 
-所有键会自动添加前缀：`myapp:user:1`
+所有键会自动添加前缀，最终写入 Redis 的 key 形如：`myapp:<key>`。
+
+- 例如：你调用 `befly.redis.getString("user:1")`，实际访问的是 `myapp:user:1`
+- 例如：你调用 `befly.redis.sismember(CacheKeys.roleApis("admin"), "/api/user")`，实际访问的是 `myapp:befly:role:apis:admin`
+
+> 注意：`redis.prefix` **不允许包含** `:`，因为 RedisHelper 会自动拼接分隔符 `:`。
 
 ---
 
@@ -313,6 +322,8 @@ Redis 插件支持配置全局前缀，避免键名冲突：
 ### 场景1：表结构缓存
 
 DbHelper 自动缓存表字段信息，避免重复查询数据库。
+
+```typescript
 // 计数 + 过期：常用于限流/风控
 // 更推荐：直接使用 Befly Core 内置的 rateLimit hook（通过 configs 配置即可）
 
@@ -323,8 +334,9 @@ const key = `ratelimit:${ctx.ip}:${ctx.route}`;
 const count = await befly.redis.incrWithExpire(key, windowSeconds);
 
 if (count > limit) {
-return befly.tool.No("请求过于频繁");
+    return befly.tool.No("请求过于频繁");
 }
+```
 
 ### 场景2：接口权限缓存
 

package/docs/quickstart.md

@@ -1,338 +1,8 @@
-# Quickstart 快速入门
+# Quickstart 快速入门（已迁移）
 
-> 5 分钟搭建你的第一个 Befly API 服务
+为避免重复内容长期漂移，本 Quickstart 已迁移到权威入口：
 
-## 目录
+- `packages/core/docs/guide/quickstart.md`
+- 在线阅读：[`./guide/quickstart.md`](./guide/quickstart.md)
 
-- [环境准备](#环境准备)
-- [项目结构](#项目结构)
-- [第一个 API](#第一个-api)
-- [配置数据库](#配置数据库)
-- [定义表结构](#定义表结构)
-- [同步数据库](#同步数据库)
-- [启动服务](#启动服务)
-- [下一步](#下一步)
-
----
-
-## 环境准备
-
-### 必需软件
-
-| 软件  | 版本要求 | 说明              |
-| ----- | -------- | ----------------- |
-| Bun   | >= 1.0   | JavaScript 运行时 |
-| MySQL | >= 8.0   | 数据库            |
-| Redis | >= 6.0   | 缓存（可选）      |
-
-### 安装 Bun
-
-```bash
-# Windows (PowerShell)
-powershell -c "irm bun.sh/install.ps1 | iex"
-
-# macOS / Linux
-curl -fsSL https://bun.sh/install | bash
-```
-
-### 创建项目
-
-```bash
-# 克隆模板项目
-git clone https://github.com/chenbimo/befly-tpl.git my-api
-cd my-api
-
-# 安装依赖
-bun install
-```
-
----
-
-## 项目结构
-
-```
-my-api/
-├── apis/                  # API 接口目录
-│   └── user/
-│       └── login.ts       # 用户登录接口
-├── tables/                # 表定义目录
-│   └── user.json          # 用户表定义
-├── configs/               # 配置文件目录
-│   ├── befly.common.json  # 公共配置
-│   ├── befly.development.json  # 开发环境配置
-│   └── befly.production.json   # 生产环境配置
-├── main.ts                # 入口文件
-└── package.json
-```
-
----
-
-## 第一个 API
-
-### 创建 API 文件
-
-在 `apis/user/` 目录下创建 `login.ts`：
-
-```typescript
-import type { ApiRoute } from "befly/types/api";
-
-export default {
-    name: "用户登录",
-    method: "POST",
-    auth: false, // 不需要登录
-    fields: {
-        email: { name: "邮箱", type: "string", min: 5, max: 100, regexp: "@email" },
-        password: { name: "密码", type: "string", min: 6, max: 100 }
-    },
-    required: ["email", "password"],
-    handler: async (befly, ctx) => {
-        // 查询用户
-        const user = await befly.db.getDetail({
-            table: "user",
-            columns: ["id", "email", "password", "nickname"],
-            where: { email: ctx.body.email }
-        });
-
-        if (!user?.id) {
-            return No("用户不存在");
-        }
-
-        // 验证密码
-        const isValid = await befly.cipher.verifyPassword(ctx.body.password, user.password);
-        if (!isValid) {
-            return No("密码错误");
-        }
-
-        // 签发令牌
-        const token = befly.jwt.sign({ userId: user.id });
-
-        return Yes("登录成功", { token: token, user: { id: user.id, nickname: user.nickname } });
-    }
-} as ApiRoute;
-```
-
-### API 路由规则
-
-文件路径自动转换为路由：
-
-| 文件路径                | 路由路径                  |
-| ----------------------- | ------------------------- |
-| `apis/user/login.ts`    | `POST /api/user/login`    |
-| `apis/user/register.ts` | `POST /api/user/register` |
-| `apis/article/list.ts`  | `POST /api/article/list`  |
-
----
-
-## 配置数据库
-
-### 编辑配置文件
-
-修改 `configs/befly.development.json`：
-
-```json
-{
-    "db": {
-        "type": "mysql",
-        "host": "127.0.0.1",
-        "port": 3306,
-        "user": "root",
-        "password": "your_password",
-        "database": "my_api"
-    },
-    "redis": {
-        "host": "127.0.0.1",
-        "port": 6379,
-        "password": ""
-    },
-    "auth": {
-        "secret": "your-jwt-secret-change-in-production",
-        "expiresIn": "7d"
-    },
-    "logger": {
-        "debug": 1,
-        "console": 1
-    }
-}
-```
-
-### 创建数据库
-
-```sql
-CREATE DATABASE my_api CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-```
-
----
-
-## 定义表结构
-
-### 创建表定义文件
-
-在 `tables/` 目录下创建 `user.json`：
-
-```json
-{
-    "email": "邮箱|string|5|100||true|^[\\w.-]+@[\\w.-]+\\.[a-zA-Z]{2,}$",
-    "password": "密码|string|6|100||true",
-    "nickname": "昵称|string|2|50|用户",
-    "avatar": "头像|string|0|500",
-    "phone": "手机号|string|0|20"
-}
-```
-
-### 字段定义格式
-
-格式：`"字段标签|类型|最小|最大|默认|必填|正则"`
-
-| 位置 | 说明        | 示例                  |
-| ---- | ----------- | --------------------- |
-| 1    | 字段标签    | `邮箱`                |
-| 2    | 数据类型    | `string` / `number`   |
-| 3    | 最小值/长度 | `5`                   |
-| 4    | 最大值/长度 | `100`                 |
-| 5    | 默认值      | `用户`                |
-| 6    | 是否必填    | `true` / `false`      |
-| 7    | 正则验证    | `@email` 或自定义正则 |
-
-### 自动字段
-
-每个表自动添加：
-
-| 字段         | 类型    | 说明                            |
-| ------------ | ------- | ------------------------------- |
-| `id`         | BIGINT  | 主键，自增                      |
-| `created_at` | BIGINT  | 创建时间戳                      |
-| `updated_at` | BIGINT  | 更新时间戳                      |
-| `state`      | TINYINT | 状态（1=正常，0=禁用，-1=删除） |
-
----
-
-## 同步数据库
-
-### 自动同步
-
-服务启动时会在**主进程**自动执行同步流程：
-
-1. `syncTable()`：同步表结构
-2. `syncData()`：固定顺序执行 `syncApi` → `syncMenu` → `syncDev`
-
-如需手动触发，可在代码中调用（一般不建议在请求路径中调用）：
-
-```typescript
-import { syncData } from "../sync/syncData.js";
-import { syncTable } from "../sync/syncTable.js";
-import { scanSources } from "../utils/scanSources.js";
-
-// ctx：BeflyContext（需已具备 ctx.db / ctx.redis / ctx.config）
-const sources = await scanSources();
-await syncTable(ctx, sources.tables);
-await syncData();
-```
-
-### 验证同步结果
-
-```bash
-# 查看数据库
-mysql -u root -p my_api -e "SHOW TABLES;"
-
-# 应该看到：
-# +------------------+
-# | Tables_in_my_api |
-# +------------------+
-# | user             |
-# +------------------+
-```
-
----
-
-## 启动服务
-
-### 开发模式
-
-```bash
-bun run dev
-```
-
-服务启动后：
-
-```
-🚀 Befly 服务已启动
-📍 http://localhost:3000
-```
-
-### 测试 API
-
-```bash
-# 测试登录接口
-curl -X POST http://localhost:3000/api/user/login \
-  -H "Content-Type: application/json" \
-  -d '{"email":"test@example.com","password":"123456"}'
-```
-
-响应示例：
-
-```json
-{
-    "code": 0,
-    "msg": "登录成功",
-    "data": {
-        "token": "eyJhbGciOiJIUzI1NiIs...",
-        "user": {
-            "id": 1,
-            "nickname": "用户"
-        }
-    }
-}
-```
-
----
-
-## 下一步
-
-### 学习更多
-
-| 主题       | 文档                                 | 说明                 |
-| ---------- | ------------------------------------ | -------------------- |
-| API 开发   | [api.md](./api/api.md)               | API 定义、字段、权限 |
-| 表结构     | [table.md](./table.md)               | 表定义格式详解       |
-| 数据库操作 | [database.md](./plugins/database.md) | CRUD 操作            |
-| 配置系统   | [config.md](./config.md)             | 配置文件说明         |
-| 插件开发   | [plugin.md](./plugins/plugin.md)     | 自定义插件           |
-| Hook 开发  | [hook.md](./hooks/hook.md)           | 请求处理钩子         |
-| 验证系统   | [validator.md](./validator.md)       | 参数验证             |
-| 日志系统   | [logger.md](./logger.md)             | 日志配置             |
-| 加密工具   | [cipher.md](./plugins/cipher.md)     | 加密与 JWT           |
-| 同步命令   | [sync.md](./sync.md)                 | 数据库同步           |
-
-### 常用命令
-
-```bash
-# 开发
-bun run dev          # 启动开发服务
-
-# 生产
-bun run build        # 构建
-bun run start        # 启动生产服务
-```
-
-### 项目示例
-
-```
-apis/
-├── user/
-│   ├── login.ts      # 登录
-│   ├── register.ts   # 注册
-│   ├── info.ts       # 获取信息
-│   └── update.ts     # 更新信息
-├── article/
-│   ├── list.ts       # 文章列表
-│   ├── detail.ts     # 文章详情
-│   ├── create.ts     # 创建文章
-│   └── delete.ts     # 删除文章
-└── common/
-    └── upload.ts     # 文件上传
-
-tables/
-├── user.json         # 用户表
-├── article.json      # 文章表
-└── category.json     # 分类表
-```
+如你从旧链接跳转到这里，请以 `guide/quickstart.md` 的内容为准（配置字段、同步流程、权限 pathname 规则等都以当前实现为准）。

package/docs/reference/addon.md

@@ -465,21 +465,6 @@ A: 在配置文件中设置：
 }
 ```
 
-### Q: Addon 的表如何迁移？
-
-A: 服务启动时（主进程）会自动执行 `syncTable()`，会同步项目与所有 Addon 的表定义。
-
-如需手动触发：
-
-```typescript
-import { syncTable } from "../../sync/syncTable.js";
-import { scanSources } from "../../utils/scanSources.js";
-
-// ctx：BeflyContext（需已具备 ctx.db / ctx.redis / ctx.config）
-const sources = await scanSources();
-await syncTable(ctx, sources.tables);
-```
-
 ### Q: 如何在 Addon 中访问项目配置？
 
 A: 通过 `befly.config` 访问：

package/docs/reference/config.md

@@ -379,7 +379,7 @@ NODE_ENV=production bun run start
     },
 
     "redis": {
-        "prefix": "myapp:"
+        "prefix": "myapp"
     },
 
     "cors": {