befly 3.9.38 → 3.9.39

package/checks/checkTable.ts

@@ -1,17 +1,17 @@
+// 类型导入
+import type { FieldDefinition } from "../types/validate.js";
+
 // 内部依赖
-import { existsSync } from 'node:fs';
+import { existsSync } from "node:fs";
 
 // 外部依赖
-import { basename } from 'pathe';
-import { scanFiles } from 'befly-shared/scanFiles';
-import { scanAddons, getAddonDir } from 'befly-shared/addonHelper';
+import { basename } from "pathe";
 
+import { Logger } from "../lib/logger.js";
+import { projectTableDir } from "../paths.js";
+import { scanAddons, getAddonDir } from "../utils/addonHelper.js";
 // 相对导入
-import { Logger } from '../lib/logger.js';
-import { projectTableDir } from '../paths.js';
-
-// 类型导入
-import type { FieldDefinition } from 'befly-shared/types';
+import { scanFiles } from "../utils/scanFiles.js";
 
 /**
  * 表文件信息接口
@@ -20,7 +20,7 @@ interface TableFileInfo {
     /** 表文件路径 */
     file: string;
     /** 文件类型：project（项目）或 addon（组件） */
-    type: 'project' | 'addon';
+    type: "project" | "addon";
     /** 如果是 addon 类型，记录 addon 名称 */
     addonName?: string;
     /** 类型名称（用于日志） */
