签入版本

RXThinkCMF_Laravel13_NaiveVue/zh/course.md

@@ -9,7 +9,7 @@
 本教程将带你从零开始，完成一个完整的后台管理系统的搭建和运行。整个过程分为以下几个步骤：
 
 ```text
-1. 环境准备：安装 PHP、MySQL、Composer、Node.js 等基础软件。
+1. 环境准备：安装 PHP、MySQL、Redis、Composer、Node.js 等基础软件。
 2. 获取源码：从[官方网站](https://www.rxthink.cn)下载授权源码包并解压。
 3. 后端启动：安装 Composer 依赖、配置环境变量、初始化数据库、启动后端服务。
 4. 前端启动：安装前端依赖、启动前端开发服务器。
@@ -23,36 +23,34 @@
 
 | 软件 | 版本要求 | 用途 |
 |------|----------|------|
-| PHP | 8.2+ | 后端运行环境 |
-| MySQL | 8.0+ | 数据库（也支持 PostgreSQL、SQL Server、Oracle、SQLite） |
+| PHP | 8.3+ | 后端运行环境 |
+| MySQL | 8.0+ | 数据库（另支持 PostgreSQL、SQL Server、Oracle、SQLite） |
+| Redis | 6.0+ | **必需**：JWT 会话、权限缓存、验证码、字典缓存均依赖 |
 | Composer | 2.x | PHP 依赖管理 |
-| Node.js | 22+ | 前端构建环境 |
-| pnpm | 12+ | 前端包管理器 |
+| Node.js | 22.18.0（22+） | 前端构建环境 |
 
 :::tip 温馨提示
-详细的安装步骤请参考 [开发环境准备](/zh/quickstart/environment.html) 章节。
+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) 购买授权后，按以下步骤获取源码：
 
-```text
 1. 登录[官方网站](https://www.rxthink.cn)，进入「个人中心」→「我的订单」页面。
 2. 在订单列表中找到已购买的授权订单，点击「下载」按钮。
-3. 下载的压缩包包含完整的前后端源码、数据库脚本及部署配置文件。
-4. 将压缩包解压到本地开发目录（如 D:\xampp\htdocs\ 或 ~/www/）。
-```
+3. 下载的压缩包包含完整的后端源码、数据库脚本及部署配置文件。
+4. 将压缩包解压到本地开发目录（如 `D:\laragon\www\` 或 `~/www/`）。
 
 ```bash
 # 进入项目目录（以实际解压路径为准）
-cd thinkphp6
+cd RXThinkCMF_Laravel13_EleVue
 ```
 
 :::tip 温馨提示
 1. 源码包请务必从[官方网站](https://www.rxthink.cn)订单中心下载，确保获取的是正版授权的最新版本。
 2. 授权有效期内可无限次下载最新版本，版本更新后可重新下载获取最新源码。
-3. 解压后请先阅读根目录下的 `README.md` 和 `CHANGELOG.md` 了解版本更新内容。
+3. 解压后请先阅读根目录下的 `README.md` 了解项目概况。
 :::
 
 ## 第三步：后端启动
@@ -61,13 +59,17 @@ cd thinkphp6
 
 ```bash
 # -----------------------------------------------------------------------------
-# 安装项目依赖（从 composer.lock 精确安装）
+# 方式一：一键初始化（推荐，自动完成依赖安装 + .env + APP_KEY + 迁移 + 前端构建）
 # -----------------------------------------------------------------------------
-composer install
+composer setup
 
 # -----------------------------------------------------------------------------
-# 如果国内下载慢，先配置阿里云镜像（加速依赖下载）
+# 方式二：手动逐步执行
 # -----------------------------------------------------------------------------
+# 安装项目依赖（从 composer.lock 精确安装）
+composer install
+
+# 如果国内下载慢，先配置阿里云镜像（加速依赖下载）
 # config -g → 修改全局配置（所有项目生效）
 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
 composer install
@@ -78,83 +80,82 @@ composer install
 ```bash
 # 复制环境变量模板（.env.example 是模板，.env 是实际配置文件）
 cp .env.example .env
+
+# 生成应用加密密钥（APP_KEY，写入 .env）
+php artisan key:generate
 ```
 
-编辑 `.env` 文件，配置数据库连接信息：
+编辑 `.env` 文件，重点确认以下配置：
 
 ```ini
-; 开启调试模式（开发环境 true，生产环境必须 false）
-APP_DEBUG = true
+# 开启调试模式（开发环境 true，生产环境必须 false）
+APP_DEBUG=true
 
-; 数据库配置
-[DATABASE]
-TYPE = mysql                        ; 数据库类型
-HOSTNAME = 127.0.0.1                ; 数据库地址
-DATABASE = rxthinkcmf.thinkphp6.elevue  ; 数据库名
-USERNAME = root                     ; 用户名
-PASSWORD = root                     ; 密码
-HOSTPORT = 3306                     ; 端口
-CHARSET = utf8mb4                   ; 字符集（支持 emoji）
-PREFIX = think_                     ; 表前缀
+# 数据库配置
+DB_CONNECTION=mysql                 # 数据库类型（mysql / pgsql / sqlsrv / sqlite）
+DB_HOST=127.0.0.1                   # 数据库地址
+DB_PORT=3306                        # 端口
+DB_DATABASE=rxthinkcmf.laravel13.elevue   # 数据库名（需提前创建）
+DB_USERNAME=root                    # 用户名
+DB_PASSWORD=root                    # 密码
+DB_PREFIX=laravel_                  # 表前缀（数据库脚本使用 laravel_ 前缀，必须保留）
 
-; JWT 密钥配置（生产环境务必修改为强随机字符串）
-[JWT]
-SECRET = rxthinkcmf_jwt_secret_key_2024     ; 签名密钥
-ACCESS_TTL = 7200                            ; access_token 有效期（秒）
-REFRESH_TTL = 604800                         ; refresh_token 有效期（秒）
+# 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 天）
 
-; 文件上传配置
-[FILE]
-UPLOAD_DIR = D:/uploads/rxthinkcmf  ; 上传目录（绝对路径）
-DOMAIN_URL = http://file.thinkphp6.elevue  ; 文件访问域名
+# 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. `.env` 使用 INI 分组格式，`[DATABASE]` 下的 `DATABASE` 是数据库名称，需提前在 MySQL 中创建。
-2. `[JWT]` 下的 `SECRET` 生产环境务必修改为强随机字符串，生成方式：`php -r "echo bin2hex(random_bytes(32));"`
-3. `[FILE]` 下的 `UPLOAD_DIR` 需使用绝对路径，确保目录存在且有写入权限。
+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 初始化数据库
 
-**方式一：导入 SQL 脚本（推荐）**
-
-项目为每种数据库提供了独立的 SQL 脚本，存放在 `document/` 目录下：
-
-```text
-document/
-├── mysql/rxthinkcmf.thinkphp6.elevue.sql        # MySQL 版本
-├── postgresql/rxthinkcmf.thinkphp6.elevue.sql   # PostgreSQL 版本
-├── sqlserver/rxthinkcmf.thinkphp6.elevue.sql    # SQL Server 版本
-├── oracle/rxthinkcmf.thinkphp6.elevue.sql       # Oracle 版本
-└── sqlite/rxthinkcmf.thinkphp6.elevue.sql       # SQLite 版本
-```
-
-以 MySQL 为例：
+**本项目未使用 Laravel 迁移建表**（`database/migrations/` 为空），数据库结构以 SQL 脚本为准：
 
 ```bash
 # -----------------------------------------------------------------------------
 # 第 1 步：登录 MySQL，创建数据库
 # -----------------------------------------------------------------------------
-# -uroot -p → 以 root 用户连接，-p 交互式输入密码
 mysql -uroot -p
 
 # 在 MySQL 命令行中执行（创建项目数据库）：
 # CHARACTER SET utf8mb4 → 支持 emoji 等四字节字符
 # COLLATE utf8mb4_general_ci → 不区分大小写的排序规则
-CREATE DATABASE `rxthinkcmf.thinkphp6.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
+CREATE DATABASE `rxthinkcmf.laravel13.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
 
 # -----------------------------------------------------------------------------
-# 第 2 步：导入数据库脚本
+# 第 2 步：导入数据库脚本（约 226MB，含 25 张业务表 + 初始数据）
 # -----------------------------------------------------------------------------
-# -uroot -proot → 用户名和密码
-# rxthinkcmf...   → 目标数据库名
-# < file.sql      → 将 SQL 文件作为 mysql 命令的输入
-mysql -uroot -proot rxthinkcmf.thinkphp6.elevue < document/mysql/rxthinkcmf.thinkphp6.elevue.sql
+mysql -uroot -proot rxthinkcmf.laravel13.elevue < document/mysql/rxthinkcmf.laravel13.elevue.sql
 ```
 
 :::tip 温馨提示
-项目支持 MySQL、PostgreSQL、SQL Server、Oracle、SQLite 五种数据库。请根据你使用的数据库类型选择对应的脚本导入。详细的多数据库初始化步骤请参考 [数据库初始化](/zh/quickstart/database-init.html) 章节。
+- 脚本位于 `document/mysql/rxthinkcmf.laravel13.elevue.sql`（五种数据库各有专用脚本，按 `document/<数据库类型>/` 分组），导入耗时约 1~3 分钟；
+- 使用 [2.8 Docker 快速体验](/zh/quickstart/docker.html) 时无需手动导入，首次启动自动完成；
+- 详细的多数据库初始化步骤请参考 [2.5 数据库初始化](/zh/quickstart/database-init.html)。
 :::
 
 初始化完成后，数据库中包含以下默认数据：
@@ -164,47 +165,59 @@ mysql -uroot -proot rxthinkcmf.thinkphp6.elevue < document/mysql/rxthinkcmf.thin
 默认角色：超级管理员角色
 默认菜单：系统管理、内容管理、监控管理等菜单及权限节点
 数据字典：系统内置字典数据
-系统配置：系统默认配置项
+系统配置：系统默认配置项、系统参数
 城市数据：全国行政区划数据
+默认租户：平台租户数据
 ```
 
 ### 3.4 启动后端服务
 
 ```bash
 # -----------------------------------------------------------------------------
-# 使用 ThinkPHP 内置开发服务器（默认监听 127.0.0.1:8000）
+# 推荐：一键启动（同时启动 artisan serve + 队列 + 日志流 + Vite 四个进程）
 # -----------------------------------------------------------------------------
-php think run
+composer dev
+
+# -----------------------------------------------------------------------------
+# 或单独启动 API 服务（默认监听 127.0.0.1:8000）
+# -----------------------------------------------------------------------------
+php artisan serve
 ```
 
 启动成功后会看到：
 
-```html
-ThinkPHP Development server is started
-<http://0.0.0.0:8000>
-You can exit with `CTRL-C`
+```text
+INFO  Server running on [http://127.0.0.1:8000].
 ```
 
 :::tip 温馨提示
-打开浏览器访问 `http://localhost:8000/` 可验证后端服务是否正常启动。
+打开浏览器访问 `http://localhost:8000/` 可验证后端服务是否正常启动；健康检查接口为 `http://localhost:8000/up`。
 :::
 
 ## 第四步：前端启动
 
 ### 4.1 安装前端依赖
 
+前端 EleVue 管理后台位于本仓库的 `ui/` 目录（Vue3 + ElementPlus）：
+
 ```bash
 # 进入前端项目目录
 cd ui
 
-# 安装依赖（从 pnpm-lock.yaml 精确安装）
+# 安装依赖（从 lock 文件精确安装）
+npm install
+# 或
 pnpm install
 ```
 
 :::tip 温馨提示
 如果安装速度较慢，可配置国内镜像源：
+
 ```bash
-# 配置 pnpm 国内镜像（加速依赖下载）
+# npm 国内镜像
+npm config set registry https://registry.npmmirror.com
+
+# pnpm 国内镜像
 pnpm config set registry https://registry.npmmirror.com
 ```
 :::
@@ -234,7 +247,7 @@ pnpm dev
 ```
 
 :::tip 温馨提示
-前端默认运行在 `8001` 端口，后端默认 `8000` 端口。`vite.config.ts` 中配置了代理，前端请求 `/api/*` 路径时自动转发到后端 `http://admin.thinkphp6.elevue/api/`。
+前端默认运行在 `8001` 端口，后端默认 `8000` 端口。Vite 开发代理由 `ui/.env.development` 的 `VITE_PROXY` 决定（默认转发到 `http://admin.laravel13.elevue/api`；直连 `php artisan serve` 时改为 `http://localhost:8000/api`，改后重启生效）。登录后请立即修改默认密码。
 :::
 
 ## 第五步：功能验证
@@ -251,9 +264,16 @@ pnpm dev
 7. 代码生成：开发工具 → 代码生成，体验代码生成功能。
 ```
 
+也可直接用命令行验证接口链路（验证码接口同时验证 PHP → Redis 链路）：
+
+```bash
+curl http://localhost:8000/api/captcha
+# → {"code":0,"ok":true,"msg":"操作成功","data":{...}}
+```
+
 ## 第六步：新增业务模块
 
-以项目内置的「案例演示」模块为例，演示如何新增一个完整的 CRUD 模块。
+以项目内置的「案例演示」模块为例，演示如何新增一个完整的 CRUD 模块（该模块是代码生成器的参考模板，以下代码均摘自项目实际源码）。
 
 ### 6.1 数据库建表
 
@@ -261,233 +281,308 @@ pnpm dev
 -- =============================================================================
 -- 创建案例演示表
 -- =============================================================================
--- 表前缀 think_ 由 .env 中 DATABASE.PREFIX 决定
--- BaseModel 会自动管理 create_time / update_time / create_user / update_user
+-- 表前缀 laravel_ 由 .env 中 DB_PREFIX 决定
+-- 模型 Trait 会自动管理 create_user / create_time / update_user / update_time
 -- =============================================================================
 
-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 自动写入）
-);
+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 后端开发
+### 6.2 模型层 — Model
 
-**Model** — `app/model/Example.php`：
+`app/Models/Example.php`：
 
 ```php
 <?php
-namespace app\model;
-use app\BaseModel;
+
+namespace App\Models;
+
+use App\Models\Concerns\HasAuditColumns;
+use App\Models\Concerns\SoftDeletesByFlag;
+use Illuminate\Database\Eloquent\Model;
 
 /**
- * 案例模型
- * 继承 BaseModel 自动获得软删除、时间戳、创建人等功能
+ * 案例演示模型
+ *
+ * 对应数据表 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 BaseModel
+class Example extends Model
 {
+    use HasAuditColumns, SoftDeletesByFlag;
+
     /**
-     * 对应数据库表名（不含前缀）
+     * 数据表名
+     *
+     * 显式指定表名为 example，覆盖默认的类名推导规则。
      *
      * @var string
      */
-    protected $name = 'example';
+    protected $table = 'example';
+
+    /**
+     * 允许批量赋值的字段列表
+     *
+     * @var array<int, string>
+     */
+    protected $fillable = [
+        'name',   // 名称
+        'avatar', // 头像/图片地址
+        'type',   // 类型：1=类型1，2=类型2，3=类型3，4=类型4
+        'status', // 状态：1=在用，2=停用
+        'sort',   // 排序值，数值越小越靠前（视业务而定）
+    ];
 }
 ```
 
-**Validate** — `app/validate/ExampleValidate.php`：
+:::tip
+表名 `example` 不含前缀，实际查询时由 `DB_PREFIX=laravel_` 自动拼接为 `laravel_example`。
+:::
+
+### 6.3 参数验证 — FormRequest
+
+`app/Http/Requests/ExampleRequest.php`：
 
 ```php
 <?php
-namespace app\validate;
-use think\Validate;
+
+namespace App\Http\Requests;
 
 /**
- * 案例验证器
- * 定义字段验证规则和场景
+ * 案例表单请求
+ *
+ * 负责案例演示新增/修改接口的参数校验。
+ *
+ * 说明：
+ * - 继承 BaseRequest，基础校验能力（失败响应统一处理）由基类提供。
+ * - 本类只声明案例特有的字段规则与自定义错误消息。
+ * - 前端传参使用 camelCase，数据库字段为 snake_case；
  */
-class ExampleValidate extends Validate
+class ExampleRequest extends BaseRequest
 {
     /**
-     * 验证规则
+     * 校验规则
      *
-     * name 字段必填
-     *
-     * @var array
+     * @return array<string, string> 字段规则
      */
-    protected $rule = ['name' => 'require'];
+    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',              // 排序值：可空，整数
+        ];
+    }
 
     /**
-     * 自定义错误提示
+     * 自定义错误消息
      *
-     * @var array
+     * @return array<string, string> 字段规则 => 错误消息
      */
