import{_ as a,o as i,c as s,a2 as l}from"./chunks/framework.BbmSSMjL.js";const k=JSON.parse('{"title":"3.11 常见问题与排错","description":"","frontmatter":{},"headers":[],"relativePath":"zh/guide/faq.md","filePath":"zh/guide/faq.md"}'),t={name:"zh/guide/faq.md"};function o(d,e,h,r,c,n){return i(),s("div",null,[...e[0]||(e[0]=[l(`

3.11 常见问题与排错 ​

后端问题 ​

Q: 新增接口返回 401 ​

A: 检查以下几点：

  1. 请求头是否携带 Authorization: Bearer <token>
  2. Token 是否过期（access_token 默认 2 小时，可调 /api/refresh 续签）
  3. 路由是否在 routes/api.php 的认证中间件组内（组外为公开接口）

Q: 新增接口返回 403 ​

A: 权限不足，检查：

  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_status）
  2. 字典项的 value 是否与数据中的值匹配
  3. Service 中 serializeMaps 配置是否正确
  4. 字典缓存是否为旧数据：php artisan dict:clear-cache
php
// ExampleService 中的配置
protected array $serializeMaps = [
    'status' => 'example_status',
];

Q: 唯一性校验不生效 / 误报重复 ​

A: 检查：

  1. Service 是否 use HasUniqueCheck（未启用时 uniqueFields 不生效）
  2. uniqueFields 字段名是否与入参键名一致（snake_case）
  3. 修改时是否正确排除自身（checkUnique($data, $excludeId) 由基类传入 id）
  4. 软删除的旧记录仍占唯一规则——这正是不用数据库唯一索引的原因，如需彻底放开需先清理历史数据

Q: 排序不生效 ​

A: 检查 Service 中 pageOrderBy 配置：

php
protected array $pageOrderBy = ['field' => 'sort', 'type' => 'asc'];

前端可通过 orderField / orderType 参数覆盖默认排序，但字段必须命中 pageOrderBy 默认字段与 orderFieldAllow 的并集（白名单防注入），否则被忽略。

Q: 新增/修改时报"参数验证失败"，data 里没有字段明细 ​

A: 两种校验路径的响应结构不同：

确认控制器方法是否类型注入了 FormRequest，以及是否误把格式规则写进了 Service。

Q: 审计字段（create_user）为空 ​

A: create_user 取自当前登录用户（Auth::username()），需经 auth.jwt 中间件（登录态）调用；命令行/队列等无登录态场景需手动赋值。

前端问题 ​

Q: 菜单不显示 ​

A: 检查：

  1. 后端菜单管理中是否添加了对应菜单
  2. 菜单的组件路径是否正确（如 tool/example/index）
  3. 前端 views 目录下是否有对应的 .vue 文件
  4. 用户角色是否包含该菜单权限

Q: API 请求 404 ​

A: 检查：

  1. routes/api.php 中是否注册了对应路由
  2. 路由路径是否与前端 API 模块中的 url 一致
  3. HTTP 方法是否正确（GET/POST/PUT/DELETE）
  4. 批量删除是 DELETE batchDelete（请求体 ids 数组——方法为 DELETE 但仍携带 body）

Q: 表格数据不显示 ​

A: 检查：

  1. API 返回的数据结构是否正确（data 应包含 records 和 total）
  2. 前端是否正确绑定了 tableData（res.records）
  3. 浏览器控制台是否有报错

Q: 导入失败 ​

A: 检查：

  1. 文件格式是否为 .xls 或 .xlsx（基类 _import 校验扩展名 + MIME + 10MB 上限）
  2. 表头是否与 headerMap 中定义的中文名一致
  3. 枚举字段的值是否在字典中存在（文本值需能反查到字典）

Q: 接口返回的键名大小写与预期不符 ​

A: 项目开启了驼峰/下划线自动转换（API_CAMEL_SNAKE_CONVERT=true）：

如需原样返回，使用 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 核对。

`,49)])])}const u=a(t,[["render",o]]);export{k as __pageData,u as default};