onezan-admin 快速开发框架

技术栈

项目遵循前后端分离架构，服务端接管业务逻辑与数据持久化，管理后台负责页面渲染与交互，两端通过 RESTful API 通信。以下版本号为系统最低要求，生产环境建议采用更新版本以保证安全与性能。

目录结构

下面展示的是项目完整目录结构，所有开发都应围绕这套结构展开。

前端规范

前端的首要目标是让新增页面与框架内置页面保持同一套 UI、布局、按钮、弹窗、提示和交互风格。

命名惯例

页面范式

1. 简单 CRUD：列表页 + 弹窗
2. 字段较多：列表页 + edit.vue 独立编辑页
3. 在线配置：顶部说明 + 可编辑表格 + 统一保存按钮
4. 详情展示：抽屉或描述列表，不额外引入陌生交互

行业设置页

行业应用可通过 menus.json 将设置页菜单自动注入到"系统设置"二级菜单下，无需修改核心框架代码。

路由模板

// admin/src/applications/{industry}/router/settings.ts
import type { RouteRecordRaw } from 'vue-router';
import Layout from '@/layouts/index.vue';

export default [
  {
    path: '/{industry}/settings',
    name: 'IndustrySettings',
    component: Layout,
    redirect: '/{industry}/settings/index',
    meta: {
      title: { zh_CN: '行业设置', en_US: 'Industry Settings' },
      icon: 'iconfont iconshezhi1',
      orderNo: 50,
      permission: 'system.view',
    },
    children: [
      {
        path: 'index',
        name: 'IndustrySettingsIndex',
        component: () => import('@/applications/{industry}/pages/settings/index.vue'),
        meta: {
          title: { zh_CN: '行业设置', en_US: 'Industry Settings' },
          permission: 'system.view',
        },
      },
    ],
  },
] satisfies RouteRecordRaw[];

行业统计页

行业统计页通过 menus.json 自动注入到"概况"二级菜单下，展示本行业的 KPI 指标、趋势图表与快捷入口。

菜单层级约束

每个 parent_code 为空的主菜单项（一级菜单）必须至少有一个 parent_code 指向它的子菜单项。如果缺少子项，侧边栏会出现冗余的二级点击层级（左侧点击主菜单后右侧仅显示主菜单自身）。框架已提供运行时兜底：若服务端菜单树中某父节点无子项，前端会从路由中自动解析子菜单。

正确示例

// api/applications/mall/menus.json — 订单管理（一级菜单 + 子菜单）
[
  {
    "code": "order",
    "title": "订单管理",
    "title_short": "订单",
    "path": "/order/index",
    "icon": "iconfont icon-menu-order",
    "parent_code": "",
    "order_no": 50
  },
  {
    "code": "order.index",
    "title": "订单列表",
    "path": "/order/index",
    "icon": "iconfont iconliebiao",
    "parent_code": "order",
    "order_no": 10
  }
]

财务示例（多子菜单）

// api/applications/mall/menus.json — 财务（一级菜单 + 三个子菜单）
[
  {
    "code": "finance",
    "title": "财务管理",
    "title_short": "财务",
    "path": "/finance/payments",
    "icon": "iconfont icon-menu-finance",
    "parent_code": "",
    "order_no": 60
  },
  {
    "code": "finance.money-detail",
    "title": "余额明细",
    "path": "/finance/money-detail",
    "parent_code": "finance",
    "order_no": 10
  },
  {
    "code": "finance.payments",
    "title": "支付记录",
    "path": "/finance/payments",
    "parent_code": "finance",
    "order_no": 20
  },
  {
    "code": "finance.points",
    "title": "积分明细",
    "path": "/finance/points-detail",
    "parent_code": "finance",
    "order_no": 30
  }
]

路由自动发现

行业模块路由和插件路由均通过 import.meta.glob 零配置自动发现，新增行业或模块无需修改核心框架代码。

// admin/src/router/registry.ts — 固定路由自动发现
const applicationModules = import.meta.glob(
  ['../applications/**/router/!(entry).ts', '../applications/**/plugins/router.ts'],
  { eager: true },
);
// 行业路由文件放 admin/src/applications/{industry}/router/{module}.ts
// 插件聚合入口放 admin/src/applications/{industry}/plugins/router.ts
// 文件存在即生效，无需手动 import

// admin/src/utils/route/index.ts — 全局页面自动扫描
const dynamicViewsModules = {
  ...import.meta.glob('../../core/pages/**/*.vue'),
  ...import.meta.glob('../../applications/*/pages/**/*.vue'),
  ...import.meta.glob('../../applications/*/plugins/pages/**/*.vue'),
};

底部导航动态菜单

框架提供一套可后台管理的 C 端底部导航能力，适用于需要由后台统一下发导航配置的用户端页面。是否使用动态菜单由前端页面自行决定；如果某些页面需要保持固定样式、固定入口或独立交互，也可以继续使用静态菜单，不接后台动态。