-    protected $message = ['name.require' => '请输入案例名称'];
-
-    /**
-     * 验证场景
-     *
-     * add 和 update 场景都验证 name
-     *
-     * @var array
-     */
-    protected $scene = ['add' => ['name'], 'update' => ['name']];
+    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' => '排序值格式不正确',
+        ];
+    }
 }
 ```
 
-**Logic** — `app/logic/ExampleLogic.php`：
+### 6.4 业务逻辑 — Service
+
+`app/Services/ExampleService.php`（节选，完整代码见项目源码）：
 
 ```php
 <?php
-namespace app\logic;
-use app\BaseLogic;
-use app\model\Example;
+
+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;
 
 /**
- * 案例业务逻辑
- * 继承 BaseLogic 自动获得分页、新增、更新、删除、详情等基础 CRUD
+ * 案例演示业务逻辑服务
+ *
+ * 继承 BaseService，案例作为示例数据，不参与多租户隔离。
+ *
+ * 说明：
+ * - 组合的 Trait 职责：
+ *   - HasCrudOperations：add/update/delete/batchDelete 主流程；
+ *   - HasQueryScopes：列表查询条件、排序白名单；
+ *   - HasSerializeMaps：为 status 补 statusText（字典编码为 status）；
+ *   - HasUniqueCheck：新增/修改时校验 name 唯一；
+ * - 未 use HasDataScope，因此不做数据权限与租户隔离；
  */
