befly-tpl 3.0.1

package/addons/_template/README.md

@@ -0,0 +1,123 @@
+# Befly Addon 模板
+
+这是一个 Befly Addon 的标准模板，以 `_` 开头的目录会被框架自动跳过，不会被加载。
+
+## 目录结构
+
+```
+_template/
+├── README.md           # 本文档
+├── apis/              # API 接口目录
+│   └── example.ts     # 示例接口
+├── checks/            # 检查脚本目录
+│   └── example.ts     # 示例检查
+├── plugins/           # 插件目录
+│   └── example.ts     # 示例插件
+├── tables/            # 表定义目录
+│   └── example.json   # 示例表定义
+├── types/             # 类型定义目录
+│   └── index.d.ts     # 类型定义文件
+└── config/            # 配置目录
+    └── default.ts     # 默认配置文件
+```
+
+## 使用方法
+
+1. 复制此模板目录到 `tpl/addons/` 下
+2. 重命名为你的组件名（小驼峰命名，如 `payment`、`smsService`）
+3. 根据需要删除不需要的子目录
+4. 实现你的功能代码
+
+## 命名规则
+
+### 组件目录名
+
+- 使用小驼峰命名：`payment`、`userCenter`、`smsService`
+- 以 `_` 开头的目录会被跳过：`_template`、`_disabled`
+
+### API 路由
+
+- 自动添加组件名前缀：`/api/{组件名}/{API路径}`
+- 示例：`payment/apis/create.ts` → `POST /api/payment/create`
+
+### 数据库表名
+
+- 自动添加组件名前缀：`{组件名}_{表名}`
+- 示例：`payment/tables/order.json` → `payment_order` 表
+
+### 插件名称
+
+- 自动添加组件名前缀：`{组件名}.{插件名}`
+- 示例：`payment/plugins/alipay.ts` → `payment.alipay` 插件
+
+## 子目录说明
+
+### apis/ - API 接口
+
+存放组件的 HTTP API 接口定义，使用 `Api()` 函数创建。
+
+**特点：**
+
+- 路由自动添加 `/api/{组件名}/` 前缀
+- 可以访问所有已加载的插件
+
+### checks/ - 检查脚本
+
+存放组件的启动检查脚本，在框架启动前执行。
+
+**要求：**
+
+- 必须使用 `export default` 导出函数
+- 函数返回 `true`（通过）或 `false`（失败）
+- 检查失败会阻止框架启动
+
+### plugins/ - 插件
+
+存放组件的插件，用于扩展 befly 对象功能。
+
+**特点：**
+
+- 插件名自动添加组件名前缀
+- 可以注册中间件、扩展 befly 对象等
+- 加载顺序：核心 → addons → 项目
+
+### tables/ - 表定义
+
+存放组件的数据库表定义（JSON 格式）。
+
+**特点：**
+
+- 表名自动添加组件名前缀
+- 使用 `bun syncDb` 自动同步到数据库
+- 支持字段规则定义（类型、长度、默认值等）
+
+### types/ - 类型定义
+
+存放组件的 TypeScript 类型定义。
+
+**建议：**
+
+- 统一导出到 `index.d.ts`
+- 声明全局类型时使用 `declare global`
+
+### config/ - 配置文件
+
+存放组件的配置文件，通常在插件初始化时加载。
+
+**建议：**
+
+- 配置项从环境变量读取
+- 提供合理的默认值
+- 在插件的 `onInit` 中加载配置
+
+## 开发建议
+
+1. **保持独立性**：组件应该是自包含的，尽量减少对其他组件的依赖
+2. **环境变量**：使用 `{ADDON_NAME}_{CONFIG_KEY}` 格式命名
+3. **错误处理**：使用 `Logger` 统一记录错误，关键错误使用 `process.exit(1)` 退出
+4. **日志记录**：使用 `Logger` 记录关键操作
+5. **测试覆盖**：为组件编写测试用例
+
+## 示例
+
+参考 `tpl/addons/demo/` 目录下的完整示例。

