签入版本

RXThinkCMF_Laravel13_NaiveVue/zh/guide/faq.md

@@ -5,67 +5,77 @@
 ### Q: 新增接口返回 401
 
 A: 检查以下几点：
+
 1. 请求头是否携带 `Authorization: Bearer <token>`
-2. Token 是否过期（默认 2 小时）
-3. 路由是否在 `route/app.php` 的需认证组中
+2. Token 是否过期（access_token 默认 2 小时，可调 `/api/refresh` 续签）
+3. 路由是否在 `routes/api.php` 的认证中间件组内（组外为公开接口）
 
 ### Q: 新增接口返回 403
 
 A: 权限不足，检查：
-1. 是否在 Controller 方法上添加了 `#[Permission]` 注解
-2. 权限码是否在菜单管理中配置
-3. 用户角色是否包含该权限节点
 
-### Q: 枚举显示名（typeText/statusText）为空
+1. 是否在 Controller 方法上添加了 `#[Permission]` 注解
+2. 权限码是否在菜单管理中配置（`permission` 字段与注解完全一致）
+3. 用户角色是否包含该权限节点（角色管理 → 勾选菜单/按钮）
+
+### Q: 报 `Table 'xxx.example' doesn't exist`
+
+A: `DB_PREFIX` 未配置。建表 SQL 使用 `laravel_` 前缀，`.env` 中必须保留 `DB_PREFIX=laravel_`，改后执行 `php artisan config:clear`。
+
+### Q: 枚举显示名（statusText）为空
 
 A: 检查：
-1. 字典表中是否存在对应的字典编码（如 `example_type`）
-2. 字典项的 value 值是否与数据中的值匹配
-3. Logic 中 `serializeMaps` 配置是否正确
+
+1. 字典表中是否存在对应的字典编码（如 `example_status`）
+2. 字典项的 value 是否与数据中的值匹配
+3. Service 中 `serializeMaps` 配置是否正确
+4. 字典缓存是否为旧数据：`php artisan dict:clear-cache`
 
 ```php
-// ExampleLogic 中的配置
-
-/**
- * 枚举显示名映射
- *
- * @var array
- */
+// ExampleService 中的配置
 protected array $serializeMaps = [
-    'type'   => 'example_type',
     'status' => 'example_status',
 ];
 ```
 
-### Q: 文件上传后 avatar 路径为空
+### Q: 唯一性校验不生效 / 误报重复
 
 A: 检查：
-1. `.env` 中 `FILE.UPLOAD_DIR` 是否配置
-2. 上传目录是否存在且有写入权限
-3. Logic 中是否配置了 `fileFields`
 
-```php
-// ExampleLogic 中的配置
-protected array $fileFields = ['avatar'];
-protected string $fileSaveDir = 'example';
-```
+1. Service 是否 `use HasUniqueCheck`（未启用时 `uniqueFields` 不生效）
+2. `uniqueFields` 字段名是否与入参键名一致（snake_case）
+3. 修改时是否正确排除自身（`checkUnique($data, $excludeId)` 由基类传入 id）
+4. 软删除的旧记录仍占唯一规则——这正是不用数据库唯一索引的原因，如需彻底放开需先清理历史数据
 
 ### Q: 排序不生效
 
-A: 检查 Logic 中 `pageOrderBy` 配置：
+A: 检查 Service 中 `pageOrderBy` 配置：
 
 ```php
-// ExampleLogic 中的配置
 protected array $pageOrderBy = ['field' => 'sort', 'type' => 'asc'];
 ```
 
-前端可通过 `orderField` 和 `orderType` 参数覆盖默认排序。
+前端可通过 `orderField` / `orderType` 参数覆盖默认排序，但字段必须命中 `pageOrderBy` 默认字段与 `orderFieldAllow` 的**并集**（白名单防注入），否则被忽略。
+
+### Q: 新增/修改时报"参数验证失败"，data 里没有字段明细
+
+A: 两种校验路径的响应结构不同：
+
+- FormRequest 注入失败：`data` 为 `{字段: [错误数组]}`（code=1）
+- Service 业务异常：`data` 为 null（code=1，看 msg）
+
+确认控制器方法是否类型注入了 FormRequest，以及是否误把格式规则写进了 Service。
+
+### Q: 审计字段（create_user）为空
+
+A: `create_user` 取自当前登录用户（`Auth::username()`），需经 `auth.jwt` 中间件（登录态）调用；命令行/队列等无登录态场景需手动赋值。
 
 ## 前端问题
 
 ### Q: 菜单不显示
 
 A: 检查：
+
 1. 后端菜单管理中是否添加了对应菜单
 2. 菜单的组件路径是否正确（如 `tool/example/index`）
 3. 前端 `views` 目录下是否有对应的 `.vue` 文件
@@ -74,20 +84,43 @@ A: 检查：
 ### Q: API 请求 404
 
 A: 检查：
-1. `route/app.php` 中是否注册了对应路由
+
+1. `routes/api.php` 中是否注册了对应路由
 2. 路由路径是否与前端 API 模块中的 `url` 一致
 3. HTTP 方法是否正确（GET/POST/PUT/DELETE）
+4. 批量删除是 **DELETE** `batchDelete`（请求体 `ids` 数组——方法为 DELETE 但仍携带 body）
 
 ### Q: 表格数据不显示
 
 A: 检查：
-1. API 返回的数据结构是否正确（应包含 `records` 和 `total`）
-2. 前端是否正确绑定了 `tableData`
+
+1. API 返回的数据结构是否正确（`data` 应包含 `records` 和 `total`）
+2. 前端是否正确绑定了 `tableData`（`res.records`）
 3. 浏览器控制台是否有报错
 
 ### Q: 导入失败
 
 A: 检查：
-1. 文件格式是否为 `.xls` 或 `.xlsx`
+
+1. 文件格式是否为 `.xls` 或 `.xlsx`（基类 `_import` 校验扩展名 + MIME + 10MB 上限）
 2. 表头是否与 `headerMap` 中定义的中文名一致
-3. 枚举字段的值是否在字典中存在
+3. 枚举字段的值是否在字典中存在（文本值需能反查到字典）
+
+### Q: 接口返回的键名大小写与预期不符
+
+A: 项目开启了驼峰/下划线自动转换（`API_CAMEL_SNAKE_CONVERT=true`）：
+
+- 响应：`create_time` → `createTime`（数据库字段 → 前端字段）
+- 请求：前端传 camelCase，Service 写入入口（doAdd/doUpdate）统一转为 snake_case
+
+如需原样返回，使用 `Result::success($data, $msg, true)`（`$raw=true`）。
+
+## 生成器问题
+
+### Q: 用生成器生成的模块菜单没有出现
+
+A: 检查生成配置中的父菜单 ID（`.env` 中 `GENERATOR_PARENT_MENU_ID`）是否存在，以及当前角色是否被分配了新菜单；生成后重新登录或刷新获取最新菜单。
+
+### Q: 生成的路由 404
+
+A: 确认生成时是否勾选路由注册；手动检查 `routes/api.php` 中是否已有对应路由（重复注册会报错），改完执行 `php artisan route:list` 核对。