-class ExampleLogic extends BaseLogic
+class ExampleService extends BaseService
 {
+    use HasCrudOperations, HasQueryScopes, HasSerializeMaps, HasUniqueCheck;
+
     /**
-     * 关联的模型类
-     *
-     * @var string
+     * 绑定的模型类
      */
     protected string $modelClass = Example::class;
 
-    /**
-     * 需要自动处理的文件上传字段
-     *
-     * @var array
-     */
-    protected array $fileFields = ['avatar'];
-
-    /**
-     * 文件保存的子目录
-     *
-     * @var string
-     */
-    protected string $fileSaveDir = 'example';
-
     /**
      * LIKE 模糊匹配字段
      *
-     * @var array
+     * @var array<int, string>
      */
     protected array $pageLikeFields = ['name'];
 
     /**
      * 精确匹配字段
      *
-     * @var array
+     * status 用于按状态筛选。
+     *
+     * @var array<int, string>
      */
-    protected array $pageEqFields = ['type', 'status'];
+    protected array $pageEqFields = ['status'];
 
     /**
-     * 默认排序规则
+     * 唯一性校验字段
      *
-     * @var array
+     * @var array<int, string>
      */
-    protected array $pageOrderBy = ['field' => 'sort', 'type' => 'asc'];
+    protected array $uniqueFields = ['name'];
 
     /**
-     * 枚举显示名映射
+     * 字典翻译配置：[字段 => 字典编码]
      *
-     * @var array
+     * 读取时为 status 补 statusText。
+     *
+     * @var array<string, string>
      */
     protected array $serializeMaps = [
-        'type' => 'example_type',
         'status' => 'example_status',
     ];
 }
 ```
 
-**Controller** — `app/controller/ExampleController.php`：
+分页、新增、修改、删除等方法**全部由 Trait 提供，无需手写**——这就是声明式 CRUD。
+
+### 6.5 接口入口 — Controller
+
+`app/Http/Controllers/Api/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;
+
+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;
 
 /**
- * 案例控制器
- * 定义 API 路由对应的处理方法
+ * 示例管理控制器
+ *
+ * 具体业务逻辑委托给 ExampleService，控制器仅做参数校验、
+ * 权限与日志标注及响应封装。
  */