相关接口

方案一：直接使用后台动态菜单

适用于需要由后台统一控制导航图标、文案、链接和展示类型的页面。推荐做法是页面进入时先请求动态菜单，拿到数据后再渲染底部导航，避免先显示静态菜单再切成动态菜单的闪动问题。

// composables/use-channel-bottom-nav.ts
import { ref } from 'vue';
import { sysApi } from '@/api';
import type { BottomNavItemData, BottomNavStyleData } from '@/api';

export function useChannelBottomNav() {
  const navItems = ref<BottomNavItemData[]>([]);
  const navStyle = ref<BottomNavStyleData | undefined>(undefined);
  const navReady = ref(false);

  const resolveChannel = () => {
    // #ifdef MP-WEIXIN
    return 'weapp';
    // #endif
    // #ifdef H5
    return /MicroMessenger/i.test(window.navigator.userAgent) ? 'wechat' : 'h5';
    // #endif
    return 'h5';
  };

  const loadBottomNav = async (menuId = 0) => {
    try {
      const res = await sysApi.getBottomNavMenus(resolveChannel(), menuId || undefined);
      if (res.code === 0) {
        const menus = Array.isArray(res.data?.menus) ? res.data.menus : [];
        const current = menus[0];
        navItems.value = Array.isArray(current?.items) ? current.items : [];
        navStyle.value = current?.style;
      }
    } finally {
      navReady.value = true;
    }
  };

  return { navItems, navStyle, navReady, loadBottomNav };
}

<script setup lang="ts">
import { onShow } from '@dcloudio/uni-app';
import AppBottomNav from '@/components/app/AppBottomNav.vue';
import { useChannelBottomNav } from '@/composables/use-channel-bottom-nav';

const { navItems, navStyle, navReady, loadBottomNav } = useChannelBottomNav();

onShow(() => {
  loadBottomNav();
});
</script>

<template>
  <AppBottomNav
    v-if="navReady && navItems.length"
    :items="navItems"
    :style-config="navStyle"
    active-key="index"
    theme="green"
  />
</template>

方案二：不使用动态菜单，但直接调用接口自行渲染

适用于自定义 C 端项目。你可以完全不用框架提供的 AppBottomNav，只调用接口拿纯数据，自己按项目视觉体系渲染。

import { sysApi } from '@/api';

const loadMenus = async () => {
  const res = await sysApi.getBottomNavMenus('h5');
  if (res.code !== 0) return [];
  return res.data?.menus || [];
};

const menus = await loadMenus();
const currentMenu = menus[0];
// currentMenu.style.display_type: text / icon / icon_text
// currentMenu.items[n].label
// currentMenu.items[n].default_icon
// currentMenu.items[n].active_icon
// currentMenu.items[n].link

<template>
  <view class="custom-nav">
    <view
      v-for="item in menu.items"
      :key="item.link?.id || item.label"
      class="custom-nav__item"
      @tap="handleNavTap(item)"
    >
      <image :src="isActive(item) ? item.active_icon : item.default_icon" mode="aspectFit" />
      <text>{{ item.label }}</text>
    </view>
  </view>
</template>

方案三：保留静态菜单

适用于需要固定入口、固定样式或独立交互逻辑的页面。这类页面可以完全不接动态菜单，继续手写静态菜单项。

<template>
  <AppBottomNav
    v-if="!isPublicMode"
    :items="bottomTabs"
    active-key="clan-home"
    theme="clan"
    floating
  />
</template>

<script setup lang="ts">
const bottomTabs = [
  { key: 'nav-home', label: '首页', icon: 'jiazu', activeIcon: 'jiazu', url: '/pages/index/index', mode: 'switchTab' },
  { key: 'nav-center', label: '中心', icon: 'zupu', activeIcon: 'zupu', url: '/pages/custom/center', mode: 'navigateTo' },
  { key: 'nav-list', label: '列表', icon: 'dangan1', activeIcon: 'dangan1', url: '/pages/custom/list', mode: 'navigateTo' },
  { key: 'nav-message', label: '消息', icon: 'zaixiankefu', activeIcon: 'zaixiankefu', url: '/pages/custom/message', mode: 'navigateTo' },
];
</script>

后端规范

后端开发围绕平台核心放 api/app/Core，平台基础能力放 api/app，行业应用、业务模块与扩展插件放 api/applications。

校验结构

行业应用开发

行业应用是一组完整业务能力的集合（如 mall）。框架设计上，平台核心与平台基础能力不变，每个行业独立部署，互不污染。

行业目录结构

