# 1.4 新手入门指南

:::warning 特别提醒
官方精心制作本教程，目的在于方便用户快速掌握软件产品的使用和部署。通过此教程，刚入行的开发者也可以快速掌握并投入产品研发。本地部署时务必请耐心阅读文档操作。
:::

## 教程概述

本教程将带你从零开始，完成一个完整的后台管理系统的搭建和运行。整个过程分为以下几个步骤：

```text
1. 环境准备：安装 PHP、MySQL、Redis、Composer、Node.js 等基础软件。
2. 获取源码：从[官方网站](https://www.rxthink.cn)下载授权源码包并解压。
3. 后端启动：安装 Composer 依赖、配置环境变量、初始化数据库、启动后端服务。
4. 前端启动：安装前端依赖、启动前端开发服务器。
5. 功能验证：登录系统，验证各功能模块是否正常。
6. 新增模块：以 example 模块为例，演示如何新增一个完整的业务模块。
```

## 第一步：环境准备

确保电脑上已安装以下软件：

| 软件 | 版本要求 | 用途 |
|------|----------|------|
| PHP | 8.3+ | 后端运行环境 |
| MySQL | 8.0+ | 数据库（另支持 PostgreSQL、SQL Server、Oracle、SQLite） |
| Redis | 6.0+ | **必需**：JWT 会话、权限缓存、验证码、字典缓存均依赖 |
| Composer | 2.x | PHP 依赖管理 |
| Node.js | 22.18.0（22+） | 前端构建环境 |

:::tip 温馨提示
Windows 环境推荐使用 Laragon 集成安装（含 PHP / MySQL / Redis），详细步骤请参考 [2.1 开发环境准备](/zh/quickstart/environment.html) 与 [2.2 Laragon 环境搭建](/zh/quickstart/laragon.html)。不想手动搭建环境可直接使用 [2.8 Docker 快速体验](/zh/quickstart/docker.html)。
:::

## 第二步：获取源码

