# 1.4 新手入门指南

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

## 教程概述

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

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

## 第一步：环境准备

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

| 软件 | 版本要求 | 用途 |
|------|----------|------|
| PHP | 8.2+ | 后端运行环境 |
| MySQL | 8.0+ | 数据库（也支持 PostgreSQL、SQL Server、Oracle、SQLite） |
| Composer | 2.x | PHP 依赖管理 |
| Node.js | 22+ | 前端构建环境 |
| pnpm | 12+ | 前端包管理器 |

:::tip 温馨提示
详细的安装步骤请参考 [开发环境准备](/zh/quickstart/environment.html) 章节。
:::

## 第二步：获取源码

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

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

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

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

## 第三步：后端启动

### 3.1 安装 Composer 依赖

```bash
# -----------------------------------------------------------------------------
# 安装项目依赖（从 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
```

编辑 `.env` 文件，配置数据库连接信息：

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

; 数据库配置
[DATABASE]
TYPE = mysql                        ; 数据库类型
HOSTNAME = 127.0.0.1                ; 数据库地址
DATABASE = rxthinkcmf.thinkphp6.naivevue  ; 数据库名
USERNAME = root                     ; 用户名
PASSWORD = root                     ; 密码
HOSTPORT = 3306                     ; 端口
CHARSET = utf8mb4                   ; 字符集（支持 emoji）
PREFIX = think_                     ; 表前缀

; JWT 密钥配置（生产环境务必修改为强随机字符串）
[JWT]
SECRET = rxthinkcmf_jwt_secret_key_2024     ; 签名密钥
ACCESS_TTL = 7200                            ; access_token 有效期（秒）
REFRESH_TTL = 604800                         ; refresh_token 有效期（秒）

; 文件上传配置
[FILE]
UPLOAD_DIR = D:\xampp8.2\htdocs\RXThinkCMF_ThinkPhp6_NaiveVue\uploads  ; 上传目录（绝对路径）
DOMAIN_URL = http://file.thinkphp6.naivevue  ; 文件访问域名
```

:::danger 重要提示
1. `.env` 使用 INI 分组格式，`[DATABASE]` 下的 `DATABASE` 是数据库名称，需提前在 MySQL 中创建。
2. `[JWT]` 下的 `SECRET` 生产环境务必修改为强随机字符串，生成方式：`php -r "echo bin2hex(random_bytes(32));"`
3. `[FILE]` 下的 `UPLOAD_DIR` 需使用绝对路径，确保目录存在且有写入权限。
:::

### 3.3 初始化数据库

**方式一：导入 SQL 脚本（推荐）**

项目为每种数据库提供了独立的 SQL 脚本，存放在 `document/` 目录下：

```text
document/
├── mysql/rxthinkcmf.thinkphp6.naivevue.sql        # MySQL 版本
├── postgresql/rxthinkcmf.thinkphp6.naivevue.sql   # PostgreSQL 版本
├── sqlserver/rxthinkcmf.thinkphp6.naivevue.sql    # SQL Server 版本
├── oracle/rxthinkcmf.thinkphp6.naivevue.sql       # Oracle 版本
└── sqlite/rxthinkcmf.thinkphp6.naivevue.sql       # SQLite 版本
```

以 MySQL 为例：

```bash
# -----------------------------------------------------------------------------
# 第 1 步：登录 MySQL，创建数据库
# -----------------------------------------------------------------------------
# -uroot -p → 以 root 用户连接，-p 交互式输入密码
mysql -uroot -p

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

