项目介绍

壹站 onezan-admin 适用于企业后台、业务运营平台、内容管理平台和交易管理平台等场景。项目采用前后端分离结构，内置后台管理、业务模块、渠道中心和基础配置能力，可作为新项目的统一底座继续扩展。

功能总览

当前系统已经包含后台常用管理能力和交易相关基础能力，可直接用于项目初始化或继续承接行业业务扩展。

使用说明

cd e:\wwwroot\onezan.test\api
composer install

# Web 根目录指向 api/public
# 然后通过域名访问：
# http://onezan.test/

# 常用命令
php think reset:admin:password
php think order:auto-cancel
php think admin:cleanup-operation-logs

# 伪静态规则
location ~* (runtime|application)/{
	return 403;
}
location / {
	if (!-e $request_filename){
		rewrite  ^(.*)$  /index.php?s=$1  last;   break;
	}
}

cd e:\wwwroot\onezan.test\admin
npm install
npm run dev

# 质量检查
npm run lint
npm run stylelint
npm run build:type
npm run build

首次使用流程

1. 导入 data/onezan.sql 初始化数据库。
2. 确认站点根目录指向 api/public。
3. 配置后台前端开发环境中的服务端地址。
4. 如需重置后台管理员密码，可执行 php think reset:admin:password。
5. 页面功能说明查看文档中心，接口调试进入 /apidoc/。

技术说明

服务端目录结构

服务端采用按访问端、职责层和业务域拆分的目录结构，便于保持控制器轻量、服务职责清晰和查询逻辑集中。

api/
├─ app/
│  ├─ adminapi/          后台正式接口入口
│  ├─ api/               前台正式接口入口
│  ├─ middleware/        中间件
│  ├─ repository/        仓储层
│  ├─ service/           服务层
│  ├─ model/             数据模型
│  ├─ event/             事件定义
│  ├─ listener/          事件监听器
│  ├─ job/               任务类
│  └─ command/           命令行入口
├─ route/                路由定义
├─ config/               配置文件
└─ public/               对外访问目录

访问端目录

app/
├─ adminapi/controller/   后台管理相关接口
├─ api/controller/        前台业务相关接口
├─ service/admin/         后台应用服务
├─ service/api/           前台应用服务
└─ service/core/          核心业务规则

服务端开发规范

类与方法规范

• 控制器只负责接收请求和返回响应，不直接编写事务、状态流转和复杂查询。
• 应用服务命名建议保持 list、detail、save、delete 等统一语义。
• 核心服务只负责真正的业务规则，如下单、状态流转、余额调整和审核处理。
• 仓储层优先处理分页、聚合、锁查询、字段筛选和模型持久化封装。

注释规范

• 控制器类建议补充职责说明，例如“后台商品管理正式入口”。
• 服务类建议明确本类负责范围与不负责范围。
• 事务、状态机、幂等、导出、审核等关键方法应补充方法说明。
• 注释只解释不直观的规则，不解释显而易见的赋值语句。

命名与结构规范

• 控制器文件使用 PascalCase，目录按业务域拆分。
• 类方法优先使用动词语义，如 forceCancel、refreshListTime。
• 新增业务优先接入 adminapi/controller 或 api/controller 正式入口。

服务端开发示例

以下示例以“新增一个后台公告模块”为例，说明服务端从路由到服务层的组织方式。示例用于说明开发结构，实际业务可替换为任意模块。

// route/admin/content.php
use think\facade\Route;

Route::group('content', function () {
    Route::get('notice/list', 'app\adminapi\controller\content\Notice@list');
    Route::get('notice/detail/:id', 'app\adminapi\controller\content\Notice@detail');
    Route::post('notice/save', 'app\adminapi\controller\content\Notice@save');
    Route::post('notice/delete', 'app\adminapi\controller\content\Notice@delete');
});

namespace app\adminapi\controller\content;

use app\adminapi\controller\BaseAdminController;
use app\service\admin\content\NoticeService;

class Notice extends BaseAdminController
{
    public function list(NoticeService $service)
    {
        return json($service->getList($this->request->get()));
    }

    public function save(NoticeService $service)
    {
        return json($service->save($this->request->post()));
    }
}

namespace app\service\admin\content;

use app\repository\content\NoticeRepository;
use app\service\core\content\CoreNoticeService;

class NoticeService
{
    public function __construct(
        protected NoticeRepository $repository,
        protected CoreNoticeService $coreService
    ) {}

    public function getList(array $params): array
    {
        return $this->repository->page($params);
    }

    public function save(array $data): array
    {
        return $this->coreService->saveNotice($data);
    }
}

namespace app\service\core\content;

