# GiiAdmin

**Repository Path**: tg1/gii-admin

## Basic Information

- **Project Name**: GiiAdmin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-14
- **Last Updated**: 2025-10-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 项目文档

本文档旨在为将来的二次开发提供参考，包含了项目的初始配置和权限管理系统的说明。

## 首次上手配置

开始项目前，需要进行以下环境配置。

1.  **创建环境配置文件**: 在项目根目录中，复制 `.example.env` 文件并重命名为 `.env`。
    ```bash
    cp .example.env .env
    ```

2.  **配置数据库**: 打开 `.env` 文件，根据你的本地环境修改以下数据库连接信息：
    ```
    DB_TYPE=mysql
    DB_HOST=127.0.0.1
    DB_NAME=your_database_name
    DB_USER=your_database_username
    DB_PASS=your_database_password
    DB_PORT=3306
    ```

3.  **导入数据库**: 将项目根目录下的 `admin.sql` 文件导入到你的 MySQL 数据库中，以创建所需的表结构。

## 权限管理 (Token 机制)

本项目使用 JWT (JSON Web Tokens) 进行用户认证。

### 工作流程

1.  **用户登录**: 用户通过用户名和密码进行登录。此逻辑由 `app/admin/controller/Admin.php` 控制器中的 `login` 方法处理。

2.  **生成 Token**: 登录成功后，`AdminService` 会生成一个 JWT Token。

3.  **请求头中携带 Token**: 客户端在后续所有需要认证的请求中，都必须在 `X-Token` 请求头中携带此 Token。

4.  **Token 验证**: `app/admin/middleware/Auth.php` 中间件会拦截所有传入的请求。它会检查请求头中的 `X-Token` 并进行验证。
    -   如果 Token 缺失、无效或已过期，中间件会返回相应的 JSON 格式错误信息。
    -   如果 Token 验证通过，用户的 ID 会被附加到请求对象上 (`$request->userId`)，然后请求会继续流向目标控制器。

### 核心文件

-   **`app/admin/middleware/Auth.php`**: 认证中间件，用于保护需要登录才能访问的路由。
-   **`app/admin/controller/Admin.php`**: 包含了 `login`（登录）和 `info`（获取用户信息）等操作。`info` 方法是一个受保护接口的例子，它会使用已认证用户的 ID。
-   **`config/jwt.php`**: JWT 的配置文件，包含了加密密钥 (`key`) 和 Token 的过期时间 (`exp`)。你可以在此文件中修改密钥和 Token 的有效时长。

### 在控制器中使用

在任何受 `Auth` 中间件保护的控制器方法中，你可以通过以下方式获取当前登录用户的 ID：

```php
$userId = $this->request->userId;
```

### 不需要验证登录的 API

如果某些 API 不需要验证登录，可以通过在控制器中设置中间件的排除规则来实现。例如：

```php
protected function initialize() {
    $this->setMiddlewareExcept(['login', 'publicApi']);
}
```

在上述代码中，`login` 和 `publicApi` 方法将不会被 `Auth` 中间件拦截。

#### 示例代码

以下是一个不需要验证登录的 API 的完整示例：

```php
public function publicApi() {
    return $this->success(['message' => '这是一个公开的 API，无需登录即可访问']);
}
```

通过这种方式，可以灵活地控制哪些方法需要验证登录，哪些方法不需要验证登录。

## 默认增删改查方法

`Base` 控制器中提供了默认的增删改查方法，方便快速开发。以下是这些方法的说明：

### 方法列表

1. **`save`**: 用于新增或更新记录。
2. **`delete`**: 用于删除记录。
3. **`info`**: 用于获取单条记录的详情。

### 钩子方法

在执行增删改查操作时，`Base` 控制器提供了以下钩子方法，允许在操作前后执行自定义逻辑：

- **`beforeSave(&$params)`**: 在保存（新增或更新）数据前执行，可以对 `$params` 进行修改或校验。
- **`afterSave($id)`**: 在保存（新增或更新）数据后执行，可以进行后续处理。
- **`beforeDelete($pkValue)`**: 在删除数据前执行，可以校验是否允许删除。
- **`afterDelete($pkValue, $result)`**: 在删除数据后执行，可以进行后续处理。
- **`beforeInfo(&$data)`**: 在获取详情前执行，可以对数据进行处理。
- **`afterInfo(&$data)`**: 在获取详情后执行，可以对数据进行处理。

### 前端如何传递数据

#### 1. 新增或更新数据

前端通过 POST 请求调用 `save` 方法，传递的参数应包含模型字段。例如：

```json
{
    "id": 1, // 如果是更新操作，需传递主键ID；新增操作则无需传递
    "username": "admin",
    "password": "123456",
    "email": "admin@example.com"
}
```

#### 2. 删除数据

前端通过 POST 请求调用 `delete` 方法，传递的参数应包含主键字段。例如：

```json
{
    "id": 1 // 要删除记录的主键ID
}
```

#### 3. 获取单条记录详情

前端通过 GET 请求调用 `info` 方法，传递的参数应包含主键字段。例如：

```json
{
    "id": 1 // 要查询记录的主键ID
}
```

通过这些默认方法和钩子，您可以快速实现增删改查功能，同时保留灵活性以满足业务需求。