befly 3.9.38 → 3.9.40

package/docs/{addon.md → reference/addon.md}

@@ -1,4 +1,4 @@
-# Addon 插件包开发
+# Addon 插件包开发
 
 > 可复用的功能模块，包含 API、表、插件、视图
 
@@ -59,11 +59,9 @@ Addon 是 Befly 的可复用功能模块，一个 Addon 可以包含：
 │   └── email.ts             # 邮件插件
 ├── views/                   # 前端视图
 │   ├── login_1/             # 登录页
-│   │   ├── login.vue
-│   │   └── meta.json
+│   │   └── index.vue
 │   └── permission/          # 权限管理
-│       ├── permission.vue
-│       └── meta.json
+│       └── index.vue
 ├── styles/                  # 样式文件
 │   └── variables.scss
 ├── package.json             # 包配置
@@ -92,7 +90,8 @@ Addon 是 Befly 的可复用功能模块，一个 Addon 可以包含：
     "files": ["apis", "plugins", "styles", "tables", "views", "package.json", "README.md"],
     "keywords": ["befly", "addon"],
     "dependencies": {
-        "befly-shared": "^1.2.0"
+        "befly": "^3.9.0",
+        "befly-vite": "^1.1.0"
     }
 }
 ```
@@ -127,14 +126,14 @@ bun init
 `apis/hello/world.ts`：
 
 ```typescript
-import type { ApiRoute } from 'befly/types/api.js';
+import type { ApiRoute } from "befly/types/api";
 
 export default {
-    name: 'Hello World',
-    method: 'GET',
+    name: "Hello World",
+    method: "GET",
     auth: false,
     handler: async (befly, ctx) => {
-        return Yes('Hello from my-addon!');
+        return Yes("Hello from my-addon!");
     }
 } as ApiRoute;
 ```
@@ -216,7 +215,7 @@ bun add @befly-addon/admin
 
 ```typescript
 // main.ts 或 vite.config.js
-import '@befly-addon/admin/styles/variables.scss';
+import "@befly-addon/admin/styles/variables.scss";
 ```
 
 ---
@@ -267,29 +266,29 @@ apis/
 ### API 定义示例
 
 ```typescript
-import type { ApiRoute } from 'befly/types/api.js';
+import type { ApiRoute } from "befly/types/api";
 
 export default {
-    name: '管理员登录',
-    method: 'POST',
+    name: "管理员登录",
+    method: "POST",
     auth: false,
-    desc: '管理员邮箱密码登录',
+    desc: "管理员邮箱密码登录",
     fields: {
-        email: { name: '邮箱', type: 'string', min: 5, max: 100, regexp: '@email' },
-        password: { name: '密码', type: 'string', min: 6, max: 100 }
+        email: { name: "邮箱", type: "string", min: 5, max: 100, regexp: "@email" },
+        password: { name: "密码", type: "string", min: 6, max: 100 }
     },
-    required: ['email', 'password'],
+    required: ["email", "password"],
     handler: async (befly, ctx) => {
         // 使用 addon 表时需要完整表名
         const admin = await befly.db.getDetail({
-            table: 'addon_admin_admin',
-            columns: ['id', 'email', 'password', 'nickname'],
+            table: "addon_admin_admin",
+            columns: ["id", "email", "password", "nickname"],
             where: { email: ctx.body.email }
         });
 
         // ... 业务逻辑
 
-        return Yes('登录成功', { token: token });
+        return Yes("登录成功", { token: token });
     }
 } as ApiRoute;
 ```
@@ -325,8 +324,8 @@ export default {
 ```typescript
 // 使用完整表名
 await befly.db.getList({
-    table: 'addon_admin_role', // addon_{name}_{table}
-    columns: ['id', 'name', 'code']
+    table: "addon_admin_role", // addon_{name}_{table}
+    columns: ["id", "name", "code"]
 });
 ```
 
@@ -339,7 +338,7 @@ await befly.db.getList({
 `plugins/email.ts`：
 
 ```typescript
