README

用户、钱包与渠道来源（2026-09-25）

生成器的用户登录接口与财务接口已接入框架统一封装。业务代码继续调用 DbsUser、DbsBalance、DbsPoints、DbsAccount，无需读取公众号配置或自行拼接来源字段。

use App\Facades\DbsAccount;
use App\Facades\DbsBalance;
use App\Facades\DbsPoints;

$wallet = DbsAccount::wallet($userId); // 一条 SQL 返回可用余额、可用积分及各自冻结额
DbsPoints::give($userId, 10, [
    'order_no' => $businessNo, 'source_identifier' => 'daily_reward', 'desc' => '签到奖励',
]);
DbsBalance::pay($userId, 19.90, ['order_no' => $orderNo, 'desc' => '购买商品']);
$hold = DbsAccount::freeze($userId, 'points', 20, [
    'order_no' => $orderNo, 'source_identifier' => 'points_reservation',
]);
DbsAccount::completeFrozen($hold['record_id']); // 原来源保留，仅扣积分
// 取消时使用 DbsAccount::cancelFrozen($hold['record_id'])，不扣款。

微信登录成功后，框架把已验证的应用、平台、渠道写入服务端令牌；后续请求自动沿用。本次交易来源与用户注册平台是不同概念，不能用 users.platform_code 推断交易来源。已有令牌无来源时保留未记录状态，重新登录后获得完整来源。
financial_records 新增 application_key、platform_code、channel_code、identity_type 和 account_origin 快照。快照包含平台名称、渠道名称、操作入口及操作人，身份表示入账账户的身份。source/source_identifier 继续表示业务来源和幂等标识，与渠道字段并存。
来源仅来自服务端路由、框架验证过的登录上下文及令牌，不读取请求参数中的来源字段，也不接受 metadata 覆盖。不要把客户端请求原样作为账务参数。
后台调整记录为 admin，普通未归属平台的 API 为 api，任务为 console，已验证平台入口为 platform；未记录平台时保持空值。历史流水不猜测、不批量补造渠道。
同一 users.id 的余额及积分按平台和应用隔离，后台单方设置并自动同步双方的共享范围由框架统一计算。生成的插件财务后台同时限定来源应用和已声明身份，避免相同身份的其他应用流水混入；无来源的历史流水仍由框架总后台查询核对。
入账/出账汇总仅计算 completed；冻结额单独计算，取消冻结不计入支出。冻结与正常扣款统一先锁用户，积分必须是整数，余额最多两位小数。
需要重试的业务必须提供稳定的 order_no 和 source_identifier。同一应用、来源、来源标识、订单号、账户类型、事件类型组成幂等键，新流水有数据库唯一索引兜底；金额或用户不一致拒绝。不同应用可使用相同订单号。冻结确认/取消只能执行一次，不会自动重建已取消的预留。

后台任务没有登录令牌时，框架可从插件类识别应用。需要明确归属某个平台的异步业务，使用服务端已保存的订单来源建立作用域：

use App\Support\AccountOrigin;

AccountOrigin::run($applicationKey, $platformCode, $identityType, function () use ($userId, $orderNo) {
    DbsPoints::give($userId, 10, ['order_no' => $orderNo, 'source_identifier' => 'order_reward']);
});

三个来源参数必须取自服务端订单/任务，不接受客户端声明；平台会校验应用绑定及身份，作用域结束自动恢复。纯后台任务没有平台时传 null，不伪装成公众号交易。

升级时先执行 2026_09_25_000003_add_account_origin.php，再启用代码；自定义认证模型使用 App\Support\Concerns\HasChannelTokens，继承框架 User 则自动生效。模板升级不会自动覆盖旧插件业务。本次已适配商城统一账号和班级应用登录，班费独立账簿也追加来源快照，不转换为个人钱包流水。旧登录票据需重新扫码。

商城公众号登录必须在商城登录设置的 login_methods.wechat_platform_code 中明确选择；未选择、平台禁用或未关联商城时不可用，不退回全局配置、唯一平台或第一条公众号。平台列表不展示“可用身份”，编辑表单仍保留每个应用的身份白名单。

dbs-admin 是大巴山开源系统的后台开发 Composer 包，提供常用管理功能、资源生成命令和 Vue 页面模板，帮助开发者搭建与扩展业务后台。

本包需要集成到大巴山开源系统中使用；页面模板依赖系统的前端组件与构建配置，不能单独部署为完整管理站点。