api/applications/{industry}/
├─ manifest.json          ← 行业清单（名称、版本、依赖、路由入口）
├─ menus.json             ← 后台左侧菜单树
├─ permissions.json       ← 权限节点注册
├─ messages.json          ← 消息模板注册
├─ settings.json          ← 行业级配置项
├─ event.php              ← 行业事件声明
├─ queue.php              ← 行业队列声明
├─ route/admin.php        ← 后台路由桥接入口
├─ route/app.php          ← 前台路由桥接入口
├─ modules/{module}/      ← 业务模块（goods / order / user 等）
├─ plugins/{plugin}/      ← 扩展插件（vip / coupon / recharge 等）
│  ├─ extension/          ← 扩展点处理器（同步 Pipeline）
│  ├─ queue/              ← 队列 handler（异步）
│  ├─ event.php           ← 插件事件声明（可选）
│  └─ queue.php           ← 插件队列声明（可选）

快速开始：一行命令创建行业应用

// === 创建行业应用（后端 + 前端 全部骨架） ===
php think make industry myindustry

// === 创建业务模块（含 CRUD 骨架代码） ===
php think make module myindustry goods

// === 创建扩展插件（含扩展点目录） ===
php think make plugin myindustry vip

手动创建（了解原理）

// 1. 创建目录
mkdir -p api/applications/myindustry
mkdir -p api/applications/myindustry/modules
mkdir -p api/applications/myindustry/plugins
mkdir -p data/install/myindustry

// 2. 创建 manifest.json
// api/applications/myindustry/manifest.json
{
  "code": "myindustry",
  "name": "我的行业",
  "version": "1.0.0",
  "description": "自定义行业应用",
  "dependencies": ["core"],
  "modules": [],
  "plugins": [],
  "route_bridges": {
    "admin": "applications/myindustry/route/admin.php",
    "app": "applications/myindustry/route/app.php"
  }
}

// 3. 创建路由桥接
// api/applications/myindustry/route/admin.php
onezan_load_php_tree(array_merge(
    glob(__DIR__ . '/modules/*/route/admin.php') ?: [],
    glob(__DIR__ . '/plugins/*/route/admin.php') ?: []
));