# -----------------------------------------------------------------------------
# 第 2 步：导入数据库脚本
# -----------------------------------------------------------------------------
# -uroot -proot → 用户名和密码
# rxthinkcmf...   → 目标数据库名
# < file.sql      → 将 SQL 文件作为 mysql 命令的输入
mysql -uroot -proot rxthinkcmf.thinkphp6.naivevue < document/mysql/rxthinkcmf.thinkphp6.naivevue.sql
```

:::tip 温馨提示
项目支持 MySQL、PostgreSQL、SQL Server、Oracle、SQLite 五种数据库。请根据你使用的数据库类型选择对应的脚本导入。详细的多数据库初始化步骤请参考 [数据库初始化](/zh/quickstart/database-init.html) 章节。
:::

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

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

### 3.4 启动后端服务

```bash
# -----------------------------------------------------------------------------
# 使用 ThinkPHP 内置开发服务器（默认监听 127.0.0.1:8000）
# -----------------------------------------------------------------------------
php think run
```

启动成功后会看到：

```html
ThinkPHP Development server is started
<http://0.0.0.0:8000>
You can exit with `CTRL-C`
```

:::tip 温馨提示
打开浏览器访问 `http://localhost:8000/` 可验证后端服务是否正常启动。
:::

## 第四步：前端启动

### 4.1 安装前端依赖

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

# 安装依赖（从 pnpm-lock.yaml 精确安装）
pnpm install
```

:::tip 温馨提示
如果安装速度较慢，可配置国内镜像源：
```bash
# 配置 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.config.ts` 中配置了代理，前端请求 `/api/*` 路径时自动转发到后端 `http://admin.thinkphp6.naivevue/api/`。
:::

## 第五步：功能验证

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

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

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

以项目内置的「案例演示」模块为例，演示如何新增一个完整的 CRUD 模块。

### 6.1 数据库建表

```sql
-- =============================================================================
-- 创建案例演示表
-- =============================================================================
-- 表前缀 think_ 由 .env 中 DATABASE.PREFIX 决定
-- BaseModel 会自动管理 create_time / update_time / create_user / update_user
-- =============================================================================

CREATE TABLE think_example (
    id INT PRIMARY KEY AUTO_INCREMENT,          -- 主键，自增
    name VARCHAR(200) NOT NULL COMMENT '案例名称',  -- 业务字段
    type TINYINT(1) DEFAULT 0 COMMENT '案例类型',   -- 字典字段（example_type）
    status TINYINT(1) DEFAULT 0 COMMENT '案例状态', -- 字典字段（example_status）
    sort INT DEFAULT 0 COMMENT '排序',              -- 排序值（升序）
    avatar VARCHAR(500) DEFAULT '' COMMENT '头像',  -- 文件字段
    is_delete TINYINT(1) DEFAULT 0,                 -- 软删除标记（0=正常，1=已删除）
    create_user VARCHAR(50) DEFAULT '',             -- 创建人（BaseModel 自动写入）
    create_time DATETIME,                           -- 创建时间（BaseModel 自动写入）
    update_user VARCHAR(50) DEFAULT '',             -- 更新人（BaseModel 自动写入）
    update_time DATETIME                            -- 更新时间（BaseModel 自动写入）
);
```

### 6.2 后端开发

**Model** — `app/model/Example.php`：

```php
<?php
namespace app\model;
use app\BaseModel;

/**
 * 案例模型
 * 继承 BaseModel 自动获得软删除、时间戳、创建人等功能
 */
class Example extends BaseModel
{
    /**
     * 对应数据库表名（不含前缀）
     *
     * @var string
     */
    protected $name = 'example';
}
```

**Validate** — `app/validate/ExampleValidate.php`：

```php
<?php
namespace app\validate;
use think\Validate;

/**
 * 案例验证器
 * 定义字段验证规则和场景
 */
class ExampleValidate extends Validate
{
    /**
     * 验证规则
     *
     * name 字段必填
     *
     * @var array
     */
    protected $rule = ['name' => 'require'];

    /**
     * 自定义错误提示
     *
     * @var array
     */
    protected $message = ['name.require' => '请输入案例名称'];

    /**
     * 验证场景
     *
     * add 和 update 场景都验证 name
     *
     * @var array
     */
    protected $scene = ['add' => ['name'], 'update' => ['name']];
}
```