主要功能

后台列表、表单、详情及常用操作组件。
控制器、模型、页面等资源的脚手架生成。
插件骨架、业务页面及配置管理支持。
用户、角色、菜单、附件与操作日志等基础能力。
页面通知、系统设置读写与任务进度管理。
配套页面模板及移动端样式支持。

大巴山开源系统另提供邮件、短信通知等业务功能，调用方式见下文。

环境要求

项目	要求
PHP	8.2 及以上，兼容 PHP 8.x
配套项目	大巴山开源系统
Composer	2.x
前端	大巴山开源系统中的 `web/` 目录（Vue 3）及配套组件

数据库、缓存、认证及前端依赖由大巴山开源系统统一配置。

安装与使用

在大巴山开源系统项目根目录执行（需已配置本包可用的包源）：

composer require dabashan/dbs-admin

web/ 是大巴山开源系统项目根目录下的前端目录，不在 dbs-admin 包内。需要发布界面资源时，仍在系统项目根目录执行：

php artisan vendor:publish --tag=dbs-admin-ui

安装后按下文生成业务页面或插件，完成字段、路由与权限配置，再执行数据库迁移和系统前端构建。

配套运行组件随包提供，支持 Linux 和 macOS 的 amd64、arm64 平台，系统会选择匹配版本，无需自行编译。

常用功能

生成业务页面

在大巴山开源系统项目根目录执行：

php artisan make:admin Category --migration

默认生成模型、控制器和前端页面等资源。按命令输出补齐模型字段、表单校验、菜单与路由，再执行迁移和前端构建。也可在后台「代码生成器」中配置资源，预览后生成。

常用选项	用途
`--migration`	同时生成数据库迁移
`--controller`	仅生成控制器
`--vue`	仅生成前端页面
`--no-web`	不生成前端资源
`--table=admin_categories`	指定数据表

列表、表单与详情

在生成的控制器中调整 grid()、form() 和 detail()。以下示例使用 Category 模型，数据表需包含 name 字段：

use App\Admin\Models\Category;
use Dabashan\DbsAdmin\Controllers\AdminController;
use Dabashan\DbsAdmin\Form\Form;
use Dabashan\DbsAdmin\Grid\Grid;
use Dabashan\DbsAdmin\Show\Show;

class CategoryController extends AdminController
{
    protected string $model = Category::class;

    protected function grid(): Grid
    {
        return Grid::make(Category::query())
            ->column('id', 'ID')->sortable()
            ->column('name', '名称')
            ->filter('name', '名称')
            ->perPage(15);
    }

    protected function form(): Form
    {
        return Form::make()
            ->text('name', '名称')->required()->rules('max:100');
    }

    protected function detail($id): Show
    {
        return Show::make(Category::findOrFail($id))
            ->text('id', 'ID')
            ->text('name', '名称');
    }
}

表单还可使用 textarea()、select()->options()、image() 和 switch() 等字段。模型中需配置可写字段，菜单权限通过配套后台管理。

页面提示

用于后台操作后的成功、警告或错误提示：

use Dabashan\DbsAdmin\Notifications\Notification;

Notification::make('保存成功')
    ->body('分类信息已更新')
    ->success()
    ->duration(3000)
    ->send();

可将 success() 换成 info()、warning() 或 error()，duration() 单位为毫秒。此方式需要系统启用 Session；通知会在后续列表请求中返回，由配套列表组件显示。自定义页面可通过 Notification::pull() 读取待显示通知，读取后即清空。

邮件与短信通知（大巴山开源系统）

先在后台「消息通知」配置并启用通道，使用测试发送确认配置，再在业务代码中调用 DbsMessage。该入口由大巴山开源系统提供，单独安装本包不会包含此服务。

发送邮件：

use App\Facades\DbsMessage;

$log = DbsMessage::emailHtml(
    to: 'user@example.com',
    subject: '处理完成',
    html: '<p>您提交的资料已处理完成。</p>',
    module: '业务通知'
);

申请验证码：

use App\Facades\DbsMessage;

$challenge = DbsMessage::requestVerification(
    to: 'user@example.com',
    channel: 'email',
    event: '身份验证',
    module: '会员中心'
);

短信验证码使用 channel: 'sms'，并将 to 改为接收手机号。用户提交验证码后，调用 DbsMessage::confirmVerification($token, $code)，其中 $token 为申请结果的 token；业务接口需将验证凭证与当前用户、操作绑定。发送记录可在后台查看。当前短信通道仅用于验证码。

