# quarkus-everwin-admin

**Repository Path**: everwin-admin_1/quarkus-everwin-admin

## Basic Information

- **Project Name**: quarkus-everwin-admin
- **Description**: 基于 Quarkus 3 + PostgreSQL 16 + Redis 的后台管理系统后端工程骨架（响应式 + Native 友好）。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-24
- **Last Updated**: 2026-03-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# quarkus-everwin-admin

基于 Quarkus 3 + PostgreSQL 16 + Redis 的后台管理系统后端工程骨架（响应式 + Native 友好）。

## 特性

- Quarkus REST + Jackson，统一响应封装
- Quarkus Security：RBAC（`@RolesAllowed`），权限点作为角色使用
- 认证方式：不透明 Token（Opaque Token），存储在 Redis（非 JWT）
- ORM：Quarkus Hibernate Reactive with Panache（Reactive）
- 数据库迁移：Flyway（JDBC 执行迁移，业务访问走 Reactive）
- 数据库约定：
  - 主键：`BIGINT GENERATED ALWAYS AS IDENTITY`
  - 不使用外键
  - 字段使用语义前缀（如 `usr_ / rol_ / perm_ / menu_ / dept_ / dict_ / oplog_`）
  - 审计字段：`created_Time/created_by/updated_Time/updated_by/deleted_Time/deleted_by`

## 目录结构（核心）

```
src/main/java/com/everwin/admin/
  bootstrap/                 # 启动入口与基础资源
  common/                    # 通用能力（响应封装、安全、工具）
  modules/
    iam/                     # 身份与权限（示例）
```

迁移脚本：

```
src/main/resources/db/migration/
  V1__init.sql
  V2__seed_admin.sql
```

## 环境要求

- JDK 17+
- Maven 3.9+
- PostgreSQL 16
- Redis 6+

## 本地启动

### 1) 准备数据库（PostgreSQL 16）

创建数据库：

```sql
create database quarkus_everwin_admin;
```

默认连接配置在：
- `src/main/resources/application.properties`

可按需调整：
- `quarkus.datasource.username`
- `quarkus.datasource.password`
- `quarkus.datasource.jdbc.url`
- `quarkus.datasource.reactive.url`

启动后 Flyway 会自动执行迁移（`quarkus.flyway.migrate-at-start=true`）。

### 2) 准备 Redis

默认连接：
- `quarkus.redis.hosts=redis://localhost:6379`

Token 存储 Key 约定：
- `auth:token:<token>` → `usrId`

### 3) 启动应用

```bash
mvn quarkus:dev
```

OpenAPI/Swagger：
- `/q/swagger-ui`
- `/q/openapi`

## 认证与权限（RBAC）

### 登录

接口：
- `POST /api/v1/auth/login`

请求示例：

```json
{"username":"admin","password":""}
```

说明：
- 种子数据中 `admin` 的 `usr_password_hash` 为空，因此 `password` 传空字符串即可（后续你写入 bcrypt hash 后会按 hash 校验）。

响应示例：

```json
{"code":"OK","data":{"token":"<opaque-token>"}}
```

### 携带 Token 访问

请求头：

```
Authorization: Bearer <opaque-token>
```

### 登出

- `POST /api/v1/auth/logout`

行为：
- 删除 Redis 中对应 token key（使 token 立即失效）

### 当前用户信息

- `GET /api/v1/auth/me`

### 权限点（示例）

接口保护示例：
- `GET /api/v1/users` 需要权限点 `iam:user:read`

实现方式：
- 用户的角色（`rol_code`）与权限点（`perm_code`）都会被放入 `SecurityIdentity.roles`，因此可以直接使用 `@RolesAllowed("iam:user:read")`。

## 已有接口

- `GET /api/v1/health`：健康检查
- `POST /api/v1/auth/login`：登录
- `POST /api/v1/auth/logout`：登出
- `GET /api/v1/auth/me`：当前用户与角色集合
- `GET /api/v1/users`：示例受保护接口（占位返回）

## 测试

```bash
mvn test
```

说明：
- test profile 下默认禁用 Flyway 自动迁移、禁用 Hibernate Reactive datasource，并禁用 Redis DevServices，保证无数据库/无 Redis 也能跑基础单测。