package/addons/_template/addon.config.json

@@ -0,0 +1,17 @@
+{
+    "name": "your-addon-name",
+    "title": "你的组件名称",
+    "version": "0.0.1",
+    "description": "组件简短描述",
+    "author": {
+        "name": "作者名称",
+        "email": "author@example.com",
+        "url": "https://example.com"
+    },
+    "repo": "https://github.com/username/repo",
+    "keywords": ["keyword1", "keyword2"],
+    "entry": "index.ts",
+    "enabled": true,
+    "dependencies": {},
+    "license": "MIT"
+}

package/addons/_template/apis/example.ts

@@ -0,0 +1,33 @@
+/**
+ * Addon API 示例
+ * 路由会自动添加组件名前缀：/api/{addonName}/example
+ */
+
+export default {
+    name: '示例接口',
+    auth: false,
+    fields: {
+        name: '名称|string|1|50|null|0|null',
+        age: '年龄|number|1|150|18|0|null'
+    },
+    required: ['name'],
+    handler: async (befly, ctx) => {
+        // 访问组件的插件（如果有）
+        // const myPlugin = befly['addonName.pluginName'];
+
+        // 访问数据库
+        // const result = await befly.db.getOne({
+        //     table: 'addon_addonName_tableName',
+        //     where: { id: 1 }
+        // });
+
+        return {
+            code: 0,
+            msg: '操作成功',
+            data: {
+                name: ctx.body.name,
+                age: ctx.body.age || 18
+            }
+        };
+    }
+};

package/addons/_template/checks/example.ts

@@ -0,0 +1,23 @@
+/**
+ * Addon 检查示例
+ * 在框架启动前执行，用于验证配置、依赖等
+ */
+
+import { Logger } from 'befly';
+
+export default async function (): Promise<boolean> {
+    try {
+        // 检查环境变量配置
+        // const config = process.env.ADDON_NAME_CONFIG;
+        // if (!config) {
+        //     Logger.error('未配置 ADDON_NAME_CONFIG 环境变量');
+        //     return false;
+        // }
+
+        Logger.info('Addon 示例检查通过');
+        return true;
+    } catch (error: any) {
+        Logger.error('Addon 示例检查失败:', error);
+        return false;
+    }
+}

package/addons/_template/config/default.ts

@@ -0,0 +1,12 @@
+/**
+ * Addon 默认配置
+ * 建议从环境变量读取配置
+ */
+
+export default {
+    // 示例配置
+    apiKey: process.env.ADDON_API_KEY || '',
+    apiSecret: process.env.ADDON_API_SECRET || '',
+    timeout: Number(process.env.ADDON_TIMEOUT) || 30000,
+    enabled: process.env.ADDON_ENABLED === 'true'
+};

package/addons/_template/plugins/example.ts

@@ -0,0 +1,39 @@
+/**
+ * Addon 插件示例
+ * 用于扩展 befly 对象功能
+ */
+
+import { Logger } from 'befly';
+
+export default {
+    name: 'example', // 实际插件名会是：{addonName}.example
+    version: '1.0.0',
+    priority: 100, // 优先级（数字越大越先加载）
+
+    /**
+     * 插件加载时执行
+     */
+    async onLoad(befly) {
+        Logger.info('Addon 示例插件加载中...');
+    },
+
+    /**
+     * 插件初始化时执行
+     * 这里可以扩展 befly 对象
+     */
+    async onInit(befly) {
+        // 扩展 befly 对象
+        return {
+            // 添加自定义方法或属性
+            sayHello: (name: string) => {
+                return `Hello, ${name}!`;
+            },
+
+            // 添加配置
+            config: {
+                apiKey: process.env.ADDON_API_KEY || '',
+                timeout: 30000
+            }
+        };
+    }
+} as BeflyPlugin;

package/addons/_template/tables/example.json