本地插件与页面

php artisan make:plugin demo_plugin
php artisan make:plugin-page demo_plugin Product --migration --vue

插件生成在大巴山开源系统项目根目录下的 plugins/ 目录中。按照生成文件完善字段、页面和菜单配置，再执行所需迁移与前端构建。本地插件可与市场插件同时使用；创建时如提示标识已占用，请更换标识。

修改本地插件配置后同步：

php artisan plugin:sync-manifest demo_plugin --local

需要交付插件时打包：

php artisan plugin:package demo_plugin

打包需要 PHP Zip 扩展，产物默认输出到 storage/app/plugin-packages/。市场插件的安装与更新通过后台插件管理页面操作。

系统设置

在大巴山开源系统中配置好后台设置表后，使用 SettingService 读写设置：

use Dabashan\DbsAdmin\Services\SettingService;

SettingService::set('site_name', '我的管理后台');
$name = SettingService::get('site_name', '管理后台');

get() 的第二个参数为默认值，删除设置使用 SettingService::forget('site_name')。上述示例用于普通展示配置，密钥等凭据使用系统专用配置。

任务进度

耗时操作可用 TaskManager 记录进度，由业务队列或命令执行实际工作：

use Dabashan\DbsAdmin\Tasks\TaskManager;

$task = TaskManager::create();
$taskId = $task['task_id'];

TaskManager::start($taskId);
TaskManager::update($taskId, ['progress' => 50, 'message' => '正在处理']);
TaskManager::finish($taskId, ['count' => 10], '处理完成');

示例各阶段调用应放在实际工作对应的位置。查询进度使用 TaskManager::get($taskId)，失败时调用 TaskManager::fail($taskId, '处理失败')。该工具仅记录状态，不会自动启动队列任务。

管理功能入口

以下功能通过大巴山开源系统后台使用，入口名称以实际菜单为准：

功能	使用方式
用户与角色	创建管理员、分配角色，再配置可访问菜单和操作权限
菜单管理	为业务页面设置名称、路由与排序
附件管理	上传文件、按分组整理，业务表单通过附件字段选择
操作日志	按用户、时间等条件查看操作记录
代码生成器	配置资源与字段，预览文件后生成
插件管理	查看本地与市场插件，按页面提示安装、启用或更新

命令速查

命令	用途
`make:admin <资源名>`	生成后台业务资源
`make:plugin <插件标识>`	创建插件骨架
`make:plugin-page <插件标识> <资源名>`	生成插件业务页面
`plugin:package <插件标识>`	打包插件
`plugin:sync-manifest <插件标识>`	同步插件配置

完整参数使用 php artisan help <命令> 查看，例如 php artisan help make:admin。

目录结构

dbs-admin/
├── src/                 # PHP 源码
│   ├── Commands/        # 脚手架命令
│   ├── Controllers/     # 控制器与管理功能
│   ├── Form/            # 表单组件
│   ├── Grid/            # 列表组件
│   ├── Models/          # 数据模型
│   ├── Providers/       # 服务提供者
│   ├── Services/        # 应用服务与配套运行组件
│   ├── Show/            # 详情组件
│   └── Traits/          # 公共能力
├── stubs/               # 代码与页面模板
├── tests/               # 测试与验证
├── composer.json        # 包信息与依赖声明
└── README.md            # 项目说明

反馈

使用问题或改进建议可通过 GitHub Issues 提交。请提供版本、复现步骤与必要的错误信息，并移除账号、密钥及业务数据。

许可证

本包在 composer.json 中声明采用 Apache-2.0 许可证。第三方依赖与配套项目遵循各自的许可证。

平台与小程序身份接入

H5、微信公众号平台使用 applications 保存多应用及各应用身份白名单；小程序保持单应用。默认身份由插件 config/platform.php 的 default_identity 声明，未声明兼容第一项身份。新生成的用户接入和设置模板统一使用 DbsPlatform::forApplication()，自动校验平台、身份并处理微信登录；渠道设置支持 settings.channel_platforms。公众号路由使用 web/session 和一次性 state，小程序路由接受微信 code，禁止使用客户端自报 OpenID 登录。find-or-create 仅接受当前认证用户的已验证手机号。旧插件不会自动覆盖，请升级现有调用；完整规范见主框架 docs/应用多平台接入.md。小程序 pluginKey 仍来自授权端 Application.key。Go 执行组件由宿主主框架 bootstrap/support/platform/bin 独立交付，本扩展仅通过 dbs_agent.binary 配置调用，不再包含运行文件。标准构建为符号裁剪，不应描述为不可逆加密。