@@ -30,17 +30,17 @@ interface TableFileInfo {
 /**
  * 保留字段列表
  */
-const RESERVED_FIELDS = ['id', 'created_at', 'updated_at', 'deleted_at', 'state'] as const;
+const RESERVED_FIELDS = ["id", "created_at", "updated_at", "deleted_at", "state"] as const;
 
 /**
  * 允许的字段类型
  */
-const FIELD_TYPES = ['string', 'number', 'text', 'array_string', 'array_text'] as const;
+const FIELD_TYPES = ["string", "number", "text", "array_string", "array_text", "array_number_string", "array_number_text"] as const;
 
 /**
  * 允许的字段属性列表
  */
-const ALLOWED_FIELD_PROPERTIES = ['name', 'type', 'min', 'max', 'default', 'detail', 'index', 'unique', 'nullable', 'unsigned', 'regexp'] as const;
+const ALLOWED_FIELD_PROPERTIES = ["name", "type", "min", "max", "default", "detail", "index", "unique", "nullable", "unsigned", "regexp"] as const;
 
 /**
  * 小驼峰命名正则
@@ -73,12 +73,12 @@ export async function checkTable(): Promise<void> {
 
         // 收集项目表字段定义文件（如果目录存在）
         if (existsSync(projectTableDir)) {
-            const files = await scanFiles(projectTableDir, '*.json', false);
+            const files = await scanFiles(projectTableDir, "*.json");
             for (const { filePath } of files) {
                 allTableFiles.push({
                     file: filePath,
-                    type: 'project',
-                    typeName: '项目'
+                    type: "project",
+                    typeName: "项目"
                 });
             }
         }
@@ -86,18 +86,18 @@ export async function checkTable(): Promise<void> {
         // 收集 addon 表字段定义文件
         const addons = scanAddons();
         for (const addonName of addons) {
-            const addonTablesDir = getAddonDir(addonName, 'tables');
+            const addonTablesDir = getAddonDir(addonName, "tables");
 
             // 检查 addon tables 目录是否存在
             if (!existsSync(addonTablesDir)) {
                 continue;
             }
 
-            const files = await scanFiles(addonTablesDir, '*.json', false);
+            const files = await scanFiles(addonTablesDir, "*.json");
             for (const { filePath } of files) {
                 allTableFiles.push({
                     file: filePath,
-                    type: 'addon',
+                    type: "addon",
                     typeName: `组件${addonName}`,
                     addonName: addonName
                 });
@@ -107,7 +107,7 @@ export async function checkTable(): Promise<void> {
         // 合并进行验证逻辑
         for (const item of allTableFiles) {
             const fileName = basename(item.file);
-            const fileBaseName = basename(item.file, '.json');
+            const fileBaseName = basename(item.file, ".json");
 
             try {
                 // 1) 文件名小驼峰校验
@@ -118,12 +118,12 @@ export async function checkTable(): Promise<void> {
                 }
 
                 // 动态导入 JSON 文件
-                const tableModule = await import(item.file, { with: { type: 'json' } });
+                const tableModule = await import(item.file, { with: { type: "json" } });
                 const table = tableModule.default;
 
                 // 检查 table 中的每个验证规则
                 for (const [colKey, fieldDef] of Object.entries(table)) {
-                    if (typeof fieldDef !== 'object' || fieldDef === null || Array.isArray(fieldDef)) {
+                    if (typeof fieldDef !== "object" || fieldDef === null || Array.isArray(fieldDef)) {
                         Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 规则必须为对象`);
                         hasError = true;
                         continue;
@@ -131,7 +131,7 @@ export async function checkTable(): Promise<void> {
 
                     // 检查是否使用了保留字段
                     if (RESERVED_FIELDS.includes(colKey as any)) {
-                        Logger.warn(`${item.typeName}表 ${fileName} 文件包含保留字段 ${colKey}，` + `不能在表定义中使用以下字段: ${RESERVED_FIELDS.join(', ')}`);
+                        Logger.warn(`${item.typeName}表 ${fileName} 文件包含保留字段 ${colKey}，` + `不能在表定义中使用以下字段: ${RESERVED_FIELDS.join(", ")}`);
                         hasError = true;
                     }
 
@@ -142,52 +142,52 @@ export async function checkTable(): Promise<void> {
                     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(', ')}`);
+                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 包含非法属性: ${illegalProps.join(", ")}，` + `允许的属性为: ${ALLOWED_FIELD_PROPERTIES.join(", ")}`);
                         hasError = true;
                     }
 
                     // 检查必填字段：name, type
-                    if (!field.name || typeof field.name !== 'string') {
+                    if (!field.name || typeof field.name !== "string") {
                         Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 缺少必填字段 name 或类型错误`);
                         hasError = true;
                         continue;
                     }
-                    if (!field.type || typeof field.type !== 'string') {
+                    if (!field.type || typeof field.type !== "string") {
                         Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 缺少必填字段 type 或类型错误`);
                         hasError = true;
                         continue;
                     }
 
                     // 检查可选字段的类型
-                    if (field.min !== undefined && !(field.min === null || typeof field.min === 'number')) {
+                    if (field.min !== undefined && !(field.min === null || typeof field.min === "number")) {
                         Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段 min 类型错误，必须为 null 或数字`);
                         hasError = true;
                     }
-                    if (field.max !== undefined && !(field.max === null || typeof field.max === 'number')) {
+                    if (field.max !== undefined && !(field.max === null || typeof field.max === "number")) {
                         Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段 max 类型错误，必须为 null 或数字`);
                         hasError = true;
                     }
-                    if (field.detail !== undefined && typeof field.detail !== 'string') {
+                    if (field.detail !== undefined && typeof field.detail !== "string") {
                         Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段 detail 类型错误，必须为字符串`);
                         hasError = true;
                     }
-                    if (field.index !== undefined && typeof field.index !== 'boolean') {
+                    if (field.index !== undefined && typeof field.index !== "boolean") {
                         Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段 index 类型错误，必须为布尔值`);
                         hasError = true;
                     }
-                    if (field.unique !== undefined && typeof field.unique !== 'boolean') {
+                    if (field.unique !== undefined && typeof field.unique !== "boolean") {
                         Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段 unique 类型错误，必须为布尔值`);
                         hasError = true;
                     }
-                    if (field.nullable !== undefined && typeof field.nullable !== 'boolean') {
+                    if (field.nullable !== undefined && typeof field.nullable !== "boolean") {
                         Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段 nullable 类型错误，必须为布尔值`);
                         hasError = true;
                     }
-                    if (field.unsigned !== undefined && typeof field.unsigned !== 'boolean') {
+                    if (field.unsigned !== undefined && typeof field.unsigned !== "boolean") {
                         Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段 unsigned 类型错误，必须为布尔值`);
                         hasError = true;
                     }
-                    if (field.regexp !== undefined && field.regexp !== null && typeof field.regexp !== 'string') {
+                    if (field.regexp !== undefined && field.regexp !== null && typeof field.regexp !== "string") {
                         Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段 regexp 类型错误，必须为 null 或字符串`);
                         hasError = true;
                     }
@@ -202,7 +202,7 @@ export async function checkTable(): Promise<void> {
 
                     // 字段类型必须为string,number,text,array_string,array_text之一
                     if (!FIELD_TYPES.includes(fieldType as any)) {
-                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段类型 "${fieldType}" 格式错误，` + `必须为${FIELD_TYPES.join('、')}之一`);
+                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 字段类型 "${fieldType}" 格式错误，` + `必须为${FIELD_TYPES.join("、")}之一`);
                         hasError = true;
                     }
 
@@ -220,7 +220,7 @@ export async function checkTable(): Promise<void> {
                     }
 
                     // 类型联动校验 + 默认值规则
-                    if (fieldType === 'text') {
+                    if (fieldType === "text") {
                         // text：min/max 应该为 null，默认值必须为 null
                         if (fieldMin !== undefined && fieldMin !== null) {
                             Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 的 text 类型最小值应为 null，当前为 "${fieldMin}"`);
@@ -234,17 +234,17 @@ export async function checkTable(): Promise<void> {
                             Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 为 text 类型，默认值必须为 null，当前为 "${fieldDefault}"`);
                             hasError = true;
                         }
-                    } else if (fieldType === 'string' || fieldType === 'array_string') {
-                        if (fieldMax !== undefined && (fieldMax === null || typeof fieldMax !== 'number')) {
+                    } 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') {
+                    } else if (fieldType === "number") {
                         // number 类型：default 如果存在，必须为 null 或 number
-                        if (fieldDefault !== undefined && fieldDefault !== null && typeof fieldDefault !== 'number') {
+                        if (fieldDefault !== undefined && fieldDefault !== null && typeof fieldDefault !== "number") {
                             Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 为 number 类型，` + `默认值必须为数字或 null，当前为 "${fieldDefault}"`);
                             hasError = true;
                         }
@@ -257,10 +257,10 @@ export async function checkTable(): Promise<void> {
         }
 
         if (hasError) {
-            throw new Error('表结构检查失败');
+            throw new Error("表结构检查失败");
         }
     } catch (error: any) {
-        Logger.error('数据表定义检查过程中出错', error);
+        Logger.error("数据表定义检查过程中出错", error);
         throw error;
     }
 }

package/docs/README.md

@@ -4,73 +4,80 @@
 
 ## 快速开始
 
-- [Quickstart 快速入门](./quickstart.md) - 5 分钟搭建第一个 API 服务
+- [Quickstart 快速入门](./guide/quickstart.md) - 5 分钟搭建第一个 API 服务
 
 ## 核心概念
 
-| 文档                             | 说明                         |
-| -------------------------------- | ---------------------------- |
-| [API 开发](./api.md)             | API 定义、字段验证、权限控制 |
-| [Table 表结构](./table.md)       | JSON 表定义格式、字段类型    |
-| [Database 数据库](./database.md) | CRUD 操作、事务、批量操作    |
-| [Config 配置](./config.md)       | 配置文件、环境分离           |
+| 文档                                     | 说明                         |
+| ---------------------------------------- | ---------------------------- |
+| [API 开发](./api/api.md)                 | API 定义、字段验证、权限控制 |
+| [Table 表结构](./reference/table.md)     | JSON 表定义格式、字段类型    |
+| [Database 数据库](./plugins/database.md) | CRUD 操作、事务、批量操作    |
+| [Config 配置](./reference/config.md)     | 配置文件、环境分离           |
 
 ## 扩展开发
 
-| 文档                       | 说明           |
-| -------------------------- | -------------- |
-| [Plugin 插件](./plugin.md) | 自定义插件开发 |
-| [Hook 钩子](./hook.md)     | 请求处理钩子   |
-| [Addon 插件包](./addon.md) | 可复用功能模块 |
+| 文档                                 | 说明           |
+| ------------------------------------ | -------------- |
+| [Plugin 插件](./plugins/plugin.md)   | 自定义插件开发 |
+| [Hook 钩子](./hooks/hook.md)         | 请求处理钩子   |
+| [Addon 插件包](./reference/addon.md) | 可复用功能模块 |
+
+常用内置 Hook：
+
+- [cors Hook](./hooks/cors.md)
+- [auth Hook](./hooks/auth.md)
+- [parser Hook](./hooks/parser.md)
+- [rateLimit Hook](./hooks/rateLimit.md)
 
 ## 工具系统
 
-| 文档                             | 说明               |
-| -------------------------------- | ------------------ |
-| [Validator 验证](./validator.md) | 参数验证、正则别名 |
-| [Logger 日志](./logger.md)       | 日志系统配置       |
-| [Cipher 加密](./cipher.md)       | 哈希、签名、JWT    |
-| [Redis 缓存](./redis.md)         | Redis 操作         |
+| 文档                                       | 说明               |
+| ------------------------------------------ | ------------------ |
+| [Validator 验证](./reference/validator.md) | 参数验证、正则别名 |
+| [Logger 日志](./reference/logger.md)       | 日志系统配置       |
+| [Cipher 加密](./plugins/cipher.md)         | 哈希、签名、JWT    |
+| [Redis 缓存](./infra/redis.md)             | Redis 操作         |
 
 ## 命令工具
 
-| 文档                   | 说明                  |
-| ---------------------- | --------------------- |
-| [Sync 同步](./sync.md) | 数据库、API、菜单同步 |
+| 文档                             | 说明                  |
+| -------------------------------- | --------------------- |
+| [Sync 同步](./reference/sync.md) | 数据库、API、菜单同步 |
 
 ## 实战示例
 
-- [Examples 实战示例](./examples.md) - 用户管理、文章管理、文件上传完整示例
+- [Examples 实战示例](./guide/examples.md) - 用户管理、文章管理、文件上传完整示例
 
 ## 文档索引
 
 ### 入门篇
 
-1. **[Quickstart](./quickstart.md)** - 环境准备、项目创建、第一个 API
+1. **[Quickstart](./guide/quickstart.md)** - 环境准备、项目创建、第一个 API
 
 ### 开发篇
 
-2. **[API](./api.md)** - API 路由定义、字段验证、权限控制、响应格式
-3. **[Table](./table.md)** - 表定义格式、字段类型、系统字段、命名规范
-4. **[Database](./database.md)** - 数据库连接、CRUD 操作、事务处理、批量操作
-5. **[Config](./config.md)** - 配置文件结构、环境分离、运行时配置
+2. **[API](./api/api.md)** - API 路由定义、字段验证、权限控制、响应格式
+3. **[Table](./reference/table.md)** - 表定义格式、字段类型、系统字段、命名规范
+4. **[Database](./plugins/database.md)** - 数据库连接、CRUD 操作、事务处理、批量操作
+5. **[Config](./reference/config.md)** - 配置文件结构、环境分离、运行时配置
 
 ### 扩展篇
 
-6. **[Plugin](./plugin.md)** - 插件生命周期、依赖管理、内置插件
-7. **[Hook](./hook.md)** - 钩子执行顺序、洋葱模型、内置钩子
-8. **[Addon](./addon.md)** - Addon 结构、创建发布、命名规范
+6. **[Plugin](./plugins/plugin.md)** - 插件生命周期、依赖管理、内置插件
+7. **[Hook](./hooks/hook.md)** - 钩子执行顺序、洋葱模型、内置钩子
+8. **[Addon](./reference/addon.md)** - Addon 结构、创建发布、命名规范
 
 ### 工具篇
 
-9. **[Validator](./validator.md)** - 验证规则、类型转换、正则别名
-10. **[Logger](./logger.md)** - 日志级别、文件轮转、测试 Mock
-11. **[Cipher](./cipher.md)** - 哈希算法、HMAC 签名、密码加密、JWT 令牌
-12. **[Redis](./redis.md)** - 缓存操作、键值存储、过期管理
+9. **[Validator](./reference/validator.md)** - 验证规则、类型转换、正则别名
+10. **[Logger](./reference/logger.md)** - 日志级别、文件轮转、测试 Mock
+11. **[Cipher](./plugins/cipher.md)** - 哈希算法、HMAC 签名、密码加密、JWT 令牌
+12. **[Redis](./infra/redis.md)** - 缓存操作、键值存储、过期管理
 
 ### 运维篇
 
-13. **[Sync](./sync.md)** - syncDb、syncApi、syncMenu、syncDev 命令
+13. **[Sync](./reference/sync.md)** - syncDb、syncApi、syncMenu、syncDev 命令
 
 ## 常用链接