-class ExampleController extends BaseController
+class ExampleController extends Controller
 {
-    protected ExampleLogic $logic;
+    public function __construct(protected ExampleService $exampleService) {}
 
-    protected function initialize(): void
+    /**
+     * 查询分页
+     *
+     * 对应权限：sys:example:page，操作日志类型：查询。
+     *
+     * @return JsonResponse 分页数据
+     */
+    #[OperationLog('示例管理-查询分页', OperationLog::TYPE_QUERY)]
+    #[Permission('sys:example:page', '示例分页')]
+    public function page(): JsonResponse
     {
-        $this->logic = new ExampleLogic();  // 初始化业务逻辑层
+        return $this->_page($this->exampleService);
     }
 
-    // #[Log] 注解：自动记录操作日志
-    // #[Permission] 注解：自动校验用户权限
-    #[Log('案例演示-查询分页', Log::TYPE_QUERY)]
-    #[Permission('sys:example:page', '案例分页')]
-    public function page(): Json
+    /**
+     * 新增
+     *
+     * @param  ExampleRequest  $request  已通过校验的示例请求
+     * @return JsonResponse 新增结果
+     */
+    #[OperationLog('示例管理-新增', OperationLog::TYPE_ADD, '新增示例：{name}')]
+    #[Permission('sys:example:add', '添加示例')]
+    public function add(ExampleRequest $request): JsonResponse
     {
-        return parent::_index($this->logic);    // 调用父类分页方法
+        return $this->_add($this->exampleService, $request->validated());
     }
 
-    #[Log('案例演示-新增', Log::TYPE_ADD, '新增案例：{name}')]
-    #[Permission('sys:example:add', '添加案例')]
-    public function add(): Json
-    {
-        return parent::_add($this->logic, $this->getJsonBody());    // 调用父类新增方法
-    }
-
-    // ... 其他 CRUD 方法
+    // 修改 / 删除 / 批量删除 / 导出 / 导入同理：
+    // _update / _delete / _batchDelete / _export / _import 快捷方法一行调用
 }
 ```
 
-### 6.3 注册路由
+### 6.6 注册路由
 
-在 `route/app.php` 中添加：
+在 `routes/api.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');   // 批量删除
-});
+// --- 案例演示 ---
+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']);
 ```
 
-### 6.4 前端开发
+:::tip
+公开接口（无需认证）应放在中间件组**外面**，认证接口放在 `['auth.jwt', 'tenant', 'demo', 'log.operation']` 组内——见 [3.7 路由注册](/zh/guide/route.html)。
+:::
 
-在 `ui/src/api/tool/example.ts` 中定义接口，在 `ui/src/views/tool/example/` 中创建页面文件。
+### 6.7 前端开发
 
-### 6.5 配置菜单权限
+在前端仓库的 `src/api/tool/example.ts` 中定义接口，在 `src/views/tool/example/` 中创建页面文件（列表页 / 编辑弹窗 / 详情弹窗 / 表格列定义 / 查询条件）。
+
+### 6.8 配置菜单权限
 
 在系统管理 → 菜单管理中：
 
 ```text