用户、渠道与流水账户（2026-09-26）

users 不保存 balance/points 物理列，兼容属性只读。用户列表模板在 select 后调用 withWalletTotals()，调整余额/积分仍走 DbsAccount 并新增财务流水；禁止生成直接 update/increment 用户金额的代码。金额与冻结按类型、状态汇总，框架账户覆盖索引必须与新代码配套迁移。

用户登录模板保留微信小程序和公众号，新增抖音/支付宝 user/login/channel 及企业微信 OAuth。标识只保存在 user_channels.channel_openid/channel_unionid，不按供应商增加专属列。各平台通过服务端应用作用域选择、验证凭证并绑定，客户端不能声明可信 OpenID。旧插件业务文件不会自动覆盖，需按框架的《用户渠道结构整理》《财务模块使用说明》同步升级。

平台共享规则

平台管理每个插件分别设置共享登录、共享余额、共享积分，默认关闭；余额/积分必须先向同一对象共享登录，登录可单独开启；关闭登录会同步撤销对应资产共享，关闭单项资产不影响登录。主框架无需配置，同名身份不自动打通账号。升级需执行宿主 2026_09_27_010000_require_login_for_asset_sharing 数据清理迁移。生成的用户查询按应用隔离，后台调整财务必须选择平台，微信登录支持服务端 phone_code 验证；用户表不写余额积分。队列任务通过 AccountOrigin::run 使用订单保存的来源。已有同手机号账号不能自动合并，双凭证关联接口由框架提供。完整规则见宿主 docs/平台账号与资产共享.md。

应用会员及等级范围

生成的会员与小黑屋列表按平台设置绑定到当前应用的平台及身份查询，可再筛选平台。共享登录不扩大后台管理范围。等级定义按应用、身份和渠道隔离，用户等级通过宿主 MemberLevelService 保存到 user_level_assignments，不能直接写 users.level_value。用户注册身份只做账号分类，不代替插件角色/认证权限。依赖宿主 2026_09_27_020000_scope_member_levels.php 及对应服务；升级既有生成插件时需同步会员控制器和页面模板。

会员模板的新增与手机号冲突检查复用宿主 DbsUserService / MemberPhone。应用列表排除已删除账号，主框架聚合列表提供统一核验恢复入口；手机号唯一范围保留软删除账号，错误提交保留弹窗内容。删除账号不删除财务及历史业务记录。

标准会员列表模板已改为宿主公共组件的薄入口：PHP 继承 App\Admin\Controllers\ApplicationUserController，Vue 导入 @dbs/core 的 ApplicationUserList。升级脚手架时需同步升级主框架（包括 core 导出和插件构建配置）；公共修复在宿主集中维护，不再复制整套会员控制器与页面。已有外部生成的独立实现不会被远程自动覆盖。

多配置页的 Tab 布局

插件设置页模板采用 Arco 原生线形 Tabs：图标、标题和简短说明组成导航，配置内容位于独立卡片。新增同类配置页可复用 stubs/plugin.settings-vue.stub 中的 workspace-tabs、workspace-tab-title、workspace-panel 结构与 scoped 样式。子级标签使用紧凑的原生线形 Tabs，避免嵌套大导航。

样式使用 Arco 主题变量，窄屏保留原生标签溢出导航；图标采用内联 SVG，不依赖字体或新增组件。保留 v-model:active-key、稳定的 pane key 和页面级表单状态。模板更新仅影响后续生成页面，不批量覆盖已生成页面；不修改全局 .arco-tabs 样式。

页面间距统一由布局提供

后台外层 .layout-content > .arco-layout-content 统一提供页边距：桌面 20px，移动端 12px。普通页面和应用页面的根容器、dbs-crud-page、DynamicCrud 不再添加页面 padding；内嵌 CRUD 同样不承担页边距。卡片内容、表单、弹窗和工具栏内部间距保留。

生成器的普通列表、应用业务页、图表首页、会员/小黑屋、财务和设置页模板均遵循此规则。共享主题覆盖旧页面根节点的重复 padding，主题安装器只定向迁移旧脚手架 .dbs-crud-page 的 18px/12px 规则，保留其余自定义主题内容。

dabashan / dbs-admin

Package info

Security

Statistics