**Logic** — `app/logic/ExampleLogic.php`：

```php
<?php
namespace app\logic;
use app\BaseLogic;
use app\model\Example;

/**
 * 案例业务逻辑
 * 继承 BaseLogic 自动获得分页、新增、更新、删除、详情等基础 CRUD
 */
class ExampleLogic extends BaseLogic
{
    /**
     * 关联的模型类
     *
     * @var string
     */
    protected string $modelClass = Example::class;

    /**
     * 需要自动处理的文件上传字段
     *
     * @var array
     */
    protected array $fileFields = ['avatar'];

    /**
     * 文件保存的子目录
     *
     * @var string
     */
    protected string $fileSaveDir = 'example';

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

    /**
     * 精确匹配字段
     *
     * @var array
     */
    protected array $pageEqFields = ['type', 'status'];

    /**
     * 默认排序规则
     *
     * @var array
     */
    protected array $pageOrderBy = ['field' => 'sort', 'type' => 'asc'];

    /**
     * 枚举显示名映射
     *
     * @var array
     */
    protected array $serializeMaps = [
        'type' => 'example_type',
        'status' => 'example_status',
    ];
}
```

**Controller** — `app/controller/ExampleController.php`：

```php
<?php
namespace app\controller;
use app\BaseController;
use app\logic\ExampleLogic;
use app\attribute\Log;             // 操作日志注解
use app\attribute\Permission;      // 权限注解
use think\response\Json;

/**
 * 案例控制器
 * 定义 API 路由对应的处理方法
 */
class ExampleController extends BaseController
{
    protected ExampleLogic $logic;

    protected function initialize(): void
    {
        $this->logic = new ExampleLogic();  // 初始化业务逻辑层
    }

    // #[Log] 注解：自动记录操作日志
    // #[Permission] 注解：自动校验用户权限
    #[Log('案例演示-查询分页', Log::TYPE_QUERY)]
    #[Permission('sys:example:page', '案例分页')]
    public function page(): Json
    {
        return parent::_index($this->logic);    // 调用父类分页方法
    }

    #[Log('案例演示-新增', Log::TYPE_ADD, '新增案例：{name}')]
    #[Permission('sys:example:add', '添加案例')]
    public function add(): Json
    {
        return parent::_add($this->logic, $this->getJsonBody());    // 调用父类新增方法
    }

    // ... 其他 CRUD 方法
}
```

### 6.3 注册路由

在 `route/app.php` 中添加：

```php
// 案例演示模块路由（RESTful 风格）
Route::group('example', function () {
    Route::get('page', 'ExampleController/page');           // 分页查询
    Route::get('detail/:id', 'ExampleController/detail');   // 详情（路径参数）
    Route::post('add', 'ExampleController/add');            // 新增
    Route::put('update', 'ExampleController/update');       // 更新
    Route::delete('delete/:id', 'ExampleController/delete');         // 删除单条
    Route::delete('batchDelete', 'ExampleController/batchDelete');   // 批量删除
});
```

### 6.4 前端开发

在 `ui/src/api/tool/example.ts` 中定义接口，在 `ui/src/views/tool/example/` 中创建页面文件。

### 6.5 配置菜单权限

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

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

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

## 常见问题

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

```text
1. 端口被占用：执行 php think run --port 8080 更换端口。
2. 数据库连接失败：检查 .env 中的数据库配置，确认 MySQL 服务已启动。
3. PHP 扩展缺失：运行 php -m 检查 pdo_mysql、mbstring、gd 等扩展。
4. Composer 安装慢：配置国内镜像 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。
5. pnpm install 失败：配置国内镜像 pnpm config set registry https://registry.npmmirror.com。
6. 前端白屏：检查后端服务是否启动，浏览器控制台是否有报错。
```

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

## 总结

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

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

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