-import type { Plugin } from 'befly/types/plugin.js';
+import type { Plugin } from "befly/types/plugin";
 
 export interface EmailConfig {
     host: string;
@@ -349,9 +348,9 @@ export interface EmailConfig {
 }
 
 const emailPlugin: Plugin = {
-    after: ['config'], // 依赖 config 插件
+    after: ["config"], // 依赖 config 插件
     async handler(befly) {
-        const config = befly.config.get('email') as EmailConfig;
+        const config = befly.config.get("email") as EmailConfig;
 
         return {
             async send(to: string, subject: string, html: string) {
@@ -375,10 +374,10 @@ export default emailPlugin;
 ```typescript
 // 在 API 中使用
 export default {
-    name: '发送邮件',
+    name: "发送邮件",
     handler: async (befly, ctx) => {
-        await befly.email.send(ctx.body.to, '欢迎注册', '<h1>欢迎使用</h1>');
-        return Yes('发送成功');
+        await befly.email.send(ctx.body.to, "欢迎注册", "<h1>欢迎使用</h1>");
+        return Yes("发送成功");
     }
 } as ApiRoute;
 ```
@@ -392,27 +391,28 @@ export default {
 ```
 views/
 ├── login_1/              # 使用 layout 1
-│   ├── login.vue         # 页面组件
-│   └── meta.json         # 菜单配置
+│   └── index.vue         # 页面组件（definePage 声明菜单元信息）
 ├── permission/
-│   ├── permission.vue
-│   ├── meta.json
+│   ├── index.vue
 │   ├── role/             # 子菜单
-│   │   ├── role.vue
-│   │   └── meta.json
+│   │   └── index.vue
 │   └── menu/
-│       ├── menu.vue
-│       └── meta.json
+│       └── index.vue
 ```
 
-### meta.json 配置
+### definePage(meta) 配置
 
-```json
-{
-    "name": "权限管理",
-    "icon": "Shield",
-    "sort": 10
-}
+在 `views/**/index.vue` 中使用 `definePage()` 声明菜单元信息：
+
+```vue
+<script setup>
+definePage({
+    meta: {
+        title: "权限管理",
+        order: 10
+    }
+});
+</script>
 ```
 
 ### 目录命名规则
@@ -474,8 +474,8 @@ A: 使用 `befly sync:db` 命令，会自动同步所有 Addon 的表定义。
 A: 通过 `befly.config` 访问：
 
 ```typescript
-const dbConfig = befly.config.get('db');
-const customConfig = befly.config.get('myAddon');
+const dbConfig = befly.config.get("db");
+const customConfig = befly.config.get("myAddon");
 ```
 
 ### Q: Addon 之间可以互相依赖吗？

package/docs/{config.md → reference/config.md}

@@ -24,9 +24,8 @@
     - [环境变量](#环境变量)
     - [完整配置示例](#完整配置示例)
         - [befly.common.json](#beflycmmonjson)
-        - [befly.dev.json](#befldevjson)
-        - [befly.prod.json](#beflprodjson)
-        - [befly.local.json](#befllocaljson)
+        - [befly.development.json](#beflydevelopmentjson)
+        - [befly.production.json](#beflyproductionjson)
     - [访问配置](#访问配置)
     - [最佳实践](#最佳实践)
     - [常见问题](#常见问题)
@@ -54,16 +53,16 @@ Befly 配置系统采用分层配置设计，支持环境分离和本地覆盖
 配置文件存放在项目根目录的 `configs/` 目录下：
 
 ```
-项目根目录/
+// befly.development.json
 └── configs/
     ├── befly.common.json   # 通用配置（所有环境共享）
-    ├── befly.dev.json      # 开发环境配置
-    ├── befly.prod.json     # 生产环境配置
-    └── befly.local.json    # 本地配置（不提交到 Git）
+    ├── befly.development.json  # 开发环境配置
+    └── befly.production.json   # 生产环境配置
 ```
 
 ### 加载优先级
 
+// befly.production.json
 配置按以下顺序加载，后加载的覆盖先加载的：
 
 ```
@@ -71,15 +70,13 @@ Befly 配置系统采用分层配置设计，支持环境分离和本地覆盖
     ↓
 befly.common.json（通用配置）
     ↓
-befly.dev.json 或 befly.prod.json（环境配置）
-    ↓
-befly.local.json（本地配置，最高优先级）
+befly.development.json 或 befly.production.json（环境配置）
 ```
 
 **环境判断**：
 
-- `NODE_ENV=production` → 加载 `befly.prod.json`
-- 其他情况 → 加载 `befly.dev.json`
+- `NODE_ENV=production` → 加载 `befly.production.json`
+- 其他情况 → 加载 `befly.development.json`
 
 ### 合并规则
 
@@ -95,7 +92,7 @@ befly.local.json（本地配置，最高优先级）
     }
 }
 
-// befly.local.json
+// befly.development.json
 {
     "db": {
         "password": "local_password"
@@ -393,7 +390,7 @@ NODE_ENV=production bun run start
 }
 ```
 
-### befly.dev.json
+### befly.development.json
 
 开发环境配置：
 
@@ -418,7 +415,7 @@ NODE_ENV=production bun run start
 }
 ```
 
-### befly.prod.json
+### befly.production.json
 
 生产环境配置：
 
@@ -443,51 +440,13 @@ NODE_ENV=production bun run start
 }
 ```
 
-### befly.local.json
-
-本地配置（不提交到 Git）：
-
-```json
-{
-    "db": {
-        "password": "my_local_password"
-    },
-
-    "redis": {
-        "password": "my_redis_password"
-    },
-
-    "auth": {
-        "secret": "my-super-secret-key-for-local-development"
-    },
-
-    "addons": {
-        "admin": {
-            "email": {
-                "user": "my-email@qq.com",
-                "pass": "my-auth-code"
-            }
-        }
-    }
-}
-```
-
-**注意**：将 `befly.local.json` 添加到 `.gitignore`：
-
-```gitignore
-# 本地配置
-configs/befly.local.json
-```
-
----
-
 ## 访问配置
 
 ### 在 API 中访问
 
 ```typescript
 export default {
-    name: '示例接口',
+    name: "示例接口",
     handler: async (befly, ctx) => {
         // 通过 befly.config 访问配置
         const appName = befly.config.appName;
@@ -497,7 +456,7 @@ export default {
         // 访问 Addon 配置
         const emailConfig = befly.config.addons?.admin?.email;
 
-        return befly.tool.Yes('成功', { appName: appName });
+        return befly.tool.Yes("成功", { appName: appName });
     }
 };
 ```
@@ -505,7 +464,7 @@ export default {
 ### 在插件中访问
 
 ```typescript
-import { beflyConfig } from '../befly.config.js';
+import { beflyConfig } from "../befly.config.js";
 
 const plugin: Plugin = {
     handler: () => {
@@ -516,10 +475,15 @@ const plugin: Plugin = {
 };
 ```
 
-### 直接导入
+### 直接导入（仅 Befly 源码/单仓内）
+
+> 说明：`befly` 包的 `exports` 仅暴露 `befly`、`befly/lib/*`、`befly/utils/*`、`befly/types/*`。
+> 因此不支持 `befly/befly.config` 这种子路径导入。
+
+如果你在 Befly 源码/单仓内开发（例如编写内置插件/命令），可以使用相对路径导入：
 
 ```typescript
-import { beflyConfig } from 'befly/befly.config';
+import { beflyConfig } from "../befly.config.js";
 
 console.log(beflyConfig.appName);
 ```
@@ -528,31 +492,21 @@ console.log(beflyConfig.appName);
 
 ## 最佳实践
 
-### 1. 敏感信息放 local 配置
+### 1. 敏感信息使用环境变量
 
-```json
-// ✅ befly.local.json（不提交）
-{
-    "db": { "password": "real_password" },
-    "auth": { "secret": "real_secret" },
-    "redis": { "password": "real_password" }
-}
+不建议在 `configs/*.json` 中保存明文密码/密钥（这些文件通常会被提交）。
 
-// ❌ befly.common.json（会提交）
-{
-    "db": { "password": "real_password" }
-}
-```
+推荐做法：通过环境变量注入敏感信息（本地用 `.env`，部署用平台的 Secret/环境变量管理）。
 
 ### 2. 环境差异放环境配置
 
 ```json
-// befly.dev.json
+// befly.development.json
 {
     "logger": { "debug": 1, "console": 1 }
 }
 
-// befly.prod.json
+// befly.production.json
 {
     "logger": { "debug": 0, "console": 0 }
 }
@@ -583,7 +537,7 @@ console.log(beflyConfig.appName);
 ### 5. 生产环境关闭调试
 
 ```json
-// befly.prod.json
+// befly.production.json
 {
     "logger": {
         "debug": 0,
@@ -607,16 +561,14 @@ console.log(beflyConfig.appName);
 
 ```typescript
 // 在 API 中打印
-befly.logger.info({ config: befly.config }, '当前配置');
+befly.logger.info({ config: befly.config }, "当前配置");
 ```
 
 ### Q3: local 配置被提交了？
 
-添加到 `.gitignore`：
+不再使用“本地覆盖配置文件”。
 
-```gitignore
-configs/befly.local.json
-```
+如果你发现敏感配置被提交：请改为环境变量注入，并在仓库层面避免提交 `.env`、密钥文件等。
 
 ### Q4: 如何动态修改配置？
 
@@ -630,7 +582,7 @@ configs/befly.local.json
 // befly.common.json
 { "disableHooks": ["hook1"] }
 
-// befly.local.json
+// befly.production.json
 { "disableHooks": ["hook2"] }
 
 // 最终结果