3.11 常见问题与排错

后端问题

Q: 新增接口返回 401

A: 检查以下几点：

1. 请求头是否携带 Authorization: Bearer <token>
2. Token 是否过期（默认 2 小时）
3. 路由是否在 route/app.php 的需认证组中

Q: 新增接口返回 403

A: 权限不足，检查：

1. 是否在 Controller 方法上添加了 #[Permission] 注解
2. 权限码是否在菜单管理中配置
3. 用户角色是否包含该权限节点

Q: 枚举显示名（typeText/statusText）为空

A: 检查：

1. 字典表中是否存在对应的字典编码（如 example_type）
2. 字典项的 value 值是否与数据中的值匹配
3. Logic 中 serializeMaps 配置是否正确

// ExampleLogic 中的配置

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

Q: 文件上传后 avatar 路径为空

A: 检查：

1. .env 中 FILE.UPLOAD_DIR 是否配置
2. 上传目录是否存在且有写入权限
3. Logic 中是否配置了 fileFields

// ExampleLogic 中的配置
protected array $fileFields = ['avatar'];
protected string $fileSaveDir = 'example';

Q: 排序不生效

A: 检查 Logic 中 pageOrderBy 配置：

// ExampleLogic 中的配置
protected array $pageOrderBy = ['field' => 'sort', 'type' => 'asc'];

前端可通过 orderField 和 orderType 参数覆盖默认排序。

前端问题

Q: 菜单不显示

A: 检查：

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

Q: API 请求 404

A: 检查：

1. route/app.php 中是否注册了对应路由
2. 路由路径是否与前端 API 模块中的 url 一致
3. HTTP 方法是否正确（GET/POST/PUT/DELETE）

Q: 表格数据不显示

A: 检查：

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

Q: 导入失败

A: 检查：

1. 文件格式是否为 .xls 或 .xlsx
2. 表头是否与 headerMap 中定义的中文名一致
3. 枚举字段的值是否在字典中存在