-1. 新增菜单：案例演示（路径：/example，组件：tool/example/index）
+1. 新增菜单：案例演示（路由 /example，组件 tool/example/index）
 2. 新增按钮：查看（sys:example:page）、新增（sys:example:add）、编辑（sys:example:update）、删除（sys:example:delete）
 3. 在角色管理中为角色分配"案例演示"菜单权限
 ```
 
 :::tip 温馨提示
-也可以使用代码生成器一键生成以上所有代码，详见 [代码生成器](/zh/generator/overview.html) 章节。
+也可以使用代码生成器一键生成以上所有代码，详见 [第 10 章 代码生成器](/zh/generator/overview.html)。
 :::
 
 ## 常见问题
@@ -495,16 +590,19 @@ Route::group('example', function () {
 在部署和使用过程中，可能会遇到以下常见问题：
 
 ```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. 前端白屏：检查后端服务是否启动，浏览器控制台是否有报错。
+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 温馨提示
-更多问题请参考 [常见问题FAQ](/zh/quickstart/faq.html) 章节。
+更多问题请参考 [2.9 常见问题 FAQ](/zh/quickstart/faq.html) 章节。
 :::
 
 ## 总结
@@ -512,12 +610,12 @@ Route::group('example', function () {
 通过以上步骤，你已经完成了从零搭建一个完整的后台管理系统的全过程：
 
 ```text
-1. 环境准备：PHP 8.2 + MySQL 8.0 + Composer 2.x + Node.js 22 + pnpm
+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 install → 配置 .env → 导入数据库 → php think run
-4. 前端启动：pnpm install → pnpm dev
+3. 后端启动：composer setup → 配置 .env → 导入数据库 → composer dev
+4. 前端启动：cd ui → pnpm install → pnpm dev
 5. 功能验证：登录系统，验证各模块功能
-6. 新增模块：Model → Validate → Logic → Controller → Route → 前端页面 → 菜单权限
+6. 新增模块：建表 → Model → FormRequest → Service → Controller → 路由 → 前端页面 → 菜单权限
 ```
 
 整个搭建过程约 30 分钟即可完成。如果在操作过程中遇到问题，请查阅文档或在社区寻求帮助。