签入版本

2026-10-20 21:19:44 +08:00
commit 7e70ed6942
2943 changed files with 498573 additions and 0 deletions
@@ -0,0 +1,523 @@
+# 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_ThinkPhp8_EleVue
+```
+
+:::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.thinkphp8.elevue  ; 数据库名
+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_ThinkPhp8_EleVue\uploads  ; 上传目录（绝对路径）
+DOMAIN_URL = http://file.thinkphp8.elevue  ; 文件访问域名
+```
+
+:::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.thinkphp8.elevue.sql        # MySQL 版本
+├── postgresql/rxthinkcmf.thinkphp8.elevue.sql   # PostgreSQL 版本
+├── sqlserver/rxthinkcmf.thinkphp8.elevue.sql    # SQL Server 版本
+├── oracle/rxthinkcmf.thinkphp8.elevue.sql       # Oracle 版本
+└── sqlite/rxthinkcmf.thinkphp8.elevue.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.thinkphp8.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
+
+# -----------------------------------------------------------------------------
+# 第 2 步：导入数据库脚本
+# -----------------------------------------------------------------------------
+# -uroot -proot → 用户名和密码
+# rxthinkcmf...   → 目标数据库名
+# < file.sql      → 将 SQL 文件作为 mysql 命令的输入
+mysql -uroot -proot rxthinkcmf.thinkphp8.elevue < document/mysql/rxthinkcmf.thinkphp8.elevue.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.thinkphp8.elevue/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 分钟即可完成。如果在操作过程中遇到问题，请查阅文档或在社区寻求帮助。