@@ -0,0 +1,7 @@
+{
+    "name": "名称|string|1|100|null|1|null",
+    "age": "年龄|number|1|150|18|0|null",
+    "email": "邮箱|string|5|100|null|1|^[\\w\\.-]+@[\\w\\.-]+\\.\\w+$",
+    "status": "状态|string|1|20|active|1|^(active|inactive|pending)$",
+    "createdAt": "创建时间|number|0|9999999999999|0|1|null"
+}

package/addons/_template/types/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Addon 类型定义
+ */
+
+declare global {
+    namespace Befly {
+        interface Context {
+            // 扩展 befly 对象的类型
+            // 示例：如果插件名是 payment.alipay
+            // 'payment.alipay'?: {
+            //     createOrder: (params: any) => Promise<string>;
+            //     config: {
+            //         appId: string;
+            //         timeout: number;
+            //     };
+            // };
+        }
+    }
+}
+
+export {};

package/addons/admin/README.md

@@ -0,0 +1,179 @@
+# Admin 管理后台插件
+
+## 功能说明
+
+提供管理后台的基础功能,包括:
+
+-   管理员注册
+-   管理员登录(支持邮箱和手机号两种方式)
+-   发送短信验证码
+-   获取用户信息
+-   退出登录
+
+## API 接口
+
+所有接口路由前缀: `/api/admin/`
+
+### 1. 注册接口
+
+**路由**: `POST /api/admin/register`
+
+**请求参数**:
+
+```json
+{
+    "name": "管理员姓名",
+    "email": "admin@example.com",
+    "password": "密码(至少6位)"
+}
+```
+
+**响应**:
+
+```json
+{
+    "code": 0,
+    "msg": "注册成功",
+    "data": {
+        "id": 1,
+        "name": "管理员姓名",
+        "email": "admin@example.com"
+    }
+}
+```
+
+### 2. 登录接口
+
+**路由**: `POST /api/admin/login`
+
+**邮箱登录**:
+
+```json
+{
+    "email": "admin@example.com",
+    "password": "密码"
+}
+```
+
+**手机号登录**:
+
+```json
+{
+    "phone": "13800138000",
+    "code": "验证码"
+}
+```
+
+**响应**:
+
+```json
+{
+    "code": 0,
+    "msg": "登录成功",
+    "data": {
+        "token": "JWT Token",
+        "userInfo": {
+            "id": 1,
+            "name": "管理员姓名",
+            "email": "admin@example.com",
+            "role": "admin",
+            "status": 1
+        }
+    }
+}
+```
+
+### 3. 发送短信验证码
+
+**路由**: `POST /api/admin/sendSmsCode`
+
+**请求参数**:
+
+```json
+{
+    "phone": "13800138000"
+}
+```
+
+**响应**:
+
+```json
+{
+    "code": 0,
+    "msg": "验证码已发送",
+    "data": {
+        "code": "123456" // 仅开发环境返回
+    }
+}
+```
+
+### 4. 获取用户信息
+
+**路由**: `GET /api/admin/userInfo`
+
+**请求头**:
+
+```
+Authorization: Bearer {token}
+```
+
+**响应**:
+
+```json
+{
+    "code": 0,
+    "msg": "获取成功",
+    "data": {
+        "id": 1,
+        "name": "管理员姓名",
+        "email": "admin@example.com",
+        "role": "admin",
+        "status": 1
+    }
+}
+```
+
+### 5. 退出登录
+
+**路由**: `POST /api/admin/logout`
+
+**请求头**:
+
+```
+Authorization: Bearer {token}
+```
+
+**响应**:
+
+```json
+{
+    "code": 0,
+    "msg": "退出成功",
+    "data": null
+}
+```
+
+## 数据库表
+
+### admin_admin 表
+
+| 字段            | 类型                 | 说明                |
+| --------------- | -------------------- | ------------------- |
+| id              | int                  | 主键 ID             |
+| name            | varchar(50)          | 姓名                |
+| email           | varchar(100)         | 邮箱                |
+| phone           | varchar(20)          | 手机号              |
+| password        | varchar(255)         | 密码(加密)          |
+| role            | enum('admin','user') | 角色                |
+| status          | tinyint(1)           | 状态(1-启用 0-禁用) |
+| last_login_time | datetime             | 最后登录时间        |
+| last_login_ip   | varchar(50)          | 最后登录 IP         |
+| created_at      | datetime             | 创建时间            |
+| updated_at      | datetime             | 更新时间            |
+
+## 注意事项
+
+1. 短信验证码功能需要配置短信服务提供商
+2. 建议在生产环境配置 Redis 来存储验证码和 token 黑名单
+3. 密码使用 bcrypt 加密存储
+4. Token 有效期默认为 7 天