use think\facade\Db;
use app\event\content\NoticeSaved;

class CoreNoticeService
{
    public function saveNotice(array $data): array
    {
        return Db::transaction(function () use ($data) {
            $noticeId = 1;

            event(new NoticeSaved($noticeId, $data));

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

// app/event/content/NoticeSaved.php
class NoticeSaved
{
    public function __construct(
        public int $noticeId,
        public array $payload
    ) {}
}

// app/listener/content/NoticeSavedListener.php
class NoticeSavedListener
{
    public function handle(NoticeSaved $event): void
    {
        // 记录日志、刷新缓存、发送通知
    }
}

// app/service/AdminPermissionRegistry.php
[
    'content.notice.view' => '查看公告',
    'content.notice.save' => '保存公告',
    'content.notice.delete' => '删除公告',
]

新增服务端模块建议顺序

1. 先定义业务目录与路由归属，确认属于 adminapi 还是 api。
2. 再创建控制器、应用服务、核心服务和仓储层。
3. 若模块涉及后台按钮权限，优先同时补权限注册与前端按钮控制。
4. 如果存在异步通知、日志、缓存刷新等派生动作，再补事件与监听器。
5. 最后同步文档中心说明与交互式接口文档。

后台前端目录结构

后台前端目录结构直接影响后续新增页面时的维护效率。项目当前已经将页面、接口、组件、类型和公共能力分开管理。

admin/src/
├─ api/                    接口调用层
├─ components/             公共组件
├─ hooks/                  通用 hooks
├─ layouts/                后台整体布局
├─ pages/                  业务页面
├─ router/                 路由配置
├─ store/                  Pinia 状态管理
├─ style/                  全局样式与 iconfont
├─ types/                  公共类型定义
└─ utils/                  通用工具与请求封装

页面目录细分

src/pages/
├─ admin-user/             用户管理
├─ admin-role/             角色权限
├─ admin-admin-user/       管理员管理
├─ admin-goods/            商品管理
├─ admin-content/          内容管理
├─ admin-content-category/ 内容分类
├─ admin-order/            订单管理
├─ admin-finance/          财务流水与支付单
├─ admin-addon/            addon 模块管理
├─ admin-addon-vip/        付费会员套餐与开通记录
├─ admin-addon-coupon/     优惠券模板与领取记录
├─ admin-media/            素材管理
├─ admin-system/           系统设置
├─ admin-channel/          渠道中心、支付与通知配置
├─ admin-operation-log/    操作日志
├─ dashboard/              数据看板
└─ login/                  登录页

后台前端开发规范

页面规范

• Vue 单文件块顺序固定为 template -> script setup lang="ts" -> style scoped lang="less"。
• 列表页查询表单统一为 searchForm，列表请求统一为 fetchList()。
• 分页统一使用 pagination.current / pageSize / total。
• 按钮和操作列图标统一使用 AppIcon。

类型规范

• 页面层禁止新增裸 any。
• 表格行统一定义 RowItem，表单统一定义 FormState。
• 列表响应统一使用 ListResponse<T>，详情统一使用 ItemResponse<T>。

样式与交互规范

• 默认禁止静态内联样式，动态尺寸除外。
• 错误反馈统一使用 MessagePlugin.success / MessagePlugin.error。
• 提交前通过 npm run lint、npm run stylelint、npm run build:type。

后台前端开发示例

以下示例展示后台前端新增页面时的常见组织方式，包括列表页、编辑页、接口调用层和路由接入。

1. 后台列表页最小骨架

const searchForm = reactive({
  keyword: '',
  status: undefined,
});

const tableData = ref([]);
const tableLoading = ref(false);
const pagination = reactive({
  current: 1,
  pageSize: 10,
  total: 0,
});

const fetchList = async () => {};
const handleSearch = () => {};
const handleReset = () => {};
const handlePageChange = (pageInfo) => {};

2. 后台列表页模板示例

<t-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>
    <t-button theme="primary" type="submit">
      <AppIcon name="iconfont icon-action-search" class="app-icon-gap" />
      查询
    </t-button>
  </t-form-item>
</t-form>

<t-table
  :data="tableData"
  :columns="columns"
  :loading="tableLoading"
  :pagination="pagination"
  @page-change="handlePageChange"
/>

3. 后台编辑页接入示例

const formData = reactive({
  id: undefined,
  title: '',
  status: 1,
});

const loadDetail = async () => {
  const res = await getNoticeDetail(detailId.value);
  Object.assign(formData, res.data || {});
};

const handleSave = async () => {
  const res = await saveNotice({ ...formData });
  if (res.code === 0) {
    MessagePlugin.success('保存成功');
  }
};

4. 前端 API 文件示例

export type NoticeRow = {
  id: number;
  title: string;
  status: number;
  create_time: string | number;
};

export function getNoticeList(params: Recordable<unknown>) {
  return request.get({
    url: '/notice/list',
    params,
  });
}

5. 菜单与路由接入示例

{
  path: '/content/notice',
  name: 'AdminContentNotice',
  component: Layout,
  meta: {
    title: '公告管理',
    icon: 'iconfont icon-menu-content',
    permission: ['content.notice.view'],
  },
}

6. 权限接入完整链路

服务端权限注册
  -> 后台登录返回 permissions
  -> 前端 store 缓存权限集合
  -> 路由 meta.permission 控制页面可见性
  -> 按钮级权限控制具体操作

示例权限码：
content.notice.view
content.notice.save
content.notice.delete

7. 按钮级权限模板

<t-button
  v-if="userStore.hasPermission('content.notice.save')"
  theme="primary"
  @click="handleCreate"
>
  <AppIcon name="iconfont icon-action-add" class="app-icon-gap" />
  新增
</t-button>

用户管理

用户模块负责平台用户资料、等级、认证和账户能力，是会员体系和账户体系扩展的基础。

权限与管理员

权限模块负责后台菜单访问、页面进入和按钮操作控制，与管理员和角色管理一起构成后台安全体系。

商品管理

商品模块负责可售内容与展示数据维护，适合用作电商、权益或内容付费类业务的商品基础层。

订单与支付

订单与支付模块承担交易主链路，包括下单、支付单管理、退款处理和财务流水等能力。

渠道管理

渠道中心负责统一管理多端渠道配置，并承接支付能力和通知能力的差异化配置。

应用中心

应用中心用于承接不应直接耦合到核心业务的能力，一期已提供 addon 模块管理、付费会员和优惠券能力，并预留分销、代理、秒杀、抽奖、积分兑换与 AI 能力扩展方式。

前台应用中心入口只展示已启用模块，便于按运营配置控制用户侧可见范围。

内容、素材与系统

内容、素材与系统模块承担平台公共信息、资源管理和基础配置维护职责，适合作为长期运营配置入口。

权限与菜单

权限和菜单需要保持同一套命名和控制逻辑，保证页面访问、菜单显示和按钮操作行为一致。

权限定义
  -> 角色绑定权限码
  -> 管理员绑定角色
  -> 登录返回 permissions
  -> 菜单、路由、按钮按权限控制

推荐风格：
模块.动作

示例：
goods.view
goods.save
goods.delete
channel.config.save

• 页面权限、按钮权限和导出权限建议分开定义。
• 菜单显示和页面访问都应基于同一组权限码判断。
• 新增模块时同步补齐权限码、菜单项、路由权限和按钮控制。

渠道使用

渠道中心用于统一管理多端渠道的接口、支付和通知能力。相关接口说明与调试能力保留在交互式接口文档中，本节仅说明后台使用方式。

当前支持渠道

后台使用方式

1. 进入后台 渠道中心，选择需要维护的渠道。
2. 在 接口配置 中填写渠道基础信息，如应用标识、密钥和平台参数。
3. 在 支付配置 中按渠道启用可用支付方式并保存支付参数。
4. 在 通知配置 中按业务通知项配置通知方式。
5. 模板类通知由后台手动触发模板同步，不自动拉取。

配置原则

• 支付证书采用上传方式维护，不要求手动粘贴证书内容。
• 回调地址由系统内置生成，不作为后台录入项显示。
• 通知配置按业务通知项组织，不按驱动平铺。
• 模板消息与订阅消息保留示例说明，便于配置时核对字段。

文档与资源

项目文档与资源按用途拆分，避免在同一页面重复维护接口内容和界面资源说明。

维护建议

长期维护时建议保持目录、权限、页面和文档的同步更新，减少后期重复维护和残留问题。

新增功能时

• 服务端优先走正式入口 adminapi/controller 或 api/controller。
• 后台前端优先从规范模板复制，保证列表页和编辑页结构统一。
• 路由、权限、页面、接口、类型和文档应同步增加。

移除功能时

• 按“路由、权限、菜单、页面、API、类型、数据库、文档”整链回收。
• 不要只删页面或只删后端接口，必须做全局残留搜索。
• 删除完成后重新验证构建、类型检查和接口访问。

质量门禁

• 后台前端提交前通过 lint、stylelint、build:type。
• 服务端新增核心规则时，补清楚类职责、方法注释和责任边界。
• 文档中心用于项目说明、规范和示例，接口调试内容通过交互式接口文档查看。