// 4. 创建安装 SQL
// data/install/myindustry/schema.sql
CREATE TABLE IF NOT EXISTS `onezan_myindustry_config` (
  `id` int unsigned NOT NULL AUTO_INCREMENT,
  `key` varchar(64) NOT NULL DEFAULT '',
  `value` text,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_key` (`key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

运行机制

插件开发

扩展插件是可关闭、可替换、可移除的扩展单元。它通过事件订阅、扩展点管道和 Provider 接口与业务模块解耦协作。

插件目录结构

api/applications/mall/plugins/my_plugin/
├─ manifest.json              ← 声明插件信息、扩展点、依赖
├─ event.php                  ← 插件事件声明（可选）
├─ queue.php                  ← 插件队列主题声明（可选）
├─ route/admin.php            ← 后台路由
├─ route/app.php              ← 前台路由
├─ adminapi/controller/       ← 后台控制器
├─ api/controller/            ← 前台控制器
├─ service/admin/             ← 后台 Service
├─ service/api/               ← 前台 Service
├─ core/                      ← 核心业务逻辑（Core Service）
├─ repository/                ← 数据查询层
├─ validate/                  ← 校验层
├─ extension/                 ← 扩展点处理器（实现 ExtensionPointHandlerInterface）
└─ queue/                     ← 队列 handler（异步消费）

快速开始：创建一个插件

// 1. 创建 manifest.json
// api/applications/mall/plugins/my_plugin/manifest.json
{
  "code": "mall.my_plugin",
  "name": "我的插件",
  "version": "1.0.0",
  "type": "plugin",
  "status": 1,
  "is_removable": true,
  "description": "演示插件",
  "files": [
    "api/applications/mall/plugins/my_plugin"
  ],
  "tables": [],
  "route_bridges": {
    "admin": "applications/mall/plugins/my_plugin/route/admin.php",
    "app": "applications/mall/plugins/my_plugin/route/app.php"
  },
  "permissions": ["plugins.my_plugin.view"],
  "dependencies": ["core", "mall"],
  "extension_points": [
    {
      "point": "order.price.calculate",
      "handler": "Applications\\mall\\plugins\\my_plugin\\extension\\MyPriceHandler",
      "priority": 30
    }
  ],
  "plugins_meta": {
    "type": "other",
    "description": "演示插件能力。",
    "icon": "iconfont iconplugin",
    "sort": 99
  }
}

// 2. 实现扩展点处理器
// api/applications/mall/plugins/my_plugin/extension/MyPriceHandler.php

use app\Core\contract\ExtensionPointHandlerInterface;

class MyPriceHandler implements ExtensionPointHandlerInterface
{
    public function point(): string
    {
        return 'order.price.calculate';
    }

    public function handle(array $ctx): array
    {
        // 读取管道上下文
        $userId = (int)($ctx['user_id'] ?? 0);
        $currentPrice = (float)($ctx['final_price'] ?? 0);

        // 业务判断
        if (!$this->isEligible($userId)) {
            return $ctx; // 不修改，原样传递
        }

        // 计算折扣（满100减10）
        $discount = $currentPrice >= 100.00 ? 10.00 : 0;
        $ctx['discount'] = ((float)($ctx['discount'] ?? 0)) + $discount;
        $ctx['final_price'] = round($currentPrice - $discount, 2);
        $ctx['breakdown'][] = [
            'type' => 'my_plugin',
            'label' => '满减优惠',
            'amount' => $discount,
        ];

        return $ctx; // 传递给下一个处理器
    }
}

// 3. 注册后台路由
// api/applications/mall/plugins/my_plugin/route/admin.php
use think\facade\Route;
Route::group('plugins/my_plugin', function () {
    Route::get('config', 'adminapi/controller/Config@index');
});

插件与业务模块的解耦规则

通信处理

框架提供三种通信机制：事件（Event）、队列（Queue）和扩展点（ExtensionPoint），分别对应异步投递、异步消费和同步管道三种模式。

三种机制对比

事件投递

业务模块写完数据库后抛出事件，Listener 接收后决定是同步处理还是投递队列。

// 1. 定义事件类（可选，按需定义）
// api/app/event/order/OrderPaid.php
namespace app\event\order;
class OrderPaid
{
    public int $orderId;
    public array $orderData;
}

// 2. 在 Core Service 中触发事件
use app\event\order\OrderCompleted;

class CoreOrderService
{
    public function complete(int $orderId): void
    {
        // 1. 写库：更新订单状态
        $this->repository->markCompleted($orderId);

        // 2. 抛事件：通知关注方（不阻塞主流程的后续逻辑在此投递队列）
        $order = $this->repository->getFull($orderId);
        app()->event->trigger(new OrderCompleted($orderId, $order));
    }
}

队列消费

Listener 接收事件后通过 QueueDispatcher 投递队列，队列 handler 异步执行耗时逻辑。框架支持一个 topic 对应多个 handler（multi-cast），并通过声明式 queue.php 自动装载。

// 1. 定义 Listener
// api/app/listener/order/OrderCompletedListener.php
namespace app\listener\order;
use app\event\order\OrderCompleted;
use app\Core\service\queue\QueueDispatcher;

class OrderCompletedListener
{
    public function handle(OrderCompleted $event): void
    {
        // 投递到队列，异步处理
        app()->make(QueueDispatcher::class)->dispatch(
            'order.completed.followup',
            ['order_id' => $event->orderId, 'data' => $event->orderData],
            ['biz_key' => 'order.completed:' . $event->orderId]
        );
    }
}

// 2. 插件中声明 queue.php
// api/applications/mall/plugins/coupon/queue.php
use Applications\mall\plugins\coupon\queue\CouponOrderCompletedHandler;

return [
    'order.completed.followup' => [
        CouponOrderCompletedHandler::class,
    ],
];

// 3. 插件中定义队列 handler
// api/applications/mall/plugins/coupon/queue/CouponOrderCompletedHandler.php
namespace Applications\mall\plugins\coupon\queue;
use app\Core\service\queue\contract\QueueHandlerInterface;

class CouponOrderCompletedHandler implements QueueHandlerInterface
{
    public function topic(): string
    {
        return 'order.completed.followup';
    }

    public function handle(array $payload): void
    {
        $orderId = (int)($payload['order_id'] ?? 0);
        // 异步发券逻辑
        $this->grantCouponAfterCompleted($orderId);
    }
}

扩展点管道

扩展点用于需要同步串联执行并收集返回值的场景。所有注册的处理器按 priority 从小到大依次执行，每个处理器的输出作为下一个的输入。

// 1. 业务模块调用扩展点
use app\Core\service\extension\ExtensionRegistry;

class CoreOrderService
{
    public function calculatePrice(int $userId, float $price, array $goodsItems): array
    {
        $ctx = [
            'user_id'       => $userId,
            'original_price' => $price,
            'final_price'   => $price,
            'discount'      => 0,
            'breakdown'     => [],
            'goods_items'   => $goodsItems,
        ];

        $registry = app()->make(ExtensionRegistry::class);

        // 管道计算：VIP(10) → Coupon(20) → Points(30)
        $result = $registry->execute('order.price.calculate', $ctx);

        return $result; // $result['final_price'] 已叠加所有折扣
    }
}

// 2. 插件实现处理器（见上方"插件开发"章节的完整示例）

支付模块：Gateway Driver 模式

设计动机

支付模块需要对接多个第三方支付服务商（微信、支付宝、余额、线下转账），且不同行业应用的支付逻辑各有不同。为避免在每个行业应用中重复编写 SDK 对接代码，框架采用 Gateway Driver 模式 实现平台层复用。

分层架构

核心接口

interface PaymentGatewayInterface
{
    public function create(array $payment, array $order, string $terminal, array $context): array;
    public function notify(Request $request, string $terminal): array;
    public function refund(array $refund, array $payment): array;
    public function refundNotify(Request $request, string $terminal): array;
    public function provider(): string;
    public function name(): string;
    public function supportsTerminal(string $terminal): bool;
    public function isAllocatable(): bool;
    public function successResponse(): array;
}

支付方式配置控制

开关联动逻辑

1. channel_profiles.status = 0 → 该终端所有支付方式不可用
2. channel_payment_configs.status = 0 → 该支付方式在该终端不可用
3. Gateway::supportsTerminal() = false → 该支付方式不支持该终端
4. APP_DEBUG = true → 自动启用 wechatpay/alipay 测试模式（Mock SDK 边界）

开闭原则：新增支付方式

class StripeGateway extends BaseGateway
{
    public function provider(): string { return 'stripe'; }
    public function name(): string { return 'Stripe支付'; }
    public function supportsTerminal(...): bool { return ...; }
    public function isAllocatable(): bool { return true; }
    public function create(...): array { /* Stripe SDK */ }
    public function notify(...): array { /* 回调验证 */ }
    public function refund(...): array { /* 退款 */ }
    public function refundNotify(...): array { return []; }
    public function successResponse(): array { return []; }
}

$payOrchestrator->register(new StripeGateway(...));
// 无需任何其他修改

行业复用

class MallPayBridge extends BaseCoreService /* 已有 */
{
    public function getOrderPayOptions(...) { /* 验证订单 → 编排器 */ }
    public function createOrderPayment(...) { /* 支付单 → 扣余额 → 编排器 */ }
}

class EduPayBridge extends BaseCoreService /* 将来 */
{
    public function getCoursePayOptions(...) { /* 验证课程 → 同一编排器 */ }
    public function createCoursePayment(...) { /* 选课锁定 → 同一编排器 */ }
}

安全过滤：Security Filter

平台层提供 CoreSecurityFilterService，封装微信小程序内容安全接口（msgSecCheck / imgSecCheck），用于用户生成内容（UGC）的文本和图片安全检测。行业应用通过注入调用接入，开关关闭时零开销。

职责划分

核心接口

// api/app/service/core/security/CoreSecurityFilterService.php
class CoreSecurityFilterService extends BaseCoreService
{
    // 检查 weapp 渠道是否开启内容安全
    public function isEnabled(): bool;

    // 文本安全过滤，违规返回 code=1
    public function filterText(string $content): array;

    // 图片安全过滤，违规返回 code=1
    public function filterImage(string $imagePath): array;
}

开关控制

• 管理员在后台 渠道管理 → 小程序设置 中切换 content_security_enabled switch
• 配置存储在 weapp 渠道的 base 配置组中
• APP_DEBUG = true 时自动 Mock，不调用真实微信 API
• 微信接口异常时降级放行，不阻塞业务流程

行业应用集成方式

1. 内容发布时过滤文本（以 mall content 为例）：

// api/applications/mall/modules/content/core/CoreContentService.php
use app\service\core\security\CoreSecurityFilterService;

public function save(array $payload): array
{
    // ... 参数校验 ...

    // 注入安全过滤
    $checkText = $title . ' ' . ((string)($payload['description'] ?? ''));
    $securityResult = $this->app->make(CoreSecurityFilterService::class)
                             ->filterText($checkText);
    if ($securityResult['code'] !== 0) {
        return $securityResult;
    }

    // ... 写库 ...
}

2. 用户昵称变更时过滤：

$result = $this->app->make(CoreSecurityFilterService::class)
                    ->filterText($newNickname);
if ($result['code'] !== 0) {
    return ['code' => 1, 'msg' => $result['msg']];
}

3. 图片上传自动检测：框架层 CoreMediaService::saveUpload() 已内置图片安全检测，上传行为无需额外接入。检测不通过时抛出异常，删除已存储文件。

关键设计决策

开发示例

下面的示例全部来自项目实际做法，目的是让新增代码与现有结构和风格保持一致。

前端列表页示例

// 文件：admin/src/applications/mall/pages/goods/index.vue
<template>
  <t-card :bordered="false">
    <div class="table-container">
      <t-form class="search-form" :data="searchForm" layout="inline" @submit="handleSearch">
        <t-form-item name="keyword" label="名称/编号">
          <t-input v-model="searchForm.keyword" placeholder="请输入商品名称/编号" />
        </t-form-item>
        <t-form-item name="status" label="状态">
          <t-select v-model="searchForm.status" placeholder="请选择状态" clearable>
            <t-option :value="1" label="上架" />
            <t-option :value="0" label="下架" />
          </t-select>
        </t-form-item>
        <t-form-item>
          <t-button theme="primary" type="submit">
            <AppIcon name="iconfont icon-action-search" class="app-icon-gap" />
            查询
          </t-button>
          <t-button theme="default" variant="base" @click="handleReset">
            <AppIcon name="iconfont icon-action-refresh" class="app-icon-gap" />
            重置
          </t-button>
          <t-button class="search-action-btn" @click="handleAdd">
            <AppIcon name="iconfont icon-action-add" class="app-icon-gap" />
            新增商品
          </t-button>
        </t-form-item>
      </t-form>

      <t-table
        :data="data"
        :columns="columns"
        :pagination="pagination"
        :loading="dataLoading"
        row-key="id"
        hover
        @page-change="handlePageChange"
      >
        <template #status="{ row }">
          <t-tag v-if="row.status === 1" theme="success" variant="light">上架</t-tag>
          <t-tag v-else theme="danger" variant="light">下架</t-tag>
        </template>
        <template #op="{ row }">
          <t-link theme="primary" hover="color" @click="handleEdit(row)">
            <AppIcon name="iconfont icon-action-edit" class="app-icon-gap" />
            编辑
          </t-link>
          <t-popconfirm content="确认删除吗？" @confirm="handleDelete(row)">
            <t-link theme="danger" hover="color" class="op-link">删除</t-link>
          </t-popconfirm>
        </template>
      </t-table>
    </div>
  </t-card>
</template>

<script setup lang="ts">
import { reactive, ref } from 'vue';
import AppIcon from '@/components/AppIcon.vue';

const data = ref([]);
const dataLoading = ref(false);
const pagination = reactive({ current: 1, pageSize: 10, total: 0 });
const searchForm = reactive({ keyword: '', status: undefined as number | undefined });

const handleSearch = () => {};
const handleReset = () => {};
const handleAdd = () => {};
const handleEdit = (_row: unknown) => {};
const handleDelete = (_row: unknown) => {};
const handlePageChange = () => {};
</script>

前端配置页示例

// 文件：admin/src/core/pages/system/menu-config.vue
<template>
  <div class="page-admin-system-menu">
    <t-card class="search-form" :bordered="false" title="菜单配置">
      <t-alert
        theme="info"
        message="左侧主栏优先显示简称，页面标题、面包屑和权限分配继续使用完整名称。保存后刷新页面即可生效。"
      />
    </t-card>

    <t-card class="table-container" :bordered="false">
      <template #actions>
        <t-space>
          <t-button theme="primary" @click="handleSave">保存配置</t-button>
          <t-button theme="default" variant="outline" @click="handleRefreshCache">更新缓存</t-button>
        </t-space>
      </template>

      <t-table row-key="code" :data="tableData" :columns="tableColumns" :loading="loading">
        <template #editableTitles="{ row }">
          <div class="edit-cell">
            <t-input v-model="row.title_short" size="small" maxlength="12" placeholder="主栏简称" />
            <t-input v-model="row.title_full" size="small" maxlength="30" placeholder="完整名称" />
          </div>
        </template>
        <template #status="{ row }">
          <t-switch :model-value="row.status === 1" @change="(value) => handleToggle(row, 'status', value)" />
        </template>
      </t-table>
    </t-card>
  </div>
</template>

前端 API 示例

// 文件：admin/src/applications/mall/api/goods.ts
import { request } from '@/utils/request';

export interface GoodsRow {
  id: number;
  goods_no?: string;
  name?: string;
  status?: number;
}

export function getGoodsList(params: Recordable<unknown>) {
  return request.get(
    {
      url: '/goods/list',
      params,
    },
    {
      isTransformResponse: false,
    },
  );
}

export function deleteGoods(id: number) {
  return request.post(
    {
      url: '/goods/delete',
      data: { id },
    },
    {
      isTransformResponse: false,
    },
  );
}

后端路由与控制器示例

以商品保存接口为例，展示从路由到数据层的完整调用链路。

1. 路由定义

// api/applications/mall/modules/goods/route/admin.php
Route::post('goods/save', 'Applications\\mall\\adminapi\\controller\\goods\\Goods@save')
    ->middleware(\app\middleware\AdminPermission::class, 'goods.save');

2. 控制器 — 入参校验 + 业务校验 + 调服务

// api/applications/mall/adminapi/controller/goods/Goods.php
public function save(Request $request)
{
    $params = $request->post();
    $this->validate($params, GoodsValidator::class . '.save');
    $this->validateDomain(
        $this->app->make(GoodsDomainValidator::class), $params, 'save'
    );
    return json($this->app->make(GoodsService::class)->save($request));
}

3. 应用服务 — 收口参数，调核心服务

// api/applications/mall/modules/goods/service/admin/GoodsService.php
public function save(Request $request): array
{
    // 可在此做幂等性防重、图片路径标准化等应用层收口
    $result = $this->core()->save([
        'id'   => (int)$request->post('id', 0),
        'name' => $request->post('name', ''),
        'status' => $request->post('status', 1),
        'skus'   => $request->post('skus/a', []),
        'banners' => $this->normalizeImageArray(
            $request->post('banners/a', [])
        ),
        // ... 其余参数收口
    ]);

    return $result;
}

private function core(): CoreGoodsService
{
    return $this->app->make(CoreGoodsService::class);
}

4. 核心服务 — 写流程、事务、状态流转

// api/applications/mall/modules/goods/core/CoreGoodsService.php
public function save(array $payload): array
{
    $id   = (int)($payload['id'] ?? 0);
    $name = trim((string)($payload['name'] ?? ''));
    if ($name === '') {
        return ['code' => 1, 'msg' => '商品名称不能为空'];
    }

    $savePayload = [
        'name'   => $name,
        'status' => (int)($payload['status'] ?? 1) ? 1 : 0,
    ];

    if ($id > 0) {
        $goods = $this->repository()->findById($id);
        if (!$goods) {
            return ['code' => 1, 'msg' => '商品不存在'];
        }
        $this->repository()->save($goods, $savePayload);
    } else {
        $savePayload['goods_no'] = $this->generateGoodsNo();
        $goods = $this->repository()->create($savePayload);
    }

    // 重建子表数据，收口最终销售价
    $this->saveSkus((int)$goods->id, $payload);
    $this->syncGoodsPriceFromSkus((int)$goods->id, $goods);

    return ['code' => 0, 'msg' => '保存成功', 'data' => ['id' => (int)$goods->id]];
}

5. 模型 — 映射数据表

// api/applications/mall/modules/goods/model/Goods.php
class Goods extends Model
{
    protected $name = 'mall_goods';
    protected $autoWriteTimestamp = true;
    protected $createTime = 'create_time';
    protected $updateTime = 'update_time';
}

6. 仓储 — 数据库访问封装

// api/applications/mall/modules/goods/repository/GoodsRepository.php
public function findById(int $id): ?Goods
{
    $goods = Goods::find($id);
    return $goods instanceof Goods ? $goods : null;
}

public function create(array $payload): Goods
{
    return Goods::create($payload);
}

public function save(Goods $goods, array $payload = []): void
{
    if ($payload) {
        $goods->save($payload);
        return;
    }
    $goods->save();
}

整条链路自上而下：路由（URL → 中间件鉴权）→ 控制器（入参校验 + 业务校验）→ 应用服务（参数收口、幂等防重）→ 核心服务（写流程 + 事务 + 状态流转）→ 仓储（数据库访问封装）→ 模型（映射数据表）→ 返回。只做简单读接口时，可省略应用服务或核心服务，由控制器直接调仓储。

业务模块目录示例

最小必要目录：

api/applications/mall/modules/goods/
├─ manifest.json              # 业务模块清单，声明编码、依赖、路由桥接
├─ route/admin.php            # 后台接口路由
├─ route/app.php              # 前台接口路由
├─ service/
│  ├─ admin/GoodsService.php  # 后台应用服务
│  └─ api/GoodsService.php    # 前台应用服务
├─ core/CoreGoodsService.php  # 核心写流程、事务、状态流转
├─ repository/GoodsRepository.php
├─ model/Goods.php
└─ validate/
   ├─ admin/GoodsValidator.php
   ├─ api/GoodsValidator.php
   └─ domain/GoodsDomainValidator.php

说明：
1. 上面是“最小必要结构”，不是要求一次把所有扩展文件全部建满。
2. `manifest.json` 的作用是声明业务模块编码、依赖关系、路由桥接与聚合元数据，便于行业应用统一注册、统一识别、统一维护。
3. `manifest.json` 更适合以下场景：
   - 一个行业应用内存在多个业务模块，需要统一注册与聚合；
   - 后续可能做模块级启停、备份、迁移、清单扫描；
   - 需要把模块边界、依赖和入口描述清楚，增强规范能力。
4. `manifest.json` 不是所有小功能都必须强制补齐；如果只是行业应用内偶尔出现的简单能力，且不涉及独立解耦、独立治理、独立交付，可以先按普通业务目录实现。
5. 只有当你希望这个能力具备更清晰的边界、更好的可维护性、或者后续适合做解耦治理时，再补业务模块清单会更有价值。
6. 只做读接口时，可保留 manifest、route、service、repository、model、validate；涉及写流程、事务、状态流转时，再补 core/CoreGoodsService.php。

交付要求

代码交付不是改完文件就结束，而是必须通过实际运行质量门槛。

交付检查清单

1. 改动文件重新阅读关键片段
2. 清理调试输出和占位代码
3. 跑前端 lint / stylelint / build:type / build
4. 跑后端真实接口验证
5. 检查文档、接口中心、skills 口径一致
6. 确认最终打包成功后再正式交付

安装与导库

数据目录承担安装与升级职责；运行时菜单、权限、消息、设置定义统一由代码与清单文件维护。

标准导入顺序

方案 A：标准新环境
1. data/install/sys.sql
2. data/install/mall/schema.sql

方案 B：完整表 + H5 测试数据
1. data/install/sys.sql
2. data/install/mall/full_with_h5_seed.sql

宝塔部署 ThinkPHP 8

1. 宝塔创建站点
   - 项目目录：/www/wwwroot/onezan.test/api
   - 运行目录：/www/wwwroot/onezan.test/api/public
   - PHP 版本：PHP 8.0

2. PHP 扩展建议
   - 必装：pdo_mysql、mbstring、curl、fileinfo、openssl、gd、zip
   - 使用 Redis 队列时额外安装：redis

3. 安装服务端依赖
   cd /www/wwwroot/onezan.test/api
   composer install --no-dev

4. 数据库配置
   编辑 api/.env：
   [DATABASE]
   TYPE = mysql
   HOSTNAME = 127.0.0.1
   HOSTPORT = 3306
   DATABASE = onezan
   USERNAME = onezan
   PASSWORD = your-password
   CHARSET = utf8mb4

5. 导库
   - 标准环境：data/install/sys.sql + data/install/mall/schema.sql
   - 测试环境：data/install/sys.sql + data/install/mall/full_with_h5_seed.sql

6. 首次检查
   - 登录后台检查系统设置
   - 菜单、权限、manifest 改动后执行“更新缓存”

伪静态配置

Nginx：
location / {
    try_files $uri $uri/ /index.php?$query_string;
}

Apache /.htaccess：
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ index.php?s=/$1 [QSA,PT,L]

说明：
- 网站运行目录必须指向 api/public
- 站点根目录下的 /admin/、/docs/、/apidoc/ 都从 api/public 对外提供

Redis 与队列设置

1. 队列配置文件
   - api/config/queue.php
   - 控制台命令：php think queue:work

2. 驱动说明
   - sync：本地开发或关闭异步时使用
   - database：推荐的生产方案
   - redis：高并发异步场景使用

3. 后台系统设置中需要维护
   - driver
   - default_queue
   - retry_delay_seconds
   - reserve_seconds
   - max_attempts
   - work_sleep_seconds

4. 使用 Redis 时补充配置
   - host、port、password
   - select
   - timeout
   - persistent
   - prefix

5. 宝塔准备项
   - 安装 Redis 服务
   - PHP 8.0 安装 redis 扩展
   - 保存系统设置后再启动 queue worker

Supervisor 长驻示例

[program:onezan_queue_default]
command=/usr/bin/php /www/wwwroot/onezan.test/api/think queue:work --queue=default --sleep=3
directory=/www/wwwroot/onezan.test/api
autostart=true
autorestart=true
startsecs=5
startretries=3
user=www
redirect_stderr=true
stdout_logfile=/www/wwwlogs/onezan_queue_default.log
stdout_logfile_maxbytes=20MB
stdout_logfile_backups=10
stopwaitsecs=60

说明：
- 在宝塔 Supervisor 或守护进程中新增这份配置
- 驱动为 sync 或队列未启用时，不需要启动 worker
- 多队列场景可按 queue 名复制多份 program 配置

前端开发环境

目录：admin/

1. 安装依赖
   npm install

2. 开发配置
   文件：admin/.env.development
   VITE_BASE_URL = /
   VITE_IS_REQUEST_PROXY = true
   VITE_API_URL = http://onezan.test
   VITE_API_URL_PREFIX = /adminapi

3. 本地开发
   npm run dev

4. 说明
   - vite.config.ts 默认把 /adminapi 代理到 http://127.0.0.1:3000/
   - 如本地宝塔站点不是该地址，按实际环境调整代理目标

前端生产打包与发布

1. 生产配置
   文件：admin/.env.release
   VITE_BASE_URL=/admin/
   VITE_IS_REQUEST_PROXY=false
   VITE_API_URL=
   VITE_API_URL_PREFIX=/adminapi

2. 打包
   cd admin
   npm run build

3. 发布产物
   - 打包目录：admin/dist/
   - 发布目标：api/public/admin/

4. 交付前检查
   npm run lint
   npm run stylelint
   npm run build:type
   npm run build

升级说明

框架升级：data/upgrade/framework/YYYYMMDD_xxx.sql
行业升级：data/upgrade/mall/YYYYMMDD_xxx.sql
平台基础能力升级（安装时执行）：api/install/xxx.sql（如 api/install/points.sql 用户积分系统）

发生表结构变更时：
1. 同步安装基线
2. 补升级 SQL
3. 如涉及菜单/权限/manifest，再更新缓存

开发资源

技能包使用

项目内置技能包规则，帮助 AI 编码助手按项目结构和规范协同开发。

1. onezan-project-context（项目上下文）
2. onezan-admin-frontend 或 onezan-backend（专项规则）
3. onezan-module（新增模块/插件时）
4. onezan-docs（修改文档时）
5. onezan-delivery-checklist（交付前）

请先加载 onezan-project-context 和 onezan-admin-frontend。
我在 mall 行业新增 notice 页面和 API 接口，
文件放到 applications/mall/pages、applications/mall/api、applications/mall/router，
页面风格与 goods 页面保持一致，
完成后执行前端构建检查。

请先加载 onezan-project-context 和 onezan-backend。
我在 mall 行业新增 notice 业务模块，
包含 manifest、route、controller、service、core、repository、validate、permissions、menus，
同步 schema.sql 与升级 SQL，最后跑接口验证。