package/addons/admin/addon.config.json

@@ -0,0 +1,13 @@
+{
+    "name": "admin",
+    "title": "管理后台",
+    "version": "1.0.0",
+    "description": "提供管理后台的基础功能，包括管理员注册、登录、用户信息管理等",
+    "author": {
+        "name": "Befly Team"
+    },
+    "keywords": ["admin", "backend", "management"],
+    "entry": "index.ts",
+    "enabled": true,
+    "license": "MIT"
+}

package/addons/admin/apis/adminDel.ts

@@ -0,0 +1,37 @@
+/**
+ * 删除管理员
+ */
+
+import { Yes, No, Fields } from 'befly';
+
+export default {
+    name: '删除管理员',
+    fields: {
+        id: Fields._id
+    },
+    required: ['id'],
+    handler: async (befly, ctx) => {
+        // 检查管理员是否存在
+        const admin = await befly.db.getOne({
+            table: 'addon_admin_admin',
+            where: { id: ctx.body.id }
+        });
+
+        if (!admin) {
+            return No('管理员不存在');
+        }
+
+        // 不能删除 dev 角色的管理员
+        if (admin.roleCode === 'dev') {
+            return No('不能删除开发者账号');
+        }
+
+        // 删除管理员
+        await befly.db.delData({
+            table: 'addon_admin_admin',
+            where: { id: ctx.body.id }
+        });
+
+        return Yes('删除成功');
+    }
+};

package/addons/admin/apis/adminInfo.ts

@@ -0,0 +1,50 @@
+/**
+ * 获取用户信息接口
+ *
+ * @returns 返回 admin 表的字段（不含 password）以及关联的角色信息（小驼峰格式）:
+ *  - id, name, email, phone, roleId, roleCode, state
+ *  - lastLoginTime, lastLoginIp
+ *  - createdAt, updatedAt
+ *  - role: 角色完整信息（包含 menus 和 apis 权限）
+ */
+
+import { Yes, No } from 'befly';
+
+export default {
+    name: '获取用户信息',
+    handler: async (befly, ctx) => {
+        // 从 JWT token 中获取用户ID
+        const userId = ctx.user?.id;
+
+        if (!userId) {
+            return No('未授权');
+        }
+
+        // 查询用户信息（框架自动转换为小驼峰）
+        const admin = await befly.db.getOne({
+            table: 'addon_admin_admin',
+            where: { id: userId }
+        });
+
+        if (!admin) {
+            return No('用户不存在');
+        }
+
+        // 查询角色信息（使用 roleCode 而非 roleId，框架自动转换为小驼峰）
+        let roleInfo = null;
+        if (admin.roleCode) {
+            roleInfo = await befly.db.getOne({
+                table: 'addon_admin_role',
+                where: { code: admin.roleCode }
+            });
+        }
+
+        // 返回用户信息（不包含密码，字段已是小驼峰格式）
+        const { password: _, ...userWithoutPassword } = admin;
+
+        return Yes('获取成功', {
+            ...userWithoutPassword,
+            role: roleInfo
+        });
+    }
+};

package/addons/admin/apis/adminIns.ts