前往 [官方网站](https://www.rxthink.cn) 购买授权后，按以下步骤获取源码：

1. 登录[官方网站](https://www.rxthink.cn)，进入「个人中心」→「我的订单」页面。
2. 在订单列表中找到已购买的授权订单，点击「下载」按钮。
3. 下载的压缩包包含完整的后端源码、数据库脚本及部署配置文件。
4. 将压缩包解压到本地开发目录（如 `D:\laragon\www\` 或 `~/www/`）。

```bash
# 进入项目目录（以实际解压路径为准）
cd RXThinkCMF_Laravel13_NaiveVue
```

:::tip 温馨提示
1. 源码包请务必从[官方网站](https://www.rxthink.cn)订单中心下载，确保获取的是正版授权的最新版本。
2. 授权有效期内可无限次下载最新版本，版本更新后可重新下载获取最新源码。
3. 解压后请先阅读根目录下的 `README.md` 了解项目概况。
:::

## 第三步：后端启动

### 3.1 安装 Composer 依赖

```bash
# -----------------------------------------------------------------------------
# 方式一：一键初始化（推荐，自动完成依赖安装 + .env + APP_KEY + 迁移 + 前端构建）
# -----------------------------------------------------------------------------
composer setup

# -----------------------------------------------------------------------------
# 方式二：手动逐步执行
# -----------------------------------------------------------------------------
# 安装项目依赖（从 composer.lock 精确安装）
composer install

# 如果国内下载慢，先配置阿里云镜像（加速依赖下载）
# config -g → 修改全局配置（所有项目生效）
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
composer install
```

### 3.2 配置环境变量

```bash
# 复制环境变量模板（.env.example 是模板，.env 是实际配置文件）
cp .env.example .env

# 生成应用加密密钥（APP_KEY，写入 .env）
php artisan key:generate
```

编辑 `.env` 文件，重点确认以下配置：

```ini
# 开启调试模式（开发环境 true，生产环境必须 false）
APP_DEBUG=true

# 数据库配置
DB_CONNECTION=mysql                 # 数据库类型（mysql / pgsql / sqlsrv / sqlite）
DB_HOST=127.0.0.1                   # 数据库地址
DB_PORT=3306                        # 端口
DB_DATABASE=rxthinkcmf.laravel13.naivevue   # 数据库名（需提前创建）
DB_USERNAME=root                    # 用户名
DB_PASSWORD=root                    # 密码
DB_PREFIX=laravel_                  # 表前缀（数据库脚本使用 laravel_ 前缀，必须保留）

# JWT 密钥配置（应用启动 fail-close 校验：必须 >= 32 字符）
JWT_SECRET=your_random_jwt_secret_key_at_least_32_bytes
JWT_ACCESS_TTL=7200                 # access_token 有效期（秒，默认 2 小时）
JWT_REFRESH_TTL=604800              # refresh_token 有效期（秒，默认 7 天）

# Redis 配置（必需；设置了 requirepass 时必须同步本项）
REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null                 # Redis 有密码时改为实际密码
REDIS_PORT=6379

# 会话 / 缓存 / 队列统一走 Redis（数据库脚本不含 framework 表）
SESSION_DRIVER=redis
CACHE_STORE=redis
QUEUE_CONNECTION=redis

# 跨域（本地开发允许前端域名，生产环境改为具体域名）
CORS_ALLOW_ORIGIN=*

# 文件上传
FILE_UPLOAD_DIR=uploads             # 上传目录（相对 public/）
FILE_DOMAIN_URL=                    # 文件访问域名（空则返回相对路径）
FILE_MAX_SIZE=10                    # 单文件大小上限（MB）
```

:::danger 重要提示
1. `JWT_SECRET` 为空或不足 32 字符时，应用**拒绝启动**并抛出异常（fail-close 安全机制）。生成方式：`openssl rand -base64 32` 或 `php -r "echo bin2hex(random_bytes(32));"`。
2. `DB_PREFIX=laravel_` 必须保留，数据库脚本中的表均使用该前缀。
3. Redis 设置了密码（`requirepass`）时，`.env` 中 `REDIS_PASSWORD` 必须同步配置，否则验证码、JWT 会话等会全部失败。
:::

### 3.3 初始化数据库

**本项目未使用 Laravel 迁移建表**（`database/migrations/` 为空），数据库结构以 SQL 脚本为准：

```bash
# -----------------------------------------------------------------------------
# 第 1 步：登录 MySQL，创建数据库
# -----------------------------------------------------------------------------
mysql -uroot -p

# 在 MySQL 命令行中执行（创建项目数据库）：
# CHARACTER SET utf8mb4 → 支持 emoji 等四字节字符
# COLLATE utf8mb4_general_ci → 不区分大小写的排序规则
CREATE DATABASE `rxthinkcmf.laravel13.naivevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

# -----------------------------------------------------------------------------
# 第 2 步：导入数据库脚本（约 226MB，含 25 张业务表 + 初始数据）
# -----------------------------------------------------------------------------
mysql -uroot -proot rxthinkcmf.laravel13.naivevue < document/mysql/rxthinkcmf.laravel13.naivevue.sql
```

:::tip 温馨提示
- 脚本位于 `document/mysql/rxthinkcmf.laravel13.naivevue.sql`（五种数据库各有专用脚本，按 `document/<数据库类型>/` 分组），导入耗时约 1~3 分钟；
- 使用 [2.8 Docker 快速体验](/zh/quickstart/docker.html) 时无需手动导入，首次启动自动完成；
- 详细的多数据库初始化步骤请参考 [2.5 数据库初始化](/zh/quickstart/database-init.html)。
:::

初始化完成后，数据库中包含以下默认数据：

```text
管理员账号：admin / 123456（超级管理员，ID=1，跳过权限校验）
默认角色：超级管理员角色
默认菜单：系统管理、内容管理、监控管理等菜单及权限节点
数据字典：系统内置字典数据
系统配置：系统默认配置项、系统参数
城市数据：全国行政区划数据
默认租户：平台租户数据
```

### 3.4 启动后端服务

```bash
# -----------------------------------------------------------------------------
# 推荐：一键启动（同时启动 artisan serve + 队列 + 日志流 + Vite 四个进程）
# -----------------------------------------------------------------------------
composer dev

# -----------------------------------------------------------------------------
# 或单独启动 API 服务（默认监听 127.0.0.1:8000）
# -----------------------------------------------------------------------------
php artisan serve
```

启动成功后会看到：

```text
INFO  Server running on [http://127.0.0.1:8000].
```

:::tip 温馨提示
打开浏览器访问 `http://admin.laravel13.naivevue/` 可验证后端服务是否正常启动；健康检查接口为 `http://admin.laravel13.naivevue/up`。
:::

## 第四步：前端启动

### 4.1 安装前端依赖

前端 NaiveVue 管理后台位于本仓库的 `ui/` 目录（Vue3 + NaiveUI）：

```bash
# 进入前端项目目录
cd ui

# 安装依赖（从 lock 文件精确安装）
npm install
# 或
pnpm install
```

:::tip 温馨提示
如果安装速度较慢，可配置国内镜像源：

```bash
# npm 国内镜像
npm config set registry https://registry.npmmirror.com

# pnpm 国内镜像
pnpm config set registry https://registry.npmmirror.com
```
:::

### 4.2 启动前端开发服务器

```bash
# 启动 Vite 开发服务器（支持热更新 — 修改代码后浏览器自动刷新）
pnpm dev
```

启动成功后会看到：

```text
  VITE v3.x.x  ready in xxx ms

  ➜  Local:   http://localhost:8001/
```

### 4.3 访问系统

打开浏览器访问 `http://localhost:8001`，使用默认账号登录：

```text
账号：admin
密码：123456
```

:::tip 温馨提示
前端默认运行在 `8001` 端口，后端默认 `8000` 端口。Vite 开发代理由 `ui/.env.development` 的 `VITE_PROXY` 决定（当前指向 `http://admin.laravel13.naivevue/api`，修改后重启 `pnpm dev` 生效）。登录后请立即修改默认密码。
:::

## 第五步：功能验证

登录成功后，可以验证以下核心功能：

```text
1. 控制台：首页仪表盘，显示系统概况。
2. 用户管理：系统管理 → 用户管理，查看用户列表、新增、编辑、删除。
3. 角色管理：系统管理 → 角色管理，管理角色和权限分配。
4. 菜单管理：系统管理 → 菜单管理，管理菜单和权限节点。
5. 数据字典：数据管理 → 字典管理，管理系统字典数据。
6. 操作日志：系统管理 → 日志管理 → 操作日志，查看操作记录。
7. 代码生成：开发工具 → 代码生成，体验代码生成功能。
```

也可直接用命令行验证接口链路（验证码接口同时验证 PHP → Redis 链路）：

```bash
curl http://admin.laravel13.naivevue/api/captcha
# → {"code":0,"ok":true,"msg":"操作成功","data":{...}}
```

## 第六步：新增业务模块

以项目内置的「案例演示」模块为例，演示如何新增一个完整的 CRUD 模块（该模块是代码生成器的参考模板，以下代码均摘自项目实际源码）。

### 6.1 数据库建表

```sql
-- =============================================================================
-- 创建案例演示表
-- =============================================================================
-- 表前缀 laravel_ 由 .env 中 DB_PREFIX 决定
-- 模型 Trait 会自动管理 create_user / create_time / update_user / update_time
-- =============================================================================

CREATE TABLE `laravel_example` (
    `id` INT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    `name` VARCHAR(200) NOT NULL COMMENT '案例名称',
    `code` VARCHAR(50) DEFAULT '' COMMENT '案例编码',
    `avatar` VARCHAR(500) DEFAULT '' COMMENT '头像/图片地址',
    `type` TINYINT(1) DEFAULT 1 COMMENT '类型：1=类型1 2=类型2 3=类型3 4=类型4',
    `status` TINYINT(1) DEFAULT 1 COMMENT '状态：1=在用 2=停用',
    `sort` INT DEFAULT 0 COMMENT '排序值',
    `is_delete` TINYINT(1) DEFAULT 0 COMMENT '软删除标记：0=正常 1=已删除',
    `create_user` VARCHAR(50) DEFAULT '' COMMENT '创建人',
    `create_time` DATETIME DEFAULT NULL COMMENT '创建时间',
    `update_user` VARCHAR(50) DEFAULT '' COMMENT '更新人',
    `update_time` DATETIME DEFAULT NULL COMMENT '更新时间',
    PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='案例演示';
```

### 6.2 模型层 — Model

`app/Models/Example.php`：

```php
<?php

namespace App\Models;

use App\Models\Concerns\HasAuditColumns;
use App\Models\Concerns\SoftDeletesByFlag;
use Illuminate\Database\Eloquent\Model;

/**
 * 案例演示模型
 *
 * 对应数据表 example，继承 Eloquent Model 获得通用模型能力。
 *
 * 说明：
 * - 通过 HasAuditColumns 自动维护审计字段（如 created_by、updated_by 等）。
 * - 通过 SoftDeletesByFlag 实现基于标志位的软删除（如 is_deleted 字段）。
 * - type 类型：1=类型1，2=类型2，3=类型3，4=类型4。
 * - status 状态：1=在用，2=停用。
 */
class Example extends Model
{
    use HasAuditColumns, SoftDeletesByFlag;

    /**
     * 数据表名
     *
     * 显式指定表名为 example，覆盖默认的类名推导规则。
     *
     * @var string
     */
    protected $table = 'example';

    /**
     * 允许批量赋值的字段列表
     *
     * @var array<int, string>
     */
    protected $fillable = [
        'name',   // 名称
        'avatar', // 头像/图片地址
        'type',   // 类型：1=类型1，2=类型2，3=类型3，4=类型4
        'status', // 状态：1=在用，2=停用
        'sort',   // 排序值，数值越小越靠前（视业务而定）
    ];
}
```

:::tip
表名 `example` 不含前缀，实际查询时由 `DB_PREFIX=laravel_` 自动拼接为 `laravel_example`。
:::

### 6.3 参数验证 — FormRequest

`app/Http/Requests/ExampleRequest.php`：

```php
<?php

namespace App\Http\Requests;

/**
 * 案例表单请求
 *
 * 负责案例演示新增/修改接口的参数校验。
 *
 * 说明：
 * - 继承 BaseRequest，基础校验能力（失败响应统一处理）由基类提供。
 * - 本类只声明案例特有的字段规则与自定义错误消息。
 * - 前端传参使用 camelCase，数据库字段为 snake_case；
 */
class ExampleRequest extends BaseRequest
{
    /**
     * 校验规则
     *
     * @return array<string, string> 字段规则
     */
    public function rules(): array
    {
        return [
            'name' => 'required|string|max:255',       // 案例名称：必填，最长 255
            'avatar' => 'nullable|string|max:255',     // 头像/图片地址：可空，最长 255
            'type' => 'nullable|integer|in:1,2,3,4',   // 类型：1=类型1，2=类型2，3=类型3，4=类型4
            'status' => 'nullable|integer|in:1,2',     // 状态：1=在用，2=停用
            'sort' => 'nullable|integer',              // 排序值：可空，整数
        ];
    }

    /**
     * 自定义错误消息
     *
     * @return array<string, string> 字段规则 => 错误消息
     */
    public function messages(): array
    {
        return [
            'name.required' => '案例名称不能为空',
            'name.max' => '案例名称不能超过 255 个字符',
            'type.in' => '案例类型不合法，允许：1-类型1 2-类型2 3-类型3 4-类型4',
            'status.in' => '状态值不合法，允许：1-在用 2-停用',
            'sort.integer' => '排序值格式不正确',
        ];
    }
}
```

### 6.4 业务逻辑 — Service

`app/Services/ExampleService.php`（节选，完整代码见项目源码）：

```php
<?php

namespace App\Services;

use App\Models\Example;
use App\Services\Concerns\HasCrudOperations;
use App\Services\Concerns\HasQueryScopes;
use App\Services\Concerns\HasSerializeMaps;
use App\Services\Concerns\HasUniqueCheck;

/**
 * 案例演示业务逻辑服务
 *
 * 继承 BaseService，案例作为示例数据，不参与多租户隔离。
 *
 * 说明：
 * - 组合的 Trait 职责：
 *   - HasCrudOperations：add/update/delete/batchDelete 主流程；
 *   - HasQueryScopes：列表查询条件、排序白名单；
 *   - HasSerializeMaps：为 status 补 statusText（字典编码为 status）；
 *   - HasUniqueCheck：新增/修改时校验 name 唯一；
 * - 未 use HasDataScope，因此不做数据权限与租户隔离；
 */
class ExampleService extends BaseService
{
    use HasCrudOperations, HasQueryScopes, HasSerializeMaps, HasUniqueCheck;

    /**
     * 绑定的模型类
     */
    protected string $modelClass = Example::class;

    /**
     * LIKE 模糊匹配字段
     *
     * @var array<int, string>
     */
    protected array $pageLikeFields = ['name'];

    /**
     * 精确匹配字段
     *
     * status 用于按状态筛选。
     *
     * @var array<int, string>
     */
    protected array $pageEqFields = ['status'];

    /**
     * 唯一性校验字段
     *
     * @var array<int, string>
     */
    protected array $uniqueFields = ['name'];

    /**
     * 字典翻译配置：[字段 => 字典编码]
     *
     * 读取时为 status 补 statusText。
     *
     * @var array<string, string>
     */
    protected array $serializeMaps = [
        'status' => 'example_status',
    ];
}
```

分页、新增、修改、删除等方法**全部由 Trait 提供，无需手写**——这就是声明式 CRUD。

### 6.5 接口入口 — Controller

`app/Http/Controllers/Api/ExampleController.php`（节选）：

```php
<?php

namespace App\Http\Controllers\Api;

use App\Attributes\OperationLog;
use App\Attributes\Permission;
use App\Http\Controllers\Controller;
use App\Http\Requests\ExampleRequest;
use App\Services\ExampleService;
use Illuminate\Http\JsonResponse;

/**
 * 示例管理控制器
 *
 * 具体业务逻辑委托给 ExampleService，控制器仅做参数校验、
 * 权限与日志标注及响应封装。
 */
class ExampleController extends Controller
{
    public function __construct(protected ExampleService $exampleService) {}

    /**
     * 查询分页
     *
     * 对应权限：sys:example:page，操作日志类型：查询。
     *
     * @return JsonResponse 分页数据
     */
    #[OperationLog('示例管理-查询分页', OperationLog::TYPE_QUERY)]
    #[Permission('sys:example:page', '示例分页')]
    public function page(): JsonResponse
    {
        return $this->_page($this->exampleService);
    }

    /**
     * 新增
     *
     * @param  ExampleRequest  $request  已通过校验的示例请求
     * @return JsonResponse 新增结果
     */
    #[OperationLog('示例管理-新增', OperationLog::TYPE_ADD, '新增示例：{name}')]
    #[Permission('sys:example:add', '添加示例')]
    public function add(ExampleRequest $request): JsonResponse
    {
        return $this->_add($this->exampleService, $request->validated());
    }

    // 修改 / 删除 / 批量删除 / 导出 / 导入同理：
    // _update / _delete / _batchDelete / _export / _import 快捷方法一行调用
}
```

### 6.6 注册路由

在 `routes/api.php` 的认证中间件组中添加：

```php
// --- 案例演示 ---
Route::get('example/page', [Api\ExampleController::class, 'page']);
Route::get('example/list', [Api\ExampleController::class, 'list']);
Route::get('example/detail/{id}', [Api\ExampleController::class, 'detail']);
Route::post('example/add', [Api\ExampleController::class, 'add']);
Route::put('example/update', [Api\ExampleController::class, 'update']);
Route::delete('example/delete/{id}', [Api\ExampleController::class, 'delete']);
Route::delete('example/batchDelete', [Api\ExampleController::class, 'batchDelete']);
Route::get('example/export', [Api\ExampleController::class, 'export']);
Route::post('example/import', [Api\ExampleController::class, 'import']);
```

:::tip
公开接口（无需认证）应放在中间件组**外面**，认证接口放在 `['auth.jwt', 'tenant', 'demo', 'log.operation']` 组内——见 [3.7 路由注册](/zh/guide/route.html)。
:::

### 6.7 前端开发

在前端仓库的 `src/api/tool/example.ts` 中定义接口，在 `src/views/tool/example/` 中创建页面文件（列表页 / 编辑弹窗 / 详情弹窗 / 表格列定义 / 查询条件）。

### 6.8 配置菜单权限

在系统管理 → 菜单管理中：

```text
1. 新增菜单：案例演示（路由 /example，组件 tool/example/index）
2. 新增按钮：查看（sys:example:page）、新增（sys:example:add）、编辑（sys:example:update）、删除（sys:example:delete）
3. 在角色管理中为角色分配"案例演示"菜单权限
```

:::tip 温馨提示
也可以使用代码生成器一键生成以上所有代码，详见 [第 10 章 代码生成器](/zh/generator/overview.html)。
:::

## 常见问题

在部署和使用过程中，可能会遇到以下常见问题：

```text
1. 端口被占用：执行 php artisan serve --port 8080 更换端口。
2. 数据库连接失败：检查 .env 中的数据库配置，确认 MySQL 服务已启动、数据库已创建并导入脚本。
3. 应用拒绝启动并提示 JWT_SECRET：密钥为空或不足 32 字符，用 openssl rand -base64 32 生成后重试。
4. 验证码报"服务不可用"：确认 Redis 已启动，且 .env 中 REDIS_PASSWORD 与 Redis 实际密码一致。
5. PHP 扩展缺失：运行 php -m 检查 pdo_mysql、mbstring、gd、redis 等扩展（Laragon 下需手动安装 php_redis.dll，
   见 2.2 Laragon 环境搭建）。
6. Composer 安装慢：配置国内镜像 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。
7. npm install 失败：配置国内镜像 npm config set registry https://registry.npmmirror.com。
8. 前端白屏：检查后端服务是否启动，浏览器控制台是否有报错。
```

:::tip 温馨提示
更多问题请参考 [2.9 常见问题 FAQ](/zh/quickstart/faq.html) 章节。
:::

## 总结

通过以上步骤，你已经完成了从零搭建一个完整的后台管理系统的全过程：

```text
1. 环境准备：PHP 8.3 + MySQL 8.0 + Redis 6.0 + Composer 2.x + Node.js 22.18.0
2. 获取源码：从[官方网站](https://www.rxthink.cn)下载授权源码包
3. 后端启动：composer setup → 配置 .env → 导入数据库 → composer dev
4. 前端启动：cd ui → pnpm install → pnpm dev
5. 功能验证：登录系统，验证各模块功能
6. 新增模块：建表 → Model → FormRequest → Service → Controller → 路由 → 前端页面 → 菜单权限
```

整个搭建过程约 30 分钟即可完成。如果在操作过程中遇到问题，请查阅文档或在社区寻求帮助。