befly 3.10.0 → 3.10.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": {

package/docs/reference/logger.md

@@ -98,8 +98,8 @@ Logger.info("用户登录成功");
 Logger.info({ userId: 123 }, "用户登录成功");
 
 // 警告日志
-Logger.warn("配置项已弃用");
-Logger.warn({ config: "oldOption" }, "配置项已弃用");
+Logger.warn("配置项不合法");
+Logger.warn({ config: "oldOption" }, "配置项不合法");
 
 // 错误日志
 Logger.error("数据库连接失败");
@@ -393,7 +393,7 @@ Logger.debug({ sql: query, params: params }, "SQL 查询");
 Logger.info({ userId: 123 }, "用户登录成功");
 
 // warn: 潜在问题，但不影响功能
-Logger.warn({ config: "deprecated" }, "配置项已弃用");
+Logger.warn({ config: "invalidOption" }, "配置项不合法");
 
 // error: 操作失败
 Logger.error({ err: error }, "数据库连接失败");

package/docs/reference/sync.md

@@ -5,10 +5,12 @@
 ## 目录
 
 - [概述](#概述)
+- [强约束清单](#强约束清单)
 - [syncTable 数据库同步](#synctable-数据库同步)
 - [syncApi 接口同步](#syncapi-接口同步)
 - [syncMenu 菜单同步](#syncmenu-菜单同步)
 - [syncDev 开发账户同步](#syncdev-开发账户同步)
+- [syncCache 缓存同步](#synccache-缓存同步)
 - [表名规则](#表名规则)
 - [注意事项](#注意事项)
 - [FAQ](#faq)
@@ -25,8 +27,18 @@ Sync 同步系统用于将代码定义同步到数据库，包括：
 | `syncApi`   | 同步 API 路由信息 | `addon_admin_api`                       |
 | `syncMenu`  | 同步菜单配置      | `addon_admin_menu`                      |
 | `syncDev`   | 创建开发者账户    | `addon_admin_role`, `addon_admin_admin` |
+| `syncCache` | 同步缓存          | Redis（apis/menu/role-permissions）     |
 
-**执行顺序**：`syncTable` → `syncApi` → `syncMenu` → `syncDev`
+**执行顺序**：`syncTable` → `syncApi` → `syncMenu` → `syncDev` → `syncCache`
+
+---
+
+## 强约束清单
+
+- **API routePath 必须是 pathname**：`syncApi` 写入数据库的 `routePath` 仅允许 `url.pathname`（例如 `/api/user/login`），禁止出现 method 前缀（`POST/api/...`、`POST /api/...`）。
+- **角色权限 apis 仅允许 pathname 字符串数组**：`syncDev` 写入角色表的 `apis` 必须是 pathname 字符串数组（严格模式不允许 numeric id）。
+- **权限缓存 Set member 仅允许 pathname**：角色接口权限缓存的 Set 成员为 pathname，与 method 无关。
+- **Redis prefix 不允许包含冒号**：配置 `redis.prefix` 不要包含 `:`（系统会自动拼接分隔符）。例如写 `befly`，不要写 `befly:`。
 
 > 说明：当前版本不提供 CLI 同步命令；同步逻辑在服务启动时由主进程自动执行（见 `packages/core/main.ts`）。
 
@@ -44,7 +56,7 @@ Sync 同步系统用于将代码定义同步到数据库，包括：
 import { syncTable } from "../sync/syncTable.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();
 await syncTable(ctx, sources.tables);
 ```
@@ -103,14 +115,16 @@ await syncTable(ctx, sources.tables);
 
 ### 基本用法
 
-通常无需单独调用：`syncData()` 会按顺序执行 `syncApi` → `syncMenu` → `syncDev`。
+通常无需单独调用：服务启动流程会按顺序执行 `syncTable` → `syncApi` → `syncMenu` → `syncDev` → `syncCache`。
 
-如需在代码中手动触发整套数据同步：
+如需在代码中手动调用：
 
 ```typescript
-import { syncData } from "../sync/syncData.js";
+import { syncApi } from "../sync/syncApi.js";
+import { scanSources } from "../utils/scanSources.js";
 
-await syncData();
+const sources = await scanSources();
+await syncApi(ctx, sources.apis as any);
 ```
 
 ### 同步逻辑
@@ -137,20 +151,15 @@ await syncData();
 └─────────────────────────────────────────────────────┘
 ```
 
-### API 信息提取
+### 存储字段（重要）
 
-从 API 文件中提取以下信息：
+`syncApi` 会把扫描到的 API 信息同步到 `addon_admin_api` 表，核心字段为：
 
-```typescript
-interface ApiInfo {
-    name: string; // 接口名称（name 属性）
-    path: string; // 路由路径（由文件路径生成）
-    method: string; // 请求方法（method 属性，默认 POST）
-    description: string; // 接口描述（desc 属性）
-    addonName: string; // 所属 Addon 名称
-    addonTitle: string; // Addon 标题
-}
-```
+- `routePath`：只存 `url.pathname`（例如 `/api/user/login`），与 method 无关
+- `name`：接口名称
+- `addonName`：所属 addon（无 addon 时为空字符串）
+
+> 注意：`routePath` 必须是 pathname（以 `/` 开头），不允许写成 `POST /api/...` 或 `POST/api/...`。
 
 ### 统计信息
 
@@ -171,7 +180,19 @@ interface SyncApiStats {
 
 ### 基本用法
 
-同 `syncApi`，通常由 `syncData()` 统一触发。
+同 `syncApi`，通常由启动流程统一触发。
+
+如需手动调用，需要先对菜单配置做校验/过滤（例如 disableMenus）：
+
+```typescript
+import { checkMenu } from "../checks/checkMenu.js";
+import { syncMenu } from "../sync/syncMenu.js";
+import { scanSources } from "../utils/scanSources.js";
+
+const sources = await scanSources();
+const checkedMenus = await checkMenu(sources.addons, { disableMenus: ctx.config.disableMenus || [] });
+await syncMenu(ctx, checkedMenus);
+```
 
 ### 菜单配置文件
 
@@ -256,49 +277,56 @@ interface SyncMenuStats {
 
 ### 基本用法
 
-同 `syncApi`，通常由 `syncData()` 统一触发。
+同 `syncApi`，通常由启动流程统一触发。
 
 ### 同步逻辑
 
 ```
 ┌─────────────────────────────────────────────────────┐
-│                   syncDev                           │
+│ syncDev │
 ├─────────────────────────────────────────────────────┤
-│  1. 创建/更新开发角色：                              │
-│     - 角色名称：开发者                              │
-│     - 角色标识：dev                                 │
-│     - 权限：所有菜单 + 所有 API                     │
-│         ↓                                           │
-│  2. 获取所有菜单 ID 列表                            │
-│         ↓                                           │
-│  3. 获取所有 API ID 列表                            │
-│         ↓                                           │
-│  4. 更新角色权限：                                   │
-│     - menus: 所有菜单 ID                           │
-│     - apis: 所有 API ID                            │
-│         ↓                                           │
-│  5. 创建/更新开发管理员：                            │
-│     - 用户名：dev                                   │
-│     - 密码：从配置读取                              │
-│     - 角色：开发者角色                              │
+│ 1. 创建/更新开发角色： │
+│ - 角色名称：开发者 │
+│ - 角色标识：dev │
+│ - 权限：所有菜单 + 所有 API │
+│ ↓ │
+│ 2. 获取所有菜单 path 列表 │
+│ ↓ │
+│ 3. 获取所有 API routePath 列表 │
+│ ↓ │
+│ 4. 更新角色权限： │
+│ - menus: 所有菜单 path（字符串数组） │
+│ - apis: 所有 API routePath（pathname 字符串数组）│
+│ ↓ │
+│ 5. 创建/更新开发管理员： │
+│ - 用户名：dev │
+│ - 密码：从配置读取 │
+│ - 角色：开发者角色 │
 └─────────────────────────────────────────────────────┘
 ```
 
 ### 配置说明
 
-开发账户配置在 `befly.config.ts` 或环境配置文件中：
+开发账户配置在 `befly.config.ts` 或环境配置文件中（仅当 `devPassword` 有值时才会创建 dev 账号）：
 
-```typescript
-// befly.config.ts
-export default {
-    dev: {
-        username: "dev", // 开发账户用户名
-        password: "dev123456" // 开发账户密码
-    }
-};
+```json
+{
+    "devEmail": "dev@qq.com",
+    "devPassword": "beflydev123456"
+}
 ```
 
-await syncTable(ctx, sources.tables);
+> 注意：`syncDev` 会把 `menus/apis` 写入角色表，并且 `apis` 必须是 pathname 字符串数组（严格模式下不允许 numeric id）。
+
+---
+
+## syncCache 缓存同步
+
+同步缓存（统一收敛到启动流程末尾执行）：
+
+- `cacheApis()`：缓存接口列表
+- `cacheMenus()`：缓存菜单列表
+- `rebuildRoleApiPermissions()`：重建角色接口权限 Set（member 为 pathname，与 method 无关）
 
 ---
 
@@ -306,16 +334,23 @@ await syncTable(ctx, sources.tables);
 
 ```typescript
 import { syncTable } from "./sync/syncTable.js";
+import { syncApi } from "./sync/syncApi.js";
+import { syncCache } from "./sync/syncCache.js";
+import { syncDev } from "./sync/syncDev.js";
+import { syncMenu } from "./sync/syncMenu.js";
 import { scanSources } from "./utils/scanSources.js";
-import { syncData } from "./sync/syncData";
+import { checkMenu } from "./checks/checkMenu.js";
 
 // 启动前/启动中手动触发同步
-// ctx：BeflyContext（需已具备 ctx.db / ctx.redis / ctx.config）
+// ctx：BeflyContext（需已具备 ctx.db / ctx.redis / ctx.cache / ctx.config）
 const sources = await scanSources();
-await syncTable(ctx, sources.tables);
-await syncData();
+const checkedMenus = await checkMenu(sources.addons, { disableMenus: ctx.config.disableMenus || [] });
 
-// 说明：syncData 内部会固定顺序执行：syncApi → syncMenu → syncDev
+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);
 ```
 
 ---
@@ -357,7 +392,7 @@ addons/demo/tables/article.json   → addon_demo_article
 
 ### 1. 执行顺序
 
-**必须按顺序执行**：`syncTable` → `syncApi` → `syncMenu` → `syncDev`
+**必须按顺序执行**：`syncTable` → `syncApi` → `syncMenu` → `syncDev` → `syncCache`
 
 - `syncApi` 依赖 `addon_admin_api` 表（由 `syncTable` 创建）
 - `syncMenu` 依赖 `addon_admin_menu` 表（由 `syncTable` 创建）
@@ -386,11 +421,10 @@ CacheKeys.tableColumns(tableName); // table:columns:{tableName}
 
 ### 4. 连接管理
 
-Sync 命令会自动管理数据库和 Redis 连接：
+`sync*` 函数本身不会负责建立连接/加载插件：
 
-- 执行前建立连接
-- 执行后关闭连接
-- 出错时正确清理资源
+- 你需要在调用前确保 `Connect.connect(...)` 已执行，并且 `Db/Redis/cache` 插件已注入到 `ctx`。
+- 服务启动流程已内置这套顺序（见 `packages/core/main.ts`）。
 
 ---
 
@@ -425,28 +459,20 @@ A: Addon 表名格式为 `addon_{addonName}_{tableName}`，建议：
 
 A:
 
-1. 检查错误日志确定失败原因
-   A: `syncTable()` 会跳过长度收缩并告警；请手动评估并处理（例如先清理/截断数据，再手动执行 DDL），再重新启动服务或再次调用 `syncTable()`。
+1. 检查错误日志确定失败原因（例如表不存在、字段变更被跳过等）
 2. sync 命令是幂等的，可以安全地多次执行
 
 ### Q: 如何只同步某个 Addon 的表？
 
-await syncTable(ctx, sources.tables);
 A: 当前不支持按 Addon 或单表筛选；会同步项目与所有 Addon 的表定义。
 
 ### Q: 开发账户密码在哪里配置？
 
-A: 在配置文件中设置：
+A: 在配置文件中设置（仅当 `devPassword` 有值时才会创建 dev 账号）：
 
-```typescript
-// befly.config.ts
-export default {
-    dev: {
-        username: "dev",
-        password: "your_password"
-    }
-};
+```json
+{
+    "devEmail": "dev@qq.com",
+    "devPassword": "beflydev123456"
+}
 ```
-
-（不再提供 CLI 参数/命令；按配置文件机制设置即可。）
-await syncTable(ctx, sources.tables);

package/docs/reference/table.md

@@ -567,7 +567,7 @@ await syncTable(ctx, sources.tables);
 
 ### 安全机制
 
-1. **禁止危险类型变更**：不允许从 `BIGINT` 改为 `VARCHAR` 等不兼容变更
+1. **禁止危险类型变更**：不允许从 `BIGINT` 改为 `VARCHAR` 等高风险变更
 2. **长度收缩保护**：默认跳过长度收缩，避免数据截断
 3. **保留字段保护**：不允许定义系统保留字段