# hyperf-admin

**Repository Path**: laravel-admin/hyperf-admin

## Basic Information

- **Project Name**: hyperf-admin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# hyperf-admin

当前仓库已完成前三个阶段中的基础环境、菜单路由源与数据层迁移工作；目前可以直接基于 `server/` 继续进行 Hyperf 后台接口迁移与联调。

## 目录结构

```text
.
├── .docker/
│   ├── data/
│   │   ├── mysql/
│   │   └── redis/
│   ├── docker-compose-local.yml
│   └── server/
├── client/
├── server/
│   ├── app/
│   │   ├── Command/
│   │   └── Model/
│   └── database/
│       ├── migrations/
│       │   └── 2026/
│       └── seeders/
├── .env.example
├── .env
└── docker-compose.yml -> .docker/docker-compose-local.yml
```

## 初始化环境

1. 复制环境文件：

```bash
cp .env.example .env
```

2. 启动容器：

```bash
docker compose up -d --build
```

3. 安装 `server/` 依赖：

```bash
docker compose exec server composer install
```

4. 确认 `server/.env` 与 `client/.env` 都软链接到根目录 `.env`：

```bash
ls -l server/.env client/.env
```

5. 执行数据库迁移：

```bash
docker compose exec server php bin/hyperf.php migrate:all
```

6. 启动 Hyperf 服务：

```bash
docker compose exec server php bin/hyperf.php start
```

7. 访问接口验证：

```bash
curl 'http://127.0.0.1:9501/?user=Stage1'
```

如果 `client/.env` 尚未建立，可以手动创建：

```bash
ln -s ../.env client/.env
```

## 常用命令

数据库迁移目录已切换到 `server/database/migrations/<year>/`，例如 `server/database/migrations/2026/`。

执行全部年度迁移：

```bash
docker compose exec server php bin/hyperf.php migrate:all
```

新增迁移文件，默认生成到当年目录：

```bash
docker compose exec server php bin/hyperf.php gen:migration create_example_table
```

数据库迁移状态：

```bash
docker compose exec server php bin/hyperf.php migrate:status
```

执行默认 Seeder 入口：

```bash
docker compose exec server php bin/hyperf.php db:seed
```

执行指定 Seeder：

```bash
docker compose exec server php bin/hyperf.php db:seed --class=Database\\Seeders\\VersionSeeder
```

重建运行时容器缓存：

```bash
docker compose exec server sh -lc 'rm -rf runtime/container'
```

查看异步队列状态：

```bash
docker compose exec server php bin/hyperf.php queue:info
```

启动 Hyperf 服务：

```bash
docker compose exec server php bin/hyperf.php start
```

生成模型骨架：

```bash
docker compose exec server php bin/hyperf.php create:model User
```

按模型生成 Seeder：

```bash
docker compose exec server php bin/hyperf.php create:seed User
```

## 第二阶段：共享菜单路由源

`server/config/route.json` 现在是后台接口路由、菜单权限数据和前端页面路由的统一源数据。

- `group`：定义路由组前缀、命名空间和中间件。
- `menus`：定义普通菜单或独立权限节点。
- `resource`：定义资源菜单，启动时会按 `options.only` 自动展开出 `index/list/create/update/delete` 等子路由。
- `update_position`：定义菜单树同步后的节点位置调整规则。

完成迁移后，可先执行一次全量同步，把 JSON 写入 `menus` 表：

```bash
docker compose exec server php bin/hyperf.php route-json:sync-to-menus --fresh
```

如果后续在页面侧维护了 `menus` 表数据，可以再导出回同一份 JSON 文件：

```bash
docker compose exec server php bin/hyperf.php menus:sync-to-route-json
```

动态路由注册由 `server/config/routes.php` 在启动时自动完成，启动服务后可直接验证：

```bash
curl 'http://127.0.0.1:9501/admin/menus/tree'
curl 'http://127.0.0.1:9501/admin/users/list'
curl 'http://127.0.0.1:9501/admin/users'
```

## 第三阶段：数据层迁移已完成

`server/database/` 与 `server/app/Model/` 已完成第三阶段的核心迁移，当前可以直接用 Hyperf 的迁移、Seeder 与模型层支撑后续接口开发。

- 迁移文件统一维护在 `server/database/migrations/<year>/`，`migrate:all` 会自动按年份目录顺序执行全部迁移。
- `gen:migration` 默认输出到当年目录，避免迁移文件散落在单层目录中。
- `Database\\Seeders\\Seeder` 与 `Database\\Seeders\\DatabaseSeeder` 已接入，支持默认全量初始化和 `--class` 指定执行。
- `server/app/Model/` 下已迁移用户、管理员、角色、菜单、配置、参数、响应体等模型，并保留自定义 Cast 与 Traits。
- `App\\Model\\Model` 统一继承 Hyperf Model，`App\\Model\\Traits\\BaseModel` 提供原项目常用的查询作用域、字段映射、表信息读取与批量 replace 能力，用于兼容 LaravelAdmin 既有调用方式。
- `create:model`、`create:seed` 已迁移到 Hyperf 项目内，便于继续补充数据模型和初始化数据脚本。

完成第三阶段后，推荐按以下顺序初始化本地数据：

```bash
docker compose exec server php bin/hyperf.php migrate:all
docker compose exec server php bin/hyperf.php db:seed
docker compose exec server php bin/hyperf.php route-json:sync-to-menus --fresh
```

## Git Hook

仓库内置了 `.githooks/post-merge` 和 `.githooks/post-checkout`，当 `server/config/route.json` 在拉取或切换分支后发生变化时，会自动执行同步命令。

首次使用需要在本地启用 hooks：

```bash
git config core.hooksPath .githooks
```

触发自动同步前请确保 `server` 容器已经启动；如果容器未运行，hook 会跳过并提示手动执行同步命令。

## 后续衔接

- 后续接口迁移优先复用 `server/app/Model/` 中已完成的模型兼容层，避免在常驻内存环境下重复拼接全局状态或绕开模型约定。
- 新增表结构继续使用 `gen:migration` 与年度目录规范；涉及初始化数据时优先补充 `database/seeders/` 并通过 `db:seed --class=...` 做增量验证。
- 菜单、权限与页面路由仍以 `server/config/route.json` 和 `menus` 表同步链路为主，后续控制器与服务层直接衔接现有数据结构即可。
- 若继续迁移后台业务接口，建议先完成用户、管理员、角色、配置相关服务，再逐步接入页面管理与权限控制。

## 说明

- `docker-compose.yml` 是软链接，默认指向 `.docker/docker-compose-local.yml`，便于后续切换不同环境配置。
- MySQL 和 Redis 的持久化数据统一存放在 `.docker/data/<service>/`。
- 根目录 `.env` 是唯一环境源，`server/.env` 和 `client/.env` 都应软链接到它。
- 数据库迁移文件统一维护在 `server/database/migrations/<year>/`，新增迁移默认写入当前年份目录。
- `server/database/seeders/` 已通过 Composer PSR-4 自动加载到 `Database\\Seeders\\` 命名空间。
- `php bin/hyperf.php start` 会同时拉起 HTTP 服务和默认的异步队列消费进程 `queue.default.0`。