@@ -0,0 +1,70 @@
+/**
+ * 添加管理员
+ */
+
+import { Yes, No, Fields, Crypto2 } from 'befly';
+import adminTable from '../tables/admin.json';
+
+export default {
+    name: '添加管理员',
+    fields: {
+        username: adminTable.username,
+        email: adminTable.email,
+        password: adminTable.password,
+        name: adminTable.name,
+        nickname: adminTable.nickname,
+        phone: adminTable.phone,
+        roleId: adminTable.roleId,
+        roleCode: adminTable.roleCode,
+        roleType: adminTable.roleType
+    },
+    required: ['username', 'email', 'password'],
+    handler: async (befly, ctx) => {
+        // 检查用户名是否已存在
+        if (ctx.body.username) {
+            const existingByUsername = await befly.db.getOne({
+                table: 'addon_admin_admin',
+                where: { username: ctx.body.username }
+            });
+
+            if (existingByUsername) {
+                return No('用户名已被使用');
+            }
+        }
+
+        // 检查邮箱是否已存在
+        const existingByEmail = await befly.db.getOne({
+            table: 'addon_admin_admin',
+            where: { email: ctx.body.email }
+        });
+
+        if (existingByEmail) {
+            return No('邮箱已被使用');
+        }
+
+        // 加密密码
+        const hashedPassword = await Crypto2.hashPassword(ctx.body.password);
+
+        // 创建管理员
+        const adminId = await befly.db.insData({
+            table: 'addon_admin_admin',
+            data: {
+                username: ctx.body.username,
+                email: ctx.body.email,
+                password: hashedPassword,
+                name: ctx.body.name,
+                nickname: ctx.body.nickname,
+                phone: ctx.body.phone,
+                roleId: ctx.body.roleId || 0,
+                roleCode: ctx.body.roleCode || '',
+                roleType: ctx.body.roleType || 'user'
+            }
+        });
+
+        return Yes('添加成功', {
+            id: adminId,
+            username: ctx.body.username,
+            email: ctx.body.email
+        });
+    }
+};

package/addons/admin/apis/adminList.ts

@@ -0,0 +1,24 @@
+/**
+ * 获取管理员列表
+ */
+
+import { Yes, Fields } from 'befly';
+
+export default {
+    name: '获取管理员列表',
+    fields: {
+        page: Fields.page,
+        limit: Fields.limit
+    },
+    handler: async (befly, ctx) => {
+        // 查询所有管理员（框架自动排除password字段，自动转换字段名为小驼峰）
+        const result = await befly.db.getList({
+            table: 'addon_admin_admin',
+            page: ctx.body.page || 1,
+            limit: ctx.body.limit || 10,
+            orderBy: ['createdAt#DESC']
+        });
+
+        return Yes('获取成功', result);
+    }
+};

package/addons/admin/apis/adminRoleDetail.ts

@@ -0,0 +1,38 @@
+/**
+ * 获取管理员的角色（单角色模式）
+ */
+
+import { Yes, No, Fields } from 'befly';
+
+export default {
+    name: '获取管理员角色',
+    fields: {
+        adminId: Fields._id
+    },
+    handler: async (befly, ctx) => {
+        // 查询管理员信息（框架自动转换为小驼峰）
+        const admin = await befly.db.getOne({
+            table: 'addon_admin_admin',
+            where: { id: ctx.body.adminId }
+        });
+
+        if (!admin) {
+            return No('管理员不存在');
+        }
+
+        // 如果有角色编码，查询角色详细信息（使用 roleCode 而非 roleId）
+        let roleInfo = null;
+        if (admin.roleCode) {
+            roleInfo = await befly.db.getOne({
+                table: 'addon_admin_role',
+                where: { code: admin.roleCode }
+            });
+        }
+
+        return Yes('操作成功', {
+            roleId: admin.roleId,
+            roleCode: admin.roleCode,
+            role: roleInfo
+        });
+    }
+};